@cosmicdrift/kumiko-renderer 0.187.0 → 0.189.0

package/src/components/render-edit.tsx

@@ -21,20 +21,62 @@ import type {
   Translate,
 } from "@cosmicdrift/kumiko-headless";
 import { computeEditViewModel } from "@cosmicdrift/kumiko-headless";
-import { type ReactNode, useMemo, useState } from "react";
+import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { z } from "zod";
 import { ExtensionFormRegistryProvider, useExtensionFormHost } from "../app/extension-form-submit";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections";
+import { useDispatcher } from "../context/dispatcher-context";
+import { useDraftStorage } from "../context/draft-storage-context";
+import { formatWhen } from "../format-when";
 import { useForm } from "../hooks/use-form";
 import { useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
 import {
+  filterEditSections,
   hasEditableSection,
   resolveExtensionEntityId,
   shouldNotifyCaller,
 } from "./render-edit-logic";
 import { RenderField } from "./render-field";
 
+// 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";
+
+// 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.
+const PATCH_DRAFT_SAVE_DEBOUNCE_MS = 500;
+
+type FormDraftBlob = {
+  readonly values: Record<string, unknown>;
+  readonly stepIndex: number;
+};
+
+type DraftCandidate = {
+  readonly id: string;
+  readonly draftKey: string;
+  readonly stepIndex: number;
+  readonly savedAt: string;
+};
+
+// 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: string): string {
+  return `${screenId}:new:`;
+}
+
 // 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
@@ -96,6 +138,58 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  Wird mit dem Field-Namen aufgerufen, returnt ReactNode oder
    *  undefined. */
   readonly fieldAppendix?: (fieldName: string) => ReactNode | undefined;
