opentui-markdown-render 0.1.0 → 0.2.0

package/README.md

@@ -77,6 +77,25 @@ Press `c` to open the configuration panel. Use Up/Down (or `j`/`k`) to select an
 
 See [Examples and demo fixtures](examples/README.md) for the complete fixture matrix and [Getting started](docs/getting-started.md) for a step-by-step walkthrough.
 
+### Install the `otmd` CLI
+
+The package also provides `otmd`, a terminal Markdown viewer. npm can install the
+package globally, but Bun is still required at runtime because the CLI executes
+TypeScript and uses the Bun native addon loader:
+
+```sh
+npm install -g opentui-markdown-render
+# or: bun add -g opentui-markdown-render
+
+otmd --version
+otmd README.md
+cat README.md | otmd -
+```
+
+Use `otmd --help` for options such as `--config` and `--no-config`. The current
+native math prebuild targets Linux x64 with glibc; other platforms keep readable
+math source when the addon is unavailable.
+
 ### Install in an OpenTUI application
 
 ```sh
@@ -85,6 +104,37 @@ bun add opentui-markdown-render @opentui/core @opentui/solid solid-js
 
 `@opentui/core`, `@opentui/solid`, and `solid-js` are peer dependencies. The package currently targets Bun 1.4+, OpenTUI 0.5.12+, and Solid 1.9+. Native prebuild coverage is currently Linux x64 with glibc.
 
+### Configuration discovery
+
+With automatic discovery enabled, the nearest project configuration wins. The
+loader checks `opentui-markdown-render.jsonc` and then
+`opentui-markdown-render.json` while walking from the current working directory
+up through its parents. If no project file exists, it checks the XDG user
+configuration directory:
+
+```text
+$XDG_CONFIG_HOME/otmd/config.jsonc  # or ~/.config when XDG_CONFIG_HOME is unset
+$XDG_CONFIG_HOME/otmd/config.json
+```
+
+Pass `--config PATH` to `otmd` or `configPath` to `MarkdownRenderer` to select a
+file explicitly. Embedded hosts can pass `discoverConfig={false}` when they own
+configuration themselves.
+
+Themes are complete JSON/JSONC files. Select a bundled theme or a user theme
+from `$XDG_CONFIG_HOME/otmd/themes` with:
+
+```jsonc
+{
+  "theme": { "name": "dark" }
+}
+```
+
+The repository includes [`themes/example.jsonc`](themes/example.jsonc), a fully
+commented template showing every theme setting. Copy it to
+`~/.config/otmd/themes/my-theme.jsonc` and select it with
+`{ "theme": { "name": "my-theme" } }`.
+
 The smallest useful component looks like this:
 
 ```tsx

package/bin/otmd.tsx

