@abide/abide 0.28.0

package/src/lib/ui/README.md

@@ -0,0 +1,86 @@
+# abide-ui
+
+A from-scratch, single-file UI framework for abide — reactive, with `<script>` +
+template + `<style>` in one `.abide` file. Signal surface, document
+substrate, server-rendered and streamed, with true DOM adoption.
+
+abide-ui is the framework's UI runtime: `createUiPageRenderer` renders and streams
+every page, and `.abide` files are the only component format.
+
+## A component
+
+```html
+<script>
+  import Layout from './Layout.abide'
+  let count = state(0)              // signal
+  let items = state([])
+  let total = derived(() => items.length)   // computed
+  function add() { items.push('item ' + (total + 1)) }
+</script>
+
+<Layout title="home">
+  <button onclick={() => count += 1}>count: {count}</button>
+  <button onclick={add}>add ({total})</button>
+  <template if={total}>
+    <ul>
+      <template each={items} as="it" key="it"><li>{it}</li></template>
+    </ul>
+    <template else><p>empty</p></template>
+  </template>
+</Layout>
+
+<style>
+  button { cursor: pointer }   /* scoped to this component */
+</style>
+```
+
+## Idioms
+
+- **Signals are the surface**: `state(v)`, `derived(fn)`, `effect(fn)`, `prop(name)`.
+  You write plain assignment (`count += 1`, `items.push(x)`); the compiler lowers
+  it. Templates auto-read (`{count}`); ordering and cross-references compose.
+- **Everything dynamic lives in `{ }`** — `{expr}` text, `name={expr}`,
+  `onclick={fn}`, `bind:value={path}`.
+- **Control flow is native `<template>`** (valid HTML, no mustache DSL):
+  `<template if>`/`<template else>`, `<template each as key>`,
+  `<template await>`/`then`/`catch`, `<template switch>`/`case`/`default`.
+- **Components** are capitalised tags (`<Layout title="…">`); children fill the
+  child's `<slot>`. Props are reactive (passed as thunks).
+- **Scoped styles**: a `<style>` block is scoped per component via a
+  `[data-b-<hash>]` attribute.
+
+## Substrate (why it's fast)
+
+State is one mutable document addressed by path; every change is a patch over a
+path. The compiler turns `model.a[i].b` into a path read and `model.x = y` into a
+patch, hoisting static paths to a `cell` resolved once. Reactivity is shape-only
+(a deep field edit wakes only that field, not the list above it). On the
+write-path microbench this runs ~20× faster than a deep-proxy signal baseline.
+
+## SSR + streaming + hydration
+
+- `compileSSR` renders to an HTML string (byte-identical to the client DOM).
+- `renderToStream` streams: pending shell first, then resolved `<template await>`
+  fragments out of order as their promises settle; `applyResolved` swaps them in.
+- `hydrate` adopts the server DOM in place (no re-render) for static-structure
+  components — claims existing nodes, splits merged text, wires effects/listeners.
+
+## Pipeline
+
+```
+.abide → analyzeComponent (split script/style/template, desugar signals → doc,
+                           lower data access, scope CSS)
+       → generateBuild  (client: openChild/appendText/attr/on/each/when/…)
+       → generateSSR    (server: HTML-string back-end, await markers)
+       → hoistCells     (static paths → cells)
+       → compileModule  (ES module: default mount + render() for SSR)
+```
+
+`compile/abideUiPlugin.ts` is the Bun loader for `.abide` files.
+
+## Known gaps
+
+- Hydration adopts static structure only; control-flow blocks (if/each/await/
+  switch) and child components fall back to `mount` (re-render).
+- `compileModule` emits `abide/ui/*` specifiers (a published consumer needs
+  `abide/ui/*` or `abideImportName`).

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

