@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/flow/run/types.ts

@@ -0,0 +1,53 @@
+// Words and shapes the run group speaks: stored runs as the host returns
+// them, the live event stream, and the status vocabulary shown on screen.
+
+import type { ActorKind } from '../../index'
+
+/** Status word every run view shows (always beside an icon). */
+export type RunWord = 'idle' | 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'restored' | 'unknown'
+
+/** State of the connection that delivers run events. */
+export type StreamStatus = 'idle' | 'streaming' | 'completed' | 'failed' | 'error'
+
+/** The person, agent or system behind a run or a version (design direction §2.11). */
+export type RunActor = { kind: ActorKind; name: string } & Partial<Record<'agentKey' | 'model' | 'email', string>>
+
+/** Outcome of one step inside a stored run. */
+export type RunNodeResult = {
+  nodeId: string
+  status: string
+} & Partial<{ label: string; kind: string; durationMs: number; error: string; outputs: unknown }>
+
+/**
+ * A run as the host's loader returns it. `status` is the engine's own
+ * spelling; views normalise it. `triggeredBy` is the engine's origin tag
+ * ("kind:baseRunId"), read with parseLineage.
+ */
+export type RunSummary = {
+  id: string
+  status: string
+  startedAt: string
+} & Partial<{
+  durationMs: number
+  nodeResults: RunNodeResult[]
+  triggeredBy: string | null
+  actor: RunActor
+  inputs: Record<string, unknown>
+}>
+
+export type LoadRuns = (flowId: string) => Promise<RunSummary[]>
+
+/** Payload per event name of the run stream; the union below is derived from it. */
+type StepTiming = { outputs?: unknown; durationMs?: number }
+interface RunEventPayloads {
+  'run-started': { runId?: string }
+  'run-completed': { runId?: string }
+  'run-failed': { runId?: string; error?: string }
+  'node-started': { nodeId: string }
+  'node-completed': { nodeId: string } & StepTiming
+  'node-restored': { nodeId: string } & StepTiming
+  'node-failed': { nodeId: string; error?: string; durationMs?: number }
+}
+
+/** Events of the run stream; names the projection does not know are allowed and ignored. */
+export type RunEvent = { [Name in keyof RunEventPayloads]: { type: Name } & RunEventPayloads[Name] }[keyof RunEventPayloads] | { type: string; [key: string]: unknown }

package/src/flow/state/dialogStack.tsx

@@ -0,0 +1,90 @@
+// Editor dialog stack: opening a dialog while another is open pushes the
+// current one; closing pops and restores it with its payload.
+
+import { createContext, useContext, useState, type ReactNode } from 'react'
+import { createStore, useStoreSelector, type Store } from './store'
+
+export type EditorDialogKind = 'agent-editor' | 'node-config' | 'flow-settings'
+
+/** Payload of the node configuration dialog. */
+export interface NodeConfigPayload {
+  nodeId: string
+  kind: string
+  label: string
+  config: Record<string, unknown>
+  /** Upstream values the forms may reference (ancestor node ids and flow inputs). */
+  references: string[]
+}
+
+/** Payload of the agent editor. */
+export interface AgentEditorPayload {
+  mode: 'create' | 'edit'
+  agent?: Record<string, unknown> & { id?: string; name?: string }
+}
+
+/** Payload of the flow settings dialog (lifecycle values only when known). */
+export interface FlowSettingsPayload {
+  name: string
+  description: string
+  slug?: string | null
+  isDraft?: boolean
+  isActive?: boolean
+}
+
+export interface EditorDialogEntry<P = unknown> {
+  kind: EditorDialogKind
+  payload: P
+}
+
+export interface DialogStackData {
+  active: EditorDialogEntry | null
+  stack: EditorDialogEntry[]
+}
+
+export interface DialogStack extends Store<DialogStackData> {
+  open<P>(kind: EditorDialogKind, payload: P): void
+  close(): void
+  closeAll(): void
+}
+
+export function createDialogStack(): DialogStack {
+  const base = createStore<DialogStackData>({ active: null, stack: [] })
+  return {
+    ...base,
+    open(kind, payload) {
+      const s = base.getState()
+      base.setState({ active: { kind, payload }, stack: s.active ? [...s.stack, s.active] : s.stack })
+    },
+    close() {
+      const s = base.getState()
+      const stack = s.stack.slice(0, -1)
+      base.setState({ active: s.stack[s.stack.length - 1] ?? null, stack })
+    },
+    closeAll() {
+      base.setState({ active: null, stack: [] })
+    },
+  }
+}
+
+const DialogStackContext = createContext<DialogStack | null>(null)
+
+export function DialogStackProvider({ stack, children }: { stack?: DialogStack; children: ReactNode }) {
+  const [own] = useState(() => stack ?? createDialogStack())
+  return <DialogStackContext.Provider value={stack ?? own}>{children}</DialogStackContext.Provider>
+}
+
+export function useDialogStack(): DialogStack {
+  const s = useContext(DialogStackContext)
+  if (!s) throw new Error('Editor dialogs must be inside <DialogStackProvider> (FlowEditor provides one).')
+  return s
+}
+
+export function useOptionalDialogStack(): DialogStack | null {
+  return useContext(DialogStackContext)
+}
+
+/** The active dialog when it is of `kind`, else null. */
+export function useActiveDialog<P = unknown>(kind: EditorDialogKind): EditorDialogEntry<P> | null {
+  const stack = useDialogStack()
+  return useStoreSelector(stack, (s) => (s.active?.kind === kind ? (s.active as EditorDialogEntry<P>) : null))
+}

package/src/flow/state/editorState.test.tsx

@@ -0,0 +1,110 @@
+import { act, render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import type { FlowConnector, FlowNode } from '../model/types'
+import { createDialogStack } from './dialogStack'
+import { createFlowEditorStore, FlowEditorStateProvider, useFlowEditorActions, useFlowEditorState } from './editorState'
+
+const n = (id: string, x = 0, selected = false): FlowNode => ({ id, kind: 'code', position: { x, y: 0 }, data: { label: id }, selected })
+const c = (source: string, target: string): FlowConnector => ({ id: `${source}-${target}`, source, target })
+
+describe('FlowEditorState', () => {
+  it('undoes and redoes graph edits', () => {
+    const s = createFlowEditorStore()
+    expect(s.getState().past.length > 0).toBe(false)
+    s.actions.setNodes([n('A')])
+    s.actions.snapshot()
+    s.actions.setNodes((prev) => [...prev, n('B')])
+    s.actions.undo()
+    expect(s.getState().nodes.map((x) => x.id)).toEqual(['A'])
+    expect(s.getState().future.length).toBe(1)
+    s.actions.redo()
+    expect(s.getState().nodes.map((x) => x.id)).toEqual(['A', 'B'])
+  })
+
+  it('bounds history depth', () => {
+    const s = createFlowEditorStore({ historyLimit: 4 })
+    for (let i = 0; i < 9; i++) s.actions.snapshot()
+    expect(s.getState().past.length).toBe(4)
+  })
+
+  it('clears the future on a new snapshot after undo', () => {
+    const s = createFlowEditorStore()
+    s.actions.snapshot()
+    s.actions.setNodes([n('A')])
+    s.actions.undo()
+    s.actions.snapshot()
+    expect(s.getState().future).toEqual([])
+  })
+
+  it('copies selected nodes with inner connectors and pastes fresh, offset, selected copies', () => {
+    const s = createFlowEditorStore()
+    s.actions.setNodes([n('A', 0, true), n('B', 100, true), n('C', 200)])
+    s.actions.setConnectors([c('A', 'B'), c('B', 'C')])
+    s.actions.copy()
+    s.actions.paste()
+    const { nodes, connectors } = s.getState()
+    const pasted = nodes.slice(3)
+    expect(pasted).toHaveLength(2)
+    expect(pasted.every((p) => !['A', 'B'].includes(p.id))).toBe(true)
+    expect(pasted.map((p) => p.position.x)).toEqual([32, 132])
+    expect(nodes.filter((x) => x.selected).map((x) => x.id)).toEqual(pasted.map((p) => p.id))
+    const added = connectors.slice(2)
+    expect(added).toHaveLength(1)
+    expect(added[0]!.source).toBe(pasted[0]!.id)
+    expect(added[0]!.target).toBe(pasted[1]!.id)
+  })
+
+  it('cascades a second paste from the first', () => {
+    const s = createFlowEditorStore()
+    s.actions.setNodes([n('A', 0, true)])
+    s.actions.copy()
+    s.actions.paste()
+    s.actions.paste()
+    expect(s.getState().nodes.map((x) => x.position.x)).toEqual([0, 32, 64])
+  })
+
+  it('refuses delete and duplicate while locked', () => {
+    const s = createFlowEditorStore()
+    s.actions.setNodes([n('A', 0, true)])
+    s.actions.setLocked(true)
+    s.actions.removeSelection()
+    s.actions.duplicate()
+    expect(s.getState().nodes.map((x) => x.id)).toEqual(['A'])
+  })
+
+  it('restores the previous dialog with its payload when a stacked dialog closes', () => {
+    const d = createDialogStack()
+    d.open('agent-editor', { agentId: 'a1' })
+    d.open('node-config', { nodeId: 'n1' })
+    expect(d.getState().active?.kind).toBe('node-config')
+    d.close()
+    expect(d.getState().active).toEqual({ kind: 'agent-editor', payload: { agentId: 'a1' } })
+    d.closeAll()
+    expect(d.getState().active).toBeNull()
+  })
+
+  it('keeps two editor instances independent', () => {
+    function Adder({ label }: { label: string }) {
+      const actions = useFlowEditorActions()
+      const count = useFlowEditorState((s) => s.nodes.length)
+      return (
+        <button type="button" onClick={() => actions.setNodes((p) => [...p, n(`${label}${p.length}`)])}>
+          {label} {count}
+        </button>
+      )
+    }
+    render(
+      <>
+        <FlowEditorStateProvider>
+          <Adder label="left" />
+        </FlowEditorStateProvider>
+        <FlowEditorStateProvider>
+          <Adder label="right" />
+        </FlowEditorStateProvider>
+      </>,
+    )
+    act(() => screen.getByText('left 0').click())
+    expect(screen.getByRole('button', { name: 'left 1' })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'right 0' })).toBeInTheDocument()
+  })
+})

package/src/flow/state/editorState.tsx

@@ -0,0 +1,296 @@
+// FlowEditorState: one store per editor (never a module singleton), with
+// actions and fine-grained read hooks.
+
+import { createContext, useContext, useState, type ReactNode } from 'react'
+import type { FlowConnector, FlowNode, LayoutDirection, NodeRunResult, Point } from '../model/types'
+import {
+  clonePiece,
+  copySelection,
+  freezeSnapshot,
+  mergePiece,
+  PASTE_OFFSET,
+  recordHistory,
+  stepBack,
+  stepForward,
+  withoutNodes,
+  type GraphSnapshot,
+} from './graphEdits'
+import { createStore, shallowEqual, useStoreSelector, type Store } from './store'
+
+export type PanelName = 'variables' | 'versions' | 'run' | 'minimap' | 'grid' | 'shortcuts' | 'preview' | 'outline'
+
+export interface CanvasMenuState {
+  kind: 'node' | 'connector' | 'canvas' | 'selection'
+  /** Screen position the menu opens at. */
+  position: Point
+  targetId?: string
+}
+
+export interface FlowEditorData {
+  nodes: FlowNode[]
+  connectors: FlowConnector[]
+  past: GraphSnapshot[]
+  future: GraphSnapshot[]
+  clipboard: GraphSnapshot | null
+  editingNodeId: string | null
+  contextMenu: CanvasMenuState | null
+  controlMode: 'select' | 'pan'
+  layoutDirection: LayoutDirection
+  panels: Record<PanelName, boolean>
+  cardDensity: 'detailed' | 'compact'
+  isRunning: boolean
+  nodeResults: Record<string, NodeRunResult>
+  selectedRunId: string | null
+  locked: boolean
+}
+
+type Updater<T> = T | ((prev: T) => T)
+
+export interface FlowEditorActions {
+  setNodes(next: Updater<FlowNode[]>): void
+  setConnectors(next: Updater<FlowConnector[]>): void
+  /** Takes a history snapshot of the current graph (call before an edit). */
+  snapshot(): void
+  undo(): void
+  redo(): void
+  copy(): void
+  paste(offset?: number): void
+  /** Copies the selection in place (offset), selecting only the copies. One undo step. */
+  duplicate(ids?: readonly string[]): void
+  /** Removes selected nodes (and connectors touching them) and selected connectors. One undo step. Refused when locked. */
+  removeSelection(): void
+  removeNodes(ids: readonly string[]): void
+  removeConnector(id: string): void
+  selectAll(): void
+  deselectAll(): void
+  select(ids: readonly string[], additive?: boolean): void
+  selectConnector(id: string | null): void
+  setEditingNode(id: string | null): void
+  openContextMenu(menu: CanvasMenuState): void
+  closeContextMenu(): void
+  setControlMode(mode: 'select' | 'pan'): void
+  setLayoutDirection(direction: LayoutDirection): void
+  togglePanel(name: PanelName): void
+  setPanel(name: PanelName, open: boolean): void
+  closeShortcuts(): void
+  toggleDensity(): void
+  setRunning(running: boolean): void
+  setNodeResult(id: string, result: NodeRunResult): void
+  clearNodeResults(): void
+  setSelectedRun(id: string | null): void
+  setLocked(locked: boolean): void
+  reset(): void
+}
+
+export interface FlowEditorStore extends Store<FlowEditorData> {
+  actions: FlowEditorActions
+  historyLimit: number
+}
+
+export interface FlowEditorStoreOptions {
+  /** Maximum undo depth (default 50). */
+  historyLimit?: number
+  initial?: Partial<Pick<FlowEditorData, 'nodes' | 'connectors' | 'controlMode' | 'layoutDirection' | 'cardDensity' | 'locked'>> & {
+    panels?: Partial<Record<PanelName, boolean>>
+  }
+}
+
+const CLOSED_PANELS: Record<PanelName, boolean> = {
+  variables: false,
+  versions: false,
+  run: false,
+  minimap: false,
+  grid: true,
+  shortcuts: false,
+  preview: false,
+  outline: false,
+}
+
+function blank(options: FlowEditorStoreOptions): FlowEditorData {
+  const i = options.initial ?? {}
+  return {
+    nodes: i.nodes ?? [],
+    connectors: i.connectors ?? [],
+    past: [],
+    future: [],
+    clipboard: null,
+    editingNodeId: null,
+    contextMenu: null,
+    controlMode: i.controlMode ?? 'select',
+    layoutDirection: i.layoutDirection ?? 'down',
+    panels: { ...CLOSED_PANELS, ...(i.panels ?? {}) },
+    cardDensity: i.cardDensity ?? 'detailed',
+    isRunning: false,
+    nodeResults: {},
+    selectedRunId: null,
+    locked: i.locked ?? false,
+  }
+}
+
+const apply = <T,>(next: Updater<T>, prev: T): T => (typeof next === 'function' ? (next as (p: T) => T)(prev) : next)
+
+export function createFlowEditorStore(options: FlowEditorStoreOptions = {}): FlowEditorStore {
+  const limit = options.historyLimit ?? 50
+  const base = createStore<FlowEditorData>(blank(options))
+  const get = base.getState
+  const set = base.setState
+  const current = () => freezeSnapshot(get().nodes, get().connectors)
+
+  const actions: FlowEditorActions = {
+    setNodes: (next) => set((s) => ({ nodes: apply(next, s.nodes) })),
+    setConnectors: (next) => set((s) => ({ connectors: apply(next, s.connectors) })),
+    snapshot() {
+      const s = get()
+      set(recordHistory({ past: s.past, future: s.future }, current(), limit))
+    },
+    undo() {
+      const s = get()
+      const r = stepBack({ past: s.past, future: s.future }, current())
+      if (r) set({ ...r.stacks, nodes: r.graph.nodes, connectors: r.graph.connectors })
+    },
+    redo() {
+      const s = get()
+      const r = stepForward({ past: s.past, future: s.future }, current())
+      if (r) set({ ...r.stacks, nodes: r.graph.nodes, connectors: r.graph.connectors })
+    },
+    copy() {
+      const piece = copySelection(get().nodes, get().connectors)
+      if (piece) set({ clipboard: piece })
+    },
+    paste(offset = PASTE_OFFSET) {
+      const s = get()
+      if (!s.clipboard || s.locked) return
+      actions.snapshot()
+      const piece = clonePiece(s.clipboard, offset)
+      const merged = mergePiece({ nodes: get().nodes, connectors: get().connectors }, piece)
+      // The clipboard follows the pasted copy so the next paste cascades.
+      set({ ...merged, clipboard: freezeSnapshot(piece.nodes, piece.connectors) })
+    },
+    duplicate(ids) {
+      const s = get()
+      if (s.locked) return
+      const chosen = ids ? new Set(ids) : null
+      const nodes = chosen ? s.nodes.map((n) => ({ ...n, selected: chosen.has(n.id) })) : s.nodes
+      const piece = copySelection(nodes, s.connectors)
+      if (!piece) return
+      actions.snapshot()
+      set(mergePiece({ nodes: get().nodes, connectors: get().connectors }, clonePiece(piece)))
+    },
+    removeSelection() {
+      const s = get()
+      if (s.locked) return
+      const ids = new Set(s.nodes.filter((n) => n.selected).map((n) => n.id))
+      const connectorIds = new Set(s.connectors.filter((c) => c.selected).map((c) => c.id))
+      if (!ids.size && !connectorIds.size) return
+      actions.snapshot()
+      const g = withoutNodes({ nodes: s.nodes, connectors: s.connectors.filter((c) => !connectorIds.has(c.id)) }, ids)
+      set(g)
+    },
+    removeNodes(idList) {
+      const s = get()
+      if (s.locked || !idList.length) return
+      actions.snapshot()
+      set(withoutNodes({ nodes: s.nodes, connectors: s.connectors }, new Set(idList)))
+    },
+    removeConnector(id) {
+      const s = get()
+      if (s.locked || !s.connectors.some((c) => c.id === id)) return
+      actions.snapshot()
+      set({ connectors: get().connectors.filter((c) => c.id !== id) })
+    },
+    selectAll: () => set((s) => ({ nodes: s.nodes.map((n) => (n.selected || n.hidden ? n : { ...n, selected: true })) })),
+    deselectAll: () =>
+      set((s) => ({
+        nodes: s.nodes.some((n) => n.selected) ? s.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)) : s.nodes,
+        connectors: s.connectors.some((c) => c.selected) ? s.connectors.map((c) => (c.selected ? { ...c, selected: false } : c)) : s.connectors,
+      })),
+    select(idList, additive = false) {
+      const chosen = new Set(idList)
+      set((s) => ({
+        nodes: s.nodes.map((n) => {
+          const on = chosen.has(n.id) || (additive && !!n.selected)
+          return !!n.selected === on ? n : { ...n, selected: on }
+        }),
+        connectors: additive ? s.connectors : s.connectors.map((c) => (c.selected ? { ...c, selected: false } : c)),
+      }))
+    },
+    selectConnector(id) {
+      set((s) => ({
+        connectors: s.connectors.map((c) => (!!c.selected === (c.id === id) ? c : { ...c, selected: c.id === id })),
+        nodes: id ? s.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)) : s.nodes,
+      }))
+    },
+    setEditingNode: (id) => set({ editingNodeId: id }),
+    openContextMenu: (menu) => set({ contextMenu: menu }),
+    closeContextMenu: () => set({ contextMenu: null }),
+    setControlMode: (mode) => set({ controlMode: mode }),
+    setLayoutDirection: (direction) => set({ layoutDirection: direction }),
+    togglePanel: (name) => set((s) => ({ panels: { ...s.panels, [name]: !s.panels[name] } })),
+    setPanel: (name, open) => set((s) => (s.panels[name] === open ? {} : { panels: { ...s.panels, [name]: open } })),
+    closeShortcuts: () => actions.setPanel('shortcuts', false),
+    toggleDensity: () => set((s) => ({ cardDensity: s.cardDensity === 'detailed' ? 'compact' : 'detailed' })),
+    setRunning: (running) => set({ isRunning: running }),
+    setNodeResult: (id, result) => set((s) => ({ nodeResults: { ...s.nodeResults, [id]: result } })),
+    clearNodeResults: () => set((s) => (Object.keys(s.nodeResults).length ? { nodeResults: {} } : {})),
+    setSelectedRun: (id) => set({ selectedRunId: id }),
+    setLocked: (locked) => set({ locked }),
+    reset: () => set(blank(options)),
+  }
+
+  return { ...base, actions, historyLimit: limit }
+}
+
+const EditorStoreContext = createContext<FlowEditorStore | null>(null)
+
+/** Provides an editor store; creates one per provider when none is passed. */
+export function FlowEditorStateProvider({ store, options, children }: { store?: FlowEditorStore; options?: FlowEditorStoreOptions; children: ReactNode }) {
+  const [own] = useState(() => store ?? createFlowEditorStore(options))
+  return <EditorStoreContext.Provider value={store ?? own}>{children}</EditorStoreContext.Provider>
+}
+
+export function useFlowEditorStore(): FlowEditorStore {
+  const store = useContext(EditorStoreContext)
+  if (!store) throw new Error('Flow editor components must be inside <FlowEditorStateProvider> (FlowEditor provides one).')
+  return store
+}
+
+/** The store when inside an editor, else null (for components usable in both). */
+export function useOptionalFlowEditorStore(): FlowEditorStore | null {
+  return useContext(EditorStoreContext)
+}
+
+export function useFlowEditorState<T>(selector: (s: FlowEditorData) => T, isEqual: (a: T, b: T) => boolean = shallowEqual as (a: T, b: T) => boolean): T {
+  return useStoreSelector(useFlowEditorStore(), selector, isEqual)
+}
+
+export const useFlowEditorActions = (): FlowEditorActions => useFlowEditorStore().actions
+
+// Read hooks named by the spec.
+export const useCanUndo = () => useFlowEditorState((s) => s.past.length > 0)
+export const useCanRedo = () => useFlowEditorState((s) => s.future.length > 0)
+export const useHasClipboard = () => useFlowEditorState((s) => !!s.clipboard && s.clipboard.nodes.length > 0)
+export const useCanvasMenu = () => useFlowEditorState((s) => s.contextMenu)
+export const useEditingNodeId = () => useFlowEditorState((s) => s.editingNodeId)
+export const useSelectedNodeCount = () => useFlowEditorState((s) => s.nodes.reduce((n, node) => n + (node.selected ? 1 : 0), 0))
+export const useIsRunning = () => useFlowEditorState((s) => s.isRunning)
+export const useNodeResults = () => useFlowEditorState((s) => s.nodeResults)
+
+/** Result of one node from the editor state, or undefined outside an editor. */
+export function useNodeResult(nodeId: string): NodeRunResult | undefined {
+  const store = useOptionalFlowEditorStore()
+  const fallback = useFallbackStore()
+  return useStoreSelector(store ?? fallback, (s) => s.nodeResults[nodeId])
+}
+
+/** Locked flag, false outside an editor. */
+export function useEditorLocked(): boolean {
+  const store = useOptionalFlowEditorStore()
+  const fallback = useFallbackStore()
+  return useStoreSelector(store ?? fallback, (s) => s.locked)
+}
+
+let sharedFallback: FlowEditorStore | null = null
+function useFallbackStore(): FlowEditorStore {
+  sharedFallback ??= createFlowEditorStore()
+  return sharedFallback
+}

