@signalsafe/tree-spec-editor-react 0.1.1 → 0.1.3

package/dist/hooks/useTreeSpecEditor.js

@@ -1,6 +1,11 @@
 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';
+import { compileTreeSpec, decompileTreeSpec, TERMINAL_OUTCOME, TREE_SPEC_ISSUE_SEVERITY, } from '@signalsafe/tree-spec';
+import { applyTreeTemplate, autoLayoutTree, AUTOSAVE_STATUS, deleteNode, deleteTransitionsForChoice, END_NODE_ID, getNextSpawnPosition, getTransition, GRAPH_SELECTION_KIND, moveChoiceInTree, moveNodeChoice, patchChoiceEdgeHints, patchGraphEditorMeta, renameNodeChoiceId, safeUUID, upsertTransition, } from '@signalsafe/tree-spec-editor-core';
+import { useEditorAdapter } from './useEditorAdapter.js';
+import { useEditorAutosave } from './useEditorAutosave.js';
+import { useEditorHistory } from './useEditorHistory.js';
+import { useEditorSelection } from './useEditorSelection.js';
+import { dispatchEditorKeyboardShortcut, resolveEditorKeyboardShortcutAction } from './keyboardShortcutDispatch.js';
 const DEFAULT_AUTOSAVE_DEBOUNCE_MS = 2500;
 function isTextFieldTarget(target) {
     const tag = target instanceof HTMLElement ? target.tagName.toLowerCase() : '';
@@ -14,69 +19,56 @@ function isTextFieldTarget(target) {
  * 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 { adapter, entityId, autosaveDebounceMs = DEFAULT_AUTOSAVE_DEBOUNCE_MS, enableAutosave = true, enableKeyboardShortcuts = true, computeRuntimeIssues, debugMode = false, onPreview, } = options;
+    const lastSavedKeyRef = useRef('');
     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 history = useEditorHistory(isPublished);
+    const { tree, canUndo, canRedo, hasCopiedNode, commitTree, replaceTreeWithoutHistory, undo, redo, copySelectedNode: copySelectedNodeInternal, pasteCopiedNode: pasteCopiedNodeInternal, duplicateNodeById: duplicateNodeByIdInternal, } = history;
+    const adapterState = useEditorAdapter({
+        options,
+        tree,
+        isPublished,
+        setIsPublished,
+        replaceTreeWithoutHistory,
+        lastSavedKeyRef,
+        setAutosaveStatus,
+    });
+    const selectionState = useEditorSelection(tree);
+    const { selection, focusNodeId, focusChoiceId, fitViewNonce, selectedNode, selectedEdge, inspectorNode, selectChoice, applySelection, setFocusNodeId, setFocusChoiceId, triggerResetView, selectIssue, setSelection, } = selectionState;
+    useEditorAutosave({
+        enableAutosave,
+        autosaveDebounceMs,
+        entityId,
+        tree,
+        isPublished,
+        saving: adapterState.saving,
+        publishing: adapterState.publishing,
+        autosaveStatus,
+        setAutosaveStatus,
+        lastSavedKeyRef,
+        saveDraftRef: adapterState.saveDraftRef,
+    });
     const baselineTree = useMemo(() => {
-        if (!rawTreeSpec)
+        if (!adapterState.rawTreeSpec)
             return null;
         try {
-            return decompileTreeSpec(rawTreeSpec);
+            return decompileTreeSpec(adapterState.rawTreeSpec);
         }
         catch {
             return null;
         }
-    }, [rawTreeSpec]);
+    }, [adapterState.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];
+        const groups = debugMode
+            ? [adapterState.localIssues, adapterState.serverIssues]
+            : [adapterState.localIssues, runtimeIssues, adapterState.serverIssues];
         for (const arr of groups) {
             for (const i of arr) {
                 const key = `${i.severity}|${i.message}|${i.node_id ?? ''}|${i.choice_id ?? ''}`;
@@ -87,201 +79,15 @@ export function useTreeSpecEditor(options) {
             }
         }
         return out;
-    }, [localIssues, serverIssues, runtimeIssues, debugMode]);
+    }, [adapterState.localIssues, adapterState.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);
+        adapterState.setPublishing(true);
         try {
             const compiled = compileTreeSpec(tree);
-            const vr = await validate(compiled);
+            const vr = await adapterState.validate(compiled);
             if (vr?.valid === false)
                 return;
             if (!canPublish)
@@ -290,110 +96,12 @@ export function useTreeSpecEditor(options) {
             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);
+            adapterState.setPublishing(false);
         }
