@bendyline/squisq 1.5.2 → 2.0.1

package/src/__tests__/applyNarrationTiming.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '../markdown/parse';
+import { markdownToDoc, flattenRenderableBlocks } from '../doc/markdownToDoc';
+import { applyNarrationTiming } from '../doc/applyNarrationTiming';
+import { resolveAudioMapping } from '../doc/audioMapping';
+import { buildNarrationScript } from '../narration/script';
+import type { NarrationTimingJsonV3 } from '../narration/sidecar';
+import { MemoryContentContainer } from '../storage/ContentContainer';
+import type { Doc } from '../schemas/Doc';
+
+const MD = `{[audio src=audio/take.webm anchor=document]}
+
+# Intro
+
+Alpha beta gamma delta epsilon words for the intro block.
+
+# Middle
+
+Zeta eta theta iota kappa words for the middle block.
+
+# Ending
+
+Lambda mu nu xi omicron words for the ending block.
+`;
+
+function makeDoc(markdown = MD): Doc {
+  return markdownToDoc(parseMarkdown(markdown));
+}
+
+/** A v3 sidecar whose block ranges use the doc's real block ids. */
+function makeSidecar(doc: Doc, overrides?: Partial<NarrationTimingJsonV3>): NarrationTimingJsonV3 {
+  const script = buildNarrationScript(doc);
+  const bounds = [0, 10, 22, 30];
+  return {
+    version: 3,
+    sourceText: script.sourceText,
+    duration: 30,
+    bookmarks: [],
+    blocks: script.blocks.map((range, i) => ({
+      blockId: range.blockId,
+      ...(range.heading !== undefined ? { heading: range.heading } : {}),
+      blockIndex: i,
+      charStart: range.charStart,
+      charEnd: range.charEnd,
+      startSec: bounds[i],
+      endSec: bounds[i + 1],
+    })),
+    ...overrides,
+  };
+}
+
+async function containerWith(sidecar: NarrationTimingJsonV3, path = 'audio/take.webm') {
+  const container = new MemoryContentContainer();
+  await container.writeFile(path, new Uint8Array([1, 2, 3]), 'audio/webm');
+  await container.writeFile(
+    `${path}.timing.json`,
+    new TextEncoder().encode(JSON.stringify(sidecar)),
+    'application/json',
+  );
+  return container;
+}
+
+describe('applyNarrationTiming', () => {
+  it('re-times blocks from v3 sidecar ranges and owns doc.duration', async () => {
+    const doc = makeDoc();
+    const container = await containerWith(makeSidecar(doc));
+    const result = await applyNarrationTiming(doc, container);
+
+    expect(result.applied).toBe(true);
+    expect(result.clipSrc).toBe('audio/take.webm');
+    const flat = flattenRenderableBlocks(result.doc.blocks);
+    expect(flat[0].startTime).toBe(0);
+    expect(flat[0].duration).toBe(10);
+    expect(flat[1].startTime).toBe(10);
+    expect(flat[1].duration).toBe(12);
+    expect(flat[2].startTime).toBe(22);
+    expect(flat[2].duration).toBe(8);
+    expect(result.doc.duration).toBe(30);
+    // Input doc untouched.
+    expect(doc.blocks[0].startTime).not.toBe(10);
+  });
+
+  it('returns the doc unchanged when no narration clip or sidecar exists', async () => {
+    const doc = makeDoc('# Just\n\nSome text.\n');
+    const container = new MemoryContentContainer();
+    const result = await applyNarrationTiming(doc, container);
+    expect(result.applied).toBe(false);
+    expect(result.doc).toBe(doc);
+  });
+
+  it('honors author pins and records an info diagnostic on real conflict', async () => {
+    const pinned = makeDoc(MD.replace('# Middle', '# Middle {duration=3}'));
+    const container = await containerWith(makeSidecar(pinned));
+    const result = await applyNarrationTiming(pinned, container);
+
+    expect(result.applied).toBe(true);
+    const flat = flattenRenderableBlocks(result.doc.blocks);
+    // Pin wins (narration said 12s, pin says 3s).
+    expect(flat[1].duration).toBe(3);
+    const conflict = result.doc.diagnostics?.find((d) => d.code === 'narration-pin-conflict');
+    expect(conflict).toBeTruthy();
+    expect(conflict!.severity).toBe('info');
+    expect(conflict!.blockId).toBe(flat[1].id);
+  });
+
+  it('matches a renamed heading through text similarity', async () => {
+    const original = makeDoc();
+    const sidecar = makeSidecar(original);
+    // Author renames the middle heading after recording: id + heading drift,
+    // but the body text still matches.
+    const edited = makeDoc(MD.replace('# Middle', '# Renamed Midsection'));
+    const container = await containerWith(sidecar);
+    const result = await applyNarrationTiming(edited, container);
+
+    expect(result.applied).toBe(true);
+    const flat = flattenRenderableBlocks(result.doc.blocks);
+    expect(flat[1].startTime).toBe(10);
+    expect(flat[1].duration).toBe(12);
+  });
+
+  it('falls back to proportional timing for v1 sidecars narrating this doc', async () => {
+    const doc = makeDoc();
+    const script = buildNarrationScript(doc);
+    const container = await containerWith({
+      version: 3,
+      sourceText: script.sourceText,
+      duration: 30,
+      bookmarks: [],
+      blocks: [],
+    });
+    const result = await applyNarrationTiming(doc, container);
+
+    expect(result.applied).toBe(true);
+    const flat = flattenRenderableBlocks(result.doc.blocks);
+    expect(flat[0].startTime).toBe(0);
+    expect(flat[1].startTime).toBeGreaterThan(0);
+    expect(flat[2].startTime).toBeGreaterThan(flat[1].startTime);
+    const last = flat[flat.length - 1];
+    expect(last.startTime + last.duration).toBeCloseTo(30, 5);
+  });
+
+  it('does not apply a v1 sidecar from an unrelated take', async () => {
+    const doc = makeDoc();
+    const container = await containerWith({
+      version: 3,
+      sourceText: 'completely different narration about sailboats and harbors and tides',
+      duration: 30,
+      bookmarks: [],
+      blocks: [],
+    });
+    const result = await applyNarrationTiming(doc, container);
+    expect(result.applied).toBe(false);
+  });
+});
+
+describe('resolveAudioMapping with a narration take', () => {
+  it('applies narration timing and never double-maps the take into segments', async () => {
+    const doc = makeDoc();
+    const container = await containerWith(makeSidecar(doc));
+    const resolved = await resolveAudioMapping(doc, container);
+
+    const flat = flattenRenderableBlocks(resolved.blocks);
+    expect(flat[1].startTime).toBe(10);
+    expect(resolved.duration).toBe(30);
+    // The take plays through the media schedule (documentMedia), so it must
+    // NOT also appear as an audio segment — that would play it twice.
+    expect(resolved.audio.segments.some((s) => s.src === 'audio/take.webm')).toBe(false);
+  });
+
+  it('keeps classic per-block segment mapping for docs without narration', async () => {
+    const doc = makeDoc('# Intro\n\nAlpha beta gamma delta epsilon words for the intro block.\n');
+    const container = new MemoryContentContainer();
+    await container.writeFile('audio/clip.mp3', new Uint8Array([9]), 'audio/mpeg');
+    await container.writeFile(
+      'audio/clip.mp3.timing.json',
+      new TextEncoder().encode(
+        JSON.stringify({
+          sourceText: 'Alpha beta gamma delta epsilon words for the intro block.',
+          duration: 7,
+          bookmarks: [],
+        }),
+      ),
+      'application/json',
+    );
+    const resolved = await resolveAudioMapping(doc, container);
+    expect(resolved.audio.segments.length).toBe(1);
+    expect(resolved.audio.segments[0].src).toBe('audio/clip.mp3');
+    expect(resolved.duration).toBe(7);
+  });
+});

