@signalsafe/tree-spec-editor 0.1.2 → 0.2.0

package/README.md

@@ -7,9 +7,40 @@ This package gives you a ready-to-embed editor component plus a small set of edi
 ## Install
 
 ```bash
-npm install @signalsafe/tree-spec-editor react react-dom reactflow
+npm install @signalsafe/tree-spec-editor react react-dom reactflow react-bootstrap
 ```
 
+The package ships React components that use `react-bootstrap` primitives (cards, buttons, form controls). The consuming app must install `react-bootstrap@^2.10.0` and load Bootstrap CSS in the usual way.
+
+## Source layout (maintainers)
+
+Published consumers import only the package root (`@signalsafe/tree-spec-editor`). This package is the **React + Bootstrap UI shell** in the layered editor stack:
+
+| Layer | Package | Owns |
+|-------|---------|------|
+| Wire | [`@signalsafe/tree-spec`](../tree-spec/README.md) | TreeSpec wire types, constants, compile/lint. Pure TS. |
+| Core | [`@signalsafe/tree-spec-editor-core`](../tree-spec-editor-core/README.md) | Editor model, tree operations, layout/autosave/keyboard helpers, constants. Pure TS. |
+| React | [`@signalsafe/tree-spec-editor-react`](../tree-spec-editor-react/README.md) | React Flow canvas (`TreeSpecGraphEditor`). React-specific, UI-library-agnostic. |
+| Shell | **`@signalsafe/tree-spec-editor`** (this package) | React + Bootstrap panels, modals, toolbar, Bootstrap badge helper. Re-exports the canvas from `-react` and the framework-agnostic surface from `-core` for one-stop import. |
+
+| Directory | Contents |
+|-----------|----------|
+| `src/panels/` | Sidebar, toolbar, inspector, and JSON chrome components (React + `react-bootstrap`) |
+| `src/modals/` | Publish review, draft history, and audit log dialogs (React + `react-bootstrap`) |
+| `src/lib/panelHelpers.ts` | `getIssueSeverityBadgeClass` (Bootstrap-flavored — Material / Angular shells ship their own equivalent) |
+| `src/index.ts` | Public barrel — **do not** import from subpaths in apps. Re-exports the canvas from `@signalsafe/tree-spec-editor-react` and the framework-agnostic surface from `@signalsafe/tree-spec-editor-core` |
+
+Tests live under `tests/panels/`, `tests/modals/`, plus `tests/index.test.ts` for the barrel. The canvas test lives in **`packages/tree-spec-editor-react/tests/`** and the framework-agnostic helper tests live in **`packages/tree-spec-editor-core/tests/`**.
+
+## Choosing the right package
+
+| You want… | Import from |
+|----------|-------------|
+| The full React + Bootstrap editor (canvas + panels + modals + toolbar) | `@signalsafe/tree-spec-editor` (this package) |
+| Just the canvas, with your own UI library (Material / Tailwind / custom) | `@signalsafe/tree-spec-editor-react` |
+| Just the framework-agnostic helpers (CLI, server-side preview, Angular shell) | `@signalsafe/tree-spec-editor-core` |
+| Just the wire contract (validation, compile, lint) | `@signalsafe/tree-spec` |
+
 ## Happy Path
 
 The smallest useful integration is:
