@cosmicdrift/kumiko-renderer 0.386.0 → 0.388.0

package/dist/components/render-list.js

@@ -12,14 +12,15 @@ import { shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
 import { ListEmptyStateBody } from "./list-empty-state.js";
 import { needsActionConfirm } from "./render-edit-action-button.js";
 const SEARCH_DEBOUNCE_MS = 300;
-// Icon-less actions are promoted too (with a "plus" fallback at the call site).
+// Icon-less actions are promoted too; on phones the call site falls back to a
+// "plus" icon, on desktop the label carries the action.
 function isHeaderPromotableToolbarAction(action) {
     return action.style === "primary" && !needsActionConfirm(action);
 }
 export function RenderList(props) {
     const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, emptyContent, narrowed = false, defaultFilterActive: defaultFilterActiveProp = false, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, rowGrouping, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
-    // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
-    // wären Column-Header raw i18n-Keys.
+    // As in RenderEdit, fall back to the i18next context for translation;
+    // otherwise column headers would display raw i18n keys.
     const t = useTranslation();
     const translate = translateProp ?? t;
     const { DataTable, Button, Dialog, Input, Banner, PageHeader } = usePrimitives();
@@ -37,24 +38,31 @@ export function RenderList(props) {
     // The parent may echo our own debounced emits back late (router/URL round
     // trip), possibly after a newer emit already went out; adopting such a stale
     // echo would erase keys typed in between. All unechoed emits are kept, and a
-    // matching echo drops itself and every older one.
+    // matching echo drops itself and every older one. The render phase only reads
+    // the list (a discarded or repeated render must find the echo again); the
+    // matched entries are dropped in an effect.
     const pendingEmitsRef = useRef([]);
     if (searchValue !== syncedSearchValue) {
         setSyncedSearchValue(searchValue);
-        const echoIndex = pendingEmitsRef.current.indexOf(searchValue ?? "");
-        if (echoIndex >= 0) {
-            pendingEmitsRef.current.splice(0, echoIndex + 1);
-        }
-        else {
+        if (!pendingEmitsRef.current.includes(searchValue ?? "")) {
             setLocalQ(searchValue ?? "");
             pendingEmitsRef.current = [];
         }
     }
+    useEffect(() => {
+        const echoIndex = pendingEmitsRef.current.indexOf(syncedSearchValue ?? "");
+        if (echoIndex >= 0)
+            pendingEmitsRef.current.splice(0, echoIndex + 1);
+    }, [syncedSearchValue]);
     useEffect(() => {
         if (onSearchChange === undefined)
             return;
         if (localQ === (searchValue ?? ""))
             return;
+        // A late echo of an older emit changes searchValue but must not re-send
+        // the value that is already in flight.
+        if (pendingEmitsRef.current.at(-1) === localQ)
+            return;
         const timer = setTimeout(() => {
             pendingEmitsRef.current.push(localQ);
             onSearchChange(localQ);
@@ -62,33 +70,32 @@ export function RenderList(props) {
         return () => clearTimeout(timer);
     }, [localQ, searchValue, onSearchChange]);
     const vm = useMemo(() => computeListViewModel({ screen, entity, rows, translate, featureName }), [screen, entity, rows, translate, featureName]);
-    // Tier 2.7e-4: Reference-Field-Eagerload via Bridge-Component-Pattern.
-    // Hooks-Rule-Konflikt: pro reference-Spalte muss useReferenceLookup
-    // gerufen werden, aber die Anzahl varriiert per Schema. Lösung —
-    // ReferenceLookupBridge-Komponenten pro Spalte gemountet, die ihre
-    // Map über onMap-Callback in einen lokalen State veröffentlichen.
-    // Anzahl der Hook-Calls pro Bridge-Component ist konstant (1), und
-    // React verwaltet die mounted/unmounted Lifecycles beim Schema-
-    // Wechsel über die key-Property automatisch.
+    // Reference-field eager loading through bridge components.
+    // The Hooks rule requires useReferenceLookup for each reference column,
+    // but the number of columns varies with the schema. Each column therefore
+    // mounts a ReferenceLookupBridge that publishes its map to local state
+    // through onMap. Each bridge makes a constant number of hook calls (one),
+    // and React manages its lifecycle when the schema changes via key.
     const referenceColumns = useMemo(() => vm.columns
         .filter((c) => c.type === "reference" && c.refEntity !== undefined)
         .map((c) => ({
         field: c.field,
         refEntity: c.refEntity ?? "",
-        // Tier 2.7e Cross-Feature: refFeature kommt aus parseRefTarget
-        // im ViewModel (default = current featureName).
+        // refFeature comes from parseRefTarget in the ViewModel
+        // (default = the current featureName).
         refFeature: c.refFeature ?? featureName,
         labelField: c.refLabelField ?? "id",
     })), [vm.columns, featureName]);
     const [referenceLookups, setReferenceLookups] = useState({});
-    const handleLookupMap = useCallback((field, map) => {
+    const handleLookupMap = useCallback((field, lookup) => {
         setReferenceLookups((prev) => {
-            // skip-update wenn die Map identisch ist (Render-Loop-Schutz —
-            // Bridge-Component re-rendert sonst und schickt die gleiche Map
-            // wieder rein bis React in eine Endlosschleife geht).
-            if (prev[field] === map)
+            // Skip the update when the lookup is identical. Otherwise the bridge
+            // would re-render and send the same map back until React entered
+            // an infinite loop.
+            const current = prev[field];
+            if (current?.map === lookup.map && current.complete === lookup.complete)
                 return prev;
-            return { ...prev, [field]: map };
+            return { ...prev, [field]: lookup };
         });
     }, []);
     const resolveReferenceLink = useReferenceLinkResolver();
@@ -98,19 +105,23 @@ export function RenderList(props) {
         return vm.columns.map((col) => {
             if (col.type !== "reference")
                 return col;
-            // Author-deklarierter Renderer übersteuert immer — Default greift
-            // nur wenn keiner gesetzt ist.
+            // An author-declared renderer always takes precedence;
+            // the default is used only when none is set.
             if (col.renderer !== undefined)
                 return col;
-            const map = referenceLookups[col.field];
+            const published = referenceLookups[col.field];
+            const map = published?.map;
             const unknownKey = UNRESOLVED_REFERENCE_LABEL_KEYS[`${col.refFeature ?? featureName}:${col.refEntity ?? ""}`];
             // No raw id for entities that opt in: a placeholder while the lookup
-            // loads, the "unknown" label once it found nothing.
+            // loads, the "unknown" label once the complete lookup found nothing. A
+            // capped lookup page cannot prove absence, so it keeps the raw id.
             const unresolvedLabel = (id) => unknownKey === undefined
                 ? id
-                : map === undefined
+                : published === undefined
                     ? EMPTY_VALUE_PLACEHOLDER
-                    : translate(unknownKey);
+                    : published.complete
+                        ? translate(unknownKey)
+                        : id;
             const labelField = col.refLabelField ?? "id";
             const refEntity = col.refEntity ?? "";
             // Only a row the user can see is linkable: resolved by the server
@@ -145,11 +156,11 @@ export function RenderList(props) {
                 });
             };
             const renderer = (value, row) => {
-                // Tier 2.7e Server-Eagerload: wenn der Server _refs mit-
-                // schickt, lesen wir den Display-Wert direkt aus der
-                // resolved Row — kein Roundtrip durch die Bridge-Map nötig
-                // und keine limit:200-Constraint. EagerloadedRow-Type aus
-                // @cosmicdrift/kumiko-framework/db pinnt die Form von _refs.
+                // Server eager loading: when the server includes _refs, read the display
+                // value directly from the resolved row. This avoids a round trip
+                // through the bridge map and the limit:200 constraint. The
+                // EagerloadedRow type from @cosmicdrift/kumiko-framework/db defines
+                // the shape of _refs.
                 const resolved = eagerloadedRef(row, col.field);
                 if (Array.isArray(resolved) && resolved.length > 0) {
                     return resolved.map((r) => String(r[labelField] ?? r["id"] ?? "")).join(", ");
@@ -157,7 +168,7 @@ export function RenderList(props) {
                 if (isPlainRecord(resolved)) {
                     return String(resolved[labelField] ?? resolved["id"] ?? "");
                 }
-                // Renderer-Side-Fallback (kein Server-Eagerload aktiv).
+                // Renderer-side fallback when server eager loading is not active.
                 if (Array.isArray(value)) {
                     if (value.length === 0)
                         return EMPTY_VALUE_PLACEHOLDER;
@@ -182,9 +193,9 @@ export function RenderList(props) {
         ...vm,
         columns: enrichedColumns,
     }), [vm, enrichedColumns]);
-    // i18n-Defaults für Toolbar/Empty-State Strings — Caller kann jeden
-    // einzeln per Prop überschreiben, sonst kommen die Framework-Bundles
-    // (kumiko.actions.create, kumiko.list.search-placeholder, …).
+    // i18n defaults for toolbar and empty-state strings. The caller can
+    // override each one through a prop; otherwise the framework bundles provide
+    // them (kumiko.actions.create, kumiko.list.search-placeholder, …).
     const effectiveCreateLabel = translate(createLabel ?? screen.createLabel ?? "kumiko.actions.create");
     const effectiveSearchPlaceholder = translate(searchPlaceholder ?? screen.searchPlaceholder ?? "kumiko.list.search-placeholder");
     const nounKey = itemNounKey ?? `${featureName}:entity:${screen.entity}:noun`;
@@ -193,12 +204,12 @@ export function RenderList(props) {
         ? (count) => translate(nounKey, { count })
         : undefined;
     const toolbarStart = searchable ? (_jsx(Input, { kind: "text", id: "render-list-search", name: "search", value: localQ, onChange: setLocalQ, placeholder: effectiveSearchPlaceholder })) : undefined;
-    // Toolbar-End-Slot: optionaler Header-Slot (z.B. Cap-Counter, links im
-    // rechten Cluster) + Toolbar-Actions (List-Header-Buttons aus dem Schema)
-    // + optional "+ Neu" am rechten Edge. Der Header-Slot lebt IN der Toolbar-
-    // Zeile (gleicher Card-Rahmen), nicht als loser Text über dem Screen-Titel
-    // (Bug-Bash 3 #12). Reihenfolge = Array-Reihenfolge (Schema-deklariert),
-    // "+ Neu" zuletzt weil das die häufigste/auffälligste CTA ist.
+    // Toolbar-end slot: an optional header slot (for example, a cap counter,
+    // at the left of the right-hand cluster), toolbar actions from the schema,
+    // and an optional "+ New" button at the right edge. The header slot lives
+    // inside the toolbar row, with the same card frame, rather than as loose
+    // text above the screen title. Items retain array order, and "+ New" comes
+    // last because it is the most common and prominent CTA.
     const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
     const hasHeaderSlot = screen.slots?.header !== undefined;
     const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
@@ -218,30 +229,29 @@ export function RenderList(props) {
         hasToolbarActionsInToolbar ||
         (onCreate !== undefined && !createInPageHeader) ? (_jsxs(_Fragment, { children: [hasHeaderSlot && _jsx(ListHeaderSlotMount, { screen: screen }), hasToolbarActionsInToolbar &&
                 toolbarActionsInToolbar.map((a) => (_jsx(ToolbarActionView, { action: a, iconOnly: toolbarIconOnly, Button: Button, Dialog: Dialog, Banner: Banner }, a.id))), !createInPageHeader && createButton] })) : undefined;
-    // Empty-State: Default zeigt Heading + Description + optional CTA-
-    // Button. Caller kann via emptyState-Prop komplett überschreiben.
-    // Wenn weder onCreate noch ein Override gegeben ist, fällt die
-    // DataTable auf den DataTable-Default zurück (`kumiko.list.no-entries`).
+    // Empty state: by default, show a heading, description, and optional CTA
+    // button. The caller can replace it completely through emptyState.
+    // Without onCreate or an override, DataTable uses its default
+    // (`kumiko.list.no-entries`).
     const defaultFilterActive = defaultFilterActiveProp && onFilterReset !== undefined;
     const composedEmptyState = emptyState ??
         (onCreate !== undefined || emptyContent !== undefined || narrowed || defaultFilterActive ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, defaultFilterActive: defaultFilterActive, ...(onFilterReset !== undefined && { onShowAll: onFilterReset }), translate: translate, createButton: onCreate !== undefined && !narrowed && !defaultFilterActive && !createInPageHeader ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined);
-    // Title-Resolution: ein konventioneller i18n-Key `screen:<id>.title`.
-    // Wenn das Bundle den Key kennt, schöner Titel; sonst kommt der
-    // screenId selber raus (kein "Untitled"-Fallback — der App-Dev sieht
-    // dann dass die Übersetzung fehlt).
+    // Title resolution uses the conventional i18n key `screen:<id>.title`.
+    // If the bundle knows the key, use its translated title; otherwise use
+    // screenId so the app developer can see that the translation is missing.
     const titleKey = `screen:${screen.id}.title`;
     const resolvedTitle = translate(titleKey);
     const toolbarTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
-    // ListSort = DataTableSort (use-list-url-state aliased) — kein Cast nötig.
+    // ListSort = DataTableSort (aliased in use-list-url-state), so no cast is needed.
     return (_jsxs(_Fragment, { children: [createInPageHeader && PageHeader !== undefined && _jsx(PageHeader, { actions: createButton }), promotedActionButton !== undefined && PageHeader !== undefined && (_jsx(PageHeader, { actions: promotedActionButton })), referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: handleLookupMap }, rc.field))), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...(onRowClick !== undefined && { onRowClick }), ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }), ...(toolbarStart !== undefined && { toolbarStart }), ...(description !== undefined && { toolbarDescription: description }), ...(toolbarEnd !== undefined && { toolbarEnd }), ...(sort !== undefined && { sort }), ...(onSortChange !== undefined && { onSortChange }), ...(pager !== undefined && { pager }), ...(onReachEnd !== undefined && { onReachEnd }), ...(loadingMore !== undefined && { loadingMore }), ...(hasMore !== undefined && { hasMore }), ...(itemNoun !== undefined && { itemNoun }), ...(rowActions !== undefined && { rowActions }), ...(rowActionMode !== undefined && { rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(filterFacets !== undefined && { filterFacets }), ...(filterValues !== undefined && { filterValues }), ...(onFilterChange !== undefined && { onFilterChange }), ...(onFilterReset !== undefined && { onFilterReset }), ...(dateRangeFacets !== undefined && { dateRangeFacets }), ...(onDateRangeChange !== undefined && { onDateRangeChange }), ...(chromeless !== undefined && { chromeless }), ...(scrollBody !== undefined && { scrollBody }), ...(screenPadding !== undefined && { screenPadding }), ...(expandedRowIds !== undefined && { expandedRowIds }), ...(onToggleRowExpanded !== undefined && { onToggleRowExpanded }), ...(renderExpandedRow !== undefined && { renderExpandedRow }), testId: "render-list-table" })] }));
 }
-// Header-Slot in der Listen-Toolbar (toolbarEnd): `screen.slots.header` ist
-// eine PlatformComponent (`{ react: { __component: "X" } }`), aufgelöst über
-// dieselbe ExtensionSectionsProvider-Registry wie entityEdit-Sections.
-// entityId ist null (Listen-Kontext, keine Row); die Component lädt ihre
-// Daten selbst (z.B. ein Cap-Counter aus einer usage-Query). Eigene
-// Component wegen Rules-of-Hooks — useExtensionSectionComponent darf nicht
-// konditional im RenderList-Body laufen.
+// Header slot in the list toolbar (toolbarEnd): `screen.slots.header` is
+// a PlatformComponent (`{ react: { __component: "X" } }`) resolved through
+// the same ExtensionSectionsProvider registry as entityEdit sections.
+// entityId is null in the list context because there is no row; the component
+// loads its own data (for example, a cap counter from a usage query). A
+// separate component is required by the Rules of Hooks because
+// useExtensionSectionComponent must not run conditionally in RenderList.
 function ListHeaderSlotMount({ screen, }) {
     const header = screen.slots?.header;
     const name = header !== undefined ? extensionSectionName(header) : undefined;
@@ -261,37 +271,36 @@ function ListHeaderSlotMount({ screen, }) {
     // (useListUrlState) — e.g. a tag filter narrowing the list to an id-set.
     return _jsx(Component, { entityName: screen.entity, entityId: null, screenId: screen.id });
 }
-// Tier 2.7e-4: Bridge-Component pro reference-Spalte. Mounted für jede
-// Spalte einmal, ruft useReferenceLookup unconditional (Hook-Rules
-// happy), und published die Map über onMap an den Parent. React
-// verwaltet das Mounting/Unmounting beim Schema-Wechsel über die
-// key-Prop im map-Loop des Parents.
+// Bridge component for each reference column. It is mounted once per
+// column, calls useReferenceLookup unconditionally, and publishes the map
+// to the parent through onMap. React manages mounting and unmounting when
+// the schema changes through the key prop in the parent's map loop.
 function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
     const lookup = useReferenceLookup(featureName, refEntity, labelField);
-    // useEffect statt direktem call damit setState außerhalb des Render-
-    // Pfads passiert (sonst React-Warning "Cannot update a component
-    // while rendering a different component").
-    // Unpublished while loading or after a failed lookup: the renderer treats a missing map as
-    // "not resolved", an empty published map as "nothing found". Only the latter may say "Unknown".
+    // Use an effect rather than calling directly so setState runs outside the
+    // render path; otherwise React warns about updating one component while
+    // rendering another.
+    // Do not publish while loading or after a failed lookup: a missing map means
+    // "not resolved", whereas an empty published map means "nothing found".
+    // Only the latter may display "Unknown".
     const resolved = !lookup.loading && !lookup.failed;
     useEffect(() => {
         if (resolved)
-            onMap(field, lookup.map);
-    }, [field, lookup.map, resolved, onMap]);
+            onMap(field, { map: lookup.map, complete: lookup.complete });
+    }, [field, lookup.map, lookup.complete, resolved, onMap]);
     return null;
 }
-// ToolbarActionView — pro Toolbar-Action ein Button (+ Confirm-Dialog
-// wenn confirm gesetzt). Same Pattern wie RowAction (Inline-Variante)
-// aber ohne row-Context. busy-State während async onTrigger; Dialog
-// öffnet sich vor dem Trigger wenn confirm/danger gesetzt.
+// ToolbarActionView renders one button per toolbar action, with a confirm
+// dialog when required. It follows the inline RowAction pattern but has no
+// row context. The busy state covers async onTrigger; the dialog opens before
+// the trigger when confirmation is required for confirm/danger actions.
 function ToolbarActionView({ action, iconOnly = false, Button, Dialog, Banner, }) {
     const [busy, setBusy] = useState(false);
     const [confirmOpen, setConfirmOpen] = useState(false);
-    // Toolbar-Actions haben (anders als rowActions, die über die DataTable-
-    // Primitive laufen) keine Toast-Primitive zur Verfügung — ein inline
-    // Error-Banner ist der surfacing-Pfad hier. Gleicher Grund wie bei
-    // rowActions (Prod-Bug 2026-06-07): ein verschlucktes Failure-Result
-    // sieht für den User wie "nichts passiert" aus.
+    // Toolbar actions do not have access to the toast primitive, unlike
+    // rowActions routed through the DataTable primitive, so an inline error
+    // banner is used to surface failures. Without it, a swallowed failure result
+    // would look to the user as though nothing happened.
     const [errorText, setErrorText] = useState(null);
     const trigger = async () => {
         setBusy(true);
@@ -309,7 +318,7 @@ function ToolbarActionView({ action, iconOnly = false, Button, Dialog, Banner, }
     const variant = action.style ?? "secondary";
     const needsConfirm = needsActionConfirm(action);
     const showIconOnly = iconOnly && action.icon !== undefined;
-    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: variant, loading: busy, ...(action.icon !== undefined && { icon: action.icon }), size: showIconOnly ? "icon" : "sm", ...(showIconOnly && { ariaLabel: action.label, title: action.label }), onClick: () => {
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: variant, loading: busy, ...(action.icon !== undefined && { icon: action.icon }), size: showIconOnly ? "icon" : "md", ...(showIconOnly && { ariaLabel: action.label, title: action.label }), onClick: () => {
                     if (needsConfirm) {
                         setConfirmOpen(true);
                     }

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

@@ -12,10 +12,10 @@ 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
+// Trailing-edge debounce for patch()-triggered draft saves. 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
+// (the 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;
@@ -40,7 +40,7 @@ function mintDraftId() {
     return `draft-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
 }
 export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draftStorage, }) {
-    // Create-mode draftId (issue #1913) — resumed from `sessionStorage` (web)
+    // Create-mode draftId — 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`
@@ -55,7 +55,7 @@ export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draf
     // 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).
+    // after the user just submitted.
     const didListRef = useRef(false);
     const [draftCandidates, setDraftCandidates] = useState(null);
     // Derived from the screen id + the host entity id only — never from
@@ -64,7 +64,7 @@ export function useWizardFormDraftState({ screenId, entityId, isCreateMode, draf
     // unchanged. Create-mode: `${screenId}:new:${draftId}` once a draftId
     // exists (resumed, adopted, or minted), `undefined` before that — two
     // parallel create sessions on the same screen must never collapse onto
-    // the same key (kumiko-framework#1908).
+    // the same key.
     const draftKey = useMemo(() => isCreateMode
         ? draftId !== null
             ? `${screenId}:new:${draftId}`
@@ -133,7 +133,7 @@ export function useWizardFormDraftRestore({ screenId, isCreateMode, draftEnabled
         hasNavigatedRef,
         setRawStep,
     ]);
-    // Mount-time fallback (issue #1913) for create-mode when no draftId
+    // Mount-time fallback 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
@@ -186,7 +186,7 @@ export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled,
     // (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" —
+        // Locked state: `disabled` means "no write possible" —
         // repointing draftKey and patching in the candidate's values is exactly
         // that, so a locked form must not adopt a draft.
         // skip: a locked form keeps its current draft (reason above).
@@ -202,8 +202,8 @@ export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled,
     //
     // 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
+    // above — both call this on step 0 too): mints the draftId here
+    // 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`.
@@ -220,7 +220,7 @@ export function buildWizardDraftActions({ screenId, isCreateMode, draftEnabled,
             key = `${screenId}:new:${mintedId}`;
             // A stale picker from the mount-time list fallback must not survive a
             // mint — picking a candidate afterwards would repoint draftKey at an
-            // unrelated draft mid-edit and overwrite it (#1908).
+            // unrelated draft mid-edit and overwrite it.
             setDraftCandidates(null);
         }
         // skip: create-mode with a draftId that failed to mint — unreachable

package/dist/context/dispatcher-context.js

@@ -32,11 +32,11 @@ export function useDispatcher() {
     }
     return dispatcher;
 }
-// Soft-Variante: null wenn kein Provider mounted statt throw. Für
-// Components die einen Dispatcher OPTIONAL brauchen (z.B. KumikoScreen
-// rendert mit/ohne rowActions; die Test-Suite mountet kein Dispatcher
-// wenn der Screen keine Mutation triggert). Caller ist zuständig dass
-// er bei null einen sinnvollen Fallback hat (typisch: kein Action-Wiring).
+// Soft variant: returns null when no provider is mounted instead of throwing. For
+// components that optionally need a Dispatcher (for example, KumikoScreen renders
+// with or without rowActions; the test suite does not mount a Dispatcher when the
+// screen triggers no mutation). Callers must provide a sensible fallback for null
+// (typically, no action wiring).
 export function useOptionalDispatcher() {
     return useContext(DispatcherContext) ?? undefined;
 }

package/dist/context/user-roles-context.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from "react";
 // Threads the current user's roles through the tree so KumikoScreen can
-// gate role-restricted screens at render time (see #1203 — nav filtering
-// alone doesn't stop a direct-URL/screenQn hit on a role-gated screen).
+// gate role-restricted screens at render time — nav filtering alone
+// doesn't stop a direct-URL/screenQn hit on a role-gated screen).
 // Apps wire this from their `shell` render-prop, the same place they
 // already pass `user` to WorkspaceShell for nav filtering.
 //

package/dist/flow-diagram/render.js

@@ -23,7 +23,15 @@ function cardSize(node) {
     return { width, height };
 }
 function assertEdgesReferenceKnownNodes(spec) {
-    const ids = new Set(spec.nodes.map((n) => n.id));
+    const ids = new Set();
+    for (const node of spec.nodes) {
+        if (ids.has(node.id))
+            throw new Error(`FlowSpec: duplicate node id "${node.id}"`);
+        ids.add(node.id);
+        if (node.icon !== undefined && node.icon !== "ai" && !Object.hasOwn(ICONS, node.icon)) {
+            throw new Error(`FlowSpec: node "${node.id}" has unknown icon "${node.icon}"`);
+        }
+    }
     for (const edge of spec.edges) {
         if (!ids.has(edge.from))
             throw new Error(`FlowSpec: edge references unknown node "${edge.from}"`);

package/dist/headless/apex/index.d.ts

@@ -231,6 +231,5 @@ export declare function injectPageHead(html: string, tagsHtml: string): string;
  *  the shared timeout. Never throws and never changes `html` on a resolver
  *  error, a `null` resolve, or a timeout — the caller's shell always ships
  *  unchanged. runProdApp and runDevApp both call this single function, so a
- *  future change to timeout or fallback semantics has one place to land
- *  (kumiko-framework#3026). */
+ *  future change to timeout or fallback semantics has one place to land. */
 export declare function resolveAndInjectPageHead(html: string, resolvePageHead: PageHeadResolver, input: PageHeadResolveInput): Promise<string>;

package/dist/headless/apex/index.js

@@ -8,8 +8,8 @@ import { APEX_STRUCTURAL_CSS } from "./css.js";
 import { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT } from "./lightbox.js";
 export { APEX_NAV_MENU_CSS, APEX_NAV_TOGGLE_RESPONSIVE_CSS, APEX_STRUCTURAL_CSS } from "./css.js";
 export { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT, APEX_LIGHTBOX_SCRIPT_CSP_HASH, } from "./lightbox.js";
-// JSON in <script>-Kontext: `<` als < serialisieren, damit weder
-// `</script>` noch `<!--` aus dem Block ausbrechen kann (JSON bleibt valide).
+// JSON in <script> context: serialize `<` as < so neither
+// `</script>` nor `<!--` can escape the block (JSON remains valid).
 function scriptSafeJsonHtml(value) {
     return JSON.stringify(value).replace(/</g, "\\u003c");
 }
@@ -265,7 +265,7 @@ export function renderApexHeadTags(head) {
 export function renderApexPage(page) {
     const { head, brand } = page;
     const theme = page.theme ?? "light";
-    // Brand-CSS ist app-authored (Trust-Boundary siehe Datei-Header), kein Tenant-Input.
+    // Brand CSS is app-authored (see the file header for the trust boundary), not tenant input.
     const cssHtml = (brand.fontFaceCss ?? "") + brand.tokensCss + APEX_STRUCTURAL_CSS;
     const sectionsHtml = page.sections.map(renderSection).join("\n\n    ");
     // interactive-widget is ignored by iOS Safari; apex pages have no fixed bottom bars, so
@@ -308,7 +308,7 @@ export function injectPageHead(html, tagsHtml) {
 // Resolver runs alongside the request, never gates it: a slow, throwing, or
 // null-returning resolver must never turn a 200 shell into a 500 or a
 // stall. One constant shared by runProdApp and runDevApp so both time out
-// on the same value (kumiko-framework#3026).
+// on the same value.
 const PAGE_HEAD_TIMEOUT_MS = 300;
 async function resolvePageHeadWithTimeout(resolvePageHead, input) {
     let timer;
@@ -367,8 +367,7 @@ function toApexHead(meta) {
  *  the shared timeout. Never throws and never changes `html` on a resolver
  *  error, a `null` resolve, or a timeout — the caller's shell always ships
  *  unchanged. runProdApp and runDevApp both call this single function, so a
- *  future change to timeout or fallback semantics has one place to land
- *  (kumiko-framework#3026). */
+ *  future change to timeout or fallback semantics has one place to land. */
 export async function resolveAndInjectPageHead(html, resolvePageHead, input) {
     const meta = await resolvePageHeadWithTimeout(resolvePageHead, input);
     if (!meta)

package/dist/headless/form/form-controller.js

@@ -68,7 +68,7 @@ function stripUntouchedEmptyStrings(values, initial, forceIncludeEmpty) {
     let out;
     for (const key of Object.keys(v)) {
         // Value-based seed strip, except keys previously submitted as "" after a
-        // real clear — those must survive post-rebase submits (#1858).
+        // real clear — those must survive post-rebase submits.
         if (!forceIncludeEmpty.has(key) && v[key] === "" && ini[key] === "") {
             out ??= { ...v };
             delete out[key];
@@ -105,7 +105,7 @@ export function createFormController(options) {
     let initial = { ...options.initial };
     let errors = Object.freeze({});
     // Keys last submitted as "" (intentional clear). Survives rebase so a later
-    // submit of other fields does not drop them (#1858).
+    // submit of other fields does not drop them.
     const forceIncludeEmpty = new Set();
     // ctx is cast-held as TCtx; `undefined` is valid when callers don't
     // declare conditional predicates that depend on it.
@@ -166,7 +166,7 @@ export function createFormController(options) {
     function runValidate(scope, opts) {
         // See the validate() doc comment in types.ts for the scope contract.
         // A scope entry matches its exact path and everything below it, but not
-        // siblings: `address.city` must not pull in `address.zip` (#1898).
+        // siblings: `address.city` must not pull in `address.zip`.
         const isInScope = scope === undefined
             ? undefined
             : (path) => scope.some((entry) => path === entry || path.startsWith(`${entry}.`));
@@ -193,8 +193,8 @@ export function createFormController(options) {
                 hiddenFields.add(fieldKey);
         }
         // Root-level .refine() issues use path "(root)". Wizard step validate()
-        // still drops them (#1885); submit() passes includeRoot so RenderEdit
-        // fields={…} cannot silently skip cross-field rules (#1907).
+        // still drops them; submit() passes includeRoot so RenderEdit
+        // fields={…} cannot silently skip cross-field rules.
         const relevantIssues = relevantFieldIssues(zodErrorToFieldIssues(parsed.error), {
             hiddenFields,
             ...(scope !== undefined && { scope }),
@@ -217,6 +217,13 @@ export function createFormController(options) {
             errors = Object.freeze({});
         invalidate();
     }
+    function runRebaseFields(fields) {
+        initial = {
+            ...initial,
+            ...Object.fromEntries(fields.map((field) => [field, values[field]])),
+        };
+        invalidate();
+    }
     // Stale-submit-safe rebase. Difference to runRebase: the baseline is
     // taken from the values that were actually SENT to the server, not
     // from `values` at the moment the server replied. If the user typed
@@ -296,6 +303,7 @@ export function createFormController(options) {
             invalidate();
         },
         rebase: runRebase,
+        rebaseFields: runRebaseFields,
         setCtx(nextCtx) {
             // Cast back to TCtx: setCtx's public signature takes unknown so
             // callers don't need to plumb generics. If conditions depend on ctx
@@ -382,7 +390,7 @@ export function createFormController(options) {
                 const result = await dispatcher.write(submitCfg.type, payload, { requestId });
                 unansweredAttempt = isTransportFailure(result) ? { requestId, fingerprint } : null;
                 if (result.isSuccess) {
-                    // Remember intentional empty clears so post-rebase submits keep them (#1858).
+                    // Remember intentional empty clears so post-rebase submits keep them.
                     if (payload && typeof payload === "object" && !Array.isArray(payload)) {
                         for (const [k, v] of Object.entries(payload)) {
                             if (v === "")

package/dist/headless/form/types.d.ts

@@ -33,6 +33,7 @@ export type FormController<TValues extends FormValues> = {
     validate(scope?: readonly FormScopeKey<TValues>[]): boolean;
     reset(): void;
     rebase(): void;
+    rebaseFields(fields: readonly string[]): void;
     setCtx(ctx: unknown): void;
     submit<TData = unknown>(): Promise<SubmitResult<TData>>;
 };

package/dist/headless/form/zod-bridge.js

@@ -46,8 +46,8 @@ export function zodErrorToFieldIssues(error) {
 }
 // The issues that count for validity: hidden fields never block, and a
 // scope narrows to the listed paths (an entry matches itself and everything
-// below it, not siblings — #1898). `includeRoot` keeps "(root)" refine issues
-// inside a scope (submit passes it, #1907). Shared by the controller's
+// below it, not siblings). `includeRoot` keeps "(root)" refine issues
+// inside a scope (submit passes it). Shared by the controller's
 // validate() and RenderEdit's `valid` dry-run so the two cannot drift.
 export function relevantFieldIssues(issues, opts) {
     const { hiddenFields, scope, includeRoot } = opts;