opentui-markdown-render 0.0.0-stage → 0.2.0

package/src/config/load.ts

@@ -0,0 +1,337 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { isFrameAlign, isFrameStyle } from "../core/frame"
+import { isTableColumnFitter, isTableOverflow, isTableWidthMode } from "../core/tables"
+import { isHeadingLevelKey, isStatusLineField, isStatusLineStyle, type HeadingLevelConfig, type HeadingsConfig, type MarkdownConfig, type StatusLineField } from "./types"
+import { validateThemeConfig } from "./theme"
+
+export const configFilenames = ["opentui-markdown-render.jsonc", "opentui-markdown-render.json"]
+export const xdgConfigFilenames = ["config.jsonc", "config.json"]
+export const xdgConfigDirectory = "otmd"
+
+// Config warnings normally go to stderr. A host that embeds the renderer can
+// collect them instead and show them in its own UI.
+export type ConfigReporter = (message: string) => void
+
+function warn(report: ConfigReporter | undefined, message: string) {
+  if (report) report(message)
+  else console.warn(`[opentui-markdown-render] ${message}`)
+}
+
+// The config is an ordinary JSON/JSONC object. Parsing is intentionally
+// forgiving: comments and trailing commas are stripped, everything else has to
+// be valid JSON.
+export function loadConfig(explicitPath?: string, cwd?: string, report?: ConfigReporter): MarkdownConfig {
+  const file = explicitPath ?? discoverConfig(cwd ?? process.cwd())
+  if (!file) return {}
+  if (!existsSync(file)) {
+    if (explicitPath) throw new Error(`Config not found: ${file}`)
+    return {}
+  }
+  return parseConfig(readFileSync(file, "utf8"), file, report)
+}
+
+// Component-facing adapter: malformed or missing explicit files should report
+// diagnostics, not abort the Solid tree. Embedders can disable discovery.
+export function loadRendererConfig(
+  configPath?: string,
+  cwd?: string,
+  options: { readonly discover?: boolean; readonly report?: ConfigReporter } = {},
+): MarkdownConfig {
+  if (options.discover === false && !configPath) return {}
+  try {
+    return loadConfig(configPath, cwd, options.report)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    warn(options.report, message)
+    return {}
+  }
+}
+
+export type ConfigEnvironment = {
+  readonly XDG_CONFIG_HOME?: string
+  readonly HOME?: string
+}
+
+export function discoverConfig(
+  start: string,
+  environment: ConfigEnvironment = { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME, HOME: process.env.HOME },
+): string | undefined {
+  let directory = path.resolve(start)
+  while (true) {
+    for (const name of configFilenames) {
+      const candidate = path.join(directory, name)
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
+    }
+    const parent = path.dirname(directory)
+    if (parent === directory) break
+    directory = parent
+  }
+
+  return discoverXdgConfig(environment)
+}
+
+function discoverXdgConfig(environment: ConfigEnvironment): string | undefined {
+  const configured = environment.XDG_CONFIG_HOME
+  const configHome = configured && path.isAbsolute(configured)
+    ? configured
+    : path.join(environment.HOME || os.homedir(), ".config")
+  const directory = path.join(configHome, xdgConfigDirectory)
+  for (const name of xdgConfigFilenames) {
+    const candidate = path.join(directory, name)
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
+  }
+  return undefined
+}
+
+export function parseConfig(source: string, file = "config", report?: ConfigReporter): MarkdownConfig {
+  const parsed = parseJsonc(source, file)
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Invalid config ${file}: expected a JSON object`)
+  }
+  return validateConfig(parsed as Record<string, unknown>, file, report)
+}
+
+export function parseJsonc(source: string, file = "config"): unknown {
+  try {
+    return JSON.parse(stripJsonComments(source))
+  } catch (error) {
+    throw new Error(`Invalid config ${file}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+const sections = ["theme", "statusline", "images", "mermaid", "headings", "frame", "tables"] as const
+
+function validateConfig(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig {
+  for (const key of Object.keys(value)) {
+    if (key === "$schema") continue
+    if (!sections.includes(key as (typeof sections)[number])) {
+      warn(report, `Unknown config section "${key}" in ${file}`)
+    }
+  }
+  return {
+    theme: isRecord(value.theme) ? validateThemeConfig(value.theme, file, report) : undefined,
+    statusline: isRecord(value.statusline) ? validateStatusLine(value.statusline, file, report) : undefined,
+    images: isRecord(value.images) ? validateImages(value.images) : undefined,
+    mermaid: isRecord(value.mermaid) ? validateMermaid(value.mermaid, file, report) : undefined,
+    headings: isRecord(value.headings) ? validateHeadings(value.headings, file, report) : undefined,
+    frame: isRecord(value.frame) ? validateFrame(value.frame, file, report) : undefined,
+    tables: isRecord(value.tables) ? validateTables(value.tables, file, report) : undefined,
+  }
+}
+
+function validateStatusLine(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig["statusline"] {
+  const fields: StatusLineField[] = []
+  if (Array.isArray(value.fields)) {
+    for (const entry of value.fields) {
+      if (isStatusLineField(entry)) fields.push(entry)
+      else warn(report, `Unknown status line field "${String(entry)}" in ${file}`)
+    }
+  }
+  if (value.style !== undefined && !isStatusLineStyle(value.style)) {
+    warn(report, `Unknown status line style "${String(value.style)}" in ${file}`)
+  }
+  if (value.highlight !== undefined && !isStatusLineField(value.highlight)) {
+    warn(report, `Unknown status line field "${String(value.highlight)}" in ${file}`)
+  }
+  return {
+    enabled: typeof value.enabled === "boolean" ? value.enabled : undefined,
+    fields: fields.length ? fields : undefined,
+    separator: typeof value.separator === "string" ? value.separator : undefined,
+    border: value.border === "none" || value.border === "top" || value.border === "bottom" ? value.border : undefined,
+    style: isStatusLineStyle(value.style) ? value.style : undefined,
+    highlight: isStatusLineField(value.highlight) ? value.highlight : undefined,
+  }
+}
+
+function validateImages(value: Record<string, unknown>): MarkdownConfig["images"] {
+  return {
+    maxColumns: positiveInteger(value.maxColumns),
+    maxRows: positiveInteger(value.maxRows),
+  }
+}
+
+function validateMermaid(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig["mermaid"] {
+  if (value.classLayout !== undefined && value.classLayout !== "builtin" && value.classLayout !== "dagre") {
+    warn(report, `Unknown Mermaid class layout "${String(value.classLayout)}" in ${file}`)
+  }
+  return {
+    compact: typeof value.compact === "boolean" ? value.compact : undefined,
+    layoutMaxWidth: positiveInteger(value.layoutMaxWidth),
+    classLayout: value.classLayout === "dagre" || value.classLayout === "builtin" ? value.classLayout : undefined,
+  }
+}
+
+// The frame is the viewer window. An option the renderer does not know is
+// reported and ignored, so a typo in the file never takes the document down.
+function validateFrame(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig["frame"] {
+  const option = <T>(name: string, check: (input: unknown) => input is T): T | undefined => {
+    const entry = value[name]
+    if (entry === undefined) return undefined
+    if (check(entry)) return entry
+    warn(report, `Invalid frame option "${name}" in ${file}`)
+    return undefined
+  }
+  const padding = (name: string) => {
+    const entry = value[name]
+    if (entry === undefined) return undefined
+    if (isNonNegativeInteger(entry)) return entry
+    warn(report, `Invalid frame option "${name}" in ${file}`)
+    return undefined
+  }
+  const boolean = (name: string) => {
+    const entry = value[name]
+    if (entry === undefined) return undefined
+    if (typeof entry === "boolean") return entry
+    warn(report, `Invalid frame option "${name}" in ${file}`)
+    return undefined
+  }
+  const width = (() => {
+    const entry = value.width
+    if (entry === undefined) return undefined
+    if (typeof entry === "number" && Number.isInteger(entry) && entry > 0) return entry
+    warn(report, `Invalid frame option "width" in ${file}`)
+    return undefined
+  })()
+  const title = value.title
+  if (title !== undefined && typeof title !== "string") {
+    warn(report, `Invalid frame option "title" in ${file}`)
+  }
+  return {
+    enabled: boolean("enabled"),
+    width,
+    align: option("align", isFrameAlign),
+    style: option("style", isFrameStyle),
+    paddingX: padding("paddingX"),
+    paddingY: padding("paddingY"),
+    title: typeof title === "string" ? title : undefined,
+    titleAlign: option("titleAlign", isFrameAlign),
+  }
+}
+
+function validateTables(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig["tables"] {
+  const option = <T>(name: string, check: (input: unknown) => input is T): T | undefined => {
+    const entry = value[name]
+    if (entry === undefined) return undefined
+    if (check(entry)) return entry
+    warn(report, `Invalid tables option "${name}" in ${file}`)
+    return undefined
+  }
+  const padding = value.cellPaddingX
+  if (padding !== undefined && !isNonNegativeInteger(padding)) {
+    warn(report, `Invalid tables option "cellPaddingX" in ${file}`)
+  }
+  return {
+    widthMode: option("widthMode", isTableWidthMode),
+    overflow: option("overflow", isTableOverflow),
+    columnFitter: option("columnFitter", isTableColumnFitter),
+    cellPaddingX: isNonNegativeInteger(padding) ? padding : undefined,
+  }
+}
+
+// The heading styles are addressed by level. A level or an option that the
+// renderer does not know is reported and ignored, so a typo in the file never
+// takes the document down.
+function validateHeadings(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig["headings"] {
+  if (value.levels !== undefined && !isRecord(value.levels)) {
+    warn(report, `Invalid heading levels in ${file}`)
+    return undefined
+  }
+  const levels: Record<string, HeadingLevelConfig> = {}
+  for (const [key, entry] of Object.entries(value.levels ?? {})) {
+    if (!isHeadingLevelKey(key)) {
+      warn(report, `Unknown heading level "${key}" in ${file}`)
+      continue
+    }
+    if (!isRecord(entry)) {
+      warn(report, `Invalid heading level "${key}" in ${file}`)
+      continue
+    }
+    levels[key] = validateHeadingLevel(key, entry, file, report)
+  }
+  return Object.keys(levels).length ? { levels: levels as HeadingsConfig["levels"] } : undefined
+}
+
+function validateHeadingLevel(key: string, value: Record<string, unknown>, file: string, report?: ConfigReporter): HeadingLevelConfig {
+  const style: Record<string, unknown> = {}
+  for (const [name, entry] of Object.entries(value)) {
+    switch (name) {
+      case "bold":
+      case "italic":
+      case "underline":
+      case "dim":
+      case "uppercase":
+        if (typeof entry !== "boolean") {
+          warn(report, `Invalid heading option "${name}" for level ${key} in ${file}`)
+          continue
+        }
+        style[name] = entry
+        break
+      case "marginTop":
+      case "marginBottom":
+        if (!isNonNegativeInteger(entry)) {
+          warn(report, `Invalid heading option "${name}" for level ${key} in ${file}`)
+          continue
+        }
+        style[name] = entry
+        break
+      default:
+        warn(report, `Unknown heading option "${name}" for level ${key} in ${file}`)
+    }
+  }
+  return style as HeadingLevelConfig
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function stripJsonComments(source: string) {
+  let result = ""
+  let index = 0
+  let inString = false
+  let quote = ""
+  while (index < source.length) {
+    const character = source[index]!
+    if (inString) {
+      result += character
+      if (character === "\\") {
+        result += source[index + 1] ?? ""
+        index += 2
+        continue
+      }
+      if (character === quote) inString = false
+      index++
+      continue
+    }
+    if (character === '"' || character === "'") {
+      inString = true
+      quote = character
+      result += character
+      index++
+      continue
+    }
+    if (character === "/" && source[index + 1] === "/") {
+      while (index < source.length && source[index] !== "\n") index++
+      continue
+    }
+    if (character === "/" && source[index + 1] === "*") {
+      index += 2
+      while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) index++
+      index += 2
+      continue
+    }
+    result += character
+    index++
+  }
+  return result.replace(/,(\s*[}\]])/g, "$1")
+}

package/src/config/resolve.ts

@@ -0,0 +1,36 @@
+import type { Theme, ThemePreset } from "../theme/types"
+import { resolveTheme } from "../theme/resolve"
+import { loadTheme } from "../theme/load"
+import { createDocumentLayout, type DocumentLayout, type FrameConfig, type TablesConfig } from "../core"
+import type { MarkdownConfig } from "./types"
+
+export type ThemeModeSetting = ThemePreset
+
+// The configuration describes the document's defaults. The host supplies live
+// values separately; a ready-made theme is never merged with the file theme.
+export type ThemeRuntime = {
+  readonly theme?: Theme
+  readonly themeMode?: ThemeModeSetting | null
+}
+
+export function resolveConfiguredTheme(config: MarkdownConfig, runtime: ThemeRuntime = {}): Theme {
+  if (runtime.theme) return runtime.theme
+  const explicit = runtime.themeMode ?? undefined
+  const override = loadTheme(explicit ?? config.theme?.name ?? "light")
+  const mode = override?.mode ?? "light"
+  return resolveTheme({ mode, override })
+}
+
+export type LayoutRuntime = {
+  readonly viewport: number
+  readonly frame?: FrameConfig
+  readonly tables?: TablesConfig
+}
+
+export function resolveConfiguredLayout(config: MarkdownConfig, runtime: LayoutRuntime): DocumentLayout {
+  return createDocumentLayout({
+    viewport: runtime.viewport,
+    frame: runtime.frame ?? config.frame,
+    tables: runtime.tables ?? config.tables,
+  })
+}

package/src/config/theme.ts

@@ -0,0 +1,110 @@
+import type { ThemeOverride } from "../theme/types"
+import type { ThemeConfig } from "./types"
+import type { ConfigReporter } from "./load"
+
+// A JSON file only carries strings, not RGBA instances. OpenTUI accepts these
+// colour names and hex forms; rejecting anything else here avoids its silent
+// magenta fallback for misspelled colours.
+const colorNames = new Set([
+  "transparent", "black", "white", "red", "green", "blue", "yellow", "cyan", "magenta",
+  "silver", "gray", "grey", "maroon", "olive", "lime", "aqua", "teal", "navy",
+  "fuchsia", "purple", "orange", "brightblack", "brightred", "brightgreen",
+  "brightblue", "brightyellow", "brightcyan", "brightmagenta", "brightwhite",
+])
+
+type Field = "name" | "color" | "mode" | "colors" | { readonly [key: string]: Field }
+const colors = <K extends string>(keys: readonly K[]): Record<K, Field> =>
+  Object.fromEntries(keys.map((key) => [key, "color"])) as Record<K, Field>
+
+// The allowlist follows ThemeOverride, not the resolved Theme: headingLevels
+// is an internal six-colour array, while heading1..heading6 are file options.
+const themeFileFields: Record<string, Field> = {
+  mode: "mode",
+  palette: "colors",
+  accent: "color",
+  categorical: "colors",
+  text: {
+    base: "color",
+    muted: "color",
+    feedback: colors(["error", "warning", "success", "info"]),
+    action: { primary: { focused: "color" } },
+  },
+  background: { base: "color" },
+  border: { base: "color" },
+  frame: colors(["border", "title"]),
+  statusline: colors(["background", "foreground", "title", "muted", "border"]),
+  markdown: colors([
+    "text", "heading", "heading1", "heading2", "heading3", "heading4", "heading5", "heading6",
+    "link", "linkText", "code", "blockQuote", "emphasis", "strong", "horizontalRule",
+    "listItem", "listEnumeration", "image", "imageText", "codeBlock",
+  ]),
+  syntax: colors(["comment", "keyword", "function", "variable", "string", "number", "type", "operator", "punctuation"]),
+  diff: {
+    text: colors(["added", "removed", "context"]),
+    background: colors(["added", "removed", "context"]),
+  },
+}
+
+function isColor(value: unknown): value is string {
+  return typeof value === "string" && (
+    /^#?(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(value) ||
+    colorNames.has(value.toLowerCase())
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export function validateTheme(value: Record<string, unknown>, file: string, report?: ConfigReporter): ThemeOverride {
+  const warn = (message: string) => {
+    if (report) report(message)
+    else console.warn(`[opentui-markdown-render] ${message}`)
+  }
+  const validate = (source: Record<string, unknown>, fields: Record<string, Field>, prefix: string): Record<string, unknown> => {
+    const result: Record<string, unknown> = Object.create(null)
+    for (const [key, entry] of Object.entries(source)) {
+      const field = Object.hasOwn(fields, key) ? fields[key] : undefined
+      const location = `${prefix}.${key}`
+      if (field === undefined) {
+        warn(`Unknown theme option "${location}" in ${file}`)
+        continue
+      }
+      if (field === "color" && isColor(entry)) result[key] = entry
+      else if (field === "mode" && (entry === "light" || entry === "dark" || entry === "solarized-light" || entry === "solarized-dark")) result[key] = entry
+      else if (field === "colors" && Array.isArray(entry)) {
+        result[key] = entry.filter((color, index) => {
+          if (isColor(color)) return true
+          warn(`Invalid theme option "${location}[${index}]" in ${file}`)
+          return false
+        })
+      } else if (typeof field === "object" && isRecord(entry)) {
+        result[key] = validate(entry, field, location)
+      } else {
+        warn(`Invalid theme option "${location}" in ${file}`)
+      }
+    }
+    return result
+  }
+  return validate(value, themeFileFields, "theme") as ThemeOverride
+}
+
+export function validateThemeConfig(value: Record<string, unknown>, file: string, report?: ConfigReporter): ThemeConfig {
+  const warn = (message: string) => {
+    if (report) report(message)
+    else console.warn(`[opentui-markdown-render] ${message}`)
+  }
+  const result: { name?: string } = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (key !== "name") {
+      warn(`Unknown theme option "theme.${key}" in ${file}`)
+      continue
+    }
+    if (typeof entry !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(entry)) {
+      warn(`Invalid theme option "theme.name" in ${file}`)
+      continue
+    }
+    result.name = entry
+  }
+  return result
+}

package/src/config/types.ts

@@ -0,0 +1,105 @@
+import type { FrameConfig } from "../core/frame"
+import type { TablesConfig } from "../core/tables"
+
+// The configuration file is a plain JSON/JSONC object. Every section is
+// optional; a missing section keeps the bundled default.
+export type MarkdownConfig = {
+  // Selects a complete theme file from the bundled or XDG theme directory.
+  readonly theme?: ThemeConfig
+  readonly statusline?: StatusLineConfig
+  readonly images?: ImagesConfig
+  readonly mermaid?: MermaidConfig
+  readonly headings?: HeadingsConfig
+  // How the viewer window is drawn around the document.
+  readonly frame?: FrameConfig
+  // How tables size themselves and what happens when they are too wide.
+  readonly tables?: TablesConfig
+}
+
+export type ThemeConfig = {
+  readonly name?: string
+}
+
+// The status line is a single row of labelled fields. `fields` selects and
+// orders them; a field without a value is skipped.
+export type StatusLineConfig = {
+  readonly enabled?: boolean
+  readonly fields?: readonly StatusLineField[]
+  readonly separator?: string
+  readonly border?: StatusLineBorder
+  // "plain" keeps the line in the page colours, "bar" gives it its own
+  // background and an accent border.
+  readonly style?: StatusLineStyle
+  // The field that gets the accent treatment.
+  readonly highlight?: StatusLineField
+}
+
+export type StatusLineField = "title" | "mode" | "protocol" | "cell" | "mathScale" | "position" | "hint" | "text"
+
+export type StatusLineBorder = "none" | "top" | "bottom"
+
+export type StatusLineStyle = "plain" | "bar"
+
+export const statusLineStyles: readonly StatusLineStyle[] = ["plain", "bar"]
+
+export function isStatusLineStyle(value: unknown): value is StatusLineStyle {
+  return typeof value === "string" && statusLineStyles.includes(value as StatusLineStyle)
+}
+
+export type ImagesConfig = {
+  // Maximum width of a rendered image in terminal columns.
+  readonly maxColumns?: number
+  // Maximum height of a rendered image in terminal rows.
+  readonly maxRows?: number
+}
+
+export type MermaidConfig = {
+  readonly compact?: boolean
+  readonly layoutMaxWidth?: number
+  /** Class diagrams only; defaults to the built-in layout. */
+  readonly classLayout?: "builtin" | "dagre"
+}
+
+// The heading levels are addressed by their number, the way Markdown writes
+// them.
+export type HeadingLevelKey = "1" | "2" | "3" | "4" | "5" | "6"
+
+// The look of a single heading level. Every option is optional: a missing one
+// keeps the bundled default for that level.
+export type HeadingLevelConfig = {
+  readonly bold?: boolean
+  readonly italic?: boolean
+  readonly underline?: boolean
+  readonly dim?: boolean
+  // Render the text of the heading in upper case.
+  readonly uppercase?: boolean
+  // Empty rows above the heading.
+  readonly marginTop?: number
+  // Empty rows below the heading.
+  readonly marginBottom?: number
+}
+
+export type HeadingsConfig = {
+  readonly levels?: { readonly [K in HeadingLevelKey]?: HeadingLevelConfig }
+}
+
+export const headingLevelKeys: readonly HeadingLevelKey[] = ["1", "2", "3", "4", "5", "6"]
+
+export function isHeadingLevelKey(value: string): value is HeadingLevelKey {
+  return (headingLevelKeys as readonly string[]).includes(value)
+}
+
+export const statusLineFields: readonly StatusLineField[] = [
+  "title",
+  "mode",
+  "protocol",
+  "cell",
+  "mathScale",
+  "position",
+  "hint",
+  "text",
+]
+
+export function isStatusLineField(value: unknown): value is StatusLineField {
+  return typeof value === "string" && statusLineFields.includes(value as StatusLineField)
+}

package/src/core/document.ts

@@ -0,0 +1,44 @@
+export type SourceRange = { readonly start: number; readonly end: number }
+
+export type NodeBase = { readonly raw: string; readonly source: SourceRange | null }
+
+export type Document = { readonly source: string; readonly blocks: readonly Block[] }
+
+export type Block =
+  | (NodeBase & { readonly type: 'paragraph'; readonly children: readonly Inline[] })
+  | (NodeBase & { readonly type: 'heading'; readonly level: 1 | 2 | 3 | 4 | 5 | 6; readonly children: readonly Inline[] })
+  | (NodeBase & { readonly type: 'quote'; readonly blocks: readonly Block[] })
+  | (NodeBase & { readonly type: 'list'; readonly ordered: boolean; readonly start: number; readonly loose: boolean; readonly items: readonly ListItem[] })
+  | (NodeBase & { readonly type: 'table'; readonly align: readonly ('left' | 'center' | 'right' | null)[]; readonly header: readonly TableCell[]; readonly rows: readonly (readonly TableCell[])[] })
+  | (NodeBase & { readonly type: 'code'; readonly language: string | null; readonly content: string; readonly fenced: boolean })
+  | (NodeBase & { readonly type: 'mermaid'; readonly content: string; readonly language: string })
+  | (NodeBase & { readonly type: 'rule' })
+  | (NodeBase & { readonly type: 'display-math'; readonly content: string; readonly open: '$$' | '\\['; readonly close: '$$' | '\\]' })
+  | (NodeBase & { readonly type: 'image'; readonly href: string; readonly alt: string; readonly title: string | null })
+  | (NodeBase & { readonly type: 'literal'; readonly text: string })
+
+export type ListItem = {
+  readonly task: boolean
+  readonly checked: boolean | null
+  readonly loose: boolean
+  readonly blocks: readonly Block[]
+  readonly source: SourceRange | null
+}
+
+export type UnitInfo =
+  | { readonly kind: 'block'; readonly block: Exclude<Block, { type: 'list' }>; readonly source: SourceRange | null }
+  | { readonly kind: 'list-item'; readonly item: ListItem; readonly source: SourceRange | null }
+
+export type TableCell = { readonly children: readonly Inline[]; readonly header: boolean; readonly align: 'left' | 'center' | 'right' | null }
+
+export type Inline =
+  | { readonly type: 'text' | 'code'; readonly text: string }
+  | { readonly type: 'strong' | 'em' | 'del'; readonly children: readonly Inline[] }
+  | { readonly type: 'link'; readonly href: string; readonly title: string | null; readonly children: readonly Inline[] }
+  | { readonly type: 'inline-image'; readonly href: string; readonly alt: string; readonly title: string | null }
+  | { readonly type: 'break'; readonly hard: boolean }
+  | { readonly type: 'math'; readonly content: string; readonly open: '$' | '\\('; readonly close: '$' | '\\)'; readonly raw: string }
+
+export function assertNever(value: never): never {
+  throw new Error(`Unexpected document node: ${String(value)}`)
+}