@cosmicdrift/kumiko-renderer 0.383.1 → 0.385.0

package/dist/components/use-wizard-form-draft.js

@@ -0,0 +1,291 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { rendererWarn } from "../dev-console.js";
+// Qualified names of the bundled `form-draft` feature. Hardcoded because the
+// renderer must not depend on @cosmicdrift/kumiko-bundled-features; a screen
+// with `layout.draft: true` and that feature unmounted is a boot error, so
+// these can never dangle silently.
+const FORM_DRAFT_GET = "form-draft:query:get";
+const FORM_DRAFT_SAVE = "form-draft:write:save";
+const FORM_DRAFT_DISCARD = "form-draft:write:discard";
+const FORM_DRAFT_LIST = "form-draft:query:list";
+// Mirrors bundled-features/src/form-draft/web/constants.ts's FORM_DRAFT_KEY_MAX_LENGTH
+// — same hardcoding rationale as the QNs above (no dependency on that package).
+const FORM_DRAFT_KEY_MAX_LENGTH = 256;
+// Trailing-edge debounce for patch()-triggered draft saves (#1914). A single
+// patch() call (VIN-decode, an extension section) should not save immediately
+// per call, but patch() can also fire from inside onChange on every keystroke
+// (the #1888 derived-field shape) — 500ms collapses a typing burst into one
+// save instead of one per keystroke, while still saving well before a user
+// abandons the tab.
+export const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
+// draftKey convention for a create-mode draft (framework-wizard-mode.md,
+// lookup.ts): `${screenId}:new:${draftId}`. Shared by the mount-time list
+// fallback (strip the prefix to recover a candidate's draftId) and the
+// list query itself (filter out edit-mode drafts, which share the same
+// `${screenId}:%` LIKE-prefix scan server-side).
+function newDraftPrefix(screenId) {
+    return `${screenId}:new:`;
+}
+// `crypto.randomUUID` is missing in non-secure contexts and React Native/Hermes
+// without a polyfill — guard like generateRequestId in headless/dispatcher/request-id.ts.
+function mintDraftId() {
+    const webCrypto = propertyOf(globalThis, "crypto");
+    const randomUUID = propertyOf(webCrypto, "randomUUID");
+    if (typeof randomUUID === "function") {
+        const id = Reflect.apply(randomUUID, webCrypto, []);
+        if (typeof id === "string")
+            return id;
+    }
+    return `draft-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draftStorage, }) {
+    // Create-mode draftId (issue #1913) — resumed from `sessionStorage` (web)
+    // on mount so a same-tab reload finds the right one of several parallel
+    // create-sessions on this screen; `null` until the first step change
+    // mints one (saveDraft), or the mount-time `form-draft:query:list`
+    // fallback below adopts an existing one. Edit-mode never touches this —
+    // its draftKey is `${screenId}:${entityId}` unconditionally.
+    const [draftId, setDraftId] = useState(() => isCreateMode ? draftStorage.getDraftId(screenId) : null);
+    // Marks a draftId this instance minted itself (saveDraft, first step
+    // change) so the restore effect below doesn't immediately re-fetch what
+    // it just wrote — there is nothing to restore, the row is brand new.
+    const mintedDraftIdRef = useRef(null);
+    // Marks that the mount-time `form-draft:query:list` fallback already ran
+    // once for this mount. Without this, a create-mode discard resets `draftId`
+    // to `null` (see discardDraft below) and would re-arm the list effect —
+    // silently adopting an unrelated parallel draft on the same screen right
+    // after the user just submitted (#1908).
+    const didListRef = useRef(false);
+    const [draftCandidates, setDraftCandidates] = useState(null);
+    // Derived from the screen id + the host entity id only — never from
+    // `vm.id`, which lives in the form values a restore mutates (load under one
+    // key, save under another). Edit-mode: `${screenId}:${entityId}`,
+    // unchanged. Create-mode: `${screenId}:new:${draftId}` once a draftId
+    // exists (resumed, adopted, or minted), `undefined` before that — two
+    // parallel create sessions on the same screen must never collapse onto
+    // the same key (kumiko-framework#1908).
+    const draftKey = useMemo(() => isCreateMode
+        ? draftId !== null
+            ? `${screenId}:new:${draftId}`
+            : undefined
+        : `${screenId}:${entityId}`, [screenId, entityId, isCreateMode, draftId]);
+    return {
+        draftId,
+        setDraftId,
+        draftCandidates,
+        setDraftCandidates,
+        mintedDraftIdRef,
+        didListRef,
+        draftKey,
+    };
+}
+export function useWizardFormDraftRestore({ screenId, isCreateMode, draftEnabled, dispatcher, controller, hasNavigatedRef, setRawStep, draftState: { draftId, draftKey, mintedDraftIdRef, didListRef, setDraftCandidates }, }) {
+    useEffect(() => {
+        // skip: this screen does not persist a draft.
+        if (!draftEnabled || dispatcher === undefined)
+            return;
+        // skip: create-mode with no draftId yet — nothing to restore, either
+        // the list-fallback effect below finds one or the first step change
+        // mints a fresh one.
+        if (draftKey === undefined)
+            return;
+        // skip: this draftId was just minted by saveDraft — the row it wrote
+        // is exactly the current form state, re-fetching it would be a no-op
+        // round-trip at best and a stale-echo clobber at worst.
+        if (draftId !== null && draftId === mintedDraftIdRef.current)
+            return;
+        let cancelled = false;
+        void (async () => {
+            try {
+                const result = await dispatcher.query(FORM_DRAFT_GET, { draftKey });
+                // skip: superseded by a newer mount, or the draft lookup failed — an
+                // unreachable draft store must not break the form itself.
+                if (cancelled || !result.isSuccess)
+                    return;
+                const draft = result.data?.draft ?? null;
+                // skip: nothing saved yet for this key.
+                if (draft === null)
+                    return;
+                // skip: the user already typed or wizard-navigated while the lookup
+                // was in flight — their input wins over the stored draft.
+                if (controller.getSnapshot().isDirty || hasNavigatedRef.current)
+                    return;
+                // @cast-boundary form-values draft blob: `values` round-trips through an opaque
+                // jsonb column and comes back untyped.
+                controller.setValues(draft.values);
+                setRawStep(Math.max(draft.stepIndex, 0));
+            }
+            catch (err) {
+                rendererWarn("render-edit: draft restore query failed", err);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        draftEnabled,
+        draftKey,
+        draftId,
+        dispatcher,
+        controller,
+        mintedDraftIdRef,
+        hasNavigatedRef,
+        setRawStep,
+    ]);
+    // Mount-time fallback (issue #1913) for create-mode when no draftId
+    // survived in storage (new tab, cleared storage): ask the server for this
+    // screen's open drafts and let the user choose via a picker (below) —
+    // even for exactly one candidate. Auto-adopting a lone candidate would
+    // silently hand this tab someone else's in-progress draft from a parallel
+    // session on the same screen (cross-tab hijack); the picker's "start new"
+    // action covers the common case (it really was this tab's own draft) with
+    // one extra click. Zero candidates → stay null, saveDraft mints a fresh
+    // draftId on the first step change same as any other fresh create.
+    useEffect(() => {
+        if (!draftEnabled ||
+            !isCreateMode ||
+            draftId !== null ||
+            didListRef.current ||
+            dispatcher === undefined) {
+            // skip: this screen does not persist a draft, this is edit-mode, a
+            // draftId is already known (from storage or an earlier adoption), or
+            // this mount already ran the list lookup once (didListRef).
+            return;
+        }
+        let cancelled = false;
+        void (async () => {
+            try {
+                const result = await dispatcher.query(FORM_DRAFT_LIST, { screenId: screenId });
+                // skip: superseded by a newer mount, or the lookup failed — an
+                // unreachable draft store must not break a fresh create.
+                if (cancelled || !result.isSuccess)
+                    return;
+                didListRef.current = true;
+                const prefix = newDraftPrefix(screenId);
+                // list's LIKE-prefix scan also matches edit-mode drafts
+                // (`${screenId}:${entityId}`) — keep only create-mode ones.
+                const candidates = (result.data?.drafts ?? []).filter((d) => d.draftKey.startsWith(prefix));
+                // skip: no open drafts for this screen — stay null, saveDraft mints a
+                // fresh draftId on the first step change same as any other create.
+                if (candidates.length === 0)
+                    return;
+                setDraftCandidates(candidates);
+            }
+            catch (err) {
+                rendererWarn("render-edit: draft list query failed", err);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [draftEnabled, isCreateMode, draftId, dispatcher, screenId, didListRef, setDraftCandidates]);
+}
+export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled, disabled, dispatcher, draftStorage, controller, sections, draftSaveTimerRef, draftState: { draftId, draftKey, mintedDraftIdRef, setDraftId, setDraftCandidates }, }) {
+    // User picked one of several open drafts from the mount-time picker
+    // (see draftCandidates below) — adopt it the same way a single
+    // auto-adopted candidate would be.
+    function adoptDraft(candidate) {
+        // Locked state (#1896/fw#1909): `disabled` means "no write possible" —
+        // repointing draftKey and patching in the candidate's values is exactly
+        // that, so a locked form must not adopt a draft.
+        // skip: a locked form keeps its current draft (reason above).
+        if (disabled)
+            return;
+        const adoptedId = candidate.draftKey.slice(newDraftPrefix(screenId).length);
+        draftStorage.setDraftId(screenId, adoptedId);
+        setDraftId(adoptedId);
+        setDraftCandidates(null);
+    }
+    // Step transitions only — never per keystroke. Deliberately not awaited: a
+    // failed draft save must not block the step change.
+    //
+    // Create-mode, first draft save (step change OR a debounced patch() from
+    // controlled mode / extension sections, see patchAndScheduleDraftSave
+    // above — both call this on step 0 too): mints the draftId here (issue
+    // #1913) rather than at mount, so a form nobody ever interacted with
+    // never claims a draftId or writes a row. `draftKey`/`draftId` state
+    // won't reflect the mint until the next render, so the just-minted key is
+    // computed inline instead of read from the memoized `draftKey`.
+    function saveDraft(stepIndex) {
+        // skip: this screen does not persist a draft.
+        if (!draftEnabled || dispatcher === undefined)
+            return;
+        let key = draftKey;
+        if (isCreateMode && draftId === null) {
+            const mintedId = mintDraftId();
+            mintedDraftIdRef.current = mintedId;
+            draftStorage.setDraftId(screenId, mintedId);
+            setDraftId(mintedId);
+            key = `${screenId}:new:${mintedId}`;
+            // A stale picker from the mount-time list fallback must not survive a
+            // mint — picking a candidate afterwards would repoint draftKey at an
+            // unrelated draft mid-edit and overwrite it (#1908).
+            setDraftCandidates(null);
+        }
+        // skip: create-mode with a draftId that failed to mint — unreachable
+        // in practice (mint above always produces one), kept as a type-level
+        // guard against a stale `undefined` key ever reaching the write.
+        if (key === undefined)
+            return;
+        // draftKeySchema.max(FORM_DRAFT_KEY_MAX_LENGTH) rejects this server-side —
+        // catch it here instead of losing the save silently to the fire-and-forget
+        // write below (the user would only notice on resume, with nothing to resume).
+        if (key.length > FORM_DRAFT_KEY_MAX_LENGTH) {
+            rendererWarn(`RenderEdit: draftKey "${key}" is ${key.length} chars, over the server's ${FORM_DRAFT_KEY_MAX_LENGTH}-char limit — skipping this draft save. Shorten screenId or entity id.`);
+            // skip: warned above, the oversized key would be rejected by the server anyway.
+            return;
+        }
+        const secretFieldNames = new Set(sections.flatMap((section) => section.kind === "fields"
+            ? section.fields
+                .filter((f) => f.format === "password" || f.writeOnly === true || f.sensitive === true)
+                .map((f) => f.field)
+            : []));
+        // A password, writeOnly or sensitive field never enters the persisted draft blob — it would be stored in the clear and restored on resume.
+        const draftValues = Object.fromEntries(Object.entries(controller.getSnapshot().values).filter(([field]) => !secretFieldNames.has(field)));
+        void dispatcher
+            .write(FORM_DRAFT_SAVE, {
+            draftKey: key,
+            values: draftValues,
+            stepIndex,
+        })
+            .catch((err) => {
+            rendererWarn("render-edit: draft save failed", err);
+        });
+    }
+    async function discardDraft() {
+        // skip: this screen does not persist a draft.
+        if (!draftEnabled || dispatcher === undefined)
+            return;
+        // A pending debounced patch-save must not fire after discard — it would
+        // resurrect the draft it just deleted.
+        if (draftSaveTimerRef.current !== null) {
+            clearTimeout(draftSaveTimerRef.current);
+            draftSaveTimerRef.current = null;
+        }
+        // skip: create-mode, no step change happened yet — no draftId was ever
+        // minted, so no row exists to discard.
+        if (draftKey === undefined)
+            return;
+        // Best-effort: a rejected write (e.g. network error) must not propagate
+        // out of handleSubmit AFTER the entity write already succeeded — that
+        // would break onSubmit/navigation/toast and risk a duplicate submit on
+        // retry. An orphaned draft row is swept later by cleanup.job.ts. Local
+        // cleanup below still runs on failure so this instance doesn't try to
+        // resume a draft it already considers submitted.
+        try {
+            await dispatcher.write(FORM_DRAFT_DISCARD, { draftKey });
+        }
+        catch {
+            // best-effort, see comment above.
+        }
+        // A successful submit ends this draftId's life — a subsequent create on
+        // the same screen (new mount) must mint its own, not resume this one.
+        if (isCreateMode) {
+            draftStorage.clearDraftId(screenId);
+            mintedDraftIdRef.current = null;
+            setDraftId(null);
+        }
+    }
+    return { adoptDraft, saveDraft, discardDraft };
+}

