@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/hooks/use-store.js

@@ -1,12 +1,12 @@
 import { useRef, useSyncExternalStore } from "react";
-// React-Bindings für Kumikos Store-Primitive (`createStore` aus
-// @cosmicdrift/kumiko-headless). Beide Hooks sind dünne Wrapper um React's
-// useSyncExternalStore — die ganze Subscribe/Notify-Mechanik lebt im
-// Store selbst, hier wird nur React verdrahtet.
+// React bindings for Kumiko's store primitive (`createStore` from
+// @cosmicdrift/kumiko-renderer/headless). Both hooks are thin wrappers around React's
+// useSyncExternalStore — the whole subscribe/notify mechanism lives in the
+// store itself, only React wiring happens here.
 //
-// useStore: gibt den ganzen Snapshot zurück. Re-rendert wenn der
-// Store seine Identität wechselt. Object.is-Gate im Store selbst
-// verhindert no-op-Updates.
+// useStore: returns the whole snapshot. Re-renders when the store changes
+// its identity. The Object.is gate in the store itself prevents no-op
+// updates.
 //
 // useStoreSelector: gibt eine abgeleitete Sicht zurück. Selectors die
 // Object-/Array-Literale zurückgeben (z.B. `s => ({ a, b })`) erzeugen

package/dist/hooks/use-stream-handler.d.ts

@@ -1,4 +1,4 @@
-import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import type { DispatcherError } from "../headless/index.ts";
 export type StreamStatus = "idle" | "streaming" | "done" | "error";
 export type UseStreamHandlerResult<TChunk> = {
     readonly chunks: readonly TChunk[];

package/dist/i18n.d.ts

@@ -1,6 +1,6 @@
 import { type Formality, type TranslationValue } from "@cosmicdrift/kumiko-framework/ui-types";
-import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import type { LocaleResolver } from "./headless/index.ts";
 /** Map of i18n key → TranslationValue. Strings may contain `{name}`
  *  placeholders (same semantics as i18next t); plural entries resolve via
  *  `resolveTranslationValue`. */

package/dist/i18n.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 // Locale handling for React consumers of the Kumiko renderer. A thin layer
 // around the platform-agnostic `LocaleResolver` contract from
-// @cosmicdrift/kumiko-headless: provider, hooks, a default no-op resolver,
+// @cosmicdrift/kumiko-renderer/headless: provider, hooks, a default no-op resolver,
 // and a fallback-bundle merge for feature-supplied translations.
 //
 // Architecture:

package/dist/index.js

@@ -4,10 +4,10 @@
 // und reichen ihre konkreten Primitives/Nav/SSE-Impls via Provider
 // in diesen Baum.
 //
-// Wer diesen Layer direkt konsumiert: andere Renderer-Packages
-// (@cosmicdrift/kumiko-renderer-web, später -native) oder eine App die ihren
-// eigenen Bootstrap schreiben will. Normale Samples gehen über
-// @cosmicdrift/kumiko-renderer-web/createKumikoApp, das alle Provider verdrahtet.
+// Direct consumers of this layer: platform bindings
+// (@cosmicdrift/kumiko-renderer/web) or an app writing its own bootstrap.
+// Normal samples go through createKumikoApp from
+// @cosmicdrift/kumiko-renderer/web, which wires all providers.
 export { formalLocaleTag } from "@cosmicdrift/kumiko-framework/ui-types";
 export { synthesizeActionFormEntity, synthesizeActionFormScreen } from "./app/action-form-shim.js";
 export { AppFeaturesProvider, useAppFeatures } from "./app/app-features-context.js";

package/dist/live/csrf.d.ts

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

package/dist/live/csrf.js

@@ -0,0 +1,60 @@
+// CSRF-token extraction from document.cookie.
+//
+// Kumiko's auth-middleware sets two cookies on login (see Vorarbeit A):
+//   - `kumiko_auth`  — HttpOnly, carries the JWT. Invisible to JS.
+//   - `kumiko_csrf`  — JS-readable, carries a random token.
+// Both carry the `__Host-` prefix when the server writes them Secure and
+// without a Domain (see @cosmicdrift/kumiko-types/session-cookies).
+//
+// The double-submit CSRF pattern: every state-changing request echoes the
+// `kumiko_csrf` value into an `X-CSRF-Token` header. Server compares header
+// vs cookie in csrfMiddleware and rejects on mismatch. An attacker on a
+// third-party origin can trigger a cross-site fetch (cookies fly with
+// 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.
+import { CSRF_COOKIE_BASE, sessionCookieNameCandidates, } from "@cosmicdrift/kumiko-types/session-cookies";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+// Kept here as a literal rather than imported from @cosmicdrift/kumiko-framework because this
+// package must remain server-dep-free (runs in browsers and React Native).
+// The framework's csrf-constants-sync test guards against drift.
+export const CSRF_HEADER_NAME = "X-CSRF-Token";
+const CSRF_COOKIE_NAMES = sessionCookieNameCandidates(CSRF_COOKIE_BASE);
+// Reads the 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)
+//
+// Callers ALWAYS handle undefined — the request still goes out, the server
+// 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) {
+    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 valuesByName = new Map();
+    for (const pair of raw.split(/;\s*/)) {
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            continue;
+        const name = pair.slice(0, eq);
+        if (!valuesByName.has(name))
+            valuesByName.set(name, pair.slice(eq + 1));
+    }
+    for (const name of CSRF_COOKIE_NAMES) {
+        const value = valuesByName.get(name);
+        if (value !== undefined)
+            return value.length > 0 ? decodeURIComponent(value) : undefined;
+    }
+    return undefined;
+}
+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 cookie = propertyOf(propertyOf(globalThis, "document"), "cookie");
+    return typeof cookie === "string" ? cookie : undefined;
+}

