@cosmicdrift/kumiko-dispatcher-live 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@cosmicdrift/kumiko-dispatcher-live",
+  "version": "0.1.0",
+  "description": "HTTP-only Dispatcher for Kumiko UIs. Always-online; failures surface immediately. Default client for web admin/cockpit apps.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "directory": "packages/dispatcher-live"
+  },
+  "bugs": {
+    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.so",
+  "type": "module",
+  "kumiko": {
+    "runtime": "client"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-headless": "workspace:*"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/csrf.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, readCsrfToken } from "../csrf";
+
+describe("CSRF token extraction", () => {
+  test("constants match server-side expectations", () => {
+    // If the server renames the cookie or header, these literals must
+    // be bumped in sync — see auth-middleware.ts.
+    expect(CSRF_COOKIE_NAME).toBe("kumiko_csrf");
+    expect(CSRF_HEADER_NAME).toBe("X-CSRF-Token");
+  });
+
+  test("reads the token from a cookie string with one entry", () => {
+    const token = readCsrfToken("kumiko_csrf=abc-123");
+    expect(token).toBe("abc-123");
+  });
+
+  test("reads the token from a cookie string with multiple entries", () => {
+    const raw = "kumiko_auth=xxx; kumiko_csrf=the-token; tenant=42";
+    expect(readCsrfToken(raw)).toBe("the-token");
+  });
+
+  test("handles whitespace variations between entries", () => {
+    // Browsers typically emit "; " but servers or testing tools can
+    // emit a single space, no space, or trailing semicolons.
+    expect(readCsrfToken("a=1;kumiko_csrf=x")).toBe("x");
+    expect(readCsrfToken("a=1;   kumiko_csrf=x")).toBe("x");
+    expect(readCsrfToken("kumiko_csrf=x;")).toBe("x");
+  });
+
+  test("decodes percent-encoded values", () => {
+    // UUIDs don't need encoding, but a future migration to opaque
+    // tokens might. Decoding is the standard cookie-semantic.
+    expect(readCsrfToken("kumiko_csrf=a%20b")).toBe("a b");
+  });
+
+  test("returns undefined when the cookie is absent", () => {
+    expect(readCsrfToken("other=value")).toBeUndefined();
+  });
+
+  test("returns undefined for an empty cookie value", () => {
+    // `kumiko_csrf=` with no value — treated as "not set", caller will
+    // send the request without the header and the server will reject
+    // with csrf_token_missing (correct failure mode).
+    expect(readCsrfToken("kumiko_csrf=")).toBeUndefined();
+  });
+
+  test("returns undefined when no cookieSource and no document", () => {
+    // Runs in Node without a document — the safe fallback.
+    expect(readCsrfToken()).toBeUndefined();
+  });
+
+  test("substring matches don't fool the parser", () => {
+    // "not_kumiko_csrf" starts with "not_" — shouldn't be mistaken for
+    // the real cookie name. The parser splits on ; first, then on =,
+    // then compares the NAME exactly.
+    const raw = "not_kumiko_csrf=other; kumiko_csrf=real";
+    expect(readCsrfToken(raw)).toBe("real");
+
+    const onlyFake = "not_kumiko_csrf=other";
+    expect(readCsrfToken(onlyFake)).toBeUndefined();
+  });
+});

package/src/__tests__/dispatcher-live.test.ts

@@ -0,0 +1,293 @@
+import { describe, expect, test, vi } from "vitest";
+import { createLiveDispatcher } from "../dispatcher-live";
+
+// Builds a fake fetch that returns a JSON body with the given
+// payload and status. Exposes the captured Request argv so tests can
+// assert on URL/headers/body.
+function makeFetch(respond: { readonly status?: number; readonly body: unknown }): {
+  readonly fetch: typeof fetch;
+  readonly calls: Array<{ url: string; init: RequestInit }>;
+} {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const fetchMock = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    return {
+      ok: (respond.status ?? 200) < 400,
+      status: respond.status ?? 200,
+      async json() {
+        return respond.body;
+      },
+    } as unknown as Response;
+  });
+  return { fetch: fetchMock as unknown as typeof globalThis.fetch, calls };
+}
+
+describe("createLiveDispatcher", () => {
+  test("write: POSTs to /api/write with Content-Type, Accept, credentials, CSRF header", async () => {
+    const { fetch, calls } = makeFetch({
+      body: { isSuccess: true, data: { id: "srv-1" } },
+    });
+    const disp = createLiveDispatcher({
+      fetch,
+      readCsrf: () => "csrf-abc",
+    });
+
+    const result = await disp.write("app:write:task:create", { title: "hello" });
+
+    expect(result.isSuccess).toBe(true);
+    if (result.isSuccess) expect((result.data as { id: string }).id).toBe("srv-1");
+
+    expect(calls).toHaveLength(1);
+    const call = calls[0];
+    expect(call?.url).toBe("/api/write");
+    expect(call?.init.method).toBe("POST");
+    expect(call?.init.credentials).toBe("include");
+    const headers = call?.init.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+    expect(headers["X-CSRF-Token"]).toBe("csrf-abc");
+    const body = JSON.parse(call?.init.body as string);
+    expect(body).toEqual({ type: "app:write:task:create", payload: { title: "hello" } });
+  });
+
+  test("write: propagates requestId into body when provided", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, data: {} } });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    await disp.write("app:write:x:create", { a: 1 }, { requestId: "idem-99" });
+
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(body.requestId).toBe("idem-99");
+  });
+
+  test("write: no CSRF token → header omitted, request still fires (server will 401/csrf-mismatch)", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, data: {} } });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => undefined });
+
+    await disp.write("x", {});
+
+    const headers = calls[0]?.init.headers as Record<string, string>;
+    expect("X-CSRF-Token" in headers).toBe(false);
+  });
+
+  test("write: maps server-failure envelope to DispatcherError", async () => {
+    const { fetch } = makeFetch({
+      status: 400,
+      body: {
+        isSuccess: false,
+        error: {
+          code: "validation_error",
+          httpStatus: 400,
+          i18nKey: "errors.validation.failed",
+          message: "Validation failed",
+          details: {
+            fields: [{ path: "title", code: "too_small", i18nKey: "errors.validation.too_small" }],
+          },
+        },
+      },
+    });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    const result = await disp.write("x", {});
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("validation_error");
+      expect(result.error.details?.fields?.[0]?.path).toBe("title");
+    }
+  });
+
+  test("query: POSTs to /api/query", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, data: [] } });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    await disp.query("app:query:task:list", { limit: 10 });
+
+    expect(calls[0]?.url).toBe("/api/query");
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(body).toEqual({ type: "app:query:task:list", payload: { limit: 10 } });
+  });
+
+  test("batch: POSTs to /api/batch with commands array", async () => {
+    const { fetch, calls } = makeFetch({
+      body: { isSuccess: true, results: [] },
+    });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    const commands = [
+      { type: "x:write:a:create", payload: { a: 1 } },
+      { type: "x:write:b:create", payload: { b: 2 } },
+    ];
+    const result = await disp.batch(commands);
+
+    expect(result.isSuccess).toBe(true);
+    expect(calls[0]?.url).toBe("/api/batch");
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(body.commands).toEqual(commands);
+  });
+
+  test("baseUrl prefix: full origin is prepended to path", async () => {
+    const { fetch, calls } = makeFetch({ body: { isSuccess: true, data: {} } });
+    const disp = createLiveDispatcher({
+      baseUrl: "https://api.example.com",
+      fetch,
+      readCsrf: () => "t",
+    });
+
+    await disp.write("x", {});
+
+    expect(calls[0]?.url).toBe("https://api.example.com/api/write");
+  });
+
+  test("network error → failure with code='network_error', status flips offline", async () => {
+    const fetch = vi.fn(async () => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof globalThis.fetch;
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    const seen: string[] = [];
+    disp.statusStore.subscribe(() => seen.push(disp.statusStore.getSnapshot()));
+
+    const result = await disp.write("x", {});
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) expect(result.error.code).toBe("network_error");
+    expect(disp.statusStore.getSnapshot()).toBe("offline");
+    expect(seen).toEqual(["offline"]);
+  });
+
+  test("network recovery: after offline → successful call flips back to online", async () => {
+    let failNext = true;
+    const fetch = vi.fn(async () => {
+      if (failNext) {
+        failNext = false;
+        throw new Error("boom");
+      }
+      return {
+        ok: true,
+        status: 200,
+        async json() {
+          return { isSuccess: true, data: {} };
+        },
+      } as unknown as Response;
+    }) as unknown as typeof globalThis.fetch;
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    const seen: string[] = [];
+    disp.statusStore.subscribe(() => seen.push(disp.statusStore.getSnapshot()));
+
+    await disp.write("x", {}); // offline
+    await disp.write("x", {}); // online
+
+    expect(seen).toEqual(["offline", "online"]);
+    expect(disp.statusStore.getSnapshot()).toBe("online");
+  });
+
+  test("abort signal: request propagated + AbortError mapped to 'aborted'", async () => {
+    const controller = new AbortController();
+    const fetch = vi.fn(async (_url: string, init: RequestInit) => {
+      // Simulate real fetch: throw AbortError synchronously when signal
+      // is already aborted.
+      if (init.signal?.aborted) {
+        const e = new Error("The operation was aborted.");
+        e.name = "AbortError";
+        throw e;
+      }
+      return {
+        ok: true,
+        status: 200,
+        async json() {
+          return { isSuccess: true, data: {} };
+        },
+      } as unknown as Response;
+    }) as unknown as typeof globalThis.fetch;
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    controller.abort();
+    const result = await disp.write("x", {}, { signal: controller.signal });
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) expect(result.error.code).toBe("aborted");
+    // Abort is a user cancellation, not a network outage — status MUST
+    // not flip to offline (UX: cancelling a save shouldn't make the
+    // online-indicator light up red).
+    expect(disp.statusStore.getSnapshot()).toBe("online");
+  });
+
+  test("non-JSON server response (HTML 502 page) maps to network_error", async () => {
+    const fetch = vi.fn(async () => {
+      return {
+        ok: false,
+        status: 502,
+        async json() {
+          throw new SyntaxError("Unexpected token < in JSON at position 0");
+        },
+      } as unknown as Response;
+    }) as unknown as typeof globalThis.fetch;
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    const result = await disp.write("x", {});
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) expect(result.error.code).toBe("network_error");
+  });
+
+  test("typed server failure (400) does NOT flip status to offline — server WAS reached", async () => {
+    const { fetch } = makeFetch({
+      status: 400,
+      body: {
+        isSuccess: false,
+        error: {
+          code: "validation_error",
+          httpStatus: 400,
+          i18nKey: "errors.validation.failed",
+          message: "nope",
+        },
+      },
+    });
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+    const seen: string[] = [];
+    disp.statusStore.subscribe(() => seen.push(disp.statusStore.getSnapshot()));
+
+    await disp.write("x", {});
+
+    expect(disp.statusStore.getSnapshot()).toBe("online");
+    expect(seen).toEqual([]); // no status flip
+  });
+
+  test("pendingWrites / pendingFiles always return empty arrays for live dispatcher", () => {
+    const disp = createLiveDispatcher({ fetch: vi.fn() as unknown as typeof globalThis.fetch });
+    expect(disp.pendingWrites()).toEqual([]);
+    expect(disp.pendingFiles()).toEqual([]);
+  });
+
+  test("subscribeStatus returns unsubscribe handle", async () => {
+    const fetch = vi.fn(async () => {
+      throw new Error("boom");
+    }) as unknown as typeof globalThis.fetch;
+    const disp = createLiveDispatcher({ fetch, readCsrf: () => "t" });
+
+    const listener = vi.fn();
+    const unsub = disp.statusStore.subscribe(listener);
+    await disp.write("x", {});
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsub();
+    // A second status change (back to online) should not fire listener.
+    // But — if fetch keeps throwing we stay offline (no transition).
+    // Force a flip back by resetting fetch to success:
+    const fetchOk = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      async json() {
+        return { isSuccess: true, data: {} };
+      },
+    })) as unknown as typeof globalThis.fetch;
+    const disp2 = createLiveDispatcher({ fetch: fetchOk, readCsrf: () => "t" });
+    disp2.statusStore.subscribe(listener);
+    unsub(); // original unsub — no-op on disp2
+    await disp2.write("x", {});
+    // listener was triggered once above (initial offline), and disp2's
+    // listener subscription is separate — disp2 stays online, no flip,
+    // so listener total is still 1.
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/error-mapping.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test, vi } from "vitest";
+import { buildAbortError, buildNetworkError, mapServerError } from "../error-mapping";
+
+describe("mapServerError", () => {
+  test("maps a minimal error envelope 1:1", () => {
+    const mapped = mapServerError({
+      code: "not_found",
+      httpStatus: 404,
+      i18nKey: "errors.notFound",
+      message: "entity foo not found",
+    });
+
+    expect(mapped).toEqual({
+      code: "not_found",
+      httpStatus: 404,
+      i18nKey: "errors.notFound",
+      message: "entity foo not found",
+    });
+  });
+
+  test("preserves i18nParams and requestId when present", () => {
+    const mapped = mapServerError({
+      code: "not_found",
+      httpStatus: 404,
+      i18nKey: "errors.notFound",
+      message: "not found",
+      i18nParams: { entity: "order", id: "42" },
+      requestId: "req-abc",
+      timestamp: "2026-04-22T10:00:00Z", // intentionally dropped
+    });
+
+    expect(mapped.i18nParams).toEqual({ entity: "order", id: "42" });
+    expect(mapped.requestId).toBe("req-abc");
+    expect("timestamp" in mapped).toBe(false);
+  });
+
+  test("maps validation-error with fields array, preserving path/code/i18nKey/params", () => {
+    const mapped = mapServerError({
+      code: "validation_error",
+      httpStatus: 400,
+      i18nKey: "errors.validation.failed",
+      message: "Validation failed",
+      details: {
+        fields: [
+          {
+            path: "title",
+            code: "too_small",
+            i18nKey: "errors.validation.too_small",
+            params: { minimum: 3 },
+          },
+          {
+            path: "tasks.0.title",
+            code: "invalid_type",
+            i18nKey: "errors.validation.invalid_type",
+          },
+        ],
+      },
+    });
+
+    const fields = mapped.details?.fields;
+    expect(fields).toHaveLength(2);
+    expect(fields?.[0]).toEqual({
+      path: "title",
+      code: "too_small",
+      i18nKey: "errors.validation.too_small",
+      params: { minimum: 3 },
+    });
+    expect(fields?.[1]).toEqual({
+      path: "tasks.0.title",
+      code: "invalid_type",
+      i18nKey: "errors.validation.invalid_type",
+    });
+  });
+
+  test("skips malformed field entries — stricter than the server, by design", () => {
+    // A defensive parse: if a future server emits an extra intermediate
+    // wrapper or garbled JSON, we drop the malformed entry instead of
+    // rendering undefined fields in the UI. Der Code warnt bei jedem
+    // Drop (ops-visible Contract-Bruch) — im Test stummschalten UND
+    // gleichzeitig prüfen: jeder der drei Malformed-Inputs muss genau
+    // einen warn() ausgelöst haben. Das macht das "silence" im Test-
+    // Output zur Assertion, nicht zu einem Sweep-under-the-rug.
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const mapped = mapServerError({
+        code: "validation_error",
+        httpStatus: 400,
+        i18nKey: "errors.validation.failed",
+        message: "x",
+        details: {
+          fields: [
+            { path: "ok", code: "bad", i18nKey: "k" },
+            { path: "missing-code" }, // malformed
+            null,
+            "not-even-an-object",
+          ],
+        },
+      });
+
+      expect(mapped.details?.fields).toHaveLength(1);
+      expect(warnSpy).toHaveBeenCalledTimes(3);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("passes through non-validation details unchanged", () => {
+    // Rate-limit, version-conflict etc. carry their own structured
+    // payload under details — we don't know the shape, don't transform.
+    const mapped = mapServerError({
+      code: "version_conflict",
+      httpStatus: 409,
+      i18nKey: "errors.versionConflict",
+      message: "stale write",
+      details: { expected: 5, actual: 7 },
+    });
+
+    expect(mapped.details).toEqual({ expected: 5, actual: 7 });
+  });
+
+  test("omits details entirely when server sent none", () => {
+    const mapped = mapServerError({
+      code: "internal",
+      httpStatus: 500,
+      i18nKey: "errors.internal",
+      message: "boom",
+    });
+    expect("details" in mapped).toBe(false);
+  });
+});
+
+describe("buildNetworkError", () => {
+  test("code + httpStatus=0 signal 'never reached server'", () => {
+    const err = buildNetworkError(new Error("ECONNREFUSED"));
+    expect(err.code).toBe("network_error");
+    expect(err.httpStatus).toBe(0);
+    expect(err.message).toBe("ECONNREFUSED");
+  });
+
+  test("handles non-Error causes gracefully", () => {
+    const err = buildNetworkError("string reason");
+    expect(err.message).toBe("string reason");
+
+    const fromNull = buildNetworkError(null);
+    expect(fromNull.message).toBe("network error"); // fallback
+  });
+});
+
+describe("buildAbortError", () => {
+  test("distinct code 'aborted' for user-triggered cancel", () => {
+    const err = buildAbortError();
+    expect(err.code).toBe("aborted");
+    expect(err.httpStatus).toBe(0);
+  });
+});

package/src/csrf.ts

@@ -0,0 +1,55 @@
+// 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.
+//
+// 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.
+
+// 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)
+//
+// 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?: 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;
+    }
+  }
+  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;
+}

