opentui-markdown-render 0.0.0-stage → 0.2.0

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,107 @@
+export { MarkdownRenderer, resolveRendererTheme, loadRendererConfig, type MarkdownRendererProps, type MarkdownRendererCommonProps, type MarkdownDiagnostic, type ThemeModeSetting } from "./app"
+export { cliUsage, parseCliArgs, type CliCommand } from "./cli"
+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,
+  xdgConfigFilenames,
+  xdgConfigDirectory,
+  resolveConfiguredTheme,
+  resolveConfiguredLayout,
+  statusLineFields,
+  isStatusLineField,
+  statusLineStyles,
+  isStatusLineStyle,
+  type MarkdownConfig,
+  type StatusLineConfig,
+  type StatusLineField,
+  type StatusLineBorder,
+  type StatusLineStyle,
+  type ImagesConfig,
+  type MermaidConfig,
+  type ThemeConfig,
+  type HeadingsConfig,
+  type HeadingLevelConfig,
+  type HeadingLevelKey,
+  type ConfigReporter,
+  type ConfigEnvironment,
+  type ThemeRuntime,
+  type LayoutRuntime,
+} from "./config"
+export {
+  defaultTheme,
+  loadTheme,
+  bundledThemeNames,
+  themeFileNames,
+  generateSyntax,
+  resolveTheme,
+  mergeTheme,
+  deriveStatusLineTheme,
+  mixColors,
+  type Theme,
+  type ThemeMode,
+  type ThemePreset,
+  type ThemeOverride,
+  type ThemeEnvironment,
+  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
+  }
+}

package/src/math/renderer.ts

@@ -0,0 +1,84 @@
+import { loadNativeMath } from "./native"
+
+export type RenderedMath = {
+  readonly png: Uint8Array
+  readonly pixelWidth: number
+  readonly pixelHeight: 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 type MathRenderRequest = {
+  readonly latex: string
+  readonly scale?: number
+  readonly enabled?: boolean
+  readonly foreground?: string
+  readonly background?: string
+  readonly display?: boolean
+  readonly cellWidth?: number
+  readonly cellHeight?: number
+  readonly compact?: boolean
+  // Keep the standard text size instead of scaling the formula down to the
+  // single text row it shares with the prose around it.
+  readonly standard?: boolean
+}
+
+const limit = 128
+const cache = new Map<string, Promise<RenderedMath | undefined>>()
+
+// A rejected render is intentionally a hole: callers keep the exact LaTeX
+// source in the layout instead of replacing it with an approximation.
+export function renderMath(request: MathRenderRequest) {
+  if (request.enabled === false) return Promise.resolve(undefined)
+  const scale = request.scale ?? 2
+  const display = request.display ?? false
+  const cellWidth = request.cellWidth ?? 8
+  const cellHeight = request.cellHeight ?? 16
+  const compact = request.compact ?? false
+  const standard = request.standard ?? false
+  const key = JSON.stringify({
+    latex: request.latex,
+    scale,
+    foreground: request.foreground,
+    background: request.background,
+    display,
+    cellWidth,
+    cellHeight,
+    compact,
+    standard,
+  })
+  const cached = cache.get(key)
+  if (cached) return cached
+  const result = loadNativeMath()
+    .then(async (native) => {
+      if (!native) return undefined
+      const image = await native.renderLatex({
+        latex: request.latex,
+        scale,
+        foreground: request.foreground,
+        background: request.background,
+        display,
+        cellWidth,
+        cellHeight,
+        compact,
+        standard,
+      })
+      return {
+        png: image.png,
+        pixelWidth: image.pixelWidth,
+        pixelHeight: image.pixelHeight,
+        baseline: image.baseline,
+        clamped: image.clamped,
+      }
+    })
+    .catch(() => undefined)
+  cache.set(key, result)
+  if (cache.size > limit) cache.delete(cache.keys().next().value!)
+  return result
+}
+
+export function clearMathCache() {
+  cache.clear()
+}

package/src/math/validate.ts

@@ -0,0 +1,44 @@
+// MiTeX and Typst both accept a truncated formula and lay out whatever they can
+// parse, so an author error such as `\frac{1}{` becomes a small, wrong image
+// instead of an error. There is no structured diagnostic to key off, so this is
+// a deliberately conservative structural check: it only rejects input that is
+// unambiguously incomplete and can never be valid math.
+//
+// Only `{}` and `\left`/`\right` are treated as structural. `[]` and `()` are
+// ordinary math characters (interval notation such as `[0, 1)` is unbalanced on
+// purpose), so they are left alone.
+export function isRenderableLatex(content: string) {
+  let depth = 0
+  let left = 0
+  let right = 0
+  for (let index = 0; index < content.length; index++) {
+    const character = content[index]!
+    if (character === "\\") {
+      if (content[index + 1] === undefined) return false
+      // A backslash protects the next character (`\{`, `\}`), so it is consumed
+      // here rather than counted as a brace.
+      if (!/[A-Za-z]/.test(content[index + 1]!)) {
+        index++
+        continue
+      }
+      let cursor = index + 1
+      while (cursor < content.length && /[A-Za-z]/.test(content[cursor]!)) cursor++
+      const name = content.slice(index, cursor)
+      if (name === "\\left") left++
+      else if (name === "\\right") right++
+      index = cursor - 1
+      continue
+    }
+    if (character === "{") {
+      depth++
+      continue
+    }
+    if (character === "}") {
+      if (depth === 0) return false
+      depth--
+    }
+  }
+  // `\frac{1}{` leaves an open group; an unmatched `\left` or `\right` is the
+  // same class of error.
+  return depth === 0 && left === right
+}