@abide/abide 0.31.1 → 0.32.0

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

@@ -1,16 +1,22 @@
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
-import { branchElements } from './branchElements.ts'
-import { escapeHtml } from './escapeHtml.ts'
 import { groupBindParts } from './groupBindParts.ts'
-import { lowerDocAccess } from './lowerDocAccess.ts'
+import { lowerContext } from './lowerContext.ts'
 import { partitionSlots } from './partitionSlots.ts'
-import { nestedBindingNames } from './prepareNestedScript.ts'
-import { renameSignalRefs } from './renameSignalRefs.ts'
+import { scopeAttr } from './scopeAttr.ts'
+import { staticAttr } from './staticAttr.ts'
 import { staticAttrValue } from './staticAttrValue.ts'
+import { staticTextPart } from './staticTextPart.ts'
 import { stripEffects } from './stripEffects.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import { VOID_TAGS } from './VOID_TAGS.ts'
 
+/* The range boundary comments a control-flow block emits around its content. They
+   serialize exactly as the client's `document.createComment('[' | ']')` markers, so
+   the client claims the same `[ … ]` boundary it builds — the comment-marked range
+   that lets a branch hold any content. */
+const RANGE_OPEN = '<!--[-->'
+const RANGE_CLOSE = '<!--]-->'
+
 /*
 Server code generator: turns the parsed template into statements that push HTML
 fragments onto an output array, reading the document synchronously (no DOM, no
@@ -36,24 +42,16 @@ export function generateSSR(
     let varCounter = 0
     const nextVar = (prefix: string): string => `${prefix}${varCounter++}`
 
-    /* Branch-scoped nested-script bindings, deref'd to `.value` (see generateBuild). */
-    const localDerived = new Set<string>()
-    const derefScope = (): ReadonlySet<string> =>
-        localDerived.size === 0 ? derivedNames : new Set([...derivedNames, ...localDerived])
-
-    function lowerExpression(code: string): string {
-        return lowerDocAccess(renameSignalRefs(code, stateNames, derefScope()), 'model')
-            .trim()
-            .replace(/;$/, '')
-    }
+    /* The shared signal→`model` lowering + branch-scoped nested-script deref scope. */
+    const {
+        expression: lowerExpression,
+        statement,
+        withNestedScripts,
+    } = lowerContext(stateNames, derivedNames)
 