@@ -0,0 +1,25 @@
+/*
+Source text for the `$esc` / `$attr` / `$text` / `$snip` helpers injected into
+every SSR render body. `$esc` escapes the five HTML-significant characters. `$attr`
+renders a dynamic `{expr}` attribute with the same present/absent semantics the
+client `attr` binding uses: false/null/undefined drops it, true emits the bare
+attribute, anything else emits `name="escaped"`. `$snip` brands a snippet's
+rendered string. `$text` is what `{expr}` interpolations push: a snippet call's
+value is emitted raw between `<!--abide:snippet-->` markers (the client runs its
+builder there to claim the nodes); a `html\`…\`` value raw between `<!--abide:html-->`
+markers; anything else is escaped. The brands are registered Symbols so they match
+across bundles. Emitted inline (not imported) so the generated render module is
+self-contained.
+*/
+export const SSR_ESCAPE =
+    'const $esc = (v) => String(v).replace(/[&<>"\']/g, (c) => ' +
+    "({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;', \"'\": '&#39;' })[c]);\n" +
+    'const $attr = (n, v) => (v === false || v === null || v === undefined) ? "" ' +
+    ': v === true ? (" " + n) : (" " + n + \'="\' + $esc(v) + \'"\');\n' +
+    "const $RAW = Symbol.for('abide.rawHtml');\n" +
+    "const $SNIP = Symbol.for('abide.snippet');\n" +
+    'const $snip = (s) => ({ [$SNIP]: s });\n' +
+    'const $text = (v) => (v !== null && typeof v === "object" && $SNIP in v) ' +
+    "? ('<!--abide:snippet-->' + v[$SNIP] + '<!--/abide:snippet-->') " +
+    ': (v !== null && typeof v === "object" && $RAW in v) ' +
+    "? ('<!--abide:html-->' + v[$RAW] + '<!--/abide:html-->') : $esc(v);"

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

@@ -0,0 +1,36 @@
+/*
+The abide-ui runtime names every compiled component module depends on, each
+paired with its package subpath (after the package name). One source of truth so
+three things can't drift: the normal module's import block (`compileModule`), the
+hot module's `window.__abide` destructure (dev component HMR), and the dev bridge
+that populates `window.__abide`. Order is the emit order.
+*/
+export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
+    { name: 'html', specifier: 'shared/html' },
+    { name: 'snippet', specifier: 'shared/snippet' },
+    { name: 'doc', specifier: 'ui/doc' },
+    { name: 'state', specifier: 'ui/state' },
+    { name: 'derived', specifier: 'ui/derived' },
+    { name: 'effect', specifier: 'ui/effect' },
+    { name: 'mount', specifier: 'ui/dom/mount' },
+    { name: 'openChild', specifier: 'ui/dom/openChild' },
+    { name: 'openRoot', specifier: 'ui/dom/openRoot' },
+    { name: 'appendText', specifier: 'ui/dom/appendText' },
+    { name: 'appendSnippet', specifier: 'ui/dom/appendSnippet' },
+    { name: 'appendStatic', specifier: 'ui/dom/appendStatic' },
+    { name: 'cloneStatic', specifier: 'ui/dom/cloneStatic' },
+    { name: 'attr', specifier: 'ui/dom/attr' },
+    { name: 'on', specifier: 'ui/dom/on' },
+    { name: 'attach', specifier: 'ui/dom/attach' },
+    { name: 'each', specifier: 'ui/dom/each' },
+    { name: 'eachAsync', specifier: 'ui/dom/eachAsync' },
+    { name: 'when', specifier: 'ui/dom/when' },
+    { name: 'awaitBlock', specifier: 'ui/dom/awaitBlock' },
+    { name: 'tryBlock', specifier: 'ui/dom/tryBlock' },
+    { name: 'switchBlock', specifier: 'ui/dom/switchBlock' },
+    { name: 'mountChild', specifier: 'ui/dom/mountChild' },
+    { name: 'hydrate', specifier: 'ui/dom/hydrate' },
+    { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId' },
+    { name: 'enterRenderPass', specifier: 'ui/runtime/enterRenderPass' },
+    { name: 'exitRenderPass', specifier: 'ui/runtime/exitRenderPass' },
+]

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

@@ -0,0 +1,21 @@
+/*
+HTML void elements — they have no closing tag and no children. Shared by the SSR
+generator and the static-clone skeleton generator so both emit `<img>` not
+`<img></img>`, keeping server markup and the client clone template identical.
+*/
+export const VOID_TAGS: ReadonlySet<string> = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+])

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

