@abide/abide 0.38.0 → 0.39.0

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

@@ -1,11 +1,13 @@
+import { OUTLET_CLOSE, OUTLET_OPEN } from '../runtime/OUTLET_MARKER.ts'
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
 import { asOutlet } from './asOutlet.ts'
-import { componentWrapperTag } from './componentWrapperTag.ts'
+import { composeProps } from './composeProps.ts'
 import { groupBindParts } from './groupBindParts.ts'
-import { isControlFlow } from './isControlFlow.ts'
+import { isAnchorPositioned } from './isAnchorPositioned.ts'
 import { lowerContext } from './lowerContext.ts'
 import { scopeAttr } from './scopeAttr.ts'
 import { skeletonContext } from './skeletonContext.ts'
+import { spreadExcludedNames } from './spreadExcludedNames.ts'
 import { staticAttr } from './staticAttr.ts'
 import { staticTextPart } from './staticTextPart.ts'
 import { stripEffects } from './stripEffects.ts'
@@ -37,12 +39,14 @@ listeners). Same expression lowering as the client back-end, so server and clien
 render the same markup. Dynamic values go through `$esc`; `if` is a plain `if`,
 `each` a `for…of`.
 
-An `await` block emits boundary comments (`<!--abide:await:N-->…<!--/abide:await:N-->`)
-and registers the promise plus its resolved/error string-renderers on `$awaits`. A
-streaming block (no `then` on the tag) puts its pending branch between the markers;
-`renderToStream` flushes each resolved fragment out of order — the await-block-streams
-half of the cache rule. A blocking block (`then` on the tag) emits an empty boundary
-and flags the entry, so `renderToStream` settles it before the first flush.
+An `await` block emits boundary comments (`<!--abide:await:N-->…<!--/abide:await:N-->`).
+A streaming block (no `then` on the tag) puts its pending branch between the markers and
+registers the promise + async resolved/error renderers on `$awaits`; `renderToStream`
+flushes each resolved fragment out of order — the await-block-streams half of the cache
+rule. A blocking block (`then` on the tag) is `await`ed INLINE at its structural position
+and its resolved branch rendered between the markers, so the render body is async and its
+id (`$ctx.next++`) allocates depth-first like the client; the resolved value lands in
+`$resume`. Block ids draw from the request-local `$ctx`, shared with inlined child renders.
 */
 export function generateSSR(
     nodes: TemplateNode[],
@@ -52,7 +56,7 @@ export function generateSSR(
     isLayout = false,
 ): string {
     /* Compile-time counter for unique temp var names (runtime block ids, child render
-       results) — block ids themselves are allocated at runtime via nextBlockId(). */
+       results) — block ids themselves are allocated at runtime via `$ctx.next++`. */
     let varCounter = 0
     const nextVar = (prefix: string): string => `${prefix}${varCounter++}`
 
@@ -82,6 +86,75 @@ export function generateSSR(
        through the generic element path exactly as the client clones it. */
     const rootNodes = isLayout ? nodes.map(asOutlet) : nodes
 
+    /* A snippet name (any identifier, `$` included) interpolated into a RegExp must have its
+       regex metacharacters escaped, or e.g. a trailing `$` would read as an end-anchor and the
+       call site would never match — leaving an un-awaited Promise stringified as `[object
+       Promise]`. */
+    const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    /* A leading boundary that, unlike `\b`, also fires before a `$`-leading name: `\b$row`
+       never matches (`$` is a non-word char, so there is no word boundary before it), which
+       would silently miss every `$row(...)` call. A negative lookbehind for word-or-`$`
+       matches the same call sites as `\b` for word-leading names while also catching them. */
+    const callPattern = (name: string): RegExp =>
+        new RegExp(`(?<![$\\w])${escapeRegExp(name)}\\s*\\(`)
+    /* A subtree call to any of `names` from a TEXT interpolation (`name()` / `name(args)`). */
+    const subtreeCalls = (children: TemplateNode[], names: ReadonlySet<string>): boolean =>
+        children.some((child) => {
+            if (child.kind === 'text') {
+                return child.parts.some(
+                    (part) =>
+                        part.kind !== 'static' &&
+                        [...names].some((name) => callPattern(name).test(part.code)),
+                )
+            }
+            return 'children' in child && subtreeCalls(child.children, names)
+        })
+
+    /* Snippet names whose body produces an `await`, so the snippet must be an `async function`
+       and its `{name(...)}` call sites awaited: it inlines a child component / holds an await
+       block (a structural scan), OR it text-calls another async snippet. The latter is a
+       dependency between snippets, so resolve it to a fixpoint — seed with the structural set,
+       then keep adding any snippet that calls an already-async one until nothing changes. */
+    const subtreeAwaits = (children: TemplateNode[]): boolean =>
+        children.some(
+            (child) =>
+                child.kind === 'component' ||
+                child.kind === 'await' ||
+                ('children' in child && subtreeAwaits(child.children)),
+        )
+    const snippetDefs = new Map<string, TemplateNode[]>()
+    const collectSnippetDefs = (children: TemplateNode[]): void => {
+        for (const child of children) {
+            if (child.kind === 'snippet') {
+                snippetDefs.set(child.name, child.children)
+            }
+            if ('children' in child) {
+                collectSnippetDefs(child.children)
+            }
+        }
+    }
+    collectSnippetDefs(rootNodes)
+    const asyncSnippets = new Set<string>()
+    for (const [name, children] of snippetDefs) {
+        if (subtreeAwaits(children)) {
+            asyncSnippets.add(name)
+        }
+    }
+    let grew = true
+    while (grew) {
+        grew = false
+        for (const [name, children] of snippetDefs) {
+            if (!asyncSnippets.has(name) && subtreeCalls(children, asyncSnippets)) {
+                asyncSnippets.add(name)
+                grew = true
+            }
+        }
+    }
+    /* A text-part expression that calls an async snippet, so its value is `await`ed before
+       `$text`. */
+    const callsAsyncSnippet = (code: string): boolean =>
+        [...asyncSnippets].some((name) => callPattern(name).test(code))
+
     /* Per-node skeleton position, computed once. Both back-ends read this single source of
        truth so their `<!--a-->` anchor placement cannot drift — the fresh-context boundaries
        (control-flow branches, component/slot/snippet content) are enumerated there, not
@@ -111,12 +184,12 @@ export function generateSSR(
         inSkeleton.get(node) ? push(target, '<!--a-->') : ''
 
     function generate(node: TemplateNode, target: string): string {
-        /* A control-flow block is positioned by an `<!--a-->` anchor when in a skeleton
-           context. Emit it ONCE here — one decision site gated by the shared `isControlFlow`,
-           mirroring the client's single `skeletonMarkup` control-flow branch — rather than
-           prefixing each block kind's own `anchorMark` call (six sites that had to stay in
-           lock-step). `anchorMark` no-ops outside a skeleton, so non-block nodes ignore it. */
-        const anchor = isControlFlow(node) ? anchorMark(node, target) : ''
+        /* Every kind that mounts as a marker range is positioned by an `<!--a-->` anchor when
+           in a skeleton context: control-flow blocks, child components, and a layout's outlet /
+           a component's `<slot>` (both elements). `isAnchorPositioned` is the ONE decision site
+           (mirrored by the client's `skeletonMarkup`); `anchorMark` no-ops outside a skeleton,
+           so non-anchored nodes ignore the precomputed `anchor`. */
+        const anchor = isAnchorPositioned(node) ? anchorMark(node, target) : ''
         if (node.kind === 'text') {
             return node.parts
                 .map((part) => {
@@ -124,7 +197,14 @@ export function generateSSR(
                         const markup = staticTextPart(part.value)
                         return markup === '' ? '' : push(target, markup)
                     }
-                    const value = `$text(${lowerExpression(part.code)})`
+                    /* A call to an async snippet returns a Promise — `await` it before `$text`.
+                       (The enclosing context is async: the render body and async-snippet bodies.)
+                       Plain expressions stay sync, so a component with only interpolation keeps a
+                       sync render. */
+                    const lowered = lowerExpression(part.code)
+                    const value = callsAsyncSnippet(part.code)
+                        ? `$text(await (${lowered}))`
+                        : `$text(${lowered})`
                     return markText.get(node)
                         ? `${target}.push('<!--a-->' + ${value});\n`
                         : `${target}.push(${value});\n`
@@ -165,7 +245,11 @@ export function generateSSR(
             /* A hoisted function returning the snippet's `$snip`-branded HTML string;
                `{name(args)}` pushes it via `$text`, which wraps it in markers. */
             const body = generateInto(node.children, '$o')
-            return `function ${node.name}(${node.params ?? ''}) {\nconst $o = [];\n${body}return $snip($o.join(''));\n}\n`
+            /* `async` only when the body produces an `await` (it inlines a child component) — then
+               call sites `await` it (`$text(await frag())`). A sync snippet stays a plain function
+               called inline, preserving the sync render contract. */
+            const keyword = asyncSnippets.has(node.name) ? 'async function' : 'function'
+            return `${keyword} ${node.name}(${node.params ?? ''}) {\nconst $o = [];\n${body}return $snip($o.join(''));\n}\n`
         }
         if (node.kind === 'script') {
             /* A scoped reactive block: re-seed its local signals (lowered, in scope)
@@ -198,48 +282,66 @@ export function generateSSR(
             return ''
         }
         if (node.kind === 'component') {
-            /* Server-render the child via its `render` and inline the HTML inside
-               the same wrapper the client mounts into, so SSR and client agree.
-               Props pass as thunks; slot content passes as a string-returning
-               `$children` the child invokes from its <slot>. */
-            const tag = componentWrapperTag(node.name)
-            const parts = node.props.map(
-                (prop) => `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`,
-            )
+            /* Server-render the child via its `render` and inline the HTML inside the same
+               `[ … ]` marker range the client mounts into (`mountRange`) — no wrapper element,
+               so SSR and client agree and the child's root lays out as a direct child. Props
+               pass as thunks; slot content passes as a string-returning `$children` the child
+               invokes from its <slot>. */
             /* Slot content is a fresh build context — the child's `<slot>` mounts it via
                `mountSlot`, not the parent skeleton clone, and the client builds it through
-               `componentParts`/`generateChildren` (never the skeleton path). `skeletonContext`
+               `propsArg`/`generateChildren` (never the skeleton path). `skeletonContext`
                records it reset, so its children emit no enclosing-skeleton anchors the client
                slot builder would lack. */
             const slotCode = generateInto(node.children, '$slot')
-            if (slotCode.trim() !== '') {
-                parts.push(
-                    `"$children": () => { const $slot = []; ${slotCode}return $slot.join(''); }`,
-                )
-            }
-            /* Render the child and MERGE its await blocks into this page's `$awaits`
-               so they join the page's SSR stream — their markers carry render-pass
-               block ids (nextBlockId), unique across page + children, so the streamed
-               fragments resolve into the right boundaries. ($awaits is captured from
-               the enclosing render body, including from branch closures.) */
+            /* `$children` is an ASYNC builder the child `await`s at its `<slot>` position
+               (`generateSlot`), NOT a pre-resolved string. Pre-resolving here would run the
+               slot's `$ctx.next++` block ids BEFORE the child render's own, but the client
+               builds slot content lazily at the `<slot>` site — so a child with an await/try
+               before its `<slot>` would allocate ids in the opposite order and desync hydration.
+               Keeping the slot lazy makes the slot's ids draw at the `<slot>` site on both
+               sides. The builder shares the enclosing render's `$ctx`/`$awaits`/`$resume` (a
+               closure), so nested awaits register and number correctly during the child render.
+               A child with a `<slot>` is therefore always an async render. */
+            const slotPart =
+                slotCode.trim() === ''
+                    ? undefined
+                    : `"$children": async () => { const $slot = []; ${slotCode}return $slot.join(''); }`
+            /* The same last-wins layering the client build emits (`composeProps`), so SSR
+               and hydration read the same prop bag. */
+            const propsExpr = composeProps(node.props, lowerExpression, slotPart)
+            /* Render the child (awaited — render is async) sharing this render's `$ctx`,
+               so its `await`/`try` block ids draw from the same depth-first counter,
+               unique across page + children, and the streamed fragments resolve into the
+               right boundaries. MERGE its streaming awaits into `$awaits` and its inline
+               blocking values into `$resume`. ($awaits/$resume are captured from the
+               enclosing render body, including from branch closures.) */
             const result = nextVar('$child')
             return (
-                push(target, `<${tag} style="display:contents">`) +
-                `const ${result} = ${node.name}.render({ ${parts.join(', ')} });\n` +
+                anchor +
+                push(target, RANGE_OPEN) +
+                `const ${result} = await ${node.name}.render(${propsExpr}, $ctx);\n` +
                 `${target}.push(${result}.html);\n` +
                 `for (const $a of ${result}.awaits) { $awaits.push($a); }\n` +
-                push(target, `</${tag}>`)
+                `Object.assign($resume, ${result}.resume);\n` +
+                push(target, RANGE_CLOSE)
             )
         }
+        if (node.kind === 'element' && node.tag === OUTLET_TAG) {
+            /* A layout's router fill point (`asOutlet` rewrote its `<slot/>`): an `<!--a-->`
+               anchor (in a skeleton) + an empty `<!--abide:outlet-->`…`<!--/abide:outlet-->`
+               boundary the chain composer folds the child layer into (`renderChain`) and the
+               client router fills/hydrates (`outlet`/`fillBoundary`) — no wrapper element. */
+            return anchor + push(target, `<!--${OUTLET_OPEN}--><!--${OUTLET_CLOSE}-->`)
+        }
         if (node.kind === 'element' && node.tag === 'slot') {
             /* `asOutlet` already rewrote a layout's top-level/element-nested `<slot/>` to an
-               `OUTLET_TAG` element (handled by the generic path below), so a `slot` node reaching
-               here in a layout is control-flow-nested — emit the same bare outlet placeholder the
-               client's nested-slot path clones, which the chain composer folds the child into. */
+               `OUTLET_TAG` element (handled above), so a `slot` node reaching here in a layout
+               is control-flow-nested — emit the same empty outlet boundary the client's
+               control-flow-nested path builds, which the chain composer folds the child into. */
             if (isLayout) {
-                return push(target, `<${OUTLET_TAG}></${OUTLET_TAG}>`)
+                return push(target, `<!--${OUTLET_OPEN}--><!--${OUTLET_CLOSE}-->`)
             }
-            return generateSlot(node, target)
+            return generateSlot(node, target, anchor)
         }
         let code = push(target, `<${node.tag}`)
         /* Every `<style>` active at this element (own siblings + ancestors) — same set
@@ -254,6 +356,12 @@ export function generateSSR(
                 /* present/absent semantics matching the client `attr` binding:
                    false/null/undefined drops it, true emits the bare attribute. */
                 code += `${target}.push($attr(${JSON.stringify(attr.name)}, ${lowerExpression(attr.code)}));\n`
+            } else if (attr.kind === 'spread') {
+                /* `{...expr}` element spread: each key as an attribute, functions (event
+                   handlers) skipped — the client `spreadAttrs` wires those on hydrate. Keys
+                   explicitly named on the element are skipped (the explicit attr wins), so
+                   no duplicate attribute is emitted and the client DOM agrees. */
+                code += `${target}.push($spread(${lowerExpression(attr.code)}, ${JSON.stringify(spreadExcludedNames(node.attrs))}));\n`
             } else if (attr.kind === 'bind' && attr.property === 'group') {
                 /* Render the checked state as a boolean attribute: present when the
                    path holds (radio) or contains (checkbox) this control's value. */
@@ -292,60 +400,105 @@ export function generateSSR(
     function generateSlot(
         node: Extract<TemplateNode, { kind: 'element' }>,
         target: string,
+        anchor: string,
     ): string {
         const wrap = inSkeleton.get(node)
         const fallback = generateInto(node.children, target)
+        /* `$children` is an async builder the parent passes lazily; `await` it here so the
+           slot content's block ids allocate AT the `<slot>` position — the same order the
+           client builds slot content — keeping hydration congruent. The `await` makes a
+           component with a `<slot>` an async render (its caller already `await`s `render()`). */
         const body =
             fallback.trim() === ''
-                ? `if ($props && $props.$children) { ${target}.push($props.$children()); }\n`
-                : `if ($props && $props.$children) { ${target}.push($props.$children()); } else {\n${fallback}}\n`
+                ? `if ($props && $props.$children) { ${target}.push(await $props.$children()); }\n`
+                : `if ($props && $props.$children) { ${target}.push(await $props.$children()); } else {\n${fallback}}\n`
         if (!wrap) {
             return body
         }
-        return `${anchorMark(node, target)}${openRange(target)}${body}${closeRange(target)}`
+        return `${anchor}${openRange(target)}${body}${closeRange(target)}`
     }
 
-    /* Boundary markers + a `$awaits` registration carrying the promise and
-       string-renderers for the resolved/error branches. Streaming emits the pending
-       branch between the markers (flushed now, value streamed later); blocking emits
-       an empty boundary — its resolved branch is the children bound to `node.as` — and
-       flags the entry so `renderToStream` settles it before the first flush. */
+    /* A blocking await (`then` on the tag) renders INLINE during the async render pass;
+       a streaming await defers its resolved branch to `renderToStream`. */
     function generateAwait(node: Extract<TemplateNode, { kind: 'await' }>, target: string): string {
+        return node.blocking
+            ? generateBlockingAwait(node, target)
+            : generateStreamingAwait(node, target)
+    }
+
+    /*
+    A blocking await — `await`ed at its structural position in the async render pass and
+    its resolved branch rendered INLINE into `target`, between the boundary markers. This
+    matches the client (which runs `then` inline during adopt): one render pass, so the
+    block id (`$ctx.next++`) and any nested await's id are allocated depth-first in the
+    same order the client hydrates them, and the resolved value is captured into `$resume`
+    for the manifest. The resolved children bind `node.as`; `finally` appends after, matching
+    the client's concatenated node range. With no catch/finally branch a rejection propagates
+    (renderToStream / the 500 surfaces it); otherwise the catch branch renders and seeds an
+    error resume. The value `const` is block-scoped to its `try`, so sibling blocking awaits
+    that bind the same name don't collide.
+    */
+    function generateBlockingAwait(
+        node: Extract<TemplateNode, { kind: 'await' }>,
+        target: string,
+    ): string {
+        const catchBranch = branchNamed(node.children, 'catch')
+        const finallyChildren = branchNamed(node.children, 'finally')?.children ?? []
+        const resolvedChildren = node.children.filter((child) => child.kind !== 'branch')
+        const resolvedAs = node.as ?? '_value'
+        const errorAs = catchBranch?.as ?? '_error'
+        const id = nextVar('$aid')
+        let code = `const ${id} = $ctx.next++;\n`
+        code += `${target}.push("<!--abide:await:" + ${id} + "-->");\n`
+        code += `try {\n`
+        code += `const ${resolvedAs} = await (${lowerExpression(node.promise)});\n`
+        code += branchContent(resolvedChildren, target)
+        code += branchContent(finallyChildren, target)
+        code += `$resume[${id}] = { ok: true, value: ${resolvedAs} };\n`
+        if (catchBranch === undefined && finallyChildren.length === 0) {
+            /* No catch/finally → let the rejection surface instead of an empty branch. */
+            code += `} catch (_error) { throw _error; }\n`
+        } else {
+            code += `} catch (${errorAs}) {\n`
+            code += branchContent(catchBranch?.children ?? [], target)
+            code += branchContent(finallyChildren, target)
+            code += `$resume[${id}] = { ok: false, error: String(${errorAs}) };\n`
+            code += `}\n`
+        }
+        code += `${target}.push("<!--/abide:await:" + ${id} + "-->");\n`
+        return code
+    }
+
+    /* A streaming await — emits the pending branch between the markers (flushed now) and
+       registers the promise + async string-renderers on `$awaits`; `renderToStream`
+       flushes the resolved fragment out of order. The renderers are async so a nested
+       `await` block inside the branch composes. `finally` appends after the outcome,
+       matching the client's concatenated node range. Neither catch nor finally → omit
+       `catch` so a rejection surfaces (renderToStream re-throws); a finally-only block
+       keeps a catch renderer that renders just finally. */
+    function generateStreamingAwait(
+        node: Extract<TemplateNode, { kind: 'await' }>,
+        target: string,
+    ): string {
         const catchBranch = branchNamed(node.children, 'catch')
         const finallyChildren = branchNamed(node.children, 'finally')?.children ?? []
-        /* Resolved branch + its bound value: the children directly when blocking, the
-           `then` child when streaming. Pending (streaming only) is the non-branch
-           children. */
         const thenBranch = branchNamed(node.children, 'then')
-        const resolvedChildren = node.blocking
-            ? node.children.filter((child) => child.kind !== 'branch')
-            : (thenBranch?.children ?? [])
-        const resolvedAs = node.blocking ? node.as : thenBranch?.as
-        const pending = node.blocking
-            ? []
-            : node.children.filter((child) => child.kind !== 'branch')
-        /* Runtime block id (shared with the client + child components in this pass). */
+        const pending = node.children.filter((child) => child.kind !== 'branch')
         const id = nextVar('$aid')
-        let code = `const ${id} = nextBlockId();\n`
+        let code = `const ${id} = $ctx.next++;\n`
         code += `${target}.push("<!--abide:await:" + ${id} + "-->");\n`
         code += branchContent(pending, target)
         code += `${target}.push("<!--/abide:await:" + ${id} + "-->");\n`
-        /* The settled closures append `finally` after the outcome markup, matching the
-           client's concatenated node range so hydration aligns. */
         const settled = (binding: string, children: TemplateNode[]) =>
-            `(${binding}) => { const $o = []; ${branchContent(children, '$o')}${branchContent(finallyChildren, '$o')}return $o.join(''); }`
-        /* Neither catch nor finally → omit `catch` so a rejection surfaces to the
-           stream/error path (renderToStream re-throws) instead of rendering an empty
-           branch. A finally-only block keeps a catch closure that renders just finally. */
+            `async (${binding}) => { const $o = []; ${branchContent(children, '$o')}${branchContent(finallyChildren, '$o')}return $o.join(''); }`
         const catchProp =
             catchBranch === undefined && finallyChildren.length === 0
                 ? ''
                 : `catch: ${settled(catchBranch?.as ?? '_error', catchBranch?.children ?? [])} `
         code +=
             `$awaits.push({ id: ${id}, ` +
-            (node.blocking ? 'blocking: true, ' : '') +
             `promise: () => (${lowerExpression(node.promise)}), ` +
-            `then: ${settled(resolvedAs ?? '_value', resolvedChildren)}, ` +
+            `then: ${settled(thenBranch?.as ?? '_value', thenBranch?.children ?? [])}, ` +
             `${catchProp}});\n`
         return code
     }
@@ -363,7 +516,7 @@ export function generateSSR(
         const errName = catchBranch?.as ?? '_error'
         const id = nextVar('$tid')
         const mark = nextVar('$trim')
-        let code = `const ${id} = nextBlockId();\n`
+        let code = `const ${id} = $ctx.next++;\n`
         code += `${target}.push("<!--abide:try:" + ${id} + "-->");\n`
         code += `const ${mark} = ${target}.length;\n`
         code += `try {\n`

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

@@ -0,0 +1,19 @@
+import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
+import { isControlFlow } from './isControlFlow.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+The node kinds that mount as a marker range and so take an `<!--a-->` anchor when in a
+skeleton — control-flow, child component, and the two outlet elements (a layout's
+`OUTLET_TAG`, a component's `<slot>`). The single positioning predicate every back-end
+shares — `generateSSR` gates its anchor emission on it, `skeletonContext` gates its anchor
+indexing on it — so SSR, the client clone, and the shared numberer cannot disagree on which
+nodes anchor.
+*/
+export function isAnchorPositioned(node: TemplateNode): boolean {
+    return (
+        isControlFlow(node) ||
+        node.kind === 'component' ||
+        (node.kind === 'element' && (node.tag === OUTLET_TAG || node.tag === 'slot'))
+    )
+}

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

@@ -5,7 +5,9 @@ A control-flow block — `if`/`each`/`await`/`switch`/`try`. In a skeleton each
 `<!--a-->` anchor cloned into its located parent at the block's position (see `anchorCursor`),
 so a block can sit ANYWHERE among static siblings. The shared classification under block
 anchor placement: both back-ends — and `skeletonable` — consult this so they agree on which
-nodes are anchor-positioned, the way `componentWrapperTag`/`isTextLeaf` already are.
+nodes are anchor-positioned. A child component is anchor-positioned too (it mounts as a
+`[`…`]` range like a block, see `mountRange`); the back-ends OR this with `kind ===
+'component'` rather than folding it in here, since a standalone component routes differently.
 */
 export function isControlFlow(node: TemplateNode): boolean {
     return (

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

@@ -8,7 +8,7 @@ located element (`generateBuild`) / emits it without an `<!--a-->` prefix (`gene
 reactive text interleaved with element children is anchor-positioned instead. Computing it
 once keeps the SSR string and the client skeleton from disagreeing about a `<!--a-->` — the
 first slice of lifting the positional model out of the two parallel traversals, alongside
-the already-shared `componentWrapperTag` and `skeletonable`.
+the already-shared `isControlFlow` and `skeletonable`.
 */
 export function isTextLeaf(node: Extract<TemplateNode, { kind: 'element' }>): boolean {
     return node.children.every((child) => child.kind === 'text' || child.kind === 'style')

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

@@ -107,35 +107,72 @@ function docAccessTransformer(docName: string): ts.TransformerFactory<ts.SourceF
                     }
                 }
             }
-            /* doc array `.push(x)` → add patch at the array's `-` slot. */
+            /* doc array `.push(a, b, …)` → one `add` patch per argument at the array's `-`
+               slot, matching native multi-arg push (each lands at the end in order). */
             if (
                 ts.isCallExpression(node) &&
                 ts.isPropertyAccessExpression(node.expression) &&
                 node.expression.name.text === 'push'
             ) {
                 const segments = pathSegments(node.expression.expression)
-                const pushed = node.arguments[0]
-                if (segments && pushed !== undefined) {
-                    return docCall(docName, 'add', [
-                        buildPath([...segments, { kind: 'literal', value: '-' }]),
-                        ts.visitNode(pushed, visit) as ts.Expression,
-                    ])
+                if (segments && node.arguments.length > 0) {
+                    const adds = node.arguments.map(
+                        (pushed) =>
+                            docCall(docName, 'add', [
+                                buildPath([...segments, { kind: 'literal', value: '-' }]),
+                                ts.visitNode(pushed, visit) as ts.Expression,
+                            ]) as ts.Expression,
+                    )
+                    /* `node.arguments.length > 0` above guarantees `adds` is non-empty, so the
+                       single-element branch's `adds[0]` is defined. */
+                    return adds.length === 1 ? adds[0]! : ts.factory.createCommaListExpression(adds)
                 }
             }
             /* A called member on a doc chain is a method on the read value, not a
-               deeper path: `model.draft.trim()` → `model.read("draft").trim()`,
-               `model.items.map(f)` → `model.read("items").map(f)`. (Array `.push`
+               deeper path: `model.draft.trim()` → `readCall(model.read("draft"), …)`,
+               `model.items.map(f)` → `readCall(model.read("items"), …)`. (Array `.push`
                above is the exception — it lowers to an `add` patch.) */
             if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
-                const segments = pathSegments(node.expression.expression)
+                const access = node.expression
+                const segments = pathSegments(access.expression)
                 if (segments) {
+                    const read = docCall(docName, 'read', [buildPath(segments)])
+                    const args = node.arguments.map(
+                        (arg) => ts.visitNode(arg, visit) as ts.Expression,
+                    )
+                    /* Optional chaining is the author's explicit skip-if-absent: a nullish
+                       read short-circuits the whole call to `undefined`. Keep it bare —
+                       routing it through the throwing guard would invert that semantics.
+                       The call continues the chain whenever the access OR the call carries a
+                       `?.`, so `model.x?.m()` short-circuits the call too. */
+                    if (access.questionDotToken || node.questionDotToken) {
+                        const member = access.questionDotToken
+                            ? ts.factory.createPropertyAccessChain(
+                                  read,
+                                  access.questionDotToken,
+                                  access.name,
+                              )
+                            : ts.factory.createPropertyAccessExpression(read, access.name.text)
+                        return ts.factory.createCallChain(
+                            member,
+                            node.questionDotToken,
+                            node.typeArguments,
+                            args,
+                        )
+                    }
+                    /* A non-optional call on an absent read throws the engine's opaque
+                       `undefined is not an object`. Route it through `readCall`, which throws
+                       naming the authored scope path and member — the key and member are both
+                       in hand here, the `.abide` location comes free off the mapped stack. */
                     return ts.factory.createCallExpression(
-                        ts.factory.createPropertyAccessExpression(
-                            docCall(docName, 'read', [buildPath(segments)]),
-                            node.expression.name.text,
-                        ),
-                        node.typeArguments,
-                        node.arguments.map((arg) => ts.visitNode(arg, visit) as ts.Expression),
+                        ts.factory.createIdentifier('readCall'),
+                        undefined,
+                        [
+                            read,
+                            buildPath(segments),
+                            ts.factory.createStringLiteral(access.name.text),
+                            ts.factory.createArrayLiteralExpression(args),
+                        ],
                     )
                 }
             }

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

@@ -121,6 +121,24 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
             if (char === '>' || char === '/' || char === undefined) {
                 break
             }
+            /* `{...expr}` standing where an attribute name would — a spread of an object's
+               keys onto the tag: props on a component, attributes on a native element. Only
+               a `<template>` directive rejects it (see `readElement`). */
+            if (char === '{') {
+                const { code, loc } = readBracedExpression()
+                if (!code.startsWith('...')) {
+                    throw new Error(
+                        `[abide] a bare {expr} is not a valid attribute — write {...expr} to spread an object's keys as props`,
+                    )
+                }
+                /* Advance `loc` past `...` and any whitespace so it points at the spread
+                   EXPRESSION, not the dots — the shadow source-map invariant (source text at
+                   `loc` equals the emitted code) requires `loc` and `code` to align. */
+                const inner = code.slice(3)
+                const leading = inner.length - inner.trimStart().length
+                attrs.push({ kind: 'spread', code: inner.trim(), loc: loc + 3 + leading })
+                continue
+            }
             let name = ''
             while (cursor < source.length && !/[\s=>/]/.test(source.charAt(cursor))) {
                 name += source.charAt(cursor)
@@ -163,6 +181,12 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
                    `>`, per the HTML unquoted-attribute rule. No delimiter to consume. */
                 let value = ''
                 while (cursor < source.length && !/[\s>]/.test(source.charAt(cursor))) {
+                    /* Stop before a `/` that closes the tag (`<Comp x=y/>`) so the value
+                       doesn't swallow the self-closing slash and defeat detection; a `/`
+                       elsewhere (e.g. a URL `href=/a/b`) stays part of the value. */
+                    if (source.charAt(cursor) === '/' && source.charAt(cursor + 1) === '>') {
+                        break
+                    }
                     value += source.charAt(cursor)
                     cursor += 1
                 }
@@ -214,6 +238,11 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
             const slotted = selfClosing ? [] : readChildren(tag)
             return { kind: 'component', name: tag, props: toProps(attrs), children: slotted }
         }
+        /* `{...expr}` spreads onto a component (its props) or a native element (its
+           attributes), but a `<template>` directive has no such bag — reject it there. */
+        if (tag === 'template' && attrs.some((attr) => attr.kind === 'spread')) {
+            throw new Error('[abide] {...expr} spread is not supported on a <template> directive')
+        }
         const children = selfClosing || VOID_TAGS.has(tag) ? [] : readChildren(tag)
         if (tag === 'template') {
             return toControlFlow(attrs, children)
@@ -296,8 +325,15 @@ function rejectStrayBranches(
    assigned) instead of being dropped. A static value becomes a string literal —
    a bare attribute coerces to `true` instead; every other kind keeps its `code`,
    letting a prop hold any value, functions included (e.g. an `onclick` callback). */
-function toProps(attrs: TemplateAttr[]): { name: string; code: string; loc?: number }[] {
+function toProps(
+    attrs: TemplateAttr[],
+): { name: string; code: string; loc?: number; spread?: boolean }[] {
     return attrs.map((attr) => {
+        /* A `{...expr}` spread carries no name — its keys merge in at runtime
+           (`mergeProps`/`spreadProps`); `spread: true` marks it for the back-ends. */
+        if (attr.kind === 'spread') {
+            return { name: '', code: attr.code, loc: attr.loc, spread: true }
+        }
         if (attr.kind === 'static') {
             /* A bare attribute (`<Toggle on />`) is a boolean flag: coerce it to
                `true` so the prop reads as a boolean, not the empty string a native
@@ -347,6 +383,13 @@ function attrName(attr: TemplateAttr): string {
     if (attr.kind === 'attach') {
         return 'attach'
     }
+    /* A spread has no name. `attrName` only feeds `<template>` directive lookups, and a
+       spread on a `<template>` is rejected at parse, so this branch is unreachable in
+       practice. (Spread itself IS supported — on components as props and on native
+       elements as attributes; only `<template>` directives reject it.) */
+    if (attr.kind === 'spread') {
+        return ''
+    }
     return attr.name
 }