@bendyline/squisq 1.5.1 → 2.0.0

package/src/__tests__/transformProvenance.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '../markdown/parse';
+import { markdownToDoc, flattenRenderableBlocks } from '../doc/markdownToDoc';
+import { applyTransform } from '../transform/applyTransform';
+import { allocateTiming } from '../transform/timingAllocator';
+import { isTemplateBlock, type TemplateBlock } from '../schemas/BlockTemplates';
+import type { Block, Doc } from '../schemas/Doc';
+
+const MD = `# The Numbers
+
+Revenue grew to 4,200 units in 2019 which was a big jump for the small team.
+"We never expected this kind of growth," said the founder about the year.
+
+# The Turning Point
+
+By 2021 the company had 87 employees across three offices and a plan.
+The expansion cost 1,500,000 dollars and took fourteen months to finish.
+
+# The Result
+
+Today the product ships to 40 countries and the team keeps growing steadily.
+`;
+
+function makeDoc(): Doc {
+  return markdownToDoc(parseMarkdown(MD));
+}
+
+/** Blocks a transform produced (positional transform-* ids). */
+function transformedBlocks(doc: Doc): Block[] {
+  return doc.blocks.filter((b) => b.id.startsWith('transform-'));
+}
+
+describe('transform provenance', () => {
+  it('every extraction-derived slide carries a sourceBlockId from the input doc', () => {
+    const source = makeDoc();
+    const sourceIds = new Set(flattenRenderableBlocks(source.blocks).map((b) => b.id));
+    const { doc } = applyTransform(source, 'data-driven');
+
+    const produced = transformedBlocks(doc).filter(
+      (b) => b.id !== 'transform-intro' && b.id !== 'transform-outro',
+    );
+    expect(produced.length).toBeGreaterThan(0);
+    for (const block of produced) {
+      expect(block.sourceBlockId, `block ${block.id} missing provenance`).toBeTruthy();
+      expect(sourceIds.has(block.sourceBlockId!)).toBe(true);
+    }
+  });
+
+  it('sourceStartTime is SECONDS on the doc timeline, not a char offset (regression)', () => {
+    const source = makeDoc();
+    const sourceEnd = Math.max(
+      ...flattenRenderableBlocks(source.blocks).map((b) => b.startTime + b.duration),
+    );
+    const { doc } = applyTransform(source, 'data-driven');
+
+    for (const block of doc.blocks) {
+      const tb = block as unknown as TemplateBlock;
+      if (typeof tb.sourceStartTime !== 'number') continue;
+      // The old bug put char offsets (hundreds) here; real seconds must
+      // stay inside the source timeline.
+      expect(tb.sourceStartTime).toBeLessThanOrEqual(sourceEnd + 1);
+      expect(tb.sourceStartTime).toBeGreaterThanOrEqual(0);
+      // The raw char offset is preserved separately as provenance.
+      expect(typeof tb.sourceCharOffset).toBe('number');
+    }
+  });
+
+  it('narration-timed source blocks anchor their slides inside the source range', () => {
+    const source = makeDoc();
+    // Simulate applyNarrationTiming: give the source blocks recorded times.
+    const flat = flattenRenderableBlocks(source.blocks);
+    const bounds = [0, 20, 45, 70];
+    flat.forEach((block, i) => {
+      block.startTime = bounds[i] ?? 70;
+      block.duration = (bounds[i + 1] ?? 70) - (bounds[i] ?? 70);
+    });
+    source.duration = 70;
+
+    const { doc } = applyTransform(source, 'data-driven');
+    const bySource = new Map(flat.map((b) => [b.id, b]));
+    let anchoredChecked = 0;
+    for (const block of transformedBlocks(doc)) {
+      // Only ANCHORED slides (real narration seconds) must sit inside
+      // their source range; floats (section headers, images) are placed
+      // approximately by design.
+      const tb = block as unknown as TemplateBlock;
+      if (!block.sourceBlockId || typeof tb.sourceStartTime !== 'number') continue;
+      const origin = bySource.get(block.sourceBlockId);
+      if (!origin || origin.duration <= 0) continue;
+      expect(block.startTime).toBeGreaterThanOrEqual(origin.startTime - 1e-6);
+      expect(block.startTime).toBeLessThan(origin.startTime + origin.duration + 1e-6);
+      anchoredChecked++;
+    }
+    expect(anchoredChecked).toBeGreaterThan(0);
+  });
+
+  it('transformed timelines stay contiguous (no uncovered narration seconds)', () => {
+    const source = makeDoc();
+    const { doc } = applyTransform(source, 'data-driven');
+    const sorted = [...doc.blocks].sort((a, b) => a.startTime - b.startTime);
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const end = sorted[i].startTime + sorted[i].duration;
+      expect(end).toBeCloseTo(sorted[i + 1].startTime, 5);
+    }
+  });
+});
+
+describe('allocateTiming fallback', () => {
+  it('keeps the historical rescale behavior when no anchors exist', () => {
+    const floats: TemplateBlock[] = [
+      { template: 'sectionHeader', id: 'a', duration: 5, audioSegment: 0, title: 'A' },
+      { template: 'sectionHeader', id: 'b', duration: 5, audioSegment: 0, title: 'B' },
+    ];
+    const result = allocateTiming(floats, 20);
+    expect(result[0].startTime).toBe(0);
+    expect(result[0].duration).toBe(10);
+    expect(result[1].startTime).toBe(10);
+    expect(result[1].duration).toBe(10);
+  });
+
+  it('anchored blocks keep their positions; floats fill the gaps', () => {
+    const blocks: TemplateBlock[] = [
+      // A floating intro before the first anchor.
+      { template: 'title', id: 'intro', duration: 4, audioSegment: 0, title: 'T' },
+      {
+        template: 'statHighlight',
+        id: 's1',
+        duration: 6,
+        audioSegment: 0,
+        stat: '42',
+        description: 'd',
+        sourceStartTime: 10,
+        sourceDuration: 6,
+      },
+      {
+        template: 'statHighlight',
+        id: 's2',
+        duration: 6,
+        audioSegment: 0,
+        stat: '87',
+        description: 'd',
+        sourceStartTime: 30,
+        sourceDuration: 6,
+      },
+    ];
+    const result = allocateTiming(blocks, 40);
+    // Intro fills [0, 10) up to the first anchor.
+    expect(result[0].startTime).toBe(0);
+    expect(result[0].duration).toBeCloseTo(10, 5);
+    // Anchors sit at their narration positions; s1 holds until s2 starts.
+    expect(result[1].startTime).toBe(10);
+    expect(result[1].duration).toBeCloseTo(20, 5);
+    expect(result[2].startTime).toBe(30);
+    // The final block covers through the total duration.
+    expect(result[2].startTime + result[2].duration).toBeCloseTo(40, 5);
+    for (const b of result) {
+      expect(isTemplateBlock(b as unknown as TemplateBlock) || true).toBe(true);
+    }
+  });
+});

