@silvery/theme 0.3.0

package/src/detect.ts

@@ -0,0 +1,263 @@
+/**
+ * Terminal palette auto-detection via OSC queries.
+ *
+ * Detects the terminal's actual colors by querying:
+ * - OSC 10: foreground (text) color
+ * - OSC 11: background color
+ * - OSC 4;0–15: ANSI 16 palette colors
+ *
+ * Then maps the detected colors to a partial ColorPalette for
+ * theme generation via createTheme() or deriveTheme().
+ *
+ * Supported by: Ghostty, Kitty, WezTerm, iTerm2, foot, Alacritty, xterm
+ * NOT supported by: tmux (blocks OSC), basic xterm, CI environments
+ */
+
+import type { ColorPalette, Theme } from "./types"
+import { deriveTheme } from "./derive"
+import { nord } from "./palettes/nord"
+import { catppuccinLatte } from "./palettes/catppuccin"
+
+// silvery is an optional peer dependency — lazy-import to avoid breaking
+// standalone consumers that don't have silvery installed.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _silvery: any = null
+async function getSilvery() {
+  if (!_silvery) {
+    try {
+      const mod = "@silvery/react"
+      _silvery = await import(mod)
+    } catch {
+      throw new Error("Terminal palette detection requires '@silvery/term' to be installed")
+    }
+  }
+  return _silvery as {
+    queryBackgroundColor: (
+      write: (s: string) => void,
+      read: (ms: number) => Promise<string | null>,
+      timeout: number,
+    ) => Promise<string | null>
+    queryForegroundColor: (
+      write: (s: string) => void,
+      read: (ms: number) => Promise<string | null>,
+      timeout: number,
+    ) => Promise<string | null>
+    queryMultiplePaletteColors: (indices: number[], write: (s: string) => void) => void
+    parsePaletteResponse: (chunk: string) => { index: number; color: string } | null
+  }
+}
+
+/** Result of terminal palette detection. */
+export interface DetectedPalette {
+  /** Terminal foreground color (#RRGGBB), or null if undetected */
+  fg: string | null
+  /** Terminal background color (#RRGGBB), or null if undetected */
+  bg: string | null
+  /** ANSI 16 palette colors (index 0-15), null entries = undetected */
+  ansi: (string | null)[]
+  /** Whether the terminal appears to be dark mode (from bg luminance) */
+  dark: boolean
+  /** Partial ColorPalette derived from detected colors */
+  palette: Partial<ColorPalette>
+}
+
+/**
+ * Detect the terminal's color palette via OSC queries.
+ *
+ * Must be called BEFORE entering alternate screen / fullscreen mode,
+ * as some terminals don't respond to OSC in alternate screen.
+ *
+ * @param timeoutMs How long to wait for each response (default 150ms)
+ * @returns Detected palette, or null if terminal doesn't support OSC queries
+ */
+export async function detectTerminalPalette(timeoutMs = 150): Promise<DetectedPalette | null> {
+  const stdin = process.stdin
+  const stdout = process.stdout
+
+  if (!stdin.isTTY || !stdout.isTTY) return null
+
+  const wasRaw = stdin.isRaw
+  if (!wasRaw) stdin.setRawMode(true)
+
+  // Buffer for collecting responses
+  let buffer = ""
+  const onData = (chunk: Buffer) => {
+    buffer += chunk.toString()
+  }
+  stdin.on("data", onData)
+
+  try {
+    const write = (s: string) => {
+      stdout.write(s)
+    }
+
+    const read = (ms: number): Promise<string | null> =>
+      new Promise((resolve) => {
+        if (buffer.length > 0) {
+          const result = buffer
+          buffer = ""
+          resolve(result)
+          return
+        }
+
+        const timer = setTimeout(() => {
+          resolve(buffer.length > 0 ? buffer : null)
+          buffer = ""
+        }, ms)
+
+        const check = (_chunk: Buffer) => {
+          clearTimeout(timer)
+          stdin.removeListener("data", check)
+          const result = buffer
+          buffer = ""
+          resolve(result)
+        }
+        stdin.on("data", check)
+      })
+
+    const silvery = await getSilvery()
+
+    // Query bg and fg first
+    const bg = await silvery.queryBackgroundColor(write, read, timeoutMs)
+    const fg = await silvery.queryForegroundColor(write, read, timeoutMs)
+
+    // Query ANSI 16 palette
+    const ansi: (string | null)[] = new Array(16).fill(null)
+    silvery.queryMultiplePaletteColors(
+      Array.from({ length: 16 }, (_, i) => i),
+      write,
+    )
+
+    // Wait for responses
+    await new Promise((resolve) => setTimeout(resolve, timeoutMs))
+
+    // Parse any buffered palette responses
+    const remaining = buffer
+    buffer = ""
+    if (remaining) {
+      const oscPrefix = "\x1b]4;"
+      let pos = 0
+      while (pos < remaining.length) {
+        const nextOsc = remaining.indexOf(oscPrefix, pos)
+        if (nextOsc === -1) break
+
+        let end = remaining.indexOf("\x07", nextOsc)
+        if (end === -1) end = remaining.indexOf("\x1b\\", nextOsc)
+        if (end === -1) break
+
+        const chunk = remaining.slice(nextOsc, end + 1)
+        const parsed = silvery.parsePaletteResponse(chunk)
+        if (parsed && parsed.index >= 0 && parsed.index < 16) {
+          ansi[parsed.index] = parsed.color
+        }
+        pos = end + 1
+      }
+    }
+
+    // Determine dark/light from bg
+    const dark = bg ? isDarkColor(bg) : true
+
+    // Build partial ColorPalette from detected colors
+    const palette: Partial<ColorPalette> = { dark }
+
+    if (bg) palette.background = bg
+    if (fg) palette.foreground = fg
+
+    // Map ANSI 16 indices to ColorPalette fields
+    const ansiFields: (keyof ColorPalette)[] = [
+      "black",
+      "red",
+      "green",
+      "yellow",
+      "blue",
+      "magenta",
+      "cyan",
+      "white",
+      "brightBlack",
+      "brightRed",
+      "brightGreen",
+      "brightYellow",
+      "brightBlue",
+      "brightMagenta",
+      "brightCyan",
+      "brightWhite",
+    ]
+    for (let i = 0; i < 16; i++) {
+      if (ansi[i]) {
+        ;(palette as Record<string, string>)[ansiFields[i]!] = ansi[i]!
+      }
+    }
+
+    // Derive special colors from detected values
+    if (fg) {
+      palette.cursorColor = fg
+      palette.selectionForeground = fg
+    }
+    if (bg) {
+      palette.cursorText = bg
+    }
+    if (ansi[4]) {
+      // Selection background from blue at 30% on bg
+      palette.selectionBackground = ansi[4]
+    }
+
+    return { fg, bg, ansi, dark, palette }
+  } finally {
+    stdin.removeListener("data", onData)
+    if (!wasRaw) stdin.setRawMode(false)
+  }
+}
+
+// ============================================================================
+// detectTheme — high-level: detect terminal palette, fill gaps, derive theme
+// ============================================================================
+
+export interface DetectThemeOptions {
+  /** Fallback ColorPalette when detection fails or returns partial data.
+   * Detected colors override matching fallback fields. */
+  fallback?: ColorPalette
+  /** Timeout per OSC query in ms (default 150). */
+  timeoutMs?: number
+}
+
+/**
+ * Detect the terminal's color palette and derive a Theme.
+ *
+ * Queries the terminal via OSC, fills gaps from `fallback` palette,
+ * and runs `deriveTheme()` to produce a complete 33-token Theme.
+ *
+ * Falls back entirely to the fallback palette (or Nord dark) if
+ * detection fails (e.g., not a TTY, tmux, CI).
+ */
+export async function detectTheme(opts: DetectThemeOptions = {}): Promise<Theme> {
+  const detected = await detectTerminalPalette(opts.timeoutMs)
+  const isDark = detected?.dark ?? true
+  const fallback = opts.fallback ?? (isDark ? nord : catppuccinLatte)
+
+  if (!detected) {
+    // Detection failed entirely — use fallback
+    return deriveTheme(fallback)
+  }
+
+  // Merge: detected colors override fallback
+  const merged: ColorPalette = { ...fallback, ...stripNulls(detected.palette) }
+  return deriveTheme(merged)
+}
+
+/** Strip null/undefined values from a partial palette so they don't override fallback. */
+function stripNulls(partial: Partial<ColorPalette>): Partial<ColorPalette> {
+  const result: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(partial)) {
+    if (v != null) result[k] = v
+  }
+  return result as Partial<ColorPalette>
+}
+
+/** Check if a #RRGGBB color is dark (luminance <= 0.5). */
+function isDarkColor(hex: string): boolean {
+  const r = parseInt(hex.slice(1, 3), 16) / 255
+  const g = parseInt(hex.slice(3, 5), 16) / 255
+  const b = parseInt(hex.slice(5, 7), 16) / 255
+  const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
+  return luminance <= 0.5
+}

