@cosmicdrift/kumiko-renderer 0.373.0 → 0.377.0

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

@@ -0,0 +1,498 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isOpenToAllGranted } from "@cosmicdrift/kumiko-framework/ui-types";
+import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { createRoot } from "react-dom/client";
+import { AppFeaturesProvider, ClientActionsProvider, ColumnRenderersProvider, ContentEditorsProvider, CustomScreensProvider, createSessionEndedSignal, DashboardBodyProvider, DispatcherProvider, DraftStorageProvider, ErrorBoundary, ExtensionSectionsProvider, hasDetailScreen, KumikoScreen, kumikoDefaultTranslations, 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 { defaultPrimitives, ScreenWidthProvider } from "../primitives/index.js";
+import { ToastProvider } from "../primitives/toast.js";
+import { createEventSourceLiveEvents } from "../sse/live-events.js";
+import { useBrowserTokensApi } from "../tokens.js";
+import { UpdateChecker } from "../version/update-checker.js";
+import { AppSchemaFetchBoot } from "./app-schema-boot.js";
+import { createBrowserLocaleResolver } from "./browser-locale.js";
+import { stackWrappers } from "./client-plugin.js";
+import { WebDashboardBody } from "./dashboard-body.js";
+import { DocumentLangSync } from "./document-lang-sync.js";
+import { createBrowserDraftStorage } from "./draft-storage.js";
+import { useBrowserNavApi } from "./nav.js";
+import { NavProvidersProvider } from "./nav-providers-context.js";
+import { ResolversProvider } from "./resolvers-context.js";
+import { RootErrorFallback } from "./root-error-fallback.js";
+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.
+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.
+//
+// Schema-derived providers (r.contentCollection) run first and hold the weaker
+// claim on a QN — an explicitly registered navProvider overrides them without
+// comment. Only two EXPLICIT registrations on the same QN are the conflict
+// that deserves the warning.
+export function buildNavProviderMaps(clientFeatures, collections) {
+    const navProviders = new Map();
+    const navEntities = new Map();
+    const derivedQns = new Set();
+    for (const f of clientFeatures) {
+        if (f.navProvidersFromCollections === undefined)
+            continue;
+        const derived = f.navProvidersFromCollections(collections);
+        for (const [qn, provider] of Object.entries(derived.providers)) {
+            navProviders.set(qn, provider);
+            derivedQns.add(qn);
+        }
+        for (const [qn, entities] of Object.entries(derived.entities ?? {})) {
+            if (entities.length > 0)
+                navEntities.set(qn, entities);
+        }
+    }
+    for (const f of clientFeatures) {
+        for (const [navId, provider] of Object.entries(f.navProviders ?? {})) {
+            const qn = qualifyNavProviderKey(f.name, navId);
+            if (navProviders.has(qn) && !derivedQns.delete(qn)) {
+                // biome-ignore lint/suspicious/noConsole: dev warning for schema conflicts
+                console.warn(`[kumiko] navProvider for "${qn}" defined by multiple clientFeatures — last wins.`);
+            }
+            navProviders.set(qn, provider);
+        }
+        for (const [navId, entities] of Object.entries(f.navEntities ?? {})) {
+            if (entities.length > 0)
+                navEntities.set(qualifyNavProviderKey(f.name, navId), entities);
+        }
+    }
+    return { navProviders, navEntities };
+}
+const BoundaryErrorHandlerContext = createContext(undefined);
+// Reads a schema an app baked into the page itself (e.g. an e2e fixture) —
+// nothing in this repo sets this global anymore now that HTML never carries
+// an injected schema. Guarded for SSR/node even though this only runs in
+// the browser today; harmless under jsdom either way.
+function readInjectedSchema() {
+    if (typeof window === "undefined")
+        return undefined;
+    const w = window;
+    return w.__KUMIKO_SCHEMA__;
+}
+// Nav reachability is required, otherwise a dormant `type: "custom"`
+// 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).
+function firstNavReachableScreenQn(features, acceptsScreen) {
+    // NavDefinition.screen carries two shapes in practice: most bundled
+    // features author it pre-qualified ("tenant:screen:members"), but the
+    // config settings-hub generator emits the bare short id. Index both
+    // forms so nav-reachability doesn't depend on which convention a given
+    // feature happens to use.
+    const navScreenQns = new Set();
+    for (const f of features) {
+        for (const n of f.navs ?? []) {
+            if (n.screen === undefined)
+                continue;
+            navScreenQns.add(n.screen);
+            navScreenQns.add(qualifyScreenId(f.featureName, n.screen));
+        }
+    }
+    for (const feature of features) {
+        const screen = feature.screens.find((s) => acceptsScreen(s) && navScreenQns.has(qualifyScreenId(feature.featureName, s.id)));
+        if (screen !== undefined)
+            return qualifyScreenId(feature.featureName, screen.id);
+    }
+    return undefined;
+}
+// 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).
+export function firstOpenScreenQn(features) {
+    return firstNavReachableScreenQn(features, (s) => s.access === undefined || isOpenToAllGranted(s.access));
+}
+// Landing fallback for a schema that arrived already role-projected by the
+// server (fetch mode, GET /api/schema strips screens the caller's roles
+// can't see) — a pure SystemAdmin whose only screens are role-restricted
+// must still get a landing instead of the "no-open-screen" banner.
+// Regular users keep today's
+// firstOpenScreenQn landing; only when that yields nothing do we fall back
+// to any nav-reachable screen, since the projection already removed
+// everything the caller's roles may not see.
+export function firstLandingScreenQnForProjectedSchema(features) {
+    return firstOpenScreenQn(features) ?? firstNavReachableScreenQn(features, () => true);
+}
+// The server's role projection may strip an explicitly configured screenQn
+// for this caller's roles; the root route then falls back to the first
+// reachable landing instead of "Screen not found". An unprojected schema
+// keeps the explicit screen as configured.
+export function resolveRootScreenQn(features, explicitScreenQn, schemaIsRoleProjected) {
+    if (explicitScreenQn === undefined) {
+        return schemaIsRoleProjected
+            ? firstLandingScreenQnForProjectedSchema(features)
+            : firstOpenScreenQn(features);
+    }
+    if (!schemaIsRoleProjected)
+        return explicitScreenQn;
+    if (findOwnerFeature(features, explicitScreenQn) !== undefined)
+        return explicitScreenQn;
+    return firstLandingScreenQnForProjectedSchema(features);
+}
+// Last-wins merge for a clientFeature-contributed map (contentEditors,
+// columnRenderers, extensionSectionComponents, ...): later features in
+// `clientFeatures` override earlier ones on key collision, logging once
+// per collision so an accidental override isn't silent.
+function mergeByKey(clientFeatures, pick, label) {
+    const merged = {};
+    for (const f of clientFeatures) {
+        const entries = pick(f);
+        if (entries === undefined)
+            continue;
+        for (const [key, value] of Object.entries(entries)) {
+            if (merged[key] !== undefined) {
+                // biome-ignore lint/suspicious/noConsole: dev warning for schema conflicts
+                console.warn(`[kumiko] ${label} "${key}" defined by multiple clientFeatures — last definition (from "${f.name}") wins.`);
+            }
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+// Merges the content-editor map — same last-wins semantics as
+// columnRenderers. No entry for a contentFormat → useContentEditor falls
+// back to the textarea on its own, no warning needed.
+export function mergeContentEditors(clientFeatures) {
+    return mergeByKey(clientFeatures, (f) => f.contentEditors, "contentEditor");
+}
+// Fail loud at boot instead of per-URL: a mounted server feature can
+// 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`
+// (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
+// 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
+// spam every affected app's console.
+function warnMissingCustomScreens(app, customScreens) {
+    if (typeof process === "undefined" || process.env.NODE_ENV === "production")
+        return;
+    const missingCustomScreens = app.features.flatMap((f) => f.screens
+        .filter((s) => s.type === "custom" && s.dormant !== true && customScreens[s.id] === undefined)
+        .map((s) => `${f.featureName}:${s.id}`));
+    if (missingCustomScreens.length > 0) {
+        // biome-ignore lint/suspicious/noConsole: dev-only diagnostic for missing client plugins
+        console.error(`[kumiko] ${missingCustomScreens.length} custom screen(s) have no registered component in clientFeatures.components — they render an error placeholder instead of the intended UI: ${missingCustomScreens.join(", ")}. Add the feature's web client plugin to clientFeatures.`);
+    }
+}
+// Everything schema-INdependent (dispatcher, providers, gates, merged
+// component maps, ...) is built once in createKumikoApp and passed in as
+// props; only the schema-dependent slice (fallbackBundles, nav-provider
+// derivation, the actual screen tree) lives in this component's own state
+// so a schema arriving later (the fetch path) doesn't need a second copy
+// of the provider tree.
+function KumikoAppRoot(props) {
+    const [app, setApp] = useState(props.initialApp);
+    // Precedence in fallbackBundles (array order = priority, highest first):
+    //   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/
+    //      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.
+    //   3. kumikoDefaultTranslations — framework defaults, the very last
+    //      fallback.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: props.clientFeatures is stable for the app instance's lifetime (built once in createKumikoApp)
+    const { fallbackBundles, navProviders, navEntities } = useMemo(() => {
+        const schemaTranslations = (app?.features ?? EMPTY_FEATURES).reduce((acc, f) => f.translations ? mergeTranslations(acc, translationsByLocaleFromKeys(f.translations)) : acc, {});
+        const bundles = [
+            ...props.clientFeatures.flatMap((f) => f.translations !== undefined ? [f.translations] : []),
+            schemaTranslations,
+            kumikoDefaultTranslations,
+        ];
+        const { navProviders: providersByQn, navEntities: entitiesByQn } = buildNavProviderMaps(props.clientFeatures, app?.features.flatMap((f) => f.contentCollections ?? []) ?? EMPTY_COLLECTIONS);
+        return { fallbackBundles: bundles, navProviders: providersByQn, navEntities: entitiesByQn };
+    }, [app]);
+    // Sync path (initialApp given at construction) never resets — that
+    // schema was handed in explicitly and stays valid for the app's
+    // lifetime. Fetch path resets to undefined on unmount so a future
+    // role-aware schema projection never lets a re-login reuse a
+    // previous user's cached app.
+    const isFetchMode = props.initialApp === undefined;
+    const screenNode = (_jsx(AppSchemaBoundary, { app: app, screenQn: props.screenQn, ...(props.schemaUrl !== undefined && { schemaUrl: props.schemaUrl }), navAdapter: props.navAdapter, onAppLoaded: (loaded) => {
+            warnMissingCustomScreens(loaded, props.customScreens);
+            setApp(loaded);
+        }, schemaIsRoleProjected: isFetchMode, ...(isFetchMode && { onUnmountResetSchema: () => setApp(undefined) }), ...(props.translate !== undefined && { translate: props.translate }), ...(props.onRowClick !== undefined && { onRowClick: props.onRowClick }), ...(props.shell !== undefined && { shell: props.shell }) }));
+    return (_jsx(TokensBoot, { children: _jsxs(LocaleProvider, { resolver: props.localeResolver, fallbackBundles: fallbackBundles, children: [_jsx(DocumentLangSync, { resolver: props.localeResolver }), _jsx(PrimitivesProvider, { value: props.primitives, children: _jsx(ScreenWidthProvider, { width: props.screenWidth, children: _jsx(AppFeaturesProvider, { features: app?.features ?? EMPTY_FEATURES, children: _jsx(DispatcherProvider, { dispatcher: props.dispatcher, children: _jsx(DraftStorageProvider, { value: props.draftStorage, children: _jsx(LiveEventsProvider, { value: props.liveEvents, children: _jsx(DashboardBodyProvider, { value: WebDashboardBody, children: _jsx(CustomScreensProvider, { value: props.customScreens, children: _jsx(ColumnRenderersProvider, { value: props.columnRenderers, children: _jsx(ContentEditorsProvider, { value: props.contentEditors, children: _jsx(ExtensionSectionsProvider, { value: props.extensionSectionComponents, children: _jsx(ClientActionsProvider, { value: props.clientActions, children: _jsx(NavProvidersProvider, { value: navProviders, entities: navEntities, children: _jsx(ResolversProvider, { resolvers: props.resolvers, children: _jsx(ToastProvider, { children: _jsxs(ToastActionNotifier, { children: [_jsx(UpdateChecker, {}), _jsx(SessionEndedSignalProvider, { signal: props.sessionEndedSignal, children: stackWrappers(props.providers, stackWrappers(props.gates, screenNode)) })] }) }) }) }) }) }) }) }) }) }) }) }) }) }) }) })] }) }));
+}
+// Sits INSIDE the clientFeature gates (e.g. an auth gate) — a gate that
+// renders a login placeholder instead of children keeps this component
+// (and its schema fetch) from ever mounting until the user is signed in.
+function AppSchemaBoundary({ app, screenQn, schemaUrl, navAdapter, onAppLoaded, schemaIsRoleProjected, onUnmountResetSchema, translate, onRowClick, shell, }) {
+    // Called unconditionally regardless of which branch below actually
+    // renders — this component's identity persists across the "no app yet"
+    // → "app loaded" transition, so its hooks must run in the same order on
+    // every render (Rules of Hooks).
+    const t = useTranslation();
+    const { Banner } = usePrimitives();
+    // Ref, not an effect dependency: onUnmountResetSchema closes over
+    // KumikoAppRoot's setApp and would otherwise force this effect to
+    // re-run (and re-fire its cleanup) on every render.
+    const onUnmountResetSchemaRef = useRef(onUnmountResetSchema);
+    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.
+    useEffect(() => {
+        return () => onUnmountResetSchemaRef.current?.();
+    }, []);
+    if (app === undefined) {
+        return (_jsx(AppSchemaFetchBoot, { onLoaded: onAppLoaded, ...(schemaUrl !== undefined && { schemaUrl }) }));
+    }
+    const fallbackQn = resolveRootScreenQn(app.features, screenQn, schemaIsRoleProjected);
+    if (fallbackQn === undefined) {
+        return (_jsx(Banner, { variant: "error", padded: true, children: t("kumiko.app-boot.no-open-screen") }));
+    }
+    return (_jsx(BrowserNavBoot, { app: app, fallbackQn: fallbackQn, useNavApi: navAdapter, hasWorkspaces: (app.workspaces?.length ?? 0) > 0, ...(translate !== undefined && { translate }), ...(onRowClick !== undefined && { onRowClick }), ...(shell !== undefined && { shell }) }));
+}
+export function createKumikoApp(options = {}) {
+    const rootId = options.rootId ?? "root";
+    const container = document.getElementById(rootId);
+    if (!container) {
+        throw new Error(`createKumikoApp: DOM element #${rootId} not found. Make sure your HTML has a matching <div id="${rootId}"></div> before the bundle loads.`);
+    }
+    // toAppSchema normalizes the FeatureSchema/AppSchema union — from here on
+    // every layout only ever sees AppSchema. No schema resolved yet (neither
+    // options.schema nor window.__KUMIKO_SCHEMA__) is no longer an error here:
+    // KumikoAppRoot/AppSchemaBoundary fetch it from GET /api/schema instead.
+    const rawSchema = options.schema ?? readInjectedSchema();
+    let initialApp;
+    if (rawSchema !== undefined) {
+        initialApp = toAppSchema(rawSchema);
+        const fallbackQn = options.screenQn ?? firstOpenScreenQn(initialApp.features);
+        if (!fallbackQn) {
+            throw new Error("createKumikoApp: schema contains no screens accessible without a role restriction. Add at least one entry to `schema.screens` without `access.roles`, or pass `screenQn` explicitly.");
+        }
+    }
+    const sessionEndedSignal = createSessionEndedSignal();
+    const dispatcher = withSessionEndedDetection(options.dispatcher ?? createLiveDispatcher(), sessionEndedSignal);
+    const draftStorage = options.draftStorage ?? createBrowserDraftStorage();
+    const primitives = { ...defaultPrimitives, ...(options.primitives ?? {}) };
+    const liveEvents = createEventSourceLiveEvents({
+        onSessionEnded: () => sessionEndedSignal.notify(),
+    });
+    // Feature plugins: providers stack outermost (every gate + screen sees
+    // every provider), gates stack between the renderer providers and the
+    // shell/screen. Array order: first element = outermost wrapper.
+    const clientFeatures = options.clientFeatures ?? [];
+    const providers = clientFeatures.flatMap((f) => f.providers ?? []);
+    const gates = clientFeatures.flatMap((f) => f.gates ?? []);
+    // Custom-screen component map merge: later features override earlier ones
+    // on screenId collision (last-wins). Lets an app override a bundled
+    // feature's screen with a local component.
+    const customScreens = {};
+    for (const f of clientFeatures) {
+        if (f.components !== undefined)
+            Object.assign(customScreens, f.components);
+    }
+    if (initialApp !== undefined)
+        warnMissingCustomScreens(initialApp, customScreens);
+    // Column-renderer map, same last-wins semantics as customScreens —
+    // duplicate keys across features are rarely intentional, so a
+    // collision logs once instead of silently overriding a library's
+    // renderer.
+    const columnRenderers = mergeByKey(clientFeatures, (f) => f.columnRenderers, "columnRenderer");
+    // Extension-section components — same last-wins + warn semantics as
+    // columnRenderers. Mounted on ExtensionSectionsProvider; RenderEdit
+    // resolves the component from the section's `__component` marker.
+    const extensionSectionComponents = mergeByKey(clientFeatures, (f) => f.extensionSectionComponents, "extensionSectionComponent");
+    const clientActions = mergeByKey(clientFeatures, (f) => f.clientActions, "clientAction");
+    const contentEditors = mergeContentEditors(clientFeatures);
+    // Aggregate editor resolvers — keyed by "featureId:action". Same
+    // last-wins semantics as columnRenderers. Warns on collision.
+    const resolvers = new Map();
+    for (const f of clientFeatures) {
+        if (f.resolvers === undefined)
+            continue;
+        for (const [key, component] of Object.entries(f.resolvers)) {
+            if (resolvers.has(key)) {
+                // biome-ignore lint/suspicious/noConsole: client-bundle has no logger; collision is a dev-time warning that must surface in the browser DevTools.
+                console.warn(`[kumiko] resolver "${key}" defined by multiple clientFeatures — last definition (from "${f.name}") wins.`);
+            }
+            resolvers.set(key, component);
+        }
+    }
+    const localeResolver = options.locale ?? createBrowserLocaleResolver();
+    const navAdapter = options.navAdapter ?? useBrowserNavApi;
+    const root = createRoot(container);
+    root.render(_jsx(ErrorBoundary, { scope: "root", ...(options.onError !== undefined && { onError: options.onError }), fallback: () => _jsx(RootErrorFallback, {}), children: _jsx(BoundaryErrorHandlerContext.Provider, { value: options.onError, children: _jsx(KumikoAppRoot, { initialApp: initialApp, screenQn: options.screenQn, ...(options.schemaUrl !== undefined && { schemaUrl: options.schemaUrl }), clientFeatures: clientFeatures, providers: providers, gates: gates, customScreens: customScreens, columnRenderers: columnRenderers, extensionSectionComponents: extensionSectionComponents, clientActions: clientActions, contentEditors: contentEditors, resolvers: resolvers, dispatcher: dispatcher, sessionEndedSignal: sessionEndedSignal, draftStorage: draftStorage, primitives: primitives, liveEvents: liveEvents, localeResolver: localeResolver, navAdapter: navAdapter, screenWidth: options.screenWidth, ...(options.translate !== undefined && { translate: options.translate }), ...(options.onRowClick !== undefined && { onRowClick: options.onRowClick }), ...(options.shell !== undefined && { shell: options.shell }) }) }) }));
+    return { root };
+}
+// TokensBoot uses the browser-backed TokensApi hook (class-based
+// dark-toggle) and passes the value through to the shared
+// TokensProvider. No own state — the class on <html> is the
+// SSoT, useSyncExternalStore in the hook syncs that into React.
+function TokensBoot({ children }) {
+    const api = useBrowserTokensApi();
+    return _jsx(TokensProvider, { value: api, children: children });
+}
+function BrowserNavBoot({ app, fallbackQn, useNavApi, hasWorkspaces, translate, onRowClick, shell, }) {
+    const navApi = useNavApi({ hasWorkspaces, features: app.features });
+    const Shell = shell;
+    const screen = (_jsx(RoutedScreen, { app: app, fallbackQn: fallbackQn, ...(translate !== undefined && { translate }), ...(onRowClick !== undefined && { onRowClick }) }));
+    return (_jsx(NavProvider, { value: navApi, children: Shell !== undefined ? _jsx(Shell, { schema: app, children: screen }) : screen }));
+}
+// Finds the feature that owns a fully qualified ScreenQn.
+// Returns undefined if the screen isn't declared in any feature schema —
+// KumikoScreen then renders the "Screen not found" banner.
+function findOwnerFeature(features, qn) {
+    for (const feature of features) {
+        for (const s of feature.screens) {
+            if (qualifyScreenId(feature.featureName, s.id) === qn)
+                return feature;
+        }
+    }
+    return undefined;
+}
+// Single source for "which entityEdit screen does a row click land on", shared
+// by the click handler and hasRowClickTarget so a row never looks clickable
+// without a target (or the reverse).
+function findEditScreenForEntity(features, entityName) {
+    for (const feature of features) {
+        const editScreen = feature.screens.find((s) => s.type === "entityEdit" && s.entity === entityName);
+        if (editScreen)
+            return editScreen;
+    }
+    return undefined;
+}
+// fw#2640: 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.
+// Only entityList/projectionList screens ever render RenderList; every other
+// screen type never wires onRowClick at all, so it can never have a target.
+function hasRowClickTarget(app, screen, onRowClick) {
+    if (screen === undefined)
+        return false;
+    if (screen.type !== "entityList" && screen.type !== "projectionList")
+        return false;
+    if (onRowClick !== undefined)
+        return true;
+    if (screen.type !== "entityList")
+        return false;
+    if (hasDetailScreen(app.features, screen.entity))
+        return true;
+    return findEditScreenForEntity(app.features, screen.entity) !== undefined;
+}
+function RoutedScreen({ app, fallbackQn, translate, onRowClick, }) {
+    const nav = useNav();
+    const onBoundaryError = useContext(BoundaryErrorHandlerContext);
+    // ScreenId from the route is NOT qualified — nav.route.screenId
+    // comes from the URL path and is the short form ("order-list"). We
+    // need to pin it to the right feature. Strategy: iterate through all
+    // features until the matching screen decl turns up. No match →
+    // fallback feature (the one from fallbackQn).
+    const { feature, qn, entityId, activeScreen } = useMemo(() => {
+        if (nav.route === undefined) {
+            const ownerFeature = findOwnerFeature(app.features, fallbackQn);
+            return {
+                feature: ownerFeature,
+                qn: fallbackQn,
+                entityId: undefined,
+                activeScreen: ownerFeature?.screens.find((s) => qualifyScreenId(ownerFeature.featureName, s.id) === fallbackQn),
+            };
+        }
+        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)) {
+                matchedFeature = f;
+                break;
+            }
+        }
+        const ownerFeature = matchedFeature ?? findOwnerFeature(app.features, fallbackQn);
+        const qualifiedQn = ownerFeature ? qualifyScreenId(ownerFeature.featureName, shortId) : shortId;
+        return {
+            feature: ownerFeature,
+            qn: qualifiedQn,
+            entityId: nav.route.entityId,
+            activeScreen: ownerFeature?.screens.find((s) => qualifyScreenId(ownerFeature.featureName, s.id) === qualifiedQn),
+        };
+    }, [nav.route, app, fallbackQn]);
+    const effectiveOnRowClick = useMemo(() => {
+        if (!hasRowClickTarget(app, activeScreen, onRowClick))
+            return undefined;
+        return (row, entityName) => {
+            // No ReturnHostProvider out here — derive the host from this memo's own qn/entityId.
+            const host = {
+                screenId: lastSegment(qn),
+                ...(entityId !== undefined && { entityId }),
+            };
+            // Precedence (fw#2164): 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.
+            if (hasDetailScreen(app.features, entityName)) {
+                navigateWithReturnTo(nav, { entity: entityName, id: row.id }, host);
+                return;
+            }
+            if (onRowClick !== undefined) {
+                onRowClick(row, entityName);
+                return;
+            }
+            // No declared detail screen and no app-wide onRowClick — search for
+            // the edit screen for the entity across all features — in a
+            // single-feature setup that's the same feature as the active one, in
+            // multi-feature the edit could theoretically live in a different
+            // feature (one that shares the entity).
+            const editScreen = findEditScreenForEntity(app.features, entityName);
+            if (editScreen) {
+                // editScreen.id is already short form; lastSegment is a no-op
+                // safety net here, kept for symmetry with the other call sites.
+                navigateWithReturnTo(nav, { screenId: lastSegment(editScreen.id), entityId: row.id }, host);
+            }
+        };
+    }, [app, activeScreen, onRowClick, nav, qn, entityId]);
+    // Copy-link action (Issue #912) 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).
+    // Silent-catch on clipboard error (non-secure context) mirrors the
+    // existing pattern in pat-tokens-screen.tsx.
+    const effectiveOnCopyLink = useMemo(() => {
+        const route = nav.route;
+        if (route?.entityId === undefined)
+            return undefined;
+        return async () => {
+            const url = `${window.location.origin}${nav.hrefFor(route)}`;
+            try {
+                await navigator.clipboard.writeText(url);
+            }
+            catch {
+                // clipboard blocked (non-secure context) — no fallback UI needed here
+            }
+        };
+    }, [nav]);
+    if (feature === undefined || activeScreen === undefined) {
+        const landingExists = findOwnerFeature(app.features, fallbackQn) !== undefined;
+        return (_jsx(ScreenMissingState, { ...(landingExists && { homeScreenId: lastSegment(fallbackQn) }), screenQn: qn }));
+    }
+    // KumikoScreen takes a single-feature schema: the feature owning the active screen.
+    const schemaForScreen = feature;
+    return (_jsx(ErrorBoundary, { scope: "screen", ...(onBoundaryError !== undefined && { onError: onBoundaryError }), fallback: ({ error, reset }) => (_jsx(ScreenErrorFallback, { screen: qn, error: error, onReset: reset })), children: _jsx(KumikoScreen, { schema: schemaForScreen, qn: qn, ...(translate !== undefined && { translate }), ...(entityId !== undefined && { entityId }), onRowClick: effectiveOnRowClick, ...(effectiveOnCopyLink !== undefined && { onCopyLink: effectiveOnCopyLink }) }) }, `${qn}/${entityId ?? ""}`));
+}

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

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { type Root } from "react-dom/client";
+import type { Dispatcher, LocaleResolver } from "../../headless/index.ts";
+import { type Formality, type PrimitivesRegistry } from "../../index.ts";
+import { type ClientFeatureDefinition } from "./client-plugin.tsx";
+export type PublicRoute = {
+    /** Exact window.location.pathname match (matched once on mount; every
+     *  apex page is a full-page reload, no SPA router). */
+    readonly path: string;
+    readonly component: ReactNode;
+};
+export type CreatePublicSurfaceOptions = {
+    readonly routes: readonly PublicRoute[];
+    /** Rendered when no route.path matches the current path. */
+    readonly fallback?: ReactNode;
+    readonly rootId?: string;
+    readonly locale?: LocaleResolver;
+    readonly primitives?: Partial<PrimitivesRegistry>;
+    /** Dispatcher for handler calls (e.g. an anonymous deletion request).
+     *  Auth screens don't need it (fetch via auth-client), but it's there for
+     *  dispatching public flows. Default: createLiveDispatcher(). */
+    readonly dispatcher?: Dispatcher;
+    /** Feature client extensions — ONLY `providers` + `translations` are
+     *  stacked. `gates` are deliberately ignored: an AuthGate would lock the
+     *  public surface behind login. */
+    readonly clientFeatures?: readonly ClientFeatureDefinition[];
+    /** Page chrome around the matched content (apex/marketing layout). */
+    readonly shell?: (props: {
+        readonly children: ReactNode;
+    }) => ReactNode;
+    /** Wording for every page of this surface. Default: `"informal"`. */
+    readonly formality?: Formality;
+};
+export declare function createPublicSurface(options: CreatePublicSurfaceOptions): {
+    readonly root: Root;
+};

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

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createRoot } from "react-dom/client";
+import { DispatcherProvider, FormalityProvider, kumikoDefaultTranslations, LocaleProvider, PrimitivesProvider, } from "../../index.js";
+import { createLiveDispatcher } from "../../live/index.js";
+import { defaultPrimitives } from "../primitives/index.js";
+import { ToastProvider } from "../primitives/toast.js";
+import { createBrowserLocaleResolver } from "./browser-locale.js";
+import { stackWrappers } from "./client-plugin.js";
+import { DocumentLangSync } from "./document-lang-sync.js";
+function matchRoute(options, pathname) {
+    for (const route of options.routes) {
+        if (route.path === pathname)
+            return route.component;
+    }
+    return options.fallback ?? null;
+}
+export function createPublicSurface(options) {
+    const rootId = options.rootId ?? "root";
+    const container = document.getElementById(rootId);
+    if (!container) {
+        throw new Error(`createPublicSurface: DOM element #${rootId} not found. Make sure your HTML has a matching <div id="${rootId}"></div> before the bundle loads.`);
+    }
+    const dispatcher = options.dispatcher ?? createLiveDispatcher();
+    const primitives = { ...defaultPrimitives, ...(options.primitives ?? {}) };
+    const localeResolver = options.locale ?? createBrowserLocaleResolver();
+    const clientFeatures = options.clientFeatures ?? [];
+    const providers = clientFeatures.flatMap((f) => f.providers ?? []);
+    const fallbackBundles = [
+        ...clientFeatures.flatMap((f) => (f.translations !== undefined ? [f.translations] : [])),
+        kumikoDefaultTranslations,
+    ];
+    const pathname = typeof window !== "undefined" ? window.location.pathname : "";
+    const matched = matchRoute(options, pathname);
+    const Shell = options.shell;
+    const content = Shell !== undefined ? _jsx(Shell, { children: matched }) : matched;
+    const tree = (_jsx(LocaleProvider, { resolver: localeResolver, fallbackBundles: fallbackBundles, children: _jsxs(FormalityProvider, { formality: options.formality ?? "informal", children: [_jsx(DocumentLangSync, { resolver: localeResolver }), _jsx(PrimitivesProvider, { value: primitives, children: _jsx(DispatcherProvider, { dispatcher: dispatcher, children: _jsx(ToastProvider, { children: stackWrappers(providers, content) }) }) })] }) }));
+    const root = createRoot(container);
+    root.render(tree);
+    return { root };
+}

package/dist/web/app/dashboard-body.d.ts

@@ -0,0 +1,3 @@
+import { type ReactNode } from "react";
+import { type DashboardBodyProps } from "../../index.ts";
+export declare function WebDashboardBody({ featureName, screen, translate, }: DashboardBodyProps): ReactNode;