@abide/abide 0.28.0

package/src/lib/ui/runtime/types/RouteLoader.ts

@@ -0,0 +1,7 @@
+import type { Route } from './Route.ts'
+
+/* A code-split page entry: imports the page chunk on demand, yielding its default
+   Route. The router resolves a loader on first match and caches the result, so
+   each page's chunk downloads only when its route is first visited — not all of
+   them up front at boot. Mirrors the `_virtual/pages` manifest shape. */
+export type RouteLoader = () => Promise<{ default: Route }>

package/src/lib/ui/runtime/types/SsrRender.ts

@@ -0,0 +1,22 @@
+/* One pending await block captured during SSR: its boundary id, the promise to
+   await, and the string-renderers for the resolved value / error. `blocking` (a
+   `then` on the `await` tag) makes `renderToStream` settle it BEFORE the first flush,
+   splicing the resolved branch into its empty boundary; absent → streamed after.
+   `catch` is absent when the block has no catch branch — a rejection then surfaces
+   to the stream/error path instead of rendering an empty branch. */
+export type SsrAwait = {
+    id: number
+    blocking?: boolean
+    promise: () => unknown
+    then: (value: unknown) => string
+    catch?: (error: unknown) => string
+}
+
+/* The result of a component's server `render()`: the pending-shell HTML, the
+   serializable document snapshot for client resume, and the await blocks to
+   stream. */
+export type SsrRender = {
+    html: string
+    state: unknown
+    awaits: SsrAwait[]
+}

package/src/lib/ui/runtime/types/State.ts

@@ -0,0 +1,3 @@
+/* A writable reactive cell. Reading `.value` subscribes the running observer;
+   assigning it notifies subscribers (an `Object.is`-equal write is a no-op). */
+export type State<T> = { value: T }

package/src/lib/ui/runtime/types/Teardown.ts

@@ -0,0 +1,5 @@
+/*
+The cleanup an effect or attachment body may return. Optionally async — abide runs
+it but never awaits it, so teardown never blocks the reactive flush.
+*/
+export type Teardown = () => void | Promise<void>

package/src/lib/ui/runtime/types/UiComponent.ts

@@ -0,0 +1,16 @@
+import type { SsrRender } from './SsrRender.ts'
+import type { UiProps } from './UiProps.ts'
+
+/*
+A compiled abide-ui component's default export: the client mounter, plus `render`
+for SSR and the hydration hooks. This is the shape `compileModule` emits and the
+page/route registries carry — abide-ui's compiled-component shape.
+*/
+export type UiComponent = ((host: Element, props?: UiProps) => () => void) & {
+    render: (props?: UiProps) => SsrRender
+    hydrate?: (host: Element, props?: UiProps) => () => void
+    hydratable?: boolean
+    /* Stable module id (project-relative source path) stamped by `compileModule`,
+       keying the component in the hot-reload registry — see `mountChild`. */
+    __abideId?: string
+}

package/src/lib/ui/runtime/types/UiProps.ts

@@ -0,0 +1,15 @@
+/*
+What a component is invoked with. Two real shapes flow through the one parameter.
+A top-level page/layout is called by the router (client) and `renderChain` (SSR)
+with its decoded route params — a plain string map. A nested child is called by
+the compiler-emitted `mountChild` with a map of reactive thunks (each authored
+prop, read in the body as `$props[name]?.()`) plus optional slot builders:
+`$children` for default-slot markup and `$slots[name]` for named slots, each
+mounting into the host element it is handed.
+*/
+export type UiProps =
+    | Record<string, string>
+    | (Record<string, () => unknown> & {
+          $children?: (host: Element) => void
+          $slots?: Record<string, (host: Element) => void>
+      })

package/src/lib/ui/runtime/unlinkDeps.ts

@@ -0,0 +1,20 @@
+import { detachLink } from './detachLink.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Detaches a node from every source it reads — the dispose path for a computed or
+effect torn down with its scope. Walks the node's dependency list once, removing
+each edge from its source's subscriber list so no source keeps a back-link to a
+dead observer, then empties the node's own list. The `Set`-era equivalent was
+`for (dep of node.deps) dep.observers.delete(node); node.deps.clear()`.
+*/
+export function unlinkDeps(node: ReactiveNode): void {
+    let link = node.depsHead
+    while (link !== undefined) {
+        const next = link.nextDep
+        detachLink(link)
+        link = next
+    }
+    node.depsHead = undefined
+    node.depsTail = undefined
+}

package/src/lib/ui/runtime/untrack.ts

