@bendyline/squisq-editor-react 1.6.2 → 2.0.0

package/src/asciiDiagram/__tests__/RepairableDiagramExtension.test.ts

@@ -0,0 +1,159 @@
+/**
+ * RepairableDiagramExtension: a broken box-art fence gets a repair entry (and
+ * the inline button); applying the repair rewrites it to clean, `diagram`-
+ * tagged art that the AsciiDiagramExtension then claims. One undo restores the
+ * original broken bytes.
+ */
+
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { detectAsciiDiagram } from '@bendyline/squisq/doc';
+import { markdownToTiptap } from '../../tiptapBridge';
+import { HeadingWithTemplate } from '../../TemplateAnnotation';
+import { AsciiDiagramExtension, ASCII_DIAGRAM_KEY } from '../AsciiDiagramExtension';
+import { RepairableDiagramExtension, REPAIRABLE_KEY } from '../RepairableDiagramExtension';
+import { applyRepairCommand } from '../asciiDiagramCommands';
+
+beforeAll(() => {
+  if (typeof globalThis.ResizeObserver === 'undefined') {
+    class ResizeObserverStub {
+      observe(): void {}
+      unobserve(): void {}
+      disconnect(): void {}
+    }
+    globalThis.ResizeObserver = ResizeObserverStub as unknown as typeof ResizeObserver;
+  }
+});
+
+// Broken box art: labels overflow + collide, so the columns desync row-to-row
+// and conservative detection declines it.
+const BROKEN = [
+  '┌──────────┐   ┌──────────┐',
+  '│ @scope/alpha-svc  │   │ @scope/beta-svc   │',
+  '│ one      │   │ two      │',
+  '└────┬─────┘   └────┬─────┘',
+  '     │              │',
+  '     ▼              ▼',
+  '┌────────────────────────────┐',
+  '│ @scope/gamma-store         │',
+  '│ persists                   │',
+  '└────────────────────────────┘',
+].join('\n');
+
+const CLEAN = [
+  '┌────────┐',
+  '│ Alpha  │',
+  '└───┬────┘',
+  '    ▼',
+  '┌────────┐',
+  '│ Beta   │',
+  '└────────┘',
+].join('\n');
+
+let editors: Editor[] = [];
+
+function makeEditor(md: string): Editor {
+  const editor = new Editor({
+    extensions: [
+      StarterKit.configure({
+        heading: false,
+        codeBlock: { HTMLAttributes: { class: 'squisq-code-block' } },
+      }),
+      HeadingWithTemplate.configure({ levels: [1, 2, 3, 4, 5, 6] }),
+      AsciiDiagramExtension,
+      RepairableDiagramExtension.configure({ onRepair: applyRepairCommand }),
+    ],
+    content: markdownToTiptap(md),
+  });
+  editors.push(editor);
+  return editor;
+}
+
+afterEach(() => {
+  for (const e of editors) e.destroy();
+  editors = [];
+});
+
+const fenced = (art: string) => '```\n' + art + '\n```\n';
+
+function fenceOf(editor: Editor): { text: string; language: string | null } {
+  let text = '';
+  let language: string | null = null;
+  editor.state.doc.descendants((node) => {
+    if (node.type.name === 'codeBlock' && text === '') {
+      text = node.textContent;
+      language = (node.attrs as { language?: string | null }).language ?? null;
+      return false;
+    }
+    return true;
+  });
+  return { text, language };
+}
+
+function repairId(editor: Editor): string | undefined {
+  return REPAIRABLE_KEY.getState(editor.state)?.entries[0]?.id;
+}
+
+describe('RepairableDiagramExtension', () => {
+  it('registers a repair entry for broken box art', () => {
+    const editor = makeEditor(fenced(BROKEN));
+    expect(REPAIRABLE_KEY.getState(editor.state)?.entries.length).toBe(1);
+    // …and the AsciiDiagramExtension does NOT claim it (garbled labels).
+    expect(ASCII_DIAGRAM_KEY.getState(editor.state)?.entries.length).toBe(0);
+  });
+
+  it('offers no button for a CLEAN diagram (the canvas handles it)', () => {
+    const editor = makeEditor(fenced(CLEAN));
+    expect(REPAIRABLE_KEY.getState(editor.state)?.entries.length).toBe(0);
+    expect(ASCII_DIAGRAM_KEY.getState(editor.state)?.entries.length).toBe(1);
+  });
+
+  it('offers no button for ordinary prose fences', () => {
+    const editor = makeEditor(fenced('just some\nplain prose\nlines here'));
+    expect(REPAIRABLE_KEY.getState(editor.state)?.entries.length).toBe(0);
+  });
+
+  it('repairs the fence into clean, diagram-tagged art the canvas then claims', () => {
+    const editor = makeEditor(fenced(BROKEN));
+    const id = repairId(editor)!;
+    expect(applyRepairCommand(editor, id)).toBe(true);
+
+    const fence = fenceOf(editor);
+    // Language promoted to the explicit `diagram` tag.
+    expect(fence.language).toBe('diagram');
+    // The art is now a clean, detectable diagram with the recovered labels.
+    const detection = detectAsciiDiagram(fence.text);
+    expect(detection.isDiagram).toBe(true);
+    expect(fence.text).toContain('@scope/alpha-svc');
+    expect(fence.text).toContain('@scope/gamma-store');
+    // The repairable entry is gone; the AsciiDiagramExtension now claims it.
+    expect(REPAIRABLE_KEY.getState(editor.state)?.entries.length).toBe(0);
+    expect(ASCII_DIAGRAM_KEY.getState(editor.state)?.entries.length).toBe(1);
+  });
+
+  it('one undo restores the original broken art', () => {
+    const editor = makeEditor(fenced(BROKEN));
+    const before = fenceOf(editor).text;
+    applyRepairCommand(editor, repairId(editor)!);
+    expect(fenceOf(editor).text).not.toBe(before);
+    editor.commands.undo();
+    expect(fenceOf(editor).text).toBe(before);
+    // …and it is a repair candidate again, NOT still claimed as a diagram
+    // (the relaxed hysteresis gate must reject the garbled art).
+    expect(REPAIRABLE_KEY.getState(editor.state)?.entries.length).toBe(1);
+    expect(ASCII_DIAGRAM_KEY.getState(editor.state)?.entries.length).toBe(0);
+  });
+
+  it('is inert when disabled', () => {
+    const editor = new Editor({
+      extensions: [
+        StarterKit.configure({ heading: false }),
+        RepairableDiagramExtension.configure({ enabled: false }),
+      ],
+      content: markdownToTiptap(fenced(BROKEN)),
+    });
+    editors.push(editor);
+    expect(REPAIRABLE_KEY.getState(editor.state)).toBeUndefined();
+  });
+});

