@abide/abide 0.48.0 → 0.49.0

package/src/lib/shared/buildArtifact.ts

@@ -0,0 +1,17 @@
+import type { BuildConfig, BuildOutput } from 'bun'
+import { exitOnBuildFailure } from './exitOnBuildFailure.ts'
+
+/*
+Runs one Bun.build and fails the process on any diagnostic, returning the
+successful output — the build-or-die pairing every one-shot build site shares
+(compile, buildCli's discovery + cli, bundleApp, buildDisconnected). Keeps the
+`Bun.build` + `exitOnBuildFailure` step atomic so a new build site can't ship
+without the failure check. The incremental client build (build.ts) does NOT use
+this: it must clean its staging dir and return `false` rather than exit, so it
+keeps its own epilogue.
+*/
+export async function buildArtifact(config: BuildConfig): Promise<BuildOutput> {
+    const result = await Bun.build(config)
+    exitOnBuildFailure(result)
+    return result
+}

package/src/lib/shared/buildRpcRequest.ts

@@ -68,8 +68,12 @@ function appendQuery(method: HttpMethod, url: string, args: unknown): string {
     if (args === undefined) {
         return url
     }
-    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
-        const got = Array.isArray(args) ? 'array' : typeof args
+    const isFormData = typeof FormData !== 'undefined' && args instanceof FormData
+    if (typeof args !== 'object' || args === null || Array.isArray(args) || isFormData) {
+        /* FormData has no own enumerable keys, so `queryStringFromArgs` would silently drop
+           every field; a query-carrying method (GET/DELETE/HEAD) can't take a body anyway.
+           Fail loudly like any other non-plain-object arg. */
+        const got = Array.isArray(args) ? 'array' : isFormData ? 'FormData' : typeof args
         throw new Error(`[abide] ${method} ${url} args must be a plain object — got ${got}`)
     }
     const suffix = queryStringFromArgs(args as Record<string, unknown>, false)

package/src/lib/shared/canonicalJson.ts

@@ -8,7 +8,8 @@ POST/PUT/PATCH bodies; the output is a key, not a request body, so it is free to
 encode types JSON.stringify would silently flatten (Map/Set → {}), coerce
 (Date → its ISO string, via toJSON before any replacer sees it) or drop
 (undefined). Covers the value types commonly passed as rpc args: primitives,
-arrays, plain objects, Date, Map, Set, and bigint. Functions and symbols can't
+arrays, plain objects, Date, Map, Set, bigint, and FormData/File/Blob (the
+multipart upload path). Functions and symbols can't
 key anything meaningful but are tagged rather than dropped so a stray one can't
 silently collapse two distinct argument sets onto the same key.
 */
@@ -55,6 +56,28 @@ export function canonicalJson(value: unknown): string {
         const members = Array.from(value, canonicalJson).sort()
         return `Set{${members.join(',')}}`
     }
+    /* FormData is the documented multipart escape hatch for body rpcs. Its fields are
+       NOT own enumerable keys, so the generic object branch below would return `{}` for
+       every distinct upload — collapsing them onto one cache key and coalescing unrelated
+       uploads onto each other. Encode its entries (sorted, so field order doesn't change
+       the key) with File/Blob distinguished by identity attributes below. */
+    if (typeof FormData !== 'undefined' && value instanceof FormData) {
+        const entries: string[] = []
+        value.forEach((entryValue, entryKey) => {
+            entries.push(`${JSON.stringify(entryKey)}=>${canonicalJson(entryValue)}`)
+        })
+        entries.sort()
+        return `FormData{${entries.join(',')}}`
+    }
+    /* File extends Blob — check it first so a named upload keys on its name too. Contents
+       can't be read synchronously, so identity attributes are the best available key;
+       distinct files (name/size/type/mtime) get distinct keys, which is the fix. */
+    if (typeof File !== 'undefined' && value instanceof File) {
+        return `File(${JSON.stringify(value.name)},${value.size},${JSON.stringify(value.type)},${value.lastModified})`
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return `Blob(${value.size},${JSON.stringify(value.type)})`
+    }
     const record = value as Record<string, unknown>
     const entries = Object.keys(record)
         .sort()

package/src/lib/shared/createChannelLog.ts

@@ -24,8 +24,32 @@ function channelPatterns(): string | undefined {
     return undefined
 }
 
+/* One line for an AggregateError sub-error: its message, prefixed with the source
+   position when it carries one. A thrown `Bun.build` failure holds a `BuildMessage`
+   per diagnostic, each with a `position.file` — naming that file is the point, since
+   without it a codegen/parse failure reads as a detail-free "Bundle failed". */
+function formatAggregateEntry(entry: unknown): string {
+    if (typeof entry === 'object' && entry !== null && 'message' in entry) {
+        const message = String((entry as { message: unknown }).message)
+        const position = (entry as { position?: { file?: string; line?: number; column?: number } })
+            .position
+        if (position?.file) {
+            return `  ${position.file}:${position.line ?? 0}:${position.column ?? 0} — ${message}`
+        }
+        return `  ${message}`
+    }
+    return `  ${String(entry)}`
+}
+
 // Prefers a full stack trace when the value is an Error so logs include the call site.
+// An AggregateError (a thrown Bun.build failure among them) carries the real diagnostics
+// in `.errors` — its own message is only a summary ("Bundle failed") — so expand each one,
+// or every per-file position is dropped and the failure reads with zero detail.
 function errorParts(value: unknown): { msg: string; stack?: string } {
+    if (value instanceof AggregateError && value.errors.length > 0) {
+        const details = value.errors.map(formatAggregateEntry).join('\n')
+        return { msg: `${value.message}\n${details}` }
+    }
     if (value instanceof Error) {
         return { msg: value.message, stack: value.stack }
     }

package/src/lib/shared/exitOnBuildFailure.ts

@@ -2,9 +2,10 @@ import type { BuildOutput } from 'bun'
 import { abideLog } from './abideLog.ts'
 
 /*
-On a failed Bun.build(), logs each diagnostic and exits non-zero. Every abide
-build entrypoint (build / compile / buildCli / bundleApp) funnels its result
-through here so failure reporting can't drift between them.
+On a failed Bun.build(), logs each diagnostic and exits non-zero. The one-shot
+build entrypoints reach it through `buildArtifact` (build-or-die); the
+incremental client build (build.ts) calls it directly on its conditional-exit
+path. One reporter so build failure can't drift between them.
 */
 export function exitOnBuildFailure(result: BuildOutput): void {
     if (result.success) {

package/src/lib/shared/parseEnv.ts

@@ -9,7 +9,9 @@ counterpart to loadEnvFile (which merges into process.env) and serializeEnv
 */
 export function parseEnv(text: string): Record<string, string> {
     const result: Record<string, string> = {}
-    for (const line of text.split('\n')) {
+    // Split on CRLF or LF — a Windows-saved (or git autocrlf) .env otherwise leaves a
+    // trailing \r that breaks ENV_LINE's `$` anchor, silently dropping every line.
+    for (const line of text.split(/\r?\n/)) {
         if (!line || line.startsWith('#')) {
             continue
         }
@@ -19,11 +21,20 @@ export function parseEnv(text: string): Record<string, string> {
         }
         const [, key, rawValue] = match
         const trimmed = rawValue?.trim() ?? ''
-        const unquoted =
-            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-            (trimmed.startsWith("'") && trimmed.endsWith("'"))
-                ? trimmed.slice(1, -1)
-                : trimmed
+        let unquoted: string
+        if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+            // Double-quoted: unescape the sequences serializeEnv writes (`\\`, `\"`, `\n`, `\r`).
+            unquoted = trimmed
+                .slice(1, -1)
+                .replace(/\\([nr"\\])/g, (_, c: string) =>
+                    c === 'n' ? '\n' : c === 'r' ? '\r' : c,
+                )
+        } else if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) {
+            // Single-quoted: taken verbatim (no escaping applied on the way out).
+            unquoted = trimmed.slice(1, -1)
+        } else {
+            unquoted = trimmed
+        }
         result[key as string] = unquoted
     }
     return result

package/src/lib/shared/serializeEnv.ts

@@ -1,18 +1,30 @@
-// Quote only values that wouldn't round-trip bare through parseEnv — empties and
-// anything carrying whitespace or a `#` (which would otherwise read as a comment).
+// Quote any value that wouldn't round-trip bare through parseEnv: empties, anything
+// carrying whitespace/`#` (a comment)/a quote/a backslash, or one that starts or ends with
+// a quote char (parseEnv strips a surrounding quote pair). Everything else stays bare.
 function needsQuoting(value: string): boolean {
-    return value === '' || /[\s#]/.test(value)
+    return value === '' || /[\s#"\\]/.test(value) || /^['"]|['"]$/.test(value)
+}
+
+// Escape a value for inside double quotes: backslash and quote so the closing quote can't
+// be faked, and newlines so an embedded `\n` can't inject a whole new `KEY=value` line
+// (the security fix — an unescaped token newline used to forge extra env entries).
+function escapeQuoted(value: string): string {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
 }
 
 /*
 Serializes a key→value record to `.env` text — the inverse of parseEnv, used by
 the connect-screen config form to persist the user's answers to the data-dir
-`.env`. One `KEY=value` per line; values that need it are wrapped in double
-quotes so parseEnv reads them back unchanged.
+`.env`. One `KEY=value` per line; values that need it are double-quoted and escaped
+so parseEnv reads them back unchanged and a value can never inject extra lines.
 */
 export function serializeEnv(values: Record<string, string>): string {
     const lines = Object.entries(values).map(([key, value]) =>
-        needsQuoting(value) ? `${key}="${value}"` : `${key}=${value}`,
+        needsQuoting(value) ? `${key}="${escapeQuoted(value)}"` : `${key}=${value}`,
     )
     return `${lines.join('\n')}\n`
 }

package/src/lib/shared/snippet.ts

@@ -1,18 +1,23 @@
 const SNIPPET = Symbol.for('abide.snippet')
 
-/* A `{#snippet name(args)}` snippet, called like a function: it carries a payload a
-   `{expr}` interpolation mounts in place — a DOM builder `(host) => void` on the
+/* The internal payload a snippet carries — a DOM builder `(host) => void` on the
    client, the pre-rendered HTML string on the server. The brand is a registered
    Symbol so it survives across module/bundle copies (same idiom as `html\`\``). */
-export type Snippet<Payload> = { readonly [SNIPPET]: Payload }
+export type SnippetValue = { readonly [SNIPPET]: unknown }
+
+/* The author-facing snippet type: a builder invoked with its arguments, yielding a
+   mountable value. `children` is `Snippet` (no args, invoked `children()`); a row
+   renderer is `Snippet<[Item]>` (invoked `row(item)`). The side-specific payload is
+   hidden behind `SnippetValue`. */
+export type Snippet<Args extends unknown[] = []> = (...args: Args) => SnippetValue
 
 /* Brands a snippet payload so a `{expr}` interpolation mounts it instead of
    inserting escaped text. The compiler wraps a snippet's body in this — the client
    builder closes over the defining component's scope, the server string is its SSR
    render — so a snippet value passes through props like any other value. */
 // @documentation templating
-export function snippet<Payload>(payload: Payload): Snippet<Payload> {
-    return { [SNIPPET]: payload }
+export function snippet<Payload>(payload: Payload): SnippetValue {
+    return { [SNIPPET]: payload } as SnippetValue
 }
 
 /* The payload of a snippet-branded value, or undefined for anything else — so a
@@ -20,6 +25,6 @@ export function snippet<Payload>(payload: Payload): Snippet<Payload> {
    reads a builder function; the server reads the rendered string. */
 export function snippetPayload(value: unknown): unknown {
     return value !== null && typeof value === 'object' && SNIPPET in value
-        ? (value as Snippet<unknown>)[SNIPPET]
+        ? (value as SnippetValue)[SNIPPET]
         : undefined
 }

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/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