@abide/abide 0.28.0

package/src/lib/shared/streamResponse.ts

@@ -0,0 +1,169 @@
+import { decodeResponse } from './decodeResponse.ts'
+import { HttpError } from './HttpError.ts'
+import { jsonlErrorFrame } from './jsonlErrorFrame.ts'
+import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
+import { sseErrorFrame } from './sseErrorFrame.ts'
+
+/*
+Turns a Response into an AsyncIterable of frames, regardless of the
+handler's chosen body format. Shared by `fn.stream(args)` (via
+subscribableFromResponse), the CLI's streaming print path, and the MCP
+tool dispatcher's stream drain — so every surface consumes sse/jsonl
+identically. Three shapes are handled:
+
+- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
+  each event. The `event: error\ndata: {message}` frame the `sse()`
+  helper emits on generator throws is mapped back to a thrown Error so
+  consumers see the failure mid-iteration.
+- application/jsonl + application/x-ndjson: emits one JSON value per
+  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
+  emits on generator throws is likewise re-thrown.
+- everything else: one-shot — yields the Content-Type-decoded body
+  once, then completes. Lets callers iterate uniformly on every rpc
+  handler, not just the streaming ones.
+
+Non-2xx responses surface as a thrown HttpError on the first pull,
+mirroring the plain `fn(args)` decode path.
+*/
+export function streamResponse<T>(response: Response): AsyncIterable<T> {
+    if (!response.ok) {
+        return errorIterable<T>(new HttpError(response))
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.startsWith('text/event-stream')) {
+        return parseSse<T>(response)
+    }
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        return parseJsonLines<T>(response)
+    }
+    return oneShot<T>(response)
+}
+
+/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
+// biome-ignore lint/correctness/useYield: throws on first pull; the generator shape is intentional so callers iterate it uniformly
+async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
+    throw error
+}
+
+/*
+One-shot iterator over a non-streaming Response: decodes the body once
+via the same Content-Type sniffing the plain call uses, yields it, then
+completes. Makes streaming symmetrical across streaming and
+non-streaming handlers — callers can pick the iteration shape without
+worrying about which body the handler returned.
+*/
+async function* oneShot<T>(response: Response): AsyncGenerator<T> {
+    yield (await decodeResponse(response)) as T
+}
+
+/*
+Reads a streaming text Response and yields raw frame strings split on
+`delimiter` (`\n\n` for SSE events, `\n` for JSON lines). Owns the whole
+buffering lifecycle: incremental decode, amortised-O(n) compaction, a
+final flush of the trailing partial frame, and reader cancellation when
+the consumer stops iterating (the generator's `finally` runs on
+`return()`). The SSE and jsonl parsers layer their per-frame parsing on
+top of this single machine so the two can't drift.
+*/
+async function* frameReader(response: Response, delimiter: string): AsyncGenerator<string> {
+    const body = response.body
+    if (!body) {
+        return
+    }
+    const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+    let buffer = ''
+    let bufferStart = 0
+    try {
+        while (true) {
+            const { value, done } = await reader.read()
+            if (done) {
+                if (bufferStart < buffer.length) {
+                    yield buffer.slice(bufferStart)
+                }
+                return
+            }
+            /*
+            Compact only when the unread region is small relative to the
+            consumed prefix — keeps amortised work O(n) instead of
+            quadratic slicing per frame boundary.
+            */
+            if (bufferStart > buffer.length / 2) {
+                buffer = buffer.slice(bufferStart) + value
+                bufferStart = 0
+            } else {
+                buffer += value
+            }
+            let boundary = buffer.indexOf(delimiter, bufferStart)
+            while (boundary !== -1) {
+                yield buffer.slice(bufferStart, boundary)
+                bufferStart = boundary + delimiter.length
+                boundary = buffer.indexOf(delimiter, bufferStart)
+            }
+        }
+    } finally {
+        await reader.cancel().catch(() => undefined)
+    }
+}
+
+/*
+SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
+frame. The error sentinel (`sseErrorFrame`) the `sse()` helper emits on a
+generator throw is surfaced as a thrown Error so consumer loops can react
+to mid-stream failure rather than silently stopping.
+*/
+async function* parseSse<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n\n')) {
+        const frame = parseFrame(raw)
+        if (!frame) {
+            continue
+        }
+        const errorMessage = sseErrorFrame.decode(frame.event, frame.data)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield JSON.parse(frame.data) as T
+    }
+}
+
+function parseFrame(raw: string): { event: string; data: string } | undefined {
+    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
+    if (lines.length === 0) {
+        return undefined
+    }
+    let event = 'message'
+    const dataLines: string[] = []
+    for (const line of lines) {
+        const colon = line.indexOf(':')
+        const field = colon === -1 ? line : line.slice(0, colon)
+        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+        if (field === 'event') {
+            event = value
+        } else if (field === 'data') {
+            dataLines.push(value)
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined
+    }
+    return { event, data: dataLines.join('\n') }
+}
+
+/*
+JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
+value. The error sentinel (`jsonlErrorFrame`) the `jsonl()` helper emits as
+a trailing line on a generator throw is surfaced here as a thrown Error so
+consumer loops can react to mid-stream failure.
+*/
+async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n')) {
+        if (raw.length === 0) {
+            continue
+        }
+        const parsed = JSON.parse(raw)
+        const errorMessage = jsonlErrorFrame.decode(parsed)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield parsed as T
+    }
+}

