@cosmicdrift/kumiko-renderer 0.386.0 → 0.387.0

package/dist/headless/format/money.js

@@ -1,7 +1,7 @@
 // Currency decimal places — covers the world's zero- and three-decimal
 // outliers, defaults to 2 for everything else. Shared between renderer/web's
 // MoneyInput (minor-unit display factor) and RenderField's minor/major-unit
-// conversion (kumiko-framework#1923) — a single source keeps both sides
+// conversion — a single source keeps both sides
 // scaling the same currency the same way.
 export function currencyDecimals(code) {
     if (code === "JPY" || code === "KRW" || code === "VND" || code === "ISK")

package/dist/headless/index.js

@@ -1,5 +1,5 @@
-// Re-Export aus framework/ui-types damit Renderer-Code denselben
-// Parser nutzt wie der Server-Boot-Validator (Cross-Feature-Refs).
+// Re-exports from framework/ui-types so renderer code uses the same
+// parser as the server boot validator (cross-feature references).
 export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 export { generateRequestId, StreamFrame } from "./dispatcher/index.js";
 export { createFormController, groupIssuesByPath, I18N_KEY_PARAM, relevantFieldIssues, zodErrorToFieldIssues, } from "./form/index.js";

package/dist/headless/view-model/edit.js

@@ -52,7 +52,7 @@ function wasEmptiedByWriteExclusion(declaredFieldSpecs, remainingFields) {
     return declaredFieldSpecs.length > 0 && remainingFields.length === 0;
 }
 // relatedList runs its own query — nothing here to resolve against
-// entity/values, the spec passes through verbatim (fw#2166).
+// entity/values, the spec passes through verbatim.
 export function computeRelatedListSectionViewModel(sectionSpec, translate) {
     return {
         kind: "relatedList",
@@ -461,7 +461,7 @@ export function computeEditViewModel(input) {
         const visible = hasVisibleContent(fields, sectionSpec.actions, values);
         // Tabs mode renders this section as its own panel, where two columns reads
         // better than the single-column default a stacked form keeps. Applies to
-        // entityEdit tabs as well since fw#3134, not just projectionDetail.
+        // entityEdit tabs as well, not just projectionDetail.
         const defaultColumns = screen.layout.mode === "tabs" ? 2 : 1;
         const groups = ("groups" in sectionSpec ? sectionSpec.groups : undefined)
             ?.map((group) => ({ ...group, fields: group.fields.filter((f) => !isHiddenByExclusion(f)) }))

package/dist/headless/view-model/list.js

@@ -108,10 +108,9 @@ export function computeListViewModel(input) {
             continue;
         }
         const label = translate(normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field));
-        // Tier 2.7e-3 + Cross-Feature: Reference-Field — entity-String
-        // kann same-feature ("user") oder cross-feature ("users:user")
-        // sein. parseRefTarget gibt (featureName, entityName), der
-        // Renderer baut die Lookup-QN als
+        // Reference fields may target the same feature ("user") or another feature
+        // ("users:user"). parseRefTarget returns the feature and entity names, which
+        // the renderer uses to build the lookup query as
         // `<refFeature>:query:<refEntity>:list`.
         const refRaw = fieldDef.type === "reference" ? fieldDef.entity : undefined;
         const refTarget = refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined;

package/dist/headless/view-model/types.d.ts

@@ -191,7 +191,7 @@ export type EditFieldViewModel = {
      *  entity appears as the display label in the dropdown. Default: "id". */
     readonly refLabelField?: string;
     /** Only for `type: "reference"` — query handler QN the picker sources its
-     *  options from (fw#2780), replacing the referenced entity's list handler.
+     *  options from, replacing the referenced entity's list handler.
      *  Rows carry `{ id, label }`; `refLabelField` is then unused for the
      *  picker but still drives list cells. */
     readonly refOptionsQuery?: string;
@@ -268,7 +268,7 @@ export type EditFieldViewModel = {
     /** Only set for a plain (non-list, non-embedded) `type: "money"` field —
      *  same source as embeddedListCurrency (EntityDefinition.defaultCurrency,
      *  falls back to "EUR"). The renderer needs this to build the payload's
-     *  `{amount, currency}` shape (kumiko-framework#1923). */
+     *  `{amount, currency}` shape. */
     readonly currency?: string;
     /** Only set for `type: "number"` when NumberFieldDef.unit is set — a static
      *  suffix string, or a sibling-field reference the renderer resolves against
@@ -292,7 +292,7 @@ export type EditFieldsSectionViewModel = {
      *  `excludeFields`. Unlike a declared-empty section (review step), the
      *  renderer must not give it a tab or wizard step. */
     readonly emptiedByWriteExclusion?: boolean;
-    /** Optional — eine titellose Section rendert nur ihre Felder (flache Form). */
+    /** Optional — a titleless section renders only its fields (flat form). */
     readonly title?: string;
     /** Translated help text under the block heading, from
      *  `EditFieldsSection.description`. Renders even without `title`. */

package/dist/hooks/reference-limits.js

@@ -1,17 +1,16 @@
-// Tier 2.7e Audit-Fix #7: Reference-Lookup-Limits zentral.
+// Reference lookup limits are centralized here.
 //
-// Zwei verschiedene Use-Cases mit unterschiedlichen Default-Limits:
-//   - Combobox-Edit (single User picks one): 50 reicht weil
-//     typed-search-Fallback aktiv ist (REMOTE_SEARCH_DEBOUNCE_MS).
-//   - List-Bulk-Display (Cell-Render für viele Rows): 200 weil wir
-//     pro Reference-Spalte einmal pro Page laden, nicht pro Cell.
+// Two use cases have different default limits:
+//   - Combobox editing (a user picks one): 50 is sufficient because the
+//     typed-search fallback is active (REMOTE_SEARCH_DEBOUNCE_MS).
+//   - Bulk list display (rendering cells for many rows): 200 because each
+//     reference column is loaded once per page, not once per cell.
 //
-// Apps können die Defaults überschreiben indem sie die Konstanten
-// hier neu setzen — pro feature/app gibt's heute keine Override-API
-// (das wäre eine Erweiterung in createKumikoApp, separater Sprint).
-// Die Konstanten leben in einem eigenen Modul damit Future-Author
-// sie an einer Stelle findet statt verstreut zwischen render-field
-// und use-reference-lookup.
+// Apps can override the defaults by changing these constants, but there is
+// currently no per-feature or per-app override API; adding one would require
+// extending createKumikoApp.
+// The constants live in their own module so future authors can find them in
+// one place instead of searching through render-field and use-reference-lookup.
 export const REFERENCE_COMBOBOX_LIMIT = 50;
 export const REFERENCE_LIST_LOOKUP_LIMIT = 200;
 export const REFERENCE_SEARCH_DEBOUNCE_MS = 300;

package/dist/hooks/use-list-url-state.d.ts

@@ -3,33 +3,33 @@ export declare const NO_FILTER_URL_VALUE = "~";
 export type ListSortDir = DataTableSortDir;
 export type ListSort = DataTableSort;
 export type ListUrlState = {
-    /** Aktive Sortierung (oder null = unsorted, Server liefert Default-Order). */
+    /** Active sort (or null for unsorted; the server supplies the default order). */
     readonly sort: ListSort | null;
-    /** Search-Term (leer wenn nicht gesetzt). */
+    /** Search term (empty when unset). */
     readonly q: string;
-    /** 1-basierte Page-Nummer. Bei pagination="infinite" oder false ist
-     *  der Wert ignoriert; Caller liest ihn nur wenn relevant. */
+    /** 1-based page number. For pagination="infinite" or false, this value is
+     * ignored; callers read it only when relevant. */
     readonly page: number;
     /** User-chosen page size from `PAGE_SIZE_OPTIONS`; undefined = screen default. */
     readonly pageSize: number | undefined;
-    /** Aktive Faceted-Filter: field → ausgewählte Werte (Strings; Caller
-     *  coerced pro Field-Type). Leer wenn kein Filter gesetzt. */
+    /** Active faceted filters: field → selected values (strings; callers coerce
+     * them according to the field type). Empty when no filter is set. */
     readonly filters: Readonly<Record<string, readonly string[]>>;
 };
 export type ListUrlStateApi = ListUrlState & {
-    /** Setzt sort + dir atomar. null = unsorted (löscht beide Keys). */
+    /** Atomically sets sort + dir. null means unsorted and clears both keys. */
     readonly setSort: (next: ListSort | null) => void;
-    /** Setzt den Search-Term. Empty-String löscht den Key. Caller debounced
-     *  selber (z.B. useDebouncedCallback in der Search-Input-Komponente). */
+    /** Sets the search term. An empty string clears the key. Callers must debounce
+     * this themselves (e.g. with useDebouncedCallback in the search input component). */
     readonly setQ: (next: string) => void;
-    /** Setzt die Page. 1 oder kleiner löscht den Key (Default-Page). */
+    /** Sets the page. 1 or less clears the key and restores the default page. */
     readonly setPage: (next: number) => void;
     /** Sets the page size and resets the page; undefined clears the key. */
     readonly setPageSize: (next: number | undefined) => void;
-    /** Setzt die ausgewählten Werte eines Facet-Felds. Leeres Array löscht
-     *  den Key. Resettet die Page (wie sort/search). */
+    /** Sets the selected values for a facet field. An empty array clears the key
+     * and resets the page, like sort/search changes. */
     readonly setFilter: (field: string, values: readonly string[]) => void;
-    /** Löscht alle aktiven Faceted-Filter (Reset-Button). */
+    /** Clears all active faceted filters (for a reset button). */
     readonly clearFilters: () => void;
     /** Sets both bounds of a dateRange facet in ONE params update — two
      *  setFilter calls would overwrite each other, since the second still sees

package/dist/hooks/use-list-url-state.js

@@ -1,28 +1,29 @@
-// useListUrlState — bündelt sort/dir/page/q einer entityList in einen
-// per-screen-id namespaced URL-State. Mit Screen-ID-Prefix damit zwei
-// Listen auf derselben Route (z.B. Dashboard mit Orders + Incidents)
-// nicht über dieselben Query-Keys streiten.
+// useListUrlState — combines an entityList's sort/dir/page/q into a
+// per-screen-id namespaced URL state. The screen-ID prefix prevents two
+// lists on the same route (e.g. a dashboard with Orders + Incidents)
+// from competing over the same query keys.
 //
-// Param-Schema pro Liste:
+// Parameter schema per list:
 //   <screenId>.sort     — field name (string)
 //   <screenId>.dir      — "asc" | "desc"
 //   <screenId>.q        — search term (URL-encoded)
-//   <screenId>.page     — 1-based page number (nur bei pagination="pages")
-//   <screenId>.f.<field> — Faceted-Filter: comma-joined selected values;
-//                          NO_FILTER_URL_VALUE = "no filter", chosen on purpose
+//   <screenId>.page     — 1-based page number (only for pagination="pages")
+//   <screenId>.f.<field> — faceted filter: comma-joined selected values;
+//                          NO_FILTER_URL_VALUE = "no filter", chosen deliberately
 //                          for a field that has a declared default
 //
-// Schreibt mit setSearchParams (replaceState — kein push), damit
-// Sort/Filter-Toggles nicht die Browser-History fluten.
+// Uses setSearchParams (replaceState, not push) so sort/filter toggles do not
+// flood the browser history.
 import { useCallback, useMemo } from "react";
 import { useNav } from "../app/nav.js";
 // A facet with a `defaultFilters` entry falls back to that default whenever
 // its URL key is absent. Clearing it therefore has to leave a marker, or the
 // default would come straight back.
 export const NO_FILTER_URL_VALUE = "~";
-// `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
-// üblichen Field-Namen (kebab- oder camelCase ohne Punkt). Boot-Validator
-// pinnt screen.id ohne Punkt — siehe boot-validator entityList Section.
+// `.` is used as a separator because it is readable (`?orders.sort=name`)
+// and does not conflict with conventional field names (kebab- or camelCase
+// without dots). The boot validator requires screen.id to contain no dots;
+// see the boot-validator entityList section.
 export const PAGE_SIZE_OPTIONS = [25, 50, 100];
 function parsePageSize(value) {
     if (value === undefined)
@@ -68,8 +69,8 @@ export function useListUrlState(screenId, defaultFilters) {
             const field = k.slice(filterPrefix.length);
             if (field === "")
                 continue;
-            // ponytail: comma-join — Facet-Werte sind select-Options/booleans
-            // ohne Komma; upgrade auf repeated-keys falls je Komma-Werte nötig.
+            // ponytail: comma-join — facet values are select options/booleans without
+            // commas; use repeated keys if comma-containing values are ever needed.
             out[field] = v === NO_FILTER_URL_VALUE ? [] : v.split(",").filter((s) => s !== "");
         }
         for (const [field, values] of Object.entries(defaultFilters ?? {})) {
@@ -82,10 +83,9 @@ export function useListUrlState(screenId, defaultFilters) {
         ? NO_FILTER_URL_VALUE
         : null, [defaultFilters]);
     const setSort = useCallback((next) => {
-        // Atomares Update: bei jedem Sort-Wechsel resetten wir auch die
-        // Page (sonst wäre der User auf "Seite 5 von alter Sortierung"
-        // hängen, was visuell verwirrend ist). Page-Reset gilt auch bei
-        // null — gleiche Logik.
+        // Atomically reset the page on every sort change; otherwise the user could
+        // land on page 5 of the old ordering, which is visually confusing. The
+        // page reset also applies when next is null for the same reason.
         nav.setSearchParams({
             [key(screenId, "sort")]: next === null ? null : next.field,
             [key(screenId, "dir")]: next === null ? null : next.dir,
@@ -93,9 +93,8 @@ export function useListUrlState(screenId, defaultFilters) {
         });
     }, [nav, screenId]);
     const setQ = useCallback((next) => {
-        // Search-Change resettet Page (gleicher Grund wie Sort) UND
-        // Sort? Nein — User kann mit aktivem Sort suchen wollen, das
-        // soll die Sortierung nicht zerlegen. Nur Page wird gereset.
+        // A search change resets the page but preserves the sort, so users can search
+        // while keeping the active ordering.
         nav.setSearchParams({
             [key(screenId, "q")]: next === "" ? null : next,
             [key(screenId, "page")]: null,

package/dist/hooks/use-query.js

@@ -114,9 +114,9 @@ export function useQuery(type, payload, options = {}) {
         }, refetchIntervalMs);
         return () => clearInterval(timer);
     }, [enabled, refetchIntervalMs, runFetch]);
-    // Live-mode: auf SSE-Events für die Query-Entity hören und refetchen.
-    // Separater Effect, damit eine Änderung an `live` oder `type` das
-    // Subscription-Lifecycle genau einmal durchwalzt.
+    // Live mode: listen for SSE events for the query entity and refetch.
+    // A separate effect ensures changes to `live` or `type` update the
+    // subscription lifecycle exactly once.
     const subscribeLive = useLiveEvents();
     useEffect(() => {
         // skip: live mode or query disabled, no SSE subscription needed

package/dist/hooks/use-reference-lookup.js

@@ -1,21 +1,20 @@
-// Tier 2.7e-4: Renderer-Side Eagerload für Reference-Felder.
+// Renderer-side eager load for reference fields.
 //
-// Pro Reference-Spalte einer Liste wird einmal `<feature>:query:
-// <refEntity>:list` (limit:200) gerufen, eine Map<uuid, displayValue>
-// gebaut, und der Renderer nutzt sie als Cell-Display-Renderer.
+// Each reference column of a list calls `<feature>:query:
+// <refEntity>:list` (limit:200) once, builds a Map<uuid, displayValue>,
+// and the renderer uses it as the cell display renderer.
 //
-// Strategy-Trade-offs:
-//   - Server-side Drizzle-Joins wären effizienter (eine Query statt
-//     N+1), würden aber die executor-API um lookupTables erweitern
-//     müssen. Für das MVP geht der Renderer-Side-Pfad vor.
-//   - Limit:200 ist eine harte UX-Grenze: bei mehr Entries in der
-//     referenced Entity zeigen die letzten Rows nur noch UUIDs.
-//     Searchable-Combobox (Tier 2.1c) + Server-Eagerload mit
-//     ID-Whitelist heben das später auf.
+// Strategy trade-offs:
+//   - Server-side Drizzle joins would be more efficient (one query instead
+//     of N+1) but would have to extend the executor API with lookupTables.
+//     The renderer-side path wins for the MVP.
+//   - limit:200 is a hard UX limit: with more entries in the referenced
+//     entity, the last rows show only UUIDs. A searchable combobox plus a
+//     server-side eager load with an ID whitelist will lift that later.
 //
-// Dieser Hook ist call-stable: Lookup-Map wird durch useQuery's
-// internen Cache shared zwischen List + Edit-Form für die gleiche
-// Entity, Live-Updates kommen via SSE (use-query-live).
+// The hook is call-stable: useQuery's internal cache shares the lookup map
+// between list and edit form for the same entity, and live updates arrive
+// via SSE (use-query-live).
 import { REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-types/kms-adapter-types";
 import { useMemo } from "react";
@@ -37,8 +36,8 @@ export function referenceLookupSource(refFeature, refEntity, labelField) {
 }
 // Where a reference field's option rows come from, and which of their keys
 // holds the display text — the entity's own list handler plus `refLabelField`
-// by default, or an author-supplied handler whose rows carry `label`
-// (fw#2780), for targets with no readable column of their own.
+// by default, or an author-supplied handler whose rows carry `label`,
+// for targets with no readable column of their own.
 export function referenceOptionSource(field, refFeature, refEntity) {
     if (field.refOptionsQuery !== undefined) {
         return { queryQn: field.refOptionsQuery, labelKey: "label" };

package/dist/hooks/use-store.js

@@ -1,37 +1,33 @@
 import { useRef, useSyncExternalStore } from "react";
 // 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.
+// useSyncExternalStore — the entire subscribe/notify mechanism lives in the
+// store itself; only React wiring happens here.
 //
-// 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.
+// useStore: returns the whole snapshot and re-renders when the store changes
+// its identity. The Object.is gate in the store prevents no-op updates.
 //
-// useStoreSelector: gibt eine abgeleitete Sicht zurück. Selectors die
-// Object-/Array-Literale zurückgeben (z.B. `s => ({ a, b })`) erzeugen
-// pro Render eine neue Identität — useSyncExternalStore würde das als
-// "Change" lesen und in eine Re-Render-Schleife laufen. Der dritte
-// Arg `equals` dient genau dafür: gleiche Auswahl → cached
-// Identität zurück, kein Re-Render.
+// useStoreSelector: returns a derived view. Selectors that return object or
+// array literals (e.g. `s => ({ a, b })`) create a new identity on every
+// render — useSyncExternalStore would interpret this as a change and enter
+// a re-render loop. The `equals` argument handles this case: when the
+// selection is equal, the cached identity is returned and no re-render occurs.
 // @wrapper-known semantic-alias
 export function useStore(store) {
     return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
 }
 export function useStoreSelector(store, select, equals = Object.is) {
-    // Cache der letzten Auswahl. Beim nächsten getSnapshot-Call vergleicht
-    // der Wrapper die neu berechnete Auswahl mit dem Cache und gibt — falls
-    // gleich — die cached Identität zurück. Das ist der Trick, der
-    // Selector-Returns wie `s => ({ a, b })` stabil hält.
-    const lastSelected = useRef(undefined);
-    const initialized = useRef(false);
+    // Cache of the last selection. On the next getSnapshot call, the wrapper
+    // compares the newly computed selection with the cache and returns the
+    // cached identity when they are equal. This keeps selector results such as
+    // `s => ({ a, b })` stable.
+    const lastSelected = useRef(null);
     const getSelectedSnapshot = () => {
         const next = select(store.getSnapshot());
-        if (initialized.current && equals(lastSelected.current, next)) {
-            return lastSelected.current;
-        }
-        lastSelected.current = next;
-        initialized.current = true;
+        const cached = lastSelected.current;
+        if (cached !== null && equals(cached.value, next))
+            return cached.value;
+        lastSelected.current = { value: next };
         return next;
     };
     return useSyncExternalStore(store.subscribe, getSelectedSnapshot, getSelectedSnapshot);

package/dist/hooks/use-stream-handler.js

@@ -80,10 +80,12 @@ export function useStreamHandler(type, payload = {}, options = {}) {
     }, []);
     return { chunks, status, error, start, abort, reset };
 }
+function isDispatcherError(e) {
+    return !!e && typeof e === "object" && "code" in e && "message" in e && "i18nKey" in e;
+}
 function asDispatcherError(e) {
-    if (e && typeof e === "object" && "code" in e && "message" in e && "i18nKey" in e) {
+    if (isDispatcherError(e))
         return e;
-    }
     return {
         code: "stream_error",
         httpStatus: 0,

package/dist/i18n-defaults.js

@@ -1,12 +1,6 @@
-// Framework-Default-Bundle. Strings die die Renderer-Components hart
-// brauchen (Save/Cancel/Delete-Buttons, Empty-States, Search-Placeholder,
-// Nav-Toggle-aria-Labels, Validation-Reasons). createKumikoApp hängt das
-// als ALLERLETZTEN Fallback in den LocaleProvider — Apps können
-// einzelne Keys via clientFeatures.translations überschreiben.
+// Framework default bundle. These strings are required by renderer components (Save/Cancel/Delete buttons, empty states, search placeholder, navigation-toggle ARIA labels, and validation reasons). createKumikoApp adds this as the last fallback in LocaleProvider, while apps can override individual keys via clientFeatures.translations.
 //
-// Convention: alle Keys mit `kumiko.`-Prefix damit sie nicht mit
-// App-Keys kollidieren. Sub-Pfade gruppieren nach Bereich (actions /
-// list / nav / form / validation).
+// All keys use the `kumiko.` prefix to avoid collisions with app keys. Subpaths group keys by area (actions / list / nav / form / validation).
 export const kumikoDefaultTranslations = {
     en: {
         "kumiko.actions.save": "Save",

package/dist/i18n.d.ts

@@ -5,7 +5,7 @@ import type { LocaleResolver } from "./headless/index.ts";
  *  placeholders (same semantics as i18next t); plural entries resolve via
  *  `resolveTranslationValue`. */
 export type TranslationBundle = Readonly<Record<string, TranslationValue>>;
-/** Map von Locale-Code (BCP-47, z.B. `"de"`, `"en-US"`) → Bundle. */
+/** Map from locale code (BCP-47, e.g. `"de"`, `"en-US"`) → bundle. */
 export type TranslationsByLocale = Readonly<Record<string, TranslationBundle>>;
 /** Key-first shape for `r.translations({ keys })` — each key maps locale → TranslationValue. */
 export type TranslationsByKey = Readonly<Record<string, Readonly<Record<string, TranslationValue>>>>;
@@ -14,9 +14,9 @@ export declare function translationsByLocaleFromKeys(source: TranslationsByKey):
 /** Inverse of `translationsByLocaleFromKeys`: pivot locale-first bundles to the key-first
  *  shape `r.translations({ keys })` expects, so one source feeds server and client. */
 export declare function translationsByKeyFromLocales(source: TranslationsByLocale): TranslationsByKey;
-/** Merged zwei TranslationsByLocale-Maps — der override gewinnt pro Key,
- *  die Locales werden zusammengeführt. Standard-Baustein für Client-
- *  Plugins, die App-Overrides über ihre Default-Bundles legen. */
+/** Merges two TranslationsByLocale maps — the override wins per key,
+ *  and the locales are combined. Standard building block for client
+ *  plugins that layer app overrides over their default bundles. */
 export declare function mergeTranslations(base: TranslationsByLocale, override: TranslationsByLocale): TranslationsByLocale;
 export type LocaleProviderProps = {
     readonly resolver: LocaleResolver;
@@ -31,9 +31,9 @@ export type LocaleProviderProps = {
     readonly children: ReactNode;
 };
 export declare function LocaleProvider({ resolver, fallbackBundles, fallbackLocale, children, }: LocaleProviderProps): ReactNode;
-/** Liefert den aktuellen LocaleResolver und abonniert automatisch
- *  Locale-Änderungen — der aufrufende Component re-rendert sobald die
- *  Sprache gewechselt wird. Wirft wenn kein Provider im Baum ist. */
+/** Provides the current LocaleResolver and automatically subscribes to
+ *  locale changes — the calling component re-renders when the language
+ *  changes. Throws when there is no provider in the tree. */
 export declare function useLocale(): LocaleResolver;
 /** `t("key", params)` resolves in this order:
  *    1. App resolver (e.g. i18next)
@@ -58,9 +58,9 @@ export declare function useOptionalLocale(): string | undefined;
 export declare function useOptionalTimeZone(): string;
 /** Non-throwing translate — undefined outside LocaleProvider. */
 export declare function useOptionalTranslation(): ((key: string, params?: Readonly<Record<string, unknown>>) => string) | undefined;
-/** Default-Resolver für Apps ohne eigene i18n-Schicht. Gibt jeden Key
- *  unverändert zurück — die Plugin-Fallback-Bundles erledigen dann die
- *  echte Übersetzung. Nützlich auch als Basis für Tests. */
+/** Default resolver for apps without their own i18n layer. Returns every key
+ *  unchanged — the plugin fallback bundles then provide the actual
+ *  translation. Also useful as a basis for tests. */
 export declare function createStaticLocaleResolver(options?: {
     readonly locale?: string;
     readonly timeZone?: string;

package/dist/i18n.js

@@ -39,9 +39,9 @@ export function translationsByKeyFromLocales(source) {
     }
     return out;
 }
-/** Merged zwei TranslationsByLocale-Maps — der override gewinnt pro Key,
- *  die Locales werden zusammengeführt. Standard-Baustein für Client-
- *  Plugins, die App-Overrides über ihre Default-Bundles legen. */
+/** Merges two TranslationsByLocale maps — the override wins per key,
+ *  and the locales are combined. Standard building block for client
+ *  plugins that layer app overrides over their default bundles. */
 export function mergeTranslations(base, override) {
     const locales = new Set([...Object.keys(base), ...Object.keys(override)]);
     const merged = {};
@@ -52,10 +52,10 @@ export function mergeTranslations(base, override) {
 }
 const LocaleContext = createContext(undefined);
 const FormalityContext = createContext("informal");
-// Stabile Referenz statt `fallbackBundles = []` als Default-Parameter:
-// ein Literal-Default wird bei JEDEM Aufruf neu allokiert und würde die
-// useMemo-Referenzprüfung im Provider unten aushebeln, sobald der
-// Aufrufer fallbackBundles weglässt.
+// Stable reference instead of `fallbackBundles = []` as a default parameter:
+// a literal default is allocated on EVERY call and would invalidate the
+// useMemo reference check in the provider below whenever the caller omits
+// fallbackBundles.
 const EMPTY_FALLBACK_BUNDLES = [];
 export function LocaleProvider({ resolver, fallbackBundles = EMPTY_FALLBACK_BUNDLES, fallbackLocale = "en", children, }) {
     // Without memoization every re-render of the provider (e.g. because an
@@ -67,16 +67,16 @@ export function LocaleProvider({ resolver, fallbackBundles = EMPTY_FALLBACK_BUND
     const value = useMemo(() => ({ resolver, fallbackBundles, fallbackLocale }), [resolver, fallbackBundles, fallbackLocale]);
     return _jsx(LocaleContext.Provider, { value: value, children: children });
 }
-/** Liefert den aktuellen LocaleResolver und abonniert automatisch
- *  Locale-Änderungen — der aufrufende Component re-rendert sobald die
- *  Sprache gewechselt wird. Wirft wenn kein Provider im Baum ist. */
+/** Provides the current LocaleResolver and automatically subscribes to
+ *  locale changes — the calling component re-renders when the language
+ *  changes. Throws when there is no provider in the tree. */
 export function useLocale() {
     const ctx = useContext(LocaleContext);
     if (ctx === undefined) {
         throw new Error("useLocale must be used inside <LocaleProvider>");
     }
-    // Subscribe + current locale-snapshot. Wir brauchen den Rückgabewert
-    // selbst nicht — wichtig ist nur der re-render-trigger.
+    // Subscribe + current locale snapshot. We do not need the return value
+    // itself — only the re-render trigger matters.
     const getLocaleSnapshot = () => ctx.resolver.locale();
     useSyncExternalStore(ctx.resolver.subscribe, getLocaleSnapshot, getLocaleSnapshot);
     return ctx.resolver;
@@ -93,16 +93,16 @@ export function useTranslation() {
     if (ctx === undefined) {
         throw new Error("useTranslation must be used inside <LocaleProvider>");
     }
-    // Re-Render bei Sprach-Wechsel. `ctx.resolver.subscribe` ist bereits
-    // eine stable-reference aus dem Resolver, daher hier keine eigene
-    // Memoization der Subscribe-Callback nötig.
+    // Re-render on language changes. `ctx.resolver.subscribe` is already
+    // a stable reference from the resolver, so no separate subscription
+    // callback memoization is needed here.
     const getLocaleSnapshot = () => ctx.resolver.locale();
     const locale = useSyncExternalStore(ctx.resolver.subscribe, getLocaleSnapshot, getLocaleSnapshot);
-    // `t` MUSS referenz-stabil sein solange sich Resolver/Bundles/Locale
-    // nicht ändern — Consumer nutzen `t` regelmäßig in useEffect-Deps
-    // (z.B. um Queries neu zu laden wenn sich die Sprache ändert). Ein neu
-    // erzeugtes `t` pro Render führt sonst zu einem Render/Effect-Endlos-
-    // Loop (siehe admin-shell Overview-Screens, Prod-Incident 2026-07-07).
+    // `t` MUST remain referentially stable while the resolver/bundles/locale
+    // do not change — consumers regularly use `t` in useEffect dependencies
+    // (e.g. to reload queries when the language changes). Creating a new `t`
+    // on every render would otherwise cause a render/effect infinite loop
+    // (see the admin-shell Overview screens, production incident).
     const formality = useContext(FormalityContext);
     return useCallback((key, params) => translateWithFallbacks(ctx, locale, formality, key, params), [ctx, locale, formality]);
 }
@@ -165,9 +165,9 @@ export function useOptionalTranslation() {
     const t = useCallback((key, params) => ctx === undefined ? key : translateWithFallbacks(ctx, locale, formality, key, params), [ctx, locale, formality]);
     return ctx === undefined ? undefined : t;
 }
-/** Default-Resolver für Apps ohne eigene i18n-Schicht. Gibt jeden Key
- *  unverändert zurück — die Plugin-Fallback-Bundles erledigen dann die
- *  echte Übersetzung. Nützlich auch als Basis für Tests. */
+/** Default resolver for apps without their own i18n layer. Returns every key
+ *  unchanged — the plugin fallback bundles then provide the actual
+ *  translation. Also useful as a basis for tests. */
 export function createStaticLocaleResolver(options = {}) {
     const locale = options.locale ?? "en";
     const timeZone = options.timeZone ?? "UTC";
@@ -175,8 +175,8 @@ export function createStaticLocaleResolver(options = {}) {
         translate: (key) => key,
         locale: () => locale,
         timeZone: () => timeZone,
-        // No-op subscribe: unsere Locale ist statisch, es gibt nie ein
-        // Change-Event. Unsubscribe ist ebenfalls no-op.
+        // No-op subscribe: our locale is static, so no change event ever occurs.
+        // Unsubscribe is also a no-op.
         subscribe: () => () => { },
     };
 }

package/dist/index.js

@@ -1,7 +1,8 @@
-// Platform-agnostic React renderer for Kumiko screens. Das ist der
-// Shared-Layer: Components, Hooks, Contexts, Types. Die Web-DOM-Impls
-// leben unter ./web und reichen ihre konkreten Primitives/Nav/SSE-Impls via
-// Provider in diesen Baum.
+// Platform-agnostic React renderer for Kumiko screens. This is the
+// shared layer for components, hooks, contexts, and types. Web DOM
+// implementations live under ./web and provide their concrete
+// primitives, navigation, and SSE implementations through providers
+// in this tree.
 //
 // Direct consumers of this layer: platform bindings
 // (@cosmicdrift/kumiko-renderer/web) or an app writing its own bootstrap.

package/dist/live/dispatcher-live.js

@@ -89,7 +89,7 @@ export function createLiveDispatcher(options = {}) {
     return {
         async write(type, payload, opts) {
             const body = { type, payload };
-            // Idempotency by default (#761): without a requestId the server-side
+            // Idempotency by default: 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.
@@ -106,7 +106,7 @@ export function createLiveDispatcher(options = {}) {
             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).
+            // re-executing the commands.
             body["requestId"] = opts?.requestId ?? generateRequestId();
             const call = await callJson(PATH_BATCH, body, opts?.signal);
             return normalizeBatchResponse(call);