@cosmicdrift/kumiko-renderer 0.386.0 → 0.388.0

package/dist/web/app/create-app.js

@@ -6,6 +6,7 @@ import { rendererError, rendererWarn } from "../../dev-console.js";
 import { AppFeaturesProvider, ClientActionsProvider, ColumnRenderersProvider, ContentEditorsProvider, CustomScreensProvider, createSessionEndedSignal, DashboardBodyProvider, DispatcherProvider, DraftStorageProvider, ErrorBoundary, ExtensionSectionsProvider, hasDetailScreen, KumikoScreen, kumikoDefaultTranslations, LeaveGuardDialog, LiveEventsProvider, LocaleProvider, mergeTranslations, NavProvider, navigateWithReturnTo, PrimitivesProvider, qualifyScreenId, ScreenMissingState, SessionEndedSignalProvider, TokensProvider, toAppSchema, translationsByLocaleFromKeys, useNav, usePrimitives, useTranslation, withSessionEndedDetection, } from "../../index.js";
 import { createLiveDispatcher } from "../../live/index.js";
 import { lastSegment } from "../layout/nav-tree.js";
+import { clearFileMetaCache } from "../primitives/file-thumbnail.js";
 import { defaultPrimitives, ScreenWidthProvider } from "../primitives/index.js";
 import { ToastProvider } from "../primitives/toast.js";
 import { createEventSourceLiveEvents } from "../sse/live-events.js";
@@ -26,20 +27,20 @@ import { ScreenErrorFallback } from "./screen-error-fallback.js";
 import { ToastActionNotifier } from "./toast-action-notifier.js";
 const EMPTY_FEATURES = [];
 const EMPTY_COLLECTIONS = [];
-// Qualifiziert den Key eines navProviders auf seine Nav-QN. Lokale ids
-// (z.B. "content") werden wie in r.nav mit dem Feature-Namen qualifiziert;
-// bereits qualifizierte QNs (App registriert die Nav für ein bundled-feature
-// und gibt die QN als navId rein, z.B. "publicstatus:nav:content") gehen
-// unverändert durch. MUSS konsistent zu qualifyNavId bleiben, sonst findet
-// der NavTree-Knoten (Schema-Seite) seinen Provider nicht.
+// Qualifies a navProvider key to its nav QN. Local IDs
+// (e.g. "content") are qualified with the feature name as in r.nav;
+// already qualified QNs (the app registers navigation for a bundled feature
+// and passes the QN as navId, e.g. "publicstatus:nav:content") pass through
+// unchanged. This MUST stay consistent with qualifyNavId, otherwise the
+// schema-side NavTree node cannot find its provider.
 export function qualifyNavProviderKey(feature, id) {
     return id.includes(":nav:") ? id : `${feature}:nav:${id}`;
 }
-// Nav-Provider-Map: ein navProvider hängt dynamische Children an einen
-// konkreten r.nav({provider:true})-Knoten (per QN). Lokale nav-ids werden wie
-// in r.nav mit dem Feature-Namen qualifiziert; bereits qualifizierte QNs
-// (cross-feature, z.B. App registriert Nav für ein bundled-feature) gehen
-// unverändert durch.
+// Nav-provider map: a navProvider attaches dynamic children to a specific
+// r.nav({provider:true}) node by QN. Local nav IDs are qualified with the
+// feature name as in r.nav; already qualified QNs (for cross-feature use,
+// e.g. when the app registers navigation for a bundled feature) pass through
+// unchanged.
 //
 // Schema-derived providers (r.contentCollection) run first and hold the weaker
 // claim on a QN — an explicitly registered navProvider overrides them without
