@zombie-mermaid/ascii-renderer 2.2.1

package/src/hyperlinks.ts

@@ -0,0 +1,248 @@
+// ============================================================================
+// ASCII renderer — OSC 8 terminal hyperlinks (opt-in)
+//
+// Modern terminals (iTerm2, WezTerm, kitty, Windows Terminal, VTE-based
+// terminals such as GNOME Terminal) turn a run of text wrapped in an OSC 8
+// escape pair into a clickable link:
+//
+//   ESC ] 8 ; ; https://example.com ESC \ Docs ESC ] 8 ; ; ESC \
+//
+// See https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+// for the de-facto spec. The escape sequences are zero-width, so they must
+// never take part in layout, column-width math, or box drawing — this module
+// records *which canvas cells* carry a link in a `LinkCanvas` (parallel to
+// `RoleCanvas`, the same column-major shape) at draw time, and the
+// canvas-to-string conversion (`canvasToString` / `colorizeLine`) inserts
+// the escape pairs around each run of linked cells as it emits a row.
+// Marking cells rather than searching rendered text for the label means a
+// label that repeats, or appears inside another label, still links only the
+// node that actually declared the `click`.
+//
+// This is what lets a `click A "https://..."` directive survive into
+// terminal output — see docs/decisions/no-script-interactivity.md for where
+// that sits in the interactivity tiers. Off by default
+// (`AsciiRenderOptions.hyperlinks`): not every terminal or pager handles
+// OSC 8 gracefully, and HTML color mode (the demo site's terminal mockup)
+// never emits it at all.
+// ============================================================================
+
+import type { Canvas, DrawingCoord, AsciiGraph } from './types.ts'
+import type { NodeInteraction } from '@zombie-mermaid/core'
+import { safeHref } from '@zombie-mermaid/core'
+
+/**
+ * [maxX, maxY] of a canvas — the same arithmetic as canvas.ts's
+ * `getCanvasSize`, inlined so this module (imported by canvas.ts for
+ * `joinWithLinks`) doesn't import canvas.ts back.
+ */
+function canvasBounds(canvas: Canvas): [number, number] {
+  return [canvas.length - 1, (canvas[0]?.length ?? 1) - 1]
+}
+
+/**
+ * Link canvas — parallel to Canvas, records the href each cell is part of.
+ * Same column-major structure: linkCanvas[x][y] gives the href at (x, y).
+ * null means the cell is not part of any link.
+ */
+export type LinkCanvas = (string | null)[][]
+
+/** OSC 8 close sequence (an empty URI ends the current link). */
+export const OSC8_CLOSE = '\x1b]8;;\x1b\\'
+
+/**
+ * OSC 8 open sequence for `href`.
+ *
+ * The URI portion is limited to printable ASCII (0x21–0x7E) by the spec
+ * linked above — anything else is percent-encoded here so a URL with a
+ * non-ASCII path or a literal space can't break the sequence or leak a
+ * control character into the terminal stream. `encodeURIComponent` on one
+ * code point yields its UTF-8 percent-encoding; the `u` flag keeps a
+ * surrogate pair together so it encodes as one code point rather than two
+ * lone surrogates (which `encodeURIComponent` would throw on).
+ */
+export function osc8Open(href: string): string {
+  const uri = href.replace(/[^\x21-\x7e]/gu, (ch) => encodeURIComponent(ch))
+  return `\x1b]8;;${uri}\x1b\\`
+}
+
+/**
+ * Matches one OSC 8 sequence — open or close, ST- or BEL-terminated. The
+ * URI can never contain ESC or BEL (`osc8Open` percent-encodes anything
+ * outside printable ASCII), so scanning to the first terminator is exact.
+ */
+export const OSC8_SEQUENCE = /\x1b\]8;[^\x07\x1b]*(?:\x1b\\|\x07)/g
+
+/** Remove every OSC 8 sequence, leaving the visible text (and any SGR color codes) intact. */
+export function stripOsc8(text: string): string {
+  return text.replace(OSC8_SEQUENCE, '')
+}
+
+// ============================================================================
+// Link canvas creation and marking
+// ============================================================================
+
+/**
+ * Create a blank link canvas filled with nulls.
+ * Dimensions are inclusive, matching `mkCanvas`: mkLinkCanvas(3, 2) covers
+ * indices 0..3 by 0..2.
+ */
+export function mkLinkCanvas(x: number, y: number): LinkCanvas {
+  const linkCanvas: LinkCanvas = []
+  for (let i = 0; i <= x; i++) {
+    const col: (string | null)[] = []
+    for (let j = 0; j <= y; j++) {
+      col.push(null)
+    }
+    linkCanvas.push(col)
+  }
+  return linkCanvas
+}
+
+/**
+ * Bounds-checked write of an href to one cell. Out-of-range coordinates
+ * are a silent no-op, the same contract as `write()` in canvas.ts — the
+ * link canvas is created at the finished canvas's size, so a cell outside
+ * it can't be printed anyway.
+ */
+export function setLink(
+  linkCanvas: LinkCanvas,
+  x: number,
+  y: number,
+  href: string,
+): void {
+  const col = linkCanvas[x]
+  if (col === undefined || y < 0 || y >= col.length) return
+  col[y] = href
+}
+
+/**
+ * Flip the link canvas vertically to match `flipCanvasVertically` (used for
+ * BT direction). Mutates in place and returns it.
+ */
+export function flipLinkCanvasVertically(linkCanvas: LinkCanvas): LinkCanvas {
+  for (const col of linkCanvas) {
+    col.reverse()
+  }
+  return linkCanvas
+}
+
+/**
+ * Mark the label text inside a drawn box as linked to `href`.
+ *
+ * `box` is a standalone box canvas (from `drawNode`/`drawMultiBox`) whose
+ * border occupies its outermost row and column; `offset` is where its
+ * top-left corner lands on the main canvas. For each interior row (or only
+ * `rows.from..rows.to`, inclusive, when given — class diagrams pass just
+ * the header's class-name rows), the linked span runs from the first to the
+ * last non-space cell, so a multi-word label ("Web Server") is one link
+ * rather than two, and each line of a multi-line label becomes its own
+ * span. A row with no text is left unmarked.
+ *
+ * Working from the box's own geometry (rather than scanning the merged
+ * canvas for the label's characters) is what keeps this exact for labels
+ * that repeat across nodes, contain box-drawing-like punctuation, or hold
+ * wide characters whose placeholder cell (`WIDE_CHAR_PLACEHOLDER`) is an
+ * empty string rather than a space.
+ */
+export function markBoxLabelLinks(
+  linkCanvas: LinkCanvas,
+  box: Canvas,
+  offset: DrawingCoord,
+  href: string,
+  rows?: { from: number; to: number },
+): void {
+  const [maxX, maxY] = canvasBounds(box)
+  const firstRow = Math.max(1, rows?.from ?? 1)
+  const lastRow = Math.min(maxY - 1, rows?.to ?? maxY - 1)
+
+  for (let y = firstRow; y <= lastRow; y++) {
+    let first = -1
+    let last = -1
+    for (let x = 1; x <= maxX - 1; x++) {
+      if (box[x]?.[y] !== ' ') {
+        if (first === -1) first = x
+        last = x
+      }
+    }
+    if (first === -1) continue
+    for (let x = first; x <= last; x++) {
+      setLink(linkCanvas, x + offset.x, y + offset.y, href)
+    }
+  }
+}
+
+/**
+ * Build the link canvas for a drawn flowchart/state graph: every node whose
+ * `click` declared a safe href (see `safeHref` — `javascript:`/`data:` and
+ * the like are dropped there, never here) gets its label cells marked. A
+ * `call`/`callback`-only interaction has no href and marks nothing.
+ *
+ * Must run after `drawGraph` (so every node has its `drawing` and
+ * `drawingCoord`) and before any BT flip of the canvas — flip this canvas
+ * alongside it with `flipLinkCanvasVertically`.
+ */
+export function buildNodeLinkCanvas(
+  graph: AsciiGraph,
+  interactions: ReadonlyMap<string, NodeInteraction>,
+): LinkCanvas {
+  const [maxX, maxY] = canvasBounds(graph.canvas)
+  const linkCanvas = mkLinkCanvas(maxX, maxY)
+
+  for (const node of graph.nodes) {
+    if (!node.drawing || !node.drawingCoord) continue
+    const href = safeHref(interactions.get(node.name)?.href)
+    if (href === undefined) continue
+    markBoxLabelLinks(linkCanvas, node.drawing, node.drawingCoord, href)
+  }
+
+  return linkCanvas
+}
+
+// ============================================================================
+// Emitting link runs while serializing a row
+// ============================================================================
+
+/**
+ * Tracks the link state across one row's cells and hands back the escape
+ * text to insert before each cell: a close when leaving a linked run, an
+ * open when entering one (both when two different links touch), and
+ * nothing while the state is unchanged. `finish()` closes a run still open
+ * at the end of the row.
+ *
+ * The markers are pure insertions into the character stream — the SGR
+ * color grouping in `colorizeLine` is left exactly as it would be without
+ * links — so stripping every OSC 8 sequence from hyperlinked output yields
+ * the non-hyperlinked output byte for byte.
+ */
+export class LinkRunTracker {
+  private current: string | null = null
+
+  /** Escape text to emit before a cell carrying `link` (null = no link). */
+  advance(link: string | null): string {
+    if (link === this.current) return ''
+    let out = this.current !== null ? OSC8_CLOSE : ''
+    if (link !== null) out += osc8Open(link)
+    this.current = link
+    return out
+  }
+
+  /** Escape text to emit after the row's last cell. */
+  finish(): string {
+    const out = this.current !== null ? OSC8_CLOSE : ''
+    this.current = null
+    return out
+  }
+}
+
+/** Join a row's cells into plain (uncolored) text with OSC 8 pairs around each linked run. */
+export function joinWithLinks(
+  chars: readonly string[],
+  links: readonly (string | null)[],
+): string {
+  const tracker = new LinkRunTracker()
+  let line = ''
+  for (const [i, char] of chars.entries()) {
+    line += tracker.advance(links[i] ?? null) + char
+  }
+  return line + tracker.finish()
+}

