@abide/abide 0.38.0 → 0.39.0

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

@@ -1,3 +1,5 @@
+import type { RpcOptions } from './RpcOptions.ts'
+
 /*
 Call signature shared by RemoteFunction and RawRemoteFunction. The base
 signature keeps `args` required so a schema'd verb can't silently drop its
@@ -6,7 +8,14 @@ optional-arg signature lets call sites write `fn()` instead of
 `fn(undefined)`. Intersection rather than a bare conditional so the type
 stays callable while `Args` is still generic (cache() invokes producers
 before `Args` resolves). FormData is the multipart upload escape hatch —
-see RemoteFunction.
+see RemoteFunction. The optional trailing `opts` carries per-call transport
+options (signal/keepalive/priority/cache/headers); the server ignores them,
+so the callable stays isomorphic.
 */
-export type RemoteCallable<Args, Resolved> = ((args: Args | FormData) => Promise<Resolved>) &
-    (undefined extends Args ? (args?: Args | FormData) => Promise<Resolved> : unknown)
+export type RemoteCallable<Args, Resolved> = ((
+    args: Args | FormData,
+    opts?: RpcOptions,
+) => Promise<Resolved>) &
+    (undefined extends Args
+        ? (args?: Args | FormData, opts?: RpcOptions) => Promise<Resolved>
+        : unknown)

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

@@ -0,0 +1,22 @@
+/*
+Per-call transport options for a remote function — a curated slice of RequestInit,
+not the whole thing. Only fields the server handler never observes are exposed, so
+the call stays isomorphic (same behaviour both sides) and a caller can't clobber the
+method, body, or framework headers the RPC contract owns.
+
+- `signal` merges with the scope abort + client timeout (AbortSignal.any), never
+  replacing them; under cache() it's ignored so one reader can't abort a coalesced
+  flight the others share.
+- `keepalive` lets a small fire-and-forget write survive page unload (the browser
+  caps the total keepalive body at ~64KB).
+- `priority` is a fetch scheduling hint; ignored where unsupported.
+- `cache` is the browser HTTP cache mode (distinct from abide's own cache()).
+- `headers` are MERGED onto the framework headers, which win — a caller adds
+  transport metadata (idempotency-key, authorization) but can't overwrite
+  traceparent/content-type/offline. Application data still belongs in `args` (the
+  only schema-validated channel); headers bypass validation.
+*/
+export type RpcOptions = Pick<
+    RequestInit,
+    'signal' | 'keepalive' | 'priority' | 'cache' | 'headers'
+>

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

@@ -0,0 +1,14 @@
+/*
+A source-map JSON object, narrowed to the fields abide reads or writes when
+post-processing emitted maps. `sources` is the list of original files (a null
+entry means an unknown source); `ignoreList` (Source Map v3 / ECMA-426) and its
+legacy Chrome alias `x_google_ignoreList` carry the indices into `sources` a
+debugger should skip. Other standard fields (`version`, `mappings`, …) are passed
+through untouched, so the type stays open.
+*/
+export type SourceMap = {
+    sources?: (string | null)[]
+    ignoreList?: number[]
+    x_google_ignoreList?: number[]
+    [field: string]: unknown
+}

package/src/lib/ui/COMPONENT_WRAPPER_PREFIX.ts

@@ -1,4 +1,5 @@
-/* The tag prefix every component instance mounts into (`abide-<name>`). One source
-   for the compiler (componentWrapperTag) and the runtime opacity checks (skeleton,
-   scopeLabel) so the wrapper convention can't drift between build and hydrate. */
+/* The `abide-` tag prefix on framework-owned custom elements (the router's
+   `abide-outlet`, the streaming `abide-resolve`/`abide-cache` fragments). `scopeLabel`
+   strips it to read the outlet host's bare name. Child components no longer mount into
+   an `abide-<name>` wrapper — they build as marker ranges (see `mountRange`). */
 export const COMPONENT_WRAPPER_PREFIX = 'abide-'

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