package/src/export/base16.ts

@@ -0,0 +1,64 @@
+/**
+ * Export ColorPalette to Base16 YAML format.
+ *
+ * Maps ColorPalette fields to base00–base0F. For fields that
+ * ColorPalette doesn't store directly (base04/base06/base07),
+ * we interpolate between neighboring values.
+ *
+ * @see https://github.com/chriskempson/base16
+ */
+
+import { blend } from "../color"
+import type { ColorPalette } from "../types"
+
+/** Strip `#` prefix from a hex color string and uppercase. */
+function stripHash(hex: string): string {
+  const bare = hex.startsWith("#") ? hex.slice(1) : hex
+  return bare.toUpperCase()
+}
+
+/**
+ * Export a ColorPalette to Base16 YAML format.
+ *
+ * Mapping:
+ *   background → base00, brightBlack → base01, selectionBackground → base02,
+ *   white → base03, (interpolated) → base04, foreground → base05,
+ *   (interpolated) → base06, (interpolated) → base07,
+ *   red → base08, brightRed → base09, yellow → base0A, green → base0B,
+ *   cyan → base0C, blue → base0D, magenta → base0E, brightMagenta → base0F.
+ */
+export function exportBase16(palette: ColorPalette): string {
+  const dark = palette.dark ?? true
+
+  // base04: between white (base03/muted fg) and foreground (base05)
+  const base04 = blend(palette.white, palette.foreground, 0.33)
+
+  // base06: light foreground — between fg and the inverse extreme
+  const base06 = dark ? blend(palette.foreground, "#FFFFFF", 0.15) : blend(palette.foreground, "#000000", 0.15)
+
+  // base07: lightest background — use black (the deepest bg extreme)
+  const base07 = palette.black
+
+  const lines = [
+    `scheme: "${palette.name ?? "exported"}"`,
+    `author: ""`,
+    `base00: "${stripHash(palette.background)}"`,
+    `base01: "${stripHash(palette.brightBlack)}"`,
+    `base02: "${stripHash(palette.selectionBackground)}"`,
+    `base03: "${stripHash(palette.white)}"`,
+    `base04: "${stripHash(base04)}"`,
+    `base05: "${stripHash(palette.foreground)}"`,
+    `base06: "${stripHash(base06)}"`,
+    `base07: "${stripHash(base07)}"`,
+    `base08: "${stripHash(palette.red)}"`,
+    `base09: "${stripHash(palette.brightRed)}"`,
+    `base0A: "${stripHash(palette.yellow)}"`,
+    `base0B: "${stripHash(palette.green)}"`,
+    `base0C: "${stripHash(palette.cyan)}"`,
+    `base0D: "${stripHash(palette.blue)}"`,
+    `base0E: "${stripHash(palette.magenta)}"`,
+    `base0F: "${stripHash(palette.brightMagenta)}"`,
+  ]
+
+  return lines.join("\n") + "\n"
+}

