@bendyline/squisq 2.0.1 → 2.2.0

package/src/doc/asciiTimeline/parse.ts

@@ -1,870 +0,0 @@
-/** ASCII timeline parser: horizontal tracks + point/callout art -> model. */
-
-import type {
-  AsciiTimeline,
-  AsciiTimelineEvent,
-  AsciiTimelineLink,
-  AsciiTimelineMarker,
-  AsciiTimelineSide,
-  AsciiTimelineStyle,
-  AsciiTimelineTrack,
-} from './types.js';
-import { parseWrappedFlowTimeline } from './wrappedFlow.js';
-
-const STRONG_MARKERS = new Set(['●', '○', '◉', '◆', '◇', '•']);
-const ASCII_MARKERS = new Set(['*', 'o', 'O']);
-const HORIZONTAL = new Set(['─', '━', '═', '╌', '╍', '┄', '┅', '┈', '┉', '-']);
-const END_ARROWS = new Set(['►', '▶', '▷', '→', '>']);
-const POINTERS = new Set(['▲', '△', '▼', '▽', '^', 'v']);
-const CONNECTOR_ANCHORS = new Set(['└', '┌', '├', '┬', '┘', '┐', '╰', '╭', '╯', '╮']);
-
-export interface AsciiTimelineStats {
-  axisLines: number;
-  markerCount: number;
-  strongMarkerCount: number;
-  horizontalChars: number;
-  pointerCount: number;
-  branchDeclarations: number;
-  /** True for high-confidence multi-lane flow art with a return edge. */
-  wrappedFlow?: boolean;
-}
-
-interface AxisAnalysis {
-  row: number;
-  id?: string;
-  startColumn: number;
-  endColumn: number;
-  markerColumns: number[];
-  markerGlyphs: string[];
-  inline: Array<{
-    label?: string;
-    description?: string;
-    id?: string;
-    column?: number;
-    side?: AsciiTimelineSide;
-    descriptionSide?: AsciiTimelineSide;
-    callout?: boolean;
-  }>;
-  label?: string;
-  endLabel?: string;
-  horizontalChars: number;
-  strongMarkerCount: number;
-}
-
-interface PendingBranch {
-  source: string;
-  target: string;
-  label?: string;
-}
-
-interface Segment {
-  start: number;
-  end: number;
-  text: string;
-}
-
-export function parseAsciiTimeline(text: string): AsciiTimeline {
-  return parseAsciiTimelineWithStats(text).timeline;
-}
-
-export function parseAsciiTimelineWithStats(text: string): {
-  timeline: AsciiTimeline;
-  stats: AsciiTimelineStats;
-} {
-  const lines = text.replace(/\r\n?/g, '\n').split('\n');
-  const width = Math.max(0, ...lines.map((line) => Array.from(line).length));
-  const wrappedFlow = parseWrappedFlowTimeline(text);
-  if (wrappedFlow) {
-    const markerCount = wrappedFlow.tracks.reduce((sum, track) => sum + track.events.length, 0);
-    return {
-      timeline: wrappedFlow,
-      stats: {
-        axisLines: wrappedFlow.tracks.length,
-        markerCount,
-        strongMarkerCount: markerCount,
-        horizontalChars: Array.from(text).filter((char) => HORIZONTAL.has(char)).length,
-        pointerCount: 0,
-        branchDeclarations: wrappedFlow.links.length,
-        wrappedFlow: true,
-      },
-    };
-  }
-  const style = detectStyle(lines);
-  const pendingBranches: PendingBranch[] = [];
-  const axes: AxisAnalysis[] = [];
-
-  for (let row = 0; row < lines.length; row++) {
-    const branch = parseBranchDeclaration(lines[row]);
-    if (branch) {
-      pendingBranches.push(branch);
-      continue;
-    }
-    const axis = analyzeAxisLine(lines[row], row, style);
-    if (axis) {
-      axes.push(axis);
-      continue;
-    }
-    const cadence = analyzeCadenceLine(lines[row], row);
-    if (cadence) axes.push(cadence);
-  }
-
-  const tracks: AsciiTimelineTrack[] = axes.map((axis, index) => ({
-    id: axis.id ?? slug(axis.label || `track-${index + 1}`),
-    ...(axis.label ? { label: axis.label } : {}),
-    ...(axis.endLabel ? { endLabel: axis.endLabel } : {}),
-    row: axis.row,
-    startColumn: axis.startColumn,
-    endColumn: axis.endColumn,
-    events: axis.markerColumns.map((markerColumn, eventIndex) => {
-      const inline = axis.inline[eventIndex];
-      return {
-        id: inline.id ?? '',
-        label: inline.label ?? '',
-        ...(inline.description ? { description: inline.description } : {}),
-        column: inline.column ?? markerColumn,
-        ...(inline.side ? { side: inline.side } : {}),
-        ...(inline.descriptionSide ? { descriptionSide: inline.descriptionSide } : {}),
-        ...(inline.callout === false ? { callout: false } : {}),
-        marker: markerKind(axis.markerGlyphs[eventIndex]),
-      } satisfies AsciiTimelineEvent;
-    }),
-  }));
-
-  // Labels immediately above an axis are the common authored form. Match by
-  // source column, conservatively: a prose prefix ("kernel ticks:") must not
-  // steal the first event just because it shares the same line.
-  for (let i = 0; i < axes.length; i++) {
-    const axis = axes[i];
-    const track = tracks[i];
-    const aboveRow = previousNonBlankRow(lines, axis.row - 1);
-    if (aboveRow >= 0 && !axes.some((candidate) => candidate.row === aboveRow)) {
-      const segments = splitPlainSegments(lines[aboveRow]);
-      const pointEvents = track.events.filter((event) => !event.label);
-      const aligned = alignedEventSegments(segments, pointEvents);
-      if (aligned) {
-        for (let eventIndex = 0; eventIndex < pointEvents.length; eventIndex++) {
-          pointEvents[eventIndex].label = cleanProseText(aligned[eventIndex].text);
-          pointEvents[eventIndex].side = 'above';
-        }
-        // A prose prefix ending in `:` on the label row is a stronger track
-        // name than a generic axis suffix such as "sim time".
-        const firstAligned = segments.indexOf(aligned[0]);
-        const prefix = firstAligned > 0 ? segments[firstAligned - 1] : undefined;
-        if (prefix?.text.trim().endsWith(':')) {
-          track.label = stripTrailingColon(prefix.text);
-          track.id = slug(track.label);
-        }
-      }
-      for (const event of track.events) {
-        if (event.label) continue;
-        const gap = nearestEventGap(track.events, event.column);
-        const threshold = Math.max(3, Math.min(8, gap * 0.38));
-        const nearest = nearestSegment(segments, event.column, threshold);
-        if (!nearest) continue;
-        event.label = cleanProseText(nearest.text);
-        event.side = 'above';
-      }
-    }
-  }
-
-  // Anchored pointers (▲/▼) are fractional events: unlike milestone dots,
-  // they may intentionally sit between snapshots/ticks.
-  let pointerCount = 0;
-  for (let row = 0; row < lines.length; row++) {
-    if (axes.some((axis) => axis.row === row)) continue;
-    const chars = Array.from(lines[row]);
-    const pointerColumns = chars
-      .map((char, column) => ({ char, column }))
-      .filter(({ column }) => isPointerAt(chars, column))
-      .map(({ column }) => column);
-    for (let pointerIndex = 0; pointerIndex < pointerColumns.length; pointerIndex++) {
-      const column = pointerColumns[pointerIndex];
-      // Canonical pointer callouts carry semantic `column=` metadata while
-      // their glyph remains aligned to the physical marker on the pretty
-      // rail. Prefer an as-yet-unclaimed marker at that source column before
-      // falling back to the general nearest-track heuristic.
-      const track =
-        nearestUnclaimedMarkerTrack(tracks, row, column) ?? nearestTrack(tracks, row, column);
-      if (!track) continue;
-      pointerCount++;
-      const nextPointer = pointerColumns[pointerIndex + 1] ?? chars.length;
-      const after = cleanProseText(chars.slice(column + 1, nextPointer).join(''));
-      // A prose prefix belongs only to the first pointer on a row. Subsequent
-      // pointers own the text to their right, preventing `▲ A  ▲ B` from
-      // contaminating both labels with the whole row.
-      const prefix = pointerIndex === 0 ? cleanProseText(chars.slice(0, column).join('')) : '';
-      const parsed = /\{[^{}]*#[^{}\s]+[^{}]*\}\s*$/u.test(after)
-        ? parseInlineEvent(after)
-        : { label: after || undefined };
-      const label =
-        stripTrailingColon(prefix) || parsed.label || after || `Event ${track.events.length + 1}`;
-      const description = prefix && after ? after : parsed.description;
-      const side: AsciiTimelineSide = parsed.side ?? (row < track.row ? 'above' : 'below');
-      const existing =
-        track.events.find((event) => !event.id && Math.abs(event.column - column) <= 1) ??
-        track.events.find(
-          (event) => event.callout !== false && Math.abs(event.column - column) <= 1,
-        );
-      if (existing) {
-        if (parsed.id) existing.id = parsed.id;
-        if (parsed.column !== undefined) existing.column = parsed.column;
-        if (!existing.label) existing.label = label;
-        if (parsed.label) existing.label = parsed.label;
-        if (description && !existing.description) existing.description = description;
-        if (parsed.description) existing.description = parsed.description;
-        if (parsed.descriptionSide) existing.descriptionSide = parsed.descriptionSide;
-        else if (description && !parsed.id) existing.descriptionSide ??= side;
-        if (parsed.callout !== undefined) existing.callout = parsed.callout;
-        existing.side = side;
-      } else {
-        track.events.push({
-          id: parsed.id ?? '',
-          label,
-          ...(description ? { description } : {}),
-          column: parsed.column ?? column,
-          side,
-          ...(parsed.descriptionSide
-            ? { descriptionSide: parsed.descriptionSide }
-            : description && !parsed.id
-              ? { descriptionSide: side }
-              : {}),
-          ...(parsed.callout !== undefined ? { callout: parsed.callout } : {}),
-          marker: 'hollow',
-        });
-      }
-    }
-  }
-
-  // Elbow-led callouts (`└─Δ28`, `└─ interpolate ...`) attach descriptions
-  // to the closest point on the closest track. This covers interval labels
-  // and multi-line explanatory callouts in the motivating sample.
-  for (let row = 0; row < lines.length; row++) {
-    if (axes.some((axis) => axis.row === row)) continue;
-    const callouts = extractConnectorCallouts(lines[row]);
-    const prefix =
-      callouts.length > 0
-        ? cleanProseText(Array.from(lines[row]).slice(0, callouts[0].start).join(''))
-        : '';
-    for (let calloutIndex = 0; calloutIndex < callouts.length; calloutIndex++) {
-      const callout = callouts[calloutIndex];
-      const track = nearestTrack(tracks, row, callout.start);
-      if (!track || track.events.length === 0) continue;
-      const event = nearestEvent(track.events, callout.start);
-      if (!event) continue;
-      const calloutText = cleanProseText(callout.text);
-      const cleaned = calloutIndex === 0 && prefix ? `${prefix} ${calloutText}` : calloutText;
-      if (!cleaned || cleaned === event.label) continue;
-      if (event.callout === false) {
-        // A cadence point becomes a real annotated event when the author
-        // attaches an elbow callout to it; leaving `callout:false` would make
-        // the template silently hide that authored text.
-        event.callout = true;
-        event.label = cleaned;
-        event.side = row < track.row ? 'above' : 'below';
-        continue;
-      }
-      event.description = event.description ? `${event.description} ${cleaned}` : cleaned;
-      event.descriptionSide ??= row < track.row ? 'above' : 'below';
-      event.side ??= row < track.row ? 'above' : 'below';
-    }
-  }
-
-  const warnings: string[] = [];
-  const usedTrackIds = new Map<string, number>();
-  for (const track of tracks) track.id = dedupe(track.id, usedTrackIds);
-
-  // Finalize ids only after labels/callouts have been associated.
-  const usedEventIds = new Map<string, number>();
-  for (const track of tracks) {
-    track.events.sort((a, b) => a.column - b.column);
-    for (let i = 0; i < track.events.length; i++) {
-      const event = track.events[i];
-      if (!event.label) {
-        event.label = `Event ${i + 1}`;
-        warnings.push(`unlabeled-event(${track.id}:${event.column})`);
-      }
-      event.id = dedupe(event.id || slug(event.label), usedEventIds);
-      event.side ??= i % 2 === 0 ? 'above' : 'below';
-    }
-  }
-
-  const eventIds = new Set(tracks.flatMap((track) => track.events.map((event) => event.id)));
-  const labelToId = new Map<string, string>();
-  for (const track of tracks) {
-    for (const event of track.events) {
-      labelToId.set(slug(event.label), event.id);
-      labelToId.set(event.id, event.id);
-    }
-  }
-  const links: AsciiTimelineLink[] = [];
-  for (const branch of pendingBranches) {
-    const source = labelToId.get(slug(branch.source)) ?? branch.source;
-    const target = labelToId.get(slug(branch.target)) ?? branch.target;
-    if (!eventIds.has(source) || !eventIds.has(target)) {
-      warnings.push(`unresolved-link(${branch.source}->${branch.target})`);
-      continue;
-    }
-    links.push({ source, target, ...(branch.label ? { label: branch.label } : {}) });
-  }
-
-  const stats: AsciiTimelineStats = {
-    axisLines: axes.length,
-    markerCount: axes.reduce((sum, axis) => sum + axis.markerColumns.length, 0),
-    strongMarkerCount: axes.reduce((sum, axis) => sum + axis.strongMarkerCount, 0),
-    horizontalChars: axes.reduce((sum, axis) => sum + axis.horizontalChars, 0),
-    pointerCount,
-    branchDeclarations: pendingBranches.length,
-    wrappedFlow: false,
-  };
-
-  return {
-    timeline: { tracks, links, width, height: lines.length, style, warnings },
-    stats,
-  };
-}
-
-/**
- * Many terminal timelines put labels at a consistent offset from every dot
- * (the motivating sample uses +6 columns), rather than centering them. When
- * the last N text segments have one stable offset, pair them in order.
- */
-function alignedEventSegments(
-  segments: readonly Segment[],
-  events: readonly AsciiTimelineEvent[],
-): Segment[] | undefined {
-  if (events.length < 2 || segments.length < events.length) return undefined;
-  const candidates = segments.slice(-events.length);
-  if (candidates.some((segment) => cleanCalloutText(segment.text).length > 40)) return undefined;
-  const offsets = candidates.map(
-    (segment, index) => (segment.start + segment.end) / 2 - events[index].column,
-  );
-  const spread = Math.max(...offsets) - Math.min(...offsets);
-  return spread <= 3 ? [...candidates] : undefined;
-}
-
-function analyzeAxisLine(
-  line: string,
-  row: number,
-  style: AsciiTimelineStyle,
-): AxisAnalysis | null {
-  const chars = Array.from(line);
-  const markerColumns: number[] = [];
-  const markerGlyphs: string[] = [];
-  let horizontalChars = 0;
-  let strongMarkerCount = 0;
-  for (let i = 0; i < chars.length; i++) {
-    const ch = chars[i];
-    if (HORIZONTAL.has(ch)) horizontalChars++;
-    if (isMarkerAt(chars, i, style)) {
-      markerColumns.push(i);
-      markerGlyphs.push(ch);
-      if (STRONG_MARKERS.has(ch)) strongMarkerCount++;
-    }
-  }
-  if (markerColumns.length === 0 || horizontalChars < 2) return null;
-
-  const firstMarker = markerColumns[0];
-  const colon = chars.slice(0, firstMarker).lastIndexOf(':');
-  let startColumn: number;
-  if (colon >= 0) {
-    startColumn = colon + 1;
-    while (chars[startColumn] === ' ') startColumn++;
-  } else {
-    let i = firstMarker - 1;
-    while (i >= 0 && (HORIZONTAL.has(chars[i]) || chars[i] === ' ')) i--;
-    startColumn = i + 1;
-    while (chars[startColumn] === ' ') startColumn++;
-  }
-
-  let endColumn = markerColumns[markerColumns.length - 1];
-  // Inline prose may contain `>` / `->`. A track terminator is structural
-  // only when it follows a rail (allowing spaces between the rail and arrow).
-  // Search directly from the last marker: brace-delimited prose may legally
-  // occur in an end label, so a blind `lastIndexOf('}')` is not an attrs gate.
-  const arrowSearchStart = endColumn + 1;
-  const arrowColumn = chars.findIndex(
-    (ch, index) =>
-      index >= arrowSearchStart &&
-      END_ARROWS.has(ch) &&
-      hasRailBefore(chars, index, ch === '>' ? 3 : 2),
-  );
-  let payloadEndExclusive: number;
-  if (arrowColumn >= 0) {
-    endColumn = arrowColumn;
-    // Do not feed the structural arrow into the event payload parser. This
-    // lets internal prose arrows survive untouched.
-    payloadEndExclusive = arrowColumn;
-  } else {
-    // With no structural arrow, all trailing prose belongs to the last event.
-    const lastNonSpace = findLastNonSpace(chars);
-    endColumn = Math.max(endColumn, lastNonSpace);
-    payloadEndExclusive = endColumn + 1;
-  }
-
-  const prefix = parseTrackPrefix(stripTrailingColon(chars.slice(0, startColumn).join('').trim()));
-  const suffix = cleanProseText(chars.slice(endColumn + 1).join(''));
-  const label = prefix.label;
-  const inline = markerColumns.map((column, index) => {
-    const next = index + 1 < markerColumns.length ? markerColumns[index + 1] : payloadEndExclusive;
-    return parseInlineEvent(chars.slice(column + 1, next).join(''));
-  });
-
-  return {
-    row,
-    ...(prefix.id ? { id: prefix.id } : {}),
-    startColumn: prefix.startColumn ?? startColumn,
-    endColumn: prefix.endColumn ?? Math.max(endColumn, startColumn + 1),
-    markerColumns,
-    markerGlyphs,
-    inline,
-    ...(label ? { label } : {}),
-    ...(suffix ? { endLabel: suffix } : {}),
-    horizontalChars,
-    strongMarkerCount,
-  };
-}
-
-/**
- * Recognize dense cadence rows such as
- * `client frames (120 Hz): f f f f f f`. They are timelines without an
- * authored rail: every repeated one-character token is a hollow point, while
- * `callout: false` keeps the visual timeline from labeling every frame.
- */
-function analyzeCadenceLine(line: string, row: number): AxisAnalysis | null {
-  const chars = Array.from(line);
-  const colon = chars.indexOf(':');
-  if (colon < 0) return null;
-  const label = chars.slice(0, colon).join('').trim();
-  if (!label) return null;
-
-  const tokens: Array<{ value: string; column: number }> = [];
-  let index = colon + 1;
-  while (index < chars.length) {
-    while (index < chars.length && /\s/u.test(chars[index])) index++;
-    if (index >= chars.length) break;
-    const start = index;
-    while (index < chars.length && !/\s/u.test(chars[index])) index++;
-    tokens.push({ value: chars.slice(start, index).join(''), column: start });
-  }
-  if (
-    tokens.length < 4 ||
-    tokens[0].value.length !== 1 ||
-    tokens.some((token) => token.value !== tokens[0].value)
-  ) {
-    return null;
-  }
-
-  return {
-    row,
-    startColumn: tokens[0].column,
-    endColumn: tokens[tokens.length - 1].column,
-    markerColumns: tokens.map((token) => token.column),
-    markerGlyphs: tokens.map(() => '○'),
-    inline: tokens.map((token, tokenIndex) => ({
-      label: token.value,
-      id: `${slug(label)}-${tokenIndex + 1}`,
-      column: token.column,
-      callout: false,
-    })),
-    label,
-    horizontalChars: 0,
-    strongMarkerCount: 0,
-  };
-}
-
-function parseInlineEvent(raw: string): {
-  label?: string;
-  description?: string;
-  id?: string;
-  column?: number;
-  side?: AsciiTimelineSide;
-  descriptionSide?: AsciiTimelineSide;
-  callout?: boolean;
-} {
-  // Separator rails only have structural meaning at the payload edges.
-  // Internal prose such as `release--candidate` and `A > B` is content.
-  let text = stripEdgeRails(raw).replace(/\s+/g, ' ').trim();
-  if (!text) return {};
-
-  let id: string | undefined;
-  let column: number | undefined;
-  let side: AsciiTimelineSide | undefined;
-  let descriptionSide: AsciiTimelineSide | undefined;
-  let callout: boolean | undefined;
-  const attrs = /\{([^{}]+)\}\s*$/.exec(text);
-  if (attrs) {
-    let recognized = false;
-    for (const token of attrs[1].trim().split(/\s+/)) {
-      if (token.startsWith('#') && token.length > 1) {
-        id = token.slice(1);
-        recognized = true;
-      } else if (token === 'side=above') {
-        side = 'above';
-        recognized = true;
-      } else if (token === 'side=below') {
-        side = 'below';
-        recognized = true;
-      } else if (token === 'descriptionSide=above') {
-        descriptionSide = 'above';
-        recognized = true;
-      } else if (token === 'descriptionSide=below') {
-        descriptionSide = 'below';
-        recognized = true;
-      } else if (token.startsWith('column=')) {
-        const parsed = parseCoordinate(token.slice(7));
-        if (parsed !== undefined) {
-          column = parsed;
-          recognized = true;
-        }
-      } else if (token === 'callout=false') {
-        callout = false;
-        recognized = true;
-      } else if (token === 'callout=true') {
-        callout = true;
-        recognized = true;
-      }
-    }
-    if (recognized) text = text.slice(0, attrs.index).trim();
-  }
-  if (text.startsWith('^ ')) {
-    side = 'above';
-    text = text.slice(2).trim();
-  } else if (/^[vV]\s+/.test(text)) {
-    side = 'below';
-    text = text.slice(2).trim();
-  }
-  const separator = text.indexOf('::');
-  const label = (separator >= 0 ? text.slice(0, separator) : text).trim();
-  const description = separator >= 0 ? text.slice(separator + 2).trim() : undefined;
-  return {
-    ...(label ? { label } : {}),
-    ...(description ? { description } : {}),
-    ...(id ? { id } : {}),
-    ...(column !== undefined ? { column } : {}),
-    ...(side ? { side } : {}),
-    ...(descriptionSide ? { descriptionSide } : {}),
-    ...(callout !== undefined ? { callout } : {}),
-  };
-}
-
-function parseTrackPrefix(text: string): {
-  label?: string;
-  id?: string;
-  startColumn?: number;
-  endColumn?: number;
-  hasMetadata: boolean;
-} {
-  let label = text.trim();
-  let id: string | undefined;
-  let startColumn: number | undefined;
-  let endColumn: number | undefined;
-  let recognized = false;
-  const attrs = /\{([^{}]+)\}\s*$/.exec(label);
-  if (attrs) {
-    for (const token of attrs[1].trim().split(/\s+/)) {
-      if (token.startsWith('#') && token.length > 1) {
-        id = token.slice(1);
-        recognized = true;
-      } else if (token.startsWith('start=')) {
-        startColumn = parseCoordinate(token.slice(6));
-        recognized ||= startColumn !== undefined;
-      } else if (token.startsWith('end=')) {
-        endColumn = parseCoordinate(token.slice(4));
-        recognized ||= endColumn !== undefined;
-      }
-    }
-    if (recognized) label = label.slice(0, attrs.index).trim();
-  }
-  return {
-    ...(label ? { label } : {}),
-    ...(id ? { id } : {}),
-    ...(startColumn !== undefined ? { startColumn } : {}),
-    ...(endColumn !== undefined ? { endColumn } : {}),
-    hasMetadata: recognized,
-  };
-}
-
-function parseCoordinate(value: string): number | undefined {
-  if (!value.trim()) return undefined;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-function stripEdgeRails(raw: string): string {
-  const chars = Array.from(raw);
-  let start = 0;
-  let end = chars.length - 1;
-
-  // A structural leading rail either touches the marker (`●── label`) or is
-  // followed by whitespace (`● ── label`). A payload that begins after a
-  // space with `-1.5`, `--watch`, or `─phase` is authored prose and stays.
-  let firstNonSpace = 0;
-  while (firstNonSpace <= end && /\s/u.test(chars[firstNonSpace])) firstNonSpace++;
-  let leadingRailEnd = firstNonSpace;
-  while (leadingRailEnd <= end && HORIZONTAL.has(chars[leadingRailEnd])) leadingRailEnd++;
-  const hasLeadingRail = leadingRailEnd > firstNonSpace;
-  const structuralLeadingRail =
-    hasLeadingRail &&
-    (firstNonSpace === 0 || leadingRailEnd > end || /\s/u.test(chars[leadingRailEnd] ?? ''));
-  start = structuralLeadingRail ? leadingRailEnd : firstNonSpace;
-  while (start <= end && /\s/u.test(chars[start])) start++;
-
-  while (end >= start && /\s/u.test(chars[end])) end--;
-  const trailingRailEnd = end;
-  while (end >= start && HORIZONTAL.has(chars[end])) end--;
-  const hasTrailingRail = end < trailingRailEnd;
-  // Separators are normally preceded by whitespace; a long/Unicode run is
-  // also safely structural in compact `label───●` authored art.
-  const trailingRun = hasTrailingRail ? chars.slice(end + 1, trailingRailEnd + 1) : [];
-  const structuralTrailingRail =
-    hasTrailingRail &&
-    (end < start ||
-      /\s/u.test(chars[end] ?? '') ||
-      trailingRun.length >= 3 ||
-      trailingRun.some((char) => char !== '-'));
-  if (!structuralTrailingRail) end = trailingRailEnd;
-  while (end >= start && /\s/u.test(chars[end])) end--;
-  return chars.slice(start, end + 1).join('');
-}
-
-function hasRailBefore(chars: readonly string[], column: number, minimum: number): boolean {
-  let index = column - 1;
-  while (index >= 0 && /\s/u.test(chars[index])) index--;
-  let count = 0;
-  while (index >= 0 && HORIZONTAL.has(chars[index])) {
-    count++;
-    index--;
-  }
-  return count >= minimum;
-}
-
-function findLastNonSpace(chars: readonly string[]): number {
-  for (let index = chars.length - 1; index >= 0; index--) {
-    if (!/\s/u.test(chars[index])) return index;
-  }
-  return -1;
-}
-
-function parseBranchDeclaration(line: string): PendingBranch | null {
-  const match =
-    /^\s*(?:branch|link)\s*:\s*([^\s:]+)\s*(?:->|=>|→)\s*([^\s:]+)(?:\s*:\s*(.+))?\s*$/i.exec(line);
-  if (!match) return null;
-  return {
-    source: match[1],
-    target: match[2],
-    ...(match[3]?.trim() ? { label: match[3].trim() } : {}),
-  };
-}
-
-function splitPlainSegments(line: string): Segment[] {
-  const chars = Array.from(line);
-  const out: Segment[] = [];
-  let start = -1;
-  let spaces = 0;
-  for (let i = 0; i <= chars.length; i++) {
-    const ch = chars[i];
-    if (ch === ' ') {
-      spaces++;
-      if (start >= 0 && spaces >= 2) {
-        const end = i - spaces;
-        const text = chars
-          .slice(start, end + 1)
-          .join('')
-          .trim();
-        if (text) out.push({ start, end, text });
-        start = -1;
-      }
-      continue;
-    }
-    spaces = 0;
-    if (ch !== undefined && start < 0) start = i;
-    if (ch === undefined && start >= 0) {
-      const text = chars.slice(start).join('').trim();
-      if (text) out.push({ start, end: chars.length - 1, text });
-    }
-  }
-  return out.filter((segment) => cleanCalloutText(segment.text).length > 0);
-}
-
-function extractConnectorCallouts(line: string): Segment[] {
-  const chars = Array.from(line);
-  const out: Segment[] = [];
-  for (let i = 0; i < chars.length; i++) {
-    if (!CONNECTOR_ANCHORS.has(chars[i])) continue;
-    let j = i + 1;
-    const railStart = j;
-    while (j < chars.length && (HORIZONTAL.has(chars[j]) || chars[j] === ' ')) j++;
-    const railEnd = j;
-    // In `└─-1.5` / `└─--watch`, the Unicode rail is structural but the
-    // following ASCII hyphen run is authored prose. Preserve that suffix.
-    const afterRail = chars[j];
-    if (afterRail !== undefined && !/\s/u.test(afterRail)) {
-      let lastNonAsciiRail = -1;
-      for (let railIndex = railStart; railIndex < j; railIndex++) {
-        if (HORIZONTAL.has(chars[railIndex]) && chars[railIndex] !== '-') {
-          lastNonAsciiRail = railIndex;
-        }
-      }
-      if (lastNonAsciiRail >= railStart && lastNonAsciiRail + 1 < j) {
-        j = lastNonAsciiRail + 1;
-      } else if (lastNonAsciiRail < 0 && j - railStart >= 3) {
-        j--;
-      }
-    }
-    const textStart = j;
-    if (j < railEnd) while (j < chars.length && chars[j] === '-') j++;
-    while (j < chars.length && !HORIZONTAL.has(chars[j]) && !CONNECTOR_ANCHORS.has(chars[j])) j++;
-    const text = chars.slice(textStart, j).join('').trim();
-    if (text) out.push({ start: i, end: Math.max(i, j - 1), text });
-  }
-  return out;
-}
-
-function nearestTrack(
-  tracks: readonly AsciiTimelineTrack[],
-  row: number,
-  column: number,
-): AsciiTimelineTrack | undefined {
-  return tracks
-    .filter((track) => column >= track.startColumn - 2 && column <= track.endColumn + 2)
-    .sort((a, b) => Math.abs(a.row - row) - Math.abs(b.row - row))[0];
-}
-
-function isPointerAt(chars: readonly string[], column: number): boolean {
-  const char = chars[column];
-  if (!POINTERS.has(char)) return false;
-  if (char !== '^' && char !== 'v') return true;
-  return (
-    (column === 0 || /\s/u.test(chars[column - 1] ?? '')) &&
-    (column + 1 >= chars.length || /\s/u.test(chars[column + 1] ?? ''))
-  );
-}
-
-function nearestUnclaimedMarkerTrack(
-  tracks: readonly AsciiTimelineTrack[],
-  row: number,
-  column: number,
-): AsciiTimelineTrack | undefined {
-  return tracks
-    .filter((track) =>
-      track.events.some((event) => !event.id && Math.abs(event.column - column) <= 1),
-    )
-    .sort((a, b) => Math.abs(a.row - row) - Math.abs(b.row - row))[0];
-}
-
-function nearestEvent(
-  events: readonly AsciiTimelineEvent[],
-  column: number,
-): AsciiTimelineEvent | undefined {
-  return [...events].sort(
-    (a, b) =>
-      Math.abs(a.column - column) - Math.abs(b.column - column) ||
-      Number(a.callout === false) - Number(b.callout === false),
-  )[0];
-}
-
-function nearestSegment(
-  segments: readonly Segment[],
-  column: number,
-  threshold: number,
-): Segment | undefined {
-  return [...segments]
-    .map((segment) => ({ segment, distance: Math.abs((segment.start + segment.end) / 2 - column) }))
-    .filter((candidate) => candidate.distance <= threshold)
-    .sort((a, b) => a.distance - b.distance)[0]?.segment;
-}
-
-function nearestEventGap(events: readonly AsciiTimelineEvent[], column: number): number {
-  const gaps = events
-    .filter((event) => event.column !== column)
-    .map((event) => Math.abs(event.column - column));
-  return gaps.length > 0 ? Math.min(...gaps) : 12;
-}
-
-function previousNonBlankRow(lines: readonly string[], from: number): number {
-  for (let row = from; row >= 0; row--) if (lines[row].trim()) return row;
-  return -1;
-}
-
-function markerKind(glyph: string): AsciiTimelineMarker {
-  if (glyph === '◆' || glyph === '◇') return 'diamond';
-  if (glyph === '○' || glyph === 'o' || glyph === 'O') return 'hollow';
-  return 'filled';
-}
-
-function isMarkerAt(chars: readonly string[], index: number, style: AsciiTimelineStyle): boolean {
-  const glyph = chars[index];
-  if (STRONG_MARKERS.has(glyph)) return true;
-  if (style !== 'ascii' || !ASCII_MARKERS.has(glyph)) return false;
-  // ASCII marker glyphs are ordinary prose/code characters too. Only treat
-  // them as points when they touch a real rail run. Requiring two rail cells
-  // plus a prose boundary avoids turning `Go-live`, `foo--bar`, or
-  // `release-o` into phantom dots.
-  const leftRail = railRun(chars, index, -1);
-  const rightRail = railRun(chars, index, 1);
-  const beforeIsWord = /[\p{L}\p{N}_]/u.test(chars[index - 1] ?? '');
-  const afterIsWord = /[\p{L}\p{N}_]/u.test(chars[index + 1] ?? '');
-  return (leftRail >= 2 && !afterIsWord) || (rightRail >= 2 && !beforeIsWord);
-}
-
-function railRun(chars: readonly string[], index: number, direction: -1 | 1): number {
-  let count = 0;
-  for (let cursor = index + direction; HORIZONTAL.has(chars[cursor] ?? ''); cursor += direction) {
-    count++;
-  }
-  return count;
-}
-
-function cleanCalloutText(text: string): string {
-  return text
-    .replace(/^[\s│|└┌├┬┘┐╰╭╯╮─━═╌╍┄┅┈┉-]+/u, '')
-    .replace(/[\s│|└┌├┬┘┐╰╭╯╮─━═╌╍┄┅┈┉►▶▷→>-]+$/u, '')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-/** Normalize already-separated prose without stripping meaningful `-`/rails. */
-function cleanProseText(text: string): string {
-  return text
-    .replace(/^[\s│|]+/u, '')
-    .replace(/[\s│|]+$/u, '')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function stripTrailingColon(text: string): string {
-  return text.replace(/:\s*$/, '').trim();
-}
-
-function slug(text: string): string {
-  return (
-    text
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '') || 'event'
-  );
-}
-
-function dedupe(base: string, used: Map<string, number>): string {
-  const count = used.get(base) ?? 0;
-  used.set(base, count + 1);
-  return count === 0 ? base : `${base}-${count + 1}`;
-}
-
-function detectStyle(lines: readonly string[]): AsciiTimelineStyle {
-  for (const line of lines) {
-    for (const ch of line) {
-      if (
-        STRONG_MARKERS.has(ch) ||
-        (HORIZONTAL.has(ch) && ch !== '-') ||
-        ['►', '▶', '▷', '→'].includes(ch)
-      ) {
-        // Unicode structural vocabulary is unambiguous. Prefer it even when
-        // labels/descriptions contain many ordinary ASCII `o`, `-`, or `>`
-        // characters; those prose characters must not flip marker parsing.
-        return 'unicode';
-      }
-    }
-  }
-  return 'ascii';
-}