@@ -1,9 +1,12 @@
 /*
-Source text for the `$esc` / `$attr` / `$text` / `$snip` helpers injected into
-every SSR render body. `$esc` escapes the five HTML-significant characters. `$attr`
+Source text for the `$esc` / `$attr` / `$spread` / `$text` / `$snip` helpers injected
+into every SSR render body. `$esc` escapes the five HTML-significant characters. `$attr`
 renders a dynamic `{expr}` attribute with the same present/absent semantics the
 client `attr` binding uses: false/null/undefined drops it, true emits the bare
-attribute, anything else emits `name="escaped"`. `$snip` brands a snippet's
+attribute, anything else emits `name="escaped"`. `$spread` renders a `{...obj}`
+element spread — each key as an attribute via `$attr`, skipping functions (event
+handlers, wired client-side by `spreadAttrs`) and any key in the `skip` list (a key the
+element names explicitly, which wins over the spread) — mirroring that client runtime. `$snip` brands a snippet's
 rendered string. `$text` is what `{expr}` interpolations push: a snippet call's
 value is emitted raw between `<!--abide:snippet-->` markers (the client runs its
 builder there to claim the nodes); a `html\`…\`` value raw between `<!--abide:html-->`
@@ -16,6 +19,13 @@ export const SSR_ESCAPE =
     "({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;', \"'\": '&#39;' })[c]);\n" +
     'const $attr = (n, v) => (v === false || v === null || v === undefined) ? "" ' +
     ': v === true ? (" " + n) : (" " + n + \'="\' + $esc(v) + \'"\');\n' +
+    'const $spread = (o, skip) => { let s = ""; for (const k in o) { ' +
+    'if (skip && skip.indexOf(k) >= 0) continue; ' +
+    /* Skip keys that aren't valid attribute names: $attr emits the name verbatim, so a
+       runtime-controlled key with whitespace/quotes/`>`/`=`/`/` would inject markup. The
+       client's setAttribute throws on these, so dropping them matches that behaviour. */
+    'if (/[\\s"\'>\\/=]/.test(k)) continue; ' +
+    'const v = o[k]; if (typeof v !== "function") s += $attr(k, v); } return s; };\n' +
     "const $RAW = Symbol.for('abide.rawHtml');\n" +
     "const $SNIP = Symbol.for('abide.snippet');\n" +
     'const $snip = (s) => ({ [$SNIP]: s });\n' +

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

@@ -30,7 +30,13 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
     { name: 'tryBlock', specifier: 'ui/dom/tryBlock' },
     { name: 'switchBlock', specifier: 'ui/dom/switchBlock' },
     { name: 'mountSlot', specifier: 'ui/dom/mountSlot' },
+    { name: 'outlet', specifier: 'ui/dom/outlet' },
     { name: 'mountChild', specifier: 'ui/dom/mountChild' },
