@cosmicdrift/kumiko-renderer 0.374.0 → 0.378.0

package/dist/components/render-edit.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { evalFieldCondition, isFieldsEditSection, normalizeEditField, PROJECTION_DETAIL_ENTITY, sectionFieldSpecs, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { computeEditViewModel, groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues, } from "@cosmicdrift/kumiko-headless";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { computeEditViewModel, groupIssuesByPath, relevantFieldIssues, zodErrorToFieldIssues, } from "../headless/index.js";
+import { changedDerivedValues } from "./form-derivation-patch.js";
 import { RenderEditActionButton } from "./render-edit-action-button.js";
 import { AllFieldsRequiredProvider } from "./render-field.js";
 import { useActionMenuItems } from "./use-action-menu-items.js";
@@ -229,7 +230,7 @@ function resolveTitleTemplate(template, values, translate, fallback) {
     return translate(template, values);
 }
 export function RenderEdit(props) {
-    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, } = props;
+    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, refreshToken, onDirtyChange, onCopyLink, actions, menuActions, onRelatedListDrawerAction, submitLabel, submitVariant, submitWithoutChanges, footerActions, summary, labelAppendix, fieldAppendix, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled: disabledProp = false, viewMode = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, headerRegion, buildSectionActions, leadContent, submitBlocked = false, formDerivation, } = props;
     // View mode is a locked form, so everything keyed on `disabled` follows.
     const disabled = disabledProp || viewMode;
     const i18nScreenId = props.i18nScreenId ?? screen.id;
@@ -367,6 +368,16 @@ export function RenderEdit(props) {
         ...(ctx !== undefined && { ctx }),
         ...(submitConfig !== undefined && { submit: submitConfig }),
     });
+    // Derived fields are written into form state (not only displayed) so required
+    // validation and the submit payload carry them; only a real change is set, which
+    // keeps this from looping.
+    useEffect(() => {
+        if (formDerivation === undefined)
+            return;
+        const patch = changedDerivedValues(snapshot.values, formDerivation);
+        if (patch !== undefined)
+            controller.setValues(patch); // @cast-boundary form-values
+    }, [snapshot.values, formDerivation, controller]);
     // Wired at the user-input boundary, not in controller.setField: computed
     // fields, prefill, draft restore and action patches also call setValues
     // after a failed submit and must not wipe the errors.
