@calliopelabs/ui 0.12.0 → 0.14.0

package/dist/workflow/canvas/WorkflowCanvas.js

@@ -191,6 +191,35 @@ function CanvasInner({ definition, flow: flowProp, registry, onChange, readOnly:
         const y = b.height * zoom <= h - pad * 2 ? (h - b.height * zoom) / 2 - b.y * zoom : pad - b.y * zoom;
         void view.setViewport({ x, y, zoom });
     }, [view]);
+    /**
+     * Centers a node that is out of view at the current zoom. `whole`: unless
+     * all of it shows (a deep link); otherwise unless its middle shows, so
+     * choosing a node at the edge does not move the canvas.
+     */
+    const reveal = React.useCallback((id, whole = false) => {
+        const el = pane.current;
+        const n = view.getInternalNode(id);
+        if (!el || !n || !el.clientWidth || !el.clientHeight)
+            return;
+        const { x, y, zoom } = view.getViewport();
+        const w = n.measured.width ?? 0;
+        const h = n.measured.height ?? 0;
+        const left = n.internals.positionAbsolute.x * zoom + x;
+        const top = n.internals.positionAbsolute.y * zoom + y;
+        const [x0, y0, x1, y1] = whole
+            ? [left, top, left + w * zoom, top + h * zoom]
+            : [
+                left + (w * zoom) / 2,
+                top + (h * zoom) / 2,
+                left + (w * zoom) / 2,
+                top + (h * zoom) / 2,
+            ];
+        if (x0 >= 0 && y0 >= 0 && x1 <= el.clientWidth && y1 <= el.clientHeight)
+            return;
+        const cx = n.internals.positionAbsolute.x + w / 2;
+        const cy = n.internals.positionAbsolute.y + h / 2;
+        void view.setCenter(cx, cy, { zoom });
+    }, [view]);
     const flowName = flowProp && definition.flows[flowProp] ? flowProp : definition.main;
     const flow = definition.flows[flowName] ?? EMPTY_FLOW;
     const readOnly = readOnlyProp || !onChange;
