@abide/abide 0.28.0

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

@@ -0,0 +1,19 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+import type { Socket } from './Socket.ts'
+
+/*
+Per-socket registry record. The Socket itself stays uniform between
+server and client by parking policy state (retained-tail snapshot, client
+publish gate, payload schema, client targeting) here instead of leaking
+into the public Socket shape.
+*/
+export type SocketRegistryEntry = {
+    socket: Socket<unknown>
+    allowClientPublish: boolean
+    schema: StandardSchemaV1 | undefined
+    clients: ClientFlags
+    /* last `count` retained frames (whole tail when omitted) — the read-only
+       face shared by the ws sub replay, the HTTP rest() face, and MCP tail */
+    snapshotTail(count?: number): unknown[]
+}

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

@@ -0,0 +1,10 @@
+import type { Socket } from './Socket.ts'
+
+/*
+Manifest of socket-name → module loader. Produced by the resolver
+plugin from each `.ts` under src/server/sockets/. Each module has exactly one
+named export, a Socket whose `.name` was stamped in by the bundler
+rewrite. The dispatcher imports a module on first access and caches the
+resolved Socket against its name.
+*/
+export type SocketRoutes = Record<string, () => Promise<Record<string, Socket<unknown>>>>

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

@@ -0,0 +1,24 @@
+/*
+Wire frame the server sends over the multiplexed socket connection.
+
+`msg` is keyed by socket name (not sub id) because one publish fans
+out to every client subscribed to the socket via Bun's native
+publish — the client demuxes against every local sub of that socket.
+
+`replay` is per-sub and batched: one frame carries the sub's requested
+slice of the retained tail (possibly empty), sent on sub before live
+fan-out reaches it. The batch is the wire's replay/live demarcation —
+a window reader commits its seed atomically at the boundary — and the
+per-sub address keeps one sub's replay out of sibling subs on the same
+socket.
+
+`end` and `err` are per-sub because they're subscription-lifecycle
+events; `err.message` is the only thrown-value field forwarded so the
+wire stays JSON-safe and server-side stack traces never reach the
+client.
+*/
+export type SocketServerFrame =
+    | { type: 'msg'; socket: string; message: unknown }
+    | { type: 'replay'; sub: string; messages: unknown[] }
+    | { type: 'end'; sub: string }
+    | { type: 'err'; sub: string; message: string }

package/src/lib/server/sse.ts

@@ -0,0 +1,54 @@
+/*
+Wraps an AsyncIterable<Frame> in a Response whose body is
+Server-Sent Events (text/event-stream) — each frame becomes one
+`data: <json>\n\n` event. Used inside an rpc handler to expose a
+generator over plain HTTP so EventSource (or `tail(fn.stream(args))`
+on the client) can consume it frame-by-frame.
+
+  export const orderFeed = GET<Args>((args) =>
+      sse(async function* () {
+          for await (const order of db.watchOrders(args)) yield order
+      }())
+  )
+
+A 15s keepalive comment (`: keepalive\n\n`) is sent between frames so
+intermediaries (proxies, load balancers) don't drop an idle connection.
+Comments are ignored by EventSource per the spec, so they're invisible to
+consumers.
+
+Cancellation flows from the consumer through ReadableStream's `cancel`
+into `iter.return()` so the handler's `for await` exits via its normal
+control path. Errors are emitted as an `event: error` frame carrying only
+the message (full error logged server-side) before the stream closes;
+EventSource surfaces this via its `error` listener and `tail()`
+maps it to the entry's `error` field.
+*/
+import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import { sseErrorFrame } from '../shared/sseErrorFrame.ts'
+import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { streamFromIterator } from './runtime/streamFromIterator.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
+
+const KEEPALIVE_INTERVAL_MS = 15000
+
+// @readme response
+export function sse<Frame>(
+    iterable: AsyncIterable<Frame>,
+    init?: ResponseInit,
+): TypedResponse<Frame> {
+    const body = streamFromIterator(iterable, {
+        encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
+        encodeError: (message) => sseErrorFrame.encode(message),
+        keepaliveMs: KEEPALIVE_INTERVAL_MS,
+        keepalivePayload: ': keepalive\n\n',
+    })
+    return new Response(
+        body,
+        withResponseDefaults(init, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': NO_STORE,
+            'X-Content-Type-Options': 'nosniff',
+            Connection: 'keep-alive',
+        }),
+    ) as TypedResponse<Frame>
+}

package/src/lib/shared/ABIDE_PACKAGE_NAME.ts

