@xp266/dshtui 0.1.0

package/src/core/paste.ts

@@ -0,0 +1,149 @@
+import { homedir } from 'node:os'
+import { statSync } from 'node:fs'
+import { fieldSlotOf, isFieldChar } from './fields.ts'
+
+export const PASTE_SUMMARY_MIN_LINES = 4
+export const PASTE_SUMMARY_MIN_CHARS = 601
+
+/**
+ * Paste is the one composer ingress without a keystroke-level guard, so every
+ * byte that cannot render predictably is dropped here: C0 controls and DEL
+ * (except the newline and tab the wrap layer understands), the C1 range, BOM
+ * leftovers from clipboard round-trips, and private-use code points. A PUA
+ * char only survives when it names a live field slot - a chip inserted by a
+ * plugin paste handler; anything else in that range is a stray sentinel that
+ * would render as a raw block glyph.
+ */
+export function sanitizePastedText(text: string): string {
+  let out = ''
+  let changed = false
+  for (const char of text) {
+    const code = char.codePointAt(0)!
+    if (code === 0x0a || code === 0x09) {
+      out += char
+      continue
+    }
+    if (code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0xfeff) {
+      changed = true
+      continue
+    }
+    if (code >= 0xe000 && code <= 0xf8ff) {
+      if (isFieldChar(char) && fieldSlotOf(char) !== undefined) {
+        out += char
+        continue
+      }
+      changed = true
+      continue
+    }
+    out += char
+  }
+  return changed ? out : text
+}
+
+export type PendingImage =
+  | { kind: 'path'; path: string }
+  | { kind: 'data'; data: Uint8Array; mediaType: string; name?: string }
+
+export type PasteSegment =
+  | { type: 'images'; paths: string[] }
+  | { type: 'text'; text: string }
+
+const IMAGE_MEDIA_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+}
+
+export function imageMediaTypeOf(path: string): string | undefined {
+  const dot = path.lastIndexOf('.')
+  if (dot < 0) return undefined
+  return IMAGE_MEDIA_TYPES[path.slice(dot).toLowerCase()]
+}
+
+function normalizePathToken(token: string): string {
+  let path = token.trim()
+  if (path.length >= 2 && ((path.startsWith('"') && path.endsWith('"')) || (path.startsWith("'") && path.endsWith("'")))) {
+    path = path.slice(1, -1)
+  }
+  if (path.startsWith('file://')) path = decodeURIComponent(path.slice('file://'.length))
+  if (path === '~') return homedir()
+  if (path.startsWith('~/')) return `${homedir()}${path.slice(1)}`
+  return path
+}
+
+/** File managers prefix dropped files with a `copy` action line. */
+function dropClipboardActionPrefix(lines: string[]): string[] {
+  if (lines.length < 2) return lines
+  const first = lines[0]!.trim()
+  if (first !== 'copy' && first !== 'cut' && first !== 'link') return lines
+  // Only strip when the remainder actually looks like dropped file paths;
+  // plain prose that merely starts with such a word must survive.
+  const rest = lines.slice(1).map(line => line.trim()).filter(line => line !== '')
+  if (rest.length === 0) return lines
+  const pathLike = rest.every(line => line.startsWith('file://') || line.startsWith('/') || line.startsWith('~/') || /^[a-zA-Z]:[\\/]/.test(line))
+  return pathLike ? lines.slice(1) : lines
+}
+
+function isImagePath(line: string): boolean {
+  const path = normalizePathToken(line)
+  if (path === '' || imageMediaTypeOf(path) === undefined) return false
+  try {
+    return statSync(path).isFile()
+  } catch {
+    // A path that does not exist (or is unreadable) is not a pasteable image.
+    return false
+  }
+}
+
+export function codePointCount(text: string): number {
+  let count = 0
+  for (let i = 0; i < text.length; i++) {
+    count += 1
+    if (text.charCodeAt(i) >= 0xd800 && text.charCodeAt(i) <= 0xdbff) i += 1
+  }
+  return count
+}
+
+export function summarizePaste(text: string): { lines: number; characters: number } | null {
+  const lines = text.split('\n').length
+  const characters = codePointCount(text)
+  if (lines >= PASTE_SUMMARY_MIN_LINES) return { lines, characters }
+  if (lines === 1 && characters >= PASTE_SUMMARY_MIN_CHARS) return { lines, characters }
+  return null
+}
+
+export function classifyPaste(raw: string): PasteSegment[] {
+  const lines = dropClipboardActionPrefix(raw.split('\n'))
+  const segments: PasteSegment[] = []
+  let textRun: string[] = []
+  const flushText = (): void => {
+    if (textRun.length === 0) return
+    const text = textRun.join('\n')
+    if (text !== '') segments.push({ type: 'text', text })
+    textRun = []
+  }
+  const pushImages = (paths: string[]): void => {
+    const last = segments[segments.length - 1]
+    if (last?.type === 'images') last.paths.push(...paths)
+    else segments.push({ type: 'images', paths })
+  }
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed !== '' && isImagePath(trimmed)) {
+      flushText()
+      pushImages([normalizePathToken(trimmed)])
+      continue
+    }
+    const tokens = trimmed.split(/\s+/).filter(token => token !== '')
+    if (tokens.length > 1 && tokens.every(isImagePath)) {
+      flushText()
+      pushImages(tokens.map(normalizePathToken))
+      continue
+    }
+    textRun.push(line)
+  }
+  flushText()
+  return segments
+}

package/src/core/segments.ts

@@ -0,0 +1,112 @@
+import { computeWrapStarts, normalizeWrapText, segmentGraphemes } from './text.ts'
+
+export interface MarkStyle {
+  color?: string
+  background?: string
+  bold?: boolean
+  italic?: boolean
+  strike?: boolean
+  underline?: boolean
+}
+
+export interface Segment {
+  text: string
+  style: MarkStyle
+}
+
+export function wrapSegments(segments: Segment[], width: number): Segment[][] {
+  if (width <= 0) return [[]]
+  const rows: Segment[][] = []
+  let clusters: string[] = []
+  let styles: MarkStyle[] = []
+  const flushLine = (): void => {
+    const starts = computeWrapStarts(clusters, width)
+    for (let r = 0; r < starts.length; r++) {
+      const from = starts[r]!
+      const to = r + 1 < starts.length ? starts[r + 1]! : clusters.length
+      if (from >= to) {
+        rows.push([])
+        continue
+      }
+      const row: Segment[] = []
+      let runText = ''
+      let runStyle = styles[from]!
+      for (let k = from; k < to; k++) {
+        const style = styles[k]!
+        if (k > from && !sameStyle(runStyle, style)) {
+          row.push({ text: runText, style: runStyle })
+          runText = ''
+          runStyle = style
+        }
+        runText += clusters[k]
+      }
+      row.push({ text: runText, style: runStyle })
+      rows.push(row)
+    }
+    clusters = []
+    styles = []
+  }
+  for (const seg of segments) {
+    const parts = normalizeWrapText(seg.text).split('\n')
+    for (let p = 0; p < parts.length; p++) {
+      if (p > 0) flushLine()
+      appendClusters(parts[p]!, seg.style, clusters, styles)
+    }
+  }
+  flushLine()
+  return rows
+}
+
+function sameStyle(a: MarkStyle, b: MarkStyle): boolean {
+  return a.color === b.color
+    && a.background === b.background
+    && a.bold === b.bold
+    && a.italic === b.italic
+    && a.strike === b.strike
+    && a.underline === b.underline
+}
+
+function appendClusters(text: string, style: MarkStyle, clusters: string[], styles: MarkStyle[]): void {
+  let ascii = true
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i)
+    if (code < 0x20 || code > 0x7e) {
+      ascii = false
+      break
+    }
+  }
+  if (ascii) {
+    for (let i = 0; i < text.length; i++) {
+      clusters.push(text[i]!)
+      styles.push(style)
+    }
+    return
+  }
+  for (const { segment } of segmentGraphemes(text)) {
+    clusters.push(segment)
+    styles.push(style)
+  }
+}
+
+export function mergeRuns(segments: Segment[]): Segment[] {
+  if (segments.length === 0) return segments
+  const out: Segment[] = []
+  for (const seg of segments) {
+    const last = out[out.length - 1]
+    if (last !== undefined && sameStyle(last.style, seg.style)) {
+      last.text += seg.text
+    } else {
+      out.push({ text: seg.text, style: seg.style })
+    }
+  }
+  return out
+}
+
+export function segmentsKey(segments: Segment[]): string {
+  let key = ''
+  for (const seg of segments) {
+    const flags = `${seg.style.bold ? 'b' : ''}${seg.style.italic ? 'i' : ''}${seg.style.strike ? 's' : ''}${seg.style.underline ? 'u' : ''}${seg.style.background ? 'g' : ''}`
+    key += `${seg.text.length}:${seg.text}\x1f${seg.style.color ?? ''}\x1e${seg.style.background ?? ''}\x1e${flags}\x1d`
+  }
+  return key
+}

package/src/core/text.ts

@@ -0,0 +1,290 @@
+import stringWidth from 'string-width'
+import { isFieldCode, fieldCodeWidth } from './fields.ts'
+
+const WIDTH_CACHE_LIMIT = 8192
+
+function cachedWidth(cache: Map<string, number>, text: string, compute: () => number): number {
+  const hit = cache.get(text)
+  if (hit !== undefined) return hit
+  const width = compute()
+  if (cache.size >= WIDTH_CACHE_LIMIT) cache.clear()
+  cache.set(text, width)
+  return width
+}
+
+const widthCache = new Map<string, number>()
+
+export function textWidth(text: string): number {
+  if (isAsciiPrintable(text)) return text.length
+  const hit = widthCache.get(text)
+  if (hit !== undefined) return hit
+  let total = 0
+  let run = ''
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i)
+    if (isFieldCode(code)) {
+      if (run !== '') {
+        total += stringWidth(run)
+        run = ''
+      }
+      total += fieldCodeWidth(code)
+      continue
+    }
+    run += text[i]
+  }
+  if (run !== '') total += stringWidth(run)
+  if (widthCache.size >= WIDTH_CACHE_LIMIT) widthCache.clear()
+  widthCache.set(text, total)
+  return total
+}
+
+function isAsciiPrintable(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i)
+    if (code < 0x20 || code > 0x7e) return false
+  }
+  return true
+}
+
+const charWidthCache = new Map<string, number>()
+
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+
+export function segmentGraphemes(text: string): Iterable<Intl.SegmentData> {
+  return graphemeSegmenter.segment(text)
+}
+
+export function charWidth(cluster: string): number {
+  if (cluster.length === 1) {
+    const code = cluster.charCodeAt(0)
+    if (code >= 0x20 && code <= 0x7e) return 1
+    if (isFieldCode(code)) return fieldCodeWidth(code)
+  }
+  return cachedWidth(charWidthCache, cluster, () => stringWidth(cluster))
+}
+
+const NO_START_CHARS = new Set<string>(
+  "!%,.:;?)]}'\"" + "。，、：；！？）］｝》〉」』】〕〗〙〛…—～·％°′″‰",
+)
+
+const NO_END_CHARS = new Set<string>(
+  "([{'\"$#@`" + "（［｛《〈「『【〔〖＄￥",
+)
+
+const BREAK_DELIM_CHARS = new Set<string>("-/\\,.;:!?)]}")
+
+function matchesAny(cluster: string, set: Set<string>): boolean {
+  for (const ch of cluster) {
+    if (set.has(ch)) return true
+  }
+  return false
+}
+
+const ASCII_NO_START = new Set<number>()
+for (const ch of "!%,.:;?)]}'\"") ASCII_NO_START.add(ch.charCodeAt(0))
+const ASCII_NO_END = new Set<number>()
+for (const ch of "([{'\"$#@`") ASCII_NO_END.add(ch.charCodeAt(0))
+
+function canBreakBefore(prev: string, cur: string): boolean {
+  if (prev.length === 1 && cur.length === 1) {
+    const pc = prev.charCodeAt(0)
+    const cc = cur.charCodeAt(0)
+    if (pc >= 0x20 && pc < 0x7f && cc >= 0x20 && cc < 0x7f) {
+      if (ASCII_NO_START.has(cc) || ASCII_NO_END.has(pc)) return false
+      if (pc === 0x20 || BREAK_DELIM_CHARS.has(prev)) return true
+      return false
+    }
+  }
+  if (matchesAny(cur, NO_START_CHARS) || matchesAny(prev, NO_END_CHARS)) return false
+  if (charWidth(prev) >= 2 || charWidth(cur) >= 2) return true
+  if (prev === ' ' || prev === '\t') return true
+  if (BREAK_DELIM_CHARS.has(prev)) return true
+  return false
+}
+
+export function computeWrapStarts(clusters: string[], width: number): number[] {
+  const total = clusters.length
+  const starts: number[] = [0]
+  let start = 0
+  let lineW = 0
+  let lastBreak = -1
+  for (let i = 0; i < total; i++) {
+    const w = charWidth(clusters[i]!)
+    if (lineW + w > width && i > start) {
+      let j: number
+      if (lastBreak > start) {
+        j = lastBreak
+      } else {
+        j = i
+        while (j > start + 1 && matchesAny(clusters[j]!, NO_START_CHARS)) j--
+        while (j > start + 1 && matchesAny(clusters[j - 1]!, NO_END_CHARS)) j--
+      }
+      starts.push(j)
+      lineW = 0
+      for (let k = j; k < i; k++) lineW += charWidth(clusters[k]!)
+      start = j
+      lastBreak = -1
+    }
+    const next = i + 1
+    if (next < total && canBreakBefore(clusters[i]!, clusters[next]!)) lastBreak = next
+    lineW += w
+  }
+  return starts
+}
+
+function pushWrapped(line: string, width: number, out: string[]): void {
+  if (line.length === 0) {
+    out.push('')
+    return
+  }
+  const clusters: string[] = []
+  for (const { segment } of segmentGraphemes(line)) clusters.push(segment)
+  const starts = computeWrapStarts(clusters, width)
+  for (let r = 0; r < starts.length; r++) {
+    const from = starts[r]!
+    const to = r + 1 < starts.length ? starts[r + 1]! : clusters.length
+    out.push(clusters.slice(from, to).join(''))
+  }
+}
+
+/**
+ * Single normalization applied before every wrap pass. Terminal rendering
+ * expands tabs and a lone carriage return rewinds the cursor, so both would
+ * make the visually rendered line wider than the width computation assumed
+ * and every later row would land on the wrong column. Both are replaced
+ * with spaces / newlines here so wrap math and rendering always agree.
+ */
+export function normalizeWrapText(text: string): string {
+  if (!text.includes('\r') && !text.includes('\t')) return text
+  return text.replace(/\r\n?/g, '\n').replace(/\t/g, '    ')
+}
+
+export function wrapLines(text: string, width: number): string[] {
+  if (width <= 0) return ['']
+  const cacheKey = `${width}\u0000${text}`
+  const hit = wrapCache.get(cacheKey)
+  if (hit !== undefined) return hit.lines
+  const lines: string[] = []
+  for (const rawLine of normalizeWrapText(text).split('\n')) {
+    pushWrapped(rawLine, width, lines)
+  }
+  evictWrapCacheIfNeeded()
+  wrapCache.set(cacheKey, { lines, bytes: text.length })
+  return lines
+}
+
+// The memo entry keeps the result lines; the key keeps the source text, so a
+// cap of ~4MB of source bounds the cache without hurting the streaming case
+// where every frame re-wraps a growing body.
+const WRAP_CACHE_MAX_BYTES = 4 * 1024 * 1024
+
+interface WrapCacheEntry {
+  lines: string[]
+  bytes: number
+}
+
+const wrapCache = new Map<string, WrapCacheEntry>()
+let wrapCacheBytes = 0
+
+function evictWrapCacheIfNeeded(): void {
+  while (wrapCache.size > 0 && wrapCacheBytes >= WRAP_CACHE_MAX_BYTES) {
+    const oldest = wrapCache.keys().next()
+    if (oldest.done) return
+    const entry = wrapCache.get(oldest.value)
+    if (entry !== undefined) wrapCacheBytes -= entry.bytes
+    wrapCache.delete(oldest.value)
+  }
+}
+
+export interface LineBreak {
+  start: number
+  end: number
+}
+
+function pushWrappedOffsets(line: string, width: number, base: number, out: LineBreak[]): void {
+  if (line.length === 0) {
+    out.push({ start: base, end: base })
+    return
+  }
+  const clusters: string[] = []
+  const offsets: number[] = []
+  for (const { segment, index } of segmentGraphemes(line)) {
+    clusters.push(segment)
+    offsets.push(index)
+  }
+  const starts = computeWrapStarts(clusters, width)
+  for (let r = 0; r < starts.length; r++) {
+    const from = starts[r]!
+    const to = r + 1 < starts.length ? offsets[starts[r + 1]!]! : line.length
+    out.push({ start: base + offsets[from]!, end: base + to })
+  }
+}
+
+export function lineBreaks(text: string, width: number): LineBreak[] {
+  const breaks: LineBreak[] = []
+  let start = 0
+  for (const rawLine of text.split('\n')) {
+    pushWrappedOffsets(rawLine, width, start, breaks)
+    start += rawLine.length + 1
+  }
+  return breaks
+}
+
+export interface Point {
+  row: number
+  col: number
+}
+
+export function locToPoint(text: string, width: number, index: number): Point {
+  const breaks = lineBreaks(text, width)
+  for (let row = 0; row < breaks.length; row++) {
+    const { start, end } = breaks[row]!
+    if (index < end || (index === end && row < breaks.length - 1 && breaks[row + 1]!.start > end)) {
+      return { row, col: textWidth(text.slice(start, index)) }
+    }
+  }
+  const last = breaks[breaks.length - 1]!
+  return { row: breaks.length - 1, col: textWidth(text.slice(last.start, last.end)) }
+}
+
+export function colToCharIndex(line: string, col: number): number {
+  let width = 0
+  for (const { segment, index } of segmentGraphemes(line)) {
+    if (width >= col) return index
+    width += charWidth(segment)
+  }
+  return line.length
+}
+
+export function caretScrollStart(text: string, caret: number, width: number): number {
+  const clamped = Math.min(Math.max(0, caret), text.length)
+  const caretCol = textWidth(text.slice(0, clamped))
+  if (caretCol <= width) return 0
+  const minPrefix = caretCol - width
+  let prefix = 0
+  for (const { segment, index } of segmentGraphemes(text)) {
+    if (index >= clamped) break
+    if (prefix >= minPrefix) return index
+    prefix += charWidth(segment)
+  }
+  return clamped
+}
+
+export function padToWidth(text: string, width: number): string {
+  const used = textWidth(text)
+  return text + ' '.repeat(Math.max(0, width - used))
+}
+
+export function truncate(text: string, width: number): string {
+  let used = 0
+  for (const { segment, index } of segmentGraphemes(text)) {
+    const w = charWidth(segment)
+    if (used + w > width) return text.slice(0, index)
+    used += w
+  }
+  return text
+}
+
+export function errorText(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause)
+}

package/src/dialog.ts

@@ -0,0 +1,11 @@
+import './runtime/prod-react.ts'
+
+export { Dialog, CloseGuardContext } from './ui/dialog/dialog.tsx'
+export type { DialogProps, DialogHandle } from './ui/dialog/dialog.tsx'
+export type { DialogRow, DialogItem, DialogFocus, TextItem } from './ui/dialog/items.ts'
+export { asTextItem } from './ui/dialog/items.ts'
+export type { DialogFooterLine } from './ui/dialog/geometry.ts'
+export { rowHeight, wrapStatusLines } from './ui/dialog/geometry.ts'
+export { registerWidget } from './ui/widgets/registry.ts'
+export { PanelSurface, panelLegend, panelAnchorRow } from './ui/panels/exports.ts'
+export type { PanelRow, PanelHint, PanelLegendOptions, PanelPointerHandle } from './ui/panels/exports.ts'

package/src/env.ts

@@ -0,0 +1,38 @@
+/**
+Every dshtui environment variable, parsed once at import.
+*/
+import { LOG_LEVELS, type LogLevel } from './log.ts'
+
+function parseLogLevel(value: string | undefined): LogLevel | undefined {
+  return (LOG_LEVELS as readonly string[]).includes(value ?? '') ? (value as LogLevel) : undefined
+}
+
+function parseBytes(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === '') return undefined
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}
+
+export const env = {
+  /** Force color level: 0 none, 1 ansi16, 2 ansi256, 3 truecolor. */
+  color: process.env.DSH_TUI_COLOR,
+  /** Render every glyph as plain ASCII. */
+  ascii: process.env.DSH_TUI_ASCII === '1',
+  /** Force background mode: 'dark' or 'light'. */
+  background: process.env.DSH_TUI_BG,
+  /** Reload theme.ts on every save (path relative to cwd, default src/theme.ts). */
+  hotTheme: process.env.DSH_TUI_HOT_THEME === '1',
+  themePath: process.env.DSH_TUI_THEME_PATH,
+  /** Mirror warnings and errors to stderr; only the exact value '1' enables it. */
+  debug: process.env.DSH_TUI_DEBUG === '1',
+  /** Write diagnostics under the harness home logs directory (default: on). */
+  logFile: process.env.DSH_TUI_LOG_FILE !== '0',
+  /** Override the harness home base directory used for logs. */
+  logDir: process.env.DSH_TUI_LOG_DIR,
+  /** Minimum level written to the log file: debug | info | warn | error. */
+  logLevel: parseLogLevel(process.env.DSH_TUI_LOG_LEVEL),
+  /** Rotation cap for the log file in bytes. */
+  logMaxBytes: parseBytes(process.env.DSH_TUI_LOG_MAX_BYTES),
+  /** Exit the host process on an uncaught crash (default: record only). */
+  crashExit: process.env.DSH_TUI_CRASH_EXIT === '1',
+}