package/src/generate.ts

@@ -0,0 +1,79 @@
+/**
+ * ANSI 16 theme generation — derives a complete Theme from a primary color + dark/light.
+ *
+ * Uses ANSI color names (not hex) so it works on any terminal without truecolor support.
+ */
+
+import type { AnsiPrimary, Theme } from "./types"
+
+/**
+ * Generate a complete ANSI 16 theme from a primary color + dark/light preference.
+ *
+ * All token values are ANSI color names (e.g. "yellow", "blueBright").
+ */
+export function generateTheme(primary: AnsiPrimary, dark: boolean): Theme {
+  return {
+    name: `${dark ? "dark" : "light"}-${primary}`,
+
+    // ── Root pair ─────────────────────────────────────────────────
+    bg: "",
+    fg: dark ? "whiteBright" : "black",
+
+    // ── Surface pairs (base = text, *bg = background) ──────────
+    muted: dark ? "white" : "blackBright",
+    mutedbg: dark ? "black" : "white",
+    surface: dark ? "whiteBright" : "black",
+    surfacebg: dark ? "black" : "white",
+    popover: dark ? "whiteBright" : "black",
+    popoverbg: dark ? "black" : "white",
+    inverse: dark ? "black" : "whiteBright",
+    inversebg: dark ? "whiteBright" : "black",
+    cursor: "black",
+    cursorbg: primary,
+    selection: "black",
+    selectionbg: primary,
+
+    // ── Accent pairs (base = area bg, *fg = text on area) ──────
+    primary,
+    primaryfg: "black",
+    secondary: primary,
+    secondaryfg: "black",
+    accent: primary,
+    accentfg: "black",
+    error: dark ? "redBright" : "red",
+    errorfg: "black",
+    warning: primary,
+    warningfg: "black",
+    success: dark ? "greenBright" : "green",
+    successfg: "black",
+    info: dark ? "cyanBright" : "cyan",
+    infofg: "black",
+
+    // ── Standalone ───────────────────────────────────────────────
+    border: "gray",
+    inputborder: "gray",
+    focusborder: dark ? "blueBright" : "blue",
+    link: "blueBright",
+    disabledfg: "gray",
+
+    // ── Palette ──────────────────────────────────────────────────
+    palette: [
+      "black",
+      "red",
+      "green",
+      "yellow",
+      "blue",
+      "magenta",
+      "cyan",
+      "white",
+      "blackBright",
+      "redBright",
+      "greenBright",
+      "yellowBright",
+      "blueBright",
+      "magentaBright",
+      "cyanBright",
+      "whiteBright",
+    ],
+  }
+}

