@object-ui/app-shell 7.0.0 → 7.2.0

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

@@ -9,7 +9,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * threaded in: previews run in a sandbox with no params context.
  */
 import * as React from 'react';
-import { SchemaRenderer } from '@object-ui/react';
+import { SchemaRenderer, RecordContextProvider } from '@object-ui/react';
+import { buildExpandFields } from '@object-ui/core';
+import { buildDefaultPageSchema } from '@object-ui/plugin-detail';
 import { PreviewShell, PreviewErrorBoundary, PreviewMessage } from './PreviewShell';
 import { OutlineStrip } from './OutlineStrip';
 import { PageBlockCanvas } from './PageBlockCanvas';
@@ -88,6 +90,113 @@ export function PagePreview({ draft, editing, selection, onSelectionChange, onPa
         onPatch({ children: next });
         onSelectionChange?.({ kind: 'block', id: `children[${next.length - 1}]`, label: newBlock.type });
     }, [canEdit, draft, onPatch, onSelectionChange, shape]);
+    // ── Record binding ──────────────────────────────────────────────────────
+    // A `type: 'record'` page's `record:*` blocks (details / highlights / path /
+    // alert) read their data from <RecordContextProvider>. The metadata editor
+    // has no record route, so without binding a sample they render the
+    // "bind a record to preview" placeholder — i.e. the author designs blind.
+    // Fetch a handful of real records of the bound object + its schema and let
+    // the author pick which one to preview against (mirrors the runtime
+    // RecordDetailView's RecordContextProvider).
+    // Match the runtime resolver (usePageAssignment): a record page is keyed by
+    // either bare `type: 'record'` (editor draft shape) or `pageType: 'record'`
+    // (persisted envelope shape). Both must bind a sample record so record:*
+    // blocks render real data.
+    const isRecordPage = draft?.type === 'record'
+        || draft?.pageType === 'record';
+    const recordObject = isRecordPage ? draft?.object : undefined;
+    const [recordSamples, setRecordSamples] = React.useState([]);
+    const [recordSchema, setRecordSchema] = React.useState(null);
+    const [selectedRecordId, setSelectedRecordId] = React.useState(null);
+    React.useEffect(() => {
+        if (!recordObject) {
+            setRecordSamples([]);
+            setRecordSchema(null);
+            setSelectedRecordId(null);
+            return;
+        }
+        let cancelled = false;
+        (async () => {
+            try {
+                const opts = { headers: { accept: 'application/json' }, credentials: 'include' };
+                // Schema first: it tells us which fields are lookup/master_detail so we
+                // can `$expand` them. Without expansion record:details/highlights would
+                // show raw foreign-key IDs (e.g. "O4VKrNesnsj2JYMa") instead of display
+                // names — the runtime RecordDetailView $expands for exactly this reason.
+                const schemaRes = await fetch(`/api/v1/meta/object/${encodeURIComponent(recordObject)}`, opts);
+                const schemaJson = await schemaRes.json().catch(() => null);
+                const schema = schemaJson?.item ?? schemaJson?.data ?? schemaJson;
+                const expand = buildExpandFields(schema?.fields);
+                const query = expand.length > 0
+                    ? `?$top=50&$expand=${encodeURIComponent(expand.join(','))}`
+                    : `?$top=50`;
+                const recsRes = await fetch(`/api/v1/data/${encodeURIComponent(recordObject)}${query}`, opts);
+                const recsJson = await recsRes.json().catch(() => null);
+                // The REST data endpoint returns `{ object, records, total, hasMore }`;
+                // tolerate the other common envelopes too.
+                const recs = Array.isArray(recsJson?.records) ? recsJson.records
+                    : Array.isArray(recsJson?.items) ? recsJson.items
+                        : Array.isArray(recsJson?.data) ? recsJson.data
+                            : Array.isArray(recsJson) ? recsJson : [];
+                if (cancelled)
+                    return;
+                setRecordSamples(recs);
+                setRecordSchema(schema);
+                // Same id-resolution order as recordIdOf so the initial selection's
+                // value matches an <option> even for objects keyed only by `name`.
+                setSelectedRecordId((prev) => prev ?? (recs[0]?.id ?? recs[0]?._id ?? recs[0]?.name ?? null));
+            }
+            catch {
+                if (!cancelled) {
+                    setRecordSamples([]);
+                    setRecordSchema(null);
+                }
+            }
+        })();
+        return () => { cancelled = true; };
+    }, [recordObject]);
+    const recordIdOf = (r) => r?.id ?? r?._id ?? r?.name;
+    const recordLabelOf = (r) => String(r?.name ?? r?.title ?? r?.label ?? r?.subject ?? recordIdOf(r) ?? '(record)');
+    const selectedRecord = React.useMemo(() => {
+        if (!recordSamples.length)
+            return null;
+        return recordSamples.find((r) => String(recordIdOf(r)) === String(selectedRecordId)) ?? recordSamples[0];
+    }, [recordSamples, selectedRecordId]);
+    // ── Slotted record page synthesis ────────────────────────────────────────
+    // A `kind: 'slotted'` page carries an empty `regions: []` plus a `slots` map
+    // of overrides, so the raw draft renders blank through SchemaRenderer (there
+    // are no regions to walk). Mirror the runtime RecordDetailView: synthesize the
+    // canonical default page from the bound object's schema and apply the slot
+    // overrides via the SAME `buildDefaultPageSchema(objectDef, { slots })` path,
+    // so omitted slots fall through to the synthesized header/details/discussion
+    // while authored slots (highlights/tabs/…) override in place. Non-slotted
+    // pages render their authored schema unchanged.
+    const isSlotted = draft?.kind === 'slotted';
+    const renderSchema = React.useMemo(() => {
+        if (!isSlotted)
+            return schema;
+        try {
+            const slots = draft?.slots ?? {};
+            // `recordSchema` arrives async; until then synthesize with no objectDef
+            // (structure renders immediately, field-level detail fills in on load).
+            return buildDefaultPageSchema(recordSchema ?? undefined, { slots });
+        }
+        catch {
+            return schema;
+        }
+    }, [isSlotted, schema, draft, recordSchema]);
+    // Wrap record-page content in the record context (+ a sample-record picker)
+    // so detail/highlights/path/alert blocks render real data. No-op for
+    // non-record pages and for record pages with no rows yet (renders the node
+    // unchanged so the existing placeholder still shows).
+    const withRecordBinding = (node) => {
+        if (!recordObject || !selectedRecord)
+            return node;
+        return (_jsxs(RecordContextProvider, { objectName: recordObject, recordId: recordIdOf(selectedRecord), data: selectedRecord, objectSchema: recordSchema ?? undefined, embedded: true, children: [recordSamples.length > 0 && (_jsxs("div", { className: "flex items-center gap-2 px-3 py-1.5 border-b bg-muted/30 text-xs", children: [_jsx("span", { className: "text-muted-foreground shrink-0", children: "Preview record" }), _jsx("select", { className: "h-7 rounded-md border bg-background px-2 text-xs max-w-[260px]", value: String(selectedRecordId ?? ''), onChange: (e) => setSelectedRecordId(e.target.value), children: recordSamples.map((r) => {
+                                const id = recordIdOf(r);
+                                return _jsx("option", { value: String(id), children: recordLabelOf(r) }, String(id));
+                            }) }), _jsxs("span", { className: "text-muted-foreground/70 shrink-0", children: [recordSamples.length, " sample", recordSamples.length === 1 ? '' : 's'] })] })), node] }));
+    };
     // Interface page → always mirror the runtime (InterfaceListPage), in BOTH
     // design and preview modes. These pages are config-driven, not region-
     // composed, so there is nothing to drag on a canvas: the author edits the