package/src/lib/shared/stripImport.ts

@@ -0,0 +1,27 @@
+/*
+Strips the user's `import { … } from '<moduleName>'` declaration from a
+module source. Used by the $rpc / $sockets rewriters to remove the
+verb / `socket` import after its call site has been replaced by the
+runtime-injected binding (defineVerb / defineSocket). Without this
+strip the dead import would still side-effect-load the verb/socket
+helper module into the server bundle for every $rpc / $sockets file.
+
+The braced body is `[^}]*` rather than `[\s\S]*?` so the lazy match
+can't backtrack across a `}` and accidentally swallow a preceding
+import whose `from` clause doesn't match (e.g. stripping
+`import { GET } from '@abide/abide/server/GET'` from a file that also has
+`import { json } from '@abide/abide/server/json'` on the line above). `[^}]`
+includes newlines, so multi-line braced imports like
+  import {
+    GET,
+  } from '@abide/abide/server/GET'
+still match — the body just can't contain another `}` to bound it.
+*/
+export function stripImport(source: string, moduleName: string): string {
+    const escaped = moduleName.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')
+    const pattern = new RegExp(
+        `^\\s*import\\s*\\{[^}]*\\}\\s*from\\s*['"]${escaped}['"]\\s*;?\\s*$`,
+        'gm',
+    )
+    return source.replace(pattern, '')
+}

package/src/lib/shared/subscribableFromResponse.ts

