@zombie-mermaid/ascii-renderer 2.2.1

package/src/converter.ts

@@ -0,0 +1,446 @@
+// ============================================================================
+// ASCII renderer — MermaidGraph → AsciiGraph converter
+//
+// Bridges the existing TypeScript parser output to the ASCII renderer's
+// internal graph structure. This avoids maintaining a separate parser
+// for ASCII rendering — we reuse parseMermaid() and convert its output.
+// ============================================================================
+
+import type { MermaidGraph, MermaidSubgraph } from '@zombie-mermaid/core'
+import type {
+  AsciiGraph,
+  AsciiNode,
+  AsciiEdge,
+  AsciiSubgraph,
+  AsciiConfig,
+} from './types.ts'
+import { EMPTY_STYLE } from './types.ts'
+import { mkCanvas, mkRoleCanvas } from './canvas.ts'
+import { createGrid } from './grid-occupancy.ts'
+import { stripFormattingTags } from '@zombie-mermaid/core'
+
+/**
+ * Convert a parsed MermaidGraph into an AsciiGraph ready for grid layout.
+ *
+ * Key mappings:
+ * - MermaidGraph.nodes (Map) → ordered AsciiNode[] preserving insertion order
+ * - MermaidGraph.edges → AsciiEdge[] with resolved node references
+ * - MermaidGraph.subgraphs → AsciiSubgraph[] with parent/child tree
+ * - Node labels are used as display names (not raw IDs)
+ */
+export function convertToAsciiGraph(
+  parsed: MermaidGraph,
+  config: AsciiConfig,
+): AsciiGraph {
+  // Collect subgraph ids (including nested) up front. When a flowchart edge
+  // references a subgraph id directly (e.g. `ONE --> TWO` where ONE/TWO are
+  // subgraph ids, not nodes — see issue #65), the parser has no way to know
+  // that at parse time and registers a phantom node with that id instead.
+  // The ELK/SVG path resolves this by never materializing a top-level node
+  // for a subgraph id and letting the edge reference the compound subgraph
+  // node directly (see `mermaidToElk` in to-elk.ts). The ASCII grid has no
+  // equivalent "compound node as edge endpoint" concept, so instead we
+  // suppress the phantom node here and, below, redirect any edge that
+  // targets a subgraph id to a real member node at that subgraph's
+  // boundary — see `resolveSubgraphEndpoint`.
+  const subgraphIds = new Set<string>()
+  const subgraphById = new Map<string, MermaidSubgraph>()
+  for (const mSg of parsed.subgraphs) {
+    indexSubgraph(mSg, subgraphIds, subgraphById)
+  }
+
+  // Build node list preserving Map insertion order
+  const nodeMap = new Map<string, AsciiNode>()
+  let index = 0
+
+  for (const [id, mNode] of parsed.nodes) {
+    // Skip phantom nodes that only exist because a subgraph id was
+    // referenced as an edge endpoint — see comment above.
+    if (subgraphIds.has(id)) continue
+
+    const asciiNode: AsciiNode = {
+      // Use the parser ID as the unique identity key to avoid collisions
+      // when multiple nodes share the same label (e.g. A[Web Server], C[Web Server]).
+      name: id,
+      // The label is used for rendering inside the box. Inline formatting
+      // tags (<b>, <i>, <em>, <strong>, ...) are meaningful to the SVG
+      // renderer (rendered as styled tspans) but the ASCII renderer has no
+      // equivalent concept, so they're stripped here rather than shown
+      // literally — see issue #65.
+      displayLabel: stripFormattingTags(mNode.label),
+      // Preserve shape from parser for shape-aware rendering
+      shape: mNode.shape,
+      index,
+      gridCoord: null,
+      drawingCoord: null,
+      drawing: null,
+      drawn: false,
+      styleClassName: '',
+      styleClass: EMPTY_STYLE,
+    }
+    nodeMap.set(id, asciiNode)
+    index++
+  }
+
+  const nodes = [...nodeMap.values()]
+
+  // Build edges with resolved node references
+  const edges: AsciiEdge[] = []
+  for (const mEdge of parsed.edges) {
+    let sourceId = mEdge.source
+    let targetId = mEdge.target
+
+    if (subgraphIds.has(sourceId)) {
+      const mSg = subgraphById.get(sourceId)
+      const resolved = mSg
+        ? resolveSubgraphEndpoint(mSg, parsed, 'exit')
+        : undefined
+      if (resolved) sourceId = resolved
+    }
+    if (subgraphIds.has(targetId)) {
+      const mSg = subgraphById.get(targetId)
+      const resolved = mSg
+        ? resolveSubgraphEndpoint(mSg, parsed, 'entry')
+        : undefined
+      if (resolved) targetId = resolved
+    }
+
+    const from = nodeMap.get(sourceId)
+    const to = nodeMap.get(targetId)
+    if (!from || !to) continue
+
+    edges.push({
+      from,
+      to,
+      text: mEdge.label ? stripFormattingTags(mEdge.label) : '',
+      path: [],
+      labelLine: [],
+      startDir: { x: 0, y: 0 },
+      endDir: { x: 0, y: 0 },
+      style: mEdge.style,
+      hasArrowStart: mEdge.hasArrowStart,
+      hasArrowEnd: mEdge.hasArrowEnd,
+      ...(mEdge.startMarker !== undefined
+        ? { startMarker: mEdge.startMarker }
+        : {}),
+      ...(mEdge.endMarker !== undefined ? { endMarker: mEdge.endMarker } : {}),
+    })
+  }
+
+  // Convert subgraphs recursively
+  const subgraphs: AsciiSubgraph[] = []
+  for (const mSg of parsed.subgraphs) {
+    convertSubgraph(mSg, null, nodeMap, subgraphs, parsed)
+  }
+
+  // Deduplicate subgraph node membership to match Go parser behavior.
+  // In Go, a node belongs only to the subgraph where it was FIRST DEFINED.
+  // The TS parser adds referenced nodes to all subgraphs they appear in,
+  // which causes incorrect bounding boxes when nodes span subgraph boundaries.
+  deduplicateSubgraphNodes(parsed.subgraphs, subgraphs, nodeMap)
+
+  /*
+   * `classDef default` is Mermaid's implicit base style for every node, not
+   * just for nodes that name it. Apply it to all nodes first so an explicit
+   * assignment below can override it property by property.
+   */
+  const defaultDef = parsed.classDefs.get('default')
+  if (defaultDef) {
+    for (const node of nodeMap.values()) {
+      node.styleClassName = 'default'
+      node.styleClass = { name: 'default', styles: defaultDef }
+    }
+  }
+
+  // Apply class definitions
+  for (const [nodeId, className] of parsed.classAssignments) {
+    const node = nodeMap.get(nodeId)
+    const classDef = parsed.classDefs.get(className)
+    if (node && classDef) {
+      node.styleClassName = className
+      node.styleClass = {
+        name: className,
+        styles: defaultDef ? { ...defaultDef, ...classDef } : classDef,
+      }
+    }
+  }
+
+  return {
+    nodes,
+    edges,
+    canvas: mkCanvas(0, 0),
+    roleCanvas: mkRoleCanvas(0, 0),
+    grid: createGrid(),
+    columnWidth: new Map(),
+    rowHeight: new Map(),
+    subgraphs,
+    config,
+    offsetX: 0,
+    offsetY: 0,
+    bundles: [], // Populated by analyzeEdgeBundles() during layout
+  }
+}
+
+/**
+ * Recursively index a subgraph (and its nested children) by id, for
+ * resolving subgraph-id edge endpoints — see issue #65 and the comment in
+ * `convertToAsciiGraph`.
+ */
+function indexSubgraph(
+  mSg: MermaidSubgraph,
+  subgraphIds: Set<string>,
+  subgraphById: Map<string, MermaidSubgraph>,
+): void {
+  subgraphIds.add(mSg.id)
+  subgraphById.set(mSg.id, mSg)
+  for (const child of mSg.children) {
+    indexSubgraph(child, subgraphIds, subgraphById)
+  }
+}
+
+/** Recursively collect every node id that's a member of `mSg` or its nested children. */
+function collectAllMemberNodeIds(mSg: MermaidSubgraph, out: Set<string>): void {
+  for (const id of mSg.nodeIds) out.add(id)
+  for (const child of mSg.children) collectAllMemberNodeIds(child, out)
+}
+
+/**
+ * Real mermaid.js ignores a subgraph's own `direction` override once any of
+ * its member nodes (including nested descendants) has an edge to something
+ * outside the subgraph — the subgraph then inherits the parent graph's
+ * direction instead. Per the docs: "If any of a subgraph's nodes are linked
+ * to the outside, subgraph direction will be ignored. Instead the subgraph
+ * will inherit the direction of the parent graph."
+ * https://mermaid.js.org/syntax/flowchart.html
+ *
+ * Verified against real mermaid.js output for issue #445 (`graph TD` +
+ * `direction LR` subgraph with `E --> A` / `D --> F` edges crossing the
+ * boundary): all member nodes render at the same x-coordinate with
+ * increasing y, i.e. stacked top-down per the outer `TD` direction, despite
+ * the subgraph's own `direction LR`.
+ */
+function subgraphDirectionIsHonored(
+  mSg: MermaidSubgraph,
+  parsed: MermaidGraph,
+): boolean {
+  const memberIds = new Set<string>()
+  collectAllMemberNodeIds(mSg, memberIds)
+  if (memberIds.size === 0) return true
+
+  const isInside = (id: string): boolean => memberIds.has(id) || id === mSg.id
+
+  return !parsed.edges.some((e) => isInside(e.source) !== isInside(e.target))
+}
+
+/**
+ * Pick a real member node to stand in for a subgraph when it's used as an
+ * edge endpoint (e.g. `ONE --> TWO` where ONE/TWO are subgraph ids — issue
+ * #65). The ASCII grid can only route edges between real nodes, so an edge
+ * "into" the subgraph is anchored to the subgraph's entry (root) node — a
+ * member with no incoming edge from another member of the same subgraph —
+ * and an edge "out of" the subgraph is anchored to its exit (leaf) node —
+ * a member with no outgoing edge to another member. That mirrors how the
+ * edge would visually enter/exit the subgraph's frame, reusing the
+ * existing (already-working) cross-subgraph edge-routing path instead of
+ * inventing a new "compound node" concept in the grid layout.
+ */
+function resolveSubgraphEndpoint(
+  mSg: MermaidSubgraph,
+  parsed: MermaidGraph,
+  end: 'entry' | 'exit',
+): string | undefined {
+  const memberIds = new Set<string>()
+  collectAllMemberNodeIds(mSg, memberIds)
+  if (memberIds.size === 0) return undefined
+
+  // Preserve overall node declaration order for deterministic selection.
+  const orderedIds = [...parsed.nodes.keys()].filter((id) => memberIds.has(id))
+  if (orderedIds.length === 0) return undefined
+
+  const candidates = orderedIds.filter((id) =>
+    end === 'entry'
+      ? !parsed.edges.some((e) => e.target === id && memberIds.has(e.source))
+      : !parsed.edges.some((e) => e.source === id && memberIds.has(e.target)),
+  )
+
+  const pool = candidates.length > 0 ? candidates : orderedIds
+  return end === 'entry' ? pool[0] : pool[pool.length - 1]
+}
+
+/**
+ * Recursively convert a MermaidSubgraph to AsciiSubgraph.
+ * Flattens the tree into the subgraphs array while maintaining parent/child references.
+ * This matches the Go implementation where all subgraphs are in a flat list
+ * but linked via parent/children pointers.
+ */
+function convertSubgraph(
+  mSg: MermaidSubgraph,
+  parent: AsciiSubgraph | null,
+  nodeMap: Map<string, AsciiNode>,
+  allSubgraphs: AsciiSubgraph[],
+  parsed: MermaidGraph,
+): AsciiSubgraph {
+  // Normalize subgraph direction: BT→TD, RL→LR (same as root graph normalization).
+  // A subgraph with an edge crossing its own boundary loses its direction
+  // override in real mermaid.js (see subgraphDirectionIsHonored) — skip
+  // normalizing it in that case so it falls through to the parent's
+  // direction like everything else.
+  let normalizedDirection: 'LR' | 'TD' | undefined
+  if (mSg.direction && subgraphDirectionIsHonored(mSg, parsed)) {
+    normalizedDirection =
+      mSg.direction === 'LR' || mSg.direction === 'RL' ? 'LR' : 'TD'
+  }
+
+  const sg: AsciiSubgraph = {
+    name: mSg.label,
+    nodes: [],
+    parent,
+    children: [],
+    minX: 0,
+    minY: 0,
+    maxX: 0,
+    maxY: 0,
+    direction: normalizedDirection,
+  }
+
+  // Resolve node references
+  for (const nodeId of mSg.nodeIds) {
+    const node = nodeMap.get(nodeId)
+    if (node) sg.nodes.push(node)
+  }
+
+  allSubgraphs.push(sg)
+
+  // Recurse into children
+  for (const childMSg of mSg.children) {
+    const child = convertSubgraph(childMSg, sg, nodeMap, allSubgraphs, parsed)
+    sg.children.push(child)
+
+    // Child nodes are also part of parent subgraphs (Go behavior).
+    // The Go parser adds nodes to ALL subgraphs in the stack, so a nested
+    // node belongs to both the inner and outer subgraph.
+    for (const childNode of child.nodes) {
+      if (!sg.nodes.includes(childNode)) {
+        sg.nodes.push(childNode)
+      }
+    }
+  }
+
+  return sg
+}
+
+/**
+ * Deduplicate subgraph node membership to match Go parser behavior.
+ *
+ * The Go parser only adds a node to the subgraph that was active when the node
+ * was FIRST CREATED. If a node is later referenced inside a different subgraph,
+ * it is NOT added to that subgraph. The TS parser is more permissive — it adds
+ * referenced nodes to whichever subgraph they appear in.
+ *
+ * This function fixes the discrepancy by:
+ * 1. Walking the edges to determine which nodes were first created inside each subgraph
+ * 2. Removing nodes from subgraphs where they weren't first created
+ */
+function deduplicateSubgraphNodes(
+  mermaidSubgraphs: MermaidSubgraph[],
+  asciiSubgraphs: AsciiSubgraph[],
+  nodeMap: Map<string, AsciiNode>,
+): void {
+  // Build a map from MermaidSubgraph to its corresponding AsciiSubgraph.
+  // The ordering matches since we convert them in the same order.
+  const sgMap = new Map<MermaidSubgraph, AsciiSubgraph>()
+  buildSgMap(mermaidSubgraphs, asciiSubgraphs, sgMap)
+
+  // Determine which subgraph each node was "first defined" in.
+  // A node is first defined in the subgraph where it first appears as a NEW node
+  // in the ordered edge/node list. We approximate this by checking the global
+  // node insertion order against subgraph membership.
+  const nodeOwner = new Map<string, AsciiSubgraph>() // nodeId → owning subgraph
+
+  // Walk all mermaid subgraphs in document order. For each subgraph,
+  // claim nodes that haven't been claimed yet by any previous subgraph.
+  function claimNodes(mSg: MermaidSubgraph): void {
+    const asciiSg = sgMap.get(mSg)
+    if (!asciiSg) return
+
+    // Recurse into children first (they appear before parent in the Go parser stack,
+    // but nodes defined in children are added to parent too — this is handled by
+    // the convertSubgraph function which propagates child nodes to parents).
+    // For dedup, we process children first so their claims propagate up correctly.
+    for (const child of mSg.children) {
+      claimNodes(child)
+    }
+
+    // Claim unclaimed nodes in this subgraph
+    for (const nodeId of mSg.nodeIds) {
+      if (!nodeOwner.has(nodeId)) {
+        nodeOwner.set(nodeId, asciiSg)
+      }
+    }
+  }
+
+  for (const mSg of mermaidSubgraphs) {
+    claimNodes(mSg)
+  }
+
+  // Now remove nodes from subgraphs that don't own them.
+  // A node should remain in: its owner subgraph + all ancestors of the owner.
+  for (const asciiSg of asciiSubgraphs) {
+    asciiSg.nodes = asciiSg.nodes.filter((node) => {
+      // Find this node's ID in the nodeMap
+      let nodeId: string | undefined
+      for (const [id, n] of nodeMap) {
+        if (n === node) {
+          nodeId = id
+          break
+        }
+      }
+      if (!nodeId) return false
+
+      const owner = nodeOwner.get(nodeId)
+      if (!owner) return true // not in any subgraph claim — keep as-is
+
+      // Keep the node if this subgraph is the owner or an ancestor of the owner
+      return isAncestorOrSelf(asciiSg, owner)
+    })
+  }
+}
+
+/** Check if `candidate` is the same as or an ancestor of `target`. */
+function isAncestorOrSelf(
+  candidate: AsciiSubgraph,
+  target: AsciiSubgraph,
+): boolean {
+  let current: AsciiSubgraph | null = target
+  while (current !== null) {
+    if (current === candidate) return true
+    current = current.parent
+  }
+  return false
+}
+
+/** Build a mapping from MermaidSubgraph → AsciiSubgraph (matching by position). */
+function buildSgMap(
+  mSgs: MermaidSubgraph[],
+  aSgs: AsciiSubgraph[],
+  result: Map<MermaidSubgraph, AsciiSubgraph>,
+): void {
+  // The asciiSubgraphs array is flat (all subgraphs including nested ones),
+  // while mermaidSubgraphs is hierarchical. We need to flatten the mermaid tree
+  // in the same order the converter processes them (pre-order DFS).
+  const flatMermaid: MermaidSubgraph[] = []
+  function flatten(sgs: MermaidSubgraph[]): void {
+    for (const sg of sgs) {
+      flatMermaid.push(sg)
+      flatten(sg.children)
+    }
+  }
+  flatten(mSgs)
+
+  for (let i = 0; i < flatMermaid.length && i < aSgs.length; i++) {
+    const mSg = flatMermaid[i]
+    const aSg = aSgs[i]
+    if (!mSg || !aSg) continue
+    result.set(mSg, aSg)
+  }
+}