package/dist/dev-console.d.ts

@@ -0,0 +1,3 @@
+export declare function rendererWarn(...args: unknown[]): void;
+export declare function rendererError(...args: unknown[]): void;
+export declare function rendererDebug(...args: unknown[]): void;

package/dist/dev-console.js

@@ -0,0 +1,15 @@
+// The renderer has no logger; the browser console is the developer-facing
+// channel. Resolved at call time (not bound at import) so tests can spy on
+// console.* per test.
+export function rendererWarn(...args) {
+    // biome-ignore lint/suspicious/noConsole: renderer has no logger, the browser console is the developer-facing channel
+    console.warn(...args);
+}
+export function rendererError(...args) {
+    // biome-ignore lint/suspicious/noConsole: renderer has no logger, the browser console is the developer-facing channel
+    console.error(...args);
+}
+export function rendererDebug(...args) {
+    // biome-ignore lint/suspicious/noConsole: renderer has no logger, the browser console is the developer-facing channel
+    console.debug(...args);
+}

package/dist/headless/contracts/primitives.js

@@ -1,21 +1,18 @@
-// Primitives-Contract — the minimal set of UI building blocks every
-// renderer must provide. A "primitive" is a unit the standard-renderers
-// (entityList, entityEdit, etc.) call into without knowing which library
-// implements it. On web that's shadcn; on mobile it's react-native-paper;
-// both packages (primitives-shadcn, primitives-paper) implement this
-// contract and the app wires one of them into the renderer via context.
+// Primitives-Contract — the minimal set of UI building blocks the
+// standard-renderers (entityList, entityEdit, etc.) call into without knowing
+// which implementation provides them. It is the DOM-free seam through which
+// apps override primitives and tests substitute fakes, both via
+// PrimitivesProvider.
 //