@@ -0,0 +1,7 @@
+/*
+The package's published npm name. The codegen and the import-name resolver
+match a consuming project's dependency (direct or aliased) against this to
+decide which specifier to emit, so keeping it in one place means a future
+rename touches a single constant.
+*/
+export const ABIDE_PACKAGE_NAME = '@abide/abide'

package/src/lib/shared/ABIDE_VERSION.ts

@@ -0,0 +1,9 @@
+import packageJson from '../../../package.json' with { type: 'json' }
+
+/*
+The framework's own version, inlined at build time from abide's package.json
+(a compiled binary has no node_modules to read at runtime). Rides the health
+payload's `abide` field — truthy for the "is this a abide server" check,
+informative for skew diagnosis.
+*/
+export const ABIDE_VERSION: string = packageJson.version

package/src/lib/shared/CACHE_CONTROL_VALUES.ts

@@ -0,0 +1,16 @@
+/*
+Cache-Control values used by abide's framework responses. Centralised so
+the framework's policy (no-store on errors and rpc dispatch helpers,
+private/no-cache on SSR HTML, the static-asset policies) lives in one place
+and can't drift between the server core, the asset servers, and the respond
+helpers.
+*/
+export const NO_STORE = 'no-store'
+export const SSR_CACHE_CONTROL = 'private, no-cache'
+
+// Content-addressed `/_app/` chunks (name carries the hash) — cache forever.
+export const IMMUTABLE_ASSET_CACHE_CONTROL = 'public, max-age=31536000, immutable'
+// Unhashed `/_app/` entries (entry bundle, shell) — must revalidate each time.
+export const REVALIDATE_ASSET_CACHE_CONTROL = 'public, max-age=0, must-revalidate'
+// Files served from public/ at the site root — short shared cache.
+export const PUBLIC_ASSET_CACHE_CONTROL = 'public, max-age=3600'

package/src/lib/shared/CACHE_WRAPPED.ts

@@ -0,0 +1,8 @@
+/*
+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 a
+re-wrapped wrapper silently downgrades a remote to an anonymous producer.
+*/
+export const CACHE_WRAPPED: unique symbol = Symbol('abide.cacheWrapped')

package/src/lib/shared/CLI_PATH.ts

@@ -0,0 +1,7 @@
+/*
+Path of the CLI install endpoint: the bare path returns the platform-detecting
+install script, `${CLI_PATH}/<platform>` the platform tarball. Shared so the
+server mount (createServer) and the script the install endpoint emits
+(installScript) agree on the path.
+*/
+export const CLI_PATH = '/__abide/cli'

package/src/lib/shared/DEV_HOT_PREFIX.ts

@@ -0,0 +1,7 @@
+/*
+Path prefix of the dev-only component hot-module endpoint (`/__abide/hot/<moduleId>`).
+The browser imports `<prefix><moduleId>?v=<hash>` to fetch one edited component's
+hot module instead of reloading. Shared so the server route (createServer) and the
+live-reload client (DEV_RELOAD_CLIENT_SCRIPT) agree.
+*/
+export const DEV_HOT_PREFIX = '/__abide/hot/'

package/src/lib/shared/DEV_RELOAD_PATH.ts

@@ -0,0 +1,6 @@
+/*
+Path of the dev-only live-reload SSE channel. Shared so the server mount
+(createServer) and the client script injected into dev pages
+(DEV_RELOAD_CLIENT_SCRIPT) agree on the path.
+*/
+export const DEV_RELOAD_PATH = '/__abide/dev'

package/src/lib/shared/HEALTH_PATH.ts

@@ -0,0 +1,7 @@
+/*
+The canonical liveness/health endpoint: the identity payload plus whatever
+the app's optional `health(request)` hook contributes. `/__abide/identity`
+stays as a compatibility alias serving the same payload (older launchers
+probe it; probeAbideServer falls back to it for older servers).
+*/
+export const HEALTH_PATH = '/__abide/health'

package/src/lib/shared/HttpError.ts

@@ -0,0 +1,20 @@
+/*
+Thrown by remote-function calls when the server responds with a non-2xx
+status. Carries the raw Response so callers can inspect body, headers, or
+status text — useful for showing user-friendly error UI without having to
+opt every call site into the `.raw()` escape hatch.
+*/
+// @readme response
+export class HttpError extends Error {
+    readonly status: number
+    readonly statusText: string
+    readonly response: Response
+
+    constructor(response: Response) {
+        super(`HTTP ${response.status} ${response.statusText || 'error'}`)
+        this.name = 'HttpError'
+        this.status = response.status
+        this.statusText = response.statusText
+        this.response = response
+    }
+}

