@object-ui/app-shell 7.0.0 → 7.2.0

package/dist/views/metadata-admin/previews/simulator/flow-sim-validate.js

@@ -28,6 +28,63 @@ export function evalCondition(expr, variables) {
         return { result: false, error: err.message || 'Evaluation failed.' };
     }
 }
+/**
+ * Find a directed cycle in `edges` over `nodeIds`, returned as the node path
+ * that closes the loop (e.g. `['a','b','a']`), or `null` when the graph is a
+ * DAG. Iterative DFS with a recursion-stack colour map; the first cycle found
+ * wins (enough to report — the author fixes one at a time).
+ */
+export function findCycle(nodeIds, edges) {
+    const adj = new Map();
+    for (const id of nodeIds)
+        adj.set(id, []);
+    for (const e of edges) {
+        if (adj.has(e.source) && adj.has(e.target))
+            adj.get(e.source).push(e.target);
+    }
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map(nodeIds.map((id) => [id, WHITE]));
+    const stack = [];
+    const visit = (start) => {
+        // Explicit stack of {node, next-child-index} frames so a deep graph can't
+        // blow the JS call stack.
+        const frames = [{ id: start, i: 0 }];
+        color.set(start, GRAY);
+        stack.push(start);
+        while (frames.length) {
+            const frame = frames[frames.length - 1];
+            const children = adj.get(frame.id) ?? [];
+            if (frame.i < children.length) {
+                const next = children[frame.i++];
+                const c = color.get(next);
+                if (c === GRAY) {
+                    // Back into the active path → cycle. Slice from `next` to close it.
+                    const from = stack.indexOf(next);
+                    return [...stack.slice(from), next];
+                }
+                if (c === WHITE) {
+                    color.set(next, GRAY);
+                    stack.push(next);
+                    frames.push({ id: next, i: 0 });
+                }
+            }
+            else {
+                color.set(frame.id, BLACK);
+                stack.pop();
+                frames.pop();
+            }
+        }
+        return null;
+    };
+    for (const id of nodeIds) {
+        if (color.get(id) === WHITE) {
+            const cycle = visit(id);
+            if (cycle)
+                return cycle;
+        }
+    }
+    return null;
+}
 /** Static structural checks; `errors` block Run, `warnings` are advisory. */
 export function validateFlowDraft(nodes, edges) {
     const errors = [];
@@ -44,10 +101,12 @@ export function validateFlowDraft(nodes, edges) {
         idSet.add(id);
     }
     for (const e of edges) {
+        // Attach the endpoints so a dangling-edge error can badge the offending
+        // connection on the canvas (not just appear as a flow-level message).
         if (!idSet.has(e.source))
-            errors.push({ level: 'error', message: `Edge source "${e.source}" does not exist.` });
+            errors.push({ level: 'error', edge: { source: e.source, target: e.target }, message: `Edge source "${e.source}" does not exist.` });
         if (!idSet.has(e.target))
-            errors.push({ level: 'error', message: `Edge target "${e.target}" does not exist.` });
+            errors.push({ level: 'error', edge: { source: e.source, target: e.target }, message: `Edge target "${e.target}" does not exist.` });
     }
     // Entry resolution: prefer an explicit `start` node, else a node with no
     // incoming edge. Zero or many → the author must fix it before running.
@@ -109,5 +168,20 @@ export function validateFlowDraft(nodes, edges) {
             }
         }
     }
+    // DAG-modulo-back-edges (ADR-0044): the engine requires the flow graph MINUS
+    // declared back-edges to be acyclic. A declared revise loop (its closing edge
+    // marked `type: 'back'`) is excluded and passes; any *unmarked* cycle is an
+    // error — the author must opt in, edge by edge, exactly as `registerFlow`
+    // enforces server-side.
+    const forwardEdges = edges.filter((e) => e.type !== 'back');
+    const cycle = findCycle(ids.filter((id) => !!id), forwardEdges);
+    if (cycle) {
+        errors.push({
+            level: 'error',
+            nodeId: cycle[0],
+            cycle,
+            message: `Cycle detected (${cycle.join(' → ')}). Mark the connection that closes the loop as a back-edge (Connection type → Back-edge) to declare an intentional revise/rework loop.`,
+        });
+    }
     return { errors, warnings, startNodeId };
 }