@@ -218,6 +247,17 @@ function CanvasInner({ definition, flow: flowProp, registry, onChange, readOnly:
     const selectedNode = selection?.type === "node" && selection.flow === flowName
         ? flow.nodes.find((n) => n.id === selection.id)
         : undefined;
+    // A node selected from outside the canvas (a deep link, a problem) comes into view.
+    const selectedId = selectedNode?.id;
+    React.useEffect(() => {
+        if (selectedId)
+            reveal(selectedId);
+    }, [selectedId, reveal]);
+    const init = React.useCallback(() => {
+        place();
+        if (selectedId)
+            reveal(selectedId, true);
+    }, [place, reveal, selectedId]);
     const selectedEdge = selection?.type === "edge" && selection.flow === flowName
         ? flow.edges.find((e) => edgeId(e) === selection.id)
         : undefined;
@@ -624,7 +664,7 @@ function CanvasInner({ definition, flow: flowProp, registry, onChange, readOnly:
                                                                 : m.kind(item.template.kind)), item.available ? null : (_jsx("span", { className: "ml-auto text-2xs text-muted-foreground", children: m.notRun }))] }, item.key)))] }, g.key))) })] }), _jsxs(Button, { size: "sm", variant: "outline", disabled: !selectedNode, onClick: () => setConnecting(true), children: [_jsx(CableIcon, { "aria-hidden": true }), m.connectAction] }), _jsxs(Button, { size: "sm", variant: "outline", disabled: !selectedNode && !selectedEdge, onClick: () => remove(selectedNode ? [selectedNode.id] : [], selectedEdge ? [edgeId(selectedEdge)] : []), children: [_jsx(Trash2Icon, { "aria-hidden": true }), m.deleteSelection] }), _jsxs(Button, { size: "sm", variant: "outline", disabled: !flow.nodes.length, onClick: () => {
                                     change(arrangeFlow(flow, registry, definition));
                                     window.requestAnimationFrame(place);
-                                }, children: [_jsx(LayoutGridIcon, { "aria-hidden": true }), m.arrange] })] })), _jsxs("span", { className: "ml-auto flex items-center gap-1", children: [_jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": m.zoomOut, title: m.zoomOut, onClick: () => void view.zoomOut(), children: _jsx(ZoomOutIcon, { "aria-hidden": true }) }), _jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": m.zoomIn, title: m.zoomIn, onClick: () => void view.zoomIn(), children: _jsx(ZoomInIcon, { "aria-hidden": true }) }), _jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": m.fit, title: m.fit, onClick: place, children: _jsx(MaximizeIcon, { "aria-hidden": true }) })] })] }), _jsx("div", { ref: pane, className: "relative min-h-0 flex-1", children: _jsx(ReactFlow, { nodes: nodes, edges: built.edges, nodeTypes: NODE_TYPES, onInit: place, minZoom: READABLE_ZOOM, maxZoom: 1.5, panOnScroll: true, snapToGrid: true, snapGrid: [GRID, GRID], nodesDraggable: !readOnly, nodesConnectable: !readOnly, nodesFocusable: true, edgesFocusable: true, elementsSelectable: true, multiSelectionKeyCode: null, selectionKeyCode: null, deleteKeyCode: readOnly ? null : ["Backspace", "Delete"], ariaLabelConfig: {
+                                }, children: [_jsx(LayoutGridIcon, { "aria-hidden": true }), m.arrange] })] })), _jsxs("span", { className: "ml-auto flex items-center gap-1", children: [_jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": m.zoomOut, title: m.zoomOut, onClick: () => void view.zoomOut(), children: _jsx(ZoomOutIcon, { "aria-hidden": true }) }), _jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": m.zoomIn, title: m.zoomIn, onClick: () => void view.zoomIn(), children: _jsx(ZoomInIcon, { "aria-hidden": true }) }), _jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": m.fit, title: m.fit, onClick: place, children: _jsx(MaximizeIcon, { "aria-hidden": true }) })] })] }), _jsx("div", { ref: pane, className: "relative min-h-0 flex-1", children: _jsx(ReactFlow, { nodes: nodes, edges: built.edges, nodeTypes: NODE_TYPES, onInit: init, minZoom: READABLE_ZOOM, maxZoom: 1.5, panOnScroll: true, snapToGrid: true, snapGrid: [GRID, GRID], nodesDraggable: !readOnly, nodesConnectable: !readOnly, nodesFocusable: true, edgesFocusable: true, elementsSelectable: true, multiSelectionKeyCode: null, selectionKeyCode: null, deleteKeyCode: readOnly ? null : ["Backspace", "Delete"], ariaLabelConfig: {
                         "node.a11yDescription.default": m.nodeHelp,
                         "node.a11yDescription.keyboardDisabled": m.nodeHelp,
                         "node.a11yDescription.ariaLiveMessage": ({ direction, x, y }) => m.movedLive(direction, x, y),

package/dist/workflow/definition.d.ts

@@ -405,4 +405,24 @@ export interface WorkflowSelection {
     flow: string;
     id: string;
 }
+/** A flow's name, its key in `flows`: a lowercase slug of up to 32 characters ("build", "escalation"). */
+export declare const WORKFLOW_FLOW_NAME: RegExp;
+/** The most flows one definition holds. */
+export declare const WORKFLOW_MAX_FLOWS = 20;
+/** Why a flow name is refused. The editor's copy names each one. */
+export type WorkflowFlowNameProblem = "empty" | "format" | "taken";
+/**
+ * Whether `name` can name a flow of the definition: a slug by
+ * `WORKFLOW_FLOW_NAME` that no other flow has. `current` is the flow being
+ * renamed, which may keep its own name. Null when it can.
+ */
+export declare function flowNameProblem(definition: WorkflowDefinition, name: string, current?: string): WorkflowFlowNameProblem | null;
+/** The definition with a new, empty flow. A label that is empty is left out. */
+export declare function addFlow(definition: WorkflowDefinition, name: string, label?: string): WorkflowDefinition;
+/**
+ * Renames a flow everywhere the definition names it: its key, `main`, and
+ * the sub-flow nodes that run it. `label` replaces the flow's label; an empty
+ * one removes it; omitted, the label stays. Flows keep their order.
+ */
+export declare function renameFlow(definition: WorkflowDefinition, from: string, to: string, label?: string): WorkflowDefinition;
 export {};

package/dist/workflow/definition.js

@@ -409,3 +409,47 @@ export function updateEdge(flow, id, patch) {
 export function withFlow(definition, name, flow) {
     return { ...definition, flows: { ...definition.flows, [name]: flow } };
 }
+// ---------------------------------------------------------------- flows
+/** A flow's name, its key in `flows`: a lowercase slug of up to 32 characters ("build", "escalation"). */
+export const WORKFLOW_FLOW_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/** The most flows one definition holds. */
+export const WORKFLOW_MAX_FLOWS = 20;
+/**
+ * Whether `name` can name a flow of the definition: a slug by
+ * `WORKFLOW_FLOW_NAME` that no other flow has. `current` is the flow being
+ * renamed, which may keep its own name. Null when it can.
+ */
+export function flowNameProblem(definition, name, current) {
+    if (!name)
+        return "empty";
+    if (!WORKFLOW_FLOW_NAME.test(name))
+        return "format";
+    if (name !== current && Object.hasOwn(definition.flows, name))
+        return "taken";
+    return null;
+}
+/** The definition with a new, empty flow. A label that is empty is left out. */
+export function addFlow(definition, name, label) {
+    const flow = { ...(label ? { label } : {}), nodes: [], edges: [] };
+    return withFlow(definition, name, flow);
+}
+/**
+ * Renames a flow everywhere the definition names it: its key, `main`, and
+ * the sub-flow nodes that run it. `label` replaces the flow's label; an empty
+ * one removes it; omitted, the label stays. Flows keep their order.
+ */
+export function renameFlow(definition, from, to, label) {
+    if (!definition.flows[from])
+        return definition;
+    const flows = {};
+    for (const [name, f] of Object.entries(definition.flows)) {
+        const nodes = f.nodes.map((n) => n.kind === "subflow" && n.flow === from ? { ...n, flow: to } : n);
+        let flow = { ...f, nodes };
+        if (name === from && label !== undefined) {
+            const { label: _old, ...rest } = flow;
+            flow = label ? { ...rest, label } : rest;
+        }
+        flows[name === from ? to : name] = flow;
+    }
+    return { ...definition, main: definition.main === from ? to : definition.main, flows };
+}

package/dist/workflow/editor/WorkflowInspector.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { type WorkflowCondition, type WorkflowDefinition, type WorkflowFlow, type WorkflowGatePolicy, type WorkflowRegistry, type WorkflowSelection } from "../definition.js";
+import { type WorkflowCondition, type WorkflowDefinition, type WorkflowFlow, type WorkflowGatePolicy, type WorkflowNode, type WorkflowRegistry, type WorkflowSelection } from "../definition.js";
 export interface WorkflowInspectorProps {
     definition: WorkflowDefinition;
     registry: WorkflowRegistry;
@@ -9,8 +9,25 @@ export interface WorkflowInspectorProps {
     /** After a delete from the inspector, the selection is cleared through this. */
     onSelectionChange?: (selection: WorkflowSelection | null) => void;
     readOnly?: boolean;
+    /**
+     * The host's own fields for the selected node, after the fields of its
+     * kind: a runner picker, what a step inherits. Switch on `node.kind`;
+     * return null to add nothing. It is called while the inspector renders, so
+     * fields that need hooks go in a component it returns.
+     */
+    renderNodeFields?: (context: WorkflowNodeFieldsContext) => React.ReactNode;
     className?: string;
 }
+/** What the inspector hands `renderNodeFields`. */
+export interface WorkflowNodeFieldsContext {
+    node: WorkflowNode;
+    /** The flow the node is in. */
+    flow: string;
+    definition: WorkflowDefinition;
+    /** Patches the node, as the inspector's own fields do. Does nothing when read only. */
+    onChange: (patch: Partial<WorkflowNode>) => void;
+    readOnly: boolean;
+}
 /** One comparison on a run fact: the fact, its node when it is a node's, the operator and the value. */
 export declare function ConditionEditor({ condition, onChange, flow, registry, label, disabled, }: {
     condition: WorkflowCondition;
@@ -34,7 +51,8 @@ export declare function GatePolicyEditor({ policy, onChange, registry, approvers
  * The selected node's or connection's fields, edited in place: per-kind
  * fields, a condition editor over the host's facts and operators, a gate
  * policy editor (roles, members, quorum, timeout), and the host's model,
- * harness and effort pickers. With nothing selected, the workflow's name and
+ * harness and effort pickers, then any fields the host adds for the node
+ * (`renderNodeFields`). With nothing selected, the workflow's name and
  * description. Every edit goes out as the whole next definition.
  */
-export declare function WorkflowInspector({ definition, registry, selection, onChange, onSelectionChange, readOnly, className, }: WorkflowInspectorProps): React.JSX.Element;
+export declare function WorkflowInspector({ definition, registry, selection, onChange, onSelectionChange, readOnly, renderNodeFields, className, }: WorkflowInspectorProps): React.JSX.Element;

package/dist/workflow/editor/WorkflowInspector.js

@@ -149,10 +149,11 @@ function PortsEditor({ legend, ports, onChange, registry, disabled, }) {
  * The selected node's or connection's fields, edited in place: per-kind
  * fields, a condition editor over the host's facts and operators, a gate
  * policy editor (roles, members, quorum, timeout), and the host's model,
- * harness and effort pickers. With nothing selected, the workflow's name and
+ * harness and effort pickers, then any fields the host adds for the node
+ * (`renderNodeFields`). With nothing selected, the workflow's name and
  * description. Every edit goes out as the whole next definition.
  */
-export function WorkflowInspector({ definition, registry, selection = null, onChange, onSelectionChange, readOnly = false, className, }) {
+export function WorkflowInspector({ definition, registry, selection = null, onChange, onSelectionChange, readOnly = false, renderNodeFields, className, }) {
     const { messages } = useUI();
     const m = messages.editor;
     const disabled = readOnly || !onChange;
@@ -165,7 +166,14 @@ export function WorkflowInspector({ definition, registry, selection = null, onCh
     let title;
     if (node) {
         title = m.inspectorFor(m.kind(node.kind), node.label);
-        body = (_jsx(NodeFields, { node: node, flow: flow, definition: definition, registry: registry, disabled: disabled, onPatch: (patch) => setFlow(updateNode(flow, node.id, patch)), onDelete: () => {
+        const patch = (p) => setFlow(updateNode(flow, node.id, p));
+        body = (_jsx(NodeFields, { node: node, flow: flow, definition: definition, registry: registry, disabled: disabled, host: renderNodeFields?.({
+                node,
+                flow: flowName,
+                definition,
+                onChange: disabled ? () => { } : patch,
+                readOnly: disabled,
+            }), onPatch: patch, onDelete: () => {
                 setFlow(removeNode(flow, node.id));
                 onSelectionChange?.(null);
             } }));
@@ -187,7 +195,7 @@ export function WorkflowInspector({ definition, registry, selection = null, onCh
     }
     return (_jsxs("section", { "aria-label": m.inspector, "data-slot": "workflow-inspector", className: cn("flex min-h-0 flex-col gap-3", className), children: [_jsx("h2", { className: "truncate text-sm font-medium", children: title }), _jsx("div", { className: "flex min-h-0 flex-col gap-4 overflow-y-auto pb-2", children: body })] }));
 }
-function NodeFields({ node, flow, definition, registry, disabled, onPatch, onDelete, }) {
+function NodeFields({ node, flow, definition, registry, disabled, host, onPatch, onDelete, }) {
     const { messages } = useUI();
     const m = messages.editor;
     const presetOptions = registry.modules.flatMap((mod) => mod.presets.map((p) => ({ value: `${mod.id}/${p.id}`, label: `${mod.label} · ${p.label}` })));
@@ -327,7 +335,7 @@ function NodeFields({ node, flow, definition, registry, disabled, onPatch, onDel
             fields = (_jsxs(_Fragment, { children: [_jsx(Field, { label: m.question, children: _jsx(Textarea, { value: node.question, disabled: disabled, onChange: (e) => onPatch({ question: e.target.value }) }) }), _jsx(Field, { label: m.yesAt, children: _jsx(PercentInput, { value: node.threshold, disabled: disabled, onValue: (threshold) => onPatch({ threshold: threshold ?? 0.5 }) }) })] }));
             break;
     }
-    return (_jsxs("div", { className: "flex flex-col gap-4", children: [common, fields, _jsx(Field, { label: m.note, children: _jsx(Textarea, { value: node.note ?? "", disabled: disabled, onChange: (e) => onPatch({ note: e.target.value || undefined }) }) }), disabled ? null : (_jsxs(Button, { type: "button", variant: "destructive", size: "sm", className: "self-start", onClick: onDelete, children: [_jsx(Trash2Icon, { "aria-hidden": true }), m.deleteNode(node.label)] }))] }));
+    return (_jsxs("div", { className: "flex flex-col gap-4", children: [common, fields, host == null || host === false ? null : (_jsx("div", { "data-slot": "workflow-inspector-host-fields", className: "flex flex-col gap-4", children: host })), _jsx(Field, { label: m.note, children: _jsx(Textarea, { value: node.note ?? "", disabled: disabled, onChange: (e) => onPatch({ note: e.target.value || undefined }) }) }), disabled ? null : (_jsxs(Button, { type: "button", variant: "destructive", size: "sm", className: "self-start", onClick: onDelete, children: [_jsx(Trash2Icon, { "aria-hidden": true }), m.deleteNode(node.label)] }))] }));
 }
 /** A preset's contract, read from the registry. */
 function PortSummary({ node, definition, registry, }) {

package/dist/workflow/editor/WorkflowWorkspace.d.ts

@@ -1,7 +1,8 @@
 import * as React from "react";
-import type { WorkflowDefinition, WorkflowRegistry } from "../definition.js";
+import { type WorkflowDefinition, type WorkflowRegistry, type WorkflowSelection } from "../definition.js";
 import { type WorkflowImportSummary as ImportPreview } from "../portable.js";
 import { type WorkflowRevision } from "../workspace.js";
+import { type WorkflowInspectorProps } from "./WorkflowInspector.js";
 /** A host action: may return a promise; a rejection's message is shown. */
 type HostAction<A extends unknown[]> = (...args: A) => Promise<unknown> | unknown;
 export interface WorkflowWorkspaceProps {
@@ -26,6 +27,28 @@ export interface WorkflowWorkspaceProps {
     importPreview?: ImportPreview | null;
     onImportConfirm?: HostAction<[]>;
     onImportCancel?: () => void;
+    /**
+     * What is selected, held by the host: a deep link to a node opens its flow
+     * with the node selected and in view. Uncontrolled when omitted.
+     */
+    selection?: WorkflowSelection | null;
+    /** Where the editor opens when the host does not hold the selection. */
+    defaultSelection?: WorkflowSelection | null;
+    onSelectionChange?: (selection: WorkflowSelection | null) => void;
+    /**
+     * Offers New flow. The workspace asks for a name (`WORKFLOW_FLOW_NAME`, not
+     * taken) and an optional label, and hands the host the definition with the
+     * flow added. The host applies it, with anything it keeps beside it.
+     */
+    onFlowCreate?: HostAction<[definition: WorkflowDefinition, name: string]>;
+    /**
+     * Offers Rename flow, for the open flow. The definition handed over has the
+     * flow renamed everywhere it names it (`renameFlow`): its key, `main` and
+     * the sub-flow nodes that run it. Anything else that names flows is the host's.
+     */
+    onFlowRename?: HostAction<[definition: WorkflowDefinition, from: string, to: string]>;
+    /** The host's own fields for the selected node in the inspector. */
+    renderNodeFields?: WorkflowInspectorProps["renderNodeFields"];
     readOnly?: boolean;
     loading?: boolean;
     error?: string | {
@@ -42,8 +65,10 @@ export interface WorkflowWorkspaceProps {
  * 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.
+ * save as, import and export are the host's; it never persists anything. A
+ * host may hold the selection (deep links), let people add and rename flows,
+ * and add its own fields to the inspector. On narrow containers the palette
+ * and the side panel open as drawers.
  */
 export declare function WorkflowWorkspace(props: WorkflowWorkspaceProps): React.JSX.Element;
 export {};

package/dist/workflow/editor/WorkflowWorkspace.js

@@ -1,6 +1,6 @@
 "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 { CopyPlusIcon, DownloadIcon, ListTreeIcon, PanelRightIcon, PencilIcon, PlusIcon, RocketIcon, SaveIcon, UndoIcon, UploadIcon, } from "lucide-react";
 import * as React from "react";
 import { cn } from "../../lib/cn.js";
 import { ConfirmDialog } from "../../overlays/ConfirmDialog.js";
@@ -16,6 +16,7 @@ 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 { WORKFLOW_MAX_FLOWS, addFlow, flowNameProblem, renameFlow, } from "../definition.js";
 import { insertPaletteItem } from "../palette.js";
 import { diffDefinitions, sameDefinition, } from "../portable.js";
 import { blockingProblems, checkDefinition } from "../problems.js";
@@ -26,6 +27,7 @@ import { WorkflowInspector } from "./WorkflowInspector.js";
 import { WorkflowJsonView } from "./WorkflowJsonView.js";
 import { WorkflowPalette } from "./WorkflowPalette.js";
 import { WorkflowProblems } from "./WorkflowProblems.js";
+const sameSelection = (a, b) => a === b || (!!a && !!b && a.type === b.type && a.flow === b.flow && a.id === b.id);
 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
@@ -35,8 +37,10 @@ const messageOf = (e) => (e instanceof Error ? e.message : typeof e === "string"
  * 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.
+ * save as, import and export are the host's; it never persists anything. A
+ * host may hold the selection (deep links), let people add and rename flows,
+ * and add its own fields to the inspector. On narrow containers the palette
+ * and the side panel open as drawers.
  */
 export function WorkflowWorkspace(props) {
     const { messages } = useUI();
@@ -46,14 +50,22 @@ export function WorkflowWorkspace(props) {
         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, }) {
+function Workspace({ definition, onChange, registry, saved = null, published = null, onSave, onPublish, onSaveAs, onExport, onImport, importPreview = null, onImportConfirm, onImportCancel, selection: selectionProp, defaultSelection = null, onSelectionChange, onFlowCreate, onFlowRename, renderNodeFields, 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 [ownSelection, setOwnSelection] = React.useState(defaultSelection);
+    const selection = selectionProp === undefined ? ownSelection : selectionProp;
+    const [flowName, setFlowName] = React.useState(selection?.flow ?? definition.main);
     const flow = definition.flows[flowName] ? flowName : definition.main;
-    const [selection, setSelection] = React.useState(null);
+    // A selection in another flow (the host's, or a problem's) opens that flow.
+    const [shown, setShown] = React.useState(selection);
+    if (!sameSelection(shown, selection)) {
+        setShown(selection);
+        if (selection && selection.flow !== flowName)
+            setFlowName(selection.flow);
+    }
     const [panel, setPanel] = React.useState("inspector");
     const [drawer, setDrawer] = React.useState(null);
     const [dialog, setDialog] = React.useState(null);
@@ -103,9 +115,15 @@ function Workspace({ definition, onChange, registry, saved = null, published = n
         }
     };
     const select = (s) => {
-        setSelection(s);
-        if (s && s.flow !== flow)
-            setFlowName(s.flow);
+        if (sameSelection(s, selection))
+            return;
+        if (selectionProp === undefined)
+            setOwnSelection(s);
+        onSelectionChange?.(s);
+    };
+    const openFlow = (next) => {
+        setFlowName(next);
+        select(null);
     };
     const add = (item) => {
         const label = item.label ||
@@ -120,7 +138,7 @@ function Workspace({ definition, onChange, registry, saved = null, published = n
     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) => {
+    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, renderNodeFields: renderNodeFields }) }), _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);
@@ -131,10 +149,13 @@ function Workspace({ definition, onChange, registry, saved = null, published = n
                                 }, 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 () => {
+                        }, 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: openFlow, options: flows.map(([key, f]) => ({ value: key, label: f.label ?? key })) })) : null, onFlowRename && !readOnly ? (_jsxs(Button, { size: "sm", variant: "ghost", disabled: busy !== null, onClick: () => {
+                                            setFailure(null);
+                                            setDialog("rename-flow");
+                                        }, children: [_jsx(PencilIcon, { "aria-hidden": true }), m.renameFlow] })) : null, onFlowCreate && !readOnly ? (_jsxs(Button, { size: "sm", variant: "ghost", disabled: busy !== null, onClick: () => {
+                                            setFailure(null);
+                                            setDialog("new-flow");
+                                        }, children: [_jsx(PlusIcon, { "aria-hidden": true }), m.newFlow] })) : 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) => {
@@ -147,8 +168,46 @@ function Workspace({ definition, onChange, registry, saved = null, published = n
                             }, 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
+                    select(null);
+                } }), _jsx(Dialog, { open: dialog === "new-flow" || dialog === "rename-flow", onOpenChange: (open) => !open && setDialog(null), children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: dialog === "rename-flow"
+                                        ? m.renameFlowTitle(definition.flows[flow]?.label ?? flow)
+                                        : m.newFlowTitle }), _jsx(DialogDescription, { children: dialog === "rename-flow" ? m.renameFlowDescription : m.newFlowDescription })] }), dialog === "new-flow" || dialog === "rename-flow" ? (_jsx(FlowForm, { definition: definition, current: dialog === "rename-flow" ? flow : undefined, busy: busy !== null, failure: failure, onCancel: () => setDialog(null), onSubmit: async (name, label) => {
+                                const renaming = dialog === "rename-flow";
+                                const done = renaming
+                                    ? await run("flow", () => onFlowRename?.(renameFlow(definition, flow, name, label), flow, name), m.flowRenamedNotice(name))
+                                    : await run("flow", () => onFlowCreate?.(addFlow(definition, name, label), name), m.flowCreatedNotice(name));
+                                if (!done)
+                                    return;
+                                setDialog(null);
+                                if (renaming && selection?.flow === flow)
+                                    select({ ...selection, flow: name });
+                                else if (!renaming)
+                                    select(null);
+                                setFlowName(name);
+                            } })) : 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] }) })] }));
 }
+/**
+ * A flow's name and label, checked as they are typed: a new flow, or the
+ * open one (`current`) being renamed. Holds its own state so typing does not
+ * redraw the canvas.
+ */
+function FlowForm({ definition, current, busy, failure, onCancel, onSubmit, }) {
+    const { messages } = useUI();
+    const m = messages.workspace;
+    const currentLabel = current ? (definition.flows[current]?.label ?? "") : "";
+    const [name, setName] = React.useState(current ?? "");
+    const [label, setLabel] = React.useState(currentLabel);
+    const [touched, setTouched] = React.useState(false);
+    const trimmed = name.trim();
+    const problem = flowNameProblem(definition, trimmed, current);
+    const full = !current && Object.keys(definition.flows).length >= WORKFLOW_MAX_FLOWS;
+    const unchanged = !!current && trimmed === current && label.trim() === currentLabel;
+    return (_jsxs("form", { className: "flex flex-col gap-4", noValidate: true, onSubmit: (e) => {
+            e.preventDefault();
+            setTouched(true);
+            if (!problem && !full && !unchanged)
+                onSubmit(trimmed, label.trim());
+        }, children: [_jsx(Field, { label: m.flowName, hint: m.flowNameHint, error: touched && problem ? m.flowNameProblem(problem) : undefined, required: true, children: _jsx(Input, { value: name, autoComplete: "off", spellCheck: false, onChange: (e) => setName(e.target.value), onBlur: () => setTouched(true) }) }), _jsx(Field, { label: m.flowLabel, hint: m.flowLabelHint, children: _jsx(Input, { value: label, onChange: (e) => setLabel(e.target.value) }) }), full ? (_jsx("p", { role: "alert", className: "text-sm text-danger-fg", children: m.flowsFull(WORKFLOW_MAX_FLOWS) })) : null, failure ? (_jsx("p", { role: "alert", className: "text-sm text-danger-fg", children: failure })) : null, _jsxs(DialogFooter, { children: [_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, children: messages.editor.cancel }), _jsx(Button, { type: "submit", disabled: full || unchanged || busy, children: busy ? m.saving : current ? m.rename : m.createFlow })] })] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calliopelabs/ui",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Calliope AI shared operator UI: app shell, navigation, page frame, data table and list patterns, status colours, design tokens and appearance for Astrolift AI and Zentinelle AI.",
   "keywords": [
     "calliope-ai",
@@ -30,12 +30,32 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "default": "./dist/agent/index.js"
+    },
+    "./agent/copilotkit": {
+      "types": "./dist/agent/copilotkit/index.d.ts",
+      "default": "./dist/agent/copilotkit/index.js"
+    },
     "./theme.css": "./dist/styles/theme.css",
     "./preset.css": "./dist/styles/preset.css",
     "./css/tokens.css": "./dist/css/tokens.css",
     "./css/appearance.js": "./dist/css/appearance.js",
     "./css/components.css": "./dist/css/components.css",
     "./css/calliope.css": "./dist/css/calliope.css",
+    "./tokens/jupyterlab.css": "./dist/tokens/jupyterlab.css",
+    "./tokens/vscode.css": "./dist/tokens/vscode.css",
+    "./tokens/plain.css": "./dist/tokens/plain.css",
+    "./tokens/tokens.py": "./dist/tokens/tokens.py",
+    "./tokens/native": {
+      "types": "./dist/tokens/tokens.native.d.ts",
+      "default": "./dist/tokens/tokens.native.js"
+    },
+    "./tokens/tokens.native.js": {
+      "types": "./dist/tokens/tokens.native.d.ts",
+      "default": "./dist/tokens/tokens.native.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
@@ -59,6 +79,7 @@
     "build-storybook": "storybook build --quiet"
   },
   "dependencies": {
+    "@ag-ui/core": "~1.0.3",
     "@xyflow/react": "^12.12.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -67,11 +88,14 @@
     "tailwind-merge": "^3.7.0"
   },
   "devDependencies": {
+    "@ag-ui/client": "1.0.2",
+    "@copilotkit/react-core": "1.88.0",
     "@eslint/js": "^9.39.5",
     "@fontsource-variable/dm-sans": "^5.3.0",
     "@fontsource/ibm-plex-mono": "^5.3.0",
     "@fontsource/ibm-plex-sans": "^5.3.0",
     "@storybook/addon-a11y": "^10.6.2",
+    "@storybook/addon-docs": "^10.6.2",
     "@storybook/react-vite": "^10.6.2",
     "@tailwindcss/cli": "^4.3.3",
     "@tailwindcss/vite": "^4.3.3",
@@ -101,14 +125,23 @@
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.71.2",
     "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "vitest": "^5.0.5",
+    "zod": "^4.6.7"
   },
   "peerDependencies": {
+    "@ag-ui/client": "^1.0.2",
+    "@copilotkit/react-core": ">=1.79.1 <2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@ag-ui/client": {
+      "optional": true
+    },
+    "@copilotkit/react-core": {
+      "optional": true
+    },
     "tailwindcss": {
       "optional": true
     }