@abide/abide 0.28.0

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

@@ -0,0 +1,13 @@
+import type { ChannelLog } from './ChannelLog.ts'
+
+/*
+The public logger: a ChannelLog on the app's own always-on channel (named
+after the app, so every record carries who spoke), plus the factory for
+DEBUG-gated diagnostic channels. Framework voices live on the internal
+abideLog; the closing request record is emitted via internal
+logClosingRecord — neither is part of this surface.
+*/
+export type Log = ChannelLog & {
+    /* Diagnostic channel: same shape, tagged with `name`, emits only when DEBUG matches. */
+    channel(name: string): ChannelLog
+}

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

@@ -0,0 +1,42 @@
+/*
+One log event, built once per emission and rendered by either formatter
+(tab-separated tsv line or ABIDE_LOG_FORMAT=json). The json rendering of these
+keys is a documented contract — ingestion pipelines (Splunk, Loki) extract
+fields by these names, so renames are breaking changes. Absent context is
+omitted, never null: trace/elapsedMs/method/path exist only inside a request
+scope, status/durationMs only on closing request records, name/spanId only on
+log.trace operation records, stack only when an Error was captured.
+*/
+export type LogRecord = {
+    /* Epoch ms; the json format renders it as an ISO timestamp. */
+    ts: number
+    level: 'info' | 'warn' | 'error'
+    msg: string
+    /* DEBUG-gated diagnostic channel that emitted this record. */
+    channel?: string
+    /* Full 32-hex trace id; tsv mode prints the first 8 chars. */
+    trace?: string
+    /* The emitting request's own trace span id (TraceContext.spanId). Stable across
+       every record one request emits, so a consumer can split a multi-request trace
+       (a propagated session) back into its individual requests. */
+    requestSpan?: string
+    /* The span this request descends from (TraceContext.parentSpanId); absent when
+       abide started the trace — the journey's root request. Lets a consumer nest
+       requests within a trace. */
+    parentSpan?: string
+    /* Ms since the request scope opened (navigation start in the browser). */
+    elapsedMs?: number
+    method?: string
+    path?: string
+    /* Structured payload passed as the second argument. */
+    data?: unknown
+    /* Closing request record: response status + total duration at settle. */
+    status?: number
+    durationMs?: number
+    /* Closing request record: the request's cache read tallies, frozen at settle. */
+    cache?: { hits: number; misses: number; coalesced: number }
+    /* log.trace operation record: chosen operation name + minted span id. */
+    name?: string
+    spanId?: string
+    stack?: string
+}

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

@@ -0,0 +1,7 @@
+/*
+Presentation hints for the tsv formatter only — the framework's styling
+voices on the 'abide' channel: 'success' paints green, 'detail' dims
+secondary text. Never serialised: the json format renders these records as
+ordinary info lines.
+*/
+export type LogVoice = 'success' | 'detail'

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

@@ -0,0 +1,14 @@
+/*
+Side-agnostic shape of the active page state: the matched route, its decoded
+params, the live request/location URL, and whether a client SPA navigation is
+in flight. The browser `page` proxy reads its public fields through this; the
+server resolver reads them off the per-request store, the client resolver off
+the module singleton. `navigating` is always false server-side — there is no
+in-flight navigation during a synchronous render.
+*/
+export type PageSnapshot = {
+    route: string
+    params: Record<string, string>
+    url: URL
+    navigating: boolean
+}

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

@@ -0,0 +1,12 @@
+/*
+A single declared argument of a markdown prompt, parsed from the file's
+YAML frontmatter `arguments:` list. `name` is the placeholder the body
+interpolates via `{{name}}`; `description` + `required` feed the argument
+list MCP advertises in `prompts/list`. Build-time only — markdown prompts
+carry no runtime schema object, so this drives the generated JSON Schema.
+*/
+export type PromptArgument = {
+    name: string
+    description?: string
+    required?: boolean
+}

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

