@cosmicdrift/kumiko-renderer 0.386.0 → 0.387.0

package/dist/primitives.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, } from "react";
 /** 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
+ *  sticky-footer split treats it as the pinned primary action even
  *  though it isn't a `Button` with `type="submit"` — e.g. RenderEdit's
  *  footer-slot mount, whose actual rendered button is opaque app code the
  *  split can't inspect (see `ScreenSlots.footerPrimary`). */

package/dist/sse/live-events.d.ts

@@ -14,15 +14,15 @@ export type LiveEvent = {
 /** Synthetic eventType delivered to every subscribed entity after the stream
  *  reconnected: frames during the gap are lost, so consumers must refetch. */
 export declare const LIVE_RESYNC_EVENT_TYPE = "live.resync";
-/** Abonniert Live-Events für eine Entity (aggregateType). Returnt die
- *  Unsubscribe-Funktion. Mehrere Subscriptions parallel auf dieselbe
- *  Entity sind erlaubt — jede bekommt ihr eigenes Event. */
+/** Subscribes to live events for an entity (aggregateType) and returns the
+ *  unsubscribe function. Multiple subscriptions to the same entity are
+ *  allowed in parallel; each receives its own event. */
 export type LiveEventSubscriber = (entityName: string, listener: (event: LiveEvent) => void) => () => void;
 export type LiveEventsProviderProps = {
     readonly children: ReactNode;
     readonly value: LiveEventSubscriber;
 };
 export declare function LiveEventsProvider({ children, value }: LiveEventsProviderProps): ReactNode;
-/** Hook für useQuery-like Consumer. Liefert die Subscribe-Function
- *  aus dem Context. Wenn kein Provider da ist, ist's ein No-op. */
+/** Hook for a useQuery-like consumer. Returns the subscription function
+ *  from the context. Without a provider, it is a no-op. */
 export declare function useLiveEvents(): LiveEventSubscriber;

package/dist/sse/live-events.js

@@ -1,31 +1,31 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// Live-Events-Contract, plattform-neutral. Die Plattform (Web mit
-// EventSource, Native mit polyfill) liefert einen `LiveEventSubscriber`
-// via `<LiveEventsProvider value={...}>`; der shared-Layer konsumiert
-// nur das Interface.
+// Platform-neutral live-events contract. The platform (Web with
+// EventSource, Native with polyfill) supplies a `LiveEventSubscriber`
+// via `<LiveEventsProvider value={...}>`; the shared layer consumes
+// only the interface.
 //
-// Warum ein Context statt Module-Singleton wie vor dem Split: ein
-// Module-Singleton koppelt an eine globale Verbindung. Mit Context
-// kann der Caller pro Tree eine andere Subscribe-Quelle durchreichen
-// — nützlich in Tests (Fake-Feed), bei Multi-Tenant-Bridges, und
-// beim Native-Renderer wo die Verbindungs-Lifecycle oft nicht dem
-// App-Lifecycle entspricht.
+// A Context is used instead of a module singleton as before the split:
+// a module singleton couples the code to a global connection. Context
+// lets the caller provide a different subscription source per tree,
+// which is useful for tests (Fake-Feed), multi-tenant bridges, and
+// the Native renderer, where connection lifecycle often differs from
+// the app lifecycle.
 import { createContext, useContext } from "react";
 /** Synthetic eventType delivered to every subscribed entity after the stream
  *  reconnected: frames during the gap are lost, so consumers must refetch. */
 export const LIVE_RESYNC_EVENT_TYPE = "live.resync";
-// Wenn kein Provider da ist, liefern wir einen No-op-Subscriber statt
-// zu crashen. Grund: useQuery({ live: true }) kann optimistisch
-// ausgehakt werden ohne den ganzen Baum abzureißen, wenn die Plattform
-// z.B. SSE temporär deaktiviert hat. Fehler-Signale würden stumm
-// geschluckt — das ist explizit dokumentiert.
+// If no provider is present, return a no-op subscriber instead of
+// throwing. This allows useQuery({ live: true }) to be optimistically
+// disabled without tearing down the entire tree when the platform has
+// temporarily disabled SSE. Error signals are silently swallowed; this
+// is intentional and documented.
 const noopSubscriber = () => () => { };
 const LiveEventsContext = createContext(noopSubscriber);
 export function LiveEventsProvider({ children, value }) {
     return _jsx(LiveEventsContext.Provider, { value: value, children: children });
 }
-/** Hook für useQuery-like Consumer. Liefert die Subscribe-Function
- *  aus dem Context. Wenn kein Provider da ist, ist's ein No-op. */
+/** Hook for a useQuery-like consumer. Returns the subscription function
+ *  from the context. Without a provider, it is a no-op. */
 export function useLiveEvents() {
     return useContext(LiveEventsContext);
 }

package/dist/tokens.d.ts

@@ -44,7 +44,7 @@ export type CoreTokens = {
     readonly shadow: ShadowTokens;
     readonly spacing: SpacingTokens;
 };
-/** Erweiterung für App-eigene Token-Kategorien. Devs augmentieren:
+/** Extension point for app-specific token categories. Augment it, for example:
  *
  *    declare module "@cosmicdrift/kumiko-renderer" {
  *      interface AppTokens {
@@ -52,8 +52,8 @@ export type CoreTokens = {
  *      }
  *    }
  *
- *  Und reichen im App-CSS die passenden `--chart-*` Variablen rein.
- *  Kumikos Default-Primitives nutzen nur CoreTokens. */
+ *  Then provide the matching `--chart-*` variables in the app's CSS.
+ *  Kumiko's default primitives use only CoreTokens. */
 export interface AppTokens {
 }
 export type Tokens = CoreTokens & AppTokens;
@@ -78,12 +78,12 @@ export type TokensProviderProps = {
     readonly value: TokensApi;
 };
 export declare function TokensProvider({ children, value }: TokensProviderProps): ReactNode;
-/** Read-only Tokens-Hook. Liefert CSS-var-Strings — nutzbar in
- *  style-Props oder Tailwind-arbitrary-values wie
- *  `bg-[var(--color-primary)]` (selten, die shadcn-Tailwind-Klassen
- *  `bg-primary` sind idiomatischer). */
+/** Read-only tokens hook. Provides CSS variable strings for use in
+ *  style props or Tailwind arbitrary values such as
+ *  `bg-[var(--color-primary)]` (rarely needed; the shadcn Tailwind class
+ *  `bg-primary` is more idiomatic). */
 export declare function useTokens(): Tokens;
-/** Volle API inkl. Theme-Toggle. Für den Dark/Light-Switch-Button. */
+/** Full API including theme toggling, for a dark/light switch button. */
 export declare function useTokenController(): TokensApi;
 /** Tokens with var-string values. Constant: the "values" are references,
  *  the real colors change via CSS without mutating the object. Platform

package/dist/tokens.js

@@ -1,32 +1,31 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// Design-Tokens im shadcn-Namensschema. Werte sind CSS-Variable-
-// Referenzen (`var(--color-primary)`) — die echten Zahlen leben in
-// styles.css (Web) bzw. in einer StyleSheet.create-Config (Native,
-// später). Der Hook ist vor allem für Custom-Components die mal
-// einen Token-Wert in eine JS-style-prop schieben müssen; die
-// Default-Primitives nutzen direkt Tailwind-Klassen und brauchen
-// ihn nicht.
+// Design tokens using the shadcn naming scheme. Values are CSS variable
+// references (`var(--color-primary)`); the actual values live in
+// styles.css (Web) or a StyleSheet.create configuration (Native,
+// later). The hook is mainly for custom components that need to pass a
+// token value to a JS style prop; the default primitives use Tailwind
+// classes directly and do not need it.
 //
-// Theme-Toggle läuft über `.dark`-Class auf `<html>` — kein JS-State
-// nötig, CSS rendert sofort neu. `useTokenController().toggleTheme()`
-// ist nur ein DOM-Wrapper, kein eigener React-State.
+// Theme toggling uses the `.dark` class on `<html>`, so no JS state is
+// needed and CSS updates immediately. `useTokenController().toggleTheme()`
+// is only a DOM wrapper, not separate React state.
 //
-// Erweiterbar: AppTokens-Interface wie bei Primitives. Dev kann
-// eigene Token-Kategorien deklarieren und mit var-Strings befüllen.
+// Extensible: augment the AppTokens interface as with primitives. Apps can
+// declare custom token categories and populate them with var strings.
 import { createContext, useContext } from "react";
 // ---- Context + Provider + Hooks ----
 const TokensContext = createContext(undefined);
 export function TokensProvider({ children, value }) {
     return _jsx(TokensContext.Provider, { value: value, children: children });
 }
-/** Read-only Tokens-Hook. Liefert CSS-var-Strings — nutzbar in
- *  style-Props oder Tailwind-arbitrary-values wie
- *  `bg-[var(--color-primary)]` (selten, die shadcn-Tailwind-Klassen
- *  `bg-primary` sind idiomatischer). */
+/** Read-only tokens hook. Provides CSS variable strings for use in
+ *  style props or Tailwind arbitrary values such as
+ *  `bg-[var(--color-primary)]` (rarely needed; the shadcn Tailwind class
+ *  `bg-primary` is more idiomatic). */
 export function useTokens() {
     return useTokenController().tokens;
 }
-/** Volle API inkl. Theme-Toggle. Für den Dark/Light-Switch-Button. */
+/** Full API including theme toggling, for a dark/light switch button. */
 export function useTokenController() {
     const api = useContext(TokensContext);
     if (api === undefined) {

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

@@ -1,10 +1,10 @@
 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. */
+    /** localStorage key used to persist the active locale.
+     *  Default: `"kumiko:locale"`. Apps that mount multiple Kumiko instances on
+     *  the same origin (rarely) should use different keys. */
     readonly storageKey?: string;
-    /** Fallback wenn weder localStorage noch navigator.language liefern.
+    /** Fallback when neither localStorage nor navigator.language provides a locale.
      *  Default: `"en"`. */
     readonly defaultLocale?: string;
     /** Maps a stored or browser-reported tag onto one of the app's locales;
@@ -14,9 +14,9 @@ export type CreateBrowserLocaleResolverOptions = {
     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 })`. */
+/** Default resolver when createKumikoApp is booted without a `locale` option.
+ *  Stateful: setLocale() persists to localStorage and notifies subscribed
+ *  listeners. Apps with a full i18n layer (i18next, FormatJS, or a custom
+ *  store) should instead pass their own resolver via
+ *  `createKumikoApp({ locale })`. */
 export declare function createBrowserLocaleResolver(options?: CreateBrowserLocaleResolverOptions): LocaleResolver;

package/dist/web/app/browser-locale.js

@@ -1,15 +1,15 @@
-// Browser-spezifischer LocaleResolver-Default für createKumikoApp.
+// Browser-specific LocaleResolver default for createKumikoApp.
 //
-// Stateful: hält die aktuelle Locale in localStorage, bricht subscribe-
-// listener bei setLocale(). Initial-wert kommt aus localStorage wenn
-// gespeichert, sonst aus navigator.language, sonst aus defaultLocale.
+// Stateful: stores the current locale in localStorage and notifies subscribed
+// listeners when setLocale() is called. The initial value comes from
+// localStorage when available, otherwise from navigator.language, and finally
+// from defaultLocale.
 //
-// App-Code setzt die Locale programmatisch via resolver.setLocale() —
-// der LanguageSwitcher-Component macht genau das. Persistenz über
-// localStorage heißt: nach Page-Reload gleiche Sprache, ohne Server-
-// Roundtrip. Für device-übergreifende Persistenz würde ein
-// user:write:update auf user.locale zusätzlich gesetzt (separater
-// App-Code, nicht im Resolver).
+// App code sets the locale programmatically via resolver.setLocale(), as the
+// LanguageSwitcher component does. localStorage persistence preserves the
+// language after a page reload without a server round trip. Cross-device
+// persistence would additionally require a user:write:update for user.locale
+// in separate app code, not in the resolver.
 import { createStore } from "../../headless/index.js";
 export const BROWSER_LOCALE_STORAGE_KEY = "kumiko:locale";
 function detectInitialLocale(storageKey, fallback, normalizeLocale) {
@@ -23,8 +23,8 @@ function detectInitialLocale(storageKey, fallback, normalizeLocale) {
             }
         }
         catch {
-            // localStorage kann throwen (safari private mode, disabled) —
-            // leise auf navigator zurückfallen.
+            // localStorage can throw (Safari private mode, disabled) —
+            // silently fall back to navigator.
         }
     }
     if (typeof navigator !== "undefined" && navigator.language) {
@@ -42,11 +42,11 @@ function detectTimeZone() {
         return "UTC";
     }
 }
-/** 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 })`. */
+/** Default resolver when createKumikoApp is booted without a `locale` option.
+ *  Stateful: setLocale() persists to localStorage and notifies subscribed
+ *  listeners. Apps with a full i18n layer (i18next, FormatJS, or a custom
+ *  store) should instead pass their own resolver via
+ *  `createKumikoApp({ locale })`. */
 export function createBrowserLocaleResolver(options = {}) {
     const storageKey = options.storageKey ?? BROWSER_LOCALE_STORAGE_KEY;
     const fallback = options.defaultLocale ?? "en";
@@ -69,8 +69,8 @@ export function createBrowserLocaleResolver(options = {}) {
                     localStorage.setItem(storageKey, next);
                 }
                 catch {
-                    // Persistenz fehlgeschlagen ist nicht fatal — die Session-Locale
-                    // bleibt trotzdem gesetzt, nur der nächste Reload verliert sie.
+                    // Persistence failure is not fatal — the session locale remains set,
+                    // but the next reload will lose it.
                 }
             }
         },

package/dist/web/app/client-plugin.d.ts

@@ -12,62 +12,57 @@ export type CollectionNavProviders = {
 };
 export type ClientFeatureDefinition = {
     readonly name: string;
-    /** Context-Provider die um den kompletten Renderer-Tree gewrapped
-     *  werden. Reihenfolge: erstes Element = äußerster Provider. Alle
-     *  Provider stehen VOR allen Gates im Baum, damit jeder Gate und
-     *  jedes Screen-Child darauf Zugriff hat. */
+    /** Context providers wrapped around the complete renderer tree. The first
+     * array element is the outermost provider. All providers precede all gates
+     * in the tree so every gate and screen child can access them. */
     readonly providers?: readonly ComponentType<{
         children: ReactNode;
     }>[];
-    /** Screen-Decorators die zwischen dem Provider-Stack und dem Shell/
-     *  Screen-Render sitzen. Typisches Muster: AuthGate rendert den
-     *  LoginScreen statt children solange der User nicht eingeloggt ist.
-     *  Reihenfolge: erstes Element = äußerster Gate. */
+    /** Screen decorators placed between the provider stack and the shell or
+     * screen render. A typical pattern is AuthGate rendering LoginScreen
+     * instead of children while the user is not signed in. The first array
+     * element is the outermost gate. */
     readonly gates?: readonly ComponentType<{
         children: ReactNode;
     }>[];
-    /** Default-Translations die das Feature für seine UI-Strings
-     *  mitbringt. Werden in den LocaleProvider als Fallback-Bundle
-     *  eingehängt — der App-Resolver (z.B. i18next) hat Vorrang und kann
-     *  einzelne Keys überschreiben, ohne dass die Feature-Bundles
-     *  komplett ausgetauscht werden müssen. */
+    /** Default translations supplied by the feature for its UI strings. They
+     * are added to the LocaleProvider as a fallback bundle; the app resolver
+     * (for example, i18next) takes precedence and can override individual keys
+     * without replacing the feature bundles entirely. */
     readonly translations?: TranslationsByLocale;
-    /** Custom-Screen-Components — Map screenId → React-Component. Wenn
-     *  ein Schema-Screen `type: "custom"` hat, schaut KumikoScreen in
-     *  diese Map (gemerged aus allen ClientFeatures) und rendert die
-     *  passende Component. So muss kein Sample mehr im AppShell-Wrapper
-     *  selbst routen. Convention: screenId entspricht dem `id` aus
-     *  `r.screen({ id, type: "custom", ... })` im server-side Feature. */
+    /** Custom screen components, mapped by screenId. When a schema screen has
+     * `type: "custom"`, KumikoScreen looks up and renders the matching component
+     * in this map, merged from all client features. This keeps routing out of
+     * the AppShell wrapper. The convention is that screenId matches the `id` in
+     * `r.screen({ id, type: "custom", ... })` in the server-side feature. */
     readonly components?: Readonly<Record<string, ComponentType>>;
-    /** Column-Renderer-Components — Map renderer-name → React-Component.
-     *  Schema deklariert eine Column mit
-     *  `renderer: { react: { __component: "ColorSwatch" } }`; client-side
-     *  zieht der DataTable-Cell-Renderer den Component hier raus.
-     *  Schemas bleiben so serializable (nur ein String-Key auf der Wire),
-     *  echte JSX-Renderer leben im Client-Bundle. Last-Wins bei Key-
-     *  Kollision über mehrere Features. */
+    /** Column renderer components, mapped by renderer name. A schema declares a
+     * column with `renderer: { react: { __component: "ColorSwatch" } }`; the
+     * client-side DataTable cell renderer looks up the component here. Schemas
+     * remain serializable because only a string key crosses the wire, while the
+     * actual JSX renderers live in the client bundle. Later features win on key
+     * collisions. */
     readonly columnRenderers?: Readonly<Record<string, ColumnRendererComponent>>;
-    /** Extension-Section-Components — Map `__component`-name → React-
-     *  Component. Schema deklariert eine entityEdit-Section mit
-     *  `kind: "extension"` + `component: { react: { __component: "X" } }`;
-     *  RenderEdit zieht den Component hier raus und mountet ihn mit
-     *  `{ entityName, entityId }`. Pattern wie columnRenderers — Last-Wins
-     *  bei Key-Kollision über mehrere Features. */
+    /** Extension-section components, mapped by `__component` name. A schema
+     * declares an entityEdit section with `kind: "extension"` and
+     * `component: { react: { __component: "X" } }`; RenderEdit looks up and
+     * mounts the component here with `{ entityName, entityId }`. As with
+     * columnRenderers, later features win on key collisions. */
     readonly extensionSectionComponents?: Readonly<Record<string, ExtensionSectionComponent>>;
     /** Handlers for RowAction `kind: "clientAction"`, keyed by the action name
      *  `<feature>:<kebab>`. Last-wins with a warning on key collisions, like
      *  columnRenderers. */
     readonly clientActions?: Readonly<Record<string, ClientActionHandler>>;
-    /** Nav-Provider für die EINE Nav (Visual-Tree-Merge): hängt dynamische
-     *  Children an einen statischen `r.nav({ provider: true })`-Knoten. Keyed
-     *  auf die LOKALE nav-id (create-app qualifiziert zu `<feature>:nav:<id>`;
-     *  bereits qualifizierte QNs gehen durch). Anders als `treeProvider` (ein
-     *  Top-Level-Branch pro Feature) attacht ein navProvider an einen konkreten
-     *  Nav-Knoten — der idiomatic Weg seit dem Tree→Nav-Merge. */
+    /** Nav providers for the single nav visual-tree merge: they attach dynamic
+     * children to a static `r.nav({ provider: true })` node. Keys use the local
+     * nav ID; create-app qualifies it as `<feature>:nav:<id>`, while already
+     * qualified names pass through. Unlike `treeProvider`, which creates one
+     * top-level branch per feature, a navProvider attaches to a specific nav
+     * node—the idiomatic approach since the tree-to-nav merge. */
     readonly navProviders?: Readonly<Record<string, TreeChildrenSubscribe>>;
-    /** SSE-Entity-Listen pro nav-id für den Live-Refresh der navProviders
-     *  (analog `treeEntities`). Live-Event für eine Entity → Provider des
-     *  Knotens wird neu aufgerufen → neue Kinder erscheinen live. */
+    /** SSE entity lists per nav ID for live refresh of navProviders, analogous
+     * to `treeEntities`. A live event for an entity re-invokes the node's
+     * provider so new children appear immediately. */
     readonly navEntities?: Readonly<Record<string, readonly string[]>>;
     /** Nav providers derived from the app schema — called with every
      *  `r.contentCollection()` the app declares. A feature that serves any
@@ -85,22 +80,19 @@ export type ClientFeatureDefinition = {
      *  format. Same last-wins semantics as columnRenderers. Public component
      *  contract: `{ value, onChange, variables, readOnly }`. */
     readonly contentEditors?: Partial<Record<ContentEditorFormat, ContentEditorComponent>>;
-    /** Editor-Resolver-Komponenten pro featureId:action-Key. Wenn ein
-     *  TreeNode mit target angeklickt wird, schlägt der EditorPanel das
-     *  Component hier nach und rendert es. Komponenten erhalten target
-     *  (mit args) und eine onClose-Callback. Ohne registrierten Resolver
-     *  zeigt der EditorPanel einen Info-Fallback.
-     *  Siehe visual-tree.md V.1.2. */
+    /** Editor resolver components keyed by featureId:action. When a TreeNode
+     * with a target is clicked, EditorPanel looks up and renders the component
+     * here. Components receive target (with args) and an onClose callback. If
+     * no resolver is registered, EditorPanel shows an informational fallback. */
     readonly resolvers?: Readonly<Record<string, ComponentType<{
         readonly target: TargetRef;
         readonly onClose: () => void;
     }>>>;
 };
-/** Wickelt einen ReactNode durch eine Liste von Providern/Gates von
- *  innen nach außen — erstes Array-Element ist äußerste Hülle.
- *  Der Key nutzt den Component-Display-Namen (falls gesetzt) plus
- *  Index, damit Mounts stabil bleiben solange die Wrapper-Liste
- *  ihre Reihenfolge nicht ändert. */
+/** Wraps a ReactNode with a list of providers or gates from inside out; the
+ * first array element is the outermost wrapper. The key uses the component's
+ * display name, when available, plus its index, keeping mounts stable while
+ * the wrapper list's order does not change. */
 export declare function stackWrappers(wrappers: readonly ComponentType<{
     children: ReactNode;
 }>[], inner: ReactNode): ReactNode;

package/dist/web/app/client-plugin.js

@@ -1,9 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-/** Wickelt einen ReactNode durch eine Liste von Providern/Gates von
- *  innen nach außen — erstes Array-Element ist äußerste Hülle.
- *  Der Key nutzt den Component-Display-Namen (falls gesetzt) plus
- *  Index, damit Mounts stabil bleiben solange die Wrapper-Liste
- *  ihre Reihenfolge nicht ändert. */
+/** Wraps a ReactNode with a list of providers or gates from inside out; the
+ * first array element is the outermost wrapper. The key uses the component's
+ * display name, when available, plus its index, keeping mounts stable while
+ * the wrapper list's order does not change. */
 export function stackWrappers(wrappers, inner) {
     return wrappers.reduceRight((acc, Wrapper, i) => {
         const key = `${Wrapper.displayName ?? Wrapper.name ?? "wrapper"}-${i}`;

package/dist/web/app/create-app.d.ts

@@ -42,7 +42,7 @@ export type CreateKumikoAppOptions = {
      *  `createLiveDispatcher`); a cross-origin URL is fetched with
      *  `credentials: "include"`. */
     readonly schemaUrl?: string;
-    /** RenderEdit's create-mode draftId storage (issue #1913) — where a
+    /** RenderEdit's create-mode draftId storage — where a
      *  same-tab reload finds which of several parallel create-sessions on a
      *  screen to resume. Default: `createBrowserDraftStorage()`
      *  (sessionStorage-backed). Apps that don't want any client-side draftId
@@ -52,51 +52,48 @@ export type CreateKumikoAppOptions = {
     readonly screenQn?: string;
     readonly translate?: Translate;
     /** Row-click fallback for entities with no declared `detailFor` screen
-     *  (fw#2164) — a `detailFor` screen always wins over this option. */
+     *  — a `detailFor` screen always wins over this option. */
     readonly onRowClick?: (row: ListRowViewModel, entityName: string) => void;
-    /** App-Shell. Bekommt das resolved `schema` als Prop — so können
-     *  AppShell-Komponenten an WorkspaceShell/DefaultAppShell durchreichen
-     *  ohne selbst das Schema zu importieren oder auf window-Globals zu
-     *  greifen. */
+    /** App shell. Receives the resolved `schema` as a prop so AppShell
+     *  components can pass it through to WorkspaceShell/DefaultAppShell
+     *  without importing the schema themselves or accessing window globals. */
     readonly shell?: (props: {
         readonly children: ReactNode;
         readonly schema: AppSchema;
     }) => ReactNode;
     readonly primitives?: Partial<PrimitivesRegistry>;
-    /** Feature-gelieferte Client-Extensions. Jedes Element bringt
-     *  Provider + Gates mit — siehe ClientFeatureDefinition. Beispiel:
-     *  `clientFeatures: [emailPasswordClient()]` für Session+Login. */
+    /** Client extensions supplied by features. Each element provides a
+     *  provider and gates; see ClientFeatureDefinition. Example:
+     *  `clientFeatures: [emailPasswordClient()]` for session and login. */
     readonly clientFeatures?: readonly ClientFeatureDefinition[];
-    /** App-level LocaleResolver. Typischerweise ein Adapter um i18next
-     *  oder eine eigene Store-Impl. Wenn nicht gesetzt → Static-Default
-     *  (`locale: "en"`, `translate: key → key`); Plugin-Translations
-     *  springen dann als Fallback ein. */
+    /** App-level LocaleResolver. Typically an adapter around i18next
+     *  or a custom store. If unset, the static default is used
+     *  (`locale: "en"`, `translate: key → key`); plugin translations then
+     *  serve as fallbacks. */
     readonly locale?: LocaleResolver;
-    /** Nav-Adapter — ein React-Hook der eine NavApi-Instanz liefert
-     *  (route + navigate + hrefFor). Default: `useBrowserNavApi`, das
-     *  window.history als Source-of-Truth benutzt. Wer einen anderen
-     *  Router anbinden will (TanStack Router, Expo Linking auf Mobile,
-     *  Memory-Router in Tests) übergibt hier seinen eigenen Hook.
+    /** Navigation adapter — a React hook that returns a NavApi instance
+     *  (route + navigate + hrefFor). Default: `useBrowserNavApi`, which uses
+     *  window.history as the source of truth. To integrate another router
+     *  (TanStack Router, Expo Linking on mobile, or a memory router in tests),
+     *  provide your own hook here.
      *
-     *  Der Hook wird EINMAL im Component-Tree aufgerufen (siehe
-     *  `BrowserNavBoot`), muss also den React-Rules-of-Hooks folgen —
-     *  `useSyncExternalStore` auf der zugrundeliegenden Router-State
-     *  ist das gängige Pattern.
+     *  The hook is called ONCE in the component tree (see `BrowserNavBoot`),
+     *  so it must follow the React Rules of Hooks — `useSyncExternalStore` on
+     *  the underlying router state is the usual pattern.
      *
-     *  Wenn das Schema Workspaces deklariert, wird der Adapter mit
-     *  `{ hasWorkspaces: true }` aufgerufen — der Default-Hook nutzt das
-     *  um das URL-Pattern auf `/<workspace>/<screen>[/<entityId>]`
-     *  umzustellen. Eigene Adapter dürfen die Option ignorieren wenn ihr
-     *  Router das anders löst. `features` ist `app.features` — der
-     *  Default-Hook braucht sie für resolveTarget() (ObjectTarget →
-     *  ScreenTarget); eigene Adapter die nie ein ObjectTarget bekommen,
-     *  dürfen sie ignorieren. */
+     *  When the schema declares workspaces, the adapter is called with
+     *  `{ hasWorkspaces: true }`; the default hook uses this to change the URL
+     *  pattern to `/<workspace>/<screen>[/<entityId>]`. Custom adapters may
+     *  ignore this option if their router handles it differently. `features` is
+     *  `app.features`; the default hook needs it for resolveTarget()
+     *  (ObjectTarget → ScreenTarget). Adapters that never receive an
+     *  ObjectTarget may ignore it. */
     readonly navAdapter?: (options?: {
         readonly hasWorkspaces?: boolean;
         readonly features?: readonly FeatureSchema[];
     }) => NavApi;
     /** App-wide default width for form/detail screens that don't set their
-     *  own `layout.width` (fw#2656). Default "4xl" (unchanged behavior) — a
+     *  own `layout.width`. Default "4xl" (unchanged behavior) — a
      *  consumer app that wants e.g. bundled-feature screens to match its own
      *  full-width lists passes `screenWidth: "full"` once here instead of
      *  forking every screen it doesn't own. Per-screen `layout.width` always