package/src/lib/shared/IDENTITY_PATH.ts

@@ -0,0 +1,6 @@
+/*
+Path of the identity probe answering `{ abide, name, version }` ahead of any
+app middleware. Shared so the server mount (createServer) and the launcher's
+probe (probeAbideServer) agree on the path.
+*/
+export const IDENTITY_PATH = '/__abide/identity'

package/src/lib/shared/INSPECTOR_PATH.ts

@@ -0,0 +1,7 @@
+/*
+Mount root of the opt-in inspector surface (the `@abide/inspector` package,
+activated by ABIDE_ENABLE_INSPECTOR=true). The UI sits at this exact path; its
+data endpoints (`/surface`, `/events`) live under `${INSPECTOR_PATH}/`. Shared
+so createServer's route gate and the inspector handler agree on the prefix.
+*/
+export const INSPECTOR_PATH = '/__abide/inspector'

package/src/lib/shared/NAV_HEADER.ts

@@ -0,0 +1,8 @@
+/*
+Request header the client router stamps (value '1') on its SPA navigation probe:
+a bare fetch of the destination that exists only to run app.handle server-side
+(auth, redirect, header gating) without paying for a render. Presence tells the
+page dispatcher to answer 204 once handle() has passed — a redirect or block from
+handle() never reaches that point. Absence is an ordinary document/render request.
+*/
+export const NAV_HEADER = 'abide-nav'

package/src/lib/shared/OFFLINE_HEADER.ts

@@ -0,0 +1,8 @@
+/*
+Request header a abide client fetch sets (value '1') only when navigator.onLine
+is false, so a handler's online() reflects the calling client's connectivity.
+Presence = offline; absence = online/unknown. In a bundle the client and the
+embedded server share a machine, so this carries exactly the outbound
+reachability a handler reaching external sites needs.
+*/
+export const OFFLINE_HEADER = 'abide-offline'

package/src/lib/shared/REMOTE_FUNCTION.ts

@@ -0,0 +1,8 @@
+/*
+Brand set by createRemoteFunction on both the decoded callable and its raw
+sibling — the exact answer to "is this a abide remote?" where structural
+checks ('url' in fn) would misclassify any user function that happens to
+carry a url property. Read by cache()'s remote/producer discriminator,
+selectorMatcher's identity branch, and the route dispatcher's export scan.
+*/
+export const REMOTE_FUNCTION: unique symbol = Symbol('abide.remoteFunction')

package/src/lib/shared/REPLAYABLE_METHODS.ts

@@ -0,0 +1,12 @@
+/*
+Methods whose remote-call cache entries can be replayed on the client from an
+SSR snapshot: the key (method + url + args-in-url) carries everything needed to
+re-issue the request, and re-issuing is safe. Only GET qualifies — it is the
+one safe (read-only) method. DELETE is idempotent but still a write, and
+body-carrying writes (POST/PUT/PATCH) additionally don't round-trip through
+the snapshot; none of them may re-fire unprompted. Shared by snapshot
+serialization and the invalidate-policy guard so both agree on which methods
+are replayable. Deliberately not consulted by the server's ttl: 0 keep —
+within one request, writes coalesce like everything else.
+*/
+export const REPLAYABLE_METHODS: ReadonlySet<string> = new Set(['GET'])

package/src/lib/shared/SOCKETS_PATH.ts

@@ -0,0 +1,7 @@
+/*
+Mount path of the framework's socket multiplex: the single ws upgrade point,
+with the per-socket HTTP face under `${SOCKETS_PATH}/<name>`. Shared so the
+server mount (createServer), the browser channel's dial (socketChannel), and
+the REST face advertised to the CLI/MCP (socketOperations) agree on the path.
+*/
+export const SOCKETS_PATH = '/__abide/sockets'

package/src/lib/shared/STREAMING_CONTENT_TYPES.ts

@@ -0,0 +1,11 @@
+/*
+Content-Type prefixes abide treats as streaming bodies — SSE for the
+`sse()` helper, JSONL / NDJSON for the `jsonl()` helper. Used by
+decodeResponse to refuse a buffered decode and by streamResponse to
+choose the frame parser.
+*/
+export const STREAMING_CONTENT_TYPES = [
+    'text/event-stream',
+    'application/jsonl',
+    'application/x-ndjson',
+]

package/src/lib/shared/SocketDisconnectedError.ts