@@ -0,0 +1,20 @@
+import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
+
+/*
+Runs `fn` with dependency tracking suspended: reads inside register no
+subscription on the surrounding observer. The inverse of `track` — for a
+reactive computation that must read or build without capturing those reads as
+its own dependencies. The router mounts a page inside an effect, so without this
+the page's build-time reads (every interpolation reads its value once before
+wrapping it in its own effect) would subscribe the router effect to the page's
+state — any in-page change would then re-run the router and re-mount the page.
+*/
+export function untrack<T>(fn: () => T): T {
+    const previous = REACTIVE_CONTEXT.observer
+    REACTIVE_CONTEXT.observer = undefined
+    try {
+        return fn()
+    } finally {
+        REACTIVE_CONTEXT.observer = previous
+    }
+}

package/src/lib/ui/runtime/valueAtPath.ts

@@ -0,0 +1,18 @@
+/*
+Reads the value at a `/`-joined path in a plain tree. `''` is the root. Returns
+undefined if any segment is missing — arrays index by their numeric segment as a
+string, which works because JS array access coerces the key.
+*/
+export function valueAtPath(tree: unknown, path: string): unknown {
+    if (path === '') {
+        return tree
+    }
+    let current: unknown = tree
+    for (const segment of path.split('/')) {
+        if (current === null || typeof current !== 'object') {
+            return undefined
+        }
+        current = (current as Record<string, unknown>)[segment]
+    }
+    return current
+}

package/src/lib/ui/runtime/writeNode.ts

