@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

package/dist/components/render-edit.js

@@ -0,0 +1,1169 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { evalFieldCondition, isFieldsEditSection, normalizeEditField, PROJECTION_DETAIL_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { computeEditViewModel } from "@cosmicdrift/kumiko-headless";
+import { RenderEditActionButton } from "./render-edit-action-button.js";
+import { AllFieldsRequiredProvider } from "./render-field.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ExtensionFormRegistryProvider, useExtensionFormHost, } from "../app/extension-form-submit.js";
+import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
+import { useOptionalDispatcher } from "../context/dispatcher-context.js";
+import { useDraftStorage } from "../context/draft-storage-context.js";
+import { formatWhen } from "../format-when.js";
+import { useForm } from "../hooks/use-form.js";
+import { useTranslation } from "../i18n.js";
+import { useInsideDrawer } from "../inside-drawer.js";
+import { usePageHeaderSlotAvailable } from "../page-header-slot.js";
+import { STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
+import { GridCellForField } from "./grid-cell-for-field.js";
+import { RelatedListSection } from "./related-list-section.js";
+import { filterEditSections, hasEditableSection, hasIssueWithoutRenderedField, resolveExtensionEntityId, shouldNotifyCaller, } from "./render-edit-logic.js";
+import { WriteFormSection } from "./write-form-section.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/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 dispatcher-live.ts's generateRequestId.
+function mintDraftId() {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function")
+        return c.randomUUID();
+    return `draft-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+// End-to-end renderer für einen entityEdit screen. Rendert aus-
+// schließlich über Primitives — kein raw HTML. Ein Native-Renderer
+// der dieselbe Primitives-Registry füllt kriegt das Form ohne weitere
+// Änderungen.
+function toConditionValue(cond) {
+    if (typeof cond === "boolean")
+        return cond;
+    // @cast-boundary form-values: TValues ist strukturell ein Record.
+    return (values) => evalFieldCondition(cond, values);
+}
+// Tab-strip key. The boot-validator makes `id` mandatory on a tabs layout and
+// entityEdit only ever has "fields"/"extension" sections (relatedList and
+// writeForm are rejected outright), so the positional fallback is unreachable
+// for a tabs screen — it only keeps this total for other layouts.
+function tabIdAt(section, index) {
+    const declared = section?.kind === "fields" || section?.kind === "extension" ? section.id : undefined;
+    return declared ?? `section-${index}`;
+}
+function deriveFormFields(screen) {
+    const out = {};
+    for (const section of screen.layout.sections) {
+        // relatedList carries no `fields` for the form-condition map either.
+        if (!isFieldsEditSection(section))
+            continue;
+        for (const spec of section.fields) {
+            const normalized = normalizeEditField(spec);
+            out[normalized.field] = {
+                ...(normalized.visible !== undefined && {
+                    visible: toConditionValue(normalized.visible),
+                }),
+                ...(normalized.readOnly !== undefined && {
+                    readonly: toConditionValue(normalized.readOnly),
+                }),
+                ...(normalized.required !== undefined && {
+                    required: toConditionValue(normalized.required),
+                }),
+            };
+        }
+    }
+    return out;
+}
+// Resolves an extension-section's `{ react: { __component: "X" } }` marker
+// to a registered React component via ExtensionSectionsProvider (filled in
+// createKumikoApp from clientFeatures.extensionSectionComponents) and
+// mounts it with the host entity name + id. Hook lives in its own
+// component so we don't call `use*` inside vm.sections.map (rules-of-
+// hooks would punish reordering sections between renders).
+function ExtensionSectionMount({ section, entityName: hostEntityName, entityId, initialValues, values, patch, validate, hideTitle, actions, }) {
+    const { Banner, FillContainer, Section, Text } = usePrimitives();
+    const name = extensionSectionName(section.component);
+    const Component = useExtensionSectionComponent(name);
+    const testId = `section-extension-${section.title}`;
+    if (Component === undefined) {
+        const placeholder = (_jsx(Banner, { variant: "info", testId: `section-extension-placeholder-${section.title}`, children: _jsxs(Text, { children: ["Extension section component ", _jsx(Text, { variant: "code", children: name ?? "(no __component name)" }), " ", "not registered in clientFeatures.extensionSectionComponents."] }) }));
+        // Tabs mode already frames this in the caller's own Card — a Section
+        // here would add a second, unwanted divider inset (px-6 py-4) on top of
+        // the Card's own padding, misaligning this tab's content against the
+        // fields tab (Grid sits directly in the Card there). FillContainer keeps
+        // the testId without adding chrome (same primitive RelatedListSection
+        // uses for its own hideTitle branch).
+        return hideTitle === true ? (FillContainer !== undefined ? (_jsx(FillContainer, { testId: testId, children: placeholder })) : (placeholder)) : (_jsx(Section, { title: section.title, testId: testId, children: placeholder }, section.title));
+    }
+    const mounted = (_jsx(Component, { entityName: section.entityName ?? hostEntityName, entityId: entityId, initialValues: initialValues, values: values, patch: patch, validate: validate }));
+    // Same reasoning as the placeholder branch above: tabs mode's outer Card
+    // is the only frame this content gets, no nested Section divider.
+    return hideTitle === true ? (FillContainer !== undefined ? (_jsx(FillContainer, { testId: testId, children: mounted })) : (mounted)) : (_jsx(Section, { ...(actions !== undefined && { actions }), title: section.title, testId: testId, children: mounted }));
+}
+// Resolves an entityEdit slot's (`screen.slots.header` / `.footer`)
+// `{ react: { __component: "X" } }` marker via the same ExtensionSectionsProvider
+// registry as ExtensionSectionMount / ListHeaderSlotMount and mounts it. One
+// component for both slots — header passes no hasUnsavedChanges/wizardStep,
+// footer does. Own component for rules-of-hooks (useExtensionSectionComponent
+// must not run conditionally inside RenderEdit's render body).
+function EditSlotMount({ slot, slotName, screenId, entityName, entityId, values, hasUnsavedChanges, wizardStep, }) {
+    const name = extensionSectionName(slot);
+    const Component = useExtensionSectionComponent(name);
+    useEffect(() => {
+        if (name !== undefined && Component === undefined) {
+            // biome-ignore lint/suspicious/noConsole: dev warning for a setup error
+            console.warn(`[kumiko] Edit ${slotName} slot component "${name}" on screen "${screenId}" is not registered in clientFeatures.extensionSectionComponents — the ${slotName} slot renders nothing.`);
+        }
+    }, [name, Component, screenId, slotName]);
+    if (Component === undefined)
+        return null;
+    return (_jsx(Component, { entityName: entityName, entityId: entityId, values: values, ...(hasUnsavedChanges !== undefined && { hasUnsavedChanges }), ...(wizardStep !== undefined && { wizardStep }) }));
+}
+function formSectionDomId(sectionIndex) {
+    return `form-section-${sectionIndex}`;
+}
+export function RenderEdit(props) {
+    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, onDirtyChange, onCopyLink, actions, onRelatedListDrawerAction, submitLabel, submitVariant, summary, labelAppendix, fieldAppendix, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, headerRegion, buildSectionActions, } = props;
+    const { customSubmit } = props;
+    // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
+    // konsumieren wir den i18next-Context direkt. Sonst wären Field-
+    // Labels ohne Caller-Wiring raw-Keys (`feature:entity:foo:field:title`).
+    // useTranslation throwt ohne LocaleProvider — das ist ok, weil RenderEdit
+    // ohnehin nur in einem mounted Kumiko-App-Tree läuft.
+    const t = useTranslation();
+    const translate = translateProp ?? t;
+    const dispatcher = useOptionalDispatcher();
+    const isWizard = screen.layout.mode === "wizard";
+    // Tabs reuse the wizard's step machinery: one section visible at a time,
+    // all of them mounted, `currentStep` as the active index. What they do NOT
+    // share is navigation — a tab form submits from any tab, so every
+    // step-transition path below stays wizard-only (fw#3134).
+    const isTabs = screen.layout.mode === "tabs";
+    const draftEnabled = isWizard && screen.layout.draft === true && dispatcher !== undefined;
+    const isCreateMode = entityIdProp === undefined || entityIdProp === null || entityIdProp === "";
+    const draftStorage = useDraftStorage();
+    const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
+    const [linkCopied, setLinkCopied] = useState(false);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [formError, setFormError] = useState(null);
+    // One state for all header actions (actions?), not per-button — only one
+    // action can be in flight at a time, and this keeps the error surfaced in
+    // the shared formError-adjacent banner region instead of inside the
+    // button row (fw#2166 review: a full-width Banner there breaks the
+    // flex justify-end action bar).
+    const [actionError, setActionError] = useState(null);
+    const [rawStep, setRawStep] = useState(0);
+    // 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 `${screen.id}:${entityIdProp}` unconditionally.
+    const [draftId, setDraftId] = useState(() => isCreateMode ? draftStorage.getDraftId(screen.id) : 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);
+    // Composed-Save: Extension-Sections melden hier ihren dirty-State (damit der
+    // Save-Button aktiv wird wenn NUR eine Section geändert wurde) + ihren
+    // Submit-Handler (läuft nach dem Entity-Write). extensionErrorKey hält den
+    // i18n-Key einer fehlgeschlagenen Section-Persistierung.
+    //
+    // Not a second write path for saveDraft()'s data (#1914): deriveFormFields
+    // (above) skips extension sections entirely, so extension-owned field state
+    // never enters `fields`/`controller.getSnapshot().values` — there is no
+    // draft-blob-covered state left for persistExtensions() to compete over.
+    const [extensionDirty, setExtensionDirty] = useState(false);
+    const [hasExtensionRegistrations, setHasExtensionRegistrations] = useState(false);
+    const [extensionErrorKey, setExtensionErrorKey] = useState(null);
+    const { registry: extensionFormRegistry, runAll: runExtensionSubmits } = useExtensionFormHost(({ anyDirty, hasRegistrations }) => {
+        setExtensionDirty(anyDirty);
+        setHasExtensionRegistrations(hasRegistrations);
+    });
+    const { Button, Banner, Card, Dialog, Form, Section, Grid, GridCell, Text, Progress, StepBar, WizardStepGroup, Tabs, PageHeader, ActionOverflowMenu, } = usePrimitives();
+    const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+    const insideDrawer = useInsideDrawer();
+    // Both stepped layouts show one section at a time and keep the rest mounted
+    // but inert. A tabs layout on a host without the Tabs primitive has no strip
+    // to switch with, so it falls back to rendering every section stacked rather
+    // than stranding the user on section 0 (fw#3134).
+    const isStepped = isWizard || (isTabs && Tabs !== undefined);
+    const fields = useMemo(() => deriveFormFields(screen), [screen]);
+    // Must be computed before submitConfig/useForm bakes it in (the controller
+    // freezes it on first render). This is the unfiltered field-name set from
+    // `fieldsFilter` ∩ `fields` — not the value-dependent `filteredSections`
+    // (which also drops `section.visible === false`). Hidden fields still fall
+    // out via form-controller's `hiddenFields` path. undefined = unscoped, since
+    // scoping would silently drop root-level .refine() issues.
+    // A `fieldsFilter` that matches nothing in `fields` (typo, renamed field)
+    // must fall back to unscoped too — an empty scope array would filter out
+    // ALL validation issues (kumiko-framework#1907), letting submit() through
+    // unvalidated on a form that also renders no sections.
+    const scopeFieldNames = useMemo(() => {
+        if (fieldsFilter === undefined)
+            return undefined;
+        const matched = fieldsFilter.filter((f) => Object.hasOwn(fields, f));
+        return matched.length === 0 ? undefined : matched;
+    }, [fieldsFilter, fields]);
+    // Submit-Config nur wenn der Caller einen writeCommand mitgibt; bei
+    // customSubmit-Pfad kommt der Form-Controller ohne Submit-Wiring,
+    // weil wir controller.submit() eh nicht rufen.
+    const submitConfig = writeCommand !== undefined
+        ? {
+            type: writeCommand,
+            payloadMode,
+            ...(buildPayload !== undefined && { buildPayload }),
+            ...(serverFieldPathPrefix !== undefined && { serverFieldPathPrefix }),
+            ...(scopeFieldNames !== undefined && { validateScope: scopeFieldNames }),
+        }
+        : undefined;
+    const { controller, snapshot } = useForm({
+        initial,
+        fields,
+        ...(schema !== undefined && { schema }),
+        ...(ctx !== undefined && { ctx }),
+        ...(submitConfig !== undefined && { submit: submitConfig }),
+    });
+    // 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: `${screen.id}:${entityIdProp}`,
+    // unchanged. Create-mode: `${screen.id}: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
+            ? `${screen.id}:new:${draftId}`
+            : undefined
+        : `${screen.id}:${entityIdProp}`, [screen.id, entityIdProp, isCreateMode, draftId]);
+    // Controlled mode (Issue #1887). Both callbacks live in refs so a
+    // re-rendering caller (identity-unstable `onChange`/`onControlsReady`
+    // closures, e.g. inline arrows) doesn't retrigger these effects — only a
+    // real snapshot mutation (typing, patch()) does. Without this, a caller
+    // whose onChange calls patch() to fill other fields (the VIN-decode use
+    // case from #1888) would loop: patch → new snapshot → effect
+    // re-subscribes with a "new" onChange → refires.
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    // Guards against redelivering to the SAME callback identity on every
+    // render (an inline-arrow onControlsReady would otherwise refire the
+    // effect below on every render since the callback itself is now a dep).
+    // Tracks the actual prop, not a ref snapshot, so a caller that swaps in a
+    // real handler after mount (e.g. `onControlsReady={ready ? cb : undefined}`)
+    // gets delivered to for THIS mount instead of never (fw#1899).
+    const deliveredControlsToRef = useRef(undefined);
+    const onControlsReadyRef = useRef(onControlsReady);
+    onControlsReadyRef.current = onControlsReady;
+    const hasNavigatedRef = useRef(false);
+    const submittedRef = useRef(false);
+    const isSubmittingRef = useRef(false);
+    const scopeFieldNamesRef = useRef(scopeFieldNames);
+    scopeFieldNamesRef.current = scopeFieldNames;
+    const scopedValidate = useCallback(() => controller.validate(scopeFieldNamesRef.current), [controller]);
+    // `saveDraft` (defined below) is a fresh closure every render, over that
+    // render's `draftKey`/`draftId` — the ref lets the debounce timer below
+    // always call the CURRENT one even though the timer was scheduled by an
+    // earlier render's patch() call. `currentStepRef` gives it the current
+    // wizard step without depending on `currentStep` (computed further down,
+    // from `filteredSections`) at the point patchAndScheduleDraftSave itself
+    // is defined — kept fresh where `currentStep` is computed below.
+    const saveDraftRef = useRef(saveDraft);
+    saveDraftRef.current = saveDraft;
+    // `handleSubmit` (defined below) is a fresh closure over this render's
+    // snapshot/extensionDirty, while the onControlsReady effect fires once per
+    // mount — the ref lets controls.submit() always reach the current one.
+    const handleSubmitRef = useRef(async () => { });
+    const currentStepRef = useRef(0);
+    const draftSaveTimerRef = useRef(null);
+    useEffect(() => {
+        return () => {
+            if (draftSaveTimerRef.current !== null) {
+                clearTimeout(draftSaveTimerRef.current);
+                // Flush the pending debounced save instead of dropping it — a
+                // navigation/unmount inside the debounce window would otherwise
+                // silently discard the last patch() (discardDraft nulls this ref
+                // first on the post-submit path, so this can't resurrect a
+                // just-submitted draft).
+                saveDraftRef.current(currentStepRef.current);
+            }
+        };
+    }, []);
+    // patch() (controlled mode, extension sections) applies immediately —
+    // only the resulting draft save is debounced (#1914), so a patch() burst
+    // (VIN-decode filling several fields, or onChange fanning a keystroke out
+    // through patch(), see the #1888 test above) collapses into one save.
+    const patchAndScheduleDraftSave = useCallback((partial) => {
+        controller.setValues(partial);
+        if (!draftEnabled || dispatcher === undefined || disabled || submittedRef.current)
+            return;
+        if (draftSaveTimerRef.current !== null)
+            clearTimeout(draftSaveTimerRef.current);
+        draftSaveTimerRef.current = setTimeout(() => {
+            draftSaveTimerRef.current = null;
+            if (disabled || submittedRef.current)
+                return;
+            saveDraftRef.current(currentStepRef.current);
+        }, PATCH_DRAFT_SAVE_DEBOUNCE_MS);
+    }, [controller, draftEnabled, dispatcher, disabled]);
+    // Runs before the onChange effect below (declaration order = React
+    // execution order) so that an onChange fired on mount always sees
+    // `controls !== undefined` — both effects depend only on mount-stable
+    // values (controller/scopedValidate/patchAndScheduleDraftSave), so the
+    // swap is otherwise a no-op. See the #1888 VIN-decode test: an initial
+    // value that should derive dependent fields on mount needs controls.patch
+    // available on the very first onChange call, not just from the second
+    // keystroke onward.
+    const hasControlsReady = onControlsReady !== undefined;
+    useEffect(() => {
+        if (!hasControlsReady)
+            return;
+        const ready = onControlsReadyRef.current;
+        if (ready === undefined)
+            return;
+        if (deliveredControlsToRef.current === ready)
+            return;
+        deliveredControlsToRef.current = ready;
+        ready({
+            patch: patchAndScheduleDraftSave,
+            validate: scopedValidate,
+            getValues: () => controller.getSnapshot().values,
+            submit: () => handleSubmitRef.current(),
+        });
+        // Dep on boolean presence only — inline-arrow identity must not redeliver.
+    }, [hasControlsReady, controller, scopedValidate, patchAndScheduleDraftSave]);
+    // `schema` is typically an inline caller prop (`schema={z.object({...})}`)
+    // with unstable identity across renders — as an effect dep it would refire
+    // on every parent render, not just on a snapshot change, risking a loop if
+    // the caller's onChange triggers a parent re-render. Held in a ref like
+    // onChangeRef so only a real snapshot mutation retriggers this effect.
+    const schemaRef = useRef(schema);
+    schemaRef.current = schema;
+    // Controls are guaranteed ready by the time this fires (see the
+    // onControlsReady effect above, which is declared first on purpose).
+    useEffect(() => {
+        const cb = onChangeRef.current;
+        if (cb === undefined)
+            return;
+        // Dry-run parse against `schema` — NOT controller.validate(). Calling
+        // validate() here would write field-level errors into snapshot.errors
+        // on every keystroke, painting error messages while the user is still
+        // typing. `valid` can therefore legitimately diverge from what's
+        // currently rendered under the fields (the last *mutating* validate()
+        // call, e.g. from controls.validate() or submit()).
+        const currentSchema = schemaRef.current;
+        const valid = currentSchema === undefined ? true : currentSchema.safeParse(snapshot.values).success;
+        cb({
+            values: snapshot.values,
+            changes: snapshot.changes,
+            dirty: snapshot.isDirty,
+            valid,
+            submitting: isSubmitting,
+        });
+    }, [snapshot, isSubmitting]);
+    const onDirtyChangeRef = useRef(onDirtyChange);
+    onDirtyChangeRef.current = onDirtyChange;
+    const hasUnsavedInput = snapshot.isDirty || extensionDirty;
+    useEffect(() => {
+        onDirtyChangeRef.current?.(hasUnsavedInput);
+    }, [hasUnsavedInput]);
+    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-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) {
+                // biome-ignore lint/suspicious/noConsole: draft restore must not red-screen the form
+                console.warn("render-edit: draft restore query failed", err);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [draftEnabled, draftKey, draftId, dispatcher, controller]);
+    // 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(() => {
+        // 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).
+        if (!draftEnabled ||
+            !isCreateMode ||
+            draftId !== null ||
+            didListRef.current ||
+            dispatcher === undefined)
+            return;
+        let cancelled = false;
+        void (async () => {
+            try {
+                const result = await dispatcher.query(FORM_DRAFT_LIST, { screenId: screen.id });
+                // 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(screen.id);
+                // 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) {
+                // biome-ignore lint/suspicious/noConsole: draft lookup must not red-screen the form
+                console.warn("render-edit: draft list query failed", err);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [draftEnabled, isCreateMode, draftId, dispatcher, screen.id]);
+    // 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.
+        if (disabled)
+            return;
+        const adoptedId = candidate.draftKey.slice(newDraftPrefix(screen.id).length);
+        draftStorage.setDraftId(screen.id, adoptedId);
+        setDraftId(adoptedId);
+        setDraftCandidates(null);
+    }
+    const vm = useMemo(() => computeEditViewModel({
+        screen,
+        entity,
+        values: snapshot.values,
+        translate,
+        featureName,
+    }), [screen, entity, snapshot.values, translate, featureName]);
+    const filteredSections = useMemo(
+    // A fully-hidden "fields" section (every field in it currently
+    // condition-hidden) must not occupy a wizard step; it would render
+    // empty and block Back/Next on nothing. Extension, relatedList and
+    // writeForm sections carry no `visible` (they own their own lifecycle /
+    // run their own query / own submit), so they always pass through. A
+    // section with no fields at all (e.g. a review-only step) has
+    // `visible: fields.some(...)` = false vacuously; that's "no fields to
+    // hide", not "hidden", so it stays too (fw#1901).
+    () => filterEditSections(vm.sections, fieldsFilter).filter((section) => section.kind === "extension" ||
+        section.kind === "relatedList" ||
+        section.kind === "writeForm" ||
+        section.fields.length === 0 ||
+        section.visible), [vm.sections, fieldsFilter]);
+    const allFieldsRequired = useMemo(() => {
+        const fillable = filteredSections.flatMap((section) => section.kind === "fields"
+            ? section.fields.filter((field) => field.visible && !field.readOnly)
+            : []);
+        return fillable.length > 0 && fillable.every((field) => field.required);
+    }, [filteredSections]);
+    const showsAllRequiredHint = allFieldsRequired && hideSectionTitles !== true && !isWizard;
+    // true when editable fields exist or an extension opted into composed submit (fw#2359).
+    const isFormEditable = hasEditableSection(filteredSections);
+    // A fieldless form (input-less secretMint mint, fw#2838 — the secret is
+    // server-generated, the mint step is only its submit button) has no
+    // section to gate on: it IS the action, so it always shows the submit
+    // button, and it can never go dirty either.
+    const isFieldless = Object.keys(entity.fields).length === 0;
+    // A lone relatedList tab (`hideSectionTitles` is only ever set by
+    // ProjectionDetailBody, which hands this component ONE section — its
+    // synthesized screen drops layout.mode, so an entityEdit tabs layout never
+    // reaches this line and `filteredSections[0]` stays the active section)
+    // needs its own tab panel capped at the available height so its table
+    // scrolls inside the panel instead of the whole page stretching to the
+    // row count (fw#2722) — a short table still sizes to its content instead
+    // of stretching the panel to the bottom (fw#2778). Any other layout —
+    // multiple sections, a non-relatedList tab, stacked (non-tabs) forms —
+    // keeps normal document-flow height untouched.
+    const fillHeight = fillScreenHeight === true ||
+        (hideSectionTitles === true && filteredSections[0]?.kind === "relatedList");
+    // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
+    // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
+    // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
+    async function persistExtensions() {
+        const entityId = resolveExtensionEntityId(entityIdProp, vm.id);
+        if (entityId === null)
+            return true;
+        const results = await runExtensionSubmits({ entityId });
+        const failed = results.find((r) => !r.isSuccess);
+        if (failed !== undefined) {
+            setExtensionErrorKey(failed.errorKey ?? "kumiko.form.extension.save-failed");
+            return false;
+        }
+        return true;
+    }
+    const lastStepIndex = Math.max(filteredSections.length - 1, 0);
+    // Clamped on read, not on write: section visibility is value-dependent, so a
+    // stored stepIndex can point past what is currently rendered — that lands on
+    // the last step instead of an empty one.
+    const currentStep = Math.min(rawStep, lastStepIndex);
+    // Kept fresh for patchAndScheduleDraftSave's debounce timer above, which
+    // is defined before `currentStep` exists (it depends on `filteredSections`,
+    // computed further up from `vm`) and so cannot close over it directly.
+    currentStepRef.current = currentStep;
+    const isLastWizardStep = currentStep >= lastStepIndex;
+    // 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(screen.id, mintedId);
+            setDraftId(mintedId);
+            key = `${screen.id}: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) {
+            // biome-ignore lint/suspicious/noConsole: no error-surfacing path exists for a fire-and-forget draft save.
+            console.warn(`RenderEdit: draftKey "${key}" is ${key.length} chars, over the server's ${FORM_DRAFT_KEY_MAX_LENGTH}-char limit — skipping this draft save. Shorten screen.id or entity id.`);
+            return;
+        }
+        const passwordFieldNames = new Set(vm.sections.flatMap((section) => section.kind === "fields"
+            ? section.fields.filter((f) => f.format === "password").map((f) => f.field)
+            : []));
+        // A password 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]) => !passwordFieldNames.has(field)));
+        void dispatcher
+            .write(FORM_DRAFT_SAVE, {
+            draftKey: key,
+            values: draftValues,
+            stepIndex,
+        })
+            .catch((err) => {
+            // biome-ignore lint/suspicious/noConsole: fire-and-forget draft save must not red-screen
+            console.warn("render-edit: draft save failed", err);
+        });
+    }
+    // Next: scoped validate() on the current step's fields — errors stay
+    // attached to the field and block the step transition. Extension steps
+    // have no field scope here (they validate via the controlled-mode
+    // controls.validate() API), so no call, no clearing of unrelated errors.
+    function handleWizardNext() {
+        const next = Math.min(currentStep + 1, lastStepIndex);
+        hasNavigatedRef.current = true;
+        // Locked state (#1896): `disabled` means "no input/no write", not "no
+        // navigation" — a disabled wizard must still be steppable so Back/Next
+        // reach every step. But neither validate() (would block on an empty
+        // required field nobody can fill in) nor saveDraft() (would mint a
+        // draftId / dispatch a write — exactly what `disabled` forbids) may run.
+        if (disabled) {
+            setRawStep(next);
+            return;
+        }
+        const section = filteredSections[currentStep];
+        const fieldNames = section?.kind === "fields" ? section.fields.map((f) => f.field) : [];
+        // skip: the current step has field errors — no transition, no draft save.
+        if (fieldNames.length > 0 && !controller.validate(fieldNames))
+            return;
+        setRawStep(next);
+        saveDraft(next);
+    }
+    function handleWizardBack() {
+        handleWizardJumpBack(currentStep - 1);
+    }
+    // Only backwards: a forward jump would skip the per-step validate() gate.
+    function handleWizardJumpBack(targetStep) {
+        if (targetStep >= currentStep)
+            return;
+        const previous = Math.max(targetStep, 0);
+        hasNavigatedRef.current = true;
+        if (disabled) {
+            setRawStep(previous);
+            return;
+        }
+        setRawStep(previous);
+        saveDraft(previous);
+    }
+    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(screen.id);
+            mintedDraftIdRef.current = null;
+            setDraftId(null);
+        }
+    }
+    // Stepped modes (wizard, tabs): locates the first step whose "fields"
+    // section contains one of the given field paths — matched on the path's
+    // first segment, since `FieldIssue.path`/`snapshot.errors` keys can be
+    // dotted (embedded-list rows, e.g. `tasks.2.title`) while a section's field
+    // name is always the plain top-level name. Returns undefined for a
+    // root-level issue (path `"(root)"`, see zod-bridge.ts) or one that matches
+    // no rendered field — callers must NOT suppress the error banner in that
+    // case, there is nowhere to jump the user to. Extension sections are not
+    // jump targets by design: they validate through the controlled-mode
+    // controls.validate() API and own no field specs to match against.
+    function findFirstErroringStep(fieldPaths) {
+        const erroredFields = new Set(fieldPaths.map((p) => p.split(".")[0]));
+        const idx = filteredSections.findIndex((s) => s.kind === "fields" && s.fields.some((f) => erroredFields.has(f.field)));
+        return idx === -1 ? undefined : idx;
+    }
+    async function handleSubmit(options) {
+        // Enter in the active step triggers the native form submit (Next is
+        // type="submit" for Enter support) — on intermediate steps that means
+        // "Next", not "Save". Checked BEFORE the `disabled` guard below:
+        // `disabled` means "no input/no write", not "no navigation" — a
+        // disabled wizard must still be steppable (handleWizardNext itself
+        // blocks validate()/saveDraft() while disabled). `saveNow` is the explicit
+        // "Save and close" button and skips the step advance.
+        if (isWizard && !isLastWizardStep && options?.saveNow !== true) {
+            handleWizardNext();
+            return;
+        }
+        // Locked state (#1896): the submit button is visibly disabled, but a
+        // native form submit (Enter key) reaches this handler regardless of the
+        // button's disabled attribute — block it here too, not just in the UI.
+        if (disabled)
+            return;
+        // Sync guard — React state `isSubmitting` is too late for double-clicks
+        // in the same tick (customSubmit has no submitInFlight of its own).
+        if (isSubmittingRef.current)
+            return;
+        isSubmittingRef.current = true;
+        setIsSubmitting(true);
+        setExtensionErrorKey(null);
+        try {
+            // Extension-only: only a section is dirty, the main form is unchanged.
+            // No entity write (would send an empty changes payload) — only
+            // die Section-Handler laufen lassen.
+            if (snapshot.isUnchanged && extensionDirty) {
+                // Same discard as the main path: an extension-only save is still a
+                // successful submit, so the draft must not survive it.
+                if (await persistExtensions()) {
+                    submittedRef.current = true;
+                    await discardDraft();
+                }
+                return;
+            }
+            let result;
+            if (customSubmit !== undefined) {
+                // customSubmit path (e.g. configEdit, which fires a separate write
+                // per field). Client-side validation first, then
+                // an den Caller; on-success rebased der Form-State explizit
+                // because controller.submit() normally does this itself and
+                // without customSubmit's help the controller knows nothing about
+                // erfolgreichen Submit (isUnchanged blieb sonst false).
+                //
+                // WICHTIG: snapshot direkt vom Controller holen statt aus
+                // React state. On rapid fill→click, React batching may not have
+                // committed input state updates yet when the submit click fires.
+                // handleSubmit's closure would then run with
+                // stale snapshot.changes={} laufen, customSubmit fired keine
+                // Writes, returnt success, Form rebase → User glaubt "saved"
+                // aber gar nichts ist passiert. controller.getSnapshot() ist
+                // immer aktuell — der Controller ist die Source-of-Truth, die
+                // React state is only a mirror for rendering.
+                const valid = controller.validate(scopeFieldNames);
+                if (!valid) {
+                    // Field order matters: validationBlocked:true is its own
+                    // variant in the SubmitResult union (NOT mixed with data/error);
+                    // TS only narrows cleanly without a discriminator fight.
+                    const blocked = {
+                        validationBlocked: true,
+                        isSuccess: false,
+                    };
+                    result = blocked;
+                }
+                else {
+                    result = await customSubmit(controller.getSnapshot());
+                    if (result.isSuccess)
+                        controller.rebase();
+                }
+            }
+            else {
+                result = await controller.submit();
+            }
+            // Form-level errors (without field-level details) go to the banner.
+            // Field errors flow via snapshot.errors into the individual fields.
+            let extensionsPersisted = true;
+            if (result.isSuccess) {
+                setFormError(null);
+                // `isNoOp: true` (payloadMode "changes", pre-filled form submitted
+                // untouched) means controller.submit() never called dispatcher.write
+                // — nothing to discard, and discarding here would delete a draft the
+                // form never persisted (fw#1978). Awaited, not fire-and-forget:
+                // `onSubmit` typically navigates away and unmounts this form, which
+                // would abort an in-flight discard and leave the draft behind after
+                // a successful submit.
+                if (result.isNoOp !== true) {
+                    submittedRef.current = true;
+                    await discardDraft();
+                }
+                extensionsPersisted = await persistExtensions();
+            }
+            else if (result.validationBlocked) {
+                // Root-level `.refine()`/cross-field issues from controller.validate()
+                // — same "jump to the erroring step" treatment as a server field
+                // error below, sourced from the freshly-validated snapshot.
+                if (isStepped) {
+                    const step = findFirstErroringStep(Object.keys(controller.getSnapshot().errors));
+                    if (step !== undefined)
+                        setRawStep(step);
+                }
+            }
+            else {
+                const fieldIssues = result.error.details?.fields ?? [];
+                const issuePaths = fieldIssues.map((i) => i.path);
+                // A server field error on a step the form isn't currently showing is
+                // otherwise invisible — jump to the first step that contains one of
+                // the errored fields. For tabs this is what keeps the submit from
+                // blocking in silence, the failure mode the boot-validator used to
+                // prevent by rejecting the layout outright (fw#3134). An issue no
+                // rendered field can show (`version`, `id`, a root-level refine, a
+                // hidden field) keeps the banner, jump or not.
+                if (isStepped) {
+                    const step = findFirstErroringStep(issuePaths);
+                    if (step !== undefined)
+                        setRawStep(step);
+                }
+                setFormError(hasIssueWithoutRenderedField(issuePaths, filteredSections) ? result.error : null);
+            }
+            // skip: on entity-success-but-extension-failure the extension-error
+            // banner is showing — don't notify (the caller navigates away on success
+            // and would unmount it before the user sees the failure).
+            if (shouldNotifyCaller(result, extensionsPersisted))
+                onSubmit?.(result);
+        }
+        finally {
+            isSubmittingRef.current = false;
+            setIsSubmitting(false);
+        }
+    }
+    handleSubmitRef.current = handleSubmit;
+    // Screen forms (entityEdit/actionForm filling the shell height) drop the card;
+    // the title then lives in the shell header when the shell offers a slot.
+    const isScreenForm = fillScreenHeight === true &&
+        hideSectionTitles !== true &&
+        headerRegion === undefined &&
+        !insideDrawer;
+    const titleInShell = PageHeader !== undefined &&
+        pageHeaderSlotAvailable &&
+        hideSectionTitles !== true &&
+        headerRegion === undefined;
+    const menuPageHeaderActions = titleInShell && isScreenForm && ActionOverflowMenu !== undefined;
+    const cancelInHeaderMenu = menuPageHeaderActions && isWizard && onCancel !== undefined;
+    // Two groups — wizard navigation on the right/top, record actions on the
+    // left/below; destructive action sits outermost, farthest from the target
+    // action.
+    const hasSecondaryFormActions = (!menuPageHeaderActions && (onDelete !== undefined || onCopyLink !== undefined)) ||
+        (actions !== undefined && actions.length > 0) ||
+        (onCancel !== undefined && !cancelInHeaderMenu);
+    // Teil-C collapse rule: driven by the custom `actions` group only — a
+    // resolved true also folds the Copy-Link button (same visual group in the
+    // footer), but never Delete/Cancel, which keep their text regardless.
+    const iconOnlyMidActions = actions !== undefined && shouldRenderActionsIconOnly(actions);
+    const headerMenuItems = menuPageHeaderActions
+        ? [
+            ...(onCopyLink !== undefined
+                ? [
+                    {
+                        id: "copy-link",
+                        label: translate(linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink"),
+                        icon: "link",
+                        onSelect: () => {
+                            void Promise.resolve(onCopyLink()).then(() => setLinkCopied(true));
+                        },
+                    },
+                ]
+                : []),
+            ...(cancelInHeaderMenu
+                ? [
+                    {
+                        id: "cancel",
+                        label: translate("kumiko.actions.cancel"),
+                        icon: "x",
+                        onSelect: () => onCancel(),
+                    },
+                ]
+                : []),
+            ...(onDelete !== undefined
+                ? [
+                    {
+                        id: "delete",
+                        label: translate("kumiko.actions.delete"),
+                        icon: "trash",
+                        variant: "danger",
+                        onSelect: () => setConfirmDeleteOpen(true),
+                    },
+                ]
+                : []),
+        ]
+        : [];
+    const secondaryFormActions = (_jsxs(_Fragment, { children: [onDelete !== undefined && !menuPageHeaderActions && (_jsx(Button, { type: "button", variant: "danger-ghost", icon: "trash", testId: "render-edit-delete", disabled: disabled, onClick: () => setConfirmDeleteOpen(true), children: translate("kumiko.actions.delete") })), onCopyLink !== undefined && !menuPageHeaderActions && (_jsx(Button, { type: "button", variant: iconOnlyMidActions ? "secondary" : "link", icon: linkCopied ? "check" : "link", testId: "render-edit-copy-link", ...(iconOnlyMidActions && {
+                    size: "icon",
+                    ariaLabel: translate(linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink"),
+                }), onClick: async () => {
+                    await onCopyLink();
+                    setLinkCopied(true);
+                }, children: iconOnlyMidActions
+                    ? null
+                    : translate(linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink") })), actions?.map((action) => (_jsx(RenderEditActionButton, { action: action, iconOnly: iconOnlyMidActions, Button: Button, Dialog: Dialog, onError: setActionError }, action.id))), onCancel !== undefined && !cancelInHeaderMenu && (_jsx(Button, { type: "button", variant: "secondary", onClick: () => onCancel(), testId: "render-edit-cancel", children: translate("kumiko.actions.cancel") }))] }));
+    const headerSlot = screen.slots?.header;
+    const headerSlotMount = headerSlot !== undefined ? (_jsx(EditSlotMount, { slot: headerSlot, slotName: "header", screenId: screen.id, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), values: snapshot.values })) : undefined;
+    // A function headerRegion places the slot itself (projectionDetail puts it
+    // into its header card next to the actions); otherwise the slot renders
+    // above the caller's own headerRegion.
+    const formHeaderRegion = typeof headerRegion === "function" ? (headerRegion(headerSlotMount)) : headerSlotMount !== undefined ? (_jsxs(_Fragment, { children: [headerSlotMount, headerRegion] })) : (headerRegion);
+    const titleActionSlot = screen.slots?.titleAction;
+    const titleActionMount = titleActionSlot !== undefined ? (_jsx(EditSlotMount, { slot: titleActionSlot, slotName: "titleAction", screenId: screen.id, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), values: snapshot.values })) : undefined;
+    // A projectionDetail's synthesized entity is empty when every section is an
+    // extension or relatedList; that is not a fieldless submit form, so it must not
+    // draw a no-op Save. Extension registrations still get their Save, since
+    // persistExtensions() runs on the customSubmit path too.
+    const isFieldlessSubmitForm = isFieldless && screen.entity !== PROJECTION_DETAIL_ENTITY;
+    const showsSubmit = isFormEditable || hasExtensionRegistrations || isFieldlessSubmitForm;
+    const footerSlot = screen.slots?.footer;
+    // Mirrors every branch inside formActions below — without this guard
+    // DefaultForm renders an empty footer strip (border + padding, no content)
+    // on read-only detail screens, since `actions` would otherwise always be
+    // a defined (if empty) fragment.
+    const hasFormActions = (isWizard && currentStep > 0) ||
+        (isWizard && !isLastWizardStep) ||
+        (showsSubmit && (!isWizard || isLastWizardStep)) ||
+        footerSlot !== undefined;
+    const nextStepTitle = isWizard ? filteredSections[currentStep + 1]?.title : undefined;
+    const formActions = (_jsxs(_Fragment, { children: [isWizard && currentStep > 0 && (_jsx(Button, { type: "button", variant: "secondary", icon: "chevron-left", onClick: handleWizardBack, testId: "render-edit-wizard-back", children: translate("kumiko.actions.back") })), footerSlot !== undefined && (_jsx(EditSlotMount, { slot: footerSlot, slotName: "footer", screenId: screen.id, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), values: snapshot.values, hasUnsavedChanges: snapshot.isDirty || extensionDirty, wizardStep: isWizard ? { index: currentStep, isLast: isLastWizardStep } : undefined, ...(screen.slots?.footerPrimary === true && { [STICKY_PRIMARY_ACTION_PROP]: true }) })), isWizard && !isLastWizardStep && showsSubmit && !isCreateMode && (_jsx(Button, { type: "button", variant: "ghost", disabled: isSubmitting || disabled, onClick: () => void handleSubmit({ saveNow: true }), testId: "render-edit-wizard-save-close", [STICKY_PRIMARY_ACTION_PROP]: true, children: translate("kumiko.wizard.save-and-close") })), isWizard && !isLastWizardStep && (_jsx(Button, { type: "submit", variant: "primary", iconEnd: "chevron-right", testId: "render-edit-wizard-next", children: nextStepTitle !== undefined
+                    ? translate("kumiko.wizard.next-with-title", { title: nextStepTitle })
+                    : translate("kumiko.actions.next") })), showsSubmit && (!isWizard || isLastWizardStep) && (_jsx(Button, { type: "submit", disabled: (snapshot.isUnchanged && !extensionDirty && !isFieldless && !insideDrawer) ||
+                    isSubmitting ||
+                    disabled, loading: isSubmitting, variant: submitVariant ?? "primary", testId: "render-edit-submit", children: translate(submitLabel ?? (isWizard ? "kumiko.actions.finish" : "kumiko.actions.save")) }))] }));
+    // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
+    //   screen:<id>.<mode>.title / .<mode>.subtitle
+    // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
+    // title falls back to screenId; subtitle falls back to screen.description,
+    // itself run through translate() so an i18n key (the established
+    // convention for description, e.g. bundled-features) resolves instead of
+    // showing the raw key — translate() returns the input unchanged for plain
+    // prose, same as it does for an unknown key (fw#2723 review). Same slot
+    // section.description already fills for a section. Falls back to
+    // undefined (no subtitle) when neither is set.
+    const isCreate = (() => {
+        const id = resolveExtensionEntityId(entityIdProp, vm.id);
+        return id == null || id === "";
+    })();
+    const formMode = isCreate ? "create" : "edit";
+    const resolveScreenText = (suffix) => {
+        for (const key of [
+            `screen:${screen.id}.${formMode}.${suffix}`,
+            `screen:${screen.id}.${suffix}`,
+        ]) {
+            const value = translate(key);
+            if (value !== key)
+                return value;
+        }
+        return undefined;
+    };
+    const formTitle = resolveScreenText("title") ?? screen.id;
+    // screen.description is head-card copy, not tab content — in tabs mode
+    // (hideSectionTitles) the head card already carries title/subtitle/status.
+    const formSubtitle = hideSectionTitles !== true
+        ? (resolveScreenText("subtitle") ??
+            (screen.description !== undefined ? translate(screen.description) : undefined))
+        : undefined;
+    const usesFieldFlow = isScreenForm || insideDrawer;
+    const allRequiredHint = (_jsx(Text, { variant: "muted", testId: "render-edit-all-required-hint", children: translate("kumiko.form.all-required") }));
+    const stepRail = isWizard && isScreenForm && StepBar !== undefined;
+    const changedFieldCount = isCreate ? 0 : Object.keys(snapshot.changes).length;
+    const unsavedCount = isCreate || !isScreenForm
+        ? 0
+        : changedFieldCount > 0
+            ? changedFieldCount
+            : extensionDirty
+                ? 1
+                : 0;
+    const sectionNavItems = isScreenForm && !isStepped
+        ? filteredSections.flatMap((section, index) => section.kind !== "extension" &&
+            section.kind !== "relatedList" &&
+            section.kind !== "writeForm" &&
+            section.visible &&
+            section.title !== undefined &&
+            section.title !== formTitle
+            ? [{ id: formSectionDomId(index), title: section.title }]
+            : [])
+        : [];
+    const compactStepLabel = (() => {
+        const currentTitle = filteredSections[currentStep]?.title;
+        return currentTitle !== undefined
+            ? translate("kumiko.wizard.step-with-title", {
+                current: currentStep + 1,
+                total: lastStepIndex + 1,
+                title: currentTitle,
+            })
+            : translate("kumiko.wizard.step", { current: currentStep + 1, total: lastStepIndex + 1 });
+    })();
+    return (_jsxs(ExtensionFormRegistryProvider, { value: extensionFormRegistry, children: [titleInShell && (_jsx(PageHeader, { title: formTitle, ...(headerMenuItems.length > 0 &&
+                    ActionOverflowMenu !== undefined && {
+                    actions: (_jsx(ActionOverflowMenu, { label: translate("kumiko.list.row-actions.more"), items: headerMenuItems, testId: "render-edit-header-menu" })),
+                }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(hideSectionTitles !== true && !titleInShell && { title: formTitle }), ...(formSubtitle !== undefined && !stepRail && { subtitle: formSubtitle }), ...(isScreenForm && { screenForm: true }), ...(unsavedCount > 0 && { unsavedCount }), ...(sectionNavItems.length > 0 && { sectionNav: sectionNavItems }), ...(stepRail && {
+                    sideRail: (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardJumpBack, orientation: "vertical", heading: translate("kumiko.wizard.step", {
+                            current: currentStep + 1,
+                            total: lastStepIndex + 1,
+                        }), ...(formSubtitle !== undefined && { description: formSubtitle }), testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" })),
+                }), ...(hideActions !== true && hasFormActions && { actions: formActions }), ...(hideActions !== true &&
+                    hasSecondaryFormActions && { secondaryActions: secondaryFormActions }), testId: "render-edit-form", stickyActions: isWizard || fillScreenHeight === true, ...(screen.layout.width !== undefined && { width: screen.layout.width }), ...(formHeaderRegion !== undefined && { headerRegion: formHeaderRegion }), ...(titleActionMount !== undefined && { titleAction: titleActionMount }), ...(fillHeight && { fillHeight }), ...(hideSectionTitles === true && { chromeless: true }), ...(summary !== undefined && { summary }), children: _jsxs(AllFieldsRequiredProvider, { value: showsAllRequiredHint, children: [showsAllRequiredHint && !insideDrawer && allRequiredHint, draftCandidates !== null && (_jsx(Banner, { variant: "info", testId: "render-edit-draft-picker", actions: [
+                                ...draftCandidates.map((candidate) => (_jsx(Button, { type: "button", variant: "link", onClick: () => adoptDraft(candidate), testId: `render-edit-draft-pick-${candidate.id}`, children: formatWhen(candidate.savedAt) }, candidate.id))),
+                                _jsx(Button, { type: "button", variant: "link", onClick: () => setDraftCandidates(null), testId: "render-edit-draft-start-new", children: translate("kumiko.form.draft.start-new") }, "start-new"),
+                            ], children: _jsx(Text, { children: translate(draftCandidates.length === 1
+                                    ? "kumiko.form.draft.resume-single"
+                                    : "kumiko.form.draft.resume-multiple") }) })), isWizard && !stepRail && (_jsxs(_Fragment, { children: [Progress !== undefined && (_jsx(Progress, { value: (currentStep + 1) / (lastStepIndex + 1), testId: "render-edit-wizard-progress" })), StepBar === undefined ? (_jsx(Text, { variant: "small", testId: "render-edit-wizard-step-label", children: compactStepLabel })) : (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardJumpBack, testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" }))] })), isTabs &&
+                            (() => {
+                                // No Tabs primitive registered → every section renders stacked
+                                // (stepHidden below is gated on the same condition), which is the
+                                // single-layout behaviour. Degrading to one long form beats
+                                // hiding sections behind a strip that never drew.
+                                if (Tabs === undefined)
+                                    return null;
+                                return (_jsx(Tabs, { testId: "render-edit-tabs", items: filteredSections.map((section, index) => ({
+                                        id: tabIdAt(section, index),
+                                        label: section.title ?? "",
+                                    })), activeId: tabIdAt(filteredSections[currentStep], currentStep), onSelect: (id) => {
+                                        const index = filteredSections.findIndex((s, i) => tabIdAt(s, i) === id);
+                                        // skip: the strip reported an id no section owns.
+                                        if (index === -1)
+                                            return;
+                                        setRawStep(index);
+                                    } }));
+                            })(), filteredSections.map((section, sectionIndex) => {
+                            // turns this section's own `actions` (RowAction[]) into
+                            // already-bound buttons via the caller-supplied builder, rendered
+                            // through the same RenderEditActionButton the top-level `actions`
+                            // prop uses (same style/confirm/icon/error handling).
+                            const sectionActions = section.actions;
+                            const sectionActionsEl = sectionActions !== undefined && sectionActions.length > 0
+                                ? buildSectionActions?.(sectionActions)?.map((action) => (_jsx(RenderEditActionButton, { action: action, Button: Button, Dialog: Dialog, onError: setActionError }, action.id)))
+                                : undefined;
+                            // Wizard steps and tabs stay mounted while off-screen (native
+                            // `hidden`, not unmounted) so an extension section's submit-registry
+                            // entry (useExtensionFormSubmit → registry.remove on unmount)
+                            // survives navigating past its step — otherwise Finish only ran the
+                            // last mounted step's handler and silently dropped earlier steps'
+                            // writes. For tabs this is also what makes ONE submit cover every
+                            // tab, including tabs the user never opened (fw#3134).
+                            const stepHidden = isStepped && sectionIndex !== currentStep;
+                            const wrapWizardStep = (key, el) => {
+                                if (!isStepped)
+                                    return el;
+                                if (WizardStepGroup === undefined) {
+                                    throw new Error(`RenderEdit: ${screen.layout.mode} layout requires primitives.WizardStepGroup, but none is registered.`);
+                                }
+                                return (_jsx(WizardStepGroup, { hidden: stepHidden, ...(hideSectionTitles === true && { inset: true }), children: el }, key));
+                            };
+                            // Off-screen wizard steps stay mounted (see comment above) but must
+                            // not participate in native constraint validation, or the Next
+                            // button's `type="submit"` triggers the browser's full-form check
+                            // — including required fields on unvisited steps, which are not
+                            // focusable while hidden, so the wizard silently stops navigating
+                            // (only a console warning, no visible error). A plain `hidden`
+                            // attribute does NOT bar descendants from constraint validation on
+                            // web — see WizardStepGroupProps for what implementations must
+                            // guarantee.
+                            if (section.kind === "extension") {
+                                const mount = (_jsx(ExtensionSectionMount, { section: section, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), initialValues: extensionInitialValues, values: snapshot.values, 
+                                    // @cast-boundary form-values: ExtensionSectionProps is not generic
+                                    // over TValues; controller is mount-lifetime-stable, see onControlsReady above.
+                                    patch: patchAndScheduleDraftSave, validate: scopedValidate, hideTitle: hideSectionTitles, ...(hideSectionTitles !== true &&
+                                        sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title));
+                                // Section always flattens to a borderless divider inside this
+                                // component's own <Form>, so tabs mode frames it with Card
+                                // instead — same reason the fields-section tabs branch below
+                                // stays on Card. No title here: the tab strip already labels the
+                                // panel (matches the non-tabs Section branch above via hideTitle).
+                                // testId stays only on the inner Section — this outer Card is
+                                // purely chrome, giving it the same testId would register two
+                                // elements under one id.
+                                const wrapped = hideSectionTitles === true ? (_jsx(Card, { ...(sectionActionsEl !== undefined && {
+                                        slots: { headerActions: sectionActionsEl },
+                                    }), children: mount }, section.title)) : (mount);
+                                return wrapWizardStep(section.title, wrapped);
+                            }
+                            if (section.kind === "relatedList") {
+                                // parentId is the displayed record's id — without it there's no
+                                // parent row whose related rows could be queried (fw#2166).
+                                // Rejected at boot in wizard layouts, so no WizardStepGroup here.
+                                const parentId = resolveExtensionEntityId(entityIdProp, vm.id);
+                                if (parentId === null)
+                                    return null;
+                                const mount = (_jsx(RelatedListSection, { section: section, parentId: parentId, 
+                                    // @cast-boundary form-values: TValues ist strukturell ein Record.
+                                    record: snapshot.values, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, ...(fillScreenHeight === true && { grow: true }), ...(hideSectionTitles !== true &&
+                                        sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(onRelatedListDrawerAction !== undefined && {
+                                        onOpenDrawer: onRelatedListDrawerAction,
+                                    }) }, section.title));
+                                // Tabs mode: the table runs full-bleed under the tab strip (board
+                                // layout); the toolbar buttons live in the list's own toolbar.
+                                return hideSectionTitles === true ? (_jsx("div", { className: fillScreenHeight === true ? "flex min-h-0 flex-1 flex-col" : undefined, children: mount }, section.title)) : (mount);
+                            }
+                            if (section.kind === "writeForm") {
+                                // Own submit button + dispatcher call, entirely independent of
+                                // this screen's (nonexistent, on projectionDetail) form submit —
+                                // rejected at boot in wizard layouts, so no WizardStepGroup here.
+                                return (_jsx(WriteFormSection, { section: section, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, onSubmitted: () => onReload?.(), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title ?? `write-form-${sectionIndex}`));
+                            }
+                            if (!section.visible)
+                                return null;
+                            // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
+                            const sectionKey = section.title ?? `section-${sectionIndex}`;
+                            const renderFieldGrid = (fields, columns, gridKey) => (_jsx(Grid, { columns: columns, ...(usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(usesFieldFlow && { flow: true }), issues: snapshot.errors[field.field], onChange: (v) => {
+                                        controller.setField(field.field, v);
+                                    }, GridCell: GridCell, featureName: featureName, ...(labelAppendix !== undefined && {
+                                        labelAppendix: labelAppendix(field.field),
+                                    }), ...(fieldAppendix !== undefined && {
+                                        fieldAppendix: fieldAppendix(field.field),
+                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...(!isCreate && field.field in snapshot.changes && { changed: true }) }, field.field))) }, gridKey));
+                            // Tabs mode renders one or more titled cards, so this card's actual
+                            // heading doesn't visually duplicate the short Tab strip label.
+                            // Stays `Card`, not `Section` — Section always flattens to a
+                            // borderless divider when rendered inside this component's own
+                            // `<Form>` (InsideFormContext), even with `chromeless` set, so it
+                            // cannot stand in for the tabs-mode card here.
+                            if (hideSectionTitles === true) {
+                                if (section.groups !== undefined) {
+                                    const groupsGrid = (_jsx(Grid, { columns: 1, children: section.groups.map((group, groupIndex) => (_jsx(Card, { slots: { title: group.title }, testId: `section-${sectionKey}-group-${groupIndex}`, children: renderFieldGrid(group.fields, group.columns, `${sectionKey}-group-${groupIndex}-grid`) }, group.title))) }, `${sectionKey}-groups`));
+                                    // `actions` on a `groups` section has no group of its own to
+                                    // sit in and would need an extra title-less Card around the
+                                    // group cards (Card-in-Card) — the boot-validator rejects that
+                                    // combination in tabs mode, so `sectionActionsEl` is always
+                                    // undefined here at runtime.
+                                    return wrapWizardStep(sectionKey, groupsGrid);
+                                }
+                                // No section title here (fw#3218) — the Tab strip right above
+                                // already names this panel, so a repeated Card title would just
+                                // duplicate it. The title row only exists to carry actions, and
+                                // then it carries only the actions, never the title text.
+                                const cardEl = (_jsx(Card, { ...(sectionActionsEl !== undefined && {
+                                        slots: { headerActions: sectionActionsEl },
+                                    }), testId: `section-${sectionKey}`, children: renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`) }, sectionKey));
+                                return wrapWizardStep(sectionKey, cardEl);
+                            }
+                            // Suppress the section header when it would just repeat the form
+                            // title verbatim (typical for single-section actionForms), or the
+                            // tab label right above it. Without a Tabs primitive the sections
+                            // render stacked, and then the titles are what tells them apart.
+                            const repeatsTabLabel = isTabs && isStepped;
+                            const sectionTitle = section.title === formTitle || repeatsTabLabel ? undefined : section.title;
+                            const sectionEl = (_jsxs(Section, { ...(sectionNavItems.some((item) => item.id === formSectionDomId(sectionIndex)) && {
+                                    id: formSectionDomId(sectionIndex),
+                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(section.description !== undefined && { subtitle: section.description }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)] }, sectionKey));
+                            return wrapWizardStep(sectionKey, sectionEl);
+                        }), formError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-form-error", actions: formError.code === "version_conflict" && onReload !== undefined ? (_jsx(Button, { variant: "secondary", onClick: () => {
+                                    onReload();
+                                    setFormError(null);
+                                }, testId: "render-edit-form-error-reload", children: translate("kumiko.actions.reload") })) : undefined, children: _jsx(Text, { testId: "render-edit-form-error-key", children: translate(formError.i18nKey) }) })), extensionErrorKey !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-extension-error", children: _jsx(Text, { testId: "render-edit-extension-error-key", children: translate(extensionErrorKey) }) })), actionError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-action-error", children: actionError })), onDelete !== undefined && (_jsx(Dialog, { open: confirmDeleteOpen, onOpenChange: setConfirmDeleteOpen, title: translate("kumiko.actions.delete-confirm"), confirmLabel: translate("kumiko.actions.delete"), variant: "danger", onConfirm: async () => {
+                                await onDelete();
+                            }, testId: "render-edit-delete-dialog" }))] }) })] }));
+}