@bendyline/squisq 1.5.1 → 2.0.0

package/src/__tests__/asciiDiagramParse.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from 'vitest';
+import { parseAsciiDiagram } from '../doc/asciiDiagram/index.js';
+import {
+  BIDIRECTIONAL,
+  CONTAINER_EMBEDDED_TITLE,
+  DUPLICATE_LABELS,
+  EDGE_LABEL,
+  EDGE_LABEL_SPACED,
+  FAN_OUT_BUS,
+  FAN_OUT_COLUMNS,
+  MULTILINE_LABELS,
+  NESTED_CONTAINER,
+  PARALLEL_DUPES,
+  ROUNDED_AND_DOUBLE,
+  SECTIONED_CARD,
+  SINGLE_BOX,
+  STACKED_SHARED_BORDER_ASCII,
+  TWO_BOX_HORIZONTAL_ASCII,
+  TWO_BOX_HORIZONTAL_UNICODE,
+  TWO_BOX_VERTICAL,
+  TWO_BOX_VERTICAL_ASCII,
+  UNDIRECTED,
+} from './fixtures/asciiDiagrams.js';
+
+describe('parseAsciiDiagram — boxes and labels', () => {
+  it('parses two unicode boxes with a vertical arrow', () => {
+    const d = parseAsciiDiagram(TWO_BOX_VERTICAL);
+    expect(d.nodes.map((n) => n.id)).toEqual(['alpha', 'beta']);
+    expect(d.nodes[0].label).toBe('Alpha');
+    expect(d.style).toBe('unicode');
+    expect(d.edges).toEqual([{ source: 'alpha', target: 'beta', directed: true }]);
+  });
+
+  it('parses the identical ASCII art with the same semantics', () => {
+    const d = parseAsciiDiagram(TWO_BOX_VERTICAL_ASCII);
+    expect(d.nodes.map((n) => n.id)).toEqual(['alpha', 'beta']);
+    expect(d.style).toBe('ascii');
+    expect(d.edges).toEqual([{ source: 'alpha', target: 'beta', directed: true }]);
+  });
+
+  it('records grid geometry (col/row/wCols/hRows)', () => {
+    const d = parseAsciiDiagram(TWO_BOX_VERTICAL);
+    expect(d.nodes[0]).toMatchObject({ col: 0, row: 0, wCols: 10, hRows: 3 });
+    expect(d.nodes[1]).toMatchObject({ col: 0, row: 5, wCols: 10, hRows: 3 });
+  });
+
+  it('keeps multi-line labels verbatim (trimmed, newline-joined)', () => {
+    const d = parseAsciiDiagram(MULTILINE_LABELS);
+    const kernel = d.nodes.find((n) => n.id === 'molen-kernel');
+    expect(kernel?.label).toBe('molen-kernel\nheadless sim\nno DOM');
+  });
+
+  it('splits ├──┤ sectioned cards into stacked sibling nodes', () => {
+    const d = parseAsciiDiagram(SECTIONED_CARD);
+    expect(d.nodes.map((n) => n.id)).toEqual(['header', 'body']);
+    expect(d.edges).toHaveLength(0);
+  });
+
+  it('parses ASCII stacked shared-border boxes as siblings, without overlap warnings', () => {
+    const d = parseAsciiDiagram(STACKED_SHARED_BORDER_ASCII);
+    expect(d.nodes.map((n) => n.id)).toEqual(['upper', 'lower']);
+    expect(d.nodes.every((n) => n.containerId === undefined)).toBe(true);
+    expect(d.warnings).not.toContain('overlapping-boxes');
+  });
+
+  it('deduplicates ids for repeated labels in reading order', () => {
+    const d = parseAsciiDiagram(DUPLICATE_LABELS);
+    expect(d.nodes.map((n) => n.id)).toEqual(['cache', 'cache-2']);
+    // Stable across re-parses of identical text.
+    expect(parseAsciiDiagram(DUPLICATE_LABELS).nodes.map((n) => n.id)).toEqual([
+      'cache',
+      'cache-2',
+    ]);
+  });
+
+  it('parses rounded and double-line corners', () => {
+    const d = parseAsciiDiagram(ROUNDED_AND_DOUBLE);
+    expect(d.nodes.map((n) => n.id)).toEqual(['round', 'double']);
+  });
+
+  it('parses a single box with no edges', () => {
+    const d = parseAsciiDiagram(SINGLE_BOX);
+    expect(d.nodes).toHaveLength(1);
+    expect(d.edges).toHaveLength(0);
+  });
+
+  it('never throws on garbage / empty input', () => {
+    expect(parseAsciiDiagram('').nodes).toHaveLength(0);
+    expect(parseAsciiDiagram('hello world').nodes).toHaveLength(0);
+    expect(parseAsciiDiagram('┌──\n│').nodes).toHaveLength(0);
+  });
+
+  it('handles CRLF and tab input', () => {
+    const crlf = TWO_BOX_VERTICAL.replace(/\n/g, '\r\n');
+    expect(parseAsciiDiagram(crlf).nodes.map((n) => n.id)).toEqual(['alpha', 'beta']);
+    const tabbed = `\t${SINGLE_BOX.split('\n').join('\n\t')}`;
+    const d = parseAsciiDiagram(tabbed);
+    expect(d.nodes).toHaveLength(1);
+    expect(d.warnings).toContain('tabs-expanded');
+  });
+
+  it('does not spawn phantom edges from label text containing | and -', () => {
+    const art = [
+      '┌─────────────┐     ┌─────────────┐',
+      '│ a | b - c   │     │ other box   │',
+      '└─────────────┘     └─────────────┘',
+    ].join('\n');
+    const d = parseAsciiDiagram(art);
+    expect(d.nodes).toHaveLength(2);
+    expect(d.edges).toHaveLength(0);
+  });
+});
+
+describe('parseAsciiDiagram — edges', () => {
+  it('parses --> as a directed horizontal edge', () => {
+    const d = parseAsciiDiagram(TWO_BOX_HORIZONTAL_ASCII);
+    expect(d.edges).toEqual([{ source: 'input', target: 'output', directed: true }]);
+  });
+
+  it('parses ────► as a directed horizontal edge', () => {
+    const d = parseAsciiDiagram(TWO_BOX_HORIZONTAL_UNICODE);
+    expect(d.edges).toEqual([{ source: 'input', target: 'output', directed: true }]);
+  });
+
+  it('parses a plain line as undirected with topmost-leftmost source', () => {
+    const d = parseAsciiDiagram(UNDIRECTED);
+    expect(d.edges).toEqual([{ source: 'left', target: 'right', directed: false }]);
+  });
+
+  it('parses ◄──► as two directed edges', () => {
+    const d = parseAsciiDiagram(BIDIRECTIONAL);
+    expect(d.edges).toEqual([
+      { source: 'peer', target: 'peer-2', directed: true },
+      { source: 'peer-2', target: 'peer', directed: true },
+    ]);
+  });
+
+  it('parses separate arrow columns from one wide box as distinct edges', () => {
+    const d = parseAsciiDiagram(FAN_OUT_COLUMNS);
+    expect(d.edges).toEqual([
+      { source: 'source', target: 'one', directed: true },
+      { source: 'source', target: 'two', directed: true },
+    ]);
+  });
+
+  it('parses a ┌──┴──┐ bus split as a fan-out from the junction-attached box', () => {
+    const d = parseAsciiDiagram(FAN_OUT_BUS);
+    expect(d.edges).toEqual([
+      { source: 'source', target: 'one', directed: true },
+      { source: 'source', target: 'two', directed: true },
+    ]);
+  });
+
+  it('dedupes parallel identical lines to one edge with a warning', () => {
+    const d = parseAsciiDiagram(PARALLEL_DUPES);
+    expect(d.edges).toEqual([{ source: 'wide-a', target: 'wide-b', directed: true }]);
+    expect(d.warnings).toContain('parallel-edges-merged');
+  });
+
+  it('captures an embedded horizontal edge label', () => {
+    const d = parseAsciiDiagram(EDGE_LABEL);
+    expect(d.edges).toEqual([
+      { source: 'client', target: 'server', label: 'auth', directed: true },
+    ]);
+  });
+
+  it('captures an embedded label with internal spaces', () => {
+    const d = parseAsciiDiagram(EDGE_LABEL_SPACED);
+    expect(d.edges).toEqual([
+      { source: 'client', target: 'server', label: 'auth flow', directed: true },
+    ]);
+  });
+});
+
+describe('parseAsciiDiagram — containers', () => {
+  it('parses the nested AI-style container fixture', () => {
+    const d = parseAsciiDiagram(NESTED_CONTAINER);
+    const container = d.nodes.find((n) => n.id === 'data-pipeline');
+    expect(container).toBeDefined();
+    expect(container?.containerId).toBeUndefined();
+    const children = d.nodes.filter((n) => n.containerId === 'data-pipeline');
+    expect(children.map((n) => n.id).sort()).toEqual([
+      'enrich',
+      'export',
+      'gold',
+      'ingest',
+      'raw',
+      'silver',
+    ]);
+    expect(d.edges).toEqual([
+      { source: 'enrich', target: 'silver', directed: true },
+      { source: 'export', target: 'gold', directed: true },
+      { source: 'ingest', target: 'raw', directed: true },
+    ]);
+  });
+
+  it('reads a title embedded in the container top border', () => {
+    const d = parseAsciiDiagram(CONTAINER_EMBEDDED_TITLE);
+    const container = d.nodes.find((n) => n.id === 'cluster');
+    expect(container?.label).toBe('Cluster');
+    const worker = d.nodes.find((n) => n.id === 'worker');
+    expect(worker?.containerId).toBe('cluster');
+  });
+});
+
+describe('parseAsciiDiagram — hand-drawn robustness', () => {
+  it('treats an arrowhead embedded in the top border as a stem, not a title', () => {
+    // An incoming edge often lands in the border (`┌───▼───┐`). The arrowhead
+    // must not be captured as the box label, and the box must still close.
+    const art = ['┌───▼───┐', '│ Alpha │', '└───────┘', '┌───────┐', '│ Beta  │', '└───────┘'].join(
+      '\n',
+    );
+    const d = parseAsciiDiagram(art);
+    expect(d.nodes.map((n) => n.label.split('\n')[0])).toEqual(['Alpha', 'Beta']);
+  });
+
+  it('traces a box whose side border overflowed on one interior row', () => {
+    // A label wider than its box leaves a gap where the `│` should be. The
+    // four corners + solid top/bottom borders still anchor the box.
+    const art = [
+      '┌──────────┐',
+      '│ Alpha    │',
+      '│ a wide overflowing note',
+      '│ tail     │',
+      '└──────────┘',
+      '┌──────────┐',
+      '│ Beta     │',
+      '└──────────┘',
+    ].join('\n');
+    const d = parseAsciiDiagram(art);
+    expect(d.nodes.map((n) => n.label.split('\n')[0])).toEqual(['Alpha', 'Beta']);
+  });
+});