package/src/asciiDiagram/__tests__/asciiDiagramCommands.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Command pipeline through a REAL tiptap editor: fence text in →
+ * `applyAsciiDiagramCommand` → fence text out, verified by re-parsing.
+ */
+
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { ASCII_CHAR_H, ASCII_CHAR_W, parseAsciiDiagram } from '@bendyline/squisq/doc';
+import { markdownToTiptap } from '../../tiptapBridge';
+import { HeadingWithTemplate } from '../../TemplateAnnotation';
+import { AsciiDiagramExtension, ASCII_DIAGRAM_KEY } from '../AsciiDiagramExtension';
+import { applyAsciiDiagramCommand, replaceAsciiFenceText } from '../asciiDiagramCommands';
+
+beforeAll(() => {
+  if (typeof globalThis.ResizeObserver === 'undefined') {
+    class ResizeObserverStub {
+      observe(): void {}
+      unobserve(): void {}
+      disconnect(): void {}
+    }
+    globalThis.ResizeObserver = ResizeObserverStub as unknown as typeof ResizeObserver;
+  }
+});
+
+const ART = [
+  '┌────────┐',
+  '│ Alpha  │',
+  '└───┬────┘',
+  '    │',
+  '    ▼',
+  '┌────────┐',
+  '│ Beta   │',
+  '└────────┘',
+].join('\n');
+
+let editors: Editor[] = [];
+
+function makeEditor(md: string): Editor {
+  const editor = new Editor({
+    extensions: [
+      StarterKit.configure({
+        heading: false,
+        codeBlock: { HTMLAttributes: { class: 'squisq-code-block' } },
+      }),
+      HeadingWithTemplate.configure({ levels: [1, 2, 3, 4, 5, 6] }),
+      AsciiDiagramExtension,
+    ],
+    content: markdownToTiptap(md),
+  });
+  editors.push(editor);
+  return editor;
+}
+
+afterEach(() => {
+  for (const e of editors) e.destroy();
+  editors = [];
+});
+
+function firstBlockId(editor: Editor): string {
+  const state = ASCII_DIAGRAM_KEY.getState(editor.state);
+  expect(state?.entries.length).toBeGreaterThan(0);
+  return state?.entries[0].id as string;
+}
+
+function fenceOf(editor: Editor): { text: string; language: string | null } {
+  let text = '';
+  let language: string | null = null;
+  editor.state.doc.descendants((node) => {
+    if (node.type.name === 'codeBlock' && text === '') {
+      text = node.textContent;
+      language = (node.attrs as { language?: string | null }).language ?? null;
+      return false;
+    }
+    return true;
+  });
+  return { text, language };
+}
+
+describe('applyAsciiDiagramCommand', () => {
+  it('moveNode rewrites the fence with the node at the new cell', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    const ok = applyAsciiDiagramCommand(editor, id, {
+      kind: 'moveNode',
+      nodeId: 'beta',
+      x: 20 * ASCII_CHAR_W,
+      y: 10 * ASCII_CHAR_H,
+    });
+    expect(ok).toBe(true);
+    const reparsed = parseAsciiDiagram(fenceOf(editor).text);
+    expect(reparsed.nodes.map((n) => n.id).sort()).toEqual(['alpha', 'beta']);
+    expect(reparsed.edges).toEqual([{ source: 'alpha', target: 'beta', directed: true }]);
+    expect(reparsed.nodes.find((n) => n.id === 'beta')?.col).toBe(20);
+  });
+
+  it('addConnection adds a reciprocal edge (renders as a double arrow)', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    expect(
+      applyAsciiDiagramCommand(editor, id, {
+        kind: 'addConnection',
+        source: 'beta',
+        target: 'alpha',
+      }),
+    ).toBe(true);
+    const reparsed = parseAsciiDiagram(fenceOf(editor).text);
+    expect(reparsed.edges).toHaveLength(2);
+  });
+
+  it('renameNode rewrites labels (and therefore ids)', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    expect(
+      applyAsciiDiagramCommand(editor, id, {
+        kind: 'renameNode',
+        nodeId: 'alpha',
+        newLabel: 'Gateway',
+      }),
+    ).toBe(true);
+    const reparsed = parseAsciiDiagram(fenceOf(editor).text);
+    expect(reparsed.nodes.map((n) => n.id).sort()).toEqual(['beta', 'gateway']);
+    expect(reparsed.edges).toEqual([{ source: 'gateway', target: 'beta', directed: true }]);
+  });
+
+  it('addNode / removeNode change the box count', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    expect(
+      applyAsciiDiagramCommand(editor, id, { kind: 'addNode', x: 40 * ASCII_CHAR_W, y: 0 }),
+    ).toBe(true);
+    expect(parseAsciiDiagram(fenceOf(editor).text).nodes).toHaveLength(3);
+    expect(applyAsciiDiagramCommand(editor, id, { kind: 'removeNode', nodeId: 'node-1' })).toBe(
+      true,
+    );
+    expect(parseAsciiDiagram(fenceOf(editor).text).nodes).toHaveLength(2);
+  });
+
+  it('promotes the fence language to the explicit `diagram` tag on edit', () => {
+    // A once-edited diagram should carry `language: 'diagram'` so its identity
+    // survives a later flatten → markdown → re-import round-trip (the language
+    // class round-trips; fence meta does not).
+    const editor = makeEditor('```text\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    expect(fenceOf(editor).language).toBe('text');
+    applyAsciiDiagramCommand(editor, id, {
+      kind: 'moveNode',
+      nodeId: 'beta',
+      x: 15 * ASCII_CHAR_W,
+      y: 9 * ASCII_CHAR_H,
+    });
+    expect(fenceOf(editor).language).toBe('diagram');
+  });
+
+  it('keeps the block id stable across the language-promotion rewrite', () => {
+    // The promotion is a `setNodeMarkup` boundary rewrite; the position
+    // registry must still recognize the same block so a follow-up command
+    // resolves it (and the widget's React root survives).
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    applyAsciiDiagramCommand(editor, id, {
+      kind: 'moveNode',
+      nodeId: 'beta',
+      x: 15 * ASCII_CHAR_W,
+      y: 9 * ASCII_CHAR_H,
+    });
+    expect(firstBlockId(editor)).toBe(id);
+    expect(fenceOf(editor).language).toBe('diagram');
+  });
+
+  it('one undo restores the original fence bytes', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    const before = fenceOf(editor).text;
+    applyAsciiDiagramCommand(editor, id, {
+      kind: 'moveNode',
+      nodeId: 'beta',
+      x: 22 * ASCII_CHAR_W,
+      y: 12 * ASCII_CHAR_H,
+    });
+    expect(fenceOf(editor).text).not.toBe(before);
+    editor.commands.undo();
+    expect(fenceOf(editor).text).toBe(before);
+  });
+
+  it('no-op commands leave the document untouched', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const id = firstBlockId(editor);
+    const beta = parseAsciiDiagram(fenceOf(editor).text).nodes.find((n) => n.id === 'beta');
+    const json = JSON.stringify(editor.state.doc.toJSON());
+    const ok = applyAsciiDiagramCommand(editor, id, {
+      kind: 'moveNode',
+      nodeId: 'beta',
+      x: (beta?.col ?? 0) * ASCII_CHAR_W,
+      y: (beta?.row ?? 0) * ASCII_CHAR_H,
+    });
+    expect(ok).toBe(false);
+    expect(JSON.stringify(editor.state.doc.toJSON())).toBe(json);
+  });
+
+  it('returns false for an unknown block id', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    expect(
+      applyAsciiDiagramCommand(editor, 'ascii-999', {
+        kind: 'removeNode',
+        nodeId: 'alpha',
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('replaceAsciiFenceText', () => {
+  it('replaces only the text content, not attributes', () => {
+    const editor = makeEditor('```text\n' + ART + '\n```\n');
+    const state = ASCII_DIAGRAM_KEY.getState(editor.state);
+    const pos = state?.entries[0].pos as number;
+    expect(replaceAsciiFenceText(editor, pos, 'replacement')).toBe(true);
+    expect(fenceOf(editor)).toEqual({ text: 'replacement', language: 'text' });
+  });
+
+  it('no-ops on identical text', () => {
+    const editor = makeEditor('```\n' + ART + '\n```\n');
+    const state = ASCII_DIAGRAM_KEY.getState(editor.state);
+    const pos = state?.entries[0].pos as number;
+    expect(replaceAsciiFenceText(editor, pos, ART)).toBe(false);
+  });
+});

package/src/asciiDiagram/__tests__/asciiDiagramOps.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { parseAsciiDiagram, type AsciiDiagram } from '@bendyline/squisq/doc';
+import {
+  addEdgeOp,
+  addNodeOp,
+  moveNodeOp,
+  removeEdgeOp,
+  removeNodeOp,
+  renameNodeOp,
+  resizeNodeOp,
+  sanitizeAsciiLabel,
+} from '../asciiDiagramOps';
+
+const TWO_BOX = [
+  '┌────────┐',
+  '│ Alpha  │',
+  '└───┬────┘',
+  '    │',
+  '    ▼',
+  '┌────────┐',
+  '│ Beta   │',
+  '└────────┘',
+].join('\n');
+
+const NESTED = [
+  '┌─── Cluster ────┐',
+  '│  ┌──────────┐  │',
+  '│  │ Worker   │  │',
+  '│  └──────────┘  │',
+  '└────────────────┘',
+].join('\n');
+
+function base(): AsciiDiagram {
+  return parseAsciiDiagram(TWO_BOX);
+}
+
+describe('sanitizeAsciiLabel', () => {
+  it('strips structural glyphs, backticks, and newlines', () => {
+    expect(sanitizeAsciiLabel('a │ b ── c ▼ `d`\ne')).toBe('a b c d e');
+  });
+});
+
+describe('asciiDiagramOps', () => {
+  it('moveNodeOp translates a node without mutating the input', () => {
+    const d = base();
+    const next = moveNodeOp(d, 'beta', 20, 10);
+    expect(next.nodes.find((n) => n.id === 'beta')).toMatchObject({ col: 20, row: 10 });
+    expect(d.nodes.find((n) => n.id === 'beta')).toMatchObject({ col: 0, row: 5 });
+  });
+
+  it('moveNodeOp on a container translates the whole subtree', () => {
+    const d = parseAsciiDiagram(NESTED);
+    const worker = d.nodes.find((n) => n.id === 'worker');
+    const next = moveNodeOp(d, 'cluster', 10, 8);
+    const movedWorker = next.nodes.find((n) => n.id === 'worker');
+    expect(movedWorker?.col).toBe((worker?.col ?? 0) + 10);
+    expect(movedWorker?.row).toBe((worker?.row ?? 0) + 8);
+  });
+
+  it('resizeNodeOp clamps to the label minimum', () => {
+    const next = resizeNodeOp(base(), 'alpha', 1, 1);
+    const alpha = next.nodes.find((n) => n.id === 'alpha');
+    expect(alpha?.wCols).toBeGreaterThanOrEqual('Alpha'.length + 4);
+    expect(alpha?.hRows).toBeGreaterThanOrEqual(3);
+  });
+
+  it('addEdgeOp adds directed edges and dedupes', () => {
+    const d = base();
+    const withEdge = addEdgeOp(d, 'beta', 'alpha', 'back');
+    expect(withEdge.edges).toHaveLength(2);
+    expect(addEdgeOp(withEdge, 'beta', 'alpha', 'back').edges).toHaveLength(2);
+    // Self-edges and unknown endpoints are no-ops.
+    expect(addEdgeOp(d, 'alpha', 'alpha')).toBe(d);
+    expect(addEdgeOp(d, 'alpha', 'ghost')).toBe(d);
+  });
+
+  it('removeEdgeOp removes the first (source, target) match', () => {
+    const next = removeEdgeOp(base(), 'alpha', 'beta');
+    expect(next.edges).toHaveLength(0);
+  });
+
+  it('renameNodeOp sanitizes and updates the label', () => {
+    const next = renameNodeOp(base(), 'alpha', 'Gate │ way');
+    expect(next.nodes.find((n) => n.id === 'alpha')?.label).toBe('Gate way');
+  });
+
+  it('addNodeOp picks a fresh label and inherits containment', () => {
+    const nested = parseAsciiDiagram(NESTED);
+    const cluster = nested.nodes.find((n) => n.id === 'cluster');
+    const inside = addNodeOp(nested, {
+      col: (cluster?.col ?? 0) + 2,
+      row: (cluster?.row ?? 0) + 1,
+    });
+    const added = inside.diagram.nodes[inside.diagram.nodes.length - 1];
+    expect(added.label).toBe('Node 1');
+    expect(added.containerId).toBe('cluster');
+
+    const outside = addNodeOp(nested, { col: 100, row: 100 });
+    const addedOutside = outside.diagram.nodes[outside.diagram.nodes.length - 1];
+    expect(addedOutside.containerId).toBeUndefined();
+  });
+
+  it('removeNodeOp drops incident edges and promotes children', () => {
+    const d = base();
+    const next = removeNodeOp(d, 'beta');
+    expect(next.nodes.map((n) => n.id)).toEqual(['alpha']);
+    expect(next.edges).toHaveLength(0);
+
+    const nested = parseAsciiDiagram(NESTED);
+    const promoted = removeNodeOp(nested, 'cluster');
+    expect(promoted.nodes.map((n) => n.id)).toEqual(['worker']);
+    expect(promoted.nodes[0].containerId).toBeUndefined();
+  });
+});

package/src/asciiDiagram/__tests__/asciiPaste.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { shouldPasteAsAsciiFence } from '../asciiPaste';
+
+const ASCII_ART = [
+  '+--------+     +--------+',
+  '| Input  | --> | Output |',
+  '+--------+     +--------+',
+].join('\n');
+
+const UNICODE_ART = [
+  '┌────────┐',
+  '│ Alpha  │',
+  '└───┬────┘',
+  '    │',
+  '    ▼',
+  '┌────────┐',
+  '│ Beta   │',
+  '└────────┘',
+].join('\n');
+
+describe('shouldPasteAsAsciiFence', () => {
+  it('accepts bare ASCII art (which would otherwise misdetect as a GFM table)', () => {
+    expect(shouldPasteAsAsciiFence(ASCII_ART)).toBe(true);
+  });
+
+  it('accepts bare Unicode box art', () => {
+    expect(shouldPasteAsAsciiFence(UNICODE_ART)).toBe(true);
+  });
+
+  it('rejects a real GFM table', () => {
+    const table = ['| Name | Role |', '|------|------|', '| Ada  | Eng  |'].join('\n');
+    expect(shouldPasteAsAsciiFence(table)).toBe(false);
+  });
+
+  it('rejects text that already contains a fence', () => {
+    expect(shouldPasteAsAsciiFence('```\n' + ASCII_ART + '\n```')).toBe(false);
+  });
+
+  it('rejects prose and empty input', () => {
+    expect(shouldPasteAsAsciiFence('Just a normal paragraph of text.')).toBe(false);
+    expect(shouldPasteAsAsciiFence('')).toBe(false);
+  });
+});

package/src/asciiDiagram/asciiDiagramCommands.ts

@@ -0,0 +1,148 @@
+/**
+ * Write direction of the ASCII diagram loop: canvas command → fence rewrite.
+ *
+ * Every semantic edit is one functional transformation of the fence text
+ * (`renderAscii(applyOp(parseAscii(text)))`) committed as a single
+ * ProseMirror transaction (= a single undo step). Before committing, the
+ * rendered art is re-parsed and verified — if the renderer ever produced
+ * something the parser disagrees with, the command aborts instead of
+ * corrupting the fence.
+ */
+
+import type { Editor } from '@tiptap/react';
+import {
+  canvasToAsciiCell,
+  ASCII_CHAR_H,
+  ASCII_CHAR_W,
+  parseAsciiDiagram,
+  renderAsciiDiagram,
+  repairAsciiDiagram,
+  type AsciiDiagram,
+} from '@bendyline/squisq/doc';
+import type { DiagramCommand } from '../diagram/DiagramCanvas';
+import { findAsciiDiagramBlockPos, parseAsciiDiagramForNode } from './AsciiDiagramExtension';
+import { findRepairableBlockPos } from './RepairableDiagramExtension';
+import {
+  addEdgeOp,
+  addNodeOp,
+  moveNodeOp,
+  removeEdgeOp,
+  removeNodeOp,
+  renameNodeOp,
+  resizeNodeOp,
+} from './asciiDiagramOps';
+
+/**
+ * Replace the TEXT inside the codeBlock at `pos` and, when `ensureLanguage`
+ * is given, promote its `language` attribute in the SAME transaction (one
+ * undo step). Promoting the language to the explicit `diagram`/`tree` tag is
+ * how a semantic edit makes the block's identity "sticky" — the language
+ * class survives markdown ↔ Tiptap round-trips, so a once-edited diagram/tree
+ * is re-recognized even after it's flattened. No-op (returns false) only when
+ * BOTH the text is already identical AND the language already matches, so
+ * history stays clean on a true no-op.
+ */
+export function replaceAsciiFenceText(
+  editor: Editor,
+  pos: number,
+  nextText: string,
+  ensureLanguage?: string,
+): boolean {
+  return editor
+    .chain()
+    .command(({ tr, state }) => {
+      const node = tr.doc.nodeAt(pos);
+      if (!node || node.type.name !== 'codeBlock') return false;
+      const textChanged = node.textContent !== nextText;
+      const currentLang = (node.attrs as { language?: string | null }).language ?? null;
+      const langChanged = ensureLanguage !== undefined && currentLang !== ensureLanguage;
+      if (!textChanged && !langChanged) return false;
+      if (langChanged) {
+        tr.setNodeMarkup(pos, undefined, { ...node.attrs, language: ensureLanguage });
+      }
+      if (textChanged) {
+        tr.replaceWith(pos + 1, pos + node.nodeSize - 1, state.schema.text(nextText));
+      }
+      return true;
+    })
+    .run();
+}
+
+/**
+ * Reconstruct a broken box-art fence into clean, `diagram`-tagged art in a
+ * single transaction (one undo step). The AsciiDiagramExtension then claims
+ * the tagged fence and mounts the interactive canvas. Returns false when the
+ * block is gone or nothing recoverable (the button simply no-ops).
+ */
+export function applyRepairCommand(editor: Editor, blockId: string): boolean {
+  const pos = findRepairableBlockPos(editor, blockId);
+  if (pos === null) return false;
+  const node = editor.state.doc.nodeAt(pos);
+  if (!node || node.type.name !== 'codeBlock') return false;
+  const repaired = repairAsciiDiagram(node.textContent);
+  if (!repaired) return false;
+  return replaceAsciiFenceText(editor, pos, repaired.art, 'diagram');
+}
+
+/** Apply one pure op to a registered block's parsed diagram. */
+function applyOp(
+  editor: Editor,
+  blockId: string,
+  op: (diagram: AsciiDiagram) => AsciiDiagram,
+): boolean {
+  // Resolve the position at dispatch time — captured positions go stale
+  // the moment anything above the block changes.
+  const pos = findAsciiDiagramBlockPos(editor, blockId);
+  if (pos === null) return false;
+  const node = editor.state.doc.nodeAt(pos);
+  if (!node || node.type.name !== 'codeBlock') return false;
+  const diagram = parseAsciiDiagramForNode(node);
+  if (!diagram) return false;
+
+  const next = op(diagram);
+  if (next === diagram) return false;
+  const rendered = renderAsciiDiagram(next);
+
+  // Verify before committing: the rendered art must re-parse to the same
+  // node count, or we'd write art the canvas can't read back.
+  const verification = parseAsciiDiagram(rendered);
+  if (verification.nodes.length !== next.nodes.length) return false;
+
+  // Promote the fence language to the explicit `diagram` tag so this block's
+  // identity survives a later flatten → markdown → re-import round-trip.
+  return replaceAsciiFenceText(editor, pos, rendered, 'diagram');
+}
+
+/** Full pipeline for a canvas command against a registered fence block. */
+export function applyAsciiDiagramCommand(
+  editor: Editor,
+  blockId: string,
+  cmd: DiagramCommand,
+): boolean {
+  switch (cmd.kind) {
+    case 'moveNode': {
+      const { col, row } = canvasToAsciiCell(cmd.x, cmd.y);
+      return applyOp(editor, blockId, (d) => moveNodeOp(d, cmd.nodeId, col, row));
+    }
+    case 'resizeNode': {
+      const wCols = Math.max(3, Math.round(cmd.width / ASCII_CHAR_W));
+      const hRows = Math.max(3, Math.round(cmd.height / ASCII_CHAR_H));
+      return applyOp(editor, blockId, (d) => resizeNodeOp(d, cmd.nodeId, wCols, hRows));
+    }
+    case 'addConnection':
+      return applyOp(editor, blockId, (d) => addEdgeOp(d, cmd.source, cmd.target, cmd.type));
+    case 'removeConnection':
+      return applyOp(editor, blockId, (d) => removeEdgeOp(d, cmd.source, cmd.target, cmd.type));
+    case 'renameNode':
+      return applyOp(editor, blockId, (d) => renameNodeOp(d, cmd.nodeId, cmd.newLabel));
+    case 'addNode': {
+      const { col, row } = canvasToAsciiCell(cmd.x, cmd.y);
+      return applyOp(editor, blockId, (d) => addNodeOp(d, { col, row }).diagram);
+    }
+    case 'removeNode':
+      return applyOp(editor, blockId, (d) => removeNodeOp(d, cmd.nodeId));
+  }
+  const _exhaustive: never = cmd;
+  void _exhaustive;
+  return false;
+}