opentui-markdown-render 0.0.0-stage → 0.2.0

package/src/merman/state/search.ts

@@ -0,0 +1,103 @@
+import type { DiagramPoint } from "../core/geometry.js"
+import type { SpatialIndex, SpatialRole } from "../core/spatial.js"
+
+const MAX_RENDER_SEARCH_VISITS = 250_000
+
+export interface StateSearchBudget {
+  remaining: number
+}
+
+export interface StateSearchSpace {
+  blocked: ReadonlySet<string>
+  minX: number
+  minY: number
+  maxX: number
+  maxY: number
+}
+
+export function createStateSearchBudget(): StateSearchBudget {
+  return { remaining: MAX_RENDER_SEARCH_VISITS }
+}
+
+export function createStateSearchSpace(
+  space: SpatialIndex,
+  clearance: (role: SpatialRole) => number = () => 0,
+): StateSearchSpace {
+  const blocked = new Set<string>()
+  let minX = 0
+  let minY = 0
+  let maxX = 0
+  let maxY = 0
+
+  for (const claim of space.claims) {
+    const padding = clearance(claim.role)
+    for (const span of claim.spans) {
+      for (let y = span.y - padding; y <= span.y + padding; y++) {
+        for (let x = span.fromX - padding; x <= span.toX + padding; x++) {
+          blocked.add(`${x}:${y}`)
+          minX = Math.min(minX, x)
+          minY = Math.min(minY, y)
+          maxX = Math.max(maxX, x)
+          maxY = Math.max(maxY, y)
+        }
+      }
+    }
+  }
+
+  return { blocked, minX, minY, maxX, maxY }
+}
+
+export function findStateManhattanPath(
+  starts: readonly DiagramPoint[],
+  goal: DiagramPoint,
+  space: Pick<StateSearchSpace, "blocked">,
+  bounds: Pick<StateSearchSpace, "minX" | "minY" | "maxX" | "maxY">,
+  budget: StateSearchBudget,
+  isFree: (point: DiagramPoint) => boolean = (point) => !space.blocked.has(pointKey(point)),
+): DiagramPoint[] | undefined {
+  const queue = [...new Map(starts.filter(isFree).map((point) => [pointKey(point), point])).values()]
+  const parents = new Map(queue.map((point) => [pointKey(point), undefined as string | undefined]))
+  const points = new Map(queue.map((point) => [pointKey(point), point]))
+
+  for (let cursor = 0; cursor < queue.length && budget.remaining > 0; cursor++, budget.remaining--) {
+    const current = queue[cursor]!
+    if (current.x === goal.x && current.y === goal.y) break
+    const dx = Math.sign(goal.x - current.x)
+    const dy = Math.sign(goal.y - current.y)
+    const candidates = [
+      ...(dx === 0 ? [] : [{ x: current.x + dx, y: current.y }]),
+      ...(dy === 0 ? [] : [{ x: current.x, y: current.y + dy }]),
+      { x: current.x + 1, y: current.y },
+      { x: current.x, y: current.y + 1 },
+      { x: current.x - 1, y: current.y },
+      { x: current.x, y: current.y - 1 },
+    ]
+    for (const candidate of candidates) {
+      if (
+        candidate.x < bounds.minX ||
+        candidate.x > bounds.maxX ||
+        candidate.y < bounds.minY ||
+        candidate.y > bounds.maxY
+      )
+        continue
+      const key = pointKey(candidate)
+      if (parents.has(key) || !isFree(candidate)) continue
+      parents.set(key, pointKey(current))
+      points.set(key, candidate)
+      queue.push(candidate)
+    }
+  }
+
+  if (!parents.has(pointKey(goal))) return undefined
+  const path: DiagramPoint[] = []
+  let cursor: string | undefined = pointKey(goal)
+  while (cursor) {
+    path.push(points.get(cursor)!)
+    cursor = parents.get(cursor)
+  }
+  return path.reverse()
+}
+
+function pointKey(point: DiagramPoint): string {
+  return `${point.x}:${point.y}`
+}

package/src/merman/state/style.ts

