@bendyline/squisq 1.5.2 → 2.0.0

package/src/doc/templates/treeBlock.ts

@@ -0,0 +1,131 @@
+/**
+ * Tree Template
+ *
+ * Renders a hierarchical filesystem-style treeview (folder/file icons +
+ * connector rails, collapsible in the live player) from an ASCII tree fence.
+ * Emits a single `TreeLayer` (foreignObject HTML, like `dataTable`) plus an
+ * optional title + themed background.
+ *
+ * Data source: `input.items` (a nested `TreeLayerItem[]`), populated from
+ * `templateData.items` which the pipeline derives from the tree fence.
+ */
+
+import type { Layer, TreeLayerItem } from '../../schemas/Doc.js';
+import type { TreeBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import {
+  getThemeFont,
+  resolveColorScheme,
+  shouldUseShadow,
+  themedFontSize,
+  themedSurfaceGradient,
+} from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
+import { createBackgroundLayer } from './captionUtils.js';
+
+/** Defensive coercion of untyped `templateData.items` into valid tree items. */
+function coerceItems(raw: unknown): TreeLayerItem[] {
+  if (!Array.isArray(raw)) return [];
+  const out: TreeLayerItem[] = [];
+  for (const r of raw) {
+    if (typeof r !== 'object' || r === null) continue;
+    const item = r as Record<string, unknown>;
+    if (typeof item.label !== 'string') continue;
+    const children = coerceItems(item.children);
+    out.push({
+      id: typeof item.id === 'string' && item.id ? item.id : slug(item.label),
+      label: item.label,
+      children,
+      ...(item.isDir === true || children.length > 0 ? { isDir: true } : {}),
+      ...(typeof item.comment === 'string' && item.comment ? { comment: item.comment } : {}),
+    });
+  }
+  return out;
+}
+
+function slug(s: string): string {
+  return (
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'node'
+  );
+}
+
+export function treeBlock(input: TreeBlockInput, context: TemplateContext): Layer[] {
+  const { theme, viewport } = context;
+  const colors = resolveColorScheme(context, input.colorScheme);
+  const items = coerceItems(input.items);
+
+  const titleFontSize = themedFontSize(48, context, true);
+  const rowFontSize = themedFontSize(28, context, false);
+
+  const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 170))];
+
+  if (items.length === 0) {
+    layers.push({
+      type: 'text',
+      id: 'tree-empty',
+      content: {
+        text: input.title ?? 'Empty tree',
+        style: {
+          fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
+          color: theme.colors.textMuted,
+          textAlign: 'center',
+        },
+      },
+      position: { x: '50%', y: '50%', anchor: 'center' },
+    });
+    return layers;
+  }
+
+  const titleBandPct = input.title ? (titleFontSize * 2.2 * 100) / viewport.height : 0;
+
+  if (input.title) {
+    layers.push({
+      type: 'text',
+      id: 'title',
+      content: {
+        text: input.title,
+        style: {
+          fontSize: titleFontSize,
+          fontFamily: getThemeFont(context, 'title'),
+          fontWeight: 'bold',
+          color: theme.colors.text,
+          textAlign: 'center',
+          shadow: shouldUseShadow(context),
+        },
+      },
+      position: { x: '50%', y: `${8 + titleBandPct / 2}%`, width: '80%', anchor: 'center' },
+      animation: { type: 'fadeIn', duration: 0.8 },
+    });
+  }
+
+  layers.push({
+    type: 'tree',
+    id: 'tree',
+    content: {
+      items,
+      style: {
+        rowColor: theme.colors.text,
+        dirColor: colors.accent ?? theme.colors.primary,
+        connectorColor: withAlpha(theme.colors.text, 0.25),
+        iconColor: colors.accent ?? theme.colors.primary,
+        commentColor: theme.colors.textMuted,
+        fontSize: rowFontSize,
+        fontFamily: getThemeFont(context, 'body'),
+        monoFontFamily: getThemeFont(context, 'mono'),
+        indentPx: Math.round(rowFontSize * 1.4),
+      },
+    },
+    position: {
+      x: '10%',
+      y: `${8 + titleBandPct}%`,
+      width: '80%',
+      height: `${Math.max(60, 90 - titleBandPct)}%`,
+    },
+    animation: { type: 'fadeIn', duration: 1, delay: input.title ? 0.4 : 0 },
+  });
+
+  return layers;
+}

package/src/doc/treeview/chars.ts