@@ -0,0 +1,16 @@
+import { trigger } from './trigger.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Writes a signal node. An `Object.is`-equal write is a no-op — equality at the
+leaf is exactly what stops a no-change patch from waking readers, and (via the
+document's structural sharing) what stops an untouched sibling subtree from
+re-running when its parent changes identity.
+*/
+export function writeNode(node: ReactiveNode, value: unknown): void {
+    if (Object.is(node.value, value)) {
+        return
+    }
+    node.value = value
+    trigger(node)
+}

package/src/lib/ui/socketChannel.ts

@@ -0,0 +1,227 @@
+import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
+import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
+import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
+import type { SocketChannel } from '../shared/types/SocketChannel.ts'
+import type { SocketSubCallbacks } from '../shared/types/SocketSubCallbacks.ts'
+import { withBase } from '../shared/withBase.ts'
+
+let singleton: SocketChannel | undefined
+
+/*
+Lazily opens the single multiplexed ws used by every socket proxy on
+the page. Routes inbound frames:
+  `msg`    → all local subs of that socket
+  `replay` → the matching sub (its batched seed)
+  `end`    → the matching sub
+  `err`    → the matching sub
+
+`msg` frames carry no sub id: one publish from the server fans out to
+every connected ws via Bun's native publish, and each ws delivers the
+message to every local sub of that socket. `replay`/`end`/`err` are
+per-sub — a seed batch belongs to the sub that requested it.
+
+Outbound frames sent before `ws.onopen` fires are queued and flushed
+on open. The channel reconnects on close with bounded backoff;
+in-flight subs are torn down with the typed disconnect signal so
+consumers' `for await` loops can surface it, then the connection
+comes back up and fresh subs can be opened. The channel itself never
+re-subscribes across a reconnect — it can't know consumer semantics;
+a delta consumer must reconcile state on a fresh connection (e.g.
+re-fetch a snapshot before reapplying deltas). tail() opts in
+above this layer because its latest-wins/window semantics make replay a
+correct reconciliation; raw `for await` consumers keep manual control.
+
+While the backoff timer is armed, `connect()` defers to it: a consumer
+re-subscribing in reaction to the disconnect would otherwise trigger an
+immediate reconnect on every failure cycle, defeating the backoff. Its
+frames queue in `pendingSends` and flush when the timer's attempt opens.
+
+Hidden tabs hold no transport: `visibilitychange: hidden` closes the ws
+through the normal drop path above — subs tear down with the typed
+disconnect, and a resyncing consumer's fresh sub frames queue (connect()
+refuses to open while hidden) until the visible transition reconnects and
+flushes them.
+*/
+export function getSocketChannel(): SocketChannel {
+    if (singleton) {
+        return singleton
+    }
+    const subs = new Map<string, { socket: string; callbacks: SocketSubCallbacks }>()
+    const subsBySocket = new Map<string, Set<string>>()
+    let ws: WebSocket | undefined
+    let pendingSends: string[] = []
+    let backoffMs = 250
+    let reconnectTimer: ReturnType<typeof setTimeout> | undefined
+
+    function flushPending(): void {
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            return
+        }
+        for (const message of pendingSends) {
+            ws.send(message)
+        }
+        pendingSends = []
+    }
+
+    function send(frame: SocketClientFrame): void {
+        const message = JSON.stringify(frame)
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(message)
+            return
+        }
+        pendingSends.push(message)
+        connect()
+    }
+
+    function connect(): void {
+        /* Backoff window owns reconnection; queued frames flush when its attempt opens. */
+        if (reconnectTimer !== undefined) {
+            return
+        }
+        /* Hidden tabs hold no transport — frames queue, the visibility listener reconnects. */
+        if (document.hidden) {
+            return
+        }
+        if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+            return
+        }
+        const scheme = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+        // The mount base routes the upgrade through the proxy (/v2/__abide/sockets).
+        ws = new WebSocket(`${scheme}//${window.location.host}${withBase(SOCKETS_PATH)}`)
+        ws.addEventListener('open', () => {
+            backoffMs = 250
+            flushPending()
+        })
+        ws.addEventListener('message', (event) => {
+            let frame: SocketServerFrame
+            try {
+                frame = JSON.parse(event.data) as SocketServerFrame
+            } catch {
+                return
+            }
+            if (frame.type === 'msg') {
+                /*
+                One Bun-published frame fans out to every local sub of
+                that socket on this ws — addressed by socket name, not
+                per-sub id.
+                */
+                const targets = subsBySocket.get(frame.socket)
+                if (!targets) {
+                    return
+                }
+                for (const subId of targets) {
+                    subs.get(subId)?.callbacks.onMessage(frame.message)
+                }
+                return
+            }
+            if (frame.type === 'replay') {
+                subs.get(frame.sub)?.callbacks.onReplay(frame.messages)
+                return
+            }
+            if (frame.type === 'end') {
+                const sub = subs.get(frame.sub)
+                if (!sub) {
+                    return
+                }
+                dropSub(frame.sub)
+                sub.callbacks.onEnd()
+                return
+            }
+            if (frame.type === 'err') {
+                const sub = subs.get(frame.sub)
+                if (!sub) {
+                    return
+                }
+                dropSub(frame.sub)
+                sub.callbacks.onError(frame.message)
+                return
+            }
+        })
+        ws.addEventListener('close', () => {
+            const active = [...subs.values()]
+            subs.clear()
+            subsBySocket.clear()
+            /*
+            Drop any queued frames too. We've just torn down every local
+            sub, so replaying their `sub`/`unsub`/`pub` frames on
+            reconnect would open ghost subscriptions on the server that
+            no client object tracks (and never gets an `unsub`). This
+            keeps the "channel never re-subscribes" contract above
+            honest — consumers re-open fresh subs. Cleared before the
+            callbacks run so a consumer reacting to the disconnect (its
+            catch resolves in a microtask, after this handler) queues
+            onto a fresh list.
+            */
+            const hadPending = pendingSends.length > 0
+            pendingSends = []
+            ws = undefined
+            for (const sub of active) {
+                sub.callbacks.onDisconnect()
+            }
+            if (active.length === 0 && !hadPending) {
+                return
+            }
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = undefined
+                connect()
+            }, backoffMs)
+            backoffMs = Math.min(backoffMs * 2, 5000)
+        })
+    }
+
+    function dropSub(id: string): void {
+        const entry = subs.get(id)
+        if (!entry) {
+            return
+        }
+        subs.delete(id)
+        const set = subsBySocket.get(entry.socket)
+        if (set) {
+            set.delete(id)
+            if (set.size === 0) {
+                subsBySocket.delete(entry.socket)
+            }
+        }
+    }
+
+    /*
+    Release the ws when the tab hides rather than hold an idle connection the
+    browser throttles. Closing rides the normal drop path (close handler →
+    typed disconnect → consumers resync), so by the visible transition the
+    resubscribed frames sit in `pendingSends` waiting for the reconnect.
+    */
+    document.addEventListener('visibilitychange', () => {
+        if (document.hidden) {
+            ws?.close()
+            return
+        }
+        if (pendingSends.length > 0) {
+            connect()
+        }
+    })
+
+    singleton = {
+        subscribe(id, socket, replay, callbacks) {
+            subs.set(id, { socket, callbacks })
+            /* Not getOrInsertComputed: browser-side code, and Safari/Chrome only shipped it within the last browser cycle (26.2 / 145). */
+            let set = subsBySocket.get(socket)
+            if (!set) {
+                set = new Set()
+                subsBySocket.set(socket, set)
+            }
+            set.add(id)
+            send({ type: 'sub', sub: id, socket, replay })
+        },
+        unsubscribe(id) {
+            if (!subs.has(id)) {
+                return
+            }
+            dropSub(id)
+            send({ type: 'unsub', sub: id })
+        },
+        publish(socket, message) {
+            send({ type: 'pub', socket, message })
+        },
+    }
+    return singleton
+}

package/src/lib/ui/socketProxy.ts