@@ -0,0 +1,52 @@
+import { RGBA } from "@opentui/core"
+import { createColorRampTheme, numberedStyleKeys, rgba, type DiagramRgb } from "../core/color/style.js"
+import type { BaseStateCellStyle, NoteConnectorRampStyle, StateCellStyle, StateDepartureRampStyle } from "./types.js"
+
+const DEFAULT_THEME_RGB = {
+  state: [228, 239, 232],
+  stateBorder: [228, 239, 232],
+  composite: [111, 138, 126],
+  compositeLabel: [111, 138, 126],
+  transition: [134, 225, 200],
+  label: [134, 225, 200],
+  noteBorder: [141, 169, 155],
+  noteText: [215, 229, 221],
+  noteConnector: [141, 169, 155],
+  start: [134, 225, 200],
+  end: [230, 177, 126],
+  choice: [134, 225, 200],
+} as const satisfies Record<BaseStateCellStyle, DiagramRgb>
+const STATE_RAMP_STEPS = [1, 2, 3] as const
+export const NOTE_CONNECTOR_RAMP_STYLES = numberedStyleKeys(
+  "noteConnectorRamp",
+  STATE_RAMP_STEPS,
+) satisfies readonly NoteConnectorRampStyle[]
+export const STATE_DEPARTURE_RAMP_STYLES = numberedStyleKeys(
+  "stateDepartureRamp",
+  STATE_RAMP_STEPS,
+) satisfies readonly StateDepartureRampStyle[]
+export type StateStyleColors = Required<Record<StateCellStyle, RGBA>>
+
+export function resolveStateStyleColors(
+  colors: Partial<Record<BaseStateCellStyle, RGBA | undefined>> = {},
+): StateStyleColors {
+  const resolved = {
+    state: colors.state ?? rgba(DEFAULT_THEME_RGB.state),
+    stateBorder: colors.stateBorder ?? colors.state ?? rgba(DEFAULT_THEME_RGB.stateBorder),
+    composite: colors.composite ?? rgba(DEFAULT_THEME_RGB.composite),
+    compositeLabel: colors.compositeLabel ?? colors.composite ?? rgba(DEFAULT_THEME_RGB.compositeLabel),
+    transition: colors.transition ?? rgba(DEFAULT_THEME_RGB.transition),
+    label: colors.label ?? rgba(DEFAULT_THEME_RGB.label),
+    noteBorder: colors.noteBorder ?? rgba(DEFAULT_THEME_RGB.noteBorder),
+    noteText: colors.noteText ?? rgba(DEFAULT_THEME_RGB.noteText),
+    noteConnector: colors.noteConnector ?? rgba(DEFAULT_THEME_RGB.noteConnector),
+    start: colors.start ?? rgba(DEFAULT_THEME_RGB.start),
+    end: colors.end ?? rgba(DEFAULT_THEME_RGB.end),
+    choice: colors.choice ?? rgba(DEFAULT_THEME_RGB.choice),
+  }
+  return {
+    ...resolved,
+    ...createColorRampTheme(NOTE_CONNECTOR_RAMP_STYLES, resolved.noteConnector, resolved.noteBorder),
+    ...createColorRampTheme(STATE_DEPARTURE_RAMP_STYLES, resolved.stateBorder, resolved.transition),
+  }
+}

package/src/merman/state/types.ts

