opentui-markdown-render 0.0.0-stage → 0.1.0

package/src/core/parse.ts

@@ -0,0 +1,208 @@
+import { Marked, type Token, type Tokens } from "marked"
+import { createMathDisplayExtension, createMathInlineExtension, type MathDisplayToken, type MathInlineToken } from "./math"
+import type { Block, Document, Inline, SourceRange, TableCell } from "./document"
+
+const parser = new Marked({
+  gfm: true,
+  breaks: false,
+  async: false,
+  extensions: [createMathDisplayExtension(), createMathInlineExtension()],
+})
+
+type ParserToken = Token | MathDisplayToken | MathInlineToken
+
+function isDisplay(token: ParserToken): token is MathDisplayToken {
+  return token.type === "mathDisplay"
+}
+
+function isInlineMath(token: ParserToken): token is MathInlineToken {
+  return token.type === "mathInline"
+}
+
+function childrenOf(token: ParserToken): ParserToken[] {
+  return "tokens" in token && Array.isArray(token.tokens) ? token.tokens : []
+}
+
+function inlineToken(token: ParserToken): Inline[] {
+  if (isInlineMath(token)) {
+    return [{ type: "math", content: token.content, raw: token.raw, open: token.open, close: token.close }]
+  }
+  if (isDisplay(token)) return [{ type: "text", text: token.raw }]
+  switch (token.type) {
+    case "text":
+      return childrenOf(token).length ? convertInline(childrenOf(token)) : [{ type: "text", text: token.text }]
+    case "escape":
+      return [{ type: "text", text: token.text }]
+    case "codespan":
+      return [{ type: "code", text: token.text }]
+    case "strong":
+    case "em":
+    case "del":
+      return [{ type: token.type, children: convertInline(token.tokens ?? []) }]
+    case "link":
+      return [{ type: "link", href: token.href, title: token.title ?? null, children: convertInline(token.tokens ?? []) }]
+    case "image":
+      return [{ type: "inline-image", href: token.href, title: token.title ?? null, alt: token.text }]
+    case "br":
+      return [{ type: "break", hard: true }]
+    case "checkbox":
+      return [] // ListItem.task/checked already carry the marker.
+    default:
+      return token.raw ? [{ type: "text", text: token.raw }] : []
+  }
+}
+
+function convertInline(tokens: readonly ParserToken[]): Inline[] {
+  return tokens.flatMap(inlineToken)
+}
+
+function directInline(tokens: readonly ParserToken[]): ParserToken[] {
+  // Marked wraps the inline tokens of tight list items in a `text` block.
+  return tokens.flatMap((token) => token.type === "text" && childrenOf(token).length ? childrenOf(token) : [token])
+}
+
+function convertParagraph(token: ParserToken, source: SourceRange | null): Block[] {
+  const tokens = directInline(childrenOf(token))
+  const visible = convertInline(tokens).filter((node) => node.type !== "text" || node.text.trim().length > 0)
+  if (visible.length === 1 && visible[0].type === "inline-image") {
+    const image = visible[0]
+    return [{ type: "image", href: image.href, alt: image.alt, title: image.title, raw: token.raw, source }]
+  }
+
+  if (!tokens.some(isDisplay)) return [{ type: "paragraph", children: convertInline(tokens), raw: token.raw, source }]
+
+  const blocks: Block[] = []
+  let pending: ParserToken[] = []
+  // Only direct top-level children with exact raw alignment receive a range;
+  // Marked normalizes tokens inside nested quotes and list items.
+  let offset = source?.start ?? 0
+  let aligned = source !== null
+  let pendingStart = offset
+  const flush = () => {
+    if (!pending.length) return
+    const raw = pending.map((child) => child.raw).join("")
+    const children = convertInline(pending)
+    if (children.length) blocks.push({ type: "paragraph", raw, source: aligned ? { start: pendingStart, end: offset } : null, children })
+    pending = []
+    pendingStart = offset
+  }
+  for (const child of tokens) {
+    if (aligned && token.raw.slice(offset - source!.start, offset - source!.start + child.raw.length) !== child.raw) aligned = false
+    if (isDisplay(child)) {
+      flush()
+      offset += child.raw.length
+      blocks.push({
+        type: "display-math", content: child.content, open: child.open, close: child.close,
+        raw: child.raw, source: aligned ? { start: offset - child.raw.length, end: offset } : null,
+      })
+      pendingStart = offset
+    } else {
+      pending.push(child)
+      offset += child.raw.length
+    }
+  }
+  flush()
+  return blocks
+}
+
+function convertBlocks(tokens: readonly ParserToken[], source: string | null, start = 0): Block[] {
+  const blocks: Block[] = []
+  let cursor = start
+  for (const token of tokens) {
+    const range: SourceRange | null = source !== null && source.slice(cursor, cursor + token.raw.length) === token.raw
+      ? { start: cursor, end: cursor + token.raw.length }
+      : null
+    // `space` and `def` are invisible, but still occupy source positions.
+    cursor += token.raw.length
+    if (token.type === "space" || token.type === "def" || token.type === "checkbox") continue
+    if (isDisplay(token)) {
+      blocks.push({ type: "display-math", content: token.content, open: token.open, close: token.close, raw: token.raw, source: range })
+      continue
+    }
+    switch (token.type) {
+      case "paragraph":
+      case "text":
+        blocks.push(...convertParagraph(token, range))
+        break
+      case "heading":
+        blocks.push({ type: "heading", level: token.depth as 1 | 2 | 3 | 4 | 5 | 6, children: convertInline(childrenOf(token)), raw: token.raw, source: range })
+        break
+      case "blockquote":
+        blocks.push({ type: "quote", blocks: convertBlocks(childrenOf(token), null), raw: token.raw, source: range })
+        break
+      case "list": {
+        const list = token as Tokens.List
+        let cursor = 0
+        const items = list.items.map((item) => {
+          let itemSource: SourceRange | null = null
+          if (range !== null && list.raw.slice(cursor, cursor + item.raw.length) === item.raw) {
+            itemSource = { start: range.start + cursor, end: range.start + cursor + item.raw.length }
+          }
+          cursor += item.raw.length
+          return {
+            task: item.task, checked: item.task ? (item.checked ?? false) : null, loose: item.loose,
+            blocks: convertBlocks(item.tokens, null),
+            source: itemSource,
+          }
+        })
+        blocks.push({
+          type: "list", raw: list.raw, source: range, ordered: list.ordered,
+          start: list.start === "" ? 1 : list.start, loose: list.loose,
+          items,
+        })
+        break
+      }
+      case "table": {
+        const table = token as Tokens.Table
+        const convertCell = (cell: Tokens.TableCell | undefined, header: boolean, align: TableCell["align"]): TableCell => ({
+          children: cell ? convertInline(cell.tokens) : [], header, align,
+        })
+        const align = table.align
+        const header = table.header.map((cell, i) => convertCell(cell, true, align[i] ?? null))
+        const rows = table.rows.map((row) => header.map((_, i) => convertCell(row[i], false, align[i] ?? null)))
+        blocks.push({ type: "table", align, header, rows, raw: table.raw, source: range })
+        break
+      }
+      case "code": {
+        const language = token.lang ?? null
+        if (language?.trim().split(/\s+/)[0]?.toLowerCase() === "mermaid") {
+          blocks.push({ type: "mermaid", content: token.text, language: "mermaid", raw: token.raw, source: range })
+        } else {
+          blocks.push({ type: "code", content: token.text, language, fenced: /^ {0,3}(?:`{3,}|~{3,})/.test(token.raw), raw: token.raw, source: range })
+        }
+        break
+      }
+      case "hr":
+        blocks.push({ type: "rule", raw: token.raw, source: range })
+        break
+      default:
+        // HTML and unknown extensions are literal, never executed or silently lost.
+        if (token.raw) blocks.push({ type: "literal", text: token.raw, raw: token.raw, source: range })
+    }
+  }
+  return blocks
+}
+
+export function parseDocument(source: string): Document {
+  // Marked token raw text uses LF even for CRLF input. Parse against the same
+  // normalized text, then translate proven offsets back into the host's source.
+  const normalized = source.replace(/\r\n?/g, "\n")
+  const blocks = convertBlocks(parser.lexer(normalized), normalized)
+  if (normalized === source) return { source, blocks }
+
+  const offsets: number[] = [0]
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === "\r" && source[index + 1] === "\n") index++
+    offsets.push(index + 1)
+  }
+  const originalRange = (range: SourceRange | null): SourceRange | null => range === null ? null
+    : { start: offsets[range.start]!, end: offsets[range.end]! }
+  const originalBlock = (block: Block): Block => {
+    if (block.type === "list") return {
+      ...block, source: originalRange(block.source),
+      items: block.items.map((item) => ({ ...item, source: originalRange(item.source) })),
+    }
+    return { ...block, source: originalRange(block.source) }
+  }
+  return { source, blocks: blocks.map(originalBlock) }
+}

package/src/core/tables.ts

@@ -0,0 +1,58 @@
+// Table sizing is a layout decision, not a renderer one: the answer is a set of
+// options OpenTUI understands, and it can be computed without a render context.
+export const tableWidthModes = ["content", "full"] as const
+
+// "content" sizes the columns to the cells, which keeps a two-column table from
+// stretching over the whole window. "full" is OpenTUI's grid default.
+export type TableWidthMode = (typeof tableWidthModes)[number]
+
+export function isTableWidthMode(value: unknown): value is TableWidthMode {
+  return typeof value === "string" && (tableWidthModes as readonly string[]).includes(value)
+}
+
+export const tableOverflows = ["scroll", "wrap"] as const
+
+// A table wider than the document either scrolls sideways (like the Mermaid
+// diagrams) or wraps its cells to fit.
+export type TableOverflow = (typeof tableOverflows)[number]
+
+export function isTableOverflow(value: unknown): value is TableOverflow {
+  return typeof value === "string" && (tableOverflows as readonly string[]).includes(value)
+}
+
+export const tableColumnFitters = ["proportional", "balanced"] as const
+
+export type TableColumnFitter = (typeof tableColumnFitters)[number]
+
+export function isTableColumnFitter(value: unknown): value is TableColumnFitter {
+  return typeof value === "string" && (tableColumnFitters as readonly string[]).includes(value)
+}
+
+export type TablesConfig = {
+  readonly widthMode?: TableWidthMode
+  readonly overflow?: TableOverflow
+  readonly columnFitter?: TableColumnFitter
+  readonly cellPaddingX?: number
+}
+
+export type ResolvedTableOptions = {
+  readonly widthMode: TableWidthMode
+  readonly overflow: TableOverflow
+  readonly columnFitter: TableColumnFitter
+  readonly cellPaddingX: number
+  // A table that may scroll keeps its intrinsic width. A table that has to fit
+  // wraps its cells instead of being clipped at the window edge.
+  readonly wrapMode: "none" | "word"
+}
+
+export function resolveTableOptions(config?: TablesConfig): ResolvedTableOptions {
+  const widthMode = config?.widthMode ?? "content"
+  const overflow = config?.overflow ?? "scroll"
+  return {
+    widthMode,
+    overflow,
+    columnFitter: config?.columnFitter ?? "balanced",
+    cellPaddingX: config?.cellPaddingX ?? 1,
+    wrapMode: overflow === "scroll" && widthMode === "content" ? "none" : "word",
+  }
+}

package/src/graphics.ts

@@ -0,0 +1,85 @@
+import type { CliRenderer, PixelResolution, TerminalCapabilities } from "@opentui/core"
+import { createMemo, createSignal, onCleanup } from "solid-js"
+
+export type CellSize = { readonly width: number; readonly height: number }
+
+// OpenTUI does not export its `resolveImageRenderProtocol`, so this mirrors it:
+// the package resolves the protocol from detected capabilities inside a renderer
+// child process whose environment is filtered down to a fixed allowlist (`TERM`,
+// `OPENTUI_*`, ...), which means `KITTY_WINDOW_ID` and friends never reach it.
+// Sniffing our own environment therefore cannot be trusted to agree with what
+// images will actually be drawn with.
+function resolveGraphicsProtocol(capabilities: TerminalCapabilities | null, hasResolution: boolean) {
+  const configured = capabilities?.image_protocol
+  if (configured && configured !== "auto") return configured === "sixel" && !hasResolution ? "blocks" : configured
+  if (!capabilities || capabilities.multiplexer === "tmux") return "blocks"
+  if (capabilities.kitty_graphics) return "kitty"
+  if (capabilities.sixel && hasResolution) return "sixel"
+  return "blocks"
+}
+
+// Terminals without an image protocol fall back to a block-character mosaic where
+// one cell is one coarse pixel, so a formula there needs a cell box twice as big
+// to stay legible.
+export const mosaicScale = (protocol: string) => (protocol === "blocks" ? 2 : 1)
+
+export function useCanvasGraphics(renderer: CliRenderer) {
+  // Capabilities and pixel size are resolved by terminal queries after startup,
+  // so the first frame can still be missing them.
+  const [queried, setQueried] = createSignal(0)
+  const onCapabilities = () => setQueried((value) => value + 1)
+  renderer.on("capabilities", onCapabilities)
+  let refresh: ReturnType<typeof setTimeout> | undefined
+  const onResize = () => {
+    if (refresh) clearTimeout(refresh)
+    refresh = setTimeout(() => {
+      refresh = undefined
+      setQueried((value) => value + 1)
+    }, 250)
+  }
+  renderer.on("resize", onResize)
+  // OpenTUI requests a render after receiving pixel resolution but does not emit
+  // a capabilities event for it. A short probe is enough to make the first raster
+  // use the returned cell size without keeping a background timer alive.
+  const probe = setInterval(() => {
+    if (!renderer.resolution) return
+    clearInterval(probe)
+    setQueried((value) => value + 1)
+  }, 50)
+  const stopProbe = setTimeout(() => clearInterval(probe), 1000)
+  onCleanup(() => {
+    renderer.off("capabilities", onCapabilities)
+    renderer.off("resize", onResize)
+    clearInterval(probe)
+    clearTimeout(stopProbe)
+    if (refresh) clearTimeout(refresh)
+  })
+
+  const resolution = createMemo<PixelResolution | null>(() => {
+    queried()
+    const value = renderer.resolution
+    return value && value.width > 0 && value.height > 0 ? value : null
+  })
+  const cell = createMemo<CellSize | null>(() => {
+    const value = resolution()
+    const width = renderer.terminalWidth
+    const height = renderer.terminalHeight
+    if (!value || width <= 0 || height <= 0) return null
+    const cellWidth = value.width / width
+    const cellHeight = value.height / height
+    if (cellWidth <= 0 || cellHeight <= 0) return null
+    return { width: Math.max(1, Math.round(cellWidth)), height: Math.max(1, Math.round(cellHeight)) }
+  })
+  const protocol = createMemo(() => {
+    queried()
+    return resolveGraphicsProtocol(renderer.capabilities, resolution() !== null)
+  })
+  const hyperlinks = createMemo(() => {
+    queried()
+    return renderer.capabilities?.hyperlinks === true
+  })
+
+  return { cell, protocol, hyperlinks }
+}
+
+export type CanvasGraphics = ReturnType<typeof useCanvasGraphics>

package/src/headings.ts

@@ -0,0 +1,77 @@
+import { TextAttributes, type RGBA } from "@opentui/core"
+import type { HeadingLevelConfig, HeadingsConfig } from "./config/types"
+import type { HeadingLevel, Theme } from "./theme/types"
+
+// A terminal has a single text size, so a heading level is expressed through
+// attributes, colour and spacing instead of a larger font.
+export type HeadingStyle = {
+  readonly bold: boolean
+  readonly italic: boolean
+  readonly underline: boolean
+  readonly dim: boolean
+  readonly uppercase: boolean
+  // Empty rows above the heading.
+  readonly marginTop: number
+  // Empty rows below the heading.
+  readonly marginBottom: number
+}
+
+export type HeadingStyles = Record<HeadingLevel, HeadingStyle>
+
+export const headingLevels: readonly HeadingLevel[] = [1, 2, 3, 4, 5, 6]
+
+// The bundled look: the top level is the loudest one, the lowest levels fade
+// into the prose around them.
+export const defaultHeadingStyles: HeadingStyles = {
+  1: { bold: true, italic: false, underline: true, dim: false, uppercase: false, marginTop: 2, marginBottom: 1 },
+  2: { bold: true, italic: false, underline: false, dim: false, uppercase: false, marginTop: 1, marginBottom: 0 },
+  3: { bold: true, italic: false, underline: false, dim: false, uppercase: false, marginTop: 1, marginBottom: 0 },
+  4: { bold: false, italic: true, underline: false, dim: false, uppercase: false, marginTop: 1, marginBottom: 0 },
+  5: { bold: false, italic: true, underline: false, dim: true, uppercase: false, marginTop: 1, marginBottom: 0 },
+  6: { bold: false, italic: false, underline: false, dim: true, uppercase: false, marginTop: 1, marginBottom: 0 },
+}
+
+// The configuration only carries the options the author set, so the rest of the
+// style keeps the bundled default of that level.
+function mergeHeadingStyle(base: HeadingStyle, override: HeadingLevelConfig | undefined): HeadingStyle {
+  if (!override) return base
+  return {
+    bold: override.bold ?? base.bold,
+    italic: override.italic ?? base.italic,
+    underline: override.underline ?? base.underline,
+    dim: override.dim ?? base.dim,
+    uppercase: override.uppercase ?? base.uppercase,
+    marginTop: override.marginTop ?? base.marginTop,
+    marginBottom: override.marginBottom ?? base.marginBottom,
+  }
+}
+
+export function resolveHeadingStyles(config?: HeadingsConfig): HeadingStyles {
+  const styles = {} as HeadingStyles
+  for (const level of headingLevels) {
+    styles[level] = mergeHeadingStyle(defaultHeadingStyles[level], config?.levels?.[`${level}` as "1"])
+  }
+  return styles
+}
+
+export function headingAttributes(style: HeadingStyle): number {
+  let attributes = TextAttributes.NONE
+  if (style.bold) attributes |= TextAttributes.BOLD
+  if (style.italic) attributes |= TextAttributes.ITALIC
+  if (style.underline) attributes |= TextAttributes.UNDERLINE
+  if (style.dim) attributes |= TextAttributes.DIM
+  return attributes
+}
+
+export function headingColor(theme: Theme, level: HeadingLevel): RGBA {
+  // A theme that was built by hand may not carry the ramp; the base heading
+  // colour is the fallback then.
+  return theme.markdown.headingLevels?.[level - 1] ?? theme.markdown.heading
+}
+
+// The level of a heading that came from a document is always one of the six,
+// but a host that builds a block by hand may pass any number.
+export function headingLevel(level: number): HeadingLevel {
+  const value = Math.min(6, Math.max(1, Math.round(level)))
+  return value as HeadingLevel
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+export { MarkdownRenderer, resolveRendererTheme, loadRendererConfig, type MarkdownRendererProps, type MarkdownRendererCommonProps, type MarkdownDiagnostic, type ThemeModeSetting } from "./app"
+export type { RenderUnit } from "./view/document"
+export { parseDocument, type Document, type Block, type Inline, type ListItem, type TableCell, type SourceRange, type UnitInfo } from "./core"
+export {
+  resolveFrame,
+  isFrameAlign,
+  isFrameStyle,
+  frameAligns,
+  frameStyles,
+  type FrameAlign,
+  type FrameConfig,
+  type FrameInsets,
+  type FrameStyle,
+  type ResolvedFrame,
+} from "./core/frame"
+export { MarkdownFrame, frameBorderColor, frameTitleColor } from "./view/frame"
+export {
+  resolveTableOptions,
+  isTableWidthMode,
+  isTableOverflow,
+  isTableColumnFitter,
+  tableWidthModes,
+  tableOverflows,
+  tableColumnFitters,
+  type ResolvedTableOptions,
+  type TableColumnFitter,
+  type TableOverflow,
+  type TableWidthMode,
+  type TablesConfig,
+} from "./core/tables"
+export { createDocumentLayout, type DocumentLayout, type DocumentLayoutInput } from "./core"
+export { LocalImage, imageBox, resolveLocalImage, resolveBackground, rgbToHex, standaloneImage, maxColumns, type ImageLimits, type MarkdownImage } from "./media"
+export { useCanvasGraphics, mosaicScale, type CanvasGraphics, type CellSize } from "./graphics"
+export {
+  defaultHeadingStyles,
+  resolveHeadingStyles,
+  headingAttributes,
+  headingColor,
+  headingLevels,
+  type HeadingStyle,
+  type HeadingStyles,
+} from "./headings"
+export { detectMermaidDiagram, MermaidSyntaxError, type MermaidDiagramKind } from "./merman"
+export { rgbaToHex, mathImageID, renderMathImage, type MathImage } from "./math"
+export { renderMath, clearMathCache, type MathRenderRequest, type RenderedMath } from "./math/renderer"
+export {
+  StatusLine,
+  statusLineSegments,
+  formatStatusLine,
+  statusLinePalette,
+  defaultStatusLineFields,
+  type StatusLineState,
+  type StatusLineSegment,
+  type StatusLinePalette,
+} from "./statusline"
+export {
+  loadConfig,
+  discoverConfig,
+  parseConfig,
+  configFilenames,
+  resolveConfiguredTheme,
+  resolveConfiguredLayout,
+  statusLineFields,
+  isStatusLineField,
+  statusLineStyles,
+  isStatusLineStyle,
+  type MarkdownConfig,
+  type StatusLineConfig,
+  type StatusLineField,
+  type StatusLineBorder,
+  type StatusLineStyle,
+  type ImagesConfig,
+  type MermaidConfig,
+  type HeadingsConfig,
+  type HeadingLevelConfig,
+  type HeadingLevelKey,
+  type ConfigReporter,
+  type ThemeRuntime,
+  type LayoutRuntime,
+} from "./config"
+export {
+  defaultTheme,
+  generateSyntax,
+  resolveTheme,
+  mergeTheme,
+  deriveStatusLineTheme,
+  mixColors,
+  type Theme,
+  type ThemeMode,
+  type ThemePreset,
+  type ThemeOverride,
+  type StatusLineTheme,
+  type StatusLineThemeOverride,
+  type MarkdownThemeOverride,
+  type FrameTheme,
+  type FrameThemeOverride,
+  type HeadingLevel,
+} from "./theme"

package/src/math/index.ts

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto"
+import type { RGBA } from "@opentui/core"
+import type { CellSize } from "../graphics"
+import { renderMath } from "./renderer"
+import { isRenderableLatex } from "./validate"
+
+export type { CellSize } from "../graphics"
+
+export type MathImage = {
+  readonly png: Uint8Array
+  readonly columns: number
+  readonly rows: number
+  readonly baseline: number
+  // Whether the raster was scaled below the standard text size to fit a single
+  // text row. A formula that was not scaled can keep that size.
+  readonly clamped: boolean
+}
+
+export function rgbaToHex(color: RGBA) {
+  const channel = (value: number) =>
+    Math.round(Math.max(0, Math.min(1, value)) * 255)
+      .toString(16)
+      .padStart(2, "0")
+  return `#${channel(color.r)}${channel(color.g)}${channel(color.b)}`
+}
+
+export function mathImageID(
+  content: string,
+  display: boolean,
+  color: string,
+  cell: CellSize | null,
+  scale = 1,
+  compact = false,
+  standard = false,
+) {
+  return createHash("sha256")
+    .update(JSON.stringify({ content, display, color, cell, scale, compact, standard, renderer: "mitex-typst-png-v2" }))
+    .digest("hex")
+}
+
+// The Typst page is laid out at 12pt, so a scale of `px / 12` puts one em at one
+// terminal cell height: the same text size the port reference targets with its
+// `textColumns = 2` / cell-aspect-ratio model. `scale` is only the caller's own
+// enlargement (`+`/`-`) on top of that text-relative base.
+const fontSizePoints = 12
+
+// The native renderer produces a tight page whose frame baseline is known, so a
+// formula maps onto a cell box without any of the padding the SVG path needed.
+export async function renderMathImage(
+  content: string,
+  display: boolean,
+  color: string,
+  background: string,
+  cell: CellSize | null,
+  scale = 1,
+  compact = false,
+  standard = false,
+): Promise<MathImage | undefined> {
+  // A formula that Typst would happily accept as a truncated expression (a
+  // trailing `\frac{1}{`, say) is not a formula an author meant to typeset, so
+  // it falls back to its source rather than rendering a mis-shaped image.
+  const latex = content.trim()
+  if (!isRenderableLatex(latex)) return undefined
+  const cellWidth = cell?.width ?? 8
+  const cellHeight = cell?.height ?? 16
+  const base = cellHeight / fontSizePoints
+  // The native raster is padded to an exact whole-cell box, so the source and the
+  // cell box share an aspect ratio and `fit` draws it 1:1 instead of stretching
+  // the ink to fill the box.
+  const rendered = await renderMath({
+    latex,
+    foreground: color,
+    background,
+    scale: base * scale,
+    display,
+    cellWidth,
+    cellHeight,
+    compact,
+    standard,
+  })
+  if (!rendered) return undefined
+  const columns = Math.max(1, Math.round(rendered.pixelWidth / cellWidth))
+  const rows = Math.max(1, Math.round(rendered.pixelHeight / cellHeight))
+  const baseline = rendered.baseline / cellHeight
+  return { png: rendered.png, columns, rows, baseline, clamped: rendered.clamped }
+}

package/src/math/native.ts

@@ -0,0 +1,39 @@
+import path from "node:path"
+import { createRequire } from "node:module"
+
+type NativeModule = {
+  renderLatex(request: {
+    latex: string
+    scale?: number
+    foreground?: string
+    background?: string
+    display?: boolean
+    cellWidth?: number
+    cellHeight?: number
+    compact?: boolean
+    standard?: boolean
+  }): Promise<{
+    png: Uint8Array
+    pixelWidth: number
+    pixelHeight: number
+    baseline: number
+    clamped: boolean
+  }>
+}
+
+let loaded: Promise<NativeModule | undefined> | undefined
+
+export function loadNativeMath() {
+  loaded ??= importNativeMath()
+  return loaded
+}
+
+async function importNativeMath(): Promise<NativeModule | undefined> {
+  if (process.platform !== "linux" || process.arch !== "x64") return undefined
+  try {
+    const file = path.join(import.meta.dir, "..", "..", "prebuilds", "linux-x64-gnu", "opentui_markdown_render.node")
+    return createRequire(import.meta.url)(file) as NativeModule
+  } catch {
+    return undefined
+  }
+}