@abide/abide 0.45.0 → 0.47.0

package/src/lib/ui/socketProxy.ts

@@ -1,6 +1,7 @@
-import type { Socket } from '../server/sockets/types/Socket.ts'
 import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
+import type { Socket } from '../shared/types/Socket.ts'
 import { getSocketChannel } from './socketChannel.ts'
+import { watch } from './watch.ts'
 
 /*
 Client-side substitute for a server-declared Socket. The bundler emits
@@ -10,7 +11,7 @@ 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 —
+from the retained tail, `.broadcast` 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.
@@ -21,5 +22,10 @@ socketProxy API, not the wire layer.
 */
 // @documentation plumbing
 export function socketProxy<T>(name: string): Socket<T> {
-    return buildSocketOverChannel<T>(name, getSocketChannel)
+    const socket = buildSocketOverChannel<T>(name, getSocketChannel)
+    /* Overwrite the shared builder's inert `.watch` with the real reaction sugar
+       (`socket.watch(handler)` ≡ `watch(socket, handler)`). Attached here so the ui-only
+       `watch` primitive never rides into a server bundle. */
+    socket.watch = (handler) => watch(socket, handler)
+    return socket
 }

package/src/lib/ui/startClient.ts

@@ -1,14 +1,11 @@
+import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
-import { healthSeedSlot } from '../shared/healthSeedSlot.ts'
-import { rpcTimeoutSlot } from '../shared/rpcTimeoutSlot.ts'
-import { setAppName } from '../shared/setAppName.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 { globalCacheStoreSlot } from '../shared/globalCacheStoreSlot.ts'
+import { pageSlot } from '../shared/pageSlot.ts'
+import type { SsrPayload } from '../shared/types/SsrPayload.ts'
 import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
 import { probeNavigation } from './probeNavigation.ts'
+import { seedBootState } from './seedBootState.ts'
 
 /* Build-time flag the production client defines false (see build.ts `define`) so the dev-only
    hot bridge — and the entire DOM runtime it statically pulls in for re-builds — is dead-code-
@@ -21,15 +18,6 @@ import { clientPage } from './runtime/clientPage.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
 import { seedResolved } from './seedResolved.ts'
 
-/* The server's __SSR__ payload this entry consumes. */
-type SsrPayload = {
-    cache?: CacheSnapshotEntry[]
-    base?: string
-    app?: string
-    health?: Record<string, unknown>
-    clientTimeout?: number
-}
-
 /*
 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
@@ -67,23 +55,21 @@ export function startClient(
     if ((globalThis as { __abideInspect?: boolean }).__abideInspect) {
         import('./installInspectorBridge.ts').then((module) => module.installInspectorBridge())
     }
-    const ssr = (globalThis as { __SSR__?: SsrPayload }).__SSR__ ?? {}
-    setBaseResolver(() => ssr.base ?? '')
-    /* Seed the per-page __SSR__ stamps into their shared slots before mount: the app
-       name (default log channel), the health payload (so health()'s first probe is warm),
-       and the env-configured RPC timeout (ABIDE_CLIENT_TIMEOUT, shipped per request).
-       Without this the browser falls back to channel 'app', a cold first health probe,
-       and unbounded RPC fetches. */
-    setAppName(ssr.app)
-    healthSeedSlot.payload = ssr.health
-    rpcTimeoutSlot.ms = ssr.clientTimeout
+    const ssr = (globalThis as { __SSR__?: Partial<SsrPayload> }).__SSR__ ?? {}
+    /* Seed the per-page __SSR__ stamps into their shared slots before mount: the mount
+       base, app name (default log channel), health payload (so health()'s first probe is
+       warm), and the env-configured RPC timeout (ABIDE_CLIENT_TIMEOUT, shipped per
+       request). Driven by the exhaustive `seedBootState` map so a new boot field can't be
+       stamped server-side and silently dropped here. Without seeding: no mount base,
+       channel 'app', a cold first health probe, and unbounded RPC fetches. */
+    seedBootState(ssr)
     /* The `page` proxy reads route/params/url off the router-updated snapshot. */
-    setPageResolver(() => clientPage.value)
+    pageSlot.resolver = () => clientPage.value
 
     const store = createCacheStore()
-    setCacheStoreResolver(() => store)
+    cacheStoreSlot.resolver = () => store
     /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