@@ -0,0 +1,99 @@
+#!/usr/bin/env bun
+import { createCliRenderer } from "@opentui/core"
+import { render } from "@opentui/solid"
+import { createSignal, onCleanup, Show } from "solid-js"
+import path from "node:path"
+import {
+  MarkdownRenderer,
+  StatusLine,
+  cliUsage,
+  loadRendererConfig,
+  parseCliArgs,
+  resolveRendererTheme,
+  useCanvasGraphics,
+} from "../src"
+
+const manifest = await Bun.file(new URL("../package.json", import.meta.url)).json() as { version: string }
+
+function fail(message: string): never {
+  console.error(`otmd: ${message}`)
+  console.error("Try 'otmd --help' for usage.")
+  process.exit(2)
+}
+
+let command
+try {
+  command = parseCliArgs(process.argv.slice(2))
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error))
+}
+
+if (command.kind === "help") {
+  process.stdout.write(cliUsage)
+  process.exit(0)
+}
+if (command.kind === "version") {
+  process.stdout.write(`${manifest.version}\n`)
+  process.exit(0)
+}
+
+const file = command.file
+const filePath = file && file !== "-" ? path.resolve(file) : undefined
+const content = file === "-"
+  ? await new Response(Bun.stdin).text()
+  : filePath
+    ? await readFile(filePath)
+    : fail("a Markdown file is required (use - to read stdin)")
+const assetBase = filePath ? path.dirname(filePath) : process.cwd()
+const config = loadRendererConfig(command.configPath, process.cwd(), { discover: command.discoverConfig })
+const renderer = await createCliRenderer({})
+
+function Otmd() {
+  const graphics = useCanvasGraphics(renderer)
+  const theme = () => resolveRendererTheme(renderer, { config, cwd: process.cwd() })
+  const [position] = createSignal("1/1")
+  const onKeypress = (key: { name?: string }) => {
+    if (key.name === "q" || key.name === "escape") {
+      renderer.destroy()
+      process.exit(0)
+    }
+  }
+  renderer.keyInput.on("keypress", onKeypress)
+  onCleanup(() => renderer.keyInput.off("keypress", onKeypress))
+  const state = () => ({
+    title: filePath ? path.basename(filePath) : "stdin",
+    protocol: graphics.protocol(),
+    cell: graphics.cell() ? `${graphics.cell()!.width}x${graphics.cell()!.height}` : undefined,
+    position: position(),
+  })
+
+  return (
+    <box width="100%" height="100%" flexDirection="column" backgroundColor={theme().background.base}>
+      <scrollbox width="100%" flexGrow={1} contentOptions={{ paddingLeft: 1, paddingRight: 1, paddingTop: 1, paddingBottom: 1 }}>
+        <MarkdownRenderer
+          content={() => content}
+          renderer={renderer}
+          assetBase={() => assetBase}
+          config={() => config}
+          cwd={process.cwd()}
+          discoverConfig={false}
+        />
+      </scrollbox>
+      <Show when={config.statusline?.enabled !== false}>
+        <StatusLine theme={theme()} state={state} fields={config.statusline?.fields} separator={config.statusline?.separator} border={config.statusline?.border} style={config.statusline?.style} highlight={config.statusline?.highlight} />
+      </Show>
+    </box>
+  )
+}
+
+await render(() => <Otmd />, renderer)
+
+async function readFile(filePath: string) {
+  const file = Bun.file(filePath)
+  if (!(await file.exists())) fail(`file not found: ${filePath}`)
+  try {
+    return await file.text()
+  } catch (error) {
+    fail(`unable to read ${filePath}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "opentui-markdown-render",
-  "version": "0.1.0",
+  "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"

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

@@ -1,4 +1,4 @@
-export { loadConfig, loadRendererConfig, discoverConfig, parseConfig, configFilenames, type ConfigReporter } from "./load"
+export { loadConfig, loadRendererConfig, discoverConfig, parseConfig, configFilenames, xdgConfigFilenames, xdgConfigDirectory, type ConfigEnvironment, type ConfigReporter } from "./load"
 export {
   resolveConfiguredTheme,
   resolveConfiguredLayout,
@@ -31,6 +31,7 @@ export type {
   StatusLineStyle,
   ImagesConfig,
   MermaidConfig,
+  ThemeConfig,
   HeadingsConfig,
   HeadingLevelConfig,
   HeadingLevelKey,

package/src/config/load.ts

@@ -1,11 +1,14 @@
 import { existsSync, readFileSync, statSync } from "node:fs"
+import os from "node:os"
 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"
+import { validateThemeConfig } from "./theme"
 
 export const configFilenames = ["opentui-markdown-render.jsonc", "opentui-markdown-render.json"]
+export const xdgConfigFilenames = ["config.jsonc", "config.json"]
+export const xdgConfigDirectory = "otmd"
 
 // Config warnings normally go to stderr. A host that embeds the renderer can
 // collect them instead and show them in its own UI.
@@ -46,7 +49,15 @@ export function loadRendererConfig(
   }
 }
 
-export function discoverConfig(start: string): string | undefined {
+export type ConfigEnvironment = {
+  readonly XDG_CONFIG_HOME?: string
+  readonly HOME?: string
+}
+
+export function discoverConfig(
+  start: string,
+  environment: ConfigEnvironment = { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME, HOME: process.env.HOME },
+): string | undefined {
   let directory = path.resolve(start)
   while (true) {
     for (const name of configFilenames) {
@@ -54,24 +65,42 @@ export function discoverConfig(start: string): string | undefined {
       if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
     }
     const parent = path.dirname(directory)
-    if (parent === directory) return undefined
+    if (parent === directory) break
     directory = parent
   }
+
+  return discoverXdgConfig(environment)
 }
 
-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)}`)
+function discoverXdgConfig(environment: ConfigEnvironment): string | undefined {
+  const configured = environment.XDG_CONFIG_HOME
+  const configHome = configured && path.isAbsolute(configured)
+    ? configured
+    : path.join(environment.HOME || os.homedir(), ".config")
+  const directory = path.join(configHome, xdgConfigDirectory)
+  for (const name of xdgConfigFilenames) {
+    const candidate = path.join(directory, name)
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
   }
+  return undefined
+}
+
+export function parseConfig(source: string, file = "config", report?: ConfigReporter): MarkdownConfig {
+  const parsed = parseJsonc(source, file)
   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)
 }
 
+export function parseJsonc(source: string, file = "config"): unknown {
+  try {
+    return JSON.parse(stripJsonComments(source))
+  } catch (error) {
+    throw new Error(`Invalid config ${file}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
 const sections = ["theme", "statusline", "images", "mermaid", "headings", "frame", "tables"] as const
 
 function validateConfig(value: Record<string, unknown>, file: string, report?: ConfigReporter): MarkdownConfig {
@@ -82,7 +111,7 @@ function validateConfig(value: Record<string, unknown>, file: string, report?: C
     }
   }
   return {
-    theme: isRecord(value.theme) ? validateTheme(value.theme, file, report) : undefined,
+    theme: isRecord(value.theme) ? validateThemeConfig(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,

package/src/config/resolve.ts

@@ -1,5 +1,6 @@
 import type { Theme, ThemePreset } from "../theme/types"
 import { resolveTheme } from "../theme/resolve"
+import { loadTheme } from "../theme/load"
 import { createDocumentLayout, type DocumentLayout, type FrameConfig, type TablesConfig } from "../core"
 import type { MarkdownConfig } from "./types"
 
@@ -15,10 +16,8 @@ export type ThemeRuntime = {
 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
+  const override = loadTheme(explicit ?? config.theme?.name ?? "light")
+  const mode = override?.mode ?? "light"
   return resolveTheme({ mode, override })
 }
 

package/src/config/theme.ts

@@ -1,4 +1,5 @@
 import type { ThemeOverride } from "../theme/types"
+import type { ThemeConfig } from "./types"
 import type { ConfigReporter } from "./load"
 
 // A JSON file only carries strings, not RGBA instances. OpenTUI accepts these
@@ -11,14 +12,15 @@ const colorNames = new Set([
   "brightblue", "brightyellow", "brightcyan", "brightmagenta", "brightwhite",
 ])
 
-type Field = "color" | "mode" | "colors" | { readonly [key: string]: Field }
+type Field = "name" | "color" | "mode" | "colors" | { readonly [key: string]: Field }
 const colors = <K extends string>(keys: readonly K[]): Record<K, Field> =>
   Object.fromEntries(keys.map((key) => [key, "color"])) as Record<K, Field>
 
 // The allowlist follows ThemeOverride, not the resolved Theme: headingLevels
 // is an internal six-colour array, while heading1..heading6 are file options.
-const themeFields: Record<string, Field> = {
+const themeFileFields: Record<string, Field> = {
   mode: "mode",
+  palette: "colors",
   accent: "color",
   categorical: "colors",
   text: {
@@ -84,5 +86,25 @@ export function validateTheme(value: Record<string, unknown>, file: string, repo
     }
     return result
   }
-  return validate(value, themeFields, "theme") as ThemeOverride
+  return validate(value, themeFileFields, "theme") as ThemeOverride
+}
+
+export function validateThemeConfig(value: Record<string, unknown>, file: string, report?: ConfigReporter): ThemeConfig {
+  const warn = (message: string) => {
+    if (report) report(message)
+    else console.warn(`[opentui-markdown-render] ${message}`)
+  }
+  const result: { name?: string } = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (key !== "name") {
+      warn(`Unknown theme option "theme.${key}" in ${file}`)
+      continue
+    }
+    if (typeof entry !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(entry)) {
+      warn(`Invalid theme option "theme.name" in ${file}`)
+      continue
+    }
+    result.name = entry
+  }
+  return result
 }

package/src/config/types.ts

@@ -1,12 +1,11 @@
 import type { FrameConfig } from "../core/frame"
 import type { TablesConfig } from "../core/tables"
-import type { ThemeOverride } from "../theme/types"
 
 // The configuration file is a plain JSON/JSONC object. Every section is
 // optional; a missing section keeps the bundled default.
 export type MarkdownConfig = {
-  // Colour scheme. Mirrors the theme override shape.
-  readonly theme?: ThemeOverride
+  // Selects a complete theme file from the bundled or XDG theme directory.
+  readonly theme?: ThemeConfig
   readonly statusline?: StatusLineConfig
   readonly images?: ImagesConfig
   readonly mermaid?: MermaidConfig
@@ -17,6 +16,10 @@ export type MarkdownConfig = {
   readonly tables?: TablesConfig
 }
 
+export type ThemeConfig = {
+  readonly name?: string
+}
+
 // The status line is a single row of labelled fields. `fields` selects and
 // orders them; a field without a value is skipped.
 export type StatusLineConfig = {

package/src/index.ts

@@ -1,4 +1,5 @@
 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 {
@@ -58,6 +59,8 @@ export {
   discoverConfig,
   parseConfig,
   configFilenames,
+  xdgConfigFilenames,
+  xdgConfigDirectory,
   resolveConfiguredTheme,
   resolveConfiguredLayout,
   statusLineFields,
@@ -71,15 +74,20 @@ export {
   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,
@@ -89,6 +97,7 @@ export {
   type ThemeMode,
   type ThemePreset,
   type ThemeOverride,
+  type ThemeEnvironment,
   type StatusLineTheme,
   type StatusLineThemeOverride,
   type MarkdownThemeOverride,

package/src/theme/index.ts

@@ -1,4 +1,6 @@
 export { defaultTheme } from "./defaults"
+export { loadTheme, bundledThemeNames, themeFileNames } from "./load"
+export type { ThemeEnvironment } from "./load"
 export { generateSyntax } from "./syntax"
 export { resolveTheme, mergeTheme, deriveStatusLineTheme } from "./resolve"
 export { mixColors } from "./colors"

package/src/theme/load.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, statSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { parseJsonc } from "../config/load"
+import { validateTheme } from "../config/theme"
+import type { ThemeOverride } from "./types"
+
+export const bundledThemeNames = ["light", "dark", "solarized-light", "solarized-dark"] as const
+export const themeFileNames = [".jsonc", ".json"] as const
+
+export type ThemeEnvironment = {
+  readonly XDG_CONFIG_HOME?: string
+  readonly HOME?: string
+}
+
+export function loadTheme(
+  name: string,
+  environment: ThemeEnvironment = { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME, HOME: process.env.HOME },
+): ThemeOverride | undefined {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) return undefined
+  const configured = environment.XDG_CONFIG_HOME
+  const configHome = configured && path.isAbsolute(configured)
+    ? configured
+    : path.join(environment.HOME || os.homedir(), ".config")
+  const directories = [
+    path.join(configHome, "otmd", "themes"),
+    path.resolve(import.meta.dir, "..", "..", "themes"),
+  ]
+  for (const directory of directories) {
+    for (const suffix of themeFileNames) {
+      const file = path.join(directory, `${name}${suffix}`)
+      if (!existsSync(file) || !statSync(file).isFile()) continue
+      const parsed = parseJsonc(readFileSync(file, "utf8"), file)
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
+      return validateTheme(parsed as Record<string, unknown>, file)
+    }
+  }
+  return undefined
+}

package/src/theme/resolve.ts

@@ -37,6 +37,7 @@ export function mergeTheme(base: Theme, override: ThemeOverride | undefined): Th
   if (!override) return base
   const color = (value: ColorInput | undefined, fallback: RGBA) => (value === undefined ? fallback : parseColor(value))
   const accent = color(override.accent, base.accent)
+  const palette = override.palette ? override.palette.map((entry) => parseColor(entry)) : base.palette
   const background = { base: color(override.background?.base, base.background.base) }
   const text = {
     base: color(override.text?.base, base.text.base),
@@ -56,10 +57,10 @@ export function mergeTheme(base: Theme, override: ThemeOverride | undefined): Th
     ),
   }
   const mode = override.mode ? (override.mode.endsWith("light") ? "light" : "dark") : base.mode
-  const derived = deriveStatusLineTheme({ mode, accent, background, text, palette: base.palette })
+  const derived = deriveStatusLineTheme({ mode, accent, background, text, palette })
   return {
     mode,
-    palette: base.palette,
+    palette,
     accent,
     categorical: override.categorical ? override.categorical.map((entry) => parseColor(entry)) : base.categorical,
     text: {

package/src/theme/types.ts

@@ -120,10 +120,11 @@ export type MarkdownThemeOverride = {
   readonly heading6?: ColorInput
 }
 
-// Host themes and the config file provide a partial, color-input override that
-// is merged over the bundled default for the selected mode.
+// Host-side theme APIs accept a partial color-input override. JSON/JSONC
+// application config selects a complete theme file by name instead.
 export type ThemeOverride = {
   readonly mode?: ThemePreset
+  readonly palette?: readonly ColorInput[]
   readonly accent?: ColorInput
   readonly categorical?: readonly ColorInput[]
   readonly text?: {

package/themes/dark.json

@@ -0,0 +1,32 @@
+{
+  "mode": "dark",
+  "accent": "#58a6ff",
+  "categorical": ["#58a6ff", "#d2a8ff", "#3fb950", "#d29922", "#f85149", "#ffa657"],
+  "text": {
+    "base": "#e6edf3",
+    "muted": "#8b949e",
+    "feedback": { "error": "#f85149", "warning": "#d29922", "success": "#3fb950", "info": "#58a6ff" },
+    "action": { "primary": { "focused": "#58a6ff" } }
+  },
+  "background": { "base": "#0d1117" },
+  "border": { "base": "#30363d" },
+  "frame": { "border": "#30363d", "title": "#8b949e" },
+  "markdown": {
+    "text": "#e6edf3", "heading": "#d2a8ff",
+    "heading1": "#58a6ff", "heading2": "#d2a8ff", "heading3": "#d2a8ff",
+    "heading4": "#8b949e", "heading5": "#8b949e", "heading6": "#8b949e",
+    "link": "#58a6ff", "linkText": "#58a6ff", "code": "#ffa657",
+    "blockQuote": "#8b949e", "emphasis": "#e6edf3", "strong": "#e6edf3",
+    "horizontalRule": "#30363d", "listItem": "#e6edf3", "listEnumeration": "#e6edf3",
+    "image": "#58a6ff", "imageText": "#58a6ff", "codeBlock": "#e6edf3"
+  },
+  "syntax": {
+    "comment": "#8b949e", "keyword": "#ff7b72", "function": "#d2a8ff",
+    "variable": "#ffa657", "string": "#a5d6ff", "number": "#79c0ff",
+    "type": "#ffa657", "operator": "#ff7b72", "punctuation": "#c9d1d9"
+  },
+  "diff": {
+    "text": { "added": "#3fb950", "removed": "#f85149", "context": "#8b949e" },
+    "background": { "added": "#12261e", "removed": "#25171c", "context": "#161b22" }
+  }
+}

package/themes/example.jsonc

@@ -0,0 +1,98 @@
+{
+  // The semantic mode controls contrast-sensitive derived colours.
+  "mode": "dark",
+
+  // Optional fixed Mermaid diagram palette. Omit it to derive diagram colours.
+  "palette": [
+    "#58a6ff", "#d2a8ff", "#3fb950", "#d29922", "#f85149", "#ffa657"
+  ],
+
+  // Main accent and the categorical colours used by diagrams and UI elements.
+  "accent": "#58a6ff",
+  "categorical": ["#58a6ff", "#d2a8ff", "#3fb950", "#d29922", "#f85149", "#ffa657"],
+
+  "text": {
+    "base": "#e6edf3",
+    "muted": "#8b949e",
+    "feedback": {
+      "error": "#f85149",
+      "warning": "#d29922",
+      "success": "#3fb950",
+      "info": "#58a6ff"
+    },
+    "action": {
+      "primary": {
+        "focused": "#58a6ff"
+      }
+    }
+  },
+
+  "background": {
+    "base": "#0d1117"
+  },
+  "border": {
+    "base": "#30363d"
+  },
+
+  // Frame and statusline are optional in the resolved API; these examples show
+  // the complete file shape and can be adjusted independently.
+  "frame": {
+    "border": "#30363d",
+    "title": "#8b949e"
+  },
+  "statusline": {
+    "background": "#161b22",
+    "foreground": "#e6edf3",
+    "title": "#58a6ff",
+    "muted": "#8b949e",
+    "border": "#58a6ff"
+  },
+
+  "markdown": {
+    "text": "#e6edf3",
+    "heading": "#d2a8ff",
+    "heading1": "#58a6ff",
+    "heading2": "#d2a8ff",
+    "heading3": "#d2a8ff",
+    "heading4": "#8b949e",
+    "heading5": "#8b949e",
+    "heading6": "#8b949e",
+    "link": "#58a6ff",
+    "linkText": "#58a6ff",
+    "code": "#ffa657",
+    "blockQuote": "#8b949e",
+    "emphasis": "#e6edf3",
+    "strong": "#e6edf3",
+    "horizontalRule": "#30363d",
+    "listItem": "#e6edf3",
+    "listEnumeration": "#e6edf3",
+    "image": "#58a6ff",
+    "imageText": "#58a6ff",
+    "codeBlock": "#e6edf3"
+  },
+
+  "syntax": {
+    "comment": "#8b949e",
+    "keyword": "#ff7b72",
+    "function": "#d2a8ff",
+    "variable": "#ffa657",
+    "string": "#a5d6ff",
+    "number": "#79c0ff",
+    "type": "#ffa657",
+    "operator": "#ff7b72",
+    "punctuation": "#c9d1d9"
+  },
+
+  "diff": {
+    "text": {
+      "added": "#3fb950",
+      "removed": "#f85149",
+      "context": "#8b949e"
+    },
+    "background": {
+      "added": "#12261e",
+      "removed": "#25171c",
+      "context": "#161b22"
+    }
+  }
+}

package/themes/light.json

@@ -0,0 +1,32 @@
+{
+  "mode": "light",
+  "accent": "#0969da",
+  "categorical": ["#0969da", "#8250df", "#1a7f37", "#9a6700", "#cf222e", "#bc4c00"],
+  "text": {
+    "base": "#1f2328",
+    "muted": "#59636e",
+    "feedback": { "error": "#cf222e", "warning": "#9a6700", "success": "#1a7f37", "info": "#0969da" },
+    "action": { "primary": { "focused": "#0969da" } }
+  },
+  "background": { "base": "#ffffff" },
+  "border": { "base": "#8c959f" },
+  "frame": { "border": "#8c959f", "title": "#59636e" },
+  "markdown": {
+    "text": "#1f2328", "heading": "#8250df",
+    "heading1": "#0969da", "heading2": "#8250df", "heading3": "#8250df",
+    "heading4": "#6f42c1", "heading5": "#3d444d", "heading6": "#3d444d",
+    "link": "#0969da", "linkText": "#0969da", "code": "#953800",
+    "blockQuote": "#59636e", "emphasis": "#1f2328", "strong": "#1f2328",
+    "horizontalRule": "#d1d9e0", "listItem": "#1f2328", "listEnumeration": "#1f2328",
+    "image": "#0969da", "imageText": "#0969da", "codeBlock": "#1f2328"
+  },
+  "syntax": {
+    "comment": "#59636e", "keyword": "#cf222e", "function": "#8250df",
+    "variable": "#1f2328", "string": "#0a3069", "number": "#0550ae",
+    "type": "#0550ae", "operator": "#0550ae", "punctuation": "#1f2328"
+  },
+  "diff": {
+    "text": { "added": "#1a7f37", "removed": "#cf222e", "context": "#59636e" },
+    "background": { "added": "#dafbe1", "removed": "#ffebe9", "context": "#f6f8fa" }
+  }
+}

package/themes/solarized-dark.json

@@ -0,0 +1,32 @@
+{
+  "mode": "dark",
+  "palette": ["#002b36", "#073642", "#586e75", "#657b83", "#839496", "#93a1a1", "#eee8d5", "#fdf6e3", "#b58900", "#cb4b16", "#dc322f", "#d33682", "#6c71c4", "#268bd2", "#2aa198", "#859900"],
+  "accent": "#268bd2",
+  "categorical": ["#268bd2", "#6c71c4", "#859900", "#b58900", "#dc322f", "#cb4b16"],
+  "text": {
+    "base": "#93a1a1", "muted": "#839496",
+    "feedback": { "error": "#dc322f", "warning": "#b58900", "success": "#859900", "info": "#268bd2" },
+    "action": { "primary": { "focused": "#268bd2" } }
+  },
+  "background": { "base": "#002b36" },
+  "border": { "base": "#586e75" },
+  "frame": { "border": "#586e75", "title": "#93a1a1" },
+  "markdown": {
+    "text": "#93a1a1", "heading": "#268bd2",
+    "heading1": "#268bd2", "heading2": "#268bd2", "heading3": "#268bd2",
+    "heading4": "#268bd2", "heading5": "#268bd2", "heading6": "#268bd2",
+    "link": "#268bd2", "linkText": "#268bd2", "code": "#cb4b16",
+    "blockQuote": "#839496", "emphasis": "#93a1a1", "strong": "#93a1a1",
+    "horizontalRule": "#586e75", "listItem": "#93a1a1", "listEnumeration": "#93a1a1",
+    "image": "#268bd2", "imageText": "#268bd2", "codeBlock": "#93a1a1"
+  },
+  "syntax": {
+    "comment": "#839496", "keyword": "#dc322f", "function": "#6c71c4",
+    "variable": "#93a1a1", "string": "#2aa198", "number": "#d33682",
+    "type": "#b58900", "operator": "#268bd2", "punctuation": "#93a1a1"
+  },
+  "diff": {
+    "text": { "added": "#859900", "removed": "#dc322f", "context": "#839496" },
+    "background": { "added": "#073642", "removed": "#073642", "context": "#073642" }
+  }
+}

package/themes/solarized-light.json

@@ -0,0 +1,32 @@
+{
+  "mode": "light",
+  "palette": ["#002b36", "#073642", "#586e75", "#657b83", "#839496", "#93a1a1", "#eee8d5", "#fdf6e3", "#b58900", "#cb4b16", "#dc322f", "#d33682", "#6c71c4", "#268bd2", "#2aa198", "#859900"],
+  "accent": "#268bd2",
+  "categorical": ["#268bd2", "#6c71c4", "#859900", "#b58900", "#dc322f", "#cb4b16"],
+  "text": {
+    "base": "#586e75", "muted": "#657b83",
+    "feedback": { "error": "#dc322f", "warning": "#b58900", "success": "#859900", "info": "#268bd2" },
+    "action": { "primary": { "focused": "#268bd2" } }
+  },
+  "background": { "base": "#fdf6e3" },
+  "border": { "base": "#657b83" },
+  "frame": { "border": "#657b83", "title": "#586e75" },
+  "markdown": {
+    "text": "#586e75", "heading": "#268bd2",
+    "heading1": "#268bd2", "heading2": "#268bd2", "heading3": "#268bd2",
+    "heading4": "#268bd2", "heading5": "#268bd2", "heading6": "#268bd2",
+    "link": "#268bd2", "linkText": "#268bd2", "code": "#cb4b16",
+    "blockQuote": "#657b83", "emphasis": "#586e75", "strong": "#586e75",
+    "horizontalRule": "#657b83", "listItem": "#586e75", "listEnumeration": "#586e75",
+    "image": "#268bd2", "imageText": "#268bd2", "codeBlock": "#586e75"
+  },
+  "syntax": {
+    "comment": "#657b83", "keyword": "#dc322f", "function": "#6c71c4",
+    "variable": "#586e75", "string": "#2aa198", "number": "#d33682",
+    "type": "#b58900", "operator": "#268bd2", "punctuation": "#586e75"
+  },
+  "diff": {
+    "text": { "added": "#859900", "removed": "#dc322f", "context": "#657b83" },
+    "background": { "added": "#eee8d5", "removed": "#eee8d5", "context": "#eee8d5" }
+  }
+}