@signalsafe/tree-spec-editor-react 0.1.0

package/dist/hooks/useTreeSpecEditor.js

@@ -0,0 +1,663 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { compileTreeSpec, decompileTreeSpec, lintTreeSpecWire, TERMINAL_OUTCOME, TREE_SPEC_ISSUE_SEVERITY } from '@signalsafe/tree-spec';
+import { applyTreeTemplate, autoLayoutTree, AUTOSAVE_STATUS, coerceTreeSpecWireForEditor as defaultCoerceRawSpec, deleteNode, deleteTransitionsForChoice, duplicateNode, END_NODE_ID, getKeyboardShortcutAction, getNextSpawnPosition, getTransition, GRAPH_SELECTION_KIND, KEYBOARD_SHORTCUT_ACTION, lintEditorTree, parsePydanticOutcomeErrors as defaultParseServerErrorMessage, safeUUID, shouldQueueInitialValidation as defaultShouldQueueInitialValidation, upsertTransition, } from '@signalsafe/tree-spec-editor-core';
+const DEFAULT_AUTOSAVE_DEBOUNCE_MS = 2500;
+function isTextFieldTarget(target) {
+    const tag = target instanceof HTMLElement ? target.tagName.toLowerCase() : '';
+    return (tag === 'input' ||
+        tag === 'textarea' ||
+        (target instanceof HTMLElement && target.getAttribute('contenteditable') === 'true'));
+}
+/**
+ * Headless React hook that owns the full stateful behavior of the SignalSafe
+ * TreeSpec graph editor — loading, autosave, validation, publish, snapshots,
+ * audit, clone-to-draft, selection, focus + fit-view, node/choice operations,
+ * and keyboard shortcuts. Consumers compose their own UI (toolbar, panels,
+ * modals, layout) on top of the returned state + actions.
+ *
+ * Boundary commitments:
+ * - **No router**: routing is host-injected via `onPreview` / `onCloneNavigate`.
+ * - **No UI library**: returns data only; never renders JSX.
+ * - **No simulator runtime**: hosts inject `computeRuntimeIssues` if needed.
+ *
+ * See {@link UseTreeSpecEditorOptions} for full option documentation and
+ * {@link UseTreeSpecEditorResult} for the returned shape.
+ */
+export function useTreeSpecEditor(options) {
+    const { adapter, entityId, autosaveDebounceMs = DEFAULT_AUTOSAVE_DEBOUNCE_MS, enableAutosave = true, enableKeyboardShortcuts = true, coerceRawSpec = defaultCoerceRawSpec, computeRuntimeIssues, debugMode = false, onPreview, onCloneNavigate, parseServerErrorMessage = defaultParseServerErrorMessage, shouldQueueInitialValidation = defaultShouldQueueInitialValidation, } = options;
+    // -----------------------------------------------------------------------
+    // Core editor state.
+    // -----------------------------------------------------------------------
+    const [loading, setLoading] = useState(true);
+    const [saving, setSaving] = useState(false);
+    const [publishing, setPublishing] = useState(false);
+    const [autosaveStatus, setAutosaveStatus] = useState(AUTOSAVE_STATUS.IDLE);
+    const [rawTreeSpec, setRawTreeSpec] = useState(null);
+    const [tree, setTree] = useState(null);
+    const [isPublished, setIsPublished] = useState(false);
+    const [versionInfo, setVersionInfo] = useState(null);
+    const [localIssues, setLocalIssues] = useState([]);
+    const [serverIssues, setServerIssues] = useState([]);
+    const [lastValidatedAt, setLastValidatedAt] = useState(null);
+    const [selection, setSelection] = useState({ kind: null, id: null });
+    const [focusNodeId, setFocusNodeId] = useState(null);
+    const [focusChoiceId, setFocusChoiceId] = useState(null);
+    const [fitViewNonce, setFitViewNonce] = useState(0);
+    const [nodeSearch, setNodeSearch] = useState('');
+    const [issueSearch, setIssueSearch] = useState('');
+    const [showMiniMap, setShowMiniMap] = useState(true);
+    const [showDraftHistory, setShowDraftHistory] = useState(false);
+    const [showAudit, setShowAudit] = useState(false);
+    const [showPublishModal, setShowPublishModal] = useState(false);
+    const [snapshots, setSnapshots] = useState([]);
+    const [auditEvents, setAuditEvents] = useState([]);
+    const [loadingSnapshots, setLoadingSnapshots] = useState(false);
+    const [loadingAudit, setLoadingAudit] = useState(false);
+    const [restoringSnapshotId, setRestoringSnapshotId] = useState(null);
+    const [creatingSnapshot, setCreatingSnapshot] = useState(false);
+    const [cloning, setCloning] = useState(false);
+    const lastSavedKeyRef = useRef('');
+    const autosaveTimerRef = useRef(null);
+    // -----------------------------------------------------------------------
+    // Derived state.
+    // -----------------------------------------------------------------------
+    const baselineTree = useMemo(() => {
+        if (!rawTreeSpec)
+            return null;
+        try {
+            return decompileTreeSpec(rawTreeSpec);
+        }
+        catch {
+            return null;
+        }
+    }, [rawTreeSpec]);
+    const compiledTreeSpec = useMemo(() => (tree ? compileTreeSpec(tree) : null), [tree]);
+    const runtimeIssues = useMemo(() => (compiledTreeSpec && computeRuntimeIssues ? computeRuntimeIssues(compiledTreeSpec) : []), [compiledTreeSpec, computeRuntimeIssues]);
+    const issues = useMemo(() => {
+        const seen = new Set();
+        const out = [];
+        const groups = debugMode ? [localIssues, serverIssues] : [localIssues, runtimeIssues, serverIssues];
+        for (const arr of groups) {
+            for (const i of arr) {
+                const key = `${i.severity}|${i.message}|${i.node_id ?? ''}|${i.choice_id ?? ''}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push(i);
+            }
+        }
+        return out;
+    }, [localIssues, serverIssues, runtimeIssues, debugMode]);
+    const canPublish = useMemo(() => !issues.some((i) => i.severity === TREE_SPEC_ISSUE_SEVERITY.ERROR), [issues]);
+    const selectedNode = useMemo(() => {
+        if (!tree || selection.kind !== GRAPH_SELECTION_KIND.NODE || !selection.id)
+            return null;
+        if (selection.id === END_NODE_ID)
+            return null;
+        return tree.nodes[selection.id] ?? null;
+    }, [tree, selection]);
+    const selectedEdge = useMemo(() => {
+        if (!tree || selection.kind !== GRAPH_SELECTION_KIND.EDGE || !selection.id)
+            return null;
+        return tree.transitions.find((t) => t.id === selection.id) ?? null;
+    }, [tree, selection]);
+    // -----------------------------------------------------------------------
+    // Initial load + local lint recomputation.
+    // -----------------------------------------------------------------------
+    // Stash latest validate in a ref so the keyboard effect can call it
+    // without re-subscribing on every tree change. Populated below.
+    const validateRef = useRef(async () => undefined);
+    const saveDraftRef = useRef(async () => undefined);
+    useEffect(() => {
+        let cancelled = false;
+        async function load() {
+            if (!entityId)
+                return;
+            setLoading(true);
+            setVersionInfo(null);
+            try {
+                const raw = await adapter.getVersion(entityId);
+                if (cancelled)
+                    return;
+                setIsPublished(Boolean(raw?.is_published));
+                setVersionInfo(raw?.info ?? null);
+                const rawSpec = raw?.tree_spec;
+                const spec = coerceRawSpec(rawSpec);
+                if (spec == null) {
+                    setRawTreeSpec(null);
+                    setTree(null);
+                    setVersionInfo(raw?.info ?? null);
+                }
+                else {
+                    setRawTreeSpec(spec);
+                    const nextTree = decompileTreeSpec(spec);
+                    setTree(nextTree);
+                    setLocalIssues([...lintTreeSpecWire(spec), ...lintEditorTree(nextTree)]);
+                    if (shouldQueueInitialValidation(raw?.is_published)) {
+                        queueMicrotask(() => {
+                            void validateRef.current(spec);
+                        });
+                    }
+                    lastSavedKeyRef.current = JSON.stringify(spec);
+                    setAutosaveStatus(AUTOSAVE_STATUS.IDLE);
+                }
+            }
+            catch {
+                if (cancelled)
+                    return;
+                setRawTreeSpec(null);
+                setTree(null);
+                setVersionInfo(null);
+            }
+            finally {
+                if (!cancelled)
+                    setLoading(false);
+            }
+        }
+        if (entityId)
+            void load();
+        return () => {
+            cancelled = true;
+        };
+    }, [entityId, adapter, coerceRawSpec, shouldQueueInitialValidation]);
+    // Local issue list stays focused on structural/editor checks; recomputed
+    // every time the compiled spec changes (which happens on every tree edit).
+    useEffect(() => {
+        if (!tree || !compiledTreeSpec)
+            return;
+        setLocalIssues([...lintTreeSpecWire(compiledTreeSpec), ...lintEditorTree(tree)]);
+    }, [tree, compiledTreeSpec]);
+    // -----------------------------------------------------------------------
+    // Validation.
+    // -----------------------------------------------------------------------
+    const validate = useCallback(async (specOverride) => {
+        if (!entityId)
+            return undefined;
+        const spec = specOverride ?? (tree ? compileTreeSpec(tree) : rawTreeSpec);
+        if (!spec)
+            return undefined;
+        if (!adapter.validate) {
+            setLastValidatedAt(new Date().toISOString());
+            return { valid: true };
+        }
+        try {
+            const payload = await adapter.validate(entityId, spec);
+            const nextIssues = (payload?.issues ?? []).map((i) => {
+                const severity = i.severity ?? i.level ?? TREE_SPEC_ISSUE_SEVERITY.ERROR;
+                return {
+                    severity,
+                    message: String(i.message ?? 'Issue'),
+                    node_id: i.node_id ?? undefined,
+                    choice_id: i.choice_id ?? undefined,
+                };
+            });
+            setServerIssues(nextIssues);
+            setLastValidatedAt(new Date().toISOString());
+            return payload;
+        }
+        catch (err) {
+            const ex = err;
+            const errData = ex?.response?.data;
+            const msg = errData?.detail ??
+                errData?.error ??
+                err?.message ??
+                'Validation failed';
+            const parsed = parseServerErrorMessage(String(msg));
+            setServerIssues(parsed ?? [{ severity: TREE_SPEC_ISSUE_SEVERITY.ERROR, message: String(msg) }]);
+            setLastValidatedAt(new Date().toISOString());
+            return {
+                valid: false,
+                issues: [{ severity: TREE_SPEC_ISSUE_SEVERITY.ERROR, message: String(msg) }],
+            };
+        }
+    }, [adapter, entityId, parseServerErrorMessage, rawTreeSpec, tree]);
+    useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
+    // -----------------------------------------------------------------------
+    // Save draft + autosave.
+    // -----------------------------------------------------------------------
+    const saveDraft = useCallback(async () => {
+        if (!entityId || !tree)
+            return;
+        if (isPublished)
+            return;
+        setSaving(true);
+        setAutosaveStatus(AUTOSAVE_STATUS.SAVING);
+        try {
+            const compiled = compileTreeSpec(tree);
+            await adapter.updateVersion(entityId, { tree_spec: compiled });
+            setRawTreeSpec(compiled);
+            lastSavedKeyRef.current = JSON.stringify(compiled);
+            setAutosaveStatus(AUTOSAVE_STATUS.SAVED);
+        }
+        finally {
+            setSaving(false);
+        }
+    }, [adapter, entityId, isPublished, tree]);
+    useEffect(() => {
+        saveDraftRef.current = saveDraft;
+    }, [saveDraft]);
+    useEffect(() => {
+        if (!enableAutosave)
+            return;
+        if (!entityId || !tree)
+            return;
+        if (isPublished)
+            return;
+        if (saving || publishing)
+            return;
+        const compiled = compileTreeSpec(tree);
+        const key = JSON.stringify(compiled);
+        if (key === lastSavedKeyRef.current) {
+            if (autosaveStatus !== AUTOSAVE_STATUS.SAVED)
+                setAutosaveStatus(AUTOSAVE_STATUS.IDLE);
+            return;
+        }
+        setAutosaveStatus(AUTOSAVE_STATUS.DIRTY);
+        if (autosaveTimerRef.current) {
+            globalThis.clearTimeout(autosaveTimerRef.current);
+            autosaveTimerRef.current = null;
+        }
+        autosaveTimerRef.current = globalThis.setTimeout(() => {
+            void saveDraftRef.current();
+        }, autosaveDebounceMs);
+        return () => {
+            if (autosaveTimerRef.current) {
+                globalThis.clearTimeout(autosaveTimerRef.current);
+                autosaveTimerRef.current = null;
+            }
+        };
+        // NOTE: autosaveStatus is intentionally NOT in deps. The dirty/idle
+        // bookkeeping above flips status, and re-running the effect on every
+        // status change would reset the debounce timer.
+    }, [tree, entityId, isPublished, saving, publishing, autosaveDebounceMs, enableAutosave]);
+    // -----------------------------------------------------------------------
+    // Publish.
+    // -----------------------------------------------------------------------
+    const publish = useCallback(async () => {
+        if (!entityId || !tree || !adapter.publish)
+            return;
+        setPublishing(true);
+        try {
+            const compiled = compileTreeSpec(tree);
+            const vr = await validate(compiled);
+            if (vr?.valid === false)
+                return;
+            if (!canPublish)
+                return;
+            await adapter.publish(entityId);
+            setIsPublished(true);
+        }
+        finally {
+            setPublishing(false);
+        }
+    }, [adapter, canPublish, entityId, tree, validate]);
+    // -----------------------------------------------------------------------
+    // Snapshots: list (when modal opens), create, restore.
+    // -----------------------------------------------------------------------
+    useEffect(() => {
+        const listSnapshots = adapter.listSnapshots;
+        if (!listSnapshots || !showDraftHistory || !entityId)
+            return;
+        let cancelled = false;
+        setLoadingSnapshots(true);
+        void (async () => {
+            try {
+                const list = await listSnapshots(entityId);
+                if (!cancelled)
+                    setSnapshots(list);
+            }
+            finally {
+                if (!cancelled)
+                    setLoadingSnapshots(false);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [adapter, showDraftHistory, entityId]);
+    const createSnapshot = useCallback(async () => {
+        if (!entityId || !tree || !adapter.createSnapshot || !adapter.listSnapshots)
+            return;
+        setCreatingSnapshot(true);
+        try {
+            const compiled = compileTreeSpec(tree);
+            await adapter.createSnapshot(entityId, { label: '', tree_spec: compiled });
+            const list = await adapter.listSnapshots(entityId);
+            setSnapshots(list);
+        }
+        finally {
+            setCreatingSnapshot(false);
+        }
+    }, [adapter, entityId, tree]);
+    const restoreSnapshot = useCallback(async (snapshotId) => {
+        if (!entityId || !adapter.restoreSnapshot)
+            return;
+        setRestoringSnapshotId(snapshotId);
+        try {
+            const { tree_spec: rawSpec } = await adapter.restoreSnapshot(entityId, snapshotId);
+            const spec = coerceRawSpec(rawSpec);
+            if (spec != null) {
+                setRawTreeSpec(spec);
+                setTree(decompileTreeSpec(spec));
+                lastSavedKeyRef.current = JSON.stringify(spec);
+                setAutosaveStatus(AUTOSAVE_STATUS.IDLE);
+            }
+            setShowDraftHistory(false);
+        }
+        finally {
+            setRestoringSnapshotId(null);
+        }
+    }, [adapter, coerceRawSpec, entityId]);
+    // -----------------------------------------------------------------------
+    // Audit: list (when modal opens).
+    // -----------------------------------------------------------------------
+    useEffect(() => {
+        const listAudit = adapter.listAudit;
+        if (!listAudit || !showAudit || !entityId)
+            return;
+        let cancelled = false;
+        setLoadingAudit(true);
+        void (async () => {
+            try {
+                const list = await listAudit(entityId);
+                if (!cancelled)
+                    setAuditEvents(list);
+            }
+            finally {
+                if (!cancelled)
+                    setLoadingAudit(false);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [adapter, showAudit, entityId]);
+    // -----------------------------------------------------------------------
+    // Clone to Draft.
+    // -----------------------------------------------------------------------
+    const cloneToDraft = useCallback(async () => {
+        if (!entityId || !adapter.cloneToDraft)
+            return;
+        setCloning(true);
+        try {
+            const { id: newId } = await adapter.cloneToDraft(entityId);
+            if (newId)
+                onCloneNavigate?.(newId);
+        }
+        finally {
+            setCloning(false);
+        }
+    }, [adapter, entityId, onCloneNavigate]);
+    // -----------------------------------------------------------------------
+    // Node + tree operations.
+    // -----------------------------------------------------------------------
+    const triggerResetView = useCallback(() => setFitViewNonce((n) => n + 1), []);
+    const addNodeOfType = useCallback((type, patch) => {
+        if (!tree)
+            return undefined;
+        const id = `n_${safeUUID().slice(0, 8)}`;
+        const p = getNextSpawnPosition(tree);
+        const nextNode = {
+            id,
+            type,
+            prompt: patch?.prompt ?? '',
+            choices: patch?.choices ?? [],
+            position: patch?.position ?? p,
+        };
+        setTree({ ...tree, nodes: { ...tree.nodes, [id]: nextNode } });
+        setSelection({ kind: GRAPH_SELECTION_KIND.NODE, id });
+        setFocusNodeId(id);
+        return id;
+    }, [tree]);
+    const autoLayout = useCallback(() => {
+        if (!tree)
+            return;
+        setTree(autoLayoutTree(tree));
+        setFitViewNonce((n) => n + 1);
+    }, [tree]);
+    const insertTemplate = useCallback((spec) => {
+        if (!tree)
+            return;
+        const { nextTree, focusNodeId: spawnedFocusNodeId } = applyTreeTemplate(tree, spec);
+        setTree(nextTree);
+        setSelection({ kind: GRAPH_SELECTION_KIND.NODE, id: spawnedFocusNodeId });
+        setFocusNodeId(spawnedFocusNodeId);
+    }, [tree]);
+    // -----------------------------------------------------------------------
+    // Choice operations (when a node is selected).
+    // -----------------------------------------------------------------------
+    const updateSelectedNode = useCallback((patch) => {
+        if (!tree || !selectedNode)
+            return;
+        const next = { ...selectedNode, ...patch };
+        setTree({ ...tree, nodes: { ...tree.nodes, [selectedNode.id]: next } });
+    }, [tree, selectedNode]);
+    const addChoice = useCallback(() => {
+        if (!tree || !selectedNode)
+            return;
+        const choiceId = `c_${safeUUID().slice(0, 6)}`;
+        const nextChoice = { id: choiceId, label: 'New choice' };
+        updateSelectedNode({ choices: [...(selectedNode.choices ?? []), nextChoice] });
+    }, [tree, selectedNode, updateSelectedNode]);
+    const deleteChoice = useCallback((choiceId) => {
+        if (!tree || !selectedNode)
+            return;
+        const nextChoices = (selectedNode.choices ?? []).filter((c) => c.id !== choiceId);
+        const nextTree = deleteTransitionsForChoice(tree, selectedNode.id, choiceId);
+        setTree({
+            ...nextTree,
+            nodes: {
+                ...nextTree.nodes,
+                [selectedNode.id]: { ...selectedNode, choices: nextChoices },
+            },
+        });
+    }, [tree, selectedNode]);
+    const setChoiceTarget = useCallback((choiceId, targetNodeId) => {
+        if (!tree || !selectedNode)
+            return;
+        const existing = getTransition(tree, selectedNode.id, choiceId);
+        const next = {
+            id: existing?.id ?? safeUUID(),
+            fromNodeId: selectedNode.id,
+            fromChoiceId: choiceId,
+            toNodeId: targetNodeId,
+            outcome: targetNodeId === END_NODE_ID
+                ? (existing?.outcome ?? TERMINAL_OUTCOME.AT_RISK)
+                : undefined,
+        };
+        setTree(upsertTransition(tree, next));
+    }, [tree, selectedNode]);
+    const setChoiceOutcome = useCallback((choiceId, outcome) => {
+        if (!tree || !selectedNode)
+            return;
+        const existing = getTransition(tree, selectedNode.id, choiceId);
+        if (!existing)
+            return;
+        if (existing.toNodeId !== END_NODE_ID)
+            return;
+        if (outcome !== TERMINAL_OUTCOME.SAFE &&
+            outcome !== TERMINAL_OUTCOME.AT_RISK &&
+            outcome !== TERMINAL_OUTCOME.COMPROMISED)
+            return;
+        setTree(upsertTransition(tree, { ...existing, outcome }));
+    }, [tree, selectedNode]);
+    // -----------------------------------------------------------------------
+    // Issue selection helper (used by an Issues panel).
+    // -----------------------------------------------------------------------
+    const selectIssue = useCallback((issue) => {
+        if (!issue.node_id)
+            return;
+        setSelection({ kind: GRAPH_SELECTION_KIND.NODE, id: issue.node_id });
+        setFocusNodeId(issue.node_id);
+        setFocusChoiceId(issue.choice_id ?? null);
+        setFitViewNonce((n) => n + 1);
+    }, []);
+    const deleteNodeById = useCallback((nodeId) => {
+        if (!tree || isPublished)
+            return false;
+        const nextTree = deleteNode(tree, nodeId);
+        if (!nextTree)
+            return false;
+        setTree(nextTree);
+        const wasSelected = selection.kind === GRAPH_SELECTION_KIND.NODE && selection.id === nodeId;
+        if (wasSelected) {
+            setSelection({ kind: null, id: null });
+            setFocusChoiceId(null);
+        }
+        if (focusNodeId === nodeId) {
+            setFocusNodeId(null);
+        }
+        return true;
+    }, [tree, isPublished, selection, focusNodeId, setTree, setSelection, setFocusNodeId, setFocusChoiceId]);
+    const deleteSelectedNode = useCallback(() => {
+        if (selection.kind !== GRAPH_SELECTION_KIND.NODE || !selection.id)
+            return false;
+        return deleteNodeById(selection.id);
+    }, [deleteNodeById, selection]);
+    // -----------------------------------------------------------------------
+    // Scroll the focused choice into view when it changes.
+    // -----------------------------------------------------------------------
+    useEffect(() => {
+        if (!selectedNode || !focusChoiceId)
+            return;
+        if (typeof document === 'undefined')
+            return;
+        const el = document.getElementById(`choice-editor-${selectedNode.id}-${focusChoiceId}`);
+        el?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    }, [selectedNode, focusChoiceId]);
+    // -----------------------------------------------------------------------
+    // Keyboard shortcuts (Save/Validate/Preview/Duplicate/Delete).
+    // -----------------------------------------------------------------------
+    useEffect(() => {
+        if (!enableKeyboardShortcuts)
+            return;
+        if (typeof globalThis.addEventListener !== 'function')
+            return;
+        const onKeyDown = (e) => {
+            if (isTextFieldTarget(e.target))
+                return;
+            const selectedNodeId = selection.kind === GRAPH_SELECTION_KIND.NODE ? selection.id : null;
+            const shortcutAction = getKeyboardShortcutAction({
+                ctrlKey: e.ctrlKey,
+                metaKey: e.metaKey,
+                shiftKey: e.shiftKey,
+                key: e.key,
+                hasSelectedNode: Boolean(tree && selectedNodeId),
+            });
+            switch (shortcutAction) {
+                case KEYBOARD_SHORTCUT_ACTION.SAVE:
+                    e.preventDefault();
+                    void saveDraftRef.current();
+                    return;
+                case KEYBOARD_SHORTCUT_ACTION.VALIDATE:
+                    e.preventDefault();
+                    void validateRef.current();
+                    return;
+                case KEYBOARD_SHORTCUT_ACTION.PREVIEW:
+                    if (!onPreview)
+                        return;
+                    e.preventDefault();
+                    onPreview();
+                    return;
+                case KEYBOARD_SHORTCUT_ACTION.DUPLICATE: {
+                    if (!tree || !selectedNodeId)
+                        return;
+                    e.preventDefault();
+                    const duplicated = duplicateNode(tree, selectedNodeId);
+                    if (!duplicated)
+                        return;
+                    setTree(duplicated.nextTree);
+                    setSelection({ kind: GRAPH_SELECTION_KIND.NODE, id: duplicated.nextNodeId });
+                    setFocusNodeId(duplicated.nextNodeId);
+                    return;
+                }
+                case KEYBOARD_SHORTCUT_ACTION.DELETE: {
+                    if (!tree || !selectedNodeId)
+                        return;
+                    if (deleteSelectedNode()) {
+                        e.preventDefault();
+                    }
+                    return;
+                }
+                default:
+                    return;
+            }
+        };
+        globalThis.addEventListener('keydown', onKeyDown);
+        return () => globalThis.removeEventListener('keydown', onKeyDown);
+    }, [enableKeyboardShortcuts, onPreview, tree, selection, deleteSelectedNode]);
+    // -----------------------------------------------------------------------
+    // Compose the public surface.
+    // -----------------------------------------------------------------------
+    const state = {
+        loading,
+        saving,
+        publishing,
+        creatingSnapshot,
+        cloning,
+        restoringSnapshotId,
+        autosaveStatus,
+        lastValidatedAt,
+        rawTreeSpec,
+        tree,
+        baselineTree,
+        compiledTreeSpec,
+        isPublished,
+        versionInfo,
+        hasTree: Boolean(tree),
+        localIssues,
+        serverIssues,
+        runtimeIssues,
+        issues,
+        canPublish,
+        selection,
+        focusNodeId,
+        focusChoiceId,
+        fitViewNonce,
+        selectedNode,
+        selectedEdge,
+        nodeSearch,
+        issueSearch,
+        showMiniMap,
+        snapshots,
+        auditEvents,
+        loadingSnapshots,
+        loadingAudit,
+        showDraftHistory,
+        showAudit,
+        showPublishModal,
+    };
+    const actions = {
+        setTree,
+        setSelection,
+        setFocusNodeId,
+        setFocusChoiceId,
+        triggerResetView,
+        setNodeSearch,
+        setIssueSearch,
+        setShowMiniMap,
+        setShowDraftHistory,
+        setShowAudit,
+        setShowPublishModal,
+        addNodeOfType,
+        deleteSelectedNode,
+        deleteNodeById,
+        autoLayout,
+        insertTemplate,
+        validate,
+        saveDraft,
+        publish,
+        createSnapshot,
+        restoreSnapshot,
+        cloneToDraft,
+        updateSelectedNode,
+        addChoice,
+        deleteChoice,
+        setChoiceTarget,
+        setChoiceOutcome,
+        selectIssue,
+    };
+    return { ...state, actions };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * Headless React layer for the SignalSafe TreeSpec graph editor.
+ *
+ * This package owns the React Flow canvas and the framework-shaped
+ * orchestration hook ({@link useTreeSpecEditor}). It depends on `react`,
+ * `react-dom`, `reactflow`, and `@signalsafe/tree-spec-editor-core`, but is
+ * intentionally free of any UI library (no `react-bootstrap`, no Material,
+ * no Tailwind) and any router (no `react-router-dom`, no Next.js router).
+ * UI shells layer on top of this package; routing is host-injected via hook
+ * callbacks.
+ */
+export { default } from './TreeSpecGraphEditor';
+export type { TreeSpecGraphEditorProps } from './TreeSpecGraphEditor';
+export { useTreeSpecEditor } from './hooks/useTreeSpecEditor';
+export type { AdapterValidationIssue, GraphEditorVersionInfo, TreeSpecEditorAdapter, UseTreeSpecEditorActions, UseTreeSpecEditorOptions, UseTreeSpecEditorResult, UseTreeSpecEditorState, } from './hooks/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EACR,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,GACzB,MAAM,eAAe,CAAC"}