opentui-markdown-render 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "opentui-markdown-render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenTUI Markdown renderer with optional native LaTeX math",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "otmd": "bin/otmd.tsx"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts"
+  },
+  "files": [
+    "src",
+    "bin",
+    "native/Cargo.toml",
+    "native/Cargo.lock",
+    "native/build.rs",
+    "native/src",
+    "prebuilds",
+    "themes",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build:native": "bun run scripts/build-native.ts",
+    "generate:examples": "bun run scripts/generate-example-assets.ts",
+    "demo": "bun --preload @opentui/solid/preload examples/app.tsx",
+    "demo:plain": "bun --preload @opentui/solid/preload examples/app.tsx plain.md",
+    "demo:tables": "bun --preload @opentui/solid/preload examples/app.tsx tables.md",
+    "demo:mermaid": "bun --preload @opentui/solid/preload examples/app.tsx mermaid.md",
+    "demo:merman-ext": "bun --preload @opentui/solid/preload examples/app.tsx merman-ext.md",
+    "demo:math": "bun --preload @opentui/solid/preload examples/app.tsx math.md",
+    "demo:images": "bun --preload @opentui/solid/preload examples/app.tsx images.md",
+    "demo:mixed": "bun --preload @opentui/solid/preload examples/app.tsx rendered.md",
+    "demo:frame": "bun --preload @opentui/solid/preload examples/app.tsx frame.md",
+    "test": "bun test --preload @opentui/solid/preload --timeout 30000",
+    "typecheck": "tsgo --noEmit",
+    "verify": "bun run build:native && bun run typecheck && bun run test && bun run verify:native",
+    "verify:native": "cargo test --manifest-path native/Cargo.toml",
+    "prepack": "bun run build:native",
+    "demo:all": "bun --preload @opentui/solid/preload examples/app.tsx all.md"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.12",
+    "@opentui/solid": ">=0.5.12",
+    "solid-js": ">=1.9.0"
+  },
+  "dependencies": {
+    "@dagrejs/dagre": "3.1.3",
+    "entities": "7.0.1",
+    "gifuct-js": "2.1.2",
+    "marked": "17.0.1",
+    "string-width": "7.2.0"
+  },
+  "devDependencies": {
+    "@opentui/core": "0.5.12",
+    "@opentui/solid": "0.5.12",
+    "@tsconfig/bun": "1.0.9",
+    "@types/bun": "1.4.0",
+    "@typescript/native-preview": "7.0.0-dev.20251207.1",
+    "solid-js": "1.9.15"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  }
+}

package/prebuilds/linux-x64-gnu/opentui_markdown_render.node

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/prebuilds/linux-x64-gnu/opentui_markdown_render.node
+size: 61904384 bytes
+sha256: cf4087e529aed7ecccc19760625ac4f3da122f9cff616d46c821a98bab8780f4

package/src/app.tsx