@@ -0,0 +1,65 @@
+import { relative } from 'node:path'
+import type { BunPlugin } from 'bun'
+import { analyzeComponent } from './analyzeComponent.ts'
+import { compileModule } from './compileModule.ts'
+import { nearestProjectRoot } from './nearestProjectRoot.ts'
+
+/*
+Bun plugin that loads `.abide` single-file components: compiles each to the ES
+module `compileModule` emits, so they import and mount like any other module. The
+only UI loader in the dev/build/preload pipeline; the emitted module's
+`abide/ui/*` imports resolve through the package exports.
+
+A `layout.abide` compiles as a layout: its `<slot/>` lowers to the router's page
+outlet (`<abide-outlet>`) rather than a passed-children slot — the file's role is
+its name, so the loader flags it from the path stem.
+
+The emitted module embeds the component's `<script>` and `{expr}` bodies verbatim,
+so it carries the author's TypeScript (a typed `prop`, an annotated handler). The
+`ts` loader strips those annotations — the generated runtime code is valid TS too —
+keeping `.abide` scripts the TypeScript that `abide check` type-checks them as.
+
+A component's scoped `<style>`(s) are bundled, not inlined: in the BROWSER build the
+module imports a virtual `abide-style:` CSS module holding every block's scoped CSS
+concatenated, so Bun folds it into the entry stylesheet (`client.css`, already linked
+by the shell). Server builds (target `bun`) omit the import — SSR styling comes from
+that same linked sheet, so a page renders styled before the client bundle loads, with
+no inlined `<style>`. The elements still carry their `data-a-…` scope attributes
+either way (one per `<style>` covering them — see `analyzeComponent`).
+*/
+// @readme plumbing
+export const abideUiPlugin: BunPlugin = {
+    name: 'abide-ui',
+    setup(build) {
+        const toBrowser = build.config?.target === 'browser'
+        /* Scoped CSS keyed by its virtual specifier, filled as each `.abide` loads and
+           read back when Bun resolves the matching `abide-style:` import (browser only). */
+        const cssByVirtual = new Map<string, string>()
+
+        build.onLoad({ filter: /\.abide$/ }, async (args) => {
+            const source = await Bun.file(args.path).text()
+            const moduleId = relative(nearestProjectRoot(args.path, process.cwd()), args.path)
+            const isLayout = (args.path.split('/').pop() ?? '') === 'layout.abide'
+            const code = compileModule(source, { isLayout, moduleId })
+            /* Browser build with `<style>`(s): concatenate every scoped block's CSS and
+               pull it into the bundle via one virtual import, keyed by `moduleId` so the
+               registry id and the CSS id agree. */
+            const styles = toBrowser ? analyzeComponent(source, moduleId).styles : []
+            if (styles.length === 0) {
+                return { contents: code, loader: 'ts' }
+            }
+            const virtual = `abide-style:${moduleId}`
+            cssByVirtual.set(virtual, styles.map((style) => style.css).join('\n'))
+            return { contents: `import ${JSON.stringify(virtual)}\n${code}`, loader: 'ts' }
+        })
+
+        build.onResolve({ filter: /^abide-style:/ }, (args) => ({
+            path: args.path,
+            namespace: 'abide-style',
+        }))
+        build.onLoad({ filter: /.*/, namespace: 'abide-style' }, (args) => ({
+            contents: cssByVirtual.get(args.path) ?? '',
+            loader: 'css',
+        }))
+    },
+}

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

