@cat-factory/app 0.302.2 → 0.303.0

package/app/utils/observability.ts

@@ -407,7 +407,7 @@ export function noFailingCallReason(evidence: RunFailureEvidence): NoFailingCall
 
 /** Tailwind text/bg colour for an output-headroom level (green → amber → red). */
 export function headroomColor(ratio: number | null, truncated: boolean): string {
-  if (truncated || (ratio != null && ratio >= 0.98)) return 'text-rose-400'
-  if (ratio != null && ratio >= 0.8) return 'text-amber-400'
-  return 'text-emerald-400'
+  if (truncated || (ratio != null && ratio >= 0.98)) return 'text-app-error-400'
+  if (ratio != null && ratio >= 0.8) return 'text-app-warning-400'
+  return 'text-app-success-400'
 }

package/app/utils/pipelineRender.ts

@@ -49,7 +49,7 @@ export type CompanionState = 'possible' | 'running' | 'completed' | 'skipped' |
  */
 export const FAILED_STEP_META = {
   label: 'Failed',
-  color: '#ef4444',
+  color: 'var(--ui-error)',
   icon: 'i-lucide-circle-x',
 } as const
 
@@ -75,32 +75,32 @@ export const COMPANION_STATE_META: Record<
 > = {
   possible: {
     label: 'May run',
-    dot: 'border-slate-600 bg-slate-800/40',
-    text: 'text-slate-400',
+    dot: 'border-app-600 bg-elevated/40',
+    text: 'text-muted',
     icon: 'i-lucide-circle-dashed',
   },
   running: {
     label: 'Running',
-    dot: 'border-amber-400 bg-amber-500/20',
-    text: 'text-amber-300',
+    dot: 'border-app-warning-400 bg-app-warning-500/20',
+    text: 'text-app-warning-300',
     icon: 'i-lucide-loader',
   },
   completed: {
     label: 'Ran',
-    dot: 'border-emerald-500 bg-emerald-500/20',
-    text: 'text-emerald-300',
+    dot: 'border-app-success-500 bg-app-success-500/20',
+    text: 'text-app-success-300',
     icon: 'i-lucide-circle-check',
   },
   skipped: {
     label: 'Skipped',
-    dot: 'border-slate-700 bg-slate-800/40',
-    text: 'text-slate-500',
+    dot: 'border-muted bg-elevated/40',
+    text: 'text-dimmed',
     icon: 'i-lucide-circle-slash',
   },
   failed: {
     label: 'Gave up',
-    dot: 'border-rose-500 bg-rose-500/20',
-    text: 'text-rose-400',
+    dot: 'border-app-error-500 bg-app-error-500/20',
+    text: 'text-app-error-400',
     icon: 'i-lucide-circle-x',
   },
 }
@@ -348,11 +348,7 @@ function describeUnhandledSkipReason(reason: never): string {
  */
 export function subtaskIconClass(status: string, runFailed: boolean): string[] {
   return [
-    status === 'in_progress'
-      ? runFailed
-        ? 'text-indigo-400'
-        : 'animate-spin text-indigo-400'
-      : '',
-    status === 'completed' ? 'text-emerald-400' : 'text-slate-500',
+    status === 'in_progress' ? (runFailed ? 'text-primary' : 'animate-spin text-primary') : '',
+    status === 'completed' ? 'text-app-success-400' : 'text-dimmed',
   ]
 }

package/app/utils/swimlanes.ts

@@ -147,25 +147,25 @@ export const LANE_META: Record<
     labelKey: 'board.lanes.notStarted.label',
     emptyKey: 'board.lanes.notStarted.empty',
     icon: 'i-lucide-circle-dashed',
-    color: '#64748b',
+    color: 'var(--ui-text-muted)',
   },
   in_progress: {
     labelKey: 'board.lanes.inProgress.label',
     emptyKey: 'board.lanes.inProgress.empty',
     icon: 'i-lucide-loader',
-    color: '#6366f1',
+    color: 'var(--ui-primary)',
   },
   needs_you: {
     labelKey: 'board.lanes.needsYou.label',
     emptyKey: 'board.lanes.needsYou.empty',
     icon: 'i-lucide-hand',
-    color: '#f59e0b',
+    color: 'var(--ui-warning)',
   },
   done: {
     labelKey: 'board.lanes.done.label',
     emptyKey: 'board.lanes.done.empty',
     icon: 'i-lucide-circle-check',
-    color: '#16a34a',
+    color: 'var(--ui-text-muted)',
   },
 }
 

