@abide/abide 0.47.0 → 0.49.0

package/src/lib/shared/types/CacheStats.ts

@@ -2,7 +2,7 @@
 Per-store cache read tallies, frozen into the request's closing log record at
 settle. hit = a read served from a settled retained entry (including the warm
 SSR sync path); coalesced = a read that joined an in-flight call; miss = a
-read that invoked its producer/remote. Reads against the process-level global
+read that invoked its producer/remote. Reads against the process-level shared
 store count into the requesting scope's store, so a request's record reflects
 everything that request asked the cache for.
 */

package/src/lib/shared/types/SmartReadOptions.ts

@@ -5,19 +5,23 @@ these govern retention and the refetch clock — NOT transport. Per-call transpo
 options (signal/keepalive/priority/cache/headers) live on `.raw(args, init)`.
 
 Fetch reads:
-- `ttl` — retention/staleness in ms: undefined = retain forever (no auto-refetch),
-  N ms = the retained value goes stale after N ms and the next access triggers a
-  background revalidation (stale stays visible, `refreshing()` true). The display
-  value is never dropped; ttl drives staleness, not eviction.
+- `ttl` — retention/staleness in ms. Default: 0 on the server (coalesce-only —
+  the request is the atomic unit, nothing is retained past it), Infinity on the
+  client (retain until invalidate/refresh — the tab is the atomic unit). On the
+  client, N ms marks a staleness deadline: the retained value goes stale after N
+  ms and the next access triggers a background revalidation (stale stays visible,
+  `refreshing()` true); the display value is never dropped. On the server, N ms
+  is a plain expiry and only takes effect in the shared store (pair with `shared`).
 - `tags` — free-form invalidation-group labels (see the selector grammar).
 - `throttle` / `debounce` — rate-limit the background refetch clock (set one, not
   both). Leading-edge-then-coalesce, or fire-after-quiet respectively.
-- `global` — store the entry in the process-level store instead of the default
-  request-scoped one (server), so a value computed in one request is reused by
-  later requests — the memoise-an-external-endpoint case. Omit it for per-user
-  data: the default keeps a per-user response from leaking across requests.
-  Write only `global: true`; there is no `false` form. On the client there is a
-  single tab store, so the flag is a no-op there.
+- `shared` — opts the entry into the process-level store instead of the default
+  request-scoped one (server) — a store that outlives every request. It selects
+  the store only; it does NOT retain (pair it with `ttl` to memoise across
+  requests). The shared store is keyed by method+url+args, never by user, so do
+  not put per-user data in it — it would be served to other users. Omit `shared`
+  for per-request data. Write only `shared: true`; there is no `false` form. On
+  the client there is a single tab store, so the flag is a no-op there.
 
 Streaming reads (jsonl/sse):
 - `n` — how many retained frames to replay before going live.
@@ -27,6 +31,6 @@ export type SmartReadOptions = {
     tags?: string[]
     throttle?: number
     debounce?: number
-    global?: boolean
+    shared?: boolean
     n?: number
 }

package/src/lib/shared/url.ts

@@ -116,6 +116,11 @@ function interpolate(segments: RouteSegment[], params: Query): string {
             if (segment.optional && (value === undefined || value === '')) {
                 return undefined
             }
+            /* A required `[name]`/`[...rest]` with no value would otherwise stringify to the
+               literal "undefined" and silently mis-route; fail loudly instead. */
+            if (value === undefined || value === null) {
+                throw new Error(`abide url(): missing required param "${segment.name}"`)
+            }
             const text = String(value)
             return segment.catchAll
                 ? text.split('/').map(encodeURIComponent).join('/')

package/src/lib/test/createTestApp.ts

@@ -37,10 +37,10 @@ import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
-import { globalCacheStoreSlot } from '../shared/globalCacheStoreSlot.ts'
 import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
+import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import type { Socket } from '../shared/types/Socket.ts'
 import { createTestSocketChannel } from './createTestSocketChannel.ts'
@@ -98,15 +98,15 @@ leaking the request-scope/cache/page resolvers into the next test file.
 export async function createTestApp(): Promise<TestApp> {
     const previous = {
         cacheResolver: cacheStoreSlot.resolver,
-        globalResolver: globalCacheStoreSlot.resolver,
+        sharedResolver: sharedCacheStoreSlot.resolver,
         pageResolver: pageSlot.resolver,
         baseResolver: baseSlot.resolver,
         activeServer: serverSlot.active,
     }
 
-    cacheStoreSlot.resolver = () => requestContext.getStore()?.cache
-    const globalStore = createCacheStore()
-    globalCacheStoreSlot.resolver = () => globalStore
+    const sharedStore = createCacheStore()
+    sharedCacheStoreSlot.resolver = () => sharedStore
+    cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedStore
     pageSlot.resolver = resolvePageSnapshot
 
     /* Eager env validation, exactly as serverEntry: a top-level env(schema) in
@@ -185,7 +185,7 @@ export async function createTestApp(): Promise<TestApp> {
         channel?.close()
         server.stop(true)
         cacheStoreSlot.resolver = previous.cacheResolver
-        globalCacheStoreSlot.resolver = previous.globalResolver
+        sharedCacheStoreSlot.resolver = previous.sharedResolver
         pageSlot.resolver = previous.pageResolver
         baseSlot.resolver = previous.baseResolver
         serverSlot.active = previous.activeServer

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

@@ -49,6 +49,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'restProps', specifier: 'ui/dom/restProps', alias: '$$restProps' },
     { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs', alias: '$$spreadAttrs' },
     { name: 'readCall', specifier: 'ui/dom/readCall', alias: '$$readCall' },
+    { name: 'mutateDocArray', specifier: 'ui/dom/mutateDocArray', alias: '$$mutateDocArray' },
     { name: 'hydrate', specifier: 'ui/dom/hydrate', alias: '$$hydrate' },
     { name: 'escapeKey', specifier: 'ui/runtime/escapeKey', alias: '$$escapeKey' },
     { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId', alias: '$$nextBlockId' },

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

@@ -2,18 +2,17 @@
 The DOM event a generic two-way `bind:<property>` listens on to write the bound
 path back. Most form fields report edits via `input`, but a few properties are
 driven by their own event and never fire `input` — `<details open>` fires
-`toggle`, a checkbox/radio `checked` fires `change`, and a `<select>` settles its
-`value` on `change`. Picking the wrong event silently breaks the write-back.
+`toggle` and a checkbox/radio `checked` fires `change`. `<select value>` is NOT
+handled here: generateBuild intercepts it before this function and routes it to
+`bindSelectValue` (a MutationObserver-based helper that re-applies on late
+options), so this function never sees that case.
 */
-export function bindListenEvent(property: string, tag: string): string {
+export function bindListenEvent(property: string): string {
     if (property === 'open') {
         return 'toggle'
     }
     if (property === 'checked') {
         return 'change'
     }
-    if (property === 'value' && tag === 'select') {
-        return 'change'
-    }
     return 'input'
 }

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

@@ -27,7 +27,7 @@ when a caller (a test, a top-level render) omits it.
 
 The body is wrapped in an ASYNC IIFE (returns `Promise<SsrRender>`) ONLY when it contains
 an inline `await` — a blocking `{#await … then}` block, a child-component render, a `<slot>`
-read (its `$children` builder is async), or a top-level `await` in the author script. A
+read (its `children` builder is async), or a top-level `await` in the author script. A
 purely synchronous / streaming-await / try-only component returns `SsrRender` directly. The
 framework always `await`s `render()`, so production is uniform either way; the sync return
 keeps static pages off the microtask queue and leaves the bulk of the SSR tests synchronous.

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

@@ -22,8 +22,10 @@ OMITTED (see `shadowPreamble`) to avoid a duplicate identifier. Otherwise
 `state`/`linked`/`computed` are declared ambiently and `effect` is imported as a fallback
 for a bare/nested use the top-level rewrite doesn't project (unused when projected — fine,
 the shadow disables noUnusedLocals). `props` is the prop reader — destructured
-(`const { a = 1 } = props<Shape>()`); declared returning its type argument (default
-`Record<string, any>`) so each binding inherits its prop type and its `= default` narrows.
+(`const { a = 1 } = props<Shape>()`); a required import (`abide/ui/props`), so the shadow
+declares it only when imported, returning the file's contextual shape (route params or
+`Record<string, any>`) intersected with its own type argument — additive, so declared props
+like `children: Snippet` layer on top instead of re-spelling the route shape.
 */
 function shadowPreamble(importedReactives: ReadonlySet<string>): string {
     /* Omit the ambient fallback for a primitive the author imports — its own binding is
@@ -46,7 +48,6 @@ function shadowPreamble(importedReactives: ReadonlySet<string>): string {
         importedReactives.has('computed')
             ? undefined
             : 'declare function computed<T>(compute: () => T): { readonly value: T }',
-        'declare const children: (() => void) | undefined',
         /* `effect` is defined either way — the preamble import or the author's own import. */
         'void [effect, snippet, scope]',
     ]
@@ -76,15 +77,32 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, types, scope, propsShapes, diagnostics, importedReactives } = analyzeScript(
-        scriptBody,
-        scriptStart,
-    )
+    const { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName } =
+        analyzeScript(scriptBody, scriptStart)
     builder.raw(shadowPreamble(importedReactives))
