@abide/abide 0.38.1 → 0.40.0

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

@@ -1,4 +1,5 @@
 import { decodeHtmlEntities } from './decodeHtmlEntities.ts'
+import { isWhitespaceText } from './isWhitespaceText.ts'
 import type { TemplateAttr } from './types/TemplateAttr.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import type { TextPart } from './types/TextPart.ts'
@@ -121,6 +122,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 +182,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 +239,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)
@@ -274,6 +304,13 @@ function rejectStrayBranches(
                 '[abide] <template else>/<template case> must be nested inside its <template if>/<template switch> — a sibling branch is not supported',
             )
         }
+        /* `elseif` is an `if`-chain branch; inside a `switch` it would silently read as the
+           default (match-less), so reject the cross-construct mix. */
+        if (node.kind === 'case' && node.condition !== undefined && parentKind === 'switch') {
+            throw new Error(
+                '[abide] <template elseif> belongs to a <template if> chain, not a <template switch> — use <template case>',
+            )
+        }
         if (
             node.kind === 'branch' &&
             parentKind !== 'await' &&
@@ -284,20 +321,77 @@ function rejectStrayBranches(
                 '[abide] <template then>/<template catch>/<template finally> must be nested inside its <template await>/<template try>/<template each await>',
             )
         }
+        if (node.kind === 'if' || node.kind === 'switch') {
+            rejectMisplacedBranchContent(node)
+        }
         if ('children' in node) {
             rejectStrayBranches(node.children, node.kind)
         }
     }
 }
 
+/* A `<template if>` chain's `then` content precedes its first branch tag
+   (`elseif`/`else`); a `<template switch>` renders only its branch tags. So rendered
+   content sitting AFTER the first branch in an `if` — or ANYWHERE in a `switch` —
+   belongs to no branch: today it silently folds into `then` / is dropped. Reject it so
+   the misplacement surfaces. Whitespace stays transparent, and `<script>`/`<style>` are
+   directives (scoping, not rendered output), so both remain legal anywhere. */
+function rejectMisplacedBranchContent(
+    node: Extract<TemplateNode, { kind: 'if' | 'switch' }>,
+): void {
+    const firstBranch = node.children.findIndex((child) => child.kind === 'case')
+    node.children.forEach((child, index) => {
+        const isRenderedContent =
+            child.kind !== 'case' &&
+            child.kind !== 'script' &&
+            child.kind !== 'style' &&
+            !isWhitespaceText(child)
+        /* In a switch nothing but branches renders, so every position is illegal; in an if
+           only content past the first branch is (the leading then-content is legal). */
+        const illegalPosition =
+            node.kind === 'switch' || (firstBranch !== -1 && index > firstBranch)
+        if (isRenderedContent && illegalPosition) {
+            throw new Error(
+                node.kind === 'switch'
+                    ? '[abide] a <template switch> renders only its <template case>/<template default> branches — move stray content into a branch'
+                    : '[abide] content after a <template elseif>/<template else> belongs to no branch — the then-content must precede the first branch tag',
+            )
+        }
+    })
+    /* In an `if` chain the match-less `<template else>` is the trailing block, so any
+       branch after it (a second `else`, or an `elseif`) compiles to invalid `} else {…}
+       else if {…}` (SSR/type-shadow) or a silently-shadowed branch (the `switchBlock`
+       default wins). Reject so the misordering surfaces here, not as opaque codegen. */
+    if (node.kind === 'if') {
+        const branches = node.children.filter(
+            (child): child is Extract<TemplateNode, { kind: 'case' }> => child.kind === 'case',
+        )
+        const elseIndex = branches.findIndex(
+            (branch) => branch.match === undefined && branch.condition === undefined,
+        )
+        if (elseIndex !== -1 && elseIndex < branches.length - 1) {
+            throw new Error(
+                '[abide] <template else> must be the last branch of its <template if> chain — no <template elseif>/<template else> may follow it',
+            )
+        }
+    }
+}
+
 /* Turns a component's attributes into props. A component has no directives —
    every attribute is a prop under its written name, so `on*`/`bind:`/`attach`
    round-trip to their original names (the kinds the tag-blind attribute parser
    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 +441,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
 }
 
@@ -425,6 +526,22 @@ function toControlFlow(attrs: TemplateAttr[], children: TemplateNode[]): Templat
         }
         return { kind: 'case', match: matchCode, children, loc: attrLoc(caseAttr) }
     }
+    /* `<template elseif={c}>` is a match-less case carrying a condition — a branch of the
+       enclosing `<template if>` chain, truthy-tested in source order. */
+    const elseif = find('elseif')
+    if (elseif !== undefined) {
+        const conditionCode = attrText(elseif)
+        if (conditionCode === undefined) {
+            throw new Error('[abide] <template elseif> requires a condition expression')
+        }
+        return {
+            kind: 'case',
+            match: undefined,
+            condition: conditionCode,
+            children,
+            loc: attrLoc(elseif),
+        }
+    }
     if (find('default') !== undefined || find('else') !== undefined) {
         return { kind: 'case', match: undefined, children } // default (switch) / else (if)
     }

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

