@abide/abide 0.42.0 → 0.43.1

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

@@ -2,12 +2,14 @@ import ts from 'typescript'
 import { TS_PRINTER } from './TS_PRINTER.ts'
 
 /*
-Removes `effect(...)` calls from a script for the SSR back-end. Effects are client
+Removes effect calls from a script for the SSR back-end. Effects are client
 lifecycle — they touch the DOM / run side effects and emit no HTML, so the server
 render (a snapshot of the pre-effect markup, like every framework) must not run
-them. Every `effect(<args>)` call is replaced by `undefined`, dropping its body:
-an `effect(() => …)` statement becomes a no-op, and a `const stop = effect(…)`
-binding keeps a defined (unused) name. Client compilation keeps effects untouched.
+them. Both surfaces are stripped: the generated/runtime bare `effect(<args>)` and
+the authored scope form `scope().effect(<args>)` (and a captured/destructured handle
+`c.effect(<args>)`), each replaced by `undefined` — an `effect(() => …)` statement
+becomes a no-op, and a `const stop = effect(…)` binding keeps a defined (unused) name.
+Client compilation keeps effects untouched.
 */
 export function stripEffects(code: string): string {
     const source = ts.createSourceFile('script.ts', code, ts.ScriptTarget.Latest, true)
@@ -23,11 +25,7 @@ export function stripEffects(code: string): string {
 export function stripEffectsTransformer(): ts.TransformerFactory<ts.SourceFile> {
     return (context) => (root) => {
         const visit = (node: ts.Node): ts.Node => {
-            if (
-                ts.isCallExpression(node) &&
-                ts.isIdentifier(node.expression) &&
-                node.expression.text === 'effect'
-            ) {
+            if (ts.isCallExpression(node) && isEffectCallee(node.expression)) {
                 return ts.factory.createIdentifier('undefined')
             }
             return ts.visitEachChild(node, visit, context)
@@ -35,3 +33,13 @@ export function stripEffectsTransformer(): ts.TransformerFactory<ts.SourceFile>
         return ts.visitNode(root, visit) as ts.SourceFile
     }
 }
+
+/* An effect callee: the bare runtime helper (`effect`) or the scope-method form
+   (`scope().effect`, `c.effect`) the author writes. Receiver-agnostic on the `.effect`
+   member name, matching `effect` being reserved as a scope primitive. */
+function isEffectCallee(expression: ts.Expression): boolean {
+    if (ts.isIdentifier(expression)) {
+        return expression.text === 'effect'
+    }
+    return ts.isPropertyAccessExpression(expression) && expression.name.text === 'effect'
+}

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

@@ -0,0 +1,22 @@
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+type Case = Extract<TemplateNode, { kind: 'case' }>
+
+/* The structural shape of a `switch`, resolved once so the build and SSR back-ends share one
+   reading of its cases and only own emission. Both previously recomputed the `case` filter;
+   SSR additionally located the match-less default. */
+export type SwitchPlan = {
+    /* The `case` branches in source order (`match` set; the default leaves it unset). */
+    cases: Case[]
+    /* The match-less default branch, if present. */
+    fallback: Case | undefined
+}
+
+/* Resolves a `switch` node's cases into the shared structural plan. */
+export function switchPlan(node: Extract<TemplateNode, { kind: 'switch' }>): SwitchPlan {
+    const cases = node.children.filter((child): child is Case => child.kind === 'case')
+    return {
+        cases,
+        fallback: cases.find((branch) => branch.match === undefined),
+    }
+}

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

@@ -0,0 +1,29 @@
+import { resolveBranches } from './resolveBranches.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The structural shape of a `try` error boundary, resolved once so the build and SSR
+   back-ends share one reading and only own emission. Both previously recomputed branch
+   resolution, the `finallyChildren` default, the guarded (children-minus-branch) split, and
+   the catch binding / presence. */
+export type TryPlan = {
+    /* The guarded content — every child except the `catch`/`finally` branch nodes. */
+    guarded: TemplateNode[]
+    /* The catch content + its bound name (`_error` default); empty when no catch branch. */
+    catchChildren: TemplateNode[]
+    catchAs: string
+    finallyChildren: TemplateNode[]
+    /* No catch → a throw propagates to the enclosing boundary (re-throw / `undefined` thunk). */
+    hasCatch: boolean
+}
+
+/* Resolves a `try` node's branches into the shared structural plan. */
+export function tryPlan(node: Extract<TemplateNode, { kind: 'try' }>): TryPlan {
+    const [catchBranch, finallyBranch] = resolveBranches(node, 'catch', 'finally')
+    return {
+        guarded: node.children.filter((child) => child.kind !== 'branch'),
+        catchChildren: catchBranch?.children ?? [],
+        catchAs: catchBranch?.as ?? '_error',
+        finallyChildren: finallyBranch?.children ?? [],
+        hasCatch: catchBranch !== undefined,
+    }
+}

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

@@ -13,9 +13,15 @@ absolute offset of `code` in the original `.abide` source (see TextPart) —
 optional, set only when the parser tracks positions for the type-checking shadow.
 */
 export type TemplateAttr =
-    | { kind: 'static'; name: string; value: string; bare?: true }
-    | { kind: 'expression'; name: string; code: string; loc?: number }
+    | { kind: 'static'; name: string; value: string; bare?: true; nameLoc?: number }
+    | { kind: 'expression'; name: string; code: string; loc?: number; nameLoc?: number }
     | { kind: 'event'; event: string; code: string; loc?: number }
     | { kind: 'bind'; property: string; code: string; loc?: number }
+    /* `class:<name>={code}` — toggles the class on/off by `code`'s truthiness, written
+       surgically (classList.toggle) without re-rendering the element. */
+    | { kind: 'class'; name: string; code: string; loc?: number }
+    /* `style:<property>={code}` — writes one inline style/custom property (style.setProperty)
+       reactively, again without a re-render. `property` may be a CSS custom prop (`--pct`). */
+    | { kind: 'style'; 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

@@ -72,9 +72,13 @@ export type TemplateNode =
     | {
           kind: 'component'
           name: string
+          /* Source offset of the tag name — the anchor for a whole-mount diagnostic
+             (a missing required prop, which has no supplied expression to point at). */
+          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 }[]
+             `name`; its keys merge in at runtime (`mergeProps`/`spreadProps`). `nameLoc` is
+             the prop name's source offset — the anchor for an excess-prop diagnostic. */
+          props: { name: string; code: string; loc?: number; nameLoc?: number; spread?: boolean }[]
           children: TemplateNode[]
       }
     | { kind: 'switch'; subject: string; children: TemplateNode[]; loc?: number }

package/src/lib/ui/createScope.ts

@@ -1,4 +1,5 @@
 import { computed } from './computed.ts'
+import { effect } from './effect.ts'
 import { history } from './history.ts'
 import { linked } from './linked.ts'
 import { persist as persistDoc } from './persist.ts'
@@ -37,6 +38,10 @@ export function createScope(
     const data = (): Doc => (document ??= createDoc({}))
     const id = parent === undefined ? `scope-${nextId++}` : `${parent.id}.${nextId++}`
     const children: Scope[] = []
+    /* Adopted build teardowns (the reactivity stopper from the mount core). Disposed
+       first and in reverse on teardown, before children and capabilities — so the one
+       `dispose` runs the order the call sites hand-composed as `stop(); lexical.dispose()`. */
+    const owned: Array<() => void> = []
     /* 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>()
@@ -56,11 +61,17 @@ export function createScope(
         cell: (path) => data().cell(path),
         derive: (path, compute) => data().derive(path, compute),
         snapshot: () => data().snapshot(),
-        /* The `.value`-cell signal forms, namespaced under the scope — standalone
-           non-serializing cells (owned by the render scope), reached only here. */
+        /* The reactive primitives — namespaced under the scope but AMBIENT-bound, not
+           receiver-bound: each binds whatever scope is rendering and the finest ambient
+           build window (branch/row), so the handle is namespacing, not a binding target.
+           Binding to the receiver would leak branch-local cells (see ADR-0012). */
         state,
         linked,
         computed,
+        effect,
+        own: (dispose) => {
+            owned.push(dispose)
+        },
         child: (childInitial = {}) => {
             const created = createScope(childInitial, self)
             children.push(created)
@@ -91,6 +102,13 @@ export function createScope(
         canUndo: () => past?.canUndo() ?? false,
         canRedo: () => past?.canRedo() ?? false,
         dispose: () => {
+            /* Stop the build's reactivity first (reverse order), before tearing down nested
+               children and the boundary-crossing capabilities — the order the call sites
+               hand-composed as `stop(); lexical.dispose()`. */
+            for (let index = owned.length - 1; index >= 0; index -= 1) {
+                owned[index]?.()
+            }
+            owned.length = 0
             for (const created of children) {
                 created.dispose()
             }

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

@@ -3,18 +3,14 @@ import { clearBetween } from './clearBetween.ts'
 
 /*
 The standard teardown for a marker-bounded range (component, layout/page boundary,
-slot): stop the content's reactivity, dispose its lexical scope, and clear the nodes
-between the markers — leaving the markers in place so a hot swap rebuilds the range.
-Shared by every range mount (`fillRange`, `mountRange`, `fillBoundary`) so the one
-disposer contract lives in a single place.
+slot): dispose its lexical scope (which stops the content's reactivity first, then its
+nested children and capabilities), and clear the nodes between the markers — leaving the
+markers in place so a hot swap rebuilds the range. Shared by every range mount
+(`fillRange`, `mountRange`, `fillBoundary`) so the one disposer contract lives in a
+single place.
 */
-export function disposeRange(
-    scoped: { stop: () => void; lexical: Scope },
-    start: Comment,
-    end: Comment,
-): () => void {
+export function disposeRange(scoped: { lexical: Scope }, start: Comment, end: Comment): () => void {
     return () => {
-        scoped.stop()
         scoped.lexical.dispose()
         clearBetween(start, end)
     }

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

@@ -29,11 +29,8 @@ export function hydrate(
     try {
         /* Same shared mount core as `mount` (see `withScope`) — a hydrated component owns a
            scope too, adopting the model its build adopts — run with the claim cursor active. */
-        const { stop, lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
-        return () => {
-            stop()
-            lexical.dispose()
-        }
+        const { lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
+        return () => lexical.dispose()
     } finally {
         RENDER.hydration = previous
     }

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

@@ -23,9 +23,8 @@ export function mount(
     /* Establish this component's lexical scope (nested, `awaiting` so it adopts the model
        doc the build's first `doc()` creates) and render pass, run the build under it, and
        restore the previous scope — the shared mount core (see `withScope`). */
-    const { stop, lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
+    const { lexical } = withScope(scopeLabel(host), () => scope(() => build(host, props)))
     return () => {
-        stop()
         lexical.dispose()
         host.textContent = ''
     }

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

@@ -11,23 +11,20 @@ under the current one in `awaiting` mode — so it adopts the model doc its firs
 creates — brackets a render pass — so its `await`/`try` block ids draw from the shared
 counter in SSR-stream order — runs `build`, then restores the previous scope (synchronous
 build, so the restore is exact). `build` returns its reactivity stopper (from `scope` or
-`fillBefore`); the caller composes its own DOM teardown (clear host vs clear range) around
-the returned `stop`/`lexical`, keeping the one scope/render-pass contract in a single place.
+`fillBefore`), which the lexical scope ADOPTS (`own`) so the scope has a single teardown:
+the caller wraps its own DOM teardown (clear host vs clear range) around one
+`lexical.dispose()`, no longer composing a separate `stop()` at every site.
 */
-export function withScope(
-    label: string | undefined,
-    build: () => () => void,
-): { stop: () => void; lexical: Scope } {
+export function withScope(label: string | undefined, build: () => () => void): { lexical: Scope } {
     const parentScope = CURRENT_SCOPE.current
     const lexical = createScope({}, parentScope, true, label)
     enterRenderPass()
     CURRENT_SCOPE.current = lexical
-    let stop: () => void = () => undefined
     try {
-        stop = build()
+        lexical.own(build())
     } finally {
         exitRenderPass()
         CURRENT_SCOPE.current = parentScope
     }
-    return { stop, lexical }
+    return { lexical }
 }

package/src/lib/ui/effect.ts

@@ -10,9 +10,11 @@ dispose — and may be async (its teardown then runs once the promise settles, b
 only the reads before its first `await` are tracked). Returns a dispose that runs
 the final teardown and detaches it from the graph. This is abide's from-scratch
 effect primitive: the open-on-first-read / close-on-last-reader lifecycle,
-grounded in abide's own reactive core.
+grounded in abide's own reactive core. Authored as `scope().effect(...)` (the bare
+name is reserved); this module export stays for the generated binding code that
+calls it directly (and for the SSR strip), so it carries no standalone demo.
 */
-// @documentation effect
+// @documentation plumbing
 export function effect(fn: () => EffectResult): () => void {
     /* Re-runs fire after the build, so pin the scope this effect was created under
        (the dep-tracking observer is managed separately, so this can't disturb it). */

package/src/lib/ui/navigate.ts

@@ -1,3 +1,6 @@
+import { parseRouteSegments } from '../shared/parseRouteSegments.ts'
+import type { PageRoutes, PathParams } from '../shared/url.ts'
+import { url } from '../shared/url.ts'
 import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 
@@ -8,21 +11,19 @@ export type NavigateOptions = {
     keepScroll?: boolean
 }
 
-/* Navigates to `path`: writes a history entry (when available) and updates the
-   reactive route, which re-mounts the matching page via `router`. `replace` swaps
-   the current entry instead of pushing — used when honouring a server redirect, so
-   the blocked URL isn't left behind in history. Each entry carries a monotonic
-   `abideEntry` id so the router can bucket/restore its scroll offset across the page
-   teardown the rebuild does. A push leaves the current entry behind — its scroll is
-   bucketed so back restores it — and mints a fresh id. A replace destroys the current
-   entry and lands fresh content (a redirect), so its saved scroll no longer applies:
+/* Writes an ALREADY-RESOLVED path into history + the reactive route. The router uses this
+   for paths it built from a real URL (a clicked link, a popstate, a server redirect) — they
+   already carry the mount base, so they must NOT pass through `url()` again. Each entry
+   carries a monotonic `abideEntry` id so the router can bucket/restore its scroll offset
+   across the page teardown the rebuild does. A push leaves the current entry behind — its
+   scroll is bucketed so back restores it — and mints a fresh id. A replace destroys the
+   current entry and lands fresh content (a redirect), so its saved scroll no longer applies:
    the bucket is discarded and the id kept, so the new page restores to top/anchor.
    `keepScroll` opts the destination out of that reset — for an in-page URL swap (e.g.
-   selecting another episode on the same detail page) where a top jump is jarring: the
-   live offset is bucketed under the destination entry id, so the post-rebuild `restore`
-   reapplies it instead of scrolling to top. */
-// @documentation navigate
-export function navigate(
+   selecting another episode on the same detail page) where a top jump is jarring: the live
+   offset is bucketed under the destination entry id, so the post-rebuild `restore` reapplies
+   it instead of scrolling to top. */
+export function navigatePath(
     path: string,
     { replace = false, keepScroll = false }: NavigateOptions = {},
 ): void {
@@ -48,3 +49,29 @@ export function navigate(
     }
     runtimePath.value = path
 }
+
+/* Navigates to a typed in-app path: a route literal with `[name]` segments takes its params
+   first (`navigate('/p/[id]', { id })`), then options; a paramless or already-interpolated
+   path takes options directly (`navigate('/p', { replace })`). The path is built through
+   `url()` — base-correct, params interpolated — exactly as a link href would be, so a
+   dynamic `/p/${x}` falls through url()'s paramless branch and is base-prefixed too. */
+// @documentation navigate
+export function navigate<P extends keyof PageRoutes | (string & {})>(
+    path: P,
+    ...rest: keyof PathParams<P> extends never
+        ? [options?: NavigateOptions]
+        : [params: PathParams<P>, options?: NavigateOptions]
+): void {
+    /* A path declaring `[name]` segments takes params first, options second — mirroring
+       url()'s own arg discrimination; otherwise the first arg is options. */
+    const hasParams = parseRouteSegments(path).some((segment) => segment.kind === 'param')
+    const [first, second] = rest as [unknown, NavigateOptions?]
+    /* Params ride url()'s first vararg slot — a path with `[name]` segments interpolates
+       them, a paramless one ignores undefined and just base-prefixes. Widen `path` to
+       string so url() takes its plain-path overload; its runtime keys off the segments. */
+    const params = hasParams
+        ? (first as Record<string, string | number | boolean | undefined>)
+        : undefined
+    const options = (hasParams ? second : (first as NavigateOptions | undefined)) ?? {}
+    navigatePath(url(path as string, params), options)
+}

package/src/lib/ui/outbox.ts

@@ -1,115 +1,35 @@
-import { online as systemOnline } from '../shared/online.ts'
-import { effect } from './effect.ts'
-import { persist } from './persist.ts'
-import { createDoc as doc } from './runtime/createDoc.ts'
-import type { Outbox } from './types/Outbox.ts'
-import type { PersistenceStore } from './types/PersistenceStore.ts'
+import type { OutboxEntry } from '../shared/types/OutboxEntry.ts'
+import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import { outboxRegistry } from './rpcOutbox/outboxRegistry.ts'
 
-/* One queued mutation: a stable id plus the serializable payload to replay. */
-type OutboxEntry<T> = { id: string; payload: T }
+/* One entry in the global outbox, tagged with the RPC it belongs to. */
+export type GlobalOutboxEntry = OutboxEntry<unknown> & { rpc: RemoteFunction<unknown, unknown> }
+
+/* The global outbox: callable for the flat entry list, awaitable `retry()` to drain every
+   queue (resolves when every replay settles). */
+export type GlobalOutbox = (() => GlobalOutboxEntry[]) & { retry: () => Promise<void> }
+
+function list(): GlobalOutboxEntry[] {
+    return outboxRegistry.all().flatMap(({ rpc, queue }) =>
+        queue.entries().map((entry) => ({
+            ...entry,
+            rpc: rpc as RemoteFunction<unknown, unknown>,
+        })),
+    )
+}
 
 /*
-A durable, FIFO mutation queue for local-first writes. Built on `doc` + `persist`,
-so the queue IS a persisted document — it survives a reload with no extra
-machinery — and on the patch bus the same as everything else. `enqueue` appends a
-payload and tries to drain; the drain sends entries head-first while `online()`
-holds:
-  - success → dequeue and continue;
-  - rejected while now offline → keep the head, retry when connectivity returns
-    (the effect below re-drains on the online edge);
-  - rejected while still online → a real server/validation failure: drop the entry
-    so the queue can't wedge, and report it via `onDrop` so the caller can roll back
-    the optimistic change it applied (e.g. `history().undo()` or a `cache.patch`).
-Delivery is at-least-once (a crash between a successful send and its dequeue
-re-sends on reload), so `send` should be idempotent. Reconnect RESYNC of reads is
-`cache.on`'s job, not this. Client-intended: `send` performs a network mutation.
+The global, reactive view of every durable RPC's outbox — a flat list of undelivered
+entries across all `outbox` rpcs, each tagged with its `rpc`. Reactive: reading it in a
+template/effect subscribes to each registered queue, so it updates as writes park, drain,
+fail, or cancel. Use it for an app-wide "N unsynced" badge or a sync panel; cancel a
+pending write through `entry.controller.abort()`, retry one through `entry.retry()`, or
+drain everything through `outbox.retry()`. A single rpc's slice is `rpc.outbox`. Server-
+side there are no client queues, so it returns an empty list.
 */
 // @documentation ui
-export function outbox<T>({
-    key,
-    send,
-    store,
-    online = systemOnline,
-    onDrop,
-}: {
-    key: string
-    send: (payload: T) => Promise<void>
-    store?: PersistenceStore
-    online?: () => boolean
-    onDrop?: (payload: T, error: unknown) => void
-}): Outbox<T> {
-    const queue = doc({ items: [] as OutboxEntry<T>[] })
-    /* `debounce: 0` because the queue writes itself synchronously below — a queued
-       mutation must be durable the instant it's recorded, not after a debounce
-       window where a crash could lose it. */
-    const persistence = persist(queue, key, { store, debounce: 0 })
-    /* Drop the head and make the dequeue durable at once, so a reload never re-sends
-       an entry already acknowledged. */
-    const dequeue = (): void => {
-        queue.remove('items/0')
-        persistence.flush()
-    }
-
-    /* At most one drain runs at a time; `settled` lets a caller await the active one.
-       A drain re-reads the queue each step, so entries enqueued mid-drain are picked
-       up by the running loop. An empty drain finishes synchronously (it hits no
-       `await`), so `draining` is back to false before the next `enqueue` — there is no
-       resolved-but-still-flagged window for a new entry to fall into. */
-    let draining = false
-    let settled: Promise<void> = Promise.resolve()
-    const flush = (): Promise<void> => {
-        if (draining) {
-            return settled
-        }
-        draining = true
-        settled = (async () => {
-            try {
-                while (online()) {
-                    const { items } = queue.snapshot() as { items: OutboxEntry<T>[] }
-                    const head = items[0]
-                    if (head === undefined) {
-                        break
-                    }
-                    try {
-                        await send(head.payload)
-                    } catch (error) {
-                        /* Went offline mid-send → keep the head, retry on reconnect. */
-                        if (!online()) {
-                            break
-                        }
-                        /* Online but rejected → permanent: drop it, report for rollback. */
-                        dequeue()
-                        onDrop?.(head.payload, error)
-                        continue
-                    }
-                    dequeue()
-                }
-            } finally {
-                draining = false
-            }
-        })()
-        return settled
-    }
-
-    /* Re-drain whenever connectivity returns — reading `online()` subscribes this
-       effect, so the offline→online edge fires it. */
-    const stop = effect(() => {
-        if (online()) {
-            void flush()
-        }
-    })
-
-    return {
-        enqueue: (payload: T) => {
-            queue.add('items/-', { id: crypto.randomUUID(), payload })
-            persistence.flush() // durable before we attempt the network
-            void flush()
-        },
-        pending: () => (queue.read('items') as OutboxEntry<T>[]).map((entry) => entry.payload),
-        flush,
-        dispose: () => {
-            stop()
-            persistence.dispose()
-        },
-    }
-}
+export const outbox: GlobalOutbox = Object.assign(list, {
+    async retry(): Promise<void> {
+        await Promise.all(outboxRegistry.all().map(({ queue }) => queue.retry()))
+    },
+})