-    /* `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`)
+    /* `props` is a required import (`abide/ui/props`). The shadow owns its type so the
+       return is file-contextual — the route param shape (page/layout) or `Record<string,
+       any>` (component), intersected with the author's annotation `T` so declared props
+       (notably `children: Snippet`) are ADDITIVE and route params never need re-spelling.
+       Emitted only when imported: a missing import surfaces as "Cannot find name 'props'"
+       (or the author's local alias), so `abide check` flags it. Declared under the LOCAL
+       binding name (alias-safe, like `state`/`effect`) — a `props as p` import must get a
+       `p` declare, or `p()` reads as undefined once the import below is stripped. */
+    if (propsLocalName !== undefined) {
+        builder.raw(`declare function ${propsLocalName}<T = {}>(): (${propsType}) & T\n`)
+    }
+    const propsSpecifier = `${ABIDE_PACKAGE_NAME}/ui/props`
     for (const line of imports) {
+        /* The `props` import is replaced by the contextual `declare function` above;
+           emitting it too would be a duplicate-identifier error. Matched by EXACT specifier
+           (either quote style, not a loose suffix match) so an unrelated user module merely
+           named `.../ui/props` survives verbatim. */
+        if (
+            line.text.includes(`from '${propsSpecifier}'`) ||
+            line.text.includes(`from "${propsSpecifier}"`)
+        ) {
+            continue
+        }
         builder.flush(line)
     }
     /* Component-local `type`/`interface` declarations are hoisted to module scope —
@@ -123,6 +141,19 @@ export function compileShadow(source: string, propsType = 'Record<string, any>')
     /* 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)
+    /* Emit the DOM-typed attachment aliases only when an element `attach` uses them: they
+       reference `HTMLElementTagNameMap`/`Element`, so a template with no element attach never
+       forces DOM lib into its shadow. `__ElementFor` maps a tag to its element interface
+       (HTML-first; unknown/custom tags fall back to `Element`); `__Attachment` sources its
+       return type from the real `attach` runtime signature so it never drifts. */
+    if (hasElementAttach(templateNodes)) {
+        builder.raw(
+            'type __ElementFor<T extends string> = T extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[T] : T extends keyof SVGElementTagNameMap ? SVGElementTagNameMap[T] : T extends keyof MathMLElementTagNameMap ? MathMLElementTagNameMap[T] : Element;\n',
+        )
+        builder.raw(
+            `type __Attachment<E extends Element> = (node: E) => ReturnType<Parameters<typeof import('${ABIDE_PACKAGE_NAME}/ui/dom/attach').attach>[1]>;\n`,
+        )
+    }
     emitNodes(templateNodes, builder)
     builder.raw('}\n')
     return { ...builder.result(), diagnostics }