package/dist/views/metadata-admin/previews/simulator/flow-simulator.d.ts

@@ -4,7 +4,8 @@
  *
  * Supported faithfully: start, decision (edge-first CEL routing), the CRUD /
  * get / http / connector / script(notification|code) side-effects (MOCKED), and
- * end. `wait` and `screen` PAUSE for manual continuation. `loop` resolves its
+ * end. `wait`, `screen`, and `approval` PAUSE for manual continuation (an approval
+ * resumes down the chosen decision's branch — approve / reject / revise). `loop` resolves its
  * collection and exposes the iterator but is a labelled single pass (the edge
  * model has no separate body/exit edge). `parallel_gateway` fans out WITHOUT
  * join synchronization; the ADR-0031 structured containers (`parallel`,
@@ -27,10 +28,38 @@ export declare class FlowSimulator {
     step(): SimStep | null;
     /** Run to completion (or until a pause / error). */
     runToEnd(): SimState;
-    /** Continue a flow paused on a `wait` / `screen` node. */
-    resume(screenOutputs?: Record<string, unknown>): void;
+    /**
+     * Continue a flow paused on a `wait`, `screen`, or `approval` node.
+     *  - `screenOutputs` — inputs captured from a paused screen.
+     *  - `decision` — the branch an approval resumes down (ADR-0019/0044:
+     *    `approve` / `reject` / `revise`). The run takes ONLY the out-edge whose
+     *    label matches, mirroring how the engine resumes a suspended approval by
+     *    branch label — instead of fanning out to every out-edge.
+     */
+    resume(opts?: {
+        screenOutputs?: Record<string, unknown>;
+        decision?: string;
+    }): void;
+    /**
+     * Resume a suspended approval down the chosen decision's out-edge: the one
+     * whose `label` equals `decision` (case-insensitive — `approve` / `reject` /
+     * `revise`). With no match (or no decision) it falls back to fanning out —
+     * mirroring the engine's unmatched-`branchLabel` fallback — and logs that so
+     * the author notices the unrouted decision.
+     */
+    private resumeApproval;
     private execute;
     private executeDecision;
+    /**
+     * assignment node — set flow variables. Normalizes the three authoring
+     * shapes the engine accepts (Studio's `{ assignments: { var: value } }`
+     * map, the example `{ assignments: [{ variable, value }] }` array, and the
+     * legacy flat `{ var: value }`) and interpolates `{var}` templates — so the
+     * Debug run mirrors runtime instead of silently no-oping.
+     */
+    private executeAssignment;
+    /** Resolve `{var}` templates in an assignment value against live variables. */
+    private interpolateValue;
     private executeLoop;
     /** Resolve a `{var}` template ref or a plain variable name from `variables`. */
     private resolveRef;

package/dist/views/metadata-admin/previews/simulator/flow-simulator.js

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 import { evalCondition, validateFlowDraft } from './flow-sim-validate';
 const MAX_STEPS = 500;
-const PASS_THROUGH = new Set(['start', 'assignment']);
+const PASS_THROUGH = new Set(['start']);
 const MOCKED_SIDE_EFFECT = new Set([
     'create_record',
     'update_record',
@@ -124,24 +124,58 @@ export class FlowSimulator {
         }
         return this.state;
     }
-    /** Continue a flow paused on a `wait` / `screen` node. */
-    resume(screenOutputs) {
+    /**
+     * Continue a flow paused on a `wait`, `screen`, or `approval` node.
+     *  - `screenOutputs` — inputs captured from a paused screen.
+     *  - `decision` — the branch an approval resumes down (ADR-0019/0044:
+     *    `approve` / `reject` / `revise`). The run takes ONLY the out-edge whose
+     *    label matches, mirroring how the engine resumes a suspended approval by
+     *    branch label — instead of fanning out to every out-edge.
+     */
+    resume(opts = {}) {
         const s = this.state;
         if (s.status !== 'paused' || !s.activeNodeId)
             return;
         const node = this.nodes.get(s.activeNodeId);
-        if (screenOutputs && node?.type === 'screen') {
-            Object.assign(s.variables, screenOutputs);
+        if (opts.screenOutputs && node?.type === 'screen') {
+            Object.assign(s.variables, opts.screenOutputs);
         }
         s.pausedReason = undefined;
         s.status = 'running';
-        if (node)
+        if (node?.type === 'approval')
+            this.resumeApproval(node, opts.decision);
+        else if (node)
             this.enqueueSuccessors(node);
         if (s.frontier.length === 0) {
             s.status = 'done';
             s.activeNodeId = null;
         }
     }
+    /**
+     * Resume a suspended approval down the chosen decision's out-edge: the one
+     * whose `label` equals `decision` (case-insensitive — `approve` / `reject` /
+     * `revise`). With no match (or no decision) it falls back to fanning out —
+     * mirroring the engine's unmatched-`branchLabel` fallback — and logs that so
+     * the author notices the unrouted decision.
+     */
+    resumeApproval(node, decision) {
+        const out = this.edges.map((e, i) => ({ e, i })).filter((x) => x.e.source === node.id);
+        const want = (decision ?? '').trim().toLowerCase();
+        const chosen = want ? out.find((x) => (x.e.label ?? '').trim().toLowerCase() === want) : undefined;
+        if (chosen) {
+            this.traverse(chosen.e, chosen.i);
+            this.record(node.id, 'approval', node.label, 'ok', { note: `Decision: ${decision} → ${chosen.e.target}` });
+        }
+        else {
+            for (const x of out)
+                this.traverse(x.e, x.i);
+            this.record(node.id, 'approval', node.label, 'ok', {
+                note: want
+                    ? `No out-edge labelled "${decision}"; took all branches (engine label-fallback).`
+                    : 'No decision supplied; took all branches.',
+            });
+        }
+    }
     // ---- node execution -----------------------------------------------------
     execute(node) {
         const type = node.type;
@@ -151,6 +185,8 @@ export class FlowSimulator {
         }
         if (type === 'decision')
             return this.executeDecision(node);
+        if (type === 'assignment')
+            return this.executeAssignment(node);
         if (UNSUPPORTED.has(type)) {
             this.enqueueSuccessors(node);
             return this.record(node.id, type, node.label, 'skipped', {
@@ -163,15 +199,34 @@ export class FlowSimulator {
                 note: 'Parallel split — branches fan out (no join synchronization is simulated).',
             });
         }
+        if (type === 'approval') {
+            // ADR-0019: an approval node opens a request and SUSPENDS the run until a
+            // decision is recorded. Model that as a pause; the author resumes down the
+            // chosen approve / reject / revise out-edge (see resumeApproval) rather
+            // than fanning out to every out-edge at once.
+            this.state.status = 'paused';
+            this.state.pausedReason = 'approval';
+            return this.record(node.id, type, node.label, 'paused', { note: 'Approval reached — choose a decision to continue.' });
+        }
         if (type === 'wait') {
             this.state.status = 'paused';
             this.state.pausedReason = 'wait';
             return this.record(node.id, type, node.label, 'paused', { note: 'Wait reached — continue manually.' });
         }
         if (type === 'screen') {
-            this.state.status = 'paused';
-            this.state.pausedReason = 'screen';
-            return this.record(node.id, type, node.label, 'paused', { note: 'Screen reached — provide inputs, then continue.' });
+            // Mirror the engine's `shouldPause`: a screen suspends only when it
+            // collects input (`fields`) or explicitly opts in (`waitForInput`).
+            // A field-less / `waitForInput:false` screen is a server pass-through.
+            const fields = Array.isArray(node.config?.fields) ? node.config.fields : [];
+            const waitForInput = node.config?.waitForInput;
+            const shouldPause = waitForInput === true || (fields.length > 0 && waitForInput !== false);
+            if (shouldPause) {
+                this.state.status = 'paused';
+                this.state.pausedReason = 'screen';
+                return this.record(node.id, type, node.label, 'paused', { note: 'Screen reached — provide inputs, then continue.' });
+            }
+            this.enqueueSuccessors(node);
+            return this.record(node.id, type, node.label, 'ok', { note: 'Screen has no input — passed through (matches runtime).' });
         }
         if (type === 'loop') {
             const step = this.executeLoop(node);
@@ -233,6 +288,61 @@ export class FlowSimulator {
             note: multiMatch ? 'Multiple conditions matched; the first declared branch was taken.' : undefined,
         });
     }
+    /**
+     * assignment node — set flow variables. Normalizes the three authoring
+     * shapes the engine accepts (Studio's `{ assignments: { var: value } }`
+     * map, the example `{ assignments: [{ variable, value }] }` array, and the
+     * legacy flat `{ var: value }`) and interpolates `{var}` templates — so the
+     * Debug run mirrors runtime instead of silently no-oping.
+     */
+    executeAssignment(node) {
+        const cfg = node.config ?? {};
+        const raw = cfg.assignments;
+        const pairs = [];
+        if (Array.isArray(raw)) {
+            for (const item of raw) {
+                if (item && typeof item === 'object') {
+                    const e = item;
+                    const name = e.variable ?? e.name ?? e.key;
+                    if (typeof name === 'string' && name)
+                        pairs.push([name, e.value]);
+                }
+            }
+        }
+        else if (raw && typeof raw === 'object') {
+            for (const [k, v] of Object.entries(raw))
+                pairs.push([k, v]);
+        }
+        else {
+            for (const [k, v] of Object.entries(cfg))
+                pairs.push([k, v]);
+        }
+        const wrote = {};
+        for (const [key, value] of pairs) {
+            const resolved = this.interpolateValue(value);
+            this.state.variables[key] = resolved;
+            wrote[key] = resolved;
+        }
+        this.enqueueSuccessors(node);
+        return this.record(node.id, 'assignment', node.label, 'ok', {
+            wrote: Object.keys(wrote).length ? wrote : undefined,
+            note: Object.keys(wrote).length ? undefined : 'No assignments defined.',
+        });
+    }
+    /** Resolve `{var}` templates in an assignment value against live variables. */
+    interpolateValue(value) {
+        if (typeof value !== 'string')
+            return value;
+        const whole = value.match(/^\{([^}]+)\}$/);
+        if (whole) {
+            const v = this.state.variables[whole[1].trim()];
+            return v !== undefined ? v : value;
+        }
+        return value.replace(/\{([^}]+)\}/g, (_m, k) => {
+            const v = this.state.variables[String(k).trim()];
+            return v === undefined || v === null ? '' : String(v);
+        });
+    }
     executeLoop(node) {
         const ref = str(node.config?.collection);
         const iterVar = str(node.config?.iteratorVariable);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/app-shell",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "type": "module",
   "license": "MIT",
   "description": "Minimal application shell for ObjectUI - framework-agnostic rendering engine",
@@ -33,36 +33,36 @@
     "qrcode": "^1.5.4",
     "sonner": "^2.0.7",
     "zod": "^4.4.3",
-    "@object-ui/auth": "7.0.0",
-    "@object-ui/collaboration": "7.0.0",
-    "@object-ui/components": "7.0.0",
-    "@object-ui/core": "7.0.0",
-    "@object-ui/data-objectstack": "7.0.0",
-    "@object-ui/fields": "7.0.0",
-    "@object-ui/i18n": "7.0.0",
-    "@object-ui/layout": "7.0.0",
-    "@object-ui/permissions": "7.0.0",
-    "@object-ui/plugin-editor": "7.0.0",
-    "@object-ui/providers": "7.0.0",
-    "@object-ui/react": "7.0.0",
-    "@object-ui/types": "7.0.0"
+    "@object-ui/auth": "7.2.0",
+    "@object-ui/collaboration": "7.2.0",
+    "@object-ui/components": "7.2.0",
+    "@object-ui/core": "7.2.0",
+    "@object-ui/data-objectstack": "7.2.0",
+    "@object-ui/fields": "7.2.0",
+    "@object-ui/i18n": "7.2.0",
+    "@object-ui/layout": "7.2.0",
+    "@object-ui/permissions": "7.2.0",
+    "@object-ui/plugin-editor": "7.2.0",
+    "@object-ui/providers": "7.2.0",
+    "@object-ui/react": "7.2.0",
+    "@object-ui/types": "7.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0",
-    "@object-ui/plugin-calendar": "^7.0.0",
-    "@object-ui/plugin-charts": "^7.0.0",
-    "@object-ui/plugin-chatbot": "^7.0.0",
-    "@object-ui/plugin-dashboard": "^7.0.0",
-    "@object-ui/plugin-designer": "^7.0.0",
-    "@object-ui/plugin-detail": "^7.0.0",
-    "@object-ui/plugin-form": "^7.0.0",
-    "@object-ui/plugin-grid": "^7.0.0",
-    "@object-ui/plugin-kanban": "^7.0.0",
-    "@object-ui/plugin-list": "^7.0.0",
-    "@object-ui/plugin-report": "^7.0.0",
-    "@object-ui/plugin-view": "^7.0.0"
+    "@object-ui/plugin-calendar": "^7.2.0",
+    "@object-ui/plugin-charts": "^7.2.0",
+    "@object-ui/plugin-chatbot": "^7.2.0",
+    "@object-ui/plugin-dashboard": "^7.2.0",
+    "@object-ui/plugin-designer": "^7.2.0",
+    "@object-ui/plugin-detail": "^7.2.0",
+    "@object-ui/plugin-form": "^7.2.0",
+    "@object-ui/plugin-grid": "^7.2.0",
+    "@object-ui/plugin-kanban": "^7.2.0",
+    "@object-ui/plugin-list": "^7.2.0",
+    "@object-ui/plugin-report": "^7.2.0",
+    "@object-ui/plugin-view": "^7.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
@@ -75,18 +75,18 @@
     "sonner": "^2.0.7",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",
-    "@object-ui/plugin-calendar": "7.0.0",
-    "@object-ui/plugin-charts": "7.0.0",
-    "@object-ui/plugin-chatbot": "7.0.0",
-    "@object-ui/plugin-dashboard": "7.0.0",
-    "@object-ui/plugin-designer": "7.0.0",
-    "@object-ui/plugin-detail": "7.0.0",
-    "@object-ui/plugin-form": "7.0.0",
-    "@object-ui/plugin-grid": "7.0.0",
-    "@object-ui/plugin-kanban": "7.0.0",
-    "@object-ui/plugin-list": "7.0.0",
-    "@object-ui/plugin-report": "7.0.0",
-    "@object-ui/plugin-view": "7.0.0"
+    "@object-ui/plugin-calendar": "7.2.0",
+    "@object-ui/plugin-charts": "7.2.0",
+    "@object-ui/plugin-chatbot": "7.2.0",
+    "@object-ui/plugin-dashboard": "7.2.0",
+    "@object-ui/plugin-designer": "7.2.0",
+    "@object-ui/plugin-detail": "7.2.0",
+    "@object-ui/plugin-form": "7.2.0",
+    "@object-ui/plugin-grid": "7.2.0",
+    "@object-ui/plugin-kanban": "7.2.0",
+    "@object-ui/plugin-list": "7.2.0",
+    "@object-ui/plugin-report": "7.2.0",
+    "@object-ui/plugin-view": "7.2.0"
   },
   "keywords": [
     "objectui",