@cosmicdrift/kumiko-dispatcher-live 0.374.0 → 0.378.0

package/README.md

@@ -1,15 +1,8 @@
 # @cosmicdrift/kumiko-dispatcher-live
 
-HTTP-only dispatcher for Kumiko UIs. Always online, failures surface immediately. The default client for web admin and cockpit apps.
+Deprecated: import from `@cosmicdrift/kumiko-renderer/live`. This package only
+re-exports it and is removed after wave 4.
 
-## Install
-
-```bash
-bun add @cosmicdrift/kumiko-dispatcher-live
-```
-
-```ts
-import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+```sh
+bun kumiko codemod package-merge . --write
 ```
-
-Documentation: https://kumiko.rocks

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,5 +1 @@
-export { 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";
+export { buildAbortError, buildNetworkError, CSRF_HEADER_NAME, createLiveDispatcher, iterateSseChunks, LOCALE_HEADER_NAME, mapServerError, parseSseBlock, parseSseFrames, readActiveLocale, readCsrfToken, } from "@cosmicdrift/kumiko-renderer/live";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmicdrift/kumiko-dispatcher-live",
-  "version": "0.374.0",
-  "description": "HTTP-only Dispatcher for Kumiko UIs. Always-online; failures surface immediately. Default client for web admin/cockpit apps.",
+  "version": "0.378.0",
+  "description": "Deprecated shim: re-exports @cosmicdrift/kumiko-renderer/live. Removed after wave 4.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
@@ -24,9 +24,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-headless": "0.374.0",
-    "@cosmicdrift/kumiko-types": "0.374.0",
-    "zod": "^4.4.3"
+    "@cosmicdrift/kumiko-renderer": "0.378.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "kumiko-dispatcher-live is a deprecated shim over kumiko-renderer/live",
+    "detail": "The package only re-exports @cosmicdrift/kumiko-renderer/live and is removed after the consumer pass of wave 4.",
+    "migration": "Import from @cosmicdrift/kumiko-renderer/live, or run bun kumiko codemod package-merge . --write."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/dist/csrf.d.ts

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

package/dist/csrf.js

@@ -1,60 +0,0 @@
-// 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/dispatcher-live.d.ts

@@ -1,7 +0,0 @@
-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

@@ -1,286 +0,0 @@
-import { createStore, } from "@cosmicdrift/kumiko-headless";
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-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/envelopes.d.ts

@@ -1,101 +0,0 @@
-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/envelopes.js

@@ -1,35 +0,0 @@
-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/error-mapping.d.ts

@@ -1,16 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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",
-    };
-}

package/dist/locale.d.ts

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

package/dist/locale.js

@@ -1,25 +0,0 @@
-// Active-locale header transport for the live dispatcher.
-//
-// @cosmicdrift/kumiko-renderer-web's DocumentLangSync (mounted by
-// createKumikoApp/createPublicSurface) sets dataset.kumikoLocale from the
-// 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.
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-// 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() {
-    const dataset = propertyOf(propertyOf(propertyOf(globalThis, "document"), "documentElement"), "dataset");
-    const lang = propertyOf(dataset, "kumikoLocale");
-    if (typeof lang !== "string" || lang.length === 0)
-        return undefined;
-    return LOCALE_TAG.test(lang) ? lang : undefined;
-}

package/dist/sse-stream.d.ts

@@ -1,14 +0,0 @@
-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

@@ -1,128 +0,0 @@
-import { StreamFrame } from "@cosmicdrift/kumiko-headless";
-import { serverErrorSchema } from "./envelopes.js";
-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 unparsableErrorFrame(data);
-    }
-    // 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 envelope = serverErrorSchema.safeParse(parsed);
-    if (!envelope.success)
-        return unparsableErrorFrame(data);
-    return mapServerError({
-        ...envelope.data,
-        httpStatus: envelope.data.httpStatus ?? 200,
-    });
-}
-function unparsableErrorFrame(data) {
-    return {
-        code: "stream_error",
-        httpStatus: 200,
-        i18nKey: "errors.unknown",
-        message: data.length > 0 ? data : "stream error frame",
-    };
-}