@cosmicdrift/kumiko-renderer 0.384.0 → 0.385.0

package/dist/components/render-edit.js

@@ -1,236 +1,31 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { evalFieldCondition, isFieldsEditSection, normalizeEditField, PROJECTION_DETAIL_ENTITY, sectionFieldSpecs, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { ErrorReference } from "../app/error-reference.js";
-import { computeEditViewModel, groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues, } from "../headless/index.js";
-import { changedDerivedValues } from "./form-derivation-patch.js";
-import { RenderEditActionButton } from "./render-edit-action-button.js";
-import { AllFieldsRequiredProvider } from "./render-field.js";
-import { useActionMenuItems } from "./use-action-menu-items.js";
+import { PROJECTION_DETAIL_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ErrorReference } from "../app/error-reference.js";
 import { ExtensionFormRegistryProvider, useExtensionFormHost, } from "../app/extension-form-submit.js";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
 import { layoutEditFields } from "../app/layout-fields.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useDraftStorage } from "../context/draft-storage-context.js";
 import { formatWhen } from "../format-when.js";
+import { computeEditViewModel, groupIssuesByPath } from "../headless/index.js";
 import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
 import { useInsideDrawer } from "../inside-drawer.js";
 import { useUnsavedInputSource } from "../leave-guard.js";
 import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
 import { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
+import { EditSlotMount, ExtensionSectionMount } from "./edit-mounts.js";
+import { changedDerivedValues } from "./form-derivation-patch.js";
 import { GridCellForField } from "./grid-cell-for-field.js";
 import { RelatedListSection } from "./related-list-section.js";
+import { RenderEditActionButton } from "./render-edit-action-button.js";
+import { deriveFormFields, dryRunFieldIssues, dryRunParse, formSectionDomId, isFieldsStepFilled, resolveRecordTitle, resolveTitleTemplate, tabIdAt, wizardStepKey, } from "./render-edit-helpers.js";
 import { filterEditSections, findFirstErroringSectionIndex, hasEditableSection, hasIssueWithoutRenderedField, isDispatcherRejection, issuesAfterEdit, ROOT_ISSUE_PATH, resolveExtensionEntityId, shouldNotifyCaller, } from "./render-edit-logic.js";
+import { AllFieldsRequiredProvider } from "./render-field.js";
+import { useActionMenuItems } from "./use-action-menu-items.js";
+import { buildWizardDraftActions, PATCH_DRAFT_SAVE_DEBOUNCE_MS, useWizardFormDraftRestore, useWizardFormDraftState, } from "./use-wizard-form-draft.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/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)}`;
-}
-// 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 sectionFieldSpecs(section)) {
-            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;
-}
-// Dry-run parse against `schema` — NOT controller.validate(), which writes
-// field errors into the snapshot. Undefined when the values parse cleanly.
-// Parse once, then narrow per scope with scopedDryRunIssues: the wizard step
-// check would otherwise re-parse the whole form per section on every keystroke.
-function dryRunParse(schema, snapshot) {
-    const parsed = schema.safeParse(snapshot.values);
-    if (parsed.success)
-        return undefined;
-    const hiddenFields = new Set(Object.entries(snapshot.fields)
-        .filter(([, state]) => !state.visible)
-        .map(([fieldKey]) => fieldKey));
-    return { issues: zodErrorToFieldIssues(parsed.error), hiddenFields };
-}
-// Issues are filtered exactly like the controller's validate(): hidden
-// fields never count, `scope` narrows.
-function scopedDryRunIssues(parse, scope, includeRoot) {
-    if (parse === undefined)
-        return [];
-    return relevantFieldIssues(parse.issues, {
-        hiddenFields: parse.hiddenFields,
-        ...(scope !== undefined && { scope }),
-        includeRoot,
-    });
-}
-function dryRunFieldIssues(schema, snapshot, scope, includeRoot) {
-    return scopedDryRunIssues(dryRunParse(schema, snapshot), scope, includeRoot);
-}
-// Index-independent: indices shift when a fields section hides.
-function wizardStepKey(section, index) {
-    const declaredId = section.kind === "fields" || section.kind === "extension" ? section.id : undefined;
-    return declaredId ?? section.title ?? `step-${index}`;
-}
-function isMoneyValue(value) {
-    return typeof value === "object" && value !== null && "amount" in value;
-}
-// The seeds buildInitialValues writes for NULL columns of an existing record.
-function isEmptyFormValue(value) {
-    if (value === null || value === undefined || value === "" || value === 0 || value === false) {
-        return true;
-    }
-    if (Array.isArray(value))
-        return value.length === 0;
-    return isMoneyValue(value) && value.amount === 0;
-}
-// select/boolean are excluded from the "holds user data" check: they are
-// often pre-filled (defaults, server-set values), so they say nothing about
-// whether the step was filled in. They still count through the validation.
-function isFieldsStepFilled(section, parse) {
-    const fieldNames = section.fields.map((f) => f.field);
-    if (scopedDryRunIssues(parse, fieldNames, false).length > 0)
-        return false;
-    return section.fields.some((f) => f.visible &&
-        !f.readOnly &&
-        f.type !== "boolean" &&
-        f.type !== "select" &&
-        !isEmptyFormValue(f.value));
-}
-// 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, markSaved, hideTitle, actions, stepKey, onReportStepComplete, }) {
-    const { Banner, FillContainer, Section, Text } = usePrimitives();
-    const name = extensionSectionName(section.component);
-    const Component = useExtensionSectionComponent(name);
-    const reportStepComplete = useCallback((complete) => {
-        if (stepKey !== undefined)
-            onReportStepComplete?.(stepKey, complete);
-    }, [stepKey, onReportStepComplete]);
-    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, markSaved: markSaved, ...(onReportStepComplete !== undefined && { reportStepComplete }) }));
-    // 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, markSaved, 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, ...(markSaved !== undefined && { markSaved }), ...(hasUnsavedChanges !== undefined && { hasUnsavedChanges }), ...(wizardStep !== undefined && { wizardStep }) }));
-}
-function formSectionDomId(sectionIndex) {
-    return `form-section-${sectionIndex}`;
-}
-/** A record title is a non-blank string; anything else leaves the screen title alone. */
-export function resolveRecordTitle(value) {
-    return typeof value === "string" && value.trim() !== "" ? value : undefined;
-}
-const TITLE_PLACEHOLDER_PATTERN = /\{(\w+)\}/g;
-// Falls back to the plain title while any placeholder value is still empty,
-// so the header never shows "Add  " mid-typing.
-function resolveTitleTemplate(template, values, translate, fallback) {
-    if (template === undefined)
-        return fallback;
-    const placeholders = [...translate(template).matchAll(TITLE_PLACEHOLDER_PATTERN)].map((match) => match[1] ?? "");
-    const isFilled = (name) => {
-        const value = values[name];
-        return value !== undefined && value !== null && String(value).trim() !== "";
-    };
-    if (!placeholders.every(isFilled))
-        return fallback;
-    return translate(template, values);
-}
 export function RenderEdit(props) {
     const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, formDerivation, actionFormScreenQn, } = props;
     // View mode is a locked form, so everything keyed on `disabled` follows.