package/src/__tests__/asciiDiagramPipeline.test.ts

@@ -0,0 +1,273 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown, stringifyMarkdown } from '../markdown/index';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { docToMarkdown } from '../doc/docToMarkdown';
+import { materializeLayers } from './materializeTestUtils';
+import { profileBlockContents, recommendTemplatesForBlock } from '../recommend/templates';
+import type { Block, Layer } from '../schemas/Doc';
+import type { DiagramTemplateEdge, DiagramTemplateNode } from '../schemas/BlockTemplates';
+import { NESTED_CONTAINER, TWO_BOX_VERTICAL } from './fixtures/asciiDiagrams';
+
+const fenced = (art: string, lang = ''): string => '```' + lang + '\n' + art + '\n```';
+
+const AUTO_DOC = ['# Systems', '', '## Architecture', '', fenced(TWO_BOX_VERTICAL), ''].join('\n');
+
+function convert(md: string, options?: Parameters<typeof markdownToDoc>[1]) {
+  return markdownToDoc(parseMarkdown(md), { generateCoverBlock: false, ...options });
+}
+
+function findBlock(doc: { blocks: Block[] }, title: string): Block | undefined {
+  const walk = (blocks: Block[]): Block | undefined => {
+    for (const b of blocks) {
+      if (b.title === title) return b;
+      const inner = b.children ? walk(b.children) : undefined;
+      if (inner) return inner;
+    }
+    return undefined;
+  };
+  return walk(doc.blocks);
+}
+
+describe('auto-template conversion of ASCII diagram fences', () => {
+  it('converts a heading with a lone eligible fence into an ephemeral diagram block', () => {
+    const doc = convert(AUTO_DOC);
+    const block = findBlock(doc, 'Architecture');
+    expect(block?.template).toBe('diagram');
+    expect(block?.autoTemplate).toBe(true);
+    const nodes = block?.templateData?.nodes as DiagramTemplateNode[];
+    const edges = block?.templateData?.edges as DiagramTemplateEdge[];
+    expect(nodes?.map((n) => n.id)).toEqual(['alpha', 'beta']);
+    expect(nodes?.[0].w).toBeGreaterThan(0);
+    expect(edges).toEqual([
+      {
+        source: 'alpha',
+        target: 'beta',
+        sourceAnchor: { side: 'bottom', offset: 0.5 },
+        targetAnchor: { side: 'top', offset: 0.5 },
+        routing: 'orthogonal',
+      },
+    ]);
+    expect(block?.templateData?.title).toBe('Architecture');
+  });
+
+  it('round-trips losslessly: fence byte-identical, no annotation injected', () => {
+    const doc = convert(AUTO_DOC);
+    const output = stringifyMarkdown(docToMarkdown(doc));
+    expect(output).toContain(TWO_BOX_VERTICAL);
+    expect(output).not.toContain('{[diagram');
+  });
+
+  it('respects the autoTemplates option kill switch', () => {
+    const doc = convert(AUTO_DOC, { autoTemplates: false });
+    const block = findBlock(doc, 'Architecture');
+    expect(block?.template).not.toBe('diagram');
+  });
+
+  it('respects the squisq-auto-templates frontmatter kill switch', () => {
+    const md = `---\nsquisq-auto-templates: false\n---\n\n${AUTO_DOC}`;
+    const doc = convert(md);
+    const block = findBlock(doc, 'Architecture');
+    expect(block?.template).not.toBe('diagram');
+  });
+
+  it('does not convert when the fence has a real language', () => {
+    const md = ['## Architecture', '', fenced(TWO_BOX_VERTICAL, 'js'), ''].join('\n');
+    const block = findBlock(convert(md), 'Architecture');
+    expect(block?.template).not.toBe('diagram');
+  });
+
+  it('does not convert when a table competes with the fence', () => {
+    const md = [
+      '## Architecture',
+      '',
+      '| a | b |',
+      '|---|---|',
+      '| 1 | 2 |',
+      '',
+      fenced(TWO_BOX_VERTICAL),
+      '',
+    ].join('\n');
+    const block = findBlock(convert(md), 'Architecture');
+    expect(block?.template).not.toBe('diagram');
+  });
+
+  it('does not convert when two fences are present', () => {
+    const md = ['## Architecture', '', fenced(TWO_BOX_VERTICAL), '', fenced('plain code'), ''].join(
+      '\n',
+    );
+    const block = findBlock(convert(md), 'Architecture');
+    expect(block?.template).not.toBe('diagram');
+  });
+
+  it('does not convert when heavy prose surrounds the fence', () => {
+    const prose = 'Lots of surrounding explanation text. '.repeat(15);
+    const md = ['## Architecture', '', prose, '', fenced(TWO_BOX_VERTICAL), ''].join('\n');
+    const block = findBlock(convert(md), 'Architecture');
+    expect(block?.template).not.toBe('diagram');
+  });
+});
+
+describe('explicit `diagram`-tagged fence (survives edit → round-trip)', () => {
+  // The `diagram` fence LANGUAGE is the durable "block tag" — it round-trips
+  // through markdown ↔ Tiptap as `class="language-diagram"`, and explicit-lang
+  // detection accepts a degenerate single-box diagram that would otherwise be
+  // rejected (the ≥2-box floor is for UNTAGGED auto-detection only).
+  const ONE_BOX = ['┌────────┐', '│ Solo   │', '└────────┘'].join('\n');
+  const TAGGED_DOC = ['# Systems', '', '## Architecture', '', fenced(ONE_BOX, 'diagram'), ''].join(
+    '\n',
+  );
+
+  it('a bare single-box fence does NOT become a diagram', () => {
+    const md = ['## Architecture', '', fenced(ONE_BOX), ''].join('\n');
+    expect(findBlock(convert(md), 'Architecture')?.template).not.toBe('diagram');
+  });
+
+  it('a `diagram`-tagged single-box fence DOES become a diagram', () => {
+    const block = findBlock(convert(TAGGED_DOC), 'Architecture');
+    expect(block?.template).toBe('diagram');
+    expect(block?.autoTemplate).toBe(true);
+    const nodes = block?.templateData?.nodes as DiagramTemplateNode[];
+    expect(nodes?.map((n) => n.id)).toEqual(['solo']);
+  });
+
+  it('round-trips losslessly: fence + `diagram` lang preserved, no annotation injected', () => {
+    const output = stringifyMarkdown(docToMarkdown(convert(TAGGED_DOC)));
+    expect(output).toContain('```diagram');
+    expect(output).toContain(ONE_BOX);
+    expect(output).not.toContain('{[diagram');
+    // Re-importing keeps it a diagram — the identity is sticky.
+    expect(findBlock(convert(output), 'Architecture')?.template).toBe('diagram');
+  });
+
+  it('profiles a `diagram`-tagged single-box fence as hasAsciiDiagram', () => {
+    const md = parseMarkdown(fenced(ONE_BOX, 'diagram'));
+    const profile = profileBlockContents(md.children as Parameters<typeof profileBlockContents>[0]);
+    expect(profile.hasAsciiDiagram).toBe(true);
+  });
+});
+
+describe('explicit {[diagram]} annotation with an ASCII fence', () => {
+  const EXPLICIT_DOC = ['## Flow {[diagram]}', '', fenced(TWO_BOX_VERTICAL), ''].join('\n');
+
+  it('derives nodes/edges even with autoTemplates off', () => {
+    const doc = convert(EXPLICIT_DOC, { autoTemplates: false });
+    const block = findBlock(doc, 'Flow');
+    expect(block?.template).toBe('diagram');
+    const nodes = block?.templateData?.nodes as DiagramTemplateNode[];
+    expect(nodes?.map((n) => n.id)).toEqual(['alpha', 'beta']);
+  });
+
+  it('keeps the explicit annotation and fence through a round-trip', () => {
+    const doc = convert(EXPLICIT_DOC);
+    const output = stringifyMarkdown(docToMarkdown(doc));
+    expect(output).toContain('{[diagram]}');
+    expect(output).toContain(TWO_BOX_VERTICAL);
+  });
+
+  it('lets an author json data fence win over the ASCII fence', () => {
+    const md = [
+      '## Flow {[diagram]}',
+      '',
+      '```json data',
+      JSON.stringify({
+        nodes: [
+          { id: 'only', label: 'Only', x: 0, y: 0 },
+          { id: 'two', label: 'Two', x: 200, y: 0 },
+        ],
+        edges: [],
+      }),
+      '```',
+      '',
+    ].join('\n');
+    const doc = convert(md);
+    const block = findBlock(doc, 'Flow');
+    const nodes = block?.templateData?.nodes as DiagramTemplateNode[];
+    expect(nodes?.map((n) => n.id)).toEqual(['only', 'two']);
+  });
+
+  it('records a diagnostic when the fence does not parse as a diagram', () => {
+    const md = ['## Flow {[diagram]}', '', fenced('just some text\nnothing else\nhere'), ''].join(
+      '\n',
+    );
+    const doc = convert(md);
+    expect(doc.diagnostics?.some((d) => d.code === 'ascii-diagram-parse')).toBe(true);
+  });
+
+  it('children-driven diagrams win over a stray fence in the body', () => {
+    const md = [
+      '## Flow {[diagram]}',
+      '',
+      fenced(TWO_BOX_VERTICAL),
+      '',
+      '### NodeA {#node-a x=100 y=100}',
+      '',
+      '### NodeB {#node-b x=400 y=100 connectsTo=node-a}',
+      '',
+    ].join('\n');
+    const doc = convert(md);
+    const block = findBlock(doc, 'Flow');
+    expect(block?.children?.length).toBe(2);
+    expect(block?.templateData?.nodes).toBeUndefined();
+  });
+});
+
+describe('rendering derived diagrams through materializeBlockLayers', () => {
+  it('renders container cards behind leaf cards with per-node sizes', () => {
+    const md = ['## Pipeline', '', fenced(NESTED_CONTAINER), ''].join('\n');
+    const doc = convert(md);
+    const block = findBlock(doc, 'Pipeline');
+    expect(block?.template).toBe('diagram');
+    const layers = materializeLayers(block as Block, {});
+    const ids = layers.map((l: Layer) => l.id);
+    // Container card present and drawn before (behind) leaf cards.
+    const containerIdx = ids.indexOf('node-card-data-pipeline');
+    const leafIdx = ids.indexOf('node-card-ingest');
+    expect(containerIdx).toBeGreaterThanOrEqual(0);
+    expect(leafIdx).toBeGreaterThan(containerIdx);
+    // Edges exist.
+    expect(ids.some((id) => id.startsWith('edge-'))).toBe(true);
+  });
+
+  it('renders undirected edges without an end marker', () => {
+    const art = [
+      '┌────────┐     ┌────────┐',
+      '│ Left   │─────│ Right  │',
+      '└────────┘     └────────┘',
+    ].join('\n');
+    const md = ['## Pair', '', fenced(art), ''].join('\n');
+    const block = findBlock(convert(md), 'Pair');
+    const layers = materializeLayers(block as Block, {});
+    const edge = layers.find((l: Layer) => l.id.startsWith('edge-'));
+    expect(edge).toBeDefined();
+    expect((edge as { content: { endMarker?: string } }).content.endMarker).toBeUndefined();
+  });
+});
+
+describe('duration/caption hygiene', () => {
+  it('excludes a consumed fence from reading-time and captions', () => {
+    // The size of the consumed art must not affect the block's duration:
+    // a tiny diagram and a huge one read identically (the fence text is
+    // data, not narration).
+    const small = findBlock(convert(AUTO_DOC), 'Architecture');
+    const bigDoc = convert(
+      ['# Systems', '', '## Architecture', '', fenced(NESTED_CONTAINER), ''].join('\n'),
+    );
+    const big = findBlock(bigDoc, 'Architecture');
+    expect(small?.template).toBe('diagram');
+    expect(big?.template).toBe('diagram');
+    expect(big?.duration).toBe(small?.duration);
+    const captionText = (bigDoc.captions?.phrases ?? []).map((p) => p.text).join(' ');
+    expect(captionText).not.toContain('┌');
+    expect(captionText).not.toContain('│');
+  });
+});
+
+describe('template picker recommendation', () => {
+  it('surfaces diagram for a fence-bearing profile', () => {
+    const md = parseMarkdown(fenced(TWO_BOX_VERTICAL));
+    const profile = profileBlockContents(md.children as Parameters<typeof profileBlockContents>[0]);
+    expect(profile.hasAsciiDiagram).toBe(true);
+    const { recommended } = recommendTemplatesForBlock(profile, ['diagram', 'title', 'quote']);
+    expect(recommended).toContain('diagram');
+  });
+});