package/src/index.ts

@@ -0,0 +1,163 @@
+// ============================================================================
+// zombie-mermaid — ASCII renderer public API
+//
+// Renders Mermaid diagrams to ASCII or Unicode box-drawing art.
+// No external dependencies — pure TypeScript.
+//
+// Supported diagram types:
+//   - Flowcharts (graph TD / flowchart LR) — grid-based layout with A* pathfinding
+//   - State diagrams (stateDiagram-v2) — same pipeline as flowcharts
+//   - Sequence diagrams (sequenceDiagram) — column-based timeline layout
+//   - Class diagrams (classDiagram) — level-based UML layout
+//   - ER diagrams (erDiagram) — grid layout with crow's foot notation
+//
+// Usage:
+//   import { renderMermaidASCII } from 'zombie-mermaid'
+//   const ascii = renderMermaidASCII('graph LR\n  A --> B')
+// ============================================================================
+
+import { detectDiagramType } from '@zombie-mermaid/core'
+import type { Direction, DiagramType } from '@zombie-mermaid/core'
+import { asciiRegistry } from './registry.ts'
+import { addCoordsOverlay } from './coords.ts'
+import {
+  detectColorMode,
+  DEFAULT_ASCII_THEME,
+  diagramColorsToAsciiTheme,
+} from './ansi.ts'
+import type { AsciiConfig, AsciiTheme, ColorMode } from './types.ts'
+import {
+  DEFAULT_PADDING_X,
+  DEFAULT_PADDING_Y,
+  DEFAULT_BOX_BORDER_PADDING,
+} from './types.ts'
+
+// Re-export types for external use
+export type { AsciiTheme, ColorMode }
+export { DEFAULT_ASCII_THEME, detectColorMode, diagramColorsToAsciiTheme }
+
+export interface AsciiRenderOptions {
+  /** true = ASCII chars (+,-,|,>), false = Unicode box-drawing (┌,─,│,►). Default: false */
+  useAscii?: boolean
+  /** Horizontal spacing between nodes. Default: 5 */
+  paddingX?: number
+  /** Vertical spacing between nodes. Default: 5 */
+  paddingY?: number
+  /** Padding inside node boxes. Default: 1 */
+  boxBorderPadding?: number
+  /**
+   * Color mode for output.
+   * - 'none': No colors (plain text)
+   * - 'auto': Auto-detect (terminal ANSI capabilities, or HTML in browsers)
+   * - 'ansi16': 16-color ANSI
+   * - 'ansi256': 256-color xterm
+   * - 'truecolor': 24-bit RGB
+   * - 'html': HTML <span> tags with inline color styles (for browser rendering)
+   * Default: 'auto'
+   */
+  colorMode?: ColorMode | 'auto'
+  /** Theme colors for ASCII output. Uses default theme if not provided. */
+  theme?: Partial<AsciiTheme>
+  /**
+   * Overlay spreadsheet-style row/column indices on the rendered output, to
+   * help debug layout spacing. Off by default.
+   */
+  showCoords?: boolean
+  /**
+   * Force the diagram's layout direction, overriding the one its source
+   * declares (a flowchart's `graph LR` header, or a state diagram's
+   * top-level `direction LR` line). Applied after parsing and before
+   * layout — the source text is never rewritten. Replaces only the
+   * top-level direction: a nested subgraph's or composite state's own
+   * `direction` line still applies on top of it, exactly as it does on top
+   * of the diagram's own header.
+   *
+   * Flowchart and state diagrams only in ASCII output. The ASCII ER layout
+   * has no direction concept (it already ignores a source `direction`
+   * line), and sequence/class/XY-chart diagrams have none to override, so
+   * all of those ignore this option (no error; output is identical with or
+   * without it). Same semantics as `RenderOptions.direction` for SVG. See
+   * issue #276.
+   */
+  direction?: Direction
+  /**
+   * Emit OSC 8 terminal hyperlinks: each node whose `click` directive
+   * declared an http/https/mailto/relative href gets its label wrapped in
+   * an `ESC ] 8 ; ; <url> ESC \` … `ESC ] 8 ; ; ESC \` pair, which
+   * terminals that support OSC 8 (iTerm2, WezTerm, kitty, Windows
+   * Terminal, VTE-based terminals) render as a clickable link. The
+   * sequences are zero-width and never affect layout; `click ... call fn()`
+   * bindings emit nothing. Off by default — not every terminal or pager
+   * handles OSC 8 gracefully (`less` needs `-R`), and no capability
+   * detection is attempted here; the caller decides. Ignored when
+   * `colorMode` is 'html'.
+   */
+  hyperlinks?: boolean
+}
+
+/**
+ * Render Mermaid diagram text to an ASCII/Unicode string.
+ *
+ * Synchronous — no async layout engine needed (unlike the SVG renderer).
+ * Auto-detects diagram type from the header line and dispatches to
+ * the appropriate renderer.
+ *
+ * @param text - Mermaid source text (any supported diagram type)
+ * @param options - Rendering options
+ * @returns Multi-line ASCII/Unicode string
+ *
+ * @example
+ * ```ts
+ * const result = renderMermaidASCII(`
+ *   graph LR
+ *     A --> B --> C
+ * `, { useAscii: true })
+ *
+ * // Output:
+ * // +---+     +---+     +---+
+ * // |   |     |   |     |   |
+ * // | A |---->| B |---->| C |
+ * // |   |     |   |     |   |
+ * // +---+     +---+     +---+
+ * ```
+ */
+export function renderMermaidASCII(
+  text: string,
+  options: AsciiRenderOptions = {},
+): string {
+  const config: AsciiConfig = {
+    useAscii: options.useAscii ?? false,
+    paddingX: options.paddingX ?? DEFAULT_PADDING_X,
+    paddingY: options.paddingY ?? DEFAULT_PADDING_Y,
+    boxBorderPadding: options.boxBorderPadding ?? DEFAULT_BOX_BORDER_PADDING,
+    graphDirection: 'TD', // default; renderFlowchartAscii overrides this for flowcharts/state diagrams
+  }
+
+  // Resolve color mode ('auto' or unset → detect environment, otherwise use specified mode)
+  const colorMode: ColorMode =
+    options.colorMode === 'auto' || options.colorMode === undefined
+      ? detectColorMode()
+      : options.colorMode
+
+  // Merge user theme with defaults
+  const theme: AsciiTheme = { ...DEFAULT_ASCII_THEME, ...options.theme }
+
+  const diagramType: DiagramType = detectDiagramType(text)
+
+  // Registry dispatch (see src/ascii/registry.ts — issue #533 / #745):
+  // every diagram type, including 'flowchart', is registered there and
+  // dispatches to the exact same renderer calls each type's original
+  // switch case (or, for 'flowchart', inline sequence) used to make.
+  // `extras` carries every ASCII-only per-type option: `hyperlinks` (read
+  // by 'class' and 'flowchart') and `direction` (read by 'flowchart'
+  // only); both are ignored by every other registered type.
+  const result = asciiRegistry[diagramType](text, config, colorMode, theme, {
+    hyperlinks: options.hyperlinks ?? false,
+    direction: options.direction,
+  })
+
+  return options.showCoords ? addCoordsOverlay(result) : result
+}
+
+/** @deprecated Use `renderMermaidASCII` */
+export const renderMermaidAscii = renderMermaidASCII

