@calliopelabs/ui 0.7.0 → 0.12.0

package/dist/workflow/editor/WorkflowWorkspace.js

@@ -0,0 +1,154 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CopyPlusIcon, DownloadIcon, ListTreeIcon, PanelRightIcon, RocketIcon, SaveIcon, UndoIcon, UploadIcon, } from "lucide-react";
+import * as React from "react";
+import { cn } from "../../lib/cn.js";
+import { ConfirmDialog } from "../../overlays/ConfirmDialog.js";
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, } from "../../overlays/Dialog.js";
+import { Drawer, DrawerContent, DrawerTitle } from "../../overlays/Drawer.js";
+import { Button } from "../../primitives/Button.js";
+import { Field } from "../../primitives/Field.js";
+import { Input } from "../../primitives/Input.js";
+import { Segmented } from "../../primitives/Segmented.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../../primitives/Tabs.js";
+import { useUI } from "../../provider/UIProvider.js";
+import { ErrorState } from "../../states/ErrorState.js";
+import { LoadingState } from "../../states/LoadingState.js";
+import { StatusBadge } from "../../status/StatusBadge.js";
+import { WorkflowCanvas } from "../canvas/WorkflowCanvas.js";
+import { insertPaletteItem } from "../palette.js";
+import { diffDefinitions, sameDefinition, } from "../portable.js";
+import { blockingProblems, checkDefinition } from "../problems.js";
+import { documentStatus } from "../workspace.js";
+import { WorkflowDiff } from "./WorkflowDiff.js";
+import { WorkflowImportPreview } from "./WorkflowImportPreview.js";
+import { WorkflowInspector } from "./WorkflowInspector.js";
+import { WorkflowJsonView } from "./WorkflowJsonView.js";
+import { WorkflowPalette } from "./WorkflowPalette.js";
+import { WorkflowProblems } from "./WorkflowProblems.js";
+const messageOf = (e) => (e instanceof Error ? e.message : typeof e === "string" ? e : "");
+/**
+ * The whole editor on one page: the palette, the canvas and a side panel
+ * (properties, problems, JSON), around a controlled working copy. It knows
+ * the saved and published revisions the host holds: it marks unsaved edits
+ * and a draft that differs from what runs, takes a newer saved revision when
+ * there are no edits, and when the saved revision moves under unsaved edits
+ * it stops and asks (use theirs, keep mine, compare). Publishing shows the
+ * draft against live first and is held while anything blocks. Save, publish,
+ * save as, import and export are the host's; it never persists anything. On
+ * narrow containers the palette and the side panel open as drawers.
+ */
+export function WorkflowWorkspace(props) {
+    const { messages } = useUI();
+    if (props.loading)
+        return (_jsx(LoadingState, { variant: "page", label: messages.workspace.loading, className: props.className }));
+    if (props.error || !props.definition)
+        return (_jsx(ErrorState, { variant: "page", title: messages.workspace.loadFailed, error: props.error ?? null, onRetry: props.onRetry, className: props.className }));
+    return _jsx(Workspace, { ...props, definition: props.definition });
+}
+function Workspace({ definition, onChange, registry, saved = null, published = null, onSave, onPublish, onSaveAs, onExport, onImport, importPreview = null, onImportConfirm, onImportCancel, readOnly: readOnlyProp = false, className, }) {
+    const { messages } = useUI();
+    const m = messages.workspace;
+    const readOnly = readOnlyProp || !onChange;
+    const [base, setBase] = React.useState(saved ?? published);
+    const [flowName, setFlowName] = React.useState(definition.main);
+    const flow = definition.flows[flowName] ? flowName : definition.main;
+    const [selection, setSelection] = React.useState(null);
+    const [panel, setPanel] = React.useState("inspector");
+    const [drawer, setDrawer] = React.useState(null);
+    const [dialog, setDialog] = React.useState(null);
+    const [busy, setBusy] = React.useState(null);
+    const [failure, setFailure] = React.useState(null);
+    const [notice, setNotice] = React.useState(null);
+    const [name, setName] = React.useState("");
+    // A newer saved revision: take it when it is this copy, or when there is nothing to lose.
+    const [seen, setSeen] = React.useState(saved?.id);
+    const [adopt, setAdopt] = React.useState(null);
+    if (saved && saved.id !== seen) {
+        setSeen(saved.id);
+        const same = sameDefinition(definition, saved.definition);
+        if (same || !base || sameDefinition(definition, base.definition)) {
+            setBase(saved);
+            if (!same)
+                setAdopt(saved.id);
+        }
+    }
+    if (adopt && (!saved || saved.id !== adopt || sameDefinition(definition, saved.definition)))
+        setAdopt(null);
+    React.useEffect(() => {
+        if (adopt && saved?.id === adopt)
+            onChange?.(saved.definition);
+    }, [adopt, saved, onChange]);
+    const status = documentStatus(definition, base, saved, published);
+    const problems = React.useMemo(() => checkDefinition(definition, registry), [definition, registry]);
+    const blocking = blockingProblems(problems).length;
+    const warnings = problems.filter((p) => p.level === "warning").length;
+    const run = async (kind, action, done) => {
+        setBusy(kind);
+        setFailure(null);
+        setNotice(null);
+        try {
+            const result = await action();
+            if (result === false)
+                return false;
+            setNotice(done);
+            return true;
+        }
+        catch (e) {
+            setFailure(messageOf(e) || m.failed);
+            return false;
+        }
+        finally {
+            setBusy(null);
+        }
+    };
+    const select = (s) => {
+        setSelection(s);
+        if (s && s.flow !== flow)
+            setFlowName(s.flow);
+    };
+    const add = (item) => {
+        const label = item.label ||
+            (item.template.kind === "step"
+                ? messages.editor.customStep
+                : messages.editor.kind(item.template.kind));
+        const r = insertPaletteItem(definition, flow, item, registry, label, selection?.type === "node" && selection.flow === flow ? selection.id : null);
+        onChange?.(r.definition);
+        select({ type: "node", flow, id: r.node.id });
+        setDrawer(null);
+    };
+    const flows = Object.entries(definition.flows);
+    const edit = readOnly ? undefined : onChange;
+    const palette = (_jsx(WorkflowPalette, { registry: registry, onAdd: readOnly ? undefined : add, className: "min-h-0 flex-1" }));
+    const side = (_jsxs(Tabs, { value: panel, onValueChange: (v) => setPanel(v), className: "flex min-h-0 flex-1 flex-col", children: [_jsxs(TabsList, { "aria-label": m.panels, children: [_jsx(TabsTrigger, { value: "inspector", children: messages.editor.inspector }), _jsx(TabsTrigger, { value: "problems", children: m.problemsTab(blocking + warnings) }), _jsx(TabsTrigger, { value: "json", children: m.jsonTab })] }), _jsx(TabsContent, { value: "inspector", className: "min-h-0 flex-1 overflow-y-auto", children: _jsx(WorkflowInspector, { definition: definition, registry: registry, selection: selection, onSelectionChange: select, onChange: edit, readOnly: readOnly }) }), _jsx(TabsContent, { value: "problems", className: "min-h-0 flex-1 overflow-y-auto", children: _jsx(WorkflowProblems, { problems: problems, definition: definition, onSelect: (s) => {
+                        select(s);
+                        setPanel("inspector");
+                        setDrawer(null);
+                    } }) }), _jsx(TabsContent, { value: "json", className: "min-h-0 flex-1 overflow-y-auto", children: _jsx(WorkflowJsonView, { definition: definition, onChange: edit, readOnly: readOnly }) })] }));
+    return (_jsxs("div", { "data-slot": "workflow-workspace", className: cn("@container flex h-full min-h-0 flex-col gap-3", className), children: [_jsxs("header", { className: "flex flex-wrap items-start justify-between gap-3", children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-1.5", children: [_jsx("h1", { className: "truncate font-head text-xl font-semibold", children: definition.name }), _jsxs("p", { role: "status", className: "flex flex-wrap items-center gap-1.5 text-sm", children: [readOnly ? _jsx(StatusBadge, { tone: "muted", children: messages.editor.readOnly }) : null, " ", status.conflict ? (_jsx(StatusBadge, { tone: "error", children: m.conflict })) : status.dirty ? (_jsx(StatusBadge, { tone: "warn", children: m.unsaved })) : saved ? (_jsx(StatusBadge, { tone: "muted", children: m.saved(saved.label) })) : null, " ", published ? (status.unpublished ? (_jsx(StatusBadge, { tone: "info", children: m.differsFromLive(published.label) })) : (_jsx(StatusBadge, { tone: "ok", children: m.live(published.label) }))) : (_jsx(StatusBadge, { tone: "muted", children: m.notPublished }))] })] }), _jsxs("div", { role: "toolbar", "aria-label": m.actions, className: "flex flex-wrap items-center gap-1.5", children: [onImport && !readOnly ? (_jsxs(Button, { size: "sm", variant: "ghost", onClick: onImport, children: [_jsx(UploadIcon, { "aria-hidden": true }), m.import] })) : null, onExport ? (_jsxs(Button, { size: "sm", variant: "ghost", onClick: () => onExport(definition), children: [_jsx(DownloadIcon, { "aria-hidden": true }), m.export] })) : null, !readOnly && status.dirty && base ? (_jsxs(Button, { size: "sm", variant: "ghost", onClick: () => setDialog("discard"), children: [_jsx(UndoIcon, { "aria-hidden": true }), m.discard] })) : null, onSaveAs && !readOnly ? (_jsxs(Button, { size: "sm", variant: "outline", disabled: busy !== null, onClick: () => {
+                                    setName(m.copyName(definition.name));
+                                    setDialog("save-as");
+                                }, children: [_jsx(CopyPlusIcon, { "aria-hidden": true }), m.saveAs] })) : null, onSave && !readOnly ? (_jsxs(Button, { size: "sm", variant: "outline", disabled: !status.dirty || status.conflict || busy !== null, onClick: () => void run("save", () => onSave(definition, base), m.savedNotice), children: [_jsx(SaveIcon, { "aria-hidden": true }), busy === "save" ? m.saving : m.save] })) : null, onPublish && !readOnly ? (_jsxs(Button, { size: "sm", disabled: status.conflict || busy !== null || (!status.unpublished && !!published), onClick: () => setDialog("publish"), children: [_jsx(RocketIcon, { "aria-hidden": true }), m.publish] })) : null] })] }), failure ? (_jsx("p", { role: "alert", className: "rounded-lg border border-danger-border bg-danger-bg px-3 py-2 text-sm text-danger-fg", children: failure })) : null, notice ? (_jsx("p", { className: "sr-only", role: "status", children: notice })) : null, status.conflict && saved ? (_jsxs("div", { role: "alert", className: "flex flex-wrap items-center gap-2 rounded-lg border border-warning-border bg-warning-bg px-3 py-2 text-sm text-warning-fg", children: [_jsx("span", { className: "min-w-0 flex-1", children: m.conflictDescription(saved.by, saved.label) }), _jsx(Button, { size: "sm", variant: "outline", onClick: () => setDialog("compare"), children: m.compare }), _jsx(Button, { size: "sm", variant: "outline", onClick: () => {
+                            setBase(saved);
+                            onChange?.(saved.definition);
+                        }, children: m.useTheirs }), _jsx(Button, { size: "sm", variant: "outline", onClick: () => setBase(saved), children: m.keepMine })] })) : null, _jsxs("div", { className: "flex min-h-0 flex-1 gap-3", children: [_jsx("aside", { "aria-label": m.paletteRegion, className: "hidden w-60 shrink-0 flex-col @5xl:flex", children: palette }), _jsxs("div", { className: "flex min-h-0 min-w-0 flex-1 flex-col gap-2", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [!readOnly ? (_jsxs(Button, { size: "sm", variant: "outline", className: "@5xl:hidden", onClick: () => setDrawer("palette"), children: [_jsx(ListTreeIcon, { "aria-hidden": true }), messages.editor.palette] })) : null, _jsxs(Button, { size: "sm", variant: "outline", className: "@5xl:hidden", onClick: () => setDrawer("panel"), children: [_jsx(PanelRightIcon, { "aria-hidden": true }), m.panels] }), flows.length > 1 ? (_jsx(Segmented, { label: m.flow, size: "sm", value: flow, onValueChange: (v) => {
+                                            setFlowName(v);
+                                            setSelection(null);
+                                        }, options: flows.map(([key, f]) => ({ value: key, label: f.label ?? key })) })) : null] }), _jsx(WorkflowCanvas, { definition: definition, flow: flow, registry: registry, onChange: edit, readOnly: readOnly, selection: selection, onSelectionChange: select, problems: problems, className: "min-h-96 flex-1" }, flow)] }), _jsx("aside", { "aria-label": m.panels, className: "hidden w-88 shrink-0 flex-col @5xl:flex", children: side })] }), _jsx(Drawer, { open: drawer !== null, onOpenChange: (open) => !open && setDrawer(null), children: _jsxs(DrawerContent, { side: drawer === "palette" ? "left" : "right", className: "p-4", children: [_jsx(DrawerTitle, { children: drawer === "palette" ? messages.editor.palette : m.panels }), _jsx("div", { className: "flex min-h-0 flex-1 flex-col", children: drawer === "palette" ? palette : side })] }) }), _jsx(Dialog, { open: dialog === "publish", onOpenChange: (open) => !open && setDialog(null), children: _jsxs(DialogContent, { className: "max-w-xl", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: m.publishTitle }), _jsx(DialogDescription, { children: published ? m.publishDescription(published.label) : m.firstPublish })] }), published ? (_jsx(WorkflowDiff, { diff: diffDefinitions(published.definition, definition), flows: definition.flows, label: m.draftAgainstLive, className: "max-h-80 overflow-y-auto" })) : null, blocking ? (_jsx("p", { role: "alert", className: "text-sm text-danger-fg", children: m.publishBlocked(blocking) })) : null, _jsxs(DialogFooter, { children: [_jsx(Button, { type: "button", variant: "outline", onClick: () => setDialog(null), children: messages.editor.cancel }), _jsx(Button, { type: "button", disabled: blocking > 0 || busy !== null, onClick: async () => {
+                                        if (await run("publish", () => onPublish?.(definition), m.publishedNotice))
+                                            setDialog(null);
+                                    }, children: busy === "publish" ? m.publishing : m.publish })] })] }) }), _jsx(Dialog, { open: dialog === "save-as", onOpenChange: (open) => !open && setDialog(null), children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: m.saveAsTitle }), _jsx(DialogDescription, { children: m.saveAsDescription })] }), _jsxs("form", { className: "flex flex-col gap-4", onSubmit: async (e) => {
+                                e.preventDefault();
+                                const trimmed = name.trim();
+                                if (!trimmed)
+                                    return;
+                                if (await run("save-as", () => onSaveAs?.({ ...definition, name: trimmed }, trimmed), m.savedAsNotice(trimmed)))
+                                    setDialog(null);
+                            }, children: [_jsx(Field, { label: messages.editor.name, required: true, children: _jsx(Input, { value: name, onChange: (e) => setName(e.target.value) }) }), _jsxs(DialogFooter, { children: [_jsx(Button, { type: "button", variant: "outline", onClick: () => setDialog(null), children: messages.editor.cancel }), _jsx(Button, { type: "submit", disabled: !name.trim() || busy !== null, children: busy === "save-as" ? m.saving : m.saveAs })] })] })] }) }), _jsx(Dialog, { open: dialog === "compare", onOpenChange: (open) => !open && setDialog(null), children: _jsxs(DialogContent, { className: "max-w-xl", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: m.compareTitle }), _jsx(DialogDescription, { children: m.compareDescription })] }), saved ? (_jsx(WorkflowDiff, { diff: diffDefinitions(saved.definition, definition), flows: definition.flows, label: m.compareTitle, className: "max-h-80 overflow-y-auto" })) : null] }) }), _jsx(ConfirmDialog, { open: dialog === "discard", onOpenChange: (open) => !open && setDialog(null), title: m.discardTitle, description: m.discardDescription, confirmLabel: m.discard, destructive: true, onConfirm: () => {
+                    if (base)
+                        onChange?.(base.definition);
+                    setSelection(null);
+                } }), _jsx(Dialog, { open: !!importPreview, onOpenChange: (open) => !open && onImportCancel?.(), children: _jsxs(DialogContent, { className: "max-w-xl", children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: m.importTitle }), _jsx(DialogDescription, { children: m.importDescription })] }), importPreview ? (_jsx(WorkflowImportPreview, { preview: importPreview, busy: busy === "import", onCancel: onImportCancel, onConfirm: onImportConfirm
+                                ? () => void run("import", () => onImportConfirm(), m.importedNotice)
+                                : undefined, className: "max-h-[70vh] overflow-y-auto" })) : null] }) })] }));
+}

