@llui/dom

Runtime for the LLui web framework — The Elm Architecture on a compile-time-optimized signal runtime.

No virtual DOM. view() runs once at mount, building real DOM nodes with reactive bindings; a chunked-mask reconciler updates only the bindings whose dependency paths actually changed.

Install

pnpm add @llui/dom

Quick Start

import { component, mountApp, button, text } from '@llui/dom'

type State = { count: number }
type Msg = { type: 'inc' } | { type: 'dec' }

const Counter = component<State, Msg>({
  name: 'Counter',
  init: () => ({ count: 0 }),
  update: (state, msg) => {
    switch (msg.type) {
      case 'inc':
        return { ...state, count: state.count + 1 }
      case 'dec':
        return { ...state, count: state.count - 1 }
    }
  },
  // `state` is a Signal<State> — derive reactive values with `.map` / `.at`.
  view: ({ state, send }) => [
    button({ onClick: () => send({ type: 'dec' }) }, [text('-')]),
    text(state.map((s) => String(s.count))),
    button({ onClick: () => send({ type: 'inc' }) }, [text('+')]),
  ],
})

mountApp(document.getElementById('app')!, Counter)

init() may return bare state (as above) or a [state, effects] tuple; likewise update(). Effects are handled in onEffect (see Effects).

The view bag and signal handles

view receives { state, send, batch }:

• state is a Signal<State> — a read handle, not the value:
  • state.at('field') — narrow to a sub-path signal (state.at('user').at('name')).
  • state.map((s) => …) — derive a reactive value; the binding's mask tracks exactly the paths read.
  • state.peek() — one-shot read, for handlers / effects / onMount (never as a slot value).
• send(msg) dispatches a message. It is synchronous — the reducer runs and the DOM updates before it returns.
• batch(fn) coalesces a burst of sends into ONE reconcile (reducers/effects still run per message; only the DOM commit is deferred to the outermost batch exit).

Element helpers (div, button, …) and structural primitives (each, show, branch, …) are module imports, not bag members. Combine multiple signals with derived([a, b], (av, bv) => …).

Mountable — everything you build is a lazy description

Every authoring helper (el/div/text/each/show/branch/unsafeHtml/lazy/virtualEach/foreign/portal/provide) returns a Mountable — a recipe materialized into live DOM at the point it is placed (as an element child, or in a view / arm / row return). Consequences:

• Annotate view helpers Renderable (readonly Mountable[] — a list) or Mountable (a single element) — not Node/Node[].
• Capture and reuse freely. A Mountable stored in a variable and reused across a show/branch remount rebuilds fresh each time; placing one twice yields two independent live instances.
• Side-effect helpers must be placed. onMount(cb) registers nothing unless its returned Mountable is in the view array — it is not an eager side effect.
• Raw DOM interop: wrap an existing node with mountable(() => node).

Structural primitives

import { show, each, branch } from '@llui/dom'

// Conditional — the condition signal is narrowed for the arm
show(
  state.at('user'),
  (user) => [text(user.map((u) => u.name))],
  () => [text('signed out')],
)

// Keyed list — each row gets its own `item` / `index` signal
each(state.at('todos'), {
  key: (t) => t.id,
  render: (item) => [text(item.map((t) => t.label))],
})

// Discriminated union — each arm receives the narrowed variant signal
branch(state.at('route'), (r) => r.kind, {
  home: () => [text('home')],
  entity: (r) => [text(r.map((e) => e.id))],
})

// Keyed form: branch(value, arms) when the value is already the key
branch(
  state.map((s) => s.tab),
  { one: () => [text('one')], two: () => [text('two')] },
)

All three accept an optional trailing transition?: TransitionOptions (from @llui/transitions) to animate arm/row swaps.

Composition

Factor sub-views as plain functions that take signal handles — they run via the runtime authoring helpers, so they compose without compilation:

import type { Signal, Renderable } from '@llui/dom'

function header(title: Signal<string>, send: (m: Msg) => void): Renderable {
  return [h1([text(title)]), button({ onClick: () => send({ type: 'menu' }) }, [text('☰')])]
}

// in view:
view: ({ state, send }) => [...header(state.at('title'), send)]

Effects

update() returns [state, effects]; each effect is passed to the component's onEffect handler. Use @llui/effects for the builders and asOnEffect to adapt a handler chain:

import { http, handleEffects, asOnEffect } from '@llui/effects'

const onEffect = asOnEffect(
  handleEffects<Effect>().else(({ effect, send }) => {
    // handle your effect union
  }),
)

component<State, Msg, Effect>({ name, init, update, view, onEffect })

API

Core

| Export | Purpose | | -------------------------------------------- | ------------------------------------------------------------- | | component(spec) | Define a component (init / update / view / onEffect?) | | mountApp(el, def, opts?) | Mount a component into a container element | | mountSignalComponent(target, def, opts?) | Lower-level mount — container or { anchor } target | | hydrateSignalApp(target, def, serverState) | Hydrate server-rendered HTML | | derived(sigs, fn) | Combine N signals into one derived signal | | isSignalHandle(v) | Detect a runtime signal handle |

View content

| Export | Purpose | | ----------------------------------- | --------------------------------------------------------------------------- | | text(value) | Reactive (or static) text node | | unsafeHtml(value) | Render a raw HTML string (escape hatch; caller owns sanitization) | | each(items, { key, render }) | Keyed list | | show(cond, render, orElse?) | Conditional render (the condition signal is narrowed for the arm) | | branch(value, discriminant, arms) | Discriminated-union render (or branch(value, arms) when value is the key) | | virtualEach(opts) | Windowed keyed list | | lazy(opts) | Async-loaded child component with fallback / error | | foreign(spec) | Imperative-library boundary (declared signals → LiveSignals) | | portal(content, target?) | Render into a different DOM location (default document.body) | | onMount(cb) | Run after mount; return a cleanup. Place the returned marker. | | mountable(build) | Wrap a build closure / raw node as placeable content | | element helpers | div, span, button, input, a, h1–h6, ul/li, table/…, 60+ |

Context

| Export | Purpose | | ------------------------------- | ------------------------------------------------ | | createContext(default, name?) | Create a context | | provide(ctx, value, render) | Provide a value to everything render builds | | useContext(ctx) | Read the nearest provided value (or the default) |

SSR

Exported from the main @llui/dom entry (pass a DomEnv from a sub-entry — see below):

| Export | Purpose | | --------------------------------- | -------------------------------------- | | renderToString(def, state, env) | Render a component to an HTML string | | renderNodes(def, state, env) | Render to detached nodes (adapter use) | | serializeNodes(nodes) | Serialize nodes to an HTML string |

Sub-path Exports

import { installSignalDebug } from '@llui/dom/devtools' // dev/agent relay — kept out of prod bundles
import { browserEnv, type DomEnv } from '@llui/dom/ssr' // SSR env contract + browser-globals env
import { jsdomEnv } from '@llui/dom/ssr/jsdom' // server: jsdom-backed DomEnv
import { linkedomEnv } from '@llui/dom/ssr/linkedom' // server: linkedom-backed DomEnv
import { subApp } from '@llui/dom/escape-hatch' // isolated child TEA loop (rare)
// '@llui/dom/internal' — render-context glue for sibling adapter packages (e.g. @llui/vike)

Performance

Competitive with the fastest fine-grained reactive frameworks on js-framework-benchmark — see the benchmarks page.