@signalsafe/tree-spec-editor-react 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @signalsafe/tree-spec-editor-react
+
+Headless React layer for the SignalSafe TreeSpec graph editor. Renders the
+React Flow canvas, owns React state plumbing, and exposes the editor as a
+single React component — without depending on any specific UI library.
+
+This is the React-specific sibling to **[`@signalsafe/tree-spec-editor-core`](../tree-spec-editor-core/README.md)**. The core package owns model + helpers (zero UI deps); this package owns React rendering. UI shells (e.g. `@signalsafe/tree-spec-editor` for React + Bootstrap, planned `@signalsafe/tree-spec-editor-react-mui` for React + Material) layer on top.
+
+## What this package owns
+
+- **`TreeSpecGraphEditor`** — the React Flow canvas (Background, Controls, MiniMap, custom node renderer, transition edges, selection wiring, focus/fit-view).
+- **`TreeSpecGraphEditorProps`** — props type.
+- Future: framework-shaped headless hooks (e.g. `useTreeSpecEditorState`,
+  `useGraphSelection`) that wrap the framework-agnostic helpers from
+  `tree-spec-editor-core`.
+
+## What lives elsewhere
+
+| Concern | Package |
+|--------|---------|
+| Editor model, tree operations, layout, autosave/keyboard helpers, constants | `@signalsafe/tree-spec-editor-core` |
+| Sidebar panels, inspector, modals, toolbar (Bootstrap-styled) | `@signalsafe/tree-spec-editor` |
+| Material-styled UI shells (planned) | `@signalsafe/tree-spec-editor-react-mui` |
+| Angular implementation (planned) | `@signalsafe/tree-spec-editor-angular` |
+
+## Install
+
+```bash
+npm install @signalsafe/tree-spec-editor-react react react-dom reactflow
+```
+
+`reactflow` is a peer dependency; you must install it (and ship its CSS,
+e.g. `import 'reactflow/dist/style.css';`) in the consuming app. The
+package itself imports the CSS file from its source, so bundlers that
+resolve module references will pick it up automatically.
+
+## Why a separate package?
+
+This layer is React-specific but **UI-library-agnostic**. Hosts that want
+to ship a Material-styled editor only need to publish their own UI shell
+(panels, modals, toolbar) — they reuse the canvas and the editor model
+unchanged. This also keeps `@signalsafe/tree-spec-editor` (the
+Bootstrap variant) from being the sole React entry point.

package/dist/TreeSpecGraphEditor.d.ts