package/dist/workflow/gallery.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The gallery's filters, and a filter over workflows held in memory. Pure:
+ * no hooks, no browser APIs. A host that searches on its server passes the
+ * filters to its query instead and hands the gallery the result.
+ */
+import type { WorkflowScope, WorkflowStatus, WorkflowSummary } from "./model.js";
+/** Every filter's "no filter" value. */
+export declare const ANY_FILTER = "any";
+export interface WorkflowGalleryFilters {
+    /** Free text, matched against name, description and module. */
+    query: string;
+    /** A module id, or `"any"`. */
+    module: string;
+    scope: WorkflowScope | typeof ANY_FILTER;
+    status: WorkflowStatus | typeof ANY_FILTER;
+}
+export declare const DEFAULT_WORKFLOW_FILTERS: WorkflowGalleryFilters;
+/** True when any filter narrows the gallery, so an empty result is "no matches", not "none yet". */
+export declare function isFiltered(filters: WorkflowGalleryFilters): boolean;
+/** The workflows the filters keep, in their order. For hosts that hold the whole set. */
+export declare function filterWorkflows(workflows: readonly WorkflowSummary[], filters: WorkflowGalleryFilters): WorkflowSummary[];

package/dist/workflow/gallery.js

@@ -0,0 +1,29 @@
+/** Every filter's "no filter" value. */
+export const ANY_FILTER = "any";
+export const DEFAULT_WORKFLOW_FILTERS = {
+    query: "",
+    module: ANY_FILTER,
+    scope: ANY_FILTER,
+    status: ANY_FILTER,
+};
+/** True when any filter narrows the gallery, so an empty result is "no matches", not "none yet". */
+export function isFiltered(filters) {
+    return (filters.query.trim() !== "" ||
+        filters.module !== ANY_FILTER ||
+        filters.scope !== ANY_FILTER ||
+        filters.status !== ANY_FILTER);
+}
+/** The workflows the filters keep, in their order. For hosts that hold the whole set. */
+export function filterWorkflows(workflows, filters) {
+    const terms = filters.query.toLocaleLowerCase().split(/\s+/).filter(Boolean);
+    return workflows.filter((w) => {
+        if (filters.module !== ANY_FILTER && w.module.id !== filters.module)
+            return false;
+        if (filters.scope !== ANY_FILTER && w.scope !== filters.scope)
+            return false;
+        if (filters.status !== ANY_FILTER && w.status !== filters.status)
+            return false;
+        const text = `${w.name} ${w.description ?? ""} ${w.module.label}`.toLocaleLowerCase();
+        return terms.every((term) => text.includes(term));
+    });
+}

