@object-ui/app-shell 7.0.0 → 7.1.0

package/dist/views/metadata-admin/inspectors/flow-node-config.js

@@ -40,10 +40,12 @@ const FLOW_NODE_CONFIG = {
             ref: { kind: 'object' },
             placeholder: 'crm_lead',
             help: 'Target object for record / scheduled-scan triggers.',
+            showWhen: { field: 'triggerType', equals: ['record-after-create', 'record-after-update', 'record-before-update', 'record-after-delete', 'record-change', 'schedule', 'webhook', 'event'] },
         }),
         cfg('condition', 'Entry condition', 'expression', {
             placeholder: 'status == "qualifying" && previous.status != "qualifying"',
             help: 'CEL predicate — the flow runs only when this is true. Leave empty to run on every event.',
+            showWhen: { field: 'triggerType', equals: ['record-after-create', 'record-after-update', 'record-before-update', 'record-after-delete', 'record-change', 'schedule', 'webhook', 'event'] },
         }),
         cfg('cron', 'Cron schedule', 'text', {
             placeholder: '0 7 * * *',
@@ -169,9 +171,19 @@ const FLOW_NODE_CONFIG = {
         }),
         { id: 'timeoutMs', path: ['timeoutMs'], label: 'Timeout (ms)', kind: 'number', placeholder: '30000' },
     ],