@@ -0,0 +1,14 @@
+import type { HttpVerb } from './HttpVerb.ts'
+import type { RemoteCallable } from './RemoteCallable.ts'
+
+/*
+Bare-response remote function — same call shape as RemoteFunction but
+resolves to the underlying Response without Content-Type decode and
+without throwing on non-2xx. Produced as `.raw` on every RemoteFunction
+so callers that need status / headers / body streaming or want to
+implement custom error handling can opt out of the decode.
+*/
+export type RawRemoteFunction<Args> = RemoteCallable<Args, Response> & {
+    readonly method: HttpVerb
+    readonly url: string
+}

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

@@ -0,0 +1,12 @@
+/*
+Call signature shared by RemoteFunction and RawRemoteFunction. The base
+signature keeps `args` required so a schema'd verb can't silently drop its
+input; when `Args` admits undefined (no-input verbs) an intersected
+optional-arg signature lets call sites write `fn()` instead of
+`fn(undefined)`. Intersection rather than a bare conditional so the type
+stays callable while `Args` is still generic (cache() invokes producers
+before `Args` resolves). FormData is the multipart upload escape hatch —
+see RemoteFunction.
+*/
+export type RemoteCallable<Args, Resolved> = ((args: Args | FormData) => Promise<Resolved>) &
+    (undefined extends Args ? (args?: Args | FormData) => Promise<Resolved> : unknown)

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

@@ -0,0 +1,47 @@
+import type { ClientFlags } from './ClientFlags.ts'
+import type { HttpVerb } from './HttpVerb.ts'
+import type { RawRemoteFunction } from './RawRemoteFunction.ts'
+import type { RemoteCallable } from './RemoteCallable.ts'
+import type { Subscribable } from './Subscribable.ts'
+
+/*
+Remote function reference produced by GET/POST/... inside an `$rpc/**`
+module and consumed by rpc dispatch, cache(), SSR auto-hydration, and
+direct calls. Same callable signature on server and client — the bundler
+swaps the implementation for browser builds.
+
+The plain call resolves to the decoded body shape (sniffed from
+Content-Type) and throws HttpError on non-2xx. `.raw` is a sibling
+RemoteFunction whose call resolves to the underlying Response — same
+method, same url, same args, no decode. Pass `fn.raw` to cache() to
+memoise raw Responses against the same cache key as `fn` (both share one
+stored entry — the decode just happens on the way out for callers of
+`fn`). `.stream(args)` returns an iterable view of the Response body:
+SSE / JSONL handlers yield each frame; non-streaming handlers yield the
+decoded body once then complete. The result is a Subscribable, so it
+can be passed to tail() and shared across reactive consumers.
+For sustained broadcast / pub-sub use the `abide/server/socket` primitive —
+HTTP rpc isn't the place for long-lived multi-publisher subscriptions.
+`.fetch(req)` is the framework's request-dispatch entry point — used by
+the router to invoke the handler from an incoming HTTP request, not
+for user code.
+`crossOrigin` (server-side only, set via the verb's opts) exempts a
+mutating verb from the router's same-origin CSRF gate, accepting browser
+requests whose Origin doesn't match the app's own host.
+*/
+/*
+A body verb (POST/PUT/PATCH) also accepts a FormData in place of typed args:
+buildRpcRequest ships it as a multipart body and the server splits text fields
+into args (still schema-validated) and File parts into files(). FormData is
+stringly-typed, so this is the upload escape hatch — typed object args remain
+the default for everything else.
+*/
+export type RemoteFunction<Args, Return> = RemoteCallable<Args, Return> & {
+    readonly method: HttpVerb
+    readonly url: string
+    readonly clients: ClientFlags
+    readonly crossOrigin?: boolean
+    readonly raw: RawRemoteFunction<Args>
+    stream(args?: Args | FormData): Subscribable<Return>
+    fetch(request: Request): Promise<Response>
+}

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

