opentui-markdown-render 0.0.0-stage → 0.2.0

package/src/core/frame.ts

@@ -0,0 +1,144 @@
+import stringWidth from "string-width"
+
+// The frame is the chrome of the viewer: a window the document is drawn in. It
+// only ever constrains and decorates the area around the document; the document
+// itself stays anchored to the left edge of that area.
+export const frameAligns = ["left", "center", "right"] as const
+
+export type FrameAlign = (typeof frameAligns)[number]
+
+export function isFrameAlign(value: unknown): value is FrameAlign {
+  return typeof value === "string" && (frameAligns as readonly string[]).includes(value)
+}
+
+export const frameStyles = ["box", "ascii", "rounded", "heavy", "double"] as const
+
+// "box" is the bundled single-line window. "ascii" draws the same window with
+// `+ - |` for terminals and fonts where the Unicode box characters do not line
+// up. The rest are the native OpenTUI border sets.
+export type FrameStyle = (typeof frameStyles)[number]
+
+export function isFrameStyle(value: unknown): value is FrameStyle {
+  return typeof value === "string" && (frameStyles as readonly string[]).includes(value)
+}
+
+export type FrameConfig = {
+  // The frame is opt-in: without it the document uses the whole measured area,
+  // which is what an embedded host (a message bubble, a sidebar) wants.
+  readonly enabled?: boolean
+  // The width of the frame in terminal columns, border and padding included.
+  // Omitted means "as wide as the area allows".
+  readonly width?: number
+  // Where the frame sits when it is narrower than the area around it.
+  readonly align?: FrameAlign
+  readonly style?: FrameStyle
+  // Empty columns between the border and the document.
+  readonly paddingX?: number
+  // Empty rows between the border and the document.
+  readonly paddingY?: number
+  // A label carved out of the middle of the top border.
+  readonly title?: string
+  readonly titleAlign?: FrameAlign
+}
+
+export type FrameInsets = {
+  readonly left: number
+  readonly right: number
+  readonly top: number
+  readonly bottom: number
+}
+
+export type ResolvedFrame = {
+  readonly enabled: boolean
+  // The width every block of the document is laid out for. This is the single
+  // content width shared across the document.
+  readonly contentWidth: number
+  // The outer width, border and padding included.
+  readonly width: number
+  // The column the frame starts at inside the area around it.
+  readonly offsetX: number
+  readonly insets: FrameInsets
+  readonly align: FrameAlign
+  readonly style: FrameStyle
+  readonly paddingX: number
+  readonly paddingY: number
+  readonly title?: string
+  readonly titleAlign: FrameAlign
+}
+
+const borderWidth = 1
+const noInsets: FrameInsets = { left: 0, right: 0, top: 0, bottom: 0 }
+
+function whole(value: number | undefined, fallback: number) {
+  if (value === undefined) return fallback
+  if (!Number.isFinite(value)) return fallback
+  return Math.max(0, Math.floor(value))
+}
+
+function alignOffset(align: FrameAlign, available: number, width: number) {
+  if (align === "right") return Math.max(0, available - width)
+  if (align === "center") return Math.max(0, Math.floor((available - width) / 2))
+  return 0
+}
+
+// A title wider than the top border would be clipped by the terminal instead of
+// by us, so it is cut here where the layout knows the frame width.
+function fitTitle(title: string | undefined, columns: number) {
+  if (!title || columns <= 0) return undefined
+  let result = ""
+  for (const character of title) {
+    if (stringWidth(result + character) > columns) break
+    result += character
+  }
+  return result || undefined
+}
+
+// `resolveFrame` is the single place that turns the host's area width and the
+// frame configuration into the widths the renderer uses. It has no dependency on
+// OpenTUI or Solid, so a host can call it without mounting anything.
+export function resolveFrame(viewport: number, config?: FrameConfig): ResolvedFrame {
+  const available = Math.max(1, Math.floor(viewport) || 1)
+  const align = config?.align ?? "left"
+  const style = config?.style ?? "box"
+  const titleAlign = config?.titleAlign ?? "left"
+  const enabled = config?.enabled ?? false
+  if (!enabled) {
+    return {
+      enabled: false,
+      contentWidth: available,
+      width: available,
+      offsetX: 0,
+      insets: noInsets,
+      align,
+      style,
+      paddingX: 0,
+      paddingY: 0,
+      title: undefined,
+      titleAlign,
+    }
+  }
+  const paddingX = whole(config?.paddingX, 1)
+  const paddingY = whole(config?.paddingY, 0)
+  const insets: FrameInsets = {
+    left: borderWidth + paddingX,
+    right: borderWidth + paddingX,
+    top: borderWidth + paddingY,
+    bottom: borderWidth + paddingY,
+  }
+  const minWidth = insets.left + insets.right + 1
+  const width = config?.width === undefined ? available : Math.max(minWidth, Math.min(available, Math.floor(config.width)))
+  const contentWidth = Math.max(1, width - insets.left - insets.right)
+  return {
+    enabled: true,
+    contentWidth,
+    width,
+    offsetX: alignOffset(align, available, width),
+    insets,
+    align,
+    style,
+    paddingX,
+    paddingY,
+    title: fitTitle(config?.title, Math.max(0, width - borderWidth * 2 - 2)),
+    titleAlign,
+  }
+}

package/src/core/image.ts

@@ -0,0 +1,9 @@
+// Retained as a public helper for hosts validating a standalone image before
+// passing the Markdown to the renderer.
+export type MarkdownImage = { readonly alt: string; readonly href: string }
+
+export function standaloneImage(source: string): MarkdownImage | undefined {
+  const match = /^!\[([^\]]*)\]\((?:<([^>]+)>|([^\s)]+))\)\s*$/.exec(source.trim())
+  if (!match) return undefined
+  return { alt: match[1] ?? "", href: match[2] ?? match[3] ?? "" }
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+export * from "./image"
+export * from "./frame"
+export * from "./layout"
+export * from "./tables"
+export * from "./document"
+export { parseDocument } from "./parse"