+    { name: 'mergeProps', specifier: 'ui/dom/mergeProps' },
+    { name: 'spreadProps', specifier: 'ui/dom/spreadProps' },
+    { name: 'restProps', specifier: 'ui/dom/restProps' },
+    { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs' },
+    { name: 'readCall', specifier: 'ui/dom/readCall' },
     { name: 'hydrate', specifier: 'ui/dom/hydrate' },
     { name: 'escapeKey', specifier: 'ui/runtime/escapeKey' },
     { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId' },

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

@@ -8,11 +8,12 @@ structure AND lets BOTH back-ends feed the same tree to `skeletonContext` — on
 for "a layout slot is an outlet, not an anchor", instead of the client running `asOutlet` while
 SSR mirrors it with an inline special-case.
 
-The outlet is a structural mount container, not styled content, so it carries NO attrs and NO
-style scope — keeping it byte-identical to the placeholder `renderChain` folds the child layer
-into (an exact `<abide-outlet></abide-outlet>` string match). Stripping `scopes` is what makes
-the two back-ends agree: the SSR special-case emitted the outlet bare, but the client clone read
-the slot's annotated `scopes` and stamped them — a hydration mismatch for any scoped layout.
+The outlet is a structural mount point, not styled content, so it carries NO attrs and NO style
+scope — both back-ends lower it to the bare `<!--abide:outlet-->`…`<!--/abide:outlet-->` boundary
+`renderChain` folds the child layer into (matching its `OUTLET_PLACEHOLDER`). Stripping `scopes`
+is what makes the two back-ends agree: SSR emits the boundary bare, but without this the client
+clone would read the slot's annotated `scopes` and stamp them — a hydration mismatch for any
+scoped layout.
 
 Control-flow children are fresh build contexts (their own runtime mounts a nested slot), so they
 are not descended into — a `<slot>` inside an `{#if}` stays a slot node, handled at its own

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

@@ -9,7 +9,10 @@ Wraps a component into a complete ES module with two entry points:
 
   - default `component(host, $props)` — mounts the client build, returns the
     disposer (`import Counter from './Counter.abide'; const stop = Counter(host)`);
-  - `render($props)` — server-renders to `{ html, state, awaits }` for SSR.
+  - `render($props, $ctx)` — async, server-renders to `{ html, state, awaits, resume }`
+    for SSR. `$ctx` is the request-local block-id counter, threaded so a child's
+    `await`/`try` ids share the page's depth-first numbering; omitted at the top level
+    (a fresh counter defaults in).
 
 `render` is also attached to the default export (`component.render`) so a parent
 can server-render a child it imported by its default name. Both entry points share
@@ -42,11 +45,13 @@ export function compileModule(
         const id = JSON.stringify(options.moduleId)
         return `const { ${names}, hotReplace } = window.__abide
 ${userImports}
-function component(host, $props) {
-    return mount(host, (host) => {
+function build(host, $props) {
 ${body}
-    })
 }
+function component(host, $props) {
+    return mount(host, build, $props)
+}
+component.build = build
 component.__abideId = ${id}
 if (!hotReplace(${id}, component)) location.reload()
 `
@@ -61,25 +66,27 @@ if (!hotReplace(${id}, component)) location.reload()
        exactly which names it emitted, so it filters here. A name absent from the body
        is unreferenced; erring toward inclusion (a stray match in user script) only
        keeps a harmless unused import, never drops a needed one. */
-    const moduleBody = `export default function component(host, $props) {
-    return mount(host, (host) => {
+    const moduleBody = `function build(host, $props) {
 ${body}
-    })
+}
+
+export default function component(host, $props) {
+    return mount(host, build, $props)
 }
 
 /* Adopt the server-rendered DOM in place instead of rebuilding it. */
 export function hydrateInto(host, $props) {
-    return hydrate(host, (host) => {
-${body}
-    })
+    return hydrate(host, build, $props)
 }
 
-export function render($props) {
+export function render($props, $ctx) {
 ${ssrBody}
 }
 
 component.render = render
 component.hydrate = hydrateInto
+/* The bare build, so a parent can range-mount this as a nested child (no wrapper). */
+component.build = build
 component.hydratable = ${analyzed.hydratable}
 ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(options.moduleId)}\n`}`
     /* Scope each name to the surface that genuinely references it. The SSR body

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

@@ -16,10 +16,24 @@ front-end, then the SSR back-end, and returns `{ html, state, awaits }`:
 Effects are stripped — they are client lifecycle and emit no HTML, so the server
 render is a snapshot of the markup before any effect runs.
 
-Runs with `doc`/`state`/`computed`/`effect`/`nextBlockId`/`enterRenderPass`/
-`exitRenderPass` in scope and defines `model`. The body is bracketed by a render
-pass so the outermost render resets the block-id counter and an inlined child
-render continues it — keeping await/try ids unique and aligned with the client.
+Defines `model` with `doc`/`state`/`computed`/`effect` in scope. The block-id counter is
+the request-local `$ctx` (threaded into child renders), not a module global — a blocking
+`await` block awaits its promise at its structural position and renders inline, so ids
+allocate depth-first like the client; render yields at that `await`, and a shared global
+counter would interleave across concurrent requests. `$ctx` defaults to a fresh counter
+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
+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.
+
+The reactive scope brackets the body; it is entered synchronously before any inline `await`,
+so `const model = scope()` resolves correctly, and `model` is captured for the rest of the
+render (its reads are object-method calls, not scope lookups, so they stay correct across
+the awaits).
 
 `analyzed` is a lazy default: a direct caller (tests) omits it and the front-end
 runs here, but `compileModule` shares one analysis across both back-ends.
@@ -31,15 +45,24 @@ export function compileSSR(
     analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
 ): string {
     const { script, stateNames, derivedNames, computedNames, nodes } = analyzed
+    const lowered = stripEffects(script)
     const ssr = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout)
     /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
        the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The
        elements still carry their `data-a-…` scopes via `generateSSR`. */
     /* `typeof model` guards a component with no reactive state (a pure-async or
        static component declares no `model`); its snapshot is then empty. */
-    return (
-        `enterRenderPass();\nconst $scope = enterScope();\ntry {\n${stripEffects(script)}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\n${ssr}` +
-        `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits };\n` +
-        `} finally { exitScope($scope); exitRenderPass(); }`
-    )
+    const body =
+        `const $scope = enterScope();\ntry {\n${lowered}\n${SSR_ESCAPE}\nconst $out = [];\nconst $awaits = [];\nconst $resume = {};\n${ssr}` +
+        `return { html: $out.join(''), state: (typeof model !== 'undefined' ? model.snapshot() : {}), awaits: $awaits, resume: $resume };\n` +
+        `} finally { exitScope($scope); }`
+    /* An inline `await` — a blocking await block, a child render, a slot read, or a
+       top-level `await` in the author script — forces an async wrapper. Match `await` as a
+       standalone token (operator), so a no-space form (`await(x)`, `await[i]`, `` await`t` ``)
+       is caught where a `.includes('await ')` substring scan would miss it and emit a bare
+       top-level `await` in a non-async function (a SyntaxError). `(?!:)` excludes the
+       `<!--abide:await:N-->` boundary-marker strings; `\b` excludes `$awaits`. A false
+       positive (the token in author text) only costs a needless async wrapper, never a crash. */
+    const needsAsync = /\bawait\b(?!:)/.test(`${lowered}${ssr}`)
+    return `var $ctx = $ctx || { next: 0 };\n${needsAsync ? `return (async () => {\n${body}\n})();` : body}`
 }

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