@@ -280,24 +75,13 @@ export function RenderEdit(props) {
     // Tabs have stable ids, so the active tab follows its id: a field change
     // that hides an earlier tab must not shift the index onto another tab.
     const [activeTabId, setActiveTabId] = useState(undefined);
-    // 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);
+    const draftState = useWizardFormDraftState({
+        screenId: screen.id,
+        entityId: entityIdProp,
+        isCreateMode,
+        draftStorage,
+    });
+    const { draftCandidates, setDraftCandidates } = draftState;
     // 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
@@ -407,18 +191,6 @@ export function RenderEdit(props) {
         controller.setValues(initial);
         controller.rebase();
     }, [refreshToken, controller, initial]);
-    // 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
@@ -455,8 +227,7 @@ export function RenderEdit(props) {
     // 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;
+    const saveDraftRef = useRef(() => { });
     // `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.
@@ -566,111 +337,16 @@ export function RenderEdit(props) {
     // Draft wizards keep their input server-side, so leaving loses nothing.
     const persistsDraft = isWizard && screen.layout.draft === true;
     useUnsavedInputSource(() => !persistsDraft && (controller.getSnapshot().isDirty || extensionDirtyRef.current));
-    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) {
-                // 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);
-    }
+    useWizardFormDraftRestore({
+        screenId: screen.id,
+        isCreateMode,
+        draftEnabled,
+        dispatcher,
+        controller,
+        hasNavigatedRef,
+        setRawStep,
+        draftState,
+    });
     const vm = useMemo(() => computeEditViewModel({
         screen,
         entity,
@@ -799,63 +475,19 @@ export function RenderEdit(props) {
         if (isTabs)
             setActiveTabId(tabIdAt(filteredSections[index], index));
     }
-    // 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 secretFieldNames = new Set(vm.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) => {
-            // biome-ignore lint/suspicious/noConsole: fire-and-forget draft save must not red-screen
-            console.warn("render-edit: draft save failed", err);
-        });
-    }
+    const { adoptDraft, saveDraft, discardDraft } = buildWizardDraftActions({
+        screenId: screen.id,
+        isCreateMode,
+        draftEnabled,
+        disabled,
+        dispatcher,
+        draftStorage,
+        controller,
+        sections: vm.sections,
+        draftSaveTimerRef,
+        draftState,
+    });
+    saveDraftRef.current = saveDraft;
     // 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
@@ -912,40 +544,6 @@ export function RenderEdit(props) {
         if (!disabled)
             saveDraft(clampedTarget);
     }
-    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

package/dist/components/render-field.js

@@ -11,6 +11,7 @@ import { evalRowExtractor } from "../app/row-actions.js";
 import { screenAccessAllows } from "../app/screen-access.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
+import { rendererError, rendererWarn } from "../dev-console.js";
 import { fileIdsOf } from "../file-ids-of.js";
 import { applyFormatSpec, currencyDecimals, EMPTY_VALUE_PLACEHOLDER, } from "../headless/index.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
@@ -228,8 +229,7 @@ function ReferenceInput({ field, id, hasError, onChange, Input, featureName, })
         // be missing from `options` (shown as a raw id instead of a label).
         setSearchTerm("");
         queryResult.refetch().catch((err) => {
-            // biome-ignore lint/suspicious/noConsole: no error-surfacing path exists in this widget yet — at minimum, don't swallow it silently.
-            console.error("render-field: refetch after create failed", err);
+            rendererError("render-field: refetch after create failed", err);
         });
         if (newId === undefined) {
             // Record was created server-side but the payload carried no id —
@@ -319,8 +319,7 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         if (Component !== undefined) {
             return (_jsx(Component, { value: field.value, row: row ?? { [field.field]: field.value }, column: { field: field.field } }));
         }
-        // biome-ignore lint/suspicious/noConsole: dev-warning for a registry mismatch, mirrors DataTableCell's columnRenderer warning.
-        console.warn(`[kumiko] fieldRenderer "${componentName}" not registered`);
+        rendererWarn(`[kumiko] fieldRenderer "${componentName}" not registered`);
     }
     return _jsx(Text, { testId: `field-value-${field.field}`, children: stringValue(field.value) });
 }