@@ -209,6 +240,10 @@ type ScriptAnalysis = {
     /* The reactive primitives the author imports (`state`/`effect`), so the preamble
        omits the ambient fallback for each and avoids a duplicate-identifier error. */
     importedReactives: Set<string>
+    /* The LOCAL binding name the author's `props` import is bound to (alias-safe — `props`
+       for the canonical import, `p` for `props as p`), or undefined when not imported. The
+       `declare function` for `props` must target this name, not the canonical `'props'`. */
+    propsLocalName: string | undefined
 }
 
 /* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
@@ -321,7 +356,15 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     const propsShapes: string[] = []
     const diagnostics: ShadowDiagnostic[] = []
     if (scriptBody.trim() === '') {
-        return { imports, types, scope, propsShapes, diagnostics, importedReactives: new Set() }
+        return {
+            imports,
+            types,
+            scope,
+            propsShapes,
+            diagnostics,
+            importedReactives: new Set(),
+            propsLocalName: undefined,
+        }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
     /* The author's reactive import bindings (alias-safe) — recognition source for
@@ -329,6 +372,15 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
        the preamble omits its ambient fallback for. */
     const bindings = reactiveImportBindings(file)
     const importedReactives = new Set(bindings.direct.values())
+    /* The local name bound to `props` (alias-safe): the key whose value is the canonical
+       `'props'`. At most one — a file imports `props` from one specifier. */
+    let propsLocalName: string | undefined
+    for (const [local, canonical] of bindings.direct) {
+        if (canonical === 'props') {
+            propsLocalName = local
+            break
+        }
+    }
     /* 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. */
@@ -368,7 +420,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, propsShapes, verbatim, span, bindings))
         }
     }