+  /** Controlled mode (issue #1887): fires on every values-snapshot change
+   *  (typing, `patch(...)` from outside) with the current values. `changes`
+   *  is the delta against the initial values — same semantics as
+   *  `payloadMode: "changes"` — so a caller never overwrites unseen fields.
+   *  `valid` is a pure dry-run parse against `schema` (not a
+   *  `controller.validate()` call), so it does not paint field errors into
+   *  the UI and can diverge from the currently rendered `snapshot.errors` —
+   *  always `true` without `schema`. A caller that patches a fresh object
+   *  reference on every call must not do so unconditionally: `setValues` is
+   *  a no-op when the merged value is reference-equal to the current one,
+   *  so only a converging patch settles instead of looping. Without this
+   *  prop, existing behavior is unchanged. */
+  readonly onChange?: (state: RenderEditChangeState<TValues>) => void;
+  /** Controlled mode (issue #1887): called once after mount, hands the
+   *  caller `patch`/`validate`/`getValues` bound to this RenderEdit
+   *  instance — addressable from outside without a remount. `patch` merges
+   *  only the given keys (existing `controller.setValues` semantics),
+   *  values on unmentioned fields stay untouched. `validate` runs without a
+   *  write and reports field issues via `snapshot.errors` on the field
+   *  itself rather than as a summary banner. Without this prop, existing
+   *  behavior is unchanged. */
+  readonly onControlsReady?: (controls: RenderEditControls<TValues>) => void;
+  /** Renders only these fields (by `field` name from the layout) — section
+   *  order, title, and visibility still come from the layout, so the caller
+   *  doesn't duplicate its shape. A section with no fields left after
+   *  filtering is dropped entirely (not rendered empty). Submit validation
+   *  is scoped to the actually-rendered fields the same way — a required
+   *  field outside this list doesn't block submit. Omitting this prop keeps
+   *  unchanged behavior. Read once at mount for `controller.submit()`'s
+   *  validation scope (the underlying `useForm` controller is mount-lived);
+   *  rendering and `controls.validate()` do stay reactive to later changes. */
+  readonly fields?: readonly string[];
+  /** Locked state (issue #1896): every rendered field and the submit button
+   *  go visibly inactive, no write possible. For cases where input becomes
+   *  moot — e.g. Solon's editor pointing at an existing record instead of
+   *  creating a new one. Extension sections are out of scope: RenderEdit has
+   *  no way to force-disable an arbitrary registered component. Omitting
+   *  this prop keeps unchanged behavior. */
+  readonly disabled?: boolean;
+};
+
+export type RenderEditChangeState<TValues extends FormValues> = {
+  readonly values: TValues;
+  readonly changes: Partial<TValues>;
+  readonly dirty: boolean;
+  readonly valid: boolean;
+};
+
+export type RenderEditControls<TValues extends FormValues> = {
+  readonly patch: (partial: Partial<TValues>) => void;
+  readonly validate: () => boolean;
+  readonly getValues: () => TValues;
 };
 
 function toConditionValue<TValues extends FormValues, TCtx>(
@@ -141,11 +235,17 @@ function ExtensionSectionMount({
   entityName,
   entityId,
   initialValues,
+  values,
+  patch,
+  validate,
 }: {
   readonly section: EditExtensionSectionViewModel;
   readonly entityName: string;
   readonly entityId: string | null;
   readonly initialValues?: Readonly<Record<string, unknown>>;
+  readonly values?: Readonly<Record<string, unknown>>;
+  readonly patch?: (partial: Readonly<Record<string, unknown>>) => void;
+  readonly validate?: () => boolean;
 }): ReactNode {
   const { Banner, Section, Text } = usePrimitives();
   const name = extensionSectionName(section.component);
@@ -169,7 +269,14 @@ function ExtensionSectionMount({
   }
   return (
     <Section title={section.title} testId={`section-extension-${section.title}`}>
-      <Component entityName={entityName} entityId={entityId} initialValues={initialValues} />
+      <Component
+        entityName={entityName}
+        entityId={entityId}
+        initialValues={initialValues}
+        values={values}
+        patch={patch}
+        validate={validate}
+      />
     </Section>
   );
 }
@@ -198,6 +305,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     fieldAppendix,
     entityId: entityIdProp,
     extensionInitialValues,
+    onChange,
+    onControlsReady,
+    fields: fieldsFilter,
+    disabled = false,
   } = props;
   const { customSubmit } = props;
   // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
@@ -207,23 +318,72 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // ohnehin nur in einem mounted Kumiko-App-Tree läuft.
   const t = useTranslation();
   const translate = translateProp ?? t;
+  const dispatcher = useDispatcher();
 
+  const isWizard = screen.layout.mode === "wizard";
+  const draftEnabled = isWizard && screen.layout.draft === true;
+  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<DispatcherError | null>(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<string | null>(() =>
+    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<string | null>(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<readonly DraftCandidate[] | null>(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 [extensionErrorKey, setExtensionErrorKey] = useState<string | null>(null);
   const { registry: extensionFormRegistry, runAll: runExtensionSubmits } =
     useExtensionFormHost(setExtensionDirty);
-  const { Button, Banner, Dialog, Form, Section, Grid, GridCell, Text } = usePrimitives();
+  const { Button, Banner, Dialog, Form, Section, Grid, GridCell, Text, Progress } = usePrimitives();
 
   const fields = useMemo(() => deriveFormFields<TValues, TCtx>(screen), [screen]);
 
+  // Scope für validate()/submit() — nur die tatsächlich gerenderten Feldnamen
+  // aus `fields` (bereits non-extension-only, siehe deriveFormFields), auf den
+  // `fields`-Filter-Prop eingeschränkt. Muss VOR submitConfig/useForm stehen
+  // (der Controller bakt submitConfig beim ersten Render dauerhaft ein) und
+  // kann daher nicht von `vm`/`filteredSections` abgeleitet werden, die erst
+  // nach dem Controller (aus snapshot.values) existieren — die Feldnamen-Menge
+  // pro Section ist aber wertunabhängig (nur visible/readOnly/value hängen von
+  // `values` ab), also liefert diese Ableitung dieselbe Menge wie
+  // filterEditSections(vm.sections, fieldsFilter) es täte. undefined (= kein
+  // Filter aktiv) heißt unscoped validate/submit — auf "alle gerenderten
+  // Felder" scopen würde sonst root-level .refine()-Issues aus der
+  // unscoped-Validierung stillschweigend wegfiltern.
+  const scopeFieldNames = useMemo(
+    () =>
+      fieldsFilter === undefined ? undefined : fieldsFilter.filter((f) => Object.hasOwn(fields, f)),
+    [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.
@@ -233,6 +393,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           type: writeCommand,
           payloadMode,
           ...(buildPayload !== undefined && { buildPayload }),
+          ...(scopeFieldNames !== undefined && { validateScope: scopeFieldNames }),
         }
       : undefined;
 
@@ -244,6 +405,190 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     ...(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;
+  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 valid = schema === undefined ? true : schema.safeParse(snapshot.values).success;
+    cb({ values: snapshot.values, changes: snapshot.changes, dirty: snapshot.isDirty, valid });
+  }, [snapshot, schema]);
+
+  const onControlsReadyRef = useRef(onControlsReady);
+  onControlsReadyRef.current = onControlsReady;
+  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;
+  const currentStepRef = useRef(0);
+  const draftSaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    return () => {
+      if (draftSaveTimerRef.current !== null) clearTimeout(draftSaveTimerRef.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: Partial<TValues>) => {
+      controller.setValues(partial);
+      if (!draftEnabled) return;
+      if (draftSaveTimerRef.current !== null) clearTimeout(draftSaveTimerRef.current);
+      draftSaveTimerRef.current = setTimeout(() => {
+        draftSaveTimerRef.current = null;
+        saveDraftRef.current(currentStepRef.current);
+      }, PATCH_DRAFT_SAVE_DEBOUNCE_MS);
+    },
+    [controller, draftEnabled],
+  );
+
+  useEffect(() => {
+    const cb = onControlsReadyRef.current;
+    if (cb === undefined) return;
+    cb({
+      patch: patchAndScheduleDraftSave,
+      validate: scopedValidate,
+      getValues: () => controller.getSnapshot().values,
+    });
+    // controller is mount-lifetime-stable (see useForm's comment on its own
+    // useMemo), same for patchAndScheduleDraftSave/scopedValidate (both
+    // useCallback over mount-stable deps) — this fires exactly once per
+    // RenderEdit mount in practice.
+  }, [controller, scopedValidate, patchAndScheduleDraftSave]);
+
+  useEffect(() => {
+    // skip: this screen does not persist a draft.
+    if (!draftEnabled) 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 () => {
+      const result = await dispatcher.query<{ readonly draft: FormDraftBlob | null }>(
+        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 while the lookup was in flight — their
+      // input wins over the stored draft.
+      if (controller.getSnapshot().isDirty) return;
+      // @cast-boundary form-draft blob: `values` round-trips through an opaque
+      // jsonb column and comes back untyped.
+      controller.setValues(draft.values as Partial<TValues>);
+      setRawStep(Math.max(draft.stepIndex, 0));
+    })();
+    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. Exactly one → adopt it silently (same
+  // effect as if storage had it). Multiple → render a simple picker
+  // (below) and let the user choose. Zero → 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) return;
+    didListRef.current = true;
+    let cancelled = false;
+    void (async () => {
+      const result = await dispatcher.query<{ readonly drafts: readonly DraftCandidate[] }>(
+        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;
+      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;
+      const [only] = candidates;
+      if (candidates.length === 1 && only !== undefined) {
+        const adoptedId = only.draftKey.slice(prefix.length);
+        draftStorage.setDraftId(screen.id, adoptedId);
+        setDraftId(adoptedId);
+        return;
+      }
+      setDraftCandidates(candidates);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [draftEnabled, isCreateMode, draftId, dispatcher, screen.id, draftStorage]);
+
+  // 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: DraftCandidate): void {
+    const adoptedId = candidate.draftKey.slice(newDraftPrefix(screen.id).length);
+    draftStorage.setDraftId(screen.id, adoptedId);
+    setDraftId(adoptedId);
+    setDraftCandidates(null);
+  }
+
   const vm = useMemo(
     () =>
       computeEditViewModel({
@@ -256,8 +601,13 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     [screen, entity, snapshot.values, translate, featureName],
   );
 
+  const filteredSections = useMemo(
+    () => filterEditSections(vm.sections, fieldsFilter),
+    [vm.sections, fieldsFilter],
+  );
+
   // true for an extension section with no fields of its own too (it carries its own dirty/save).
-  const isFormEditable = hasEditableSection(vm.sections);
+  const isFormEditable = hasEditableSection(filteredSections);
 
   // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
   // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
@@ -274,7 +624,105 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     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 step change: mints the draftId here (issue #1913)
+  // rather than at mount, so a form abandoned on step 0 never claims a
+  // draftId or writes a row at all. `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: number): void {
+    // skip: this screen does not persist a draft.
+    if (!draftEnabled) return;
+    let key = draftKey;
+    if (isCreateMode && draftId === null) {
+      const mintedId = crypto.randomUUID();
+      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;
+    void dispatcher.write(FORM_DRAFT_SAVE, {
+      draftKey: key,
+      values: controller.getSnapshot().values,
+      stepIndex,
+    });
+  }
+
+  // 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(): void {
+    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;
+    const next = Math.min(currentStep + 1, lastStepIndex);
+    setRawStep(next);
+    saveDraft(next);
+  }
+
+  function handleWizardBack(): void {
+    const previous = Math.max(currentStep - 1, 0);
+    setRawStep(previous);
+    saveDraft(previous);
+  }
+
+  async function discardDraft(): Promise<void> {
+    // skip: this screen does not persist a draft.
+    if (!draftEnabled) 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;
+    await dispatcher.write(FORM_DRAFT_DISCARD, { draftKey });
+    // 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);
+    }
+  }
+
   async function handleSubmit(): Promise<void> {
+    // 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;
+    // 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".
+    if (isWizard && !isLastWizardStep) {
+      handleWizardNext();
+      return;
+    }
     setIsSubmitting(true);
     setExtensionErrorKey(null);
     try {
@@ -282,7 +730,9 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       // Kein Entity-Write (würde einen leeren changes-Payload schreiben) — nur
       // die Section-Handler laufen lassen.
       if (snapshot.isUnchanged && extensionDirty) {
-        await persistExtensions();
+        // 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()) await discardDraft();
         return;
       }
       let result: SubmitResult<unknown>;
@@ -303,7 +753,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         // aber gar nichts ist passiert. controller.getSnapshot() ist
         // immer aktuell — der Controller ist die Source-of-Truth, die
         // React-State ist nur ein Mirror für's Rendering.
-        const valid = controller.validate();
+        const valid = controller.validate(scopeFieldNames);
         if (!valid) {
           // Field-Order matters: validationBlocked-true ist eine eigene
           // Variante in der SubmitResult-Union (NICHT mit data/error
@@ -325,6 +775,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       let extensionsPersisted = true;
       if (result.isSuccess) {
         setFormError(null);
+        // 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.
+        await discardDraft();
         extensionsPersisted = await persistExtensions();
       } else if (!result.validationBlocked) {
         const fieldIssues = result.error.details?.fields ?? [];
@@ -378,15 +832,35 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           {translate("kumiko.actions.cancel")}
         </Button>
       )}
-      {isFormEditable && (
+      {isWizard && currentStep > 0 && (
+        <Button
+          type="button"
+          variant="secondary"
+          onClick={handleWizardBack}
+          testId="render-edit-wizard-back"
+        >
+          {translate("kumiko.actions.back")}
+        </Button>
+      )}
+      {isWizard && !isLastWizardStep && (
         <Button
           type="submit"
-          disabled={(snapshot.isUnchanged && !extensionDirty) || isSubmitting}
+          disabled={disabled}
+          variant="primary"
+          testId="render-edit-wizard-next"
+        >
+          {translate("kumiko.actions.next")}
+        </Button>
+      )}
+      {isFormEditable && (!isWizard || isLastWizardStep) && (
+        <Button
+          type="submit"
+          disabled={(snapshot.isUnchanged && !extensionDirty) || isSubmitting || disabled}
           loading={isSubmitting}
           variant="primary"
           testId="render-edit-submit"
         >
-          {translate(submitLabel ?? "kumiko.actions.save")}
+          {translate(submitLabel ?? (isWizard ? "kumiko.actions.finish" : "kumiko.actions.save"))}
         </Button>
       )}
     </>
@@ -422,59 +896,106 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         {...(formSubtitle !== undefined && { subtitle: formSubtitle })}
         actions={formActions}
         testId="render-edit-form"
+        stickyActions={isWizard}
         {...(screen.layout.width !== undefined && { width: screen.layout.width })}
       >
-        {vm.sections.map((section: EditSectionViewModel, sectionIndex: number) => {
-          if (section.kind === "extension") {
-            return (
-              <ExtensionSectionMount
-                key={section.title}
-                section={section}
-                entityName={vm.entityName}
-                entityId={resolveExtensionEntityId(entityIdProp, vm.id)}
-                initialValues={extensionInitialValues}
+        {draftCandidates !== null && (
+          <Banner
+            variant="info"
+            testId="render-edit-draft-picker"
+            actions={draftCandidates.map((candidate) => (
+              <Button
+                key={candidate.id}
+                type="button"
+                variant="link"
+                onClick={() => adoptDraft(candidate)}
+                testId={`render-edit-draft-pick-${candidate.id}`}
+              >
+                {formatWhen(candidate.savedAt)}
+              </Button>
+            ))}
+          >
+            <Text>{translate("kumiko.form.draft.resume-multiple")}</Text>
+          </Banner>
+        )}
+        {isWizard && (
+          <>
+            {Progress !== undefined && (
+              <Progress
+                value={(currentStep + 1) / (lastStepIndex + 1)}
+                testId="render-edit-wizard-progress"
               />
+            )}
+            <Text variant="small" testId="render-edit-wizard-step-label">
+              {translate("kumiko.wizard.step", {
+                current: currentStep + 1,
+                total: lastStepIndex + 1,
+              })}
+            </Text>
+          </>
+        )}
+        {(isWizard ? filteredSections.filter((_, i) => i === currentStep) : filteredSections).map(
+          (section: EditSectionViewModel, sectionIndex: number) => {
+            if (section.kind === "extension") {
+              return (
+                <ExtensionSectionMount
+                  key={section.title}
+                  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 as (
+                      partial: Readonly<Record<string, unknown>>,
+                    ) => void
+                  }
+                  validate={scopedValidate}
+                />
+              );
+            }
+            if (!section.visible) return null;
+            // Section-Header unterdrücken wenn er den Form-Titel der
+            // Action-Bar 1:1 wiederholen würde (typisch bei Single-Section-
+            // ActionForms, deren Section-Label = Screen-Titel ist).
+            const sectionTitle = section.title === formTitle ? undefined : section.title;
+            // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
+            const sectionKey = section.title ?? `section-${sectionIndex}`;
+            return (
+              <Section
+                key={sectionKey}
+                {...(sectionTitle !== undefined && { title: sectionTitle })}
+                {...(section.description !== undefined && { subtitle: section.description })}
+                testId={`section-${sectionKey}`}
+              >
+                <Grid columns={section.columns}>
+                  {section.fields.map((field: EditFieldViewModel) => (
+                    <GridCellForField
+                      key={field.field}
+                      field={disabled ? { ...field, readOnly: true } : field}
+                      columns={section.columns}
+                      issues={snapshot.errors[field.field]}
+                      onChange={(v) => {
+                        (controller.setField as (k: string, v: unknown) => void)(field.field, v);
+                      }}
+                      GridCell={GridCell}
+                      featureName={featureName}
+                      {...(labelAppendix !== undefined && {
+                        labelAppendix: labelAppendix(field.field),
+                      })}
+                      {...(fieldAppendix !== undefined && {
+                        fieldAppendix: fieldAppendix(field.field),
+                      })}
+                      allIssues={snapshot.errors}
+                    />
+                  ))}
+                </Grid>
+              </Section>
             );
-          }
-          if (!section.visible) return null;
-          // Section-Header unterdrücken wenn er den Form-Titel der
-          // Action-Bar 1:1 wiederholen würde (typisch bei Single-Section-
-          // ActionForms, deren Section-Label = Screen-Titel ist).
-          const sectionTitle = section.title === formTitle ? undefined : section.title;
-          // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
-          const sectionKey = section.title ?? `section-${sectionIndex}`;
-          return (
-            <Section
-              key={sectionKey}
-              {...(sectionTitle !== undefined && { title: sectionTitle })}
-              {...(section.description !== undefined && { subtitle: section.description })}
-              testId={`section-${sectionKey}`}
-            >
-              <Grid columns={section.columns}>
-                {section.fields.map((field: EditFieldViewModel) => (
-                  <GridCellForField
-                    key={field.field}
-                    field={field}
-                    columns={section.columns}
-                    issues={snapshot.errors[field.field]}
-                    onChange={(v) => {
-                      (controller.setField as (k: string, v: unknown) => void)(field.field, v);
-                    }}
-                    GridCell={GridCell}
-                    featureName={featureName}
-                    {...(labelAppendix !== undefined && {
-                      labelAppendix: labelAppendix(field.field),
-                    })}
-                    {...(fieldAppendix !== undefined && {
-                      fieldAppendix: fieldAppendix(field.field),
-                    })}
-                    allIssues={snapshot.errors}
-                  />
-                ))}
-              </Grid>
-            </Section>
-          );
-        })}
+          },
+        )}
         {formError !== null && (
           <Banner
             variant="error"