package/dist/workflow/layout.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Where a flow's nodes sit on the canvas, and the parts of it that fold into
+ * one: node sizes from their ports, a layered layout along the run (ranks by
+ * longest path over next edges, two barycentre sweeps to untangle branches),
+ * and the regions a person can collapse (a loop's body, a fan-out's branches
+ * up to their join). Pure.
+ */
+import { type WorkflowDefinition, type WorkflowFlow, type WorkflowNode, type WorkflowPosition, type WorkflowRegistry } from "./definition.js";
+export declare const NODE_WIDTH = 224;
+/** The header: kind, label, summary. */
+export declare const NODE_HEADER = 76;
+/** One port row below the header. */
+export declare const PORT_ROW = 22;
+/** The rows a node draws below its header: inputs on the left; exits (when it has several) and outputs on the right. */
+export declare function portRows(node: WorkflowNode, registry: WorkflowRegistry, definition?: WorkflowDefinition): {
+    left: number;
+    right: number;
+};
+export declare function nodeSize(node: WorkflowNode, registry: WorkflowRegistry, definition?: WorkflowDefinition): {
+    width: number;
+    height: number;
+};
+/** Longest-path ranks over next edges. */
+export declare function ranksOf(flow: WorkflowFlow): Map<string, number>;
+/**
+ * A layered layout, left to right along the run. Every node gets a position;
+ * `keep` (the default) lets a node's stored `at` win, so only new nodes move.
+ */
+export declare function layoutFlow(flow: WorkflowFlow, registry: WorkflowRegistry, options?: {
+    keep?: boolean;
+    definition?: WorkflowDefinition;
+}): Record<string, WorkflowPosition>;
+/** The flow with every node placed by the layered layout, stored positions replaced. */
+export declare function arrangeFlow(flow: WorkflowFlow, registry: WorkflowRegistry, definition?: WorkflowDefinition): WorkflowFlow;
+/** A part of a flow that folds into one: a loop's body or a fan-out's branches. */
+export interface WorkflowRegion {
+    /** `loop:<from>><to>` or `branches:<fan-out id>`. */
+    id: string;
+    kind: "loop" | "branches";
+    /** The node it is named after: the loop's first node, or the fan-out. */
+    head: string;
+    members: readonly string[];
+}
+/**
+ * The regions of a flow: each loop's body (from where it returns to where it
+ * leaves) and each fan-out's branches up to their nearest join. Regions that
+ * overlap without nesting are dropped, so they always form a tree.
+ */
+export declare function regionsOf(flow: WorkflowFlow): WorkflowRegion[];

