@abide/abide 0.38.1 → 0.40.0

package/src/lib/server/runtime/internalErrorResponse.ts

@@ -1,4 +1,5 @@
 import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { escapeHtml } from '../../shared/escapeHtml.ts'
 
 /*
 The framework's default 500 response. Shared by the per-request scope's catch
@@ -8,12 +9,14 @@ drift. Only reached when the app supplies no `handleError` hook.
 Secure by default: a bare `Internal Server Error` so paths, library versions,
 and message contents never leak to clients in production. The full stack is
 shown only under `abide dev` (ABIDE_DEV=1, the orchestrator's signal); the
-cause is logged server-side regardless.
+cause is logged server-side regardless. The stack is HTML-escaped because a
+thrown Error built from request-influenced input can carry markup that would
+otherwise execute in the dev browser when embedded in the `<pre>`.
 */
 export function internalErrorResponse(error: unknown): Response {
     const body =
         Bun.env.ABIDE_DEV === '1'
-            ? `<pre>${String((error as Error)?.stack ?? error)}</pre>`
+            ? `<pre>${escapeHtml(String((error as Error)?.stack ?? error))}</pre>`
             : 'Internal Server Error'
     return new Response(body, {
         status: 500,

package/src/lib/server/runtime/snapshotEntryFromCache.ts

@@ -52,7 +52,10 @@ export async function snapshotEntryFromCache(
     if (!isTextual(contentType)) {
         return undefined
     }
-    const body = await response.text()
+    /* Read a CLONE, not the original: a reader that captured this same `entry.promise`
+       before the replacement below still holds `response` and may `.clone()` it — reading
+       the original here would lock its body and throw "Body already used" for that reader. */
+    const body = await response.clone().text()
     entry.promise = Promise.resolve(
         new Response(body, {
             status: response.status,

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,5 +1,7 @@
 import type { ServerWebSocket } from 'bun'
 import { abideLog } from '../../shared/abideLog.ts'
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
 import { error } from '../error.ts'
@@ -104,7 +106,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         if (ws.readyState !== WebSocket.OPEN) {
             return
         }
-        ws.send(JSON.stringify(frame))
+        ws.send(encodeRefJson(frame))
     }
 
     function addSub(state: ConnectionState, name: string, sub: string): boolean {
@@ -152,6 +154,13 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             return fail(resolution.message)
         }
         const { entry } = resolution
+        /* A client reusing a live `sub` id rebinds it: drop the prior binding first (and
+           unsubscribe its topic if that was the last local sub) so the old socket's Set
+           doesn't retain the id forever, leaking the topic subscription. */
+        const rebound = removeSub(state, frame.sub)
+        if (rebound) {
+            ws.unsubscribe(`socket:${rebound}`)
+        }
         const isFirstLocalSub = addSub(state, frame.socket, frame.sub)
         if (isFirstLocalSub) {
             ws.subscribe(`socket:${frame.socket}`)
@@ -305,11 +314,18 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             const text = typeof data === 'string' ? data : textDecoder.decode(data)
             let frame: SocketClientFrame
             try {
-                frame = JSON.parse(text) as SocketClientFrame
+                /* ref-json from abide's own client; a non-abide client sends a plain-JSON
+                   frame, which decodeRefJson rejects (a frame is always an object, never the
+                   `[root, slots]` envelope) — fall back to JSON.parse so raw WS clients work. */
+                try {
+                    frame = decodeRefJson(text) as SocketClientFrame
+                } catch {
+                    frame = JSON.parse(text) as SocketClientFrame
+                }
             } catch {
                 return
             }
-            // JSON.parse succeeds on `null`/`42`/`true`; ignore anything that isn't a frame object.
+            // both codecs yield a value for `null`/`42`/`true` too; ignore anything that isn't a frame object.
             if (typeof frame !== 'object' || frame === null) {
                 return
             }

package/src/lib/server/sockets/defineSocket.ts

@@ -1,4 +1,5 @@
 import { createPushIterator } from '../../shared/createPushIterator.ts'
+import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
 import { socketTapSlot } from '../../shared/socketTapSlot.ts'
 import type { TailHooks } from '../../shared/types/TailHooks.ts'
@@ -123,7 +124,8 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
                silently drift from this construction site (the dispatcher's `send` is already
                typed; this was the last `msg` frame built through an unchecked JSON.stringify). */
             const frame: SocketServerFrame = { type: 'msg', socket: name, message: validated }
-            server.publish(topic, JSON.stringify(frame))
+            // ref-json (matching the dispatcher + client) so a message graph with cycles/shared refs fans out intact.
+            server.publish(topic, encodeRefJson(frame))
         }
     }
 

package/src/lib/shared/REF_JSON_HEADER.ts

@@ -0,0 +1,9 @@
+/*
+Request header the RPC client stamps (value '1') when an `application/json` body is
+ref-json-encoded (encodeRefJson), so the server decodes with the matching codec.
+Its presence is the unambiguous discriminator: ref-json's `[rootValue, slots]`
+envelope collides with a legitimate plain-JSON 2-element array body, so the shape
+alone can't be trusted. Absence means an ordinary JSON body from a non-abide client
+(curl, an OpenAPI-generated SDK, a webhook) — parseArgs reads it with plain JSON.parse.
+*/
+export const REF_JSON_HEADER = 'abide-ref-json'

package/src/lib/shared/REF_JSON_TAGS.ts

@@ -0,0 +1,31 @@
+/*
+Value tags for the ref-json codec (encodeRefJson / decodeRefJson). The output is
+a `[rootValue, slots]` pair: `slots` holds only the hoisted CONTAINERS (objects,
+arrays, Maps, Sets) addressed by index; every other value is encoded INLINE at its
+position — a bare JSON primitive, or one of these tagged arrays. Primitives never
+get their own slot, so a primitive-heavy payload stays close to plain-JSON size and
+speed. A tag is always the first element of a JSON array at a value position; bare
+JSON values are literal primitives, and plain objects only ever appear AS slots
+(hoisted), so user data — even an object keyed `~r` or an array shaped like a tag —
+can't collide with these. Shared between encoder and decoder so the tokens can't drift.
+*/
+export const REF_JSON_TAGS = {
+    // ['~r', slotIndex] — reference to a hoisted container; breaks cycles, preserves shared identity.
+    REF: '~r',
+    // ['~a', ...values]
+    ARRAY: '~a',
+    // ['~m', [[keyValue, valValue], …]]
+    MAP: '~m',
+    // ['~s', [value, …]]
+    SET: '~s',
+    // ['~d', epochMs]
+    DATE: '~d',
+    // ['~x', source, flags]
+    REGEXP: '~x',
+    // ['~g', decimalString] — BigInt can't go through JSON natively.
+    BIGINT: '~g',
+    // ['~u'] — undefined (and functions/symbols, folded to it).
+    UNDEFINED: '~u',
+    // ['~n', token] — the numbers JSON flattens to null: 'NaN' | 'Infinity' | '-Infinity' | '-0'.
+    NUMBER: '~n',
+} as const

package/src/lib/shared/buildRpcRequest.ts

@@ -1,5 +1,7 @@
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { encodeRefJson } from './encodeRefJson.ts'
 import { queryStringFromArgs } from './queryStringFromArgs.ts'
+import { REF_JSON_HEADER } from './REF_JSON_HEADER.ts'
 import type { HttpVerb } from './types/HttpVerb.ts'
 
 /*
@@ -49,11 +51,16 @@ export function buildRpcRequest({
             body: args,
         })
     }
+    /* ref-json (still valid JSON, so the content-type holds) so an arg graph with
+       cycles or shared back-references reaches the handler instead of throwing here.
+       The REF_JSON_HEADER flags the encoding so parseArgs decodes it with the same
+       codec; a non-abide client omits it and parseArgs reads plain JSON.parse. */
     requestHeaders.set('content-type', 'application/json')
+    requestHeaders.set(REF_JSON_HEADER, '1')
     return new Request(new URL(url, baseUrl).href, {
         method,
         headers: requestHeaders,
-        body: JSON.stringify(args),
+        body: encodeRefJson(args),
     })
 }
 

package/src/lib/shared/createRemoteFunction.ts

@@ -8,6 +8,7 @@ import type { ClientFlags } from './types/ClientFlags.ts'
 import type { HttpVerb } from './types/HttpVerb.ts'
 import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
 import type { RemoteFunction } from './types/RemoteFunction.ts'
+import type { RpcOptions } from './types/RpcOptions.ts'
 import type { Subscribable } from './types/Subscribable.ts'
 
 /*
@@ -39,8 +40,12 @@ export function createRemoteFunction<Args, Return>(opts: {
     clients: ClientFlags
     /* Server-side only: exempts a mutating verb from the router's same-origin CSRF gate. */
     crossOrigin?: boolean
-    buildRequest: (args: Args | undefined) => Request
-    invoke: (args: Args | undefined, getRequest: () => Request) => Promise<Response>
+    buildRequest: (args: Args | undefined, opts?: RpcOptions) => Request
+    invoke: (
+        args: Args | undefined,
+        getRequest: () => Request,
+        opts?: RpcOptions,
+    ) => Promise<Response>
     parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
 }): RemoteFunction<Args, Return> {
     const { method, url, clients, crossOrigin, buildRequest, invoke, parseArgsForFetch } = opts
@@ -52,15 +57,19 @@ export function createRemoteFunction<Args, Return>(opts: {
     short-circuits to the prebuilt one — and caches the result so the
     client invoke + the cache meta reader share a single Request.
     */
-    function dispatch(args: Args | undefined, prebuilt?: Request): Promise<Response> {
+    function dispatch(
+        args: Args | undefined,
+        opts?: RpcOptions,
+        prebuilt?: Request,
+    ): Promise<Response> {
         let cached = prebuilt
         function getRequest(): Request {
             if (cached === undefined) {
-                cached = buildRequest(args)
+                cached = buildRequest(args, opts)
             }
             return cached
         }
-        const promise = invoke(args, getRequest)
+        const promise = invoke(args, getRequest, opts)
         recordRemoteMeta(promise, getRequest)
         return promise
     }
@@ -72,8 +81,8 @@ export function createRemoteFunction<Args, Return>(opts: {
     contained type lie — buildRpcRequest's `instanceof FormData` branch handles
     it at runtime.
     */
-    function rawCall(args: Args | FormData): Promise<Response> {
-        return dispatch(args as Args)
+    function rawCall(args: Args | FormData, opts?: RpcOptions): Promise<Response> {
+        return dispatch(args as Args, opts)
     }
     rawCall.method = method
     rawCall.url = url
@@ -81,8 +90,8 @@ export function createRemoteFunction<Args, Return>(opts: {
     Object.defineProperty(rawCall, REMOTE_FUNCTION, { value: true })
     const raw = rawCall as RawRemoteFunction<Args>
 
-    function callable(args: Args | FormData): Promise<Return> {
-        return raw(args).then(decodeResponse) as Promise<Return>
+    function callable(args: Args | FormData, opts?: RpcOptions): Promise<Return> {
+        return raw(args, opts).then(decodeResponse) as Promise<Return>
     }
     callable.method = method
     callable.url = url
@@ -113,10 +122,10 @@ export function createRemoteFunction<Args, Return>(opts: {
                   }
                   throw error
               }
-              return dispatch(args, request)
+              return dispatch(args, undefined, request)
           }
         : (request: Request): Promise<Response> => {
-              return dispatch(undefined, request)
+              return dispatch(undefined, undefined, request)
           }
     return callable as RemoteFunction<Args, Return>
 }

package/src/lib/shared/decodeRefJson.ts

@@ -0,0 +1,110 @@
+/*
+Inverse of encodeRefJson — rebuild a value graph (cycles, shared references, and the
+JSON-hostile types) from a `[rootValue, slots]` ref-json string. Two passes are
+required: pass one allocates every hoisted container as an empty shell, pass two fills
+them. The shell must exist before its contents are filled so a back-reference to an
+ancestor resolves to the already-allocated object — which is what reconnects a cycle.
+Inline primitives need no shell; they decode directly where they sit.
+*/
+import { REF_JSON_TAGS } from './REF_JSON_TAGS'
+
+export function decodeRefJson(text: string): unknown {
+    const parsed = JSON.parse(text)
+    if (!Array.isArray(parsed) || parsed.length !== 2 || !Array.isArray(parsed[1])) {
+        // encodeRefJson always emits a `[rootValue, slots]` pair; anything else isn't our format.
+        throw new TypeError('decodeRefJson: not a ref-json payload')
+    }
+    const [rootValue, slots] = parsed as [unknown, unknown[]]
+    // Pass 1: an empty container shell per slot. Pass 2 fills them so a ref to an ancestor finds its shell.
+    const shells = slots.map(buildShell)
+    slots.forEach((slot, index) => {
+        fillShell(slot, shells[index], shells)
+    })
+    return resolveValue(rootValue, shells)
+}
+
+// Empty container matching a slot's kind. Every slot is a container (only containers are hoisted).
+function buildShell(slot: unknown): unknown {
+    if (Array.isArray(slot)) {
+        if (slot[0] === REF_JSON_TAGS.ARRAY) {
+            return []
+        }
+        if (slot[0] === REF_JSON_TAGS.MAP) {
+            return new Map()
+        }
+        if (slot[0] === REF_JSON_TAGS.SET) {
+            return new Set()
+        }
+    }
+    return {}
+}
+
+// Decode an inline value: bare primitive (itself), a leaf-special, or a reference to a built shell.
+function resolveValue(value: unknown, shells: unknown[]): unknown {
+    if (!Array.isArray(value)) {
+        return value
+    }
+    switch (value[0]) {
+        case REF_JSON_TAGS.REF:
+            return shells[value[1] as number]
+        case REF_JSON_TAGS.UNDEFINED:
+            return undefined
+        case REF_JSON_TAGS.DATE:
+            return new Date(value[1] as number)
+        case REF_JSON_TAGS.REGEXP:
+            return new RegExp(value[1] as string, value[2] as string)
+        case REF_JSON_TAGS.BIGINT:
+            return BigInt(value[1] as string)
+        case REF_JSON_TAGS.NUMBER:
+            return decodeNumberToken(value[1] as string)
+        default:
+            throw new TypeError(`decodeRefJson: unknown value tag ${String(value[0])}`)
+    }
+}
+
+// Fill a container shell from its slot, resolving each inline child.
+function fillShell(slot: unknown, shell: unknown, shells: unknown[]): void {
+    if (!Array.isArray(slot)) {
+        const target = shell as Record<string, unknown>
+        const record = slot as Record<string, unknown>
+        for (const key of Object.keys(record)) {
+            target[key] = resolveValue(record[key], shells)
+        }
+        return
+    }
+    if (slot[0] === REF_JSON_TAGS.ARRAY) {
+        const target = shell as unknown[]
+        // Loop (not push(...spread)) so a huge array can't blow the call-stack arg limit.
+        for (let index = 1; index < slot.length; index++) {
+            target.push(resolveValue(slot[index], shells))
+        }
+        return
+    }
+    if (slot[0] === REF_JSON_TAGS.MAP) {
+        const target = shell as Map<unknown, unknown>
+        for (const [key, val] of slot[1] as [unknown, unknown][]) {
+            target.set(resolveValue(key, shells), resolveValue(val, shells))
+        }
+        return
+    }
+    if (slot[0] === REF_JSON_TAGS.SET) {
+        const target = shell as Set<unknown>
+        for (const member of slot[1] as unknown[]) {
+            target.add(resolveValue(member, shells))
+        }
+    }
+}
+
+// Reverse of encodeRefJson's numberToken.
+function decodeNumberToken(token: string): number {
+    if (token === 'NaN') {
+        return Number.NaN
+    }
+    if (token === 'Infinity') {
+        return Number.POSITIVE_INFINITY
+    }
+    if (token === '-Infinity') {
+        return Number.NEGATIVE_INFINITY
+    }
+    return -0
+}

package/src/lib/shared/encodeRefJson.ts

@@ -0,0 +1,106 @@
+/*
+Serialise an arbitrary value graph to a JSON string that survives cycles and shared
+references — the gap JSON.stringify can't cross. Only mutable CONTAINERS (objects,
+arrays, Maps, Sets) are hoisted into a flat `slots` array and referenced by index, so
+a cycle becomes a back-reference instead of infinite recursion, and two paths to the
+same container decode back to the same object. Primitives are encoded INLINE at their
+position (not hoisted), so a primitive-heavy payload stays near plain-JSON size and
+speed. Beyond plain objects/arrays it round-trips the types JSON drops or coerces:
+undefined, bigint, NaN, ±Infinity, -0, Date, RegExp, Map and Set. Functions and
+symbols can't be serialised and encode as undefined, matching JSON.stringify. Output
+shape is `[rootValue, slots]`. Decode with decodeRefJson. Not streaming — the whole
+graph is walked up front.
+*/
+import { REF_JSON_TAGS } from './REF_JSON_TAGS'
+
+export function encodeRefJson(value: unknown): string {
+    // Hoisted containers only; slots[i] is addressed by ['~r', i]. Primitives stay inline.
+    const slots: unknown[] = []
+    // Container identity → slot index: a revisited container emits a back-reference instead of recursing.
+    const ids = new Map<object, number>()
+
+    // Hoist a container to a slot (once) and return its index. Reserve the index BEFORE encoding
+    // children so a cyclic child resolves back to this slot.
+    function intern(container: object): number {
+        const seen = ids.get(container)
+        if (seen !== undefined) {
+            return seen
+        }
+        const index = slots.length
+        slots.push(0)
+        ids.set(container, index)
+        slots[index] = encodeContainer(container)
+        return index
+    }
+
+    // Inline encoding of a value at its position: bare primitive, leaf-special tag, or a container reference.
+    function encodeValue(input: unknown): unknown {
+        if (input === null) {
+            return null
+        }
+        const type = typeof input
+        if (type === 'string' || type === 'boolean') {
+            return input
+        }
+        if (type === 'number') {
+            const numeric = input as number
+            // -0, NaN, ±Infinity can't round-trip as bare JSON; tag them.
+            if (!Number.isFinite(numeric) || Object.is(numeric, -0)) {
+                return [REF_JSON_TAGS.NUMBER, numberToken(numeric)]
+            }
+            return numeric
+        }
+        if (type === 'bigint') {
+            return [REF_JSON_TAGS.BIGINT, (input as bigint).toString()]
+        }
+        // undefined | function | symbol — not representable; fold to undefined as JSON drops them.
+        if (type !== 'object') {
+            return [REF_JSON_TAGS.UNDEFINED]
+        }
+        if (input instanceof Date) {
+            return [REF_JSON_TAGS.DATE, input.getTime()]
+        }
+        if (input instanceof RegExp) {
+            return [REF_JSON_TAGS.REGEXP, input.source, input.flags]
+        }
+        // Mutable container: hoist for identity and reference it — primitives above never reach here.
+        return [REF_JSON_TAGS.REF, intern(input as object)]
+    }
+
+    // A hoisted container's slot: a tagged array (or plain object) whose nested values are encoded inline.
+    function encodeContainer(container: object): unknown {
+        if (Array.isArray(container)) {
+            return [REF_JSON_TAGS.ARRAY, ...container.map(encodeValue)]
+        }
+        if (container instanceof Map) {
+            return [
+                REF_JSON_TAGS.MAP,
+                Array.from(container, ([key, val]) => [encodeValue(key), encodeValue(val)]),
+            ]
+        }
+        if (container instanceof Set) {
+            return [REF_JSON_TAGS.SET, Array.from(container, encodeValue)]
+        }
+        const record = container as Record<string, unknown>
+        // Own enumerable keys, built in one loop — ~2× cheaper than Object.fromEntries(keys.map(...))
+        // (no intermediate pairs array / closures) on this per-object always-hot path.
+        const encoded: Record<string, unknown> = {}
+        for (const key of Object.keys(record)) {
+            encoded[key] = encodeValue(record[key])
+        }
+        return encoded
+    }
+
+    return JSON.stringify([encodeValue(value), slots])
+}
+
+// Stable token for the numbers JSON can't carry.
+function numberToken(value: number): string {
+    if (Object.is(value, -0)) {
+        return '-0'
+    }
+    if (Number.isNaN(value)) {
+        return 'NaN'
+    }
+    return value > 0 ? 'Infinity' : '-Infinity'
+}

package/src/lib/shared/escapeHtml.ts

@@ -0,0 +1,15 @@
+/*
+HTML-escapes the five HTML-significant characters — the same set the runtime
+`$esc` handles. Isomorphic: shared by the build-time SSR/static-clone generators
+(so server markup and the client clone template can't diverge on escaping) and
+the server runtime's dev error page. Static text reaches the compile callers
+already entity-decoded (see parseTemplate), so escaping round-trips it through
+the HTML parser to the same plain text the client would build directly.
+*/
+export function escapeHtml(value: string): string {
+    return value.replace(
+        /[&<>"']/g,
+        (char) =>
+            ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char,
+    )
+}

package/src/lib/shared/markFrameworkSourcesIgnored.ts

@@ -0,0 +1,47 @@
+import type { SourceMap } from './types/SourceMap.ts'
+
+/*
+The path fragment that identifies abide's own framework sources in a source map.
+The mount stack's "wall" — `scope`, `withScope`, `mountRange`, `runNode`,
+`createEffectNode`, … — all live under the package's `src/lib/`; an author's
+`.abide`/`.ts` frames never do. Matched as the contiguous directory + lib path
+(not the npm name `@abide/abide`, which differs from the on-disk dir `abide`), so
+it holds across the monorepo (`packages/abide/src/lib/`) and an install
+(`node_modules/@abide/abide/src/lib/`) alike, while a user app dir like
+`my-abide-app/src/lib/` does not match.
+
+DERIVED from THIS module's own location (`…/<pkgDir>/src/lib/shared/…`) rather than
+hardcoded, so it tracks a package-dir rename instead of silently going stale (an
+empty ignore-list = the mount-stack wall reappears, which no test would catch). Falls
+back to the literal if the expected `/src/lib/` layout is ever absent.
+*/
+const FRAMEWORK_LIB_PATH = ((): string => {
+    const LIB_MARKER = '/src/lib/'
+    const here = new URL(import.meta.url).pathname
+    const libIndex = here.indexOf(LIB_MARKER)
+    if (libIndex === -1) {
+        return 'abide/src/lib/'
+    }
+    const beforeLib = here.slice(0, libIndex)
+    const packageDir = beforeLib.slice(beforeLib.lastIndexOf('/') + 1)
+    return `${packageDir}${LIB_MARKER}`
+})()
+
+/*
+Marks every abide-framework source in a parsed source map as ignore-listed, so a
+debugger collapses framework frames and a stack trace shows only authored ones —
+the fix for the long mount-stack wall, applied without touching the runtime. Sets
+both the standardized `ignoreList` and Chrome's legacy `x_google_ignoreList` for
+the widest debugger support. Mutates and returns the same map.
+*/
+export function markFrameworkSourcesIgnored(map: SourceMap): SourceMap {
+    const ignored = (map.sources ?? []).reduce<number[]>((indices, source, index) => {
+        if (source !== null && source.includes(FRAMEWORK_LIB_PATH)) {
+            indices.push(index)
+        }
+        return indices
+    }, [])
+    map.ignoreList = ignored
+    map.x_google_ignoreList = ignored
+    return map
+}

package/src/lib/shared/streamResponse.ts

@@ -122,6 +122,11 @@ async function* parseSse<T>(response: Response): AsyncGenerator<T> {
         if (errorMessage !== undefined) {
             throw new Error(errorMessage)
         }
+        /* A frame with an empty `data:` value (a keepalive) carries no payload — skip it
+           rather than letting JSON.parse('') throw and tear down the whole iteration. */
+        if (frame.data === '') {
+            continue
+        }
         yield JSON.parse(frame.data) as T
     }
 }
@@ -157,7 +162,9 @@ 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) {
+        /* Skip blank lines: a CRLF stream yields a lone `\r` (non-zero length) between
+           records, and JSON.parse('\r') would throw and tear down the whole iteration. */
+        if (raw.trim().length === 0) {
             continue
         }
         const parsed = JSON.parse(raw)

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

@@ -1,3 +1,5 @@
+import type { RpcOptions } from './RpcOptions.ts'
+
 /*
 Call signature shared by RemoteFunction and RawRemoteFunction. The base
 signature keeps `args` required so a schema'd verb can't silently drop its
@@ -6,7 +8,14 @@ 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.
+see RemoteFunction. The optional trailing `opts` carries per-call transport
+options (signal/keepalive/priority/cache/headers); the server ignores them,
+so the callable stays isomorphic.
 */
-export type RemoteCallable<Args, Resolved> = ((args: Args | FormData) => Promise<Resolved>) &
-    (undefined extends Args ? (args?: Args | FormData) => Promise<Resolved> : unknown)
+export type RemoteCallable<Args, Resolved> = ((
+    args: Args | FormData,
+    opts?: RpcOptions,
+) => Promise<Resolved>) &
+    (undefined extends Args
+        ? (args?: Args | FormData, opts?: RpcOptions) => Promise<Resolved>
+        : unknown)

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

@@ -0,0 +1,22 @@
+/*
+Per-call transport options for a remote function — a curated slice of RequestInit,
+not the whole thing. Only fields the server handler never observes are exposed, so
+the call stays isomorphic (same behaviour both sides) and a caller can't clobber the
+method, body, or framework headers the RPC contract owns.
+
+- `signal` merges with the scope abort + client timeout (AbortSignal.any), never
+  replacing them; under cache() it's ignored so one reader can't abort a coalesced
+  flight the others share.
+- `keepalive` lets a small fire-and-forget write survive page unload (the browser
+  caps the total keepalive body at ~64KB).
+- `priority` is a fetch scheduling hint; ignored where unsupported.
+- `cache` is the browser HTTP cache mode (distinct from abide's own cache()).
+- `headers` are MERGED onto the framework headers, which win — a caller adds
+  transport metadata (idempotency-key, authorization) but can't overwrite
+  traceparent/content-type/offline. Application data still belongs in `args` (the
+  only schema-validated channel); headers bypass validation.
+*/
+export type RpcOptions = Pick<
+    RequestInit,
+    'signal' | 'keepalive' | 'priority' | 'cache' | 'headers'
+>

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

@@ -0,0 +1,14 @@
+/*
+A source-map JSON object, narrowed to the fields abide reads or writes when
+post-processing emitted maps. `sources` is the list of original files (a null
+entry means an unknown source); `ignoreList` (Source Map v3 / ECMA-426) and its
+legacy Chrome alias `x_google_ignoreList` carry the indices into `sources` a
+debugger should skip. Other standard fields (`version`, `mappings`, …) are passed
+through untouched, so the type stays open.
+*/
+export type SourceMap = {
+    sources?: (string | null)[]
+    ignoreList?: number[]
+    x_google_ignoreList?: number[]
+    [field: string]: unknown
+}

package/src/lib/test/createTestSocketChannel.ts

@@ -3,6 +3,8 @@ import type { SocketClientFrame } from '../server/sockets/types/SocketClientFram
 import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
 import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
 import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
+import { decodeRefJson } from '../shared/decodeRefJson.ts'
+import { encodeRefJson } from '../shared/encodeRefJson.ts'
 
 /*
 Test-side substitute for the browser socketChannel: one ws to the booted
@@ -37,7 +39,8 @@ export function createTestSocketChannel(wsUrl: string): {
     }
 
     function send(frame: SocketClientFrame): void {
-        const message = JSON.stringify(frame)
+        // ref-json, matching the browser channel + the server's dispatcher/publish codec.
+        const message = encodeRefJson(frame)
         if (ws.readyState === WebSocket.OPEN) {
             ws.send(message)
             return
@@ -53,7 +56,8 @@ export function createTestSocketChannel(wsUrl: string): {
     ws.addEventListener('message', (event) => {
         let frame: SocketServerFrame
         try {
-            frame = JSON.parse(event.data as string) as SocketServerFrame
+            // The server sends ref-json frames (createSocketDispatcher/defineSocket); decode to match.
+            frame = decodeRefJson(event.data as string) as SocketServerFrame
         } catch {
             return
         }