@bendyline/squisq 1.5.2 → 2.0.1

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

package/src/doc/asciiDiagram/index.ts

@@ -0,0 +1,38 @@
+/**
+ * ASCII diagram codec: detect / parse / render box-and-line art, plus
+ * mapping helpers between the grid model and the diagram canvas model.
+ *
+ * The fence text is the source of truth end-to-end: the editor parses it
+ * live for an interactive canvas and re-renders it after each semantic
+ * edit; the doc pipeline derives `templateData.nodes`/`edges` from it so
+ * preview/player/exports show the same diagram.
+ */
+
+export { parseAsciiDiagram, parseAsciiDiagramWithStats } from './parse.js';
+export type { AsciiParseStats } from './parse.js';
+export { renderAsciiDiagram } from './render.js';
+export type { RenderAsciiDiagramOptions } from './render.js';
+export {
+  ASCII_DIAGRAM_FENCE_LANGS,
+  detectAsciiDiagram,
+  isAsciiDiagramFence,
+  isEligibleAsciiFenceLang,
+  isExplicitDiagramLang,
+} from './detect.js';
+export type { DetectDiagramOptions } from './detect.js';
+export { repairAsciiDiagram, isRepairableDiagram } from './repair.js';
+export type { RepairResult } from './repair.js';
+export {
+  asciiCellToCanvas,
+  asciiDiagramFromBlocks,
+  asciiDiagramFromTemplateData,
+  asciiDiagramToTemplateData,
+  canvasToAsciiCell,
+} from './mapping.js';
+export { ASCII_CHAR_H, ASCII_CHAR_W } from './types.js';
+export type {
+  AsciiDiagram,
+  AsciiDiagramDetection,
+  AsciiDiagramEdge,
+  AsciiDiagramNode,
+} from './types.js';

package/src/doc/asciiDiagram/mapping.ts