package/src/core/layout.ts

@@ -0,0 +1,27 @@
+import { resolveFrame, type FrameConfig, type ResolvedFrame } from "./frame"
+import { resolveTableOptions, type ResolvedTableOptions, type TablesConfig } from "./tables"
+
+export type DocumentLayoutInput = {
+  // The width the host gives the document, in terminal columns.
+  readonly viewport: number
+  readonly frame?: FrameConfig
+  readonly tables?: TablesConfig
+}
+
+// Everything a host needs to size the document without mounting the renderer.
+// The frame width and the content width are resolved together so no block can
+// disagree about where the right edge is.
+export type DocumentLayout = {
+  readonly frame: ResolvedFrame
+  readonly contentWidth: number
+  readonly tables: ResolvedTableOptions
+}
+
+export function createDocumentLayout(input: DocumentLayoutInput): DocumentLayout {
+  const frame = resolveFrame(input.viewport, input.frame)
+  return {
+    frame,
+    contentWidth: frame.contentWidth,
+    tables: resolveTableOptions(input.tables),
+  }
+}

package/src/core/math.ts

@@ -0,0 +1,170 @@
+import type { TokenizerAndRendererExtension } from "marked"
+
+export type MathInlineToken = {
+  type: "mathInline"
+  raw: string
+  text: string
+  content: string
+  open: "$" | "\\("
+  close: "$" | "\\)"
+}
+
+export type MathDisplayToken = {
+  type: "mathDisplay"
+  raw: string
+  text: string
+  content: string
+  open: "$$" | "\\["
+  close: "$$" | "\\]"
+}
+
+export type MathToken = MathInlineToken | MathDisplayToken
+
+function isEscaped(src: string, index: number): boolean {
+  let backslashes = 0
+  let i = index - 1
+  while (i >= 0 && src[i] === "\\") {
+    backslashes++
+    i--
+  }
+  return backslashes % 2 === 1
+}
+
+function closing(src: string, delimiter: string, start: number, singleLine: boolean): number {
+  for (let index = start; index < src.length; index++) {
+    if (singleLine && src[index] === "\n") break
+    if (src.startsWith(delimiter, index) && !isEscaped(src, index)) return index
+  }
+  return -1
+}
+
+export function createMathInlineExtension(): TokenizerAndRendererExtension {
+  return {
+    name: "mathInline",
+    level: "inline",
+    start(src: string) {
+      let i = 0
+      while (i < src.length) {
+        const ch = src[i]
+        if (ch === "\\") {
+          if (src[i + 1] === "(") {
+            if (!isEscaped(src, i)) return i
+          }
+          i += 2
+          continue
+        }
+        if (ch === "$") {
+          if (src[i + 1] === "$") {
+            i += 2
+            continue
+          }
+          if (!isEscaped(src, i)) return i
+        }
+        i++
+      }
+      return
+    },
+    tokenizer(src: string) {
+      // Try \(...\)
+      if (src.startsWith("\\(")) {
+        // look for \)
+        const end = closing(src, "\\)", 2, true)
+        if (end > 2 && src.slice(2, end).indexOf("\n") === -1) {
+          const content = src.slice(2, end)
+          const raw = src.slice(0, end + 2)
+          return {
+            type: "mathInline",
+            raw,
+            text: content,
+            content,
+            open: "\\(",
+            close: "\\)",
+          }
+        }
+      }
+      // Try single $
+      if (src[0] === "$" && src[1] !== "$") {
+        // find closing $ not escaped
+        let j = 1
+        while (j < src.length) {
+          if (src[j] === "\n") break
+          if (src[j] === "$" && !isEscaped(src, j)) {
+            if (j === 1) break // empty
+            const content = src.slice(1, j)
+            const raw = src.slice(0, j + 1)
+            return {
+              type: "mathInline",
+              raw,
+              text: content,
+              content,
+              open: "$",
+              close: "$",
+            }
+          }
+          j++
+        }
+      }
+      return
+    },
+  }
+}
+
+export function createMathDisplayExtension(): TokenizerAndRendererExtension {
+  return {
+    name: "mathDisplay",
+    level: "inline",
+    start(src: string) {
+      let i = 0
+      while (i < src.length) {
+        const ch = src[i]
+        if (ch === "\\") {
+          if (src[i + 1] === "[") {
+            if (!isEscaped(src, i)) return i
+          }
+          i += 2
+          continue
+        }
+        if (ch === "$") {
+          if (src[i + 1] === "$" && !isEscaped(src, i)) return i
+        }
+        i++
+      }
+      return
+    },
+    tokenizer(src: string) {
+      // $$...$$
+      if (src.startsWith("$$")) {
+        const end = closing(src, "$$", 2, false)
+        if (end > 2) {
+          const content = src.slice(2, end)
+          const raw = src.slice(0, end + 2)
+          return {
+            type: "mathDisplay",
+            raw,
+            text: content,
+            content,
+            open: "$$",
+            close: "$$",
+          }
+        }
+      }
+      // \[...\]
+      if (src.startsWith("\\[")) {
+        const end = closing(src, "\\]", 2, false)
+        if (end > 2) {
+          const content = src.slice(2, end)
+          const raw = src.slice(0, end + 2)
+          return {
+            type: "mathDisplay",
+            raw,
+            text: content,
+            content,
+            open: "\\[",
+            close: "\\]",
+          }
+        }
+      }
+      return
+    },
+  }
+}

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",
+  }
+}