-    setGlobalCacheStoreResolver(() => store)
+    globalCacheStoreSlot.resolver = () => store
     /* Seed both SSR cache partitions through the one streamed-resolution sink: `ssr.cache`
        (inline — reads settled at render-return, in __SSR__) and `__abideResumeCache` (pending
        {#await} reads whose `__abideResolve(...)` chunks the stream pushed during parse, before

package/src/lib/ui/state.ts

@@ -1,15 +1,42 @@
+import { computed } from './computed.ts'
+import { linked } from './linked.ts'
 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'
+import { scope } from './scope.ts'
+
+/* The imported reactive surface: the `state` callable plus its attached members.
+   `state`/`state.linked`/`state.computed` are the reactive primitives an author
+   imports (`import { state } from '@abide/abide/ui/state'`); the compiler resolves
+   the import binding (alias-safe) and lowers each onto the ambient scope. `.share`/
+   `.shared` are the context seam — the reference store the runtime scope exposes,
+   reached ambiently so a component can pass a named value down its subtree. */
+type StateFn = {
+    /* No-arg form for an undefined initial with a declared type: `state<Foo>()` is
+       `State<Foo | undefined>`. Without it `state<Foo>(undefined)` is an arity/assign
+       error and `state(undefined)` infers `T = undefined` (every `.value` access then
+       narrows to `never`). */
+    <T>(): State<T | undefined>
+    <T>(initial: T, transform?: (next: T, previous: T) => T): State<T>
+    /* A writable cell reseeded from a reactive thunk (`state.linked(() => src())`). */
+    linked: typeof linked
+    /* A read-only cell computed from other cells (`state.computed(() => a() + b())`). */
+    computed: typeof computed
+    /* Puts a named value on the ambient scope, read down the tree by `state.shared`. */
+    share: (key: string, value: unknown) => void
+    /* Reads the closest ancestor scope that shared `key`; undefined if none provided. */
+    shared: <T>(key: string) => T | undefined
+}
 
 /*
 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 enforces scope attachment (bare `state()` is a compile
-error — use `scope().state()`), desugars plain `state(initial)` to a serializable `model`
-doc slot, and keeps `state(initial, transform)` as a `.value` cell; the runtime needs no magic.
+in a stack trace. Imported and called bare (`let count = state(0)`); the compiler
+resolves the `state` import binding (alias-safe), desugars plain `state(initial)` to
+a serializable `model` doc slot, and keeps `state(initial, transform)` as a `.value`
+cell routed onto the ambient scope; the runtime needs no magic.
 
 `transform` is an optional coercion gate on the write path: every `.value =`
 runs it and stores what it returns, with `previous` for clamp-relative writes or
@@ -18,16 +45,7 @@ mirror of `computed`'s write-through `set` — here the value lives in this cell
 the gate *returns* what to store rather than writing an external target. The
 construction `initial` is taken verbatim; the gate runs on writes only.
 */