@@ -0,0 +1,51 @@
+import { streamResponse } from './streamResponse.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Builds the Subscribable returned by `fn.stream(args)`. The carried
+`name` is the cache-style key for (method, url, args) so tail()
+dedupes multiple readers of identical args into one underlying
+fetch. The fetch is deferred until the first iterator pull so
+constructing the Subscribable (which happens on every $derived
+re-evaluation) doesn't open a connection — tail()'s registry
+short-circuits the second instance before it iterates.
+*/
+export function subscribableFromResponse<T>(
+    name: string,
+    fetchResponse: () => Promise<Response>,
+): Subscribable<T> {
+    return {
+        name,
+        [Symbol.asyncIterator]() {
+            let inner: AsyncIterator<T, void, undefined> | undefined
+            let cancelled = false
+            return {
+                async next() {
+                    if (cancelled) {
+                        return { value: undefined, done: true }
+                    }
+                    if (!inner) {
+                        const response = await fetchResponse()
+                        inner = streamResponse<T>(response)[Symbol.asyncIterator]()
+                        /*
+                        If return() landed while we were awaiting the
+                        fetch, `inner` was still undefined then so its
+                        reader was never cancelled — release the body now
+                        rather than leaving the HTTP stream open.
+                        */
+                        if (cancelled) {
+                            await inner.return?.(undefined)
+                            return { value: undefined, done: true }
+                        }
+                    }
+                    return inner.next()
+                },
+                async return() {
+                    cancelled = true
+                    await inner?.return?.(undefined)
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}

package/src/lib/shared/tailProbeSlot.ts

@@ -0,0 +1,16 @@
+/*
+Internal slot the browser tail() registry registers its prober into, so the
+shared probes (pending / refreshing) can answer for Subscribables without
+shared/ importing browser/. The prober taps the registry's lifecycle channel
+(reactive inside $derived / $effect) and reports one stream by source name —
+spanning its latest-wins and window entries — or, with no name, whether any
+registered stream matches. When no prober is registered (server render, or
+tail was never imported) the probes fall back to the same answers tail()
+itself gives on the server: a named stream has no value yet (pending true),
+and nothing is reconnecting (refreshing false).
+*/
+export const tailProbeSlot: {
+    probe: ((name?: string) => { pending: boolean; refreshing: boolean }) | undefined
+} = {
+    probe: undefined,
+}

package/src/lib/shared/toBunRoutePattern.ts

@@ -0,0 +1,28 @@
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+Translates a abide route URL (`/media/[id]/[...rest]`) into the pattern Bun
+needs (`/media/:id/*`) for `Bun.serve({ routes })`. Returns the catch-all
+segment's original name alongside so the server can rename Bun's `*` param
+back to that name on the way out, keeping page-prop destructuring consistent
+with the route file path.
+*/
+export function toBunRoutePattern(routeUrl: string): {
+    pattern: string
+    catchAllName: string | undefined
+} {
+    let catchAllName: string | undefined
+    const pattern = parseRouteSegments(routeUrl)
+        .map((segment) => {
+            if (segment.kind === 'literal') {
+                return segment.value
+            }
+            if (segment.catchAll) {
+                catchAllName = segment.name
+                return '*'
+            }
+            return `:${segment.name}`
+        })
+        .join('/')
+    return { pattern, catchAllName }
+}

package/src/lib/shared/toScopeSet.ts

@@ -0,0 +1,4 @@
+/* Normalizes a scope option (one tag or many) to a Set for O(1) membership. */
+export function toScopeSet(scope: string | string[]): Set<string> {
+    return new Set(typeof scope === 'string' ? [scope] : scope)
+}

package/src/lib/shared/trace.ts

@@ -0,0 +1,16 @@
+import { formatTraceparent } from './formatTraceparent.ts'
+import { requestScopeSlot } from './requestScopeSlot.ts'
+
+/*
+The current request's W3C `traceparent`, or undefined outside any request
+scope (boot scripts, build, background work). Isomorphic: the server resolves
+it from the ALS request scope, the browser from the trace stamped into
+__SSR__ — so a client-side read returns the trace of the request that
+rendered the page. The string is propagation-ready: hand it to your own logs,
+error reports, or `propagation.extract` when attaching OpenTelemetry spans.
+*/
+// @readme observability
+export function trace(): string | undefined {
+    const scope = requestScopeSlot.resolver?.()
+    return scope ? formatTraceparent(scope.trace) : undefined
+}

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

@@ -0,0 +1,84 @@
+/*
+Stored shape per cache key. The stored promise resolves to the raw Response for
+a remote function (the snapshot reads its status/headers/body and the cache
+layer hands callers a decoded view derived from it) or to the producer's value
+for a plain producer — hence `Promise<unknown>`.
+
+`request` is retained for remote entries so SSR snapshot serialization can
+record the URL and method without re-deriving them from the function. Producer
+entries have no wire request, so it is absent — and the snapshot readers skip
+any entry lacking it (a producer value has no rpc identity to rehydrate against).
+
+`ttl`/`expiresAt` drive eviction: expiresAt = undefined means "no TTL" (lives
+forever); ttl = 0 means "dedupe only" (entry is pruned as soon as the promise
+settles).
+
+`value` is the decoded warm value served synchronously by the read path
+(cloned per read). It is set at hydration — the SSR snapshot body is
+pre-decoded so the first client render reads it without a microtask hop and
+byte-matches the SSR DOM — and also by cache.on's `context.patch`, which folds
+an authoritative frame delta straight onto it without a refetch (ADR-0007).
+Live fetches leave it undefined and take the async decode path until a patch
+populates it.
+
+`hydrated` marks an entry built from the SSR snapshot, which ships no wrap
+options — the first read consumes the flag and adopts its call site's `ttl`
+(omitted = forever, as shipped; ttl > 0 = expiry clock starts at that read;
+ttl = 0 = the warm value exists only to complete the hydration render and is
+evicted a macrotask later). Live entries never carry it; their ttl was fixed
+at registration.
+
+`scope` holds the cache() call's scope tags as a Set so
+`cache.invalidate({ scope })` can drop every entry sharing any tag with O(1)
+membership; a re-read merges new tags in rather than replacing them.
+
+`settled` flips true once the stored promise resolves. SSR snapshot
+serialization reads it after `render()` returns to partition entries: ones
+settled by then were consumed via `await` (render blocked on them) and inline
+into `__SSR__`; ones still pending were consumed via `{#await}` (render emitted
+the pending branch without blocking) and stream a resolve chunk instead.
+
+`refreshing` flips true while this entry is reloading data it already held —
+either a policy stale-while-revalidate refetch (value still visible) or the
+default drop-then-reload (the prior entry was invalidated and dropped, this is
+its replacement read). It backs refreshing(), distinguishing a reload from a
+first-ever load; cleared when the read settles.
+
+`invalidation` holds an `invalidate` throttle/debounce policy: the refetch
+thunk (the call captured with its args) plus the policy and its runtime timer
+state, so invalidate() can rate-limit refetches of this key instead of dropping
+the entry and refetching on every invalidation. Set at registration when the
+creating read declared a policy, or attached by a later read declaring one on
+an entry that lacks it (hydrated snapshot entries always start without one) —
+first policy wins. An armed `timer` is cleared if the entry is evicted, so a
+dead key never refetches. Wrap-time validation guarantees a policy never
+coexists with ttl: 0 and never sits on a non-replayable remote method.
+*/
+export type CacheEntry = {
+    key: string
+    promise: Promise<unknown>
+    request?: Request
+    ttl: number | undefined
+    expiresAt: number | undefined
+    value?: unknown
+    scope?: Set<string>
+    settled?: boolean
+    hydrated?: boolean
+    refreshing?: boolean
+    invalidation?: InvalidationState
+}
+
+/* Per-key invalidate coalescing: the throttle/debounce policy plus the timer/in-flight state. */
+type InvalidationState = {
+    refetch: () => Promise<unknown>
+    throttle?: number
+    debounce?: number
+    lastFiredAt?: number
+    timer?: ReturnType<typeof setTimeout>
+    /*
+    An invalidation that arrived while a refetch was already in flight: fireRefetch
+    can't run concurrently, so it records the request here and re-schedules once the
+    in-flight refetch settles, rather than dropping the newer invalidation.
+    */
+    pending?: boolean
+}

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

@@ -0,0 +1,9 @@
+/*
+Detail payload of the cache store's 'invalidate' event — the set of cache
+keys one invalidation touched. A Set so each subscriber's membership check
+is O(1) regardless of how many keys a single invalidate spans. Shared
+between both dispatchers (cache.invalidate + streamed-resolution settling)
+and the cache store's listener, so the event's shape has one definition
+instead of an inline cast repeated at every site.
+*/
+export type CacheInvalidation = Set<string>

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

@@ -0,0 +1,25 @@
+import type { CacheSelector } from './CacheSelector.ts'
+
+/*
+Capabilities handed to a cache.on handler — exactly what behaves differently
+inside a binding. `invalidate` is the binding-scoped copy of cache.invalidate
+(same selector grammar, same effect): calls through it are recorded in the
+binding's coverage set by function identity, so attribution survives awaits
+and the coverage replays after a reconnect gap; the global cache.invalidate
+still works inside a handler but is not covered. `patch` folds an
+authoritative delta carried by the frame into the matching cached entries
+without a refetch (ADR-0007) — `updater` maps the current decoded value to the
+next; it resolves to the touched keys and is covered for reconnect resync the
+same way (the gap re-invalidates, since a delta can't be replayed). Await it to
+keep deltas ordered under sequential delivery. `signal` aborts when the binding
+is disposed, so an async handler mid-flight can bail or cancel its own fetches.
+*/
+export type CacheOnContext = {
+    invalidate: <Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args) => void
+    patch: <Args, Return>(
+        arg: CacheSelector<Args, Return>,
+        updater: (current: Return) => Return,
+        args?: Args,
+    ) => Promise<string[]>
+    signal: AbortSignal
+}

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

@@ -0,0 +1,39 @@
+/*
+Options for cache(). The key is always auto-derived (method+url+args for a remote
+function, producer-reference+args for a plain producer): hoist a producer to a
+stable reference to share its entry across calls. `ttl` is the
+milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
+dedupe only (entry dropped once the promise settles — the mutation idiom:
+in-flight coalescing and pending() visibility, nothing retained), any other
+number = TTL.
+`scope` is one or more free-form tags grouping unrelated calls so one
+`cache.invalidate({ scope })` drops every entry sharing any of them — pass an
+array when a call belongs to multiple invalidation groups. A unique tag (e.g. a
+uuid) shared by a set of calls gives them their own private invalidation group.
+
+`global` opts the entry into the process-level store instead of the default
+request-scoped one (server) — so a value computed in one request is reused by
+later requests, e.g. memoising an external endpoint the server calls. Omit it
+for per-request data: the default keeps a per-user response from leaking across
+requests. Write only `global: true`; there is no `false` form. On the client
+there is a single tab store, so the flag is a no-op there.
+
+`invalidate` controls how a `cache.invalidate` hit on this key is applied, in ms.
+`{ throttle: N }` refetches on the leading edge then at most once per N ms while
+invalidations keep arriving; `{ debounce: N }` refetches only after N ms of
+quiet. Both coalesce a burst of invalidations (e.g. a socket spraying
+`cache.invalidate`) into far fewer calls and keep serving the existing (stale)
+value until the refetch resolves — stale-while-revalidate. They affect only the
+refetch-after-invalidate; the first fetch and arg-change fetches stay immediate.
+A policy declares the call safe to re-run unprompted: cache() throws at wrap
+time on both set at once, on ttl: 0 (nothing retained, nothing to revalidate),
+and on a non-replayable remote method (replaying a write is a state change
+disguised as a refresh). Producers are uncheckable — declare a policy only on
+a producer that is a pure read.
+*/
+export type CacheOptions = {
+    ttl?: number
+    scope?: string | string[]
+    global?: boolean
+    invalidate?: { throttle?: number; debounce?: number }
+}

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

@@ -0,0 +1,17 @@
+import type { CacheOptions } from './CacheOptions.ts'
+import type { RawRemoteFunction } from './RawRemoteFunction.ts'
+import type { RemoteFunction } from './RemoteFunction.ts'
+
+/*
+Selector grammar shared by cache.invalidate(), pending(), and refreshing():
+  undefined   → every entry
+  remote fn   → that function's calls (method+url prefix); fn and fn.raw match
+                the same set since they share wire identity
+  producer fn → that producer's calls (reference-id prefix)
+  { scope }   → any entry sharing one of the requested scope tags
+*/
+export type CacheSelector<Args, Return> =
+    | RemoteFunction<Args, Return>
+    | RawRemoteFunction<Args>
+    | ((args?: Args) => Promise<Return>)
+    | Pick<CacheOptions, 'scope'>

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

@@ -0,0 +1,16 @@
+import type { CacheEntry } from './CacheEntry.ts'
+import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
+
+/*
+The SSR partition of a request's cache, read after `render()` returns.
+`inline` are entries settled by then (consumed via `await`, so render blocked
+on them) — they ship in the first chunk's `__SSR__` blob. `pending` are
+GET/DELETE entries still in flight (consumed via `{#await}`, which render emits
+as a pending branch without blocking) — the streamer awaits each and pushes a
+`__abideResolve` chunk as it lands. Non-GET/DELETE pending entries are dropped:
+they can't be snapshotted, so the client re-fetches them live on cache miss.
+*/
+export type CacheSnapshot = {
+    inline: CacheSnapshotEntry[]
+    pending: CacheEntry[]
+}

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

@@ -0,0 +1,17 @@
+import type { ReplayableMethod } from './ReplayableMethod.ts'
+
+/*
+Wire format for a single cached response shipped from SSR to client hydration.
+Only replayable entries (see REPLAYABLE_METHODS) with a textual Content-Type
+are emitted — writes must not re-fire from a snapshot, and binary bodies don't
+survive a JSON round-trip.
+*/
+export type CacheSnapshotEntry = {
+    key: string
+    url: string
+    method: ReplayableMethod
+    status: number
+    statusText: string
+    headers: Array<[string, string]>
+    body: string
+}

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

@@ -0,0 +1,13 @@
+/*
+Per-store cache read tallies, frozen into the request's closing log record at
+settle. hit = a read served from a settled retained entry (including the warm
+SSR sync path); coalesced = a read that joined an in-flight call; miss = a
+read that invoked its producer/remote. Reads against the process-level global
+store count into the requesting scope's store, so a request's record reflects
+everything that request asked the cache for.
+*/
+export type CacheStats = {
+    hits: number
+    misses: number
+    coalesced: number
+}

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

@@ -0,0 +1,39 @@
+import type { CacheEntry } from './CacheEntry.ts'
+import type { CacheStats } from './CacheStats.ts'
+
+/*
+Cache map paired with a reactive per-key subscriber. Calling
+`subscribe(key)` from inside a tracking scope (derived / effect) registers
+that scope to re-run when the entry is invalidated; called outside tracking
+it's a no-op. Subscribers live for the lifetime of the store: the server
+uses a fresh store per request (so subscribers die with the response), the
+client uses a single module-level store (so subscribers persist for the tab).
+
+`trackLifecycle`/`markLifecycle` are the probes' lifecycle channels, scoped
+by selector prefix. `trackLifecycle(prefix)` taps a channel keyed to that
+fn selector's entries (see selectorPrefix), so a `pending(fn)` reader
+re-derives only when fn's calls change state; `trackLifecycle()` taps the
+store-wide channel — bare and scope selectors scan many entries, so they
+(deliberately) wake on every event. `markLifecycle(key)` — fired whenever a
+call starts, settles, is evicted, or is invalidated — marks the store-wide
+channel plus every probed prefix channel owning `key`.
+*/
+export type CacheStore = {
+    entries: Map<string, CacheEntry>
+    events: EventTarget
+    subscribe: (key: string) => void
+    trackLifecycle: (keyPrefix?: string) => void
+    markLifecycle: (key?: string) => void
+    /*
+    Keys dropped by a (policy-less) invalidate, awaiting their next read. The
+    drop erases the entry, so the next cache() call is a cold miss with no memory
+    it followed an invalidate; this set carries that signal across the gap so the
+    replacement entry is flagged a reload (refreshing() true) rather than a
+    first-ever load. Consumed when that entry is created; a key invalidated but
+    never re-read just lingers (bounded by distinct such keys; the server's
+    request-scoped store discards it with the response).
+    */
+    pendingRefresh: Set<string>
+    /* Read tallies for the closing log record + Server-Timing; see CacheStats. */
+    stats: CacheStats
+}

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

@@ -0,0 +1,13 @@
+/*
+The log shape a channel returns — the same callable + levels + trace as the
+root logger, every record tagged with the channel name and emitted only when
+DEBUG matches it. Levels are presentation, never gates: a channeled warn is
+yellow when the channel is on and silent when it's off.
+*/
+export type ChannelLog = {
+    (message: string, data?: unknown): void
+    warn(message: string, data?: unknown): void
+    error(value: unknown, data?: unknown): void
+    /* Times `work`, logs `name` with the duration at settle; rethrows failures. */
+    trace<Return>(name: string, work: () => Return | Promise<Return>): Promise<Return>
+}

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

@@ -0,0 +1,11 @@
+/*
+Which client surfaces a verb or socket is exposed to. Browser is the
+historical default; MCP and CLI flip on automatically when the
+declaration carries a Standard Schema (the schema is what makes the
+non-browser surfaces safe to advertise). Explicit values always win.
+*/
+export type ClientFlags = {
+    browser: boolean
+    mcp: boolean
+    cli: boolean
+}

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

@@ -0,0 +1,6 @@
+export type CompileTarget =
+    | 'bun-darwin-arm64'
+    | 'bun-darwin-x64'
+    | 'bun-linux-arm64'
+    | 'bun-linux-x64'
+    | 'bun-windows-x64'

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

@@ -0,0 +1,13 @@
+import type { Log } from './Log.ts'
+
+/*
+The framework's internal voice — the public Log shape bound to the always-on
+'abide' channel, plus the CLI/build styling voices: info (plain message),
+success (green), detail (dim secondary text). Internal only; apps speak
+through their own channel via the public log.
+*/
+export type FrameworkLog = Log & {
+    info(message: string): void
+    success(message: string): void
+    detail(message: string): void
+}

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

@@ -0,0 +1 @@
+export type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'

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

@@ -0,0 +1,9 @@
+/*
+The launcher/CLI-owned record of the last connection, kept in the data dir so it
+survives relaunch and is readable before any window or session opens. It records
+the *intent*, not a concrete embedded URL — an embedded server picks a fresh port
+each launch, so only `{ kind: 'embedded' }` is durable; a remote connection keeps
+its url. resolveLaunchTarget / resolveCliTarget read it; /connect and /start write
+it; /disconnect clears it.
+*/
+export type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }