herm-tui 1.0.0-dev.1

package/src/ui/splash-art.ts

@@ -0,0 +1,123 @@
+// GENERATED by scripts/bake-splash.ts — do not edit.
+// Baked braille 9-patch frame pieces for the launch splash (herm-tji.2).
+// Source: docs/splash/frame/nine/2-*.png @ PICK.md settings.
+
+/* eslint-disable */
+
+export const FRAME = { cw: 16, ch: 8, tw: 20, tv: 8 } as const
+
+const TL = [
+  "⠀⢀⣤⠤⢄⣀⠄⢀⣠⣤⣄⡤⡄⡀⠀⠀",
+  "⠀⣜⡁⢩⣈⡂⢀⣋⣭⠉⠈⢈⣮⣻⡑⣶",
+  "⠀⢸⡖⢿⠏⣤⣶⣽⣫⢶⣢⡌⠹⣧⡏⠻",
+  "⠀⠈⡤⢒⣦⢻⣿⣿⣿⢿⣅⡇⣆⡉⠂⢀",
+  "⠁⢸⡏⠘⠋⢞⢳⣿⣿⣟⡍⡍⣤⠅⠀⢨",
+  "⠀⠤⢯⣆⣀⠙⢦⣿⡋⢀⣜⠇⣁⣒⣊⣉",
+  "⠀⢀⣷⣝⣻⣶⣶⢄⠍⠘⡁⡇⣧⣠⣤⡢",
+  "⠀⠀⠘⢎⢿⣯⠃⠁⡤⣚⡼⠀⡏⣹⣿⡩",
+]
+
+const TR = [
+  "⠀⠀⢀⢠⢠⣠⣤⣀⡀⠠⣀⡠⠤⣤⣀⠀",
+  "⣶⢊⣟⣵⡁⠁⠉⣭⣙⠀⢐⣂⡍⢈⣣⠀",
+  "⠟⢹⣼⠏⢡⣔⢶⣝⣯⣶⣤⠹⡿⢲⡇⠀",
+  "⡀⠁⢉⣰⢸⣨⡿⣿⣿⣿⡟⣴⡒⢤⠁⠀",
+  "⡅⠄⠨⣤⢩⢩⣻⣿⣿⡞⡳⠙⠃⢹⡇⠀",
+  "⣉⣑⣒⣈⠸⣣⡀⢙⣿⡴⠋⣀⣰⡽⠤⢀",
+  "⢄⣤⣄⣸⢸⢈⠃⠩⡠⣶⣶⣟⣫⣾⠂⠀",
+  "⢍⣿⢟⢹⠀⢧⣒⢤⠁⠈⣽⡿⡱⠇⠀⠀",
+]
+
+const BL = [
+  "⠀⠀⣀⣿⣿⡟⠁⠀⠻⢬⣳⠀⣇⣲⣟⢿",
+  "⠀⢐⡺⣛⡯⣭⠷⠌⢂⢀⡂⡇⡏⠙⠛⠧",
+  "⠀⠖⡼⠉⠉⢠⣰⠥⢭⠘⣛⣄⢋⣉⣉⡙",
+  "⠀⢸⡌⢀⣠⣵⣿⣿⣿⣿⣨⠃⠷⠂⠐⢍",
+  "⠀⠀⠻⠝⠿⣴⣿⣿⡿⣿⣟⣋⡏⡁⠄⠘",
+  "⠀⢸⣰⣶⣄⠻⠿⣿⣹⠰⠟⢂⢠⡟⣆⣴",
+  "⠀⢪⡉⠸⣻⠇⠀⡝⣛⢀⡀⣘⡟⡷⣫⡯",
+  "⠀⠙⠻⠪⠜⠓⠂⠈⠛⠓⠛⠙⠚⠈⠁⠀",
+]
+
+const BR = [
+  "⡿⣻⣖⣸⠀⣞⡡⠟⢀⠄⢻⣿⣿⣀⠀⠀",
+  "⠶⠛⠋⢹⢸⢐⡀⡐⠡⠾⣭⢽⣛⢗⡂⠀",
+  "⢋⣉⣉⡙⣠⣛⠃⡭⠬⣆⡄⠉⠩⢧⠲⠀",
+  "⡩⠂⠐⠾⠘⣅⣿⣿⣿⣿⣮⣄⡀⢱⡇⠀",
+  "⠃⢀⢈⢳⣙⣻⣿⣟⣿⣿⣦⠿⠫⠟⠀⠀",
+  "⣦⣰⢻⡄⡐⠻⠃⣏⣿⠿⠟⣠⣶⣆⡇⠀",
+  "⢽⣝⢯⢻⣃⢀⡀⣛⣩⠀⠸⣟⠇⢉⡕⠀",
+  "⠁⠀⠁⠓⠋⠛⠚⠛⠁⠐⠚⠣⠇⠟⠋⠀",
+]
+
+const T = [
+  "⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀",
+  "⡄⣢⣴⣶⠶⠖⠲⣌⠘⠉⠢⡛⢡⠴⠲⠶⣰⢖⢴⣤",
+  "⣾⣥⠿⠀⣠⢰⠿⢾⡐⠾⠿⢇⡳⣿⣗⠄⠀⠣⣑⣵",
+  "⢾⡟⠄⠐⢭⣍⢖⡄⠨⢻⣫⠽⡼⡿⢽⢥⡂⠄⠻⡽",
+  "⠓⡻⢶⣄⡈⠘⠭⠚⠍⢻⡉⠋⠋⠭⠃⠃⡡⣶⣟⢾",
+  "⠁⠄⠉⠉⠚⠤⠤⠬⠟⠰⠧⠊⠯⠴⠤⠓⠛⠉⠐⠢",
+  "⣛⣛⡟⣛⡛⣛⣛⢛⣛⣛⡛⣛⣛⢛⣻⣻⣟⠛⣻⢻",
+  "⣊⣉⣉⣛⣋⣙⣋⣼⣷⣥⣯⣺⣋⣵⣷⣭⣙⣑⣻⣽",
+]
+
+const B = [
+  "⣿⢿⣿⣿⢿⣿⡿⡿⣿⣿⠿⣿⢿⡿⣿⣿⡿⣿⡿⢿",
+  "⣃⣛⣈⣓⣚⣚⣃⣙⣛⣉⣛⣛⣁⣛⣙⣙⣋⣘⣉⣙",
+  "⠠⢄⢄⣀⡤⣤⠐⣠⢄⢠⡄⡤⣄⠀⡤⢄⣀⡀⢀⢀",
+  "⣱⠬⠫⠑⢁⣠⢠⡫⣡⣠⣤⣉⢅⢄⣄⠉⠻⡐⢥⣌",
+  "⢔⣈⠀⢰⡁⢶⣿⣿⣟⣿⣃⡛⠕⠍⣦⣃⡄⠂⣹⡢",
+  "⡿⢏⢄⠀⠃⣫⣿⢜⢩⣶⣦⠉⡶⣾⡖⠛⠀⣠⡛⡿",
+  "⠼⢾⠿⣵⣖⣘⠴⠃⠈⢆⢀⠀⡳⠤⣂⣲⣾⠯⠚⠏",
+  "⠀⠀⠁⠀⠀⠀⠀⠈⠉⠙⠋⠉⠁⠀⠀⠀⠀⠀⠀⠀",
+]
+
+const L = [
+  "⠀⠀⢐⢟⣾⠿⠮⠶⡷⣪⠾⠂⡗⢭⢿⢹",
+  "⠀⠀⣨⡕⠉⡡⠤⣁⡌⠪⢧⠁⡇⣰⣿⢼",
+  "⠀⠀⠹⡃⢾⣕⣷⡦⣓⡀⡉⡆⡏⣶⡣⣻",
+  "⠀⢰⡶⢬⣭⡜⣿⣿⣯⢈⢓⠁⡏⣚⡾⣿",
+  "⠀⠘⡛⢊⣙⠣⢇⢯⣿⠨⡭⡁⡧⢼⣲⣿",
+  "⠀⠀⢱⡉⢿⡇⠤⣝⡄⠀⡁⠁⡏⣶⢖⢿",
+  "⠀⠀⢰⣧⡀⠓⠓⠉⢁⣴⡍⠀⡇⠺⠽⢺",
+  "⠀⠀⠨⠺⣽⣷⣦⡴⡚⠃⢀⠀⡇⡾⣿⢹",
+]
+
+const R = [
+  "⡏⡿⡭⢺⢀⠷⢝⢾⠶⠵⠿⣷⡻⡂⠀⠀",
+  "⡧⣿⣆⢸⠀⡼⠕⢡⣀⠤⢌⠉⢪⣅⠁⠀",
+  "⣟⢜⣶⢹⢰⢉⢀⣚⢴⣾⣪⡷⢘⠏⠀⠀",
+  "⣿⢷⡛⢹⠈⡚⡁⣽⣿⣿⢣⣭⡥⢶⡆⠀",
+  "⣿⣖⡧⢼⢈⢭⠅⣿⡽⡸⡘⣋⡑⢛⠃⠀",
+  "⡿⡲⣶⢹⠈⢈⠀⢠⣫⠤⢸⡿⢉⡆⠀⠀",
+  "⡗⠯⠗⢸⠀⢩⣦⡈⠉⠚⠚⢀⣼⡆⠀⠀",
+  "⡏⣿⢯⢸⠀⢀⠘⢓⢦⢶⣾⣯⠗⠅⠀⠀",
+]
+
+export type Inner = { x: number; y: number; w: number; h: number }
+
+/** Assemble the frame at terminal size. Returns the full row list plus
+ *  the inner text window (where wordmark + info + prompt go). Rows are
+ *  exactly `w` grapheme-columns wide. Returns no frame below minimum. */
+export function frame(w: number, h: number): { lines: string[]; inner: Inner } {
+  const { cw, ch, tw, tv } = FRAME
+  const mw = w - 2 * cw
+  const mh = h - 2 * ch
+  const inner: Inner = { x: cw, y: ch, w: Math.max(0, mw), h: Math.max(0, mh) }
+  if (mw < 4 || mh < 2) return { lines: [], inner }
+
+  const repH = (p: string[], span: number) =>
+    p.map(l => l.repeat(Math.ceil(span / tw)).slice(0, span))
+  const repV = (p: string[], span: number) =>
+    Array.from({ length: span }, (_, i) => p[i % tv])
+
+  const t = repH(T, mw), b = repH(B, mw)
+  const l = repV(L, mh), r = repV(R, mh)
+  const mid = " ".repeat(mw)
+
+  const out: string[] = []
+  for (let i = 0; i < ch; i++) out.push(TL[i] + t[i] + TR[i])
+  for (let i = 0; i < mh; i++) out.push(l[i] + mid + r[i])
+  for (let i = 0; i < ch; i++) out.push(BL[i] + b[i] + BR[i])
+  return { lines: out, inner }
+}

package/src/ui/table.tsx

@@ -0,0 +1,117 @@
+import { useRef, useEffect, type ReactNode } from "react"
+import type { RGBA } from "@opentui/core"
+import { useTheme } from "../theme"
+import * as prefs from "../utils/preferences"
+
+// Flex-cell column primitive for list tabs. Replaces the .padEnd(N)
+// single-<text> pattern that bleeds whenever a value exceeds its pad
+// width or the terminal narrows. A Col is either fixed-width-clipped
+// (w) or grow-truncated (grow); height=1 + overflow=hidden guarantees
+// single-line, so the worst case is an ellipsis-free cut, never a
+// shove into the neighbouring column.
+
+// Scrollbox v-bar steals 1 col from body rows. Headers that sit
+// outside the scrollbox pad by the same so the grow column lands on
+// identical x in both. Requires the scrollbox to force its v-bar
+// visible (auto-hide would make the gutter conditional → post-layout
+// feedback loop).
+export const VBAR_W = 1
+
+// Stable prop for list scrollboxes so `updateProperties`' `!==`
+// check doesn't re-set the scrollbar config on every host reconcile.
+// Inline `{{ visible: true }}` is a new object each render → every
+// reconcile triggers `setProperty → requestRender()` for nothing.
+export const VBAR = { visible: true } as const
+
+export const Col = (p: {
+  /** Fixed width in cells. Mutually exclusive with `grow`. */
+  w?: number
+  /** Take remaining width; truncates under narrow terminals. */
+  grow?: boolean
+  /** Floor for a grow column (default 12). Ignored when `w` is set. */
+  min?: number
+  right?: boolean
+  fg?: RGBA
+  bold?: boolean
+  children: string
+}) => {
+  const theme = useTheme().theme
+  const fg = p.fg ?? theme.text
+  return (
+    <box width={p.w} flexGrow={p.grow ? 1 : 0} flexShrink={p.grow ? 1 : 0}
+         minWidth={p.grow ? (p.min ?? 12) : p.w} height={1} overflow="hidden"
+         flexDirection="row" justifyContent={p.right ? "flex-end" : "flex-start"}>
+      <text>{p.bold
+        ? <span fg={fg}><strong>{p.children}</strong></span>
+        : <span fg={fg}>{p.children}</span>}</text>
+    </box>
+  )
+}
+
+// Header row container. paddingRight mirrors the body scrollbox's
+// v-bar so header and data Cols share available width.
+export const Hdr = (p: { children: ReactNode }) => (
+  <box flexDirection="row" height={1} paddingRight={VBAR_W}>
+    {p.children}
+  </box>
+)
+
+// A Col that horizontal-scrolls its text while active. The box still
+// truncates via overflow; the string is just rotated each tick so the
+// clipped slice advances. Only animates when the full text doesn't
+// fit (measured post-layout from the renderable's width), so
+// non-truncated cells and unselected rows don't tick.
+export const Marquee = (p: {
+  w?: number; grow?: boolean; min?: number
+  fg?: RGBA; bold?: boolean
+  active: boolean
+  /** ms per character step (default 180). */
+  speed?: number
+  /** ms to sit still before scrolling starts (default 600). */
+  hold?: number
+  children: string
+}) => {
+  const theme = useTheme().theme
+  const fg = p.fg ?? theme.text
+  const text = p.children
+  const box = useRef<import("@opentui/core").BoxRenderable | null>(null)
+  const node = useRef<import("@opentui/core").TextRenderable | null>(null)
+
+  const animate = prefs.get("animations") !== false && p.active
+  useEffect(() => {
+    const tn = node.current
+    if (!tn) return
+    if (!animate) { tn.scrollX = 0; return }
+    // Hold static briefly before scrolling so the cell is readable at
+    // rest on select; also keeps frame-snapshot tests deterministic.
+    // scrollX on the TextRenderable is a direct native paint request
+    // — zero React reconciles per tick (vs ~5/s at 180ms with the
+    // previous setState(off)).
+    let id: ReturnType<typeof setInterval> | undefined
+    const period = text.length + GAP.length
+    const hold = setTimeout(() => {
+      id = setInterval(() => {
+        const w = box.current?.width ?? 0
+        if (text.length <= w) { tn.scrollX = 0; return }
+        tn.scrollX = (tn.scrollX + 1) % period
+      }, p.speed ?? 180)
+    }, p.hold ?? 600)
+    return () => {
+      clearTimeout(hold); if (id) clearInterval(id)
+      if (node.current) node.current.scrollX = 0
+    }
+  }, [animate, text, p.speed, p.hold])
+
+  // `text + GAP + text` renders once; scrollX wraps at period so the
+  // visible window always has GAP-then-head following the tail.
+  return (
+    <box ref={box}
+         width={p.w} flexGrow={p.grow ? 1 : 0} flexShrink={p.grow ? 1 : 0}
+         minWidth={p.grow ? (p.min ?? 12) : p.w} height={1} overflow="hidden">
+      <text ref={node} wrapMode="none">{p.bold
+        ? <span fg={fg}><strong>{text + GAP + text}</strong></span>
+        : <span fg={fg}>{text + GAP + text}</span>}</text>
+    </box>
+  )
+}
+const GAP = "   "

package/src/ui/ticker.tsx

@@ -0,0 +1,90 @@
+// Single-line styled text that horizontally auto-scrolls when active.
+//
+// Differs from ui/table.tsx Marquee in two ways:
+//   1. Content is a ReactNode (styled <span>s), not a plain string —
+//      the component can't slice it, so it animates the text node's
+//      native scrollX instead of rebuilding a substring each tick.
+//   2. Because scrollX is driven via ref (not React state), there's
+//      exactly one React render regardless of scroll position. At
+//      35ms/char that's 0 extra renders vs Marquee's ~28/s.
+//
+// The trade-off: no gap-and-loop. When scrollX hits maxScrollX the
+// animation reverses back to 0 (ping-pong). Cheaper than duplicating
+// the span tree to fake a seamless loop.
+
+import { useEffect, useRef, type ReactNode } from "react"
+import type { TextRenderable } from "@opentui/core"
+import * as prefs from "../utils/preferences"
+
+export const Ticker = (p: {
+  active: boolean
+  /** ms per cell (default 35 — fast). */
+  speed?: number
+  /** ms to sit still before scrolling (default 150). */
+  hold?: number
+  fg?: import("@opentui/core").RGBA
+  children: ReactNode
+}) => {
+  const ref = useRef<TextRenderable | null>(null)
+
+  const animate = prefs.get("animations") !== false && p.active
+  useEffect(() => {
+    const node = ref.current
+    if (!node) return
+    if (!animate) { node.scrollX = 0; return }
+    let dir = 1
+    let id: ReturnType<typeof setInterval> | undefined
+    const hold = setTimeout(() => {
+      id = setInterval(() => {
+        const max = node.maxScrollX
+        if (max <= 0) return
+        const next = node.scrollX + dir
+        if (next >= max) { dir = -1; node.scrollX = max; return }
+        if (next <= 0)   { dir =  1; node.scrollX = 0;   return }
+        node.scrollX = next
+      }, p.speed ?? 35)
+    }, p.hold ?? 150)
+    return () => {
+      clearTimeout(hold)
+      if (id) clearInterval(id)
+      if (ref.current) ref.current.scrollX = 0
+    }
+  }, [animate, p.speed, p.hold])
+
+  return (
+    <box flexGrow={1} flexShrink={1} minWidth={0} height={1} overflow="hidden">
+      <text ref={ref} wrapMode="none" fg={p.fg}>{p.children}</text>
+    </box>
+  )
+}
+
+// ─── Inline markdown → spans ─────────────────────────────────────────
+// Just enough for a one-line peek: **bold**, `code`, _italic_/*italic*.
+// Block syntax (headings, lists, fences) was already flattened by the
+// caller's whitespace collapse; we strip the markers we don't style.
+
+type Seg = { t: string; b?: boolean; c?: boolean; i?: boolean }
+
+// Order matters — code first so ** inside backticks stays literal.
+// Single * / _ require a non-word char (or start/end) on the outer
+// side so snake_case and a*b don't become italics.
+const RX = /(`[^`]+`)|(\*\*[^*]+\*\*)|(__[^_]+__)|((?<![\w*])\*[^*\s][^*]*\*(?![\w*]))|((?<!\w)_[^_\s][^_]*_(?!\w))/g
+
+/** Tokenize one line of collapsed markdown into styled segments. */
+export const inline = (s: string): Seg[] => {
+  const out: Seg[] = []
+  let last = 0
+  for (const m of s.matchAll(RX)) {
+    const at = m.index ?? 0
+    if (at > last) out.push({ t: s.slice(last, at) })
+    const hit = m[0]
+    if (hit.startsWith("`"))       out.push({ t: hit.slice(1, -1), c: true })
+    else if (hit.startsWith("**") || hit.startsWith("__"))
+                                   out.push({ t: hit.slice(2, -2), b: true })
+    else                           out.push({ t: hit.slice(1, -1), i: true })
+    last = at + hit.length
+  }
+  if (last < s.length) out.push({ t: s.slice(last) })
+  // Scrub residual block markers that survived the collapse.
+  return out.map(seg => seg.c ? seg : { ...seg, t: seg.t.replace(/^#{1,6}\s+/, "") })
+}

package/src/ui/toast.tsx

@@ -0,0 +1,130 @@
+/**
+ * Toast notification system — auto-dismiss messages.
+ *
+ * Usage:
+ *   <ToastProvider><App /></ToastProvider>
+ *
+ *   const toast = useToast()
+ *   toast.show({ variant: "success", message: "Done!" })
+ *   toast.error(new Error("oops"))
+ */
+
+import { createContext, useContext, useState, useCallback, useRef, useMemo, useEffect } from "react"
+import type { ReactNode } from "react"
+import { useTheme } from "../theme"
+import type { RGBA } from "@opentui/core"
+
+type ToastVariant = "info" | "error" | "warning" | "success"
+
+type ToastOptions = {
+  readonly variant: ToastVariant
+  readonly title?: string
+  readonly message: string
+  readonly duration?: number
+  /** Clickable affordance on the toast (e.g. "view" → open dialog). */
+  readonly action?: { label: string; run: () => void }
+}
+
+type ToastEntry = ToastOptions & {
+  readonly id: number
+}
+
+type ToastContext = {
+  readonly show: (opts: ToastOptions) => void
+  readonly error: (err: Error) => void
+}
+
+const Ctx = createContext<ToastContext | null>(null)
+
+const DEFAULT_DURATION = 3000
+
+export const ToastProvider = ({ children }: { children: ReactNode }) => {
+  const [items, setItems] = useState<ToastEntry[]>([])
+  const counter = useRef(0)
+  const timers = useRef(new Map<number, ReturnType<typeof setTimeout>>())
+
+  useEffect(() => () => {
+    for (const t of timers.current.values()) clearTimeout(t)
+  }, [])
+
+  const show = useCallback((opts: ToastOptions) => {
+    const id = ++counter.current
+    setItems(prev => [...prev, { ...opts, id }])
+    const dur = opts.duration ?? DEFAULT_DURATION
+    timers.current.set(id, setTimeout(() => {
+      timers.current.delete(id)
+      setItems(prev => prev.filter(t => t.id !== id))
+    }, dur))
+  }, [])
+
+  const error = useCallback((err: Error) => {
+    show({ variant: "error", title: "Error", message: err.message })
+  }, [show])
+
+  const value = useMemo<ToastContext>(() => ({ show, error }), [show, error])
+
+  return (
+    <Ctx.Provider value={value}>
+      {children}
+      {items.length > 0 ? <ToastOverlay items={items} /> : null}
+    </Ctx.Provider>
+  )
+}
+
+const ToastOverlay = ({ items }: { items: ReadonlyArray<ToastEntry> }) => {
+  const theme = useTheme().theme
+
+  const color = (variant: ToastVariant): RGBA => {
+    switch (variant) {
+      case "error": return theme.error
+      case "warning": return theme.warning
+      case "success": return theme.success
+      default: return theme.info
+    }
+  }
+
+  return (
+    <box
+      position="absolute"
+      top={2}
+      right={2}
+      flexDirection="column"
+      gap={1}
+      zIndex={200}
+      maxWidth={60}
+    >
+      {items.map(item => (
+        <box
+          key={item.id}
+          backgroundColor={theme.backgroundPanel}
+          border={["left"] as const}
+          borderStyle="single"
+          borderColor={color(item.variant)}
+          paddingLeft={1}
+          paddingRight={1}
+          flexDirection="column"
+        >
+          {item.title ? (
+            <text fg={theme.text}>
+              <strong>{item.title}</strong>
+            </text>
+          ) : null}
+          <text fg={theme.textMuted} wrapMode="word">
+            {item.message}
+          </text>
+          {item.action ? (
+            <box height={1} marginTop={0} onMouseDown={item.action.run}>
+              <text fg={color(item.variant)}><u>{item.action.label}</u></text>
+            </box>
+          ) : null}
+        </box>
+      ))}
+    </box>
+  )
+}
+
+export const useToast = (): ToastContext => {
+  const ctx = useContext(Ctx)
+  if (!ctx) throw new Error("useToast() must be inside <ToastProvider>")
+  return ctx
+}

package/src/utils/categorical.ts

@@ -0,0 +1,77 @@
+/**
+ * Categorical color ramp — golden-angle HSL walk anchored on a seed color.
+ *
+ * Used by the Context grid where N adjacent category swatches must be
+ * mutually distinguishable. Theme-semantic keys (info/accent/…) weren't
+ * designed for that; this generates the ramp at runtime so no per-theme
+ * palette is needed.
+ */
+
+import { RGBA } from "@opentui/core"
+
+/** Golden angle in degrees — maximally irrational, so successive hues spread evenly for any N. */
+const GOLDEN_ANGLE = 137.50776405003785
+
+export function luminance(c: RGBA): number {
+  return 0.299 * c.r + 0.587 * c.g + 0.114 * c.b
+}
+
+/** RGBA (0–1 floats) → [h°, s, l] with h in [0,360), s/l in [0,1]. */
+export function rgbaToHsl(c: RGBA): [number, number, number] {
+  const r = c.r, g = c.g, b = c.b
+  const max = Math.max(r, g, b), min = Math.min(r, g, b)
+  const l = (max + min) / 2
+  const d = max - min
+  if (d === 0) return [0, 0, l]
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+  let h: number
+  switch (max) {
+    case r: h = (g - b) / d + (g < b ? 6 : 0); break
+    case g: h = (b - r) / d + 2; break
+    default: h = (r - g) / d + 4
+  }
+  return [h * 60, s, l]
+}
+
+/** [h°, s, l] → RGBA (0–1 floats, alpha=1). */
+export function hslToRgba(h: number, s: number, l: number): RGBA {
+  h = ((h % 360) + 360) % 360 / 360
+  if (s === 0) return RGBA.fromValues(l, l, l, 1)
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s
+  const p = 2 * l - q
+  const ch = (t: number) => {
+    if (t < 0) t += 1
+    if (t > 1) t -= 1
+    if (t < 1 / 6) return p + (q - p) * 6 * t
+    if (t < 1 / 2) return q
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6
+    return p
+  }
+  return RGBA.fromValues(ch(h + 1 / 3), ch(h), ch(h - 1 / 3), 1)
+}
+
+/**
+ * Generate N categorical colors.
+ *
+ * Hue starts at `seed`'s hue and steps by the golden angle. Saturation and
+ * lightness are picked from `bg` luminance so swatches stay legible on both
+ * dark and light themes without per-theme tuning. Slot i is stable across
+ * calls: same id → same slot → same hue family on every theme.
+ */
+export function categorical(seed: RGBA, bg: RGBA, n: number): RGBA[] {
+  const [h0] = rgbaToHsl(seed)
+  const dark = luminance(bg) < 0.5
+  const s = dark ? 0.60 : 0.70
+  const l = dark ? 0.62 : 0.42
+  const out: RGBA[] = []
+  for (let i = 0; i < n; i++) out.push(hslToRgba(h0 + i * GOLDEN_ANGLE, s, l))
+  return out
+}
+
+/** Minimum hue separation (degrees) across N golden-angle slots. Useful for test assertions. */
+export function minHueSeparation(n: number): number {
+  const hs = Array.from({ length: n }, (_, i) => (i * GOLDEN_ANGLE) % 360).sort((a, b) => a - b)
+  let min = 360 - hs[n - 1] + hs[0]
+  for (let i = 1; i < n; i++) min = Math.min(min, hs[i] - hs[i - 1])
+  return min
+}