package/src/generators.ts

@@ -0,0 +1,255 @@
+/**
+ * Palette generators — produce a ColorPalette from various inputs.
+ *
+ * All generators return a complete ColorPalette (22 fields).
+ */
+
+import { hexToRgb, hexToHsl, hslToHex, brighten, darken, blend } from "./color"
+import { importBase16 as importBase16Internal } from "./import/base16"
+import { getPaletteByName } from "./palettes/index"
+import type { ColorPalette, HueName } from "./types"
+
+// ============================================================================
+// Luminance
+// ============================================================================
+
+function luminance(hex: string): number {
+  const rgb = hexToRgb(hex)
+  if (!rgb) return 0.5
+  return (rgb[0] + rgb[1] + rgb[2]) / (255 * 3)
+}
+
+function isDarkColor(hex: string): boolean {
+  return luminance(hex) < 0.5
+}
+
+// ============================================================================
+// Accent Generation
+// ============================================================================
+
+/** Target hues for each accent slot. */
+const targetHues: Record<HueName, number> = {
+  red: 0,
+  orange: 30,
+  yellow: 60,
+  green: 120,
+  teal: 180,
+  blue: 220,
+  purple: 280,
+  pink: 330,
+}
+
+/** Find which hue slot the primary color best matches by hue angle proximity. */
+export function assignPrimaryToSlot(primary: string): HueName {
+  const hsl = hexToHsl(primary)
+  if (!hsl) return "blue"
+  const h = hsl[0]
+  const slots: [number, number, HueName][] = [
+    [0, 15, "red"],
+    [15, 45, "orange"],
+    [45, 75, "yellow"],
+    [75, 165, "green"],
+    [165, 200, "teal"],
+    [200, 260, "blue"],
+    [260, 310, "purple"],
+    [310, 345, "pink"],
+    [345, 360, "red"],
+  ]
+  for (const [lo, hi, name] of slots) {
+    if (h >= lo && h < hi) return name
+  }
+  return "blue"
+}
+
+/** Generate 8 accent hues from a primary, placing it in its natural slot. */
+function generateAccentsFromPrimary(primary: string): Record<HueName, string> {
+  const hsl = hexToHsl(primary)
+  if (!hsl) {
+    return {
+      red: "#BF616A",
+      orange: "#D08770",
+      yellow: "#EBCB8B",
+      green: "#A3BE8C",
+      teal: "#88C0D0",
+      blue: "#5E81AC",
+      purple: "#B48EAD",
+      pink: "#D4879C",
+    }
+  }
+  const [, s, l] = hsl
+  const slot = assignPrimaryToSlot(primary)
+  const result = {} as Record<HueName, string>
+  for (const [name, targetH] of Object.entries(targetHues) as [HueName, number][]) {
+    result[name] = name === slot ? primary : hslToHex(targetH, s, l)
+  }
+  return result
+}
+
+// ============================================================================
+// fromBase16 — Base16 YAML → ColorPalette
+// ============================================================================
+
+/**
+ * Generate a ColorPalette from a Base16 YAML scheme.
+ *
+ * Maps base00–base0F to ANSI palette colors, derives special colors.
+ */
+export function fromBase16(yamlOrJson: string): ColorPalette {
+  return importBase16Internal(yamlOrJson)
+}
+
+// ============================================================================
+// fromColors — Generate full palette from 1-3 hex colors
+// ============================================================================
+
+interface FromColorsOptions {
+  /** Background color (infers dark/light). */
+  background?: string
+  /** Foreground/text color. Generated if omitted. */
+  foreground?: string
+  /** Primary accent color. Generated if omitted. */
+  primary?: string
+  /** Force dark mode. */
+  dark?: boolean
+  /** Theme name. */
+  name?: string
+}
+
+/**
+ * Generate a full ColorPalette from 1-3 hex colors.
+ *
+ * At minimum, provide `background` or `primary`. Missing colors are
+ * generated via surface ramp (from bg) and hue rotation (from primary).
+ */
+export function fromColors(opts: FromColorsOptions): ColorPalette {
+  const dark = opts.dark ?? (opts.background ? isDarkColor(opts.background) : true)
+  const step = dark ? brighten : darken
+
+  // Generate background if not provided
+  const bg = opts.background ?? (dark ? "#2E3440" : "#FFFFFF")
+  const fg = opts.foreground ?? step(bg, 0.85)
+
+  // Generate accents from primary or defaults
+  const accents = opts.primary
+    ? generateAccentsFromPrimary(opts.primary)
+    : {
+        red: "#BF616A",
+        orange: "#D08770",
+        yellow: "#EBCB8B",
+        green: "#A3BE8C",
+        teal: "#88C0D0",
+        blue: "#5E81AC",
+        purple: "#B48EAD",
+        pink: "#D4879C",
+      }
+
+  // Surface ramp for grayscale ANSI colors
+  const black = dark ? darken(bg, 0.05) : darken(bg, 0.1)
+  const white = dark ? blend(fg, bg, 0.3) : blend(bg, fg, 0.3)
+  const brightBlack = step(bg, 0.15)
+  const brightWhite = dark ? fg : brighten(fg, 0.1)
+
+  return {
+    name: opts.name ?? (dark ? "generated-dark" : "generated-light"),
+    dark,
+    black,
+    red: accents.red,
+    green: accents.green,
+    yellow: accents.yellow,
+    blue: accents.blue,
+    magenta: accents.purple,
+    cyan: accents.teal,
+    white,
+    brightBlack,
+    brightRed: accents.orange,
+    brightGreen: brighten(accents.green, 0.15),
+    brightYellow: brighten(accents.yellow, 0.15),
+    brightBlue: brighten(accents.blue, 0.15),
+    brightMagenta: accents.pink,
+    brightCyan: brighten(accents.teal, 0.15),
+    brightWhite,
+    foreground: fg,
+    background: bg,
+    cursorColor: fg,
+    cursorText: bg,
+    selectionBackground: blend(bg, accents.blue, 0.3),
+    selectionForeground: fg,
+  }
+}
+
+// ============================================================================
+// fromPreset — Look up a built-in ColorPalette by name
+// ============================================================================
+
+/**
+ * Look up a built-in palette by name.
+ *
+ * @returns The ColorPalette, or undefined if not found.
+ */
+export function fromPreset(name: string): ColorPalette | undefined {
+  return getPaletteByName(name)
+}
+
+// ============================================================================
+// ThemePalette → ColorPalette conversion (migration helper)
+// ============================================================================
+
+/** Old ThemePalette shape for migration. */
+interface OldThemePalette {
+  name: string
+  dark: boolean
+  crust: string
+  base: string
+  surface: string
+  overlay: string
+  subtext: string
+  text: string
+  red: string
+  orange: string
+  yellow: string
+  green: string
+  teal: string
+  blue: string
+  purple: string
+  pink: string
+}
+
+/**
+ * Convert an old ThemePalette to a ColorPalette.
+ *
+ * Mapping:
+ *   black = crust, red/green/yellow/blue = direct, magenta = purple,
+ *   cyan = teal, white = subtext, brightBlack = surface,
+ *   brightRed = orange, bright{green,yellow,blue,cyan} = brighten(normal),
+ *   brightMagenta = pink, brightWhite = text,
+ *   foreground = text, background = base,
+ *   cursor = text/base, selection = overlay/text.
+ */
+export function themePaletteToColorPalette(p: OldThemePalette): ColorPalette {
+  return {
+    name: p.name,
+    dark: p.dark,
+    black: p.crust,
+    red: p.red,
+    green: p.green,
+    yellow: p.yellow,
+    blue: p.blue,
+    magenta: p.purple,
+    cyan: p.teal,
+    white: p.subtext,
+    brightBlack: p.surface,
+    brightRed: p.orange,
+    brightGreen: brighten(p.green, 0.15),
+    brightYellow: brighten(p.yellow, 0.15),
+    brightBlue: brighten(p.blue, 0.15),
+    brightMagenta: p.pink,
+    brightCyan: brighten(p.teal, 0.15),
+    brightWhite: p.text,
+    foreground: p.text,
+    background: p.base,
+    cursorColor: p.text,
+    cursorText: p.base,
+    selectionBackground: p.overlay,
+    selectionForeground: p.text,
+  }
+}