package/app/utils/theme/bootPalette.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import {
+  BOOT_PALETTE_KEY,
+  readBootPalette,
+  writeBootPalette,
+  type BootPaletteEntry,
+} from '~/utils/theme/bootPalette'
+
+const dark: BootPaletteEntry = {
+  bg: 'oklch(0.129 0.042 264.695)',
+  track: 'oklch(0.279 0.041 260.031)',
+  accent: 'oklch(0.673 0.182 276.935)',
+  status: 'oklch(0.704 0.04 256.788)',
+}
+const light: BootPaletteEntry = {
+  bg: 'rgb(226, 232, 240)',
+  track: '#cbd5e1',
+  accent: 'black',
+  status: 'rgb(100, 116, 139)',
+}
+
+describe('boot palette cache', () => {
+  it('keeps one entry per colour mode under one theme', () => {
+    writeBootPalette('cat-factory', 'dark', dark)
+    writeBootPalette('cat-factory', 'light', light)
+    expect(readBootPalette()).toEqual({ theme: 'cat-factory', dark, light })
+    const darkAgain = { ...dark, accent: 'white' }
+    writeBootPalette('cat-factory', 'dark', darkAgain)
+    expect(readBootPalette()).toEqual({ theme: 'cat-factory', dark: darkAgain, light })
+  })
+
+  it("drops the other mode's entry when the theme changes, so a stale palette never dresses the shell", () => {
+    writeBootPalette('cat-factory', 'dark', dark)
+    writeBootPalette('cat-factory', 'light', light)
+    const monoDark = { ...dark, accent: 'white' }
+    writeBootPalette('mono', 'dark', monoDark)
+    expect(readBootPalette()).toEqual({ theme: 'mono', dark: monoDark })
+  })
+
+  it('drops an entry that is not a set of computed colours', () => {
+    localStorage.setItem(
+      BOOT_PALETTE_KEY,
+      JSON.stringify({
+        theme: 'x',
+        dark,
+        light: { ...light, bg: 'red; } body { display: none' },
+        other: dark,
+      }),
+    )
+    expect(readBootPalette()).toEqual({ theme: 'x', dark })
+    localStorage.setItem(BOOT_PALETTE_KEY, 'not json')
+    expect(readBootPalette()).toEqual({})
+  })
+})

package/app/utils/theme/bootPalette.ts