@@ -0,0 +1,117 @@
+import { desugarSignals } from './desugarSignals.ts'
+import { lowerDocAccess } from './lowerDocAccess.ts'
+import { parseTemplate } from './parseTemplate.ts'
+import { scopeCss } from './scopeCss.ts'
+import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+The shared compile front-end: splits the leading `<script>` off the template,
+desugars the signal surface to the doc form, lowers the script's data access, and
+parses the template (which keeps each `<style>` as an in-place node). Each `<style>`
+is scoped to its own attribute (`data-a-<hash>`); `annotateScopes` stamps that
+attribute onto every element in the style's sibling subtree, so a top-level
+`<style>` covers the whole component while a nested one covers only the branch it
+sits in. Both client and SSR back-ends read the per-element `scopes`, so the targets
+always agree.
+
+`scopeSeed` (the component's stable module id, supplied by the loader) seeds each
+hash — combined with the style's source-order index — so the attribute tracks
+component+position identity, not CSS text: an edit to a `<style>` keeps the same
+`data-a-…`, so the live elements still match and the CSS can hot-swap in place.
+Absent (direct compile calls / tests) it falls back to hashing the style body.
+*/
+export function analyzeComponent(source: string, scopeSeed?: string): AnalyzedComponent {
+    /* Only the LEADING `<script>` is the component script; scripts nested in the
+       template (scoped reactive blocks) survive into the parsed nodes. The `<style>`
+       is left in the template for the parser to extract structurally (below), so a
+       `<style>` quoted inside an expression is never mistaken for the component's. */
+    const scriptMatch = source.match(/^\s*<script[^>]*>([\s\S]*?)<\/script>/)
+    const scriptBody = (scriptMatch?.[1] ?? '').trim()
+    const template = source.replace(/^\s*<script[^>]*>[\s\S]*?<\/script>/, '').trim()
+
+    const { code: desugared, stateNames, derivedNames } = desugarSignals(scriptBody)
+    const lowered = desugared.trim() === '' ? '' : lowerDocAccess(desugared, 'model')
+    /* Hoist top-level import statements (e.g. child components) out of the script
+       so the module wrapper can place them at module scope — they can't live
+       inside the mount callback / render function. */
+    const imports: string[] = []
+    const script = lowered
+        .replace(/^[ \t]*import\s[^\n]*$/gm, (line) => {
+            imports.push(line.trim())
+            return ''
+        })
+        .replace(/\n{2,}/g, '\n')
+        .trim()
+    /* The parser keeps each `<style>` as an in-place node (one inside an expression
+       is text, never a node). `annotateScopes` mutates the tree — assigning each
+       style its scope attribute and stamping covered elements — and returns the
+       scoped CSS per block for the bundler. */
+    const { nodes } = parseTemplate(template)
+    const styles = annotateScopes(nodes, [], scopeSeed, { count: 0 })
+    return {
+        script,
+        imports: imports.join('\n'),
+        stateNames,
+        derivedNames,
+        nodes,
+        styles,
+        /* Hydration adopts every block in place — including `await`, which resumes
+           from the streamed value in the resume manifest (see `runtime/RESUME`). */
+        hydratable: true,
+    }
+}
+
+/* The children of a control-flow / element / component node, or undefined for a
+   leaf (text/script/style). Every children-bearing kind carries `children`. */
+function childrenOf(node: TemplateNode): TemplateNode[] | undefined {
+    return 'children' in node ? node.children : undefined
+}
+
+/*
+Walks `nodes` in source order, scoping each `<style>` to its sibling subtree: a
+style among a sibling list covers every element in that list AND every descendant
+(so its attribute reaches the whole branch it sits in, like the nested-`<script>`
+rule). `inherited` is the scope attributes already active from ancestors; this
+level adds its own styles' attributes, stamps the resulting set onto each element
+here, and recurses with it. `index.count` is the running source-order ordinal that
+(with `scopeSeed`) keeps each attribute stable across CSS edits. Returns the scoped
+CSS for every non-empty style, in source order, for the bundler to concatenate.
+*/
+function annotateScopes(
+    nodes: TemplateNode[],
+    inherited: string[],
+    scopeSeed: string | undefined,
+    index: { count: number },
+): { attribute: string; css: string }[] {
+    const collected: { attribute: string; css: string }[] = []
+    /* This sibling list's own style attributes — active for every element here. */
+    const here = [...inherited]
+    for (const node of nodes) {
+        if (node.kind === 'style' && node.css.trim() !== '') {
+            const attribute = `data-a-${hashString(`${scopeSeed ?? node.css}#${index.count}`)}`
+            index.count += 1
+            collected.push({ attribute, css: scopeCss(node.css, attribute) })
+            here.push(attribute)
+        }
+    }
+    for (const node of nodes) {
+        if (node.kind === 'element') {
+            node.scopes = here
+        }
+        const children = childrenOf(node)
+        if (children !== undefined) {
+            collected.push(...annotateScopes(children, here, scopeSeed, index))
+        }
+    }
+    return collected
+}
+
+/* Small stable hash (djb2 → base36) for a per-style scope attribute. */
+function hashString(value: string): string {
+    let hash = 5381
+    for (let index = 0; index < value.length; index += 1) {
+        hash = (hash * 33) ^ value.charCodeAt(index)
+    }
+    return (hash >>> 0).toString(36)
+}

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

@@ -0,0 +1,32 @@
+import { resolve } from 'node:path'
+
+/*
+A single virtual ambient-declaration file injected into the shadow world so the
+type-checker resolves bundler-handled asset imports instead of erroring "cannot
+find module". Bun bundles a stylesheet import for its side effect and resolves a
+static asset to its URL string; these declarations mirror that. One shared file
+(not a per-component preamble) keeps the wildcard module patterns declared once,
+which TypeScript requires. Used by both the check Program and the LSP service so
+the editor and CLI agree.
+*/
+export function assetModulesFile(cwd: string): { path: string; content: string } {
+    return {
+        path: resolve(cwd, '__abide_assets__.d.ts'),
+        content: [
+            "declare module '*.css' {}",
+            "declare module '*.scss' {}",
+            "declare module '*.sass' {}",
+            "declare module '*.less' {}",
+            "declare module '*.svg' { const src: string; export default src }",
+            "declare module '*.png' { const src: string; export default src }",
+            "declare module '*.jpg' { const src: string; export default src }",
+            "declare module '*.jpeg' { const src: string; export default src }",
+            "declare module '*.gif' { const src: string; export default src }",
+            "declare module '*.webp' { const src: string; export default src }",
+            "declare module '*.avif' { const src: string; export default src }",
+            "declare module '*.woff' { const src: string; export default src }",
+            "declare module '*.woff2' { const src: string; export default src }",
+            '',
+        ].join('\n'),
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+The element roots of a control-flow branch (`if`/`else`/`switch case`/`await
+then|catch`). A branch may hold one or MORE top-level elements — each becomes a
+root the block tracks as a range. Whitespace-only text between/around them is
+dropped (so SSR and the client build agree on the node set, keeping hydration
+aligned). Any other top-level content — meaningful text, a component, or a nested
+control-flow `<template>` — must be wrapped in an element; it throws a clear error
+rather than silently dropping (full fragment roots are a separate feature).
+
+Both back-ends call this, so the server HTML and the client build contain exactly
+the same roots in the same order.
+*/
+type ElementNode = Extract<TemplateNode, { kind: 'element' }>
+
+export function branchElements(
+    children: TemplateNode[],
+    context: string,
+    allowEmpty = false,
+): ElementNode[] {
+    const elements: ElementNode[] = []
+    for (const child of children) {
+        if (child.kind === 'element') {
+            elements.push(child)
+            continue
+        }
+        /* Whitespace-only text is layout noise between roots — drop it. */
+        if (child.kind === 'text' && isWhitespaceOnly(child)) {
+            continue
+        }
+        /* A scoped `<script>` is emitted as code by the back-end, not a root; a
+           `<style>` is bundled CSS (its scope already stamped on the roots). */
+        if (child.kind === 'script' || child.kind === 'style') {
+            continue
+        }
+        throw new Error(
+            `[abide] ${context} content must be element(s); wrap text / components / nested <template> in an element`,
+        )
+    }
+    if (elements.length === 0 && !allowEmpty) {
+        throw new Error(`[abide] ${context} must contain at least one element`)
+    }
+    return elements
+}
+
+/* A text node whose parts are all whitespace literals (no interpolation). */
+function isWhitespaceOnly(node: Extract<TemplateNode, { kind: 'text' }>): boolean {
+    return node.parts.every((part) => part.kind === 'static' && part.value.trim() === '')
+}

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

@@ -0,0 +1,59 @@
+import ts from 'typescript'
+import type { ShadowProgram } from './createShadowProgram.ts'
+import { remapShadowDiagnostic } from './remapShadowDiagnostic.ts'
+import type { AbideDiagnostic } from './types/AbideDiagnostic.ts'
+
+/*
+Runs the shadow program's type-checker over every `.abide` shadow and relocates
+each diagnostic onto its source component. Only diagnostics that fall inside a
+mapped expression survive (remapShadowDiagnostic drops shadow-internal noise);
+a template that failed to parse contributes a single error at the file head.
+Shared by `abide check` (one-shot render) and the LSP (per-file publish).
+*/
+export function collectAbideDiagnostics(shadow: ShadowProgram): AbideDiagnostic[] {
+    const { program, shadows, parseErrors, abidePaths } = shadow
+    const diagnostics: AbideDiagnostic[] = []
+    for (const abidePath of abidePaths) {
+        const parseError = parseErrors.get(abidePath)
+        if (parseError !== undefined) {
+            diagnostics.push({
+                file: abidePath,
+                start: 0,
+                length: 0,
+                message: parseError,
+                category: ts.DiagnosticCategory.Error,
+            })
+            continue
+        }
+        const sourceFile = program.getSourceFile(`${abidePath}.ts`)
+        const mappings = shadows.get(abidePath)?.mappings
+        if (sourceFile === undefined || mappings === undefined) {
+            continue
+        }
+        const raw = [
+            ...program.getSyntacticDiagnostics(sourceFile),
+            ...program.getSemanticDiagnostics(sourceFile),
+        ]
+        for (const diagnostic of raw) {
+            if (diagnostic.start === undefined) {
+                continue
+            }
+            const located = remapShadowDiagnostic(
+                mappings,
+                diagnostic.start,
+                diagnostic.length ?? 0,
+            )
+            if (located === undefined) {
+                continue
+            }
+            diagnostics.push({
+                file: abidePath,
+                start: located.start,
+                length: located.length,
+                message: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'),
+                category: diagnostic.category,
+            })
+        }
+    }
+    return diagnostics
+}

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

@@ -0,0 +1,20 @@
+import { analyzeComponent } from './analyzeComponent.ts'
+import { generateBuild } from './generateBuild.ts'
+import { hoistCells } from './hoistCells.ts'
+
+/*
+Compiles a single-file abide component into the body of a client build function.
+Runs the shared front-end (`analyzeComponent`), generates the DOM build from the
+template, and hoists static paths to cells. The returned body runs against a
+`host` element with `doc`/`state`/`derived`/`effect` and the dom bindings in
+scope and defines `model` itself. `compileModule` wraps it (and the SSR body) into
+a real module; tests wrap it with `new Function`.
+*/
+export function compileComponent(source: string, isLayout = false, scopeSeed?: string): string {
+    const { script, stateNames, derivedNames, nodes } = analyzeComponent(source, scopeSeed)
+    const build = generateBuild(nodes, 'host', stateNames, derivedNames, isLayout)
+    /* The scoped CSS is bundled into the entry stylesheet (see `abideUiPlugin`), not
+       injected at runtime; the build only needs the `data-a-…` scope attributes on
+       elements, which `generateBuild` reads from each node's annotated `scopes`. */
+    return `${script}\n${hoistCells(build, 'model')}`
+}

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

@@ -0,0 +1,116 @@
+import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
+import { analyzeComponent } from './analyzeComponent.ts'
+import { compileComponent } from './compileComponent.ts'
+import { compileSSR } from './compileSSR.ts'
+import { UI_RUNTIME_IMPORTS } from './UI_RUNTIME_IMPORTS.ts'
+
+/*
+Wraps a component into a complete ES module with two entry points:
+
+  - default `component(host, $props)` — mounts the client build, returns the
+    disposer (`import Counter from './Counter.abide'; const stop = Counter(host)`);
+  - `render($props)` — server-renders to `{ html, state, awaits }` for SSR.
+
+`render` is also attached to the default export (`component.render`) so a parent
+can server-render a child it imported by its default name. Both entry points share
+the lowered script and template (via the shared front-end), so client and server
+always agree. The `abide/ui/*` imports resolve through the package exports. This is
+what the `.abide` bundler loader emits.
+*/
+export function compileModule(
+    source: string,
+    options: { isLayout?: boolean; moduleId?: string; hot?: boolean } = {},
+): string {
+    const isLayout = options.isLayout ?? false
+    /* Component-authored imports (e.g. child components) hoisted to module scope. */
+    const analyzed = analyzeComponent(source)
+    const userImports = analyzed.imports
+    const body = indent(compileComponent(source, isLayout, options.moduleId))
+
+    /* Hot module (dev component HMR): the same client build, but its runtime comes
+       from the live bundle via `window.__abide` — so it shares the one reactive graph
+       and instance registry, not fresh copies — and on load it hands the new factory
+       to `hotReplace`, which disposes + re-runs every live instance in place. No SSR /
+       hydrate / export: it is imported only to replace, never mounted fresh. Supports
+       leaf components today; one importing children falls back to a reload (the dev
+       layer decides what to hot-swap). */
+    if (options.hot) {
+        const names = UI_RUNTIME_IMPORTS.map((entry) => entry.name).join(', ')
+        const id = JSON.stringify(options.moduleId)
+        return `const { ${names}, hotReplace } = window.__abide
+${userImports}
+function component(host, $props) {
+    return mount(host, (host) => {
+${body}
+    })
+}
+component.__abideId = ${id}
+if (!hotReplace(${id}, component)) location.reload()
+`
+    }
+
+    const ssrBody = indent(compileSSR(source, isLayout, options.moduleId))
+    /* Per-component dead-import elimination: emit only the runtime names this module
+       actually references. A component that uses no `each`/`await`/`html` shouldn't
+       drag those modules into its chunk. The package isn't globally side-effect-free
+       (the dev/runtime entries register globals), so a bundler can't tree-shake the
+       unused imports for us — but the generated code is the one place that knows
+       exactly which names it emitted, so it filters here. A name absent from the body
+       is unreferenced; erring toward inclusion (a stray match in user script) only
+       keeps a harmless unused import, never drops a needed one. */
+    const moduleBody = `export default function component(host, $props) {
+    return mount(host, (host) => {
+${body}
+    })
+}
+
+/* Adopt the server-rendered DOM in place instead of rebuilding it. */
+export function hydrateInto(host, $props) {
+    return hydrate(host, (host) => {
+${body}
+    })
+}
+
+export function render($props) {
+${ssrBody}
+}
+
+component.render = render
+component.hydrate = hydrateInto
+component.hydratable = ${analyzed.hydratable}
+${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(options.moduleId)}\n`}`
+    /* Scope each name to the surface that genuinely references it. The SSR body
+       carries fixed boilerplate ($attr/$text helpers, `<!--abide:html-->` markers,
+       the `{ html, state, awaits }` return shape) whose substrings would falsely
+       match value/DOM imports — so client helpers are matched against the client
+       build, render-pass helpers against the SSR body, and the two wrapper calls
+       (mount/hydrate) are always present. */
+    const clientSurface = `${userImports}\n${body}`
+    const isReferenced = (entry: { name: string; specifier: string }): boolean => {
+        if (entry.name === 'mount' || entry.name === 'hydrate') {
+            return true
+        }
+        /* Render-pass helpers are emitted by both back-ends (e.g. client and server
+           await/try blocks both call nextBlockId); their names are distinctive enough
+           that scanning both surfaces adds no false match. */
+        const surface = entry.specifier.startsWith('ui/runtime/')
+            ? `${clientSurface}\n${ssrBody}`
+            : clientSurface
+        return new RegExp(`\\b${entry.name}\\b`).test(surface)
+    }
+    const importBlock = UI_RUNTIME_IMPORTS.filter(isReferenced)
+        .map((entry) => `import { ${entry.name} } from '${ABIDE_PACKAGE_NAME}/${entry.specifier}'`)
+        .join('\n')
+    return `${importBlock}
+${userImports}
+
+${moduleBody}`
+}
+
+/* Indents a body block for embedding inside a wrapper function. */
+function indent(body: string): string {
+    return body
+        .split('\n')
+        .map((line) => (line === '' ? line : `    ${line}`))
+        .join('\n')
+}