package/dist/workflow/layout.js

@@ -0,0 +1,162 @@
+/**
+ * Where a flow's nodes sit on the canvas, and the parts of it that fold into
+ * one: node sizes from their ports, a layered layout along the run (ranks by
+ * longest path over next edges, two barycentre sweeps to untangle branches),
+ * and the regions a person can collapse (a loop's body, a fan-out's branches
+ * up to their join). Pure.
+ */
+import { downstream, exitsOf, inputsOf, outputsOf, upstream, } from "./definition.js";
+export const NODE_WIDTH = 224;
+/** The header: kind, label, summary. */
+export const NODE_HEADER = 76;
+/** One port row below the header. */
+export const PORT_ROW = 22;
+const GAP_ALONG = 72;
+const GAP_ACROSS = 40;
+/** The rows a node draws below its header: inputs on the left; exits (when it has several) and outputs on the right. */
+export function portRows(node, registry, definition) {
+    const exits = exitsOf(node);
+    return {
+        left: inputsOf(node, registry, definition).length,
+        right: (exits.length > 1 ? exits.length : 0) + outputsOf(node, registry, definition).length,
+    };
+}
+export function nodeSize(node, registry, definition) {
+    const { left, right } = portRows(node, registry, definition);
+    const rows = Math.max(left, right);
+    return { width: NODE_WIDTH, height: NODE_HEADER + (rows ? rows * PORT_ROW + 8 : 0) };
+}
+/** Longest-path ranks over next edges. */
+export function ranksOf(flow) {
+    const rank = new Map(flow.nodes.map((n) => [n.id, 0]));
+    const next = flow.edges.filter((e) => e.kind === "next" && rank.has(e.from) && rank.has(e.to));
+    for (let pass = 0; pass < flow.nodes.length; pass++) {
+        let changed = false;
+        for (const e of next) {
+            const want = (rank.get(e.from) ?? 0) + 1;
+            if (want > (rank.get(e.to) ?? 0)) {
+                rank.set(e.to, want);
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    return rank;
+}
+/**
+ * A layered layout, left to right along the run. Every node gets a position;
+ * `keep` (the default) lets a node's stored `at` win, so only new nodes move.
+ */
+export function layoutFlow(flow, registry, options = {}) {
+    const keep = options.keep ?? true;
+    const rank = ranksOf(flow);
+    const byRank = [];
+    for (const n of flow.nodes)
+        (byRank[rank.get(n.id) ?? 0] ??= []).push(n.id);
+    for (let r = 0; r < byRank.length; r++)
+        byRank[r] ??= [];
+    const order = new Map();
+    byRank.forEach((ids) => ids.forEach((id, i) => order.set(id, i)));
+    const next = flow.edges.filter((e) => e.kind === "next");
+    for (let sweep = 0; sweep < 2; sweep++)
+        for (let r = 1; r < byRank.length; r++) {
+            const bary = (id) => {
+                const ins = next
+                    .filter((e) => e.to === id && rank.get(e.from) === r - 1)
+                    .map((e) => order.get(e.from) ?? 0);
+                return ins.length ? ins.reduce((a, b) => a + b, 0) / ins.length : (order.get(id) ?? 0);
+            };
+            const sorted = [...(byRank[r] ?? [])].sort((a, b) => bary(a) - bary(b) || (order.get(a) ?? 0) - (order.get(b) ?? 0));
+            byRank[r] = sorted;
+            sorted.forEach((id, i) => order.set(id, i));
+        }
+    const size = new Map(flow.nodes.map((n) => [n.id, nodeSize(n, registry, options.definition)]));
+    const heights = byRank.map((ids) => ids.reduce((sum, id, i) => sum + (size.get(id)?.height ?? 0) + (i ? GAP_ACROSS : 0), 0));
+    const tallest = Math.max(0, ...heights);
+    const out = {};
+    byRank.forEach((ids, r) => {
+        let y = (tallest - (heights[r] ?? 0)) / 2;
+        for (const id of ids) {
+            out[id] = { x: r * (NODE_WIDTH + GAP_ALONG), y: Math.round(y) };
+            y += (size.get(id)?.height ?? 0) + GAP_ACROSS;
+        }
+    });
+    if (keep)
+        for (const n of flow.nodes)
+            if (n.at)
+                out[n.id] = n.at;
+    return out;
+}
+/** The flow with every node placed by the layered layout, stored positions replaced. */
+export function arrangeFlow(flow, registry, definition) {
+    const at = layoutFlow(flow, registry, { keep: false, definition });
+    return { ...flow, nodes: flow.nodes.map((n) => ({ ...n, at: at[n.id] ?? n.at })) };
+}
+/**
+ * The regions of a flow: each loop's body (from where it returns to where it
+ * leaves) and each fan-out's branches up to their nearest join. Regions that
+ * overlap without nesting are dropped, so they always form a tree.
+ */
+export function regionsOf(flow) {
+    const found = [];
+    for (const e of flow.edges) {
+        if (e.kind !== "loop")
+            continue;
+        const down = downstream(flow, e.to);
+        const up = upstream(flow, e.from);
+        const members = [
+            e.to,
+            ...flow.nodes.map((n) => n.id).filter((id) => down.has(id) && up.has(id)),
+            e.from,
+        ];
+        const unique = [...new Set(members)];
+        if (unique.length >= 2)
+            found.push({ id: `loop:${e.from}>${e.to}`, kind: "loop", head: e.to, members: unique });
+    }
+    for (const n of flow.nodes) {
+        if (n.kind !== "fanout")
+            continue;
+        const dist = new Set([n.id]);
+        const queue = [n.id];
+        let join = null;
+        while (queue.length && !join) {
+            const id = queue.shift();
+            for (const e of flow.edges)
+                if (e.kind === "next" && e.from === id && !dist.has(e.to)) {
+                    dist.add(e.to);
+                    if (flow.nodes.find((x) => x.id === e.to)?.kind === "join") {
+                        join = e.to;
+                        break;
+                    }
+                    queue.push(e.to);
+                }
+        }
+        if (!join)
+            continue;
+        const down = downstream(flow, n.id);
+        const up = upstream(flow, join);
+        const members = [
+            n.id,
+            ...flow.nodes.map((x) => x.id).filter((id) => down.has(id) && up.has(id)),
+            join,
+        ];
+        found.push({
+            id: `branches:${n.id}`,
+            kind: "branches",
+            head: n.id,
+            members: [...new Set(members)],
+        });
+    }
+    found.sort((a, b) => b.members.length - a.members.length);
+    const kept = [];
+    for (const r of found) {
+        const ok = kept.every((k) => {
+            const shared = r.members.filter((id) => k.members.includes(id)).length;
+            return shared === 0 || shared === r.members.length || shared === k.members.length;
+        });
+        if (ok && !kept.some((k) => k.id === r.id))
+            kept.push(r);
+    }
+    return kept;
+}

package/dist/workflow/model.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The shared workflow model: what a host hands the workflow components. It is
+ * module-neutral. A module (software, content, media, legal, paperwork, a
+ * process) is a label and a version the host supplies; nothing here assumes
+ * tickets, repositories, branches or code. Pure: no hooks, no browser APIs.
+ */
+/** A saved definition's publication state. */
+export type WorkflowStatus = "draft" | "published";
+/** Who can see and use a saved definition. */
+export type WorkflowScope = "private" | "project" | "organization" | "shared";
+/** The module a workflow belongs to, as the host names it. */
+export interface WorkflowModule {
+    /** Stable key, for filters ("media", "legal"). */
+    id: string;
+    /** Display name, in the host's copy ("Media", "Legal review"). */
+    label: string;
+    /** The module version the definition was written against. */
+    version?: string;
+}
+/**
+ * Whether this factory can run the workflow, as the host has established it.
+ * `unsupported`: the module is not installed or not qualified here.
+ * `missing-capabilities`: the module is present but a capability it needs is not.
+ * Only `available` lets a start action be enabled; the host still owns
+ * authorization and execution.
+ */
+export interface WorkflowAvailability {
+    status: "available" | "unsupported" | "missing-capabilities";
+    /** The capabilities this destination lacks, by display name. */
+    missing?: readonly string[];
+    /** The host's own explanation, shown in place of the default. */
+    reason?: string;
+}
+/** One saved, reusable workflow definition, as a gallery shows it. */
+export interface WorkflowSummary {
+    /** Stable across revisions. */
+    id: string;
+    name: string;
+    description?: string;
+    module: WorkflowModule;
+    /** The definition's revision, as the host labels it ("12", "2026-11-14.3"). */
+    revision?: string;
+    scope: WorkflowScope;
+    status: WorkflowStatus;
+    availability: WorkflowAvailability;
+}
+/** The actions a workflow card can offer. */
+export type WorkflowAction = "edit" | "start" | "export";
+/** What the person may do, as the host's authorization says. Omitted means allowed. */
+export type WorkflowPermissions = Partial<Record<WorkflowAction, boolean>>;

package/dist/workflow/model.js

@@ -0,0 +1,7 @@
+/**
+ * The shared workflow model: what a host hands the workflow components. It is
+ * module-neutral. A module (software, content, media, legal, paperwork, a
+ * process) is a label and a version the host supplies; nothing here assumes
+ * tickets, repositories, branches or code. Pure: no hooks, no browser APIs.
+ */
+export {};

package/dist/workflow/palette.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What can be added to a flow, grouped as the palette and the canvas's add
+ * menu show it: each module's step presets, then gates by kind, logic, and
+ * judges, then a custom step and a sub-flow. Pure.
+ */
+import { type WorkflowDefinition, type WorkflowNode, type WorkflowNodeTemplate, type WorkflowRegistry } from "./definition.js";
+export interface WorkflowPaletteItem {
+    /** Unique across the palette. */
+    key: string;
+    template: WorkflowNodeTemplate;
+    /** The preset's or gate kind's own words; empty for a bare kind, which the caller's copy names. */
+    label: string;
+    hint?: string;
+    /** Whether this destination runs it; an unavailable item can still be added. */
+    available: boolean;
+}
+export interface WorkflowPaletteGroup {
+    /** A module id, or `gates`, `logic`, `judges`, `other`. */
+    key: string;
+    /** A module's label; empty for the fixed groups, which the caller's copy names. */
+    label: string;
+    module: boolean;
+    items: WorkflowPaletteItem[];
+}
+export declare function paletteOf(registry: WorkflowRegistry): WorkflowPaletteGroup[];
+/**
+ * The definition with a palette item added to a flow, after `after` (or the
+ * flow's last node) on its first free exit, placed one column to its right.
+ * `name` is the caller's copy for an item with no label of its own.
+ */
+export declare function insertPaletteItem(definition: WorkflowDefinition, flowName: string, item: WorkflowPaletteItem, registry: WorkflowRegistry, name: string, after?: string | null): {
+    definition: WorkflowDefinition;
+    node: WorkflowNode;
+};

package/dist/workflow/palette.js

@@ -0,0 +1,70 @@
+/**
+ * What can be added to a flow, grouped as the palette and the canvas's add
+ * menu show it: each module's step presets, then gates by kind, logic, and
+ * judges, then a custom step and a sub-flow. Pure.
+ */
+import { addNode, createNode, freshId, withFlow, } from "./definition.js";
+import { NODE_WIDTH, layoutFlow } from "./layout.js";
+const LOGIC = ["condition", "goto", "fanout", "join", "variants"];
+const JUDGES = ["evaluator", "classifier", "check"];
+export function paletteOf(registry) {
+    const runs = (kind) => (registry.nodeKinds?.[kind]?.status ?? "available") === "available";
+    const bare = (kind) => ({
+        key: kind,
+        template: { kind },
+        label: "",
+        available: runs(kind),
+    });
+    const modules = registry.modules.map((m) => ({
+        key: m.id,
+        label: m.label,
+        module: true,
+        items: m.presets.map((p) => ({
+            key: `${m.id}/${p.id}`,
+            template: { kind: "step", preset: { module: m.id, id: p.id } },
+            label: p.label,
+            ...(p.hint ? { hint: p.hint } : {}),
+            available: runs("step") &&
+                (m.availability?.status ?? "available") === "available" &&
+                (!registry.capabilities ||
+                    (p.capabilities ?? []).every((c) => registry.capabilities?.includes(c))),
+        })),
+    }));
+    return [
+        ...modules.filter((m) => m.items.length),
+        {
+            key: "gates",
+            label: "",
+            module: false,
+            items: registry.gateKinds.map((g) => ({
+                key: `gate/${g.id}`,
+                template: { kind: "gate", gate: g.id },
+                label: g.label,
+                ...(g.hint ? { hint: g.hint } : {}),
+                available: runs("gate") &&
+                    (g.availability?.status ?? "available") === "available" &&
+                    (!registry.capabilities ||
+                        (g.capabilities ?? []).every((c) => registry.capabilities?.includes(c))),
+            })),
+        },
+        { key: "logic", label: "", module: false, items: LOGIC.map(bare) },
+        { key: "judges", label: "", module: false, items: JUDGES.map(bare) },
+        { key: "other", label: "", module: false, items: [bare("step"), bare("subflow")] },
+    ].filter((g) => g.items.length);
+}
+/**
+ * The definition with a palette item added to a flow, after `after` (or the
+ * flow's last node) on its first free exit, placed one column to its right.
+ * `name` is the caller's copy for an item with no label of its own.
+ */
+export function insertPaletteItem(definition, flowName, item, registry, name, after) {
+    const flow = definition.flows[flowName] ?? { nodes: [], edges: [] };
+    const id = freshId(item.label || name, Object.values(definition.flows).flatMap((f) => f.nodes.map((n) => n.id)));
+    const prev = flow.nodes.find((n) => n.id === after) ?? flow.nodes.at(-1);
+    const base = prev ? layoutFlow(flow, registry, { definition })[prev.id] : undefined;
+    const node = {
+        ...createNode(item.template, id, registry, item.label || name),
+        ...(base ? { at: { x: base.x + NODE_WIDTH + 72, y: base.y } } : {}),
+    };
+    return { definition: withFlow(definition, flowName, addNode(flow, node, prev?.id)), node };
+}