-    return { imports, types, scope, propsShapes, diagnostics, importedReactives }
+    return { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`
@@ -446,14 +498,22 @@ function scopeLineFor(
     })
     if (callee === 'state') {
         /* state<T>(initial): T is the value type — carry it onto the `let` so an
-           explicit annotation isn't lost to `any`/`any[]` inference of the initial. */
-        const typeNode = call.typeArguments?.[0]
+           explicit annotation isn't lost to `any`/`any[]` inference of the initial. The
+           type comes from the generic (`state<T>(v)`), else the binding annotation
+           (`let x: T = state(v)`) — either form pins the cell type, so a narrow/`any`
+           inference of the initial (`state([])` → `any[]`) can't leak. */
+        const typeNode = call.typeArguments?.[0] ?? declaration.type
         const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
         const init = call.arguments[0]
-        if (init === undefined) {
-            /* No initial (`state<T>()`): the value is `T | undefined`. A definite-
-               assignment assertion (`!`) gives that union without a use-before-assign
-               false-positive AND without control-flow narrowing it to just `undefined`
+        /* A literal `undefined` initial is the no-arg form spelled out (`state<T>(undefined)`):
+           the value is `T | undefined`, never `= (undefined)` checked against a non-optional
+           `T` — which would spuriously flag "undefined not assignable to T". */
+        const initIsUndefined =
+            init !== undefined && ts.isIdentifier(init) && init.text === 'undefined'
+        if (init === undefined || initIsUndefined) {
+            /* No initial (`state<T>()` / `state<T>(undefined)`): the value is `T | undefined`.
+               A definite-assignment assertion (`!`) gives that union without a use-before-
+               assign false-positive AND without control-flow narrowing it to just `undefined`
                (an `= undefined` initializer, never reassigned in the shadow, would make
                a guard like `x !== undefined` collapse to `never`). Unguarded access is
                then correctly flagged possibly-undefined; a guard narrows cleanly. */
@@ -471,9 +531,12 @@ function scopeLineFor(
         })
     }
     /* computed<T>(compute) / linked<T>(seed) — the only callees left: T is the value
-       type — the call's first arg is a thunk, so invoking it yields the value. Annotate
-       so an explicit type argument isn't lost to inference of the thunk's return. */
-    const typeNode = call.typeArguments?.[0]
+       type — the call's first arg is a thunk, so invoking it yields the value. The type
+       comes from the generic (`computed<T>(fn)`), else the binding annotation
+       (`let x: T = state.computed(fn)`) — same fallback as `state` above, so a binding
+       annotation isn't dropped and `abide check` doesn't emit `never`-inference false
+       positives on the thunk's return. */
+    const typeNode = call.typeArguments?.[0] ?? declaration.type
     const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
     const fn = call.arguments[0]
     /* `linked` is a writable `State<T>` at runtime (it reseeds AND accepts `.value =`
@@ -494,6 +557,28 @@ function scopeLineFor(
     })
 }
 
+/* Whether any ELEMENT in the tree carries an `attach` — gates emitting the DOM-typed
+   attachment aliases. All nested content (block bodies, await/switch branches, snippet
+   bodies) routes through `children`, so a recursive `children` walk is complete. */
+function hasElementAttach(nodes: TemplateNode[]): boolean {
+    for (const node of nodes) {
+        if (node === undefined) {
+            continue
+        }
+        if (node.kind === 'element') {
+            for (const attr of node.attrs) {
+                if (attr.kind === 'attach') {
+                    return true
+                }
+            }
+        }
+        if ('children' in node && node.children !== undefined && hasElementAttach(node.children)) {
+            return true
+        }
+    }
+    return false
+}
+
 /* Emits a sibling list — each node standalone via `emitNode`. */
 function emitNodes(nodes: TemplateNode[], builder: Builder): void {
     for (const node of nodes) {
@@ -517,15 +602,26 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             return
         case 'element':
             for (const attr of node.attrs) {
-                /* An interpolated value checks each `{expr}` part on its own offset; every
-                   other dynamic attribute checks its single `code`. */
-                if (attr.kind === 'interpolated') {
+                if (attr.kind === 'attach') {
+                    /* `attach={code}` types its callback's `node` param from the element's tag
+                       (via `__ElementFor`) and checks the whole value is an attachment: an inline
+                       arrow's `node` reads the specific DOM interface, and a non-function value is
+                       rejected. Same IIFE-parameter contextual-typing trick the component-prop
+                       path uses; the leading `;` guards an unterminated preceding statement. */
+                    builder.raw(
+                        `;((__attach: __Attachment<__ElementFor<${JSON.stringify(node.tag)}>>) => {})(`,
+                    )
+                    builder.expr(attr.code, attr.loc)
+                    builder.raw(');\n')
+                } else if (attr.kind === 'interpolated') {
+                    /* An interpolated value checks each `{expr}` part on its own offset. */
                     for (const part of attr.parts) {
                         if (part.kind === 'expression') {
                             builder.stmt(part.code, part.loc)
                         }
                     }
                 } else if (attr.kind !== 'static') {
+                    /* Every other dynamic attribute checks its single `code`. */
                     builder.stmt(attr.code, attr.loc)
                 }
             }
@@ -773,7 +869,7 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 builder.mapped(node.params, node.loc)
             }
             /* Wrap the body in `snippet(() => …)` so the shadow types the snippet as
-               `(args) => Snippet<…>` — mirroring the runtime lowering (which returns
+               `(args) => SnippetValue` — mirroring the runtime lowering (which returns
                `$$snippet(($host) => …)`) so a snippet passed to a `Snippet`-typed prop
                type-checks instead of reading as `() => void`. */
             builder.raw(') => snippet(() => {\n')

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

@@ -11,8 +11,9 @@ SSR/client prop congruence rests on. No spread → the plain object literal of n
 value thunks (+ the trailing slot). With a `{...expr}` spread → a `mergeProps` of
 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
+`lowerExpression` is the caller's expression lowering; `slotPart` is its `children`
+layer — slotted content as a `Snippet` under the `children` prop key (a builder-
+returning callable for the client, a `$snip`-string-returning callable for SSR) — or
 undefined when the component has no slotted children.
 */
 export function composeProps(

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

@@ -430,7 +430,7 @@ function propsStatements(
                 ),
             )
         }
-        /* The rest bag gathers every prop not named above (and not `$children`). */
+        /* The rest bag gathers every prop not named above (and not `children`). */
         if (rest !== undefined) {
             const consumed = propBindings.map((binding) => factory.createStringLiteral(binding.key))
             statements.push(

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

@@ -200,7 +200,7 @@ export function generateBuild(
            (`type="number"`/`"range"`) reports its edit as a string on `el.value`, which
            would corrupt number-typed state; source the write-back from `valueAsNumber`
            instead (empty field → `undefined`), gated on a statically-known type. */
-        const event = bindListenEvent(attr.property, node.tag)
+        const event = bindListenEvent(attr.property)
         const staticType = staticAttrValue(node, 'type')
         const isNumericInput =
             attr.property === 'value' &&
@@ -547,21 +547,29 @@ export function generateBuild(
         return `$$switchBlock(${parentVar}, () => (${lowerExpression(node.subject)}), [${cases}], ${before});\n`
     }
 
-    /* A `{children()}` slot fill point: render the parent-provided content (`$children`).
-       A fallback is now an authored `{#if children}…{:else}…{/if}`, so the slot node never
-       carries children — the invoke is unconditional but guarded against a propless mount. */
+    /* A component `{children()}` fill point: mount the `children` prop (a `Snippet`) by
+       calling it and mounting the resulting value through the snippet interpolation path,
+       exactly as any `{snippet(args)}`. `lowerExpression('children()')` reads the destructured
+       `children` computed and calls it → a `SnippetValue`, which `appendText` routes to
+       `appendSnippet`. A fallback is now an authored `{#if children}…{:else}…{/if}`, so the slot
+       node carries no children. Layouts never reach here — their slots are rewritten to `outlet`
+       elements by `asOutlet`. */
     function generateSlot(
         _node: Extract<TemplateNode, { kind: 'element' }>,
         parentVar: string,
     ): string {
-        return `if ($props && $props.$children) { $props.$children(${parentVar}); }\n`
+        return `$$appendText(${parentVar}, () => (${lowerExpression('children()')}));\n`
     }
 
-    /* The child's slot content as a host-taking builder (`$children`), or undefined when
-       the component has no slotted children. */
+    /* Slot content as a zero-arg `Snippet` under the `children` key — a callable returning a
+       `$$snippet`-branded builder, so it unifies with a passed `children={snippet}` and mounts
+       through the standard snippet interpolation path. `composeProps` wraps it in the prop-bag
+       thunk, so the final bag value is `() => (Snippet callable)`. */
     function slotPart(node: Extract<TemplateNode, { kind: 'component' }>): string | undefined {
         const slotCode = generateChildren(node.children, '$slot')
-        return slotCode.trim() === '' ? undefined : `"$children": ($slot) => {\n${slotCode}}`
+        return slotCode.trim() === ''
+            ? undefined
+            : `"children": () => (() => $$snippet(($slot) => {\n${slotCode}}))`
     }
 
     /* The props bag a child mount receives — composed by the shared `composeProps` so the
@@ -581,7 +589,13 @@ export function generateBuild(
         parentVar: string,
         before: string,
     ): string {
-        return `$$mountChild(${parentVar}, ${node.name}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)});\n`
+        /* The tag lowers through `lowerExpression` like any other reference: a static
+           module import (`Button`) is left bare, but a reactive binding — a `{#for}`
+           item, an `await` `then` value, a component signal — derefs to its `.value`
+           cell, so `<Icon>` from `{#for {icon: Icon} of …}` mounts the component the cell
+           holds, not the cell object (whose `.build` is undefined → `build is not a
+           function`). SSR emits the same lowering for congruence. */
+        return `$$mountChild(${parentVar}, ${lowerExpression(node.name)}, ${propsArg(node)}, ${before}, ${JSON.stringify(node.name)});\n`
     }
 
     /* An await block: pending → resolved(value) / error branches. Each branch is a