package/dist/live/dispatcher-live.d.ts

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

package/dist/live/dispatcher-live.js

@@ -0,0 +1,286 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { createStore, } from "../headless/index.js";
+import { CSRF_HEADER_NAME, readCsrfToken } from "./csrf.js";
+import { batchEnvelopeSchema, errorOnlyEnvelopeSchema, queryEnvelopeSchema, writeEnvelopeSchema, } from "./envelopes.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 gateFailure = errorOnlyEnvelopeSchema.safeParse(parsed);
+                if (gateFailure.success) {
+                    throw mapServerErrorWithStatus(gateFailure.data.error, 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 webCrypto = propertyOf(globalThis, "crypto");
+    const randomUUID = propertyOf(webCrypto, "randomUUID");
+    if (typeof randomUUID === "function") {
+        const id = Reflect.apply(randomUUID, webCrypto, []);
+        if (typeof id === "string")
+            return id;
+    }
+    return `req-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+function buildUnexpectedShapeError(status) {
+    // The server did answer: keep its status so 401/5xx handling still applies.
+    return { ...buildNetworkError(`unexpected response shape (${status})`), httpStatus: status };
+}
+// Middleware gates (csrf, origin, auth, rate limits) answer write and batch
+// calls with a bare `{ error }`, without the isSuccess envelope.
+function gateOrShapeError(body, status) {
+    const gateFailure = errorOnlyEnvelopeSchema.safeParse(body);
+    return gateFailure.success
+        ? mapServerErrorWithStatus(gateFailure.data.error, status)
+        : buildUnexpectedShapeError(status);
+}
+// 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 envelope = writeEnvelopeSchema.safeParse(call.body);
+    if (!envelope.success) {
+        return { isSuccess: false, error: gateOrShapeError(call.body, call.status) };
+    }
+    const body = envelope.data;
+    if (body.isSuccess)
+        return { isSuccess: true, data: body.data };
+    return { isSuccess: false, error: mapServerErrorWithStatus(body.error, call.status) };
+}
+function normalizeBatchResponse(call) {
+    if (!call.ok) {
+        return { isSuccess: false, error: call.networkFailure, failedIndex: -1, results: [] };
+    }
+    const envelope = batchEnvelopeSchema.safeParse(call.body);
+    if (!envelope.success) {
+        return {
+            isSuccess: false,
+            error: gateOrShapeError(call.body, call.status),
+            failedIndex: -1,
+            results: [],
+        };
+    }
+    const body = envelope.data;
+    const results = body.results.map((item) => {
+        if (item.isSuccess)
+            return { isSuccess: true, data: item.data };
+        return { isSuccess: false, error: mapServerErrorWithStatus(item.error, call.status) };
+    });
+    if (body.isSuccess)
+        return { isSuccess: true, results };
+    return {
+        isSuccess: false,
+        error: mapServerErrorWithStatus(body.error, call.status),
+        failedIndex: body.failedIndex,
+        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 })`).
+function normalizeQueryResponse(call) {
+    if (!call.ok)
+        return { isSuccess: false, error: call.networkFailure };
+    const envelope = queryEnvelopeSchema.safeParse(call.body);
+    if (!envelope.success) {
+        return { isSuccess: false, error: buildUnexpectedShapeError(call.status) };
+    }
+    const body = envelope.data;
+    if (body.error) {
+        return { isSuccess: false, error: mapServerErrorWithStatus(body.error, call.status) };
+    }
+    return { isSuccess: true, data: body.data };
+}
+// The HTTP status carries the failure-status; the error body itself
+// doesn't repeat it (serializeError drops httpStatus to keep the wire
+// payload lean). Every envelope has to reinject it from Response.status,
+// otherwise status-based checks like isSessionEndedError never match.
+function mapServerErrorWithStatus(error, responseStatus) {
+    return mapServerError({ ...error, httpStatus: error.httpStatus ?? responseStatus });
+}
+function isAbortError(e) {
+    return !!e && typeof e === "object" && "name" in e && e.name === "AbortError";
+}

package/dist/live/envelopes.d.ts

@@ -0,0 +1,101 @@
+import * as z from "zod";
+export declare const serverErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    httpStatus: z.ZodOptional<z.ZodNumber>;
+    i18nKey: z.ZodDefault<z.ZodString>;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodUnknown>;
+    i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    docsUrl: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ServerErrorLike = z.infer<typeof serverErrorSchema>;
+export declare const writeEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    isSuccess: z.ZodLiteral<true>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    isSuccess: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "isSuccess">;
+export declare const batchEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    isSuccess: z.ZodLiteral<true>;
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        isSuccess: z.ZodLiteral<true>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        isSuccess: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: z.ZodString;
+            httpStatus: z.ZodOptional<z.ZodNumber>;
+            i18nKey: z.ZodDefault<z.ZodString>;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+            i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            docsUrl: z.ZodOptional<z.ZodString>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "isSuccess">>;
+}, z.core.$strip>, z.ZodObject<{
+    isSuccess: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    failedIndex: z.ZodNumber;
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        isSuccess: z.ZodLiteral<true>;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        isSuccess: z.ZodLiteral<false>;
+        error: z.ZodObject<{
+            code: z.ZodString;
+            httpStatus: z.ZodOptional<z.ZodNumber>;
+            i18nKey: z.ZodDefault<z.ZodString>;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+            i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            docsUrl: z.ZodOptional<z.ZodString>;
+            requestId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "isSuccess">>;
+}, z.core.$strip>], "isSuccess">;
+export declare const queryEnvelopeSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const errorOnlyEnvelopeSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        httpStatus: z.ZodOptional<z.ZodNumber>;
+        i18nKey: z.ZodDefault<z.ZodString>;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodUnknown>;
+        i18nParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        docsUrl: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/live/envelopes.js

