@bendyline/squisq 1.5.2 → 2.0.0

package/src/__tests__/versions.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, beforeEach } from 'vitest';
 import { MemoryContentContainer } from '../storage/ContentContainer';
+import { scopeContainer } from '../storage/ScopedContentContainer';
 import {
   DocumentVersionManager,
   VERSIONS_PREFIX,
@@ -111,6 +112,49 @@ describe('saveVersion', () => {
     expect(result.version?.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z.md`);
     expect(result.version?.basename).toBe('index');
     expect(await readUtf8(container, result.version!.path)).toBe('# hello');
+    expect(await readUtf8(container, '.gitignore')).toBe('.versions/\n');
+  });
+
+  it('writes the ignore rule at the root of a scoped *_files sidecar', async () => {
+    const parent = new MemoryContentContainer();
+    const sidecar = scopeContainer(parent, 'notes_files');
+    const now = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+
+    const result = await saveVersion(sidecar, {
+      basename: 'notes',
+      content: '# hello',
+      now,
+    });
+
+    expect(result.saved).toBe(true);
+    expect(await readUtf8(parent, 'notes_files/.gitignore')).toBe('.versions/\n');
+    expect(await parent.exists(`notes_files/${result.version!.path}`)).toBe(true);
+  });
+
+  it('preserves existing .gitignore rules and does not duplicate the versions rule', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    await container.writeFile(
+      '.gitignore',
+      new TextEncoder().encode('generated/\r\n'),
+      'text/plain',
+    );
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)) });
+
+    expect(await readUtf8(container, '.gitignore')).toBe('generated/\r\n.versions/\r\n');
+  });
+
+  it('backfills .gitignore when an existing snapshot is unchanged', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    await container.removeFile('.gitignore');
+
+    const result = await saveVersion(container, {
+      now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)),
+    });
+
+    expect(result.reason).toBe('unchanged');
+    expect(await readUtf8(container, '.gitignore')).toBe('.versions/\n');
   });
 
   it('returns unchanged on identical second save', async () => {

package/src/doc/applyNarrationTiming.ts

@@ -0,0 +1,244 @@
+/**
+ * Apply narration timing from a document-anchored take to a Doc's block
+ * timeline.
+ *
+ * When a doc carries a document-spanning narration clip (a preamble
+ * `{[audio src=… anchor=document]}` → `doc.documentMedia`) whose
+ * `.timing.json` sidecar has per-block ranges (v3, written by the
+ * teleprompter's aligner), the blocks are re-timed so playback and
+ * exports advance in sync with the recorded voice. Runs as step 0 of
+ * `resolveAudioMapping`, so every surface that resolves audio gets it.
+ *
+ * Precedence: author-pinned `duration=`/`startTime=` heading attrs win
+ * over narration ranges (a conflicting pin gets an `info` diagnostic);
+ * narration ranges win over per-block audio-segment mapping and
+ * reading-time estimates.
+ */
+
+import type { Block, Doc, DocDiagnostic } from '../schemas/Doc.js';
+import type { MediaClip } from '../schemas/Media.js';
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import { estimateTimeFromText } from '../timing/narrationTiming.js';
+import { buildNarrationScript } from '../narration/script.js';
+import {
+  parseNarrationTimingJson,
+  type NarrationTimingBlock,
+  type NarrationTimingJsonV3,
+} from '../narration/sidecar.js';
+import { flattenRenderableBlocks, getBlockBodyText, getPinnedBlockMeta } from './markdownToDoc.js';
+import { scoreTextSimilarity } from './audioMapping.js';
+
+export interface NarrationResolution {
+  doc: Doc;
+  /** False → the doc is returned unchanged (no clip / no sidecar / no match). */
+  applied: boolean;
+  /** The narration media path, for callers that bundle assets. */
+  clipSrc?: string;
+}
+
+/** Minimum similarity for the fuzzy block-matching rung. */
+const MIN_BLOCK_SIMILARITY = 0.5;
+/** Minimum whole-script similarity for the v1 proportional fallback. */
+const MIN_V1_SCRIPT_SIMILARITY = 0.8;
+/** Pins that disagree with the narration range by more than this get a diagnostic. */
+const PIN_CONFLICT_TOLERANCE_SEC = 1;
+
+interface BlockRangeSec {
+  startSec: number;
+  endSec: number;
+}
+
+/** Spoken text of a block, mirroring the narration script builder. */
+function blockSpokenText(block: Block): string {
+  const title = block.title ? block.title.trim() : '';
+  const body = getBlockBodyText(block);
+  if (title && body) return `${title}\n${body}`;
+  return title || body;
+}
+
+/**
+ * Match sidecar block ranges to doc blocks with a deterministic ladder:
+ * exact blockId → text similarity (greedy best-first, ≥ 0.5) →
+ * in-order zip when the leftover counts agree. Unmatchable sidecar
+ * blocks are dropped.
+ */
+function matchSidecarBlocks(
+  flat: Block[],
+  timing: NarrationTimingJsonV3,
+): Map<string, BlockRangeSec> {
+  const ranges = new Map<string, BlockRangeSec>();
+  const remainingBlocks = new Set(flat.map((b) => b.id));
+  const remainingSidecar: NarrationTimingBlock[] = [];
+
+  const byId = new Map(flat.map((b) => [b.id, b]));
+  for (const entry of timing.blocks) {
+    if (entry.blockId && byId.has(entry.blockId) && remainingBlocks.has(entry.blockId)) {
+      ranges.set(entry.blockId, { startSec: entry.startSec, endSec: entry.endSec });
+      remainingBlocks.delete(entry.blockId);
+    } else {
+      remainingSidecar.push(entry);
+    }
+  }
+
+  // Fuzzy rung: greedy best pair first, each side used once.
+  if (remainingSidecar.length > 0 && remainingBlocks.size > 0) {
+    const candidates: Array<{ score: number; entry: NarrationTimingBlock; blockId: string }> = [];
+    for (const entry of remainingSidecar) {
+      const slice = timing.sourceText.slice(entry.charStart, entry.charEnd);
+      for (const block of flat) {
+        if (!remainingBlocks.has(block.id)) continue;
+        const score = scoreTextSimilarity(slice, blockSpokenText(block));
+        if (score >= MIN_BLOCK_SIMILARITY) candidates.push({ score, entry, blockId: block.id });
+      }
+    }
+    candidates.sort((a, b) => b.score - a.score || a.entry.blockIndex - b.entry.blockIndex);
+    const usedEntries = new Set<NarrationTimingBlock>();
+    for (const candidate of candidates) {
+      if (usedEntries.has(candidate.entry) || !remainingBlocks.has(candidate.blockId)) continue;
+      ranges.set(candidate.blockId, {
+        startSec: candidate.entry.startSec,
+        endSec: candidate.entry.endSec,
+      });
+      usedEntries.add(candidate.entry);
+      remainingBlocks.delete(candidate.blockId);
+    }
+    // Order rung: leftover counts equal → zip in document/sidecar order.
+    const leftoverEntries = remainingSidecar.filter((e) => !usedEntries.has(e));
+    if (leftoverEntries.length > 0 && leftoverEntries.length === remainingBlocks.size) {
+      const leftoverBlocks = flat.filter((b) => remainingBlocks.has(b.id));
+      leftoverEntries.sort((a, b) => a.blockIndex - b.blockIndex);
+      leftoverBlocks.forEach((block, i) => {
+        const entry = leftoverEntries[i];
+        ranges.set(block.id, { startSec: entry.startSec, endSec: entry.endSec });
+      });
+    }
+  }
+
+  return ranges;
+}
+
+/**
+ * v1 fallback: no block ranges in the sidecar. If the take's source
+ * text still narrates this doc (whole-script similarity ≥ 0.8), derive
+ * per-block ranges by spoken-word proportion.
+ */
+function proportionalRanges(
+  doc: Doc,
+  timing: NarrationTimingJsonV3,
+): Map<string, BlockRangeSec> | null {
+  const script = buildNarrationScript(doc);
+  if (script.blocks.length === 0) return null;
+  if (scoreTextSimilarity(script.sourceText, timing.sourceText) < MIN_V1_SCRIPT_SIMILARITY) {
+    return null;
+  }
+  const ranges = new Map<string, BlockRangeSec>();
+  const starts = script.blocks.map((range) =>
+    estimateTimeFromText(script.sourceText, range.charStart, timing.duration),
+  );
+  script.blocks.forEach((range, i) => {
+    ranges.set(range.blockId, {
+      startSec: starts[i],
+      endSec: i + 1 < starts.length ? starts[i + 1] : timing.duration,
+    });
+  });
+  return ranges;
+}
+
+interface RetimeContext {
+  clipStart: number;
+  ranges: Map<string, BlockRangeSec>;
+  diagnostics: DocDiagnostic[];
+  /** Timeline cursor (doc seconds) for unmatched blocks. */
+  cursor: number;
+}
+
+/** Recursively clone blocks, applying narration ranges to matched, unpinned blocks. */
+function retimeBlocks(blocks: Block[], ctx: RetimeContext): Block[] {
+  return blocks.map((block) => {
+    const range = ctx.ranges.get(block.id);
+    const pinned = getPinnedBlockMeta(block);
+    const next: Block = { ...block };
+
+    if (range && pinned.duration == null && pinned.startTime == null) {
+      next.startTime = ctx.clipStart + range.startSec;
+      next.duration = Math.max(0, range.endSec - range.startSec);
+      ctx.cursor = Math.max(ctx.cursor, next.startTime + next.duration);
+    } else if (range) {
+      // Author pins win; surface real disagreement as an info diagnostic.
+      const pinnedStart = pinned.startTime ?? block.startTime;
+      const pinnedDuration = pinned.duration ?? block.duration;
+      const narrStart = ctx.clipStart + range.startSec;
+      const narrDuration = Math.max(0, range.endSec - range.startSec);
+      if (
+        Math.abs(pinnedStart - narrStart) > PIN_CONFLICT_TOLERANCE_SEC ||
+        Math.abs(pinnedDuration - narrDuration) > PIN_CONFLICT_TOLERANCE_SEC
+      ) {
+        ctx.diagnostics.push({
+          severity: 'info',
+          code: 'narration-pin-conflict',
+          message:
+            `Block timing is pinned (duration=/startTime=) but the recorded narration says ` +
+            `~${narrDuration.toFixed(1)}s starting at ~${narrStart.toFixed(1)}s. The pin wins; ` +
+            `remove it to follow the narration.`,
+          blockId: block.id,
+        });
+      }
+      ctx.cursor = Math.max(ctx.cursor, pinnedStart + pinnedDuration);
+    } else {
+      // No narration range (block added after the take, or unmatched):
+      // keep its duration but place it at the running cursor so the
+      // timeline stays monotonic.
+      next.startTime = ctx.cursor;
+      ctx.cursor += next.duration;
+    }
+
+    if (block.children && block.children.length > 0) {
+      next.children = retimeBlocks(block.children, ctx);
+    }
+    return next;
+  });
+}
+
+/**
+ * Find the doc's document-anchored narration clip, load its timing
+ * sidecar, and re-time the blocks from its ranges. Pure with respect to
+ * the input doc — returns a new Doc (or the original when nothing
+ * applies).
+ */
+export async function applyNarrationTiming(
+  doc: Doc,
+  container: ContentContainer,
+): Promise<NarrationResolution> {
+  const clips: MediaClip[] = (doc.documentMedia ?? []).filter((c) => c.anchor === 'document');
+  for (const clip of clips) {
+    if (!clip.src) continue;
+    const sidecarData = await container.readFile(`${clip.src}.timing.json`);
+    if (!sidecarData) continue;
+    const timing = parseNarrationTimingJson(sidecarData);
+    if (!timing) continue;
+
+    const flat = flattenRenderableBlocks(doc.blocks);
+    const ranges =
+      timing.blocks.length > 0 ? matchSidecarBlocks(flat, timing) : proportionalRanges(doc, timing);
+    if (!ranges || ranges.size === 0) continue;
+
+    const ctx: RetimeContext = {
+      clipStart: clip.startAt,
+      ranges,
+      diagnostics: [],
+      cursor: 0,
+    };
+    const blocks = retimeBlocks(doc.blocks, ctx);
+    const duration = Math.max(clip.startAt + timing.duration, ctx.cursor);
+    const retimed: Doc = {
+      ...doc,
+      blocks,
+      duration,
+      ...(ctx.diagnostics.length > 0
+        ? { diagnostics: [...(doc.diagnostics ?? []), ...ctx.diagnostics] }
+        : {}),
+    };
+    return { doc: retimed, applied: true, clipSrc: clip.src };
+  }
+  return { doc, applied: false };
+}

package/src/doc/asciiDiagram/chars.ts

@@ -0,0 +1,210 @@
+/**
+ * Character classification for ASCII/Unicode box-and-line diagram art.
+ *
+ * The parse side accepts a superset (light/rounded/heavy/double Unicode
+ * box-drawing plus ASCII `+ - |` and both arrow families); the render
+ * side always emits one of the two `StyleVocab` tables below.
+ *
+ * Internal to the asciiDiagram module — not exported from the barrel.
+ */
+
+const TL_CORNERS = new Set(['┌', '╭', '┏', '╔']);
+const TR_CORNERS = new Set(['┐', '╮', '┓', '╗']);
+const BL_CORNERS = new Set(['└', '╰', '┗', '╚']);
+const BR_CORNERS = new Set(['┘', '╯', '┛', '╝']);
+const HORIZ = new Set(['─', '━', '═', '-']);
+const VERT = new Set(['│', '┃', '║', '|']);
+const JUNCTIONS = new Set([
+  '├',
+  '┤',
+  '┬',
+  '┴',
+  '┼',
+  '┣',
+  '┫',
+  '┳',
+  '┻',
+  '╋',
+  '╠',
+  '╣',
+  '╦',
+  '╩',
+  '╬',
+  '╞',
+  '╡',
+  '╥',
+  '╨',
+  '╫',
+  '╪',
+]);
+/** Junctions whose stems include a vertical component (legal on side borders). */
+const SIDE_JUNCTIONS = new Set(['├', '┤', '┼', '┣', '┫', '╋', '╠', '╣', '╬', '╞', '╡', '╫', '╪']);
+/** Junctions whose stems include a horizontal component (legal on top/bottom borders). */
+const FLAT_JUNCTIONS = new Set(['┬', '┴', '┼', '┳', '┻', '╋', '╦', '╩', '╬', '╥', '╨', '╫', '╪']);
+
+const ARROW_UP = new Set(['▲', '↑']);
+const ARROW_DOWN = new Set(['▼', '↓']);
+const ARROW_LEFT = new Set(['◄', '←', '◀']);
+const ARROW_RIGHT = new Set(['►', '→', '▶']);
+
+export type ArrowDirection = 'up' | 'down' | 'left' | 'right';
+
+export function isTlCorner(ch: string): boolean {
+  return TL_CORNERS.has(ch);
+}
+export function isTrCorner(ch: string): boolean {
+  return TR_CORNERS.has(ch);
+}
+export function isBlCorner(ch: string): boolean {
+  return BL_CORNERS.has(ch);
+}
+export function isBrCorner(ch: string): boolean {
+  return BR_CORNERS.has(ch);
+}
+export function isAnyCorner(ch: string): boolean {
+  return TL_CORNERS.has(ch) || TR_CORNERS.has(ch) || BL_CORNERS.has(ch) || BR_CORNERS.has(ch);
+}
+export function isHoriz(ch: string): boolean {
+  return HORIZ.has(ch);
+}
+export function isVert(ch: string): boolean {
+  return VERT.has(ch);
+}
+export function isJunction(ch: string): boolean {
+  return JUNCTIONS.has(ch);
+}
+export function isPlus(ch: string): boolean {
+  return ch === '+';
+}
+
+/** Acceptable interior of a top/bottom border walk (corners excluded). */
+export function isFlatBorderChar(ch: string): boolean {
+  return isHoriz(ch) || FLAT_JUNCTIONS.has(ch) || isPlus(ch);
+}
+
+/** Acceptable interior of a left/right border walk (corners excluded). */
+export function isSideBorderChar(ch: string): boolean {
+  return isVert(ch) || SIDE_JUNCTIONS.has(ch) || isPlus(ch);
+}
+
+/**
+ * Direction of an unconditional (Unicode) arrowhead, or null. ASCII
+ * `^ v < >` are ambiguous with prose and must be gated on an adjacent
+ * line character by the caller — use {@link asciiArrowDirection}.
+ */
+export function arrowDirection(ch: string): ArrowDirection | null {
+  if (ARROW_UP.has(ch)) return 'up';
+  if (ARROW_DOWN.has(ch)) return 'down';
+  if (ARROW_LEFT.has(ch)) return 'left';
+  if (ARROW_RIGHT.has(ch)) return 'right';
+  return null;
+}
+
+/** Direction for ASCII arrow candidates (`^ v V < >`); caller applies the adjacency gate. */
+export function asciiArrowDirection(ch: string): ArrowDirection | null {
+  if (ch === '^') return 'up';
+  if (ch === 'v' || ch === 'V') return 'down';
+  if (ch === '<') return 'left';
+  if (ch === '>') return 'right';
+  return null;
+}
+
+/** True for any character that can be part of an edge polyline (lines, turns, junctions). */
+export function isLineChar(ch: string): boolean {
+  return isHoriz(ch) || isVert(ch) || isJunction(ch) || isPlus(ch) || isAnyCorner(ch);
+}
+
+/** True for structural Unicode box-drawing characters (used for the style vote). */
+export function isUnicodeStructural(ch: string): boolean {
+  const code = ch.codePointAt(0) ?? 0;
+  // Box Drawing block U+2500–U+257F plus the arrow glyphs we emit.
+  return (
+    (code >= 0x2500 && code <= 0x257f) ||
+    ARROW_UP.has(ch) ||
+    ARROW_DOWN.has(ch) ||
+    ch === '←' ||
+    ch === '→' ||
+    ch === '◄' ||
+    ch === '►' ||
+    ch === '◀' ||
+    ch === '▶'
+  );
+}
+
+/** True for structural ASCII drawing characters (used for the style vote). */
+export function isAsciiStructural(ch: string): boolean {
+  return ch === '+' || ch === '-' || ch === '|';
+}
+
+export interface StyleVocab {
+  tl: string;
+  tr: string;
+  bl: string;
+  br: string;
+  h: string;
+  v: string;
+  /** Horizontal border cell with a stem descending below it (e.g. a line leaving a bottom border). */
+  stemDown: string;
+  /** Horizontal border cell with a stem ascending above it (e.g. a line arriving at a top border). */
+  stemUp: string;
+  /** Vertical border cell with a stem extending leftward. */
+  stemLeft: string;
+  /** Vertical border cell with a stem extending rightward. */
+  stemRight: string;
+  cross: string;
+  arrowUp: string;
+  arrowDown: string;
+  arrowLeft: string;
+  arrowRight: string;
+  /** Turn glyphs for routed edges: connects the two named directions. */
+  turnDownRight: string;
+  turnDownLeft: string;
+  turnUpRight: string;
+  turnUpLeft: string;
+}
+
+export const UNICODE_VOCAB: StyleVocab = {
+  tl: '┌',
+  tr: '┐',
+  bl: '└',
+  br: '┘',
+  h: '─',
+  v: '│',
+  stemDown: '┬',
+  stemUp: '┴',
+  stemLeft: '┤',
+  stemRight: '├',
+  cross: '┼',
+  arrowUp: '▲',
+  arrowDown: '▼',
+  arrowLeft: '◄',
+  arrowRight: '►',
+  // Named by the pair of open sides: e.g. turnDownRight opens downward and
+  // to the right (a line coming from below turning to the right) = '┌'.
+  turnDownRight: '┌',
+  turnDownLeft: '┐',
+  turnUpRight: '└',
+  turnUpLeft: '┘',
+};
+
+export const ASCII_VOCAB: StyleVocab = {
+  tl: '+',
+  tr: '+',
+  bl: '+',
+  br: '+',
+  h: '-',
+  v: '|',
+  stemDown: '+',
+  stemUp: '+',
+  stemLeft: '+',
+  stemRight: '+',
+  cross: '+',
+  arrowUp: '^',
+  arrowDown: 'v',
+  arrowLeft: '<',
+  arrowRight: '>',
+  turnDownRight: '+',
+  turnDownLeft: '+',
+  turnUpRight: '+',
+  turnUpLeft: '+',
+};

package/src/doc/asciiDiagram/detect.ts

@@ -0,0 +1,175 @@
+/**
+ * ASCII diagram detection: is this fence content a box-and-line diagram?
+ *
+ * False positives are the expensive failure (they hide real code behind a
+ * canvas / template); false negatives just leave a code block alone. Every
+ * rejection path records a machine-greppable reason so the corpus tests
+ * act as the contract for any future threshold tuning.
+ */
+
+import type { MarkdownCodeBlock } from '../../markdown/types.js';
+import { parseAsciiDiagramWithStats } from './parse.js';
+import type { AsciiDiagramDetection } from './types.js';
+
+/** Fence languages eligible for diagram detection (plus no language at all). */
+export const ASCII_DIAGRAM_FENCE_LANGS: ReadonlySet<string> = new Set([
+  'text',
+  'txt',
+  'plaintext',
+  'plain',
+  'ascii',
+  'diagram',
+]);
+
+const MAX_LINES = 400;
+const MAX_COLS = 400;
+const MIN_LINES = 3;
+const MAX_LOOSE_RATIO = 0.25;
+
+/**
+ * Box-drawing corners, junctions, and (Unicode) verticals — characters that
+ * signal a box border leaked into a node's label, i.e. a mis-aligned parse.
+ * ASCII `|`/`+`/`-` and the horizontal `─` are excluded: they occur in real
+ * label text (`stdin | stdout`, `read-only`, `A + B`).
+ */
+const STRUCTURAL_IN_LABEL = /[│┃║┌┐└┘├┤┬┴┼╭╮╰╯┏┓┗┛╔╗╚╝┣┫┳┻╋╠╣╦╩╬╞╡╥╨╫╪]/;
+
+export function isEligibleAsciiFenceLang(lang: string | null | undefined): boolean {
+  if (lang === null || lang === undefined) return true;
+  const normalized = lang.trim().toLowerCase();
+  return normalized === '' || ASCII_DIAGRAM_FENCE_LANGS.has(normalized);
+}
+
+/**
+ * True when the fence LANGUAGE is the explicit `diagram` tag — an author-set
+ * "this is a diagram" marker that survives round-trips (the language class
+ * round-trips; fence meta does not). Detection of a tagged fence is lenient
+ * (≥1 box, no lattice rejector) so a degenerate diagram stays a diagram.
+ */
+export function isExplicitDiagramLang(lang: string | null | undefined): boolean {
+  return typeof lang === 'string' && lang.trim().toLowerCase() === 'diagram';
+}
+
+export interface DetectDiagramOptions {
+  /** The fence is explicitly `diagram`-tagged: accept ≥1 box, skip rejectors. */
+  explicit?: boolean;
+}
+
+export function detectAsciiDiagram(
+  text: string,
+  opts: DetectDiagramOptions = {},
+): AsciiDiagramDetection {
+  const explicit = opts.explicit === true;
+  const reasons: string[] = [];
+
+  // ---- Cheap prefilter (no parse) ----------------------------------------
+  const lines = text.replace(/\r\n?/g, '\n').split('\n');
+  if (lines.length < MIN_LINES) {
+    return { isDiagram: false, reasons: [`too-few-lines(${lines.length})`] };
+  }
+  if (lines.length > MAX_LINES) {
+    return { isDiagram: false, reasons: [`too-many-lines(${lines.length})`] };
+  }
+  let maxCols = 0;
+  for (const line of lines) maxCols = Math.max(maxCols, line.length);
+  if (maxCols > MAX_COLS) {
+    return { isDiagram: false, reasons: [`too-wide(${maxCols})`] };
+  }
+
+  if (!explicit) {
+    let tlCandidates = 0;
+    for (const line of lines) {
+      // Unicode TL corners, junction-started shared borders (`├──`), and
+      // ASCII `+-` starts. Junctions over-count (file trees use `├──`), but
+      // the prefilter only gates the full parse — box tracing decides.
+      const unicodeMatches = line.match(/[┌╭┏╔]|[├┬┼┣┳╋╠╦╬][─━═]/gu);
+      tlCandidates += unicodeMatches ? unicodeMatches.length : 0;
+      const plusMatches = line.match(/\+[-+]/g);
+      tlCandidates += plusMatches ? plusMatches.length : 0;
+    }
+    if (tlCandidates < 2) {
+      return { isDiagram: false, reasons: [`too-few-corner-candidates(${tlCandidates})`] };
+    }
+  }
+
+  // Markdown/GFM table shape: mostly `| … |` rows plus a separator row.
+  const nonBlank = lines.filter((l) => l.trim().length > 0);
+  const pipeRows = nonBlank.filter((l) => /^\s*\|.*\|\s*$/.test(l)).length;
+  const hasGfmSeparator = nonBlank.some((l) => /^\s*\|?[\s:|-]+\|?\s*$/.test(l) && l.includes('-'));
+  if (pipeRows > nonBlank.length / 2 && hasGfmSeparator) {
+    return { isDiagram: false, reasons: ['markdown-table'] };
+  }
+
+  // ---- Full parse + acceptance -------------------------------------------
+  const { diagram, stats } = parseAsciiDiagramWithStats(text);
+
+  const minBoxes = explicit ? 1 : 2;
+  if (diagram.nodes.length < minBoxes) {
+    return { isDiagram: false, reasons: [`too-few-boxes(${diagram.nodes.length})`] };
+  }
+
+  // Garbled-label guard: a clean box label never contains box-drawing
+  // corners/junctions/verticals — those only leak in when the label columns
+  // are desynced from the box borders (hand-drawn art whose labels overflow
+  // their boxes and shove every following column out of alignment row-to-row,
+  // so no parser can map the text back to the boxes). When a meaningful share
+  // of labels are corrupt this way, the "diagram" would render as garbage, so
+  // decline detection and let the fence fall back to a faithful code block.
+  const garbled = diagram.nodes.filter((n) => STRUCTURAL_IN_LABEL.test(n.label)).length;
+  if (garbled > 0 && garbled >= diagram.nodes.length * 0.25) {
+    return { isDiagram: false, reasons: [`garbled-labels(${garbled}/${diagram.nodes.length})`] };
+  }
+
+  if (!explicit) {
+    // Table-lattice rejector: an edge-less shared-border grid of ≥2×2 boxes
+    // is a psql/MySQL-style result table, not a diagram. Single-column
+    // stacks still pass (a legitimate "layer stack" diagram).
+    if (diagram.edges.length === 0 && diagram.nodes.length >= 4 && isLattice(diagram)) {
+      return { isDiagram: false, reasons: ['table-lattice'] };
+    }
+    if (stats.totalNonSpaceCells > 0) {
+      const looseRatio = stats.looseNonSpaceCells / stats.totalNonSpaceCells;
+      if (looseRatio > MAX_LOOSE_RATIO) {
+        return { isDiagram: false, reasons: [`loose-ratio(${looseRatio.toFixed(2)})`] };
+      }
+    }
+  }
+
+  reasons.push(`boxes(${diagram.nodes.length})`, `edges(${diagram.edges.length})`);
+  if (explicit) reasons.push('explicit');
+  return { isDiagram: true, diagram, reasons };
+}
+
+/** Convenience gate for pipeline callers: lang allowlist + content detection. */
+export function isAsciiDiagramFence(node: MarkdownCodeBlock): boolean {
+  if (node.type !== 'code') return false;
+  if (!isEligibleAsciiFenceLang(node.lang)) return false;
+  return detectAsciiDiagram(node.value, { explicit: isExplicitDiagramLang(node.lang) }).isDiagram;
+}
+
+function isLattice(diagram: {
+  nodes: ReadonlyArray<{
+    col: number;
+    row: number;
+    wCols: number;
+    hRows: number;
+    containerId?: string;
+  }>;
+}): boolean {
+  const leaves = diagram.nodes.filter((n) => !n.containerId);
+  if (leaves.length < 4) return false;
+  const rowBands = new Set(leaves.map((n) => n.row));
+  const colBands = new Set(leaves.map((n) => n.col));
+  if (rowBands.size < 2 || colBands.size < 2) return false;
+  // Every box shares a border line with some other box.
+  return leaves.every((a) =>
+    leaves.some((b) => {
+      if (a === b) return false;
+      const aR1 = a.row + a.hRows - 1;
+      const aC1 = a.col + a.wCols - 1;
+      const bR1 = b.row + b.hRows - 1;
+      const bC1 = b.col + b.wCols - 1;
+      return a.row === bR1 || aR1 === b.row || a.col === bC1 || aC1 === b.col;
+    }),
+  );
+}