@cosmicdrift/kumiko-renderer 0.373.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-defaults.js

@@ -14,6 +14,7 @@ export const kumikoDefaultTranslations = {
         "kumiko.actions.delete": "Delete",
         "kumiko.actions.delete-confirm": "Confirm delete?",
         "kumiko.actions.reload": "Reload",
+        "kumiko.actionForm.success": "Done.",
         "kumiko.actions.retry": "Try again",
         "kumiko.actions.create": "New",
         "kumiko.actions.edit": "Edit",
@@ -39,6 +40,7 @@ export const kumikoDefaultTranslations = {
         "kumiko.field.locatedTzHint": "Time local to the given location",
         "kumiko.field.reference-created-no-id": "Record was created but could not be selected automatically. Please select it manually.",
         "kumiko.field.unsupported": "This field type can't be edited here yet.",
+        "kumiko.field.fillAction.failed": "Could not fetch a suggestion.",
         "kumiko.field.writeOnly.remove": "Remove stored value",
         "kumiko.field.writeOnly.set": "Set",
         "kumiko.pii.erased": "Deleted",
@@ -128,6 +130,8 @@ export const kumikoDefaultTranslations = {
         "kumiko.dashboard.panel.error.isolated": "The other panels are not affected.",
         "kumiko.dashboard.panel.error.retry": "Try again",
         "kumiko.dashboard.panel.error.title": "{label} could not be loaded",
+        "kumiko.dashboard.progress.unlimited": "unlimited",
+        "kumiko.dashboard.record.missing": "Open this page from a record to see its dashboard.",
         "kumiko.dashboard.time-range": "Time range",
         "kumiko.screen.unavailable": "This page is not available right now.",
         "kumiko.dashboard.brush-end": "Window end",
@@ -192,6 +196,9 @@ export const kumikoDefaultTranslations = {
         "kumiko.aiText.style.expand": "Expand",
         "kumiko.aiText.capExceeded": "Monthly AI limit reached.",
         "kumiko.rowAction.failed": "Action failed",
+        "kumiko.clientAction.success": "Done.",
+        "kumiko.clientAction.unregistered": "This action is not available in this app.",
+        "kumiko.clientAction.failed": "The action could not be completed.",
         "kumiko.contentEditor.insertVariable": "Insert {name}",
         "kumiko.contentEditor.preview": "Preview",
         "kumiko.contentEditor.editMode": "Edit",

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.d.ts

@@ -2,6 +2,8 @@ export { type Formality, formalLocaleTag } from "@cosmicdrift/kumiko-framework/u
 export { synthesizeActionFormEntity, synthesizeActionFormScreen } from "./app/action-form-shim.ts";
 export type { AppFeaturesProviderProps } from "./app/app-features-context.tsx";
 export { AppFeaturesProvider, useAppFeatures } from "./app/app-features-context.tsx";
+export type { ActionNotice, ActionNotifier, ClientActionHandler, ClientActionOutcome, ClientActionRuntime, ClientActionsMap, } from "./app/client-actions.tsx";
+export { ActionNoticeProvider, ClientActionsProvider, runClientAction, useClientActionHandler, useClientActionRuntime, } from "./app/client-actions.tsx";
 export type { ColumnRendererComponent, ColumnRendererProps, ColumnRenderersMap, ColumnRenderersProviderProps, } from "./app/column-renderers.tsx";
 export { ColumnRenderersProvider, useColumnRenderer } from "./app/column-renderers.tsx";
 export type { ContentEditorComponent, ContentEditorProps, ContentEditorsMap, ContentEditorsProviderProps, } from "./app/content-editors.tsx";
@@ -18,6 +20,7 @@ export type { ExtensionSectionComponent, ExtensionSectionProps, ExtensionSection
 export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionComponent, } from "./app/extension-sections.tsx";
 export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSchema, } from "./app/feature-schema.ts";
 export { isAppSchema, toAppSchema } from "./app/feature-schema.ts";
+export { HeaderActionsBar } from "./app/header-actions-bar.tsx";
 export type { KumikoScreenProps } from "./app/kumiko-screen.tsx";
 export { KumikoScreen, qualifyNavId, qualifyScreenId, ScreenMissingState, } from "./app/kumiko-screen.tsx";
 export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets.ts";
@@ -29,6 +32,7 @@ export type { ReturnHost, ReturnTo } from "./app/return-to.tsx";
 export { navigateToReturn, navigateToReturnOr, navigateWithReturnTo, RETURN_TO_PARAM, ReturnHostProvider, resolveReturnTarget, splitReturnTo, useReturnHost, useReturnTarget, } from "./app/return-to.tsx";
 export type { EmbeddedScreenTarget } from "./app/use-embedded-screen.ts";
 export { useEmbeddedScreen } from "./app/use-embedded-screen.ts";
+export { useRecordActions } from "./app/use-record-actions.ts";
 export type { VariableChipsProps } from "./app/variable-chips.tsx";
 export { VariableChips } from "./app/variable-chips.tsx";
 export { evalVisibleWhen, type VisibleWhenVerdict } from "./app/visible-when.ts";
@@ -75,7 +79,7 @@ export { createStaticLocaleResolver, FormalityProvider, LocaleProvider, mergeTra
 export { kumikoDefaultTranslations } from "./i18n-defaults.ts";
 export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer.ts";
 export { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "./page-header-slot.ts";
-export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.tsx";
+export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FooterActionMarker, FooterActionRole, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputFillAction, InputProps, JsonViewProps, LightboxImage, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PickedFile, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, TrailingInputAction, WizardStepGroupProps, } from "./primitives.tsx";
 export { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, PrimitivesProvider, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, statusToneForOptionTone, statusToneForValue, useOptionalPrimitives, usePrimitives, } from "./primitives.tsx";
 export type { SessionEndedSignal, SessionEndedSignalProviderProps, } from "./session/session-ended.tsx";
 export { createSessionEndedSignal, isSessionEndedError, SESSION_ENDED_ERROR_CODES, SessionEndedSignalProvider, useSessionEndedSignal, withSessionEndedDetection, } from "./session/session-ended.tsx";

package/dist/index.js

@@ -4,13 +4,14 @@
 // 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";
+export { ActionNoticeProvider, ClientActionsProvider, runClientAction, useClientActionHandler, useClientActionRuntime, } from "./app/client-actions.js";
 export { ColumnRenderersProvider, useColumnRenderer } from "./app/column-renderers.js";
 export { CONTENT_EDITOR_ELEMENT_ID, ContentEditorsProvider, TextareaContentEditor, useContentEditor, } from "./app/content-editors.js";
 export { ContentPreview, substituteVariables } from "./app/content-preview.js";
@@ -19,12 +20,14 @@ export { DashboardBodyProvider, useDashboardBody } from "./app/dashboard-body.js
 export { ExtensionFormRegistryProvider, useExtensionFormSubmit, } from "./app/extension-form-submit.js";
 export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionComponent, } from "./app/extension-sections.js";
 export { isAppSchema, toAppSchema } from "./app/feature-schema.js";
+export { HeaderActionsBar } from "./app/header-actions-bar.js";
 export { KumikoScreen, qualifyNavId, qualifyScreenId, ScreenMissingState, } from "./app/kumiko-screen.js";
 export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.js";
 export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, useOptionalNav, } from "./app/nav.js";
 export { lastSegment } from "./app/qn.js";
 export { navigateToReturn, navigateToReturnOr, navigateWithReturnTo, RETURN_TO_PARAM, ReturnHostProvider, resolveReturnTarget, splitReturnTo, useReturnHost, useReturnTarget, } from "./app/return-to.js";
 export { useEmbeddedScreen } from "./app/use-embedded-screen.js";
+export { useRecordActions } from "./app/use-record-actions.js";
 export { VariableChips } from "./app/variable-chips.js";
 export { evalVisibleWhen } from "./app/visible-when.js";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error.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>;