-// Why a contract here (in ui-core) instead of in each renderer:
-// ui-core's view-model builder and form-controller produce metadata
-// (field-type, validation-state, label, placeholder) that the renderer
-// translates into primitive invocations. Having the contract shape in
-// ui-core means the metadata can carry references to primitives by name
-// ("text-input", "select") and the translation is a pure map-lookup on
-// the renderer side, not a switch statement that re-derives UI intent
-// from entity-schema.
+// Why a contract in headless: the view-model builder and form-controller
+// produce metadata (field-type, validation-state, label, placeholder) that the
+// renderer translates into primitive invocations. Having the contract shape
+// here means the metadata can carry references to primitives by name
+// ("text-input", "select") and the translation is a pure map-lookup on the
+// renderer side, not a switch statement that re-derives UI intent from
+// entity-schema.
 //
 // Runtime-free: every primitive is expressed as its input contract only
-// (what props it takes). Concrete components live in each primitives-*
-// package and depend on React / React Native / etc.; ui-core never
-// imports them.
+// (what props it takes). Concrete components live in web/primitives and
+// headless never imports them.
 export {};

package/dist/headless/format/index.js

@@ -1,7 +1,8 @@
 // Pure format utilities — no web or platform dependencies.
-// Shared between renderer/web, renderer-native, and server-side tests.
+// Shared between renderer/web and server-side tests.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { rendererWarn } from "../../dev-console.js";
 export const EMPTY_VALUE_PLACEHOLDER = "—";
 function toPlainDate(raw) {
     try {
@@ -68,11 +69,11 @@ function formatDateCell(value, type, opts) {
 // No `locale` fallback to a browser API here (headless has none) — passing
 // `undefined` to Intl.NumberFormat resolves the runtime's default locale,
 // the same value a browser's navigator.language-based guess would produce.
-function formatNumberCell(value, locale, grouping = true) {
+function formatNumberCell(value, locale, grouping = true, fractionDigits = {}) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return String(value);
     try {
-        return new Intl.NumberFormat(locale, { useGrouping: grouping }).format(value);
+        return new Intl.NumberFormat(locale, { useGrouping: grouping, ...fractionDigits }).format(value);
     }
     catch {
         // Malformed BCP-47 locale tag — mirrors formatDateCell's fallback above.
@@ -152,6 +153,25 @@ function stringSpec(spec, key) {
     const v = spec[key];
     return typeof v === "string" ? v : undefined;
 }
+const MAX_FRACTION_DIGITS = 20;
+function fractionDigitSpec(spec, key) {
+    const v = spec[key];
+    return typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= MAX_FRACTION_DIGITS
+        ? v
+        : undefined;
+}
+// Out-of-range or inverted options fall back to the Intl default instead of
+// throwing: a bad schema option must not crash the screen it renders in.
+function fractionDigitsSpec(spec) {
+    const min = fractionDigitSpec(spec, "minimumFractionDigits");
+    const max = fractionDigitSpec(spec, "maximumFractionDigits");
+    if (min !== undefined && max !== undefined && min > max)
+        return {};
+    return {
+        ...(min !== undefined && { minimumFractionDigits: min }),
+        ...(max !== undefined && { maximumFractionDigits: max }),
+    };
+}
 function booleanSpec(spec, key) {
     const v = spec[key];
     return typeof v === "boolean" ? v : undefined;
@@ -197,7 +217,7 @@ export function applyFormatSpec(spec, value, translate) {
         case "number":
         case "decimal":
         case "bigInt":
-            return formatNumberCell(value, stringSpec(spec, "locale"), booleanSpec(spec, "grouping") ?? true);
+            return formatNumberCell(value, stringSpec(spec, "locale"), booleanSpec(spec, "grouping") ?? true, spec.format === "bigInt" ? {} : fractionDigitsSpec(spec));
         case "unit":
             return formatUnitCell(value, stringSpec(spec, "unit"), stringSpec(spec, "locale"), unitDisplaySpec(spec));
         case "priority": {
@@ -229,8 +249,7 @@ export function applyFormatSpec(spec, value, translate) {
             return stringifyJsonOrString(value, typeof spec["indent"] === "number" ? spec["indent"] : 2);
         default:
             if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
-                // biome-ignore lint/suspicious/noConsole: dev-only warning
-                console.warn(`[kumiko] applyFormatSpec: unknown format key "${spec.format}" — registered via FieldFormatRegistry module augmentation?`);
+                rendererWarn(`[kumiko] applyFormatSpec: unknown format key "${spec.format}" — registered via FieldFormatRegistry module augmentation?`);
             }
             return typeof value === "string" ? value : String(value);
     }

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

@@ -2,7 +2,7 @@ import type { EditRelatedListSection, EntityDefinition, EntityEditScreenDefiniti
 import type { EditRelatedListSectionViewModel, EditViewModel, Translate } from "./types.ts";
 export type ComputeEditViewModelInput<TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
     readonly screen: EntityEditScreenDefinition;
-    readonly entity: EntityDefinition;
+    readonly entity: Pick<EntityDefinition, "fields" | "defaultCurrency">;
     readonly values: TValues;
     readonly translate: Translate;
     readonly featureName: string;

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

@@ -42,6 +42,12 @@ function computeWriteFormSectionViewModel(sectionSpec, screenId, values, transla
         ...(sectionSpec.actions !== undefined && { actions: sectionSpec.actions }),
     };
 }
+// A section whose only content is an action (a conditional field plus a delete button) stays on the screen.
+function hasVisibleContent(fields, actions, values) {
+    if (fields.some((field) => field.visible))
+        return true;
+    return (actions ?? []).some((action) => action.visible === undefined || evalFieldCondition(action.visible, values));
+}
 function wasEmptiedByWriteExclusion(declaredFieldSpecs, remainingFields) {
     return declaredFieldSpecs.length > 0 && remainingFields.length === 0;
 }
@@ -178,11 +184,12 @@ function deriveTextFieldHints(fieldDef) {
         ...("sensitive" in fieldDef && fieldDef.sensitive === true && { sensitive: true }),
     };
 }
+// files/images field defs carry no `required` property.
+function isRequiredByEntity(fieldDef) {
+    return "required" in fieldDef && fieldDef.required === true;
+}
 function deriveDateFieldHints(fieldDef) {
-    const wallClock = fieldDef.type === "timestamp" &&
-        fieldDef.locatedBy !== undefined
-        ? true
-        : undefined;
+    const wallClock = fieldDef.type === "timestamp" && fieldDef.locatedBy !== undefined ? true : undefined;
     const dateBounds = fieldDef.type === "date" ||
         fieldDef.type === "timestamp" ||
         fieldDef.type === "locatedTimestamp"
@@ -206,9 +213,7 @@ function deriveNumericFieldHints(fieldDef, resolvedCurrency) {
 // Declared reference metadata (EditFieldSpec.refEntity) takes priority over
 // fieldDef.type — see computeEditViewModel's effectiveType, same reasoning.
 function deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, featureName) {
-    const refRaw = declaredRefTarget === undefined && fieldDef.type === "reference"
-        ? fieldDef.entity
-        : undefined;
+    const refRaw = declaredRefTarget === undefined && fieldDef.type === "reference" ? fieldDef.entity : undefined;
     const refTarget = declaredRefTarget ?? (refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined);
     const refLabelField = declaredRefTarget !== undefined
         ? (normalized.refLabelField ?? "id")
@@ -226,9 +231,7 @@ function deriveReferenceFieldHints(fieldDef, normalized, declaredRefTarget, feat
 // (it targets row-meta/derived fields, always single-valued and resolved
 // through the target entity) — only a real ReferenceFieldDef carries them.
 function deriveReferenceMultiHints(fieldDef, declaredRefTarget) {
-    const ownReferenceDef = declaredRefTarget === undefined && fieldDef.type === "reference"
-        ? fieldDef
-        : undefined;
+    const ownReferenceDef = declaredRefTarget === undefined && fieldDef.type === "reference" ? fieldDef : undefined;
     const refMultiple = ownReferenceDef === undefined ? undefined : (ownReferenceDef.multiple ?? false);
     return {
         ...(ownReferenceDef?.optionsQuery !== undefined && {
@@ -312,11 +315,7 @@ function buildEmbeddedListCell(subFieldName, subField, translate, featureName, e
 // apart by whether embeddedListCells is set, not by `type` (which stays
 // "embedded" either way).
 function deriveEmbeddedListHints(fieldDef, translate, featureName, entityName, fieldName, resolvedCurrency, listSpec) {
-    const isEmbeddedList = fieldDef.type === "embedded" &&
-        fieldDef.multiple === true;
-    const embeddedListDef = isEmbeddedList
-        ? fieldDef
-        : undefined;
+    const embeddedListDef = fieldDef.type === "embedded" && fieldDef.multiple === true ? fieldDef : undefined;
     const embeddedListCells = embeddedListDef !== undefined
         ? Object.entries(embeddedListDef.schema).map(([subFieldName, subField]) => buildEmbeddedListCell(subFieldName, subField, translate, featureName, entityName, fieldName, listSpec))
         : undefined;
@@ -421,7 +420,7 @@ export function computeEditViewModel(input) {
             // field that's required at the entity-level but marked required:
             // false on the screen (e.g. a soft-onboarding wizard that
             // collects less up-front) respects the screen override.
-            const entityRequired = fieldDef.required === true;
+            const entityRequired = isRequiredByEntity(fieldDef);
             const required = !lockedByDerivation && evalCondition(normalized.required, entityRequired, values);
             // ponytail: "EUR" mirrors DEFAULT_CURRENCIES[0] from
             // framework/src/engine/field-helpers.ts — headless has no dependency
@@ -459,7 +458,7 @@ export function computeEditViewModel(input) {
         });
         // The boot-validator rejects declared-empty sections (screens.ts), but a
         // create-excluded field list can still empty one here: then `visible` is false.
-        const visible = fields.some((field) => field.visible);
+        const visible = hasVisibleContent(fields, sectionSpec.actions, values);
         // Tabs mode renders this section as its own panel, where two columns reads
         // better than the single-column default a stacked form keeps. Applies to
         // entityEdit tabs as well since fw#3134, not just projectionDetail.

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

@@ -2,7 +2,7 @@ import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/
 import type { ListViewModel, Translate } from "./types.ts";
 export type ComputeListViewModelInput = {
     readonly screen: EntityListScreenDefinition;
-    readonly entity: EntityDefinition;
+    readonly entity: Pick<EntityDefinition, "fields" | "derivedFields">;
     readonly rows: readonly Readonly<Record<string, unknown>>[];
     readonly translate: Translate;
     readonly featureName: string;

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

@@ -113,15 +113,11 @@ export function computeListViewModel(input) {
         // sein. parseRefTarget gibt (featureName, entityName), der
         // Renderer baut die Lookup-QN als
         // `<refFeature>:query:<refEntity>:list`.
-        const refRaw = fieldDef.type === "reference"
-            ? fieldDef.entity
-            : undefined;
+        const refRaw = fieldDef.type === "reference" ? fieldDef.entity : undefined;
         const refTarget = refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined;
         const refEntity = refTarget?.entityName;
         const refFeature = refTarget?.featureName;
-        const refLabelField = fieldDef.type === "reference"
-            ? (fieldDef.labelField ?? "id")
-            : undefined;
+        const refLabelField = fieldDef.type === "reference" ? (fieldDef.labelField ?? "id") : undefined;
         // For select and multiSelect fields: bake in translated option labels.
         // Convention matches the form path → one translation source for list +
         // form. A missing key returns the key itself per convention; the
@@ -224,6 +220,5 @@ export function buildOptionLabels(translate, keyFor, options) {
 // (ORDER BY safety) and by the UI (column header click indicator). All
 // field types can bear the flag; it's off by default.
 function fieldIsSortable(field) {
-    const flag = field.sortable;
-    return flag === true;
+    return "sortable" in field && field.sortable === true;
 }

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { AppSchema, FeatureSchema, QualifiedContentCollection, WorkspaceSch
 export { isAppSchema, toAppSchema } from "./app/feature-schema.ts";
 export { HeaderActionsBar } from "./app/header-actions-bar.tsx";
 export type { KumikoScreenProps } from "./app/kumiko-screen.tsx";
-export { KumikoScreen, qualifyNavId, qualifyScreenId, ScreenMissingState, } from "./app/kumiko-screen.tsx";
+export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.tsx";
 export type { DateRangeBound, DateRangeValue, ResolvedDateRangeFacet } from "./app/list-facets.ts";
 export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.ts";
 export type { NavApi, NavigateOptions, NavProviderProps, NavRoute, NavTarget, ObjectTarget, ScreenTarget, } from "./app/nav.tsx";
@@ -31,6 +31,7 @@ export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, use
 export { lastSegment } from "./app/qn.ts";
 export type { ReturnHost, ReturnTo } from "./app/return-to.tsx";
 export { navigateToReturn, navigateToReturnOr, navigateWithReturnTo, RETURN_TO_PARAM, ReturnHostProvider, resolveReturnTarget, splitReturnTo, useReturnHost, useReturnTarget, } from "./app/return-to.tsx";
+export { ScreenMissingState } from "./app/screen-shared.tsx";
 export type { EmbeddedScreenTarget } from "./app/use-embedded-screen.ts";
 export { useEmbeddedScreen } from "./app/use-embedded-screen.ts";
 export { useRecordActions } from "./app/use-record-actions.ts";

package/dist/index.js

@@ -1,8 +1,7 @@
 // Platform-agnostic React renderer for Kumiko screens. Das ist der
-// Shared-Layer: Components, Hooks, Contexts, Types. Plattform-Impls
-// (Web-DOM, React-Native) leben in den jeweiligen Plattform-Packages
-// und reichen ihre konkreten Primitives/Nav/SSE-Impls via Provider
-// in diesen Baum.
+// Shared-Layer: Components, Hooks, Contexts, Types. Die Web-DOM-Impls
+// leben unter ./web und reichen ihre konkreten Primitives/Nav/SSE-Impls via
+// Provider in diesen Baum.
 //
 // Direct consumers of this layer: platform bindings
 // (@cosmicdrift/kumiko-renderer/web) or an app writing its own bootstrap.
@@ -22,11 +21,12 @@ export { ExtensionFormRegistryProvider, useExtensionFormSubmit, } from "./app/ex
 export { ExtensionSectionsProvider, extensionSectionName, useExtensionSectionComponent, } from "./app/extension-sections.js";
 export { isAppSchema, toAppSchema } from "./app/feature-schema.js";
 export { HeaderActionsBar } from "./app/header-actions-bar.js";
-export { KumikoScreen, qualifyNavId, qualifyScreenId, ScreenMissingState, } from "./app/kumiko-screen.js";
+export { KumikoScreen, qualifyNavId, qualifyScreenId } from "./app/kumiko-screen.js";
 export { buildDateRangePayload, clampDateRange, readDateRange, resolveDateRangeFacets, } from "./app/list-facets.js";
 export { formatPath, hasDetailScreen, NavProvider, parsePath, resolveTarget, useNav, useNavigateWithInitialValues, useOptionalNav, } from "./app/nav.js";
 export { lastSegment } from "./app/qn.js";
 export { navigateToReturn, navigateToReturnOr, navigateWithReturnTo, RETURN_TO_PARAM, ReturnHostProvider, resolveReturnTarget, splitReturnTo, useReturnHost, useReturnTarget, } from "./app/return-to.js";
+export { ScreenMissingState } from "./app/screen-shared.js";
 export { useEmbeddedScreen } from "./app/use-embedded-screen.js";
 export { useRecordActions } from "./app/use-record-actions.js";
 export { VariableChips } from "./app/variable-chips.js";

package/dist/live/error-mapping.js

@@ -1,4 +1,5 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { rendererWarn } from "../dev-console.js";
 // Narrow cast into the DispatcherError shape. Pass-through for everything
 // except `details.fields`, which we normalize: the server uses
 // ValidationFieldIssue (path/code/i18nKey/params), which is structurally
@@ -33,16 +34,14 @@ function normalizeDetails(details) {
             // Server sent a non-object entry in details.fields — contract
             // breach (ValidationFieldIssue shape is required). Warn so the
             // skip doesn't hide a broken server build.
-            // biome-ignore lint/suspicious/noConsole: ops-visible warning when the server breaks the validation-error contract
-            console.warn("[dispatcher-live] dropping malformed field issue (not an object):", r);
+            rendererWarn("[dispatcher-live] dropping malformed field issue (not an object):", r);
             continue;
         }
         if (typeof r["path"] !== "string" ||
             typeof r["code"] !== "string" ||
             typeof r["i18nKey"] !== "string") {
             // Entry is an object but missing required keys — same reasoning.
-            // biome-ignore lint/suspicious/noConsole: ops-visible warning when the server breaks the validation-error contract
-            console.warn("[dispatcher-live] dropping malformed field issue (missing keys):", r);
+            rendererWarn("[dispatcher-live] dropping malformed field issue (missing keys):", r);
             continue;
         }
         mappedFields.push({