@@ -0,0 +1,108 @@
+/**
+ * The handful of colours the pre-JS loading shell (`spa-loading-template.html`) paints with,
+ * cached per colour mode so the FIRST frame after a reload wears the active theme instead of the
+ * default one.
+ *
+ * The shell renders before any stylesheet or the theme plugin exists, so it cannot resolve a token.
+ * What it can do is read `localStorage` from a two-line inline script. So after every theme or
+ * mode change the plugin resolves these tokens on `<html>` and writes the computed colours here,
+ * keyed by mode UNDER the active theme's id: the colour-mode script in `<head>` has already classed
+ * `<html>` when the shell paints, so the shell picks the entry for the mode it is about to show.
+ * A theme change drops the other mode's entry too (it belonged to the previous theme), so a mode
+ * never seen since the theme was picked has no entry and the shell falls back to its defaults.
+ *
+ * Values are computed colours (`oklch(...)`, `rgb(...)`), never the theme's own input, and the shell
+ * applies them through `style.setProperty`, which cannot break out of a declaration.
+ */
+
+export const BOOT_PALETTE_KEY = 'cf-boot-palette'
+
+export type ColorModeName = 'light' | 'dark'
+
+/** The shell's slots, each the token it mirrors in the running app. */
+export const BOOT_PALETTE_TOKENS = {
+  bg: '--app-bg-canvas',
+  track: '--ui-border',
+  accent: '--ui-primary',
+  status: '--ui-text-muted',
+} as const
+
+export type BootPaletteEntry = Record<keyof typeof BOOT_PALETTE_TOKENS, string>
+export type BootPalette = { theme?: string } & Partial<Record<ColorModeName, BootPaletteEntry>>
+
+// A computed colour as the browser reports it: a colour function or a hex literal.
+const COMPUTED_COLOR = /^(?:[a-z]+\([\d.%,\s/a-z-]+\)|#[0-9a-f]{3,8}|[a-z]+)$/i
+
+// A sentinel the probe's fallback lands on when a token is undefined. `color` is an INHERITED
+// property, so a bare `color: var(--missing)` is invalid at computed-value time and resolves to the
+// inherited colour (always a real `rgb(...)`), not to nothing: the guard below could never tell an
+// unresolved token from a resolved one. Giving the `var()` this fallback makes the difference
+// observable, since no theme paints a slot in it. `getComputedStyle` normalises it to this string.
+const UNRESOLVED_SENTINEL = 'rgb(1, 2, 3)' // colour-literal-ok: a probe sentinel, never a painted colour
+
+function isEntry(value: unknown): value is BootPaletteEntry {
+  if (typeof value !== 'object' || value === null) return false
+  return Object.keys(BOOT_PALETTE_TOKENS).every((slot) => {
+    const colour = (value as Record<string, unknown>)[slot]
+    return typeof colour === 'string' && COMPUTED_COLOR.test(colour)
+  })
+}
+
+/** Resolve the shell's slots against the current document, or null if any is not resolvable yet. */
+export function captureBootPalette(
+  root: Element = document.documentElement,
+): BootPaletteEntry | null {
+  const probe = document.createElement('div')
+  root.appendChild(probe)
+  try {
+    const entry: Partial<BootPaletteEntry> = {}
+    for (const [slot, token] of Object.entries(BOOT_PALETTE_TOKENS)) {
+      probe.style.color = `var(${token}, ${UNRESOLVED_SENTINEL})`
+      const computed = getComputedStyle(probe).color
+      if (computed === UNRESOLVED_SENTINEL || !COMPUTED_COLOR.test(computed)) return null
+      entry[slot as keyof BootPaletteEntry] = computed
+    }
+    return entry as BootPaletteEntry
+  } finally {
+    probe.remove()
+  }
+}
+
+export function readBootPalette(storage: Storage = localStorage): BootPalette {
+  try {
+    const parsed: unknown = JSON.parse(storage.getItem(BOOT_PALETTE_KEY) ?? '{}')
+    if (typeof parsed !== 'object' || parsed === null) return {}
+    const palette: BootPalette = {}
+    const theme = (parsed as Record<string, unknown>).theme
+    if (typeof theme === 'string') palette.theme = theme
+    for (const mode of ['light', 'dark'] as const) {
+      const entry = (parsed as Record<string, unknown>)[mode]
+      if (isEntry(entry)) palette[mode] = entry
+    }
+    return palette
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Record one mode's colours for a theme. The other mode's entry survives only if it was captured
+ * under the SAME theme; otherwise it is the previous theme's and would dress the shell wrongly the
+ * first time the OS starts the app in that mode.
+ */
+export function writeBootPalette(
+  theme: string,
+  mode: ColorModeName,
+  entry: BootPaletteEntry,
+  storage: Storage = localStorage,
+): void {
+  const previous = readBootPalette(storage)
+  const palette: BootPalette = previous.theme === theme ? previous : { theme }
+  palette.theme = theme
+  palette[mode] = entry
+  try {
+    storage.setItem(BOOT_PALETTE_KEY, JSON.stringify(palette))
+  } catch {
+    // Storage full or disabled: the shell keeps its default colours, nothing else depends on it.
+  }
+}

package/app/utils/theme/builtins.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest'
+import { BUILTIN_THEMES, CAT_FACTORY_THEME, DEFAULT_THEME_ID } from '~/utils/theme/builtins'
+
+// `app.config.ts` / `nuxt.config.ts` call Nuxt's auto-imported define helpers; under plain Vitest
+// each is an identity function.
+vi.stubGlobal('defineAppConfig', <T>(config: T) => config)
+vi.stubGlobal('defineNuxtConfig', <T>(config: T) => config)
+
+describe('built-in themes', () => {
+  it('states the default theme as exactly what app.config.ts paints the first frame with', async () => {
+    // A disagreement would flash one palette and settle on another: the theme plugin applies the
+    // document AFTER Nuxt UI's colours plugin has already emitted the ramps from `app.config`.
+    const appConfig = (await import('~/app.config')).default as {
+      ui: { colors: Record<string, string> }
+    }
+    expect(CAT_FACTORY_THEME.doc.colors).toEqual(appConfig.ui.colors)
+  })
+
+  it('self-hosts every face a built-in theme names', async () => {
+    // The theme plugin sets the family at runtime, which `@nuxt/fonts`' CSS scan cannot see, so the
+    // face must be listed in `fonts.families` or the built-in renders in the browser's fallback.
+    const nuxtConfig = (await import('../../../nuxt.config')).default as {
+      fonts: { families: Array<{ name: string }> }
+    }
+    const hosted = new Set(nuxtConfig.fonts.families.map((family) => family.name))
+    for (const theme of BUILTIN_THEMES) {
+      for (const face of Object.values(theme.doc.font ?? {})) {
+        if (typeof face === 'string') expect(hosted, `${theme.id} names ${face}`).toContain(face)
+      }
+    }
+  })
+
+  it('has unique ids and names the default among them', () => {
+    const ids = BUILTIN_THEMES.map((theme) => theme.id)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(ids).toContain(DEFAULT_THEME_ID)
+  })
+})

package/app/utils/theme/builtins.ts

@@ -0,0 +1,55 @@
+import type { ThemeDoc } from '~/utils/theme/doc'
+import { presets } from '~/utils/theme/presets'
+
+/**
+ * A theme the switcher offers: a editor document under a display name. Built-ins and the user's
+ * imported themes share this shape, so the switcher, the store and the applier never branch on
+ * where a theme came from.
+ */
+export interface NamedTheme {
+  id: string
+  /** A proper noun (a theme's name is data the way a locale's `name` is), not an i18n key. */
+  name: string
+  doc: ThemeDoc
+}
+
+export const DEFAULT_THEME_ID = 'cat-factory'
+
+/**
+ * The app's own theme, stated as the document a user could have exported from the editor. It MUST
+ * agree with `app.config.ts`'s `ui.colors`: that block is what the very first paint renders from,
+ * before the theme plugin runs, and a disagreement would flash one palette and settle on another.
+ * `theme.builtins.spec.ts` pins the equality.
+ *
+ * Status hues are the app's long-standing choices (amber for warning, rose for error, emerald
+ * for success, sky for info, violet for the secondary accent), named here as aliases so a theme
+ * that recolours `warning` recolours every warning surface.
+ */
+export const CAT_FACTORY_THEME: NamedTheme = {
+  id: DEFAULT_THEME_ID,
+  name: 'Cat Factory',
+  doc: {
+    version: 1,
+    colors: {
+      primary: 'indigo',
+      secondary: 'violet',
+      success: 'emerald',
+      info: 'sky',
+      warning: 'amber',
+      error: 'rose',
+      neutral: 'slate',
+    },
+  },
+}
+
+/**
+ * The editor's own Mono preset (black on a pure grey neutral, generous radius, Geist), taken from
+ * the preset table rather than copied, so it stays whatever the editor ships. Its faces are
+ * self-hosted in `nuxt.config.ts` (`fonts.families`); `builtins.spec.ts` pins that.
+ */
+const monoPreset = presets.find((preset) => preset.id === 'mono')
+if (!monoPreset) throw new Error('the editor preset table has no "mono" entry')
+
+export const MONO_THEME: NamedTheme = { id: 'mono', name: monoPreset.name, doc: monoPreset.doc }
+
+export const BUILTIN_THEMES: readonly NamedTheme[] = [CAT_FACTORY_THEME, MONO_THEME]

package/app/utils/theme/css.ts

@@ -0,0 +1,162 @@
+import {
+  THEME_DEFAULTS,
+  styleTokens,
+  type ModeTokens,
+  type ThemeDoc,
+  type ThemePalette,
+} from '~/utils/theme/doc'
+
+/**
+ * A theme document as the stylesheet the app injects at runtime (the `<style id="app-theme">` the
+ * theme plugin owns). This is the runtime twin of the editor's `main.css` export: the same
+ * variables, but scoped so they win without depending on source order.
+ *
+ * Every rule is anchored on `:root[data-theme]`, the attribute the plugin sets on `<html>`. That
+ * gives each block a specificity the library's own `@layer theme` rules AND `main.css`'s unlayered
+ * `.dark {}` blocks cannot reach: light values ride `:root[data-theme]` (0,2,0), dark values
+ * `:root[data-theme].dark` (0,3,0), so dark wins whenever the colour-mode class is present and the
+ * editor's "restate the library's dark value" workaround is unnecessary. It also means a theme can
+ * override the app's own `--app-*` tokens (declared in `main.css` on `.dark`) with no ordering
+ * game.
+ *
+ * Values are the WRITE BOUNDARY for untrusted input: an imported document ends up concatenated into
+ * a stylesheet, so every character class below excludes `;`, `}` and `<`, which is what keeps a
+ * value from ending its declaration early or closing the tag. A rejected value is dropped, never
+ * escaped: a half-applied theme is visible, a corrupted stylesheet is not.
+ */
+
+const SAFE_CSS_VAR_KEY = /^--[\w-]+$/
+const OKLCH_NUMBER = String.raw`\d+(?:\.\d+)?|\.\d+`
+const SAFE_OKLCH = new RegExp(
+  String.raw`^oklch\(\s*(?:${OKLCH_NUMBER})%?\s+(?:${OKLCH_NUMBER}|none)\s+(?:(?:${OKLCH_NUMBER})(?:deg)?|none)\s*\)$`,
+  'i',
+)
+const SAFE_HEX = /^#[0-9a-f]{3,8}$/i
+// var() refs, hex, keywords, px/% lengths and literal oklch()/rgb() colours.
+const SAFE_CSS_VAR_VALUE =
+  /^(?:var\(--[\w-]+\)|#[0-9a-f]{3,8}|[a-z]+|-?\d{1,3}(?:\.\d+)?(?:px|%|rem)|oklch\([\w.% -]{1,40}\)|rgba?\([\d.%, /]{1,40}\))$/i
+const SAFE_PALETTE_NAME = /^[\w-]{1,50}$/
+const SAFE_FONT_NAME = /^[\w -]{1,50}$/
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+export function isSafeCssVarKey(key: string): boolean {
+  return SAFE_CSS_VAR_KEY.test(key) && !UNSAFE_KEYS.has(key.slice(2))
+}
+
+export function isSafeCssVarValue(value: unknown): value is string {
+  return typeof value === 'string' && SAFE_CSS_VAR_VALUE.test(value)
+}
+
+export function isSafeShadeValue(value: unknown): value is string {
+  return typeof value === 'string' && (SAFE_OKLCH.test(value) || SAFE_HEX.test(value))
+}
+
+export function isSafeFontName(value: unknown): value is string {
+  return typeof value === 'string' && SAFE_FONT_NAME.test(value)
+}
+
+/**
+ * A palette NAME safe to interpolate into `--color-<name>-<shade>` and into the alias map Nuxt UI
+ * re-emits as `--ui-color-<alias>-<shade>: var(--color-<value>-<shade>)`. Both a custom palette key
+ * and a document's alias VALUE reach generated CSS this way, so both must pass this one rule.
+ */
+export function isSafePaletteName(value: unknown): value is string {
+  return typeof value === 'string' && SAFE_PALETTE_NAME.test(value) && !UNSAFE_KEYS.has(value)
+}
+
+function cleanVars(vars: Record<string, unknown> | undefined): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(vars ?? {})) {
+    if (isSafeCssVarKey(key) && isSafeCssVarValue(value)) result[key] = value
+  }
+  return result
+}
+
+/**
+ * The per-mode variable set a document resolves to. One precedence in BOTH modes: style shades
+ * first, then `blackAsPrimary` (the coarser instruction), then explicit tokens win. Light mirrors
+ * dark so a document carrying both `blackAsPrimary` and a `--ui-primary` style shade cannot render
+ * monochrome in one mode and a ramp colour in the other.
+ */
+export function docModeTokens(doc: ThemeDoc): ModeTokens {
+  const style = styleTokens(doc.style)
+  const light = {
+    ...style.light,
+    ...(doc.blackAsPrimary ? { '--ui-primary': 'black' } : {}),
+    ...cleanVars(doc.tokens?.light),
+  }
+  const dark = {
+    ...style.dark,
+    ...(doc.blackAsPrimary ? { '--ui-primary': 'white' } : {}),
+    ...cleanVars(doc.tokens?.dark),
+  }
+  return { light, dark }
+}
+
+function paletteLines(name: string, palette: ThemePalette): string[] {
+  if (!isSafePaletteName(name)) return []
+  return Object.entries(palette.shades ?? {})
+    .filter(([shade, value]) => /^\d{2,3}$/.test(shade) && isSafeShadeValue(value))
+    .map(([shade, value]) => `  --color-${name}-${shade}: ${value};`)
+}
+
+function block(selector: string, lines: string[]): string[] {
+  return lines.length > 0 ? [`${selector} {`, ...lines, '}'] : []
+}
+
+function declarations(vars: Record<string, string>): string[] {
+  return Object.entries(vars).map(([key, value]) => `  ${key}: ${value};`)
+}
+
+/**
+ * The stylesheet for a document. Empty for an empty document, so the stock library theme injects
+ * nothing at all.
+ */
+export function themeDocToCss(doc: ThemeDoc): string {
+  const root: string[] = []
+
+  // Custom palettes ride the runtime colours plugin's fallback: it emits
+  // `var(--color-<name>-<shade>, <tailwind literal>)` for every alias, so declaring the ramp as a
+  // real custom property on the root is enough for the alias to pick it up.
+  for (const [name, palette] of Object.entries(doc.palettes ?? {})) {
+    root.push(...paletteLines(name, palette))
+  }
+  if (doc.radius !== undefined && doc.radius !== THEME_DEFAULTS.radius && isFinite(doc.radius)) {
+    root.push(`  --ui-radius: ${doc.radius}rem;`)
+  }
+  // Tailwind's `--font-*` theme variables are live custom properties (`font-sans` compiles to
+  // `var(--font-sans)`, and preflight's body family derives from it), so a root override reaches
+  // every utility and the classless body alike. The FACE is the deployment's to provide: this
+  // names the family and lets the browser fall back when it is not installed or self-hosted.
+  if (isSafeFontName(doc.font?.sans) && doc.font.sans !== THEME_DEFAULTS.font) {
+    root.push(`  --font-sans: '${doc.font.sans}', ui-sans-serif, system-ui, sans-serif;`)
+  }
+  if (isSafeFontName(doc.font?.serif)) {
+    root.push(`  --font-serif: '${doc.font.serif}', ui-serif, serif;`)
+  }
+  if (isSafeFontName(doc.font?.mono)) {
+    root.push(`  --font-mono: '${doc.font.mono}', ui-monospace, monospace;`)
+  }
+  for (const step of ['normal', 'medium', 'semibold', 'bold'] as const) {
+    const weight = doc.font?.weights?.[step]
+    if (typeof weight === 'number' && weight >= 100 && weight <= 900) {
+      root.push(`  --font-weight-${step}: ${weight};`)
+    }
+  }
+
+  const tokens = docModeTokens(doc)
+  const lines = [
+    ...block(':root[data-theme]', root),
+    ...block(':root[data-theme]', declarations(tokens.light)),
+    ...block(':root[data-theme].dark', declarations(tokens.dark)),
+  ]
+  if (
+    doc.fontSize !== undefined &&
+    doc.fontSize !== THEME_DEFAULTS.fontSize &&
+    doc.fontSize >= 8 &&
+    doc.fontSize <= 32
+  ) {
+    lines.push(`html[data-theme] { font-size: ${doc.fontSize}px; }`)
+  }
+  return lines.join('\n')
+}