@@ -0,0 +1,13 @@
+/*
+Typed transport-loss signal: the multiplexed ws channel went down and tore this
+subscription with it. Distinct from an application error (a server `err` frame)
+because it is recoverable — tail() catches this type to reconnect with the
+last value retained (refreshing), while raw `for await` consumers surface it
+like any other error and keep manual control over reconciliation.
+*/
+export class SocketDisconnectedError extends Error {
+    constructor() {
+        super('socket channel disconnected')
+        this.name = 'SocketDisconnectedError'
+    }
+}

package/src/lib/shared/TEXT_PLAIN.ts

@@ -0,0 +1,7 @@
+/*
+Content-Type for the framework's plain-text responses (404, 405, CSRF refusal,
+internal error). Explicit so intermediaries don't sniff the body and browsers
+render it inline — a bodied Response with no Content-Type ships as
+`application/octet-stream`, which the browser downloads instead of displaying.
+*/
+export const TEXT_PLAIN = 'text/plain; charset=utf-8'

package/src/lib/shared/abideImportName.ts

@@ -0,0 +1,44 @@
+import { ABIDE_PACKAGE_NAME } from './ABIDE_PACKAGE_NAME.ts'
+import { readPackageJson } from './readPackageJson.ts'
+
+/*
+Resolves the bare specifier prefix a consuming project imports abide under —
+the name abide is installed as in its package.json. A project may depend on
+abide directly (`abide`) or behind a package alias
+(`"abide": "npm:abide@..."`, or `workspace:abide@*`
+inside this repo). An alias-only install resolves only under the alias key and
+a direct install only under the canonical name, so the generated rpc / socket
+/ prompt modules must import under whichever name the project
+declared.
+
+Prefers a `abide` alias (the ergonomic surface the docs use) when present, then
+a direct canonical dependency, then any other alias targeting abide. Falls back
+to the canonical name when abide isn't found in package.json — the build can't
+resolve abide at all in that case, and the canonical name yields the clearest
+resolution error.
+*/
+export async function abideImportName(cwd: string): Promise<string> {
+    const packageJson = (await readPackageJson(cwd)) as
+        | { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        | undefined
+    if (!packageJson) {
+        return ABIDE_PACKAGE_NAME
+    }
+    const dependencies = { ...packageJson.devDependencies, ...packageJson.dependencies }
+    /*
+    Alias entries whose target is abide — `npm:` for a published install,
+    `workspace:` for the in-repo examples. The key is the name the project
+    imports under; the version suffix (`@^0.2.0`, `@*`) is optional.
+    */
+    const aliasPattern = new RegExp(`^(npm|workspace):${ABIDE_PACKAGE_NAME}(@.*)?$`)
+    const aliasNames = Object.entries(dependencies)
+        .filter(([, specifier]) => aliasPattern.test(specifier))
+        .map(([name]) => name)
+    if (aliasNames.includes('abide')) {
+        return 'abide'
+    }
+    if (ABIDE_PACKAGE_NAME in dependencies) {
+        return ABIDE_PACKAGE_NAME
+    }
+    return aliasNames[0] ?? ABIDE_PACKAGE_NAME
+}

package/src/lib/shared/abideLog.ts

@@ -0,0 +1,38 @@
+import { createChannelLog } from './createChannelLog.ts'
+import { emitLogRecord } from './emitLogRecord.ts'
+import type { ChannelLog } from './types/ChannelLog.ts'
+import type { FrameworkLog } from './types/FrameworkLog.ts'
+
+const ABIDE_CHANNEL = 'abide'
+
+/*
+The framework's own voice: the public log shape bound to the always-on
+'abide' channel, so every framework line — boot messages, build output,
+internal warns/errors, the closing record's sibling diagnostics — reads
+`[abide] …` and json consumers filter channel='abide'. The styling voices
+(info/success/detail) ride the same channel and the same negation gate, so
+DEBUG=-abide silences every voice; diagnostic sub-channels (abide:cache,
+abide:rpc, …) stay DEBUG-gated via .channel().
+*/
+const channelVoice = createChannelLog(() => ABIDE_CHANNEL, true)
+
+export const abideLog: FrameworkLog = Object.assign(channelVoice, {
+    channel(name: string): ChannelLog {
+        return createChannelLog(() => name, false)
+    },
+    info(message: string): void {
+        if (channelVoice.enabled()) {
+            emitLogRecord({ level: 'info', msg: message, channel: ABIDE_CHANNEL })
+        }
+    },
+    success(message: string): void {
+        if (channelVoice.enabled()) {
+            emitLogRecord({ level: 'info', msg: message, channel: ABIDE_CHANNEL }, 'success')
+        }
+    },
+    detail(message: string): void {
+        if (channelVoice.enabled()) {
+            emitLogRecord({ level: 'info', msg: message, channel: ABIDE_CHANNEL }, 'detail')
+        }
+    },
+})

package/src/lib/shared/activeCacheStore.ts

@@ -0,0 +1,20 @@
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
+import { createCacheStore } from './createCacheStore.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Resolves the active CacheStore. The runtime is registered via
+`setCacheStoreResolver` from the server entry (request-scoped via ALS)
+or the client entry (module-level singleton). If no resolver is registered,
+a single fallback store is created lazily so isolated tests still work.
+*/
+export function activeCacheStore(): CacheStore {
+    const fromResolver = cacheStoreSlot.resolver?.()
+    if (fromResolver) {
+        return fromResolver
+    }
+    if (!cacheStoreSlot.fallback) {
+        cacheStoreSlot.fallback = createCacheStore()
+    }
+    return cacheStoreSlot.fallback
+}

package/src/lib/shared/activePage.ts

@@ -0,0 +1,25 @@
+import { pageSlot } from './pageSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
+
+/*
+Resolves the active page snapshot. The runtime is registered via
+`setPageResolver` from the server entry (request-scoped via ALS) or the
+client entry (module-level singleton). If no resolver is registered, a single
+fallback snapshot is created lazily so isolated tests still work. Mirrors
+activeCacheStore.
+*/
+export function activePage(): PageSnapshot {
+    const fromResolver = pageSlot.resolver?.()
+    if (fromResolver) {
+        return fromResolver
+    }
+    if (!pageSlot.fallback) {
+        pageSlot.fallback = {
+            route: '',
+            params: {},
+            url: new URL('http://localhost/'),
+            navigating: false,
+        }
+    }
+    return pageSlot.fallback
+}

package/src/lib/shared/appDataDir.ts

@@ -0,0 +1,34 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/*
+Platform-standard per-user data directory for a bundle, keyed by its program
+name. cwd-independent on purpose: the path derives from `programName`, not the
+process working directory — which the OS `open` command sets to `/`, so anything
+relying on cwd (Bun's `.env` autoload, relative paths) finds nothing inside a
+launched `.app`. This is where a bundle keeps what can't be baked at compile time
+— the user's config, DB, and cache. macOS Application Support, Windows %APPDATA%,
+XDG data home elsewhere. Pure: computes the path, never touches the filesystem.
+
+`ABIDE_DATA_DIR` overrides the lot on every platform, used as-is (no programName
+appended) — a cross-platform `XDG_DATA_HOME` that also works on macOS/Windows. Set
+it to point dev at a throwaway dir without touching app code; leave it unset in
+prod for the platform default. A relative value reintroduces cwd-dependence, so a
+launched `.app` (cwd `/`) needs an absolute path. Must come from a layer above the
+data-dir `.env` (shell, CWD `.env`, or binary-dir `.env`) — it can't be read from
+the very file whose location it decides.
+*/
+export function appDataDir(programName: string): string {
+    const override = process.env.ABIDE_DATA_DIR
+    if (override !== undefined && override !== '') {
+        return override
+    }
+    const home = homedir()
+    if (process.platform === 'darwin') {
+        return join(home, 'Library', 'Application Support', programName)
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), programName)
+    }
+    return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), programName)
+}

