@cosmicdrift/kumiko-renderer 0.193.1 → 0.195.0

package/src/components/render-edit.tsx

@@ -25,7 +25,7 @@ import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } fro
 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 { useOptionalDispatcher } from "../context/dispatcher-context";
 import { useDraftStorage } from "../context/draft-storage-context";
 import { formatWhen } from "../format-when";
 import { useForm } from "../hooks/use-form";
@@ -47,6 +47,9 @@ 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
@@ -77,6 +80,14 @@ function newDraftPrefix(screenId: string): string {
   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(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).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
@@ -149,7 +160,10 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  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. */
+   *  prop, existing behavior is unchanged. `onControlsReady` is guaranteed
+   *  to have already fired by the time the mount-time `onChange` call
+   *  happens, so a caller patching dependent fields from inside `onChange`
+   *  never has to guard against `controls` being undefined. */
   readonly onChange?: (state: RenderEditChangeState<TValues>) => void;
   /** Controlled mode (issue #1887): called once after mount, hands the
    *  caller `patch`/`validate`/`getValues` bound to this RenderEdit
@@ -175,7 +189,13 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  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. */
+   *  this prop keeps unchanged behavior.
+   *
+   *  ponytail: direct-consumer only — kumiko-screen.tsx's RenderEdit call
+   *  sites pass explicit prop lists without a spread and never forward
+   *  `disabled`, so a screen-driven app can't set the locked state today.
+   *  Upgrade path if that's needed: thread a screen-spec flag through to
+   *  `EntityEditCreateBody`/`EntityEditEditBody`. */
   readonly disabled?: boolean;
   /** Renders the fields without RenderEdit's own action bar (save, cancel,
    *  delete, copy-link). For hosts that put those controls into their own
@@ -250,7 +270,6 @@ function ExtensionSectionMount({
   values,
   patch,
   validate,
-  hidden,
 }: {
   readonly section: EditExtensionSectionViewModel;
   readonly entityName: string;
@@ -259,7 +278,6 @@ function ExtensionSectionMount({
   readonly values?: Readonly<Record<string, unknown>>;
   readonly patch?: (partial: Readonly<Record<string, unknown>>) => void;
   readonly validate?: () => boolean;
-  readonly hidden?: boolean;
 }): ReactNode {
   const { Banner, Section, Text } = usePrimitives();
   const name = extensionSectionName(section.component);
@@ -270,7 +288,6 @@ function ExtensionSectionMount({
         key={section.title}
         title={section.title}
         testId={`section-extension-${section.title}`}
-        hidden={hidden}
       >
         <Banner variant="info" testId={`section-extension-placeholder-${section.title}`}>
           <Text>
@@ -283,7 +300,7 @@ function ExtensionSectionMount({
     );
   }
   return (
-    <Section title={section.title} testId={`section-extension-${section.title}`} hidden={hidden}>
+    <Section title={section.title} testId={`section-extension-${section.title}`}>
       <Component
         entityName={entityName}
         entityId={entityId}
@@ -334,10 +351,10 @@ 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 dispatcher = useOptionalDispatcher();
 
   const isWizard = screen.layout.mode === "wizard";
-  const draftEnabled = isWizard && screen.layout.draft === true;
+  const draftEnabled = isWizard && screen.layout.draft === true && dispatcher !== undefined;
   const isCreateMode = entityIdProp === undefined || entityIdProp === null || entityIdProp === "";
   const draftStorage = useDraftStorage();
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
@@ -378,23 +395,26 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const [extensionErrorKey, setExtensionErrorKey] = useState<string | null>(null);
   const { registry: extensionFormRegistry, runAll: runExtensionSubmits } =
     useExtensionFormHost(setExtensionDirty);
-  const { Button, Banner, Dialog, Form, Section, Grid, GridCell, Text, Progress, StepBar } =
-    usePrimitives();
+  const {
+    Button,
+    Banner,
+    Dialog,
+    Form,
+    Section,
+    Grid,
+    GridCell,
+    Text,
+    Progress,
+    StepBar,
+    WizardStepGroup,
+  } = 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.
+  // Must be computed before submitConfig/useForm bakes it in (the controller
+  // freezes it on first render) — safe because a section's field-name set is
+  // value-independent, so it matches filterEditSections(vm.sections, fieldsFilter).
+  // undefined = unscoped, since scoping would silently drop root-level .refine() issues.
   const scopeFieldNames = useMemo(
     () =>
       fieldsFilter === undefined ? undefined : fieldsFilter.filter((f) => Object.hasOwn(fields, f)),
@@ -453,23 +473,6 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // 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;
-  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 });
-  }, [snapshot]);
-
   const onControlsReadyRef = useRef(onControlsReady);
   onControlsReadyRef.current = onControlsReady;
   const scopeFieldNamesRef = useRef(scopeFieldNames);
@@ -507,16 +510,24 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const patchAndScheduleDraftSave = useCallback(
     (partial: Partial<TValues>) => {
       controller.setValues(partial);
-      if (!draftEnabled) return;
+      if (!draftEnabled || dispatcher === undefined) 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],
+    [controller, draftEnabled, dispatcher],
   );
 
+  // 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.
   useEffect(() => {
     const cb = onControlsReadyRef.current;
     if (cb === undefined) return;
@@ -532,9 +543,28 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     // RenderEdit mount in practice.
   }, [controller, scopedValidate, patchAndScheduleDraftSave]);
 
+  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 });
+  }, [snapshot]);
+
   useEffect(() => {
     // skip: this screen does not persist a draft.
-    if (!draftEnabled) return;
+    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.
@@ -581,7 +611,14 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     // 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;
+    if (
+      !draftEnabled ||
+      !isCreateMode ||
+      draftId !== null ||
+      didListRef.current ||
+      dispatcher === undefined
+    )
+      return;
     didListRef.current = true;
     let cancelled = false;
     void (async () => {
@@ -665,17 +702,19 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // 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
+  // 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: number): void {
     // skip: this screen does not persist a draft.
-    if (!draftEnabled) return;
+    if (!draftEnabled || dispatcher === undefined) return;
     let key = draftKey;
     if (isCreateMode && draftId === null) {
-      const mintedId = crypto.randomUUID();
+      const mintedId = mintDraftId();
       mintedDraftIdRef.current = mintedId;
       draftStorage.setDraftId(screen.id, mintedId);
       setDraftId(mintedId);
@@ -689,6 +728,16 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     // 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;
+    }
     void dispatcher.write(FORM_DRAFT_SAVE, {
       draftKey: key,
       values: controller.getSnapshot().values,
@@ -727,7 +776,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
 
   async function discardDraft(): Promise<void> {
     // skip: this screen does not persist a draft.
-    if (!draftEnabled) return;
+    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) {
@@ -791,8 +840,8 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     setIsSubmitting(true);
     setExtensionErrorKey(null);
     try {
-      // Extension-only: nur eine Section ist dirty, das Haupt-Form unverändert.
-      // Kein Entity-Write (würde einen leeren changes-Payload schreiben) — nur
+      // 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
@@ -802,27 +851,27 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       }
       let result: SubmitResult<unknown>;
       if (customSubmit !== undefined) {
-        // customSubmit-Pfad (z.B. configEdit, das pro Field einen
-        // separaten Write feuert). Erst client-side Validation, dann
+        // 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
-        // weil controller.submit() das normalerweise selbst macht und
-        // ohne customSubmit's Hilfe weiß der Controller nichts vom
+        // 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. Bei rapid fill→click kann React-Batching die
-        // Input-State-Updates noch nicht commited haben, wenn der
-        // submit-Click fire'd. handleSubmit's Closure würde dann mit
+        // 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 ist nur ein Mirror für's Rendering.
+        // React state is only a mirror for rendering.
         const valid = controller.validate(scopeFieldNames);
         if (!valid) {
-          // Field-Order matters: validationBlocked-true ist eine eigene
-          // Variante in der SubmitResult-Union (NICHT mit data/error
-          // gemixt), TS narrowt das nur ohne den Discriminator-Fight.
+          // 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: SubmitResult<unknown> = {
             validationBlocked: true,
             isSuccess: false,
@@ -835,8 +884,8 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       } else {
         result = await controller.submit();
       }
-      // Form-level Errors (ohne field-level details) landen im Banner.
-      // Field-Errors fließen über snapshot.errors in die einzelnen Fields.
+      // 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);
@@ -888,7 +937,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
 
   // Sticky-top Action-Bar: Delete (links, destructive) + Cancel +
   // Save. Delete sitzt links abgesetzt damit die Click-Distanz zu
-  // Save groß ist; rot + Confirm-Dialog sind ausreichend Schutz
+  // Save is large; red styling + confirm dialog are enough protection
   // gegen Fehlklicks. Save bleibt rechts (primary affordance).
   const formActions = (
     <>
@@ -957,7 +1006,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // 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 fällt zuletzt auf screenId, subtitle auf undefined (kein Untertitel).
+  // title falls back to screenId; subtitle to undefined (no subtitle).
   const isCreate = (() => {
     const id = resolveExtensionEntityId(entityIdProp, vm.id);
     return id == null || id === "";
@@ -1049,9 +1098,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
               }
               return (
                 <StepBar
-                  steps={filteredSections.map(
-                    (section, sectionIndex) => section.title ?? String(sectionIndex + 1),
-                  )}
+                  steps={filteredSections.map((section) => section.title ?? "")}
                   currentIndex={currentStep}
                   compactLabel={compactLabel}
                   testId="render-edit-wizard-steps"
@@ -1068,8 +1115,17 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           // navigating past its step — otherwise Finish only ran the last
           // mounted step's handler and silently dropped earlier steps' writes.
           const stepHidden = isWizard && sectionIndex !== currentStep;
+          // 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") {
-            return (
+            const mount = (
               <ExtensionSectionMount
                 key={section.title}
                 section={section}
@@ -1083,9 +1139,20 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                   patchAndScheduleDraftSave as (partial: Readonly<Record<string, unknown>>) => void
                 }
                 validate={scopedValidate}
-                hidden={stepHidden}
               />
             );
+            if (!isWizard) return mount;
+            if (WizardStepGroup === undefined) {
+              // Both silent fallbacks are unsafe here — render-visible-all-steps or unmount-drops-registry.
+              throw new Error(
+                "RenderEdit: wizard layout requires primitives.WizardStepGroup, but none is registered.",
+              );
+            }
+            return (
+              <WizardStepGroup key={section.title} hidden={stepHidden}>
+                {mount}
+              </WizardStepGroup>
+            );
           }
           if (!section.visible) return null;
           // Section-Header unterdrücken wenn er den Form-Titel der
@@ -1094,13 +1161,12 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           const sectionTitle = section.title === formTitle ? undefined : section.title;
           // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
           const sectionKey = section.title ?? `section-${sectionIndex}`;
-          return (
+          const sectionEl = (
             <Section
               key={sectionKey}
               {...(sectionTitle !== undefined && { title: sectionTitle })}
               {...(section.description !== undefined && { subtitle: section.description })}
               testId={`section-${sectionKey}`}
-              hidden={stepHidden}
             >
               <Grid columns={section.columns}>
                 {section.fields.map((field: EditFieldViewModel) => (
@@ -1126,6 +1192,17 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
               </Grid>
             </Section>
           );
+          if (!isWizard) return sectionEl;
+          if (WizardStepGroup === undefined) {
+            throw new Error(
+              "RenderEdit: wizard layout requires primitives.WizardStepGroup, but none is registered.",
+            );
+          }
+          return (
+            <WizardStepGroup key={sectionKey} hidden={stepHidden}>
+              {sectionEl}
+            </WizardStepGroup>
+          );
         })}
         {formError !== null && (
           <Banner

package/src/components/render-field.tsx

@@ -23,6 +23,12 @@ import { ReferenceCreateDialog } from "./reference-create-dialog";
 // Der field.type → Input-kind Mapping bleibt hier, weil es
 // Domain-Logik ist (EntityDefinition-Feldtyp) und nicht Darstellung.
 
+// No `hideLabel` prop here (fw#1870/#1871#3, deliberately out of scope):
+// RenderField is driven entirely by EditFieldViewModel/EntityEditScreenDefinition,
+// which have no per-field hideLabel slot — wiring it through would need a
+// schema change, not just a prop. Declarative grid/table screens stay on
+// visible labels until that schema work happens; imperative *Field widgets
+// (form-fields.tsx, AiTextField) already support it.
 export type RenderFieldProps = {
   readonly field: EditFieldViewModel;
   readonly issues?: readonly FieldIssue[];
@@ -53,7 +59,7 @@ export function RenderField({
   fieldAppendix,
   allIssues,
 }: RenderFieldProps): ReactNode {
-  const { Field, Input, Banner } = usePrimitives();
+  const { Field, Input, Banner, Text } = usePrimitives();
   // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
   // navigator.language (Browser-Sprache) zurück statt der gewählten
   // App-Sprache. BEWUSSTE API-Verschärfung (seit 0.38): RenderField ist
@@ -88,7 +94,7 @@ export function RenderField({
         featureName={featureName ?? ""}
       />
     ) : (
-      renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, t })
+      renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, Text, t })
     );
 
   return (
@@ -303,6 +309,7 @@ function renderInput({
   Input,
   appLocale,
   Banner,
+  Text,
   t,
 }: {
   readonly field: EditFieldViewModel;
@@ -312,6 +319,7 @@ function renderInput({
   readonly Input: ReturnType<typeof usePrimitives>["Input"];
   readonly appLocale: string;
   readonly Banner: ReturnType<typeof usePrimitives>["Banner"];
+  readonly Text: ReturnType<typeof usePrimitives>["Text"];
   readonly t: ReturnType<typeof useTranslation>;
 }): ReactNode {
   const common = {
@@ -476,6 +484,7 @@ function renderInput({
           {...(field.entityType !== undefined && { entityType: field.entityType })}
           {...(field.fieldName !== undefined && { fieldName: field.fieldName })}
           {...(field.imageVariant !== undefined && { imageVariant: field.imageVariant })}
+          {...(field.capture !== undefined && { capture: field.capture })}
         />
       );
     }
@@ -492,12 +501,15 @@ function renderInput({
     case "embedded":
     case "jsonb":
     case "files":
-    case "images":
+    case "images": {
+      const hasValue = field.value !== undefined && field.value !== null && field.value !== "";
       return (
         <Banner id={id} variant="info">
           {t("kumiko.field.unsupported")}
+          {hasValue && <Text variant="code">{JSON.stringify(field.value)}</Text>}
         </Banner>
       );
+    }
     default: {
       // text + unknown scalar type → text input. If TextFieldDef.multiline
       // is set (the view-model carries it), the renderer switches to

package/src/i18n-defaults.ts

@@ -30,9 +30,6 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.wizard.step": "Schritt {current} von {total}",
     "kumiko.wizard.step-with-title": "Schritt {current} von {total} · {title}",
 
-    // StepBar widget (renderer-web) — screen-reader text for completed steps whose number is visually replaced by a checkmark.
-    "kumiko.widget.stepBar.done": "Erledigt",
-
     // Version — Update-Awareness-Banner (UpdateChecker).
     "kumiko.version.update-available": "Eine neue Version ist verfügbar.",
 
@@ -57,6 +54,10 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.field.embedded-list.move-down": "Nach unten verschieben",
     "kumiko.field.embedded-list.empty": "Noch keine Zeilen.",
     "kumiko.field.embedded-list.empty-cta": "Erste Zeile hinzufügen",
+    "kumiko.field.embedded-list.paste-rows-truncated":
+      "{count} eingefügte Zeile(n) wurden verworfen (maximale Zeilenzahl erreicht).",
+    "kumiko.field.embedded-list.paste-cells-unmatched":
+      "{count} Zelle(n) hatten keine passende Option und wurden nicht geändert.",
 
     // List — DataTable Toolbar, Empty-State, Search.
     "kumiko.list.search-placeholder": "Suchen…",
@@ -83,12 +84,20 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.widget.upload.uploading": "Wird hochgeladen…",
     "kumiko.widget.upload.done": "Hochgeladen",
     "kumiko.widget.upload.error": "Fehlgeschlagen",
+    "kumiko.widget.upload.rejected-type": "Dateityp nicht erlaubt",
+
+    // Widgets — StepBar screen-reader text for completed steps whose number is visually replaced by a checkmark.
+    "kumiko.widget.step-bar.done": "Erledigt",
 
     // Nav — Sidebar Tree (Toggle-aria-Labels).
     "kumiko.nav.expand": "Aufklappen",
     "kumiko.nav.collapse": "Zuklappen",
     "kumiko.nav.search": "Navigation durchsuchen…",
 
+    // Workspace — Switcher-Trigger aria-Label (renderer-web).
+    "kumiko.workspace.switch": "Workspace wechseln",
+    "kumiko.workspace.select": "Workspace wählen",
+
     // Dialog — Confirm-Buttons + Close-aria-Label.
     "kumiko.dialog.confirm": "Bestätigen",
     "kumiko.dialog.cancel": "Abbrechen",
@@ -211,8 +220,6 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.wizard.step": "Step {current} of {total}",
     "kumiko.wizard.step-with-title": "Step {current} of {total} · {title}",
 
-    "kumiko.widget.stepBar.done": "Done",
-
     "kumiko.version.update-available": "A new version is available.",
 
     "kumiko.toast.learn-more": "Learn more",
@@ -234,6 +241,10 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.field.embedded-list.move-down": "Move down",
     "kumiko.field.embedded-list.empty": "No rows yet.",
     "kumiko.field.embedded-list.empty-cta": "Add first row",
+    "kumiko.field.embedded-list.paste-rows-truncated":
+      "{count} pasted row(s) were dropped (max row count reached).",
+    "kumiko.field.embedded-list.paste-cells-unmatched":
+      "{count} cell(s) had no matching option and were left unchanged.",
 
     "kumiko.list.search-placeholder": "Search…",
     "kumiko.list.empty.title": "No entries yet.",
@@ -254,11 +265,18 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.widget.upload.uploading": "Uploading…",
     "kumiko.widget.upload.done": "Uploaded",
     "kumiko.widget.upload.error": "Failed",
+    "kumiko.widget.upload.rejected-type": "File type not allowed",
+
+    "kumiko.widget.step-bar.done": "Done",
 
     "kumiko.nav.expand": "Expand",
     "kumiko.nav.collapse": "Collapse",
     "kumiko.nav.search": "Search navigation…",
 
+    "kumiko.workspace.switch": "Switch workspace",
+    // Workspace-Switcher fallback label when activeId points at no visible workspace.
+    "kumiko.workspace.select": "Select workspace",
+
     "kumiko.dialog.confirm": "Confirm",
     "kumiko.dialog.cancel": "Cancel",
     "kumiko.dialog.close": "Close",

package/src/index.ts

@@ -180,6 +180,7 @@ export type {
   SectionProps,
   StepBarProps,
   TextProps,
+  WizardStepGroupProps,
 } from "./primitives";
 export { PrimitivesProvider, usePrimitives } from "./primitives";
 export { sortByAccessor } from "./sort-by-accessor";