package/dist/components/render-list.js

@@ -3,6 +3,7 @@ import { UNRESOLVED_REFERENCE_LABEL_KEYS, } from "@cosmicdrift/kumiko-framework/
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
 import { useReferenceLinkResolver } from "../app/reference-link.js";
+import { rendererWarn } from "../dev-console.js";
 import { computeListViewModel, EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
 import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
@@ -251,8 +252,7 @@ function ListHeaderSlotMount({ screen, }) {
     // (the toolbar has no room for a banner, so a dev-warn it is).
     useEffect(() => {
         if (name !== undefined && Component === undefined) {
-            // biome-ignore lint/suspicious/noConsole: dev-warning für Setup-Fehler
-            console.warn(`[kumiko] List header slot component "${name}" on screen "${screen.id}" is not registered in clientFeatures.extensionSectionComponents — the header slot renders nothing.`);
+            rendererWarn(`[kumiko] List header slot component "${name}" on screen "${screen.id}" is not registered in clientFeatures.extensionSectionComponents — the header slot renders nothing.`);
         }
     }, [name, Component, screen.id]);
     if (Component === undefined)

package/dist/components/use-wizard-form-draft.d.ts

@@ -0,0 +1,51 @@
+import { type MutableRefObject } from "react";
+import type { DraftStorage } from "../context/draft-storage-context.tsx";
+import type { Dispatcher, EditSectionViewModel, FormController, FormValues } from "../headless/index.ts";
+export declare const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
+export type DraftCandidate = {
+    readonly id: string;
+    readonly draftKey: string;
+    readonly stepIndex: number;
+    readonly savedAt: string;
+};
+export declare function useWizardFormDraftState({ screenId, entityId, isCreateMode, draftStorage, }: {
+    readonly screenId: string;
+    readonly entityId: string | null | undefined;
+    readonly isCreateMode: boolean;
+    readonly draftStorage: DraftStorage;
+}): {
+    draftId: string | null;
+    setDraftId: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    draftCandidates: readonly DraftCandidate[] | null;
+    setDraftCandidates: import("react").Dispatch<import("react").SetStateAction<readonly DraftCandidate[] | null>>;
+    mintedDraftIdRef: import("react").RefObject<string | null>;
+    didListRef: import("react").RefObject<boolean>;
+    draftKey: string | undefined;
+};
+export type WizardFormDraftState = ReturnType<typeof useWizardFormDraftState>;
+export declare function useWizardFormDraftRestore<TValues extends FormValues>({ screenId, isCreateMode, draftEnabled, dispatcher, controller, hasNavigatedRef, setRawStep, draftState: { draftId, draftKey, mintedDraftIdRef, didListRef, setDraftCandidates }, }: {
+    readonly screenId: string;
+    readonly isCreateMode: boolean;
+    readonly draftEnabled: boolean;
+    readonly dispatcher: Dispatcher | undefined;
+    readonly controller: FormController<TValues>;
+    readonly hasNavigatedRef: MutableRefObject<boolean>;
+    readonly setRawStep: (step: number) => void;
+    readonly draftState: WizardFormDraftState;
+}): void;
+export declare function buildWizardDraftActions<TValues extends FormValues>({ screenId, isCreateMode, draftEnabled, disabled, dispatcher, draftStorage, controller, sections, draftSaveTimerRef, draftState: { draftId, draftKey, mintedDraftIdRef, setDraftId, setDraftCandidates }, }: {
+    readonly screenId: string;
+    readonly isCreateMode: boolean;
+    readonly draftEnabled: boolean;
+    readonly disabled: boolean;
+    readonly dispatcher: Dispatcher | undefined;
+    readonly draftStorage: DraftStorage;
+    readonly controller: FormController<TValues>;
+    readonly sections: readonly EditSectionViewModel[];
+    readonly draftSaveTimerRef: MutableRefObject<ReturnType<typeof setTimeout> | null>;
+    readonly draftState: WizardFormDraftState;
+}): {
+    adoptDraft: (candidate: DraftCandidate) => void;
+    saveDraft: (stepIndex: number) => void;
+    discardDraft: () => Promise<void>;
+};