@@ -90,10 +121,22 @@ export function ExampleTreeSpecEditor(): JSX.Element {
 ## What You Get
 
 - `TreeSpecGraphEditor`: the default React editor component.
+- `IssuesPanel`, `NodesPanel`: presentational sidebar panels for issues and node search/selection.
+- `AdvancedJsonPanel`: presentational card chrome for displaying a host-owned JSON renderer (e.g. the compiled `tree_spec`).
+- `InspectorPanel`: right-rail node inspector (Type / Prompt / Choices with Label / Next / Outcome / Delete) with optional render-prop slots and overridable outcome options for project-specific extensions.
+- `SelectedEdgePanel`: compact read-only card showing the currently selected transition.
+- `PublishReviewModal`, `DraftHistoryModal`, `AuditLogModal`: presentational modals for the publish-review / draft-snapshot / audit-log authoring flows; all strings are overridable.
+- `ToolbarPanel`: data-driven toolbar that takes an `items: ToolbarItem[]` array (`button` / `dropdown` / `badge` / `text` / `custom` kinds) and renders Bootstrap chrome in a single flex wrapper.
+- `duplicateNode`, `deleteNode`, `computeTreeDiffSummary`, `applyTreeTemplate`: project-agnostic tree-operation helpers (clone a node, delete a node with cascade, summarize a structural diff, insert a reusable subgraph template).
+- `getAutosaveStatusLabel`, `getKeyboardShortcutAction`, `shouldQueueInitialValidation`: editor-lifecycle helpers (default autosave label, default keyboard-shortcut mapper, "should we validate on load?" tri-state policy).
+- `AUTOSAVE_STATUS`, `KEYBOARD_SHORTCUT_ACTION`, `GRAPH_SELECTION_KIND`, `TOOLBAR_ITEM_KIND`: runtime constant objects for the matching string-union types. Use these instead of bare string literals (`AUTOSAVE_STATUS.SAVING`, `KEYBOARD_SHORTCUT_ACTION.SAVE`, `GRAPH_SELECTION_KIND.NODE`, `TOOLBAR_ITEM_KIND.BUTTON`). The types (`AutosaveStatus`, `KeyboardShortcutAction`, `GraphSelectionKind`, `ToolbarItemKind`) are derived from these constants.
+- `DEFAULT_OUTCOME_OPTIONS`: the canonical TerminalOutcome list used by `InspectorPanel`'s outcome `<select>` when no override is supplied.
+- `TreeSpecSnapshotItem`, `TreeSpecAuditEventItem`: canonical data shapes consumed by the draft-history and audit-log modals.
 - `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.
+- `buildStableEntries`, `getIssueSeverityBadgeClass`: small helpers reused by the sidebar panels and available for hosts that compose their own UI.
 
 ## Feature Examples
 
@@ -257,6 +300,618 @@ export function EditorWithFitView({ initialTree }: Props): JSX.Element {
 }
 ```
 
+## Sidebar Panels
+
+The package also ships two presentational components for the editor's left rail. They are purely view-only: the host owns all state (issues, selection, search query, minimap toggle) and passes callbacks back in.
+
+### `IssuesPanel`
+
+Renders a Bootstrap **card** matching **`NodesPanel`** chrome (`card-header` + `bg-body-secondary`): the body is **`card-body p-0`** with **`list-group list-group-flush`**. Each issue row mirrors the **Nodes** header rhythm: **truncated `node id, type`** on the left (type resolved from the optional **`tree`** prop), **severity** as a **`badge`** on the right, then the **message** (monospace) and optional **choice id** line. The empty state is a single flush list item. Clicking a row invokes `onSelectIssue`.
+
+```tsx
+import { useMemo, useState, type JSX } from 'react';
+import TreeSpecGraphEditor, {
+    IssuesPanel,
+    lintEditorTree,
+    type EditorTree,
+    type TreeSpecIssue,
+} from '@signalsafe/tree-spec-editor';
+
+type Props = { initialTree: EditorTree };
+
+export function EditorWithIssuesPanel({ initialTree }: Props): JSX.Element {
+    const [tree, setTree] = useState<EditorTree>(initialTree);
+    const issues = useMemo<TreeSpecIssue[]>(() => lintEditorTree(tree), [tree]);
+
+    return (
+        <div className="row g-3">
+            <div className="col-3">
+                <IssuesPanel
+                    issues={issues}
+                    tree={tree}
+                    lastValidatedAt={null}
+                    onSelectIssue={(issue) => console.log('focus', issue)}
+                />
+            </div>
+            <div className="col-9">
+                <TreeSpecGraphEditor tree={tree} onChange={setTree} issues={issues} />
+            </div>
+        </div>
+    );
+}
+```
+
+`IssuesPanel` accepts optional overrides:
+
+- `tree`: when passed, each issue row resolves **node type** from `tree.nodes[issue.node_id]` for the header (same **id, type** pattern as **NodesPanel**).
+- `title`: card header text (default `"Issues"`).
+- `formatTimestamp(iso)`: override how `lastValidatedAt` is displayed in the header (default `new Date(iso).toLocaleString()`).
+- `showValidationSummaryInHeader`: when `false`, the validated / not validated line is omitted from the header (default `true`).
+
+### `NodesPanel`
+
+Renders a search input plus the filtered node list, with a minimap toggle. Each row header is one line: **node id**, a comma, **type** (truncated on narrow widths), with an optional **delete** icon on the right when `onDeleteNode` is set; below that are the prompt preview and choice count. Rows are keyboard-activatable (`role="button"`). Use this when you want consistent left-rail navigation alongside the canvas.
+
+```tsx
+import { useState, type JSX } from 'react';
+import TreeSpecGraphEditor, {
+    NodesPanel,
+    type EditorTree,
+    type GraphSelection,
+} from '@signalsafe/tree-spec-editor';
+
+type Props = { initialTree: EditorTree };
+
+export function EditorWithNodesPanel({ initialTree }: Props): JSX.Element {
+    const [tree, setTree] = useState<EditorTree>(initialTree);
+    const [selection, setSelection] = useState<GraphSelection>({ kind: null, id: null });
+    const [nodeSearch, setNodeSearch] = useState('');
+    const [showMiniMap, setShowMiniMap] = useState(true);
+
+    return (
+        <div className="row g-3">
+            <div className="col-3">
+                <NodesPanel
+                    tree={tree}
+                    nodeSearch={nodeSearch}
+                    selection={selection}
+                    showMiniMap={showMiniMap}
+                    onNodeSearchChange={setNodeSearch}
+                    onNodeSelect={(nodeId) => setSelection({ kind: 'node', id: nodeId })}
+                    onShowMiniMapChange={setShowMiniMap}
+                />
+            </div>
+            <div className="col-9">
+                <TreeSpecGraphEditor
+                    tree={tree}
+                    onChange={setTree}
+                    selected={selection}
+                    onSelect={setSelection}
+                    showMiniMap={showMiniMap}
+                />
+            </div>
+        </div>
+    );
+}
+```
+
+`NodesPanel` accepts optional overrides:
+
+- `searchPlaceholder`: override the search input placeholder text.
+- `tipText`: override the muted helper text below the node list.
+- `onAddNode`: when set, shows an add-node icon in the card header (same pattern as grid action icons); invoke from `useTreeSpecEditor().actions.addNodeOfType`, etc.
+- `onDeleteNode(nodeId)`: when set, each row shows a delete icon on the right; wire to `deleteNodeById` (or equivalent). Omit to hide per-row delete.
+- `isPublished`: when true, per-row delete icons are disabled.
+
+### `AdvancedJsonPanel`
+
+Renders a card with a header (title + optional subtitle + optional Expand/Compress button group) and a body slot that hosts your own JSON renderer. The package intentionally does **not** ship a JSON editor — pass any component (e.g. an existing `JsonEditor`) as `children` so the package stays independent of CDN-loaded jsoneditor libraries.
+
+```tsx
+import { useRef, type JSX } from 'react';
+import { compileTreeSpec } from '@signalsafe/tree-spec';
+import { AdvancedJsonPanel, type EditorTree } from '@signalsafe/tree-spec-editor';
+import JsonEditor, { type JsonEditorHandle } from '@/components/JsonEditor';
+
+type Props = { tree: EditorTree };
+
+export function CompiledTreeSpecPanel({ tree }: Props): JSX.Element {
+    const ref = useRef<JsonEditorHandle>(null);
+
+    return (
+        <AdvancedJsonPanel
+            subtitle="This is the compiled tree_spec that will be saved/published."
+            onExpandAll={() => ref.current?.expandAll()}
+            onCollapseAll={() => ref.current?.collapseAll()}
+        >
+            <JsonEditor
+                ref={ref}
+                value={compileTreeSpec(tree) as Record<string, unknown>}
+                readOnly
+                height="280px"
+            />
+        </AdvancedJsonPanel>
+    );
+}
+```
+
+`AdvancedJsonPanel` accepts these optional props:
+
+- `title`: header title text (default `"Advanced JSON (read-only)"`).
+- `subtitle`: muted line below the title; the line is hidden when omitted.
+- `onExpandAll`, `onCollapseAll`: when provided, the matching button renders in the header. Omit both to hide the button group entirely.
+- `expandAllLabel`, `collapseAllLabel`: override the button labels (defaults `"Expand all"` and `"Compress all"`).
+- `className`: extra classes applied to the outer `card mt-3` element.
+
+### `InspectorPanel`
+
+The right-rail node inspector. When a node is selected, it renders two Bootstrap cards: **Required** (Type, Prompt, and `renderExtraNodeFields`) and **Choices** (list-group rows). The universal fields the package owns:
+
+- **Type** `<select>` (with the package's `TREE_SPEC_NODE_TYPE_PRESETS` + custom-value input).
+- **Prompt** `<textarea>`.
+- **Choices** list with **Label**, **Next** (target-node `<select>`), and a **delete** control per choice.
+- **Outcome** `<select>` per choice — only shown when the choice targets `END_NODE_ID`. Default options are the canonical `TerminalOutcome` values from `@signalsafe/tree-spec` (`safe` / `at_risk` / `compromised`).
+
+For project-specific UI, `InspectorPanel` exposes **render-prop slots** so the package stays generic while hosts can extend it without forking. The package owns nothing app-specific.
+
+```tsx
+import {
+    InspectorPanel,
+    SelectedEdgePanel,
+    type EditorNode,
+    type EditorTree,
+    type EditorTransition,
+} from '@signalsafe/tree-spec-editor';
+
+function RightRail({
+    tree,
+    selectedNode,
+    selectedEdge,
+    focusChoiceId,
+    isPublished,
+    onUpdateSelectedNode,
+    onAddChoice,
+    onDeleteChoice,
+    onSetChoiceTarget,
+    onSetChoiceOutcome,
+}: {
+    tree: EditorTree;
+    selectedNode: EditorNode | null;
+    selectedEdge: EditorTransition | null;
+    focusChoiceId: string | null;
+    isPublished: boolean;
+    onUpdateSelectedNode: (patch: Partial<EditorNode>) => void;
+    onAddChoice: () => void;
+    onDeleteChoice: (choiceId: string) => void;
+    onSetChoiceTarget: (choiceId: string, targetNodeId: string) => void;
+    onSetChoiceOutcome: (choiceId: string, outcome: string) => void;
+}) {
+    return (
+        <>
+            <InspectorPanel
+                tree={tree}
+                selectedNode={selectedNode}
+                focusChoiceId={focusChoiceId}
+                isPublished={isPublished}
+                onUpdateSelectedNode={onUpdateSelectedNode}
+                onAddChoice={onAddChoice}
+                onDeleteChoice={onDeleteChoice}
+                onSetChoiceTarget={onSetChoiceTarget}
+                onSetChoiceOutcome={onSetChoiceOutcome}
+                renderExtraNodeFields={({ node, onUpdateNode }) => (
+                    <YourProjectNodeMetadataFields node={node} onChange={onUpdateNode} />
+                )}
+                renderExtraChoiceFields={({ choice, onUpdateNode }) => (
+                    <YourProjectChoiceMetadataFields choice={choice} onChange={onUpdateNode} />
+                )}
+            />
+            <SelectedEdgePanel selectedEdge={selectedEdge} />
+        </>
+    );
+}
+```
+
+`InspectorPanel` accepts these optional extension points:
+
+- `outcomeOptions`: override the END-transition outcome `<select>` options (e.g. `[{ value: 'pass', label: 'Pass' }, { value: 'fail', label: 'Fail' }]`). Defaults to the canonical `TerminalOutcome` values exported as `DEFAULT_OUTCOME_OPTIONS`.
+- `hideOutcomeField`: hide the outcome `<select>` entirely (useful when the host manages outcomes via `renderExtraChoiceFields` or stores them outside the wire format).
+- `renderExtraNodeFields({ tree, node, isPublished, onUpdateNode })`: render extra UI below the Prompt textarea, scoped to the currently-selected node. Use for project-specific node metadata (render hints, scoring, classification, etc.).
+- `renderExtraChoiceFields({ tree, node, choice, transition, isPublished, onUpdateNode })`: render extra UI below each choice card (after Next/Outcome). Use for project-specific per-choice metadata.
+- `onDeleteSelectedNode`: when set, shows a delete-node icon in the Required card header; wire to `useTreeSpecEditor().actions.deleteSelectedNode` (or equivalent). Disabled automatically when `isPublished` is true.
+- `title`: Required card header text (default `"Required"`).
+- `emptyStateText`: text shown when no node is selected (default `"Select a node to edit it."`).
+- `typeHelperText`: muted helper text under the Type field (default explains the open `type` string).
+
+### `SelectedEdgePanel`
+
+The compact read-only card that surfaces the currently selected transition. Returns `null` when `selectedEdge` is `null`, so hosts can render it unconditionally.
+
+`SelectedEdgePanel` accepts these optional props:
+
+- `title`: header title text (default `"Selected Edge"`).
+- `renderDetails(edge)`: replace the default `from · choice → to` line with a custom renderer.
+
+## Modals
+
+Three presentational modals cover the standard TreeSpec authoring flows. Each renders Bootstrap-styled chrome via a native `<dialog>` element, owns its list/empty/loading rendering, and exposes overridable `title` / `subtitle` / `emptyStateText` / button-label props so the package stays free of project-specific wording. Hosts wire the data, fetch on `show`, and provide callbacks.
+
+### `PublishReviewModal`
+
+A confirmation modal for the publish flow: shows a summary of what's about to be published (diff lines), a validation-error alert when any issue has `severity === 'error'`, and a Publish button that is disabled while `publishing` is `true` or any error issue exists. The package does not own the diff logic — pass `computeDiffSummary(baseline, current) => { lines, hasChanges }` so the host can compute it in whatever way it likes.
+
+```tsx
+import {
+    PublishReviewModal,
+    type EditorTree,
+    type TreeSpecIssue,
+} from '@signalsafe/tree-spec-editor';
+
+function PublishModalContainer({
+    show,
+    tree,
+    baselineTree,
+    issues,
+    publishing,
+    onClose,
+    onPublish,
+    computeDiffSummary,
+}: {
+    show: boolean;
+    tree: EditorTree | null;
+    baselineTree: EditorTree | null;
+    issues: TreeSpecIssue[];
+    publishing: boolean;
+    onClose: () => void;
+    onPublish: () => void;
+    computeDiffSummary: (
+        before: EditorTree | null,
+        after: EditorTree,
+    ) => { lines: string[]; hasChanges: boolean };
+}) {
+    return (
+        <PublishReviewModal
+            show={show}
+            tree={tree}
+            baselineTree={baselineTree}
+            issues={issues}
+            publishing={publishing}
+            onClose={onClose}
+            onPublish={onPublish}
+            computeDiffSummary={computeDiffSummary}
+        />
+    );
+}
+```
+
+`PublishReviewModal` accepts these optional props:
+
+- `title`: modal title (default `"Review changes before publishing"`).
+- `summaryText`: info alert text shown above the diff list.
+- `errorAlertText`: red alert shown when `issues` contains any `severity === 'error'` item.
+- `cancelLabel`, `publishLabel`, `publishingLabel`: button labels.
+
+### `DraftHistoryModal`
+
+A modal that lists draft snapshots and offers per-row "Restore" plus a top-right "Create snapshot". The host owns the `snapshots: TreeSpecSnapshotItem[]` array, the `creatingSnapshot` / `restoringSnapshotId` busy flags, and the `onCreateSnapshot` / `onRestoreSnapshot` callbacks. "Create snapshot" is disabled when `tree` is `null` (e.g. while loading) or `creatingSnapshot` is `true`.
+
+```tsx
+import {
+    DraftHistoryModal,
+    type EditorTree,
+    type TreeSpecSnapshotItem,
+} from '@signalsafe/tree-spec-editor';
+
+function DraftHistoryModalContainer({
+    show,
+    snapshots,
+    loadingSnapshots,
+    creatingSnapshot,
+    restoringSnapshotId,
+    tree,
+    onClose,
+    onCreateSnapshot,
+    onRestoreSnapshot,
+}: {
+    show: boolean;
+    snapshots: TreeSpecSnapshotItem[];
+    loadingSnapshots: boolean;
+    creatingSnapshot: boolean;
+    restoringSnapshotId: string | null;
+    tree: EditorTree | null;
+    onClose: () => void;
+    onCreateSnapshot: () => void;
+    onRestoreSnapshot: (snapshotId: string) => void;
+}) {
+    return (
+        <DraftHistoryModal
+            show={show}
+            snapshots={snapshots}
+            loadingSnapshots={loadingSnapshots}
+            creatingSnapshot={creatingSnapshot}
+            restoringSnapshotId={restoringSnapshotId}
+            tree={tree}
+            onClose={onClose}
+            onCreateSnapshot={onCreateSnapshot}
+            onRestoreSnapshot={onRestoreSnapshot}
+        />
+    );
+}
+```
+
+`DraftHistoryModal` accepts these optional props:
+
+- `title`, `subtitle`, `listCaption`: header / instructions / list caption.
+- `createSnapshotLabel`, `creatingSnapshotLabel`, `restoreLabel`, `restoringLabel`, `closeLabel`: button labels.
+- `loadingText`, `emptyStateText`: state text overrides.
+
+### `AuditLogModal`
+
+A modal that lists authoring audit events for the current tree_spec version. Each row shows the `action` as a Bootstrap badge, the formatted `created_at` timestamp, the optional `actor` (numeric id or string), and the optional `detail` JSON. The host owns the `auditEvents: TreeSpecAuditEventItem[]` array and the `loadingAudit` flag.
+
+```tsx
+import { AuditLogModal, type TreeSpecAuditEventItem } from '@signalsafe/tree-spec-editor';
+
+function AuditLogModalContainer({
+    show,
+    auditEvents,
+    loadingAudit,
+    onClose,
+}: {
+    show: boolean;
+    auditEvents: TreeSpecAuditEventItem[];
+    loadingAudit: boolean;
+    onClose: () => void;
+}) {
+    return (
+        <AuditLogModal
+            show={show}
+            auditEvents={auditEvents}
+            loadingAudit={loadingAudit}
+            onClose={onClose}
+        />
+    );
+}
+```
+
+`AuditLogModal` accepts these optional props:
+
+- `title`, `subtitle`: header text.
+- `loadingText`, `emptyStateText`: state text overrides.
+- `actorLabel`: prefix shown before the actor id (default `"Actor ID:"`).
+- `closeLabel`: footer Close button label.
+
+## Toolbar
+
+### `ToolbarPanel`
+
+A data-driven toolbar for editor pages. Hosts pass an `items: ToolbarItem[]`
+array; the package renders Bootstrap chrome (`Button`, `Dropdown`, badge,
+muted text) inside a single flex wrapper. All project-specific concerns —
+adapter capability gates, dropdown vocabularies, button labels, disabled
+rules, and router-aware links — stay in the host as closures inside each
+item.
+
+```tsx
+import {
+    ToolbarPanel,
+    type ToolbarItem,
+} from '@signalsafe/tree-spec-editor';
+import { Link } from 'react-router-dom';
+
+const items: ToolbarItem[] = [
+    {
+        kind: 'custom',
+        id: 'back',
+        render: () => (
+            <Link className="btn btn-outline-secondary" to="/scenarios">
+                Back
+            </Link>
+        ),
+    },
+    {
+        kind: 'dropdown',
+        id: 'add',
+        label: '+ Add',
+        disabled: isPublished,
+        entries: [
+            { id: 'prompt', label: 'Prompt', onClick: () => addNode('prompt') },
+            { id: 'email', label: 'Email', onClick: () => addNode('email') },
+            { id: 'div', label: '', divider: true },
+            { id: 'outcome', label: 'Outcome node', onClick: () => addNode('outcome') },
+        ],
+    },
+    { kind: 'button', id: 'reset', label: 'Reset view', onClick: onReset, title: 'Reset view to fit graph' },
+    { kind: 'button', id: 'save', label: saving ? 'Saving…' : 'Save Draft', variant: 'primary', onClick: onSave, disabled: saving },
+    { kind: 'badge', id: 'status', label: isPublished ? 'Published (read-only)' : 'Draft', variant: isPublished ? 'success' : 'secondary' },
+    { kind: 'text', id: 'autosave', content: autosaveLabel },
+];
+
+<ToolbarPanel items={items} />;
+```
+
+**Item kinds.** Each `ToolbarItem` is one of:
+
+- `kind: 'button'`: `label`, `onClick`, optional `variant` (Bootstrap variant string, default `outline-secondary`), `disabled`, `title`, `className`.
+- `kind: 'dropdown'`: `label`, `entries` (array of `{ id?, label, onClick?, disabled?, divider? }`), optional `variant` (toggle variant, default `outline-secondary`), `disabled`, `className`. Entries with `divider: true` render a `<Dropdown.Divider />`.
+- `kind: 'badge'`: `label`, optional `variant` (Bootstrap badge variant, default `secondary`) or full `className` override.
+- `kind: 'text'`: `content`, optional `className` (default `"ms-2 text-muted font-size-12"`).
+- `kind: 'custom'`: `render: () => ReactNode` for one-offs the package shouldn't know about (e.g. `<Link>` from `react-router-dom`).
+
+Every item supports an optional `id` used as the React key. `ToolbarPanel` also accepts an optional `className` to override the outer wrapper styling.
+
+## Tree Operations
+
+Project-agnostic helpers for the things every TreeSpec authoring UI needs.
+
+### `duplicateNode(tree, nodeId)`
+
+Returns `{ nextTree, nextNodeId } | null`. The clone gets a fresh node id, fresh choice ids, and a `(+40, +40)` position offset from the source. Transitions are intentionally **not** copied — the new node starts orphaned. Returns `null` for the synthetic `END_NODE_ID` and unknown ids.
+
+```tsx
+import { duplicateNode } from '@signalsafe/tree-spec-editor';
+
+const result = duplicateNode(tree, selectedNodeId);
+if (result) {
+    setTree(result.nextTree);
+    setSelection({ kind: 'node', id: result.nextNodeId });
+}
+```
+
+### `deleteNode(tree, nodeId)`
+
+Returns the next `EditorTree | null`. Removes the node and any transition with that node on either endpoint. When the deleted node was `tree.start_node`, picks the first remaining node (insertion order) as the new start. Returns `null` for the synthetic `END_NODE_ID` and unknown ids.
+
+```tsx
+import { deleteNode } from '@signalsafe/tree-spec-editor';
+
+const nextTree = deleteNode(tree, selectedNodeId);
+if (nextTree) setTree(nextTree);
+```
+
+### `computeTreeDiffSummary(before, after)`
+
+Returns `{ lines: string[]; hasChanges: boolean }`. Produces a short human-readable diff (added/removed nodes, changed type-or-prompt counts, changed choice counts, added/removed transition keys). Suitable as the default `computeDiffSummary` callback for `PublishReviewModal`.
+
+```tsx
+import { computeTreeDiffSummary, PublishReviewModal } from '@signalsafe/tree-spec-editor';
+
+<PublishReviewModal
+    show={showPublish}
+    onClose={() => setShowPublish(false)}
+    onPublish={publish}
+    currentTree={tree}
+    baselineTree={publishedTree}
+    computeDiffSummary={computeTreeDiffSummary}
+/>;
+```
+
+### `applyTreeTemplate(tree, spec, options?)`
+
+Inserts a reusable sub-graph (`TreeTemplateSpec`) into `tree`. The spec uses **slot names** (host-defined strings like `"focus"`, `"verify"`) to wire its internal transitions; the helper generates a fresh node id for each slot at insertion time so the same template can be inserted multiple times without collisions. Transitions reference either a slot name or the literal `END_NODE_ID`.
+
+Returns `{ nextTree, focusNodeId }`. The original tree's `start_node` is preserved when set; otherwise the focus node id is used.
+
+```tsx
+import {
+    applyTreeTemplate,
+    END_NODE_ID,
+    type TreeTemplateSpec,
+} from '@signalsafe/tree-spec-editor';
+
+const CEO_CALL: TreeTemplateSpec = {
+    focusSlot: 'focus',
+    nodes: {
+        focus: {
+            type: 'call',
+            prompt: 'You receive an urgent call from your CEO...',
+            choices: [
+                { id: 'comply', label: 'Comply immediately' },
+                { id: 'verify', label: 'Verify identity out-of-band' },
+            ],
+            offset: { x: 60, y: 0 },
+        },
+        verify: {
+            type: 'prompt',
+            prompt: 'What is the safest way to verify the request?',
+            choices: [
+                { id: 'callback', label: 'Call a known number / assistant' },
+                { id: 'reply', label: 'Ask follow-ups on the same call' },
+            ],
+            offset: { x: 420, y: 0 },
+        },
+    },
+    transitions: [
+        { fromSlot: 'focus', fromChoiceId: 'comply', toSlot: END_NODE_ID, outcome: 'compromised' },
+        { fromSlot: 'focus', fromChoiceId: 'verify', toSlot: 'verify' },
+        { fromSlot: 'verify', fromChoiceId: 'callback', toSlot: END_NODE_ID, outcome: 'safe' },
+        { fromSlot: 'verify', fromChoiceId: 'reply', toSlot: END_NODE_ID, outcome: 'at_risk' },
+    ],
+};
+
+const { nextTree, focusNodeId } = applyTreeTemplate(tree, CEO_CALL);
+setTree(nextTree);
+setSelection({ kind: 'node', id: focusNodeId });
+```
+
+**Positioning.** Each node spec's `offset` is added to a base position. The default base is `{ x: 0, y: getNextSpawnPosition(tree).y }`, which places the cluster at the next vertical slot while letting nodes declare absolute X coordinates. Override via `options.basePosition` to anchor elsewhere.
+
+**Validation.** `applyTreeTemplate` throws when `spec.focusSlot` is missing from `spec.nodes`, or when any transition references an unknown slot.
+
+## Editor Lifecycle Helpers
+
+Small pure helpers for the parts of an editor page that aren't graph-shaped: the autosave indicator, keyboard shortcuts, and the "is this a draft?" load policy. Hosts can use them as-is, wrap them for i18n, or replace them entirely — they hold no editor state.
+
+### `getAutosaveStatusLabel(status)`
+
+Maps an `AutosaveStatus` (`'idle' | 'dirty' | 'saving' | 'saved'`) to a default toolbar label. Returns the empty string for `'idle'` so the toolbar can render nothing between editing sessions.
+
+```tsx
+import {
+    getAutosaveStatusLabel,
+    ToolbarPanel,
+    type AutosaveStatus,
+    type ToolbarItem,
+} from '@signalsafe/tree-spec-editor';
+
+function buildToolbar(autosaveStatus: AutosaveStatus): ToolbarItem[] {
+    return [
+        { kind: 'text', id: 'autosave', content: getAutosaveStatusLabel(autosaveStatus) },
+    ];
+}
+```
+
+### `getKeyboardShortcutAction(params)`
+
+Pure key-event-to-action mapper. Accepts the modifier flags and `key` string directly (not a `KeyboardEvent`) so tests don't need a DOM event.
+
+Default bindings:
+
+| Combo                       | Action      | Notes |
+|-----------------------------|-------------|-------|
+| `Ctrl/Cmd + S`              | `save`      | — |
+| `Ctrl/Cmd + Shift + V`      | `validate`  | — |
+| `Ctrl/Cmd + P`              | `preview`   | — |
+| `Ctrl/Cmd + D`              | `duplicate` | Only when `hasSelectedNode === true` |
+| `Delete` or `Backspace`     | `delete`    | Only when `hasSelectedNode === true` |
+
+```tsx
+import { getKeyboardShortcutAction } from '@signalsafe/tree-spec-editor';
+
+useEffect(() => {
+    function onKeyDown(event: KeyboardEvent) {
+        const action = getKeyboardShortcutAction({
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            shiftKey: event.shiftKey,
+            key: event.key,
+            hasSelectedNode: selection.kind === 'node',
+        });
+        if (action) {
+            event.preventDefault();
+            dispatch(action);
+        }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+}, [selection.kind, dispatch]);
+```
+
+If a host needs different bindings, write your own dispatcher and skip this helper — the package does not require it.
+
+### `shouldQueueInitialValidation(isPublished)`
+
+Returns `true` when `isPublished` is anything other than strictly `true` (i.e. `false`, `null`, or `undefined`). Lets editors open drafts in a "validate on load" state without treating unknown-status loads as published.
+
+```tsx
+import { shouldQueueInitialValidation } from '@signalsafe/tree-spec-editor';
+
+useEffect(() => {
+    if (shouldQueueInitialValidation(rawVersion?.is_published)) {
+        queueValidate();
+    }
+}, [rawVersion?.is_published, queueValidate]);
+```
+
 ## Helper Examples
 
 Use `autoLayoutTree` before first render when you want a readable default layout.
@@ -369,5 +1024,5 @@ function addPromptNode(tree: EditorTree): EditorTree {
 ## Notes
 
 - Import from the package root only.
-- Install `react`, `react-dom`, and `reactflow` in the consuming app.
+- Install `react`, `react-dom`, `reactflow`, and `react-bootstrap` in the consuming app, and load Bootstrap CSS as usual.
 - If you need wire-format compile/decompile helpers, use `@signalsafe/tree-spec`.