@object-ui/app-shell 6.2.3 → 7.1.0

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

@@ -0,0 +1,120 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * FlowPreview — read-only summary of a Flow metadata draft.
+ *
+ * A full DAG canvas lives in `@object-ui/plugin-designer` and would
+ * pull in ReactFlow + its deps every time the metadata-admin loads,
+ * which is too heavy for a glance-preview. Instead we render:
+ *
+ *   1. A header strip with type / status / runAs / version.
+ *   2. A topologically ordered step list inferred from `nodes` +
+ *      `edges`. Each step shows label, action type, branch markers,
+ *      and outgoing edge conditions so authors can sanity-check the
+ *      logic without launching the designer.
+ *   3. A variables side panel listing declared flow variables.
+ *
+ * The renderer is defensive — drafts may be mid-edit with dangling
+ * edges or duplicate node ids; we never throw, we just degrade.
+ */
+import * as React from 'react';
+import { Bug, CircleDot, GitBranch, History, PanelRight, Plus, Settings2, Variable, Zap, } from 'lucide-react';
+import { PreviewShell, PreviewMessage, PreviewErrorBoundary } from './PreviewShell';
+import { uniqueId, appendArray } from '../inspectors/_shared';
+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;
+    // 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;
+    const selectedId = selection && selection.kind === 'node' ? selection.id : null;
+    const selectedEdgeId = selection && selection.kind === 'edge' ? selection.id : null;
+    const [showDebug, setShowDebug] = React.useState(false);
+    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;
+        const existingIds = nodes.map((n) => n.id).filter(Boolean);
+        // A flow's first node is its trigger — seed a `start` node (not a generic
+        // `task`) so the canvas opens on the canonical entry point and the author
+        // adds subsequent steps from there.
+        const newNode = { id: uniqueId('node', existingIds), type: 'start', label: 'Start' };
+        const next = appendArray(nodes, newNode);
+        onPatch({ nodes: next });
+        onSelectionChange?.({ kind: 'node', id: newNode.id, label: newNode.label || newNode.id });
+    }, [canEdit, nodes, onPatch, onSelectionChange]);
+    // Run history needs the published flow name (the engine keys runs by it).
+    const flowName = typeof d.name === 'string' && d.name ? d.name : '';
+    const flowType = String(d.type ?? 'autolaunched');
+    const status = String(d.status ?? (d.active ? 'active' : 'draft'));
+    const runAs = String(d.runAs ?? 'user');
+    const version = d.version != null ? String(d.version) : undefined;
+    const errorStrategy = d.errorHandling?.strategy;
+    if (nodes.length === 0) {
+        return (_jsx(PreviewShell, { hint: `flow${designMode ? ' · design' : ''}`, children: canEdit ? (_jsx("div", { className: "p-3", children: _jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded border border-dashed px-3 py-2 text-xs text-muted-foreground hover:bg-muted/30 hover:text-foreground", onClick: handleAddNode, children: [_jsx(Plus, { className: "h-3 w-3" }), tr('engine.inspector.add.node', locale)] }) })) : (_jsx(PreviewMessage, { children: "Add nodes in the Form tab to see the flow preview." })) }));
+    }
+    return (_jsx(PreviewShell, { hint: `flow · ${nodes.length} node${nodes.length === 1 ? '' : 's'}`, children: _jsx(PreviewErrorBoundary, { fallbackHint: "One of the flow nodes or edges is malformed.", children: _jsxs("div", { className: 'grid gap-0 h-full min-h-[440px] ' +
+                    (showDebug || showVars || showRuns ? 'lg:grid-cols-[1fr_240px]' : 'grid-cols-1'), children: [_jsxs("div", { className: "flex flex-col min-w-0 min-h-0", children: [_jsxs("div", { className: "rounded-none border-b bg-muted/30 px-3 py-2 text-xs flex flex-wrap items-center gap-x-4 gap-y-1", children: [_jsx(Pill, { icon: Zap, label: "Trigger", value: flowType }), _jsx(Pill, { icon: CircleDot, label: "Status", value: status, tone: status === 'active' ? 'green' : status === 'draft' ? 'gray' : 'amber' }), _jsx(Pill, { icon: Settings2, label: "Run as", value: runAs }), version && _jsx(Pill, { label: "v", value: version }), errorStrategy && _jsx(Pill, { icon: GitBranch, label: "On error", value: errorStrategy }), _jsxs("div", { className: "ml-auto flex items-center gap-1.5", children: [!showDebug && !showRuns && (_jsxs("button", { type: "button", onClick: () => setShowVars((v) => !v), className: 'inline-flex items-center gap-1 rounded border px-2 py-0.5 text-[11px] font-medium transition-colors ' +
+                                                    (showVars
+                                                        ? 'border-violet-500 bg-violet-50 text-violet-700'
+                                                        : 'border-border text-muted-foreground hover:bg-muted/50 hover:text-foreground'), title: showVars ? 'Hide variables panel' : 'Show variables panel', children: [_jsx(PanelRight, { className: "h-3 w-3" }), " Variables"] })), flowName && (_jsxs("button", { type: "button", onClick: () => {
+                                                    setShowRuns((v) => !v);
+                                                    setShowDebug(false);
+                                                }, className: 'inline-flex items-center gap-1 rounded border px-2 py-0.5 text-[11px] font-medium transition-colors ' +
+                                                    (showRuns
+                                                        ? 'border-emerald-500 bg-emerald-50 text-emerald-700'
+                                                        : 'border-border text-muted-foreground hover:bg-muted/50 hover:text-foreground'), title: "Run history from the automation engine", children: [_jsx(History, { className: "h-3 w-3" }), " Runs"] })), _jsxs("button", { type: "button", onClick: () => {
+                                                    setShowDebug((v) => !v);
+                                                    setShowRuns(false);
+                                                }, 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, 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}` })
+                                        : onSelectionChange?.(null), onPatch: onPatch }) })] }), showDebug ? (_jsx("div", { className: "border-l bg-muted/20", children: _jsx(FlowSimulatorPanel, { nodes: nodes, edges: edges, variables: variables, onRunStateChange: setRunHL }) })) : showRuns && flowName ? (_jsx("div", { className: "border-l bg-muted/20", children: _jsx(FlowRunsPanel, { flowName: flowName }) })) : showVars ? (_jsxs("div", { className: "border-l bg-muted/20 p-3 text-xs space-y-2", children: [_jsxs("div", { className: "flex items-center gap-1.5 font-medium text-muted-foreground", children: [_jsx(Variable, { className: "h-3 w-3" }), " Variables"] }), variables.length === 0 ? (_jsx("div", { className: "text-muted-foreground italic", children: "No variables declared." })) : (_jsx("ul", { className: "space-y-1.5", children: variables.map((v, i) => (_jsxs("li", { className: "rounded border bg-background p-1.5", children: [_jsxs("div", { className: "flex items-baseline gap-1 flex-wrap", children: [_jsx("span", { className: "font-mono", children: v.name }), v.type && (_jsx("span", { className: "text-[10px] uppercase text-muted-foreground", children: v.type })), v.isInput && (_jsx("span", { className: "text-[9px] font-semibold uppercase px-1 rounded bg-sky-100 text-sky-700", children: "in" })), v.isOutput && (_jsx("span", { className: "text-[9px] font-semibold uppercase px-1 rounded bg-emerald-100 text-emerald-700", children: "out" }))] }), v.defaultValue !== undefined && (_jsxs("div", { className: "text-[10px] text-muted-foreground font-mono truncate", children: ["= ", String(v.defaultValue)] }))] }, v.name || i))) }))] })) : null] }) }) }));
+}
+function Pill({ icon: Icon, label, value, tone = 'gray', }) {
+    const cls = tone === 'green'
+        ? 'text-emerald-700'
+        : tone === 'amber'
+            ? 'text-amber-700'
+            : 'text-foreground';
+    return (_jsxs("span", { className: "inline-flex items-center gap-1", children: [Icon && _jsx(Icon, { className: "h-3 w-3 text-muted-foreground" }), _jsxs("span", { className: "text-muted-foreground", children: [label, ":"] }), _jsx("span", { className: `font-medium ${cls}`, children: value })] }));
+}

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

@@ -0,0 +1,46 @@
+/**
+ * FlowRunsPanel — run history for a flow, fetched from the automation engine
+ * (`GET /api/v1/automation/{name}/runs`, the observability surface next to
+ * resume/screen). Renders each run's status / start time / duration with an
+ * expandable per-node step log (the `ExecutionLog.steps` ADR-0019/#1479 shape),
+ * so authors can see where a run paused or failed without leaving the Studio.
+ *
+ * Degrades like the palette fetch: offline / plugin-absent / older backend →
+ * a quiet "history unavailable" note, never an error state that blocks the
+ * designer.
+ */
+import * as React from 'react';
+/** Step entry of a run log (spec `ExecutionStepLogSchema`, fields we render). */
+interface RunStep {
+    nodeId: string;
+    nodeType?: string;
+    status: 'success' | 'failure' | 'skipped' | string;
+    durationMs?: number;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/** Run log entry (spec `ExecutionLogSchema`, fields we render). */
+export interface FlowRun {
+    id: string;
+    status: 'completed' | 'failed' | 'paused' | 'running' | 'cancelled' | string;
+    startedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    trigger?: {
+        type?: string;
+        userId?: string;
+        object?: string;
+    };
+    steps?: RunStep[];
+    error?: {
+        message?: string;
+    };
+}
+/** Fetch a flow's run history. Exposed for tests. */
+export declare function fetchFlowRuns(flowName: string, signal?: AbortSignal): Promise<FlowRun[] | null>;
+export declare function FlowRunsPanel({ flowName }: {
+    flowName: string;
+}): React.JSX.Element;
+export {};

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

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * FlowRunsPanel — run history for a flow, fetched from the automation engine
+ * (`GET /api/v1/automation/{name}/runs`, the observability surface next to
+ * resume/screen). Renders each run's status / start time / duration with an
+ * expandable per-node step log (the `ExecutionLog.steps` ADR-0019/#1479 shape),
+ * so authors can see where a run paused or failed without leaving the Studio.
+ *
+ * Degrades like the palette fetch: offline / plugin-absent / older backend →
+ * a quiet "history unavailable" note, never an error state that blocks the
+ * designer.
+ */
+import * as React from 'react';
+import { AlertCircle, CheckCircle2, ChevronDown, ChevronRight, Clock, Loader2, PauseCircle, RefreshCw, SkipForward } from 'lucide-react';
+import { cn } from '@object-ui/components';
+import { apiBase } from './useFlowNodePalette';
+/** Fetch a flow's run history. Exposed for tests. */
+export async function fetchFlowRuns(flowName, signal) {
+    try {
+        const res = await fetch(`${apiBase()}/automation/${encodeURIComponent(flowName)}/runs?limit=25`, { credentials: 'include', headers: { 'Content-Type': 'application/json' }, signal });
+        if (!res.ok)
+            return null; // 404/501 — plugin absent or older backend
+        const payload = (await res.json());
+        const runs = payload?.data?.runs ?? payload?.runs;
+        return Array.isArray(runs) ? runs : null;
+    }
+    catch {
+        return null; // offline / aborted
+    }
+}
+const STATUS_META = {
+    completed: { icon: CheckCircle2, cls: 'text-emerald-600 dark:text-emerald-400', label: 'Completed' },
+    failed: { icon: AlertCircle, cls: 'text-rose-600 dark:text-rose-400', label: 'Failed' },
+    paused: { icon: PauseCircle, cls: 'text-amber-600 dark:text-amber-400', label: 'Paused' },
+    running: { icon: Loader2, cls: 'text-sky-600 dark:text-sky-400', label: 'Running' },
+    cancelled: { icon: SkipForward, cls: 'text-muted-foreground', label: 'Cancelled' },
+};
+function statusMeta(status) {
+    return STATUS_META[status] ?? { icon: Clock, cls: 'text-muted-foreground', label: status };
+}
+function fmtTime(iso) {
+    if (!iso)
+        return '—';
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? iso : d.toLocaleString();
+}
+function fmtDuration(ms) {
+    if (ms == null)
+        return null;
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${Math.round(ms / 60000)}m`;
+}
+function StepRow({ step }) {
+    const cls = step.status === 'success'
+        ? 'text-emerald-600 dark:text-emerald-400'
+        : step.status === 'failure'
+            ? 'text-rose-600 dark:text-rose-400'
+            : 'text-muted-foreground';
+    return (_jsxs("li", { className: "flex items-baseline gap-1.5 py-0.5", children: [_jsx("span", { className: cn('shrink-0 text-[9px] font-semibold uppercase', cls), children: step.status }), _jsx("span", { className: "truncate font-mono text-[10px]", title: step.nodeId, children: step.nodeId }), step.nodeType && _jsx("span", { className: "shrink-0 text-[9px] uppercase text-muted-foreground", children: step.nodeType }), fmtDuration(step.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[9px] text-muted-foreground", children: fmtDuration(step.durationMs) })), step.error?.message && (_jsx("span", { className: "min-w-0 truncate text-[9px] text-rose-600", title: step.error.message, children: step.error.message }))] }));
+}
+function RunRow({ run }) {
+    const [open, setOpen] = React.useState(false);
+    const meta = statusMeta(run.status);
+    const Icon = meta.icon;
+    const steps = Array.isArray(run.steps) ? run.steps : [];
+    return (_jsxs("li", { className: "rounded border bg-background", children: [_jsxs("button", { type: "button", onClick: () => setOpen((v) => !v), className: "flex w-full items-center gap-1.5 p-1.5 text-left", "aria-expanded": open, children: [open ? (_jsx(ChevronDown, { className: "h-3 w-3 shrink-0 text-muted-foreground" })) : (_jsx(ChevronRight, { className: "h-3 w-3 shrink-0 text-muted-foreground" })), _jsx(Icon, { className: cn('h-3.5 w-3.5 shrink-0', meta.cls, run.status === 'running' && 'animate-spin') }), _jsx("span", { className: cn('shrink-0 text-[10px] font-semibold', meta.cls), children: meta.label }), _jsx("span", { className: "min-w-0 truncate text-[10px] text-muted-foreground", title: run.id, children: fmtTime(run.startedAt) }), fmtDuration(run.durationMs) && (_jsx("span", { className: "ml-auto shrink-0 text-[10px] text-muted-foreground", children: fmtDuration(run.durationMs) }))] }), open && (_jsxs("div", { className: "border-t px-2 py-1.5", children: [_jsxs("div", { className: "pb-1 font-mono text-[9px] text-muted-foreground", title: run.id, children: ["run ", run.id, run.trigger?.type && ` · trigger ${run.trigger.type}`] }), run.error?.message && (_jsx("div", { className: "pb-1 text-[10px] text-rose-600", children: run.error.message })), steps.length === 0 ? (_jsx("div", { className: "text-[10px] italic text-muted-foreground", children: "No step log recorded." })) : (_jsx("ul", { className: "divide-y divide-border/50", children: steps.map((s, i) => (_jsx(StepRow, { step: s }, `${s.nodeId}#${i}`))) }))] }))] }));
+}
+export function FlowRunsPanel({ flowName }) {
+    const [runs, setRuns] = React.useState([]);
+    const [state, setState] = React.useState('loading');
+    const [reloadKey, setReloadKey] = React.useState(0);
+    React.useEffect(() => {
+        const controller = new AbortController();
+        let alive = true;
+        setState('loading');
+        (async () => {
+            const result = await fetchFlowRuns(flowName, controller.signal);
+            if (!alive)
+                return;
+            if (result === null)
+                setState('unavailable');
+            else {
+                setRuns(result);
+                setState('ready');
+            }
+        })();
+        return () => {
+            alive = false;
+            controller.abort();
+        };
+    }, [flowName, reloadKey]);
+    return (_jsxs("div", { className: "flex h-full flex-col p-3 text-xs", children: [_jsxs("div", { className: "flex items-center gap-1.5 pb-2 font-medium text-muted-foreground", children: [_jsx(Clock, { className: "h-3 w-3" }), " Runs", _jsx("button", { type: "button", onClick: () => setReloadKey((k) => k + 1), title: "Refresh run history", "aria-label": "Refresh run history", className: "ml-auto rounded p-0.5 text-muted-foreground transition-colors hover:bg-muted/50 hover:text-foreground", children: _jsx(RefreshCw, { className: cn('h-3 w-3', state === 'loading' && 'animate-spin') }) })] }), state === 'unavailable' ? (_jsx("div", { className: "italic text-muted-foreground", children: "Run history unavailable \u2014 the automation engine is offline or this flow hasn\u2019t been published." })) : state === 'ready' && runs.length === 0 ? (_jsx("div", { className: "italic text-muted-foreground", children: "No runs yet." })) : (_jsx("ul", { className: "min-h-0 flex-1 space-y-1.5 overflow-y-auto", children: runs.map((r) => (_jsx(RunRow, { run: r }, r.id))) }))] }));
+}

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

@@ -0,0 +1,25 @@
+/**
+ * FlowSimulatorPanel — the designer-time debug runner UI. Drives a
+ * `FlowSimulator` (pure engine) and lifts its highlight state up so the canvas
+ * can paint the active node / traversed edges. Side effects are mocked; the
+ * panel only collects the flow's input variables as the run seed.
+ */
+import * as React from 'react';
+import type { SimEdge, SimNode } from './simulator/flow-sim-types';
+export interface FlowVariableDecl {
+    name: string;
+    type?: string;
+    defaultValue?: unknown;
+    isInput?: boolean;
+}
+export interface FlowSimulatorPanelProps {
+    nodes: SimNode[];
+    edges: SimEdge[];
+    variables: FlowVariableDecl[];
+    onRunStateChange?: (s: {
+        activeNodeId: string | null;
+        visitedNodeIds: string[];
+        traversedEdgeIds: string[];
+    } | null) => void;
+}
+export declare function FlowSimulatorPanel({ nodes, edges, variables, onRunStateChange }: FlowSimulatorPanelProps): React.JSX.Element;

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

@@ -0,0 +1,204 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * FlowSimulatorPanel — the designer-time debug runner UI. Drives a
+ * `FlowSimulator` (pure engine) and lifts its highlight state up so the canvas
+ * can paint the active node / traversed edges. Side effects are mocked; the
+ * panel only collects the flow's input variables as the run seed.
+ */
+import * as React from 'react';
+import { Play, StepForward, RotateCcw, ChevronRight, AlertTriangle, CircleAlert, Plus, Trash2 } from 'lucide-react';
+import { Button, Input, Label, cn } from '@object-ui/components';
+import { FlowSimulator } from './simulator/flow-simulator';
+import { ScreenPreview } from './ScreenPreview';
+/** Coerce a free-text seed value: number / boolean / JSON object|array / string. */
+function parseSeed(raw) {
+    const s = raw.trim();
+    if (s === '')
+        return undefined;
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return Number(s);
+    if ((s.startsWith('{') && s.endsWith('}')) || (s.startsWith('[') && s.endsWith(']'))) {
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+}
+/** Node types whose side effects are mocked — authors can pin their output. */
+const MOCKABLE = new Set([
+    'create_record',
+    'update_record',
+    'delete_record',
+    'get_record',
+    'http_request',
+    'connector_action',
+    'script',
+]);
+function mockableNodes(nodes) {
+    const out = [];
+    for (const n of nodes) {
+        if (!MOCKABLE.has(n.type))
+            continue;
+        const cfg = (n.config ?? {});
+        const outputs = [];
+        if (typeof cfg.outputVariable === 'string' && cfg.outputVariable)
+            outputs.push(cfg.outputVariable);
+        if (Array.isArray(cfg.outputVariables)) {
+            for (const o of cfg.outputVariables)
+                if (typeof o === 'string')
+                    outputs.push(o);
+        }
+        out.push({ id: n.id, label: n.label || n.id, type: n.type, outputs });
+    }
+    return out;
+}
+const STATUS_TONE = {
+    ok: 'bg-emerald-100 text-emerald-700',
+    mocked: 'bg-violet-100 text-violet-700',
+    paused: 'bg-amber-100 text-amber-700',
+    skipped: 'bg-zinc-100 text-zinc-600',
+    error: 'bg-rose-100 text-rose-700',
+};
+export function FlowSimulatorPanel({ nodes, edges, variables, onRunStateChange }) {
+    const simRef = React.useRef(null);
+    const [snapshot, setSnapshot] = React.useState(null);
+    const [validation, setValidation] = React.useState(null);
+    const inputs = React.useMemo(() => variables.filter((v) => v.isInput), [variables]);
+    const mockNodes = React.useMemo(() => mockableNodes(nodes), [nodes]);
+    const [seed, setSeed] = React.useState({});
+    /** Free-form variable overrides so any branch can be exercised (e.g. a
+     * decision that reads a computed value no input declares). */
+    const [scratch, setScratch] = React.useState([]);
+    /** Per-node mock outputs, keyed by node id (raw text, parsed on run). */
+    const [mocks, setMocks] = React.useState({});
+    const sync = React.useCallback(() => {
+        const sim = simRef.current;
+        if (!sim)
+            return;
+        const st = sim.state;
+        setSnapshot({
+            ...st,
+            steps: [...st.steps],
+            variables: { ...st.variables },
+            frontier: [...st.frontier],
+            visitedNodeIds: [...st.visitedNodeIds],
+            traversedEdgeIds: [...st.traversedEdgeIds],
+        });
+        onRunStateChange?.({
+            activeNodeId: st.activeNodeId,
+            visitedNodeIds: [...st.visitedNodeIds],
+            traversedEdgeIds: [...st.traversedEdgeIds],
+        });
+    }, [onRunStateChange]);
+    const buildSeed = React.useCallback(() => {
+        const out = {};
+        for (const v of inputs) {
+            const raw = seed[v.name];
+            const parsed = raw != null ? parseSeed(raw) : undefined;
+            out[v.name] = parsed !== undefined ? parsed : v.defaultValue;
+        }
+        // Scratch overrides win — they let an author drive any branch.
+        for (const row of scratch) {
+            const key = row.k.trim();
+            if (key)
+                out[key] = parseSeed(row.v);
+        }
+        return out;
+    }, [inputs, seed, scratch]);
+    const buildMocks = React.useCallback(() => {
+        const out = {};
+        for (const [id, raw] of Object.entries(mocks)) {
+            if (raw != null && raw.trim() !== '')
+                out[id] = parseSeed(raw);
+        }
+        return out;
+    }, [mocks]);
+    const reset = React.useCallback(() => {
+        const sim = new FlowSimulator(nodes, edges);
+        simRef.current = sim;
+        setValidation(sim.reset(buildSeed(), buildMocks()));
+        sync();
+    }, [nodes, edges, buildSeed, buildMocks, sync]);
+    const ensure = React.useCallback(() => {
+        if (!simRef.current)
+            reset();
+        return simRef.current;
+    }, [reset]);
+    const onRun = () => {
+        // A paused run (wait / screen) continues from where it halted. Any other
+        // state — fresh, done, or errored — starts a clean run that re-seeds with
+        // the current Set-variables and Mock-outputs editors, so editing them and
+        // pressing Run again always reflects the new values.
+        let sim = simRef.current;
+        if (sim && sim.state.status === 'paused') {
+            // An approval pause needs an explicit decision (use the branch buttons);
+            // blind-resuming would fan out to every branch — so leave it for the user.
+            if (sim.state.pausedReason === 'approval') {
+                sync();
+                return;
+            }
+            sim.resume();
+        }
+        else {
+            reset();
+            sim = simRef.current;
+        }
+        sim.runToEnd();
+        sync();
+    };
+    const onStep = () => {
+        const sim = ensure();
+        sim.step();
+        sync();
+    };
+    const onResume = () => onDecision();
+    /** Continue a paused run; `decision` routes an approval down one out-edge. */
+    const onDecision = (decision) => {
+        const sim = ensure();
+        sim.resume(decision ? { decision } : {});
+        sim.runToEnd();
+        sync();
+    };
+    const onReset = () => {
+        simRef.current = null;
+        setSnapshot(null);
+        setValidation(null);
+        onRunStateChange?.(null);
+    };
+    const status = snapshot?.status ?? 'idle';
+    const blocked = (validation?.errors.length ?? 0) > 0;
+    // When the run pauses at a `screen` node, preview the form the end user would
+    // see (the shared runtime renderer) instead of just showing "paused".
+    const screenPause = React.useMemo(() => {
+        if (snapshot?.status !== 'paused' || snapshot.pausedReason !== 'screen' || !snapshot.activeNodeId)
+            return null;
+        const node = nodes.find((n) => n.id === snapshot.activeNodeId);
+        return node ? { node, variables: snapshot.variables } : null;
+    }, [snapshot, nodes]);
+    // When paused at an approval node, offer its out-edge labels (approve /
+    // reject / revise) as decision buttons so the run resumes down ONE branch —
+    // letting an author walk a revise loop instead of fanning out to every edge.
+    const approvalPause = React.useMemo(() => {
+        if (snapshot?.status !== 'paused' || snapshot.pausedReason !== 'approval' || !snapshot.activeNodeId)
+            return null;
+        const node = nodes.find((n) => n.id === snapshot.activeNodeId);
+        if (!node)
+            return null;
+        const decisions = [
+            ...new Set(edges
+                .filter((e) => e.source === node.id && typeof e.label === 'string' && e.label.trim())
+                .map((e) => e.label.trim())),
+        ];
+        return { node, decisions };
+    }, [snapshot, nodes, edges]);
+    return (_jsxs("div", { className: "flex h-full flex-col text-xs", children: [_jsxs("div", { className: "flex items-center gap-1.5 border-b bg-muted/30 px-3 py-2", children: [_jsxs(Button, { size: "sm", className: "h-7 gap-1 px-2", onClick: onRun, disabled: blocked, children: [_jsx(Play, { className: "h-3.5 w-3.5" }), " Run"] }), _jsxs(Button, { size: "sm", variant: "outline", className: "h-7 gap-1 px-2", onClick: onStep, disabled: blocked || status === 'done' || status === 'error', children: [_jsx(StepForward, { className: "h-3.5 w-3.5" }), " Step"] }), status === 'paused' &&
+                        (approvalPause && approvalPause.decisions.length > 0 ? (_jsx("div", { className: "flex items-center gap-1", children: approvalPause.decisions.map((d) => (_jsxs(Button, { size: "sm", variant: "outline", className: "h-7 gap-1 px-2 capitalize", onClick: () => onDecision(d), title: `Resume down the "${d}" branch`, children: [_jsx(ChevronRight, { className: "h-3.5 w-3.5" }), " ", d] }, d))) })) : (_jsxs(Button, { size: "sm", variant: "outline", className: "h-7 gap-1 px-2", onClick: onResume, children: [_jsx(ChevronRight, { className: "h-3.5 w-3.5" }), " Continue"] }))), _jsxs(Button, { size: "sm", variant: "ghost", className: "h-7 gap-1 px-2 text-muted-foreground", onClick: onReset, children: [_jsx(RotateCcw, { className: "h-3.5 w-3.5" }), " Reset"] }), _jsx("span", { className: cn('ml-auto rounded px-1.5 py-0.5 text-[10px] font-semibold uppercase', STATUS_TONE[status === 'idle' || status === 'running' ? 'ok' : status] ?? 'bg-muted'), children: status })] }), _jsxs("div", { className: "min-h-0 flex-1 space-y-3 overflow-auto p-3", children: [validation && (validation.errors.length > 0 || validation.warnings.length > 0) && (_jsxs("div", { className: "space-y-1", children: [validation.errors.map((d, i) => (_jsxs("div", { className: "flex items-start gap-1.5 rounded border border-rose-200 bg-rose-50 px-2 py-1 text-rose-700", children: [_jsx(CircleAlert, { className: "mt-0.5 h-3 w-3 shrink-0" }), _jsx("span", { children: d.message })] }, `e${i}`))), validation.warnings.map((d, i) => (_jsxs("div", { className: "flex items-start gap-1.5 rounded border border-amber-200 bg-amber-50 px-2 py-1 text-amber-700", children: [_jsx(AlertTriangle, { className: "mt-0.5 h-3 w-3 shrink-0" }), _jsx("span", { children: d.message })] }, `w${i}`)))] })), screenPause && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Screen" }), _jsx(ScreenPreview, { node: screenPause.node, variables: screenPause.variables })] })), inputs.length > 0 && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Inputs" }), inputs.map((v) => (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Label, { className: "w-24 shrink-0 truncate font-mono text-[11px]", title: v.name, children: v.name }), _jsx(Input, { value: seed[v.name] ?? (v.defaultValue != null ? String(v.defaultValue) : ''), onChange: (e) => setSeed((p) => ({ ...p, [v.name]: e.target.value })), placeholder: v.type ?? 'value', className: "h-7 flex-1 text-xs" })] }, v.name)))] })), _jsxs("section", { className: "space-y-1.5", children: [_jsxs("div", { className: "flex items-center gap-1.5 font-medium text-muted-foreground", children: [_jsx("span", { children: "Set variables" }), _jsxs("button", { type: "button", className: "ml-auto inline-flex items-center gap-0.5 rounded border px-1.5 py-0.5 text-[10px] hover:bg-muted/50", onClick: () => setScratch((p) => [...p, { k: '', v: '' }]), children: [_jsx(Plus, { className: "h-3 w-3" }), " Add"] })] }), scratch.length === 0 ? (_jsx("div", { className: "italic text-muted-foreground", children: "Override or inject any variable (wins over inputs and mocks at start)." })) : (scratch.map((row, i) => (_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx(Input, { value: row.k, onChange: (e) => setScratch((p) => p.map((r, j) => (j === i ? { ...r, k: e.target.value } : r))), placeholder: "name", className: "h-7 w-24 shrink-0 font-mono text-[11px]" }), _jsx("span", { className: "text-muted-foreground", children: "=" }), _jsx(Input, { value: row.v, onChange: (e) => setScratch((p) => p.map((r, j) => (j === i ? { ...r, v: e.target.value } : r))), placeholder: "value", className: "h-7 flex-1 text-xs" }), _jsx("button", { type: "button", className: "shrink-0 rounded p-1 text-muted-foreground hover:bg-muted/50 hover:text-rose-600", onClick: () => setScratch((p) => p.filter((_, j) => j !== i)), "aria-label": "Remove variable", children: _jsx(Trash2, { className: "h-3 w-3" }) })] }, i))))] }), mockNodes.length > 0 && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Mock outputs" }), mockNodes.map((m) => (_jsxs("div", { className: "space-y-0.5", children: [_jsxs(Label, { className: "flex items-baseline gap-1.5 text-[11px]", title: m.id, children: [_jsx("span", { className: "truncate font-medium", children: m.label }), _jsx("span", { className: "text-[9px] uppercase text-muted-foreground", children: m.type.replace(/_/g, ' ') }), m.outputs.length > 0 && (_jsxs("span", { className: "truncate font-mono text-[10px] text-violet-600", children: ["\u2192 ", m.outputs.join(', ')] }))] }), _jsx(Input, { value: mocks[m.id] ?? '', onChange: (e) => setMocks((p) => ({ ...p, [m.id]: e.target.value })), placeholder: m.type === 'script' && m.outputs.length ? `{ "${m.outputs[0]}": … }` : 'mocked result (JSON)', className: "h-7 w-full font-mono text-[11px]" })] }, m.id)))] })), snapshot && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Variables" }), Object.keys(snapshot.variables).length === 0 ? (_jsx("div", { className: "italic text-muted-foreground", children: "No variables set." })) : (_jsx("ul", { className: "space-y-1", children: Object.entries(snapshot.variables).map(([k, val]) => (_jsxs("li", { className: "flex items-baseline gap-1.5 rounded border bg-background px-1.5 py-1", children: [_jsx("span", { className: "font-mono text-[11px]", children: k }), _jsxs("span", { className: "truncate font-mono text-[10px] text-muted-foreground", children: ["= ", typeof val === 'object' ? JSON.stringify(val) : String(val)] })] }, k))) }))] })), snapshot && snapshot.steps.length > 0 && (_jsxs("section", { className: "space-y-1.5", children: [_jsx("div", { className: "font-medium text-muted-foreground", children: "Timeline" }), _jsx("ol", { className: "space-y-1", children: snapshot.steps.map((s) => (_jsxs("li", { className: "rounded border bg-background p-1.5", children: [_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "font-mono text-[10px] text-muted-foreground", children: s.seq + 1 }), _jsx("span", { className: "truncate font-medium", children: s.label }), _jsx("span", { className: "text-[10px] uppercase text-muted-foreground", children: s.type }), _jsx("span", { className: cn('ml-auto rounded px-1 py-0.5 text-[9px] font-semibold uppercase', STATUS_TONE[s.status]), children: s.status })] }), s.note && _jsx("div", { className: "mt-0.5 text-[10px] text-muted-foreground", children: s.note }), s.error && _jsx("div", { className: "mt-0.5 text-[10px] text-rose-600", children: s.error }), s.wrote && (_jsxs("div", { className: "mt-0.5 truncate font-mono text-[10px] text-violet-600", children: ["\u2192 ", Object.keys(s.wrote).join(', ')] })), s.edges && s.edges.length > 0 && (_jsx("ul", { className: "mt-0.5 space-y-0.5", children: s.edges.map((ed) => (_jsxs("li", { className: "space-y-0.5", children: [_jsxs("div", { className: cn('flex items-center gap-1 font-mono text-[10px]', ed.selected ? 'text-sky-700' : 'text-muted-foreground'), children: [_jsx("span", { children: ed.selected ? '▶' : '·' }), _jsx("span", { className: "truncate", children: ed.isDefault ? 'else' : ed.condition }), _jsx("span", { className: cn('ml-auto', ed.error && 'text-rose-600'), children: ed.error ? 'error' : ed.result ? 'true' : 'false' })] }), ed.error && _jsx("div", { className: "pl-3 text-[10px] text-rose-600", children: ed.error })] }, ed.edgeId))) }))] }, s.seq))) })] })), !snapshot && !blocked && (_jsx("p", { className: "italic text-muted-foreground", children: "Press Run to simulate, or Step to walk node by node. Side effects are mocked \u2014 no backend is called." }))] })] }));
+}

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

@@ -0,0 +1,28 @@
+/**
+ * JobPreview — read-only summary of a Background Job draft.
+ *
+ * Canonical shape (see `packages/spec/src/system/job.zod.ts`):
+ *   schedule: { type: 'cron',     expression: string | { dialect:'cron', source:string }, timezone? }
+ *           | { type: 'interval', intervalMs: number }
+ *           | { type: 'once',     at: string (ISO) }
+ *   handler: string         — function key registered in defineStack({ functions })
+ *   retryPolicy?: { maxRetries, backoffMs, backoffMultiplier }
+ *   timeout?: number (ms)
+ *   enabled?: boolean
+ *
+ * Legacy / app-supplied flat shapes are also tolerated:
+ *   • `cron` (string)        — top-level cron expression
+ *   • `every` / `interval`   — interval like "5m" or millis number
+ *   • `at` / `runAs`         — one-shot ISO
+ *   • `timezone` / `tz`
+ *   • `active` / `enabled`
+ *
+ * For cron schedules we compute the **next 5 fire times** locally so
+ * operators can sanity-check the schedule without waiting for the
+ * runtime. The cron parser handles standard 5-field cron with `*`,
+ * `*\/N`, comma lists, and ranges (`a-b`). Special tokens like
+ * `@daily` / `@hourly` are also expanded.
+ */
+import * as React from 'react';
+import type { MetadataPreviewProps } from '../preview-registry';
+export declare function JobPreview({ name, draft }: MetadataPreviewProps): React.JSX.Element;