opentui-markdown-render 0.0.0-stage → 0.2.0

package/src/merman/class/parser.ts

@@ -0,0 +1,308 @@
+import { firstMeaningfulMermaidLine, meaningfulNumberedMermaidLines, stripMermaidQuotes } from "../core/mermaid.js"
+import { MermaidSyntaxError } from "../diagnostics.js"
+import type {
+  ClassDefinition,
+  ClassDiagram,
+  ClassDiagramDirection,
+  ClassMember,
+  ClassRelationship,
+  ClassRelationshipKind,
+} from "./types.js"
+
+const HEADER_RE = /^classDiagram(?:\s+(TB|BT|LR|RL))?$/i
+const DIRECTION_RE = /^direction\s+(TB|BT|LR|RL)$/i
+const ACCESSIBILITY_RE = /^acc(?:Title|Descr)(?::|\s|$)/i
+const CLASS_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_.\-~]*$/
+const ANNOTATION_RE = /^<<(.+?)>>\s+(.+)$/
+const STEREOTYPE_ONLY_RE = /^<<(.+?)>>$/
+const CLASS_LABEL_RE = /^([A-Za-z0-9_][A-Za-z0-9_.\-~]*)\s*\[(["'])(.+)\2\]$/
+const CLASS_NOTE_RE = /^note\s+for\s+(\S+)\s+(["'])(.+)\2$/i
+
+interface RelationshipOperator {
+  token: string
+  kind: ClassRelationshipKind
+  headAt: "from" | "to" | "none"
+  dashed: boolean
+}
+
+// Longest first so `--|>` wins over `--` and `-->` over `--` at the same index.
+const RELATIONSHIP_OPERATOR_LIST: RelationshipOperator[] = [
+  { token: "<|--", kind: "inheritance", headAt: "from", dashed: false },
+  { token: "--|>", kind: "inheritance", headAt: "to", dashed: false },
+  { token: "<|..", kind: "realization", headAt: "from", dashed: true },
+  { token: "..|>", kind: "realization", headAt: "to", dashed: true },
+  { token: "*--", kind: "composition", headAt: "from", dashed: false },
+  { token: "--*", kind: "composition", headAt: "to", dashed: false },
+  { token: "o--", kind: "aggregation", headAt: "from", dashed: false },
+  { token: "--o", kind: "aggregation", headAt: "to", dashed: false },
+  { token: "-->", kind: "association", headAt: "to", dashed: false },
+  { token: "<--", kind: "association", headAt: "from", dashed: false },
+  { token: "..>", kind: "dependency", headAt: "to", dashed: true },
+  { token: "<..", kind: "dependency", headAt: "from", dashed: true },
+  { token: "--", kind: "link", headAt: "none", dashed: false },
+  { token: "..", kind: "link", headAt: "none", dashed: true },
+]
+const RELATIONSHIP_OPERATORS: RelationshipOperator[] = [...RELATIONSHIP_OPERATOR_LIST].sort(
+  (left, right) => right.token.length - left.token.length,
+)
+
+export function isMermaidClassDiagram(content: string): boolean {
+  return HEADER_RE.test(firstMeaningfulMermaidLine(content) ?? "")
+}
+
+export function parseMermaidClassDiagram(content: string): ClassDiagram {
+  const firstLine = firstMeaningfulMermaidLine(content)
+  if (!HEADER_RE.test(firstLine ?? "")) throw syntaxError(1, firstLine ?? "", "Class diagram header is required")
+
+  const classes: ClassDefinition[] = []
+  const byId = new Map<string, ClassDefinition>()
+  const relationships: ClassRelationship[] = []
+  let direction: ClassDiagramDirection = "TB"
+  let current: ClassDefinition | undefined
+  let inAccessibilityDescription = false
+  let lastLineNumber = 1
+  let lastLineText = firstLine ?? ""
+
+  const ensureClass = (id: string): ClassDefinition => {
+    let definition = byId.get(id)
+    if (!definition) {
+      definition = { id, members: [] }
+      byId.set(id, definition)
+      classes.push(definition)
+    }
+    return definition
+  }
+
+  for (const source of meaningfulNumberedMermaidLines(content)) {
+    lastLineNumber = source.lineNumber
+    const line = stripComment(source.text)
+    lastLineText = line
+    if (inAccessibilityDescription) {
+      if (line === "}") inAccessibilityDescription = false
+      continue
+    }
+    if (/^accDescr\s*\{$/i.test(line)) {
+      inAccessibilityDescription = true
+      continue
+    }
+    if (!line || ACCESSIBILITY_RE.test(line)) continue
+
+    if (current) {
+      if (line === "}") {
+        current = undefined
+        continue
+      }
+      const stereotype = line.match(STEREOTYPE_ONLY_RE)
+      if (stereotype) {
+        setStereotype(current, stereotype[1]!, source.lineNumber, line)
+        continue
+      }
+      current.members.push(parseMember(line))
+      continue
+    }
+
+    const header = line.match(HEADER_RE)
+    if (header) {
+      direction = (header[1]?.toUpperCase() as ClassDiagramDirection | undefined) ?? direction
+      continue
+    }
+
+    const directionMatch = line.match(DIRECTION_RE)
+    if (directionMatch) {
+      direction = directionMatch[1]!.toUpperCase() as ClassDiagramDirection
+      continue
+    }
+
+    const noteMatch = line.match(CLASS_NOTE_RE)
+    if (noteMatch) {
+      const id = normalizeClassName(noteMatch[1]!)
+      if (!id) throw syntaxError(source.lineNumber, line, "Class note target is not a valid class name")
+      const definition = ensureClass(id)
+      definition.notes ??= []
+      definition.notes.push(stripMermaidQuotes(noteMatch[2]! + noteMatch[3]! + noteMatch[2]!))
+      continue
+    }
+
+    const annotation = line.match(ANNOTATION_RE)
+    if (annotation) {
+      const id = normalizeClassName(annotation[2]!)
+      if (!id) throw syntaxError(source.lineNumber, line, "Class annotation target is not a valid class name")
+      setStereotype(ensureClass(id), annotation[1]!, source.lineNumber, line)
+      continue
+    }
+
+    const classMatch = line.match(/^class\s+(.+)$/i)
+    if (classMatch) {
+      let raw = classMatch[1]!.trim()
+      let openBody = false
+      if (raw.endsWith("{")) {
+        openBody = true
+        raw = raw.slice(0, -1).trim()
+      }
+      const labelMatch = raw.match(CLASS_LABEL_RE)
+      const id = normalizeClassName(labelMatch?.[1] ?? raw)
+      if (!id) throw syntaxError(source.lineNumber, line, "Class name is not valid")
+      const definition = ensureClass(id)
+      if (labelMatch) definition.label = stripMermaidQuotes(labelMatch[2]! + labelMatch[3]! + labelMatch[2]!)
+      if (openBody) current = definition
+      continue
+    }
+
+    const found = findOperator(line)
+    if (found) {
+      relationships.push(parseRelationship(line, found.operator, found.index, source.lineNumber, ensureClass))
+      continue
+    }
+
+    const colon = line.indexOf(":")
+    if (colon > 0) {
+      const id = normalizeClassName(line.slice(0, colon))
+      if (id) {
+        const right = line.slice(colon + 1).trim()
+        const stereotype = right.match(STEREOTYPE_ONLY_RE)
+        if (stereotype) setStereotype(ensureClass(id), stereotype[1]!, source.lineNumber, line)
+        else if (right) ensureClass(id).members.push(parseMember(right))
+        continue
+      }
+    }
+
+    throw syntaxError(source.lineNumber, line, unsupportedReason(line))
+  }
+
+  if (current) throw syntaxError(lastLineNumber, lastLineText, "Unclosed class body")
+  return { direction, classes, relationships }
+}
+
+function parseMember(text: string): ClassMember {
+  const value = text.trim()
+  return { text: value, method: value.includes("(") && value.includes(")") }
+}
+
+function setStereotype(definition: ClassDefinition, stereotype: string, lineNumber: number, line: string): void {
+  const value = stereotype.trim()
+  if (!value) throw syntaxError(lineNumber, line, "Class stereotype cannot be empty")
+  definition.stereotype = value
+}
+
+function findOperator(line: string): { operator: RelationshipOperator; index: number } | undefined {
+  let quote: '"' | "'" | undefined
+  for (let index = 0; index < line.length; index++) {
+    const char = line[index]
+    if (char === '"' || char === "'") {
+      if (quote === undefined) quote = char
+      else if (quote === char) quote = undefined
+      continue
+    }
+    // Cardinalities and quoted class names can contain operator-looking text such
+    // as `"0..*"`, so never treat operator tokens inside quotes as the separator.
+    if (quote !== undefined) continue
+    for (const operator of RELATIONSHIP_OPERATORS) {
+      if (line.startsWith(operator.token, index)) return { operator, index }
+    }
+  }
+  return undefined
+}
+
+function parseRelationship(
+  line: string,
+  operator: RelationshipOperator,
+  index: number,
+  lineNumber: number,
+  ensureClass: (id: string) => ClassDefinition,
+): ClassRelationship {
+  const leftRaw = line.slice(0, index).trim()
+  const rightRaw = line.slice(index + operator.token.length).trim()
+
+  let targetPart = rightRaw
+  let label: string | undefined
+  const colon = rightRaw.indexOf(":")
+  if (colon >= 0) {
+    targetPart = rightRaw.slice(0, colon).trim()
+    label = stripMermaidQuotes(rightRaw.slice(colon + 1).trim()) || undefined
+  }
+
+  const from = splitSourceCardinality(leftRaw)
+  const to = splitTargetCardinality(targetPart)
+  if (!from.name) throw syntaxError(lineNumber, line, "Relationship source is missing")
+  if (!to.name) throw syntaxError(lineNumber, line, "Relationship target is missing")
+  const fromId = normalizeClassName(from.name)
+  const toId = normalizeClassName(to.name)
+  if (!fromId) throw syntaxError(lineNumber, line, "Relationship source is not a valid class name")
+  if (!toId) throw syntaxError(lineNumber, line, "Relationship target is not a valid class name")
+  ensureClass(fromId)
+  ensureClass(toId)
+
+  return {
+    from: fromId,
+    to: toId,
+    kind: operator.kind,
+    headAt: operator.headAt,
+    dashed: operator.dashed,
+    ...(label === undefined ? {} : { label }),
+    ...(from.cardinality === undefined ? {} : { fromCardinality: from.cardinality }),
+    ...(to.cardinality === undefined ? {} : { toCardinality: to.cardinality }),
+  }
+}
+
+function splitSourceCardinality(value: string): { name: string; cardinality?: string } {
+  const match = value.match(/^(.*?)\s*(?:"([^"]*)"|'([^']*)')$/)
+  if (match?.[1]?.trim()) return { name: match[1].trim(), cardinality: match[2] ?? match[3] }
+  return { name: value }
+}
+
+function splitTargetCardinality(value: string): { name: string; cardinality?: string } {
+  const match = value.match(/^(?:"([^"]*)"|'([^']*)')\s+(.+)$/)
+  if (match) return { name: match[3]!.trim(), cardinality: match[1] ?? match[2] }
+  return { name: value }
+}
+
+function normalizeClassName(raw: string): string | undefined {
+  const trimmed = raw.trim()
+  if (!trimmed) return undefined
+  const quoted =
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  if (quoted) {
+    const value = trimmed.slice(1, -1).trim()
+    return value || undefined
+  }
+  return CLASS_NAME_RE.test(trimmed) ? trimmed : undefined
+}
+
+function stripComment(value: string): string {
+  let quote: '"' | "'" | undefined
+  for (let index = 0; index < value.length - 1; index += 1) {
+    const char = value[index]
+    if ((char === '"' || char === "'") && (quote === undefined || quote === char)) {
+      quote = quote === char ? undefined : char
+      continue
+    }
+    if (quote === undefined && char === "%" && value[index + 1] === "%") return value.slice(0, index).trim()
+  }
+  return value.trim()
+}
+
+function unsupportedReason(line: string): string {
+  const keyword = line.split(/[\s:{]/, 1)[0]?.toLowerCase() ?? ""
+  switch (keyword) {
+    case "note":
+      return "Standalone class diagram notes are not supported"
+    case "namespace":
+      return "Class diagram namespaces are not supported"
+    case "package":
+      return "Class diagram packages are not supported"
+    case "click":
+    case "link":
+    case "callback":
+      return "Class diagram hyperlinks are not supported"
+    case "style":
+    case "classdef":
+    case "cssclass":
+      return "Class diagram styling is not supported"
+    default:
+      return "Unsupported class diagram syntax"
+  }
+}
+
+function syntaxError(lineNumber: number, sourceLine: string, reason?: string): MermaidSyntaxError {
+  return new MermaidSyntaxError("classDiagram", lineNumber, sourceLine, reason)
+}

package/src/merman/class/render-grid.ts

@@ -0,0 +1,18 @@
+import type { StyledText } from "@opentui/core"
+import type { DiagramCanvas } from "../core/canvas.js"
+import { renderDiagramGridStyledText } from "../core/render-grid.js"
+import type { ClassStyleColors } from "./style.js"
+import type { ClassCellStyle } from "./types.js"
+
+export type ClassGrid = DiagramCanvas<ClassCellStyle>
+
+export function renderClassGridText(grid: ClassGrid): string {
+  return grid.toString({ trimTop: true, trimBottom: true })
+}
+
+export function renderClassGridStyledText(grid: ClassGrid, colors: ClassStyleColors): StyledText {
+  return renderDiagramGridStyledText(grid, (run) => (run.style ? colors[run.style] : undefined), undefined, {
+    trimTop: true,
+    trimBottom: true,
+  })
+}

package/src/merman/class/style.ts

@@ -0,0 +1,27 @@
+import { RGBA } from "@opentui/core"
+import { rgba, type DiagramRgb } from "../core/color/style.js"
+import type { ClassCellStyle } from "./types.js"
+
+const DEFAULT_THEME_RGB = {
+  border: [141, 169, 155],
+  title: [228, 239, 232],
+  stereotype: [154, 184, 169],
+  member: [215, 229, 221],
+  edge: [134, 225, 200],
+  label: [134, 225, 200],
+} as const satisfies Record<ClassCellStyle, DiagramRgb>
+
+export type ClassStyleColors = Required<Record<ClassCellStyle, RGBA>>
+
+export function resolveClassStyleColors(
+  colors: Partial<Record<ClassCellStyle, RGBA | undefined>> = {},
+): ClassStyleColors {
+  return {
+    border: colors.border ?? rgba(DEFAULT_THEME_RGB.border),
+    title: colors.title ?? rgba(DEFAULT_THEME_RGB.title),
+    stereotype: colors.stereotype ?? colors.title ?? rgba(DEFAULT_THEME_RGB.stereotype),
+    member: colors.member ?? rgba(DEFAULT_THEME_RGB.member),
+    edge: colors.edge ?? rgba(DEFAULT_THEME_RGB.edge),
+    label: colors.label ?? colors.edge ?? rgba(DEFAULT_THEME_RGB.label),
+  }
+}

package/src/merman/class/types.ts

@@ -0,0 +1,57 @@
+export type ClassDiagramDirection = "TB" | "BT" | "LR" | "RL"
+export type ClassLayoutEngine = "builtin" | "dagre"
+
+export type ClassRelationshipKind =
+  | "inheritance"
+  | "composition"
+  | "aggregation"
+  | "association"
+  | "dependency"
+  | "realization"
+  | "link"
+
+export interface ClassMember {
+  /** Display text exactly as written, e.g. `+String name` or `+getAge()`. */
+  text: string
+  /** Members written with a call shape are methods. */
+  method: boolean
+}
+
+export interface ClassDefinition {
+  id: string
+  /** Display label from `class Id["Readable label"]`. */
+  label?: string
+  /** Annotation written between `<<` and `>>`, e.g. `interface`. */
+  stereotype?: string
+  /** Notes attached with `note for Id "..."`. */
+  notes?: string[]
+  members: ClassMember[]
+}
+
+export interface ClassRelationship {
+  from: string
+  to: string
+  kind: ClassRelationshipKind
+  /** Which endpoint carries the triangle/diamond/arrowhead marker. */
+  headAt: "from" | "to" | "none"
+  /** Dependency and realization edges draw as dashed lines. */
+  dashed: boolean
+  label?: string
+  fromCardinality?: string
+  toCardinality?: string
+}
+
+export interface ClassDiagram {
+  direction: ClassDiagramDirection
+  classes: ClassDefinition[]
+  relationships: ClassRelationship[]
+}
+
+export interface ClassDiagramRenderOptions {
+  /** Fold horizontally over this many columns. Defaults to 120. */
+  layoutMaxWidth?: number
+  /** Choose the built-in terminal layout or Dagre's layered layout. */
+  classLayout?: ClassLayoutEngine
+}
+
+export type ClassCellStyle = "border" | "title" | "stereotype" | "member" | "edge" | "label"

package/src/merman/core/canvas.ts

@@ -0,0 +1,228 @@
+import stringWidth from "string-width"
+import { diagramTextGraphemes } from "./text.js"
+
+export type DiagramCanvasCell<Style extends string, Metadata extends object = object> = {
+  char: string
+  style?: Style
+} & Partial<Metadata>
+
+export interface DiagramCanvasRun<Style extends string, Metadata extends object = object> {
+  text: string
+  style: Style | undefined
+  cell: DiagramCanvasCell<Style, Metadata>
+}
+
+export interface DiagramCanvasOptions<Style extends string, Metadata extends object = object> {
+  measure?: (text: string) => number
+  mergeCell?: (
+    existing: DiagramCanvasCell<Style, Metadata>,
+    incoming: DiagramCanvasCell<Style, Metadata>,
+  ) => DiagramCanvasCell<Style, Metadata>
+}
+
+export interface DiagramCanvasTextOptions {
+  trimTop?: boolean
+  trimBottom?: boolean
+}
+
+export interface DiagramCanvasTextSize {
+  width: number
+  height: number
+}
+
+export type DiagramCanvasTextMetadata<Metadata extends object> =
+  | Partial<Metadata>
+  | ((x: number, y: number) => Partial<Metadata>)
+
+export interface DiagramCanvasRunOptions<Style extends string, Metadata extends object = object> {
+  key?: (cell: DiagramCanvasCell<Style, Metadata>) => readonly unknown[]
+  trimTop?: boolean
+  trimBottom?: boolean
+}
+
+const MAX_DIAGRAM_CELLS = 250_000
+
+export class DiagramCanvasSizeError extends Error {
+  constructor(
+    readonly width: number,
+    readonly height: number,
+  ) {
+    const invalid = !Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 0 || height < 0
+    super(
+      invalid
+        ? `Diagram canvas dimensions must be non-negative safe integers, received ${width}x${height}`
+        : `Diagram canvas ${width}x${height} exceeds the ${MAX_DIAGRAM_CELLS.toLocaleString()} cell limit`,
+    )
+    this.name = "DiagramCanvasSizeError"
+  }
+}
+
+function createEmptyCell<Style extends string, Metadata extends object>(): DiagramCanvasCell<Style, Metadata> {
+  return { char: " " } as DiagramCanvasCell<Style, Metadata>
+}
+
+function sameKey(left: readonly unknown[] | undefined, right: readonly unknown[]): boolean {
+  return Boolean(left && left.length === right.length && left.every((value, index) => Object.is(value, right[index])))
+}
+
+export class DiagramCanvas<Style extends string, Metadata extends object = object> {
+  private readonly cells: Array<Array<DiagramCanvasCell<Style, Metadata>>>
+  private readonly measure: (text: string) => number
+  private readonly mergeCell?: DiagramCanvasOptions<Style, Metadata>["mergeCell"]
+  private readonly rowEnds: Uint32Array
+
+  constructor(
+    readonly width: number,
+    readonly height: number,
+    options: DiagramCanvasOptions<Style, Metadata> = {},
+  ) {
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 0 || height < 0) {
+      throw new DiagramCanvasSizeError(width, height)
+    }
+    if (width * height > MAX_DIAGRAM_CELLS) throw new DiagramCanvasSizeError(width, height)
+    this.measure = options.measure ?? stringWidth
+    this.mergeCell = options.mergeCell
+    this.cells = Array.from({ length: height }, () => Array.from({ length: width }, () => createEmptyCell()))
+    this.rowEnds = new Uint32Array(height)
+  }
+
+  get rows(): ReadonlyArray<ReadonlyArray<Readonly<DiagramCanvasCell<Style, Metadata>>>> {
+    return this.cells
+  }
+
+  private rowText(row: Array<DiagramCanvasCell<Style, Metadata>>, rowEnd: number): string {
+    return row
+      .slice(0, rowEnd)
+      .map((cell) => cell.char)
+      .join("")
+  }
+
+  private textRowRange(trimTop: boolean, trimBottom: boolean): { start: number; end: number } {
+    let start = 0
+    let end = this.cells.length
+    if (trimTop) while (start < end && this.rowEnds[start] === 0) start += 1
+    if (trimBottom) while (end > start && this.rowEnds[end - 1] === 0) end -= 1
+    return { start, end }
+  }
+
+  setCell(x: number, y: number, char: string, style?: Style, metadata?: Partial<Metadata>): void {
+    this.writeCell(x, y, char, style, metadata, true)
+  }
+
+  replaceCell(x: number, y: number, char: string, style?: Style, metadata?: Partial<Metadata>): void {
+    this.writeCell(x, y, char, style, metadata, false)
+  }
+
+  private writeCell(
+    x: number,
+    y: number,
+    char: string,
+    style: Style | undefined,
+    metadata: Partial<Metadata> | undefined,
+    merge: boolean,
+  ): void {
+    if (y < 0 || y >= this.cells.length || x < 0 || x >= this.cells[y]!.length) return
+    const incoming = { char, style, ...metadata } as DiagramCanvasCell<Style, Metadata>
+    const cell = merge ? (this.mergeCell?.(this.cells[y]![x]!, incoming) ?? incoming) : incoming
+    this.cells[y]![x] = cell
+    if (cell.char !== " ") {
+      this.rowEnds[y] = Math.max(this.rowEnds[y]!, x + 1)
+    } else if (this.rowEnds[y] === x + 1) {
+      let end = x
+      while (end > 0 && this.cells[y]![end - 1]?.char === " ") end -= 1
+      this.rowEnds[y] = end
+    }
+  }
+
+  getCell(x: number, y: number): Readonly<DiagramCanvasCell<Style, Metadata>> | undefined {
+    return this.cells[y]?.[x]
+  }
+
+  setText(x: number, y: number, text: string, style?: Style, metadata?: DiagramCanvasTextMetadata<Metadata>): void {
+    const metadataAt = (cellX: number) => (typeof metadata === "function" ? metadata(cellX, y) : metadata)
+    if (this.measure === stringWidth && /^[\x20-\x7e]*$/.test(text)) {
+      for (let index = 0; index < text.length; index++) {
+        this.setCell(x + index, y, text[index]!, style, metadataAt(x + index))
+      }
+      return
+    }
+
+    let offset = 0
+    for (const grapheme of diagramTextGraphemes(text)) {
+      const width = Math.max(1, this.measure(grapheme))
+      if (x + offset < 0 || x + offset + width > this.width) {
+        offset += width
+        continue
+      }
+      this.setCell(x + offset, y, grapheme, style, metadataAt(x + offset))
+      for (let continuation = 1; continuation < width; continuation++) {
+        this.setCell(x + offset + continuation, y, "", style, metadataAt(x + offset + continuation))
+      }
+      offset += width
+    }
+  }
+
+  toString(options: DiagramCanvasTextOptions = {}): string {
+    const lines: string[] = []
+    const rows = this.textRowRange(options.trimTop ?? false, options.trimBottom ?? false)
+    for (let rowIndex = rows.start; rowIndex < rows.end; rowIndex++) {
+      lines.push(this.rowText(this.cells[rowIndex]!, this.rowEnds[rowIndex]!))
+    }
+    return lines.join("\n")
+  }
+
+  getTextSize(options: DiagramCanvasTextOptions = {}): DiagramCanvasTextSize {
+    const rows = this.textRowRange(options.trimTop ?? false, options.trimBottom ?? false)
+    let width = 0
+    for (let rowIndex = rows.start; rowIndex < rows.end; rowIndex++) {
+      const row = this.cells[rowIndex]!
+      const rowEnd = this.rowEnds[rowIndex]!
+      if (rowEnd > 0) width = Math.max(width, this.measure(this.rowText(row, rowEnd)))
+    }
+    return { width, height: rows.end - rows.start }
+  }
+
+  getTextHeight(options: DiagramCanvasTextOptions = {}): number {
+    const rows = this.textRowRange(options.trimTop ?? false, options.trimBottom ?? false)
+    return rows.end - rows.start
+  }
+
+  forEachRun(
+    onRun: (run: DiagramCanvasRun<Style, Metadata>) => void,
+    onLineEnd: () => void,
+    options: DiagramCanvasRunOptions<Style, Metadata> = {},
+  ): void {
+    const key = options.key
+    const rows = this.textRowRange(options.trimTop ?? false, options.trimBottom ?? false)
+
+    for (let rowIndex = rows.start; rowIndex < rows.end; rowIndex++) {
+      const row = this.cells[rowIndex]!
+      let rowEnd = this.rowEnds[rowIndex]!
+      while (rowEnd < row.length && row[rowEnd]?.style !== undefined) rowEnd += 1
+
+      let currentCell: DiagramCanvasCell<Style, Metadata> | undefined
+      let currentKey: readonly unknown[] | undefined
+      let currentText = ""
+      const flush = () => {
+        if (!currentText || !currentCell) return
+        onRun({ text: currentText, style: currentCell.style, cell: currentCell })
+        currentText = ""
+      }
+
+      for (let x = 0; x < rowEnd; x++) {
+        const cell = row[x]!
+        const nextKey = key?.(cell)
+        const sameRun = currentCell && (key ? sameKey(currentKey, nextKey!) : currentCell.style === cell.style)
+        if (!sameRun) {
+          flush()
+          currentCell = cell
+          currentKey = nextKey
+        }
+        currentText += cell.char
+      }
+
+      flush()
+      if (rowIndex < rows.end - 1) onLineEnd()
+    }
+  }
+}

package/src/merman/core/color/style.ts

@@ -0,0 +1,56 @@
+import { RGBA } from "@opentui/core"
+
+export type DiagramRgb = readonly [number, number, number]
+export type DiagramFadeStep = 1 | 2 | 3 | 4 | 5
+
+export const DIAGRAM_FADE_STEPS = [1, 2, 3, 4, 5] as const satisfies readonly DiagramFadeStep[]
+
+export function numberedStyleKeys<Prefix extends string, Step extends number>(
+  prefix: Prefix,
+  steps: readonly Step[],
+): Array<`${Prefix}${Step}`> {
+  return steps.map((step) => `${prefix}${step}` as `${Prefix}${Step}`)
+}
+
+export function rgba(rgb: DiagramRgb): RGBA {
+  return RGBA.fromInts(rgb[0], rgb[1], rgb[2], 255)
+}
+
+export function blendColor(from: RGBA, to: RGBA, amount: number): RGBA
+export function blendColor(from: RGBA | undefined, to: RGBA | undefined, amount: number): RGBA | undefined
+export function blendColor(from: RGBA | undefined, to: RGBA | undefined, amount: number): RGBA | undefined {
+  if (!from && !to) return undefined
+  if (!from) return to
+  if (!to) return from
+
+  const [fromR, fromG, fromB, fromA] = from.toInts()
+  const [toR, toG, toB, toA] = to.toInts()
+  const mix = (left: number, right: number) => left + (right - left) * amount
+
+  return RGBA.fromInts(mix(fromR, toR), mix(fromG, toG), mix(fromB, toB), mix(fromA, toA))
+}
+
+export function colorsEqual(left?: RGBA, right?: RGBA): boolean {
+  if (!left || !right) return left === right
+  return left.equals(right)
+}
+
+export function createColorRampTheme<Style extends string>(
+  styles: readonly Style[],
+  from: RGBA,
+  to: RGBA,
+): Record<Style, RGBA>
+export function createColorRampTheme<Style extends string>(
+  styles: readonly Style[],
+  from: RGBA | undefined,
+  to: RGBA | undefined,
+): Record<Style, RGBA | undefined>
+export function createColorRampTheme<Style extends string>(
+  styles: readonly Style[],
+  from: RGBA | undefined,
+  to: RGBA | undefined,
+): Record<Style, RGBA | undefined> {
+  return Object.fromEntries(
+    styles.map((style, index) => [style, blendColor(from, to, (index + 1) / (styles.length + 1))]),
+  ) as Record<Style, RGBA | undefined>
+}