-    /* Lowers a scoped-script body for SSR: rename refs, lower doc access, then strip
-       effects (client-only lifecycle that emits no HTML). */
-    function lowerScript(code: string): string {
-        return stripEffects(
-            lowerDocAccess(renameSignalRefs(code, stateNames, derefScope()), 'model').trim(),
-        )
-    }
+    /* A scoped-script body for SSR: the shared lowering, then strip effects
+       (client-only lifecycle that emits no HTML) — the one SSR-side asymmetry. */
+    const lowerScript = (code: string): string => stripEffects(statement(code))
 
     function push(target: string, literal: string): string {
         return `${target}.push(${JSON.stringify(literal)});\n`
@@ -63,41 +61,25 @@ export function generateSSR(
         return children.map((child) => generate(child, target)).join('')
     }
 
-    /* A control-flow branch's body: run its nested `<script>`s (lowered, in scope)
-       first, then push the element markup — so SSR re-seeds the same local signals
-       the client build does, keeping hydration aligned. */
-    function branchInto(children: TemplateNode[], context: string, target: string): string {
-        const added: string[] = []
-        for (const child of children) {
-            if (child.kind === 'script') {
-                for (const name of nestedBindingNames(child.code)) {
-                    if (!localDerived.has(name)) {
-                        localDerived.add(name)
-                        added.push(name)
-                    }
-                }
-            }
-        }
-        const scriptCode = children
-            .filter(
-                (child): child is Extract<TemplateNode, { kind: 'script' }> =>
-                    child.kind === 'script',
-            )
-            .map((child) => `${lowerScript(child.code)}\n`)
-            .join('')
-        const markup = generateInto(branchElements(children, context, true), target)
-        for (const name of added) {
-            localDerived.delete(name)
-        }
-        return scriptCode + markup
+    /* A control-flow branch's content, generated exactly like a normal child list so
+       a branch holds ANY content (components, text, nested blocks). `generate` emits
+       nested `<script>`s in document order; `withNestedScripts` puts their bindings in
+       scope — matching the client build, so hydration stays aligned. The caller wraps
+       it in the `[ … ]` range markers the runtime tracks (unconditionally per block,
+       so an empty/false branch still emits the boundary the client claims). */
+    function branchContent(children: TemplateNode[], target: string): string {
+        return withNestedScripts(children, () => generateInto(children, target))
     }
+    const openRange = (target: string): string => push(target, RANGE_OPEN)
+    const closeRange = (target: string): string => push(target, RANGE_CLOSE)
 
     function generate(node: TemplateNode, target: string): string {
         if (node.kind === 'text') {
             return node.parts
                 .map((part) => {
                     if (part.kind === 'static') {
-                        return part.value.trim() === '' ? '' : push(target, escapeHtml(part.value))
+                        const markup = staticTextPart(part.value)
+                        return markup === '' ? '' : push(target, markup)
                     }
                     return `${target}.push($text(${lowerExpression(part.code)}));\n`
                 })
@@ -106,11 +88,11 @@ export function generateSSR(
         if (node.kind === 'if') {
             const elseBranch = node.children.find((child) => child.kind === 'case')
             const thenChildren = node.children.filter((child) => child.kind !== 'case')
-            let code = `if (${lowerExpression(node.condition)}) {\n${branchInto(thenChildren, '<template if>', target)}}`
+            let code = `if (${lowerExpression(node.condition)}) {\n${branchContent(thenChildren, target)}}`
             if (elseBranch !== undefined && elseBranch.kind === 'case') {
-                code += ` else {\n${branchInto(elseBranch.children, '<template else>', target)}}`
+                code += ` else {\n${branchContent(elseBranch.children, target)}}`
             }
-            return `${code}\n`
+            return `${openRange(target)}${code}\n${closeRange(target)}`
         }
         if (node.kind === 'switch') {
             const cases = node.children.filter(
@@ -120,15 +102,15 @@ export function generateSSR(
             let started = false
             for (const branch of cases) {
                 if (branch.match !== undefined) {
-                    code += `${started ? 'else ' : ''}if ($s === (${lowerExpression(branch.match)})) {\n${branchInto(branch.children, '<template case>', target)}}\n`
+                    code += `${started ? 'else ' : ''}if ($s === (${lowerExpression(branch.match)})) {\n${branchContent(branch.children, target)}}\n`
                     started = true
                 }
             }
             const fallback = cases.find((branch) => branch.match === undefined)
             if (fallback !== undefined) {
-                code += `${started ? 'else ' : ''}{\n${branchInto(fallback.children, '<template case>', target)}}\n`
+                code += `${started ? 'else ' : ''}{\n${branchContent(fallback.children, target)}}\n`
             }
-            return `${code}}\n`
+            return `${openRange(target)}${code}}\n${closeRange(target)}`
         }
         if (node.kind === 'case') {
             return ''
@@ -156,7 +138,7 @@ export function generateSSR(
             if (node.async) {
                 return ''
             }
-            return `for (const ${node.as} of (${lowerExpression(node.items)})) {\n${branchInto(node.children, '<template each>', target)}}\n`
+            return `for (const ${node.as} of (${lowerExpression(node.items)})) {\n${openRange(target)}${branchContent(node.children, target)}${closeRange(target)}}\n`
         }
         if (node.kind === 'await') {
             return generateAwait(node, target)
@@ -218,14 +200,11 @@ export function generateSSR(
         /* Every `<style>` active at this element (own siblings + ancestors) — same set
            the client stamps, so server and client markup carry identical attributes. */
         for (const scope of node.scopes ?? []) {
-            code += push(target, ` ${scope}=""`)
+            code += push(target, scopeAttr(scope))
         }
         for (const attr of node.attrs) {
             if (attr.kind === 'static') {
-                /* Escape the literal value so a `"`/`&`/`<` in it can't break out of
-                   the attribute or inject markup (the client uses setAttribute, which
-                   needs no escaping — escaping here keeps SSR and client in sync). */
-                code += push(target, ` ${attr.name}="${escapeHtml(attr.value)}"`)
+                code += push(target, staticAttr(attr.name, attr.value))
             } else if (attr.kind === 'expression') {
                 /* present/absent semantics matching the client `attr` binding:
                    false/null/undefined drops it, true emits the bare attribute. */
@@ -249,21 +228,7 @@ export function generateSSR(
         code += push(target, '>')
         if (!VOID_TAGS.has(node.tag)) {
             /* A `<script>` child scopes its bindings to this element's subtree. */
-            const added: string[] = []
-            for (const child of node.children) {
-                if (child.kind === 'script') {
-                    for (const name of nestedBindingNames(child.code)) {
-                        if (!localDerived.has(name)) {
-                            localDerived.add(name)
-                            added.push(name)
-                        }
-                    }
-                }
-            }
-            code += generateInto(node.children, target)
-            for (const name of added) {
-                localDerived.delete(name)
-            }
+            code += withNestedScripts(node.children, () => generateInto(node.children, target))
             code += push(target, `</${node.tag}>`)
         }
         return code
@@ -318,24 +283,24 @@ export function generateSSR(
         const id = nextVar('$aid')
         let code = `const ${id} = nextBlockId();\n`
         code += `${target}.push("<!--abide:await:" + ${id} + "-->");\n`
-        code += branchInto(pending, '<template await> pending', target)
+        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[], context: string) =>
-            `(${binding}) => { const $o = []; ${branchInto(children, context, '$o')}${branchInto(finallyChildren, '<template finally>', '$o')}return $o.join(''); }`
+        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. */
         const catchProp =
             catchBranch === undefined && finallyChildren.length === 0
                 ? ''
-                : `catch: ${settled(catchBranch?.as ?? '_error', catchBranch?.children ?? [], '<template catch>')} `
+                : `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, node.blocking ? '<template await then>' : '<template then>')}, ` +
+            `then: ${settled(resolvedAs ?? '_value', resolvedChildren)}, ` +
             `${catchProp}});\n`
         return code
     }
@@ -362,12 +327,12 @@ export function generateSSR(
         code += `${target}.push("<!--abide:try:" + ${id} + "-->");\n`
         code += `const ${mark} = ${target}.length;\n`
         code += `try {\n`
-        code += branchInto(guarded, '<template try>', target)
-        code += branchInto(finallyChildren, '<template finally>', target)
+        code += branchContent(guarded, target)
+        code += branchContent(finallyChildren, target)
         code += `} catch (${errName}) {\n${target}.length = ${mark};\n`
         if (catchBranch !== undefined) {
-            code += branchInto(catchBranch.children, '<template catch>', target)
-            code += branchInto(finallyChildren, '<template finally>', target)
+            code += branchContent(catchBranch.children, target)
+            code += branchContent(finallyChildren, target)
         } else {
             code += `throw ${errName};\n`
         }

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

@@ -0,0 +1,64 @@
+import { lowerDocAccess } from './lowerDocAccess.ts'
+import { nestedBindingNames } from './prepareNestedScript.ts'
+import { renameSignalRefs } from './renameSignalRefs.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+import { unwrapParens } from './unwrapParens.ts'
+
+/*
+The shared expression-lowering context both back-ends build on: the signal→`model`
+rewrite and doc-access lowering that turns the signal surface the author writes
+(`count` → `model.count` → patch/read) into the doc API, plus the branch-scoped
+nested-`<script>` deref scope. Identical on both sides by design — server and
+client must lower an expression the same way or their markup diverges and
+hydration breaks — so it lives in one place: a new sugar token or a paren/scope
+fix lands here once instead of in lockstep across `generateBuild`/`generateSSR`.
+SSR's effect-stripping stays a caller-side wrap (`stripEffects`), the one real
+asymmetry; the node-walk skeletons stay in each back-end.
+*/
+export function lowerContext(stateNames: ReadonlySet<string>, derivedNames: ReadonlySet<string>) {
+    /* Branch-scoped signal bindings (from nested `<script>`s) — they deref to
+       `.value` like a `derived`. Pushed while a branch's script + markup compile,
+       popped after, so they shadow only within that subtree. */
+    const localDerived = new Set<string>()
+    const derefScope = (): ReadonlySet<string> =>
+        localDerived.size === 0 ? derivedNames : new Set([...derivedNames, ...localDerived])
+
+    /* Rewrites signal refs, then lowers a single expression (no trailing `;`).
+       Wrapped in parens so a bare object literal (`{ a: 1 }`) parses as an
+       expression, not a block of labeled statements, through both rewrite passes;
+       the wrapper is then peeled back off. */
+    function expression(code: string): string {
+        const renamed = renameSignalRefs(`(${code})`, stateNames, derefScope())
+        return unwrapParens(lowerDocAccess(renamed, 'model').trim().replace(/;$/, ''))
+    }
+
+    /* As above but keeps the trailing `;` for a statement/handler body. */
+    function statement(code: string): string {
+        const renamed = renameSignalRefs(code, stateNames, derefScope())
+        return lowerDocAccess(renamed, 'model').trim()
+    }
+
+    /* Adds any `<script>` children's binding names to the deref scope (so the script
+       bodies and the branch's markup auto-deref them), runs `body` within that scope,
+       then pops the names it added. Returns whatever `body` produces. */
+    function withNestedScripts<T>(children: TemplateNode[], body: () => T): T {
+        const added: string[] = []
+        for (const child of children) {
+            if (child.kind === 'script') {
+                for (const name of nestedBindingNames(child.code)) {
+                    if (!localDerived.has(name)) {
+                        localDerived.add(name)
+                        added.push(name)
+                    }
+                }
+            }
+        }
+        const result = body()
+        for (const name of added) {
+            localDerived.delete(name)
+        }
+        return result
+    }
+
+    return { expression, statement, withNestedScripts }
+}

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

@@ -32,12 +32,17 @@ export function lowerDocAccess(code: string, docName: string): string {
 /* A path segment is either a literal key or a runtime expression (a dynamic index). */
 type Segment = { kind: 'literal'; value: string } | { kind: 'expression'; node: ts.Expression }
 
-/* Maps a compound-assignment operator to its plain binary counterpart. */
+/* Maps a compound-assignment operator to its plain binary counterpart. Logical
+   assignments (`||=`/`&&=`/`??=`) lower to an unconditional replace of the
+   combined value — consistent with how `+=` lowers (the patch always writes). */
 const COMPOUND_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
     [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
     [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
     [ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskToken],
     [ts.SyntaxKind.SlashEqualsToken, ts.SyntaxKind.SlashToken],
+    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
+    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
+    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
 ])
 
 function docAccessTransformer(docName: string): ts.TransformerFactory<ts.SourceFile> {

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

@@ -0,0 +1,16 @@
+/*
+Converts an absolute source offset to 1-based `{ line, column }`. Used to turn a
+compile error's tracked offset into a human location for the loader's message
+(Bun frames plugin throws at `<file>:0`, so abide carries the real position in the
+message text itself).
+*/
+export function offsetToLineColumn(
+    source: string,
+    offset: number,
+): { line: number; column: number } {
+    const clamped = Math.max(0, Math.min(offset, source.length))
+    const preceding = source.slice(0, clamped)
+    const line = preceding.split('\n').length
+    const column = clamped - (preceding.lastIndexOf('\n') + 1) + 1
+    return { line, column }
+}

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

@@ -0,0 +1,9 @@
+/*
+Serializes one `<style>` scope marker to its empty-valued attribute fragment,
+leading space included. Shared by the SSR generator and the static-clone skeleton
+generator so server markup and the client clone template stamp the same scope
+attributes in the same byte-shape.
+*/
+export function scopeAttr(scope: string): string {
+    return ` ${scope}=""`
+}

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

@@ -0,0 +1,11 @@
+import { escapeHtml } from './escapeHtml.ts'
+
+/*
+Serializes one static attribute to its markup fragment, leading space included.
+Shared by the SSR generator and the static-clone skeleton generator so the two
+back-ends can't diverge on attribute byte-shape or value escaping — the contract
+that lets the client clone template hydrate the server markup.
+*/
+export function staticAttr(name: string, value: string): string {
+    return ` ${name}="${escapeHtml(value)}"`
+}

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

@@ -0,0 +1,12 @@
+import { escapeHtml } from './escapeHtml.ts'
+
+/*
+Serializes one static text part to its markup: whitespace-only parts drop (both
+back-ends omit them, so a blank part neither emits markup nor breaks a clone run),
+everything else is HTML-escaped. Shared by the SSR generator and the static-clone
+skeleton generator so server markup and the client clone template agree on both
+the whitespace rule and escaping.
+*/
+export function staticTextPart(value: string): string {
+    return value.trim() === '' ? '' : escapeHtml(value)
+}

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

@@ -0,0 +1,10 @@
+/*
+Peels one outer paren pair off a lowered expression. The lowering passes wrap an
+expression in `(…)` to force expression-position parsing (so a bare object literal
+isn't read as a block); the printer preserves that wrapper, so the result is
+always `(EXPR)` and the outermost pair is the one we added. Removed for clean,
+canonical output.
+*/
+export function unwrapParens(code: string): string {
+    return code.startsWith('(') && code.endsWith(')') ? code.slice(1, -1) : code
+}

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

@@ -29,11 +29,11 @@ export function awaitBlock(
     parent: Node,
     id: number,
     promiseThunk: () => unknown,
-    renderPending: ((parent: Node) => Node[]) | undefined,
-    renderThen: (parent: Node, value: unknown) => Node[],
+    renderPending: ((parent: Node) => void) | undefined,
+    renderThen: (parent: Node, value: unknown) => void,
     /* Absent when the block has no catch branch — a rejection then surfaces (re-throws
        to the unhandled-rejection path) instead of rendering an empty branch. */
-    renderCatch: ((parent: Node, error: unknown) => Node[]) | undefined,
+    renderCatch: ((parent: Node, error: unknown) => void) | undefined,
 ): void {
     const hydration = RENDER.hydration
     let active: { nodes: Node[]; dispose: () => void } | undefined
@@ -45,24 +45,27 @@ export function awaitBlock(
     const detach = (): void => {
         if (active !== undefined) {
             active.dispose()
+            /* Remove via each node's LIVE parent, not the captured `parent` — when this
+               await is a bare child of a control-flow branch, `parent` is the branch's
+               build fragment, emptied into the document once the enclosing block placed
+               it (`place` already inserts via `anchor.parentNode` for the same reason). */
             for (const node of active.nodes) {
-                parent.removeChild(node)
+                node.parentNode?.removeChild(node)
             }
             active = undefined
         }
     }
 
-    /* Replace the current content with a freshly-built range, before the anchor. */
-    const place = (build: (parent: Node) => Node[]): void => {
+    /* Replace the current content with a freshly-built branch, before the anchor. The
+       branch builds into a fragment (so any content — components, text, nested blocks
+       — appends freely), whose top-level nodes are tracked for the next swap. */
+    const place = (build: (parent: Node) => void): void => {
         detach()
-        let nodes: Node[] = []
-        const dispose = scope(() => {
-            nodes = build(parent)
-        })
+        const fragment = document.createDocumentFragment()
+        const dispose = scope(() => build(fragment))
+        const nodes = [...fragment.childNodes]
+        ;(anchor?.parentNode ?? parent).insertBefore(fragment, anchor ?? null)
         active = { nodes, dispose }
-        for (const node of nodes) {
-            parent.insertBefore(node, anchor ?? null)
-        }
     }
 
     /* Render a settled-or-pending result into the current generation. */
@@ -96,17 +99,20 @@ export function awaitBlock(
         )
     }
 
-    /* Adopt an SSR-resolved branch in place (its roots claim the existing nodes),
-       then park an anchor just before the close marker for later swaps. */
-    const adopt = (open: Node | null, build: (parent: Node) => Node[]): void => {
+    /* Adopt an SSR-resolved branch in place (its content claims the existing nodes),
+       then park an anchor just before the close marker for later swaps. The adopted
+       content is everything the build claimed between the open and close markers. */
+    const adopt = (open: Node | null, build: (parent: Node) => void): void => {
         const cursor = hydration as NonNullable<typeof hydration>
         cursor.next.set(parent, open?.nextSibling ?? null)
-        let nodes: Node[] = []
-        const dispose = scope(() => {
-            nodes = build(parent)
-        })
+        const dispose = scope(() => build(parent))
         const close = claimChild(cursor, parent)
         cursor.next.set(parent, close?.nextSibling ?? null)
+        const nodes: Node[] = []
+        for (let node = open?.nextSibling ?? null; node !== null && node !== close; ) {
+            nodes.push(node)
+            node = node.nextSibling
+        }
         anchor = document.createTextNode('')
         parent.insertBefore(anchor, close)
         active = { nodes, dispose }
@@ -143,7 +149,7 @@ export function awaitBlock(
         const open = claimChild(cursor, parent)
         const entry = RESUME[id]
         if (entry !== undefined) {
-            let build: (host: Node) => Node[]
+            let build: (host: Node) => void
             if (entry.ok) {
                 build = (host) => renderThen(host, entry.value)
             } else if (renderCatch !== undefined) {

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

@@ -0,0 +1,16 @@
+/*
+Tears down a control-flow range: disposes its reactive scope, then removes every
+node between the `start` and `end` markers (exclusive). Walking between the markers
+at clear time — rather than tracking a captured node list — is what lets a branch
+hold dynamic nested blocks: nodes a nested block inserted after the initial build
+still sit between the markers, so they're removed too.
+*/
+export function clearBetween(start: Node, end: Node, dispose?: () => void): void {
+    dispose?.()
+    let node = start.nextSibling
+    while (node !== null && node !== end) {
+        const next = node.nextSibling
+        end.parentNode?.removeChild(node)
+        node = next
+    }
+}