@@ -0,0 +1,7 @@
+/*
+Method of a cache entry that may re-fire unprompted — snapshot replay on the
+client, invalidate-policy refetch. Mirrors REPLAYABLE_METHODS (the runtime
+gate; narrow via isReplayableMethod): only GET qualifies, the one safe
+read-only method.
+*/
+export type ReplayableMethod = 'GET'

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

@@ -0,0 +1,16 @@
+import type { TraceContext } from './TraceContext.ts'
+
+/*
+The request-scope facts the shared layer reads through requestScopeSlot:
+trace position, elapsed ms since the scope opened (request start on the
+server, navigation start in the browser), and the verb+path that anchors log
+lines. Resolved fresh per read so `elapsedMs` is current at the call.
+*/
+export type RequestScopeInfo = {
+    trace: TraceContext
+    elapsedMs: number
+    method: string
+    path: string
+    /* The calling client's reported connectivity (server only, from OFFLINE_HEADER); drives server-side online(). Omitted client-side — online() reads navigator there. */
+    online?: boolean
+}

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

@@ -0,0 +1,6 @@
+/* A verb invoker mirrors the verb's own call: a plain call decodes the body
+   (throws HttpError on non-2xx), `.raw` returns the Response untouched. Shared
+   by every name→callable RPC proxy (the CLI client, the test harness). */
+export type RpcInvoker = ((args?: unknown) => Promise<unknown>) & {
+    raw: (args?: unknown) => Promise<Response>
+}

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

@@ -0,0 +1,17 @@
+import type { SocketSubCallbacks } from './SocketSubCallbacks.ts'
+
+/* The multiplexed-ws abstraction a Socket<T> drives: open/close a per-sub
+   subscription and publish to a topic. The browser singleton (socketChannel)
+   and the test harness (createTestSocketChannel) each implement it;
+   buildSocketOverChannel turns either into Socket<T> objects, so the two
+   surfaces can't drift on the Socket contract. */
+export type SocketChannel = {
+    subscribe(
+        sub: string,
+        socket: string,
+        replay: number | undefined,
+        callbacks: SocketSubCallbacks,
+    ): void
+    unsubscribe(sub: string): void
+    publish(socket: string, message: unknown): void
+}

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

@@ -0,0 +1,13 @@
+/* The callback contract a SocketChannel drives per subscription — how the
+   channel hands a sub its frames and lifecycle. Shared by every channel
+   implementation (the browser multiplex, the test harness) and the Socket<T>
+   builder that wires these onto a push iterator. */
+export type SocketSubCallbacks = {
+    onMessage(message: unknown): void
+    /* The sub's batched seed from the retained tail (possibly empty) — the replay/live boundary. */
+    onReplay(messages: unknown[]): void
+    onError(message: string): void
+    onEnd(): void
+    /* Transport loss (ws close), as opposed to a per-sub server `err` frame — recoverable. */
+    onDisconnect(): void
+}

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

@@ -0,0 +1,56 @@
+/*
+Mirror of the Standard Schema v1 spec interface (standardschema.dev). Any
+library that implements the spec — zod, valibot, arktype, etc. — produces
+values whose `~standard` property structurally matches this shape, so users
+can pass their existing schemas to verb helpers without an adapter.
+
+Kept inline (no `@standard-schema/spec` dep) because the spec is type-only
+and tiny; adding a package for ~30 lines of interface would be churn. The
+namespace pattern below is the spec's own convention — `InferInput` /
+`InferOutput` ride along the same export.
+*/
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>
+}
+
+export namespace StandardSchemaV1 {
+    export interface Props<Input = unknown, Output = Input> {
+        readonly version: 1
+        readonly vendor: string
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>
+        readonly types?: Types<Input, Output> | undefined
+    }
+
+    export type Result<Output> = SuccessResult<Output> | FailureResult
+
+    export interface SuccessResult<Output> {
+        readonly value: Output
+        readonly issues?: undefined
+    }
+
+    export interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>
+    }
+
+    export interface Issue {
+        readonly message: string
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
+    }
+
+    export interface PathSegment {
+        readonly key: PropertyKey
+    }
+
+    export interface Types<Input = unknown, Output = Input> {
+        readonly input: Input
+        readonly output: Output
+    }
+
+    export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+        Schema['~standard']['types']
+    >['input']
+
+    export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+        Schema['~standard']['types']
+    >['output']
+}

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

