@abide/abide 0.43.1 → 0.44.0

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

@@ -6,9 +6,9 @@ import type { AnalyzedComponent } from './types/AnalyzedComponent.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`/`computed`/`effect` and the dom bindings in
-scope and defines `model` itself. `compileModule` wraps it (and the SSR body) into
+template, and hoists static paths to cells. The returned body operates on `host`
+with the `$$`-prefixed dom bindings and `$$model` in scope (the latter emitted by
+`desugarSignals`). `compileModule` wraps it (and the SSR body) into
 a real module; tests wrap it with `new Function`.
 
 `analyzed` is a lazy default: a direct caller (tests) omits it and the front-end
@@ -26,5 +26,5 @@ export function compileComponent(
     /* 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')}`
+    return `${script}\n${hoistCells(build, '$$model')}`
 }

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

@@ -44,7 +44,13 @@ export function compileModule(
        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(', ')
+        /* Bridge keys are the bare source names; bind each to its emitted local (`$$`
+           alias when set), so the hot body's `$$mountChild(...)` resolves. */
+        const names = UI_RUNTIME_IMPORTS.map((entry) =>
+            entry.alias === undefined || entry.alias === entry.name
+                ? entry.name
+                : `${entry.name}: ${entry.alias}`,
+        ).join(', ')
         const id = JSON.stringify(options.moduleId)
         return `const { ${names}, hotReplace } = window.__abide
 ${userImports}
@@ -52,7 +58,7 @@ function build(host, $props) {
 ${body}
 }
 function component(host, $props) {
-    return mount(host, build, $props)
+    return $$mount(host, build, $props)
 }
 component.build = build
 component.__abideId = ${id}
@@ -66,12 +72,12 @@ ${body}
 }
 
 export default function component(host, $props) {
-    return mount(host, build, $props)
+    return $$mount(host, build, $props)
 }
 
 /* Adopt the server-rendered DOM in place instead of rebuilding it. */
 export function hydrateInto(host, $props) {
-    return hydrate(host, build, $props)
+    return $$hydrate(host, build, $props)
 }
 
 export function render($props, $ctx) {
@@ -96,8 +102,16 @@ ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(
        forces a spurious import, so no per-surface scoping is needed: a client-only helper
        simply doesn't appear as an identifier in the SSR body. */
     const referenced = collectIdentifiers(`${userImports}\n${body}\n${ssrBody}\n${moduleBody}`)
-    const importBlock = UI_RUNTIME_IMPORTS.filter((entry) => referenced.has(entry.name))
-        .map((entry) => `import { ${entry.name} } from '${ABIDE_PACKAGE_NAME}/${entry.specifier}'`)
+    const importBlock = UI_RUNTIME_IMPORTS.filter((entry) =>
+        referenced.has(entry.alias ?? entry.name),
+    )
+        .map((entry) => {
+            const local =
+                entry.alias === undefined || entry.alias === entry.name
+                    ? entry.name
+                    : `${entry.name} as ${entry.alias}`
+            return `import { ${local} } from '${ABIDE_PACKAGE_NAME}/${entry.specifier}'`
+        })
         .join('\n')
     const module = `${importBlock}
 ${userImports}

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

@@ -5,17 +5,20 @@ import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 
 /*
 Compiles a component into the body of a server render function. Runs the shared
-front-end, then the SSR back-end, and returns `{ html, state, awaits }`:
+front-end, then the SSR back-end, and returns `{ html, state, awaits, resume }`:
 
   - `html`  — server-rendered markup (await blocks render their pending shell);
   - `state` — the document snapshot the client adopts on resume;
   - `awaits` — pending await blocks (id + promise + resolved/error renderers) that
-    `renderToStream` flushes out of order; empty for a fully synchronous component.
+    `renderToStream` flushes out of order; empty for a fully synchronous component;
+  - `resume` — blocking await values rendered inline, keyed by boundary id, seeded
+    into the hydration manifest.
 
 Effects are stripped — they are client lifecycle and emit no HTML, so the server
 render is a snapshot of the markup before any effect runs.
 
-Defines `model` with `doc`/`state`/`computed`/`effect` in scope. The block-id counter is
+Defines `$$model` via the lowered script; the reactive scope is entered via `$$enterScope`
+and exited in a `finally` block. The block-id counter is
 the request-local `$ctx` (threaded into child renders), not a module global — a blocking
 `await` block awaits its promise at its structural position and renders inline, so ids
 allocate depth-first like the client; render yields at that `await`, and a shared global
@@ -29,10 +32,9 @@ purely synchronous / streaming-await / try-only component returns `SsrRender` di
 framework always `await`s `render()`, so production is uniform either way; the sync return
 keeps static pages off the microtask queue and leaves the bulk of the SSR tests synchronous.
 
-The reactive scope brackets the body; it is entered synchronously before any inline `await`,
-so `const model = scope()` resolves correctly, and `model` is captured for the rest of the
-render (its reads are object-method calls, not scope lookups, so they stay correct across
-the awaits).
+The reactive scope brackets the body: `$$enterScope()` runs synchronously before any inline
+`await`, and `$$model` is captured for the rest of the render (its reads are object-method
+calls, not scope lookups, so they stay correct across the awaits).
 
 `analyzed` is a lazy default: a direct caller (tests) omits it and the front-end
 runs here, but `compileModule` shares one analysis across both back-ends.
@@ -51,9 +53,9 @@ export function compileSSR(
     /* `typeof model` guards a component with no reactive state (a pure-async or
        static component declares no `model`); its snapshot is then empty. */
     const body =
-        `const $scope = enterScope();\ntry {\n${lowered}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\nconst $resume = {};\n${ssr}` +
-        `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits, resume: $resume };\n` +
-        `} finally { exitScope($scope); }`
+        `const $scope = $$enterScope();\ntry {\n${lowered}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\nconst $resume = {};\n${ssr}` +
+        `return { html: $out.join(''), state: (typeof $$model !== 'undefined' ? $$model.snapshot() : {}), awaits: $awaits, resume: $resume };\n` +
+        `} finally { $$exitScope($scope); }`
     /* An inline `await` — a blocking await block, a child render, a slot read, or a
        top-level `await` in the author script — forces an async wrapper. Match `await` as a
        standalone token (operator), so a no-space form (`await(x)`, `await[i]`, `` await`t` ``)

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

@@ -2,12 +2,24 @@ import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
 import { parseTemplate } from './parseTemplate.ts'
 import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
-import type { CompiledShadow, ShadowMapping } from './types/CompiledShadow.ts'
+import type { CompiledShadow, ShadowDiagnostic, ShadowMapping } from './types/CompiledShadow.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
+/*
+Runtime helpers published as package subpaths solely so generated component code
+can import them; an author must reach them through their namespaced surface
+instead. The module resolver can't tell codegen from user source (same specifier),
+so the ban can only live in the check — map each forbidden specifier to the
+guidance shown when an author imports it.
+*/
+const INTERNAL_ONLY_IMPORTS: Record<string, string> = {
+    [`${ABIDE_PACKAGE_NAME}/ui/effect`]:
+        '`effect` is compiler-internal — author it as `scope().effect(...)`',
+}
+
 /*
 Framework callables the `.abide` loader injects into a component's scope. `effect`,
-`html`, `snippet`, and `scope` keep their real published types via imports so author
+`snippet`, and `scope` keep their real published types via imports so author
 calls type-check — `scope()` is the authored reactive surface (`scope().state(...)` /
 `.computed(...)` / `.undo()` …), so it must resolve like any import. `state`/`linked`/
 `computed` are ALSO declared ambiently as a fallback for the rare bare/nested use the
@@ -18,14 +30,13 @@ argument (default `Record<string, any>`) so each binding inherits its prop type
 `= default` narrows.
 */
 const SHADOW_PREAMBLE = `import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'
-import { html } from '${ABIDE_PACKAGE_NAME}/shared/html'
 import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'
 import { scope } from '${ABIDE_PACKAGE_NAME}/ui/scope'
 declare function state<T>(initial?: T, transform?: (next: T, previous: T) => T): { value: T }
 declare function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): { value: T }
 declare function computed<T>(compute: () => T): { readonly value: T }
-declare function props<T = Record<string, any>>(): T
-void [effect, html, snippet, scope]
+declare const children: (() => void) | undefined
+void [effect, snippet, scope]
 `
 
 /*
@@ -43,7 +54,7 @@ The script's signal surface is rewritten to value types:
 Everything else (functions, plain consts, imports) is emitted verbatim, so
 expressions inside it (e.g. a computed's compute body) are checked and mapped too.
 */
-export function compileShadow(source: string): CompiledShadow {
+export function compileShadow(source: string, propsType = 'Record<string, any>'): CompiledShadow {
     const builder = createBuilder()
     const leadingScript = source.match(/^\s*<script[^>]*>([\s\S]*?)<\/script>/)
     const scriptBody = leadingScript?.[1] ?? ''
@@ -51,8 +62,14 @@ export function compileShadow(source: string): CompiledShadow {
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, types, scope, propsShapes } = analyzeScript(scriptBody, scriptStart)
+    const { imports, types, scope, propsShapes, diagnostics } = analyzeScript(
+        scriptBody,
+        scriptStart,
+    )
     builder.raw(SHADOW_PREAMBLE)
+    /* `props()` defaults to the file's type — a page/layout's route param shape, else
+       `Record<string, any>` — so `const { id } = props()` infers from the route. */
+    builder.raw(`declare function props<T = ${propsType}>(): T\n`)
     for (const line of imports) {
         builder.flush(line)
     }
@@ -82,7 +99,7 @@ export function compileShadow(source: string): CompiledShadow {
     }
     emitNodes(parseTemplate(source.slice(templateStart), templateStart).nodes, builder)
     builder.raw('}\n')
-    return builder.result()
+    return { ...builder.result(), diagnostics }
 }
 
 /* The shadow text builder: `raw` appends synthesised scaffolding (no mapping),
@@ -162,6 +179,39 @@ type ScriptAnalysis = {
     types: ScopeLine[]
     scope: ScopeLine[]
     propsShapes: string[]
+    diagnostics: ShadowDiagnostic[]
+}
+
+/* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
+   prefix — variable/function/class declarations, parameters, and destructuring leaves.
+   Read structurally off the parsed script; the message points at the offending name. */
+function collectReservedNameDiagnostics(
+    file: ts.SourceFile,
+    scriptStart: number,
+    diagnostics: ShadowDiagnostic[],
+): void {
+    const flag = (name: ts.Node | undefined): void => {
+        if (name !== undefined && ts.isIdentifier(name) && name.text.startsWith('$$')) {
+            diagnostics.push({
+                start: scriptStart + name.getStart(file),
+                length: name.getEnd() - name.getStart(file),
+                message: `\`${name.text}\` is reserved — the \`$$\` prefix is the compiler's injected runtime namespace; rename this binding.`,
+            })
+        }
+    }
+    const visit = (node: ts.Node): void => {
+        if (
+            ts.isVariableDeclaration(node) ||
+            ts.isFunctionDeclaration(node) ||
+            ts.isClassDeclaration(node) ||
+            ts.isParameter(node) ||
+            ts.isBindingElement(node)
+        ) {
+            flag(node.name)
+        }
+        ts.forEachChild(node, visit)
+    }
+    visit(file)
 }
 
 /* Walks the leading `<script>` and produces the shadow's module imports, the
@@ -173,10 +223,15 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     const types: ScopeLine[] = []
     const scope: ScopeLine[] = []
     const propsShapes: string[] = []
+    const diagnostics: ShadowDiagnostic[] = []
     if (scriptBody.trim() === '') {
-        return { imports, types, scope, propsShapes }
+        return { imports, types, scope, propsShapes, diagnostics }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
+    /* The `$$` prefix is reserved for the compiler's injected runtime (`$$each`, `$$model`,
+       `$$scope`, …), so an author binding may not start with it — that's the contract that
+       lets a user freely name a variable after any helper. Flag every such declaration. */
+    collectReservedNameDiagnostics(file, scriptStart, diagnostics)
     /* A verbatim span: original text + the segment mapping it back, relative to the
        line start (the caller rebases shadowStart onto the running shadow length). */
     const span = (node: ts.Node, prefixLength: number): ScopeLine['segments'][number] => ({
@@ -188,6 +243,20 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
 
     for (const statement of file.statements) {
         if (ts.isImportDeclaration(statement)) {
+            const specifier = ts.isStringLiteral(statement.moduleSpecifier)
+                ? statement.moduleSpecifier.text
+                : undefined
+            const banned = specifier !== undefined ? INTERNAL_ONLY_IMPORTS[specifier] : undefined
+            if (banned !== undefined) {
+                /* Flag and drop it — leaving it out keeps `effect` resolving via the
+                   preamble (no duplicate-identifier noise on top of our message). */
+                diagnostics.push({
+                    start: scriptStart + statement.getStart(file),
+                    length: statement.getEnd() - statement.getStart(file),
+                    message: banned,
+                })
+                continue
+            }
             /* Emit verbatim with a span so hover/go-to resolve on the imported names. */
             imports.push({ text: verbatim(statement), segments: [span(statement, 0)] })
             continue
@@ -207,7 +276,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, propsShapes, verbatim, span))
         }
     }
-    return { imports, types, scope, propsShapes }
+    return { imports, types, scope, propsShapes, diagnostics }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`
@@ -363,7 +432,15 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             return
         case 'element':
             for (const attr of node.attrs) {
-                if (attr.kind !== 'static') {
+                /* An interpolated value checks each `{expr}` part on its own offset; every
+                   other dynamic attribute checks its single `code`. */
+                if (attr.kind === 'interpolated') {
+                    for (const part of attr.parts) {
+                        if (part.kind === 'expression') {
+                            builder.stmt(part.code, part.loc)
+                        }
+                    }
+                } else if (attr.kind !== 'static') {
                     builder.stmt(attr.code, attr.loc)
                 }
             }

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

@@ -9,7 +9,7 @@ The props-bag source expression a child mount/render receives, shared by the bui
 and SSR back-ends so their last-wins layering stays byte-identical — the invariant
 SSR/client prop congruence rests on. No spread → the plain object literal of named
 value thunks (+ the trailing slot). With a `{...expr}` spread → a `mergeProps` of
-ordered layers — explicit-prop runs, `spreadProps(expr)` spreads, the slot —
+ordered layers — explicit-prop runs, `$$spreadProps(expr)` spreads, the slot —
 resolved last-wins per key, so source order decides overrides (like JSX).
 `lowerExpression` is the caller's expression lowering; `slotPart` is its `$children`
 layer (a host-taking builder for the client, a string-returning thunk for SSR) or
@@ -40,7 +40,7 @@ export function composeProps(
     for (const prop of props) {
         if (prop.spread) {
             flushRun()
-            layers.push(`spreadProps(() => (${lowerExpression(prop.code)}))`)
+            layers.push(`$$spreadProps(() => (${lowerExpression(prop.code)}))`)
         } else {
             run.push(propThunk(prop))
         }
@@ -49,5 +49,5 @@ export function composeProps(
     if (slotPart !== undefined) {
         layers.push(`{ ${slotPart} }`)
     }
-    return `mergeProps([${layers.join(', ')}])`
+    return `$$mergeProps([${layers.join(', ')}])`
 }

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

@@ -1,10 +1,11 @@
 import { resolve } from 'node:path'
 import ts from 'typescript'
 import { messageFromError } from '../../shared/messageFromError.ts'
-import { mapTsClassification } from './ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
+import { mapSyntacticClassification, mapTsClassification } from './ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
 import { compileShadow } from './compileShadow.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
+import { pagePropsType } from './pagePropsType.ts'
 import { remapShadowDiagnostic } from './remapShadowDiagnostic.ts'
 import { resolveAbideImports } from './resolveAbideImports.ts'
 import { shadowNaming } from './shadowNaming.ts'
@@ -58,7 +59,7 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
     const shadowText = (abidePath: string): string => {
         const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
         try {
-            const compiled = compileShadow(source)
+            const compiled = compileShadow(source, pagePropsType(abidePath))
             shadows.set(abidePath, compiled)
             parseErrors.delete(abidePath)
             return compiled.code
@@ -240,6 +241,33 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
                     modifiers: mapped.modifiers,
                 })
             }
+            /* Literal syntactic tokens (string/number/regex) the semantic classifier
+               never emits — so a template-literal string inside `{…}` gets colored. */
+            const syntactic = service.getEncodedSyntacticClassifications(fileName, {
+                start: 0,
+                length: shadow.code.length,
+            })
+            for (let index = 0; index + 2 < syntactic.spans.length; index += 3) {
+                const spanStart = syntactic.spans[index]
+                const spanLength = syntactic.spans[index + 1]
+                const classification = syntactic.spans[index + 2]
+                if (
+                    spanStart === undefined ||
+                    spanLength === undefined ||
+                    classification === undefined
+                ) {
+                    continue
+                }
+                const type = mapSyntacticClassification(classification)
+                if (type === undefined) {
+                    continue
+                }
+                const located = remapShadowDiagnostic(shadow.mappings, spanStart, spanLength)
+                if (located === undefined) {
+                    continue
+                }
+                tokens.push({ start: located.start, length: located.length, type, modifiers: [] })
+            }
             return tokens
         },
     }

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

@@ -4,6 +4,7 @@ import { messageFromError } from '../../shared/messageFromError.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
 import { compileShadow } from './compileShadow.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
+import { pagePropsType } from './pagePropsType.ts'
 import { resolveAbideImports } from './resolveAbideImports.ts'
 import { shadowNaming } from './shadowNaming.ts'
 import type { CompiledShadow } from './types/CompiledShadow.ts'
@@ -46,7 +47,7 @@ export function createShadowProgram(cwd: string, abidePaths?: string[]): ShadowP
     const shadowText = (abidePath: string): string => {
         const source = ts.sys.readFile(abidePath) ?? ''
         try {
-            const compiled = compileShadow(source)
+            const compiled = compileShadow(source, pagePropsType(abidePath))
             shadows.set(abidePath, compiled)
             parseErrors.delete(abidePath)
             return compiled.code

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

@@ -0,0 +1,42 @@
+import type { ShadowKind } from './types/ShadowKind.ts'
+import type { ShadowScope } from './types/ShadowScope.ts'
+
+/*
+Builds a fresh `ShadowScope` — the typed, auto-popping branch-local shadow stack. One
+`Set` per `ShadowKind`, reached only through `withShadow` (push on entry, pop in a
+`finally`), never directly. The `finally` is the safety move: the old hand-written
+pop ran after the body returned, so any throw inside the body (e.g. SSR's `await then`
+TDZ path) leaked the branch's shadows into every later sibling. Here the pop is
+unconditional, so a branch's shadows cannot outlive the branch.
+*/
+export function createShadowScope(): ShadowScope {
+    const byKind: Record<ShadowKind, Set<string>> = {
+        derived: new Set<string>(),
+        plain: new Set<string>(),
+    }
+
+    function withShadow<T>(names: Iterable<string>, kind: ShadowKind, body: () => T): T {
+        const scope = byKind[kind]
+        /* Track only the names this call newly added, so a name already shadowing from an
+           outer branch survives this branch's pop. */
+        const added: string[] = []
+        for (const name of names) {
+            if (!scope.has(name)) {
+                scope.add(name)
+                added.push(name)
+            }
+        }
+        try {
+            return body()
+        } finally {
+            for (const name of added) {
+                scope.delete(name)
+            }
+        }
+    }
+
+    return {
+        withShadow,
+        names: (kind) => byKind[kind],
+    }
+}

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

@@ -15,6 +15,10 @@ const NAMED_ENTITIES: Record<string, string> = {
     gt: '>',
     quot: '"',
     apos: "'",
+    /* A literal brace where `{` would otherwise open an interpolation (text or
+       attribute value); written `&lbrace;` / `&rbrace;`. */
+    lbrace: '{',
+    rbrace: '}',
     nbsp: ' ',
     copy: '©',
     reg: '®',

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

@@ -152,11 +152,12 @@ export function desugarSignals(source: ts.SourceFile): {
             return root
         }
         const statements: ts.Statement[] = []
-        /* A shared `model = scope()` host for the state slots, prepended once. */
+        /* A shared `$$model = scope()` host for the state slots, prepended once. The doc
+           base is `$$`-reserved so a user variable named `model` can never collide. */
         if (stateNames.size > 0) {
             statements.push(
                 constDeclaration(
-                    'model',
+                    '$$model',
                     factory.createCallExpression(factory.createIdentifier('scope'), undefined, []),
                 ),
             )
@@ -425,10 +426,14 @@ function propsStatements(statement: ts.Statement): ts.Statement[] | undefined {
             statements.push(
                 constDeclaration(
                     rest,
-                    factory.createCallExpression(factory.createIdentifier('restProps'), undefined, [
-                        factory.createIdentifier('$props'),
-                        factory.createArrayLiteralExpression(consumed),
-                    ]),
+                    factory.createCallExpression(
+                        factory.createIdentifier('$$restProps'),
+                        undefined,
+                        [
+                            factory.createIdentifier('$props'),
+                            factory.createArrayLiteralExpression(consumed),
+                        ],
+                    ),
                 ),
             )
         }
@@ -457,7 +462,7 @@ function stateAssignmentStatements(statement: ts.Statement): ts.Statement[] | un
             factory.createExpressionStatement(
                 factory.createAssignment(
                     factory.createPropertyAccessExpression(
-                        factory.createIdentifier('model'),
+                        factory.createIdentifier('$$model'),
                         declaration.name.text,
                     ),
                     initial,

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

@@ -0,0 +1,61 @@
+import { catchBinding } from './catchBinding.ts'
+import { resolveBranches } from './resolveBranches.ts'
+import type { Binding } from './types/Binding.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The structural shape of an `each`/`for` loop, resolved once so the build and SSR back-ends
+   share one reading of it and only own emission. Both previously read the item/index/key
+   names, the `async` split, and the row children straight off the node; build additionally
+   resolved the async-each `catch` branch. The names the row introduces are now classified
+   ONCE here as `bindings` (item + index, both `reactive`) and `catchBindings` (the async-each
+   `catch` error, `plain`) — the single source both back-ends register through `withBindings`. */
+export type EachPlan = {
+    /* The list expression — an Array (sync) or AsyncIterable (`async`). */
+    items: string
+    /* The item binding pattern (`node.as`): a plain identifier or a destructuring pattern. */
+    as: string
+    /* `by={k}` key expression, or undefined → key on the item's own identity. */
+    key: string | undefined
+    /* `index="i"` → the row's position bound to this name; undefined → unbound. */
+    index: string | undefined
+    /* `await` on the tag → `items` is an AsyncIterable, drained on the client. */
+    async: boolean
+    /* The row content. */
+    children: TemplateNode[]
+    /* The async-each `catch` content + its bound name (`_error` default); empty when absent.
+       Build renders it after the streamed rows on iterator rejection; SSR renders no async
+       rows so it ignores this. */
+    catchChildren: TemplateNode[]
+    catchAs: string
+    /* No catch → the rejection surfaces instead of rendering an empty branch. */
+    hasCatch: boolean
+    /* The row body's bindings, classified once: the item (`as`) and, when present, the
+       `index`, both `reactive` (a `.value` cell on the client). */
+    bindings: Binding[]
+    /* The async-each `catch` branch's binding (`catchAs`, `plain`); empty when no catch. */
+    catchBindings: Binding[]
+}
+
+/* Resolves an `each` node's structure into the shared structural plan. */
+export function eachPlan(node: Extract<TemplateNode, { kind: 'each' }>): EachPlan {
+    const [catchBranch] = resolveBranches(node, 'catch')
+    const catchAs = catchBranch?.as ?? '_error'
+    return {
+        items: node.items,
+        as: node.as,
+        key: node.key,
+        index: node.index,
+        async: node.async,
+        children: node.children,
+        catchChildren: catchBranch?.children ?? [],
+        catchAs,
+        hasCatch: catchBranch !== undefined,
+        bindings: [
+            { name: node.as, classification: 'reactive' },
+            ...(node.index === undefined
+                ? []
+                : [{ name: node.index, classification: 'reactive' } as const]),
+        ],
+        catchBindings: catchBinding(catchAs, catchBranch !== undefined),
+    }
+}

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

@@ -0,0 +1,55 @@
+import { classStyleMergePlan } from './classStyleMergePlan.ts'
+import type { ElementPlan, ElementPlanAttr } from './types/ElementPlan.ts'
+import type { TemplateAttr } from './types/TemplateAttr.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+import { VOID_TAGS } from './VOID_TAGS.ts'
+
+/*
+The single decision site for one element's attribute emission — lifted out of the two
+hand-mirrored code-gen back-ends (`generateBuild`, `generateSSR`) so the load-bearing
+agreement on which attribute is which kind, which class/style parts merge, and which tag
+is void lives ONCE (ADR-0013, the locality milestone). Each back-end RENDERS the plan
+differently — build wires live effects/thunks, SSR pushes escaped strings — but consults
+the same classification, so the markup the client clones and the server emits cannot drift.
+
+`classStyleMergePlan` folds in as the class/style branch. Each attr is tagged `mergedBuild`
+/`mergedSSR` from the two merge triggers (build merges only on an interpolated base, SSR on
+any directive), so a back-end skips exactly the attrs it folded into its merged class/style
+attribute. The positional holes/anchors stay in `skeletonContext`; this plan layers over it.
+*/
+export function elementPlan(
+    node: Extract<TemplateNode, { kind: 'element' }>,
+    lower: (code: string) => string,
+): ElementPlan {
+    const merge = classStyleMergePlan(node.attrs, lower)
+    /* True when this attr is folded into the build back-end's merged class/style effect — the
+       interpolated base or any directive of a merged property (a static base stays surgical). */
+    const isMergedBuild = (attr: TemplateAttr): boolean =>
+        (merge.mergeClassBuild && (attr === merge.classBase || attr.kind === 'class')) ||
+        (merge.mergeStyleBuild && (attr === merge.styleBase || attr.kind === 'style'))
+    /* True when this attr is folded into the SSR back-end's merged class/style attribute,
+       whenever a directive exists. A `class:`/`style:` directive always folds; a static or
+       interpolated base folds by NAME (so a duplicate `class`/`style` base is folded too,
+       never double-emitted next to the merged attribute — the old SSR by-name skip). */
+    const isMergedSSR = (attr: TemplateAttr): boolean => {
+        if (attr.kind === 'class') {
+            return merge.mergeClass
+        }
+        if (attr.kind === 'style') {
+            return merge.mergeStyle
+        }
+        if (attr.kind === 'static' || attr.kind === 'interpolated') {
+            return (
+                (attr.name === 'class' && merge.mergeClass) ||
+                (attr.name === 'style' && merge.mergeStyle)
+            )
+        }
+        return false
+    }
+    const attrs: ElementPlanAttr[] = node.attrs.map((attr) => ({
+        attr,
+        mergedBuild: isMergedBuild(attr),
+        mergedSSR: isMergedSSR(attr),
+    }))
+    return { attrs, merge, isVoid: VOID_TAGS.has(node.tag) }
+}

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

@@ -10,8 +10,31 @@ by start; tokens with an unknown legend type, and any token overlapping the one
 before it, are dropped — the protocol requires a strictly non-overlapping,
 positionally-ordered stream.
 */
+/*
+A token may span newlines (a multiline template-literal string), but the protocol
+forbids a token crossing a line — so split it into one segment per covered line,
+dropping empty lines. A single-line token returns unchanged.
+*/
+function splitByLine(text: string, token: SemanticToken): SemanticToken[] {
+    const raw = text.slice(token.start, token.start + token.length)
+    if (!raw.includes('\n')) {
+        return [token]
+    }
+    const segments: SemanticToken[] = []
+    let offset = token.start
+    for (const line of raw.split('\n')) {
+        if (line.length > 0) {
+            segments.push({ ...token, start: offset, length: line.length })
+        }
+        offset += line.length + 1
+    }
+    return segments
+}
+
 export function encodeSemanticTokens(text: string, tokens: SemanticToken[]): number[] {
-    const sorted = [...tokens].sort((a, b) => a.start - b.start || a.length - b.length)
+    const sorted = tokens
+        .flatMap((token) => splitByLine(text, token))
+        .sort((a, b) => a.start - b.start || a.length - b.length)
     const data: number[] = []
     let previousLine = 0
     let previousCharacter = 0