@@ -0,0 +1,63 @@
+import type { BorderStyle } from "@opentui/core"
+
+export type StateDiagramDirection = "TB" | "TD" | "BT" | "LR" | "RL"
+export type StateDiagramArrowHeadStyle = "filled" | "line"
+
+export interface StateDiagramState {
+  id: string
+  label: string
+  kind: "state" | "start" | "end" | "choice" | "fork" | "join"
+  parentId?: string
+}
+
+export interface StateDiagramTransition {
+  from: string
+  to: string
+  label: string
+}
+
+export interface StateDiagramCompositeState {
+  id: string
+  label: string
+  parentId?: string
+}
+
+export interface StateDiagramNote {
+  target: string
+  position: "left" | "right"
+  lines: string[]
+}
+
+export interface StateDiagram {
+  direction: StateDiagramDirection
+  states: StateDiagramState[]
+  transitions: StateDiagramTransition[]
+  composites: StateDiagramCompositeState[]
+  notes: StateDiagramNote[]
+}
+
+export interface StateDiagramRenderOptions {
+  direction?: StateDiagramDirection
+  borderStyle?: BorderStyle
+  arrowHeadStyle?: StateDiagramArrowHeadStyle
+  minStateGap?: number
+  /** Target rendered width. Oversized horizontal layouts fold vertically. */
+  layoutMaxWidth?: number
+}
+
+export type NoteConnectorRampStyle = `noteConnectorRamp${1 | 2 | 3}`
+export type StateDepartureRampStyle = `stateDepartureRamp${1 | 2 | 3}`
+export type BaseStateCellStyle =
+  | "state"
+  | "stateBorder"
+  | "composite"
+  | "compositeLabel"
+  | "transition"
+  | "label"
+  | "noteBorder"
+  | "noteText"
+  | "noteConnector"
+  | "start"
+  | "end"
+  | "choice"
+export type StateCellStyle = BaseStateCellStyle | NoteConnectorRampStyle | StateDepartureRampStyle

package/src/merman/state/visible-model.ts

@@ -0,0 +1,77 @@
+import type { StateDiagram, StateDiagramState, StateDiagramTransition } from "./types.js"
+
+export type StateVisibleTransition = StateDiagramTransition
+
+export interface StateVisibleDiagram extends Omit<StateDiagram, "transitions"> {
+  transitions: StateVisibleTransition[]
+}
+
+export function isHiddenCompositeMarker(state: StateDiagramState | undefined): boolean {
+  return Boolean(state?.parentId && (state.kind === "start" || state.kind === "end"))
+}
+
+function composeTransitionLabel(incoming: StateDiagramTransition, outgoing: StateDiagramTransition): string {
+  return [incoming.label, outgoing.label].filter(Boolean).join("<br/>")
+}
+
+function collapseHiddenCompositeMarkerTransitionsOnce(
+  transitions: readonly StateVisibleTransition[],
+  statesById: ReadonlyMap<string, StateDiagramState>,
+): { transitions: StateVisibleTransition[]; changed: boolean } {
+  const hiddenMarkers = new Set(
+    [...statesById.values()].filter((state) => isHiddenCompositeMarker(state)).map((state) => state.id),
+  )
+  if (hiddenMarkers.size === 0) return { transitions: [...transitions], changed: false }
+
+  for (const markerId of hiddenMarkers) {
+    const incoming = transitions.filter((transition) => transition.to === markerId && transition.from !== markerId)
+    const outgoing = transitions.filter((transition) => transition.from === markerId && transition.to !== markerId)
+    if (incoming.length === 0 || outgoing.length === 0) continue
+
+    const skipped = new Set([...incoming, ...outgoing])
+    return {
+      transitions: [
+        ...transitions.filter((transition) => !skipped.has(transition)),
+        ...incoming.flatMap((incomingTransition) =>
+          outgoing.map((outgoingTransition) => ({
+            from: incomingTransition.from,
+            to: outgoingTransition.to,
+            label: composeTransitionLabel(incomingTransition, outgoingTransition),
+          })),
+        ),
+      ],
+      changed: true,
+    }
+  }
+
+  return { transitions: [...transitions], changed: false }
+}
+
+function collapseHiddenCompositeMarkerTransitions(diagram: StateDiagram): StateVisibleTransition[] {
+  const statesById = new Map(diagram.states.map((state) => [state.id, state]))
+  let transitions: StateVisibleTransition[] = diagram.transitions.map((transition) => ({ ...transition }))
+
+  while (true) {
+    const result = collapseHiddenCompositeMarkerTransitionsOnce(transitions, statesById)
+    transitions = result.transitions
+    if (!result.changed) return transitions
+  }
+}
+
+export function prepareVisibleStateDiagram(diagram: StateDiagram): StateVisibleDiagram {
+  const transitions = collapseHiddenCompositeMarkerTransitions(diagram)
+  const referencedHiddenMarkers = new Set<string>()
+  const statesById = new Map(diagram.states.map((state) => [state.id, state]))
+  for (const transition of transitions) {
+    const from = statesById.get(transition.from)
+    const to = statesById.get(transition.to)
+    if (from && isHiddenCompositeMarker(from)) referencedHiddenMarkers.add(from.id)
+    if (to && isHiddenCompositeMarker(to)) referencedHiddenMarkers.add(to.id)
+  }
+
+  return {
+    ...diagram,
+    states: diagram.states.filter((state) => !isHiddenCompositeMarker(state) || referencedHiddenMarkers.has(state.id)),
+    transitions,
+  }
+}

package/src/merman/timeline/diagram.ts

@@ -0,0 +1,8 @@
+import { drawTimelineDiagramGrid } from "./drawing.js"
+import { parseMermaidTimelineDiagram } from "./parser.js"
+import { renderTimelineGridText } from "./render-grid.js"
+import type { TimelineDiagramRenderOptions } from "./types.js"
+
+export function renderTimelineDiagram(content: string, options: TimelineDiagramRenderOptions = {}): string {
+  return renderTimelineGridText(drawTimelineDiagramGrid(parseMermaidTimelineDiagram(content), options))
+}

package/src/merman/timeline/drawing.ts

@@ -0,0 +1,109 @@
+import { DiagramCanvas } from "../core/canvas.js"
+import { splitDiagramLines } from "../core/text-lines.js"
+import { diagramTextWidth } from "../core/text.js"
+import type { TimelineGrid } from "./render-grid.js"
+import { TIMELINE_PERIOD_FADE_STYLES, TIMELINE_SECTION_FADE_STYLES } from "./style.js"
+import type { TimelineCellStyle, TimelineDiagram, TimelineDiagramRenderOptions, TimelinePeriod } from "./types.js"
+
+interface PeriodLayout {
+  period: TimelinePeriod
+  periodLines: string[]
+  eventLines: string[][]
+  height: number
+}
+
+const JOIN_WIDTH = TIMELINE_SECTION_FADE_STYLES.length
+const SPINE_OFFSET = JOIN_WIDTH + 1
+const EVENT_OFFSET = 3
+
+export function drawTimelineDiagramGrid(
+  diagram: TimelineDiagram,
+  _options: TimelineDiagramRenderOptions = {},
+): TimelineGrid {
+  const periodLayouts = new Map<TimelinePeriod, PeriodLayout>()
+  let leftWidth = 0
+  let rightWidth = 0
+  let bodyHeight = 0
+
+  for (const entry of diagram.entries) {
+    if (entry.type === "section") {
+      const lines = splitDiagramLines(entry.section.label)
+      bodyHeight += lines.length + 1
+      for (const line of lines) leftWidth = Math.max(leftWidth, diagramTextWidth(line))
+      continue
+    }
+    const periodLines = splitDiagramLines(entry.period.period)
+    const eventLines = entry.period.events.map(splitDiagramLines)
+    const eventHeight = eventLines.reduce((height, lines) => height + lines.length, 0)
+    const height = Math.max(periodLines.length, eventHeight)
+    periodLayouts.set(entry.period, { period: entry.period, periodLines, eventLines, height })
+    for (const line of periodLines) leftWidth = Math.max(leftWidth, diagramTextWidth(line))
+    for (const lines of eventLines) {
+      for (const line of lines) rightWidth = Math.max(rightWidth, diagramTextWidth(line))
+    }
+    bodyHeight += height + 1
+  }
+
+  const titleLines = diagram.title ? splitDiagramLines(diagram.title) : []
+  const bodyWidth = diagram.entries.length === 0 ? 0 : leftWidth + SPINE_OFFSET + EVENT_OFFSET + rightWidth + 1
+  let titleWidth = 0
+  for (const line of titleLines) titleWidth = Math.max(titleWidth, diagramTextWidth(line))
+  const width = Math.max(bodyWidth, titleWidth)
+  const titleHeight = titleLines.length === 0 ? 0 : titleLines.length + (diagram.entries.length === 0 ? 0 : 1)
+  if (width === 0) return new DiagramCanvas(0, 0)
+
+  const grid: TimelineGrid = new DiagramCanvas(width, titleHeight + bodyHeight)
+  titleLines.forEach((line, index) =>
+    setText(grid, Math.floor((width - diagramTextWidth(line)) / 2), index, line, "title"),
+  )
+  if (diagram.entries.length === 0) return grid
+
+  const spineX = leftWidth + SPINE_OFFSET
+  let y = titleHeight
+  let railStarted = false
+  for (const entry of diagram.entries) {
+    if (entry.type === "section") {
+      const lines = splitDiagramLines(entry.section.label)
+      lines.forEach((line, index) => {
+        setText(grid, leftWidth - diagramTextWidth(line), y + index, line, "section")
+        if (index > 0) setCell(grid, spineX, y + index, "│", "spine")
+      })
+      drawJoin(grid, leftWidth, y, TIMELINE_SECTION_FADE_STYLES)
+      setCell(grid, spineX, y, railStarted ? "┤" : "┐", "spine")
+      setCell(grid, spineX, y + lines.length, "│", "spine")
+      railStarted = true
+      y += lines.length + 1
+      continue
+    }
+
+    const layout = periodLayouts.get(entry.period)!
+    for (let row = 0; row < layout.height + 1; row++) setCell(grid, spineX, y + row, "│", "spine")
+    railStarted = true
+    setCell(grid, spineX, y, "●", "spine")
+    layout.periodLines.forEach((line, index) => {
+      const lineWidth = diagramTextWidth(line)
+      setText(grid, leftWidth - lineWidth, y + index, line, "period")
+    })
+    drawJoin(grid, leftWidth, y, TIMELINE_PERIOD_FADE_STYLES)
+
+    let eventY = y
+    for (const lines of layout.eventLines) {
+      lines.forEach((line, index) => setText(grid, spineX + EVENT_OFFSET, eventY + index, line, "event"))
+      eventY += lines.length
+    }
+    y += layout.height + 1
+  }
+  return grid
+}
+
+function drawJoin(grid: TimelineGrid, x: number, y: number, styles: readonly TimelineCellStyle[]): void {
+  styles.forEach((style, index) => setCell(grid, x + index + 1, y, "─", style))
+}
+
+function setCell(grid: TimelineGrid, x: number, y: number, char: string, style: TimelineCellStyle): void {
+  grid.setCell(x, y, char, style)
+}
+
+function setText(grid: TimelineGrid, x: number, y: number, text: string, style: TimelineCellStyle): void {
+  grid.setText(x, y, text, style)
+}

package/src/merman/timeline/parser.ts

@@ -0,0 +1,119 @@
+import { firstMeaningfulMermaidLine, meaningfulNumberedMermaidLines, stripMermaidQuotes } from "../core/mermaid.js"
+import { MermaidSyntaxError } from "../diagnostics.js"
+import type { TimelineDiagram, TimelineDirection, TimelineEntry, TimelinePeriod, TimelineSection } from "./types.js"
+
+const HEADER_RE = /^timeline(?:\s+(TD|LR))?$/i
+const TITLE_RE = /^title(?:\s+(.+))?$/i
+const SECTION_RE = /^section(?:\s+(.+))?$/i
+const ACCESSIBILITY_RE = /^acc(?:Title|Descr)(?::|\s|$)/i
+
+export function isMermaidTimelineDiagram(content: string): boolean {
+  return HEADER_RE.test(firstMeaningfulMermaidLine(content) ?? "")
+}
+
+export function parseMermaidTimelineDiagram(content: string): TimelineDiagram {
+  const sections: TimelineSection[] = []
+  const periods: TimelinePeriod[] = []
+  const entries: TimelineEntry[] = []
+  let direction: TimelineDirection = "LR"
+  let title: string | undefined
+  let currentPeriod: TimelinePeriod | undefined
+  let inAccessibilityDescription = false
+
+  for (const source of meaningfulNumberedMermaidLines(content)) {
+    const line = stripTimelineComment(source.text)
+    if (inAccessibilityDescription) {
+      if (line === "}") inAccessibilityDescription = false
+      continue
+    }
+    if (/^accDescr\s*\{$/i.test(line)) {
+      inAccessibilityDescription = true
+      continue
+    }
+    if (!line || line.startsWith("#") || ACCESSIBILITY_RE.test(line)) continue
+    const header = line.match(HEADER_RE)
+    if (header) {
+      direction = (header[1]?.toUpperCase() as TimelineDirection | undefined) ?? "LR"
+      continue
+    }
+
+    const titleMatch = line.match(TITLE_RE)
+    if (titleMatch) {
+      if (!titleMatch[1]) throw syntaxError(source.lineNumber, line, "Timeline title cannot be empty")
+      title = stripMermaidQuotes(titleMatch[1])
+      continue
+    }
+
+    const sectionMatch = line.match(SECTION_RE)
+    if (sectionMatch) {
+      if (!sectionMatch[1]) throw syntaxError(source.lineNumber, line, "Timeline section cannot be empty")
+      const section = { label: stripMermaidQuotes(sectionMatch[1]) }
+      sections.push(section)
+      entries.push({ type: "section", section })
+      currentPeriod = undefined
+      continue
+    }
+
+    if (line.startsWith(":")) {
+      if (!currentPeriod) {
+        throw syntaxError(source.lineNumber, line, "Timeline continuation requires a preceding period")
+      }
+      currentPeriod.events.push(...parseEvents(line.slice(1), source.lineNumber, line))
+      continue
+    }
+
+    const fields = splitEventFields(line)
+    const periodLabel = stripMermaidQuotes(fields.shift()!)
+    if (!periodLabel) throw syntaxError(source.lineNumber, line, "Timeline period cannot be empty")
+    const period = {
+      period: periodLabel,
+      events: fields.length === 0 ? [] : parseEventFields(fields, source.lineNumber, line),
+    }
+    periods.push(period)
+    entries.push({ type: "period", period })
+    currentPeriod = period
+  }
+
+  return { direction, ...(title === undefined ? {} : { title }), sections, periods, entries }
+}
+
+function parseEvents(value: string, lineNumber: number, sourceLine: string): string[] {
+  return parseEventFields(splitEventFields(value), lineNumber, sourceLine)
+}
+
+function parseEventFields(fields: string[], lineNumber: number, sourceLine: string): string[] {
+  const events = fields.map(stripMermaidQuotes)
+  if (events.length === 0 || events.some((event) => event.length === 0)) {
+    throw syntaxError(lineNumber, sourceLine, "Timeline event cannot be empty")
+  }
+  return events
+}
+
+function splitEventFields(value: string): string[] {
+  const fields: string[] = []
+  let quote: '"' | "'" | undefined
+  let start = 0
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index]
+    if (char === '"' || char === "'") {
+      if (quote === char) quote = undefined
+      else if (quote === undefined && value.slice(start, index).trim() === "") quote = char
+      continue
+    }
+    const next = value[index + 1]
+    if (char !== ":" || quote !== undefined || (next !== undefined && !/\s/.test(next))) continue
+    fields.push(value.slice(start, index))
+    start = index + 1
+  }
+  fields.push(value.slice(start))
+  return fields
+}
+
+function stripTimelineComment(value: string): string {
+  const comment = value.indexOf("%%")
+  return (comment < 0 ? value : value.slice(0, comment)).trim()
+}
+
+function syntaxError(lineNumber: number, sourceLine: string, reason?: string): MermaidSyntaxError {
+  return new MermaidSyntaxError("timeline", lineNumber, sourceLine, reason)
+}

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

@@ -0,0 +1,17 @@
+import type { StyledText } from "@opentui/core"
+import type { DiagramCanvas } from "../core/canvas.js"
+import { renderDiagramGridStyledText } from "../core/render-grid.js"
+import type { TimelineStyleColors } from "./style.js"
+import type { TimelineCellStyle } from "./types.js"
+
+export type TimelineGrid = DiagramCanvas<TimelineCellStyle>
+
+export function renderTimelineGridText(grid: TimelineGrid): string {
+  return grid.toString({ trimBottom: true })
+}
+
+export function renderTimelineGridStyledText(grid: TimelineGrid, colors: TimelineStyleColors): StyledText {
+  return renderDiagramGridStyledText(grid, (run) => (run.style ? colors[run.style] : undefined), undefined, {
+    trimBottom: true,
+  })
+}

package/src/merman/timeline/style.ts

@@ -0,0 +1,36 @@
+import { RGBA } from "@opentui/core"
+import { blendColor, numberedStyleKeys, rgba, type DiagramRgb } from "../core/color/style.js"
+import type { TimelineBaseCellStyle, TimelineCellStyle } from "./types.js"
+
+const DEFAULT_THEME_RGB = {
+  title: [228, 239, 232],
+  section: [154, 184, 169],
+  period: [230, 177, 126],
+  spine: [111, 138, 126],
+  event: [134, 225, 200],
+} as const satisfies Record<TimelineBaseCellStyle, DiagramRgb>
+
+export type TimelineStyleColors = Required<Record<TimelineCellStyle, RGBA>>
+export const TIMELINE_SECTION_FADE_STYLES = numberedStyleKeys("sectionFade", [1, 2, 3] as const)
+export const TIMELINE_PERIOD_FADE_STYLES = numberedStyleKeys("periodFade", [1, 2, 3] as const)
+
+export function resolveTimelineStyleColors(
+  colors: Partial<Record<TimelineBaseCellStyle, RGBA | undefined>> = {},
+): TimelineStyleColors {
+  const section = colors.section ?? rgba(DEFAULT_THEME_RGB.section)
+  const period = colors.period ?? rgba(DEFAULT_THEME_RGB.period)
+  const spine = colors.spine ?? rgba(DEFAULT_THEME_RGB.spine)
+  return {
+    title: colors.title ?? rgba(DEFAULT_THEME_RGB.title),
+    section,
+    period,
+    spine,
+    event: colors.event ?? rgba(DEFAULT_THEME_RGB.event),
+    sectionFade1: blendColor(section, spine, 0.5),
+    sectionFade2: blendColor(section, spine, 0.67),
+    sectionFade3: blendColor(section, spine, 0.83),
+    periodFade1: blendColor(period, spine, 0.5),
+    periodFade2: blendColor(period, spine, 0.67),
+    periodFade3: blendColor(period, spine, 0.83),
+  }
+}

package/src/merman/timeline/types.ts

@@ -0,0 +1,31 @@
+export type TimelineDirection = "TD" | "LR"
+
+export interface TimelineSection {
+  label: string
+}
+
+export interface TimelinePeriod {
+  period: string
+  events: string[]
+}
+
+export type TimelineEntry = { type: "section"; section: TimelineSection } | { type: "period"; period: TimelinePeriod }
+
+export interface TimelineDiagram {
+  direction: TimelineDirection
+  title?: string
+  sections: TimelineSection[]
+  periods: TimelinePeriod[]
+  entries: TimelineEntry[]
+}
+
+export interface TimelineDiagramRenderOptions {
+  /** Parsed for Mermaid compatibility. Timeline diagrams always use a vertical terminal layout. */
+  direction?: TimelineDirection
+}
+
+export type TimelineBaseCellStyle = "title" | "section" | "period" | "spine" | "event"
+export type TimelineFadeStep = 1 | 2 | 3
+export type TimelineSectionFadeStyle = `sectionFade${TimelineFadeStep}`
+export type TimelinePeriodFadeStyle = `periodFade${TimelineFadeStep}`
+export type TimelineCellStyle = TimelineBaseCellStyle | TimelineSectionFadeStyle | TimelinePeriodFadeStyle

package/src/merman.ts

@@ -0,0 +1,3 @@
+export { detectMermaidDiagram } from "./merman/detect"
+export { MermaidSyntaxError, type MermaidDiagramKind } from "./merman/diagnostics"
+export { createOpenCodeDiagramPalette, resolveOpenCodeDiagramPalette, type OpenCodeDiagramPalette } from "./merman/palette"