-/* No-arg form for an undefined initial with a declared type: `state<Foo>()` is
-   `State<Foo | undefined>`. Without it `state<Foo>(undefined)` is an arity/assign
-   error and `state(undefined)` infers `T = undefined` (every `.value` access then
-   narrows to `never`). */
-export function state<T>(): State<T | undefined>
-export function state<T>(initial: T, transform?: (next: T, previous: T) => T): State<T>
-export function state<T>(
-    initial?: T,
-    transform?: (next: T, previous: T) => T,
-): State<T | undefined> {
+function stateCell<T>(initial?: T, transform?: (next: T, previous: T) => T): State<T | undefined> {
     const node = createSignalNode(initial)
     return {
         get value(): T | undefined {
@@ -38,3 +56,16 @@ export function state<T>(
         },
     }
 }
+
+const stateFn = stateCell as StateFn
+stateFn.linked = linked
+stateFn.computed = computed
+/* `.share`/`.shared` route onto the ambient scope, read/written at call time so the
+   state ↔ scope module cycle resolves. */
+stateFn.share = (key: string, value: unknown): void => {
+    scope().share(key, value)
+}
+stateFn.shared = <T>(key: string): T | undefined => scope().shared<T>(key)
+
+// @documentation reactive-state
+export const state = stateFn

package/src/lib/ui/sync.ts

@@ -1,5 +1,6 @@
 import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
 import type { Doc } from './runtime/types/Doc.ts'
+import type { Patch } from './runtime/types/Patch.ts'
 import type { SyncTransport } from './types/SyncTransport.ts'
 
 /*
@@ -17,20 +18,25 @@ this core). Returns a disposer.
 */
 // @documentation plumbing
 export function sync(doc: Doc, transport: SyncTransport): () => void {
-    /* True only while applying a received patch, so its bus echo isn't re-sent. */
-    let applying = false
+    /* The specific inbound patches currently being applied — their own bus echo must not be
+       re-sent. Tracked by IDENTITY (not a blanket `applying` flag): `doc.apply` emits the
+       patch on the bus inside its batch, then flushes effects on batch exit while still
+       synchronously inside this apply. A local effect that writes the doc in reaction emits
+       a DIFFERENT patch during that flush — a genuine new local change peers need — which a
+       blanket flag would wrongly suppress, diverging peers permanently. */
+    const applyingPatches = new Set<Patch>()
 
     const unsubscribeInbound = transport.subscribe((patch) => {
-        applying = true
+        applyingPatches.add(patch)
         try {
             doc.apply(patch)
         } finally {
-            applying = false
+            applyingPatches.delete(patch)
         }
     })
 
     const unsubscribeBus = PATCH_BUS.subscribe((event) => {
-        if (event.doc === doc && !applying) {
+        if (event.doc === doc && !applyingPatches.has(event.patch)) {
             transport.send(event.patch)
         }
     })

package/src/lib/ui/tryEncodeResume.ts

@@ -1,5 +1,5 @@
 import { encodeRefJson } from '../shared/encodeRefJson.ts'
-import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
 
 /* ref-json-encode an await-resume entry, or `undefined` if it can't be serialized.
    encodeRefJson is total (cycles become back-references, functions fold to undefined),
@@ -7,10 +7,7 @@ import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
    entry and warn, so the client re-runs that one branch's promise while every other
    branch stays seeded. Shared by the streaming (`renderToStream`) and buffered/seed
    (`resumeSeedScript`) paths so the serialize-or-refetch policy lives in one place. */
-export function tryEncodeResume(
-    entry: ResumeEntry | DeferMarker,
-    id: number | string,
-): string | undefined {
+export function tryEncodeResume(entry: ResumeEntry, id: number | string): string | undefined {
     try {
         return encodeRefJson(entry)
     } catch (cause) {

package/src/lib/ui/types/Scope.ts

@@ -7,18 +7,22 @@ import type { SyncTransport } from './SyncTransport.ts'
 
 /*
 A lexical scope: the unit that owns a region's reactive data, its lifetime, and
-the capabilities applied to it. Its data surface MIRRORS `Doc` (read/replace/add/
-remove/derive/apply/snapshot) so the compiler can target a scope as a
-component's data binding directly. It nests (`child`/`root`), passes values
-down the tree as context (`share`/`shared`), and carries the capability surface as
-methods so a scope is a passable value: `<Child parentScope={scope} />`.
+the capabilities applied to it. This is the INTERNAL shape — the compiler's lowering
+host and the runtime object; it is no longer the author surface. The author reactive
+surface is the imported `state`/`state.linked`/`state.computed`/`effect` (see
+`state.ts`); the compiler resolves those import bindings and lowers each onto this
+scope (`$$scope().derive`/`.linked`/`.effect`, `state.share`/`.shared` → `share`/
+`shared`). The data surface MIRRORS `Doc` (read/replace/add/remove/derive/apply/
+snapshot) so the compiler can target a scope as a component's data binding directly;
+it nests (`child`/`root`) and passes values down the tree as context (`share`/`shared`).
 
+The reactive primitives and capabilities remain on this internal shape because the
+lowered runtime calls them (`$$scope().linked(...)`, generated undo/persist) — they are
+withdrawn from the AUTHOR-facing public surface (docs/examples), not the runtime object.
 Capabilities route where the scope's changes go: `record()` to an undo journal,
-`persist()` to durable storage, `broadcast()` to peers — declared once, then
-`undo`/`redo` act on a recorded scope. `id` is the scope's identity for the
-boundary-crossing capabilities — `persist()` defaults its key to it. `scope()` is the only user-facing public entry; `effect` is also exported
-but only for generated binding code and the SSR strip (tagged plumbing). The
-`history`/`persist`/`sync` helpers it composes are internal.
+`persist()` to durable storage, `broadcast()` to peers — declared once, then `undo`/
+`redo` act on a recorded scope. The `history`/`persist`/`sync` helpers it composes are
+internal.
 */
 export type Scope = {
     readonly id: string

package/src/lib/ui/watch.ts

@@ -0,0 +1,140 @@
+import { cache } from '../shared/cache.ts'
+import { REMOTE_FUNCTION } from '../shared/REMOTE_FUNCTION.ts'
+import type { CacheOnContext } from '../shared/types/CacheOnContext.ts'
+import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
+import type { Subscribable } from '../shared/types/Subscribable.ts'
+import { effect } from './effect.ts'
+import { generationGuard } from './runtime/generationGuard.ts'
+import type { EffectResult } from './runtime/types/EffectResult.ts'
+import type { State } from './runtime/types/State.ts'
+
+/*
+The single reaction primitive: `watch(source, handler)` names its trigger and runs
+`handler` with the source's new value whenever it changes. It unifies three
+previously-separate things — the author `effect`, `socket.on`, and `cache.on` —
+and it is also the compiler's binding primitive (emitted as `$$watch(thunk)` for
+`{expr}` / `class:` / `bind:*`). Client-only: SSR-inert here and stripped by the
+compiler. Returns a scope-tied disposer.
+
+Instance sugar mirrors the global for the two subscribable/rpc sources (the other
+sources have no instance home): `socket.watch(handler)` ≡ `watch(socket, handler)`, and
+`getUser.watch(handler)` / `getUser.watch(args, handler)` ≡ `watch(getUser, …)`. The
+method is client-attached (socketProxy / remoteProxy) so this ui primitive never rides
+into a server bundle; server-side it is an inert no-op. Unlike bare `watch(…)` — which
+the SSR back-end strips — a `.watch(…)` member call survives to the server and relies on
+that inert stub.
+
+Sources (discriminated at runtime, monomorphic per branch):
+  watch(thunk)                       // compiler binding form — auto-tracked, == effect(thunk)
+  watch(count, n => …)               // a state cell → handler(newValue)
+  watch([a, b], vals => …)           // multiple cells → fires on any change
+  watch(socket, frame => …)          // a subscribable → handler per frame (cache.on loop)
+  watch(getUser, user => …)          // an rpc → runs the smart read, handler(resolved value)
+  watch(getUser, args, user => …)    // an rpc with args
+*/
+// @documentation reactive-state
+export function watch(thunk: () => EffectResult): () => void
+export function watch<T>(source: State<T>, handler: (value: T) => void): () => void
+export function watch(
+    sources: ReadonlyArray<State<unknown>>,
+    handler: (values: unknown[]) => void,
+): () => void
+export function watch<Frame>(
+    source: Subscribable<Frame>,
+    handler: (frame: Frame, context: CacheOnContext) => void | Promise<void>,
+): () => void
+export function watch<Args, Return>(
+    fn: RemoteFunction<Args, Return>,
+    handler: (value: Return) => void,
+): () => void
+export function watch<Args, Return>(
+    fn: RemoteFunction<Args, Return>,
+    args: Args,
+    handler: (value: Return) => void,
+): () => void
+export function watch(
+    source: unknown,
+    argsOrHandler?: unknown,
+    maybeHandler?: unknown,
+): () => void {
+    /* Client lifecycle, exactly like the effect it wraps: no runtime window guard (that would
+       also silence the compiler's generated bindings, which build on the client where the test
+       DOM sets no global `window`). SSR-safety comes from the compiler stripping author
+       `watch(...)` calls, and the subscribable branch's own server guard (cache.on). */
+    /* Compiler binding form watch(thunk): a bare auto-tracked effect (== today's $$effect). */
+    if (argsOrHandler === undefined) {
+        return effect(source as () => EffectResult)
+    }
+    /* watch(fn, args, handler): an rpc selector with explicit args. */
+    if (maybeHandler !== undefined) {
+        return reactToRpc(source, argsOrHandler, maybeHandler as (value: unknown) => void)
+    }
+    const handler = argsOrHandler as (value: unknown, context?: CacheOnContext) => void
+    /* A subscribable (socket / stream): per-frame delivery with reconnect-replay — the
+       existing cache.on loop is the single implementation this branch delegates to. */
+    if (isSubscribable(source)) {
+        return cache.on(
+            source as Subscribable<unknown>,
+            handler as (frame: unknown, context: CacheOnContext) => void | Promise<void>,
+        )
+    }
+    /* An rpc without args → run the smart read reactively, pipe its value to the handler. A
+       RemoteFunction is a callable, so accept `function` too — a state cell is a branded-free
+       object and never matches, and a streaming rpc was already caught by isSubscribable above. */
+    if (
+        source !== null &&
+        (typeof source === 'object' || typeof source === 'function') &&
+        REMOTE_FUNCTION in source
+    ) {
+        return reactToRpc(source, undefined, handler)
+    }
+    /* Multiple cells → fire on any change; hand the handler the current values. */
+    if (Array.isArray(source)) {
+        const cells = source as ReadonlyArray<State<unknown>>
+        return effect(() => {
+            const values = cells.map((cell) => cell.value)
+            handler(values)
+        })
+    }
+    /* A single state cell → handler(newValue) on change. */
+    const cell = source as State<unknown>
+    return effect(() => {
+        handler(cell.value)
+    })
+}
+
+/* True for a socket / rpc stream — anything async-iterable. */
+function isSubscribable(source: unknown): boolean {
+    return (
+        source !== null &&
+        (typeof source === 'object' || typeof source === 'function') &&
+        typeof (source as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function'
+    )
+}
+
+/*
+Reacts to an rpc's cached value: an effect that runs the smart read (subscribing
+its key synchronously, so the effect re-runs when the value changes — a refresh,
+a patch, an invalidate) and pipes the resolved value to the handler. Triggers the
+read, unlike peek: `watch` observes a live query, so it keeps it flowing.
+*/
+function reactToRpc(fn: unknown, args: unknown, handler: (value: unknown) => void): () => void {
+    const call = fn as (args: unknown) => Promise<unknown>
+    /* The bare call routes through cache.read (cache-managed flight, not scope-abortable), so
+       a slow flight can settle AFTER a faster re-run's flight OR after the owner tears down.
+       Guard the handler on the generation so only the current flight's value lands and a
+       post-teardown settle is dropped — a re-run renews, teardown bumps (both via the shared
+       generationGuard). */
+    const guard = generationGuard()
+    return effect(() => {
+        const generation = guard.renew()
+        void Promise.resolve(call(args)).then(
+            (value) => {
+                if (guard.live(generation)) {
+                    handler(value)
+                }
+            },
+            () => undefined,
+        )
+    })
+}

package/src/serverEntry.ts

@@ -29,12 +29,12 @@ import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { resolvePageSnapshot } from './lib/server/runtime/resolvePageSnapshot.ts'
+import { cacheStoreSlot } from './lib/shared/cacheStoreSlot.ts'
 import { createCacheStore } from './lib/shared/createCacheStore.ts'
+import { globalCacheStoreSlot } from './lib/shared/globalCacheStoreSlot.ts'
 import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
+import { pageSlot } from './lib/shared/pageSlot.ts'
 import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
-import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
-import { setGlobalCacheStoreResolver } from './lib/shared/setGlobalCacheStoreResolver.ts'
-import { setPageResolver } from './lib/shared/setPageResolver.ts'
 
 /*
 Resolve config into process.env before anything reads it (createServer reads
@@ -65,16 +65,16 @@ await import('./_virtual/config.ts')
 // In a bundle, tie this server's life to the launcher's (no-op standalone).
 exitWithParent()
 
-setCacheStoreResolver(() => requestContext.getStore()?.cache)
+cacheStoreSlot.resolver = () => requestContext.getStore()?.cache
 
-setPageResolver(resolvePageSnapshot)
+pageSlot.resolver = resolvePageSnapshot
 
 /*
 Process-level store for cache(fn, { global: true }) — one per server process,
 outlives every request so memoised external calls are shared across them.
 */
 const globalCacheStore = createCacheStore()
-setGlobalCacheStoreResolver(() => globalCacheStore)
+globalCacheStoreSlot.resolver = () => globalCacheStore
 
 await createServer({
     pages,

package/template/CLAUDE.md

@@ -14,7 +14,7 @@ at `node_modules/@abide/abide/README.md`.
 ## Conventions (see AGENTS.md for the full list)
 
 - One export per file, named after the file. No barrels — import each name by its
-  own path (`@abide/abide/server/GET`, `@abide/abide/shared/cache`, …).
+  own path (`@abide/abide/server/GET`, `@abide/abide/shared/refresh`, …).
 - RPCs live in `src/server/rpc/<name>.ts`; sockets in `src/server/sockets/`;
   pages are `**/page.abide`, layouts `**/layout.abide`.
 - Generated types land in `src/.abide/` — do not hand-edit them; run `abide dev`/

package/template/package.json

@@ -13,7 +13,7 @@
         "test": "bun test"
     },
     "dependencies": {
-        "@abide/abide": "^0.27.0"
+        "@abide/abide": "^0.46.0"
     },
     "devDependencies": {
         "@types/bun": "^1.3.14"

package/template/src/server/rpc/getHello.ts

@@ -25,9 +25,9 @@ dedupe). Other helpers are siblings, one per file: `abide/server/error`,
 `abide/server/redirect`, `abide/server/sse`, `abide/server/jsonl`.
 
 Every rpc value also exposes `.raw(args?)` (returns the underlying
-`Response`) and `.stream(args?)` (returns a `Subscribable` over the frames —
-feed it to `tail()`) for callers that need headers/status or want to iterate
-jsonl/sse frames.
+`Response`) for callers that need headers or status. A streaming rpc — a
+jsonl/sse handler — returns a `Subscribable` over the frames from its bare
+call (`fn(args)`); iterate it with `for await` or react to it with `watch(fn(args), frame => …)`.
 */
 
 import { GET } from '@abide/abide/server/GET'

package/template/src/ui/pages/page.abide

@@ -5,15 +5,15 @@ page.abide mounts at that folder's URL; the root layout.abide wraps it.
 
 The blocking await-block below (the `then` clause sits in the `{#await}` head)
 resolves on the server during SSR and renders inline — no pending placeholder. The
+bare rpc call IS the smart read: cached, coalesced, and reactive by default. The
 decoded body is captured into the per-request cache, serialized into the HTML, and
 replayed on the client during hydration with no second fetch. A `{:then}` *branch*
 instead would stream the resolution in out of order.
 */
-import { cache } from '@abide/abide/shared/cache'
 import { getHello } from '$server/rpc/getHello.ts'
 </script>
 
-{#await cache(getHello)() then hello}
+{#await getHello() then hello}
     <h1>{hello.message}</h1>
 {/await}
 <p>Edit <code>src/ui/pages/page.abide</code> and the page hot-reloads.</p>

package/template/test/app.test.ts

@@ -5,7 +5,7 @@ same wiring as `abide start`, no fixtures) and hands back the whole surface:
   app.fetch(path)        — pages and raw HTTP, origin + mount base resolved
   app.rpc.<name>(args)   — RPCs over the real pipeline (CSRF, cookies, base),
                            typed and decoded; .raw(args) for the Response
-  app.sockets.<name>     — a live Socket: iterate it, .tail(n), .publish(m)
+  app.sockets.<name>     — a live Socket: iterate it (for await), .peek(), .broadcast(m)
   app.health()           — the /__abide/health payload
 
 `app.rpc` / `app.sockets` are typed from your own RPCs and sockets — generated

package/src/lib/server/reachable.ts

@@ -1,45 +0,0 @@
-import { parseBoundedEnvInt } from '../shared/parseBoundedEnvInt.ts'
-import { createReachable } from './runtime/createReachable.ts'
-
-/*
-Server-only outbound reachability for an external host. `await reachable(host)`
-HEADs the host's origin: the first call awaits a real probe (faithful — a down
-host costs the full timeout, an up host one handshake) and starts a background
-poll that re-probes every TTL, so every later call resolves instantly off the
-warm value, fresh within one TTL. A down host going down is caught within
-~failureLimit polls; recovery flips it back automatically.
-
-  if (!(await reachable('api.example.com'))) return error(503)
-
-A bare host defaults to https; pass an explicit http://… for a non-TLS host.
-Answers "can I connect to this host," NOT "is my endpoint healthy": any
-completed HTTP response (even 4xx/5xx, even a 405 to HEAD) counts as reachable;
-only a connection failure or timeout reads as unreachable. There is no ambient
-server-side connectivity signal, so this is the honest way to fail a doomed
-outbound call fast — see online() for the inbound/client-reported counterpart.
-
-ABIDE_REACHABLE_TTL (poll cadence / freshness, ms) and ABIDE_REACHABLE_TIMEOUT
-(per-HEAD bound, ms) tune the defaults; the timeout is deliberately generous so
-a healthy-but-distant host over a slow link is not mis-read as down.
-*/
-const TTL_MS = parseBoundedEnvInt(process.env.ABIDE_REACHABLE_TTL, 1_000, 600_000) ?? 30_000
-const TIMEOUT_MS = parseBoundedEnvInt(process.env.ABIDE_REACHABLE_TIMEOUT, 100, 60_000) ?? 3_000
-/* Stop polling a host nobody has read in a few TTLs; the next read restarts it cold. */
-const IDLE_MS = TTL_MS * 3
-
-/* Status-agnostic HEAD: a completed response proves connectivity; reject/timeout does not. */
-async function probeOrigin(origin: string): Promise<boolean> {
-    try {
-        await fetch(origin, { method: 'HEAD', signal: AbortSignal.timeout(TIMEOUT_MS) })
-        return true
-    } catch {
-        return false
-    }
-}
-
-// @documentation observability
-export const reachable = createReachable({
-    probe: probeOrigin,
-    intervalMs: TTL_MS,
-    idleMs: IDLE_MS,
-}).reachable

package/src/lib/server/sockets/types/Socket.ts

@@ -1,23 +0,0 @@
-import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
-import type { TailHooks } from '../../../shared/types/TailHooks.ts'
-
-/*
-Bidirectional named broadcast primitive. Declared once with `socket<T>()`
-inside a file under `src/server/sockets/`; the same import resolves to a server-side
-fan-out and a client-side ws proxy by build target. Iterating the socket
-is the live stream — no replay. `.tail(count)` opens a subscription seeded
-with the last `count` frames of the retained tail (declared via
-`{ tail: n }`; no-arg = the whole retained tail) before going live — the
-optional Subscribable retention capability the reactive `tail()` consumer
-seeds from. `publish` is isomorphic: server code publishes in-process
-and fans out to remote subscribers; client code sends a `pub` frame the
-dispatcher validates against the topic's `clientPublish` flag. `clients`
-exposes which adapter surfaces (browser / mcp / cli) advertise this
-socket.
-*/
-export interface Socket<T> extends AsyncIterable<T> {
-    readonly name: string
-    readonly clients: ClientFlags
-    publish(message: T): void
-    tail(count?: number, hooks?: TailHooks): AsyncIterable<T>
-}

package/src/lib/shared/CACHE_WRAPPED.ts

@@ -1,9 +0,0 @@
-/*
-Brand on the invoker cache() returns; its property value is the wrapped fn,
-so inspection shows what a wrapper wraps. Detection is certain (set by us,
-never heuristic), which is why misuse throws instead of warning: a wrapper
-used as a selector matches nothing (no url/method, no producer id), and
-without detection a re-wrapped wrapper would silently downgrade a remote to
-an anonymous producer (no url/method, no shared key, no SSR snapshot).
-*/
-export const CACHE_WRAPPED: unique symbol = Symbol('abide.cacheWrapped')

package/src/lib/shared/baseResolver.ts

@@ -1,10 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-
-/*
-The mount-base slot/resolver/reader bundle. The server entry installs an
-APP_URL-derived resolver at boot; the client entry one reading
-window.__SSR__.base. No lazy fallback creator — `fallback` is a plain string set
-directly by isolated tests, and basePath() supplies the '' default. baseSlot /
-basePath re-export the slot and reader; setBaseResolver the setter.
-*/
-export const baseResolver = createResolverSlot<string>()

package/src/lib/shared/cacheKeyOf.ts

@@ -1,7 +0,0 @@
-import { cacheKeyStore } from './cacheKeyStore.ts'
-
-/* The store key behind a cache() read's promise, or undefined if it carries none
-   (a producer read, a raw Response read, or a non-cache promise). */
-export function cacheKeyOf(promise: Promise<unknown>): string | undefined {
-    return cacheKeyStore.get(promise)
-}

package/src/lib/shared/cacheKeyStore.ts

@@ -1,8 +0,0 @@
-/*
-WeakMap recording the cache key behind a `cache()` read's returned promise, so a
-consumer holding only the promise can recover its key. Mirrors remoteMetaStore (which
-records the synthesized Request the same way). The SSR resume path uses it to decide
-whether a `{#await cache()}` value is a large cache-backed read it can defer — shipping a
-`{ defer, key }` marker instead of the value. Collected with the promise.
-*/
-export const cacheKeyStore = new WeakMap<Promise<unknown>, string>()