@@ -0,0 +1,10 @@
+import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
+
+/*
+Payload of one streamed `window.__abideResolve(...)` call. A full
+`CacheSnapshotEntry` settles the placeholder with warm data; a `{ key, miss }`
+marker means the server couldn't snapshot that body (binary, rejected, evicted)
+so the client settles the placeholder with a live re-fetch instead. Discriminate
+on the `miss` field.
+*/
+export type StreamedResolution = CacheSnapshotEntry | { key: string; miss: true }

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

@@ -0,0 +1,26 @@
+import type { TailHooks } from './TailHooks.ts'
+
+/*
+The thing `tail()` reads from: an AsyncIterable carrying a stable `name`
+used as the subscription registry key. Both `Socket<T>` (the declared
+broadcast primitive) and the result of `fn.stream(args)` (per-call HTTP
+stream consumer) satisfy this shape, so tail() can share one iterator
+across multiple readers regardless of source.
+
+The name on a Socket comes from the file path under `src/server/sockets/`.
+The name on an fn.stream(args) result is `keyForRemoteCall(method, url,
+args)` — the same key cache() uses — so two readers of the same remote-call
+args dedupe to one underlying fetch.
+
+`tail` is the optional retention capability: a source that keeps a tail of
+recent frames hands back an iterable seeded with at most the last `count`
+before going live. Sockets implement it verbatim; one-shot rpc streams omit
+it. The tail() consumer uses it to bound replay to what the reader will
+keep — it never requires it. Implementers must signal `hooks.replayed`
+in-band once the seed portion is delivered (even when empty) so window
+readers can commit atomically; see TailHooks.
+*/
+export interface Subscribable<T> extends AsyncIterable<T> {
+    readonly name: string
+    tail?(count: number, hooks?: TailHooks): AsyncIterable<T>
+}

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

@@ -0,0 +1,12 @@
+/*
+Hooks a tail() reader passes to a Subscribable's retention capability.
+`replayed` must be signalled in-band exactly once per iteration — after the
+last replayed frame, before any live frame, and even when nothing was
+replayed — so a window reader can commit its seed atomically instead of
+guessing where replay ends (an empty replay keeps the reader's held window;
+nothing was replayed, so nothing can duplicate). Sources without the
+capability never see hooks.
+*/
+export interface TailHooks {
+    readonly replayed?: () => void
+}

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

@@ -0,0 +1,10 @@
+/*
+Window form of `tail()`: `last` is the rolling window size — the reader holds
+the last ≤`last` frames, however they arrived. A source that retains a tail
+(a socket declared with `{ tail: n }`) seeds the window by replaying up to
+`last` retained frames; a source with no retention (an rpc stream, an
+undeclared socket) fills it from live frames only. Integer ≥ 1.
+*/
+export interface TailOptions {
+    readonly last: number
+}

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

@@ -0,0 +1,17 @@
+/*
+The request's W3C Trace Context position. `traceId` identifies the whole
+end-to-end operation (inherited from an inbound `traceparent` or minted at the
+boundary); `spanId` is the id abide mints for this request — it rides outbound
+`traceparent` headers as the parent of downstream work, and a future span
+exporter materialises the request's root span under this exact id.
+`parentSpanId` preserves the inbound header's span id so that root span can
+parent under the upstream caller; absent when abide started the trace.
+`flags` echo the inbound sampling flags ('01' when abide starts the trace, so
+downstream recorders don't drop what the developer is trying to see).
+*/
+export type TraceContext = {
+    traceId: string
+    spanId: string
+    parentSpanId?: string
+    flags: string
+}

