@abide/abide 0.28.0

package/src/lib/ui/compile/prepareNestedScript.ts

@@ -0,0 +1,42 @@
+import ts from 'typescript'
+
+/*
+The signal binding names a `<script>` nested in a control-flow branch declares
+(`state`/`derived`/`prop`). The back-end adds them to the deref scope so both the
+script body and the branch's markup rewrite `{a}` → `a.value` — these stay PLAIN
+signals (local to the branch's render, owned by its scope, re-seeded from the
+in-scope data each mount), unlike the top-level component script which desugars to
+the serializable `doc`.
+*/
+export function nestedBindingNames(code: string): Set<string> {
+    const source = ts.createSourceFile('nested.ts', code, ts.ScriptTarget.Latest, true)
+    const names = new Set<string>()
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            const callee = signalCallee(declaration)
+            if (
+                (callee === 'state' || callee === 'derived' || callee === 'prop') &&
+                ts.isIdentifier(declaration.name)
+            ) {
+                names.add(declaration.name.text)
+            }
+        }
+    }
+    return names
+}
+
+/* The callee name of a `NAME = state(...)` / `derived(...)` / `prop(...)` declaration. */
+function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
+    const initializer = declaration.initializer
+    if (
+        initializer !== undefined &&
+        ts.isCallExpression(initializer) &&
+        ts.isIdentifier(initializer.expression)
+    ) {
+        return initializer.expression.text
+    }
+    return undefined
+}

package/src/lib/ui/compile/remapShadowDiagnostic.ts

@@ -0,0 +1,30 @@
+import type { ShadowMapping } from './types/CompiledShadow.ts'
+
+/*
+Relocates a diagnostic's shadow span back to the original `.abide` source. The
+diagnostic must *overlap* a mapped segment (a verbatim-emitted expression);
+diagnostics confined to synthesised scaffolding overlap nothing and are dropped —
+that is the filter that keeps shadow-internal noise out of the editor. Overlap
+(not containment) is required because TypeScript often reports a whole-expression
+mismatch at the synthetic wrapping `(`, one char before the mapped span; the
+result is clamped into the segment so it lands on real source either way.
+*/
+export function remapShadowDiagnostic(
+    mappings: ShadowMapping[],
+    shadowStart: number,
+    shadowLength: number,
+): { start: number; length: number } | undefined {
+    const shadowEnd = shadowStart + Math.max(shadowLength, 1)
+    const mapping = mappings.find(
+        (entry) => shadowStart < entry.shadowStart + entry.length && entry.shadowStart < shadowEnd,
+    )
+    if (mapping === undefined) {
+        return undefined
+    }
+    const clampedStart = Math.max(shadowStart, mapping.shadowStart)
+    const segmentEnd = mapping.shadowStart + mapping.length
+    return {
+        start: mapping.sourceStart + (clampedStart - mapping.shadowStart),
+        length: Math.max(1, Math.min(shadowEnd, segmentEnd) - clampedStart),
+    }
+}

package/src/lib/ui/compile/renameSignalRefs.ts