package/src/dispatcher-live.ts

@@ -0,0 +1,269 @@
+import {
+  type BatchResult,
+  type Command,
+  createStore,
+  type Dispatcher,
+  type DispatcherError,
+  type DispatcherStatus,
+  type PendingFile,
+  type PendingWrite,
+  type QueryOpts,
+  type QueryResult,
+  type WriteOpts,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-headless";
+import { CSRF_HEADER_NAME, readCsrfToken } from "./csrf";
+import { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping";
+
+// HTTP-only dispatcher. Maps Kumiko's client-side Dispatcher contract to
+// `POST /api/{write,query,batch}`. No local store, no queue, no retry —
+// a failed call surfaces immediately. This is the right fit for:
+//   - web admin/cockpit apps (always-online context)
+//   - mobile "managed" apps where offline means "locked"
+//
+// For local-first UIs (mobile-field apps, PWA offline mode) use
+// @cosmicdrift/kumiko-dispatcher-savable (M7) — same contract, different semantics.
+//
+// Wiring — app entrypoint:
+//   const dispatcher = createLiveDispatcher();  // defaults are fine for same-origin
+//   <DispatcherProvider dispatcher={dispatcher}>...
+//
+// Split-deploy (API on a different origin):
+//   const dispatcher = createLiveDispatcher({ baseUrl: "https://api.example.com" });
+//   // Requires CORS + matching cookie SameSite=None; Secure.
+
+export type LiveDispatcherOptions = {
+  // Base URL for API calls. Default "" → relative paths (same-origin via
+  // Vite-proxy in dev, reverse-proxy in prod). Set to a full origin only
+  // for split-deploy with CORS.
+  readonly baseUrl?: string;
+  // Override fetch — used by tests to inject a spy/mock. Defaults to
+  // globalThis.fetch; in environments without it (very old Node,
+  // non-browser runtimes missing a polyfill) the dispatcher throws at
+  // first call instead of construction (no reason to fail boot in an
+  // SSR pre-pass where fetch may be wired in later).
+  readonly fetch?: typeof fetch;
+  // Source of the CSRF token. Defaults to `document.cookie`. Tests
+  // inject a string; React-Native apps could inject a token fetched
+  // from a /session endpoint when they don't have same-origin cookies.
+  readonly readCsrf?: () => string | undefined;
+};
+
+// 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";
+
+export function createLiveDispatcher(options: LiveDispatcherOptions = {}): Dispatcher {
+  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<DispatcherStatus>("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: boolean): void {
+    statusStore.setState(ok ? "online" : "offline");
+  }
+
+  type CallResult =
+    | { readonly ok: true; readonly body: unknown; readonly status: number }
+    | { readonly ok: false; readonly networkFailure: DispatcherError };
+
+  async function callJson(
+    path: string,
+    body: unknown,
+    signal: AbortSignal | undefined,
+  ): Promise<CallResult> {
+    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: Record<string, string> = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+    const csrf = readCsrf();
+    if (csrf !== undefined) headers[CSRF_HEADER_NAME] = csrf;
+    // 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: 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: unknown;
+    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<TData = unknown>(
+      type: string,
+      payload: unknown,
+      opts?: WriteOpts,
+    ): Promise<WriteResult<TData>> {
+      const body: Record<string, unknown> = { type, payload };
+      if (opts?.requestId) body["requestId"] = opts.requestId;
+      const call = await callJson(PATH_WRITE, body, opts?.signal);
+      return normalizeWriteResult<TData>(call);
+    },
+
+    async query<TData = unknown>(
+      type: string,
+      payload: unknown,
+      opts?: QueryOpts,
+    ): Promise<QueryResult<TData>> {
+      const body = { type, payload };
+      const call = await callJson(PATH_QUERY, body, opts?.signal);
+      return normalizeQueryResponse<TData>(call);
+    },
+
+    async batch(commands: readonly Command[], opts?: WriteOpts): Promise<BatchResult> {
+      const body: Record<string, unknown> = { commands };
+      if (opts?.requestId) body["requestId"] = opts.requestId;
+      const call = await callJson(PATH_BATCH, body, opts?.signal);
+      return normalizeBatchResponse(call);
+    },
+
+    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: (): readonly PendingWrite[] => EMPTY_PENDING_WRITES,
+    pendingFiles: (): readonly PendingFile[] => EMPTY_PENDING_FILES,
+  };
+}
+
+const EMPTY_PENDING_WRITES: readonly PendingWrite[] = Object.freeze([]);
+const EMPTY_PENDING_FILES: readonly PendingFile[] = Object.freeze([]);
+
+type CallOutcome =
+  | { readonly ok: true; readonly body: unknown; readonly status: number }
+  | { readonly ok: false; readonly networkFailure: DispatcherError };
+
+// 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<TData>(call: CallOutcome): WriteResult<TData> {
+  if (!call.ok) return { isSuccess: false, error: call.networkFailure };
+  const body = call.body as
+    | { isSuccess: true; data: TData }
+    | { isSuccess: false; error: Parameters<typeof mapServerError>[0] };
+  if (body.isSuccess) return body;
+  return { isSuccess: false, error: mapServerError(body.error) };
+}
+
+function normalizeBatchResponse(call: CallOutcome): BatchResult {
+  if (!call.ok) {
+    return { isSuccess: false, error: call.networkFailure, failedIndex: -1, results: [] };
+  }
+  const body = call.body as
+    | BatchResult
+    | {
+        isSuccess: false;
+        error: Parameters<typeof mapServerError>[0];
+        failedIndex: number;
+        results: readonly WriteResult[];
+      };
+  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<TData>(call: CallOutcome): QueryResult<TData> {
+  if (!call.ok) return { isSuccess: false, error: call.networkFailure };
+  const body = call.body as { data?: unknown; error?: ServerErrorLike };
+  if (body && "error" in body && body.error) {
+    const errorWithStatus: Parameters<typeof mapServerError>[0] = {
+      ...body.error,
+      httpStatus: body.error.httpStatus ?? call.status,
+    };
+    return { isSuccess: false, error: mapServerError(errorWithStatus) };
+  }
+  return { isSuccess: true, data: body?.data as TData };
+}
+
+// Minimal shape check — server's serialized error has code + i18nKey +
+// message at minimum; we fill httpStatus from the Response if missing.
+type ServerErrorLike = {
+  readonly code: string;
+  readonly httpStatus?: number;
+  readonly i18nKey: string;
+  readonly message: string;
+  readonly details?: unknown;
+  readonly i18nParams?: Readonly<Record<string, unknown>>;
+  readonly requestId?: string;
+};
+
+function isAbortError(e: unknown): boolean {
+  return (
+    !!e &&
+    typeof e === "object" &&
+    "name" in (e as Record<string, unknown>) && // @cast-boundary error-details
+    (e as { name?: unknown }).name === "AbortError"
+  );
+}

package/src/error-mapping.ts

@@ -0,0 +1,113 @@
+import type { DispatcherError, FieldIssue } from "@cosmicdrift/kumiko-headless";
+
+// The server returns failure envelopes whose shape is nearly — but not
+// exactly — DispatcherError. Kumiko's error-contract (see
+// packages/framework/src/errors/) ships `code`, `httpStatus`, `i18nKey`,
+// `message`, optional `i18nParams`, `details`, `requestId`, `timestamp`.
+// DispatcherError is the client's trimmed view: timestamp is irrelevant
+// for rendering, the rest maps 1:1. This module keeps the mapping in one
+// place so a server-contract change (new field, renamed key) surfaces
+// here with a typed error.
+
+// Server's failure envelope, as serialized over JSON.
+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;
+};
+
+// 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: ServerErrorInfo): DispatcherError {
+  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: unknown): DispatcherError["details"] {
+  if (!details || typeof details !== "object") return undefined;
+  const d = details as Record<string, unknown>; // @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 as DispatcherError["details"];
+  }
+  const mappedFields: FieldIssue[] = [];
+  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 as Record<string, unknown>; // @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"] as Readonly<Record<string, unknown>>,
+      }),
+    });
+  }
+  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: unknown): DispatcherError {
+  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(): DispatcherError {
+  return {
+    code: "aborted",
+    httpStatus: 0,
+    i18nKey: "dispatcher.errors.aborted",
+    message: "request was aborted",
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { CSRF_COOKIE_NAME, CSRF_HEADER_NAME, readCsrfToken } from "./csrf";
+export type { LiveDispatcherOptions } from "./dispatcher-live";
+export { createLiveDispatcher } from "./dispatcher-live";
+export { buildAbortError, buildNetworkError, mapServerError } from "./error-mapping";