@@ -0,0 +1,72 @@
+/**
+ * Character classification + render vocabularies for ASCII tree art.
+ *
+ * The parser accepts a superset (Unicode light/heavy/rounded branches plus
+ * ASCII `|-- ` / `` `-- `` / `+-- `); the renderer emits one `TreeVocab`.
+ * Internal to the treeview module.
+ */
+
+/** Vertical rail glyphs (an ancestor line continuing downward). */
+const RAIL_CHARS = new Set(['│', '┃', '╎', '╏', '║', '|']);
+/** Branch-tee glyphs (a node that has a following sibling). */
+const BRANCH_TEE = new Set(['├', '┣', '┠', '┝', '╠', '╞']);
+/** Branch-elbow glyphs (the last child). */
+const BRANCH_ELBOW = new Set(['└', '┗', '╰', '╚', '╘']);
+/** Horizontal dash glyphs used in a branch arm. */
+const DASH_CHARS = new Set(['─', '━', '═', '-']);
+
+export function isRailChar(ch: string): boolean {
+  return RAIL_CHARS.has(ch);
+}
+export function isBranchTee(ch: string): boolean {
+  return BRANCH_TEE.has(ch);
+}
+export function isBranchElbow(ch: string): boolean {
+  return BRANCH_ELBOW.has(ch);
+}
+export function isUnicodeBranch(ch: string): boolean {
+  return BRANCH_TEE.has(ch) || BRANCH_ELBOW.has(ch);
+}
+export function isDashChar(ch: string): boolean {
+  return DASH_CHARS.has(ch);
+}
+
+/** Structural glyphs used for the style vote. */
+export function isUnicodeTreeChar(ch: string): boolean {
+  return (
+    BRANCH_TEE.has(ch) ||
+    BRANCH_ELBOW.has(ch) ||
+    ch === '│' ||
+    ch === '┃' ||
+    ch === '─' ||
+    ch === '━'
+  );
+}
+export function isAsciiTreeChar(ch: string): boolean {
+  return ch === '|' || ch === '`' || ch === '+' || ch === '-';
+}
+
+export interface TreeVocab {
+  /** Branch to a node that has a later sibling (`├── `). */
+  tee: string;
+  /** Branch to the last child (`└── `). */
+  elbow: string;
+  /** Ancestor rail column (`│   `). */
+  rail: string;
+  /** Ended-ancestor gap column (`    `). */
+  gap: string;
+}
+
+export const UNICODE_TREE_VOCAB: TreeVocab = {
+  tee: '├── ',
+  elbow: '└── ',
+  rail: '│   ',
+  gap: '    ',
+};
+
+export const ASCII_TREE_VOCAB: TreeVocab = {
+  tee: '|-- ',
+  elbow: '`-- ',
+  rail: '|   ',
+  gap: '    ',
+};

package/src/doc/treeview/detect.ts

@@ -0,0 +1,145 @@
+/**
+ * ASCII tree detection: is this fence content a file-tree / outline?
+ *
+ * The mirror image of the diagram detector. A diagram has ≥2 closed boxes;
+ * a tree has ZERO closed boxes plus connector-branch structure. The two
+ * partition the `├──` glyph space cleanly, so a fence is at most one of
+ * them. Auto-detection is deliberately conservative (requires connector
+ * branches — the unambiguous AI file-tree signal); the parser still handles
+ * pure-indentation renditions for explicitly `{[tree]}`-annotated fences.
+ */
+
+import type { MarkdownCodeBlock } from '../../markdown/types.js';
+import { parseAsciiDiagramWithStats } from '../asciiDiagram/parse.js';
+import { detectAsciiTimeline } from '../asciiTimeline/detect.js';
+import { parseTreeWithStats } from './parse.js';
+import type { TreeDetection } from './types.js';
+
+/** Fence languages eligible for tree detection (plus no language at all). */
+export const TREE_FENCE_LANGS: ReadonlySet<string> = new Set([
+  'text',
+  'txt',
+  'plaintext',
+  'plain',
+  'ascii',
+  'tree',
+]);
+
+const MAX_LINES = 400;
+const MIN_LINES = 2;
+const MIN_CONNECTOR_LINES = 2;
+const MIN_NODES = 2;
+
+/**
+ * Box-drawing corners a file tree NEVER contains: top-left/right and
+ * bottom-right in light, heavy, double, and rounded weights. Bottom-LEFT
+ * corners (└ ┗ ╰ ╚ ╘) are excluded — the tree codec uses them as elbows.
+ */
+const BOX_CORNER_RE = /[┌┐┘┏┓┛╔╗╝╭╮╯]/u;
+
+export function isEligibleTreeFenceLang(lang: string | null | undefined): boolean {
+  if (lang === null || lang === undefined) return true;
+  const normalized = lang.trim().toLowerCase();
+  return normalized === '' || TREE_FENCE_LANGS.has(normalized);
+}
+
+/**
+ * True when the fence LANGUAGE is the explicit `tree` tag — an author-set
+ * "this is a tree" marker that survives markdown ↔ Tiptap round-trips (the
+ * language class round-trips; fence meta does not). Detection of a tagged
+ * fence is lenient (no connector requirement) so a flattened/degenerate
+ * tree stays a tree.
+ */
+export function isExplicitTreeLang(lang: string | null | undefined): boolean {
+  return typeof lang === 'string' && lang.trim().toLowerCase() === 'tree';
+}
+
+export interface DetectTreeOptions {
+  /** The fence is explicitly `tree`-tagged: skip the connector requirement. */
+  explicit?: boolean;
+}
+
+export function detectTree(text: string, opts: DetectTreeOptions = {}): TreeDetection {
+  const explicit = opts.explicit === true;
+  const lines = text.replace(/\r\n?/g, '\n').split('\n');
+  const nonBlank = lines.filter((l) => l.trim().length > 0);
+  // A `tree`-tagged fence can be a single-node tree (e.g. the outline edited
+  // down to one item); an untagged fence needs ≥2 lines to auto-detect.
+  const minLines = explicit ? 1 : MIN_LINES;
+  if (nonBlank.length < minLines) {
+    return { isTree: false, reasons: [`too-few-lines(${nonBlank.length})`] };
+  }
+  if (lines.length > MAX_LINES) {
+    return { isTree: false, reasons: [`too-many-lines(${lines.length})`] };
+  }
+
+  // Markdown/GFM table shape → not a tree (even when explicitly tagged; it
+  // wouldn't parse into a sensible hierarchy anyway).
+  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 { isTree: false, reasons: ['markdown-table'] };
+  }
+
+  // Box-drawing CORNERS are an unambiguous box-diagram signal. A file tree /
+  // outline is built only from tees (├), elbows (└ ┗ ╰), rails (│), and dashes
+  // (─) — it never contains a TOP corner (┌ ┐) or a BOTTOM-RIGHT corner (┘).
+  // A fence with those is a diagram, even a MALFORMED one whose borders are
+  // misaligned so the tracer finds <2 closed boxes (e.g. hand-drawn art
+  // knocked out of alignment by a later rename that widened the labels).
+  // Without this, such art falls through to a mangled treeview. (Bottom-LEFT
+  // corners └ ┗ ╰ ╚ ╘ are deliberately excluded — they double as tree elbows.)
+  if (BOX_CORNER_RE.test(text)) {
+    return { isTree: false, reasons: ['has-box-corners'] };
+  }
+
+  // Timeline callout elbows can resemble tree branches. Give a qualifying
+  // marker+axis timeline ownership before the loose tree parser sees it.
+  if (!explicit && detectAsciiTimeline(text).isTimeline) {
+    return { isTree: false, reasons: ['is-timeline'] };
+  }
+
+  // Mutual exclusion with the diagram codec: a fence with ≥2 closed boxes is
+  // a diagram, not a tree.
+  const boxes = parseAsciiDiagramWithStats(text).diagram.nodes.length;
+  if (boxes >= 2) {
+    return { isTree: false, reasons: [`has-boxes(${boxes})`] };
+  }
+
+  const { tree, stats } = parseTreeWithStats(text);
+  const nodeCount = countNodes(tree.roots);
+  const minNodes = explicit ? 1 : MIN_NODES;
+  if (nodeCount < minNodes) {
+    return { isTree: false, reasons: [`too-few-nodes(${nodeCount})`] };
+  }
+  if (!explicit) {
+    // Auto-detection of an UNTAGGED fence requires the connector signal
+    // (pure-indentation art could be prose or a list). A `tree`-tagged fence
+    // trusts the author and skips this.
+    if (stats.connectorLines < MIN_CONNECTOR_LINES) {
+      return { isTree: false, reasons: [`too-few-connectors(${stats.connectorLines})`] };
+    }
+    if (stats.looseLines > stats.contentLines * 0.25) {
+      return { isTree: false, reasons: [`loose-ratio(${stats.looseLines}/${stats.contentLines})`] };
+    }
+  }
+
+  return {
+    isTree: true,
+    tree,
+    reasons: [`nodes(${nodeCount})`, explicit ? 'explicit' : `connectors(${stats.connectorLines})`],
+  };
+}
+
+/** Convenience gate for pipeline callers: lang allowlist + content detection. */
+export function isTreeFence(node: MarkdownCodeBlock): boolean {
+  if (node.type !== 'code') return false;
+  if (!isEligibleTreeFenceLang(node.lang)) return false;
+  return detectTree(node.value, { explicit: isExplicitTreeLang(node.lang) }).isTree;
+}
+
+function countNodes(nodes: readonly import('./types.js').TreeNode[]): number {
+  let n = 0;
+  for (const node of nodes) n += 1 + countNodes(node.children);
+  return n;
+}

package/src/doc/treeview/index.ts

@@ -0,0 +1,30 @@
+/**
+ * ASCII treeview codec: detect / parse / render file-tree & outline art,
+ * plus mapping helpers between the tree model and the template/layer data.
+ *
+ * The fence text is the source of truth end-to-end: the editor parses it
+ * live for an interactive outline and re-renders it after each edit; the
+ * doc pipeline derives `templateData.items` from it so the player renders
+ * the same tree. Peer to the ASCII diagram codec.
+ */
+
+export { parseTree, parseTreeWithStats } from './parse.js';
+export type { TreeLineStats } from './parse.js';
+export { renderTree } from './render.js';
+export type { RenderTreeOptions } from './render.js';
+export {
+  detectTree,
+  isTreeFence,
+  isEligibleTreeFenceLang,
+  isExplicitTreeLang,
+  TREE_FENCE_LANGS,
+} from './detect.js';
+export type { DetectTreeOptions } from './detect.js';
+export {
+  treeToTemplateData,
+  treeFromTemplateData,
+  treeFromMarkdownList,
+  findFirstList,
+} from './mapping.js';
+export type { TreeItem } from './mapping.js';
+export type { Tree, TreeNode, TreeDetection } from './types.js';

package/src/doc/treeview/mapping.ts

