Compile-time DOM bindings

This simplified counter uses back-arrow syntax to sequence its IO operations. Constructing an IO value does not mutate state. write returns IO[Unit], an inert value that describes a mutation without performing it. (Reading the notation: x <- e.flat_map() is a do-block, meaning “run e, bind its result to x”. pure lifts a plain value into IO.) The handler returns an effect for runtime dispatch. Read the complete counter source.

package Demo/Counter

from Bosatsu/Predef import add, Int, Unit, int_to_String
from Yichus/IO import IO, pure, flat_map
from Yichus/UI import VNode, State, state, read, write, h, text, on_click

count: IO[State[Int]] = state(0)

def increment() -> IO[Unit]:
  c <- count.flat_map()
  current <- c.read().flat_map()
  c.write(current.add(1))

def render_counter() -> IO[VNode]:
  c <- count.flat_map()
  current <- c.read().flat_map()
  pure(h("div", [("class", "card")], [
    h("span", [("id", "count-display")], [text(int_to_String(current))]),
    h("button", [on_click(increment())], [text("+")])
  ]))

main: IO[VNode] = render_counter()

On the JVM (Scala) side, write constructs a deferred FlatMap node. This path is used during evaluation and testing. Takeaway: constructing the external does not mutate the cell; the JVM external shows the boundary.

// From UI.scala — JVM external for write
private def deferredUiMutation(effect: => Unit): Value =
  ExternalValue(
    YichusIO.FlatMap(YichusIO.Pure(UnitValue), (_: Value) => {
      effect
      YichusIO.Pure(UnitValue)
    })
  )

The mutation closure is captured but not called until runWithProvenance interprets the FlatMap chain. A test in UITest.scala proves this:

val writeIo = call2("write", stateVal, Str("after"))
assertEquals(state.value, Str("before"))   // still "before"

val result = runIO(writeIo)                // interpret the IO
assertEquals(state.value, Str("after"))    // NOW it changed

UIAnalyzer walks the TypedExpr AST of main before generating any JavaScript. It sees:

1. state(0): allocates state, assigns it an internal id like "count"
2. read(c): records that "count" is read during render
3. text(int_to_String(current)) inside h("span", ...): the state read flows into a text node inside a <span>

From this it produces a DOMBinding. The record identifies the state, target element, and property to update.

This binding is serialized into JavaScript and embedded in the generated HTML as a literal object. Takeaway: the update target is resolved at compile time. The exact extraction and serialization live in UIAnalyzer.scala:

const _bindings = {
  "count": [{
    elementId: "count-display",
    property:  "textContent",
    when:      null,
    transform: "_int_to_String"
  }]
};

JsGen compiles IO operations into JavaScript thunks that return { value, trace } objects. The snippets in this section explain the shape and are not promised as byte-verbatim current generator output. Takeaway: event handlers still return IO, and runtime dispatch executes it. Follow the current implementation in JsGen.scala and reactive.js:

State allocation. state(0) compiles to a memoized thunk that creates or reuses a state object:

var count = (() => {
  let _state_ref = null;
  return () => {
    _state_ref = _state_ref || _ui_create_state(0);
    return { value: _state_ref, trace: [] };
  };
})();

_ui_create_state produces { id: "count", value: 0 }.

Event handler registration. on_click(increment) compiles to a prop tuple that stores the handler in a global table:

["data-onclick", _ui_register_handler("click", increment)]

_ui_register_handler stores the handler function under an id like "h_0" and returns that id. The VNode ends up with data-onclick="h_0" in its props.

The compiled increment handler. The entire function becomes a chain of IO thunks:

var increment = (_) => {
  // Returns an IO (a thunk). Nothing runs yet.
  return () => {
    const _a = count();                   // IO[State[Int]] → state obj
    const _b = (() => {
      const _a2 = (() => ({               // read(c) → IO thunk
        value: _a.value.value,            // reads stateObj.value
        trace: []
      }))();
      const _b2 = _ui_write_io(           // write(c, current + 1)
        _a.value,                          // the state object
        _a2.value + 1                      // new value
      )();                                 // ← invoked: effect runs
      return { value: _b2.value,
        trace: _a2.trace.concat(_b2.trace) };
    })();
    return { value: _b.value,
      trace: _a.trace.concat(_b.trace) };
  };
};

When the VNode tree is rendered to real DOM, event props are wired to addEventListener. Takeaway: the listener calls the handler and passes the returned IO to _ui_run_io. See the event branch in reactive.js:

_ui_run_io is the IO interpreter. It calls the thunk:

var _ui_run_io = (io) => {
  if (typeof io === 'function') return io();
  return io;
};

The base _ui_write_io from JsGen returns a thunk that calls _ui_write:

var _ui_write_io = (state, value) => () => {
  _ui_write(state, value);
  return { value: [], trace: [] };
};

UIGen embeds the shared reactive runtime, which overrides _ui_write to route through the binding map. The actual path checks for a direct binding, canvas binding, tracked render read, or declared rerender route before changing state. A state with no route increments bindingMapMisses and throws instead of silently rerendering. Takeaway: scalar bindings queue direct updates, while missing routes fail loudly. Read the current runtime source and the routing tests:

On the next microtask, _flushPendingUpdates calls _updateBindings for each queued state id. The function throws on a missing binding and supports several property types. Takeaway: a valid scalar binding resolves the target element and writes the named property. Read the exact runtime function: