@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/editor-annotations.ts

@@ -0,0 +1,301 @@
+/**
+ * Sticky notes and named groups (spec section 4.5).
+ *
+ * Annotations are DOCUMENTATION and never execution semantics. They live in
+ * `metadata.editor.annotations` only — `graphToDefinition` filters their nodes
+ * out of `steps` and `transitions` entirely, so a definition carrying a hundred
+ * notes serializes byte-identically to one carrying none and the engine can
+ * never see them.
+ *
+ * They are still React Flow NODES while the editor is open, which is what makes
+ * dragging, selection, the undo stack and the arrangement autosave work for a
+ * note exactly as they do for a step: the page owns one node array and the
+ * annotations are derived back out of it on save.
+ *
+ * PURE: plain data in, plain data out — React Flow is a type-only import.
+ */
+
+import type { Node } from '@xyflow/react'
+
+export const ANNOTATION_NOTE_NODE_TYPE = 'annotationNote'
+export const ANNOTATION_GROUP_NODE_TYPE = 'annotationGroup'
+
+export const DEFAULT_NOTE_SIZE = { width: 220, height: 140 }
+export const DEFAULT_GROUP_SIZE = { width: 360, height: 260 }
+
+/** Groups render behind the steps they frame; notes sit in the normal plane. */
+const GROUP_Z_INDEX = -1
+
+export interface AnnotationPoint {
+  x: number
+  y: number
+}
+
+export interface AnnotationSize {
+  width: number
+  height: number
+}
+
+export interface AnnotationRect extends AnnotationPoint, AnnotationSize {}
+
+export interface WorkflowEditorNote {
+  id: string
+  markdown: string
+  position: AnnotationPoint
+  size: AnnotationSize
+}
+
+/**
+ * A group is stored as a RECT rather than a member-id list. A region needs no
+ * maintenance when a step it happens to overlap is deleted, pasted or converted,
+ * and "which steps are in this group" is already answered by the canvas — an id
+ * list would be a second source of truth the engine must never read anyway.
+ */
+export interface WorkflowEditorGroup {
+  id: string
+  name: string
+  rect: AnnotationRect
+  collapsed?: boolean
+}
+
+export interface WorkflowEditorAnnotations {
+  notes: WorkflowEditorNote[]
+  groups: WorkflowEditorGroup[]
+}
+
+export interface WorkflowNoteNodeData extends Record<string, unknown> {
+  markdown: string
+}
+
+export interface WorkflowGroupNodeData extends Record<string, unknown> {
+  name: string
+  collapsed: boolean
+}
+
+export function createEmptyAnnotations(): WorkflowEditorAnnotations {
+  return { notes: [], groups: [] }
+}
+
+export function isAnnotationNodeType(nodeType: string | undefined | null): boolean {
+  return nodeType === ANNOTATION_NOTE_NODE_TYPE || nodeType === ANNOTATION_GROUP_NODE_TYPE
+}
+
+export function isAnnotationNode(node: { type?: string | null }): boolean {
+  return isAnnotationNodeType(node.type)
+}
+
+export function hasAnnotations(annotations: WorkflowEditorAnnotations | null | undefined): boolean {
+  if (!annotations) return false
+  return annotations.notes.length > 0 || annotations.groups.length > 0
+}
+
+export function generateAnnotationId(prefix: 'note' | 'group'): string {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 11)}`
+}
+
+function readPoint(value: unknown, fallback: AnnotationPoint): AnnotationPoint {
+  if (!value || typeof value !== 'object') return fallback
+  const candidate = value as Record<string, unknown>
+  const x = typeof candidate.x === 'number' && Number.isFinite(candidate.x) ? candidate.x : fallback.x
+  const y = typeof candidate.y === 'number' && Number.isFinite(candidate.y) ? candidate.y : fallback.y
+  return { x, y }
+}
+
+function readSize(value: unknown, fallback: AnnotationSize): AnnotationSize {
+  if (!value || typeof value !== 'object') return fallback
+  const candidate = value as Record<string, unknown>
+  const width = typeof candidate.width === 'number' && candidate.width > 0 ? candidate.width : fallback.width
+  const height = typeof candidate.height === 'number' && candidate.height > 0 ? candidate.height : fallback.height
+  return { width, height }
+}
+
+function readNote(value: unknown): WorkflowEditorNote | null {
+  if (!value || typeof value !== 'object') return null
+  const candidate = value as Record<string, unknown>
+  if (typeof candidate.id !== 'string' || candidate.id.length === 0) return null
+  return {
+    id: candidate.id,
+    markdown: typeof candidate.markdown === 'string' ? candidate.markdown : '',
+    position: readPoint(candidate.position, { x: 0, y: 0 }),
+    size: readSize(candidate.size, DEFAULT_NOTE_SIZE),
+  }
+}
+
+function readGroup(value: unknown): WorkflowEditorGroup | null {
+  if (!value || typeof value !== 'object') return null
+  const candidate = value as Record<string, unknown>
+  if (typeof candidate.id !== 'string' || candidate.id.length === 0) return null
+  const point = readPoint(candidate.rect, { x: 0, y: 0 })
+  const size = readSize(candidate.rect, DEFAULT_GROUP_SIZE)
+  const group: WorkflowEditorGroup = {
+    id: candidate.id,
+    name: typeof candidate.name === 'string' ? candidate.name : '',
+    rect: { x: point.x, y: point.y, width: size.width, height: size.height },
+  }
+  if (candidate.collapsed === true) group.collapsed = true
+  return group
+}
+
+/**
+ * Read the annotations carried by a definition's metadata bag, tolerating every
+ * shape a hand-edited or older document can hold. Anything unreadable is simply
+ * dropped rather than throwing: annotations are documentation, and a malformed
+ * note must never stop a workflow from opening.
+ */
+export function readEditorAnnotations(
+  metadata: Record<string, unknown> | null | undefined,
+): WorkflowEditorAnnotations {
+  const editorValue = metadata?.editor
+  if (!editorValue || typeof editorValue !== 'object' || Array.isArray(editorValue)) return createEmptyAnnotations()
+  const annotationsValue = (editorValue as Record<string, unknown>).annotations
+  if (!annotationsValue || typeof annotationsValue !== 'object' || Array.isArray(annotationsValue)) {
+    return createEmptyAnnotations()
+  }
+  const candidate = annotationsValue as Record<string, unknown>
+  const notes = Array.isArray(candidate.notes)
+    ? candidate.notes.map(readNote).filter((note): note is WorkflowEditorNote => note !== null)
+    : []
+  const groups = Array.isArray(candidate.groups)
+    ? candidate.groups.map(readGroup).filter((group): group is WorkflowEditorGroup => group !== null)
+    : []
+  return { notes, groups }
+}
+
+/**
+ * Write annotations back into a metadata bag. An empty set REMOVES the key (and
+ * the `editor` bag when nothing else lives there), so a workflow that never used
+ * an annotation keeps saving exactly the metadata it always did.
+ */
+export function writeEditorAnnotations(
+  metadata: Record<string, unknown> | null,
+  annotations: WorkflowEditorAnnotations | null | undefined,
+): Record<string, unknown> | null {
+  const base: Record<string, unknown> = { ...(metadata ?? {}) }
+  const editorValue = base.editor
+  const editor: Record<string, unknown> =
+    editorValue && typeof editorValue === 'object' && !Array.isArray(editorValue)
+      ? { ...(editorValue as Record<string, unknown>) }
+      : {}
+
+  if (hasAnnotations(annotations)) {
+    const payload: Record<string, unknown> = {}
+    if (annotations!.notes.length > 0) payload.notes = annotations!.notes
+    if (annotations!.groups.length > 0) payload.groups = annotations!.groups
+    editor.annotations = payload
+  } else {
+    delete editor.annotations
+  }
+
+  if (Object.keys(editor).length > 0) base.editor = editor
+  else delete base.editor
+  return Object.keys(base).length > 0 ? base : null
+}
+
+export function annotationsToNodes(annotations: WorkflowEditorAnnotations | null | undefined): Node[] {
+  if (!annotations) return []
+  const groupNodes: Node[] = annotations.groups.map((group) => ({
+    id: group.id,
+    type: ANNOTATION_GROUP_NODE_TYPE,
+    position: { x: group.rect.x, y: group.rect.y },
+    width: group.rect.width,
+    height: group.rect.height,
+    style: { width: group.rect.width, height: group.rect.height },
+    zIndex: GROUP_Z_INDEX,
+    data: { name: group.name, collapsed: group.collapsed === true } satisfies WorkflowGroupNodeData,
+  }))
+  const noteNodes: Node[] = annotations.notes.map((note) => ({
+    id: note.id,
+    type: ANNOTATION_NOTE_NODE_TYPE,
+    position: { x: note.position.x, y: note.position.y },
+    width: note.size.width,
+    height: note.size.height,
+    style: { width: note.size.width, height: note.size.height },
+    data: { markdown: note.markdown } satisfies WorkflowNoteNodeData,
+  }))
+  return [...groupNodes, ...noteNodes]
+}
+
+function nodeSize(node: Node, fallback: AnnotationSize): AnnotationSize {
+  const width = typeof node.width === 'number' && node.width > 0
+    ? node.width
+    : typeof node.measured?.width === 'number' && node.measured.width > 0
+      ? node.measured.width
+      : fallback.width
+  const height = typeof node.height === 'number' && node.height > 0
+    ? node.height
+    : typeof node.measured?.height === 'number' && node.measured.height > 0
+      ? node.measured.height
+      : fallback.height
+  return { width, height }
+}
+
+/** Derive the persisted annotations back out of the live node array. */
+export function annotationsFromNodes(nodes: Node[]): WorkflowEditorAnnotations {
+  const notes: WorkflowEditorNote[] = []
+  const groups: WorkflowEditorGroup[] = []
+  for (const node of nodes) {
+    if (node.type === ANNOTATION_NOTE_NODE_TYPE) {
+      const data = node.data as Partial<WorkflowNoteNodeData> | undefined
+      notes.push({
+        id: node.id,
+        markdown: typeof data?.markdown === 'string' ? data.markdown : '',
+        position: { x: node.position.x, y: node.position.y },
+        size: nodeSize(node, DEFAULT_NOTE_SIZE),
+      })
+      continue
+    }
+    if (node.type === ANNOTATION_GROUP_NODE_TYPE) {
+      const data = node.data as Partial<WorkflowGroupNodeData> | undefined
+      const size = nodeSize(node, DEFAULT_GROUP_SIZE)
+      const group: WorkflowEditorGroup = {
+        id: node.id,
+        name: typeof data?.name === 'string' ? data.name : '',
+        rect: { x: node.position.x, y: node.position.y, width: size.width, height: size.height },
+      }
+      if (data?.collapsed === true) group.collapsed = true
+      groups.push(group)
+    }
+  }
+  return { notes, groups }
+}
+
+export function createNoteNode(position: AnnotationPoint, markdown: string): Node {
+  return {
+    id: generateAnnotationId('note'),
+    type: ANNOTATION_NOTE_NODE_TYPE,
+    position: { x: position.x, y: position.y },
+    width: DEFAULT_NOTE_SIZE.width,
+    height: DEFAULT_NOTE_SIZE.height,
+    style: { width: DEFAULT_NOTE_SIZE.width, height: DEFAULT_NOTE_SIZE.height },
+    data: { markdown } satisfies WorkflowNoteNodeData,
+  }
+}
+
+export function createGroupNode(position: AnnotationPoint, name: string): Node {
+  return {
+    id: generateAnnotationId('group'),
+    type: ANNOTATION_GROUP_NODE_TYPE,
+    position: { x: position.x, y: position.y },
+    width: DEFAULT_GROUP_SIZE.width,
+    height: DEFAULT_GROUP_SIZE.height,
+    style: { width: DEFAULT_GROUP_SIZE.width, height: DEFAULT_GROUP_SIZE.height },
+    zIndex: GROUP_Z_INDEX,
+    data: { name, collapsed: false } satisfies WorkflowGroupNodeData,
+  }
+}
+
+export function updateAnnotationNode(
+  nodes: Node[],
+  nodeId: string,
+  updates: Partial<WorkflowNoteNodeData & WorkflowGroupNodeData>,
+): Node[] {
+  return nodes.map((node) =>
+    node.id === nodeId && isAnnotationNode(node)
+      ? { ...node, data: { ...node.data, ...updates } }
+      : node,
+  )
+}
+
+export function removeAnnotationNode(nodes: Node[], nodeId: string): Node[] {
+  return nodes.filter((node) => !(node.id === nodeId && isAnnotationNode(node)))
+}

package/src/modules/workflows/lib/editor-commands.ts

@@ -0,0 +1,205 @@
+/**
+ * The command list behind the Studio's Cmd+K palette (spec section 4.6).
+ *
+ * "Every canvas operation is reachable without a pointer: the command palette +
+ * inspector + Problems panel + Code view together form a complete non-pointer
+ * authoring path, and this is an explicit acceptance criterion." The palette is
+ * therefore not a convenience layer over the toolbar — it is the surface that
+ * makes the toolbar optional, which is why every mutating action the page
+ * exposes appears here and why a command that cannot run right now is DISABLED
+ * with its reason rather than hidden (a missing entry reads as "unsupported",
+ * a disabled one as "not now").
+ *
+ * PURE: descriptors in, descriptors out. The palette component only renders
+ * them and the page owns the effects, so dispatch is unit-testable without a
+ * dialog, a canvas or a keyboard.
+ */
+
+export type WorkflowCommandGroupId = 'edit' | 'add' | 'navigate' | 'view' | 'run'
+
+export const WORKFLOW_COMMAND_GROUP_ORDER: WorkflowCommandGroupId[] = ['edit', 'add', 'navigate', 'view', 'run']
+
+export interface WorkflowEditorCommand {
+  id: string
+  group: WorkflowCommandGroupId
+  label: string
+  description?: string
+  shortcut?: string
+  disabled: boolean
+  run: () => void
+}
+
+export interface WorkflowCommandStepOption {
+  id: string
+  label: string
+  typeLabel: string
+}
+
+export interface WorkflowCommandPaletteLabels {
+  undo: string
+  redo: string
+  deleteSelection: string
+  copy: string
+  paste: string
+  duplicate: string
+  addStep: (typeLabel: string) => string
+  addNote: string
+  addGroup: string
+  goToStep: string
+  tidy: string
+  togglePalette: string
+  toggleMetadata: string
+  toggleFocus: string
+  toggleProblems: string
+  toggleCodeView: string
+  toggleCompensation: string
+  validate: string
+  runTest: string
+  save: string
+  aiDraft: string
+}
+
+export interface WorkflowCommandPaletteActions {
+  undo: () => void
+  redo: () => void
+  deleteSelection: () => void
+  copy: () => void
+  paste: () => void
+  duplicate: () => void
+  addStep: (nodeType: string) => void
+  addNote: () => void
+  addGroup: () => void
+  goToStep: (stepId: string) => void
+  tidy: () => void
+  togglePalette: () => void
+  toggleMetadata: () => void
+  toggleFocus: () => void
+  toggleProblems: () => void
+  toggleCodeView: () => void
+  toggleCompensation: () => void
+  validate: () => void
+  runTest: () => void
+  aiDraft: () => void
+  save: () => void
+}
+
+export interface WorkflowCommandContext {
+  readOnly: boolean
+  canUndo: boolean
+  canRedo: boolean
+  hasNodes: boolean
+  hasSelection: boolean
+  canRunTest: boolean
+  stepTypes: Array<{ nodeType: string; typeLabel: string }>
+  steps: WorkflowCommandStepOption[]
+  labels: WorkflowCommandPaletteLabels
+  actions: WorkflowCommandPaletteActions
+}
+
+export function buildWorkflowEditorCommands(context: WorkflowCommandContext): WorkflowEditorCommand[] {
+  const { readOnly, labels, actions } = context
+  const commands: WorkflowEditorCommand[] = [
+    {
+      id: 'edit.undo',
+      group: 'edit',
+      label: labels.undo,
+      shortcut: 'Cmd+Z',
+      disabled: readOnly || !context.canUndo,
+      run: actions.undo,
+    },
+    {
+      id: 'edit.redo',
+      group: 'edit',
+      label: labels.redo,
+      shortcut: 'Cmd+Shift+Z',
+      disabled: readOnly || !context.canRedo,
+      run: actions.redo,
+    },
+    {
+      id: 'edit.delete',
+      group: 'edit',
+      label: labels.deleteSelection,
+      shortcut: 'Del',
+      disabled: readOnly || !context.hasSelection,
+      run: actions.deleteSelection,
+    },
+    {
+      id: 'edit.copy',
+      group: 'edit',
+      label: labels.copy,
+      shortcut: 'Cmd+C',
+      disabled: !context.hasSelection,
+      run: actions.copy,
+    },
+    {
+      id: 'edit.paste',
+      group: 'edit',
+      label: labels.paste,
+      shortcut: 'Cmd+V',
+      disabled: readOnly,
+      run: actions.paste,
+    },
+    {
+      id: 'edit.duplicate',
+      group: 'edit',
+      label: labels.duplicate,
+      shortcut: 'Cmd+D',
+      disabled: readOnly || !context.hasSelection,
+      run: actions.duplicate,
+    },
+  ]
+
+  for (const stepType of context.stepTypes) {
+    commands.push({
+      id: `add.step.${stepType.nodeType}`,
+      group: 'add',
+      label: labels.addStep(stepType.typeLabel),
+      disabled: readOnly,
+      run: () => actions.addStep(stepType.nodeType),
+    })
+  }
+
+  commands.push(
+    { id: 'add.note', group: 'add', label: labels.addNote, disabled: readOnly, run: actions.addNote },
+    { id: 'add.group', group: 'add', label: labels.addGroup, disabled: readOnly, run: actions.addGroup },
+  )
+
+  for (const step of context.steps) {
+    commands.push({
+      id: `navigate.step.${step.id}`,
+      group: 'navigate',
+      label: `${labels.goToStep}: ${step.label}`,
+      description: step.typeLabel,
+      disabled: false,
+      run: () => actions.goToStep(step.id),
+    })
+  }
+
+  commands.push(
+    { id: 'view.tidy', group: 'view', label: labels.tidy, disabled: readOnly || !context.hasNodes, run: actions.tidy },
+    { id: 'view.togglePalette', group: 'view', label: labels.togglePalette, disabled: false, run: actions.togglePalette },
+    { id: 'view.toggleMetadata', group: 'view', label: labels.toggleMetadata, disabled: false, run: actions.toggleMetadata },
+    { id: 'view.toggleFocus', group: 'view', label: labels.toggleFocus, shortcut: 'F', disabled: false, run: actions.toggleFocus },
+    { id: 'view.toggleProblems', group: 'view', label: labels.toggleProblems, disabled: false, run: actions.toggleProblems },
+    { id: 'view.toggleCodeView', group: 'view', label: labels.toggleCodeView, disabled: false, run: actions.toggleCodeView },
+    { id: 'view.toggleCompensation', group: 'view', label: labels.toggleCompensation, disabled: false, run: actions.toggleCompensation },
+    // Prompt-to-draft (spec section 9). Present here for the same reason every
+    // other mutating action is: the palette is the complete non-pointer path,
+    // and a missing entry reads as "unsupported".
+    { id: 'add.aiDraft', group: 'add', label: labels.aiDraft, disabled: readOnly, run: actions.aiDraft },
+    { id: 'run.validate', group: 'run', label: labels.validate, disabled: false, run: actions.validate },
+    { id: 'run.test', group: 'run', label: labels.runTest, disabled: !context.canRunTest, run: actions.runTest },
+    { id: 'run.save', group: 'run', label: labels.save, shortcut: 'Cmd+S', disabled: readOnly, run: actions.save },
+  )
+
+  return commands
+}
+
+/** Group commands for rendering, preserving `WORKFLOW_COMMAND_GROUP_ORDER`. */
+export function groupWorkflowEditorCommands(
+  commands: WorkflowEditorCommand[],
+): Array<{ group: WorkflowCommandGroupId; commands: WorkflowEditorCommand[] }> {
+  return WORKFLOW_COMMAND_GROUP_ORDER
+    .map((group) => ({ group, commands: commands.filter((command) => command.group === group) }))
+    .filter((section) => section.commands.length > 0)
+}

package/src/modules/workflows/lib/editor-history.ts

@@ -0,0 +1,151 @@
+/**
+ * Undo/redo command stack for the workflow Studio (spec section 4.5).
+ *
+ * One stack over the whole editor document — the canvas and the inspector edit
+ * the same `{ nodes, edges, metadata }` object, so a step rename undoes exactly
+ * like a deleted route. Entries are SNAPSHOTS rather than diffs: a workflow
+ * document is small enough that copying a reference to the already-immutable
+ * node/edge arrays costs nothing, and a snapshot cannot drift out of sync with
+ * the live state the way an inverse-command log can.
+ *
+ * The stack stores the document as it was BEFORE each edit, which is what lets
+ * callers commit from inside an asynchronous handler: capture the document up
+ * front, run the confirmation, and only commit once the edit actually lands.
+ *
+ * Every entry carries a human label ("Delete step", "Paste"), so the shortcut
+ * can say what it just reverted and a later phase can name AI checkpoints in
+ * the same stack.
+ *
+ * PURE: plain data in, plain data out — no React, no xyflow runtime.
+ */
+
+import type { Node, Edge } from '@xyflow/react'
+
+/** Spec section 4.5: "100 steps". */
+export const EDITOR_HISTORY_LIMIT = 100
+
+/**
+ * The document the stack versions. `metadata` is the definition's editor-owned
+ * metadata bag (pinned samples and, from step 3.9, annotations); the
+ * definition-panel text fields are deliberately NOT on the stack — a text input
+ * has its own native undo and committing per keystroke would evict real
+ * structural edits from a 100-entry stack.
+ */
+/**
+ * The definition-panel fields the canvas does NOT carry — triggers, the context
+ * schema, the sub-workflow port contract, the interpolation mode and the
+ * workflow-level error handler.
+ *
+ * Kept OPAQUE here on purpose: this module must not learn the definition's
+ * vocabulary to version it, and the page is the only thing that reads the
+ * shape back. Versioning them matters because the Code view's Apply replaces
+ * the WHOLE document — undoing it without them would restore the graph with
+ * somebody else's triggers attached.
+ */
+export interface WorkflowEditorPanelState {
+  triggers: unknown
+  contextSchema: unknown
+  io: unknown
+  interpolation: unknown
+  errorHandler: unknown
+}
+
+export interface WorkflowEditorDocument {
+  nodes: Node[]
+  edges: Edge[]
+  metadata: Record<string, unknown> | null
+  /**
+   * Absent on entries captured before this field existed, which is why every
+   * reader treats it as optional and simply leaves the panel alone when it is
+   * missing.
+   */
+  panel?: WorkflowEditorPanelState
+}
+
+export interface EditorHistoryEntry<TDocument> {
+  /** Translated description of the edit this entry reverts. */
+  label: string
+  document: TDocument
+}
+
+export interface EditorHistoryState<TDocument> {
+  past: EditorHistoryEntry<TDocument>[]
+  future: EditorHistoryEntry<TDocument>[]
+}
+
+export interface EditorHistoryStep<TDocument> {
+  state: EditorHistoryState<TDocument>
+  document: TDocument
+  label: string
+}
+
+export function createEditorHistory<TDocument>(): EditorHistoryState<TDocument> {
+  return { past: [], future: [] }
+}
+
+/**
+ * Record an edit.
+ *
+ * `previousDocument` is the state to return to, and `label` names the edit that
+ * replaced it. A new edit invalidates the redo branch: once the author has
+ * diverged, the abandoned future is unreachable and keeping it would let a redo
+ * resurrect a document that never followed from what is on screen.
+ */
+export function commitEditorHistory<TDocument>(
+  state: EditorHistoryState<TDocument>,
+  previousDocument: TDocument,
+  label: string,
+  limit: number = EDITOR_HISTORY_LIMIT,
+): EditorHistoryState<TDocument> {
+  const past = [...state.past, { label, document: previousDocument }]
+  return {
+    past: past.length > limit ? past.slice(past.length - limit) : past,
+    future: [],
+  }
+}
+
+export function canUndoEditorHistory<TDocument>(state: EditorHistoryState<TDocument>): boolean {
+  return state.past.length > 0
+}
+
+export function canRedoEditorHistory<TDocument>(state: EditorHistoryState<TDocument>): boolean {
+  return state.future.length > 0
+}
+
+/**
+ * Step back one edit. Returns the document to restore plus the next stack
+ * state, or `null` when there is nothing to undo. `currentDocument` is what is
+ * on screen right now — it becomes the redo target.
+ */
+export function undoEditorHistory<TDocument>(
+  state: EditorHistoryState<TDocument>,
+  currentDocument: TDocument,
+): EditorHistoryStep<TDocument> | null {
+  const entry = state.past[state.past.length - 1]
+  if (!entry) return null
+  return {
+    state: {
+      past: state.past.slice(0, state.past.length - 1),
+      future: [{ label: entry.label, document: currentDocument }, ...state.future],
+    },
+    document: entry.document,
+    label: entry.label,
+  }
+}
+
+/** Step forward one previously undone edit. */
+export function redoEditorHistory<TDocument>(
+  state: EditorHistoryState<TDocument>,
+  currentDocument: TDocument,
+): EditorHistoryStep<TDocument> | null {
+  const entry = state.future[0]
+  if (!entry) return null
+  return {
+    state: {
+      past: [...state.past, { label: entry.label, document: currentDocument }],
+      future: state.future.slice(1),
+    },
+    document: entry.document,
+    label: entry.label,
+  }
+}