package/src/lib/shared/appNameSlot.ts

@@ -0,0 +1,10 @@
+/*
+The app's name — the default log channel every unchanneled record carries.
+Set once per process by createServer (package.json name / appInfo) and once
+per page by startClient (the __SSR__ stamp). Undefined until the runtime
+boots; readers fall back to 'app' so isolated tests and pre-boot logging
+still carry a channel.
+*/
+export const appNameSlot: { name: string | undefined } = {
+    name: undefined,
+}

package/src/lib/shared/basePath.ts

@@ -0,0 +1,10 @@
+import { baseSlot } from './baseSlot.ts'
+
+/*
+The current mount base path ('' at root). Resolved per side: the server
+installs an APP_URL-derived resolver at boot, the client one reading
+window.__SSR__.base. url() reads this to prefix rooted internal paths.
+*/
+export function basePath(): string {
+    return baseSlot.resolver?.() ?? baseSlot.fallback ?? ''
+}

package/src/lib/shared/basePathFromAppUrl.ts

@@ -0,0 +1,20 @@
+/*
+Derives the mount base path from APP_URL. APP_URL carries both the app's
+public origin (for absolute URLs) and, via its pathname, where the app is
+mounted — `https://foo.com/v2` → `/v2`. Returns the pathname with any
+trailing slash stripped; root (`/`), unset, or unparseable collapses to ''
+(root mount, the zero-config default). A bare path value with no origin is
+tolerated so `.env` can carry `APP_URL=/v2`.
+*/
+export function basePathFromAppUrl(appUrl: string | undefined): string {
+    if (!appUrl) {
+        return ''
+    }
+    let pathname: string
+    try {
+        pathname = new URL(appUrl).pathname
+    } catch {
+        pathname = appUrl.startsWith('/') ? appUrl : ''
+    }
+    return pathname.replace(/\/+$/, '')
+}