@@ -68,6 +68,18 @@ export function renameSignalRefs(
                with that name added, so shadowing is per-branch (a sibling scope is unaffected). */
             const makeVisitor = (shadowed: ReadonlySet<string>): ts.Visitor => {
                 const visit = (node: ts.Node): ts.Node => {
+                    /* Type space never holds a value read. A type alias, an interface, or any
+                       type annotation can name a signal — a prop-type member `option?: …`, a
+                       `typeof x` — without it being a runtime reference. Leave the whole type
+                       subtree untouched so it isn't rewritten into a call/access (`option()`)
+                       and emitted as broken code (types erase at build anyway). */
+                    if (
+                        ts.isTypeAliasDeclaration(node) ||
+                        ts.isInterfaceDeclaration(node) ||
+                        ts.isTypeNode(node)
+                    ) {
+                        return node
+                    }
                     /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`,
                        unless a nearer scope shadows the name. */
                     if (ts.isShorthandPropertyAssignment(node) && !shadowed.has(node.name.text)) {

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

@@ -0,0 +1,21 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+type Branch = Extract<TemplateNode, { kind: 'branch' }>
+type BranchName = Branch['branch']
+
+/* Extracts the `then`/`catch`/`finally` branch children of a control-flow block
+   (await/try), one slot per requested name in the order asked, so callers
+   destructure them directly. A requested branch that is absent yields `undefined`
+   — the caller reads `?.children`/`?.as` for its content and bound var. This is
+   the one branch-lookup site both back-ends share, replacing the per-generator
+   `findBranch`/`branchNamed`/`branchChildren`/`branchVar` copies. */
+export function resolveBranches(
+    node: Extract<TemplateNode, { children: TemplateNode[] }>,
+    ...which: BranchName[]
+): (Branch | undefined)[] {
+    return which.map((name) =>
+        node.children.find(
+            (child): child is Branch => child.kind === 'branch' && child.branch === name,
+        ),
+    )
+}

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

@@ -0,0 +1,27 @@
+import type { TemplateAttr } from './types/TemplateAttr.ts'
+
+/*
+The explicitly-authored attribute names on a native element that also carries a
+`{...spread}`. An explicit attribute wins over a spread key of the same name, so
+both back-ends pass this set to skip those keys from the spread — keeping the
+server string and the client DOM congruent (no duplicate attribute, and no
+SSR-first-wins vs client-spread-wins divergence). Excluding by NAME (not by a
+runtime present/absent check) means the two sides agree regardless of a dynamic
+attribute's runtime value. Static and dynamic (`{expr}`) attrs contribute their
+name, a `bind:` its property, an `on<event>` its `on…` form; `attach`/`spread`
+carry no attribute name.
+*/
+export function spreadExcludedNames(attrs: TemplateAttr[]): string[] {
+    return attrs.flatMap((attr) => {
+        if (attr.kind === 'static' || attr.kind === 'expression') {
+            return [attr.name]
+        }
+        if (attr.kind === 'bind') {
+            return [attr.property]
+        }
+        if (attr.kind === 'event') {
+            return [`on${attr.event}`]
+        }
+        return []
+    })
+}

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

@@ -1,4 +1,4 @@
-import { escapeHtml } from './escapeHtml.ts'
+import { escapeHtml } from '../../shared/escapeHtml.ts'
 
 /*
 Serializes one static attribute to its markup fragment, leading space included.

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

@@ -1,4 +1,4 @@
-import { escapeHtml } from './escapeHtml.ts'
+import { escapeHtml } from '../../shared/escapeHtml.ts'
 
 /*
 Serializes one static text part to its markup: whitespace-only parts drop (both

package/src/lib/ui/compile/types/TemplateAttr.ts

@@ -6,7 +6,9 @@ reactively; `event` is `on<event>={code}` where `code` evaluates to the handler;
 `bind` is `bind:<property>={lvalue}`, a two-way binding whose `code` is the
 writable doc path read into the property and written back on input; `attach` is
 `attach={code}` where `code` evaluates to an attachment `(node) => teardown` run
-at build with node-lifetime teardown. `loc` is the
+at build with node-lifetime teardown; `spread` is `{...code}` where `code`
+evaluates to an object whose own keys each become a prop on a component or an
+attribute on a native element. `loc` is the
 absolute offset of `code` in the original `.abide` source (see TextPart) —
 optional, set only when the parser tracks positions for the type-checking shadow.
 */
@@ -16,3 +18,4 @@ export type TemplateAttr =
     | { kind: 'event'; event: string; code: string; loc?: number }
     | { kind: 'bind'; property: string; code: string; loc?: number }
     | { kind: 'attach'; code: string; loc?: number }
+    | { kind: 'spread'; code: string; loc?: number }

package/src/lib/ui/compile/types/TemplateNode.ts

@@ -4,7 +4,7 @@ import type { TextPart } from './TextPart.ts'
 /*
 A parsed template node. `text` carries interpolation parts; `element` carries
 attributes and children; `each` is the `<template each as key>` control flow over
-a list. (if/await/switch are future siblings.)
+a list; `if`/`await`/`switch`/`try` are its control-flow siblings.
 
 `loc` (where present) is the absolute offset of the node's primary expression in
 the original `.abide` source — additive, set only when the parser tracks
@@ -61,11 +61,23 @@ export type TemplateNode =
     | {
           kind: 'component'
           name: string
-          props: { name: string; code: string; loc?: number }[]
+          /* Each authored attribute as a prop. A `spread` entry (`{...code}`) carries no
+             `name`; its keys merge in at runtime (`mergeProps`/`spreadProps`). */
+          props: { name: string; code: string; loc?: number; spread?: boolean }[]
           children: TemplateNode[]
       }
     | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }
-    | { kind: 'case'; match: string | undefined; children: TemplateNode[]; loc?: number }
+    /* A branch of a `<template switch>` (`match` set) or `<template if>` chain. Inside an
+       `if`, `<template elseif={c}>` sets `condition` (match-less, truthy-tested), and
+       `<template else>` leaves both unset (the default). `loc` points at whichever
+       expression the node carries (`match` or `condition`). */
+    | {
+          kind: 'case'
+          match: string | undefined
+          condition?: string
+          children: TemplateNode[]
+          loc?: number
+      }
     /* A `<template name="row" args={item}>` snippet: a named, scope-capturing
        builder declared once and called like a function (`{row(item)}`). `params`
        is the raw `args` source spliced into the builder's parameter list. */

package/src/lib/ui/createScope.ts

@@ -37,6 +37,9 @@ export function createScope(
     const data = (): Doc => (document ??= createDoc({}))
     const id = parent === undefined ? `scope-${nextId++}` : `${parent.id}.${nextId++}`
     const children: Scope[] = []
+    /* Context values shared down the tree, held apart from the reactive doc (which
+       a child does not inherit): keyed by name, read by the closest ancestor walk. */
+    const shared = new Map<string, unknown>()
     let past: History | undefined
     let persistence: PersistHandle | undefined
     let unsync: (() => void) | undefined
@@ -64,6 +67,16 @@ export function createScope(
             return created
         },
         root: () => (parent === undefined ? self : parent.root()),
+        /* Reference store — no tracking, so a lookup never subscribes; reactivity comes
+           from what is shared (a cell/scope), not from the share. */
+        share: (key, value) => {
+            shared.set(key, value)
+        },
+        /* Closest-ancestor resolve: own map first (self can read what it shared), then
+           defer up via each scope's own `shared`. `has` distinguishes a shared
+           `undefined` from "not provided"; undefined at the root means no provider. */
+        shared: <T>(key: string): T | undefined =>
+            shared.has(key) ? (shared.get(key) as T) : parent?.shared<T>(key),
         record: (options) => {
             past ??= history(data(), options)
         },
@@ -82,6 +95,7 @@ export function createScope(
                 created.dispose()
             }
             children.length = 0
+            shared.clear()
             past?.dispose()
             past = undefined
             persistence?.dispose()

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

@@ -4,6 +4,7 @@ import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { appendSnippet } from './appendSnippet.ts'
+import { parseRawNodes } from './parseRawNodes.ts'
 
 const CLOSE = '/abide:html'
 
@@ -73,9 +74,7 @@ function appendRawHtml(parent: Node, read: () => unknown): void {
         for (const node of nodes) {
             parent.removeChild(node)
         }
-        const holder = document.createElement('div')
-        holder.innerHTML = value
-        nodes = [...holder.childNodes]
+        nodes = parseRawNodes(parent, value)
         for (const node of nodes) {
             parent.insertBefore(node, anchor)
         }

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

@@ -4,6 +4,7 @@ import { effect } from '../effect.ts'
 import { RENDER } from '../runtime/RENDER.ts'
 import { appendSnippet } from './appendSnippet.ts'
 import { appendText } from './appendText.ts'
+import { parseRawNodes } from './parseRawNodes.ts'
 
 /*
 A reactive `{expr}` interpolation mounted at a skeleton anchor comment (`<!--a-->`), used
@@ -51,9 +52,7 @@ export function appendTextAt(anchor: Node, read: () => unknown): void {
             for (const node of nodes) {
                 parent.removeChild(node)
             }
-            const holder = document.createElement('div')
-            holder.innerHTML = rawHtmlString(read()) ?? ''
-            nodes = [...holder.childNodes]
+            nodes = parseRawNodes(parent, rawHtmlString(read()) ?? '')
             /* Insert the fresh markup just after the anchor (its live re-insertion point). */
             const after = anchor.nextSibling
             for (const node of nodes) {

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

@@ -41,16 +41,13 @@ export function applyResolved(root: Element, frame: string): void {
     if (id === null) {
         return
     }
-    /* The resolved value rides in a leading <script type=application/json>; parse and
-       remove it so only the resolved markup moves into the boundary. Recording it lets a
-       later hydrate adopt this branch (no re-fetch). */
+    /* The resolved value rides in a leading <script type=application/json> as ref-json
+       text; store it raw and remove the node so only the resolved markup moves into the
+       boundary. Decoding is deferred to the read in `awaitBlock` (which has the codec);
+       recording it lets a later hydrate adopt this branch (no re-fetch). */
     const payload = resolved.firstChild as Element | null
     if (payload !== null && payload.nodeName === 'SCRIPT') {
-        try {
-            RESUME[Number(id)] = JSON.parse(payload.textContent ?? 'null')
-        } catch {
-            /* malformed payload — leave unregistered, hydration re-runs the promise */
-        }
+        RESUME[Number(id)] = payload.textContent ?? ''
         payload.remove()
     }
     const open = `abide:await:${id}`

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

@@ -1,6 +1,8 @@
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { effect } from '../effect.ts'
 import { claimChild } from '../runtime/claimChild.ts'
 import { RENDER } from '../runtime/RENDER.ts'
+import type { ResumeEntry } from '../runtime/RESUME.ts'
 import { RESUME } from '../runtime/RESUME.ts'
 import { scope } from '../runtime/scope.ts'
 import { scopeGroup } from '../runtime/scopeGroup.ts'
@@ -161,7 +163,18 @@ export function awaitBlock(
     const firstHydrate = (result: unknown): void => {
         const cursor = hydration as NonNullable<typeof hydration>
         const open = claimChild(cursor, parent)
-        const entry = RESUME[id]
+        /* RESUME holds the ref-json-encoded entry STRING; decode here, where the codec
+           lives. A decode failure (malformed/absent payload) reads as "no resume" — fall
+           through to the live promise rather than crash hydration. */
+        const raw = RESUME[id]
+        let entry: ResumeEntry | undefined
+        if (raw !== undefined) {
+            try {
+                entry = decodeRefJson(raw) as ResumeEntry
+            } catch {
+                entry = undefined
+            }
+        }
         if (entry !== undefined) {
             let build: (host: Node) => void
             if (entry.ok) {

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

@@ -0,0 +1,32 @@
+import type { UiProps } from '../runtime/types/UiProps.ts'
+
+/*
+Composes a child's props from ordered layers — explicit prop runs (`{ name: () =>
+value }` thunk maps), `{...spread}` layers (`spreadProps`), and a trailing slot
+layer (`$children`) — into one prop bag, last layer wins per key (source order, like
+JSX). A key resolves by scanning layers in reverse for the first that carries it, so
+an explicit prop after a spread overrides it and vice-versa. Emitted only when a
+component carries a spread; the plain object literal stays the path otherwise.
+*/
+// @documentation plumbing
+export function mergeProps(layers: Record<string | symbol, unknown>[]): UiProps {
+    return new Proxy(Object.create(null), {
+        get(_target, key) {
+            for (let index = layers.length - 1; index >= 0; index -= 1) {
+                const layer = layers[index]
+                if (layer !== undefined && key in layer) {
+                    return layer[key]
+                }
+            }
+            return undefined
+        },
+        has: (_target, key) => layers.some((layer) => key in layer),
+        /* Enumerable across every layer (deduped), so `restProps` can collect a
+           parent-spread bag's keys. */
+        ownKeys: () => [...new Set(layers.flatMap((layer) => Reflect.ownKeys(layer)))],
+        getOwnPropertyDescriptor: (_target, key) =>
+            layers.some((layer) => key in layer)
+                ? { enumerable: true, configurable: true }
+                : undefined,
+    }) as UiProps
+}

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

@@ -12,6 +12,13 @@ resolves the component, not whatever is current when the event fires.
 */
 // @documentation plumbing
 export function on(element: Element, type: string, handler: EventListener): void {
+    /* A caller that omits an optional `on*` prop forwards it as undefined, yet the
+       compiler still emits this on() call — so skip attaching a non-function rather
+       than invoke undefined when the event fires (e.g. input/keydown on a search box,
+       which would throw "handler is not a function" on every keystroke). */
+    if (typeof handler !== 'function') {
+        return
+    }
     const captured = CURRENT_SCOPE.current
     const wrapped: EventListener = (event) => inScope(captured, () => handler(event))
     element.addEventListener(type, wrapped)

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

@@ -0,0 +1,17 @@
+import { foreignWrapperTag } from './foreignWrapperTag.ts'
+
+/*
+Parses a trusted raw-markup string into detached nodes in the SAME foreign namespace
+as `parent`. The HTML fragment parser namespaces by its context element, so markup
+bound inside an <svg>/<math> must parse inside a matching wrapper — otherwise a bare
+`<path>` lands in the HTML namespace and never renders. Mirrors `cloneStatic`'s
+foreign handling, but parses per-call into a throwaway `<template>` rather than the
+skeleton cache: raw values are dynamic, so caching every distinct string would leak.
+*/
+export function parseRawNodes(parent: Node, markup: string): Node[] {
+    const wrapper = foreignWrapperTag(parent)
+    const template = document.createElement('template')
+    template.innerHTML = wrapper === undefined ? markup : `<${wrapper}>${markup}</${wrapper}>`
+    const source = wrapper === undefined ? template.content : (template.content.firstChild as Node)
+    return [...source.childNodes]
+}

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

@@ -0,0 +1,27 @@
+/*
+Guarded method call on a reactive-document read. The doc-access lowering rewrites
+`model.draft.trim()` into `model.read("draft").trim()`; when that read is nullish
+the bare form throws the engine's opaque `undefined is not an object (evaluating
+'…read("draft").trim()')`, naming only the desugared call. This wraps the
+non-optional call so the throw names the authored scope path and member instead —
+the source-mapped stack frame still resolves to the `.abide` line, so message and
+location together read in authored terms. Both opaque engine errors are covered: a
+nullish receiver (`undefined is not an object`) AND a present receiver whose member
+is not callable (`… is not a function`, the misspelled/missing-method case).
+Optional-chained calls are left bare: `?.` means skip-if-absent, not throw, so
+guarding them would change semantics. `.apply(target, …)` preserves the receiver, so
+the method sees the same `this` the bare `target.member(…)` would.
+*/
+// @documentation plumbing
+export function readCall(target: unknown, path: string, member: string, args: unknown[]): unknown {
+    if (target === undefined || target === null) {
+        throw new TypeError(`abide: cannot call .${member}() — scope value "${path}" is ${target}`)
+    }
+    const method = (target as Record<string, unknown>)[member]
+    if (typeof method !== 'function') {
+        throw new TypeError(
+            `abide: cannot call .${member}() — "${path}".${member} is not a function (got ${typeof method})`,
+        )
+    }
+    return (method as (...args: unknown[]) => unknown).apply(target, args)
+}

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

@@ -0,0 +1,32 @@
+import type { UiProps } from '../runtime/types/UiProps.ts'
+
+/*
+The rest of a component's props — `const { foo, ...rest } = props()` — as a live
+object of the UNCONSUMED prop values. A child receives prop THUNKS, so `rest.key`
+unwraps them (`$props[key]?.()`), tracking as a reactive dependency; a top-level
+page/layout instead receives its route params as PLAIN values, so a non-function
+value is returned as-is rather than called (which would throw `value is not a
+function`). The explicitly-destructured keys and the `$children` slot are excluded.
+Enumerable (`ownKeys`/`for…in`/`Object.keys`), so `{...rest}` can forward the
+remaining props onto a child or a native element. Key membership is live, but a
+consumer that captures the key SET (a `{...rest}` spread) snapshots it at that point.
+*/
+// @documentation plumbing
+export function restProps(props: UiProps, consumed: string[]): Record<string, unknown> {
+    const skip = new Set([...consumed, '$children'])
+    const bag = props as Record<string, unknown>
+    const visible = (key: string | symbol): key is string =>
+        typeof key === 'string' && !skip.has(key) && key in bag
+    const read = (key: string): unknown =>
+        typeof bag[key] === 'function' ? (bag[key] as () => unknown)() : bag[key]
+    return new Proxy(
+        {},
+        {
+            get: (_target, key) => (visible(key) ? read(key) : undefined),
+            has: (_target, key) => visible(key),
+            ownKeys: () => Reflect.ownKeys(bag).filter(visible),
+            getOwnPropertyDescriptor: (_target, key) =>
+                visible(key) ? { enumerable: true, configurable: true } : undefined,
+        },
+    )
+}

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

@@ -0,0 +1,34 @@
+import { attr } from './attr.ts'
+import { on } from './on.ts'
+
+/*
+Spreads an object's keys onto a native element — the `<div {...rest}>` runtime. `source`
+is a thunk over the spread expression; its keys are enumerated ONCE (so the attribute set
+is fixed at build, not reactively added/removed), but each value stays live: an `on<event>`
+key holding a function attaches as that event listener (mirroring `onclick={…}` on an
+element), and every other key binds as a reactive attribute (`attr`, re-reading the source
+per change, with the same present/absent semantics — `false`/`null`/`undefined` removes it,
+`true` sets it bare). A function under a non-`on` key is skipped (no attribute for it). A key
+in `exclude` is skipped — the element names it explicitly, and an explicit attribute wins
+over a spread key (the same set SSR's `$spread` skips, keeping the two sides congruent).
+*/
+// @documentation plumbing
+export function spreadAttrs(
+    element: Element,
+    source: () => Record<string, unknown>,
+    exclude: string[] = [],
+): void {
+    const skip = new Set(exclude)
+    const object = source()
+    for (const key in object) {
+        if (skip.has(key)) {
+            continue
+        }
+        const value = object[key]
+        if (key.startsWith('on') && typeof value === 'function') {
+            on(element, key.slice(2), value as EventListener)
+        } else if (typeof value !== 'function') {
+            attr(element, key, () => source()[key])
+        }
+    }
+}

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

@@ -0,0 +1,32 @@
+/*
+Wraps a `{...source}` spread layer so every key resolves to a live value thunk —
+the same `() => value` shape an explicit `name={expr}` prop compiles to, so a child
+reads a spread key exactly like an authored one (`$props[key]?.()`). `source` is a
+THUNK over the spread expression (not its value), re-evaluated on each key read and
+membership test, so a reactive source stays live both when its keys mutate and when
+the whole object is replaced — and the read registers as the reader's dependency. A
+nullish source spreads nothing. The reserved `$children` slot key is never surfaced —
+a source happening to carry one must not masquerade as slot content.
+*/
+// @documentation plumbing
+export function spreadProps(
+    source: () => Record<string, unknown> | null | undefined,
+): Record<string, () => unknown> {
+    /* A spread key the merged bag exposes — present on the current source and not the
+       reserved `$children` slot key (a source carrying one must not become slot content). */
+    const carries = (key: string | symbol): boolean =>
+        key !== '$children' && key in (source() ?? {})
+    return new Proxy(
+        {},
+        {
+            /* Each read returns a fresh thunk that re-evaluates the source for the key. */
+            get: (_target, key) => () => source()?.[key as string],
+            /* Live membership: whether the current source object carries the key. */
+            has: (_target, key) => carries(key),
+            /* Enumerable over the current source, so a merged bag reports spread keys. */
+            ownKeys: () => Reflect.ownKeys(source() ?? {}).filter(carries),
+            getOwnPropertyDescriptor: (_target, key) =>
+                carries(key) ? { enumerable: true, configurable: true } : undefined,
+        },
+    ) as Record<string, () => unknown>
+}