@@ -0,0 +1,180 @@
+import type { CliRenderer } from "@opentui/core"
+import { createMemo, createSignal } from "solid-js"
+import { useCanvasGraphics } from "./graphics"
+import { resolveHeadingStyles } from "./headings"
+import { rgbaToHex } from "./math"
+import { loadRendererConfig, resolveConfiguredTheme, resolveConfiguredLayout } from "./config"
+import type { ImagesConfig, MarkdownConfig, ThemeModeSetting } from "./config"
+import { parseDocument, type Document, type FrameConfig, type TablesConfig } from "./core"
+import { MarkdownFrame } from "./view/frame"
+import { DocumentView, type RenderUnit } from "./view/document"
+import type { Theme } from "./theme/types"
+
+export type { ThemeModeSetting } from "./config"
+export { loadRendererConfig } from "./config"
+
+// A diagnostic is a warning or a failure the host may want to show in its own
+// UI instead of the terminal's stderr.
+export type MarkdownDiagnostic = {
+  readonly level: "warning" | "error"
+  readonly message: string
+}
+
+export type MarkdownRendererCommonProps = {
+  readonly renderer: CliRenderer
+  readonly columns?: () => number
+  readonly assetBase?: () => string | undefined
+  // A host that already resolved a theme wins over the config file and default.
+  readonly theme?: Theme | (() => Theme)
+  // A ready-made configuration. It replaces the file lookup entirely.
+  readonly config?: MarkdownConfig | (() => MarkdownConfig)
+  // An explicit JSON/JSONC config path. Without one the package walks up from
+  // `cwd` looking for `opentui-markdown-render.json[c]`.
+  readonly configPath?: string
+  readonly themeMode?: ThemeModeSetting | (() => ThemeModeSetting | null | undefined)
+  readonly cwd?: string
+  // The viewer window. `enabled: false` keeps the document in the whole area.
+  readonly frame?: FrameConfig | (() => FrameConfig)
+  // Table sizing and overflow. Defaults to content-sized, horizontally
+  // scrollable tables.
+  readonly tables?: TablesConfig | (() => TablesConfig)
+  // An embedded host passes `false` so the renderer never walks the file system
+  // for a config that belongs to a standalone viewer.
+  readonly discoverConfig?: boolean
+  // Warnings and errors are reported here instead of stderr, which lets a host
+  // put them in its own UI.
+  readonly onDiagnostic?: (diagnostic: MarkdownDiagnostic) => void
+  // The host may wrap every top-level block and every item of a top-level list.
+  readonly renderUnit?: RenderUnit
+}
+
+// The renderer takes either Markdown text or a document the host already parsed.
+// A ready document skips the parser entirely.
+export type MarkdownRendererProps = MarkdownRendererCommonProps & (
+  | { readonly content: () => string; readonly document?: never }
+  | { readonly document: () => Document; readonly content?: never }
+)
+
+// Keep the public host helper, but use the same config/runtime resolution as
+// the component. Loading the file remains an optional concern of this adapter.
+// The renderer argument stays for existing callers, but its terminal theme
+// does not determine the default palette.
+export function resolveRendererTheme(
+  renderer: CliRenderer,
+  options: {
+    theme?: Theme | (() => Theme)
+    config?: MarkdownConfig
+    configPath?: string
+    themeMode?: ThemeModeSetting | null | undefined
+    cwd?: string
+  } = {},
+): Theme {
+  const host = typeof options.theme === "function" ? options.theme() : options.theme
+  if (host) return host
+  const config = options.config ?? loadRendererConfig(options.configPath, options.cwd)
+  return resolveConfiguredTheme(config, {
+    themeMode: options.themeMode,
+  })
+}
+
+export function MarkdownRenderer(props: MarkdownRendererProps) {
+  const renderer = props.renderer
+  const graphics = useCanvasGraphics(renderer)
+  const surface = () => rgbaToHex(theme().background.base)
+  // The document is laid out for the width of the area it is rendered in, not
+  // for the width of the terminal: a host that insets the document (a scroll
+  // box with padding, a sidebar, a border) leaves less room, and a line that
+  // reaches past it is cut off by the terminal. The root box measures itself,
+  // so the layout follows the host. An explicit `columns` wins over it.
+  const [measured, setMeasured] = createSignal(0)
+  // The area the host gives the viewer: the terminal is only the fallback for
+  // the first frame, before the root box has been measured.
+  const viewportWidth = () => {
+    const explicit = props.columns?.()
+    if (explicit !== undefined && explicit > 0) return Math.max(8, explicit)
+    const width = measured()
+    return Math.max(8, width > 0 ? width : renderer.terminalWidth)
+  }
+
+  const themeModeSetting = () => (typeof props.themeMode === "function" ? props.themeMode() : props.themeMode)
+  const config = createMemo<MarkdownConfig>(() => {
+    const provided = typeof props.config === "function" ? props.config() : props.config
+    if (provided) return provided
+    return loadRendererConfig(props.configPath, props.cwd, {
+      discover: props.discoverConfig,
+      report: (message) => {
+        const handler = props.onDiagnostic
+        if (handler) {
+          handler({ level: "warning", message })
+          return
+        }
+        console.warn(`[opentui-markdown-render] ${message}`)
+      },
+    })
+  })
+  const theme = createMemo<Theme>(() =>
+    resolveRendererTheme(renderer, {
+      theme: props.theme,
+      config: config(),
+      themeMode: themeModeSetting(),
+    }),
+  )
+
+  // The frame decides how much of the measured area the document gets. Every
+  // block engine reads the same `contentWidth`, so text, tables and formulas
+  // cannot disagree about where the right edge is.
+  const frameSetting = createMemo<FrameConfig | undefined>(() => {
+    const explicit = typeof props.frame === "function" ? props.frame() : props.frame
+    return explicit ?? config().frame
+  })
+  const tableSetting = createMemo<TablesConfig | undefined>(() => {
+    const explicit = typeof props.tables === "function" ? props.tables() : props.tables
+    return explicit ?? config().tables
+  })
+  const layout = createMemo(() =>
+    resolveConfiguredLayout(config(), { viewport: viewportWidth(), frame: frameSetting(), tables: tableSetting() }),
+  )
+  const frame = () => layout().frame
+  const contentWidth = () => layout().contentWidth
+  const tableOptions = () => layout().tables
+
+  const document = createMemo<Document>(() => {
+    const ready = props.document
+    if (ready) return ready()
+    const content = props.content
+    if (!content) throw new Error("MarkdownRenderer requires either a content or a document accessor")
+    return parseDocument(content())
+  })
+  // The look of the heading levels is a configuration of its own: the colours
+  // come from the theme, the attributes and the spacing from the config file.
+  const headings = createMemo(() => resolveHeadingStyles(config().headings))
+  return (
+        <box
+          width="100%"
+          flexDirection="column"
+          flexShrink={0}
+          backgroundColor={theme().background.base}
+          onSizeChange={function () {
+            const width = this.width
+            if (width !== viewportWidth()) queueMicrotask(() => setMeasured(width))
+          }}
+        >
+          <MarkdownFrame frame={frame()} theme={theme()}>
+            <DocumentView
+              document={document()}
+              columns={contentWidth()}
+              theme={theme()}
+              headings={headings()}
+              graphics={graphics}
+              surface={surface}
+              assetBase={() => props.assetBase?.()}
+              imageLimits={config().images}
+              tableOptions={tableOptions()}
+              mermaidOptions={config().mermaid}
+              onDiagnostic={props.onDiagnostic}
+              renderUnit={props.renderUnit}
+            />
+          </MarkdownFrame>
+        </box>
+  )
+}

