@object-ui/app-shell 7.0.0 → 7.2.0

package/dist/views/metadata-admin/previews/flow-expr-problems.js

@@ -0,0 +1,97 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * flow-expr-problems — pure, client-side detection of EXPRESSION issues across a
+ * whole flow draft, for surfacing in the Problems panel + canvas badges (#1934).
+ *
+ * Two kinds, mirroring the inline inspector checks but aggregated per node/edge:
+ *   • ADR-0032 brace / shape ERRORS on every CEL field (decision conditions +
+ *     branch expressions, screen `visibleWhen`, loop collection, edge guards…).
+ *     Deterministic, scope-free → zero false positives.
+ *   • Scope-aware "unknown reference" WARNINGS — a bare root not in scope at the
+ *     node. The START node is skipped: its entry condition legitimately uses the
+ *     trigger record's fields *bare* (`status`), which can't be told apart from a
+ *     typo without the object schema (an async fetch this pure pass avoids); the
+ *     inline inspector check, which does fetch, still covers it.
+ *
+ * Only CEL (`expression`) surfaces are scanned — template (`{var}`) values use
+ * single braces legally and are left to the inline check.
+ */
+import { fieldsForNodeType, getFieldValue } from '../inspectors/flow-node-config';
+import { resolveFlowScope } from '../inspectors/flow-scope';
+import { scopeRoots, findUnknownRefs, describeUnknownRefs } from '../inspectors/flow-ref-check';
+import { validateExpressionClient } from '../inspectors/expression-validate';
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function asRecord(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function str(v) {
+    return typeof v === 'string' && v ? v : undefined;
+}
+/** Brace error (error) else unknown-ref (warning, when `roots` given) for one CEL value. */
+function checkCel(value, roots) {
+    const issue = validateExpressionClient('predicate', value);
+    if (issue)
+        return { level: 'error', message: issue.message };
+    if (roots && roots.size > 0) {
+        const unknown = findUnknownRefs(value, 'predicate', roots);
+        if (unknown.length > 0)
+            return { level: 'warning', message: describeUnknownRefs(unknown) };
+    }
+    return null;
+}
+/**
+ * Scan a flow draft for expression problems, resolved onto node / edge targets.
+ * Pure: no network — the trigger object's fields are not expanded (root-only
+ * scope), which is why the start node is excluded from the ref check.
+ */
+export function flowExpressionProblems(draft) {
+    const nodes = asArray(draft.nodes).map(asRecord);
+    const edges = asArray(draft.edges).map(asRecord);
+    const startId = str(nodes.find((n) => str(n.type) === 'start')?.id);
+    const out = [];
+    for (const node of nodes) {
+        const nodeId = str(node.id);
+        const type = str(node.type);
+        if (!nodeId || !type)
+            continue;
+        // Root-only scope at this node; skip the ref check on the start node (its
+        // bare trigger-record fields are indistinguishable from typos here).
+        const roots = nodeId === startId ? null : scopeRoots(resolveFlowScope(draft, nodeId).refs);
+        for (const field of fieldsForNodeType(type)) {
+            if (field.kind === 'expression') {
+                const hit = checkCel(getFieldValue(node, field), roots);
+                if (hit)
+                    out.push({ target: { kind: 'node', nodeId }, level: hit.level, message: hit.message });
+            }
+            else if (field.kind === 'objectList' && field.columns) {
+                const exprCols = field.columns.filter((c) => c.kind === 'expression');
+                if (exprCols.length === 0)
+                    continue;
+                for (const row of asArray(getFieldValue(node, field))) {
+                    const r = asRecord(row);
+                    const rowLabel = str(r.label);
+                    for (const col of exprCols) {
+                        const hit = checkCel(r[col.key], roots);
+                        if (hit) {
+                            const prefix = rowLabel || col.label;
+                            out.push({ target: { kind: 'node', nodeId }, level: hit.level, message: prefix ? `${prefix}: ${hit.message}` : hit.message });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    for (const edge of edges) {
+        const source = str(edge.source);
+        const target = str(edge.target);
+        if (!source || !target || edge.isDefault === true)
+            continue;
+        const roots = source === startId ? null : scopeRoots(resolveFlowScope(draft, source).refs);
+        const hit = checkCel(edge.condition, roots);
+        if (hit)
+            out.push({ target: { kind: 'edge', source, target }, level: hit.level, message: hit.message });
+    }
+    return out;
+}

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

@@ -0,0 +1,84 @@
+import type { DiagnosticLevel } from './simulator/flow-sim-types';
+import { type FlowEdge, type FlowNode } from './flow-canvas-layout';
+/** What a problem points at on the canvas — drives badge placement + reveal. */
+export type FlowProblemTarget = {
+    kind: 'node';
+    nodeId: string;
+} | {
+    kind: 'edge';
+    edgeKey: string;
+    source: string;
+    target: string;
+} | {
+    kind: 'flow';
+};
+/** Origin of a problem — labels the panel row and lets the UI group counts. */
+export type FlowProblemSource = 'structural' | 'server' | 'expression';
+/** One actionable issue, resolved onto a concrete canvas element. */
+export interface FlowProblem {
+    /** Stable-enough key for React lists. */
+    id: string;
+    level: DiagnosticLevel;
+    message: string;
+    target: FlowProblemTarget;
+    source: FlowProblemSource;
+    /**
+     * Extra elements to flag with the red error ring/stroke beyond `target` —
+     * e.g. every hop of a cycle. The badge + click-reveal still use `target`.
+     */
+    highlight?: {
+        nodeIds: string[];
+        edges: Array<{
+            source: string;
+            target: string;
+        }>;
+    };
+}
+/** A server diagnostic entry (subset of the layered record's `_diagnostics`). */
+export interface ServerDiagnostic {
+    /** Dotted (or array) JSON path, e.g. `nodes.2.config.objectName`. */
+    path?: string | Array<string | number>;
+    message: string;
+    /** Defaults to `'error'`. */
+    severity?: DiagnosticLevel;
+}
+/** Stable `source->target` key matching an edge problem to a rendered edge. */
+export declare function edgeProblemKey(source: string, target: string): string;
+export interface BuildFlowProblemsArgs {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    /** Server `_diagnostics`, flattened to a severity-tagged, path-keyed list. */
+    serverDiagnostics?: ServerDiagnostic[];
+    /** Declared flow variables — needed to resolve scope for the expression check. */
+    variables?: unknown[];
+}
+/**
+ * Build the unified problem list from structural validation + server
+ * diagnostics. Errors are listed before warnings; within a level each source
+ * keeps its own emit order (structural before server).
+ */
+export declare function buildFlowProblems({ nodes, edges, serverDiagnostics, variables }: BuildFlowProblemsArgs): FlowProblem[];
+/** A folded badge for one canvas element (errors dominate warnings). */
+export interface ProblemBadge {
+    level: DiagnosticLevel;
+    /** Tooltip text — each problem message on its own line. */
+    title: string;
+    count: number;
+}
+export interface ProblemIndex {
+    byNode: Map<string, ProblemBadge>;
+    byEdge: Map<string, ProblemBadge>;
+}
+/** Group problems into per-node / per-edge badges for the canvas overlay. */
+export declare function indexProblemBadges(problems: FlowProblem[]): ProblemIndex;
+/**
+ * Error elements to paint with the red ring/stroke, derived from the unified
+ * problem list. ERRORS ONLY — warnings get an amber badge but no ring. Includes
+ * each error's `highlight` set, so a cycle paints its whole loop (every hop node
+ * + edge) red while its badge still sits on the closing edge. Lets the preview
+ * derive the red sets from `problems` instead of a second validateFlowDraft pass.
+ */
+export declare function deriveInvalidElements(problems: FlowProblem[]): {
+    invalidNodeIds: string[];
+    invalidEdges: Set<string>;
+};

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

@@ -0,0 +1,209 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * flow-problems — unify the two flow-validation sources into one flat,
+ * per-element issue list that the canvas badges and the Problems panel both
+ * render.
+ *
+ *   1. `validateFlowDraft` (client, structural): no resolvable entry,
+ *      unreachable nodes, a decision with no default branch, duplicate node
+ *      ids, dangling edges, un-declared cycles.
+ *   2. The server `_diagnostics` already attached to the layered record
+ *      (schema validation), each keyed by a dotted JSON path.
+ *
+ * "Surfacing, not detection": detection already exists. This module only maps
+ * each detected issue onto a concrete canvas element — a node id or a stable
+ * edge key — so a badge can sit on the offending element and a Problems-panel
+ * row can select + reveal it. Flow-level issues (no specific element) are kept
+ * too: listed in the panel, but without a badge.
+ */
+import { validateFlowDraft } from './simulator/flow-sim-validate';
+import { edgeKey } from './flow-canvas-layout';
+import { flowExpressionProblems } from './flow-expr-problems';
+/** Stable `source->target` key matching an edge problem to a rendered edge. */
+export function edgeProblemKey(source, target) {
+    return `${source}->${target}`;
+}
+/** Resolve an edge's selection key (`edgeKey`) from its endpoints. */
+function resolveEdgeKey(edges, source, target) {
+    const idx = edges.findIndex((e) => e.source === source && e.target === target);
+    return idx >= 0 ? edgeKey(edges[idx], idx) : `${source}->${target}#-1`;
+}
+/** Normalize a dotted/array JSON path to segments (numbers stay numeric). */
+function pathSegments(path) {
+    if (Array.isArray(path))
+        return path;
+    if (typeof path !== 'string' || !path)
+        return [];
+    return path.split('.').map((seg) => {
+        const n = Number(seg);
+        return Number.isInteger(n) && String(n) === seg ? n : seg;
+    });
+}
+/**
+ * Map a structural diagnostic's optional anchors (`edge`, `cycle`, `nodeId`)
+ * onto a badge target. A cycle points its badge at the *closing* hop — the edge
+ * the author marks as a back-edge to resolve it — but flags EVERY hop (nodes +
+ * edges) for the red error highlight so the whole loop reads as the problem.
+ */
+function structuralMapping(diag, edges) {
+    if (diag.edge) {
+        const { source, target } = diag.edge;
+        return { target: { kind: 'edge', source, target, edgeKey: resolveEdgeKey(edges, source, target) } };
+    }
+    if (diag.cycle && diag.cycle.length >= 2) {
+        const c = diag.cycle;
+        const source = c[c.length - 2];
+        const target = c[c.length - 1];
+        const nodeIds = [];
+        const hops = [];
+        for (let i = 0; i < c.length - 1; i++) {
+            nodeIds.push(c[i]);
+            hops.push({ source: c[i], target: c[i + 1] });
+        }
+        return {
+            target: { kind: 'edge', source, target, edgeKey: resolveEdgeKey(edges, source, target) },
+            highlight: { nodeIds, edges: hops },
+        };
+    }
+    if (diag.nodeId)
+        return { target: { kind: 'node', nodeId: diag.nodeId } };
+    return { target: { kind: 'flow' } };
+}
+/** Map a server diagnostic's JSON path onto a node/edge/flow target. */
+function serverTarget(path, nodes, edges) {
+    const segs = pathSegments(path);
+    if (segs.length >= 2 && typeof segs[1] === 'number') {
+        const idx = segs[1];
+        if (segs[0] === 'nodes' && nodes[idx]?.id)
+            return { kind: 'node', nodeId: nodes[idx].id };
+        if (segs[0] === 'edges' && edges[idx]) {
+            const e = edges[idx];
+            return { kind: 'edge', source: e.source, target: e.target, edgeKey: edgeKey(e, idx) };
+        }
+    }
+    return { kind: 'flow' };
+}
+/** Short stable token for a target, used in a problem's React key. */
+function targetKey(t) {
+    if (t.kind === 'node')
+        return `n:${t.nodeId}`;
+    if (t.kind === 'edge')
+        return `e:${t.source}->${t.target}`;
+    return 'flow';
+}
+/**
+ * Build the unified problem list from structural validation + server
+ * diagnostics. Errors are listed before warnings; within a level each source
+ * keeps its own emit order (structural before server).
+ */
+export function buildFlowProblems({ nodes, edges, serverDiagnostics, variables }) {
+    const problems = [];
+    const v = validateFlowDraft(nodes, edges);
+    const pushStructural = (level, list) => {
+        list.forEach((diag, i) => {
+            const { target, highlight } = structuralMapping(diag, edges);
+            problems.push({
+                id: `structural:${level}:${i}:${targetKey(target)}`,
+                level,
+                message: diag.message,
+                target,
+                source: 'structural',
+                ...(highlight ? { highlight } : {}),
+            });
+        });
+    };
+    pushStructural('error', v.errors);
+    pushStructural('warning', v.warnings);
+    (serverDiagnostics ?? []).forEach((diag, i) => {
+        const level = diag.severity === 'warning' ? 'warning' : 'error';
+        const target = serverTarget(diag.path, nodes, edges);
+        problems.push({
+            id: `server:${i}:${targetKey(target)}`,
+            level,
+            message: diag.message,
+            target,
+            source: 'server',
+        });
+    });
+    // Client-side EXPRESSION issues (ADR-0032 braces + scope-aware unknown refs),
+    // resolved onto node / edge targets — see flow-expr-problems.
+    flowExpressionProblems({ nodes, edges, variables: variables ?? [] }).forEach((ep, i) => {
+        const target = ep.target.kind === 'edge'
+            ? {
+                kind: 'edge',
+                source: ep.target.source,
+                target: ep.target.target,
+                edgeKey: resolveEdgeKey(edges, ep.target.source, ep.target.target),
+            }
+            : { kind: 'node', nodeId: ep.target.nodeId };
+        problems.push({
+            id: `expression:${ep.level}:${i}:${targetKey(target)}`,
+            level: ep.level,
+            message: ep.message,
+            target,
+            source: 'expression',
+        });
+    });
+    // Errors first so the panel + counts lead with blockers (stable within level).
+    return problems
+        .map((p, i) => [p, i])
+        .sort((a, b) => {
+        if (a[0].level !== b[0].level)
+            return a[0].level === 'error' ? -1 : 1;
+        return a[1] - b[1];
+    })
+        .map(([p]) => p);
+}
+function foldBadge(list) {
+    const level = list.some((p) => p.level === 'error') ? 'error' : 'warning';
+    return { level, title: list.map((p) => p.message).join('\n'), count: list.length };
+}
+/** Group problems into per-node / per-edge badges for the canvas overlay. */
+export function indexProblemBadges(problems) {
+    const nodeLists = new Map();
+    const edgeLists = new Map();
+    for (const p of problems) {
+        if (p.target.kind === 'node') {
+            const l = nodeLists.get(p.target.nodeId) ?? [];
+            l.push(p);
+            nodeLists.set(p.target.nodeId, l);
+        }
+        else if (p.target.kind === 'edge') {
+            const k = edgeProblemKey(p.target.source, p.target.target);
+            const l = edgeLists.get(k) ?? [];
+            l.push(p);
+            edgeLists.set(k, l);
+        }
+    }
+    const byNode = new Map();
+    for (const [id, list] of nodeLists)
+        byNode.set(id, foldBadge(list));
+    const byEdge = new Map();
+    for (const [k, list] of edgeLists)
+        byEdge.set(k, foldBadge(list));
+    return { byNode, byEdge };
+}
+/**
+ * Error elements to paint with the red ring/stroke, derived from the unified
+ * problem list. ERRORS ONLY — warnings get an amber badge but no ring. Includes
+ * each error's `highlight` set, so a cycle paints its whole loop (every hop node
+ * + edge) red while its badge still sits on the closing edge. Lets the preview
+ * derive the red sets from `problems` instead of a second validateFlowDraft pass.
+ */
+export function deriveInvalidElements(problems) {
+    const nodeSet = new Set();
+    const edgeSet = new Set();
+    for (const p of problems) {
+        if (p.level !== 'error')
+            continue;
+        if (p.target.kind === 'node')
+            nodeSet.add(p.target.nodeId);
+        else if (p.target.kind === 'edge')
+            edgeSet.add(edgeProblemKey(p.target.source, p.target.target));
+        for (const id of p.highlight?.nodeIds ?? [])
+            nodeSet.add(id);
+        for (const e of p.highlight?.edges ?? [])
+            edgeSet.add(edgeProblemKey(e.source, e.target));
+    }
+    return { invalidNodeIds: [...nodeSet], invalidEdges: edgeSet };
+}

package/dist/views/metadata-admin/previews/object-fields-io.d.ts

@@ -35,6 +35,27 @@ export declare function newField(name: string, type: FieldTypeId, label?: string
 export declare function toLabel(name: string): string;
 /** Normalize an arbitrary string into a valid snake_case field name. */
 export declare function toFieldName(raw: string): string;
+/**
+ * Prefix-stable variant of {@link toFieldName} for *live keystroke* input.
+ *
+ * The strict `toFieldName` trims a trailing `_`, which makes it impossible
+ * to TYPE a multi-word identifier into a controlled input: the field's
+ * `onChange` re-normalizes on every keystroke, so the instant the user
+ * presses `_` the value is `"repair_"` -> trimmed to `"repair"` -> the
+ * underscore vanishes before the next letter arrives, yielding
+ * `"repairticket"` instead of `"repair_ticket"`. (Authors of non-Latin
+ * locales hit this hardest: their label cannot derive a Latin slug, so
+ * they MUST type the identifier by hand.)
+ *
+ * This variant keeps a single trailing `_` so typing can continue, and
+ * returns `''` (not the `'field'` placeholder) on empty input so clearing
+ * the box actually clears it. A trailing `_` is itself a valid identifier
+ * per the spec ("starts with a letter, may contain letters/digits/`_`"),
+ * so no separate commit-time trim is required for correctness; callers
+ * that need a canonical form for a *complete* string (label->name
+ * derivation, group keys) should keep using strict `toFieldName`.
+ */
+export declare function toFieldNameLoose(raw: string): string;
 /**
  * A declared field group (a.k.a. "section"). Lives at the object's
  * top level as `draft.fieldGroups`; individual fields opt into a group

package/dist/views/metadata-admin/previews/object-fields-io.js

@@ -38,9 +38,11 @@ export function indexOfField(view, name) {
 /** Build a fresh field definition for the given type. */
 export function newField(name, type, label) {
     const def = { type, label: label ?? toLabel(name) };
-    // Seed a single empty option so picklist editor renders a row to fill in.
+    // Picklist-style fields start with no options; the OptionsEditor shows a
+    // blank input row locally and only persists rows once they have a value, so
+    // an unfilled row never trips the spec's identifier validation.
     if (type === 'select' || type === 'multiselect' || type === 'radio' || type === 'checkboxes') {
-        def.options = [{ value: '', label: '' }];
+        def.options = [];
     }
     return { name, def };
 }
@@ -67,6 +69,39 @@ export function toFieldName(raw) {
         return `f_${sanitized}`;
     return sanitized;
 }
+/**
+ * Prefix-stable variant of {@link toFieldName} for *live keystroke* input.
+ *
+ * The strict `toFieldName` trims a trailing `_`, which makes it impossible
+ * to TYPE a multi-word identifier into a controlled input: the field's
+ * `onChange` re-normalizes on every keystroke, so the instant the user
+ * presses `_` the value is `"repair_"` -> trimmed to `"repair"` -> the
+ * underscore vanishes before the next letter arrives, yielding
+ * `"repairticket"` instead of `"repair_ticket"`. (Authors of non-Latin
+ * locales hit this hardest: their label cannot derive a Latin slug, so
+ * they MUST type the identifier by hand.)
+ *
+ * This variant keeps a single trailing `_` so typing can continue, and
+ * returns `''` (not the `'field'` placeholder) on empty input so clearing
+ * the box actually clears it. A trailing `_` is itself a valid identifier
+ * per the spec ("starts with a letter, may contain letters/digits/`_`"),
+ * so no separate commit-time trim is required for correctness; callers
+ * that need a canonical form for a *complete* string (label->name
+ * derivation, group keys) should keep using strict `toFieldName`.
+ */
+export function toFieldNameLoose(raw) {
+    const sanitized = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+/g, '') // trim leading only -- a trailing `_` must survive
+        .replace(/_{2,}/g, '_');
+    if (!sanitized)
+        return '';
+    if (!/^[a-z_]/.test(sanitized))
+        return `f_${sanitized}`;
+    return sanitized;
+}
 /** Read `draft.fieldGroups` into a normalized, well-typed list. */
 export function readGroups(fieldGroupsInput) {
     if (!Array.isArray(fieldGroupsInput))

package/dist/views/metadata-admin/previews/screen-spec.d.ts

@@ -0,0 +1,43 @@
+/**
+ * screen-spec — pure helpers that map a flow `screen` node's authored `config`
+ * onto the runtime `ScreenSpec` (the contract {@link ScreenView} renders), plus
+ * `{var}` interpolation for the title/description and `visibleWhen` field
+ * gating. Kept framework-free so {@link ScreenPreview} stays a thin component
+ * and these stay unit-testable.
+ */
+import type { ScreenSpec } from '../../ScreenView';
+/** Minimal node shape the preview needs (id + authored config). */
+export interface ScreenPreviewNode {
+    id: string;
+    label?: string;
+    config?: Record<string, unknown>;
+}
+/**
+ * Interpolate `{var}` references, mirroring the simulator's `{var}` syntax
+ * (flow-simulator.ts). Known vars are substituted; unknown refs stay literal so
+ * the author still sees the dependency in the design preview.
+ */
+export declare function interpolate(text: string | undefined, vars: Record<string, unknown> | undefined): string;
+/**
+ * A field's `visibleWhen` gate, evaluated against the current variables using
+ * the SAME evaluator the simulator uses for edge conditions (so the preview
+ * agrees with the simulator). Real metadata mixes `{var}` and bare-var styles
+ * (e.g. `{createOpportunity} == true`, `stage == "review"`), so brace
+ * placeholders are normalised to bare identifiers first.
+ *
+ * Fail-OPEN: a missing condition, an unparseable one, or one that references a
+ * not-yet-set variable (the inspector has no run state) keeps the field
+ * visible — the design preview never hides a configured field just because it
+ * lacks the data to decide. With live run state (the simulator) it gates
+ * faithfully: `createOpportunity == false` hides the field.
+ */
+export declare function isFieldVisibleWhen(visibleWhen: unknown, variables: Record<string, unknown> | undefined): boolean;
+/** Count of authored field rows hidden by their `visibleWhen` against `variables`. */
+export declare function hiddenFieldCount(node: ScreenPreviewNode, variables: Record<string, unknown> | undefined): number;
+/**
+ * Map a screen node's authored `config` onto the runtime `ScreenSpec` — the
+ * same keys the engine's `screen` executor reads (title / description / fields
+ * / objectName / mode / defaults / idVariable). `fields` are gated by their
+ * `visibleWhen` against `variables` (omit `variables` to keep every field).
+ */
+export declare function buildScreenSpec(node: ScreenPreviewNode, variables?: Record<string, unknown>): ScreenSpec;

package/dist/views/metadata-admin/previews/screen-spec.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { evalCondition } from './simulator/flow-sim-validate';
+/**
+ * Interpolate `{var}` references, mirroring the simulator's `{var}` syntax
+ * (flow-simulator.ts). Known vars are substituted; unknown refs stay literal so
+ * the author still sees the dependency in the design preview.
+ */
+export function interpolate(text, vars) {
+    if (!text)
+        return '';
+    if (!vars)
+        return text;
+    return text.replace(/\{([^{}]+)\}/g, (m, k) => {
+        const v = vars[String(k).trim()];
+        return v === undefined || v === null ? m : String(v);
+    });
+}
+/**
+ * A field's `visibleWhen` gate, evaluated against the current variables using
+ * the SAME evaluator the simulator uses for edge conditions (so the preview
+ * agrees with the simulator). Real metadata mixes `{var}` and bare-var styles
+ * (e.g. `{createOpportunity} == true`, `stage == "review"`), so brace
+ * placeholders are normalised to bare identifiers first.
+ *
+ * Fail-OPEN: a missing condition, an unparseable one, or one that references a
+ * not-yet-set variable (the inspector has no run state) keeps the field
+ * visible — the design preview never hides a configured field just because it
+ * lacks the data to decide. With live run state (the simulator) it gates
+ * faithfully: `createOpportunity == false` hides the field.
+ */
+export function isFieldVisibleWhen(visibleWhen, variables) {
+    if (typeof visibleWhen !== 'string' || !visibleWhen.trim())
+        return true;
+    if (!variables)
+        return true;
+    const normalized = visibleWhen.replace(/\{([\w.]+)\}/g, '$1');
+    const { result, error } = evalCondition(normalized, variables);
+    return error ? true : result;
+}
+/**
+ * Coerce the authored `config.fields` rows into runtime `ScreenFieldSpec`s,
+ * dropping any whose `visibleWhen` evaluates false against `variables` — exactly
+ * what the runtime `screen` executor emits (it filters server-side before
+ * sending the ScreenSpec).
+ */
+function toScreenFields(raw, variables) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const f of raw) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const row = f;
+        if (typeof row.name !== 'string' || !row.name)
+            continue;
+        if (!isFieldVisibleWhen(row.visibleWhen, variables))
+            continue;
+        out.push({
+            name: row.name,
+            label: typeof row.label === 'string' ? row.label : undefined,
+            type: typeof row.type === 'string' ? row.type : undefined,
+            required: row.required === true,
+        });
+    }
+    return out;
+}
+/** Count of authored field rows hidden by their `visibleWhen` against `variables`. */
+export function hiddenFieldCount(node, variables) {
+    const raw = node.config?.fields;
+    if (!Array.isArray(raw))
+        return 0;
+    let hidden = 0;
+    for (const f of raw) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const row = f;
+        if (typeof row.name !== 'string' || !row.name)
+            continue;
+        if (!isFieldVisibleWhen(row.visibleWhen, variables))
+            hidden++;
+    }
+    return hidden;
+}
+/**
+ * Map a screen node's authored `config` onto the runtime `ScreenSpec` — the
+ * same keys the engine's `screen` executor reads (title / description / fields
+ * / objectName / mode / defaults / idVariable). `fields` are gated by their
+ * `visibleWhen` against `variables` (omit `variables` to keep every field).
+ */
+export function buildScreenSpec(node, variables) {
+    const c = (node.config && typeof node.config === 'object' ? node.config : {});
+    const objectName = typeof c.objectName === 'string' && c.objectName ? c.objectName : undefined;
+    const mode = c.mode === 'edit' ? 'edit' : c.mode === 'create' ? 'create' : undefined;
+    const defaults = c.defaults && typeof c.defaults === 'object' && !Array.isArray(c.defaults)
+        ? c.defaults
+        : undefined;
+    return {
+        nodeId: node.id,
+        title: typeof c.title === 'string' ? c.title : undefined,
+        description: typeof c.description === 'string' ? c.description : undefined,
+        fields: toScreenFields(c.fields, variables),
+        kind: objectName ? 'object-form' : 'fields',
+        objectName,
+        mode,
+        defaults,
+        idVariable: typeof c.idVariable === 'string' ? c.idVariable : undefined,
+    };
+}

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

@@ -28,6 +28,12 @@ export interface SimEdge {
     };
     isDefault?: boolean;
     label?: string;
+    /**
+     * Connection type (FlowEdgeSchema). A `'back'` edge is an ADR-0044 declared
+     * back-edge: traversed normally at run time, but excluded from DAG cycle
+     * validation so a revise/rework loop can re-enter an earlier node.
+     */
+    type?: string;
 }
 export type SimStatus = 'idle' | 'running' | 'paused' | 'done' | 'error';
 /** One evaluated outgoing edge of a decision (kept for the debug timeline). */
@@ -74,8 +80,22 @@ export interface SimState {
 export type DiagnosticLevel = 'error' | 'warning';
 export interface Diagnostic {
     level: DiagnosticLevel;
+    /** The node this diagnostic points at (for an inline badge + click-to-reveal). */
     nodeId?: string;
+    /**
+     * The edge this diagnostic points at (e.g. a dangling endpoint). Carries the
+     * endpoints so the designer can key the inline badge by `source->target`.
+     */
+    edge?: {
+        source: string;
+        target: string;
+    };
     message: string;
+    /**
+     * For a cycle error: the node path that closes the loop (e.g. `['a','b','a']`),
+     * so the designer can paint the offending edges/nodes inline on the canvas.
+     */
+    cycle?: string[];
 }
 export interface FlowValidation {
     errors: Diagnostic[];

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

@@ -4,5 +4,12 @@ export declare function evalCondition(expr: string, variables: Record<string, un
     result: boolean;
     error?: string;
 };
+/**
+ * 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 declare function findCycle(nodeIds: string[], edges: SimEdge[]): string[] | null;
 /** Static structural checks; `errors` block Run, `warnings` are advisory. */
 export declare function validateFlowDraft(nodes: SimNode[], edges: SimEdge[]): FlowValidation;