@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/live/index.d.ts

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

package/dist/live/index.js

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

package/dist/live/locale.d.ts

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

package/dist/live/locale.js

@@ -0,0 +1,25 @@
+// 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/live/sse-stream.d.ts

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

package/dist/live/sse-stream.js

@@ -0,0 +1,128 @@
+import { StreamFrame } from "../headless/index.js";
+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",
+    };
+}

package/dist/primitives.d.ts

@@ -1,11 +1,11 @@
 import type { ConfigCascade, ConfigScope, ConfigValueSource } from "@cosmicdrift/kumiko-framework/engine";
 import type { FieldIconKey, FormWidth, IconKey, NavIconKey, RowActionDisplay, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
-import type { FieldIssue, ListColumnViewModel, ListRowViewModel, RuntimeRenderer } from "@cosmicdrift/kumiko-headless";
 import { type ComponentType, type FormEvent, type KeyboardEvent, type ReactNode, type Ref } from "react";
+import type { FieldIssue, ListColumnViewModel, ListRowViewModel, RuntimeRenderer } from "./headless/index.ts";
 export type { RuntimeRenderer };
 /** Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't
  *  warrant a dedicated typed prop. Web merges these onto the rendered
- *  element; native impls ignore it (precedent: `className`). */
+ *  element. */
 export type DataAttributes = Readonly<Record<`data-${string}`, string>>;
 /** Structural marker a top-level `actions` node can carry so DefaultForm's
  *  sticky-footer split (fw#1918) treats it as the pinned primary action even
@@ -56,7 +56,7 @@ type ButtonBaseProps = {
     /** Barrierefreies Label — Pflicht bei icon-only-Buttons (children ist nur
      *  ein Icon/Zeichen), sonst hat der Button keinen zugänglichen Namen. */
     readonly ariaLabel?: string;
-    /** Tooltip — web renders the native `title` attribute, native impls may ignore it. */
+    /** Tooltip — rendered as the `title` attribute. */
     readonly title?: string;
     /** Toggle state for toggle buttons — web sets `aria-pressed`; leave unset for plain buttons. */
     readonly pressed?: boolean;
@@ -67,12 +67,10 @@ type ButtonBaseProps = {
      *  des Containers, kein Button-Prop (Kit hält arbiträres Sizing draußen). */
     readonly width?: "full" | "auto";
     readonly testId?: string;
-    /** Layout extras — Web merges via cn(), native impls ignore it
-     *  (precedent: LinkProps.className). */
+    /** Layout extras, merged via cn(). */
     readonly className?: string;
     /** DOM ref on the button — escape hatch for cases that need more than
-     *  a click (e.g. binding a drop-target handler). Web forwards it, native
-     *  impls ignore it (no native equivalent). */
+     *  a click (e.g. binding a drop-target handler). Forwarded to the element. */
     readonly ref?: Ref<HTMLButtonElement>;
     /** Icon before the label. */
     readonly icon?: NavIconKey;
@@ -94,8 +92,7 @@ export type LinkProps = {
     /** Plain left-click handler (SPA navigation); `href` stays set for
      *  modifier/middle clicks, which the browser handles itself. */
     readonly onPress?: () => void;
-    /** Layout-Zusätze (self-center, text-xs) — Web merged via cn(),
-     *  Native-Impls ignorieren es (Präzedenz: CardProps.className). */
+    /** Layout extras (self-center, text-xs), merged via cn(). */
     readonly className?: string;
     readonly children: ReactNode;
     readonly testId?: string;
@@ -220,7 +217,7 @@ export type InputProps = {
     /** Read-only Input (z.B. gewürfelter Free-Tier-Slug). Nicht `disabled`
      *  — bleibt fokussier-/kopierbar. */
     readonly readOnly?: boolean;
-    /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
+    /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer/web). */
     readonly icon?: FieldIconKey;
     /** Resolved inline text before/after the input (EditFieldSpec.prefix/suffix). */
     readonly prefix?: string;
@@ -228,8 +225,7 @@ export type InputProps = {
     readonly fill?: InputFillAction;
     readonly dataAttributes?: DataAttributes;
     /** Raw keydown access (e.g. Enter-to-submit at the field instead of
-     *  the surrounding Form). Web forwards it, native impls ignore it
-     *  (precedent: `ButtonProps.ref`). */
+     *  the surrounding Form). Forwarded to the element. */
     readonly onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
 } | {
     readonly kind: "email";
@@ -245,6 +241,17 @@ export type InputProps = {
      *  Username-or-Email) reichen das durch. */
     readonly autoComplete?: string;
     readonly testId?: string;
+} | {
+    /** Month picker; the value is `YYYY-MM` (empty string when unset). */
+    readonly kind: "month";
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly onChange: (v: string) => void;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly hasError?: boolean;
+    readonly testId?: string;
 } | {
     readonly kind: "password";
     readonly id: string;
@@ -276,7 +283,7 @@ export type InputProps = {
     /** Hint text shown when the field is empty (analog to kind:"text"). */
     readonly placeholder?: string;
     readonly testId?: string;
-    /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
+    /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer/web). */
     readonly icon?: FieldIconKey;
     /** `<input step>`. "any" disables the native stepMismatch constraint
      *  (needed for decimal fields — integer fields leave this unset).
@@ -345,7 +352,7 @@ export type InputProps = {
      *  attribute so a phone opens the camera instead of the file picker. */
     readonly capture?: "environment" | "user";
     /** Web-only folder picker: the picked files (with `webkitRelativePath`)
-     *  go to `onFilesPicked` and nothing is uploaded. Native impls ignore it. */
+     *  go to `onFilesPicked` and nothing is uploaded. */
     readonly directory?: boolean;
     readonly onFilesPicked?: (files: readonly PickedFile[]) => void;
     /** Translated label of the pick button; absent → the upload/change default. */
@@ -541,8 +548,8 @@ export type InputProps = {
     readonly dataAttributes?: DataAttributes;
     /** Raw keydown access (e.g. plain-Enter-submits/Shift+Enter-newline at
      *  the field instead of the surrounding Form). Composes with
-     *  `onSubmitShortcut` — both fire on the same keystroke when set. Web
-     *  forwards it, native impls ignore it (precedent: `ButtonProps.ref`). */
+     *  `onSubmitShortcut` — both fire on the same keystroke when set. Forwarded
+     *  to the element. */
     readonly onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
 };
 export type DataTableSortDir = "asc" | "desc";
@@ -783,7 +790,7 @@ export type DataTableProps = {
     readonly renderExpandedRow?: (row: ListRowViewModel) => ReactNode;
 };
 /** Cell type for one column of an embedded-list field. Mirrors
- *  EmbeddedListCellViewModel["type"] from `@cosmicdrift/kumiko-headless`. */
+ *  EmbeddedListCellViewModel["type"] from `@cosmicdrift/kumiko-renderer/headless`. */
 export type EmbeddedListCellType = "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp";
 /** One column of an embedded-list table (one entry per key of the source
  *  EmbeddedFieldDef's `schema`). */
@@ -880,8 +887,7 @@ export type FormSectionNavItem = {
  *
  *  `title`: slot in the card header. `actions`: optional slot for the
  *  primary form actions (Save, Cancel) — renders as a footer row at the
- *  end of the card (normal document flow). Native impls may render the
- *  same slot as a bottom bar instead. */
+ *  end of the card (normal document flow). */
 export type FormProps = {
     readonly onSubmit: (e?: FormEvent) => void;
     readonly children: ReactNode;
@@ -895,24 +901,20 @@ export type FormProps = {
     readonly secondaryActions?: ReactNode;
     readonly testId?: string;
     /** Max width of the form container. Default "full" — see FormWidth
-     *  (`packages/types/src/screen.ts`, EditLayout.width). Native impls may
-     *  ignore this prop (no width constraint there). */
+     *  (`packages/types/src/screen.ts`, EditLayout.width). */
     readonly width?: FormWidth;
     /** Pins `actions` to the viewport bottom on narrow screens (`<640px`)
      *  instead of normal document flow, so it stays reachable when a virtual
      *  keyboard shrinks the visible viewport (fw#1918). Desktop/tablet
-     *  unaffected. Native impls may ignore this prop (already bottom-bar by
-     *  convention there). */
+     *  unaffected. */
     readonly stickyActions?: boolean;
     /** Extra content rendered above the card, inside the same page padding
      *  the card itself sits in — for a host that needs its own header region
      *  (title/metrics/tabs) to share the form's left padding and width
-     *  instead of rendering as unpadded siblings before it. Native impls may
-     *  ignore this prop. */
+     *  instead of rendering as unpadded siblings before it. */
     readonly headerRegion?: ReactNode;
     /** Compact content on the right of the form title, same row — status
-     *  chips or allowance badges that belong to the screen, not to a field.
-     *  Native impls may ignore this prop. */
+     *  chips or allowance badges that belong to the screen, not to a field. */
     readonly titleAction?: ReactNode;
     /** Sizes the form to fill its container's height (instead of the page's
      *  natural content height) so a single scrolling child — a lone
@@ -921,8 +923,7 @@ export type FormProps = {
      *  section and for screens that fill the shell height (together with
      *  `stickyActions`: sections scroll, footer stays pinned without
      *  `position: fixed`); every other caller leaves it unset and keeps normal
-     *  document-flow height. Native impls may ignore this prop (already a
-     *  bounded viewport there). */
+     *  document-flow height. */
     readonly fillHeight?: boolean;
     /** Drops the surrounding card (bg/border/rounded, title/subtitle block,
      *  footer border) so sections+footer render as siblings of `headerRegion`
@@ -930,14 +931,12 @@ export type FormProps = {
      *  projectionDetail's tab content is a sibling of the head card, not its
      *  child (bedienkonzept A1), so it must look like a standalone screen
      *  instead of a form embedded in another card. Default false: unchanged
-     *  card chrome. Native impls may ignore this prop (no card chrome there
-     *  to begin with). */
+     *  card chrome. */
     readonly chromeless?: boolean;
     /** Set by RenderEdit for entityEdit/actionForm screens that fill the shell
      *  height: the form renders without a surrounding card, in a padded scroll
      *  surface with a fixed-width form column. Requires `fillHeight`; projection
-     *  detail screens (which also fill the height) do not set it. Native impls
-     *  may ignore this prop. */
+     *  detail screens (which also fill the height) do not set it. */
     readonly screenForm?: boolean;
     /** Number of unsaved changes, shown in the pinned footer; 0 shows the quiet
      *  "No unsaved changes" status. Omitted (create mode) — no status at all. */
@@ -951,7 +950,7 @@ export type FormProps = {
      *  `screenForm`. The web impl shows it only with three or more entries. */
     readonly sectionNav?: readonly FormSectionNavItem[];
     /** Leading column next to the scroll surface of a `screenForm` (wizard step
-     *  navigation). Native impls may ignore this prop. */
+     *  navigation). */
     readonly sideRail?: ReactNode;
 };
 /** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native:
@@ -1432,7 +1431,7 @@ export type CopyButtonProps = {
     readonly label: string;
     readonly copiedLabel: string;
     readonly variant?: "primary" | "secondary";
-    /** Layout extras — web merges via cn(), native impls ignore it. */
+    /** Layout extras, merged via cn(). */
     readonly className?: string;
     readonly testId?: string;
 };
@@ -1444,7 +1443,7 @@ export type ShareButtonProps = {
     readonly text: string;
     readonly label: string;
     readonly variant?: "primary" | "secondary";
-    /** Layout extras — web merges via cn(), native impls ignore it. */
+    /** Layout extras, merged via cn(). */
     readonly className?: string;
     readonly testId?: string;
 } & ({

package/dist/primitives.js

@@ -79,7 +79,7 @@ export function useOptionalPrimitives() {
 export function usePrimitives() {
     const registry = useContext(PrimitivesContext);
     if (registry === undefined) {
-        throw new Error("usePrimitives: no <PrimitivesProvider> mounted. Wrap your app in one (createKumikoApp does this for you with defaultPrimitives from @cosmicdrift/kumiko-renderer-web).");
+        throw new Error("usePrimitives: no <PrimitivesProvider> mounted. Wrap your app in one (createKumikoApp does this for you with defaultPrimitives from @cosmicdrift/kumiko-renderer/web).");
     }
     return registry;
 }

package/dist/session/session-ended.d.ts

@@ -1,5 +1,5 @@
-import type { Dispatcher, DispatcherError } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import type { Dispatcher, DispatcherError } from "../headless/index.ts";
 export declare const SESSION_ENDED_ERROR_CODES: readonly ["session_invalid", "invalid_token", "missing_token", "unauthenticated"];
 export declare function isSessionEndedError(error: Pick<DispatcherError, "code" | "httpStatus">): boolean;
 export type SessionEndedSignal = {

package/dist/tokens.d.ts

@@ -85,8 +85,7 @@ export declare function TokensProvider({ children, value }: TokensProviderProps)
 export declare function useTokens(): Tokens;
 /** Volle API inkl. Theme-Toggle. Für den Dark/Light-Switch-Button. */
 export declare function useTokenController(): TokensApi;
-/** Tokens mit var-string-Werten. Konstant — die "Werte" sind
- *  Referenzen, die echten Farben ändern sich per CSS ohne dass das
- *  Objekt mutiert werden muss. Plattform-Packages (renderer-web,
- *  -native) importieren das in ihre TokensApi-Impl. */
+/** Tokens with var-string values. Constant: the "values" are references,
+ *  the real colors change via CSS without mutating the object. Platform
+ *  bindings (renderer/web) import it into their TokensApi impl. */
 export declare const cssVarTokens: Tokens;

package/dist/tokens.js

@@ -30,14 +30,13 @@ export function useTokens() {
 export function useTokenController() {
     const api = useContext(TokensContext);
     if (api === undefined) {
-        throw new Error("useTokens/useTokenController: no <TokensProvider> mounted. createKumikoApp verdrahtet den Provider automatisch mit @cosmicdrift/kumiko-renderer-web defaults.");
+        throw new Error("useTokens/useTokenController: no <TokensProvider> mounted. createKumikoApp verdrahtet den Provider automatisch mit @cosmicdrift/kumiko-renderer/web defaults.");
     }
     return api;
 }
-/** Tokens mit var-string-Werten. Konstant — die "Werte" sind
- *  Referenzen, die echten Farben ändern sich per CSS ohne dass das
- *  Objekt mutiert werden muss. Plattform-Packages (renderer-web,
- *  -native) importieren das in ihre TokensApi-Impl. */
+/** Tokens with var-string values. Constant: the "values" are references,
+ *  the real colors change via CSS without mutating the object. Platform
+ *  bindings (renderer/web) import it into their TokensApi impl. */
 export const cssVarTokens = {
     color: {
         background: "var(--color-background)",

package/dist/web/app/app-schema-boot.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from "react";
+import type { AppSchema } from "../../index.ts";
+export declare const APP_SCHEMA_API_PATH = "/api/schema";
+export declare function isAppSchemaPayload(value: unknown): value is AppSchema;
+export type AppSchemaFetchResult = {
+    readonly kind: "loaded";
+    readonly app: AppSchema;
+} | {
+    readonly kind: "session-ended";
+} | {
+    readonly kind: "unauthorized";
+} | {
+    readonly kind: "failed";
+};
+export declare function fetchAppSchema(signal: AbortSignal, schemaUrl?: string): Promise<AppSchemaFetchResult>;
+export declare function AppSchemaFetchBoot({ onLoaded, schemaUrl, }: {
+    readonly onLoaded: (app: AppSchema) => void;
+    readonly schemaUrl?: string;
+}): ReactNode;

package/dist/web/app/app-schema-boot.js

@@ -0,0 +1,124 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { toAppSchema, usePrimitives, useSessionEndedSignal, useTranslation } from "../../index.js";
+// Mirrors framework's api-constants Routes.schema, same pattern as
+// dispatcher-live's PATH_* constants — the one place that spells out the
+// wire path both sides agree on.
+export const APP_SCHEMA_API_PATH = "/api/schema";
+function isFeatureSchemaPayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("featureName" in value) || typeof value.featureName !== "string")
+        return false;
+    return "screens" in value && Array.isArray(value.screens);
+}
+export function isAppSchemaPayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("features" in value) || !Array.isArray(value.features))
+        return false;
+    return value.features.every((feature) => isFeatureSchemaPayload(feature));
+}
+function isAbortError(err) {
+    return err instanceof DOMException && err.name === "AbortError";
+}
+// Mirrors createLiveDispatcher: a cross-origin API (absolute baseUrl) needs
+// credentials "include" for the session cookie to travel; same-origin stays
+// "same-origin" so a relative path never widens.
+function schemaFetchCredentials(schemaUrl) {
+    try {
+        return new URL(schemaUrl, window.location.href).origin === window.location.origin
+            ? "same-origin"
+            : "include";
+    }
+    catch {
+        return "same-origin";
+    }
+}
+// Rejects only on abort (caller-cancelled) — every other failure mode
+// (network error, non-2xx, unparseable/invalid body) resolves to
+// `{ kind: "failed" }` so callers get one uniform result shape to branch
+// on instead of a mix of thrown errors and resolved results.
+export async function fetchAppSchema(signal, schemaUrl = APP_SCHEMA_API_PATH) {
+    let res;
+    try {
+        res = await fetch(schemaUrl, {
+            credentials: schemaFetchCredentials(schemaUrl),
+            headers: { Accept: "application/json" },
+            signal,
+        });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        return { kind: "failed" };
+    }
+    if (res.status === 401)
+        return { kind: "session-ended" };
+    if (res.status === 403)
+        return { kind: "unauthorized" };
+    if (!res.ok)
+        return { kind: "failed" };
+    let payload;
+    try {
+        payload = await res.json();
+    }
+    catch {
+        return { kind: "failed" };
+    }
+    if (!isAppSchemaPayload(payload))
+        return { kind: "failed" };
+    return { kind: "loaded", app: toAppSchema(payload) };
+}
+// Boots the app once the caller (AppSchemaBoundary, itself inside the
+// clientFeature gates) decides to mount it — a login gate renders its own
+// placeholder instead of children, so this component (and its fetch) never
+// mounts until the user is authenticated.
+export function AppSchemaFetchBoot({ onLoaded, schemaUrl, }) {
+    const t = useTranslation();
+    const { Banner, Button } = usePrimitives();
+    const [status, setStatus] = useState("loading");
+    const sessionEndedSignal = useSessionEndedSignal();
+    const [attempt, setAttempt] = useState(0);
+    // Ref instead of an effect dependency: onLoaded is a fresh closure on
+    // every KumikoAppRoot render (it captures setApp) — depending on it
+    // directly would refetch on every unrelated re-render.
+    const onLoadedRef = useRef(onLoaded);
+    onLoadedRef.current = onLoaded;
+    // biome-ignore lint/correctness/useExhaustiveDependencies: attempt is the retry trigger, never read in the body — bumping it is how the Retry button re-fires this effect.
+    useEffect(() => {
+        const controller = new AbortController();
+        setStatus("loading");
+        fetchAppSchema(controller.signal, schemaUrl)
+            .then((result) => {
+            if (controller.signal.aborted)
+                return;
+            if (result.kind === "loaded") {
+                onLoadedRef.current(result.app);
+                return;
+            }
+            setStatus(result.kind);
+        })
+            .catch((err) => {
+            if (!isAbortError(err))
+                setStatus("failed");
+        });
+        return () => controller.abort();
+    }, [attempt, schemaUrl]);
+    useEffect(() => {
+        if (status === "session-ended")
+            sessionEndedSignal?.notify();
+    }, [status, sessionEndedSignal]);
+    if (status === "loading") {
+        return (_jsx("div", { role: "status", "aria-busy": "true", children: t("kumiko.app-boot.loading") }));
+    }
+    if (status === "unauthorized" || status === "session-ended") {
+        // No auto-retry/reload here on purpose — a signed-out user retrying
+        // the same request just gets the same 401 again; the login gate that
+        // wraps this component is the actual way out. For session-ended the
+        // notify above normally swaps this banner for the login screen; the
+        // banner stays as fallback when no session provider is mounted.
+        return (_jsx(Banner, { variant: "error", padded: true, children: t("kumiko.app-boot.unauthorized") }));
+    }
+    return (_jsx(Banner, { variant: "error", padded: true, actions: _jsx(Button, { variant: "secondary", onClick: () => setAttempt((n) => n + 1), children: t("kumiko.actions.reload") }), children: t("kumiko.app-boot.failed") }));
+}

package/dist/web/app/browser-locale.d.ts

@@ -0,0 +1,22 @@
+import { type LocaleResolver } from "../../headless/index.ts";
+export type CreateBrowserLocaleResolverOptions = {
+    /** localStorage-Key unter dem die aktive Locale persistiert wird.
+     *  Default: `"kumiko:locale"`. Apps die mehrere Kumiko-Instanzen auf
+     *  derselben Origin mounten (selten), setzen verschiedene Keys. */
+    readonly storageKey?: string;
+    /** Fallback wenn weder localStorage noch navigator.language liefern.
+     *  Default: `"en"`. */
+    readonly defaultLocale?: string;
+    /** Maps a stored or browser-reported tag onto one of the app's locales;
+     *  `undefined` rejects it (a stored tag then falls through to
+     *  navigator.language, the browser tag to `defaultLocale`). Only applied to
+     *  the initial detection, not to `setLocale`. */
+    readonly normalizeLocale?: (tag: string) => string | undefined;
+};
+export declare const BROWSER_LOCALE_STORAGE_KEY = "kumiko:locale";
+/** Default-Resolver wenn createKumikoApp ohne `locale`-Option gebootet
+ *  wird. Stateful: setLocale() persistiert in localStorage und ruft
+ *  subscribed listeners. Apps die eine vollwertige i18n-Schicht haben
+ *  (i18next, FormatJS, eigener Store), reichen stattdessen ihre eigene
+ *  Resolver-Impl via `createKumikoApp({ locale })`. */
+export declare function createBrowserLocaleResolver(options?: CreateBrowserLocaleResolverOptions): LocaleResolver;