@@ -654,7 +665,9 @@ export function RenderEdit(props) {
         featureName,
         mode: writeVerb,
         ...(!isCreateMode && entityIdProp != null && { entityId: entityIdProp }),
+        ...(formDerivation !== undefined && { derivation: formDerivation }),
     }), [
+        formDerivation,
         screen,
         entity,
         snapshot.values,
@@ -1075,6 +1088,7 @@ export function RenderEdit(props) {
     wizardBackRef.current = isWizard ? handleWizardBack : () => { };
     // Screen forms (entityEdit/actionForm filling the shell height) drop the card;
     // the title then lives in the shell header when the shell offers a slot.
+    const rootIssues = snapshot.errors[ROOT_ISSUE_PATH] ?? [];
     const isScreenForm = fillScreenHeight === true && hideSectionTitles !== true && !insideDrawer;
     const titleInShell = PageHeader !== undefined &&
         pageHeaderSlotAvailable &&
@@ -1480,7 +1494,8 @@ export function RenderEdit(props) {
                                     onReload();
                                     setFormError(null);
                                     setExtraDeleteIssues([]);
-                                }, testId: "render-edit-form-error-reload", children: translate("kumiko.actions.reload") })) : undefined, children: [_jsx(Text, { testId: "render-edit-form-error-key", children: translate(formError.i18nKey, formError.i18nParams) }), extraDeleteIssues.map((issue) => (_jsx(Text, { testId: "render-edit-form-error-extra", children: translate(issue.i18nKey, issue.params) }, `${issue.path}:${issue.i18nKey}`)))] })), (snapshot.errors[ROOT_ISSUE_PATH] ?? []).map((issue) => (_jsx(Banner, { variant: "error", testId: "render-edit-root-issue", children: _jsx(Text, { children: translate(issue.i18nKey, issue.params) }) }, issue.i18nKey))), extensionErrorKey !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-extension-error", children: _jsx(Text, { testId: "render-edit-extension-error-key", children: translate(extensionErrorKey) }) })), actionError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-action-error", children: actionError })), onDelete !== undefined && (_jsx(Dialog, { open: confirmDeleteOpen, onOpenChange: setConfirmDeleteOpen, title: translate("kumiko.actions.delete-confirm"), confirmLabel: translate("kumiko.actions.delete"), variant: "danger", onConfirm: async () => {
+                                }, testId: "render-edit-form-error-reload", children: translate("kumiko.actions.reload") })) : undefined, children: [_jsx(Text, { testId: "render-edit-form-error-key", children: translate(formError.i18nKey, formError.i18nParams) }), rootIssues.map((issue) => (_jsx(Text, { testId: "render-edit-form-error-root", children: translate(issue.i18nKey, issue.params) }, `${issue.path}:${issue.i18nKey}`))), extraDeleteIssues.map((issue) => (_jsx(Text, { testId: "render-edit-form-error-extra", children: translate(issue.i18nKey, issue.params) }, `${issue.path}:${issue.i18nKey}`)))] })), formError === null &&
+                            rootIssues.map((issue) => (_jsx(Banner, { variant: "error", testId: "render-edit-root-issue", children: _jsx(Text, { children: translate(issue.i18nKey, issue.params) }) }, issue.i18nKey))), extensionErrorKey !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-extension-error", children: _jsx(Text, { testId: "render-edit-extension-error-key", children: translate(extensionErrorKey) }) })), actionError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-action-error", children: actionError })), onDelete !== undefined && (_jsx(Dialog, { open: confirmDeleteOpen, onOpenChange: setConfirmDeleteOpen, title: translate("kumiko.actions.delete-confirm"), confirmLabel: translate("kumiko.actions.delete"), variant: "danger", onConfirm: async () => {
                                 const rejection = await onDelete();
                                 // A rejected delete (e.g. a preDelete hook) carries its reason in
                                 // the field issues; the top-level key is only "validation failed".

package/dist/components/render-field.d.ts

@@ -1,5 +1,5 @@
-import { type EditFieldViewModel, type FieldIssue } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import { type EditFieldViewModel, type FieldIssue } from "../headless/index.ts";
 import { type FieldProps } from "../primitives.tsx";
 export type RenderFieldProps = {
     readonly field: EditFieldViewModel;

package/dist/components/render-field.js

@@ -1,6 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { isFormatSpec, SYSTEM_REFERENCE_LABELS, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { applyFormatSpec, currencyDecimals, EMPTY_VALUE_PLACEHOLDER, } from "@cosmicdrift/kumiko-headless";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { createContext, Fragment, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { useAppFeatures } from "../app/app-features-context.js";
@@ -12,6 +11,8 @@ import { evalRowExtractor } from "../app/row-actions.js";
 import { screenAccessAllows } from "../app/screen-access.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
+import { fileIdsOf } from "../file-ids-of.js";
+import { applyFormatSpec, currencyDecimals, EMPTY_VALUE_PLACEHOLDER, } from "../headless/index.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
 import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
@@ -280,7 +281,7 @@ function inputId(field) {
 // Doesn't resolve the `string` (cross-feature QN) FieldRenderer variant — the
 // list-column path (DataTableCell) doesn't either, so this stays in parity.
 function FieldRendererOutput({ field, renderer, row, appLocale, }) {
-    const { Text, JsonView } = usePrimitives();
+    const { Text, JsonView, FileValueList } = usePrimitives();
     const t = useTranslation();
     const componentName = !isFormatSpec(renderer) && typeof renderer === "object" && renderer !== null
         ? extensionSectionName(renderer)
@@ -293,6 +294,12 @@ function FieldRendererOutput({ field, renderer, row, appLocale, }) {
         if (renderer.format === "json" && JsonView !== undefined) {
             return (_jsx(JsonView, { value: field.value, indent: renderer.indent, testId: `field-value-${field.field}` }));
         }
+        if (renderer.format === "file" && FileValueList !== undefined) {
+            const fileIds = fileIdsOf(field.value);
+            if (fileIds.length === 0)
+                return _jsx(Text, { testId: `field-value-${field.field}`, children: EMPTY_VALUE_PLACEHOLDER });
+            return _jsx(FileValueList, { fileIds: fileIds, testId: `field-value-${field.field}` });
+        }
         // App locale as default when the FormatSpec declares none of its own —
         // otherwise locale-sensitive formats (timestamp/date/number/decimal/
         // bigInt/unit) fell back to Intl's runtime default instead of the app
@@ -494,6 +501,9 @@ function renderInput({ field, id, hasError, onChange, Input, appLocale, Banner,
             if (field.type === "text" && field.format === "password") {
                 return (_jsx(Input, { kind: "password", ...common, value: stringValue(field.value), onChange: (v) => onChange(v) }));
             }
+            if (field.type === "text" && field.format === "month") {
+                return (_jsx(Input, { kind: "month", ...common, value: stringValue(field.value), onChange: (v) => onChange(v) }));
+            }
             // text + unknown scalar type → text input. If TextFieldDef.multiline
             // is set (the view-model carries it), the renderer switches to
             // textarea. longText always renders a textarea — that's the point of

package/dist/components/render-list.d.ts

@@ -1,6 +1,6 @@
 import type { EntityDefinition, EntityListScreenDefinition, IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
-import type { ListRowViewModel, Translate } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import type { ListRowViewModel, Translate } from "../headless/index.ts";
 import type { ListSort } from "../hooks/use-list-url-state.ts";
 import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableProps, type DataTableRowAction, type DataTableRowActionMode, type DataTableRowGrouping } from "../primitives.tsx";
 import { type ListEmptyStateContent } from "./list-empty-state.tsx";

package/dist/components/render-list.js

@@ -1,8 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { computeListViewModel, EMPTY_VALUE_PLACEHOLDER } from "@cosmicdrift/kumiko-headless";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
 import { useReferenceLinkResolver } from "../app/reference-link.js";
+import { computeListViewModel, EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
 import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
@@ -104,7 +104,7 @@ export function RenderList(props) {
             const labelField = col.refLabelField ?? "id";
             const refEntity = col.refEntity ?? "";
             // Only a row the user can see is linkable: resolved by the server
-            // eagerload or by the lookup query. A multi-reference stays text.
+            // eagerload or by the lookup query. A multi-reference links per entry via linkItemsFor.
             const linkFor = (value, row) => {
                 if (value === null || value === undefined || value === "" || Array.isArray(value)) {
                     return undefined;
@@ -118,6 +118,22 @@ export function RenderList(props) {
                     map?.has(id);
                 return resolved === true ? resolveReferenceLink(refEntity, id) : undefined;
             };
+            const linkItemsFor = (value, row) => {
+                if (!Array.isArray(value) || value.length === 0)
+                    return undefined;
+                const eagerloaded = eagerloadedRef(row, col.field);
+                const eagerById = new Map(Array.isArray(eagerloaded) ? eagerloaded.map((r) => [String(r["id"]), r]) : []);
+                return value.map((v) => {
+                    const id = String(v);
+                    const target = eagerById.get(id);
+                    const label = String(target?.[labelField] ?? map?.get(id) ?? id);
+                    // Only a row the user can see is linkable: server eagerload or lookup query.
+                    const link = target !== undefined || map?.has(id) === true
+                        ? resolveReferenceLink(refEntity, id)
+                        : undefined;
+                    return { id, label, ...(link !== undefined && { link }) };
+                });
+            };
             const renderer = (value, row) => {
                 // Tier 2.7e Server-Eagerload: wenn der Server _refs mit-
                 // schickt, lesen wir den Display-Wert direkt aus der
@@ -142,7 +158,7 @@ export function RenderList(props) {
                 const idStr = String(value);
                 return map?.get(idStr) ?? idStr;
             };
-            return { ...col, renderer, linkFor };
+            return { ...col, renderer, linkFor, linkItemsFor };
         });
     }, [vm.columns, referenceColumns, referenceLookups, resolveReferenceLink]);
     const enrichedVm = useMemo(() => ({
@@ -190,7 +206,7 @@ export function RenderList(props) {
     // Wenn weder onCreate noch ein Override gegeben ist, fällt die
     // DataTable auf den DataTable-Default zurück (`kumiko.list.no-entries`).
     const composedEmptyState = emptyState ??
-        (onCreate !== undefined || emptyContent !== undefined || narrowed ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, translate: translate, createButton: onCreate !== undefined && !narrowed ? (_jsx(Button, { variant: "primary", icon: "plus", onClick: onCreate, testId: "render-list-empty-create", children: effectiveCreateLabel })) : undefined })) : undefined);
+        (onCreate !== undefined || emptyContent !== undefined || narrowed ? (_jsx(ListEmptyStateBody, { content: emptyContent, narrowed: narrowed, translate: translate, createButton: onCreate !== undefined && !narrowed && !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

package/dist/components/write-form-section.d.ts

@@ -1,5 +1,5 @@
-import type { EditWriteFormSectionViewModel, Translate } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import type { EditWriteFormSectionViewModel, Translate } from "../headless/index.ts";
 export type WriteFormSectionProps = {
     readonly section: EditWriteFormSectionViewModel;
     readonly featureName: string;

package/dist/components/write-form-section.js

@@ -1,9 +1,9 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
 import { useEffect, useMemo, useRef, useState } from "react";
 import * as z from "zod";
 import { isPresent, REQUIRED_FIELD_I18N_KEY } from "../app/form-schema.js";
 import { dispatcherErrorText } from "../app/write-failed-error.js";
+import { I18N_KEY_PARAM } from "../headless/index.js";
 import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
 import { STICKY_PRIMARY_ACTION_PROP, usePrimitives } from "../primitives.js";

package/dist/context/dispatcher-context.d.ts

@@ -1,5 +1,5 @@
-import type { Dispatcher, DispatcherStatus } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import type { Dispatcher, DispatcherStatus } from "../headless/index.ts";
 import { type QueryPools } from "./query-pool.ts";
 export type DispatcherProviderProps = {
     readonly dispatcher: Dispatcher;

package/dist/file-ids-of.d.ts

@@ -0,0 +1 @@
+export declare function fileIdsOf(value: unknown): readonly string[];

package/dist/file-ids-of.js

@@ -0,0 +1,7 @@
+export function fileIdsOf(value) {
+    if (typeof value === "string")
+        return value === "" ? [] : [value];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string" && entry !== "");
+}

package/dist/flow-diagram/icons.d.ts

@@ -0,0 +1,3 @@
+import type { FlowIcon } from "./types.ts";
+/** Inner markup for a 24x24 viewBox, stroked via the `.icon` CSS class. "ai" renders as a text badge instead — see render.ts. */
+export declare const ICONS: Record<Exclude<FlowIcon, "ai">, string>;

package/dist/flow-diagram/icons.js

@@ -0,0 +1,14 @@
+/** Inner markup for a 24x24 viewBox, stroked via the `.icon` CSS class. "ai" renders as a text badge instead — see render.ts. */
+export const ICONS = {
+    ui: '<rect class="icon" x="3" y="4" width="18" height="15" rx="1.5"/><path class="icon" d="M3 8h18"/>',
+    api: '<path class="icon" d="M8 6l-5 6 5 6"/><path class="icon" d="M16 6l5 6-5 6"/>',
+    handler: '<path class="icon" d="M8 4l-4 8 4 8"/><path class="icon" d="M16 4l4 8-4 8"/><path class="icon" d="M11 20l2-16"/>',
+    "event-store": '<path class="icon" d="M4 6c0-1.5 3.6-2.5 8-2.5S20 4.5 20 6s-3.6 2.5-8 2.5S4 7.5 4 6z"/><path class="icon" d="M4 6v12c0 1.5 3.6 2.5 8 2.5s8-1 8-2.5V6"/><path class="icon" d="M4 12c0 1.5 3.6 2.5 8 2.5s8-1 8-2.5"/>',
+    database: '<path class="icon" d="M4 6c0-1.5 3.6-2.5 8-2.5S20 4.5 20 6s-3.6 2.5-8 2.5S4 7.5 4 6z"/><path class="icon" d="M4 6v12c0 1.5 3.6 2.5 8 2.5s8-1 8-2.5V6"/>',
+    inbox: '<path class="icon" d="M3 6h18v13H3z"/><path class="icon" d="M3 6l9 7 9-7"/>',
+    broadcast: '<path class="icon" d="M12 20v-1"/><path class="icon" d="M8.5 15.5a5 5 0 017 0"/><path class="icon" d="M5 12a9 9 0 0114 0"/>',
+    person: '<circle class="icon" cx="12" cy="8" r="3.2"/><path class="icon" d="M5 20c0-4 3-6 7-6s7 2 7 6"/>',
+    check: '<path class="icon" d="M5 12l5 5L20 6"/>',
+    stop: '<rect class="icon" x="7" y="7" width="10" height="10" rx="1.5"/>',
+    box: '<rect class="icon" x="4" y="4" width="16" height="16" rx="2"/>',
+};

package/dist/flow-diagram/index.d.ts

@@ -0,0 +1,2 @@
+export { renderFlow } from "./render.ts";
+export type { FlowEdge, FlowIcon, FlowNode, FlowNodeKind, FlowSpec } from "./types.ts";

package/dist/flow-diagram/index.js

@@ -0,0 +1 @@
+export { renderFlow } from "./render.js";

package/dist/flow-diagram/render.d.ts

@@ -0,0 +1,3 @@
+import type { FlowSpec } from "./types.ts";
+/** Renders a FlowSpec (a small acyclic node/edge graph) to a self-contained, animated SVG diagram string for embedding in docs pages. */
+export declare function renderFlow(spec: FlowSpec): string;

package/dist/flow-diagram/render.js

@@ -0,0 +1,234 @@
+import { escapeHtml } from "../headless/index.js";
+import { ICONS } from "./icons.js";
+const BADGE = 24;
+const ICON_SIZE = 13;
+const PAD_X = 9.6;
+const GAP_BADGE_TEXT = 8;
+const GAP_RIGHT = 11.2;
+const ROW_GAP = 35;
+const COL_GAP = 22;
+const MIN_CARD_WIDTH = 120;
+const TITLE_SIZE = 11.2;
+const SUB_SIZE = 9.2;
+const STEP_SECONDS = 1.2;
+function textWidth(text, fontSize, bold) {
+    return text.length * fontSize * (bold ? 0.62 : 0.56);
+}
+function cardSize(node) {
+    const titleWidth = textWidth(node.title, TITLE_SIZE, true);
+    const subWidth = node.sub ? textWidth(node.sub, SUB_SIZE, false) : 0;
+    const content = Math.max(titleWidth, subWidth);
+    const width = Math.max(MIN_CARD_WIDTH, BADGE + GAP_BADGE_TEXT + content + PAD_X + GAP_RIGHT);
+    const height = node.sub ? 42 : 32;
+    return { width, height };
+}
+function assertEdgesReferenceKnownNodes(spec) {
+    const ids = new Set(spec.nodes.map((n) => n.id));
+    for (const edge of spec.edges) {
+        if (!ids.has(edge.from))
+            throw new Error(`FlowSpec: edge references unknown node "${edge.from}"`);
+        if (!ids.has(edge.to))
+            throw new Error(`FlowSpec: edge references unknown node "${edge.to}"`);
+    }
+}
+function buildAdjacency(spec) {
+    const children = new Map();
+    const inDegree = new Map();
+    for (const node of spec.nodes)
+        inDegree.set(node.id, 0);
+    for (const edge of spec.edges) {
+        children.set(edge.from, [...(children.get(edge.from) ?? []), edge]);
+        inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+    }
+    return { children, inDegree };
+}
+/** Longest-path depth per node via Kahn's algorithm; throws if the graph has no root or contains a cycle. */
+function longestPathDepths(spec, children, inDegree) {
+    const depth = new Map();
+    const queue = spec.nodes.filter((n) => inDegree.get(n.id) === 0).map((n) => n.id);
+    if (queue.length === 0 && spec.nodes.length > 0) {
+        throw new Error("FlowSpec: no root node found (every node has an incoming edge — check for a cycle)");
+    }
+    for (const id of queue)
+        depth.set(id, 0);
+    const remaining = new Map(inDegree);
+    let visited = 0;
+    for (const id of queue) {
+        visited += 1;
+        for (const edge of children.get(id) ?? []) {
+            const next = Math.max(depth.get(edge.to) ?? 0, (depth.get(id) ?? 0) + 1);
+            depth.set(edge.to, next);
+            const left = (remaining.get(edge.to) ?? 0) - 1;
+            remaining.set(edge.to, left);
+            if (left === 0)
+                queue.push(edge.to);
+        }
+    }
+    if (visited < spec.nodes.length) {
+        throw new Error("FlowSpec: graph has a cycle — a flow diagram must be acyclic");
+    }
+    return depth;
+}
+function computeDepths(spec) {
+    assertEdgesReferenceKnownNodes(spec);
+    const { children, inDegree } = buildAdjacency(spec);
+    return longestPathDepths(spec, children, inDegree);
+}
+function layout(spec) {
+    const depthById = computeDepths(spec);
+    const maxDepth = Math.max(0, ...[...depthById.values()]);
+    const rows = Array.from({ length: maxDepth + 1 }, () => []);
+    for (const node of spec.nodes)
+        rows[depthById.get(node.id) ?? 0]?.push(node);
+    // Siblings in the same row share one card size (the row's largest), so a
+    // row of 3+ always lands symmetrically under its parent — an odd sibling
+    // count with mismatched widths otherwise throws the middle card off-center.
+    const sizedRows = rows.map((row) => {
+        const sizes = row.map((n) => cardSize(n));
+        return {
+            row,
+            width: Math.max(MIN_CARD_WIDTH, ...sizes.map((s) => s.width)),
+            height: Math.max(0, ...sizes.map((s) => s.height)),
+        };
+    });
+    const rowWidths = sizedRows.map(({ row, width }) => row.length * width + COL_GAP * Math.max(0, row.length - 1));
+    const canvasWidth = Math.max(...rowWidths, MIN_CARD_WIDTH) + 40;
+    const centerX = canvasWidth / 2;
+    const placed = new Map();
+    let y = 20;
+    for (const { row, width, height } of sizedRows) {
+        const rowWidth = row.length * width + COL_GAP * Math.max(0, row.length - 1);
+        let x = centerX - rowWidth / 2;
+        for (const node of row) {
+            placed.set(node.id, { node, depth: depthById.get(node.id) ?? 0, x, y, width, height });
+            x += width + COL_GAP;
+        }
+        y += height + ROW_GAP;
+    }
+    const canvasHeight = y - ROW_GAP + 20;
+    return { placed, width: canvasWidth, height: canvasHeight, maxDepth };
+}
+function computeTiming(placed, spec, maxDepth) {
+    const totalSeconds = STEP_SECONDS * (maxDepth + 1) + STEP_SECONDS * 0.5;
+    const timingByEdge = new Map();
+    const arrivalByNode = new Map();
+    for (const edge of spec.edges) {
+        const from = placed.get(edge.from);
+        const to = placed.get(edge.to);
+        if (!from || !to)
+            continue;
+        const span = Math.max(1, to.depth - from.depth);
+        const startT = from.depth * STEP_SECONDS;
+        const travelT = STEP_SECONDS * 0.75 * span;
+        const startFrac = startT / totalSeconds;
+        const endFrac = Math.min(0.98, (startT + travelT) / totalSeconds);
+        timingByEdge.set(edge, { startFrac, endFrac });
+        arrivalByNode.set(edge.to, Math.max(arrivalByNode.get(edge.to) ?? 0, endFrac));
+    }
+    return { totalSeconds, timingByEdge, arrivalByNode };
+}
+const CORNER_RADIUS = 8; // 10 * 0.8
+function edgePath(from, to) {
+    const x1 = from.x + from.width / 2;
+    const y1 = from.y + from.height;
+    const x2 = to.x + to.width / 2;
+    const y2 = to.y;
+    if (Math.abs(x1 - x2) < 1) {
+        return { d: `M ${x1} ${y1} L ${x2} ${y2}`, midX: x1, midY: (y1 + y2) / 2 };
+    }
+    const midY = (y1 + y2) / 2;
+    const dir = x2 > x1 ? 1 : -1;
+    const r = Math.min(CORNER_RADIUS, Math.abs(x2 - x1) / 2, midY - y1, y2 - midY);
+    const d = `M ${x1} ${y1} L ${x1} ${midY - r} ` +
+        `Q ${x1} ${midY} ${x1 + dir * r} ${midY} ` +
+        `L ${x2 - dir * r} ${midY} ` +
+        `Q ${x2} ${midY} ${x2} ${midY + r} ` +
+        `L ${x2} ${y2}`;
+    return { d, midX: (x1 + x2) / 2, midY };
+}
+/** Renders a FlowSpec (a small acyclic node/edge graph) to a self-contained, animated SVG diagram string for embedding in docs pages. */
+export function renderFlow(spec) {
+    const { placed, width, height, maxDepth } = layout(spec);
+    const { totalSeconds, timingByEdge, arrivalByNode } = computeTiming(placed, spec, maxDepth);
+    const wires = [];
+    const dots = [];
+    const labels = [];
+    for (const edge of spec.edges) {
+        const from = placed.get(edge.from);
+        const to = placed.get(edge.to);
+        if (!from || !to)
+            continue;
+        const { d, midX, midY } = edgePath(from, to);
+        // html-ok: d is built in edgePath() from numeric coordinates only, never user input
+        wires.push(`<path class="wire" d="${d}"/>`);
+        if (edge.label) {
+            labels.push(`<text class="edge-label" x="${midX}" y="${midY - 6}" text-anchor="middle">${escapeHtml(edge.label)}</text>`);
+        }
+        const timing = timingByEdge.get(edge);
+        if (!timing)
+            continue;
+        const { startFrac, endFrac } = timing;
+        const fadeIn = Math.min(startFrac + 0.02, endFrac);
+        const fadeOut = Math.min(endFrac + 0.02, 1);
+        dots.push(`<circle r="3.2" class="dot">` +
+            `<animateMotion dur="${totalSeconds}s" repeatCount="indefinite" calcMode="linear" ` +
+            `keyPoints="0;0;1;1" keyTimes="0;${startFrac};${endFrac};1" path="${d}"/>` +
+            `<animate attributeName="opacity" dur="${totalSeconds}s" repeatCount="indefinite" ` +
+            `values="0;0;1;1;0;0" keyTimes="0;${startFrac};${fadeIn};${endFrac};${fadeOut};1"/>` +
+            `</circle>`);
+    }
+    const cards = spec.nodes.map((node) => {
+        const p = placed.get(node.id);
+        if (!p)
+            return "";
+        const arrival = arrivalByNode.get(node.id) ?? 0.02;
+        const pulseEnd = Math.min(arrival + 0.05, 1);
+        const badgeX = p.x + PAD_X;
+        const badgeY = p.y + (p.height - BADGE) / 2;
+        const textX = badgeX + BADGE + GAP_BADGE_TEXT;
+        const isTerminal = node.kind === "terminal";
+        const badgeFill = isTerminal
+            ? "var(--flow-card)"
+            : node.icon === "check"
+                ? "var(--flow-green)"
+                : "var(--flow-badge)";
+        const badgeClass = isTerminal ? "flow-badge flow-badge-terminal" : "flow-badge";
+        const iconGroupClass = isTerminal ? "flow-icon-terminal" : "";
+        const iconInset = (BADGE - ICON_SIZE) / 2;
+        const iconInner = node.icon === "ai"
+            ? `<text class="flow-ai-label" x="${BADGE / 2}" y="${BADGE / 2 + 3}" text-anchor="middle">AI</text>`
+            : // html-ok: ICONS is a static internal map keyed by the FlowIcon union, not user input
+                `<svg class="${iconGroupClass}" x="${iconInset}" y="${iconInset}" width="${ICON_SIZE}" height="${ICON_SIZE}" viewBox="0 0 24 24">${ICONS[node.icon ?? "box"]}</svg>`;
+        return `<g>
+      <rect class="flow-card" x="${p.x}" y="${p.y}" width="${p.width}" height="${p.height}" rx="9">
+        <animate attributeName="stroke" dur="${totalSeconds}s" repeatCount="indefinite"
+          values="var(--flow-card-border);var(--flow-card-border);var(--flow-violet);var(--flow-card-border);var(--flow-card-border)"
+          keyTimes="0;${Math.max(0, arrival - 0.02)};${arrival};${pulseEnd};1"/>
+      </rect>
+      <g transform="translate(${badgeX}, ${badgeY})">
+        <rect class="${badgeClass}" width="${BADGE}" height="${BADGE}" rx="6" fill="${badgeFill}"/>
+        ${iconInner}
+      </g>
+      <text class="flow-title" x="${textX}" y="${node.sub ? p.y + p.height / 2 - 2 : p.y + p.height / 2 + 3.5}">${escapeHtml(node.title)}</text>
+      ${node.sub ? `<text class="flow-sub" x="${textX}" y="${p.y + p.height / 2 + 11}">${escapeHtml(node.sub)}</text>` : ""}
+    </g>`;
+    });
+    // html-ok: wires/dots/labels/cards hold only fragments built from numeric
+    // coordinates or already-escaped text (escapeHtml above), never raw user input
+    return `<div class="kumiko-flow">
+  <svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Flow diagram">
+    ${
+    // html-ok: see comment above return
+    wires.join("\n    ")}
+    ${
+    // html-ok: see comment above return
+    dots.join("\n    ")}
+    ${
+    // html-ok: see comment above return
+    labels.join("\n    ")}
+    ${
+    // html-ok: see comment above return
+    cards.join("\n    ")}
+  </svg>
+</div>`;
+}

package/dist/flow-diagram/types.d.ts

@@ -0,0 +1,18 @@
+export type FlowIcon = "ui" | "api" | "handler" | "event-store" | "database" | "broadcast" | "ai" | "inbox" | "person" | "check" | "stop" | "box";
+export type FlowNodeKind = "process" | "decision" | "terminal";
+export interface FlowNode {
+    id: string;
+    title: string;
+    sub?: string;
+    icon?: FlowIcon;
+    kind?: FlowNodeKind;
+}
+export interface FlowEdge {
+    from: string;
+    to: string;
+    label?: string;
+}
+export interface FlowSpec {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}

package/dist/flow-diagram/types.js

@@ -0,0 +1 @@
+export {};

package/dist/format-when.js

@@ -1,4 +1,4 @@
-import { toInstant } from "@cosmicdrift/kumiko-headless";
+import { toInstant } from "./headless/index.js";
 // Shared timestamp formatter for operator screens (audit log, job runs) —
 // falls back to the raw ISO string on an unparseable value instead of "Invalid Date".
 export function formatWhen(value) {

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

@@ -0,0 +1,3 @@
+export declare const APEX_NAV_MENU_CSS = "\n  .nav-toggle { display: none; }\n  .nav-toggle__trigger { display: none; align-items: center; justify-content: center;\n    width: 2.25rem; height: 2.25rem; border-radius: 0.5rem; cursor: pointer;\n    color: var(--fg-muted); list-style: none; }\n  .nav-toggle__trigger::-webkit-details-marker { display: none; }\n  .nav-toggle__trigger:hover { color: var(--fg); background: var(--bg-muted); }\n  .nav-toggle__trigger svg { width: 1.35rem; height: 1.35rem; }\n  .apex-dark .nav-toggle__trigger { color: var(--on-dark-muted); }\n  .apex-dark .nav-toggle__trigger:hover { color: var(--on-dark); background: rgba(255,255,255,0.08); }\n\n  .nav-menu { position: relative; display: inline-flex; }\n  .nav-menu__trigger { display: inline-flex; align-items: center; gap: 0.3rem;\n    font: inherit; font-size: 0.9375rem; color: var(--fg-muted);\n    cursor: pointer; list-style: none; }\n  .nav-menu__trigger::-webkit-details-marker { display: none; }\n  .nav-menu__trigger:hover { color: var(--fg); }\n  .nav-menu__chev { display: inline-flex; transition: transform 0.15s; opacity: 0.7; }\n  .nav-menu__chev svg { width: 0.95em; height: 0.95em; }\n  .nav-menu[open] .nav-menu__chev { transform: rotate(180deg); }\n  .nav-menu__panel { position: absolute; top: calc(100% + 0.5rem); left: 0; z-index: 20;\n    min-width: 21rem; padding: 0.5rem; background: var(--bg-card); color: var(--fg);\n    border: 1px solid var(--border); border-radius: 0.75rem; box-shadow: var(--shadow);\n    flex-direction: column; gap: 0.125rem; }\n  .nav-menu[open] .nav-menu__panel { display: flex; }\n  .nav-menu__item { display: flex; gap: 0.75rem; align-items: flex-start;\n    padding: 0.6rem 0.7rem; border-radius: 0.5rem; color: var(--fg); }\n  .nav-menu__item:hover { background: var(--bg-muted); color: var(--fg); }\n  .nav-menu__icon { flex: none; display: inline-flex; align-items: center; justify-content: center;\n    width: 2rem; height: 2rem; border-radius: 0.5rem;\n    background: color-mix(in srgb, var(--primary) 12%, transparent); color: var(--primary); }\n  .nav-menu__icon svg { width: 1.1rem; height: 1.1rem; }\n  .nav-menu__text { display: flex; flex-direction: column; gap: 0.1rem; }\n  .nav-menu__title { font-weight: 600; font-size: 0.9rem; line-height: 1.2; }\n  .nav-menu__desc { font-size: 0.8rem; color: var(--fg-muted); line-height: 1.35; }\n  .nav-menu__sep { height: 1px; background: var(--border); margin: 0.375rem 0.3rem; }\n  .nav-menu__more { display: inline-flex; padding: 0.4rem 0.7rem; font-size: 0.85rem; font-weight: 600; color: var(--primary); }\n  .nav-menu__more:hover { color: var(--primary-hover); }\n  .apex-dark .nav-menu__trigger { color: var(--on-dark-muted); }\n  .apex-dark .nav-menu__trigger:hover { color: var(--on-dark); }\n  /* The panel is a light popover; its links must NOT inherit the dark-chrome\n     nav-link color (.apex-dark .nav-links a, specificity 0,2,1) or a consumer's\n     own .nav-links a. Pin both link types with matching specificity (0,2,1) so\n     titles + the footer link stay readable in the dark theme. */\n  .nav-menu__panel a.nav-menu__item { color: var(--fg); }\n  .nav-menu__panel a.nav-menu__item:hover { color: var(--fg); }\n  .nav-menu__panel a.nav-menu__more { color: var(--primary); }\n  .nav-menu__panel a.nav-menu__more:hover { color: var(--primary-hover); }\n";
+export declare const APEX_NAV_TOGGLE_RESPONSIVE_CSS = "\n  @media (max-width: 640px) {\n    .nav { position: relative; }\n    .nav .nav-toggle { display: inline-flex; }\n    .nav .nav-toggle__trigger { display: inline-flex; }\n    .nav-toggle[open] > .nav-links { display: flex; flex-direction: column; align-items: stretch;\n      gap: 0.25rem; position: absolute; top: calc(100% + 0.5rem); left: 0; right: 0; z-index: 30;\n      background: var(--bg-card); border: 1px solid var(--border); border-radius: 0.75rem;\n      box-shadow: var(--shadow); padding: 0.75rem; }\n    .nav-toggle[open] > .nav-links > a { color: var(--fg); padding: 0.4rem 0.25rem; }\n    .nav-toggle[open] > .nav-links > a:hover { color: var(--fg); }\n    .nav-toggle .nav-menu { display: block; }\n    .nav-toggle .nav-menu__panel { position: static; min-width: 0;\n      margin-top: 0.375rem; box-shadow: none; }\n  }\n";
+export declare const APEX_STRUCTURAL_CSS: string;