@abide/abide 0.28.0

package/src/lib/shared/probeRegistries.ts

@@ -0,0 +1,68 @@
+import { cacheStores } from './cacheStores.ts'
+import { isSubscribable } from './isSubscribable.ts'
+import { selectorMatcher } from './selectorMatcher.ts'
+import { selectorPrefix } from './selectorPrefix.ts'
+import { tailProbeSlot } from './tailProbeSlot.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Shared scan behind the pending() / refreshing() probes: one selector
+interpretation and one tap order — the lifecycle channel is tapped before
+any check, so short-circuiting can't skip a subscription and a $derived
+re-runs whenever a matching call or stream changes state. The tap is scoped
+to the selector: a fn selector taps only its own prefix channel, so reading
+`pending(fn)` in an effect can't be re-woken by unrelated cache events (an
+effect that probes one fn and invalidates another no longer feeds itself);
+bare and scope selectors scan many entries and tap the store-wide channel. A
+producer never cached resolves no prefix yet and taps store-wide — its first
+cache() marks that channel, the re-derive resolves the prefix, and the scope
+re-tracks narrowed. `matchesEntry` is the probe's cache-side question;
+`field` selects the stream-side answer; `unprobed` is the answer for a
+stream no prober can see (server, or tail never imported) — matching what
+tail() itself reports there. The bare form (no selector) spans both
+registries; fn/scope selectors are cache identities only. Outside a tracking
+scope the taps are no-ops and the current value returns.
+*/
+export function probeRegistries<Args, Return>(
+    arg: CacheSelector<Args, Return> | Subscribable<unknown> | undefined,
+    args: Args | undefined,
+    field: 'pending' | 'refreshing',
+    matchesEntry: (entry: CacheEntry) => boolean,
+    unprobed: boolean,
+): boolean {
+    if (isSubscribable(arg)) {
+        return tailProbeSlot.probe?.(arg.name)?.[field] ?? unprobed
+    }
+    /* fn + args narrows further: the exact key is a one-entry "prefix" (its === branch). */
+    const prefix = selectorPrefix(arg, args)
+    const stores = cacheStores()
+    stores.forEach((store) => {
+        store.trackLifecycle(prefix)
+    })
+    const streams = arg === undefined ? tailProbeSlot.probe?.() : undefined
+    const matches = selectorMatcher(arg, args, prefix)
+    return (
+        stores.some((store) => anyEntryMatches(store, matchesEntry, matches)) ||
+        streams?.[field] === true
+    )
+}
+
+/*
+A plain for-of over the entries Map rather than .values().some() — Iterator
+Helpers are too new for this module's browser baseline (see producerKey).
+*/
+function anyEntryMatches(
+    store: CacheStore,
+    matchesEntry: (entry: CacheEntry) => boolean,
+    matches: (entry: CacheEntry) => boolean,
+): boolean {
+    for (const entry of store.entries.values()) {
+        if (matchesEntry(entry) && matches(entry)) {
+            return true
+        }
+    }
+    return false
+}

package/src/lib/shared/producerKey.ts

@@ -0,0 +1,32 @@
+import { canonicalJson } from './canonicalJson.ts'
+
+/*
+Producers have no wire identity, so each is assigned a stable id on first use,
+kept in a WeakMap so it's collected with the function. The cache key is that id
+plus the canonicalised args — a hoisted producer dedupes across calls; an inline
+arrow gets a fresh id every call and never does.
+
+`producerKey.existing` reads the id without assigning one — selectors matching
+prior entries must not mint identities for producers never cached.
+*/
+const producerIds = new WeakMap<object, string>()
+let producerCounter = 0
+
+export function producerKey(producer: object, args: unknown): string {
+    /* Not getOrInsertComputed: shared module ships to the browser, where support is too new (Safari 26.2 / Chrome 145). */
+    let id = producerIds.get(producer)
+    if (id === undefined) {
+        id = `@producer:${++producerCounter}`
+        producerIds.set(producer, id)
+    }
+    return args === undefined ? id : `${id} ${canonicalJson(args)}`
+}
+
+/* With `args`, the exact entry key for that call (same format as producerKey) — still never minting. */
+producerKey.existing = function existing(producer: object, args?: unknown): string | undefined {
+    const id = producerIds.get(producer)
+    if (id === undefined || args === undefined) {
+        return id
+    }
+    return `${id} ${canonicalJson(args)}`
+}