@@ -0,0 +1,35 @@
+import * as z from "zod";
+// Wire envelopes of /api/{write,query,batch,stream}. Only the envelope is
+// validated; `data` payloads stay unknown and are typed by the caller.
+export const serverErrorSchema = z.object({
+    code: z.string(),
+    httpStatus: z.number().optional(),
+    // Some gates (bad-request helper in server.ts, pii-leak-guard) send no
+    // i18nKey; keeping their `code` beats collapsing them into network_error.
+    i18nKey: z.string().default("errors.unknown"),
+    message: z.string(),
+    details: z.unknown().optional(),
+    i18nParams: z.record(z.string(), z.unknown()).optional(),
+    docsUrl: z.string().optional(),
+    requestId: z.string().optional(),
+});
+const writeItemSchema = z.discriminatedUnion("isSuccess", [
+    z.object({ isSuccess: z.literal(true), data: z.unknown().optional() }),
+    z.object({ isSuccess: z.literal(false), error: serverErrorSchema }),
+]);
+export const writeEnvelopeSchema = writeItemSchema;
+export const batchEnvelopeSchema = z.discriminatedUnion("isSuccess", [
+    z.object({ isSuccess: z.literal(true), results: z.array(writeItemSchema) }),
+    z.object({
+        isSuccess: z.literal(false),
+        error: serverErrorSchema,
+        failedIndex: z.number(),
+        results: z.array(writeItemSchema),
+    }),
+]);
+// `error` is nullish: a null/absent error means success, as before.
+export const queryEnvelopeSchema = z.object({
+    data: z.unknown().optional(),
+    error: serverErrorSchema.nullish(),
+});
+export const errorOnlyEnvelopeSchema = z.object({ error: serverErrorSchema });

package/dist/live/error-mapping.d.ts

@@ -0,0 +1,16 @@
+import type { DispatcherError } from "../headless/index.ts";
+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/live/error-mapping.js

@@ -0,0 +1,82 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+// 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 (!isPlainObject(details))
+        return undefined;
+    const { fields, ...otherDetails } = details;
+    if (!Array.isArray(fields)) {
+        // Details without fields still pass through — non-validation errors
+        // (rate-limit, version-conflict, ...) carry their own structured
+        // payload here.
+        return otherDetails;
+    }
+    const mappedFields = [];
+    for (const r of fields) {
+        if (!isPlainObject(r)) {
+            // 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):", r);
+            continue;
+        }
+        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"],
+            ...(isPlainObject(r["params"]) && { params: r["params"] }),
+        });
+    }
+    return { ...otherDetails, 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",
+    };
+}