@@ -92,7 +93,7 @@ function readInjectedSchema() {
 // screen a feature only registers for manual app-side placement (e.g.
 // auth-mfa's enable screen) can win by declaration order alone, landing
 // every app without an explicit `screenQn` on a screen nobody wired a
-// component for (#1258).
+// component for.
 function firstNavReachableScreenQn(features, acceptsScreen) {
     // NavDefinition.screen carries two shapes in practice: most bundled
     // features author it pre-qualified ("tenant:screen:members"), but the
@@ -117,7 +118,7 @@ function firstNavReachableScreenQn(features, acceptsScreen) {
 }
 // Only screens whose `access` excludes nobody: on an unprojected schema the
 // landing is picked without knowing the user's roles, so a role-restricted
-// screen would land every non-admin on access-denied (#1176).
+// screen would land every non-admin on access-denied.
 export function firstOpenScreenQn(features) {
     return firstNavReachableScreenQn(features, (s) => s.access === undefined || isOpenToAllGranted(s.access));
 }
@@ -177,15 +178,15 @@ export function mergeContentEditors(clientFeatures) {
 // declare a `type: "custom"` screen that's reachable directly by URL
 // even without nav placement — without this check, a missing client
 // plugin only surfaces as an error placeholder to whoever happens to
-// open that URL (kumiko-framework#2025). Screens flagged `dormant`
+// open that URL. Screens flagged `dormant`
 // (e.g. user-data-rights privacy-center, auth-mfa's enable screen) are
 // registered without a self-owned r.nav on purpose — an app opts in by
 // navving them explicitly, so a consumer that hasn't done that yet isn't
-// missing anything (kumiko-framework#2034). Still dev-only: several
+// missing anything. Still dev-only: several
 // bundled screens that ARE self-navved (e.g. compliance-profiles'
 // profile-picker) have real unmounted-client-plugin bugs in existing
-// consumer apps today (kumiko-framework#2025) — running this in
-// production before those are fixed (tracked via infra#503) would just
+// consumer apps today — running this in
+// production before those are fixed would just
 // spam every affected app's console.
 function warnMissingCustomScreens(app, customScreens) {
     if (typeof process === "undefined" || process.env.NODE_ENV === "production")
@@ -209,7 +210,7 @@ function KumikoAppRoot(props) {
     //   1. clientFeatures.translations — app overrides always win, even
     //      against the framework's own labels.
     //   2. schemaTranslations — server-authored r.translations, projected
-    //      verbatim by buildAppSchema (#1059). Without this bundle, nav/
+    //      verbatim by buildAppSchema. Without this bundle, nav/
     //      screen labels only resolve if an app ALSO duplicates them in its
     //      own web/i18n.ts — most bundled features never did, labels then
     //      render as raw i18n keys.
@@ -255,9 +256,13 @@ function AppSchemaBoundary({ app, screenQn, schemaUrl, navAdapter, onAppLoaded,
     onUnmountResetSchemaRef.current = onUnmountResetSchema;
     // A real unmount (the gate withdrawing children, e.g. on logout) resets
     // the schema so the next mount re-fetches instead of reusing this
-    // session's — fetch-mode only, see isFetchMode in KumikoAppRoot.
+    // session's — fetch-mode only, see isFetchMode in KumikoAppRoot. The file
+    // meta cache is dropped in every mode.
     useEffect(() => {
-        return () => onUnmountResetSchemaRef.current?.();
+        return () => {
+            clearFileMetaCache();
+            onUnmountResetSchemaRef.current?.();
+        };
     }, []);
     if (app === undefined) {
         return (_jsx(AppSchemaFetchBoot, { onLoaded: onAppLoaded, ...(schemaUrl !== undefined && { schemaUrl }) }));
@@ -388,7 +393,7 @@ function findEditScreenForEntity(features, entityName) {
     }
     return undefined;
 }
-// fw#2640: a list screen with no reachable click target (no `detailFor`
+// A list screen with no reachable click target (no `detailFor`
 // screen for its entity, no app-wide onRowClick, no entityEdit screen)
 // must render without the row-click affordance instead of a silent no-op —
 // mirrors the precedence effectiveOnRowClick itself resolves at click time.
@@ -426,7 +431,6 @@ function RoutedScreen({ app, fallbackQn, translate, onRowClick, }) {
             };
         }
         const shortId = nav.route.screenId;
-        // Suche das Feature dessen Screens den short id enthalten.
         let matchedFeature;
         for (const f of app.features) {
             if (f.screens.some((s) => s.id === shortId)) {
@@ -452,7 +456,7 @@ function RoutedScreen({ app, fallbackQn, translate, onRowClick, }) {
                 screenId: lastSegment(qn),
                 ...(entityId !== undefined && { entityId }),
             };
-            // Precedence (fw#2164): detailFor screen, then onRowClick, then the
+            // Precedence: detailFor screen, then onRowClick, then the
             // entityEdit-search fallback below. An explicit rowActions
             // rowClick:true already wins over all of this — kumiko-screen.tsx
             // handles it before onRowClick is ever called.
@@ -477,7 +481,7 @@ function RoutedScreen({ app, fallbackQn, translate, onRowClick, }) {
             }
         };
     }, [app, activeScreen, onRowClick, nav, qn, entityId]);
-    // Copy-link action (Issue #912) for entityEdit update screens. Builds
+    // Copy-link action for entityEdit update screens. Builds
     // the absolute permalink URL from the current route + copies it —
     // `navigator`/`window` are allowed here (renderer/web, not a
     // platform-neutral package). No button without entityId (create-mode).
@@ -499,7 +503,7 @@ function RoutedScreen({ app, fallbackQn, translate, onRowClick, }) {
     }, [nav]);
     if (feature === undefined || activeScreen === undefined) {
         const landingExists = findOwnerFeature(app.features, fallbackQn) !== undefined;
-        return (_jsx(ScreenMissingState, { ...(landingExists && { homeScreenId: lastSegment(fallbackQn) }), screenQn: qn }));
+        return (_jsx(ScreenMissingState, { ...(landingExists && { homeScreenId: lastSegment(fallbackQn) }), screenQn: nav.route?.screenId ?? qn }));
     }
     // KumikoScreen takes a single-feature schema: the feature owning the active screen.
     const schemaForScreen = feature;

package/dist/web/app/dashboard-body.js

@@ -140,6 +140,20 @@ function useVisibilityGateResults() {
     }, []);
     return { results, report, forget };
 }
+const NOOP_REFETCH = async () => { };
+// A gate reports through an effect, so for its first commit (and after a payload change) no
+// result exists yet; without a placeholder that reads as "hidden" and flashes the fallback.
+function withPendingGates(results, gateKeys) {
+    if (gateKeys.every((key) => results.has(key)))
+        return results;
+    const merged = new Map(results);
+    for (const key of gateKeys) {
+        if (!merged.has(key)) {
+            merged.set(key, { data: null, error: null, loading: true, refetch: NOOP_REFETCH });
+        }
+    }
+    return merged;
+}
 function distinctVisibilityGates(panels, screenParams) {
     const gates = new Map();
     for (const panel of panels) {
@@ -227,6 +241,8 @@ export function WebDashboardBody({ featureName, screen, translate, }) {
     const { loadedAtMs, reportLoaded } = useLoadedAt(screenParams);
     const visibilityGates = distinctVisibilityGates(screen.panels, screenParams);
     const gateResults = useVisibilityGateResults();
+    const gateKeysSignature = visibilityGates.map((gate) => gate.key).join("\n");
+    const gateResultsWithPending = useMemo(() => withPendingGates(gateResults.results, gateKeysSignature === "" ? [] : gateKeysSignature.split("\n")), [gateResults.results, gateKeysSignature]);
     // The record query is not a panel query: it needs the interval before the
     // registry context below exists, and `refresh.field` reads from its own row.
     const [refreshIntervalMs, setRefreshIntervalMs] = useState(() => resolveRefreshIntervalMs(screen.refresh, null));
@@ -271,7 +287,7 @@ export function WebDashboardBody({ featureName, screen, translate, }) {
     // The shell header owns the title; the badge and the actions sit in it there.
     const badgeInHeader = scopeBadge !== null && usesPageHeaderSlot;
     const showPageHeader = usesPageHeaderSlot && (badgeInHeader || recordTitle !== undefined || headerActionsBar !== null);
-    return (_jsx(PanelLoadedContext.Provider, { value: reportLoaded, children: _jsx(DashboardQueryContext.Provider, { value: queryRuntime, children: _jsxs(PageSection, { className: "flex flex-col gap-4", testId: `dashboard-${screen.id}`, children: [showPageHeader && (_jsx(PageHeader, { ...(recordTitle !== undefined && { title: recordTitle }), ...(badgeInHeader && { status: scopeBadge }), ...(headerActionsBar !== null && { actions: headerActionsBar }) })), _jsxs("div", { className: "flex flex-wrap items-end justify-between gap-3", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2", children: [!usesPageHeaderSlot && recordTitle !== undefined && (_jsx(Heading, { variant: "page", testId: `dashboard-${screen.id}-record-title`, children: recordTitle })), !badgeInHeader && scopeBadge, picker] }), _jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [!usesPageHeaderSlot && headerActionsBar, screen.showUpdatedAt !== false && (_jsx("span", { "data-testid": `dashboard-${screen.id}-updated-at`, className: "text-xs tabular-nums text-muted-foreground", children: t("kumiko.dashboard.updated-at", { time: formatDateTime(loadedAtMs) }) })), rangeControl] })] }), actionError !== null && (_jsxs(Banner, { variant: "error", testId: "render-edit-action-error", children: [actionError.message, _jsx(ErrorReference, { requestId: actionError.requestId })] })), recordQuery.error !== null && recordRow === null && (_jsxs("div", { role: "alert", "data-testid": `dashboard-${screen.id}-record-error`, className: "flex flex-col items-start gap-2 text-sm", children: [_jsx("span", { className: "text-status-bad", children: dispatcherErrorText(recordQuery.error, t) }), _jsx(Button, { variant: "secondary", onClick: () => void refetchRecord(), children: t("kumiko.dashboard.panel.error.retry") })] })), description !== undefined && (_jsx(Text, { variant: "muted", testId: `dashboard-${screen.id}-description`, children: description })), scope?.notice !== undefined && (_jsx(Banner, { variant: "info", testId: `dashboard-${screen.id}-scope-notice`, children: effectiveTranslate(scope.notice) })), _jsxs(VisibilityQueryContext.Provider, { value: gateResults.results, children: [_jsx(VisibilityGateQueries, { gates: visibilityGates, onResult: gateResults.report, onForget: gateResults.forget }), _jsx("div", { className: "grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4", children: screen.panels.map((panel) => {
+    return (_jsx(PanelLoadedContext.Provider, { value: reportLoaded, children: _jsx(DashboardQueryContext.Provider, { value: queryRuntime, children: _jsxs(PageSection, { className: "flex flex-col gap-4", testId: `dashboard-${screen.id}`, children: [showPageHeader && (_jsx(PageHeader, { ...(recordTitle !== undefined && { title: recordTitle }), ...(badgeInHeader && { status: scopeBadge }), ...(headerActionsBar !== null && { actions: headerActionsBar }) })), _jsxs("div", { className: "flex flex-wrap items-end justify-between gap-3", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2", children: [!usesPageHeaderSlot && recordTitle !== undefined && (_jsx(Heading, { variant: "page", testId: `dashboard-${screen.id}-record-title`, children: recordTitle })), !badgeInHeader && scopeBadge, picker] }), _jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [!usesPageHeaderSlot && headerActionsBar, screen.showUpdatedAt !== false && (_jsx("span", { "data-testid": `dashboard-${screen.id}-updated-at`, className: "text-xs tabular-nums text-muted-foreground", children: t("kumiko.dashboard.updated-at", { time: formatDateTime(loadedAtMs) }) })), rangeControl] })] }), actionError !== null && (_jsxs(Banner, { variant: "error", testId: "render-edit-action-error", children: [actionError.message, _jsx(ErrorReference, { requestId: actionError.requestId })] })), recordQuery.error !== null && recordRow === null && (_jsxs("div", { role: "alert", "data-testid": `dashboard-${screen.id}-record-error`, className: "flex flex-col items-start gap-2 text-sm", children: [_jsx("span", { className: "text-status-bad", children: dispatcherErrorText(recordQuery.error, t) }), _jsx(Button, { variant: "secondary", onClick: () => void refetchRecord(), children: t("kumiko.dashboard.panel.error.retry") })] })), description !== undefined && (_jsx(Text, { variant: "muted", testId: `dashboard-${screen.id}-description`, children: description })), scope?.notice !== undefined && (_jsx(Banner, { variant: "info", testId: `dashboard-${screen.id}-scope-notice`, children: effectiveTranslate(scope.notice) })), _jsxs(VisibilityQueryContext.Provider, { value: gateResultsWithPending, children: [_jsx(VisibilityGateQueries, { gates: visibilityGates, onResult: gateResults.report, onForget: gateResults.forget }), _jsx("div", { className: "grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4", children: screen.panels.map((panel) => {
                                     if (panel.kind === "screen") {
                                         return (_jsx(ScreenPanelTile, { panel: panel, featureName: featureName, translate: effectiveTranslate }, panel.id));
                                     }

package/dist/web/app/dashboard-panels.js

@@ -311,7 +311,7 @@ function TextBlockView({ block, translate, }) {
                     ? "text-sm font-medium text-foreground"
                     : "text-sm text-muted-foreground", children: translate(block.text) }));
         case "list":
-            return (_jsx("ul", { "data-block": "list", className: "list-disc space-y-1 pl-5 text-sm text-muted-foreground", children: block.items.map((item) => (_jsx("li", { children: translate(item) }, item))) }));
+            return (_jsx("ul", { "data-block": "list", className: "list-disc space-y-1 pl-5 text-sm text-muted-foreground", children: withOccurrenceKeys(block.items, (item) => item).map(({ entry, key }) => (_jsx("li", { children: translate(entry) }, key))) }));
         case "code":
             return (_jsx("pre", { "data-block": "code", className: "overflow-x-auto rounded-md bg-muted p-3 text-xs", children: _jsx("code", { children: block.code }) }));
         case "hint":
@@ -330,6 +330,16 @@ function TextBlockLink({ block, translate, }) {
     const target = { screenId: lastSegment(block.screen) };
     return (_jsx(Link, { href: nav.hrefFor(target), onPress: () => nav.navigate(target), testId: `dashboard-text-link-${target.screenId}`, children: translate(block.text) }));
 }
+// Content-derived keys collide for identical entries; the occurrence count keeps them unique.
+function withOccurrenceKeys(entries, contentKey) {
+    const seen = new Map();
+    return entries.map((entry) => {
+        const content = contentKey(entry);
+        const occurrence = seen.get(content) ?? 0;
+        seen.set(content, occurrence + 1);
+        return { entry, key: `${content}#${occurrence}` };
+    });
+}
 function textBlockKey(block) {
     switch (block.kind) {
         case "list":
@@ -341,7 +351,7 @@ function textBlockKey(block) {
     }
 }
 export function TextPanelBody({ panel, label, translate, }) {
-    const blocks = (_jsx("div", { className: "flex flex-col gap-3", children: panel.blocks.map((block) => (_jsx(TextBlockView, { block: block, translate: translate }, textBlockKey(block)))) }));
+    const blocks = (_jsx("div", { className: "flex flex-col gap-3", children: withOccurrenceKeys(panel.blocks, textBlockKey).map(({ entry, key }) => (_jsx(TextBlockView, { block: entry, translate: translate }, key))) }));
     const testId = `dashboard-panel-${panel.id}`;
     if (label !== undefined) {
         return (_jsx(PanelShell, { testId: testId, title: label, children: blocks }));

package/dist/web/app/document-lang-sync.js

@@ -13,7 +13,7 @@ import { useEffect } from "react";
 function syncDocumentLocale(locale) {
     document.documentElement.lang = locale;
     // Dedicated marker for dispatcher-live — static <html lang> must not
-    // look like an active UI locale (kumiko-framework#2334).
+    // look like an active UI locale.
     document.documentElement.dataset["kumikoLocale"] = locale;
 }
 export function DocumentLangSync({ resolver }) {

package/dist/web/app/draft-storage.js

@@ -1,4 +1,4 @@
-// Browser-backed DraftStorage default for createKumikoApp (issue #1913).
+// Browser-backed DraftStorage default for createKumikoApp.
 //
 // Persists a create-mode draftId per screen in `sessionStorage` — same-tab
 // scope only (deliberately, unlike browser-locale.ts's localStorage): the

package/dist/web/app/nav-providers-context.d.ts

@@ -6,8 +6,8 @@ export type NavProvidersProviderProps = {
     readonly children: ReactNode;
 };
 export declare function NavProvidersProvider({ value, entities, children, }: NavProvidersProviderProps): ReactNode;
-/** Provider-Map keyed auf Nav-QN. Empty-Map-Default → kein Crash ohne
- *  registrierte Provider. */
+/** Provider map keyed by Nav-QN. The empty-map default prevents crashes when
+ *  no providers are registered. */
 export declare function useNavProviders(): ReadonlyMap<string, TreeChildrenSubscribe>;
-/** SSE-Entity-Liste pro Provider-QN für Live-Refresh. Empty-Map-Default. */
+/** SSE entity list for each provider QN, used for live refresh. Empty-map default. */
 export declare function useNavEntities(): ReadonlyMap<string, readonly string[]>;

package/dist/web/app/nav-providers-context.js

@@ -7,12 +7,12 @@ const NavEntitiesContext = createContext(EMPTY_ENTITIES);
 export function NavProvidersProvider({ value, entities, children, }) {
     return (_jsx(NavProvidersContext.Provider, { value: value, children: _jsx(NavEntitiesContext.Provider, { value: entities ?? EMPTY_ENTITIES, children: children }) }));
 }
-/** Provider-Map keyed auf Nav-QN. Empty-Map-Default → kein Crash ohne
- *  registrierte Provider. */
+/** Provider map keyed by Nav-QN. The empty-map default prevents crashes when
+ *  no providers are registered. */
 export function useNavProviders() {
     return useContext(NavProvidersContext);
 }
-/** SSE-Entity-Liste pro Provider-QN für Live-Refresh. Empty-Map-Default. */
+/** SSE entity list for each provider QN, used for live refresh. Empty-map default. */
 export function useNavEntities() {
     return useContext(NavEntitiesContext);
 }

package/dist/web/app/nav.d.ts

@@ -1,31 +1,32 @@
 import { type AnchorHTMLAttributes, type ReactNode } from "react";
 import { type FeatureSchema, type NavApi, type NavTarget } from "../../index.ts";
-/** React-Hook der eine NavApi aus der Browser-History baut. Sollte
- *  einmal im App-Root aufgerufen und als value an den shared
- *  `<NavProvider>` durchgereicht werden — createKumikoApp tut das.
+/** React hook that builds a NavApi from browser history. It should be
+ *  called once at the app root and passed as the value to the shared
+ *  `<NavProvider>`—createKumikoApp does this.
  *
- *  hasWorkspaces aus dem Schema (schema.workspaces non-empty) entscheidet,
- *  ob das erste URL-Segment als Workspace-id parsed wird. Pure Pass-
- *  through an parsePath; formatPath checkt selbst auf target.workspaceId.
+ *  Whether the schema has workspaces (schema.workspaces is non-empty) determines
+ *  whether the first URL segment is parsed as a workspace ID. This is a pure
+ *  pass-through to parsePath; formatPath checks target.workspaceId itself.
  *
- *  basePath mounted die App unter einem URL-Prefix (z.B. "/admin"). Read-
- *  Pfad strippt vor parsePath, Write-Pfad prepend'd vor pushState/href.
- *  URLs außerhalb des basePath liefern route=undefined, ohne Auto-Redirect.
+ *  basePath mounts the app under a URL prefix (for example, "/admin"). The read
+ *  path strips it before parsePath, and the write path prepends it before
+ *  pushState/href. URLs outside basePath produce route=undefined without an
+ *  automatic redirect.
  *
- *  Achtung — Ambiguität bei route=undefined mit basePath:
- *  Sowohl die App-Root (URL === basePath, z.B. "/admin") als auch URLs
- *  außerhalb des basePath (z.B. "/marketing") liefern route=undefined. Eine
- *  App die zwischen "render Default-Screen" und "render Not-Found"
- *  unterscheiden muss, muss zusätzlich `window.location.pathname` prüfen:
+ *  Note the ambiguity of route=undefined with basePath:
+ *  Both the app root (URL === basePath, for example, "/admin") and URLs
+ *  outside basePath (for example, "/marketing") produce route=undefined. An
+ *  app that must distinguish between "render Default-Screen" and "render
+ *  Not-Found" must also inspect `window.location.pathname`:
  *
  *    if (window.location.pathname.startsWith("/admin")) {
- *      // in-app, aber an der Root → Default-Screen
+ *      // in-app, but at the root → Default-Screen
  *    } else {
  *      // out-of-app → Not-Found / Marketing-Layer
  *    }
  *
- *  Im non-basePath-Modus ergibt sich diese Ambiguität nicht — out-of-app
- *  ist dort kein Konzept. */
+ *  In non-basePath mode, this ambiguity does not arise—out-of-app is not a
+ *  concept there. */
 export declare function useBrowserNavApi(options?: {
     readonly hasWorkspaces?: boolean;
     readonly basePath?: string;

package/dist/web/app/nav.js

@@ -1,36 +1,37 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// Browser-Impl der Navigation: HTML5-History + popstate subscribe.
-// Types + Context + useNav leben im shared `@cosmicdrift/kumiko-renderer`; dieser
-// File liefert nur die Web-spezifische NavApi-Instanz und die
-// `<KumikoLink>` Anchor-Komponente.
+// Browser navigation implementation: HTML5 History + popstate subscription.
+// Types, Context, and useNav live in the shared `@cosmicdrift/kumiko-renderer`; this
+// file provides only the web-specific NavApi instance and the
+// `<KumikoLink>` anchor component.
 //
-// Bewusst KEIN createStore: Source-of-truth ist `window.location.pathname`
-// (extern, kann via replaceState außerhalb unserer Kontrolle wechseln).
-// Ein Store wäre entweder eine zweite Wahrheit (Drift-Risiko) oder ein
-// reiner Tick-Counter (Anti-Pattern — createStore ist State-Holder, kein
-// Event-Bus). Hand-rolled Listener-Set ist hier idiomatisch: zwei
-// Notify-Trigger (eigenes pushPath, popstate-Event), nicht generalisierbar.
+// Deliberately no createStore: the source of truth is `window.location.pathname`
+// (external and able to change through replaceState outside our control).
+// A store would either be a second source of truth (risking drift) or a
+// tick counter (an anti-pattern—createStore is a state holder, not an
+// event bus). A hand-rolled listener set is appropriate here: there are two
+// notification triggers (our pushPath and the popstate event), so this is not
+// generalizable.
 import { useCallback, useMemo, useSyncExternalStore, } from "react";
 import { formatPath, hasUnsavedInput, parsePath, requestLeave, resolveTarget, useNav, } from "../../index.js";
-// basePath erlaubt es, die App unter einem URL-Prefix zu mounten
-// (z.B. `/admin`). Read-Pfad strippt den Prefix vor dem parsePath,
-// Write-Pfad prepend'd ihn vor dem pushState/replaceState/href.
+// basePath allows the app to be mounted under a URL prefix
+// (for example, `/admin`). The read path strips the prefix before parsePath;
+// the write path prepends it before pushState/replaceState/href.
 //
-// Wenn die URL nicht im basePath liegt (z.B. /marketing/foo bei
-// basePath="/admin"), liefert stripBasePath `undefined` — useBrowserNavApi
-// gibt dann route=undefined zurück, die App rendert ihren "outside"-State
-// (Not-Found, Marketing-Layer, Server-Routing-Pickup, …). Es gibt KEIN
-// Auto-Redirect zur App-Root — die Host-App entscheidet selbst.
+// If the URL is not under basePath (for example, /marketing/foo with
+// basePath="/admin"), stripBasePath returns `undefined`—useBrowserNavApi then
+// returns route=undefined, and the app renders its "outside" state
+// (Not-Found, marketing layer, server-routing pickup, …). There is no
+// automatic redirect to the app root—the host app decides.
 function normalizeBasePath(raw) {
     if (raw === undefined || raw === "" || raw === "/")
         return "";
     const withLeading = raw.startsWith("/") ? raw : `/${raw}`;
     return withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
 }
-// Returns the in-app path (basePath-relativ) wenn `path` im basePath liegt,
-// sonst `undefined`. Strict-segment-Boundary: "/administrator" matcht
-// nicht "/admin" — sonst würde der Prefix-Check auf String-Ebene falsche
-// Treffer liefern.
+// Returns the in-app (basePath-relative) path when `path` is under basePath;
+// otherwise returns `undefined`. The segment boundary is strict: "/administrator"
+// does not match "/admin"—otherwise a string-level prefix check would produce
+// false matches.
 function stripBasePath(path, basePath) {
     if (basePath === "")
         return path;
@@ -43,15 +44,15 @@ function stripBasePath(path, basePath) {
 function prependBasePath(path, basePath) {
     if (basePath === "")
         return path;
-    // formatPath liefert immer absoluten in-app-Pfad: "/" oder "/screen-id"
-    // oder "/screen-id/entity-id". "/" → einfach basePath, sonst concat.
+    // formatPath always returns an absolute in-app path: "/" or "/screen-id"
+    // or "/screen-id/entity-id". "/" becomes basePath; otherwise, concatenate.
     if (path === "/" || path === "")
         return basePath;
     return `${basePath}${path}`;
 }
-// pushState feuert keinen popstate — wir halten einen eigenen
-// Listener-Set, den navigate() notifiziert. popstate (Back/Forward)
-// läuft über einen window-Listener, den wir einmalig verdrahten.
+// pushState does not fire popstate, so we maintain a listener set that
+// navigate() notifies. Back/Forward navigation goes through a window listener
+// wired exactly once.
 const listeners = new Set();
 let popstateWired = false;
 // URL the app currently shows; popstate has already moved the browser to the
@@ -107,11 +108,11 @@ function subscribe(listener) {
 function readPath() {
     return typeof window !== "undefined" ? window.location.pathname : "/";
 }
-// Read der aktuellen ?key=value-Pairs als Plain-Record. URLSearchParams-
-// Iterator gibt String/String — wir kollabieren auf "letzter Wert
-// gewinnt" wenn ein Key mehrfach im Query auftaucht (`?a=1&a=2` → "2").
-// Multi-Value-Lists sind kein Use-Case in Kumiko-Filter-State; explizit
-// dokumentieren statt unspezifizierten Behavior zu liefern.
+// Reads the current ?key=value pairs as a plain record. URLSearchParams-
+// iterator yields String/String; when a key occurs more than once, the last
+// value wins (`?a=1&a=2` → "2").
+// Multi-value lists are not supported in Kumiko filter state; documenting this
+// explicitly is preferable to providing unspecified behavior.
 function readSearch() {
     return typeof window !== "undefined" ? window.location.search : "";
 }
@@ -124,10 +125,10 @@ function parseSearchParams(search) {
         out[k] = v;
     return out;
 }
-// Mergt updates in den aktuellen ?-String. `null` löscht, sonst
-// überschreibt. Verwendet replaceState (KEIN push) — Sort/Filter-Toggles
-// flutten sonst die Back-Navigation und User clicked sich durch
-// dutzende Zwischen-States um zur vorherigen Seite zu kommen.
+// Merges updates into the current query string. `null` deletes a key; other
+// values overwrite it. Uses replaceState rather than pushState—otherwise
+// sort/filter toggles would flood Back navigation, forcing users through
+// dozens of intermediate states to reach the previous page.
 function applySearchParamUpdates(updates) {
     if (typeof window === "undefined")
         return;
@@ -194,38 +195,39 @@ function replacePath(path, search) {
     else
         apply();
 }
-/** React-Hook der eine NavApi aus der Browser-History baut. Sollte
- *  einmal im App-Root aufgerufen und als value an den shared
- *  `<NavProvider>` durchgereicht werden — createKumikoApp tut das.
+/** React hook that builds a NavApi from browser history. It should be
+ *  called once at the app root and passed as the value to the shared
+ *  `<NavProvider>`—createKumikoApp does this.
  *
- *  hasWorkspaces aus dem Schema (schema.workspaces non-empty) entscheidet,
- *  ob das erste URL-Segment als Workspace-id parsed wird. Pure Pass-
- *  through an parsePath; formatPath checkt selbst auf target.workspaceId.
+ *  Whether the schema has workspaces (schema.workspaces is non-empty) determines
+ *  whether the first URL segment is parsed as a workspace ID. This is a pure
+ *  pass-through to parsePath; formatPath checks target.workspaceId itself.
  *
- *  basePath mounted die App unter einem URL-Prefix (z.B. "/admin"). Read-
- *  Pfad strippt vor parsePath, Write-Pfad prepend'd vor pushState/href.
- *  URLs außerhalb des basePath liefern route=undefined, ohne Auto-Redirect.
+ *  basePath mounts the app under a URL prefix (for example, "/admin"). The read
+ *  path strips it before parsePath, and the write path prepends it before
+ *  pushState/href. URLs outside basePath produce route=undefined without an
+ *  automatic redirect.
  *
- *  Achtung — Ambiguität bei route=undefined mit basePath:
- *  Sowohl die App-Root (URL === basePath, z.B. "/admin") als auch URLs
- *  außerhalb des basePath (z.B. "/marketing") liefern route=undefined. Eine
- *  App die zwischen "render Default-Screen" und "render Not-Found"
- *  unterscheiden muss, muss zusätzlich `window.location.pathname` prüfen:
+ *  Note the ambiguity of route=undefined with basePath:
+ *  Both the app root (URL === basePath, for example, "/admin") and URLs
+ *  outside basePath (for example, "/marketing") produce route=undefined. An
+ *  app that must distinguish between "render Default-Screen" and "render
+ *  Not-Found" must also inspect `window.location.pathname`:
  *
  *    if (window.location.pathname.startsWith("/admin")) {
- *      // in-app, aber an der Root → Default-Screen
+ *      // in-app, but at the root → Default-Screen
  *    } else {
  *      // out-of-app → Not-Found / Marketing-Layer
  *    }
  *
- *  Im non-basePath-Modus ergibt sich diese Ambiguität nicht — out-of-app
- *  ist dort kein Konzept. */
+ *  In non-basePath mode, this ambiguity does not arise—out-of-app is not a
+ *  concept there. */
 export function useBrowserNavApi(options) {
     const path = useSyncExternalStore(subscribe, readPath, () => "/");
-    // Search wird über denselben Listener-Set notifiziert (popstate +
-    // unsere replaceState-Calls), also reichen wir denselben subscribe
-    // durch. Beide Snapshots werden zusammen recomputed — kein Drift
-    // zwischen Pfad und Query.
+    // Search is notified through the same listener set (popstate +
+    // our replaceState calls), so we reuse the same subscribe function.
+    // Both snapshots are recomputed together, preventing drift
+    // between the path and query.
     const search = useSyncExternalStore(subscribe, readSearch, () => "");
     const hasWorkspaces = options?.hasWorkspaces === true;
     const basePath = useMemo(() => normalizeBasePath(options?.basePath), [options?.basePath]);
@@ -234,11 +236,11 @@ export function useBrowserNavApi(options) {
     const features = options?.features ?? NO_FEATURES;
     return useMemo(() => {
         const route = inAppPath === undefined ? undefined : parsePath(inAppPath, hasWorkspaces);
-        // NavTarget-Contract: workspaceId weglassen = aktueller Workspace
-        // bleibt. formatPath kennt die aktuelle Route nicht — ohne Injection
-        // landet `/screen-id` in parsePath(hasWorkspaces) als workspaceId,
-        // WorkspaceShell sieht einen unbekannten Workspace und revertet
-        // sofort auf den Default-Screen ("Klick tut nichts"-Prod-Bug).
+        // NavTarget contract: omitting workspaceId preserves the current workspace.
+        // formatPath does not know the current route, so without this injection
+        // `/screen-id` is parsed as a workspaceId by parsePath(hasWorkspaces),
+        // causing WorkspaceShell to see an unknown workspace and immediately
+        // revert to the default screen (a production bug where "click does nothing").
         const inCurrentWorkspace = (target) => hasWorkspaces && target.workspaceId === undefined && route?.workspaceId !== undefined
             ? { ...target, workspaceId: route.workspaceId }
             : target;
@@ -262,8 +264,8 @@ export function KumikoLink({ to, onClick, children, ...rest }) {
         onClick?.(e);
         if (e.defaultPrevented)
             return;
-        // Standard-Browser-Verhalten für Cmd/Ctrl/Shift/Alt + Middle-Click
-        // erhalten — nur der plain-left-click landet bei navigate().
+        // Preserve standard browser behavior for Cmd/Ctrl/Shift/Alt + middle-click;
+        // only a plain left click is handled by navigate().
         if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
             return;
         e.preventDefault();

package/dist/web/app/rich-content-editor.js

@@ -6,7 +6,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 // crosses this boundary. tiptap itself is dynamic-imported (TiptapEditor
 // lives in ./tiptap-editor) so an app that never mounts a "rich" collection
 // never pays for it; the fallback while the chunk loads is the same plain
-// textarea #1794 uses for a missing editor, never a blank panel.
+// textarea uses for a missing editor, never a blank panel.
 import { lazy, Suspense } from "react";
 import { TextareaContentEditor } from "../../index.js";
 const TiptapEditor = lazy(() => import("./tiptap-editor.js"));