@@ -0,0 +1,85 @@
+import ts from 'typescript'
+
+/*
+Rewrites references to a component's signal bindings into the document form the
+rest of the pipeline understands: a `state` binding `count` becomes `model.count`
+(data access `lowerDocAccess` then lowers to a patch/read), and a `derived`
+binding `total` becomes `total.value`. Only value-position identifiers are
+touched — declaration names, parameter names, and property names are collected
+into a skip set first, and object shorthand (`{ count }`) is expanded to
+`{ count: model.count }`. This is the bridge from the signal surface the author
+writes to the patch substrate underneath.
+*/
+export function renameSignalRefs(
+    code: string,
+    stateNames: ReadonlySet<string>,
+    derivedNames: ReadonlySet<string>,
+): string {
+    const source = ts.createSourceFile('component.ts', code, ts.ScriptTarget.Latest, true)
+
+    /* Identifier nodes that are names, not value reads — never rewritten. */
+    const skip = new Set<ts.Node>()
+    const collect = (node: ts.Node): void => {
+        if (ts.isPropertyAccessExpression(node)) {
+            skip.add(node.name)
+        }
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+            skip.add(node.name)
+        }
+        if (ts.isParameter(node) && ts.isIdentifier(node.name)) {
+            skip.add(node.name)
+        }
+        if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+            skip.add(node.name)
+        }
+        if (
+            (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) &&
+            node.name !== undefined
+        ) {
+            skip.add(node.name)
+        }
+        ts.forEachChild(node, collect)
+    }
+    collect(source)
+
+    const result = ts.transform(source, [
+        (context) => (root) => {
+            const visit = (node: ts.Node): ts.Node => {
+                /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`. */
+                if (ts.isShorthandPropertyAssignment(node)) {
+                    const replacement = referenceFor(node.name.text, stateNames, derivedNames)
+                    if (replacement !== undefined) {
+                        return ts.factory.createPropertyAssignment(node.name.text, replacement)
+                    }
+                }
+                if (ts.isIdentifier(node) && !skip.has(node)) {
+                    const replacement = referenceFor(node.text, stateNames, derivedNames)
+                    if (replacement !== undefined) {
+                        return replacement
+                    }
+                }
+                return ts.visitEachChild(node, visit, context)
+            }
+            return ts.visitNode(root, visit) as ts.SourceFile
+        },
+    ])
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
+    const output = printer.printFile(result.transformed[0] as ts.SourceFile)
+    result.dispose()
+    return output
+}
+
+/* `model.<name>` for a state binding, `<name>.value` for a derived one, else undefined. */
+function referenceFor(
+    name: string,
+    stateNames: ReadonlySet<string>,
+    derivedNames: ReadonlySet<string>,
+): ts.Expression | undefined {
+    if (stateNames.has(name)) {
+        return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier('model'), name)
+    }
+    if (derivedNames.has(name)) {
+        return ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(name), 'value')
+    }
+    return undefined
+}

package/src/lib/ui/compile/resolveAbideImports.ts

@@ -0,0 +1,29 @@
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+
+/*
+A module-name resolver shared by the shadow Program (check) and LanguageService
+(LSP). A relative `./X.abide` import resolves directly to its virtual shadow
+`./X.abide.ts` (the host serves shadow text for any `*.abide.ts` name), so
+cross-component prop checking works. An aliased `.abide` (`$ui/X.abide`) falls
+through to TypeScript's own resolver, which applies the tsconfig `paths` and —
+because the host reports the shadow `.abide.ts` exists — lands on the same
+shadow. Every other specifier (`abide/*`, `$server/*`, plain relative `.ts`,
+asset modules covered by the ambient declarations) resolves through TypeScript
+directly, exactly as for the real module.
+*/
+export function resolveAbideImports(
+    options: ts.CompilerOptions,
+    host: ts.ModuleResolutionHost,
+): (moduleNames: string[], containingFile: string) => (ts.ResolvedModule | undefined)[] {
+    return (moduleNames, containingFile) =>
+        moduleNames.map((name) => {
+            if (name.endsWith('.abide')) {
+                const relative = resolve(dirname(containingFile), name)
+                if (ts.sys.fileExists(relative)) {
+                    return { resolvedFileName: `${relative}.ts`, extension: ts.Extension.Ts }
+                }
+            }
+            return ts.resolveModuleName(name, containingFile, options, host).resolvedModule
+        })
+}

package/src/lib/ui/compile/scopeCss.ts

@@ -0,0 +1,115 @@
+/*
+Scopes a component's CSS to its own elements by appending an attribute selector
+(`[data-a-<hash>]`) to each rule's key compound selector — the proven approach
+(every element the component renders carries the attribute, so descendant
+selectors still resolve, but styles never leak out). At-rule preludes (`@media`,
+etc.) pass through untouched while the nested rules inside them are still scoped.
+The attribute is inserted before any pseudo (`a:hover` → `a[attr]:hover`) so the
+selector stays valid.
+*/
+export function scopeCss(css: string, attribute: string): string {
+    let result = ''
+    let prelude = '' // chars accumulated since the last brace
+    let depth = 0
+    let keyframesDepth = -1 // brace depth of the open @keyframes block, or -1 when outside one
+    for (const char of css) {
+        if (char === '{') {
+            const insideKeyframes = keyframesDepth !== -1 && depth >= keyframesDepth
+            if (prelude.trim().startsWith('@')) {
+                /* At-rule prelude: leave it; its inner rules scope on their own. A
+                   @keyframes block is the exception — its `from`/`to`/`%` steps aren't
+                   selectors, so track its depth and leave the steps inside it bare. */
+                if (/^@(-[a-z]+-)?keyframes\b/i.test(prelude.trim())) {
+                    keyframesDepth = depth + 1
+                }
+                result += `${prelude}{`
+            } else if (insideKeyframes) {
+                result += `${prelude}{` // a keyframe step (from/to/%) — not a selector
+            } else {
+                result += `${scopeSelectorList(prelude, attribute)} {`
+            }
+            depth += 1
+            prelude = ''
+        } else if (char === '}') {
+            result += `${prelude}}`
+            prelude = ''
+            depth -= 1
+            if (keyframesDepth !== -1 && depth < keyframesDepth) {
+                keyframesDepth = -1
+            }
+        } else {
+            prelude += char
+        }
+    }
+    return result + prelude
+}
+
+/* Scopes each selector in a comma-separated list, splitting at top-level commas
+   only so a `,` inside `:is(.a, .b)` / `[attr=","]` doesn't fragment a selector. */
+function scopeSelectorList(prelude: string, attribute: string): string {
+    return splitSelectorList(prelude)
+        .map((selector) => scopeSelector(selector.trim(), attribute))
+        .join(', ')
+}
+
+/* Splits a selector list on commas that aren't nested inside `()` or `[]`. */
+function splitSelectorList(prelude: string): string[] {
+    const selectors: string[] = []
+    let current = ''
+    let nesting = 0
+    for (const char of prelude) {
+        if (char === '(' || char === '[') {
+            nesting += 1
+        } else if (char === ')' || char === ']') {
+            nesting -= 1
+        }
+        if (char === ',' && nesting === 0) {
+            selectors.push(current)
+            current = ''
+        } else {
+            current += char
+        }
+    }
+    selectors.push(current)
+    return selectors
+}
+
+/* Appends `[attribute]` to a selector's last compound, before any pseudo. */
+function scopeSelector(selector: string, attribute: string): string {
+    if (selector === '') {
+        return selector
+    }
+    const match = selector.match(/^(.*?)([^\s>+~]+)$/)
+    if (match === null) {
+        return `${selector}[${attribute}]`
+    }
+    const prefix = match[1] ?? ''
+    const last = match[2] ?? ''
+    const pseudo = pseudoIndex(last)
+    const scopedLast =
+        pseudo === -1
+            ? `${last}[${attribute}]`
+            : `${last.slice(0, pseudo)}[${attribute}]${last.slice(pseudo)}`
+    return `${prefix}${scopedLast}`
+}
+
+/*
+Index of the first pseudo-class/element colon in a compound — i.e. a `:` at
+bracket depth zero. Skips colons inside an attribute selector's value
+(e.g. `a[href='http://x']`), which must not be treated as a pseudo boundary.
+Returns -1 when the compound has no pseudo.
+*/
+function pseudoIndex(compound: string): number {
+    let depth = 0
+    for (let index = 0; index < compound.length; index += 1) {
+        const char = compound[index]
+        if (char === '[') {
+            depth += 1
+        } else if (char === ']') {
+            depth -= 1
+        } else if (char === ':' && depth === 0) {
+            return index
+        }
+    }
+    return -1
+}

package/src/lib/ui/compile/shadowNaming.ts

@@ -0,0 +1,11 @@
+/*
+A `.abide` component's virtual shadow is the same absolute path with `.ts`
+appended (`Foo.abide` → `Foo.abide.ts`). The suffix lets a TypeScript host tell a
+shadow apart from a real file and recover the source path. Shared by the one-shot
+Program (`createShadowProgram`) and the incremental LanguageService (the LSP).
+*/
+export const shadowNaming = {
+    suffixed: (abidePath: string): string => `${abidePath}.ts`,
+    isShadow: (fileName: string): boolean => fileName.endsWith('.abide.ts'),
+    sourceOf: (shadowName: string): string => shadowName.slice(0, -'.ts'.length),
+}

package/src/lib/ui/compile/sourceToShadowOffset.ts

@@ -0,0 +1,24 @@
+import type { ShadowMapping } from './types/CompiledShadow.ts'
+
+/*
+Translates an offset in the original `.abide` source to the equivalent offset in
+its type-checking shadow — the inverse of `remapShadowDiagnostic`. Drives
+position-based language-service queries (hover, completion, …) from an editor
+position: find the verbatim-emitted segment whose source span covers the offset
+and shift it into shadow coordinates. An offset outside every mapped span
+(whitespace, markup, framework syntax the shadow doesn't emit verbatim) has no
+shadow position, so the query is skipped.
+*/
+export function sourceToShadowOffset(
+    mappings: ShadowMapping[],
+    sourceOffset: number,
+): number | undefined {
+    const mapping = mappings.find(
+        (entry) =>
+            entry.sourceStart <= sourceOffset && sourceOffset < entry.sourceStart + entry.length,
+    )
+    if (mapping === undefined) {
+        return undefined
+    }
+    return mapping.shadowStart + (sourceOffset - mapping.sourceStart)
+}

package/src/lib/ui/compile/staticAttrValue.ts

@@ -0,0 +1,13 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The value of a static attribute on an element node, or undefined when absent.
+   Used to read directive attributes like `slot` / `slot name` off the template. */
+export function staticAttrValue(
+    node: Extract<TemplateNode, { kind: 'element' }>,
+    name: string,
+): string | undefined {
+    const attr = node.attrs.find(
+        (candidate) => candidate.kind === 'static' && candidate.name === name,
+    )
+    return attr !== undefined && attr.kind === 'static' ? attr.value : undefined
+}

package/src/lib/ui/compile/stripEffects.ts

@@ -0,0 +1,32 @@
+import ts from 'typescript'
+
+/*
+Removes `effect(...)` calls from a script for the SSR back-end. Effects are client
+lifecycle — they touch the DOM / run side effects and emit no HTML, so the server
+render (a snapshot of the pre-effect markup, like every framework) must not run
+them. Every `effect(<args>)` call is replaced by `undefined`, dropping its body:
+an `effect(() => …)` statement becomes a no-op, and a `const stop = effect(…)`
+binding keeps a defined (unused) name. Client compilation keeps effects untouched.
+*/
+export function stripEffects(code: string): string {
+    const source = ts.createSourceFile('script.ts', code, ts.ScriptTarget.Latest, true)
+    const result = ts.transform(source, [
+        (context) => (root) => {
+            const visit = (node: ts.Node): ts.Node => {
+                if (
+                    ts.isCallExpression(node) &&
+                    ts.isIdentifier(node.expression) &&
+                    node.expression.text === 'effect'
+                ) {
+                    return ts.factory.createIdentifier('undefined')
+                }
+                return ts.visitEachChild(node, visit, context)
+            }
+            return ts.visitNode(root, visit) as ts.SourceFile
+        },
+    ])
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
+    const output = printer.printFile(result.transformed[0] as ts.SourceFile)
+    result.dispose()
+    return output
+}

package/src/lib/ui/compile/types/AbideDiagnostic.ts

@@ -0,0 +1,14 @@
+import type ts from 'typescript'
+
+/*
+A type-check diagnostic relocated onto a `.abide` source file: `start`/`length`
+are an offset range in the original component file (not the shadow), ready for a
+CLI to render or the LSP to convert to a line/character range.
+*/
+export type AbideDiagnostic = {
+    file: string
+    start: number
+    length: number
+    message: string
+    category: ts.DiagnosticCategory
+}

package/src/lib/ui/compile/types/AnalyzedComponent.ts

@@ -0,0 +1,25 @@
+import type { TemplateNode } from './TemplateNode.ts'
+
+/*
+The shared front-end result for a component, consumed by both the client
+(`generateBuild`) and server (`generateSSR`) code generators: the lowered script
+(signal surface desugared to the doc patch/read API), the signal binding names
+(so template expressions rewrite consistently), and the parsed template tree.
+*/
+export type AnalyzedComponent = {
+    script: string
+    /* Top-level import statements hoisted out of the script (e.g. child
+       components), placed at module scope by the module wrapper. */
+    imports: string
+    stateNames: Set<string>
+    derivedNames: Set<string>
+    nodes: TemplateNode[]
+    /* One entry per non-empty `<style>` in the template (in source order): the scope
+       attribute its covered elements carry (annotated onto `nodes`) and the scoped
+       CSS to bundle. A top-level `<style>` covers the whole component; a nested one
+       covers only its sibling subtree. Empty for a component with no style. */
+    styles: { attribute: string; css: string }[]
+    /* False when the template contains an `await` block (not adoptable yet) — the
+       router mounts (re-renders) rather than hydrates such a page. */
+    hydratable: boolean
+}

package/src/lib/ui/compile/types/CompiledShadow.ts

@@ -0,0 +1,15 @@
+/*
+The type-checking shadow of a `.abide` component: a synthetic `.ts` module that
+reconstructs the author-facing scope with value types and references every
+template expression in a checkable position, plus the segment map that relocates
+a diagnostic in the shadow back to the original `.abide` source.
+
+Each mapping covers one verbatim-emitted span: `length` characters at `shadowStart`
+in the shadow correspond to the same `length` characters at `sourceStart` in the
+`.abide` file (expressions are emitted unchanged, so the spans are equal length).
+A shadow offset inside a mapping translates to `sourceStart + (offset - shadowStart)`;
+an offset in no mapping is synthesised scaffolding and its diagnostic is dropped.
+*/
+export type ShadowMapping = { shadowStart: number; sourceStart: number; length: number }
+
+export type CompiledShadow = { code: string; mappings: ShadowMapping[] }

package/src/lib/ui/compile/types/TemplateAttr.ts

@@ -0,0 +1,16 @@
+/*
+An element attribute. `static` is a literal; `expression` is `name={code}` bound
+reactively; `event` is `on<event>={code}` where `code` evaluates to the handler;
+`bind` is `bind:<property>={lvalue}`, a two-way binding whose `code` is the
+writable doc path read into the property and written back on input; `attach` is
+`attach={code}` where `code` evaluates to an attachment `(node) => teardown` run
+at build with node-lifetime teardown. `loc` is the
+absolute offset of `code` in the original `.abide` source (see TextPart) —
+optional, set only when the parser tracks positions for the type-checking shadow.
+*/
+export type TemplateAttr =
+    | { kind: 'static'; name: string; value: string }
+    | { kind: 'expression'; name: string; code: string; loc?: number }
+    | { kind: 'event'; event: string; code: string; loc?: number }
+    | { kind: 'bind'; property: string; code: string; loc?: number }
+    | { kind: 'attach'; code: string; loc?: number }

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -0,0 +1,78 @@
+import type { TemplateAttr } from './TemplateAttr.ts'
+import type { TextPart } from './TextPart.ts'
+
+/*
+A parsed template node. `text` carries interpolation parts; `element` carries
+attributes and children; `each` is the `<template each as key>` control flow over
+a list. (if/await/switch are future siblings.)
+
+`loc` (where present) is the absolute offset of the node's primary expression in
+the original `.abide` source — additive, set only when the parser tracks
+positions for the type-checking shadow, ignored by the runtime back-ends.
+*/
+export type TemplateNode =
+    | { kind: 'text'; parts: TextPart[] }
+    | { kind: 'script'; code: string }
+    /* A `<style>` declared in the template. `css` is its raw body, read structurally
+       so a `<style>` inside an expression isn't mistaken for one. The node stays in
+       place: it scopes its sibling subtree, so the front-end derives each scope
+       attribute and the elements it covers from the node's position (see
+       `analyzeComponent`). Emits no DOM/markup. */
+    | { kind: 'style'; css: string }
+    | {
+          kind: 'element'
+          tag: string
+          attrs: TemplateAttr[]
+          children: TemplateNode[]
+          /* The scope attributes (`data-a-…`) this element carries — one per `<style>`
+             active at its position (its own sibling list plus every ancestor's),
+             filled by `analyzeComponent`. Absent until annotated. */
+          scopes?: string[]
+      }
+    | {
+          kind: 'each'
+          items: string
+          as: string
+          key: string | undefined
+          /* `await` on the tag → `items` is an AsyncIterable, drained on the client. */
+          async: boolean
+          children: TemplateNode[]
+          loc?: number
+      }
+    | { kind: 'if'; condition: string; children: TemplateNode[]; loc?: number }
+    | {
+          kind: 'await'
+          promise: string
+          /* `then` riding the `await` tag (`<template await={p} then={v}>`) makes the
+             block BLOCKING: no pending branch, children are the resolved content bound
+             to `as`, SSR settles before the first flush. Absent → streaming. */
+          blocking: boolean
+          as: string | undefined
+          children: TemplateNode[]
+          loc?: number
+      }
+    | { kind: 'try'; children: TemplateNode[] }
+    | {
+          kind: 'branch'
+          branch: 'then' | 'catch' | 'finally'
+          as: string | undefined
+          children: TemplateNode[]
+      }
+    | {
+          kind: 'component'
+          name: string
+          props: { name: string; code: string; loc?: number }[]
+          children: TemplateNode[]
+      }
+    | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
+    | { kind: 'case'; match: string | undefined; children: TemplateNode[]; loc?: number }
+    /* A `<template name="row" args={item}>` snippet: a named, scope-capturing
+       builder declared once and called like a function (`{row(item)}`). `params`
+       is the raw `args` source spliced into the builder's parameter list. */
+    | {
+          kind: 'snippet'
+          name: string
+          params: string | undefined
+          children: TemplateNode[]
+          loc?: number
+      }

package/src/lib/ui/compile/types/TextPart.ts

@@ -0,0 +1,8 @@
+/* A piece of a text node: literal characters, or a `{expr}` interpolation whose
+   `code` is lowered and bound reactively. `loc` is the absolute offset of the
+   expression's first character in the original `.abide` source — present only
+   when the parser was given the source's base offset; the runtime back-ends
+   ignore it, the type-checking shadow maps diagnostics through it. */
+export type TextPart =
+    | { kind: 'static'; value: string }
+    | { kind: 'expression'; code: string; loc?: number }

package/src/lib/ui/derived.ts

@@ -0,0 +1,28 @@
+import { createComputedNode } from './runtime/createComputedNode.ts'
+import { OWNER } from './runtime/OWNER.ts'
+import { readNode } from './runtime/readNode.ts'
+import type { Derived } from './runtime/types/Derived.ts'
+import { unlinkDeps } from './runtime/unlinkDeps.ts'
+
+/*
+A read-only reactive cell computed from other cells — the abide replacement for
+`$derived`. Lazy: it recomputes on read only when a dependency has changed, and
+never serializes (it is re-derived from its inputs on resume). Read via `.value`.
+*/
+// @readme plumbing
+export function derived<T>(compute: () => T): Derived<T> {
+    const node = createComputedNode(compute as () => unknown)
+    /* Tear down with the enclosing scope, the way an effect does. A computed only
+       unlinks from its sources when it re-runs (`runNode` re-tracking); one read
+       once and then abandoned never re-runs, so absent this it would sit in its
+       source signals' subscriber lists forever — re-marked dirty on every write to
+       them — for the source's lifetime. Outside a scope it owns its own life (no-op). */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => unlinkDeps(node))
+    }
+    return {
+        get value(): T {
+            return readNode(node) as T
+        },
+    }
+}

package/src/lib/ui/doc.ts

@@ -0,0 +1,15 @@
+import { createDoc } from './runtime/createDoc.ts'
+import type { Doc } from './runtime/types/Doc.ts'
+
+/*
+Creates a reactive document: a single immutable, serializable tree addressed by
+path, where every change is a patch. `doc.read(path)` is path-granular reactive
+read; `doc.replace/add/remove` emit patches that wake only the readers whose
+paths the change touched. This is the substrate the whole framework stands on —
+deep reactivity, resumability, undo, and sync all reduce to "a patch over a
+path", so they share one mechanism instead of being bolted on.
+*/
+// @readme plumbing
+export function doc(initial: unknown = {}): Doc {
+    return createDoc(initial)
+}

package/src/lib/ui/dom/appendSnippet.ts

@@ -0,0 +1,34 @@
+import { snippetPayload } from '../../shared/snippet.ts'
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+
+/*
+A `{snippet(args)}` interpolation: mount the branded builder's nodes at this
+position. The builder builds straight into `parent` — sequential build order
+places it correctly among siblings, and its effects join the surrounding
+component scope (so they tear down with it). The body's reactive reads update
+fine-grained via those effects; an enclosing `each` re-mounts on list changes.
+
+On hydrate the builder runs against the server-rendered nodes between the
+`<!--abide:snippet-->`/`<!--/abide:snippet-->` markers — its `openChild`/`appendText`
+claim them in place. The cursor is advanced past the open marker before, and past
+the close marker after, so the markers themselves are skipped.
+*/
+// @readme plumbing
+export function appendSnippet(parent: Node, read: () => unknown): void {
+    const builder = snippetPayload(read())
+    if (typeof builder !== 'function') {
+        return
+    }
+    const mount = builder as (host: Node) => void
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        const open = claimChild(hydration, parent)
+        hydration.next.set(parent, open === null ? null : open.nextSibling)
+        mount(parent)
+        const close = claimChild(hydration, parent)
+        hydration.next.set(parent, close === null ? null : close.nextSibling)
+        return
+    }
+    mount(parent)
+}

package/src/lib/ui/dom/appendStatic.ts

@@ -0,0 +1,27 @@
+import { claimChild } from '../runtime/claimChild.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+
+/*
+A static (non-reactive) text node under `parent`: created and appended (create
+mode), or claimed from the server-rendered text (hydrate mode). As with reactive
+text, a merged SSR text node is split at this literal's length so the next claim
+lines up; nothing is bound since the text never changes.
+*/
+// @readme plumbing
+export function appendStatic(parent: Node, value: string, splitAlways = false): void {
+    const hydration = RENDER.hydration
+    if (hydration !== undefined) {
+        const node = claimChild(hydration, parent) as unknown as Text
+        /* Split even on an exact-length consume when a sibling text binding follows
+           (`splitAlways`), so it gets its own node; see appendText for the rationale. */
+        if (
+            node !== null &&
+            (splitAlways ? value.length <= node.data.length : value.length < node.data.length)
+        ) {
+            node.splitText(value.length)
+        }
+        hydration.next.set(parent, node === null ? null : node.nextSibling)
+        return
+    }
+    parent.appendChild(document.createTextNode(value))
+}