package/src/lib/shared/url.ts

@@ -0,0 +1,118 @@
+import { basePath } from './basePath.ts'
+import type { RouteSegment } from './parseRouteSegments.ts'
+import { parseRouteSegments } from './parseRouteSegments.ts'
+import { queryStringFromArgs } from './queryStringFromArgs.ts'
+
+/* `undefined` is allowed and dropped (queryStringFromArgs skips it), so an
+   optional field — url('/p', { ref: maybeUndefined }) — types without a guard. */
+type QueryValue = string | number | boolean | undefined
+type Query = Record<string, QueryValue>
+
+/*
+Augmentable rpc map. Codegen emits a `declare module '<importName>/shared/url'`
+block filling this with `'/rpc/<file>': args` for each query-carrying (GET)
+verb, so url('/rpc/search', { q }) types its args against the verb's own
+signature. Empty by default — an absent entry falls through to the page/asset
+branch, so the helper works before the generated d.ts lands.
+*/
+// @readme url
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated rpc.d.ts
+export interface RpcRoutes {}
+
+/*
+Augmentable autocomplete sets — keys only, values unused. The page codegen
+(writeRoutesDts) fills PageRoutes with each route path, the public codegen
+(writePublicAssetsDts) fills PublicAssets with each `public/` file path. They
+exist purely so editors suggest known paths; PathParams still derives a page's
+params from the literal, so neither map drives typing.
+*/
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated routes.d.ts
+export interface PageRoutes {}
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated publicAssets.d.ts
+export interface PublicAssets {}
+
+/*
+Known in-app paths for autocomplete. `(string & {})` at the call site keeps any
+string accepted (dynamic/raw/external paths) — there's no hard route-existence
+error, which would reject assets and interpolated strings — while these light
+up suggestions once codegen lands.
+*/
+type KnownPath = keyof PageRoutes | keyof RpcRoutes | keyof PublicAssets
+
+/*
+Pulls the `[name]` / `[...rest]` params a route literal declares straight from
+the path type, so url('/product/[id]', …) requires `id` without a generated
+shape map. Values accept string | number (stringified on output). A path with
+no bracket segments yields {}, which collapses the params slot away. The
+catch-all branch recurses on its head too, so `[name]` segments before a
+`[...rest]` are kept.
+*/
+type PathParams<P extends string> = P extends `${infer Head}[...${infer Rest}]${infer Tail}`
+    ? PathParams<Head> & { [K in Rest]: string | number } & PathParams<Tail>
+    : P extends `${string}[${infer Name}]${infer Tail}`
+      ? { [K in Name]: string | number } & PathParams<Tail>
+      : // biome-ignore lint/complexity/noBannedTypes: {} is the "no params" base case — keyof {} is never, which collapses the params slot; Record<string, never> would not (keyof is string)
+        {}
+
+/*
+Resolves any in-app URL to its base-correct, typed form — the single chokepoint
+so a project mounted under APP_URL's subpath (e.g. /v2) generates links, asset
+refs, and rpc hrefs that stay within the mount. Three disjoint URL kinds, keyed
+off the path:
+  - rpc (flat /rpc/*, present in RpcRoutes): the verb's args, serialised to query.
+  - page route (has [name] segments): path params, then optional query.
+  - asset / paramless / raw: bare path, then optional query.
+External URLs (scheme-qualified or protocol-relative) skip the base untouched,
+as do non-rooted specifiers — base only ever prefixes a rooted internal path.
+*/
+export function url<P extends KnownPath | (string & {})>(
+    path: P,
+    ...args: P extends keyof RpcRoutes
+        ? undefined extends RpcRoutes[P]
+            ? [args?: RpcRoutes[P]]
+            : [args: RpcRoutes[P]]
+        : keyof PathParams<P> extends never
+          ? [query?: Query]
+          : [params: PathParams<P>, query?: Query]
+): string
+export function url(path: string, first?: Query, second?: Query): string {
+    // Scheme-qualified (http:, mailto:) or protocol-relative URLs are external — leave them whole.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith('//')) {
+        return appendQuery(path, first)
+    }
+    const segments = parseRouteSegments(path)
+    const hasParams = segments.some((segment) => segment.kind === 'param')
+    // With path params the second arg is the query; without, the first arg is.
+    const query = hasParams ? second : first
+    const resolved = hasParams ? interpolate(segments, first ?? {}) : path
+    // Base only prefixes rooted internal paths; relative specifiers are left alone.
+    const prefixed = resolved.startsWith('/') ? basePath() + resolved : resolved
+    return appendQuery(prefixed, query)
+}
+
+/* Substitutes `[name]` / `[...rest]` segments with their stringified, URL-encoded
+   param values (matching the query side, which encodes too). A `[name]` value is
+   encoded whole so `/`, `?`, `#`, and spaces can't alter the path structure; a
+   `[...rest]` catch-all keeps its `/` separators and encodes each sub-segment. */
+function interpolate(segments: RouteSegment[], params: Query): string {
+    return segments
+        .map((segment) => {
+            if (segment.kind === 'literal') {
+                return segment.value
+            }
+            const value = String(params[segment.name])
+            return segment.catchAll
+                ? value.split('/').map(encodeURIComponent).join('/')
+                : encodeURIComponent(value)
+        })
+        .join('/')
+}
+
+/* Appends a `?`-query built from the same encoder buildRpcRequest uses, or nothing. */
+function appendQuery(target: string, query: Query | undefined): string {
+    if (!query) {
+        return target
+    }
+    const queryString = queryStringFromArgs(query, false)
+    return queryString ? `${target}?${queryString}` : target
+}