package/src/__tests__/transformV2.test.ts

@@ -1,10 +1,9 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import {
   applyTransform,
   resolveTransformStyle,
-  registerTransformStyle,
-  unregisterTransformStyle,
   getTransformStyleIds,
+  createTransformStyleRegistry,
 } from '../transform/index.js';
 import type { TransformStyleConfig } from '../transform/index.js';
 import type { Doc, Block } from '../schemas/Doc.js';
@@ -49,8 +48,6 @@ function sampleDoc(): Doc {
 }
 
 describe('transform style contract v2', () => {
-  afterEach(() => unregisterTransformStyle('custom-test'));
-
   it('suggestedThemeId applies only when the doc declares no theme', () => {
     const { doc } = applyTransform(sampleDoc(), 'magazine');
     expect(doc.themeId).toBe('magazine');
@@ -88,23 +85,53 @@ describe('transform style contract v2', () => {
     expect(last.template).toBe('sectionHeader');
   });
 
-  it('registerTransformStyle adds a resolvable style that wins over unknown fallback', () => {
+  it('resolves custom styles only through their caller-owned registry', () => {
     const custom: TransformStyleConfig = {
       ...resolveTransformStyle('minimal'),
       id: 'custom-test',
       name: 'Custom Test',
       description: 'test style',
     };
-    registerTransformStyle(custom);
-    expect(getTransformStyleIds()).toContain('custom-test');
-    expect(resolveTransformStyle('custom-test').name).toBe('Custom Test');
-    unregisterTransformStyle('custom-test');
-    // Unknown id falls back to the default (documentary)
+    const registry = createTransformStyleRegistry([custom]);
+    expect(getTransformStyleIds(registry)).toContain('custom-test');
+    expect(resolveTransformStyle('custom-test', registry).name).toBe('Custom Test');
     expect(resolveTransformStyle('custom-test').id).toBe('documentary');
+    expect(
+      applyTransform(sampleDoc(), 'custom-test', { registry }).doc.blocks.length,
+    ).toBeGreaterThan(0);
   });
 
-  it("accepts 'dataDriven' as an alias for the hyphenated registry id", () => {
+  it('normalizes the stored legacy dataDriven id without advertising it', () => {
+    expect(resolveTransformStyle('data-driven').id).toBe('data-driven');
     expect(resolveTransformStyle('dataDriven').id).toBe('data-driven');
+    expect(getTransformStyleIds()).not.toContain('dataDriven');
+  });
+
+  it('validates and stores immutable style snapshots in isolated registries', () => {
+    const base = resolveTransformStyle('minimal');
+    const source: TransformStyleConfig = {
+      ...base,
+      id: 'tenant-style',
+      name: 'Tenant Style',
+      preferredTypes: [...base.preferredTypes],
+      colorSchemes: [...base.colorSchemes],
+      blocksPerSection: { ...base.blocksPerSection },
+    };
+    const tenantA = createTransformStyleRegistry([source]);
+    const tenantB = createTransformStyleRegistry();
+    source.name = 'Changed later';
+    source.colorSchemes[0] = 'red';
+
+    const stored = tenantA.get('tenant-style')!;
+    expect(stored.name).toBe('Tenant Style');
+    expect(stored.colorSchemes[0]).toBe(base.colorSchemes[0]);
+    expect(Object.isFrozen(stored)).toBe(true);
+    expect(Object.isFrozen(stored.colorSchemes)).toBe(true);
+    expect(tenantB.get('tenant-style')).toBeUndefined();
+
+    expect(() => tenantA.register({ ...source, id: 'bad-style', transformRatio: 2 })).toThrow(
+      /transformRatio/,
+    );
   });
 
   it('budget.slidesPerMinute caps promotions on long docs', () => {
@@ -127,9 +154,8 @@ describe('transform style contract v2', () => {
       id: 'custom-test',
       budget: { slidesPerMinute: 2 },
     };
-    registerTransformStyle(budgeted);
     const loose = applyTransform(manyBlocks, 'data-driven');
-    const tight = applyTransform(manyBlocks, 'custom-test');
+    const tight = applyTransform(manyBlocks, budgeted);
     expect(tight.stats.transformedBlocks).toBeLessThan(loose.stats.transformedBlocks);
     // 12 blocks x 5s = 60s → 2/minute → at most 2 promotions
     expect(tight.stats.transformedBlocks).toBeLessThanOrEqual(2);

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']);
+  });
+});