@signalsafe/tree-spec-editor

React graph editor for authoring TreeSpec content.

This package gives you a ready-to-embed editor component plus a small set of editor helpers. It is focused on graph editing only: nodes, choices, transitions, selection, layout, and validation hints.

Install

npm install @signalsafe/tree-spec-editor react react-dom reactflow

Happy Path

The smallest useful integration is:

1. Keep an EditorTree in React state.
2. Render TreeSpecGraphEditor.
3. Replace the state value in onChange.

The screenshot below was captured from the exact example tree in this section.

import { useState, type JSX } from 'react';
import TreeSpecGraphEditor, {
    END_NODE_ID,
    type EditorTree,
} from '@signalsafe/tree-spec-editor';

const initialTree: EditorTree = {
    start_node: 'start',
    nodes: {
        start: {
            id: 'start',
            type: 'prompt',
            prompt: 'A message asks for your company password.',
            choices: [
                { id: 'report', label: 'Report it to security' },
                { id: 'enter-password', label: 'Enter my password' },
            ],
            position: { x: 40, y: 260 },
        },
        follow_up: {
            id: 'follow_up',
            type: 'prompt',
            prompt: 'Security asks for a screenshot.',
            choices: [{ id: 'send', label: 'Send the screenshot' }],
            position: { x: 420, y: 420 },
        },
    },
    transitions: [
        {
            id: 'start-report',
            fromNodeId: 'start',
            fromChoiceId: 'report',
            toNodeId: 'follow_up',
        },
        {
            id: 'start-enter-password',
            fromNodeId: 'start',
            fromChoiceId: 'enter-password',
            toNodeId: END_NODE_ID,
            outcome: 'compromised',
        },
        {
            id: 'follow-up-send',
            fromNodeId: 'follow_up',
            fromChoiceId: 'send',
            toNodeId: END_NODE_ID,
            outcome: 'safe',
        },
    ],
};

export function ExampleTreeSpecEditor(): JSX.Element {
    const [tree, setTree] = useState<EditorTree>(initialTree);

    return (
        <TreeSpecGraphEditor
            tree={tree}
            onChange={setTree}
            className="h-[70vh] rounded border"
        />
    );
}

What You Get

• TreeSpecGraphEditor: the default React editor component.
• EditorTree, EditorNode, EditorTransition, EditorChoice: editor model types.
• GraphSelection and GraphEditorIssue: optional selection and issue-display types.
• autoLayoutTree and getNextSpawnPosition: layout helpers for placing nodes.
• lintEditorTree, getTransition, upsertTransition, deleteTransitionsForChoice: editor helpers for validation and transition updates.

Feature Examples

Show validation issues

Pass issues when you want the editor to highlight problem nodes and edges.

The screenshot below was captured from the exact example tree in this section.

import { useMemo, useState, type JSX } from 'react';
import TreeSpecGraphEditor, {
    END_NODE_ID,
    lintEditorTree,
    type EditorTree,
    type GraphEditorIssue,
} from '@signalsafe/tree-spec-editor';

const validationTree: EditorTree = {
    start_node: 'start',
    nodes: {
        start: {
            id: 'start',
            type: 'prompt',
            prompt: 'Review the message before acting.',
            choices: [
                { id: 'investigate', label: 'Investigate' },
                { id: 'escalate', label: 'Escalate' },
            ],
            position: { x: 40, y: 260 },
        },
        follow_up: {
            id: 'follow_up',
            type: 'prompt',
            prompt: 'Collect a screenshot and report it.',
            choices: [{ id: 'send', label: 'Send screenshot' }],
            position: { x: 420, y: 420 },
        },
    },
    transitions: [
        {
            id: 'start-investigate',
            fromNodeId: 'start',
            fromChoiceId: 'investigate',
            toNodeId: 'follow_up',
        },
        {
            id: 'start-escalate',
            fromNodeId: 'start',
            fromChoiceId: 'escalate',
            toNodeId: END_NODE_ID,
        },
        {
            id: 'follow-up-send',
            fromNodeId: 'follow_up',
            fromChoiceId: 'send',
            toNodeId: END_NODE_ID,
            outcome: 'safe',
        },
    ],
};

export function EditorWithIssues(): JSX.Element {
    const [tree, setTree] = useState<EditorTree>(validationTree);
    const issues = useMemo<GraphEditorIssue[]>(() => lintEditorTree(tree), [tree]);

    return <TreeSpecGraphEditor tree={tree} onChange={setTree} issues={issues} />;
}

Track selection

Pass selected and onSelect when another part of your page needs to know which node or edge is active.

import { useState, type JSX } from 'react';
import TreeSpecGraphEditor, {
    type EditorTree,
    type GraphSelection,
} from '@signalsafe/tree-spec-editor';

type Props = {
    initialTree: EditorTree;
};

export function EditorWithSelection({ initialTree }: Props): JSX.Element {
    const [tree, setTree] = useState<EditorTree>(initialTree);
    const [selected, setSelected] = useState<GraphSelection>({ kind: null, id: null });

    return (
        <TreeSpecGraphEditor
            tree={tree}
            onChange={setTree}
            selected={selected}
            onSelect={setSelected}
        />
    );
}