@@ -0,0 +1,95 @@
+/**
+ * Mapping between the tree model and the template/layer data model, plus a
+ * nested-markdown-list → tree walker (none exists in core — `extractListItems`
+ * flattens, losing depth).
+ */
+
+import type { MarkdownBlockNode, MarkdownList, MarkdownListItem } from '../../markdown/types.js';
+import { extractPlainText } from '../../markdown/utils.js';
+import type { Tree, TreeNode } from './types.js';
+
+/** JSON-serializable tree item carried on `templateData.items` / a `TreeLayer`. */
+export interface TreeItem {
+  id: string;
+  label: string;
+  isDir?: boolean;
+  comment?: string;
+  children: TreeItem[];
+}
+
+/** Tree model → template/layer items (structure-preserving). */
+export function treeToTemplateData(tree: Tree): { items: TreeItem[] } {
+  return { items: tree.roots.map(toItem) };
+}
+
+function toItem(node: TreeNode): TreeItem {
+  return {
+    id: node.id,
+    label: node.label,
+    ...(node.isDir ? { isDir: true } : {}),
+    ...(node.comment ? { comment: node.comment } : {}),
+    children: node.children.map(toItem),
+  };
+}
+
+/** Template/layer items → tree model (editor write-back / render). */
+export function treeFromTemplateData(
+  items: readonly TreeItem[],
+  options: { style?: 'unicode' | 'ascii' } = {},
+): Tree {
+  const roots = items.map(fromItem);
+  return { roots, style: options.style ?? 'unicode', warnings: [] };
+}
+
+function fromItem(item: TreeItem): TreeNode {
+  const children = Array.isArray(item.children) ? item.children.map(fromItem) : [];
+  return {
+    id: typeof item.id === 'string' && item.id ? item.id : 'node',
+    label: typeof item.label === 'string' ? item.label : '',
+    children,
+    isDir: item.isDir === true || children.length > 0,
+    ...(item.comment ? { comment: item.comment } : {}),
+  };
+}
+
+/**
+ * Recursively convert a nested markdown bullet list into a tree. Used by
+ * `deriveTemplateInputs` when an author explicitly `{[tree]}`-annotates a
+ * block whose body is a nested list rather than a fence.
+ */
+export function treeFromMarkdownList(list: MarkdownList): Tree {
+  const usedIds = new Map<string, number>();
+  const slugify = (s: string): string =>
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'node';
+  const idFor = (label: string): string => {
+    const base = slugify(label.replace(/\/$/, ''));
+    const count = usedIds.get(base) ?? 0;
+    usedIds.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count + 1}`;
+  };
+
+  const itemToNode = (item: MarkdownListItem): TreeNode => {
+    // The item's own label = its first non-list block's plain text.
+    const labelNode = item.children.find((c) => c.type !== 'list');
+    const label = labelNode ? extractPlainText(labelNode).trim() : '';
+    const childLists = item.children.filter((c): c is MarkdownList => c.type === 'list');
+    const children: TreeNode[] = [];
+    for (const cl of childLists) for (const ci of cl.children) children.push(itemToNode(ci));
+    return {
+      id: idFor(label),
+      label,
+      children,
+      isDir: label.endsWith('/') || children.length > 0,
+    };
+  };
+
+  return { roots: list.children.map(itemToNode), style: 'unicode', warnings: [] };
+}
+
+/** Find the first top-level markdown list in a block's body, if any. */
+export function findFirstList(contents: MarkdownBlockNode[] | undefined): MarkdownList | undefined {
+  return contents?.find((n): n is MarkdownList => n.type === 'list');
+}

package/src/doc/treeview/parse.ts

@@ -0,0 +1,201 @@
+/**
+ * ASCII tree parser: file-tree / outline art → nested nodes.
+ *
+ * Pure, deterministic, never throws. Handles the many renditions AI emits:
+ * Unicode connectors (`├── `/`└── `/`│   `), ASCII (`|-- `/`` `-- ``/`+-- `),
+ * bullet-indented (`- `/`* `), and pure indentation. Depth is recovered by
+ * finding where each line's LABEL begins (after any connector/indent
+ * prefix) and running the standard outline indent-stack — this unifies all
+ * renditions and tolerates ragged dedents.
+ */
+
+import {
+  isBranchElbow,
+  isBranchTee,
+  isDashChar,
+  isRailChar,
+  isAsciiTreeChar,
+  isUnicodeTreeChar,
+} from './chars.js';
+import type { Tree, TreeNode } from './types.js';
+
+/** Internal per-line analysis fed to the reconstruction stack. */
+export interface TreeLineStats {
+  /** Non-blank content lines. */
+  contentLines: number;
+  /** Lines carrying a connector branch (`├──`/`└──`/`|--`/`` `--``/`+--`). */
+  connectorLines: number;
+  /** Lines that could not be analyzed as a node (loose text). */
+  looseLines: number;
+  /** Distinct label-start columns observed (a hierarchy has ≥2). */
+  indentLevels: number;
+}
+
+interface AnalyzedLine {
+  indent: number; // column where the label begins
+  label: string;
+  comment?: string;
+  hadConnector: boolean;
+}
+
+export function parseTree(text: string): Tree {
+  return parseTreeWithStats(text).tree;
+}
+
+export function parseTreeWithStats(text: string): { tree: Tree; stats: TreeLineStats } {
+  const warnings: string[] = [];
+  const rawLines = text.replace(/\r\n?/g, '\n').split('\n');
+
+  const style = detectStyle(rawLines);
+  const stats: TreeLineStats = {
+    contentLines: 0,
+    connectorLines: 0,
+    looseLines: 0,
+    indentLevels: 0,
+  };
+  const indentSet = new Set<number>();
+
+  const analyzed: AnalyzedLine[] = [];
+  for (const raw of rawLines) {
+    if (raw.trim().length === 0) continue;
+    stats.contentLines++;
+    const a = analyzeLine(raw);
+    if (!a || a.label.length === 0) {
+      stats.looseLines++;
+      continue;
+    }
+    if (a.hadConnector) stats.connectorLines++;
+    indentSet.add(a.indent);
+    analyzed.push(a);
+  }
+  stats.indentLevels = indentSet.size;
+
+  // ---- Reconstruct the hierarchy via an indent stack --------------------
+  const roots: TreeNode[] = [];
+  const stack: Array<{ indent: number; node: TreeNode }> = [];
+  for (const a of analyzed) {
+    const node: TreeNode = {
+      id: '',
+      label: a.label,
+      children: [],
+      ...(a.comment ? { comment: a.comment } : {}),
+    };
+    // Pop ancestors that are at the same or deeper indent.
+    while (stack.length > 0 && stack[stack.length - 1].indent >= a.indent) stack.pop();
+    if (stack.length === 0) {
+      roots.push(node);
+    } else {
+      stack[stack.length - 1].node.children.push(node);
+    }
+    stack.push({ indent: a.indent, node });
+  }
+
+  // ---- Post-pass: isDir + stable ids ------------------------------------
+  const usedIds = new Map<string, number>();
+  const finalize = (node: TreeNode): void => {
+    node.isDir = node.label.endsWith('/') || node.children.length > 0;
+    const base = slugify(stripTrailingSlash(node.label));
+    const count = usedIds.get(base) ?? 0;
+    usedIds.set(base, count + 1);
+    node.id = count === 0 ? base : `${base}-${count + 1}`;
+    for (const child of node.children) finalize(child);
+  };
+  for (const root of roots) finalize(root);
+
+  if (analyzed.length > 0 && stats.looseLines > 0) {
+    warnings.push(`loose-lines(${stats.looseLines})`);
+  }
+
+  return { tree: { roots, style, warnings }, stats };
+}
+
+// ---------------------------------------------------------------------------
+// Line analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip a line's connector / indent prefix and return the column where the
+ * label begins plus the cleaned label + trailing comment. Returns null for
+ * a rails-only spacer line.
+ */
+function analyzeLine(line: string): AnalyzedLine | null {
+  const chars = Array.from(line);
+  let i = 0;
+  let hadConnector = false;
+
+  // Consume leading whitespace + vertical rails. A rail is a rail glyph NOT
+  // immediately followed by a dash (which would make it an ASCII branch).
+  for (;;) {
+    while (i < chars.length && (chars[i] === ' ' || chars[i] === '\t')) i++;
+    const ch = chars[i];
+    if (ch === undefined) return null; // blank / rails-only
+    if (isRailChar(ch) && !isDashChar(chars[i + 1] ?? '')) {
+      i++;
+      continue;
+    }
+    break;
+  }
+
+  // Optional branch: a Unicode tee/elbow + dashes, or ASCII `|`/`` ` ``/`+`
+  // + dashes. The label follows (after any trailing spaces).
+  const ch = chars[i];
+  if (ch !== undefined) {
+    if (isBranchTee(ch) || isBranchElbow(ch)) {
+      i++;
+      while (i < chars.length && (isDashChar(chars[i]) || isRailChar(chars[i]))) i++;
+      hadConnector = true;
+    } else if ((ch === '|' || ch === '`' || ch === '+') && isDashChar(chars[i + 1] ?? '')) {
+      i++;
+      while (i < chars.length && isDashChar(chars[i])) i++;
+      hadConnector = true;
+    } else if ((ch === '-' || ch === '*' || ch === '+') && (chars[i + 1] ?? '') === ' ') {
+      // Markdown-style bullet (indent-based rendition).
+      i++;
+      hadConnector = false;
+    }
+  }
+  while (i < chars.length && (chars[i] === ' ' || chars[i] === '\t')) i++;
+
+  const indent = i;
+  let label = chars.slice(i).join('').replace(/\s+$/u, '');
+  if (label.length === 0) return null;
+
+  // Trailing comment: ` # …`, ` <-- …`, or ` // …` (needs a leading space).
+  let comment: string | undefined;
+  const commentMatch = /\s+(?:#|<--|\/\/)\s?(.*)$/.exec(label);
+  if (commentMatch) {
+    comment = commentMatch[1].trim() || undefined;
+    label = label.slice(0, commentMatch.index).replace(/\s+$/u, '');
+  }
+  if (label.length === 0) return null;
+
+  return { indent, label, hadConnector, ...(comment ? { comment } : {}) };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function detectStyle(lines: string[]): 'unicode' | 'ascii' {
+  let unicode = 0;
+  let ascii = 0;
+  for (const line of lines) {
+    for (const ch of line) {
+      if (isUnicodeTreeChar(ch)) unicode++;
+      else if (isAsciiTreeChar(ch)) ascii++;
+    }
+  }
+  return ascii > unicode ? 'ascii' : 'unicode';
+}
+
+function stripTrailingSlash(s: string): string {
+  return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+
+function slugify(s: string): string {
+  const slug = s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'node';
+}