package/src/lib/shared/withBase.ts

@@ -0,0 +1,11 @@
+import { basePath } from './basePath.ts'
+
+/*
+Prefixes a rooted internal path (`/rpc/…`, `/__abide/…`) with the mount base
+so the client's framework requests route through the proxy (`/v2/rpc/…`). The
+single rule the runtime fetch sites (remoteProxy, openResolveStream,
+socketChannel, the streaming placeholders) share — '' at root is a no-op.
+*/
+export function withBase(path: string): string {
+    return `${basePath()}${path}`
+}

package/src/lib/shared/withBaseUrl.ts

@@ -0,0 +1,17 @@
+import { basePath } from './basePath.ts'
+
+/*
+Re-homes a URL under the mount base by prefixing its pathname (`/people` →
+`/v2/people`) — the URL-level counterpart of withBase for sites that carry
+whole URLs rather than rooted paths. Identity at root mount, so there is no
+allocation (and no behaviour change) when no base is set.
+*/
+export function withBaseUrl(url: URL): URL {
+    const base = basePath()
+    if (!base) {
+        return url
+    }
+    const prefixed = new URL(url)
+    prefixed.pathname = base + url.pathname
+    return prefixed
+}

package/src/lib/shared/withJsonSchema.ts

@@ -0,0 +1,21 @@
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
+
+/*
+Attaches a `toJSONSchema()` projection to a Standard Schema whose library
+doesn't expose one natively. jsonSchemaForSchema probes that method to feed the
+OpenAPI document, the MCP tool schemas, the CLI flag help, and the bundle setup
+form. Zod 4 / Effect / Arktype carry their own; everything else wraps once where
+the schema is declared:
+
+  export const config = env(withJsonSchema(vSchema, (s) => toJsonSchema(s)))
+
+Mutates and returns the same schema with the method attached, so the wrapped
+value stays usable everywhere the bare schema was.
+*/
+// @readme rpc
+export function withJsonSchema<Schema extends StandardSchemaV1>(
+    schema: Schema,
+    toJsonSchema: (schema: Schema) => Record<string, unknown>,
+): Schema & { toJSONSchema: () => Record<string, unknown> } {
+    return Object.assign(schema, { toJSONSchema: () => toJsonSchema(schema) })
+}