package/src/harness-home.ts

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+export const DSH_HOME_DIR_NAME = '.dsh'
+export const DSH_HOME_ENV = 'DSH_HOME'
+
+function expandHomePath(path: string): string {
+  if (path === '~') return homedir()
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(homedir(), path.slice(2))
+  return path
+}
+
+/**
+ * Resolve the DeepSeek Harness home the same way the harness does:
+ * `$DSH_HOME` when set (blank counts as unset), otherwise `~/.dsh`.
+ * Mirrors @deepseek-ai/dsh-home-paths without depending on it.
+ */
+export function resolveDshHome(env: Record<string, string | undefined> = process.env): string {
+  const fromEnv = env[DSH_HOME_ENV]
+  const selected = fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), DSH_HOME_DIR_NAME)
+  return resolve(expandHomePath(selected))
+}

package/src/hot-theme.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { replacePalettes } from './theme.ts'
+import type { Theme, ThemeMode } from './theme.ts'
+import { env } from './env.ts'
+import { bumpSurface } from './kernel/surface.ts'
+
+const REFRESH_MS = 300
+
+export interface HotThemeHandle {
+  stop(): void
+}
+
+const themeUrl = env.themePath === undefined
+  ? new URL('../src/theme.ts', import.meta.url)
+  : pathToFileURL(resolve(process.cwd(), env.themePath))
+
+export function startHotTheme(onChange: () => void): HotThemeHandle | undefined {
+  if (!env.hotTheme) return undefined
+  let lastSource = ''
+  try {
+    lastSource = readFileSync(themeUrl, 'utf8')
+  } catch {
+    console.error('dshtui: DSH_TUI_HOT_THEME is set but the theme file is missing; hot theme disabled')
+    return undefined
+  }
+  console.error('dshtui: hot theme enabled; saving the theme file applies colors live')
+  const timer = setInterval(async () => {
+    let source: string
+    try {
+      source = readFileSync(themeUrl, 'utf8')
+    } catch {
+      // The theme file vanished mid-session; keep the last applied palette.
+      return
+    }
+    if (source === lastSource) return
+    lastSource = source
+    try {
+      const fresh = (await import(`${themeUrl.href}?t=${Date.now()}`)) as {
+        palettes: Record<ThemeMode, Theme>
+      }
+      replacePalettes(fresh.palettes)
+      bumpSurface()
+      onChange()
+    } catch {
+      // The theme file is mid-edit or temporarily broken; retry on the next tick.
+    }
+  }, REFRESH_MS)
+  timer.unref()
+  return {
+    stop() {
+      clearInterval(timer)
+    },
+  }
+}