-    }, [adapter, entityId, onCloneNavigate]);
-    // -----------------------------------------------------------------------
-    // Node + tree operations.
-    // -----------------------------------------------------------------------
-    const triggerResetView = useCallback(() => setFitViewNonce((n) => n + 1), []);
+    }, [adapter, adapterState, canPublish, entityId, tree]);
+    const [nodeSearch, setNodeSearch] = useState('');
+    const [issueSearch, setIssueSearch] = useState('');
+    const [showMiniMap, setShowMiniMap] = useState(true);
     const addNodeOfType = useCallback((type, patch) => {
         if (!tree)
             return undefined;
@@ -406,34 +114,34 @@ export function useTreeSpecEditor(options) {
             choices: patch?.choices ?? [],
             position: patch?.position ?? p,
         };
-        setTree({ ...tree, nodes: { ...tree.nodes, [id]: nextNode } });
+        commitTree({ ...tree, nodes: { ...tree.nodes, [id]: nextNode } });
         setSelection({ kind: GRAPH_SELECTION_KIND.NODE, id });
         setFocusNodeId(id);
         return id;
-    }, [tree]);
+    }, [tree, commitTree, setSelection, setFocusNodeId]);
     const autoLayout = useCallback(() => {
         if (!tree)
             return;
-        setTree(autoLayoutTree(tree));
-        setFitViewNonce((n) => n + 1);
-    }, [tree]);
+        commitTree(autoLayoutTree(tree));
+        triggerResetView();
+    }, [tree, commitTree, triggerResetView]);
     const insertTemplate = useCallback((spec) => {
         if (!tree)
             return;
         const { nextTree, focusNodeId: spawnedFocusNodeId } = applyTreeTemplate(tree, spec);
-        setTree(nextTree);
+        commitTree(nextTree);
         setSelection({ kind: GRAPH_SELECTION_KIND.NODE, id: spawnedFocusNodeId });
         setFocusNodeId(spawnedFocusNodeId);
-    }, [tree]);
-    // -----------------------------------------------------------------------
-    // Choice operations (when a node is selected).
-    // -----------------------------------------------------------------------
+    }, [tree, commitTree, setSelection, setFocusNodeId]);
+    const copySelectedNode = useCallback(() => copySelectedNodeInternal(selection), [copySelectedNodeInternal, selection]);
+    const pasteCopiedNode = useCallback(() => pasteCopiedNodeInternal(setSelection, setFocusNodeId), [pasteCopiedNodeInternal, setSelection, setFocusNodeId]);
+    const duplicateNodeById = useCallback((nodeId) => duplicateNodeByIdInternal(nodeId, setSelection, setFocusNodeId), [duplicateNodeByIdInternal, setSelection, setFocusNodeId]);
     const updateSelectedNode = useCallback((patch) => {
         if (!tree || !selectedNode)
             return;
         const next = { ...selectedNode, ...patch };
-        setTree({ ...tree, nodes: { ...tree.nodes, [selectedNode.id]: next } });
-    }, [tree, selectedNode]);
+        commitTree({ ...tree, nodes: { ...tree.nodes, [selectedNode.id]: next } });
+    }, [tree, selectedNode, commitTree]);
     const addChoice = useCallback(() => {
         if (!tree || !selectedNode)
             return;
@@ -441,19 +149,67 @@ export function useTreeSpecEditor(options) {
         const nextChoice = { id: choiceId, label: 'New choice' };
         updateSelectedNode({ choices: [...(selectedNode.choices ?? []), nextChoice] });
     }, [tree, selectedNode, updateSelectedNode]);
+    const setChoiceType = useCallback((choiceId, typeId, defaultLabel) => {
+        if (!tree || !selectedNode)
+            return;
+        const next = renameNodeChoiceId(tree, selectedNode.id, choiceId, typeId);
+        if (!next)
+            return;
+        if (defaultLabel) {
+            const node = next.nodes[selectedNode.id];
+            if (node) {
+                const choices = (node.choices ?? []).map((choice) => {
+                    if (choice.id !== typeId)
+                        return choice;
+                    if (choice.label === 'New choice' || !choice.label.trim()) {
+                        return { ...choice, label: defaultLabel };
+                    }
+                    return choice;
+                });
+                next.nodes[selectedNode.id] = { ...node, choices };
+            }
+        }
+        commitTree(next);
+        if (focusChoiceId === choiceId) {
+            selectChoice(selectedNode.id, typeId);
+        }
+    }, [tree, selectedNode, commitTree, focusChoiceId, selectChoice]);
     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({
+        commitTree({
             ...nextTree,
             nodes: {
                 ...nextTree.nodes,
                 [selectedNode.id]: { ...selectedNode, choices: nextChoices },
             },
         });
-    }, [tree, selectedNode]);
+    }, [tree, selectedNode, commitTree]);
+    const moveChoice = useCallback((choiceId, direction) => {
+        if (!tree || !selectedNode)
+            return;
+        const nextChoices = moveNodeChoice(selectedNode.choices ?? [], choiceId, direction);
+        if (!nextChoices)
+            return;
+        commitTree({
+            ...tree,
+            nodes: {
+                ...tree.nodes,
+                [selectedNode.id]: { ...selectedNode, choices: nextChoices },
+            },
+        });
+    }, [tree, selectedNode, commitTree]);
+    const repositionChoice = useCallback((fromNodeId, choiceId, toNodeId, toIndex) => {
+        if (!tree)
+            return;
+        const next = moveChoiceInTree(tree, fromNodeId, choiceId, toNodeId, toIndex);
+        if (!next)
+            return;
+        commitTree(next);
+        selectChoice(toNodeId, choiceId);
+    }, [tree, commitTree, selectChoice]);
     const setChoiceTarget = useCallback((choiceId, targetNodeId) => {
         if (!tree || !selectedNode)
             return;
@@ -467,8 +223,8 @@ export function useTreeSpecEditor(options) {
                 ? (existing?.outcome ?? TERMINAL_OUTCOME.AT_RISK)
                 : undefined,
         };
-        setTree(upsertTransition(tree, next));
-    }, [tree, selectedNode]);
+        commitTree(upsertTransition(tree, next));
+    }, [tree, selectedNode, commitTree]);
     const setChoiceOutcome = useCallback((choiceId, outcome) => {
         if (!tree || !selectedNode)
             return;
@@ -481,26 +237,35 @@ export function useTreeSpecEditor(options) {
             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)
+        commitTree(upsertTransition(tree, { ...existing, outcome }));
+    }, [tree, selectedNode, commitTree]);
+    const updateChoiceEdgeHints = useCallback((nodeId, choiceId, patch) => {
+        if (!tree)
+            return;
+        const node = tree.nodes[nodeId];
+        if (!node)
             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 choices = (node.choices ?? []).map((choice) => choice.id === choiceId ? patchChoiceEdgeHints(choice, patch) : choice);
+        commitTree({
+            ...tree,
+            nodes: {
+                ...tree.nodes,
+                [nodeId]: { ...node, choices },
+            },
+        });
+    }, [tree, commitTree]);
+    const setDefaultEdgeType = useCallback((edgeType) => {
+        if (!tree)
+            return;
+        commitTree(patchGraphEditorMeta(tree, { default_edge_type: edgeType }));
+    }, [tree, commitTree]);
     const deleteNodeById = useCallback((nodeId) => {
         if (!tree || isPublished)
             return false;
         const nextTree = deleteNode(tree, nodeId);
         if (!nextTree)
             return false;
-        setTree(nextTree);
+        commitTree(nextTree);
         const wasSelected = selection.kind === GRAPH_SELECTION_KIND.NODE && selection.id === nodeId;
         if (wasSelected) {
             setSelection({ kind: null, id: null });
@@ -510,26 +275,21 @@ export function useTreeSpecEditor(options) {
             setFocusNodeId(null);
         }
         return true;
-    }, [tree, isPublished, selection, focusNodeId, setTree, setSelection, setFocusNodeId, setFocusChoiceId]);
+    }, [
+        tree,
+        isPublished,
+        selection,
+        focusNodeId,
+        commitTree,
+        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;
@@ -538,77 +298,71 @@ export function useTreeSpecEditor(options) {
         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),
+            const shortcutAction = resolveEditorKeyboardShortcutAction(e, {
+                tree,
+                selection,
+                canUndo,
+                canRedo,
+                hasCopiedNode,
+                isPublished,
+            });
+            dispatchEditorKeyboardShortcut(shortcutAction, e, {
+                tree,
+                selection,
+                isPublished,
+                onPreview,
+                undo,
+                redo,
+                copySelectedNode,
+                pasteCopiedNode,
+                deleteSelectedNode,
+                saveDraft: () => void adapterState.saveDraftRef.current?.(),
+                validate: () => void adapterState.validateRef.current?.(),
+                commitTree,
+                setSelection: applySelection,
+                setFocusNodeId,
             });
-            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.
-    // -----------------------------------------------------------------------
+    }, [
+        enableKeyboardShortcuts,
+        onPreview,
+        tree,
+        selection,
+        deleteSelectedNode,
+        canUndo,
+        canRedo,
+        hasCopiedNode,
+        isPublished,
+        undo,
+        redo,
+        copySelectedNode,
+        pasteCopiedNode,
+        commitTree,
+        applySelection,
+        setFocusNodeId,
+        adapterState.saveDraftRef,
+        adapterState.validateRef,
+    ]);
     const state = {
-        loading,
-        saving,
-        publishing,
-        creatingSnapshot,
-        cloning,
-        restoringSnapshotId,
+        loading: adapterState.loading,
+        saving: adapterState.saving,
+        publishing: adapterState.publishing,
+        creatingSnapshot: adapterState.creatingSnapshot,
+        cloning: adapterState.cloning,
+        restoringSnapshotId: adapterState.restoringSnapshotId,
         autosaveStatus,
-        lastValidatedAt,
-        rawTreeSpec,
+        lastValidatedAt: adapterState.lastValidatedAt,
+        rawTreeSpec: adapterState.rawTreeSpec,
         tree,
         baselineTree,
         compiledTreeSpec,
         isPublished,
-        versionInfo,
+        versionInfo: adapterState.versionInfo,
         hasTree: Boolean(tree),
-        localIssues,
-        serverIssues,
+        localIssues: adapterState.localIssues,
+        serverIssues: adapterState.serverIssues,
         runtimeIssues,
         issues,
         canPublish,
@@ -618,46 +372,61 @@ export function useTreeSpecEditor(options) {
         fitViewNonce,
         selectedNode,
         selectedEdge,
+        inspectorNode,
         nodeSearch,
         issueSearch,
         showMiniMap,
-        snapshots,
-        auditEvents,
-        loadingSnapshots,
-        loadingAudit,
-        showDraftHistory,
-        showAudit,
-        showPublishModal,
+        snapshots: adapterState.snapshots,
+        auditEvents: adapterState.auditEvents,
+        loadingSnapshots: adapterState.loadingSnapshots,
+        loadingAudit: adapterState.loadingAudit,
+        showDraftHistory: adapterState.showDraftHistory,
+        showAudit: adapterState.showAudit,
+        showPublishModal: adapterState.showPublishModal,
+        canUndo,
+        canRedo,
+        hasCopiedNode,
     };
     const actions = {
-        setTree,
-        setSelection,
+        setTree: commitTree,
+        setSelection: applySelection,
+        selectChoice,
         setFocusNodeId,
         setFocusChoiceId,
         triggerResetView,
         setNodeSearch,
         setIssueSearch,
         setShowMiniMap,
-        setShowDraftHistory,
-        setShowAudit,
-        setShowPublishModal,
+        setShowDraftHistory: adapterState.setShowDraftHistory,
+        setShowAudit: adapterState.setShowAudit,
+        setShowPublishModal: adapterState.setShowPublishModal,
         addNodeOfType,
         deleteSelectedNode,
         deleteNodeById,
         autoLayout,
         insertTemplate,
-        validate,
-        saveDraft,
+        validate: adapterState.validate,
+        saveDraft: adapterState.saveDraft,
         publish,
-        createSnapshot,
-        restoreSnapshot,
-        cloneToDraft,
+        createSnapshot: adapterState.createSnapshot,
+        restoreSnapshot: adapterState.restoreSnapshot,
+        cloneToDraft: adapterState.cloneToDraft,
         updateSelectedNode,
         addChoice,
+        setChoiceType,
         deleteChoice,
+        moveChoice,
+        repositionChoice,
         setChoiceTarget,
         setChoiceOutcome,
+        updateChoiceEdgeHints,
+        setDefaultEdgeType,
         selectIssue,
+        undo,
+        redo,
+        copySelectedNode,
+        pasteCopiedNode,
+        duplicateNodeById,
     };
     return { ...state, actions };
 }