@@ -0,0 +1,25 @@
+import type { Socket } from '../server/sockets/types/Socket.ts'
+import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
+import { getSocketChannel } from './socketChannel.ts'
+
+/*
+Client-side substitute for a server-declared Socket. The bundler emits
+one call per socket export under `src/server/sockets/`: server target uses
+defineSocket (real fan-out), browser target uses socketProxy (subscribe
+over the multiplexed ws channel). Both paths produce identical Socket
+shapes so user code reads the same on either side.
+
+The Socket surface — bare iteration as the live stream, `.tail(n)` seeded
+from the retained tail, `.publish` sending a server-validated `pub` frame —
+is built by buildSocketOverChannel over the page's lazily-opened singleton
+channel; this module only binds that builder to the browser channel so the
+test harness can reuse the identical surface over its own channel.
+
+Backpressure is unbounded — a slow consumer with a chatty socket will
+grow the per-iterator buffer; bounded policies belong in a future
+socketProxy API, not the wire layer.
+*/
+// @readme plumbing
+export function socketProxy<T>(name: string): Socket<T> {
+    return buildSocketOverChannel<T>(name, getSocketChannel)
+}

package/src/lib/ui/startClient.ts

@@ -0,0 +1,58 @@
+import { cacheEntryFromSnapshot } from '../shared/cacheEntryFromSnapshot.ts'
+import { createCacheStore } from '../shared/createCacheStore.ts'
+import { setBaseResolver } from '../shared/setBaseResolver.ts'
+import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
+import { setGlobalCacheStoreResolver } from '../shared/setGlobalCacheStoreResolver.ts'
+import { setPageResolver } from '../shared/setPageResolver.ts'
+import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
+import { installHotBridge } from './installHotBridge.ts'
+import { probeNavigation } from './probeNavigation.ts'
+import { router } from './router.ts'
+import { clientPage } from './runtime/clientPage.ts'
+import type { RouteLoader } from './runtime/types/RouteLoader.ts'
+
+/* The server's __SSR__ payload this entry consumes. */
+type SsrPayload = { cache?: CacheSnapshotEntry[]; base?: string }
+
+/*
+The official abide-ui client entry. Reads the server's `window.__SSR__` payload,
+seeds a tab-scoped cache store from the inline snapshot (so a warm `cache()` read
+resolves synchronously and the matching `<template await>` adopts the SSR DOM with
+no re-fetch), installs the mount base, and starts the router — which imports the
+current route's chunk, adopts the server-rendered `#app`, then drives SPA
+navigation — importing each further page's chunk on first visit and probing the
+destination through the server's app.handle so auth/redirect gating still applies.
+Returns a disposer. `target` defaults to `#app`; pass one explicitly in tests.
+*/
+// @readme plumbing
+export function startClient(
+    routes: Record<string, RouteLoader>,
+    layoutRoutes: Record<string, RouteLoader> = {},
+    target: Element | null = typeof document !== 'undefined'
+        ? document.getElementById('app')
+        : null,
+): () => void {
+    if (target === null) {
+        throw new Error('[abide] startClient: missing #app target')
+    }
+    /* Dev only: the live-reload script sets `__abideDev` before this module runs,
+       so the runtime bridge is in place before any component mounts and records
+       its instances (mountChild) for hot replacement. */
+    if ((globalThis as { __abideDev?: boolean }).__abideDev) {
+        installHotBridge()
+    }
+    const ssr = (globalThis as { __SSR__?: SsrPayload }).__SSR__ ?? {}
+    setBaseResolver(() => ssr.base ?? '')
+    /* The `page` proxy reads route/params/url off the router-updated snapshot. */
+    setPageResolver(() => clientPage.value)
+
+    const store = createCacheStore()
+    setCacheStoreResolver(() => store)
+    /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
+    setGlobalCacheStoreResolver(() => store)
+    for (const entry of ssr.cache ?? []) {
+        store.entries.set(entry.key, cacheEntryFromSnapshot(entry))
+    }
+
+    return router(target, routes, layoutRoutes, probeNavigation)
+}

package/src/lib/ui/state.ts

@@ -0,0 +1,25 @@
+import { createSignalNode } from './runtime/createSignalNode.ts'
+import { readNode } from './runtime/readNode.ts'
+import type { State } from './runtime/types/State.ts'
+import { writeNode } from './runtime/writeNode.ts'
+
+/*
+A writable reactive cell — abide's from-scratch reactive primitive, with no
+compiler sigil and no external reactivity-library import. `.value` is a
+plain getter/setter over a signal node, so a read/write shows up as exactly that
+in a stack trace. The compiler's job (later) is only to auto-deref `{cell}` in
+templates and tag this declaration as a serializable manifest slot; the runtime
+needs no magic.
+*/
+// @readme plumbing
+export function state<T>(initial: T): State<T> {
+    const node = createSignalNode(initial)
+    return {
+        get value(): T {
+            return readNode(node) as T
+        },
+        set value(next: T) {
+            writeNode(node, next)
+        },
+    }
+}