@cosmicdrift/kumiko-dispatcher-live 0.328.0 → 0.329.0

package/dist/csrf.d.ts

@@ -0,0 +1,3 @@
+export declare const CSRF_COOKIE_NAME = "kumiko_csrf";
+export declare const CSRF_HEADER_NAME = "X-CSRF-Token";
+export declare function readCsrfToken(cookieSource?: string): string | undefined;

package/{src/csrf.ts → dist/csrf.js}

@@ -11,14 +11,12 @@
 // SameSite=Lax on top-level GETs, or Strict blocks them entirely) but
 // cannot READ `document.cookie` of our origin — so they can't populate the
 // header with the matching value.
-
 // Exported constants stay in sync with auth-middleware.ts. Kept here as
 // literals rather than imported from @cosmicdrift/kumiko-framework because this
 // package must remain server-dep-free (runs in browsers and React Native).
 // If the server ever renames the cookie, this file needs a one-line bump.
 export const CSRF_COOKIE_NAME = "kumiko_csrf";
 export const CSRF_HEADER_NAME = "X-CSRF-Token";
-
 // Reads the kumiko_csrf token from document.cookie. Returns undefined when:
 //   - `document` isn't available (SSR, Web Worker, React Native)
 //   - the cookie was never set (before login, after logout)
@@ -27,29 +25,30 @@ export const CSRF_HEADER_NAME = "X-CSRF-Token";
 // rejects with csrf_token_missing and the UI surfaces an auth-expired
 // toast. That's the right failure mode: silently skipping the header
 // would hide a broken auth state.