package/src/lane-search.ts

@@ -0,0 +1,68 @@
+// ============================================================================
+// ASCII renderers — shared "nearest free lane" search
+//
+// `er-diagram.ts` (`chooseFreeRow`) and `class-diagram.ts`
+// (`findClearColumn`) independently grew the same search: start at a
+// preferred row/column, and if that one is occupied, walk outward one step
+// at a time — forward first, then backward — until a candidate passes the
+// caller's occupancy check.
+//
+// Only the *search order* is shared here. The occupancy check itself stays
+// with each renderer and arrives as a callback, because the two renderers
+// answer "is this lane usable?" from genuinely different sources: ER scans
+// the rendered canvas itself, while class-diagram tests against the placed
+// box rectangles. Unifying that *storage* was scoped out as unsafe — see
+// `docs/decisions/ascii-occupancy-unification-532.md` (issue #532) — so this
+// module deliberately extracts the algorithm and nothing else.
+// ============================================================================
+
+/**
+ * Caller-supplied occupancy check: whether the whole region a candidate
+ * lane would occupy is usable. Called at most once per candidate, and only
+ * for candidates already inside `[min, max]` (plus `preferred`, see below),
+ * so an expensive check isn't run on lanes that would be rejected anyway.
+ */
+export type LaneFree = (candidate: number) => boolean
+
+/**
+ * Find the nearest usable lane (a row or a column) to `preferred`, scanning
+ * outward in alternating directions and stopping at the first candidate
+ * `isFree` accepts.
+ *
+ * Search order: `preferred`, then `preferred + 1`, `preferred - 1`,
+ * `preferred + 2`, `preferred - 2`, … — the forward direction is always
+ * tried first at each distance, which is what both original call sites did
+ * (ER scanned below-then-above; class-diagram right-then-left).
+ *
+ * `min`/`max` are *inclusive* bounds on the outward candidates only.
+ * `preferred` itself is tested unconditionally, even when it falls outside
+ * them: both call sites relied on that. ER's bounds are the open interval
+ * between two entity borders, so a gap too narrow to hold any candidate row
+ * still lets the plain midpoint through; class-diagram's `min` of 0 keeps
+ * the search on-canvas while `preferred` is a box's own centre column.
+ *
+ * Returns `undefined` when no candidate in range is free — including when
+ * `min > max` leaves no candidates at all. Each caller supplies its own
+ * fallback for that case (they differ), rather than this function inventing
+ * one.
+ */
+export function findFreeLane(
+  preferred: number,
+  min: number,
+  max: number,
+  isFree: LaneFree,
+): number | undefined {
+  if (isFree(preferred)) return preferred
+
+  // Far enough to reach whichever bound is further from `preferred`; beyond
+  // that every remaining candidate is out of range in both directions.
+  const maxOffset = Math.max(preferred - min, max - preferred)
+  for (let offset = 1; offset <= maxOffset; offset++) {
+    const forward = preferred + offset
+    if (forward <= max && isFree(forward)) return forward
+    const backward = preferred - offset
+    if (backward >= min && isFree(backward)) return backward
+  }
+
+  return undefined
+}