package/src/coords.ts

@@ -0,0 +1,58 @@
+// ============================================================================
+// ASCII renderer — debug coordinate overlay (`--coords`)
+//
+// Annotates a finished, rendered ASCII/Unicode string with spreadsheet-style
+// row/column indices — numbered column headers across the top, row numbers
+// down the left side — to help debug layout spacing (padding, box sizes,
+// edge routing) without having to count characters by hand.
+//
+// This deliberately overlays the *character* grid of the final rendered
+// output, not the internal logical grid used by grid.ts (AsciiGraph's
+// node-placement lattice, where each node occupies a 3x3 block on a 4-unit
+// step). The internal grid has no 1:1 relationship with rendered character
+// columns/rows (column widths and row heights vary per node), so annotating
+// it directly wouldn't produce a marker a user looking at the printed
+// diagram could actually line up against. The character grid is what's
+// visible on screen, so its indices are what's useful to overlay.
+// ============================================================================
+
+import { stripOsc8 } from './hyperlinks.ts'
+
+/**
+ * Add a column-index ruler (two rows: tens digit, ones digit) above the
+ * diagram and a row-index gutter to the left of each line.
+ *
+ * Purely a string transform over the already-rendered output — safe to
+ * apply regardless of diagram type, color mode, or Unicode/ASCII mode.
+ */
+// Matches SGR color escape sequences (`\x1b[...m`) produced by ansi.ts's
+// ansi16/ansi256/truecolor modes. Stripped — along with any OSC 8
+// hyperlink sequences (hyperlinks.ts) — only for width MEASUREMENT below;
+// the original lines (with codes intact) are still what gets printed.
+const ANSI_ESCAPE = /\x1b\[[0-9;]*m/g
+
+export function addCoordsOverlay(rendered: string): string {
+  const lines = rendered.split('\n')
+  const width = lines.reduce(
+    (max, line) =>
+      Math.max(max, stripOsc8(line.replace(ANSI_ESCAPE, '')).length),
+    0,
+  )
+  const rowGutterWidth = String(Math.max(0, lines.length - 1)).length
+
+  const gutter = ' '.repeat(rowGutterWidth + 1)
+  const tensRow =
+    gutter +
+    Array.from({ length: width }, (_, x) =>
+      String(Math.floor(x / 10) % 10),
+    ).join('')
+  const onesRow =
+    gutter + Array.from({ length: width }, (_, x) => String(x % 10)).join('')
+
+  const bodyLines = lines.map((line, y) => {
+    const rowLabel = String(y).padStart(rowGutterWidth, ' ')
+    return `${rowLabel} ${line}`
+  })
+
+  return [tensRow, onesRow, ...bodyLines].join('\n')
+}

package/src/display-width.ts

@@ -0,0 +1,151 @@
+// ============================================================================
+// ASCII renderer — display width helpers
+//
+// The ASCII grid is column-major with one grid cell reserved per *grapheme
+// cluster* — the Unicode notion of a single user-perceived character, which
+// may span several JS code points. Measuring by code point instead breaks in
+// two opposite directions:
+//
+//   - A combining mark (e.g. decomposed "e" + U+0301 COMBINING ACUTE ACCENT)
+//     is its own code point but claims no terminal column of its own — it
+//     attaches to the preceding base character. Counting it as a full column
+//     overcounts (issue #205).
+//   - A composed emoji sequence (ZWJ family emoji, flag via regional
+//     indicators, skin-tone modifier) is several code points that render as
+//     ONE glyph occupying at most 2 terminal columns. Counting each code
+//     point separately overcounts even more badly (issue #214).
+//
+// Segmenting by grapheme cluster (`Intl.Segmenter`) and measuring each
+// cluster as a unit fixes both: a cluster is 2 columns if any code point
+// within it is "wide" (CJK etc, via the same `isWideChar` the SVG
+// text-measurement path uses), else 1 column — except a cluster made
+// entirely of combining marks with no base character, which is 0 columns
+// (the degenerate case the general Unicode categories Mn/Me describe;
+// ordinarily unreachable since a mark attaches to a preceding base within
+// the same cluster, but handled explicitly for a lone/leading mark).
+//
+// This module is the single source of truth for "how many terminal columns
+// does this text occupy" and "how many grid cells does writing it need"
+// across the ASCII renderer.
+// ============================================================================
+
+import { isWideChar } from '@zombie-mermaid/core'
+
+/**
+ * Placeholder written into the grid cell immediately following a wide
+ * grapheme cluster. It reserves a grid column — keeping every subsequent
+ * cell's x-index aligned with the same column in other rows (borders, other
+ * labels, etc.) — but contributes no text when a canvas row is joined into
+ * a string, because the wide glyph itself already renders across two
+ * terminal columns.
+ */
+export const WIDE_CHAR_PLACEHOLDER = ''
+
+/** Unicode general categories Mn (Nonspacing_Mark) and Me (Enclosing_Mark). */
+const COMBINING_MARK_REGEX = /\p{Mn}|\p{Me}/u
+
+function isCombiningMark(char: string): boolean {
+  return COMBINING_MARK_REGEX.test(char)
+}
+
+const graphemeSegmenter = new Intl.Segmenter(undefined, {
+  granularity: 'grapheme',
+})
+
+/**
+ * U+FE0F VARIATION SELECTOR-16 explicitly requests the emoji (wide)
+ * presentation for the preceding base character, overriding whatever that
+ * character's own default presentation is. `isWideChar` only ever sees one
+ * isolated code point at a time (it's shared with the SVG text-measurement
+ * path, which has no grapheme-cluster concept), so it has no way to look
+ * ahead for a following VS16 — that requires cluster-level context, which
+ * only exists here. A base character normally classified narrow (e.g. ▶
+ * U+25B6, excluded from `isWideChar` as a Geometric Shapes glyph — see
+ * `isGeometricShapesTextDefault` in text-metrics.ts) still renders as a
+ * double-width emoji glyph in ▶️ once VS16 forces emoji presentation.
+ */
+const VARIATION_SELECTOR_16 = '\u{FE0F}'
+
+/**
+ * Split text into grapheme clusters — user-perceived characters. A cluster
+ * may span multiple JS code points: a combining mark attaches to its base
+ * character, and a ZWJ emoji sequence / flag / skin-tone modifier sequence
+ * forms a single rendered glyph. Naive code-point iteration (`for...of`)
+ * tears these apart, which is the root cause of both #205 and #214.
+ */
+function graphemeClusters(text: string): string[] {
+  const clusters: string[] = []
+  for (const { segment } of graphemeSegmenter.segment(text)) {
+    clusters.push(segment)
+  }
+  return clusters
+}
+
+/**
+ * Number of terminal display columns a single grapheme cluster occupies.
+ * Always 0, 1, or 2 for the ASCII grid (unlike the fractional SVG metrics in
+ * `text-metrics.ts`, which model proportional-font rendering).
+ *
+ * - 2 if any code point in the cluster is "wide" (`isWideChar`) — covers
+ *   both plain CJK/fullwidth characters and composed emoji sequences, since
+ *   the sequence's base emoji code point is itself flagged wide.
+ * - 0 if the cluster consists entirely of combining marks (Mn/Me) with no
+ *   base character — a degenerate case in practice, since a mark normally
+ *   attaches to a preceding base within the same cluster instead of forming
+ *   a standalone one.
+ * - 1 otherwise, including a base character followed by zero-width
+ *   combining marks (e.g. decomposed "é"), since the marks contribute no
+ *   additional column within their cluster.
+ *
+ * A cluster containing VS16 (see `VARIATION_SELECTOR_16` above) is always
+ * width 2, regardless of what `isWideChar` reports for its base character —
+ * VS16 is an explicit, cluster-level request for emoji presentation that a
+ * single isolated code point can't express.
+ */
+export function charDisplayWidth(cluster: string): number {
+  if (cluster.includes(VARIATION_SELECTOR_16)) return 2
+  let sawWide = false
+  let sawNonMark = false
+  for (const ch of cluster) {
+    if (isWideChar(ch)) sawWide = true
+    if (!isCombiningMark(ch)) sawNonMark = true
+  }
+  if (sawWide) return 2
+  return sawNonMark ? 1 : 0
+}
+
+/**
+ * Total terminal display width of a string, measured per grapheme cluster
+ * (not per code point or UTF-16 code unit) so combining marks and composed
+ * emoji sequences are each counted once, correctly.
+ */
+export function displayWidth(text: string): number {
+  let width = 0
+  for (const cluster of graphemeClusters(text)) {
+    width += charDisplayWidth(cluster)
+  }
+  return width
+}
+
+/**
+ * Split a string into grid cells for canvas writing.
+ *
+ * Each grapheme cluster produces one cell containing the full cluster text
+ * (so a combining mark shares its base character's cell instead of
+ * claiming one of its own). A wide cluster (display width 2) additionally
+ * produces a trailing `WIDE_CHAR_PLACEHOLDER` cell. This keeps grid-cell
+ * count in sync with display-column count so that box-width math (computed
+ * via `displayWidth`) and the actual character-writing loop agree — a
+ * zero-width cluster (a lone combining mark with no base) contributes no
+ * cell at all, since it claims no column.
+ */
+export function toDisplayCells(text: string): string[] {
+  const cells: string[] = []
+  for (const cluster of graphemeClusters(text)) {
+    const width = charDisplayWidth(cluster)
+    if (width === 0) continue
+    cells.push(cluster)
+    if (width === 2) cells.push(WIDE_CHAR_PLACEHOLDER)
+  }
+  return cells
+}