package/src/lib/shared/programNameForPackage.ts

@@ -0,0 +1,14 @@
+/*
+Derives the CLI program/binary name from a package.json `name` field.
+Scoped names (`@scope/tool`) keep only the final segment so the value is
+safe as a filesystem path, tar entry name, and CLI display name — a raw
+`/` would otherwise nest the binary into an unexpected directory and break
+the `/__abide/cli/<platform>` download route's path lookup. Falls back to
+`app` when the name is absent or empty.
+*/
+export function programNameForPackage(name: string | undefined): string {
+    if (name === undefined || name === '') {
+        return 'app'
+    }
+    return name.split('/').pop() || 'app'
+}

package/src/lib/shared/promptNameForFile.ts

@@ -0,0 +1,10 @@
+/*
+Translates a prompt file path under `src/mcp/prompts/` into the prompt's
+MCP name. Strips `.md` and joins nested folder segments with `-` (e.g.
+`code/review.md` → `code-review`) so two prompts with the same stem in
+different folders don't collide and the name stays a single valid MCP
+prompt identifier.
+*/
+export function promptNameForFile(relativePath: string): string {
+    return relativePath.replace(/\.md$/, '').replaceAll('/', '-')
+}

package/src/lib/shared/queryStringFromArgs.ts

@@ -0,0 +1,27 @@
+/*
+Canonical query-string encoding for a query-carrying verb's args bag. The
+single definition both the synthesized Request (buildRpcRequest) and its
+cache key (keyForRemoteCall) build their query from, so the request URL and
+the key encode every value identically and can't drift. `undefined` values
+are dropped; each surviving value is coerced with String() and percent-
+encoded with encodeURIComponent on both name and value. Keys come in
+insertion order for the request and sorted for the key (`sort`), so the key
+is stable under arg reordering. Returns the query body without a leading
+`?` (empty string when nothing survives the filter). Concatenated in one
+walk — no entries / filtered / URLSearchParams intermediates — to keep the
+hot GET-cache path allocation-light. Callers validate that `args` is a
+plain object first; this assumes that.
+*/
+export function queryStringFromArgs(args: Record<string, unknown>, sort: boolean): string {
+    const keys = sort ? Object.keys(args).sort() : Object.keys(args)
+    let query = ''
+    for (const key of keys) {
+        const value = args[key]
+        if (value === undefined) {
+            continue
+        }
+        query += query ? '&' : ''
+        query += `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
+    }
+    return query
+}

package/src/lib/shared/randomHexId.ts

@@ -0,0 +1,14 @@
+/*
+Mints a random lowercase-hex id of `bytes` length via the web-standard
+crypto.getRandomValues — trace ids (16 bytes) and span ids (8 bytes). Loops on
+the all-zero value, which W3C Trace Context reserves as invalid.
+*/
+export function randomHexId(bytes: number): string {
+    const buffer = new Uint8Array(bytes)
+    let id = ''
+    do {
+        crypto.getRandomValues(buffer)
+        id = Array.from(buffer, (byte) => byte.toString(16).padStart(2, '0')).join('')
+    } while (/^0+$/.test(id))
+    return id
+}

package/src/lib/shared/readEnvFile.ts

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs'
+import { parseEnv } from './parseEnv.ts'
+
+/*
+Reads a `.env` at `path` into a key→value record, or {} when it doesn't exist.
+The shared read-and-parse primitive: loadEnvFile builds on it to merge into
+process.env, and the bundle launcher uses the record directly to resolve config
+form pre-fills.
+*/
+export async function readEnvFile(path: string): Promise<Record<string, string>> {
+    if (!existsSync(path)) {
+        return {}
+    }
+    return parseEnv(await Bun.file(path).text())
+}

package/src/lib/shared/readLastConnection.ts

@@ -0,0 +1,18 @@
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+/*
+Reads the saved connection intent, or undefined when none is recorded or the file
+is unreadable/corrupt — callers treat undefined as "nothing to resume".
+*/
+export async function readLastConnection(programName: string): Promise<LastConnection | undefined> {
+    const file = Bun.file(lastConnectionPath(programName))
+    if (!(await file.exists())) {
+        return undefined
+    }
+    try {
+        return (await file.json()) as LastConnection
+    } catch {
+        return undefined
+    }
+}

package/src/lib/shared/readPackageJson.ts

@@ -0,0 +1,9 @@
+/*
+Reads and parses a project's `package.json`, or undefined when absent. Callers
+apply their own field defaults — this centralizes only the exists-check + parse
+boilerplate. Bun.file().json() so no Node fs.
+*/
+export async function readPackageJson(cwd: string): Promise<Record<string, unknown> | undefined> {
+    const file = Bun.file(`${cwd}/package.json`)
+    return (await file.exists()) ? ((await file.json()) as Record<string, unknown>) : undefined
+}

package/src/lib/shared/recordRemoteMeta.ts

@@ -0,0 +1,5 @@
+import { remoteMetaStore } from './remoteMetaStore.ts'
+
+export function recordRemoteMeta(promise: Promise<unknown>, getRequest: () => Request): void {
+    remoteMetaStore.set(promise, getRequest)
+}

package/src/lib/shared/refreshing.ts

@@ -0,0 +1,31 @@
+import { probeRegistries } from './probeRegistries.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Reactive revalidation probe over both registries. Refreshing means "holding a
+value it already had while a fresher source is in flight":
+  refreshing()              → anything reloading data it already had
+  refreshing(fn)            → that function's calls (per-route "updating…" badge)
+  refreshing(fn, args)      → exactly that call (per-row badge)
+  refreshing({ scope })     → a tagged group
+  refreshing(subscribable)  → that stream reconnecting with its last value
+                              retained — never merely `open`; a live stream's
+                              arriving frames are its normal mode, not a reload
+On the cache side this covers a policy stale-while-revalidate refetch (settled,
+value visible, fresh fetch in flight) and the default drop-then-reload (pending
+is also true there). The distinction from pending(): pending answers "is there
+no value yet?", refreshing answers "is a held value being superseded?".
+Probes report, never act. Scan semantics (tap order, selector grammar,
+registry spans) live in probeRegistries.
+*/
+// @readme probes
+export function refreshing<Args, Return>(
+    arg?: CacheSelector<Args, Return> | Subscribable<unknown>,
+    args?: Args,
+): boolean {
+    return probeRegistries(arg, args, 'refreshing', reloading, false)
+}
+
+const reloading = (entry: CacheEntry) => entry.refreshing === true

package/src/lib/shared/remoteMetaStore.ts

@@ -0,0 +1,16 @@
+/*
+WeakMap that records how to obtain the synthesized Request for a verb
+call. The cache layer reads it to populate an entry's stored request
+without rebuilding from scratch.
+
+Stored as a thunk rather than the Request itself so SSR pages that fire
+dozens of in-process verb calls without ever reaching cache() don't pay
+the URL + Headers + Request allocation per call. The thunk memoises its
+own first call inside createRemoteFunction, so cache() and any future
+meta reader see the same Request instance.
+
+method/url/key are intentionally not stored — they're derivable from
+the RemoteFunction itself, and cache() does that derivation
+independently.
+*/
+export const remoteMetaStore = new WeakMap<Promise<unknown>, () => Request>()

package/src/lib/shared/requestScopeSlot.ts

@@ -0,0 +1,15 @@
+import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
+
+/*
+Internal slot the runtime entries register their request-scope resolver into.
+The server installs an ALS-backed resolver (createServer, reading the
+RequestStore); the client installs a module-singleton resolver seeded from
+__SSR__ (startClient). Undefined resolver — or a resolver returning undefined
+outside any request — means "no scope": trace() returns undefined and log
+lines print without the context prefix. Mirrors pageSlot / cacheStoreSlot.
+*/
+export const requestScopeSlot: {
+    resolver: (() => RequestScopeInfo | undefined) | undefined
+} = {
+    resolver: undefined,
+}

package/src/lib/shared/resolveClientFlags.ts

@@ -0,0 +1,20 @@
+import type { ClientFlags } from './types/ClientFlags.ts'
+
+/*
+Fills in the missing keys of a user-supplied `clients` option. Browser
+always defaults to true (the historical surface). The mcp/cli auto-on
+defaults are decided by the caller and passed in, since the safe default
+differs per declaration: a read-only verb may auto-expose to MCP while a
+mutating one must not, and sockets gate differently again. Explicit
+values in `flags` always win over the computed defaults.
+*/
+export function resolveClientFlags(
+    flags: Partial<ClientFlags> | undefined,
+    defaults: { mcp: boolean; cli: boolean },
+): ClientFlags {
+    return {
+        browser: flags?.browser ?? true,
+        mcp: flags?.mcp ?? defaults.mcp,
+        cli: flags?.cli ?? defaults.cli,
+    }
+}

package/src/lib/shared/responseErrorText.ts

@@ -0,0 +1,9 @@
+/*
+Human-readable message for a non-2xx Response: `status statusText: body`.
+Shared by the CLI error path and the MCP tool result so the two frame a
+failed request identically. Consumes the body, so call only on a response
+you're done with.
+*/
+export async function responseErrorText(response: Response): Promise<string> {
+    return `${response.status} ${response.statusText}: ${await response.text()}`
+}

package/src/lib/shared/rpcTimeoutSlot.ts

@@ -0,0 +1,9 @@
+/*
+Slot the client entry registers the env-configured RPC fetch timeout (ms)
+into. The server reads ABIDE_CLIENT_TIMEOUT at boot and ships it via
+__SSR__.clientTimeout, so the value reflects the running server's env rather
+than build time; startClient installs it here and remoteProxy reads it.
+undefined = no timeout (the default — RPC fetches stay unbounded as before).
+Mirrors baseSlot.
+*/
+export const rpcTimeoutSlot: { ms: number | undefined } = { ms: undefined }

package/src/lib/shared/rpcUrlForFile.ts

@@ -0,0 +1,19 @@
+/*
+Maps an rpc-relative path (under `src/server/rpc/`) to its URL. Each file
+is one endpoint at `/rpc/<file path>`, dropping the `.ts` extension.
+$rpc URLs are flat function-call endpoints (args go in query or body), so
+bracket-style `[name]` / `[...rest]` segments are rejected — those belong
+in `src/ui/pages/` where they map to dynamic path params.
+*/
+export function rpcUrlForFile(relPath: string): string {
+    const withoutExt = relPath.replace(/\.ts$/, '')
+    const segments = withoutExt.split('/').filter(Boolean)
+    for (const segment of segments) {
+        if (segment.startsWith('[')) {
+            throw new Error(
+                `[abide] src/server/rpc/${relPath} has a dynamic segment '${segment}' — $rpc URLs are flat; pass identifiers via args, not the path`,
+            )
+        }
+    }
+    return `/rpc/${segments.join('/')}`
+}

package/src/lib/shared/runningAsStandaloneBinary.ts

@@ -0,0 +1,13 @@
+/*
+True when this code runs inside a `bun build --compile` standalone executable
+(the bundle's embedded server, or an install-tarball server binary) rather than
+under the `bun` CLI. Bun mounts a compiled binary's embedded modules under a
+synthetic root — `/$bunfs/…` on posix, `…~BUN…` on Windows — so `Bun.main`
+carries that marker only in a standalone binary; under `bun dev`/`bun start`
+it's a real on-disk path. Used to scope the bundle's data-dir/binary-dir `.env`
+loading to the shipped app, so `bun dev`/`bun start` keep to their project-local
+CWD `.env` alone.
+*/
+export function runningAsStandaloneBinary(): boolean {
+    return Bun.main.includes('$bunfs') || Bun.main.includes('~BUN')
+}

package/src/lib/shared/selectorMatcher.ts

@@ -0,0 +1,68 @@
+import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
+import { selectorPrefix } from './selectorPrefix.ts'
+import { toScopeSet } from './toScopeSet.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+
+/*
+Compiles a selector into an entry predicate shared by cache.invalidate(),
+pending(), and refreshing() so all three interpret the call shapes identically:
+  undefined            → every entry
+  remote fn            → that function's calls (method+url prefix). `arg.url` is
+                         the route template; per-call args appear as `?...`
+                         (GET/DELETE) or after a space (canonical-json body) —
+                         see keyForRemoteCall. `fn` and `fn.raw` match the same
+                         set since they share method+url.
+  producer fn          → that producer's calls (reference id prefix). Matches
+                         only if the producer was cached at least once (else it
+                         has no id and nothing matches).
+  { scope }            → any entry sharing one of the requested scope tags. An
+                         empty selector matches nothing.
+  fn + args            → exactly that call's entry (the key derived from the
+                         same encoders the read path uses); other args
+                         variants of the fn are untouched.
+Fn-selector identity (prefix resolution + the cache()-wrapper throw) lives in
+selectorPrefix, the prefix grammar in keyMatchesPrefix — both shared with the
+probes' scoped lifecycle channels so a probe subscribes to exactly the entries
+this predicate would match. A caller that already resolved the prefix (the
+invalidate/probe paths derive it for their own use) passes it as
+`precomputedPrefix` so the args encoding isn't re-derived per call.
+*/
+export function selectorMatcher<Args, Return>(
+    arg?: CacheSelector<Args, Return>,
+    args?: Args,
+    precomputedPrefix?: string,
+): (entry: CacheEntry) => boolean {
+    if (arg === undefined) {
+        return () => true
+    }
+    if (typeof arg === 'function') {
+        const prefix = precomputedPrefix ?? selectorPrefix(arg, args)
+        if (prefix === undefined) {
+            return () => false
+        }
+        if (args !== undefined) {
+            return (entry) => entry.key === prefix
+        }
+        return (entry) => keyMatchesPrefix(entry.key, prefix)
+    }
+    if (arg.scope === undefined) {
+        return () => false
+    }
+    const requestedScopes = toScopeSet(arg.scope)
+    return (entry) => entry.scope !== undefined && intersects(entry.scope, requestedScopes)
+}
+
+/*
+True when an entry's tags and the requested tags overlap on any tag. A plain
+for-of over the Set rather than .values().some() — Iterator Helpers are too new
+for this module's browser baseline (see producerKey).
+*/
+function intersects(entryScopes: Set<string>, requestedScopes: Set<string>): boolean {
+    for (const scope of requestedScopes) {
+        if (entryScopes.has(scope)) {
+            return true
+        }
+    }
+    return false
+}

package/src/lib/shared/selectorPrefix.ts

@@ -0,0 +1,39 @@
+import { CACHE_WRAPPED } from './CACHE_WRAPPED.ts'
+import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { producerKey } from './producerKey.ts'
+import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
+
+/*
+Resolves a fn selector to the key prefix its entries share: a remote keys on
+method+url (fn and fn.raw agree — same wire identity), a producer on the
+reference id minted at first cache. With `args`, the exact entry key for that
+one call instead — derived through the same encoders the read path uses
+(keyForRemoteCall / producerKey format), so selector and entry can't
+disagree. Undefined when no prefix exists — bare and scope selectors (they
+scan, not prefix-match) and producers never cached (no id was minted;
+minting one here would leak identities for probe-only reads). The
+cache()-wrapper throw lives here so both consumers — the matcher and the
+probes' channel tap — reject it before subscribing to anything.
+*/
+export function selectorPrefix<Args, Return>(
+    arg: CacheSelector<Args, Return> | undefined,
+    args?: Args,
+): string | undefined {
+    if (typeof arg !== 'function') {
+        return undefined
+    }
+    if (CACHE_WRAPPED in arg) {
+        throw new Error(
+            '[abide] a cache() wrapper is not a selector — pass the function it wraps, e.g. pending(getPost), not pending(cache(getPost))',
+        )
+    }
+    const remote = REMOTE_FUNCTION in arg ? (arg as RawRemoteFunction<Args>) : undefined
+    if (remote) {
+        return args === undefined
+            ? `${remote.method} ${remote.url}`
+            : keyForRemoteCall(remote.method, remote.url, args)
+    }
+    return producerKey.existing(arg, args)
+}

package/src/lib/shared/serializeEnv.ts

@@ -0,0 +1,18 @@
+// Quote only values that wouldn't round-trip bare through parseEnv — empties and
+// anything carrying whitespace or a `#` (which would otherwise read as a comment).
+function needsQuoting(value: string): boolean {
+    return value === '' || /[\s#]/.test(value)
+}
+
+/*
+Serializes a key→value record to `.env` text — the inverse of parseEnv, used by
+the connect-screen config form to persist the user's answers to the data-dir
+`.env`. One `KEY=value` per line; values that need it are wrapped in double
+quotes so parseEnv reads them back unchanged.
+*/
+export function serializeEnv(values: Record<string, string>): string {
+    const lines = Object.entries(values).map(([key, value]) =>
+        needsQuoting(value) ? `${key}="${value}"` : `${key}=${value}`,
+    )
+    return `${lines.join('\n')}\n`
+}

package/src/lib/shared/setAppName.ts

@@ -0,0 +1,5 @@
+import { appNameSlot } from './appNameSlot.ts'
+
+export function setAppName(name: string | undefined): void {
+    appNameSlot.name = name
+}

package/src/lib/shared/setBaseResolver.ts

@@ -0,0 +1,6 @@
+import { baseSlot } from './baseSlot.ts'
+
+// Registers the runtime's mount-base resolver. Called once per side at boot.
+export function setBaseResolver(fn: () => string): void {
+    baseSlot.resolver = fn
+}

package/src/lib/shared/setCacheStoreResolver.ts

@@ -0,0 +1,6 @@
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+export function setCacheStoreResolver(fn: () => CacheStore | undefined): void {
+    cacheStoreSlot.resolver = fn
+}

package/src/lib/shared/setGlobalCacheStoreResolver.ts

@@ -0,0 +1,6 @@
+import { globalCacheStoreSlot } from './globalCacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+export function setGlobalCacheStoreResolver(fn: () => CacheStore | undefined): void {
+    globalCacheStoreSlot.resolver = fn
+}

package/src/lib/shared/setPageResolver.ts

@@ -0,0 +1,7 @@
+import { pageSlot } from './pageSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+// Registers the runtime's page resolver. Called once per side at boot.
+export function setPageResolver(fn: () => PageSnapshot | undefined): void {
+    pageSlot.resolver = fn
+}

package/src/lib/shared/setRequestScopeResolver.ts

@@ -0,0 +1,6 @@
+import { requestScopeSlot } from './requestScopeSlot.ts'
+import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
+
+export function setRequestScopeResolver(fn: () => RequestScopeInfo | undefined): void {
+    requestScopeSlot.resolver = fn
+}

package/src/lib/shared/snippet.ts

@@ -0,0 +1,25 @@
+const SNIPPET = Symbol.for('abide.snippet')
+
+/* A `<template name args>` snippet, called like a function: it carries a payload a
+   `{expr}` interpolation mounts in place — a DOM builder `(host) => void` on the
+   client, the pre-rendered HTML string on the server. The brand is a registered
+   Symbol so it survives across module/bundle copies (same idiom as `html\`\``). */
+export type Snippet<Payload> = { readonly [SNIPPET]: Payload }
+
+/* Brands a snippet payload so a `{expr}` interpolation mounts it instead of
+   inserting escaped text. The compiler wraps a snippet's body in this — the client
+   builder closes over the defining component's scope, the server string is its SSR
+   render — so a snippet value passes through props like any other value. */
+// @readme plumbing
+export function snippet<Payload>(payload: Payload): Snippet<Payload> {
+    return { [SNIPPET]: payload }
+}
+
+/* The payload of a snippet-branded value, or undefined for anything else — so a
+   text binding fast-paths plain values and only branded ones mount. The client
+   reads a builder function; the server reads the rendered string. */
+export function snippetPayload(value: unknown): unknown {
+    return value !== null && typeof value === 'object' && SNIPPET in value
+        ? (value as Snippet<unknown>)[SNIPPET]
+        : undefined
+}

package/src/lib/shared/socketNameForFile.ts

@@ -0,0 +1,11 @@
+/*
+Translates a socket file path under `src/server/sockets/` into the socket's
+identity used on the wire. The name is the file path minus `.ts` so
+nested paths (e.g. `orders/new.ts`) become `orders/new`. Sockets don't
+need a URL prefix the way rpc routes do — they multiplex over the
+framework-owned `/__abide/sockets` ws and are dispatched by name in the
+registry, not by HTTP path.
+*/
+export function socketNameForFile(relativePath: string): string {
+    return relativePath.replace(/\.ts$/, '')
+}

package/src/lib/shared/socketTapSlot.ts

@@ -0,0 +1,12 @@
+/*
+Passive observation seam for published socket frames — the socket analogue of
+logTapSlot. defineSocket's publish() calls the tap (when set) with every frame
+it fans out, so an observer sees the same payloads subscribers receive. The
+inspector installs one to fold socket traffic into its feed; unset everywhere
+else, so the call no-ops. One slot, one in-process observer. Mirrors logTapSlot.
+*/
+export const socketTapSlot: {
+    tap: ((frame: { socket: string; message: unknown }) => void) | undefined
+} = {
+    tap: undefined,
+}

package/src/lib/shared/sseErrorFrame.ts

@@ -0,0 +1,29 @@
+/*
+The in-band error sentinel for an SSE stream: when a handler's generator
+throws, `sse()` emits an `event: error` frame whose data is `{ message }`,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel (event name + payload shape) has one
+definition and can't drift between the two ends of the wire.
+*/
+export const sseErrorFrame = {
+    // Full `event: error` frame for a thrown message, including the SSE delimiters.
+    encode(message: string): string {
+        return `event: error\ndata: ${JSON.stringify({ message })}\n\n`
+    },
+    /*
+    The message carried by an error frame, or undefined when `event` isn't
+    the error sentinel. Falls back to the raw data when it isn't the JSON
+    the encoder produces.
+    */
+    decode(event: string, data: string): string | undefined {
+        if (event !== 'error') {
+            return undefined
+        }
+        try {
+            const decoded = JSON.parse(data) as { message?: string }
+            return decoded?.message ?? 'sse stream error'
+        } catch {
+            return data || 'sse stream error'
+        }
+    },
+}