opentui-markdown-render 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "opentui-markdown-render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenTUI Markdown renderer with optional native LaTeX math",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts"
+  },
+  "files": [
+    "src",
+    "native/Cargo.toml",
+    "native/Cargo.lock",
+    "native/build.rs",
+    "native/src",
+    "prebuilds",
+    "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/config/index.ts

@@ -0,0 +1,45 @@
+export { loadConfig, loadRendererConfig, discoverConfig, parseConfig, configFilenames, 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,
+  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"

package/src/config/load.ts

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+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 { validateTheme } from "./theme"
+
+export const configFilenames = ["opentui-markdown-render.jsonc", "opentui-markdown-render.json"]
+
+// 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 function discoverConfig(start: string): 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) return undefined
+    directory = parent
+  }
+}
+
+export function parseConfig(source: string, file = "config", report?: ConfigReporter): MarkdownConfig {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(stripJsonComments(source))
+  } catch (error) {
+    throw new Error(`Invalid config ${file}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  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)
+}
+
+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) ? validateTheme(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,37 @@
+import type { Theme, ThemePreset } from "../theme/types"
+import { resolveTheme } from "../theme/resolve"
+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 mode = explicit ?? config.theme?.mode ?? "light"
+  // resolveTheme normally gives override.mode precedence over mode. An explicit
+  // host setting must win over the mode in the file, including for defaults.
+  const override = explicit ? { ...config.theme, mode } : config.theme
+  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,
+  })
+}