package/src/cli.ts

@@ -0,0 +1,63 @@
+export type CliCommand =
+  | { readonly kind: "help" }
+  | { readonly kind: "version" }
+  | {
+      readonly kind: "run"
+      readonly file?: string
+      readonly configPath?: string
+      readonly discoverConfig: boolean
+    }
+
+export const cliUsage = `Usage: otmd [options] [file]
+
+Render a Markdown file in the terminal. Use - to read Markdown from stdin.
+
+Options:
+  -c, --config <path>  Load a specific JSON/JSONC config file
+      --no-config      Disable automatic config discovery
+  -h, --help           Show this help
+  -v, --version        Show the package version
+`
+
+export function parseCliArgs(args: readonly string[]): CliCommand {
+  let configPath: string | undefined
+  let discoverConfig = true
+  let file: string | undefined
+
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]!
+    if (argument === "--") {
+      if (file !== undefined || index + 1 >= args.length) throw new Error("Expected one Markdown file after --")
+      file = args[++index]
+      continue
+    }
+    if (argument === "-h" || argument === "--help") return { kind: "help" }
+    if (argument === "-v" || argument === "--version") return { kind: "version" }
+    if (argument === "--no-config") {
+      discoverConfig = false
+      continue
+    }
+    if (argument === "-") {
+      if (file !== undefined) throw new Error("Only one Markdown file can be rendered")
+      file = argument
+      continue
+    }
+    if (argument === "-c" || argument === "--config") {
+      const value = args[++index]
+      if (!value) throw new Error(`${argument} requires a path`)
+      configPath = value
+      continue
+    }
+    if (argument.startsWith("--config=")) {
+      const value = argument.slice("--config=".length)
+      if (!value) throw new Error("--config requires a path")
+      configPath = value
+      continue
+    }
+    if (argument.startsWith("-")) throw new Error(`Unknown option: ${argument}`)
+    if (file !== undefined) throw new Error("Only one Markdown file can be rendered")
+    file = argument
+  }
+
+  return { kind: "run", file, configPath, discoverConfig }
+}

package/src/config/index.ts

@@ -0,0 +1,46 @@
+export { loadConfig, loadRendererConfig, discoverConfig, parseConfig, configFilenames, xdgConfigFilenames, xdgConfigDirectory, type ConfigEnvironment, type ConfigReporter } from "./load"
+export {
+  resolveConfiguredTheme,
+  resolveConfiguredLayout,
+  type ThemeModeSetting,
+  type ThemeRuntime,
+  type LayoutRuntime,
+} from "./resolve"
+export {
+  statusLineFields,
+  isStatusLineField,
+  statusLineStyles,
+  isStatusLineStyle,
+  headingLevelKeys,
+  isHeadingLevelKey,
+} from "./types"
+export { isFrameAlign, isFrameStyle, frameAligns, frameStyles } from "../core/frame"
+export {
+  isTableWidthMode,
+  isTableOverflow,
+  isTableColumnFitter,
+  tableWidthModes,
+  tableOverflows,
+  tableColumnFitters,
+} from "../core/tables"
+export type {
+  MarkdownConfig,
+  StatusLineConfig,
+  StatusLineField,
+  StatusLineBorder,
+  StatusLineStyle,
+  ImagesConfig,
+  MermaidConfig,
+  ThemeConfig,
+  HeadingsConfig,
+  HeadingLevelConfig,
+  HeadingLevelKey,
+} from "./types"
+export type { FrameConfig, FrameAlign, FrameStyle, FrameInsets, ResolvedFrame } from "../core/frame"
+export type {
+  TablesConfig,
+  TableWidthMode,
+  TableOverflow,
+  TableColumnFitter,
+  ResolvedTableOptions,
+} from "../core/tables"