package/src/__tests__/applyRenderStyle.test.ts

@@ -73,13 +73,13 @@ describe('applyRenderStyleToLayers', () => {
     expect(c[0].animation?.type).toBe('slowZoom');
   });
 
-  it("treats defaultImageAnimation 'slowZoom' as ambient motion", () => {
+  it('does not let a default entrance animation override ambientMotion=false', () => {
     const out = applyRenderStyleToLayers(
       [fullBleedImage()],
       BLOCK,
-      themeWith({ defaultImageAnimation: 'slowZoom' }),
+      themeWith({ ambientMotion: false, defaultImageAnimation: 'slowZoom' }),
     );
-    expect(out[0].animation?.type).toBe('slowZoom');
+    expect(out[0].animation).toBeUndefined();
   });
 
   it('never overrides an authored animation, including type none', () => {

package/src/__tests__/asciiDiagramBattle.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, it } from 'vitest';
+import {
+  detectAsciiDiagram,
+  parseAsciiDiagram,
+  renderAsciiDiagram,
+  type AsciiDiagram,
+} from '../doc/asciiDiagram/index.js';
+import { BATTLE_DIAGRAMS, type BattleDiagram } from './fixtures/asciiDiagramBattle.js';
+
+/**
+ * Battle test: a broad corpus of AI-style ASCII diagrams (linear flows,
+ * fan-out/in, DAGs, cycles, many-to-many, containers, labeled edges,
+ * styles) driven through the codec end-to-end. Each fixture asserts:
+ *
+ *  1. Detection — the art is recognized as a diagram.
+ *  2. Parse accuracy — it parses to EXACTLY the intended nodes / edges /
+ *     containment (the "we read what the AI drew" guarantee).
+ *  3. Semantic fixpoint — render→parse preserves that semantic (editing
+ *     the canvas never silently drops a node or edge).
+ *  4. Byte idempotence — render→parse→render is byte-stable across cycles
+ *     (no jitter, no drift).
+ *
+ * Followed by a focused many-to-many section and honest graceful-
+ * degradation / known-limitation coverage.
+ */
+
+interface Semantic {
+  nodes: string[];
+  edges: string[];
+}
+function semantic(d: AsciiDiagram): Semantic {
+  return {
+    nodes: d.nodes.map((n) => `${n.id}${n.containerId ? `<${n.containerId}` : ''}`).sort(),
+    edges: d.edges.map((e) => `${e.source}|${e.target}|${e.directed}|${e.label ?? ''}`).sort(),
+  };
+}
+function expectedEdgeStrings(fx: BattleDiagram): string[] {
+  return fx.edges
+    .map(
+      ([s, t, label, directed]) => `${s}|${t}|${directed === false ? false : true}|${label ?? ''}`,
+    )
+    .sort();
+}
+
+describe('battle test — every fixture round-trips', () => {
+  for (const fx of BATTLE_DIAGRAMS) {
+    describe(`${fx.category}: ${fx.name}`, () => {
+      const d = parseAsciiDiagram(fx.art);
+
+      it('detects as a diagram', () => {
+        expect(detectAsciiDiagram(fx.art).isDiagram).toBe(true);
+      });
+
+      it('parses the intended nodes', () => {
+        expect(d.nodes.map((n) => n.id).sort()).toEqual([...fx.nodes].sort());
+      });
+
+      it('parses the intended edges (source, target, direction, label)', () => {
+        const got = d.edges
+          .map((e) => `${e.source}|${e.target}|${e.directed}|${e.label ?? ''}`)
+          .sort();
+        expect(got).toEqual(expectedEdgeStrings(fx));
+      });
+
+      it('parses the intended containment', () => {
+        const got: Record<string, string> = {};
+        for (const n of d.nodes) if (n.containerId) got[n.id] = n.containerId;
+        expect(got).toEqual(fx.containers ?? {});
+      });
+
+      it('render→parse preserves the semantic (fixpoint)', () => {
+        const reparsed = parseAsciiDiagram(renderAsciiDiagram(d));
+        expect(semantic(reparsed)).toEqual(semantic(d));
+      });
+
+      it('render→parse→render is byte-stable across three cycles', () => {
+        const t1 = renderAsciiDiagram(d);
+        const t2 = renderAsciiDiagram(parseAsciiDiagram(t1));
+        const t3 = renderAsciiDiagram(parseAsciiDiagram(t2));
+        expect(t2).toBe(t1);
+        expect(t3).toBe(t1);
+      });
+    });
+  }
+});
+
+describe('battle test — coverage sanity', () => {
+  it('covers every intended category', () => {
+    const categories = new Set(BATTLE_DIAGRAMS.map((f) => f.category));
+    for (const c of [
+      'linear',
+      'fan-out',
+      'fan-in',
+      'dag',
+      'cycle',
+      'many-to-many',
+      'edges',
+      'labels',
+      'container',
+      'style',
+    ]) {
+      expect(categories.has(c)).toBe(true);
+    }
+  });
+
+  it('fixture names are unique', () => {
+    const names = BATTLE_DIAGRAMS.map((f) => f.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});
+
+describe('battle test — many-to-many relationships', () => {
+  it('recovers every edge of a full 3-node mesh (6 directed edges)', () => {
+    const fx = BATTLE_DIAGRAMS.find((f) => f.name === 'fullMesh3')!;
+    const d = parseAsciiDiagram(fx.art);
+    expect(d.edges).toHaveLength(6);
+    const pairs = new Set(d.edges.map((e) => `${e.source}->${e.target}`));
+    for (const a of ['alpha', 'beta', 'gamma']) {
+      for (const b of ['alpha', 'beta', 'gamma']) {
+        if (a !== b) expect(pairs.has(`${a}->${b}`)).toBe(true);
+      }
+    }
+  });
+
+  it('recovers a fan-out hub connecting to all of its targets', () => {
+    const fx = BATTLE_DIAGRAMS.find((f) => f.name === 'loadBalancerFanout')!;
+    const d = parseAsciiDiagram(fx.art);
+    const targets = d.edges
+      .filter((e) => e.source === 'load-balancer')
+      .map((e) => e.target)
+      .sort();
+    expect(targets).toEqual(['web1', 'web2', 'web3', 'web4']);
+  });
+
+  it('recovers a fan-in hub reached by all of its sources', () => {
+    const fx = BATTLE_DIAGRAMS.find((f) => f.name === 'collectorFanin')!;
+    const d = parseAsciiDiagram(fx.art);
+    const sources = d.edges
+      .filter((e) => e.target === 'collector')
+      .map((e) => e.source)
+      .sort();
+    expect(sources).toEqual(['s1', 's2', 's3']);
+  });
+
+  it('recovers a diamond (two disjoint paths reconverging)', () => {
+    const fx = BATTLE_DIAGRAMS.find((f) => f.name === 'diamond')!;
+    const d = parseAsciiDiagram(fx.art);
+    const edges = new Set(d.edges.map((e) => `${e.source}->${e.target}`));
+    expect(edges).toEqual(new Set(['a->b', 'a->c', 'b->d', 'c->d']));
+    // Byte-stable, so an edit never collapses one of the two paths.
+    expect(renderAsciiDiagram(parseAsciiDiagram(renderAsciiDiagram(d)))).toBe(
+      renderAsciiDiagram(d),
+    );
+  });
+
+  it('preserves a bidirectional pair as two directed edges', () => {
+    const fx = BATTLE_DIAGRAMS.find((f) => f.name === 'bidirReplication')!;
+    const d = parseAsciiDiagram(fx.art);
+    expect(d.edges).toHaveLength(2);
+    expect(new Set(d.edges.map((e) => `${e.source}->${e.target}`))).toEqual(
+      new Set(['primary->replica', 'replica->primary']),
+    );
+  });
+});
+
+describe('battle test — graceful degradation of the hard cases', () => {
+  // Dense bipartite crossing meshes are inherently ambiguous in ASCII (two
+  // lines that cross in a tight channel cannot be told from a merge). The
+  // parser must not crash or hallucinate — it returns *some* subset without
+  // throwing, and detection/rendering stay well-defined.
+  it('does not crash on a dense bipartite crossing mesh', () => {
+    const art = [
+      '┌────────┐          ┌────────┐',
+      '│   A    │          │   B    │',
+      '└─┬────┬─┘          └─┬────┬─┘',
+      '  │    └──────┐   ┌───┘    │',
+      '  │           │   │        │',
+      '  ▼           ▼   ▼        ▼',
+      '┌────────┐        ┌────────┐',
+      '│   X    │        │   Y    │',
+      '└────────┘        └────────┘',
+    ].join('\n');
+    const d = parseAsciiDiagram(art);
+    expect(d.nodes.map((n) => n.id).sort()).toEqual(['a', 'b', 'x', 'y']);
+    // Render never throws and stays byte-idempotent even if edges are lossy.
+    const r1 = renderAsciiDiagram(d);
+    expect(renderAsciiDiagram(parseAsciiDiagram(r1))).toBe(r1);
+  });
+
+  // Boxes whose top and bottom borders are different widths (a very common
+  // AI misalignment) don't trace as boxes — the fence stays plain code
+  // (safe failure) rather than producing a garbled diagram.
+  it('rejects a misaligned container as a non-diagram (stays code)', () => {
+    const art = [
+      '┌───────────────── Cluster ─────────────────┐',
+      '│  ┌─────────┐    ┌─────────┐   │',
+      '│  │  Pod A  │    │  Pod B  │   │',
+      '│  └─────────┘    └─────────┘   │',
+      '└────────────────────────────────────────────┘',
+    ].join('\n');
+    const detection = detectAsciiDiagram(art);
+    // The outer misaligned box is dropped; whatever remains is not a
+    // confident diagram, so it degrades to a plain code block.
+    expect(detection.reasons.length).toBeGreaterThan(0);
+  });
+
+  it('never throws on garbage, empty, or non-diagram fences', () => {
+    for (const junk of ['', '   ', 'hello world', '┌──\n│ x', '|||\n---\n|||', 'a | b | c']) {
+      expect(() => parseAsciiDiagram(junk)).not.toThrow();
+      expect(() => renderAsciiDiagram(parseAsciiDiagram(junk))).not.toThrow();
+    }
+  });
+});
+
+describe('battle test — known limitation: labels on tight splits / cross-box feedback', () => {
+  // The PARSER reads per-branch labels on a shared bus correctly; the
+  // RENDERER can only host one label per tight two-way split, so a
+  // re-render may normalize one away. Documented so the behavior is a
+  // conscious contract, not a silent surprise. (Parse accuracy holds; only
+  // re-render label placement is lossy.)
+  it('parses both labels of a two-way split, even if re-render keeps one', () => {
+    const art = [
+      '        ┌───────────┐',
+      '        │  Check?   │',
+      '        └──┬─────┬──┘',
+      '     yes │       │ no',
+      '         ▼       ▼',
+      '    ┌────────┐ ┌────────┐',
+      '    │ Accept │ │ Reject │',
+      '    └────────┘ └────────┘',
+    ].join('\n');
+    const d = parseAsciiDiagram(art);
+    const labels = d.edges
+      .map((e) => e.label)
+      .filter(Boolean)
+      .sort();
+    expect(labels).toEqual(['no', 'yes']);
+    // The edges themselves are always preserved; only label placement is
+    // best-effort on the tight-split re-render.
+    const reparsed = parseAsciiDiagram(renderAsciiDiagram(d));
+    expect(reparsed.edges.map((e) => `${e.source}->${e.target}`).sort()).toEqual([
+      'check->accept',
+      'check->reject',
+    ]);
+  });
+});

package/src/__tests__/asciiDiagramDetect.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import {
+  detectAsciiDiagram,
+  isAsciiDiagramFence,
+  isEligibleAsciiFenceLang,
+  isExplicitDiagramLang,
+} from '../doc/asciiDiagram/index.js';
+import type { MarkdownCodeBlock } from '../markdown/types.js';
+import { NEGATIVE_FIXTURES, POSITIVE_FIXTURES } from './fixtures/asciiDiagrams.js';
+
+/**
+ * The negative corpus is the CONTRACT for detection tuning: every entry
+ * must stay rejected. False positives hide real code behind a diagram
+ * canvas; false negatives merely leave a code block alone.
+ */
+
+const EXPECTED_REJECT_REASONS: Record<string, RegExp> = {
+  NEG_MARKDOWN_TABLE: /markdown-table|too-few-corner-candidates/,
+  NEG_PSQL_TABLE: /table-lattice/,
+  NEG_MYSQL_TABLE: /table-lattice/,
+  NEG_SHELL_PIPES: /too-few-corner-candidates|too-few-lines|too-few-boxes/,
+  NEG_TS_UNION: /too-few-corner-candidates|too-few-boxes/,
+  NEG_SQL_DDL: /too-few-corner-candidates|too-few-boxes/,
+  NEG_FILE_TREE: /too-few-corner-candidates|too-few-boxes/,
+  NEG_YAML: /too-few-corner-candidates|too-few-boxes/,
+  NEG_LOG_COLUMNS: /too-few-corner-candidates|too-few-boxes/,
+  NEG_PROSE_HEAVY: /loose-ratio/,
+  SINGLE_BOX: /too-few-boxes|too-few-corner-candidates/,
+};
+
+describe('detectAsciiDiagram — negative corpus (must all reject)', () => {
+  for (const [name, fixture] of Object.entries(NEGATIVE_FIXTURES)) {
+    it(`rejects ${name}`, () => {
+      const detection = detectAsciiDiagram(fixture);
+      expect(detection.isDiagram).toBe(false);
+      const expected = EXPECTED_REJECT_REASONS[name];
+      expect(detection.reasons.join(' ')).toMatch(expected);
+    });
+  }
+
+  it('rejects oversized fences without parsing', () => {
+    const huge = Array.from({ length: 500 }, () => '┌──┐').join('\n');
+    const detection = detectAsciiDiagram(huge);
+    expect(detection.isDiagram).toBe(false);
+    expect(detection.reasons.join(' ')).toMatch(/too-many-lines/);
+  });
+
+  it('rejects tiny fragments', () => {
+    expect(detectAsciiDiagram('┌┐\n└┘').isDiagram).toBe(false);
+  });
+});
+
+describe('detectAsciiDiagram — positive fixtures (must all accept)', () => {
+  for (const [name, fixture] of Object.entries(POSITIVE_FIXTURES)) {
+    it(`accepts ${name}`, () => {
+      const detection = detectAsciiDiagram(fixture);
+      expect(detection.isDiagram).toBe(true);
+      expect(detection.diagram).toBeDefined();
+      expect(detection.diagram?.nodes.length).toBeGreaterThanOrEqual(2);
+    });
+  }
+});
+
+describe('garbled-label guard (over-broken art falls back to code)', () => {
+  // Hand-drawn boxes whose labels overflow their borders AND collide with a
+  // neighbour desync the columns row-to-row, so box-drawing chars leak into
+  // the extracted labels. That's an unrecoverable parse — detection must
+  // decline so the fence renders as a faithful code block, not a garbled
+  // canvas. (This is the shape of real "half-broken" architecture art.)
+  const COLLIDING = [
+    '┌────────┐   ┌────────┐',
+    '│ @scope/kernel  │   │ @scope/client  │',
+    '│ x      │   │ y      │',
+    '└────────┘   └────────┘',
+    '┌────────┐   ┌────────┐',
+    '│ @scope/materls │   │ @scope/schema  │',
+    '│ z      │   │ w      │',
+    '└────────┘   └────────┘',
+  ].join('\n');
+
+  it('rejects a diagram whose labels are structurally garbled', () => {
+    const d = detectAsciiDiagram(COLLIDING);
+    expect(d.isDiagram).toBe(false);
+    expect(d.reasons.join(' ')).toMatch(/garbled-labels/);
+  });
+
+  it('rejects garbled art even when explicitly `diagram`-tagged', () => {
+    expect(detectAsciiDiagram(COLLIDING, { explicit: true }).isDiagram).toBe(false);
+  });
+
+  it('does not flag a clean diagram (no box chars in labels)', () => {
+    // Sanity: clean labels never trip the guard.
+    expect(detectAsciiDiagram(POSITIVE_FIXTURES.TWO_BOX_VERTICAL).isDiagram).toBe(true);
+    expect(detectAsciiDiagram(POSITIVE_FIXTURES.NESTED_CONTAINER).isDiagram).toBe(true);
+  });
+});
+
+describe('explicit `diagram` tag (lenient detection)', () => {
+  const ONE_BOX = ['┌────────┐', '│ Solo   │', '└────────┘'].join('\n');
+
+  it('isExplicitDiagramLang matches only the `diagram` tag', () => {
+    for (const lang of ['diagram', ' Diagram ', 'DIAGRAM'])
+      expect(isExplicitDiagramLang(lang)).toBe(true);
+    for (const lang of [undefined, null, '', 'text', 'ascii', 'tree', 'js'])
+      expect(isExplicitDiagramLang(lang)).toBe(false);
+  });
+
+  it('a single-box diagram is rejected untagged but accepted when explicit', () => {
+    expect(detectAsciiDiagram(ONE_BOX).isDiagram).toBe(false);
+    const explicit = detectAsciiDiagram(ONE_BOX, { explicit: true });
+    expect(explicit.isDiagram).toBe(true);
+    expect(explicit.diagram?.nodes).toHaveLength(1);
+  });
+
+  it('still rejects a markdown table even when explicitly tagged', () => {
+    expect(
+      detectAsciiDiagram(NEGATIVE_FIXTURES.NEG_MARKDOWN_TABLE, { explicit: true }).isDiagram,
+    ).toBe(false);
+  });
+
+  it('`diagram` is an eligible fence lang and isAsciiDiagramFence accepts a tagged single box', () => {
+    expect(isEligibleAsciiFenceLang('diagram')).toBe(true);
+    const fence: MarkdownCodeBlock = { type: 'code', lang: 'diagram', value: ONE_BOX };
+    expect(isAsciiDiagramFence(fence)).toBe(true);
+    // The same content in a bare fence is not auto-detected.
+    expect(isAsciiDiagramFence({ type: 'code', value: ONE_BOX })).toBe(false);
+  });
+});
+
+describe('fence language gate', () => {
+  it('allows no language, empty, and the inert allowlist', () => {
+    expect(isEligibleAsciiFenceLang(undefined)).toBe(true);
+    expect(isEligibleAsciiFenceLang(null)).toBe(true);
+    expect(isEligibleAsciiFenceLang('')).toBe(true);
+    expect(isEligibleAsciiFenceLang('text')).toBe(true);
+    expect(isEligibleAsciiFenceLang('TXT')).toBe(true);
+    expect(isEligibleAsciiFenceLang('plaintext')).toBe(true);
+    expect(isEligibleAsciiFenceLang('plain')).toBe(true);
+    expect(isEligibleAsciiFenceLang('ascii')).toBe(true);
+  });
+
+  it('rejects real programming languages', () => {
+    for (const lang of ['js', 'ts', 'python', 'sql', 'mermaid', 'json', 'yaml', 'bash']) {
+      expect(isEligibleAsciiFenceLang(lang)).toBe(false);
+    }
+  });
+
+  it('isAsciiDiagramFence combines the lang gate with content detection', () => {
+    const art = POSITIVE_FIXTURES.TWO_BOX_VERTICAL;
+    const fence = (lang?: string): MarkdownCodeBlock => ({
+      type: 'code',
+      ...(lang !== undefined ? { lang } : {}),
+      value: art,
+    });
+    expect(isAsciiDiagramFence(fence())).toBe(true);
+    expect(isAsciiDiagramFence(fence('text'))).toBe(true);
+    expect(isAsciiDiagramFence(fence('js'))).toBe(false);
+    expect(isAsciiDiagramFence({ type: 'code', value: NEGATIVE_FIXTURES.NEG_PSQL_TABLE })).toBe(
+      false,
+    );
+  });
+});

package/src/__tests__/asciiDiagramMapping.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { asciiDiagramToTemplateData, parseAsciiDiagram } from '../doc/asciiDiagram/index';
+
+const LOAD_BALANCER_FAN_OUT = `           ┌───────────────┐
+           │ Load Balancer │
+           └──┬──┬──┬──┬───┘
+       ┌──────┘  │  │  └──────┐
+       ▼         ▼  ▼         ▼
+    ┌──────┐┌──────┐┌──────┐┌──────┐
+    │ Web1 ││ Web2 ││ Web3 ││ Web4 │
+    └──────┘└──────┘└──────┘└──────┘`;
+
+describe('ASCII diagram canvas mapping', () => {
+  it('maps fan-out arrows to distributed bottom ports and top-center targets', () => {
+    const diagram = parseAsciiDiagram(LOAD_BALANCER_FAN_OUT);
+    const { edges } = asciiDiagramToTemplateData(diagram);
+
+    expect(edges.map((edge) => edge.target)).toEqual(['web1', 'web2', 'web3', 'web4']);
+    expect(edges.map((edge) => edge.routing)).toEqual([
+      'orthogonal',
+      'orthogonal',
+      'orthogonal',
+      'orthogonal',
+    ]);
+    expect(edges.map((edge) => edge.sourceAnchor)).toEqual([
+      { side: 'bottom', offset: 0.2 },
+      { side: 'bottom', offset: 0.4 },
+      { side: 'bottom', offset: 0.6 },
+      { side: 'bottom', offset: 0.8 },
+    ]);
+    expect(edges.map((edge) => edge.targetAnchor)).toEqual([
+      { side: 'top', offset: 0.5 },
+      { side: 'top', offset: 0.5 },
+      { side: 'top', offset: 0.5 },
+      { side: 'top', offset: 0.5 },
+    ]);
+  });
+});