package/src/flow/state/graphEdits.ts

@@ -0,0 +1,107 @@
+// Pure edits on a graph snapshot: history stacks, copy, paste, duplicate and
+// removal. Shared by the editor state and the stand-alone EditorShortcuts hooks.
+
+import { createId } from '../internal/ids'
+import type { FlowConnector, FlowNode } from '../model/types'
+
+export interface GraphSnapshot {
+  nodes: FlowNode[]
+  connectors: FlowConnector[]
+}
+
+/** Deep copy of node data so later edits never leak into history entries. */
+export function freezeSnapshot(nodes: readonly FlowNode[], connectors: readonly FlowConnector[]): GraphSnapshot {
+  return {
+    nodes: nodes.map((n) => ({ ...n, position: { ...n.position }, data: structuredClone(n.data) })),
+    connectors: connectors.map((c) => ({ ...c })),
+  }
+}
+
+export interface HistoryStacks {
+  past: GraphSnapshot[]
+  future: GraphSnapshot[]
+}
+
+/** Pushes `current` onto past (bounded), clears future. */
+export function recordHistory(stacks: HistoryStacks, current: GraphSnapshot, limit: number): HistoryStacks {
+  const past = [...stacks.past, current]
+  while (past.length > Math.max(1, limit)) past.shift()
+  return { past, future: [] }
+}
+
+export function stepBack(stacks: HistoryStacks, current: GraphSnapshot): { stacks: HistoryStacks; graph: GraphSnapshot } | null {
+  if (!stacks.past.length) return null
+  const past = stacks.past.slice(0, -1)
+  const graph = stacks.past[stacks.past.length - 1]!
+  return { stacks: { past, future: [current, ...stacks.future] }, graph }
+}
+
+export function stepForward(stacks: HistoryStacks, current: GraphSnapshot): { stacks: HistoryStacks; graph: GraphSnapshot } | null {
+  if (!stacks.future.length) return null
+  const [graph, ...future] = stacks.future
+  return { stacks: { past: [...stacks.past, current], future }, graph: graph! }
+}
+
+/** Selected nodes plus only the connectors whose both ends are selected; null when nothing is selected. */
+export function copySelection(nodes: readonly FlowNode[], connectors: readonly FlowConnector[]): GraphSnapshot | null {
+  const picked = nodes.filter((n) => n.selected)
+  if (!picked.length) return null
+  const ids = new Set(picked.map((n) => n.id))
+  return freezeSnapshot(
+    picked,
+    connectors.filter((c) => ids.has(c.source) && ids.has(c.target)),
+  )
+}
+
+export const PASTE_OFFSET = 32
+
+/**
+ * New nodes and connectors for a paste: fresh ids, remapped connectors,
+ * positions shifted diagonally, only the new nodes selected.
+ */
+export function clonePiece(piece: GraphSnapshot, offset = PASTE_OFFSET): GraphSnapshot {
+  const remap = new Map<string, string>()
+  for (const n of piece.nodes) remap.set(n.id, createId(n.kind || 'node'))
+  const nodes = piece.nodes.map((n) => ({
+    ...n,
+    id: remap.get(n.id)!,
+    position: n.parentId && remap.has(n.parentId) ? { ...n.position } : { x: n.position.x + offset, y: n.position.y + offset },
+    ...(n.parentId ? { parentId: remap.get(n.parentId) ?? n.parentId } : {}),
+    data: structuredClone(n.data),
+    selected: true,
+  }))
+  const connectors = piece.connectors.map((c) => ({
+    ...c,
+    id: createId('connector'),
+    source: remap.get(c.source)!,
+    target: remap.get(c.target)!,
+    selected: false,
+  }))
+  return { nodes, connectors }
+}
+
+/** Graph with `piece` merged in and everything else deselected. */
+export function mergePiece(graph: GraphSnapshot, piece: GraphSnapshot): GraphSnapshot {
+  return {
+    nodes: [...graph.nodes.map((n) => (n.selected ? { ...n, selected: false } : n)), ...piece.nodes],
+    connectors: [...graph.connectors.map((c) => (c.selected ? { ...c, selected: false } : c)), ...piece.connectors],
+  }
+}
+
+/** Removes the given nodes, their members and every connector touching them. */
+export function withoutNodes(graph: GraphSnapshot, ids: ReadonlySet<string>): GraphSnapshot {
+  const gone = new Set(ids)
+  // Members of removed frames go too.
+  let grew = true
+  while (grew) {
+    grew = false
+    for (const n of graph.nodes) if (n.parentId && gone.has(n.parentId) && !gone.has(n.id)) {
+      gone.add(n.id)
+      grew = true
+    }
+  }
+  return {
+    nodes: graph.nodes.filter((n) => !gone.has(n.id)),
+    connectors: graph.connectors.filter((c) => !gone.has(c.source) && !gone.has(c.target)),
+  }
+}