@@ -0,0 +1,225 @@
+/**
+ * Mapping between the grid-native ASCII diagram model and the diagram
+ * canvas / template model (canvas units, the same space as `Block.x`/`y`).
+ *
+ * Quantization uses plain `round()` per axis — monotonic and local, so a
+ * small canvas nudge either changes nothing or moves exactly one cell
+ * (cluster-based schemes flap under small moves and churn the art).
+ */
+
+import type {
+  DiagramEdgeAnchor,
+  DiagramTemplateEdge,
+  DiagramTemplateNode,
+} from '../../schemas/BlockTemplates.js';
+import type { Block } from '../../schemas/Doc.js';
+import { computeDiagramLayout } from '../templates/diagramLayout.js';
+import {
+  ASCII_CHAR_H,
+  ASCII_CHAR_W,
+  type AsciiDiagram,
+  type AsciiDiagramEdge,
+  type AsciiDiagramNode,
+} from './types.js';
+
+export function asciiCellToCanvas(col: number, row: number): { x: number; y: number } {
+  return { x: col * ASCII_CHAR_W, y: row * ASCII_CHAR_H };
+}
+
+export function canvasToAsciiCell(x: number, y: number): { col: number; row: number } {
+  return {
+    col: Math.max(0, Math.round(x / ASCII_CHAR_W)),
+    row: Math.max(0, Math.round(y / ASCII_CHAR_H)),
+  };
+}
+
+/** Grid model → template/canvas model (`templateData.nodes`/`edges`). */
+export function asciiDiagramToTemplateData(diagram: AsciiDiagram): {
+  nodes: DiagramTemplateNode[];
+  edges: DiagramTemplateEdge[];
+} {
+  const nodes: DiagramTemplateNode[] = diagram.nodes.map((n) => ({
+    id: n.id,
+    label: n.label,
+    ...asciiCellToCanvas(n.col, n.row),
+    w: n.wCols * ASCII_CHAR_W,
+    h: n.hRows * ASCII_CHAR_H,
+    ...(n.containerId ? { container: n.containerId } : {}),
+  }));
+  const anchors = inferEdgeAnchors(nodes, diagram.edges);
+  const edges: DiagramTemplateEdge[] = diagram.edges.map((e, index) => ({
+    source: e.source,
+    target: e.target,
+    ...(e.label ? { label: e.label } : {}),
+    ...(e.directed ? {} : { directed: false }),
+    ...anchors[index],
+    routing: 'orthogonal',
+  }));
+  return { nodes, edges };
+}
+
+interface EdgeAnchorPair {
+  sourceAnchor: DiagramEdgeAnchor;
+  targetAnchor: DiagramEdgeAnchor;
+}
+
+/**
+ * Recover the visual intent carried by orthogonal ASCII art. Fan-out ports
+ * spread across the source face; fan-in ports spread across the target face.
+ * A single endpoint stays centered on its facing side.
+ */
+function inferEdgeAnchors(
+  nodes: readonly DiagramTemplateNode[],
+  edges: readonly AsciiDiagramEdge[],
+): EdgeAnchorPair[] {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const pairs = edges.map((edge) => {
+    const source = nodeById.get(edge.source);
+    const target = nodeById.get(edge.target);
+    if (!source || !target) {
+      return {
+        sourceAnchor: { side: 'right' as const, offset: 0.5 },
+        targetAnchor: { side: 'left' as const, offset: 0.5 },
+      };
+    }
+    const sourceW = source.w ?? ASCII_CHAR_W * 12;
+    const sourceH = source.h ?? ASCII_CHAR_H * 3;
+    const targetW = target.w ?? ASCII_CHAR_W * 12;
+    const targetH = target.h ?? ASCII_CHAR_H * 3;
+    const dx = target.x + targetW / 2 - (source.x + sourceW / 2);
+    const dy = target.y + targetH / 2 - (source.y + sourceH / 2);
+    const horizontalDistance = Math.abs(dx) / Math.max(1, (sourceW + targetW) / 2);
+    const verticalDistance = Math.abs(dy) / Math.max(1, (sourceH + targetH) / 2);
+    if (verticalDistance >= horizontalDistance) {
+      return dy >= 0
+        ? {
+            sourceAnchor: { side: 'bottom' as const, offset: 0.5 },
+            targetAnchor: { side: 'top' as const, offset: 0.5 },
+          }
+        : {
+            sourceAnchor: { side: 'top' as const, offset: 0.5 },
+            targetAnchor: { side: 'bottom' as const, offset: 0.5 },
+          };
+    }
+    return dx >= 0
+      ? {
+          sourceAnchor: { side: 'right' as const, offset: 0.5 },
+          targetAnchor: { side: 'left' as const, offset: 0.5 },
+        }
+      : {
+          sourceAnchor: { side: 'left' as const, offset: 0.5 },
+          targetAnchor: { side: 'right' as const, offset: 0.5 },
+        };
+  });
+
+  distributeOffsets(pairs, edges, nodes, 'source');
+  distributeOffsets(pairs, edges, nodes, 'target');
+  return pairs;
+}
+
+function distributeOffsets(
+  pairs: EdgeAnchorPair[],
+  edges: readonly AsciiDiagramEdge[],
+  nodes: readonly DiagramTemplateNode[],
+  endpoint: 'source' | 'target',
+): void {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const groups = new Map<string, number[]>();
+  for (let index = 0; index < edges.length; index++) {
+    const edge = edges[index];
+    const anchor = endpoint === 'source' ? pairs[index].sourceAnchor : pairs[index].targetAnchor;
+    const nodeId = endpoint === 'source' ? edge.source : edge.target;
+    const key = `${nodeId}:${anchor.side}`;
+    const group = groups.get(key) ?? [];
+    group.push(index);
+    groups.set(key, group);
+  }
+  for (const indexes of groups.values()) {
+    if (indexes.length < 2) continue;
+    const side =
+      endpoint === 'source'
+        ? pairs[indexes[0]].sourceAnchor.side
+        : pairs[indexes[0]].targetAnchor.side;
+    indexes.sort((a, b) => {
+      const oppositeA = nodeById.get(endpoint === 'source' ? edges[a].target : edges[a].source);
+      const oppositeB = nodeById.get(endpoint === 'source' ? edges[b].target : edges[b].source);
+      const axisA = side === 'top' || side === 'bottom' ? (oppositeA?.x ?? 0) : (oppositeA?.y ?? 0);
+      const axisB = side === 'top' || side === 'bottom' ? (oppositeB?.x ?? 0) : (oppositeB?.y ?? 0);
+      return axisA - axisB || a - b;
+    });
+    indexes.forEach((edgeIndex, rank) => {
+      const anchor =
+        endpoint === 'source' ? pairs[edgeIndex].sourceAnchor : pairs[edgeIndex].targetAnchor;
+      anchor.offset = (rank + 1) / (indexes.length + 1);
+    });
+  }
+}
+
+/** Template/canvas model → grid model, quantizing positions and sizes. */
+export function asciiDiagramFromTemplateData(
+  nodes: readonly DiagramTemplateNode[],
+  edges: readonly DiagramTemplateEdge[],
+  options: { style?: 'unicode' | 'ascii' } = {},
+): AsciiDiagram {
+  const ids = new Set(nodes.map((n) => n.id));
+  const outNodes: AsciiDiagramNode[] = nodes.map((n) => {
+    const { col, row } = canvasToAsciiCell(n.x, n.y);
+    const labelLines = n.label.length > 0 ? n.label.split('\n') : [];
+    const innerW = labelLines.reduce((w, l) => Math.max(w, l.length), 0);
+    const wCols =
+      typeof n.w === 'number' ? Math.max(3, Math.round(n.w / ASCII_CHAR_W)) : innerW + 4;
+    const hRows =
+      typeof n.h === 'number' ? Math.max(3, Math.round(n.h / ASCII_CHAR_H)) : labelLines.length + 2;
+    return {
+      id: n.id,
+      label: n.label,
+      col,
+      row,
+      wCols: Math.max(wCols, 3),
+      hRows: Math.max(hRows, 3),
+      ...(n.container && ids.has(n.container) && n.container !== n.id
+        ? { containerId: n.container }
+        : {}),
+    };
+  });
+  return {
+    nodes: outNodes,
+    edges: edges
+      .filter((e) => ids.has(e.source) && ids.has(e.target))
+      .map((e) => ({
+        source: e.source,
+        target: e.target,
+        ...(e.label ? { label: e.label } : {}),
+        directed: e.directed !== false,
+      })),
+    style: options.style ?? 'unicode',
+    warnings: [],
+  };
+}
+
+/**
+ * Legacy heading-based diagram children → ASCII diagram model. Used to
+ * migrate `### Node {#id x= y= connectsTo=}` sections to ASCII fences;
+ * positions run through the shared `computeDiagramLayout` so unpinned
+ * children get the same grid placement as the legacy renderer.
+ */
+export function asciiDiagramFromBlocks(
+  children: readonly Block[],
+  options: { style?: 'unicode' | 'ascii' } = {},
+): AsciiDiagram {
+  const layout = computeDiagramLayout(children);
+  const nodes: DiagramTemplateNode[] = layout.nodes.map((n) => ({
+    id: n.id,
+    label: n.label,
+    x: n.x,
+    y: n.y,
+  }));
+  const edges: DiagramTemplateEdge[] = layout.edges.map((e) => ({
+    source: e.source,
+    target: e.target,
+    ...(e.type ? { label: e.type } : {}),
+  }));
+  const diagram = asciiDiagramFromTemplateData(nodes, edges, options);
+  diagram.warnings.push(...layout.warnings);
+  return diagram;
+}