@@ -357,9 +357,17 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                    unterminated (a script ending in a call with no trailing semicolon,
                    e.g. `effect(() => …)`) merges across the newline into `effect(…)(…)`
                    — a spurious "not callable" on the author's last statement. */
-                builder.raw(
-                    `;((__prop: Parameters<typeof ${node.name}>[0][${JSON.stringify(prop.name)}]) => {})(`,
-                )
+                if (prop.spread) {
+                    /* A `{...expr}` spread contributes a SUBSET of the props (required ones
+                       may come from another spread/explicit prop), so check it against
+                       `Partial<Props>` — every key it does carry must match the child's
+                       declared type, without demanding completeness. */
+                    builder.raw(`;((__spread: Partial<Parameters<typeof ${node.name}>[0]>) => {})(`)
+                } else {
+                    builder.raw(
+                        `;((__prop: Parameters<typeof ${node.name}>[0][${JSON.stringify(prop.name)}]) => {})(`,
+                    )
+                }
                 builder.expr(prop.code, prop.loc)
                 builder.raw(');\n')
             }

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

@@ -0,0 +1,53 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The authored props of a child-component node (each attribute lowered to a prop;
+   a `spread` entry carries no `name`). */
+type ComponentProps = Extract<TemplateNode, { kind: 'component' }>['props']
+
+/*
+The props-bag source expression a child mount/render receives, shared by the build
+and SSR back-ends so their last-wins layering stays byte-identical — the invariant
+SSR/client prop congruence rests on. No spread → the plain object literal of named
+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
+undefined when the component has no slotted children.
+*/
+export function composeProps(
+    props: ComponentProps,
+    lowerExpression: (code: string) => string,
+    slotPart: string | undefined,
+): string {
+    const propThunk = (prop: { name: string; code: string }): string =>
+        `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`
+    if (!props.some((prop) => prop.spread)) {
+        const parts = props.map(propThunk)
+        if (slotPart !== undefined) {
+            parts.push(slotPart)
+        }
+        return `{ ${parts.join(', ')} }`
+    }
+    const layers: string[] = []
+    let run: string[] = []
+    const flushRun = (): void => {
+        if (run.length > 0) {
+            layers.push(`{ ${run.join(', ')} }`)
+            run = []
+        }
+    }
+    for (const prop of props) {
+        if (prop.spread) {
+            flushRun()
+            layers.push(`spreadProps(() => (${lowerExpression(prop.code)}))`)
+        } else {
+            run.push(propThunk(prop))
+        }
+    }
+    flushRun()
+    if (slotPart !== undefined) {
+        layers.push(`{ ${slotPart} }`)
+    }
+    return `mergeProps([${layers.join(', ')}])`
+}

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