package/src/multiline-utils.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// ASCII renderer — multi-line text utilities
+//
+// Shared utilities for handling multi-line labels (containing \n from <br> tags)
+// in ASCII/Unicode rendering. Provides consistent text splitting, sizing, and
+// centered rendering across all diagram types.
+// ============================================================================
+
+import type { Canvas } from './types.ts'
+import { drawText } from './canvas.ts'
+import { displayWidth } from './display-width.ts'
+
+/**
+ * Split a label into lines.
+ * Labels are already normalized by parsers (br tags → \n).
+ */
+export function splitLines(label: string): string[] {
+  return label.split('\n')
+}
+
+/**
+ * Get the maximum line width (in terminal display columns) for sizing
+ * calculations. Used to determine column widths for multi-line labels.
+ *
+ * Uses `displayWidth` rather than `.length` so CJK/kana/hangul/fullwidth-form
+ * and emoji characters — which render as two terminal columns each — are
+ * accounted for correctly. Using code-unit `.length` here would produce
+ * boxes too narrow for wide-character labels.
+ */
+export function maxLineWidth(label: string): number {
+  const lines = splitLines(label)
+  return Math.max(...lines.map((l) => displayWidth(l)), 0)
+}
+
+/**
+ * Get the number of lines for height calculations.
+ * Used to determine row heights for multi-line labels.
+ */
+export function lineCount(label: string): number {
+  return splitLines(label).length
+}
+
+/**
+ * Draw multi-line text centered at (cx, cy).
+ * Expands vertically from the center point.
+ * Each line is horizontally centered independently.
+ */
+export function drawMultilineTextCentered(
+  canvas: Canvas,
+  label: string,
+  cx: number,
+  cy: number,
+): void {
+  const lines = splitLines(label)
+  const totalHeight = lines.length
+  // Center vertically: start y positions lines evenly around cy
+  const startY = cy - Math.floor((totalHeight - 1) / 2)
+
+  for (const [i, line] of lines.entries()) {
+    // Center each line horizontally (in display columns, not code units)
+    const startX = cx - Math.floor(displayWidth(line) / 2)
+    // Force overwrite for node labels (they take priority)
+    drawText(canvas, { x: startX, y: startY + i }, line, true)
+  }
+}
+
+/**
+ * Draw multi-line text left-aligned starting at (x, y).
+ * Each subsequent line is placed one row below.
+ */
+export function drawMultilineTextLeft(
+  canvas: Canvas,
+  label: string,
+  x: number,
+  y: number,
+): void {
+  const lines = splitLines(label)
+  for (const [i, line] of lines.entries()) {
+    // Force overwrite for node labels (they take priority)
+    drawText(canvas, { x, y: y + i }, line, true)
+  }
+}