Focus a node and hide the minimap

Use focusNodeId when you want the editor to center a node, and showMiniMap={false} when you want a simpler layout.

import { useState, type JSX } from 'react';
import TreeSpecGraphEditor, {
    type EditorTree,
} from '@signalsafe/tree-spec-editor';

type Props = {
    initialTree: EditorTree;
};

export function FocusedEditor({ initialTree }: Props): JSX.Element {
    const [tree, setTree] = useState<EditorTree>(initialTree);

    return (
        <TreeSpecGraphEditor
            tree={tree}
            onChange={setTree}
            focusNodeId="start"
            showMiniMap={false}
        />
    );
}

Refit the graph after external changes

Increment fitViewNonce when your page adds, removes, or rearranges nodes and you want the editor to recenter everything.

import { useState, type JSX } from 'react';
import TreeSpecGraphEditor, {
    type EditorTree,
} from '@signalsafe/tree-spec-editor';

type Props = {
    initialTree: EditorTree;
};

export function EditorWithFitView({ initialTree }: Props): JSX.Element {
    const [tree, setTree] = useState<EditorTree>(initialTree);
    const [fitViewNonce, setFitViewNonce] = useState<number>(1);

    return (
        <>
            <button type="button" onClick={() => setFitViewNonce((value) => value + 1)}>
                Refit graph
            </button>
            <TreeSpecGraphEditor
                tree={tree}
                onChange={setTree}
                fitViewNonce={fitViewNonce}
            />
        </>
    );
}

Helper Examples

Use autoLayoutTree before first render when you want a readable default layout.

import { autoLayoutTree, type EditorTree } from '@signalsafe/tree-spec-editor';

const tree: EditorTree = autoLayoutTree({
    start_node: 'start',
    nodes: {
        start: {
            id: 'start',
            type: 'prompt',
            prompt: 'Choose a response',
            choices: [{ id: 'continue', label: 'Continue' }],
            position: { x: 0, y: 0 },
        },
    },
    transitions: [],
});

Use lintEditorTree when you want editor-side warnings or errors to display next to nodes and edges.

import { lintEditorTree, type GraphEditorIssue } from '@signalsafe/tree-spec-editor';

const issues: GraphEditorIssue[] = lintEditorTree(tree);

Use getTransition, upsertTransition, and deleteTransitionsForChoice when a host toolbar needs to read or replace a choice transition.

import {
    END_NODE_ID,
    deleteTransitionsForChoice,
    getTransition,
    upsertTransition,
    type EditorTree,
    type EditorTransition,
} from '@signalsafe/tree-spec-editor';

function connectChoiceToEnd(tree: EditorTree, fromNodeId: string, fromChoiceId: string): EditorTree {
    const existing = getTransition(tree, fromNodeId, fromChoiceId);

    const nextTransition: EditorTransition = {
        id: existing?.id ?? `${fromNodeId}-${fromChoiceId}-to-end`,
        fromNodeId,
        fromChoiceId,
        toNodeId: END_NODE_ID,
        outcome: 'safe',
    };

    return upsertTransition(tree, nextTransition);
}

function clearChoiceTransition(tree: EditorTree, fromNodeId: string, fromChoiceId: string): EditorTree {
    return deleteTransitionsForChoice(tree, fromNodeId, fromChoiceId);
}

Use parsePydanticOutcomeErrors when your backend returns a generic validation string and you want node-level editor issues.

import {
    parsePydanticOutcomeErrors,
    type GraphEditorIssue,
} from '@signalsafe/tree-spec-editor';

const backendMessage =
    "Transition to END must include outcome. input_value={'from': ['start', 'escalate'], 'to': 'END'}";

const issues: GraphEditorIssue[] = parsePydanticOutcomeErrors(backendMessage) ?? [];

Use getNextSpawnPosition, safeUUID, and TREE_SPEC_NODE_TYPE_PRESETS when a host UI creates new nodes outside the canvas.

import {
    TREE_SPEC_NODE_TYPE_PRESETS,
    getNextSpawnPosition,
    safeUUID,
    type EditorNode,
    type EditorTree,
} from '@signalsafe/tree-spec-editor';

function addPromptNode(tree: EditorTree): EditorTree {
    const id = safeUUID();
    const position = getNextSpawnPosition(tree);
    const type = TREE_SPEC_NODE_TYPE_PRESETS[0];

    const nextNode: EditorNode = {
        id,
        type,
        prompt: 'New step',
        choices: [{ id: 'choice-1', label: 'New choice' }],
        position,
    };

    return {
        ...tree,
        nodes: {
            ...tree.nodes,
            [id]: nextNode,
        },
    };
}

Notes

• Import from the package root only.
• Install react, react-dom, and reactflow in the consuming app.
• If you need wire-format compile/decompile helpers, use @signalsafe/tree-spec.