package/src/lib/shared/baseSlot.ts

@@ -0,0 +1,14 @@
+/*
+Internal slot the runtime entries register their mount-base resolver into.
+The server entry installs an APP_URL-derived resolver at boot; the client
+entry installs one reading window.__SSR__.base. `fallback` is a single value
+used only when no resolver is registered — lets isolated tests set a base
+without spinning up the runtime. Mirrors pageSlot / cacheStoreSlot.
+*/
+export const baseSlot: {
+    resolver: (() => string) | undefined
+    fallback: string | undefined
+} = {
+    resolver: undefined,
+    fallback: undefined,
+}

package/src/lib/shared/binaryDirEnvPath.ts

@@ -0,0 +1,12 @@
+import { dirname } from 'node:path'
+import { bundleLayout } from './bundleLayout.ts'
+
+/*
+The bundle's shipped `.env` (its default config layer), resolved from the
+running binary's directory via bundleLayout — beside the binary in the flat
+layout, under `Contents/Resources` in a macOS `.app`. One statement of the
+location for the boot loader, the config form, and the embedded-port resolver.
+*/
+export function binaryDirEnvPath(): string {
+    return bundleLayout(dirname(process.execPath)).envPath
+}

package/src/lib/shared/browserClientFlags.ts

@@ -0,0 +1,10 @@
+import type { ClientFlags } from './types/ClientFlags.ts'
+
+/*
+Client surface flags for a browser-emitted RPC/socket stub. The bundler only
+emits the browser proxy when clients.browser is true, so browser is always true
+here; mcp/cli are server-only discovery state with no meaning in the browser
+bundle, defaulted false so the public RemoteFunction/Socket shape matches the
+server side. Single source shared by remoteProxy and socketProxy.
+*/
+export const browserClientFlags: ClientFlags = { browser: true, mcp: false, cli: false }

package/src/lib/shared/buildRpcProxy.ts

@@ -0,0 +1,39 @@
+import { decodeResponse } from './decodeResponse.ts'
+import type { RpcInvoker } from './types/RpcInvoker.ts'
+
+/*
+Builds the name→callable proxy every RPC client surface shares (the CLI client,
+the test harness). The caller supplies `resolveSend`, the one part that differs:
+it maps a command name to the closure that issues that command's wire call, or
+undefined for an unknown name. This module owns the invariant — a plain call
+decodes the body (decodeResponse throws HttpError on non-2xx), `.raw` returns the
+untouched Response — so the two surfaces can't drift from each other or from the
+remote-function path they mirror.
+
+Each name resolves once: the per-name invoker (or its absence) is memoised, since
+the underlying registry/manifest is fixed for a client's lifetime, so repeated
+`client.foo` accesses skip both the resolve and a fresh closure allocation.
+*/
+export function buildRpcProxy<Api extends object>(
+    resolveSend: (name: string) => ((args?: unknown) => Promise<Response>) | undefined,
+): Api {
+    const invokerCache = new Map<string, RpcInvoker | undefined>()
+    return new Proxy({} as Api, {
+        get(_target, prop): RpcInvoker | undefined {
+            if (typeof prop !== 'string') {
+                return undefined
+            }
+            // Caches undefined too, so an unknown name resolves once, not per access.
+            return invokerCache.getOrInsertComputed(prop, () => {
+                const send = resolveSend(prop)
+                if (!send) {
+                    return undefined
+                }
+                const invoker = (async (args?: unknown) =>
+                    decodeResponse(await send(args))) as RpcInvoker
+                invoker.raw = (args?: unknown) => send(args)
+                return invoker
+            })
+        },
+    })
+}