@@ -0,0 +1,16 @@
+import 'reactflow/dist/style.css';
+import { type EditorTree, type GraphSelection, type GraphEditorIssue } from '@signalsafe/tree-spec-editor-core';
+export type TreeSpecGraphEditorProps = {
+    tree: EditorTree;
+    onChange: (next: EditorTree) => void;
+    issues?: GraphEditorIssue[];
+    showMiniMap?: boolean;
+    selected?: GraphSelection;
+    onSelect?: (sel: GraphSelection) => void;
+    focusNodeId?: string | null;
+    fitViewNonce?: number;
+    /** Optional class for the outer container (default includes h-70vh border rounded). */
+    className?: string;
+};
+export default function TreeSpecGraphEditor(props: Readonly<TreeSpecGraphEditorProps>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=TreeSpecGraphEditor.d.ts.map

package/dist/TreeSpecGraphEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeSpecGraphEditor.d.ts","sourceRoot":"","sources":["../src/TreeSpecGraphEditor.tsx"],"names":[],"mappings":"AAkBA,OAAO,0BAA0B,CAAC;AAIlC,OAAO,EAKH,KAAK,UAAU,EAEf,KAAK,cAAc,EACnB,KAAK,gBAAgB,EAGxB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,wBAAwB,GAAG;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAkZF,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,wBAAwB,CAAC,2CAMpF"}

package/dist/TreeSpecGraphEditor.js

@@ -0,0 +1,274 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import ReactFlow, { Background, Controls, Handle, MiniMap, Position, ReactFlowProvider, addEdge, useEdgesState, useNodesState, useReactFlow, } from 'reactflow';
+import 'reactflow/dist/style.css';
+import { TERMINAL_OUTCOME, TREE_SPEC_ISSUE_SEVERITY } from '@signalsafe/tree-spec';
+import { END_NODE_ID, GRAPH_SELECTION_KIND, safeUUID, } from '@signalsafe/tree-spec-editor-core';
+/** Background highlight when the node matches editor selection (sidebar / issues / canvas). */
+const CANVAS_NODE_SELECTED_CLASS = 'bg-primary-subtle';
+function getPromptNodeBorderClass(hasErrors, warningCount) {
+    if (hasErrors) {
+        return 'border-danger';
+    }
+    if (warningCount > 0) {
+        return 'border-warning';
+    }
+    return '';
+}
+function getIssueEdgeStyle(style, hasIssue) {
+    if (!hasIssue) {
+        return style;
+    }
+    return style ? { ...style, strokeWidth: 2, strokeDasharray: '6 4' } : { strokeWidth: 2, strokeDasharray: '6 4' };
+}
+function PromptNode({ data, selected }) {
+    const n = data.node;
+    const choices = n.choices ?? [];
+    const hasErrors = data.issuesErrors > 0;
+    const borderClass = getPromptNodeBorderClass(hasErrors, data.issuesWarnings);
+    return (_jsxs("div", { className: `card card-min-width-280 ${borderClass}${selected ? ` ${CANVAS_NODE_SELECTED_CLASS}` : ''}`, children: [_jsx(Handle, { type: "target", position: Position.Left, id: "in", className: "handle-bg-default" }), _jsxs("div", { className: "card-body p-2", children: [_jsxs("div", { className: "d-flex justify-content-between align-items-center", children: [_jsxs("div", { children: [_jsxs("div", { className: "fw-bold font-size-13", children: [data.isStart ? '▶ ' : '', n.type, data.issuesTotal > 0 ? (_jsxs("span", { className: "ms-2", title: `${data.issuesErrors} errors, ${data.issuesWarnings} warnings, ${data.issuesInfo} info`, children: [data.issuesErrors > 0 ? _jsx("span", { className: "badge bg-danger me-1", children: data.issuesErrors }) : null, data.issuesWarnings > 0 ? (_jsx("span", { className: "badge bg-warning text-dark me-1", children: data.issuesWarnings })) : null, data.issuesInfo > 0 ? _jsx("span", { className: "badge bg-info text-dark", children: data.issuesInfo }) : null] })) : null] }), _jsx("div", { className: "font-size-12 opacity-90 text-truncate", children: n.prompt || _jsx("em", { className: "text-muted", children: "(empty prompt)" }) })] }), _jsx("div", { className: "text-muted font-size-11", children: n.id.slice(0, 8) })] }), _jsx("hr", { className: "my-2" }), _jsx("div", { className: "font-size-12", children: choices.length === 0 ? (_jsx("div", { className: "text-muted", children: _jsx("em", { children: "No choices" }) })) : (_jsx("ul", { className: "list-unstyled mb-0", children: choices.map((c) => (_jsxs("li", { className: "d-flex justify-content-between align-items-center position-relative pr-18", children: [_jsx("span", { className: "text-truncate max-w-210", children: c.label }), _jsx("span", { className: "badge bg-light text-dark", children: c.id }), _jsx(Handle, { type: "source", position: Position.Right, id: `choice:${c.id}`, className: "graph-editor-handle", style: {
+                                            position: 'absolute',
+                                            right: -6,
+                                            top: '50%',
+                                            transform: 'translateY(-50%)',
+                                        } })] }, c.id))) })) })] })] }));
+}
+function EndNode({ selected }) {
+    return (_jsxs("div", { className: `card border-danger w-180${selected ? ` ${CANVAS_NODE_SELECTED_CLASS}` : ''}`, children: [_jsx(Handle, { type: "target", position: Position.Left, id: "in", className: "handle-bg-danger" }), _jsxs("div", { className: "card-body p-2 text-center", children: [_jsx("div", { className: "fw-bold text-danger", children: "END" }), _jsx("div", { className: "text-muted font-size-12", children: "Outcome required" })] })] }));
+}
+function choiceIdFromHandle(h) {
+    if (!h)
+        return '';
+    if (h.startsWith('choice:'))
+        return h.slice('choice:'.length);
+    return h;
+}
+function edgeLabelForTransition(tree, t) {
+    const node = tree.nodes[t.fromNodeId];
+    const choice = node?.choices?.find((c) => c.id === t.fromChoiceId);
+    const base = choice?.label || t.fromChoiceId;
+    if (t.toNodeId === END_NODE_ID) {
+        const oc = t.outcome ?? TERMINAL_OUTCOME.AT_RISK;
+        return `${base}  →  END (${oc})`;
+    }
+    return base;
+}
+function buildEdgesFromTransitions(tree) {
+    return tree.transitions.map((t) => ({
+        id: t.id,
+        source: t.fromNodeId,
+        target: t.toNodeId,
+        sourceHandle: `choice:${t.fromChoiceId}`,
+        label: edgeLabelForTransition(tree, t),
+    }));
+}
+function buildTransitionsFromEdges(edges, existing) {
+    const existingById = new Map(existing.map((t) => [t.id, t]));
+    return edges
+        .filter((e) => e.source && e.target && e.source !== END_NODE_ID)
+        .map((e) => {
+        const fromChoiceId = choiceIdFromHandle(e.sourceHandle);
+        const prior = existingById.get(String(e.id));
+        return {
+            id: String(e.id),
+            fromNodeId: String(e.source),
+            fromChoiceId: fromChoiceId,
+            toNodeId: String(e.target),
+            outcome: String(e.target) === END_NODE_ID ? (prior?.outcome ?? TERMINAL_OUTCOME.AT_RISK) : undefined,
+        };
+    })
+        .filter((t) => t.fromChoiceId.length > 0);
+}
+function TreeSpecGraphInner({ tree, onChange, issues = [], selected, onSelect, focusNodeId, showMiniMap = true, fitViewNonce, className = 'h-70vh border rounded', }) {
+    const rf = useReactFlow();
+    const isDraggingRef = useRef(false);
+    const nodesRef = useRef([]);
+    const edgesRef = useRef([]);
+    const issuesByNode = useMemo(() => {
+        const m = new Map();
+        for (const i of issues) {
+            if (!i.node_id)
+                continue;
+            const cur = m.get(i.node_id) ?? { total: 0, errors: 0, warnings: 0, info: 0 };
+            cur.total += 1;
+            const sev = String(i.severity ?? '').toLowerCase();
+            if (sev === TREE_SPEC_ISSUE_SEVERITY.WARNING)
+                cur.warnings += 1;
+            else if (sev === TREE_SPEC_ISSUE_SEVERITY.INFO)
+                cur.info += 1;
+            else
+                cur.errors += 1;
+            m.set(i.node_id, cur);
+        }
+        return m;
+    }, [issues]);
+    const issueKeySet = useMemo(() => {
+        const s = new Set();
+        for (const i of issues) {
+            if (!i.node_id || !i.choice_id)
+                continue;
+            s.add(`${i.node_id}::${i.choice_id}`);
+        }
+        return s;
+    }, [issues]);
+    const initialNodes = useMemo(() => {
+        const arr = [];
+        for (const n of Object.values(tree.nodes)) {
+            arr.push({
+                id: n.id,
+                type: 'promptNode',
+                position: n.position ?? { x: 0, y: 0 },
+                data: {
+                    node: n,
+                    isStart: tree.start_node === n.id,
+                    issuesTotal: issuesByNode.get(n.id)?.total ?? 0,
+                    issuesErrors: issuesByNode.get(n.id)?.errors ?? 0,
+                    issuesWarnings: issuesByNode.get(n.id)?.warnings ?? 0,
+                    issuesInfo: issuesByNode.get(n.id)?.info ?? 0,
+                },
+            });
+        }
+        arr.push({
+            id: END_NODE_ID,
+            type: 'endNode',
+            position: { x: 700, y: 0 },
+            data: {},
+            selectable: true,
+            draggable: true,
+        });
+        return arr;
+    }, [tree.nodes, tree.start_node, issuesByNode]);
+    const initialEdges = useMemo(() => buildEdgesFromTransitions(tree), [tree]);
+    const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+    const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+    useEffect(() => {
+        nodesRef.current = nodes;
+    }, [nodes]);
+    useEffect(() => {
+        edgesRef.current = edges;
+    }, [edges]);
+    const lastTreeRef = useRef('');
+    useEffect(() => {
+        const nextKey = JSON.stringify({ tree, issues: issues.length });
+        if (nextKey === lastTreeRef.current)
+            return;
+        lastTreeRef.current = nextKey;
+        setNodes(initialNodes);
+        setEdges(initialEdges);
+    }, [tree, issues.length, initialNodes, initialEdges, setNodes, setEdges]);
+    useEffect(() => {
+        if (!focusNodeId)
+            return;
+        try {
+            const n = rf.getNode(focusNodeId);
+            if (!n)
+                return;
+            rf.setCenter(n.position.x + 150, n.position.y + 60, { zoom: 1, duration: 300 });
+        }
+        catch {
+            // ignore
+        }
+    }, [focusNodeId, rf]);
+    useEffect(() => {
+        if (!fitViewNonce)
+            return;
+        const id = setTimeout(() => {
+            try {
+                rf.fitView({ padding: 0.2, duration: 300 });
+            }
+            catch {
+                // ignore
+            }
+        }, 100);
+        return () => clearTimeout(id);
+    }, [fitViewNonce, rf]);
+    const nodeTypes = useMemo(() => ({
+        promptNode: PromptNode,
+        endNode: EndNode,
+    }), []);
+    const commit = useCallback((nextNodes, nextEdges) => {
+        if (isDraggingRef.current)
+            return;
+        const updatedNodes = { ...tree.nodes };
+        for (const n of nextNodes) {
+            if (n.id === END_NODE_ID)
+                continue;
+            const existing = updatedNodes[n.id];
+            if (!existing)
+                continue;
+            updatedNodes[n.id] = {
+                ...existing,
+                position: { x: n.position.x, y: n.position.y },
+            };
+        }
+        const transitions = buildTransitionsFromEdges(nextEdges, tree.transitions);
+        onChange({
+            ...tree,
+            nodes: updatedNodes,
+            transitions,
+        });
+    }, [tree, onChange]);
+    const onConnect = useCallback((conn) => {
+        const choiceId = choiceIdFromHandle(conn.sourceHandle);
+        if (!conn.source || !conn.target || !choiceId)
+            return;
+        const newEdge = {
+            id: safeUUID(),
+            source: conn.source,
+            target: conn.target,
+            sourceHandle: conn.sourceHandle,
+            label: choiceId,
+        };
+        setEdges((eds) => {
+            const next = addEdge(newEdge, eds);
+            commit(nodesRef.current, next);
+            return next;
+        });
+    }, [setEdges, commit]);
+    const onNodesChangeWrapped = useCallback((changes) => {
+        onNodesChange(changes);
+        const shouldCommit = changes.some((c) => {
+            if (c?.type === 'select' || c?.type === 'dimensions')
+                return false;
+            if (c?.type === 'position' && c?.dragging)
+                return false;
+            return true;
+        });
+        if (shouldCommit)
+            queueMicrotask(() => commit(nodesRef.current, edgesRef.current));
+    }, [onNodesChange, commit]);
+    const onEdgesChangeWrapped = useCallback((changes) => {
+        onEdgesChange(changes);
+        const shouldCommit = changes.some((c) => c?.type !== 'select');
+        if (shouldCommit)
+            queueMicrotask(() => commit(nodesRef.current, edgesRef.current));
+    }, [onEdgesChange, commit]);
+    const onNodeDragStart = useCallback(() => {
+        isDraggingRef.current = true;
+    }, []);
+    const onNodeDragStop = useCallback(() => {
+        isDraggingRef.current = false;
+        commit(nodesRef.current, edgesRef.current);
+    }, [commit]);
+    const onNodeClick = useCallback((_evt, node) => {
+        onSelect?.({ kind: GRAPH_SELECTION_KIND.NODE, id: node.id });
+    }, [onSelect]);
+    const onEdgeClick = useCallback((_evt, edge) => {
+        onSelect?.({ kind: GRAPH_SELECTION_KIND.EDGE, id: edge.id });
+    }, [onSelect]);
+    return (_jsx("div", { className: className, children: _jsxs(ReactFlow, { nodes: nodes.map((n) => ({
+                ...n,
+                selected: selected?.kind === GRAPH_SELECTION_KIND.NODE && selected.id === n.id,
+            })), edges: edges.map((e) => {
+                const fromChoiceId = choiceIdFromHandle(e.sourceHandle);
+                const hasIssue = fromChoiceId ? issueKeySet.has(`${e.source}::${fromChoiceId}`) : false;
+                return {
+                    ...e,
+                    selected: selected?.kind === GRAPH_SELECTION_KIND.EDGE && selected.id === e.id,
+                    style: getIssueEdgeStyle(e.style, hasIssue),
+                };
+            }), onNodesChange: onNodesChangeWrapped, onEdgesChange: onEdgesChangeWrapped, onConnect: onConnect, onNodeDragStart: onNodeDragStart, onNodeDragStop: onNodeDragStop, onNodeClick: onNodeClick, onEdgeClick: onEdgeClick, nodeTypes: nodeTypes, children: [showMiniMap ? _jsx(MiniMap, {}) : null, _jsx(Controls, {}), _jsx(Background, {})] }) }));
+}
+export default function TreeSpecGraphEditor(props) {
+    return (_jsx(ReactFlowProvider, { children: _jsx(TreeSpecGraphInner, { ...props }) }));
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,337 @@
+import type { AutosaveStatus, EditorChoice, EditorNode, EditorTransition, EditorTree, GraphSelection, KeyboardShortcutAction, TreeSpecAuditEventItem, TreeSpecIssue, TreeSpecSnapshotItem, TreeSpecWire, TreeTemplateSpec } from '@signalsafe/tree-spec-editor-core';
+/**
+ * Optional metadata returned with {@link TreeSpecEditorAdapter.getVersion} for
+ * host info panels (e.g. scenario id, version label, timestamps).
+ */
+export interface GraphEditorVersionInfo {
+    scenarioId: string;
+    versionId: string;
+    /** Display name (e.g. scenario title or version label). */
+    name: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+/**
+ * Data-only adapter consumed by {@link useTreeSpecEditor}. Hosts pass an
+ * object satisfying this contract; the hook never reads or writes routing,
+ * URLs, or page chrome through it. Host pages may extend this adapter with
+ * extra methods (e.g. `getPreviewUrl`, `getBackUrl`) for their own use —
+ * those methods are not part of the hook contract.
+ *
+ * Every method except `getVersion` and `updateVersion` is optional; the hook
+ * gates the corresponding feature (Validate / Publish / Snapshots / Audit /
+ * Clone) on its presence.
+ */
+export interface TreeSpecEditorAdapter {
+    /**
+     * Load the current TreeSpec wire and published flag for an entity.
+     * Returning `null` makes the hook surface a "failed to load" state.
+     */
+    getVersion: (entityId: string) => Promise<{
+        tree_spec: Record<string, unknown>;
+        is_published: boolean;
+        info?: GraphEditorVersionInfo;
+    } | null>;
+    /** Persist the current TreeSpec wire (called by Save Draft + autosave). */
+    updateVersion: (entityId: string, payload: {
+        tree_spec: Record<string, unknown>;
+    }) => Promise<void>;
+    /**
+     * Optional server-side validation. When absent, Validate becomes a local
+     * (lint-only) operation and the toolbar should hide the Validate button.
+     */
+    validate?: (entityId: string, tree_spec: Record<string, unknown>) => Promise<{
+        valid: boolean;
+        issues?: AdapterValidationIssue[];
+    }>;
+    /** Optional publish. When absent, Publish is unavailable. */
+    publish?: (entityId: string) => Promise<void>;
+    /** Optional snapshot listing. When absent, Draft history is unavailable. */
+    listSnapshots?: (entityId: string) => Promise<TreeSpecSnapshotItem[]>;
+    /** Optional snapshot restore. */
+    restoreSnapshot?: (entityId: string, snapshotId: string) => Promise<{
+        tree_spec: Record<string, unknown>;
+    }>;
+    /** Optional manual snapshot creation. */
+    createSnapshot?: (entityId: string, payload: {
+        label?: string;
+        tree_spec: Record<string, unknown>;
+    }) => Promise<void>;
+    /**
+     * Optional clone-to-draft. Returns the id of the newly created draft.
+     * When absent, Clone is unavailable.
+     */
+    cloneToDraft?: (entityId: string) => Promise<{
+        id: string;
+    }>;
+    /** Optional audit listing. When absent, Audit is unavailable. */
+    listAudit?: (entityId: string) => Promise<TreeSpecAuditEventItem[]>;
+}
+/**
+ * Adapter-shaped validation issue. Hosts that surface server validation should
+ * normalize their backend payload to this shape inside the adapter — the hook
+ * then maps it into the standard {@link TreeSpecIssue}.
+ */
+export interface AdapterValidationIssue {
+    severity?: 'error' | 'warning' | 'info';
+    level?: string;
+    message?: string;
+    node_id?: string;
+    choice_id?: string;
+}
+/**
+ * Input options for {@link useTreeSpecEditor}. Only `adapter` and `entityId`
+ * are required; everything else is opt-in.
+ */
+export interface UseTreeSpecEditorOptions {
+    /** Data adapter for the editor (see {@link TreeSpecEditorAdapter}). */
+    adapter: TreeSpecEditorAdapter;
+    /**
+     * Stable identifier for the entity being edited (host extracts from its
+     * router, e.g. `useParams().scenarioVersionId`). `undefined` puts the
+     * hook in a loading-without-target state until a value is supplied.
+     */
+    entityId: string | undefined;
+    /**
+     * Autosave debounce delay in milliseconds. Default `2500`.
+     * Ignored when {@link enableAutosave} is `false`.
+     */
+    autosaveDebounceMs?: number;
+    /** Enable/disable autosave entirely. Default `true`. */
+    enableAutosave?: boolean;
+    /** Enable/disable the global keyboard shortcut listener. Default `true`. */
+    enableKeyboardShortcuts?: boolean;
+    /**
+     * Coerce the raw `tree_spec` payload returned by the adapter into a
+     * `TreeSpecWire`. Defaults to {@link coerceTreeSpecWireForEditor} from
+     * `@signalsafe/tree-spec-editor-core`, which passes valid wires through
+     * and bootstraps a starter graph for `null`/`undefined`/empty payloads.
+     * Override to change the bootstrap behavior (e.g. ship a richer template,
+     * or refuse to bootstrap).
+     */
+    coerceRawSpec?: (raw: unknown) => TreeSpecWire | null;
+    /**
+     * Optional computation of runtime issues from the compiled TreeSpec.
+     * Hosts that integrate with the simulator pass
+     * `treeSpecRuntimeIssues` from `@signalsafe/simulator-core`. Hosts that
+     * don't can omit this; runtime issues will be an empty array.
+     * The hook itself never imports the simulator package.
+     */
+    computeRuntimeIssues?: (compiled: Record<string, unknown>) => TreeSpecIssue[];
+    /**
+     * When `true`, the runtime-issue category is folded into the developer
+     * tools surface rather than appearing in the dedup'd `issues` list. Host
+     * supplies this from its debug-mode toggle. Default `false`.
+     */
+    debugMode?: boolean;
+    /**
+     * Invoked when the user triggers the Preview action (toolbar button or
+     * `Ctrl/Cmd+P` keyboard shortcut). Hosts wire their router here.
+     */
+    onPreview?: () => void;
+    /**
+     * Invoked after a successful `cloneToDraft` with the new draft id. Hosts
+     * wire their router here.
+     */
+    onCloneNavigate?: (newDraftId: string) => void;
+    /**
+     * Optional parser for backend validation errors that arrive as a single
+     * detail string (e.g. Pydantic outcome errors). Defaults to
+     * {@link parsePydanticOutcomeErrors} from
+     * `@signalsafe/tree-spec-editor-core`.
+     */
+    parseServerErrorMessage?: (message: string) => TreeSpecIssue[] | null;
+    /**
+     * Decide whether the hook should auto-validate on initial load. Defaults
+     * to {@link shouldQueueInitialValidation} from
+     * `@signalsafe/tree-spec-editor-core` (validates drafts, skips published).
+     */
+    shouldQueueInitialValidation?: (isPublished: boolean | undefined) => boolean;
+}
+/** Mutable editor state surfaced by {@link useTreeSpecEditor}. */
+export interface UseTreeSpecEditorState {
+    /** Loading the entity from the adapter. `true` until first load resolves or rejects. */
+    loading: boolean;
+    /** A `Save Draft` round-trip is in flight. */
+    saving: boolean;
+    /** A `Publish` round-trip is in flight. */
+    publishing: boolean;
+    /** A `Snapshot` round-trip is in flight. */
+    creatingSnapshot: boolean;
+    /** A `Clone to Draft` round-trip is in flight. */
+    cloning: boolean;
+    /** Id of the snapshot currently being restored, or `null`. */
+    restoringSnapshotId: string | null;
+    /** Autosave state machine snapshot. */
+    autosaveStatus: AutosaveStatus;
+    /** ISO timestamp of the most recent validation, or `null`. */
+    lastValidatedAt: string | null;
+    /** The most recent raw wire from the adapter (or the last successful save). */
+    rawTreeSpec: TreeSpecWire | null;
+    /** Editor-shaped tree derived from `rawTreeSpec` plus user edits. */
+    tree: EditorTree | null;
+    /**
+     * Decompiled `rawTreeSpec` — used by the Publish modal to diff against the
+     * current `tree`. `null` until the initial load resolves.
+     */
+    baselineTree: EditorTree | null;
+    /** Compiled `tree`, or `null` when `tree` is `null`. Memoized. */
+    compiledTreeSpec: Record<string, unknown> | null;
+    /** Whether the loaded entity is published (read-only). */
+    isPublished: boolean;
+    /**
+     * Optional version/scenario metadata from {@link TreeSpecEditorAdapter.getVersion}
+     * (e.g. for an info panel). `null` when absent or not yet loaded.
+     */
+    versionInfo: GraphEditorVersionInfo | null;
+    /** Convenience: `Boolean(tree)`. */
+    hasTree: boolean;
+    /** Local lint issues (editor + wire) — recomputed on every tree change. */
+    localIssues: TreeSpecIssue[];
+    /** Server validation issues — populated by `actions.validate`. */
+    serverIssues: TreeSpecIssue[];
+    /**
+     * Runtime issues from {@link UseTreeSpecEditorOptions.computeRuntimeIssues}
+     * (empty when no callback is wired).
+     */
+    runtimeIssues: TreeSpecIssue[];
+    /** Dedup'd union of `localIssues`, `serverIssues`, and `runtimeIssues`. */
+    issues: TreeSpecIssue[];
+    /** `true` when `issues` contains no error-severity entries. */
+    canPublish: boolean;
+    /** Current graph selection (node, edge, or none). */
+    selection: GraphSelection;
+    /** Node the canvas should focus into view (e.g. after add/duplicate). */
+    focusNodeId: string | null;
+    /** Choice within the focused node to scroll into view. */
+    focusChoiceId: string | null;
+    /** Bump-counter the canvas watches to trigger `fitView`. */
+    fitViewNonce: number;
+    /** Node object for `selection` when it's a NODE selection; `null` otherwise. */
+    selectedNode: EditorNode | null;
+    /** Transition object for `selection` when it's an EDGE selection; `null` otherwise. */
+    selectedEdge: EditorTransition | null;
+    /** Search filter for the Nodes panel. */
+    nodeSearch: string;
+    /** Search filter for the Issues panel. */
+    issueSearch: string;
+    /** Whether the canvas mini-map is visible. */
+    showMiniMap: boolean;
+    /** Snapshot list (loaded when `showDraftHistory` opens). */
+    snapshots: TreeSpecSnapshotItem[];
+    /** Audit event list (loaded when `showAudit` opens). */
+    auditEvents: TreeSpecAuditEventItem[];
+    /** Fetching the snapshot list. */
+    loadingSnapshots: boolean;
+    /** Fetching the audit event list. */
+    loadingAudit: boolean;
+    /** Draft-history modal visibility. */
+    showDraftHistory: boolean;
+    /** Audit modal visibility. */
+    showAudit: boolean;
+    /** Publish-review modal visibility. */
+    showPublishModal: boolean;
+}
+/** Actions surfaced by {@link useTreeSpecEditor}. */
+export interface UseTreeSpecEditorActions {
+    /** Replace the entire tree (e.g. after the canvas emits a change). */
+    setTree: (next: EditorTree | null) => void;
+    /** Replace the current selection. */
+    setSelection: (next: GraphSelection) => void;
+    /** Replace the node-focus marker. */
+    setFocusNodeId: (id: string | null) => void;
+    /** Replace the choice-focus marker. */
+    setFocusChoiceId: (id: string | null) => void;
+    /** Bump the fitView nonce (e.g. for a "Reset view" button). */
+    triggerResetView: () => void;
+    /** Update the Nodes-panel search filter. */
+    setNodeSearch: (next: string) => void;
+    /** Update the Issues-panel search filter. */
+    setIssueSearch: (next: string) => void;
+    /** Toggle the canvas mini-map. */
+    setShowMiniMap: (next: boolean) => void;
+    /** Show/hide the draft-history modal. */
+    setShowDraftHistory: (next: boolean) => void;
+    /** Show/hide the audit modal. */
+    setShowAudit: (next: boolean) => void;
+    /** Show/hide the publish-review modal. */
+    setShowPublishModal: (next: boolean) => void;
+    /**
+     * Spawn a new node of the supplied type (host owns the type vocabulary).
+     * Returns the id of the spawned node, or `undefined` when no tree is loaded.
+     */
+    addNodeOfType: (type: string, patch?: Partial<EditorNode>) => string | undefined;
+    /**
+     * Remove the currently selected node (same semantics as the Delete keyboard shortcut).
+     * Returns `true` when a node was removed. No-op (returns `false`) when there is no tree,
+     * nothing is selected, the selection is not a node, the version is published, or delete is
+     * not allowed for that node.
+     */
+    deleteSelectedNode: () => boolean;
+    /**
+     * Remove a node by id (clears selection / focus when they pointed at that node).
+     * Returns `true` when the node was removed. No-op when there is no tree, the version is
+     * published, or `deleteNode` refuses (e.g. invalid id).
+     */
+    deleteNodeById: (nodeId: string) => boolean;
+    /** Run the auto-layout helper and bump the fitView nonce. */
+    autoLayout: () => void;
+    /** Apply a starter template (host owns the template vocabulary). */
+    insertTemplate: (spec: TreeTemplateSpec) => void;
+    /**
+     * Run server-side validation if the adapter supports it; otherwise just
+     * stamp `lastValidatedAt`. Pass an explicit wire to validate something
+     * other than the current `tree`. Returns the adapter's payload, or
+     * `{ valid: false, issues }` when the call rejected.
+     */
+    validate: (specOverride?: TreeSpecWire) => Promise<{
+        valid: boolean;
+        issues?: AdapterValidationIssue[];
+    } | undefined>;
+    /** Save the current draft via the adapter. No-op when published or loading. */
+    saveDraft: () => Promise<void>;
+    /**
+     * Validate then publish. Surfaces validation errors via `serverIssues`
+     * and refuses to publish when `canPublish` is `false`.
+     */
+    publish: () => Promise<void>;
+    /** Create a snapshot of the current tree via the adapter. */
+    createSnapshot: () => Promise<void>;
+    /** Restore the tree to a snapshot via the adapter; clears local edits. */
+    restoreSnapshot: (snapshotId: string) => Promise<void>;
+    /**
+     * Clone the current entity to a new draft via the adapter and invoke
+     * {@link UseTreeSpecEditorOptions.onCloneNavigate} when the new id arrives.
+     */
+    cloneToDraft: () => Promise<void>;
+    /** Patch the currently-selected node. No-op when no node is selected. */
+    updateSelectedNode: (patch: Partial<EditorNode>) => void;
+    /** Append a new (empty) choice to the currently-selected node. */
+    addChoice: () => void;
+    /** Remove a choice from the selected node (and its outgoing transitions). */
+    deleteChoice: (choiceId: string) => void;
+    /** Re-target a choice's transition (creates the transition if missing). */
+    setChoiceTarget: (choiceId: string, targetNodeId: string) => void;
+    /** Update the terminal outcome of a choice targeting the END node. */
+    setChoiceOutcome: (choiceId: string, outcome: string) => void;
+    /**
+     * Click an issue from the Issues panel: focuses the issue's node + choice,
+     * selects the node, and bumps the fitView nonce.
+     */
+    selectIssue: (issue: {
+        node_id?: string;
+        choice_id?: string;
+    }) => void;
+}
+/** Return value of {@link useTreeSpecEditor}. */
+export interface UseTreeSpecEditorResult extends UseTreeSpecEditorState {
+    actions: UseTreeSpecEditorActions;
+}
+/**
+ * Map of keyboard shortcut actions the hook handled most recently. Test-only
+ * surface; not part of the public API.
+ * @internal
+ */
+export type DispatchedKeyboardAction = KeyboardShortcutAction | null;
+export type { EditorChoice, EditorNode, EditorTransition, EditorTree };
+//# sourceMappingURL=types.d.ts.map