@@ -60,6 +60,9 @@ export function desugarSignals(scriptBody: string): {
     const stateNames = new Set<string>()
     const derivedNames = new Set<string>()
     const computedNames = new Set<string>()
+    /* A `props()` destructure must be lowered even when it declares no reactive binding
+       (a rest-only `const { ...rest } = props()`), so track its presence on its own. */
+    let hasPropsDestructure = false
     for (const statement of source.statements) {
         if (!ts.isVariableStatement(statement)) {
             continue
@@ -67,14 +70,16 @@ export function desugarSignals(scriptBody: string): {
         for (const declaration of statement.declarationList.declarations) {
             const callee = signalCallee(declaration)
             if (callee === 'props') {
-                /* `const {…} = props()` — each destructured binding is a read-only
-                   computed over the parent thunk, read as `name()`. */
+                /* `const {…, ...rest} = props()` — each named binding is a read-only computed
+                   over the parent thunk (read as `name()`); a `...rest` binding stays a plain
+                   const (a `restProps` bag), so it joins no reactive set. */
                 if (!ts.isObjectBindingPattern(declaration.name)) {
                     throw new Error(
                         'abide: `props()` must be destructured — `const { a, b } = props()`',
                     )
                 }
-                for (const binding of propsBindings(declaration)) {
+                hasPropsDestructure = true
+                for (const binding of propsDestructure(declaration).bindings) {
                     computedNames.add(binding.local)
                 }
                 continue
@@ -98,7 +103,12 @@ export function desugarSignals(scriptBody: string): {
             }
         }
     }
-    if (stateNames.size === 0 && derivedNames.size === 0 && computedNames.size === 0) {
+    if (
+        stateNames.size === 0 &&
+        derivedNames.size === 0 &&
+        computedNames.size === 0 &&
+        !hasPropsDestructure
+    ) {
         return { code: scriptBody, stateNames, derivedNames, computedNames }
     }
 
@@ -249,23 +259,34 @@ function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
    the optional `= default` expression (the fallback when the prop is absent). */
 type PropsBinding = { local: string; key: string; initializer: ts.Expression | undefined }
 
-/* The bindings of a `const {…} = props()` pattern. Rest (`...rest`) and nested
-   destructuring have no single prop key, so they throw a legible compile error. */
-function propsBindings(declaration: ts.VariableDeclaration): PropsBinding[] {
+/* The destructure of a `const {…, ...rest} = props()` pattern — its named bindings
+   plus an optional rest binding (the unconsumed props, gathered by `restProps`).
+   Nested destructuring has no single prop key, so it throws a legible compile error. */
+function propsDestructure(declaration: ts.VariableDeclaration): {
+    bindings: PropsBinding[]
+    rest: string | undefined
+} {
     const pattern = declaration.name as ts.ObjectBindingPattern
-    return pattern.elements.map((element) => {
+    const bindings: PropsBinding[] = []
+    let rest: string | undefined
+    for (const element of pattern.elements) {
         if (element.dotDotDotToken !== undefined) {
-            throw new Error('abide: `...rest` in `props()` destructuring is not supported')
+            if (!ts.isIdentifier(element.name)) {
+                throw new Error('abide: `...rest` in `props()` must bind a plain name')
+            }
+            rest = element.name.text
+            continue
         }
         if (!ts.isIdentifier(element.name)) {
             throw new Error('abide: nested destructuring in `props()` is not supported')
         }
-        return {
+        bindings.push({
             local: element.name.text,
             key: propsBindingKey(element),
             initializer: element.initializer,
-        }
-    })
+        })
+    }
+    return { bindings, rest }
 }
 
 /* The parent prop key a binding element reads — its rename source (`name: alias` →
@@ -285,10 +306,11 @@ function propsBindingKey(element: ts.BindingElement): string {
     throw new Error('abide: computed prop keys in `props()` destructuring are not supported')
 }
 
-/* If `statement` is a `const {…} = props()` destructure, returns one reactive
-   computed per binding — `scope().derive("name", () => $props["key"]?.() ?? default)`
-   — read as `name()`; otherwise undefined. The `?? default` applies the binding's
-   `= default` fallback when the prop is absent. */
+/* If `statement` is a `const {…, ...rest} = props()` destructure, returns one reactive
+   computed per named binding — `scope().derive("name", () => $props["key"]?.() ?? default)`,
+   read as `name()` — plus a `const rest = restProps($props, [consumed])` line for a rest
+   binding; otherwise undefined. The `?? default` applies the binding's `= default` fallback
+   when the prop is absent. */
 function propsDestructureLines(
     statement: ts.Statement,
     printer: ts.Printer,
@@ -302,7 +324,8 @@ function propsDestructureLines(
         if (signalCallee(declaration) !== 'props' || !ts.isObjectBindingPattern(declaration.name)) {
             return undefined
         }
-        for (const { local, key, initializer } of propsBindings(declaration)) {
+        const { bindings, rest } = propsDestructure(declaration)
+        for (const { local, key, initializer } of bindings) {
             const fallback =
                 initializer === undefined
                     ? ''
@@ -311,6 +334,11 @@ function propsDestructureLines(
                 `const ${local} = scope().derive(${JSON.stringify(local)}, () => $props[${JSON.stringify(key)}]?.()${fallback})`,
             )
         }
+        /* The rest bag gathers every prop not named above (and not `$children`). */
+        if (rest !== undefined) {
+            const consumed = bindings.map((binding) => binding.key)
+            lines.push(`const ${rest} = restProps($props, ${JSON.stringify(consumed)})`)
+        }
     }
     return lines
 }