package/src/lib/shared/writeDts.ts

@@ -0,0 +1,12 @@
+/* The banner every generated abide `.d.ts` carries, warning off hand edits. */
+const DTS_BANNER = '// Generated by abide. Do not edit by hand.'
+
+/*
+Writes a generated `.d.ts` to `src/.abide/<name>.d.ts` (the path the consumer's
+src tsconfig include picks up), wrapping `body` in the shared banner + the
+`export {}` footer that makes the file a module. The three codegen writers
+(routes, rpc, public assets) differ only in `body`, so the envelope lives here.
+*/
+export async function writeDts(cwd: string, name: string, body: string): Promise<void> {
+    await Bun.write(`${cwd}/src/.abide/${name}.d.ts`, `${DTS_BANNER}\n${body}\n\nexport {}\n`)
+}

package/src/lib/shared/writeHealthDts.ts

@@ -0,0 +1,36 @@
+import { writeDts } from './writeDts.ts'
+
+/*
+Emits a `.d.ts` that augments abide's `AppHealthMap` interface with the app
+health() hook's resolved return type, so the client `health()` read types
+against the project's own hook (e.g. `health().authenticated`). Conditional
+over `typeof import('../app.ts')` because the hook is optional — absent, the
+fields resolve empty; a non-object return is ignored, matching the runtime
+merge. With no src/app.ts at all the import would be an error, so the file
+carries only the framework shape. Written to `src/.abide/health.d.ts` like
+its routes/rpc siblings.
+*/
+export async function writeHealthDts({
+    cwd,
+    hasAppModule,
+    importName,
+}: {
+    cwd: string
+    hasAppModule: boolean
+    importName: string
+}): Promise<void> {
+    const body = hasAppModule
+        ? `type AppHealthFields<App> = App extends { health: (...args: never[]) => infer Result }
+    ? Awaited<Result> extends object
+        ? Awaited<Result>
+        : Record<never, never>
+    : Record<never, never>
+
+declare module '${importName}/shared/health' {
+    interface AppHealthMap {
+        fields: AppHealthFields<typeof import('../app.ts')>
+    }
+}`
+        : '// src/app.ts absent — health() carries only the framework fields.'
+    await writeDts(cwd, 'health', body)
+}

package/src/lib/shared/writeLastConnection.ts

@@ -0,0 +1,13 @@
+import { mkdir } from 'node:fs/promises'
+import { appDataDir } from './appDataDir.ts'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+// Persists the connection intent, creating the data dir on first write.
+export async function writeLastConnection(
+    programName: string,
+    value: LastConnection,
+): Promise<void> {
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(lastConnectionPath(programName), JSON.stringify(value))
+}

package/src/lib/shared/writePublicAssetsDts.ts

@@ -0,0 +1,31 @@
+import { writeDts } from './writeDts.ts'
+
+/*
+Emits a `.d.ts` that augments abide's `PublicAssets` interface with one entry
+per file under `public/`, keyed by its site-root path (`/logo.png`) — the same
+key createPublicAssetServer serves it at. Keys only (value `true`): the map
+exists purely so `url('/logo.png')` autocompletes known assets; it carries no
+type beyond the path. Written to `src/.abide/publicAssets.d.ts` so the
+consumer's src tsconfig include picks it up, keyed on the project's abide
+import name like writeRoutesDts / writeRpcDts.
+*/
+export async function writePublicAssetsDts({
+    cwd,
+    publicFiles,
+    importName,
+}: {
+    cwd: string
+    publicFiles: string[]
+    importName: string
+}): Promise<void> {
+    const entries = publicFiles
+        .map((file) => `        ${JSON.stringify(`/${file}`)}: true`)
+        .toSorted()
+        .join('\n')
+    const body = `declare module '${importName}/shared/url' {
+    interface PublicAssets {
+${entries}
+    }
+}`
+    await writeDts(cwd, 'publicAssets', body)
+}