@abide/abide 0.43.1 → 0.44.1

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)
     }
@@ -80,9 +97,13 @@ export function compileShadow(source: string): CompiledShadow {
     for (const line of scope) {
         builder.flush(line)
     }
-    emitNodes(parseTemplate(source.slice(templateStart), templateStart).nodes, builder)
+    const templateNodes = parseTemplate(source.slice(templateStart), templateStart).nodes
+    /* Nested `<script>` blocks inline into the synchronous `build()` too, so a top-level
+       await in one is the same build-breaker — flag it, mapped via the node's body offset. */
+    collectNestedScriptAwaitDiagnostics(templateNodes, diagnostics)
+    emitNodes(templateNodes, builder)
     builder.raw('}\n')
-    return builder.result()
+    return { ...builder.result(), diagnostics }
 }
 
 /* The shadow text builder: `raw` appends synthesised scaffolding (no mapping),
@@ -162,6 +183,106 @@ 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)
+}
+
+/* Pushes a diagnostic for every `await` sitting at the script's top level — outside any
+   nested function. The generated `build()` runs the leading script synchronously, so a
+   top-level await transpiles to `await` in a non-async function and breaks the bundle; the
+   shadow's render fn is async, so `tsc` alone never flags it (a check/runtime parity gap).
+   Stops descending at function boundaries — their own async-ness is the author's concern —
+   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. */
+function collectTopLevelAwaitDiagnostics(
+    file: ts.SourceFile,
+    scriptStart: number,
+    diagnostics: ShadowDiagnostic[],
+): void {
+    const message =
+        'top-level `await` is not allowed in a `<script>` — the component build runs synchronously. Use `{#await expr}…{:then value}…{/await}` markup for blocking data, or `await` inside an async event handler.'
+    const visit = (node: ts.Node): void => {
+        /* A nested function introduces its own (possibly async) scope; its awaits are legal. */
+        if (
+            ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isArrowFunction(node) ||
+            ts.isMethodDeclaration(node) ||
+            ts.isGetAccessorDeclaration(node) ||
+            ts.isSetAccessorDeclaration(node) ||
+            ts.isConstructorDeclaration(node)
+        ) {
+            return
+        }
+        /* The `await` keyword token: the AwaitExpression's first child, or a `for await`'s
+           await modifier. */
+        const keyword = ts.isAwaitExpression(node)
+            ? node.getChildAt(0, file)
+            : ts.isForOfStatement(node)
+              ? node.awaitModifier
+              : undefined
+        if (keyword !== undefined) {
+            diagnostics.push({
+                start: scriptStart + keyword.getStart(file),
+                length: keyword.getEnd() - keyword.getStart(file),
+                message,
+            })
+        }
+        ts.forEachChild(node, visit)
+    }
+    visit(file)
+}
+
+/* Recursively visits every nested `<script>` in the template and flags a top-level await in
+   its body — the same trap as the leading script (it inlines into the sync `build()`), mapped
+   through the node's body offset (`loc`). Walks `children` on every node kind that carries
+   them, so a script buried in an `{#if}`/`{#for}`/`{#await}` branch is still reached. */
+function collectNestedScriptAwaitDiagnostics(
+    nodes: TemplateNode[],
+    diagnostics: ShadowDiagnostic[],
+): void {
+    for (const node of nodes) {
+        if (node === undefined) {
+            continue
+        }
+        if (node.kind === 'script' && node.loc !== undefined) {
+            const file = ts.createSourceFile('nested.ts', node.code, ts.ScriptTarget.Latest, true)
+            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics)
+        }
+        if ('children' in node) {
+            collectNestedScriptAwaitDiagnostics(node.children, diagnostics)
+        }
+    }
 }
 
 /* Walks the leading `<script>` and produces the shadow's module imports, the
@@ -173,10 +294,18 @@ 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)
+    /* The leading script runs in the synchronous `build()`, so a top-level await breaks the
+       bundle — catch it here with a legible message instead of an opaque transpile error. */
+    collectTopLevelAwaitDiagnostics(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 +317,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 +350,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 +506,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'
@@ -46,6 +47,21 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
     const versions = new Map<string, number>()
     const shadows = new Map<string, CompiledShadow>()
     const parseErrors = new Map<string, string>()
+    /* Memo of `shadowText` output keyed by source path, tagged with the shadow
+       version it was compiled at; a stale tag forces recompilation. `update`/`close`
+       bump that version, so the next read recompiles. */
+    const compiledAt = new Map<string, { version: number; code: string }>()
+    /* Memo of `pagePropsType` (route re-parse) per source path; the path → props
+       type mapping is immutable, so no version tag is needed. */
+    const propsTypes = new Map<string, string | undefined>()
+
+    /* The route props type for a component, parsed once and reused. */
+    const propsTypeOf = (abidePath: string): string | undefined => {
+        if (!propsTypes.has(abidePath)) {
+            propsTypes.set(abidePath, pagePropsType(abidePath))
+        }
+        return propsTypes.get(abidePath)
+    }
 
     /* Ambient declarations for bundler-handled asset imports (`*.css`, …). */
     const assets = assetModulesFile(cwd)
@@ -54,18 +70,29 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
         overlays.has(abidePath) || ts.sys.fileExists(abidePath)
 
     /* Compiles (and caches) a component's shadow from its overlay or disk text; a
-       template parse error yields a minimal valid module + a recorded message. */
+       template parse error yields a minimal valid module + a recorded message.
+       Memoised against the shadow's version (bumped by `update`/`close`), so
+       repeated reads at the same version skip the ~700-line compile and the
+       `shadows`/`parseErrors` caches stay current. */
     const shadowText = (abidePath: string): string => {
+        const version = versions.get(suffixed(abidePath)) ?? 0
+        const memo = compiledAt.get(abidePath)
+        if (memo !== undefined && memo.version === version) {
+            return memo.code
+        }
         const source = overlays.get(abidePath) ?? ts.sys.readFile(abidePath) ?? ''
         try {
-            const compiled = compileShadow(source)
+            const compiled = compileShadow(source, propsTypeOf(abidePath))
             shadows.set(abidePath, compiled)
             parseErrors.delete(abidePath)
+            compiledAt.set(abidePath, { version, code: compiled.code })
             return compiled.code
         } catch (error) {
             shadows.set(abidePath, { code: '', mappings: [] })
             parseErrors.set(abidePath, messageFromError(error))
-            return 'export default function (): void {}\n'
+            const code = 'export default function (): void {}\n'
+            compiledAt.set(abidePath, { version, code })
+            return code
         }
     }
 
@@ -240,6 +267,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