package/src/__tests__/asciiDiagramRender.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import {
+  asciiDiagramFromTemplateData,
+  asciiDiagramToTemplateData,
+  parseAsciiDiagram,
+  renderAsciiDiagram,
+  type AsciiDiagram,
+} from '../doc/asciiDiagram/index.js';
+import { POSITIVE_FIXTURES } from './fixtures/asciiDiagrams.js';
+
+/** Semantic equality: node ids/labels/containment + edge tuple sets. */
+function semanticSnapshot(d: AsciiDiagram): {
+  nodes: Array<{ id: string; label: string; containerId?: string }>;
+  edges: Array<{ source: string; target: string; label?: string; directed: boolean }>;
+} {
+  return {
+    nodes: [...d.nodes]
+      .map((n) => ({
+        id: n.id,
+        label: n.label,
+        ...(n.containerId ? { containerId: n.containerId } : {}),
+      }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+    edges: [...d.edges]
+      .map((e) => ({
+        source: e.source,
+        target: e.target,
+        ...(e.label ? { label: e.label } : {}),
+        directed: e.directed,
+      }))
+      .sort(
+        (a, b) =>
+          a.source.localeCompare(b.source) ||
+          a.target.localeCompare(b.target) ||
+          (a.label ?? '').localeCompare(b.label ?? ''),
+      ),
+  };
+}
+
+describe('renderAsciiDiagram — output shape', () => {
+  it('renders a simple two-node diagram with box borders and an arrow', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL);
+    const art = renderAsciiDiagram(d);
+    expect(art).toContain('┌');
+    expect(art).toContain('Alpha');
+    expect(art).toContain('Beta');
+    expect(art).toContain('▼');
+    expect(art).toContain('┬'); // junction on the source's bottom border
+    expect(art).toContain('┴'); // junction on the target's top border
+  });
+
+  it('emits ASCII vocabulary for ascii-style diagrams', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL_ASCII);
+    const art = renderAsciiDiagram(d);
+    expect(art).toContain('+--');
+    expect(art).toContain('v');
+    expect(art).not.toMatch(/[┌─│▼]/u);
+  });
+
+  it('honours a style override', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL);
+    const art = renderAsciiDiagram(d, { style: 'ascii' });
+    expect(art).not.toMatch(/[┌─│▼]/u);
+  });
+
+  it('grows a box when its label no longer fits', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL);
+    d.nodes[0] = { ...d.nodes[0], label: 'A much longer label than before' };
+    const art = renderAsciiDiagram(d);
+    expect(art).toContain('A much longer label than before');
+    const reparsed = parseAsciiDiagram(art);
+    expect(reparsed.nodes.map((n) => n.label)).toContain('A much longer label than before');
+  });
+
+  it('never shrinks a parsed box (visual stability)', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL);
+    const art = renderAsciiDiagram(d);
+    const reparsed = parseAsciiDiagram(art);
+    for (const node of reparsed.nodes) {
+      const original = d.nodes.find((n) => n.id === node.id);
+      expect(node.wCols).toBeGreaterThanOrEqual(original?.wCols ?? 0);
+      expect(node.hRows).toBeGreaterThanOrEqual(original?.hRows ?? 0);
+    }
+  });
+
+  it('renders containers with an embedded top-border title around their children', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.NESTED_CONTAINER);
+    const art = renderAsciiDiagram(d);
+    expect(art).toContain(' Data Pipeline ');
+    const reparsed = parseAsciiDiagram(art);
+    const children = reparsed.nodes.filter((n) => n.containerId === 'data-pipeline');
+    expect(children).toHaveLength(6);
+  });
+
+  it('merges a reciprocal directed pair into one double-arrow line', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.BIDIRECTIONAL);
+    const art = renderAsciiDiagram(d);
+    expect(art).toContain('◄');
+    expect(art).toContain('►');
+    // One line, not two.
+    const arrowRows = art.split('\n').filter((l) => l.includes('◄') || l.includes('►'));
+    expect(arrowRows).toHaveLength(1);
+  });
+
+  it('writes edge labels into a horizontal segment', () => {
+    const d = parseAsciiDiagram(POSITIVE_FIXTURES.EDGE_LABEL);
+    const art = renderAsciiDiagram(d);
+    expect(art).toContain(' auth ');
+  });
+
+  it('returns empty output for an empty diagram', () => {
+    expect(renderAsciiDiagram({ nodes: [], edges: [], style: 'unicode', warnings: [] })).toBe('');
+  });
+});
+
+describe('renderAsciiDiagram ↔ parseAsciiDiagram fixpoint', () => {
+  for (const [name, fixture] of Object.entries(POSITIVE_FIXTURES)) {
+    it(`semantic fixpoint + byte idempotence: ${name}`, () => {
+      const d1 = parseAsciiDiagram(fixture);
+      const t1 = renderAsciiDiagram(d1);
+      const d2 = parseAsciiDiagram(t1);
+      expect(semanticSnapshot(d2)).toEqual(semanticSnapshot(d1));
+      const t2 = renderAsciiDiagram(d2);
+      expect(t2).toBe(t1);
+      // Three full cycles stay byte-stable.
+      const d3 = parseAsciiDiagram(t2);
+      const t3 = renderAsciiDiagram(d3);
+      expect(t3).toBe(t1);
+    });
+  }
+
+  it('anti-churn: nudging one node by one column only changes locally', () => {
+    const d1 = parseAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL);
+    const t1 = renderAsciiDiagram(d1);
+    const d2 = parseAsciiDiagram(t1);
+    d2.nodes[1] = { ...d2.nodes[1], col: d2.nodes[1].col + 1 };
+    const t2 = renderAsciiDiagram(d2);
+    const d3 = parseAsciiDiagram(t2);
+    expect(semanticSnapshot(d3)).toEqual(semanticSnapshot(d1));
+    // Byte-stable after the nudge normalizes.
+    expect(renderAsciiDiagram(d3)).toBe(t2);
+  });
+});
+
+describe('templateData mapping round-trip', () => {
+  for (const [name, fixture] of Object.entries(POSITIVE_FIXTURES)) {
+    it(`grid → canvas → grid preserves semantics: ${name}`, () => {
+      const d1 = parseAsciiDiagram(fixture);
+      const { nodes, edges } = asciiDiagramToTemplateData(d1);
+      const d2 = asciiDiagramFromTemplateData(nodes, edges, { style: d1.style });
+      expect(semanticSnapshot(d2)).toEqual(semanticSnapshot(d1));
+      // Positions survive exactly (the mapping is scale + round).
+      for (const node of d2.nodes) {
+        const original = d1.nodes.find((n) => n.id === node.id);
+        expect({ col: node.col, row: node.row }).toEqual({
+          col: original?.col,
+          row: original?.row,
+        });
+      }
+    });
+  }
+});