-export function readCsrfToken(cookieSource?: string): string | undefined {
-  const raw = cookieSource ?? readDocumentCookie();
-  if (!raw) return undefined;
-  // cookie format: "a=1; b=2; kumiko_csrf=<uuid>; c=3"
-  // Parse by splitting on "; " — cookie values never contain that
-  // delimiter literally (they're percent-encoded if needed).
-  const pairs = raw.split(/;\s*/);
-  for (const pair of pairs) {
-    const eq = pair.indexOf("=");
-    if (eq < 0) continue;
-    const name = pair.slice(0, eq);
-    if (name === CSRF_COOKIE_NAME) {
-      const value = pair.slice(eq + 1);
-      return value.length > 0 ? decodeURIComponent(value) : undefined;
+export function readCsrfToken(cookieSource) {
+    const raw = cookieSource ?? readDocumentCookie();
+    if (!raw)
+        return undefined;
+    // cookie format: "a=1; b=2; kumiko_csrf=<uuid>; c=3"
+    // Parse by splitting on "; " — cookie values never contain that
+    // delimiter literally (they're percent-encoded if needed).
+    const pairs = raw.split(/;\s*/);
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            continue;
+        const name = pair.slice(0, eq);
+        if (name === CSRF_COOKIE_NAME) {
+            const value = pair.slice(eq + 1);
+            return value.length > 0 ? decodeURIComponent(value) : undefined;
+        }
     }
-  }
-  return undefined;
+    return undefined;
 }
-
-function readDocumentCookie(): string | undefined {
-  // Guard for non-browser environments. Avoid `typeof document` on the
-  // left so a bundler that const-folds to "document is defined" still
-  // compiles — the actual runtime check is what matters.
-  const g = globalThis as { document?: { cookie?: string } };
-  return g.document?.cookie;
+function readDocumentCookie() {
+    // Guard for non-browser environments. Avoid `typeof document` on the
+    // left so a bundler that const-folds to "document is defined" still
+    // compiles — the actual runtime check is what matters.
+    const g = globalThis;
+    return g.document?.cookie;
 }

package/dist/dispatcher-live.d.ts

@@ -0,0 +1,7 @@
+import { type Dispatcher } from "@cosmicdrift/kumiko-headless";
+export type LiveDispatcherOptions = {
+    readonly baseUrl?: string;
+    readonly fetch?: typeof fetch;
+    readonly readCsrf?: () => string | undefined;
+};
+export declare function createLiveDispatcher(options?: LiveDispatcherOptions): Dispatcher;

package/dist/dispatcher-live.js

@@ -0,0 +1,253 @@
+import { createStore, } from "@cosmicdrift/kumiko-headless";
+import { CSRF_HEADER_NAME, readCsrfToken } from "./csrf.js";
+import { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping.js";
+import { LOCALE_HEADER_NAME, readActiveLocale } from "./locale.js";
+import { iterateSseChunks } from "./sse-stream.js";
+// Paths — matched against the server routes (packages/framework/src/api/routes.ts).
+// Kept as constants so refactors elsewhere (api-constants.ts bumped on the
+// server) flag a mismatch here in a code review instead of at runtime.
+const PATH_WRITE = "/api/write";
+const PATH_QUERY = "/api/query";
+const PATH_BATCH = "/api/batch";
+const PATH_STREAM = "/api/stream";
+export function createLiveDispatcher(options = {}) {
+    const baseUrl = options.baseUrl ?? "";
+    const readCsrf = options.readCsrf ?? (() => readCsrfToken());
+    // Status state — transitions between "online" and "offline" driven
+    // purely by call outcomes. "syncing" never fires here (live has
+    // nothing to catch up on). Initial "online": optimism — we haven't
+    // proven the server is unreachable, and a down-state on boot would
+    // show an offline-toast before the user has even clicked anything.
+    const statusStore = createStore("online");
+    // A status-flip drives network-error → "offline" and any subsequent
+    // success → "online". Typed server failures (400, 403, ...) don't flip
+    // status — the network reached the server, the server answered, we're
+    // online in every operational sense.
+    function observeNetworkOutcome(ok) {
+        statusStore.setState(ok ? "online" : "offline");
+    }
+    async function callJson(path, body, signal) {
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f) {
+            return {
+                ok: false,
+                networkFailure: buildNetworkError("fetch is not available in this runtime — inject via LiveDispatcherOptions.fetch"),
+            };
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        const csrf = readCsrf();
+        if (csrf !== undefined)
+            headers[CSRF_HEADER_NAME] = csrf;
+        const locale = readActiveLocale();
+        if (locale !== undefined)
+            headers[LOCALE_HEADER_NAME] = locale;
+        // If no CSRF token, still send the request — public / pre-login
+        // routes like /auth/login don't require CSRF, and POST /write/query/
+        // batch against a logged-out client returns 401 via auth-middleware
+        // which is a cleaner error than a csrf-mismatch.
+        let response;
+        try {
+            response = await f(`${baseUrl}${path}`, {
+                method: "POST",
+                credentials: "include",
+                headers,
+                body: JSON.stringify(body),
+                signal,
+            });
+        }
+        catch (e) {
+            // Abort surfaces as a DOMException with name="AbortError" in the
+            // standard fetch contract. Handle it distinctly so the caller
+            // doesn't see the user-cancellation as a network drop.
+            if (isAbortError(e)) {
+                return { ok: false, networkFailure: buildAbortError() };
+            }
+            observeNetworkOutcome(false);
+            return { ok: false, networkFailure: buildNetworkError(e) };
+        }
+        observeNetworkOutcome(true);
+        // JSON body parse. A server that returned a non-JSON body for any
+        // reason (HTML error page from a reverse-proxy, empty body on a
+        // weird 502) maps to network-error — structurally the same as a
+        // fetch-throw from the UI's perspective.
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch (e) {
+            return {
+                ok: false,
+                networkFailure: buildNetworkError(`invalid JSON response (${response.status}): ${e instanceof Error ? e.message : String(e)}`),
+            };
+        }
+        return { ok: true, body: parsed, status: response.status };
+    }
+    return {
+        async write(type, payload, opts) {
+            const body = { type, payload };
+            // Idempotency by default (#761): without a requestId the server-side
+            // dedup never engages and a transport-level double-send duplicates
+            // events. Callers with a logical-submit id (savable queue, form
+            // controllers) pass their own and keep it across their retries.
+            body["requestId"] = opts?.requestId ?? generateRequestId();
+            const call = await callJson(PATH_WRITE, body, opts?.signal);
+            return normalizeWriteResult(call);
+        },
+        async query(type, payload, opts) {
+            const body = { type, payload };
+            const call = await callJson(PATH_QUERY, body, opts?.signal);
+            return normalizeQueryResponse(call);
+        },
+        async batch(commands, opts) {
+            const body = { commands };
+            // One id for the whole batch — the server caches the BatchResult
+            // under it, so a retried batch returns the cached outcome instead of
+            // re-executing the commands (#761).
+            body["requestId"] = opts?.requestId ?? generateRequestId();
+            const call = await callJson(PATH_BATCH, body, opts?.signal);
+            return normalizeBatchResponse(call);
+        },
+        async *stream(type, payload, opts) {
+            const f = options.fetch ?? globalThis.fetch;
+            if (!f) {
+                throw buildNetworkError("fetch is not available in this runtime — inject via LiveDispatcherOptions.fetch");
+            }
+            const headers = {
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+            };
+            const csrf = readCsrf();
+            if (csrf !== undefined)
+                headers[CSRF_HEADER_NAME] = csrf;
+            const locale = readActiveLocale();
+            if (locale !== undefined)
+                headers[LOCALE_HEADER_NAME] = locale;
+            let response;
+            try {
+                response = await f(`${baseUrl}${PATH_STREAM}`, {
+                    method: "POST",
+                    credentials: "include",
+                    headers,
+                    body: JSON.stringify({ type, payload }),
+                    signal: opts?.signal,
+                });
+            }
+            catch (e) {
+                if (isAbortError(e))
+                    throw buildAbortError();
+                observeNetworkOutcome(false);
+                throw buildNetworkError(e);
+            }
+            observeNetworkOutcome(true);
+            const contentType = response.headers.get("content-type") ?? "";
+            // Pre-SSE gate failures (PAT deny, etc.) return a normal JSON error
+            // envelope — map them like /api/query before trying to read SSE.
+            if (!contentType.includes("text/event-stream")) {
+                let parsed;
+                try {
+                    parsed = await response.json();
+                }
+                catch (e) {
+                    throw buildNetworkError(`invalid stream response (${response.status}): ${e instanceof Error ? e.message : String(e)}`);
+                }
+                const body = parsed;
+                if (body?.error) {
+                    throw mapServerError({
+                        ...body.error,
+                        httpStatus: body.error.httpStatus ?? response.status,
+                    });
+                }
+                throw buildNetworkError(`unexpected non-SSE stream response (${response.status})`);
+            }
+            if (!response.body) {
+                throw buildNetworkError("stream response has no body");
+            }
+            try {
+                yield* iterateSseChunks(response.body);
+            }
+            catch (e) {
+                // Abort can surface on the initial fetch OR while reading the SSE
+                // body — both must map to the same `aborted` envelope so hooks
+                // (useStreamHandler) can ignore user-cancel without an error toast.
+                if (isAbortError(e) || opts?.signal?.aborted)
+                    throw buildAbortError();
+                observeNetworkOutcome(false);
+                throw e;
+            }
+        },
+        statusStore,
+        // Live dispatcher has no queue. Returning a constant empty array
+        // keeps the contract uniform with savable; UI code that renders
+        // pending-badges draws nothing instead of branching on dispatcher
+        // type.
+        pendingWrites: () => EMPTY_PENDING_WRITES,
+        pendingFiles: () => EMPTY_PENDING_FILES,
+    };
+}
+const EMPTY_PENDING_WRITES = Object.freeze([]);
+const EMPTY_PENDING_FILES = Object.freeze([]);
+// crypto.randomUUID where available (browser, Bun, Node); Math.random
+// fallback for React-Native runtimes without the WebCrypto polyfill.
+// Uniqueness only needs to hold per user within the server's dedup window —
+// this is an idempotency key, not a security token.
+function generateRequestId() {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function")
+        return c.randomUUID();
+    return `req-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+// Write / Batch share the same envelope: `{ isSuccess: true, data }` on
+// success, `{ isSuccess: false, error: ServerErrorInfo, ... }` on failure.
+// Query uses a different envelope (see normalizeQueryResponse).
+function normalizeWriteResult(call) {
+    if (!call.ok)
+        return { isSuccess: false, error: call.networkFailure };
+    const body = call.body;
+    if (body.isSuccess)
+        return body;
+    return { isSuccess: false, error: mapServerError(body.error) };
+}
+function normalizeBatchResponse(call) {
+    if (!call.ok) {
+        return { isSuccess: false, error: call.networkFailure, failedIndex: -1, results: [] };
+    }
+    const body = call.body;
+    if (body.isSuccess)
+        return body;
+    return {
+        isSuccess: false,
+        error: mapServerError(body.error),
+        failedIndex: body.failedIndex,
+        results: body.results,
+    };
+}
+// Query envelope: Kumiko's /api/query returns `{ data: ... }` on success
+// (no isSuccess flag) and `{ error: { code, i18nKey, message, ... } }`
+// on failure. Source of truth: packages/framework/src/api/routes.ts:85
+// (the query route handler that emits `c.json({ data: result })`).
+// The HTTP status carries the failure-status; the error body itself
+// doesn't repeat it (serializeError drops httpStatus to keep the wire
+// payload lean). We have to reinject httpStatus from the Response.status
+// here.
+function normalizeQueryResponse(call) {
+    if (!call.ok)
+        return { isSuccess: false, error: call.networkFailure };
+    const body = call.body;
+    if (body && "error" in body && body.error) {
+        const errorWithStatus = {
+            ...body.error,
+            httpStatus: body.error.httpStatus ?? call.status,
+        };
+        return { isSuccess: false, error: mapServerError(errorWithStatus) };
+    }
+    return { isSuccess: true, data: body?.data };
+}
+function isAbortError(e) {
+    return (!!e &&
+        typeof e === "object" &&
+        "name" in e && // @cast-boundary error-details
+        e.name === "AbortError");
+}

package/dist/error-mapping.d.ts

@@ -0,0 +1,16 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+type ServerErrorInfo = {
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly i18nKey: string;
+    readonly i18nParams?: Readonly<Record<string, unknown>>;
+    readonly message: string;
+    readonly details?: unknown;
+    readonly docsUrl?: string;
+    readonly requestId?: string;
+    readonly timestamp?: string;
+};
+export declare function mapServerError(serverError: ServerErrorInfo): DispatcherError;
+export declare function buildNetworkError(cause: unknown): DispatcherError;
+export declare function buildAbortError(): DispatcherError;
+export {};

package/dist/error-mapping.js

@@ -0,0 +1,85 @@
+// Narrow cast into the DispatcherError shape. Pass-through for everything
+// except `details.fields`, which we normalize: the server uses
+// ValidationFieldIssue (path/code/i18nKey/params), which is structurally
+// identical to FieldIssue — but we re-build it so a future field-addition
+// on either side forces a compile error here, the right place to update.
+export function mapServerError(serverError) {
+    const normalizedDetails = normalizeDetails(serverError.details);
+    return {
+        code: serverError.code,
+        httpStatus: serverError.httpStatus,
+        i18nKey: serverError.i18nKey,
+        message: serverError.message,
+        ...(serverError.i18nParams && { i18nParams: serverError.i18nParams }),
+        ...(normalizedDetails && { details: normalizedDetails }),
+        ...(serverError.docsUrl && { docsUrl: serverError.docsUrl }),
+        ...(serverError.requestId && { requestId: serverError.requestId }),
+    };
+}
+function normalizeDetails(details) {
+    if (!details || typeof details !== "object")
+        return undefined;
+    const d = details; // @cast-boundary error-details — generic über alle DispatcherError-shapes
+    const fields = d["fields"];
+    if (!Array.isArray(fields)) {
+        // Details without fields still pass through — non-validation errors
+        // (rate-limit, version-conflict, ...) carry their own structured
+        // payload here.
+        return d;
+    }
+    const mappedFields = [];
+    for (const f of fields) {
+        if (!f || typeof f !== "object") {
+            // Server sent a non-object entry in details.fields — contract
+            // breach (ValidationFieldIssue shape is required). Warn so the
+            // skip doesn't hide a broken server build.
+            // biome-ignore lint/suspicious/noConsole: ops-visible warning when the server breaks the validation-error contract
+            console.warn("[dispatcher-live] dropping malformed field issue (not an object):", f);
+            continue;
+        }
+        const r = f; // @cast-boundary error-details
+        if (typeof r["path"] !== "string" ||
+            typeof r["code"] !== "string" ||
+            typeof r["i18nKey"] !== "string") {
+            // Entry is an object but missing required keys — same reasoning.
+            // biome-ignore lint/suspicious/noConsole: ops-visible warning when the server breaks the validation-error contract
+            console.warn("[dispatcher-live] dropping malformed field issue (missing keys):", r);
+            continue;
+        }
+        mappedFields.push({
+            path: r["path"],
+            code: r["code"],
+            i18nKey: r["i18nKey"],
+            ...(r["params"] !== undefined && {
+                params: r["params"],
+            }),
+        });
+    }
+    return { ...d, fields: mappedFields };
+}
+// Builds a DispatcherError for a failure that never reached the server —
+// network dropped, DNS error, CORS block, fetch() threw. The UI should
+// surface this differently (offline indicator, retry button) from a
+// typed server-rejection; callers key off `code === "network_error"`.
+export function buildNetworkError(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause ?? "network error");
+    return {
+        code: "network_error",
+        // 0 is the JS fetch-failure convention (xhr.status is 0 on abort/fail
+        // too). Distinguishes network from typed 5xx server errors.
+        httpStatus: 0,
+        i18nKey: "dispatcher.errors.network",
+        message,
+    };
+}
+// Abort-specific error — used when the caller canceled via AbortSignal.
+// Distinct code so a form submit that was cancelled because the user
+// closed the modal doesn't toast "network error" (confusing).
+export function buildAbortError() {
+    return {
+        code: "aborted",
+        httpStatus: 0,
+        i18nKey: "dispatcher.errors.aborted",
+        message: "request was aborted",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, readCsrfToken } from "./csrf.js";
+export type { LiveDispatcherOptions } from "./dispatcher-live.js";
+export { createLiveDispatcher } from "./dispatcher-live.js";
+export { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping.js";
+export { LOCALE_HEADER_NAME, readActiveLocale } from "./locale.js";
+export type { SseFrame } from "./sse-stream.js";
+export { iterateSseChunks, parseSseBlock, parseSseFrames } from "./sse-stream.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, readCsrfToken } from "./csrf.js";
+export { createLiveDispatcher } from "./dispatcher-live.js";
+export { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping.js";
+export { LOCALE_HEADER_NAME, readActiveLocale } from "./locale.js";
+export { iterateSseChunks, parseSseBlock, parseSseFrames } from "./sse-stream.js";

package/dist/locale.d.ts

@@ -0,0 +1,2 @@
+export declare const LOCALE_HEADER_NAME = "X-Locale";
+export declare function readActiveLocale(): string | undefined;

package/{src/locale.ts → dist/locale.js}

@@ -5,24 +5,20 @@
 // LocaleResolver. This module reads that marker back so every outgoing
 // request carries the language the user is ACTUALLY using — not a static
 // <html lang> — with zero app-side wiring.
-
 // Kept in sync with LOCALE_HEADER_NAME in api-constants.ts by hand rather
 // than imported from @cosmicdrift/kumiko-framework — this package must
 // remain server-dep-free (runs in browsers and React Native).
 export const LOCALE_HEADER_NAME = "X-Locale";
-
 // Loose BCP-47 tag check — reject newlines/junk that would break fetch headers.
 const LOCALE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
-
 // Reads dataset.kumikoLocale. Returns undefined for non-browser environments
 // (SSR, Web Worker, React Native), before DocumentLangSync has run, or when
 // the value is not a safe language tag — callers skip the header and the
 // server falls back to Accept-Language, then its boot default.
-export function readActiveLocale(): string | undefined {
-  const g = globalThis as {
-    document?: { documentElement?: { dataset?: { kumikoLocale?: string } } };
-  };
-  const lang = g.document?.documentElement?.dataset?.kumikoLocale;
-  if (lang === undefined || lang.length === 0) return undefined;
-  return LOCALE_TAG.test(lang) ? lang : undefined;
+export function readActiveLocale() {
+    const g = globalThis;
+    const lang = g.document?.documentElement?.dataset?.kumikoLocale;
+    if (lang === undefined || lang.length === 0)
+        return undefined;
+    return LOCALE_TAG.test(lang) ? lang : undefined;
 }

package/dist/sse-stream.d.ts

@@ -0,0 +1,14 @@
+export type SseFrame = {
+    readonly event: string;
+    readonly data: string;
+};
+export declare function parseSseBlock(block: string): SseFrame | null;
+/** Split a complete SSE body (tests / non-streaming buffers) into frames. */
+export declare function parseSseFrames(text: string): SseFrame[];
+/**
+ * Incremental SSE reader over a fetch body. Yields `chunk` payloads as
+ * parsed JSON; swallows `ping`; returns on `done`; throws DispatcherError
+ * on `error` frames. Caller is responsible for aborting the underlying
+ * fetch via AbortSignal.
+ */
+export declare function iterateSseChunks<TChunk>(body: ReadableStream<Uint8Array>): AsyncGenerator<TChunk, void, undefined>;

package/dist/sse-stream.js

@@ -0,0 +1,122 @@
+import { StreamFrame } from "@cosmicdrift/kumiko-headless";
+import { mapServerError } from "./error-mapping.js";
+export function parseSseBlock(block) {
+    const trimmed = block.trim();
+    if (trimmed.length === 0)
+        return null;
+    const event = /^event: (.*)$/m.exec(trimmed)?.[1] ?? "";
+    const data = /^data: (.*)$/m.exec(trimmed)?.[1] ?? "";
+    return { event, data };
+}
+/** Split a complete SSE body (tests / non-streaming buffers) into frames. */
+export function parseSseFrames(text) {
+    return text
+        .split("\n\n")
+        .map(parseSseBlock)
+        .filter((f) => f !== null);
+}
+/**
+ * Incremental SSE reader over a fetch body. Yields `chunk` payloads as
+ * parsed JSON; swallows `ping`; returns on `done`; throws DispatcherError
+ * on `error` frames. Caller is responsible for aborting the underlying
+ * fetch via AbortSignal.
+ */
+export async function* iterateSseChunks(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let sawDone = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const parts = buffer.split("\n\n");
+            buffer = parts.pop() ?? "";
+            for (const part of parts) {
+                const frame = parseSseBlock(part);
+                if (frame === null)
+                    continue;
+                if (frame.event === StreamFrame.ping)
+                    continue;
+                // skip: terminal SSE done frame — end the generator cleanly
+                if (frame.event === StreamFrame.done) {
+                    sawDone = true;
+                    return;
+                }
+                if (frame.event === StreamFrame.error) {
+                    throw frameDataToDispatcherError(frame.data);
+                }
+                if (frame.event === StreamFrame.chunk) {
+                    yield parseChunkData(frame.data);
+                }
+            }
+        }
+        // Trailing buffer without final blank line (some runtimes).
+        const frame = parseSseBlock(buffer);
+        if (frame?.event === StreamFrame.chunk) {
+            yield parseChunkData(frame.data);
+        }
+        else if (frame?.event === StreamFrame.error) {
+            throw frameDataToDispatcherError(frame.data);
+        }
+        else if (frame?.event === StreamFrame.done) {
+            sawDone = true;
+        }
+        if (!sawDone) {
+            throw buildTruncatedStreamError();
+        }
+    }
+    finally {
+        // cancel() releases the reader's lock too (safe on an already-drained
+        // stream) and, unlike releaseLock() alone, tells the underlying HTTP
+        // response to close instead of leaving the connection open until the
+        // server finishes writing a body no one is reading anymore.
+        await reader.cancel().catch(() => { });
+    }
+}
+function parseChunkData(data) {
+    try {
+        return JSON.parse(data);
+    }
+    catch (e) {
+        const cause = e instanceof Error ? e.message : String(e);
+        throw {
+            code: "stream_error",
+            httpStatus: 200,
+            i18nKey: "errors.unknown",
+            message: `malformed chunk frame: ${cause}`,
+        };
+    }
+}
+function buildTruncatedStreamError() {
+    return {
+        code: "stream_error",
+        httpStatus: 200,
+        i18nKey: "errors.unknown",
+        message: "stream ended without a done frame",
+    };
+}
+function frameDataToDispatcherError(data) {
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch {
+        return {
+            code: "stream_error",
+            httpStatus: 200,
+            i18nKey: "errors.unknown",
+            message: data.length > 0 ? data : "stream error frame",
+        };
+    }
+    // Server serializeError shape — mapServerError expects the same fields
+    // as /api/query failures (httpStatus may be absent; reinject 200 for
+    // mid-stream gates that flush SSE headers first).
+    const err = parsed;
+    return mapServerError({
+        ...err,
+        httpStatus: err.httpStatus ?? 200,
+    });
+}