@bendyline/squisq 1.5.2 → 2.0.0

package/src/__tests__/treeviewBattle.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import {
+  detectTree,
+  parseTree,
+  renderTree,
+  treeFromTemplateData,
+  treeToTemplateData,
+  type Tree,
+} from '../doc/treeview/index.js';
+import { TREE_FIXTURES } from './fixtures/treeviewFixtures.js';
+
+/**
+ * Battle test: a broad corpus of AI-style trees (project scaffolds,
+ * monorepos, dependency trees, category/decision outlines, forests) each
+ * asserting detect + parse-accuracy + fixpoint + byte-stability + mapping
+ * round-trip. Peer to asciiDiagramBattle.test.ts.
+ */
+
+function flat(t: Tree): string[] {
+  const out: string[] = [];
+  const walk = (nodes: Tree['roots'], depth: number): void => {
+    for (const n of nodes) {
+      out.push(`${depth}:${n.label}${n.comment ? ` #${n.comment}` : ''}`);
+      walk(n.children, depth + 1);
+    }
+  };
+  walk(t.roots, 0);
+  return out;
+}
+
+describe('tree battle — every fixture', () => {
+  for (const fx of TREE_FIXTURES) {
+    describe(`${fx.category}: ${fx.name}`, () => {
+      const t = parseTree(fx.art);
+
+      it('detects as a tree', () => {
+        expect(detectTree(fx.art).isTree).toBe(true);
+      });
+
+      it('parses the intended hierarchy', () => {
+        expect(flat(t)).toEqual(fx.expect);
+      });
+
+      it('render→parse preserves the semantic (fixpoint)', () => {
+        expect(flat(parseTree(renderTree(t)))).toEqual(flat(t));
+      });
+
+      it('render→parse→render is byte-stable across three cycles', () => {
+        const t1 = renderTree(t);
+        const t2 = renderTree(parseTree(t1));
+        const t3 = renderTree(parseTree(t2));
+        expect(t2).toBe(t1);
+        expect(t3).toBe(t1);
+      });
+
+      it('templateData round-trips', () => {
+        const back = treeFromTemplateData(treeToTemplateData(t).items, { style: t.style });
+        expect(flat(back)).toEqual(flat(t));
+      });
+    });
+  }
+});
+
+describe('tree battle — coverage sanity', () => {
+  it('covers every intended category', () => {
+    const categories = new Set(TREE_FIXTURES.map((f) => f.category));
+    for (const c of ['scaffold', 'style', 'comments', 'outline', 'shape']) {
+      expect(categories.has(c)).toBe(true);
+    }
+  });
+
+  it('fixture names are unique', () => {
+    const names = TREE_FIXTURES.map((f) => f.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});

package/src/__tests__/treeviewDetect.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import {
+  detectTree,
+  isTreeFence,
+  isEligibleTreeFenceLang,
+  isExplicitTreeLang,
+} from '../doc/treeview/index.js';
+import { detectAsciiDiagram, isAsciiDiagramFence } from '../doc/asciiDiagram/index.js';
+import type { MarkdownCodeBlock } from '../markdown/types.js';
+import { TREE_FIXTURES } from './fixtures/treeviewFixtures.js';
+
+const NEGATIVES: Record<string, string> = {
+  boxDiagram: [
+    '┌────────┐',
+    '│ Alpha  │',
+    '└───┬────┘',
+    '    │',
+    '    ▼',
+    '┌────────┐',
+    '│ Beta   │',
+    '└────────┘',
+  ].join('\n'),
+  // A hand-drawn box diagram whose right borders are misaligned (e.g. a
+  // rename widened the labels), so NO box traces as a closed rectangle. It
+  // must still be rejected as a tree — the top corners (┌ ┐) give it away.
+  misalignedBoxDiagram: [
+    '┌─────────────────┐',
+    '│  @scope/tooling      │',
+    '│  CLI + MCP server │',
+    '└───────┬─────────┘',
+    '        │',
+    '        ▼',
+    '┌───────┴──┐   ┌──────────┐',
+    '│  kernel  │   │  client  │',
+    '└──────────┘   └──────────┘',
+  ].join('\n'),
+  markdownTable: ['| Name  | Role     |', '|-------|----------|', '| Ada   | Engineer |'].join(
+    '\n',
+  ),
+  prose: [
+    'This is a paragraph of ordinary text.',
+    'It has multiple lines but no tree structure at all.',
+    'Nothing here should look like a hierarchy.',
+  ].join('\n'),
+  indentedCode: [
+    'function foo() {',
+    '  const x = 1;',
+    '  if (x) {',
+    '    return x;',
+    '  }',
+    '}',
+  ].join('\n'),
+  yaml: ['services:', '  web:', '    image: nginx', '    ports:', '      - "80:80"'].join('\n'),
+  singleLine: 'just one line',
+};
+
+describe('detectTree — negative corpus (must all reject)', () => {
+  for (const [name, art] of Object.entries(NEGATIVES)) {
+    it(`rejects ${name}`, () => {
+      const d = detectTree(art);
+      expect(d.isTree).toBe(false);
+      expect(d.reasons.length).toBeGreaterThan(0);
+    });
+  }
+
+  it('rejects a misaligned box diagram via the corner signal, not the box count', () => {
+    // No box traces closed (misaligned), so the ≥2-box rule can't catch it —
+    // the corner rejector is what keeps it out of the tree widget.
+    const d = detectTree(NEGATIVES.misalignedBoxDiagram);
+    expect(d.isTree).toBe(false);
+    expect(d.reasons).toContain('has-box-corners');
+  });
+
+  it('rejects box-corner art even when explicitly `tree`-tagged', () => {
+    expect(detectTree(NEGATIVES.misalignedBoxDiagram, { explicit: true }).isTree).toBe(false);
+    expect(detectTree(NEGATIVES.boxDiagram, { explicit: true }).isTree).toBe(false);
+  });
+});
+
+describe('detectTree — positive fixtures (must all accept)', () => {
+  for (const fx of TREE_FIXTURES) {
+    it(`accepts ${fx.name}`, () => {
+      const d = detectTree(fx.art);
+      expect(d.isTree).toBe(true);
+      expect(d.tree).toBeDefined();
+    });
+  }
+});
+
+describe('mutual exclusion with the diagram codec', () => {
+  it('a box diagram is a diagram, not a tree', () => {
+    expect(detectAsciiDiagram(NEGATIVES.boxDiagram).isDiagram).toBe(true);
+    expect(detectTree(NEGATIVES.boxDiagram).isTree).toBe(false);
+  });
+
+  it('every tree fixture is a tree, not a diagram', () => {
+    for (const fx of TREE_FIXTURES) {
+      expect(detectTree(fx.art).isTree).toBe(true);
+      expect(detectAsciiDiagram(fx.art).isDiagram).toBe(false);
+    }
+  });
+});
+
+describe('explicit `tree` tag (lenient detection)', () => {
+  const FLAT = ['README.md', 'index.ts', 'package.json'].join('\n');
+  const SINGLE = 'src/';
+
+  it('isExplicitTreeLang matches only the `tree` tag', () => {
+    for (const lang of ['tree', ' Tree ', 'TREE']) expect(isExplicitTreeLang(lang)).toBe(true);
+    for (const lang of [undefined, null, '', 'text', 'ascii', 'diagram', 'js'])
+      expect(isExplicitTreeLang(lang)).toBe(false);
+  });
+
+  it('a flat connector-less list is rejected untagged but accepted when explicit', () => {
+    // The exact bug the fence tag fixes: flattening a tree drops its
+    // connectors, so auto-detection rejects it on round-trip. The explicit
+    // `tree` tag trusts the author and keeps it a tree.
+    expect(detectTree(FLAT).isTree).toBe(false);
+    const explicit = detectTree(FLAT, { explicit: true });
+    expect(explicit.isTree).toBe(true);
+    expect(explicit.tree?.roots).toHaveLength(3);
+  });
+
+  it('a single-node tree is accepted when explicit', () => {
+    expect(detectTree(SINGLE).isTree).toBe(false);
+    expect(detectTree(SINGLE, { explicit: true }).isTree).toBe(true);
+  });
+
+  it('still rejects a box diagram even when explicitly tagged', () => {
+    expect(detectTree(NEGATIVES.boxDiagram, { explicit: true }).isTree).toBe(false);
+  });
+
+  it('still rejects a markdown table even when explicitly tagged', () => {
+    expect(detectTree(NEGATIVES.markdownTable, { explicit: true }).isTree).toBe(false);
+  });
+
+  it('isTreeFence accepts a flat `tree`-tagged fence via the lang gate', () => {
+    const fence: MarkdownCodeBlock = { type: 'code', lang: 'tree', value: FLAT };
+    expect(isTreeFence(fence)).toBe(true);
+    // The same content in a bare fence is not auto-detected.
+    expect(isTreeFence({ type: 'code', value: FLAT })).toBe(false);
+  });
+});
+
+describe('fence language gate', () => {
+  it('allows inert langs incl. tree; rejects real languages', () => {
+    for (const lang of [undefined, null, '', 'text', 'txt', 'plain', 'tree', 'ascii']) {
+      expect(isEligibleTreeFenceLang(lang)).toBe(true);
+    }
+    for (const lang of ['js', 'python', 'yaml', 'json', 'bash']) {
+      expect(isEligibleTreeFenceLang(lang)).toBe(false);
+    }
+  });
+
+  it('isTreeFence combines the lang gate with content detection', () => {
+    const art = TREE_FIXTURES[0].art;
+    const fence = (lang?: string): MarkdownCodeBlock => ({
+      type: 'code',
+      ...(lang !== undefined ? { lang } : {}),
+      value: art,
+    });
+    expect(isTreeFence(fence())).toBe(true);
+    expect(isTreeFence(fence('tree'))).toBe(true);
+    expect(isTreeFence(fence('js'))).toBe(false);
+    // And it is NOT an ascii-diagram fence.
+    expect(isAsciiDiagramFence(fence())).toBe(false);
+  });
+});

package/src/__tests__/treeviewParse.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { parseTree, type TreeNode } from '../doc/treeview/index.js';
+
+/** Flatten to "depth:label[ #comment]" lines, depth-first. */
+function flat(nodes: readonly TreeNode[], depth = 0, out: string[] = []): string[] {
+  for (const n of nodes) {
+    out.push(`${depth}:${n.label}${n.comment ? ` #${n.comment}` : ''}`);
+    flat(n.children, depth + 1, out);
+  }
+  return out;
+}
+
+describe('parseTree — renditions', () => {
+  it('parses a Unicode file tree', () => {
+    const art = [
+      'src/',
+      '├── index.ts',
+      '├── components/',
+      '│   ├── App.tsx',
+      '│   └── Button.tsx',
+      '└── utils/',
+      '    └── math.ts',
+    ].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual([
+      '0:src/',
+      '1:index.ts',
+      '1:components/',
+      '2:App.tsx',
+      '2:Button.tsx',
+      '1:utils/',
+      '2:math.ts',
+    ]);
+  });
+
+  it('parses ASCII `|-- ` / `` `-- `` style with identical semantics', () => {
+    const art = ['src/', '|-- a.ts', '|-- sub/', '|   `-- b.ts', '`-- c.ts'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:src/', '1:a.ts', '1:sub/', '2:b.ts', '1:c.ts']);
+    expect(parseTree(art).style).toBe('ascii');
+  });
+
+  it('parses `+-- ` style', () => {
+    const art = ['root', '+-- a', '|   +-- a1', '+-- b'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:root', '1:a', '2:a1', '1:b']);
+  });
+
+  it('parses pure 2-space indentation', () => {
+    const art = ['src/', '  a.ts', '  sub/', '    b.ts'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:src/', '1:a.ts', '1:sub/', '2:b.ts']);
+  });
+
+  it('parses 4-space indentation', () => {
+    const art = ['src/', '    a.ts', '    sub/', '        b.ts'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:src/', '1:a.ts', '1:sub/', '2:b.ts']);
+  });
+
+  it('parses bullet-indented lists', () => {
+    const art = ['- src/', '  - a.ts', '  - sub/', '    - b.ts'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:src/', '1:a.ts', '1:sub/', '2:b.ts']);
+  });
+
+  it('captures trailing comments (# and <--)', () => {
+    const art = ['p/', '├── a.ts   # first', '└── b.ts   <-- second'].join('\n');
+    const roots = parseTree(art).roots;
+    expect(flat(roots)).toEqual(['0:p/', '1:a.ts #first', '1:b.ts #second']);
+  });
+
+  it('marks directories (trailing slash or has children)', () => {
+    const art = ['top', '├── leaf.txt', '└── branch', '    └── deep.txt'].join('\n');
+    const roots = parseTree(art).roots;
+    expect(roots[0].isDir).toBe(true); // has children
+    const leaf = roots[0].children.find((n) => n.id === 'leaf-txt');
+    expect(leaf?.isDir).toBe(false);
+    const branch = roots[0].children.find((n) => n.id === 'branch');
+    expect(branch?.isDir).toBe(true); // has children
+  });
+
+  it('parses a forest (multiple roots)', () => {
+    const art = ['a/', '└── a1', 'b/', '└── b1'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:a/', '1:a1', '0:b/', '1:b1']);
+  });
+
+  it('assigns stable, deduplicated ids', () => {
+    const art = ['root/', '├── index.ts', '└── sub/', '    └── index.ts'].join('\n');
+    const roots = parseTree(art).roots;
+    const ids: string[] = [];
+    const walk = (ns: TreeNode[]) => ns.forEach((n) => (ids.push(n.id), walk(n.children)));
+    walk(roots);
+    expect(ids).toEqual(['root', 'index-ts', 'sub', 'index-ts-2']);
+    // Stable across re-parses.
+    const ids2: string[] = [];
+    const walk2 = (ns: TreeNode[]) => ns.forEach((n) => (ids2.push(n.id), walk2(n.children)));
+    walk2(parseTree(art).roots);
+    expect(ids2).toEqual(ids);
+  });
+
+  it('tolerates ragged dedents (clamp to nearest shallower level)', () => {
+    const art = ['a/', '    b/', '        c', '   d'].join('\n'); // d dedents to an in-between column
+    const roots = parseTree(art).roots;
+    // d clamps under a/ (the nearest shallower node).
+    expect(flat(roots)).toEqual(['0:a/', '1:b/', '2:c', '1:d']);
+  });
+
+  it('skips rails-only spacer lines', () => {
+    const art = ['a/', '├── b', '│', '└── c'].join('\n');
+    expect(flat(parseTree(art).roots)).toEqual(['0:a/', '1:b', '1:c']);
+  });
+
+  it('never throws on garbage / empty', () => {
+    expect(parseTree('').roots).toEqual([]);
+    expect(() => parseTree('|||\n---')).not.toThrow();
+    expect(parseTree('single line').roots.length).toBe(1);
+  });
+
+  it('handles CRLF input', () => {
+    const art = 'a/\r\n├── b\r\n└── c';
+    expect(flat(parseTree(art).roots)).toEqual(['0:a/', '1:b', '1:c']);
+  });
+});

package/src/__tests__/treeviewPipeline.test.ts

@@ -0,0 +1,183 @@
+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 { TreeTemplateItem } from '../schemas/BlockTemplates';
+
+const TREE_ART = ['src/', '├── index.ts', '├── components/', '│   └── App.tsx', '└── utils/'].join(
+  '\n',
+);
+const fenced = (art: string, lang = ''): string => '```' + lang + '\n' + art + '\n```';
+const AUTO_DOC = ['# Project', '', '## Layout', '', fenced(TREE_ART), ''].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 tree fences', () => {
+  it('converts a heading with a lone tree fence into an ephemeral tree block', () => {
+    const block = findBlock(convert(AUTO_DOC), 'Layout');
+    expect(block?.template).toBe('tree');
+    expect(block?.autoTemplate).toBe(true);
+    const items = block?.templateData?.items as TreeTemplateItem[];
+    expect(items?.map((i) => i.label)).toEqual(['src/']);
+    expect(items?.[0].children.map((c) => c.label)).toEqual(['index.ts', 'components/', 'utils/']);
+    expect(block?.templateData?.title).toBe('Layout');
+  });
+
+  it('round-trips losslessly: fence byte-identical, no annotation injected', () => {
+    const output = stringifyMarkdown(docToMarkdown(convert(AUTO_DOC)));
+    expect(output).toContain(TREE_ART);
+    expect(output).not.toContain('{[tree');
+  });
+
+  it('respects the autoTemplates kill switch', () => {
+    expect(findBlock(convert(AUTO_DOC, { autoTemplates: false }), 'Layout')?.template).not.toBe(
+      'tree',
+    );
+  });
+
+  it('respects the frontmatter kill switch', () => {
+    const md = `---\nsquisq-auto-templates: false\n---\n\n${AUTO_DOC}`;
+    expect(findBlock(convert(md), 'Layout')?.template).not.toBe('tree');
+  });
+
+  it('does not convert a real-language fence', () => {
+    const md = ['## Layout', '', fenced(TREE_ART, 'bash'), ''].join('\n');
+    expect(findBlock(convert(md), 'Layout')?.template).not.toBe('tree');
+  });
+
+  it('does not convert when a table competes with the fence', () => {
+    const md = [
+      '## Layout',
+      '',
+      '| a | b |',
+      '|---|---|',
+      '| 1 | 2 |',
+      '',
+      fenced(TREE_ART),
+      '',
+    ].join('\n');
+    expect(findBlock(convert(md), 'Layout')?.template).not.toBe('tree');
+  });
+
+  it('does not steal a box-diagram fence (mutual exclusion)', () => {
+    const diagram = [
+      '┌────────┐',
+      '│ Alpha  │',
+      '└───┬────┘',
+      '    ▼',
+      '┌────────┐',
+      '│ Beta   │',
+      '└────────┘',
+    ].join('\n');
+    const block = findBlock(convert(['## Arch', '', fenced(diagram), ''].join('\n')), 'Arch');
+    expect(block?.template).toBe('diagram');
+  });
+});
+
+describe('explicit `tree`-tagged fence (survives flatten → round-trip)', () => {
+  // A flattened tree loses its connector lines, so an untagged fence would no
+  // longer auto-detect. The `tree` fence LANGUAGE is the durable "block tag"
+  // (it round-trips through markdown ↔ Tiptap as `class="language-tree"`),
+  // and explicit-lang detection accepts the flat art.
+  const FLAT_ART = ['README.md', 'index.ts', 'package.json'].join('\n');
+  const FLAT_DOC = ['# Project', '', '## Files', '', fenced(FLAT_ART, 'tree'), ''].join('\n');
+
+  it('a bare flat fence does NOT become a tree', () => {
+    const md = ['## Files', '', fenced(FLAT_ART), ''].join('\n');
+    expect(findBlock(convert(md), 'Files')?.template).not.toBe('tree');
+  });
+
+  it('a `tree`-tagged flat fence DOES become a tree', () => {
+    const block = findBlock(convert(FLAT_DOC), 'Files');
+    expect(block?.template).toBe('tree');
+    expect(block?.autoTemplate).toBe(true);
+    const items = block?.templateData?.items as TreeTemplateItem[];
+    expect(items?.map((i) => i.label)).toEqual(['README.md', 'index.ts', 'package.json']);
+  });
+
+  it('round-trips losslessly: fence + `tree` lang preserved, no annotation injected', () => {
+    const output = stringifyMarkdown(docToMarkdown(convert(FLAT_DOC)));
+    expect(output).toContain('```tree');
+    expect(output).toContain(FLAT_ART);
+    expect(output).not.toContain('{[tree');
+    // Re-importing the output keeps it a tree — the identity is sticky.
+    expect(findBlock(convert(output), 'Files')?.template).toBe('tree');
+  });
+
+  it('profiles a `tree`-tagged flat fence as hasTree', () => {
+    const md = parseMarkdown(fenced(FLAT_ART, 'tree'));
+    const profile = profileBlockContents(md.children as Parameters<typeof profileBlockContents>[0]);
+    expect(profile.hasTree).toBe(true);
+  });
+});
+
+describe('explicit {[tree]} annotation', () => {
+  it('derives items even with autoTemplates off', () => {
+    const md = ['## Files {[tree]}', '', fenced(TREE_ART), ''].join('\n');
+    const block = findBlock(convert(md, { autoTemplates: false }), 'Files');
+    expect(block?.template).toBe('tree');
+    expect((block?.templateData?.items as TreeTemplateItem[])?.length).toBe(1);
+  });
+
+  it('converts a nested markdown list under an explicit annotation', () => {
+    const md = ['## Files {[tree]}', '', '- src/', '  - index.ts', '  - utils/', ''].join('\n');
+    const block = findBlock(convert(md, { autoTemplates: false }), 'Files');
+    const items = block?.templateData?.items as TreeTemplateItem[];
+    expect(items?.[0].label).toBe('src/');
+    expect(items?.[0].children.map((c) => c.label)).toEqual(['index.ts', 'utils/']);
+  });
+
+  it('records a diagnostic when the body does not parse as a tree', () => {
+    const md = ['## Files {[tree]}', '', 'just prose, no hierarchy at all', ''].join('\n');
+    const doc = convert(md);
+    expect(doc.diagnostics?.some((d) => d.code === 'tree-parse')).toBe(true);
+  });
+});
+
+describe('rendering a derived tree through materializeBlockLayers', () => {
+  it('emits a single tree layer with the item hierarchy', () => {
+    const block = findBlock(convert(AUTO_DOC), 'Layout') as Block;
+    const layers = materializeLayers(block, {});
+    const treeLayer = layers.find((l: Layer) => l.type === 'tree');
+    expect(treeLayer).toBeDefined();
+    if (treeLayer?.type === 'tree') {
+      expect(treeLayer.content.items[0].label).toBe('src/');
+      expect(treeLayer.content.items[0].isDir).toBe(true);
+    }
+  });
+});
+
+describe('duration/caption hygiene', () => {
+  it('excludes the consumed tree fence from captions', () => {
+    const doc = convert(AUTO_DOC);
+    const captionText = (doc.captions?.phrases ?? []).map((p) => p.text).join(' ');
+    expect(captionText).not.toContain('├──');
+    expect(captionText).not.toContain('index.ts');
+  });
+});
+
+describe('template picker recommendation', () => {
+  it('surfaces tree for a tree-fence profile', () => {
+    const md = parseMarkdown(fenced(TREE_ART));
+    const profile = profileBlockContents(md.children as Parameters<typeof profileBlockContents>[0]);
+    expect(profile.hasTree).toBe(true);
+    const { recommended } = recommendTemplatesForBlock(profile, ['tree', 'list', 'title']);
+    expect(recommended).toContain('tree');
+  });
+});

package/src/__tests__/treeviewRender.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import {
+  parseTree,
+  renderTree,
+  treeFromTemplateData,
+  treeToTemplateData,
+  type Tree,
+} from '../doc/treeview/index.js';
+import { TREE_FIXTURES } from './fixtures/treeviewFixtures.js';
+
+function semantic(t: Tree): string[] {
+  const out: string[] = [];
+  const walk = (nodes: Tree['roots'], depth: number): void => {
+    for (const n of nodes) {
+      out.push(`${depth}:${n.label}${n.comment ? ` #${n.comment}` : ''}`);
+      walk(n.children, depth + 1);
+    }
+  };
+  walk(t.roots, 0);
+  return out;
+}
+
+describe('renderTree — output', () => {
+  it('renders a clean Unicode tree with connectors', () => {
+    const t = parseTree(['a/', '├── b', '└── c/', '    └── d'].join('\n'));
+    expect(renderTree(t)).toBe(['a/', '├── b', '└── c/', '    └── d'].join('\n'));
+  });
+
+  it('renders ASCII vocabulary for ascii-style trees', () => {
+    const t = parseTree(['a/', '|-- b', '`-- c'].join('\n'));
+    const out = renderTree(t);
+    expect(out).toContain('|-- b');
+    expect(out).toContain('`-- c');
+    expect(out).not.toMatch(/[├└│─]/u);
+  });
+
+  it('honours a style override', () => {
+    const t = parseTree(['a/', '├── b', '└── c'].join('\n'));
+    expect(renderTree(t, { style: 'ascii' })).toContain('|-- b');
+  });
+
+  it('renders trailing comments', () => {
+    const t = parseTree(['p/', '└── a.ts # note'].join('\n'));
+    expect(renderTree(t)).toContain('a.ts  # note');
+  });
+
+  it('roots carry no connector; children do', () => {
+    const t = parseTree(['root/', '└── only'].join('\n'));
+    const lines = renderTree(t).split('\n');
+    expect(lines[0]).toBe('root/');
+    expect(lines[1]).toBe('└── only');
+  });
+});
+
+describe('renderTree ↔ parseTree fixpoint', () => {
+  for (const fx of TREE_FIXTURES) {
+    it(`fixpoint + byte-idempotence: ${fx.name}`, () => {
+      const d1 = parseTree(fx.art);
+      const t1 = renderTree(d1);
+      const d2 = parseTree(t1);
+      expect(semantic(d2)).toEqual(semantic(d1));
+      const t2 = renderTree(d2);
+      const t3 = renderTree(parseTree(t2));
+      expect(t2).toBe(t1);
+      expect(t3).toBe(t1);
+    });
+  }
+
+  it('anti-churn: a structural edit only changes locally, then is stable', () => {
+    const t = parseTree(['a/', '├── b', '└── c'].join('\n'));
+    // Rename one node (structure-only edit) via the template-data round-trip.
+    const { items } = treeToTemplateData(t);
+    items[0].children[0].label = 'renamed';
+    const edited = treeFromTemplateData(items);
+    const r1 = renderTree(edited);
+    expect(r1).toContain('renamed');
+    expect(renderTree(parseTree(r1))).toBe(r1);
+  });
+});
+
+describe('templateData mapping round-trip', () => {
+  for (const fx of TREE_FIXTURES) {
+    it(`grid → items → grid preserves semantics: ${fx.name}`, () => {
+      const t = parseTree(fx.art);
+      const back = treeFromTemplateData(treeToTemplateData(t).items, { style: t.style });
+      expect(semantic(back)).toEqual(semantic(t));
+      // And renders identically.
+      expect(renderTree(back)).toBe(renderTree(t));
+    });
+  }
+});