+    // Screen — collect input (a flat `fields` list) OR render an object's full
+    // create/edit form (`objectName`, master-detail). `title`/`description`
+    // head the screen (description interpolates {var}); `waitForInput` forces a
+    // pause on a field-less message/confirmation screen. All optional and shown
+    // together so neither a message screen nor an object-form step needs JSON.
     screen: [
+        cfg('title', 'Title', 'text', { placeholder: 'Request a discount', help: 'Heading shown above the screen.' }),
+        cfg('description', 'Description', 'textarea', {
+            placeholder: 'Enter the deal amount and the discount you want.',
+            help: 'Body text. Interpolates {var} references (e.g. {approval_path}).',
+        }),
         cfg('fields', 'Fields', 'objectList', {
-            help: 'Fields presented on this screen.',
+            help: 'Input fields collected on this screen. Leave empty for a message-only screen.',
             columns: [
                 { key: 'name', label: 'Name', kind: 'text', placeholder: 'discount' },
                 { key: 'label', label: 'Label', kind: 'text', placeholder: 'Discount %' },
@@ -180,6 +192,29 @@ const FLOW_NODE_CONFIG = {
                 { key: 'visibleWhen', label: 'Visible when', kind: 'expression', placeholder: 'stage == "review"' },
             ],
         }),
+        cfg('waitForInput', 'Wait for input', 'boolean', {
+            help: 'Pause to show this screen even with no fields (a message / confirmation). A field-less screen with this off is a server pass-through.',
+        }),
+        cfg('objectName', 'Object form', 'reference', {
+            ref: { kind: 'object' },
+            placeholder: 'crm_account',
+            help: 'Render this object\u2019s full create/edit form (incl. master-detail) instead of a flat field list.',
+        }),
+        cfg('idVariable', 'Saved-record variable', 'text', {
+            placeholder: 'account_id',
+            help: 'Object form only: variable bound to the saved record\u2019s id, for later steps.',
+        }),
+        cfg('mode', 'Form mode', 'select', {
+            options: [
+                { value: 'create', label: 'Create' },
+                { value: 'edit', label: 'Edit' },
+            ],
+            defaultValue: 'create',
+            help: 'Object form only.',
+        }),
+        cfg('defaults', 'Form defaults', 'keyValue', {
+            help: 'Object form only: prefilled values (e.g. account \u2192 {account_id}).',
+        }),
     ],
     // Approval node (ADR-0019). The node opens an approval request on entry,
     // suspends the run, and resumes down its `approve` / `reject` out-edge once a
@@ -260,6 +295,15 @@ const FLOW_NODE_CONFIG = {
         },
         { id: 'escalation.escalateTo', path: ['config', 'escalation', 'escalateTo'], label: 'Escalate to', kind: 'reference', ref: { kind: 'role' }, placeholder: 'user id / role / manager level', showWhen: { field: 'escalation.enabled', equals: ['true'] } },
         { id: 'escalation.notifySubmitter', path: ['config', 'escalation', 'notifySubmitter'], label: 'Notify submitter', kind: 'boolean', showWhen: { field: 'escalation.enabled', equals: ['true'] } },
+        // ADR-0044 send-back-for-revision guard. Surfaces from the engine's
+        // published configSchema when online; this hardcoded copy keeps it visible
+        // offline / on an older backend. Only meaningful once the node has a
+        // `revise` out-edge (author one via the canvas "add revision loop").
+        cfg('maxRevisions', 'Max revisions', 'number', {
+            placeholder: '3',
+            defaultValue: '3',
+            help: 'Max send-backs for revision before the request auto-rejects (0 disables send-back). Needs a "revise" out-edge to take effect.',
+        }),
     ],
     wait: [
         at('waitEventConfig', 'eventType', 'Wait for', 'select', {
@@ -368,6 +412,7 @@ const FLOW_NODE_CONFIG = {
  */
 const TYPE_ALIASES = {
     action: 'legacy_action',
+    http: 'http_request',
     branch: 'decision',
     gateway: 'decision',
     condition: 'decision',

package/dist/views/metadata-admin/issuePath.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Render a (possibly nested) validation issue path into a human-readable trail
+ * that names the offending element. A Zod issue on a dashboard widget arrives as
+ * a dot-joined path like `widgets.2.layout`; shown as just its head field
+ * ("Widgets") the author can't tell WHICH widget or sub-field is at fault. This
+ * turns it into "Widgets → priority_split → layout" by resolving each array
+ * index to the item's stable identity (id/name/title) from the draft value.
+ *
+ * @param headLabel resolved human label for the first segment (caller knows the
+ *                  form/schema labels).
+ * @param path      dot-joined issue path (e.g. `widgets.2.layout`).
+ * @param rootValue the draft object the path indexes into (used to resolve an
+ *                  array index to the item's identity).
+ */
+export declare function describeIssuePath(headLabel: string, path: string, rootValue: unknown): string;

package/dist/views/metadata-admin/issuePath.js

@@ -0,0 +1,65 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Render a (possibly nested) validation issue path into a human-readable trail
+ * that names the offending element. A Zod issue on a dashboard widget arrives as
+ * a dot-joined path like `widgets.2.layout`; shown as just its head field
+ * ("Widgets") the author can't tell WHICH widget or sub-field is at fault. This
+ * turns it into "Widgets → priority_split → layout" by resolving each array
+ * index to the item's stable identity (id/name/title) from the draft value.
+ *
+ * @param headLabel resolved human label for the first segment (caller knows the
+ *                  form/schema labels).
+ * @param path      dot-joined issue path (e.g. `widgets.2.layout`).
+ * @param rootValue the draft object the path indexes into (used to resolve an
+ *                  array index to the item's identity).
+ */
+export function describeIssuePath(headLabel, path, rootValue) {
+    const segments = path.split('.');
+    if (segments.length <= 1)
+        return headLabel;
+    const parts = [headLabel];
+    let cursor = asRecord(rootValue)?.[segments[0]];
+    for (let i = 1; i < segments.length; i++) {
+        const seg = segments[i];
+        if (/^\d+$/.test(seg)) {
+            const idx = Number(seg);
+            const item = Array.isArray(cursor) ? cursor[idx] : undefined;
+            // 1-based index reads naturally for non-developers ("#1" not "#0").
+            parts.push(itemIdentity(item) ?? `#${idx + 1}`);
+            cursor = item;
+        }
+        else {
+            parts.push(seg);
+            cursor = asRecord(cursor)?.[seg];
+        }
+    }
+    return parts.join(' → ');
+}
+/** Best-effort stable identity of an array item, resolving an I18nLabel object
+ *  ({ key, defaultValue }) to its string. Returns undefined when none usable. */
+function itemIdentity(item) {
+    const o = asRecord(item);
+    if (!o)
+        return undefined;
+    for (const k of ['id', 'name', 'key', 'title', 'label']) {
+        const v = o[k];
+        if (typeof v === 'string' && v.trim())
+            return v;
+        const nested = asRecord(v);
+        if (nested) {
+            const s = nested.defaultValue ?? nested.key;
+            if (typeof s === 'string' && s.trim())
+                return s;
+        }
+    }
+    return undefined;
+}
+function asRecord(v) {
+    return v && typeof v === 'object' ? v : undefined;
+}

package/dist/views/metadata-admin/package-scope.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sentinel "package" id for this environment's runtime, DB-authored metadata —
+ * items with no code-package binding (`package_id IS NULL`). The metadata
+ * list/get API treats `?package=sys_metadata` as exactly that local scope on
+ * READ, and a WRITE under it persists `package_id = null` (matching the
+ * server's runtime-only provenance, see framework #2252).
+ *
+ * Why this exists: a self-hosted, metadata-customizable environment is
+ * single-tenant — there is no "org" dimension here; the real axis is
+ * code-package vs. runtime (DB-authored). Before this scope, the package
+ * selector only listed code packages, so metadata authored at runtime
+ * (`package_id = null`) was filtered out of every code-package view and became
+ * un-navigable (the route redirected to "new"). Surfacing the local scope as a
+ * first-class, always-present selector entry makes it discoverable and editable.
+ */
+export declare const LOCAL_PACKAGE_ID = "sys_metadata";
+/**
+ * Build the Studio package-scope options from the raw `package` metadata list.
+ * Filters out system/cloud-scoped packages and appends a stable
+ * "Local / Custom (this environment)" scope so runtime metadata authored here
+ * is always selectable/visible — even when zero items exist yet.
+ */
+export declare function buildPackageScopeOptions(rawList: unknown[] | null | undefined): {
+    id: string;
+    name: string;
+}[];

package/dist/views/metadata-admin/package-scope.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { detectLocale, t } from './i18n';
+/**
+ * Sentinel "package" id for this environment's runtime, DB-authored metadata —
+ * items with no code-package binding (`package_id IS NULL`). The metadata
+ * list/get API treats `?package=sys_metadata` as exactly that local scope on
+ * READ, and a WRITE under it persists `package_id = null` (matching the
+ * server's runtime-only provenance, see framework #2252).
+ *
+ * Why this exists: a self-hosted, metadata-customizable environment is
+ * single-tenant — there is no "org" dimension here; the real axis is
+ * code-package vs. runtime (DB-authored). Before this scope, the package
+ * selector only listed code packages, so metadata authored at runtime
+ * (`package_id = null`) was filtered out of every code-package view and became
+ * un-navigable (the route redirected to "new"). Surfacing the local scope as a
+ * first-class, always-present selector entry makes it discoverable and editable.
+ */
+export const LOCAL_PACKAGE_ID = 'sys_metadata';
+const SYSTEM_SCOPES = new Set(['system', 'cloud']);
+/**
+ * Build the Studio package-scope options from the raw `package` metadata list.
+ * Filters out system/cloud-scoped packages and appends a stable
+ * "Local / Custom (this environment)" scope so runtime metadata authored here
+ * is always selectable/visible — even when zero items exist yet.
+ */
+export function buildPackageScopeOptions(rawList) {
+    const rows = (rawList ?? [])
+        .map((raw) => {
+        const item = raw && typeof raw === 'object' && 'item' in raw ? raw.item : raw;
+        const m = (item?.manifest ?? item ?? {});
+        return {
+            id: m.id,
+            scope: m.scope,
+            name: m.name || m.id,
+        };
+    })
+        .filter((p) => p.id && !SYSTEM_SCOPES.has(p.scope));
+    rows.sort((a, b) => a.name.localeCompare(b.name));
+    const opts = rows.map((p) => ({ id: p.id, name: p.name }));
+    // Append (never default) so the existing first-code-package default is
+    // preserved; the user opts into the local scope explicitly.
+    return [...opts, { id: LOCAL_PACKAGE_ID, name: t('engine.package.local', detectLocale()) }];
+}

package/dist/views/metadata-admin/previews/DatasetPreview.js

@@ -77,13 +77,29 @@ export function DatasetPreview({ draft }) {
     const resultObject = state.status === 'ok' ? state.object : undefined;
     const { measureField, headerLabel } = buildDatasetFieldHelpers(resultFields, resultObject, fieldLabel);
     const columns = [...dimensionNames, ...measureNames];
+    // A ratio/percent measure (format like `0.0%`) on the same axis as a
+    // magnitude measure (currency in the hundred-thousands) renders as an
+    // invisible sliver. When the selection MIXES the two scales, plot the ratio
+    // measures as a line on a secondary (right) Y axis via the `combo` chart —
+    // bars (magnitude) keep the left axis. Same-scale selections stay a plain bar.
+    const isRatioMeasure = (m) => {
+        const f = measureField(m)?.format;
+        return typeof f === 'string' && f.includes('%');
+    };
+    const ratioMeasures = measureNames.filter(isRatioMeasure);
+    const mixedScale = ratioMeasures.length > 0 && ratioMeasures.length < measureNames.length;
     return (_jsx(PreviewShell, { hint: `dataset · ${objectName}${dimensionNames.length ? ' · by ' + dimensionNames.join(', ') : ''}`, children: _jsxs("div", { className: "p-3 space-y-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("button", { type: "button", onClick: () => void run(), disabled: state.status === 'loading', className: "inline-flex items-center gap-1.5 rounded-md border bg-background px-3 py-1.5 text-xs font-medium hover:bg-accent disabled:opacity-50", children: [state.status === 'loading'
                                     ? _jsx(Loader2, { className: "h-3.5 w-3.5 animate-spin" })
-                                    : _jsx(BarChart3, { className: "h-3.5 w-3.5" }), "Run preview"] }), _jsxs("span", { className: "text-[11px] text-muted-foreground", children: [measureNames.length, " measure", measureNames.length === 1 ? '' : 's', " \u00B7 ", dimensionNames.length, " dimension", dimensionNames.length === 1 ? '' : 's'] })] }), state.status === 'error' && (_jsxs("div", { role: "alert", className: "flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-xs text-destructive", children: [_jsx(AlertTriangle, { className: "h-3.5 w-3.5 mt-0.5 shrink-0" }), _jsx("span", { className: "break-words", children: state.error })] })), state.status === 'ok' && state.rows.length === 0 && (_jsx(PreviewEmptyState, { icon: _jsx(BarChart3, { className: "h-8 w-8" }), title: "No rows", description: "The dataset returned no rows for the current scope." })), state.rows.length > 0 && dimensionNames.length >= 1 && (_jsx(PreviewErrorBoundary, { fallbackHint: "Couldn't render the chart for this result \u2014 the table below still shows the data.", children: _jsx(React.Suspense, { fallback: _jsx("div", { className: "h-[260px] flex items-center justify-center text-xs text-muted-foreground", children: _jsx(Loader2, { className: "h-4 w-4 animate-spin" }) }), children: _jsx("div", { className: "rounded-md border p-2", children: _jsx(ChartRenderer, { schema: {
-                                    data: state.rows,
-                                    xAxisKey: dimensionNames[0],
-                                    series: measureNames.map((m) => ({ dataKey: m, label: headerLabel(m), chartType: 'bar' })),
-                                } }) }) }) })), state.rows.length > 0 && (_jsx("div", { className: "overflow-auto max-h-[60vh] rounded-md border", children: _jsxs("table", { className: "w-full text-xs", children: [_jsx("thead", { className: "bg-muted/40", children: _jsx("tr", { children: columns.map((c) => (_jsx("th", { className: "px-2 py-1.5 text-left font-medium whitespace-nowrap", children: headerLabel(c) }, c))) }) }), _jsx("tbody", { children: state.rows.map((row, i) => (_jsx("tr", { className: "border-t", children: columns.map((c) => (_jsx("td", { className: "px-2 py-1 tabular-nums whitespace-nowrap", children: measureNames.includes(c)
+                                    : _jsx(BarChart3, { className: "h-3.5 w-3.5" }), "Run preview"] }), _jsxs("span", { className: "text-[11px] text-muted-foreground", children: [measureNames.length, " measure", measureNames.length === 1 ? '' : 's', " \u00B7 ", dimensionNames.length, " dimension", dimensionNames.length === 1 ? '' : 's'] })] }), state.status === 'error' && (_jsxs("div", { role: "alert", className: "flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-xs text-destructive", children: [_jsx(AlertTriangle, { className: "h-3.5 w-3.5 mt-0.5 shrink-0" }), _jsx("span", { className: "break-words", children: state.error })] })), state.status === 'ok' && state.rows.length === 0 && (_jsx(PreviewEmptyState, { icon: _jsx(BarChart3, { className: "h-8 w-8" }), title: "No rows", description: "The dataset returned no rows for the current scope." })), state.rows.length > 0 && dimensionNames.length >= 1 && (_jsx(PreviewErrorBoundary, { fallbackHint: "Couldn't render the chart for this result \u2014 the table below still shows the data.", children: _jsx(React.Suspense, { fallback: _jsx("div", { className: "h-[260px] flex items-center justify-center text-xs text-muted-foreground", children: _jsx(Loader2, { className: "h-4 w-4 animate-spin" }) }), children: _jsxs("div", { className: "rounded-md border p-2", children: [_jsx(ChartRenderer, { schema: {
+                                        data: state.rows,
+                                        xAxisKey: dimensionNames[0],
+                                        chartType: mixedScale ? 'combo' : 'bar',
+                                        series: measureNames.map((m) => ({
+                                            dataKey: m,
+                                            label: headerLabel(m),
+                                            chartType: mixedScale ? (isRatioMeasure(m) ? 'line' : 'bar') : 'bar',
+                                        })),
+                                    } }), mixedScale && (_jsxs("p", { className: "mt-1 px-1 text-[10px] text-muted-foreground", children: ["Ratio measures (", ratioMeasures.map(headerLabel).join(', '), ") use the right axis."] }))] }) }) })), state.rows.length > 0 && (_jsx("div", { className: "overflow-auto max-h-[60vh] rounded-md border", children: _jsxs("table", { className: "w-full text-xs", children: [_jsx("thead", { className: "bg-muted/40", children: _jsx("tr", { children: columns.map((c) => (_jsx("th", { className: "px-2 py-1.5 text-left font-medium whitespace-nowrap", children: headerLabel(c) }, c))) }) }), _jsx("tbody", { children: state.rows.map((row, i) => (_jsx("tr", { className: "border-t", children: columns.map((c) => (_jsx("td", { className: "px-2 py-1 tabular-nums whitespace-nowrap", children: measureNames.includes(c)
                                             ? formatMeasure(row[c], measureField(c)?.format, measureField(c)?.currency)
                                             : formatDimensionValue(row[c]) }, c))) }, i))) })] }) }))] }) }));
 }

package/dist/views/metadata-admin/previews/FlowCanvas.d.ts

@@ -35,9 +35,15 @@ export interface FlowCanvasProps {
     visitedNodeIds?: string[];
     /** Simulation overlay: ids of edges that were traversed. */
     traversedEdgeIds?: string[];
+    /** Structural-validation: node ids to paint with a red error ring. */
+    invalidNodeIds?: string[];
+    /** Structural-validation: edges (keyed `${source}->${target}`) to paint red. */
+    invalidEdges?: ReadonlySet<string>;
+    /** Structural-validation error messages shown in an inline canvas banner. */
+    validationErrors?: string[];
     onSelect: (node: FlowNode | null) => void;
     /** Select an edge (its `edgeKey`), or clear selection with `null`. */
     onSelectEdge?: (edge: FlowEdge | null, key: string) => void;
     onPatch?: (partial: Record<string, unknown>) => void;
 }
-export declare function FlowCanvas({ nodes, edges, editable, designMode, selectedId, selectedEdgeId, locale, activeNodeId, visitedNodeIds, traversedEdgeIds, onSelect, onSelectEdge, onPatch, }: FlowCanvasProps): React.JSX.Element;
+export declare function FlowCanvas({ nodes, edges, editable, designMode, selectedId, selectedEdgeId, locale, activeNodeId, visitedNodeIds, traversedEdgeIds, invalidNodeIds, invalidEdges, validationErrors, onSelect, onSelectEdge, onPatch, }: FlowCanvasProps): React.JSX.Element;

package/dist/views/metadata-admin/previews/FlowCanvas.js

@@ -21,17 +21,17 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * `onPatch(partial)` and the host merges + persists.
  */
 import * as React from 'react';
-import { Maximize2, Plus, ZoomIn, ZoomOut } from 'lucide-react';
+import { AlertTriangle, Maximize2, Plus, ZoomIn, ZoomOut } from 'lucide-react';
 import { cn } from '@object-ui/components';
 import { uniqueId, appendArray, spliceArray } from '../inspectors/_shared';
 import { t as tr } from '../i18n';
-import { computeLayout, diagramSize, bottomAnchor, topAnchor, edgePath, edgeMidpoint, edgeKey, conditionText, } from './flow-canvas-layout';
+import { computeLayout, diagramSize, bottomAnchor, topAnchor, rightAnchor, edgePath, edgeMidpoint, backEdgePath, backEdgeLabelAnchor, isBackEdge, edgeKey, conditionText, } from './flow-canvas-layout';
 import { NodeCard, NodePalette, defaultNodeLabel, defaultNodeExtras } from './flow-canvas-parts';
 import { useFlowNodePalette } from './useFlowNodePalette';
 const MIN_ZOOM = 0.4;
 const MAX_ZOOM = 1.6;
 const DRAG_THRESHOLD = 4;
-export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, selectedEdgeId, locale, activeNodeId, visitedNodeIds, traversedEdgeIds, onSelect, onSelectEdge, onPatch, }) {
+export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, selectedEdgeId, locale, activeNodeId, visitedNodeIds, traversedEdgeIds, invalidNodeIds, invalidEdges, validationErrors, onSelect, onSelectEdge, onPatch, }) {
     const viewportRef = React.useRef(null);
     const [zoom, setZoom] = React.useState(1);
     const [pan, setPan] = React.useState({ x: 0, y: 0 });
@@ -51,6 +51,7 @@ export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, sel
     // Simulation overlay sets (display-only; never drives engine behavior).
     const visitedSet = React.useMemo(() => new Set(visitedNodeIds ?? []), [visitedNodeIds]);
     const traversedSet = React.useMemo(() => new Set(traversedEdgeIds ?? []), [traversedEdgeIds]);
+    const invalidNodeSet = React.useMemo(() => new Set(invalidNodeIds ?? []), [invalidNodeIds]);
     const simRunning = (visitedNodeIds?.length ?? 0) > 0 || !!activeNodeId;
     const positionOf = React.useCallback((id) => {
         if (dragPos && dragPos.id === id)
@@ -88,6 +89,28 @@ export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, sel
                 source: opts.from,
                 target: id,
             };
+            // When the source is a decision, carry its matching branch (by order:
+            // the k-th out-edge takes the k-th branch) onto the new edge so it
+            // actually routes. The decision's config.conditions are otherwise
+            // disconnected from the edges, leaving every branch unconditional.
+            const fromNode = nodes.find((n) => n.id === opts.from);
+            if (fromNode?.type === 'decision') {
+                const branches = Array.isArray(fromNode.config?.conditions)
+                    ? fromNode.config.conditions
+                    : [];
+                const outCount = edges.filter((e) => e.source === opts.from).length;
+                const branch = branches[outCount];
+                if (branch && typeof branch === 'object') {
+                    const expr = typeof branch.expression === 'string' ? branch.expression.trim() : '';
+                    const label = typeof branch.label === 'string' ? branch.label.trim() : '';
+                    if (label)
+                        newEdge.label = label;
+                    if (expr === 'true')
+                        newEdge.isDefault = true;
+                    else if (expr)
+                        newEdge.condition = expr;
+                }
+            }
             patch.edges = appendArray(edges, newEdge);
         }
         onPatch(patch);
@@ -124,6 +147,49 @@ export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, sel
         onPatch({ nodes: appendArray(nodes, newNode), edges: appendArray(nextEdges, secondSegment) });
         onSelect(newNode);
     }, [edges, nodes, onPatch, onSelect, positionOf]);
+    /**
+     * ADR-0044 one-click "add revision loop": drop a signal `wait` node plus the
+     * two edges that form a send-back-for-revision loop on an approval node —
+     * a `revise` out-edge to the wait point, and a declared `back`-edge closing
+     * the loop (resubmit re-enters the approval node as round N+1). Reproduces the
+     * canonical `showcase_budget_approval` shape in a single gesture. The wait
+     * node is left unpinned so the layered auto-layout slots it among the
+     * approval node's other branches.
+     */
+    const addReviseLoop = React.useCallback((approvalId) => {
+        if (!onPatch)
+            return;
+        if (!nodes.some((n) => n.id === approvalId))
+            return;
+        const waitId = uniqueId('node', nodes.map((n) => n.id).filter(Boolean));
+        const waitNode = {
+            id: waitId,
+            type: 'wait',
+            label: 'Awaiting Revision',
+            // Signal-flavored wait: the submitter's resubmit signal resumes the run.
+            waitEventConfig: { eventType: 'signal', signalName: 'revision', onTimeout: 'fail' },
+        };
+        const existingEdgeIds = edges.map((e) => e.id).filter(Boolean);
+        const reviseId = uniqueId('edge', existingEdgeIds);
+        const backId = uniqueId('edge', [...existingEdgeIds, reviseId]);
+        const reviseEdge = { id: reviseId, source: approvalId, target: waitId, label: 'revise' };
+        const backEdge = { id: backId, source: waitId, target: approvalId, label: 'resubmit', type: 'back' };
+        onPatch({
+            nodes: appendArray(nodes, waitNode),
+            edges: appendArray(appendArray(edges, reviseEdge), backEdge),
+        });
+        onSelect(waitNode);
+    }, [edges, nodes, onPatch, onSelect]);
+    // Approval nodes that already declare a `revise` out-edge — used to hide the
+    // "add revision loop" affordance once a loop exists (avoid duplicates).
+    const reviseLoopSources = React.useMemo(() => {
+        const s = new Set();
+        for (const e of edges) {
+            if (typeof e.label === 'string' && e.label.trim().toLowerCase() === 'revise')
+                s.add(e.source);
+        }
+        return s;
+    }, [edges]);
     const deleteNode = React.useCallback((id) => {
         if (!onPatch)
             return;
@@ -220,7 +286,7 @@ export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, sel
         }
     }, [deleteNode, editable, selectedId]);
     // ── Render ─────────────────────────────────────────────────────────────────
-    return (_jsxs("div", { className: "relative h-full min-h-[320px] w-full overflow-hidden", children: [_jsxs("div", { className: "absolute right-2 top-2 z-30 flex items-center gap-1.5", children: [editable && (_jsxs("div", { className: "relative", children: [_jsxs("button", { type: "button", onClick: () => setPaletteOpen((v) => !v), className: "inline-flex items-center gap-1.5 rounded-lg border bg-background/90 px-2.5 py-1.5 text-xs font-medium shadow-sm backdrop-blur-sm transition-colors hover:border-primary/50 hover:bg-accent hover:text-foreground", children: [_jsx(Plus, { className: "h-3.5 w-3.5" }), tr('engine.inspector.add.node', locale)] }), paletteOpen && (_jsx(NodePalette, { locale: locale, items: paletteItems, onClose: () => setPaletteOpen(false), onPick: (type) => addNode(type, { from: selectedId ?? undefined }) }))] })), _jsxs("div", { className: "flex items-center rounded-lg border bg-background/90 shadow-sm backdrop-blur-sm", children: [_jsx("button", { type: "button", title: "Zoom out", "aria-label": "Zoom out", onClick: () => setZoom((z) => clampZoom(z - 0.15)), className: "inline-flex h-7 w-7 items-center justify-center text-muted-foreground hover:text-foreground", children: _jsx(ZoomOut, { className: "h-3.5 w-3.5" }) }), _jsxs("span", { className: "w-10 text-center text-[11px] tabular-nums text-muted-foreground", children: [Math.round(zoom * 100), "%"] }), _jsx("button", { type: "button", title: "Zoom in", "aria-label": "Zoom in", onClick: () => setZoom((z) => clampZoom(z + 0.15)), className: "inline-flex h-7 w-7 items-center justify-center text-muted-foreground hover:text-foreground", children: _jsx(ZoomIn, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", title: "Fit to view", "aria-label": "Fit to view", onClick: fitToView, className: "inline-flex h-7 w-7 items-center justify-center border-l text-muted-foreground hover:text-foreground", children: _jsx(Maximize2, { className: "h-3.5 w-3.5" }) })] })] }), _jsx("div", { ref: viewportRef, tabIndex: 0, role: "application", "aria-label": "Flow canvas", onKeyDown: onKeyDown, onPointerDown: onBgPointerDown, onPointerMove: (e) => {
+    return (_jsxs("div", { className: "relative h-full min-h-[320px] w-full overflow-hidden", children: [validationErrors && validationErrors.length > 0 && (_jsxs("div", { className: "absolute left-2 top-2 z-30 max-w-[min(60%,420px)] space-y-1", children: [validationErrors.slice(0, 3).map((msg, i) => (_jsxs("div", { role: "alert", className: "flex items-start gap-1.5 rounded-lg border border-destructive/40 bg-destructive/10 px-2.5 py-1.5 text-[11px] leading-snug text-destructive shadow-sm backdrop-blur-sm", children: [_jsx(AlertTriangle, { className: "mt-0.5 h-3.5 w-3.5 shrink-0" }), _jsx("span", { children: msg })] }, i))), validationErrors.length > 3 && (_jsxs("div", { className: "px-2.5 text-[10px] text-destructive/80", children: ["+", validationErrors.length - 3, " more\u2026"] }))] })), _jsxs("div", { className: "absolute right-2 top-2 z-30 flex items-center gap-1.5", children: [editable && (_jsxs("div", { className: "relative", children: [_jsxs("button", { type: "button", onClick: () => setPaletteOpen((v) => !v), className: "inline-flex items-center gap-1.5 rounded-lg border bg-background/90 px-2.5 py-1.5 text-xs font-medium shadow-sm backdrop-blur-sm transition-colors hover:border-primary/50 hover:bg-accent hover:text-foreground", children: [_jsx(Plus, { className: "h-3.5 w-3.5" }), tr('engine.inspector.add.node', locale)] }), paletteOpen && (_jsx(NodePalette, { locale: locale, items: paletteItems, onClose: () => setPaletteOpen(false), onPick: (type) => addNode(type, { from: selectedId ?? undefined }) }))] })), _jsxs("div", { className: "flex items-center rounded-lg border bg-background/90 shadow-sm backdrop-blur-sm", children: [_jsx("button", { type: "button", title: "Zoom out", "aria-label": "Zoom out", onClick: () => setZoom((z) => clampZoom(z - 0.15)), className: "inline-flex h-7 w-7 items-center justify-center text-muted-foreground hover:text-foreground", children: _jsx(ZoomOut, { className: "h-3.5 w-3.5" }) }), _jsxs("span", { className: "w-10 text-center text-[11px] tabular-nums text-muted-foreground", children: [Math.round(zoom * 100), "%"] }), _jsx("button", { type: "button", title: "Zoom in", "aria-label": "Zoom in", onClick: () => setZoom((z) => clampZoom(z + 0.15)), className: "inline-flex h-7 w-7 items-center justify-center text-muted-foreground hover:text-foreground", children: _jsx(ZoomIn, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", title: "Fit to view", "aria-label": "Fit to view", onClick: fitToView, className: "inline-flex h-7 w-7 items-center justify-center border-l text-muted-foreground hover:text-foreground", children: _jsx(Maximize2, { className: "h-3.5 w-3.5" }) })] })] }), _jsx("div", { ref: viewportRef, tabIndex: 0, role: "application", "aria-label": "Flow canvas", onKeyDown: onKeyDown, onPointerDown: onBgPointerDown, onPointerMove: (e) => {
                     onBgPointerMove(e);
                     onNodePointerMove(e);
                 }, onPointerUp: (e) => {
@@ -238,44 +304,66 @@ export function FlowCanvas({ nodes, edges, editable, designMode, selectedId, sel
                         width: size.width,
                         height: size.height,
                         transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
-                    }, children: [_jsxs("svg", { className: "pointer-events-none absolute left-0 top-0 overflow-visible", width: size.width, height: size.height, children: [_jsx("defs", { children: _jsx("marker", { id: "flow-arrow", viewBox: "0 0 10 10", refX: "8", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 0 L 10 5 L 0 10 z", className: "fill-muted-foreground/55" }) }) }), edges.map((edge, i) => {
+                    }, children: [_jsxs("svg", { className: "pointer-events-none absolute left-0 top-0 overflow-visible", width: size.width, height: size.height, children: [_jsxs("defs", { children: [_jsx("marker", { id: "flow-arrow", viewBox: "0 0 10 10", refX: "8", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 0 L 10 5 L 0 10 z", className: "fill-muted-foreground/55" }) }), _jsx("marker", { id: "flow-arrow-back", viewBox: "0 0 10 10", refX: "8", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 0 L 10 5 L 0 10 z", className: "fill-amber-500/80" }) }), _jsx("marker", { id: "flow-arrow-error", viewBox: "0 0 10 10", refX: "8", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse", children: _jsx("path", { d: "M 0 0 L 10 5 L 0 10 z", className: "fill-destructive" }) })] }), edges.map((edge, i) => {
                                     const sp = layout.get(edge.source);
                                     const tp = layout.get(edge.target);
                                     if (!sp || !tp)
                                         return null;
-                                    const from = bottomAnchor(dragPos?.id === edge.source ? positionOf(edge.source) : sp);
-                                    const to = topAnchor(dragPos?.id === edge.target ? positionOf(edge.target) : tp);
-                                    const mid = edgeMidpoint(from, to);
+                                    // ADR-0044 back-edges (revise loop) re-enter an earlier node, so
+                                    // they attach to the right side of both endpoints and render as a
+                                    // dashed amber return arc — visually distinct from the forward
+                                    // top-to-bottom flow.
+                                    const back = isBackEdge(edge);
+                                    // Structural-validation error (e.g. part of an un-declared cycle).
+                                    // Back-edges are excluded from cycle detection, so they're never invalid.
+                                    const invalid = !back && !!invalidEdges?.has(`${edge.source}->${edge.target}`);
+                                    const sPos = dragPos?.id === edge.source ? positionOf(edge.source) : sp;
+                                    const tPos = dragPos?.id === edge.target ? positionOf(edge.target) : tp;
+                                    const from = back ? rightAnchor(sPos) : bottomAnchor(sPos);
+                                    const to = back ? rightAnchor(tPos) : topAnchor(tPos);
+                                    const labelPos = back ? backEdgeLabelAnchor(from, to) : edgeMidpoint(from, to);
                                     const cond = conditionText(edge.condition);
                                     const branchLabel = edge.isDefault ? 'else' : cond ? `if ${cond}` : edge.label;
                                     const eid = edgeKey(edge, i);
                                     const traversed = traversedSet.has(eid);
                                     const selected = selectedEdgeId === eid;
-                                    const d = edgePath(from, to);
+                                    const d = back ? backEdgePath(from, to) : edgePath(from, to);
                                     // Edges are selectable in design mode; the host opens the edge
                                     // inspector. A wide transparent hit-path widens the click target
                                     // beyond the 1.5px visible stroke without altering the visuals.
                                     const selectable = designMode && !!onSelectEdge;
-                                    return (_jsxs("g", { children: [_jsx("path", { d: d, strokeLinecap: "round", className: cn('fill-none transition-[stroke] duration-150', traversed
+                                    return (_jsxs("g", { "data-invalid": invalid || undefined, children: [_jsx("path", { d: d, strokeLinecap: "round", strokeDasharray: back ? '5 4' : undefined, className: cn('fill-none transition-[stroke] duration-150', traversed
                                                     ? 'stroke-sky-500'
                                                     : selected
                                                         ? 'stroke-primary'
-                                                        : simRunning
-                                                            ? 'stroke-muted-foreground/20'
-                                                            : 'stroke-muted-foreground/40'), strokeWidth: traversed || selected ? 2.5 : 1.75, markerEnd: "url(#flow-arrow)" }), selectable && (_jsx("path", { d: d, className: "pointer-events-auto cursor-pointer fill-none stroke-transparent", strokeWidth: 14, onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
+                                                        : invalid
+                                                            ? 'stroke-destructive'
+                                                            : back
+                                                                ? 'stroke-amber-500/70'
+                                                                : simRunning
+                                                                    ? 'stroke-muted-foreground/20'
+                                                                    : 'stroke-muted-foreground/40'), strokeWidth: traversed || selected || invalid ? 2.5 : 1.75, markerEnd: invalid ? 'url(#flow-arrow-error)' : back ? 'url(#flow-arrow-back)' : 'url(#flow-arrow)' }), selectable && (_jsx("path", { d: d, className: "pointer-events-auto cursor-pointer fill-none stroke-transparent", strokeWidth: 14, onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
                                                     e.stopPropagation();
                                                     onSelectEdge(edge, eid);
-                                                }, children: _jsx("title", { children: `${edge.source} → ${edge.target}` }) })), branchLabel && (_jsx("foreignObject", { x: mid.x - 60, y: mid.y - 11, width: 120, height: 22, className: cn(selectable && 'pointer-events-auto'), children: _jsx("div", { className: "flex justify-center", children: _jsx("span", { onPointerDown: selectable ? (e) => e.stopPropagation() : undefined, onClick: selectable ? (e) => { e.stopPropagation(); onSelectEdge(edge, eid); } : undefined, className: cn('max-w-full truncate rounded-full border bg-background/95 px-2 py-0.5 text-[10px] font-medium shadow-sm backdrop-blur-sm transition-colors', selectable && 'cursor-pointer hover:border-primary/60', selected ? 'border-primary text-primary' : 'border-border text-muted-foreground'), children: branchLabel }) }) })), editable && (_jsx("foreignObject", { 
+                                                }, children: _jsx("title", { children: invalid ? `${edge.source} → ${edge.target} — part of an un-declared cycle; mark the edge that closes the loop as a back-edge` : back ? `${edge.source} ↩ ${edge.target} (back-edge)` : `${edge.source} → ${edge.target}` }) })), branchLabel && (_jsx("foreignObject", { x: labelPos.x - 60, y: labelPos.y - 11, width: 120, height: 22, className: cn(selectable && 'pointer-events-auto'), children: _jsx("div", { className: "flex justify-center", children: _jsx("span", { onPointerDown: selectable ? (e) => e.stopPropagation() : undefined, onClick: selectable ? (e) => { e.stopPropagation(); onSelectEdge(edge, eid); } : undefined, className: cn('max-w-full truncate rounded-full border bg-background/95 px-2 py-0.5 text-[10px] font-medium shadow-sm backdrop-blur-sm transition-colors', selectable && 'cursor-pointer hover:border-primary/60', selected
+                                                            ? 'border-primary text-primary'
+                                                            : invalid
+                                                                ? 'border-destructive/60 text-destructive'
+                                                                : back
+                                                                    ? 'border-amber-500/50 text-amber-600 dark:text-amber-400'
+                                                                    : 'border-border text-muted-foreground'), children: branchLabel }) }) })), editable && !back && (_jsx("foreignObject", { 
                                                 // Sit the insert handle at the edge midpoint, but slide it
                                                 // to the right of the branch-label pill when one is present
                                                 // so the two don't stack on the same spot.
-                                                x: branchLabel ? mid.x + 66 : mid.x - 11, y: mid.y - 11, width: 22, height: 22, className: "pointer-events-auto", children: _jsx("button", { type: "button", title: "Insert node here", "aria-label": "Insert node here", onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
+                                                x: branchLabel ? labelPos.x + 66 : labelPos.x - 11, y: labelPos.y - 11, width: 22, height: 22, className: "pointer-events-auto", children: _jsx("button", { type: "button", title: "Insert node here", "aria-label": "Insert node here", onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
                                                         e.stopPropagation();
                                                         insertOnEdge(edge);
                                                     }, className: "inline-flex h-[22px] w-[22px] items-center justify-center rounded-full border bg-background/90 text-muted-foreground opacity-50 shadow-sm backdrop-blur-sm transition-all hover:scale-110 hover:border-primary hover:bg-background hover:text-primary hover:opacity-100 focus-visible:opacity-100", children: _jsx(Plus, { className: "h-3 w-3" }) }) }))] }, edge.id || `${edge.source}-${edge.target}-${i}`));
                                 })] }), nodes.map((node) => {
                             const runState = activeNodeId === node.id ? 'active' : visitedSet.has(node.id) ? 'visited' : undefined;
-                            return (_jsx(NodeCard, { id: node.id, type: node.type, label: node.label || node.id, summary: nodeSummary(node), position: positionOf(node.id), selected: selectedId === node.id, editable: editable, runState: runState, dimmed: simRunning && !runState, onPointerDown: onNodePointerDown(node.id), onSelect: () => designMode && onSelect(node), onAppend: () => addNode('create_record', { from: node.id }) }, node.id));
+                            return (_jsx(NodeCard, { id: node.id, type: node.type, label: node.label || node.id, summary: nodeSummary(node), position: positionOf(node.id), selected: selectedId === node.id, editable: editable, runState: runState, dimmed: simRunning && !runState, onPointerDown: onNodePointerDown(node.id), onSelect: () => designMode && onSelect(node), onAppend: () => addNode('create_record', { from: node.id }), onAddReviseLoop: editable && node.type === 'approval' && !reviseLoopSources.has(node.id)
+                                    ? () => addReviseLoop(node.id)
+                                    : undefined, invalid: invalidNodeSet.has(node.id) }, node.id));
                         })] }) })] }));
 }
 /** One-line config summary shown on the node card (best-effort, type-aware). */

package/dist/views/metadata-admin/previews/FlowPreview.js

@@ -25,10 +25,13 @@ import { t as tr } from '../i18n';
 import { FlowCanvas } from './FlowCanvas';
 import { FlowSimulatorPanel } from './FlowSimulatorPanel';
 import { FlowRunsPanel } from './FlowRunsPanel';
+import { validateFlowDraft } from './simulator/flow-sim-validate';
 export function FlowPreview({ draft, editing, selection, onSelectionChange, onPatch, locale }) {
     const d = draft;
-    const nodes = Array.isArray(d.nodes) ? d.nodes : [];
-    const edges = Array.isArray(d.edges) ? d.edges : [];
+    // Memoized so hook deps (validation memo, handleAddNode) get a stable array
+    // reference across renders instead of a fresh `[]`/cast each time.
+    const nodes = React.useMemo(() => (Array.isArray(d.nodes) ? d.nodes : []), [d.nodes]);
+    const edges = React.useMemo(() => (Array.isArray(d.edges) ? d.edges : []), [d.edges]);
     const variables = Array.isArray(d.variables) ? d.variables : [];
     const designMode = !!(editing && onSelectionChange);
     const canEdit = designMode && !!onPatch;
@@ -38,6 +41,31 @@ export function FlowPreview({ draft, editing, selection, onSelectionChange, onPa
     const [showVars, setShowVars] = React.useState(true);
     const [showRuns, setShowRuns] = React.useState(false);
     const [runHL, setRunHL] = React.useState(null);
+    // Continuous structural validation surfaced INLINE on the canvas (ADR-0044):
+    // an un-declared cycle (and other structural errors) paints the offending
+    // edges/nodes red and shows a banner — so the author sees it without opening
+    // the Debug panel. Same `validateFlowDraft` the simulator preflight uses.
+    const { invalidNodeIds, invalidEdges, validationErrors } = React.useMemo(() => {
+        const v = validateFlowDraft(nodes, edges);
+        const nodeSet = new Set();
+        const edgeSet = new Set();
+        for (const diag of v.errors) {
+            if (diag.nodeId)
+                nodeSet.add(diag.nodeId);
+            // A cycle error carries its closing node path → mark each hop's edge red.
+            if (diag.cycle) {
+                for (let i = 0; i < diag.cycle.length - 1; i++) {
+                    nodeSet.add(diag.cycle[i]);
+                    edgeSet.add(`${diag.cycle[i]}->${diag.cycle[i + 1]}`);
+                }
+            }
+        }
+        return {
+            invalidNodeIds: [...nodeSet],
+            invalidEdges: edgeSet,
+            validationErrors: v.errors.map((diag) => diag.message),
+        };
+    }, [nodes, edges]);
     const handleAddNode = React.useCallback(() => {
         if (!canEdit)
             return;
@@ -76,7 +104,7 @@ export function FlowPreview({ draft, editing, selection, onSelectionChange, onPa
                                                 }, className: 'inline-flex items-center gap-1 rounded border px-2 py-0.5 text-[11px] font-medium transition-colors ' +
                                                     (showDebug
                                                         ? 'border-sky-500 bg-sky-50 text-sky-700'
-                                                        : 'border-border text-muted-foreground hover:bg-muted/50 hover:text-foreground'), children: [_jsx(Bug, { className: "h-3 w-3" }), " Debug"] })] })] }), _jsx("div", { className: "flex-1 min-h-0", children: _jsx(FlowCanvas, { nodes: nodes, edges: edges, editable: canEdit, designMode: designMode, selectedId: selectedId, selectedEdgeId: selectedEdgeId, locale: locale, activeNodeId: runHL?.activeNodeId ?? null, visitedNodeIds: runHL?.visitedNodeIds, traversedEdgeIds: runHL?.traversedEdgeIds, onSelect: (n) => n
+                                                        : 'border-border text-muted-foreground hover:bg-muted/50 hover:text-foreground'), children: [_jsx(Bug, { className: "h-3 w-3" }), " Debug"] })] })] }), _jsx("div", { className: "flex-1 min-h-0", children: _jsx(FlowCanvas, { nodes: nodes, edges: edges, editable: canEdit, designMode: designMode, selectedId: selectedId, selectedEdgeId: selectedEdgeId, locale: locale, activeNodeId: runHL?.activeNodeId ?? null, visitedNodeIds: runHL?.visitedNodeIds, traversedEdgeIds: runHL?.traversedEdgeIds, invalidNodeIds: invalidNodeIds, invalidEdges: invalidEdges, validationErrors: validationErrors, onSelect: (n) => n
                                         ? onSelectionChange?.({ kind: 'node', id: n.id, label: n.label || n.id })
                                         : onSelectionChange?.(null), onSelectEdge: (e, key) => e
                                         ? onSelectionChange?.({ kind: 'edge', id: key, label: `${e.source} → ${e.target}` })