@@ -106,7 +215,7 @@ export function PagePreview({ draft, editing, selection, onSelectionChange, onPa
     // rename, and add blocks inline. The outline strip becomes
     // redundant in this view.
     if (designMode && shape === 'regions') {
-        return (_jsx(PreviewShell, { hint: `page · design`, children: _jsx(PageBlockCanvas, { draft: draft, onPatch: canEdit ? onPatch : undefined, selection: selection ?? null, onSelectionChange: onSelectionChange }) }));
+        return (_jsx(PreviewShell, { hint: `page · design`, children: withRecordBinding(_jsx(PageBlockCanvas, { draft: draft, onPatch: canEdit ? onPatch : undefined, selection: selection ?? null, onSelectionChange: onSelectionChange })) }));
     }
-    return (_jsx(PreviewShell, { hint: `page${designMode ? ' · design' : ''}`, children: _jsxs(PreviewErrorBoundary, { fallbackHint: "The Page schema is incomplete or references a component that hasn't been registered yet.", children: [designMode && (_jsx(OutlineStrip, { title: tr('engine.inspector.pageBlock.outlineLabel', locale), entries: blockEntries, selectedId: selectedId, onSelect: (e) => onSelectionChange?.({ kind: 'block', id: e.id, label: e.label }), onAdd: canEdit ? handleAddBlock : undefined, addLabel: tr('engine.inspector.add.block', locale) })), _jsx("div", { className: "min-h-[200px] max-h-[70vh] overflow-auto p-4", children: _jsx(SchemaRenderer, { schema: schema }) })] }) }));
+    return (_jsx(PreviewShell, { hint: `page${designMode ? ' · design' : ''}`, children: _jsxs(PreviewErrorBoundary, { fallbackHint: "The Page schema is incomplete or references a component that hasn't been registered yet.", children: [designMode && (_jsx(OutlineStrip, { title: tr('engine.inspector.pageBlock.outlineLabel', locale), entries: blockEntries, selectedId: selectedId, onSelect: (e) => onSelectionChange?.({ kind: 'block', id: e.id, label: e.label }), onAdd: canEdit ? handleAddBlock : undefined, addLabel: tr('engine.inspector.add.block', locale) })), withRecordBinding(_jsx("div", { className: "min-h-[200px] max-h-[70vh] overflow-auto p-4", children: _jsx(SchemaRenderer, { schema: renderSchema }) }))] }) }));
 }

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

@@ -0,0 +1,18 @@
+/**
+ * ProblemsPanel — lists every structural + server validation issue for the
+ * flow draft. Each row shows the severity icon and the message; clicking a row
+ * selects and reveals (pans to) the offending node/edge on the canvas. Mirrors
+ * the "Problems" tab of an IDE / the error panel in Salesforce Flow Builder.
+ *
+ * Pure presentation: the issue list is derived upstream (see `flow-problems`)
+ * from the live draft, so rows clear as the author fixes each problem.
+ */
+import * as React from 'react';
+import type { FlowProblem } from './flow-problems';
+export interface ProblemsPanelProps {
+    problems: FlowProblem[];
+    /** Selected element key (`node:<id>` or an edge's `edgeKey`) to highlight matching rows. */
+    selectedKey?: string | null;
+    onSelectProblem: (problem: FlowProblem) => void;
+}
+export declare function ProblemsPanel({ problems, selectedKey, onSelectProblem }: ProblemsPanelProps): React.JSX.Element;

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

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AlertCircle, AlertTriangle, CheckCircle2, CircleDot, GitBranch } from 'lucide-react';
+import { cn } from '@object-ui/components';
+function targetLabel(p) {
+    if (p.target.kind === 'node')
+        return p.target.nodeId;
+    if (p.target.kind === 'edge')
+        return `${p.target.source} → ${p.target.target}`;
+    return 'flow';
+}
+export function ProblemsPanel({ problems, selectedKey, onSelectProblem }) {
+    const errorCount = problems.filter((p) => p.level === 'error').length;
+    const warningCount = problems.length - errorCount;
+    return (_jsxs("div", { className: "flex h-full flex-col text-xs", children: [_jsxs("div", { className: "flex items-center gap-2 border-b px-3 py-2 font-medium text-muted-foreground", children: [_jsx("span", { children: "Problems" }), errorCount > 0 && (_jsxs("span", { className: "inline-flex items-center gap-1 text-destructive", children: [_jsx(AlertCircle, { className: "h-3 w-3" }), " ", errorCount] })), warningCount > 0 && (_jsxs("span", { className: "inline-flex items-center gap-1 text-amber-600 dark:text-amber-400", children: [_jsx(AlertTriangle, { className: "h-3 w-3" }), " ", warningCount] }))] }), problems.length === 0 ? (_jsxs("div", { className: "flex flex-1 flex-col items-center justify-center gap-1.5 p-4 text-center text-muted-foreground", children: [_jsx(CheckCircle2, { className: "h-5 w-5 text-emerald-500" }), _jsx("span", { children: "No problems \u2014 this flow is structurally valid." })] })) : (_jsx("ul", { className: "flex-1 overflow-auto p-1.5", children: problems.map((p) => {
+                    const isEdge = p.target.kind === 'edge';
+                    const isFlow = p.target.kind === 'flow';
+                    const key = p.target.kind === 'node'
+                        ? `node:${p.target.nodeId}`
+                        : p.target.kind === 'edge'
+                            ? p.target.edgeKey
+                            : null;
+                    const active = !!key && key === selectedKey;
+                    const Icon = p.level === 'error' ? AlertCircle : AlertTriangle;
+                    const TargetIcon = isEdge ? GitBranch : CircleDot;
+                    return (_jsx("li", { children: _jsxs("button", { type: "button", disabled: isFlow, onClick: () => onSelectProblem(p), className: cn('flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left transition-colors', isFlow ? 'cursor-default' : 'cursor-pointer hover:bg-accent', active && 'bg-accent ring-1 ring-primary/40'), children: [_jsx(Icon, { className: cn('mt-0.5 h-3.5 w-3.5 shrink-0', p.level === 'error' ? 'text-destructive' : 'text-amber-500') }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block leading-snug text-foreground", children: p.message }), _jsxs("span", { className: "mt-0.5 flex items-center gap-1 text-[10px] text-muted-foreground", children: [_jsx(TargetIcon, { className: "h-2.5 w-2.5 shrink-0" }), _jsx("span", { className: "truncate font-mono", children: targetLabel(p) }), p.source === 'server' && _jsx("span", { className: "uppercase tracking-wide", children: "\u00B7 schema" }), p.source === 'expression' && _jsx("span", { className: "uppercase tracking-wide", children: "\u00B7 expression" })] })] })] }) }, p.id));
+                }) }))] }));
+}

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

@@ -4,15 +4,16 @@
  *
  * A 9.0 report binds a semantic-layer `dataset` and selects its measures
  * (`values`) grouped by dimensions (`rows`, plus `columns` across for a
- * matrix); rendering through plugin-report's `ReportRenderer` keeps the
- * studio preview pixel-equal with the runtime — including the matrix
- * cross-tab — and the numbers consistent with every other surface on the
- * same dataset (`adapter.queryDataset`). Drill-down stays inert here: the
- * preview passes no `onDrill` sink.
+ * matrix); a `joined` report instead stacks dataset-bound `blocks`. Both
+ * render through plugin-report's `ReportRenderer` (→ DatasetReportRenderer),
+ * keeping the studio preview pixel-equal with the runtime — including the
+ * matrix cross-tab and the joined block stack — and the numbers consistent
+ * with every other surface on the same dataset (`adapter.queryDataset`).
+ * Drill-down stays inert here: the preview passes no `onDrill` sink.
  *
- * A draft without a dataset binding (e.g. stored pre-9.0 query-form JSON)
- * gets an actionable empty state pointing at the inspector's Dataset control
- * instead of the retired legacy renderer.
+ * A draft with neither a dataset nor any dataset-bound block gets an
+ * actionable empty state pointing at the right inspector control instead of
+ * the retired pre-9.0 inline-query renderer.
  */
 import * as React from 'react';
 import type { MetadataPreviewProps } from '../preview-registry';

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

@@ -6,15 +6,16 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * A 9.0 report binds a semantic-layer `dataset` and selects its measures
  * (`values`) grouped by dimensions (`rows`, plus `columns` across for a
- * matrix); rendering through plugin-report's `ReportRenderer` keeps the
- * studio preview pixel-equal with the runtime — including the matrix
- * cross-tab — and the numbers consistent with every other surface on the
- * same dataset (`adapter.queryDataset`). Drill-down stays inert here: the
- * preview passes no `onDrill` sink.
+ * matrix); a `joined` report instead stacks dataset-bound `blocks`. Both
+ * render through plugin-report's `ReportRenderer` (→ DatasetReportRenderer),
+ * keeping the studio preview pixel-equal with the runtime — including the
+ * matrix cross-tab and the joined block stack — and the numbers consistent
+ * with every other surface on the same dataset (`adapter.queryDataset`).
+ * Drill-down stays inert here: the preview passes no `onDrill` sink.
  *
- * A draft without a dataset binding (e.g. stored pre-9.0 query-form JSON)
- * gets an actionable empty state pointing at the inspector's Dataset control
- * instead of the retired legacy renderer.
+ * A draft with neither a dataset nor any dataset-bound block gets an
+ * actionable empty state pointing at the right inspector control instead of
+ * the retired pre-9.0 inline-query renderer.
  */
 import * as React from 'react';
 import { Database, Loader2 } from 'lucide-react';
@@ -23,13 +24,29 @@ import { PreviewShell, PreviewErrorBoundary, PreviewEmptyState } from './Preview
 const ReportRenderer = React.lazy(() => import('@object-ui/plugin-report').then((m) => ({ default: m.ReportRenderer })));
 export function ReportPreview({ draft }) {
     const adapter = useAdapter();
-    // ADR-0021 single-form: a report binds a semantic-layer dataset.
-    if (typeof draft.dataset === 'string' && draft.dataset) {
-        const rows = Array.isArray(draft.rows) ? draft.rows.filter(Boolean) : [];
-        return (_jsx(PreviewShell, { hint: `report · dataset "${draft.dataset}"${rows.length ? ' · by ' + rows.join(', ') : ''}`, children: _jsx(PreviewErrorBoundary, { fallbackHint: "The Report references a dataset/measure that doesn't resolve, or its config is incomplete.", children: _jsx(React.Suspense, { fallback: _jsxs("div", { className: "flex items-center gap-2 p-4 text-xs text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), " Loading report renderer\u2026"] }), children: _jsx("div", { className: "p-3 min-h-[200px] max-h-[70vh] overflow-auto", children: _jsx(ReportRenderer, { schema: draft, dataSource: adapter }) }) }) }) }));
+    const d = draft;
+    // ADR-0021 single-form: a report binds a semantic-layer dataset; a `joined`
+    // report instead carries its data on dataset-bound `blocks`. Both render
+    // through plugin-report's ReportRenderer (→ DatasetReportRenderer, which
+    // stacks each block). Previously only the single-dataset shape was
+    // previewed, so a joined report fell through to the "bind a dataset" empty
+    // state and the author designed blind.
+    const hasDataset = typeof d.dataset === 'string' && !!d.dataset;
+    const isJoinedWithBlocks = d.type === 'joined' &&
+        Array.isArray(d.blocks) &&
+        d.blocks.some((b) => typeof b?.dataset === 'string' && !!b.dataset);
+    if (hasDataset || isJoinedWithBlocks) {
+        const rows = Array.isArray(d.rows) ? d.rows.filter(Boolean) : [];
+        const hint = isJoinedWithBlocks
+            ? `report · joined · ${d.blocks.length} block${d.blocks.length === 1 ? '' : 's'}`
+            : `report · dataset "${d.dataset}"${rows.length ? ' · by ' + rows.join(', ') : ''}`;
+        return (_jsx(PreviewShell, { hint: hint, children: _jsx(PreviewErrorBoundary, { fallbackHint: "The Report references a dataset/measure that doesn't resolve, or its config is incomplete.", children: _jsx(React.Suspense, { fallback: _jsxs("div", { className: "flex items-center gap-2 p-4 text-xs text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), " Loading report renderer\u2026"] }), children: _jsx("div", { className: "p-3 min-h-[200px] max-h-[70vh] overflow-auto", children: _jsx(ReportRenderer, { schema: draft, dataSource: adapter }) }) }) }) }));
     }
-    // No dataset bound — either a fresh draft or stored pre-9.0 query-form
-    // JSON (objectName/columns), whose inline-query renderer was retired with
-    // the 9.0 cutover. Point the author at the dataset binding.
-    return (_jsx(PreviewShell, { children: _jsx(PreviewEmptyState, { icon: _jsx(Database, { className: "h-8 w-8" }), title: "Bind a dataset to preview this report", description: "Since the 9.0 single-form cutover a report renders its dataset's measures (values) grouped by dimensions (rows). Choose a Dataset in the right panel to start designing." }) }));
+    // Nothing renderable yet. A joined report needs at least one dataset-bound
+    // block; every other type needs a top-level dataset. Point the author at the
+    // right control instead of the retired pre-9.0 inline-query renderer.
+    const joined = d.type === 'joined';
+    return (_jsx(PreviewShell, { children: _jsx(PreviewEmptyState, { icon: _jsx(Database, { className: "h-8 w-8" }), title: joined ? 'Add a block to preview this joined report' : 'Bind a dataset to preview this report', description: joined
+                ? 'A joined report stacks dataset-bound blocks. Add a block and bind its dataset + measures in the right panel to start designing.'
+                : "Since the 9.0 single-form cutover a report renders its dataset's measures (values) grouped by dimensions (rows). Choose a Dataset in the right panel to start designing." }) }));
 }

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

@@ -0,0 +1,38 @@
+/**
+ * ScreenPreview — live design-time preview of a flow `screen` node, rendered
+ * exactly as the end user will see it at runtime.
+ *
+ * It builds a runtime `ScreenSpec` from the node's authored `config` and hands
+ * it to the shared {@link ScreenView} — the SAME renderer the runtime
+ * FlowRunner uses — so the preview can never drift from runtime (the
+ * design↔runtime divergence #1927 set out to kill). `{var}` references in the
+ * title/description are interpolated, and `fields` are gated by their
+ * `visibleWhen`, against the supplied `variables` (the flow's declared defaults
+ * in the inspector, or the live simulated values when paused in the Debug
+ * simulator).
+ *
+ * Object-form mode is fed the SAME enriched object list the runtime uses
+ * (`useMetadata().objects`, which derives inline master-detail `subforms` from
+ * `inlineEdit` relationships) so the preview renders those child grids too.
+ *
+ * Homes: the flow node inspector (live-updates as the config is edited) and the
+ * Debug simulator's paused-at-screen state.
+ */
+import * as React from 'react';
+import { type ScreenPreviewNode } from './screen-spec';
+export type { ScreenPreviewNode } from './screen-spec';
+export interface ScreenPreviewProps {
+    /** The screen node to preview. */
+    node: ScreenPreviewNode;
+    /**
+     * Variable values for `{var}` interpolation in the title/description AND for
+     * evaluating each field's `visibleWhen`. The inspector passes the flow's
+     * declared defaults; the simulator passes the live run state at the pause
+     * point. Unknown `{var}` refs stay literal, and fields whose `visibleWhen`
+     * can't be decided stay visible — the design preview never hides on missing
+     * data.
+     */
+    variables?: Record<string, unknown>;
+    className?: string;
+}
+export declare function ScreenPreview({ node, variables, className }: ScreenPreviewProps): React.JSX.Element;

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

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * ScreenPreview — live design-time preview of a flow `screen` node, rendered
+ * exactly as the end user will see it at runtime.
+ *
+ * It builds a runtime `ScreenSpec` from the node's authored `config` and hands
+ * it to the shared {@link ScreenView} — the SAME renderer the runtime
+ * FlowRunner uses — so the preview can never drift from runtime (the
+ * design↔runtime divergence #1927 set out to kill). `{var}` references in the
+ * title/description are interpolated, and `fields` are gated by their
+ * `visibleWhen`, against the supplied `variables` (the flow's declared defaults
+ * in the inspector, or the live simulated values when paused in the Debug
+ * simulator).
+ *
+ * Object-form mode is fed the SAME enriched object list the runtime uses
+ * (`useMetadata().objects`, which derives inline master-detail `subforms` from
+ * `inlineEdit` relationships) so the preview renders those child grids too.
+ *
+ * Homes: the flow node inspector (live-updates as the config is edited) and the
+ * Debug simulator's paused-at-screen state.
+ */
+import * as React from 'react';
+import { Button, cn } from '@object-ui/components';
+import { useAdapter } from '../../../providers/AdapterProvider';
+import { useMetadata } from '../../../providers/MetadataProvider';
+import { ScreenView, isObjectFormScreen, initialScreenValues } from '../../ScreenView';
+import { buildScreenSpec, interpolate, hiddenFieldCount } from './screen-spec';
+export function ScreenPreview({ node, variables, className }) {
+    const adapter = useAdapter();
+    const meta = useMetadata();
+    const spec = React.useMemo(() => buildScreenSpec(node, variables), [node, variables]);
+    const isObjectForm = isObjectFormScreen(spec);
+    // Enriched object defs (incl. derived master-detail `subforms`) — the exact
+    // list the runtime FlowRunner gets. Only read in object-form mode so a plain
+    // field screen never triggers the all-objects fetch.
+    const objects = isObjectForm ? meta.objects : undefined;
+    const title = interpolate(spec.title, variables);
+    const description = interpolate(spec.description, variables);
+    const hidden = isObjectForm ? 0 : hiddenFieldCount(node, variables);
+    // Reset transient input state when the screen's STRUCTURE changes (fields
+    // added/removed/retyped/gated, or object-form target/mode); typing survives a
+    // label/title-only edit.
+    const structKey = isObjectForm
+        ? `obj:${spec.objectName}:${spec.mode ?? 'create'}`
+        : 'fields:' + spec.fields.map((f) => `${f.name}:${f.type ?? ''}:${f.required ? 1 : 0}`).join('|');
+    const empty = !title && !description && !isObjectForm && spec.fields.length === 0 && hidden === 0;
+    return (_jsxs("div", { className: cn('overflow-hidden rounded-md border bg-background', className), children: [_jsx("div", { className: "flex items-center gap-1.5 border-b bg-muted/30 px-3 py-1.5 text-[11px] font-medium uppercase tracking-wide text-muted-foreground", children: "Preview" }), _jsx("div", { className: "max-h-[60vh] overflow-auto p-4", children: empty ? (_jsx("p", { className: "text-sm italic text-muted-foreground", children: "Add a title, description, fields, or an object form to preview this screen." })) : (_jsxs(_Fragment, { children: [title && _jsx("h3", { className: "text-base font-semibold leading-tight", children: title }), description && (_jsx("p", { className: cn('whitespace-pre-line text-sm text-muted-foreground', title && 'mt-1'), children: description })), _jsx(ScreenFormPreview, { spec: spec, adapter: adapter, objects: objects }, structKey), !isObjectForm && hidden > 0 && (_jsxs("p", { className: "mt-3 text-[11px] italic text-muted-foreground", children: [hidden, " field", hidden === 1 ? '' : 's', " hidden by ", hidden === 1 ? 'its' : 'their', " \u201Cvisible when\u201D", ' ', "condition", hidden === 1 ? '' : 's', "."] })), !isObjectForm && spec.fields.length > 0 && (_jsx("div", { className: "mt-4 flex justify-end", children: _jsx(Button, { size: "sm", disabled: true, children: "Submit" }) }))] })) })] }));
+}
+/**
+ * Holds the transient field values so the preview is interactive (the author
+ * can type into it) while never persisting anything.
+ */
+function ScreenFormPreview({ spec, adapter, objects }) {
+    const [values, setValues] = React.useState(() => initialScreenValues(spec));
+    return (_jsx(ScreenView, { screen: spec, values: values, onValueChange: (name, v) => setValues((p) => ({ ...p, [name]: v })), dataSource: adapter ?? undefined, objects: objects, objectForm: {
+            showSubmit: false,
+            showCancel: false,
+            noDataSourceMessage: 'Connect to a backend to preview this object form.',
+        } }));
+}

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

@@ -75,6 +75,20 @@ export declare function topAnchor(p: Point): Point;
 export declare function edgePath(from: Point, to: Point): string;
 /** Midpoint of an edge — anchor for the condition label + insert affordance. */
 export declare function edgeMidpoint(from: Point, to: Point): Point;
+/** True for an ADR-0044 declared back-edge (a revise/rework loop's return). */
+export declare function isBackEdge(edge: Pick<FlowEdge, 'type'>): boolean;
+/** Right-center anchor of a node — where a back-edge's return arc attaches. */
+export declare function rightAnchor(p: Point): Point;
+/**
+ * Curved return path for a declared back-edge (ADR-0044 revise loop). Unlike a
+ * forward edge (top→bottom), a back-edge re-enters an earlier node, so we route
+ * it off the right side of both endpoints and bow it out to the right — a
+ * distinct return arc that reads as "loop back" rather than crossing the
+ * top-to-bottom forward edges.
+ */
+export declare function backEdgePath(from: Point, to: Point): string;
+/** Anchor for a back-edge's label pill — the apex of its return arc. */
+export declare function backEdgeLabelAnchor(from: Point, to: Point): Point;
 /**
  * Stable identity for an edge. Prefers an explicit `edge.id`; otherwise falls
  * back to a `source->target#index` composite so an unsaved edge still has a

package/dist/views/metadata-admin/previews/flow-canvas-layout.js

@@ -40,6 +40,12 @@ export function computeLayout(nodes, edges) {
     for (const e of edges) {
         if (!byId.has(e.source) || !byId.has(e.target) || e.source === e.target)
             continue;
+        // ADR-0044: a declared back-edge (`type: 'back'`) re-enters an earlier node
+        // to close a revise loop. Exclude it from layering — exactly as the engine
+        // excludes it from DAG validation — so the loop doesn't drag its target
+        // node below the wait point. The edge is still drawn (as a return arc).
+        if (isBackEdge(e))
+            continue;
         if (!outAdj.has(e.source))
             outAdj.set(e.source, []);
         outAdj.get(e.source).push(e.target);
@@ -167,6 +173,37 @@ export function edgePath(from, to) {
 export function edgeMidpoint(from, to) {
     return { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 };
 }
+/** True for an ADR-0044 declared back-edge (a revise/rework loop's return). */
+export function isBackEdge(edge) {
+    return edge.type === 'back';
+}
+/** Right-center anchor of a node — where a back-edge's return arc attaches. */
+export function rightAnchor(p) {
+    return { x: p.x + NODE_W, y: p.y + NODE_H / 2 };
+}
+/** Horizontal bow of a back-edge's return arc, scaled to the vertical span. */
+function backEdgeBow(from, to) {
+    return Math.max(64, Math.abs(to.y - from.y) * 0.35);
+}
+/**
+ * Curved return path for a declared back-edge (ADR-0044 revise loop). Unlike a
+ * forward edge (top→bottom), a back-edge re-enters an earlier node, so we route
+ * it off the right side of both endpoints and bow it out to the right — a
+ * distinct return arc that reads as "loop back" rather than crossing the
+ * top-to-bottom forward edges.
+ */
+export function backEdgePath(from, to) {
+    const bow = backEdgeBow(from, to);
+    const c1 = { x: from.x + bow, y: from.y };
+    const c2 = { x: to.x + bow, y: to.y };
+    return `M ${from.x},${from.y} C ${c1.x},${c1.y} ${c2.x},${c2.y} ${to.x},${to.y}`;
+}
+/** Anchor for a back-edge's label pill — the apex of its return arc. */
+export function backEdgeLabelAnchor(from, to) {
+    // The cubic's t=0.5 point sits ~0.75·bow right of the (shared) right edge.
+    const bow = backEdgeBow(from, to);
+    return { x: Math.max(from.x, to.x) + bow * 0.75, y: (from.y + to.y) / 2 };
+}
 /**
  * Stable identity for an edge. Prefers an explicit `edge.id`; otherwise falls
  * back to a `source->target#index` composite so an unsaved edge still has a

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

@@ -66,16 +66,32 @@ export interface NodeCardProps {
     runState?: 'active' | 'visited';
     /** Dim nodes not yet reached while a simulation is in progress. */
     dimmed?: boolean;
+    /** Structural-validation error highlight (e.g. part of an un-declared cycle). */
+    invalid?: boolean;
+    /**
+     * Validation badge shown at the card's top-right corner (error or warning),
+     * with the issue message(s) as its tooltip. Cleared when the issue resolves.
+     */
+    badge?: {
+        level: 'error' | 'warning';
+        title: string;
+    };
     onPointerDown?: (e: React.PointerEvent) => void;
     onSelect?: () => void;
     onAppend?: () => void;
+    /**
+     * ADR-0044: when set (approval nodes without an existing revise loop), render
+     * the one-click "add revision loop" affordance — drops a wait node + the
+     * `revise` and declared `back` edges in a single gesture.
+     */
+    onAddReviseLoop?: () => void;
 }
 /**
  * A single draggable flow node rendered at an absolute canvas coordinate.
  * The card body drives selection + reposition; a dedicated bottom "+" handle
  * (edit mode only) appends a connected child without ambiguity.
  */
-export declare function NodeCard({ type, label, summary, position, selected, editable, runState, dimmed, onPointerDown, onSelect, onAppend, }: NodeCardProps): React.JSX.Element;
+export declare function NodeCard({ type, label, summary, position, selected, editable, runState, dimmed, invalid, badge, onPointerDown, onSelect, onAppend, onAddReviseLoop, }: NodeCardProps): React.JSX.Element;
 export interface NodePaletteProps {
     locale?: string;
     /** Node types to offer. Defaults to the hardcoded {@link NODE_PALETTE}. */

package/dist/views/metadata-admin/previews/flow-canvas-parts.js

@@ -6,7 +6,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * palette popover. Kept dependency-free and Shadcn-native (Tailwind + lucide).
  */
 import * as React from 'react';
-import { Code, CircleDot, CircleStop, Diamond, FilePen, FilePlus, FileSearch, FileX, GitFork, Globe, ListChecks, MonitorSmartphone, Play, Plug, Plus, Repeat, ShieldAlert, TimerReset, UserCheck, Variable, Workflow, Zap, } from 'lucide-react';
+import { AlertCircle, AlertTriangle, Code, CircleDot, CircleStop, Diamond, FilePen, FilePlus, FileSearch, FileX, GitFork, Globe, IterationCcw, ListChecks, MonitorSmartphone, Play, Plug, Plus, Repeat, ShieldAlert, TimerReset, UserCheck, Variable, Workflow, Zap, } from 'lucide-react';
 import { cn } from '@object-ui/components';
 import { NODE_W, NODE_H } from './flow-canvas-layout';
 export function nodeIcon(type) {
@@ -188,6 +188,7 @@ export function nodeTone(type) {
         case 'delete_record':
         case 'get_record':
             return TONES.record;
+        case 'http':
         case 'http_request':
         case 'connector_action':
         case 'script':
@@ -237,6 +238,7 @@ export function nodeCategory(type) {
         case 'screen':
         case 'user_task':
             return 'Human';
+        case 'http':
         case 'http_request':
         case 'connector_action':
         case 'script':
@@ -265,7 +267,7 @@ export const NODE_PALETTE = [
     { type: 'try_catch', label: 'Try / Catch', hint: 'Protect steps with error handling and retry', category: 'Logic' },
     { type: 'approval', label: 'Approval', hint: 'Pause for a human decision', category: 'Human' },
     { type: 'screen', label: 'Screen', hint: 'Collect input from a user', category: 'Human' },
-    { type: 'http_request', label: 'HTTP request', hint: 'Call an external API', category: 'Integration' },
+    { type: 'http', label: 'HTTP request', hint: 'Call an external API', category: 'Integration' },
     { type: 'connector_action', label: 'Connector', hint: 'Run an integration action', category: 'Integration' },
     { type: 'script', label: 'Script', hint: 'Run custom code', category: 'Integration' },
     { type: 'subflow', label: 'Subflow', hint: 'Invoke another flow', category: 'Flow' },
@@ -301,6 +303,7 @@ export function defaultNodeExtras(type) {
             // Seed a node-model approval: at least one approver + spec defaults. The
             // author wires the out-edges with labels `approve` / `reject`.
             return { config: { approvers: [{ type: 'manager' }], behavior: 'first_response', lockRecord: true } };
+        case 'http':
         case 'http_request':
             return { config: { method: 'GET' } };
         case 'script':
@@ -314,9 +317,13 @@ export function defaultNodeExtras(type) {
  * The card body drives selection + reposition; a dedicated bottom "+" handle
  * (edit mode only) appends a connected child without ambiguity.
  */
-export function NodeCard({ type, label, summary, position, selected, editable, runState, dimmed, onPointerDown, onSelect, onAppend, }) {
+export function NodeCard({ type, label, summary, position, selected, editable, runState, dimmed, invalid, badge, onPointerDown, onSelect, onAppend, onAddReviseLoop, }) {
     const tone = nodeTone(type);
-    return (_jsxs("div", { className: "absolute transition-opacity duration-200", style: { left: position.x, top: position.y, width: NODE_W, height: NODE_H, opacity: dimmed ? 0.35 : 1 }, children: [_jsxs("div", { role: "button", tabIndex: 0, "aria-pressed": selected, onPointerDown: onPointerDown, onClick: (e) => {
+    return (_jsxs("div", { 
+        // `group` so the hover-revealed affordances (append "+", revise loop)
+        // appear when the pointer is anywhere over the card, not only over the
+        // tiny button itself.
+        className: "group absolute transition-opacity duration-200", "data-invalid": invalid || undefined, style: { left: position.x, top: position.y, width: NODE_W, height: NODE_H, opacity: dimmed ? 0.35 : 1 }, children: [_jsxs("div", { role: "button", tabIndex: 0, "aria-pressed": selected, onPointerDown: onPointerDown, onClick: (e) => {
                     e.stopPropagation();
                     onSelect?.();
                 }, onKeyDown: (e) => {
@@ -330,10 +337,20 @@ export function NodeCard({ type, label, summary, position, selected, editable, r
                         ? 'border-emerald-500/70 ring-1 ring-emerald-400/40'
                         : selected
                             ? 'border-primary shadow-md ring-2 ring-primary/30'
-                            : 'border-border/80'), children: [_jsx("div", { className: cn('flex h-9 w-9 shrink-0 items-center justify-center rounded-lg transition-transform duration-150 group-hover:scale-105', tone.chip, runState === 'active' && 'animate-pulse'), children: _jsx(NodeTypeIcon, { type: type, className: cn('h-[18px] w-[18px]', tone.icon) }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { title: label, className: "truncate text-[13px] font-semibold leading-tight text-foreground", children: label }), _jsxs("div", { className: "mt-1 flex items-baseline gap-1.5 leading-tight", children: [_jsx("span", { className: cn('shrink-0 text-[10px] font-semibold uppercase tracking-[0.08em]', tone.label), children: type }), summary && (_jsx("span", { className: "min-w-0 truncate font-mono text-[10px] text-muted-foreground", title: summary, children: summary }))] })] })] }), editable && type !== 'end' && (_jsx("button", { type: "button", title: "Add connected node", "aria-label": "Add connected node", onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
+                            : invalid
+                                ? 'border-destructive ring-2 ring-destructive/50'
+                                : 'border-border/80'), children: [_jsx("div", { className: cn('flex h-9 w-9 shrink-0 items-center justify-center rounded-lg transition-transform duration-150 group-hover:scale-105', tone.chip, runState === 'active' && 'animate-pulse'), children: _jsx(NodeTypeIcon, { type: type, className: cn('h-[18px] w-[18px]', tone.icon) }) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { title: label, className: "truncate text-[13px] font-semibold leading-tight text-foreground", children: label }), _jsxs("div", { className: "mt-1 flex items-baseline gap-1.5 leading-tight", children: [_jsx("span", { className: cn('shrink-0 text-[10px] font-semibold uppercase tracking-[0.08em]', tone.label), children: type }), summary && (_jsx("span", { className: "min-w-0 truncate font-mono text-[10px] text-muted-foreground", title: summary, children: summary }))] })] })] }), badge && (_jsx("span", { title: badge.title, "data-problem": badge.level, className: cn('absolute -right-2 -top-2 z-20 inline-flex h-5 w-5 items-center justify-center rounded-full border bg-background shadow-sm', badge.level === 'error'
+                    ? 'border-destructive/50 text-destructive'
+                    : 'border-amber-500/50 text-amber-600 dark:text-amber-400'), children: badge.level === 'error' ? (_jsx(AlertCircle, { className: "h-3 w-3" })) : (_jsx(AlertTriangle, { className: "h-3 w-3" })) })), editable && type !== 'end' && (_jsx("button", { type: "button", title: "Add connected node", "aria-label": "Add connected node", onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
                     e.stopPropagation();
                     onAppend?.();
-                }, className: cn('absolute left-1/2 -bottom-3 z-10 inline-flex h-6 w-6 -translate-x-1/2 items-center justify-center rounded-full border bg-background text-muted-foreground shadow-sm transition-colors', 'opacity-0 hover:border-primary hover:text-primary group-hover:opacity-100 focus-visible:opacity-100'), children: _jsx(Plus, { className: "h-3.5 w-3.5" }) }))] }));
+                }, className: cn('absolute left-1/2 -bottom-3 z-10 inline-flex h-6 w-6 -translate-x-1/2 items-center justify-center rounded-full border bg-background text-muted-foreground shadow-sm transition-colors', 'opacity-0 hover:border-primary hover:text-primary group-hover:opacity-100 focus-visible:opacity-100'), children: _jsx(Plus, { className: "h-3.5 w-3.5" }) })), onAddReviseLoop && (_jsx("button", { type: "button", title: "Add revision loop (send back for revision)", "aria-label": "Add revision loop", onPointerDown: (e) => e.stopPropagation(), onClick: (e) => {
+                    e.stopPropagation();
+                    onAddReviseLoop();
+                }, 
+                // Anchored to the right edge — where the back-edge's return arc
+                // attaches — and tinted amber to match the rendered back-edge.
+                className: cn('absolute -right-3 top-1/2 z-10 inline-flex h-6 w-6 -translate-y-1/2 items-center justify-center rounded-full border bg-background text-amber-600 shadow-sm transition-colors dark:text-amber-400', 'opacity-0 hover:border-amber-500 hover:text-amber-600 group-hover:opacity-100 focus-visible:opacity-100 dark:hover:text-amber-400'), children: _jsx(IterationCcw, { className: "h-3.5 w-3.5" }) }))] }));
 }
 /** Compact popover listing the node types an author can add, grouped by category. */
 export function NodePalette({ items = NODE_PALETTE, onPick, onClose }) {

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

@@ -0,0 +1,19 @@
+import type { DiagnosticLevel } from './simulator/flow-sim-types';
+export interface ExprProblem {
+    target: {
+        kind: 'node';
+        nodeId: string;
+    } | {
+        kind: 'edge';
+        source: string;
+        target: string;
+    };
+    level: DiagnosticLevel;
+    message: string;
+}
+/**
+ * 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 declare function flowExpressionProblems(draft: Record<string, unknown>): ExprProblem[];