@cat-factory/app 0.302.2 → 0.303.0

package/app/plugins/theme.client.ts

@@ -0,0 +1,125 @@
+import { computed, nextTick, ref, toRaw, watch } from 'vue'
+import { useThemeStore } from '~/stores/theme'
+import { captureBootPalette, writeBootPalette } from '~/utils/theme/bootPalette'
+import { isSafePaletteName, themeDocToCss } from '~/utils/theme/css'
+import {
+  COLOR_ALIASES,
+  DEFAULT_COLORS,
+  docColors,
+  docComponentOverrides,
+  mergeUi,
+  type ComponentOverrides,
+  type ThemeDoc,
+} from '~/utils/theme/doc'
+
+/**
+ * Applies the active theme document to the running app, the runtime twin of pasting the editor's
+ * `main.css` + `app.config.ts` export into the source tree:
+ *
+ * - the alias → palette map lands on `appConfig.ui.colors`, which Nuxt UI's own colours plugin
+ *   watches and re-emits as the `--ui-color-<alias>-<shade>` ramps (so every role token, every
+ *   bare `text-primary`, and the app's `--app-*` tokens follow with no work here);
+ * - the default-variant expansion and explicit component overrides land on `appConfig.ui.<comp>`,
+ *   merged INTO the layer's own overrides from `app.config.ts` (the modal / slideover / toaster
+ *   slots) rather than over them, and reset when the next theme no longer touches a component;
+ * - everything that is a CSS variable rides one `<style id="app-theme">` in the head plus a
+ *   `data-theme` attribute on `<html>` the stylesheet's selectors anchor on (see `css.ts`).
+ *
+ * Runs client-only because the SPA is `ssr: false` and the document lives in browser storage.
+ */
+
+type UiConfig = Record<string, unknown> & { colors: Record<string, string> }
+
+export default defineNuxtPlugin(() => {
+  const store = useThemeStore()
+  const appConfig = useAppConfig()
+  const ui = appConfig.ui as unknown as UiConfig
+
+  // The layer's own overrides, snapshotted ONCE before any theme touches them: they are the base
+  // every theme merges into, and the value a component returns to when a theme stops naming it.
+  const baseUi: ComponentOverrides = {}
+  for (const [key, value] of Object.entries(toRaw(ui))) {
+    if (key !== 'colors' && typeof value === 'object' && value !== null) {
+      baseUi[key] = structuredClone(toRaw(value)) as Record<string, unknown>
+    }
+  }
+  let themedKeys = new Set<string>()
+
+  function apply(doc: ThemeDoc) {
+    // `docColors` fills defaults but passes a document's own alias values through untouched, and
+    // Nuxt UI interpolates each into `--ui-color-<alias>-<shade>: var(--color-<value>-<shade>)`, so
+    // an imported document's value has to clear the same grammar as any token that reaches CSS.
+    const colors = docColors(doc)
+    for (const alias of COLOR_ALIASES) {
+      const value = colors[alias]
+      ui.colors[alias] = isSafePaletteName(value) ? value : DEFAULT_COLORS[alias]
+    }
+
+    const overrides = docComponentOverrides(doc)
+    const next = new Set(Object.keys(overrides))
+    for (const key of themedKeys) {
+      if (next.has(key)) continue
+      if (key in baseUi) ui[key] = structuredClone(baseUi[key])
+      else delete ui[key]
+    }
+    const merged = mergeUi(
+      Object.fromEntries([...next].map((key) => [key, baseUi[key]]).filter(([, v]) => v)),
+      overrides,
+    )
+    for (const key of next) ui[key] = merged[key]
+    themedKeys = next
+  }
+
+  const css = computed(() => themeDocToCss(store.active.doc))
+  useHead({
+    htmlAttrs: { 'data-theme': computed(() => store.active.id) },
+    style: [{ id: 'app-theme', innerHTML: css }],
+  })
+
+  watch(() => store.active.doc, apply, { immediate: true })
+
+  // The browser chrome and the loading shell's cache both want the COMPUTED canvas colour, which
+  // exists only after unhead has written the theme style and Nuxt UI's colour ramps into the DOM.
+  // That moment is unhead's own `dom:rendered` hook (the same one Nuxt UI's colours plugin uses),
+  // so the capture runs there rather than after a tick or a frame: a tick is too early, and a
+  // hidden tab never gets a frame. `getComputedStyle` flushes style itself.
+  //
+  // The chrome rides `useHead` too: unhead dedupes a `theme-color` meta by name AND media, so this
+  // pair (same media as the first-paint pair in `nuxt.config.ts`, no key) overrides those two tags
+  // with the live colour, whichever the OS scheme selects, and unhead never re-renders a stale
+  // value over a hand-edited tag.
+  const colorMode = useColorMode()
+  const chrome = ref<string | null>(null)
+  useHead({
+    meta: [
+      {
+        name: 'theme-color',
+        media: '(prefers-color-scheme: dark)',
+        // The first-paint fallbacks, the same two values `nuxt.config.ts` ships.
+        content: computed(() => chrome.value ?? '#020618'), // colour-literal-ok: first paint
+      },
+      {
+        name: 'theme-color',
+        media: '(prefers-color-scheme: light)',
+        content: computed(() => chrome.value ?? '#e2e8f0'), // colour-literal-ok: first paint
+      },
+    ],
+  })
+  function recordBootColours() {
+    const mode = colorMode.value
+    if (mode !== 'light' && mode !== 'dark') return
+    const entry = captureBootPalette()
+    if (!entry) return
+    writeBootPalette(store.active.id, mode, entry)
+    chrome.value = entry.bg
+  }
+  injectHead()?.hooks?.hook('dom:rendered', recordBootColours)
+  watch(
+    () => [store.active.id, colorMode.value] as const,
+    async () => {
+      await nextTick()
+      recordBootColours()
+    },
+    { immediate: true },
+  )
+})

package/app/spa-loading-template.html

@@ -4,6 +4,29 @@
      brand name (a proper noun, identical in every locale) so it stays locale-neutral.
      Wired via app.spaLoadingTemplate in nuxt.config.ts. -->
 <div class="cf-spa-loader" role="status" aria-label="Cat Factory is starting">
+  <!-- Wear the ACTIVE theme, not the default: the theme plugin caches the computed colours of the
+       few tokens this shell paints with, per colour mode, under `cf-boot-palette` (see
+       utils/theme/bootPalette.ts). The colour-mode script in <head> has already classed <html>, so
+       pick that mode's entry; a mode never seen since the theme was picked keeps the defaults below.
+       Values are computed colours applied through setProperty, so nothing here can be injected. -->
+  <script>
+    ;(function () {
+      try {
+        var mode = document.documentElement.classList.contains('light') ? 'light' : 'dark'
+        var palette = JSON.parse(localStorage.getItem('cf-boot-palette') || '{}')[mode]
+        if (!palette) return
+        var el = document.currentScript.parentElement
+        var slots = ['bg', 'track', 'accent', 'status']
+        for (var i = 0; i < slots.length; i++) {
+          if (typeof palette[slots[i]] === 'string') {
+            el.style.setProperty('--cf-' + slots[i], palette[slots[i]])
+          }
+        }
+      } catch (e) {
+        /* storage unavailable: the shell keeps its default colours */
+      }
+    })()
+  </script>
   <div class="cf-spa-loader__badge">
     <div class="cf-spa-loader__ring"></div>
     <!-- Cat face, drawn inline so it paints without the icon font. -->
@@ -12,11 +35,11 @@
         d="M4 4l3 3.2A7.5 7.5 0 0 1 12 6c1.9 0 3.6.5 5 1.2L20 4v8a8 8 0 0 1-16 0V4z"
         fill="currentColor"
       />
-      <circle cx="9" cy="11.5" r="1.1" fill="#0b1020" />
-      <circle cx="15" cy="11.5" r="1.1" fill="#0b1020" />
+      <circle cx="9" cy="11.5" r="1.1" />
+      <circle cx="15" cy="11.5" r="1.1" />
       <path
         d="M10.6 14.4c.4.5 2.4.5 2.8 0"
-        stroke="#0b1020"
+        stroke="currentColor"
         stroke-width="1"
         stroke-linecap="round"
       />
@@ -38,8 +61,14 @@
     align-items: center;
     justify-content: center;
     gap: 1.5rem;
-    /* --board-bg / slate-950, matching the board surface AuthGate renders on. */
-    background-color: #0b1020;
+    /* Defaults are the default theme's tokens (slate-950 / slate-200 canvas, indigo primary),
+       hardcoded because main.css is not loaded yet; the inline script above overrides the
+       `--cf-*` slots with the active theme's cached colours when it has them. */
+    --cf-bg: #020618;
+    --cf-track: #1e293b;
+    --cf-accent: #818cf8;
+    --cf-status: #94a3b8;
+    background-color: var(--cf-bg);
     font-family:
       ui-sans-serif,
       system-ui,
@@ -60,15 +89,15 @@
     position: absolute;
     inset: 0;
     border-radius: 9999px;
-    /* Track in slate-700, the active arc in indigo-500 (the app's primary). */
-    border: 3px solid #1e293b;
-    border-top-color: #6366f1;
+    /* Track in the border token, the active arc in the primary. */
+    border: 3px solid var(--cf-track);
+    border-top-color: var(--cf-accent);
     animation: cf-spa-spin 1s linear infinite;
   }
   .cf-spa-loader__cat {
     width: 2.5rem;
     height: 2.5rem;
-    color: #818cf8;
+    color: var(--cf-accent);
     animation: cf-spa-bob 1.6s ease-in-out infinite;
   }
   .cf-spa-loader__text {
@@ -81,14 +110,23 @@
     font-size: 1.35rem;
     font-weight: 700;
     letter-spacing: 0.01em;
-    background: linear-gradient(90deg, #818cf8, #6366f1);
-    -webkit-background-clip: text;
-    background-clip: text;
-    color: transparent;
+    color: var(--cf-accent);
   }
   .cf-spa-loader__status {
     font-size: 0.875rem;
-    color: #94a3b8;
+    color: var(--cf-status);
+  }
+  /* Light colour mode: the canvas and the two neutral shades flip; the indigo accents stay. */
+  html.light .cf-spa-loader {
+    --cf-bg: #e2e8f0;
+    --cf-track: #cbd5e1;
+    --cf-accent: #6366f1;
+    --cf-status: #64748b;
+  }
+  .cf-spa-loader__cat circle,
+  .cf-spa-loader__cat path[stroke] {
+    fill: var(--cf-bg);
+    stroke: var(--cf-bg);
   }
   .cf-spa-loader__dots i {
     font-style: normal;

package/app/stores/agents.ts

@@ -151,7 +151,7 @@ export const useAgentsStore = defineStore('agents', () => {
       label: input.label.trim() || 'Custom Agent',
       description: input.description?.trim() || 'Custom agent.',
       icon: input.icon || 'i-lucide-sparkles',
-      color: input.color || '#22d3ee',
+      color: input.color || 'var(--app-hue-cyan)',
     }
     runtimeAgents.value = [...runtimeAgents.value, archetype]
     return archetype

package/app/stores/theme.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { useThemeStore } from '~/stores/theme'
+import { BUILTIN_THEMES, DEFAULT_THEME_ID } from '~/utils/theme/builtins'
+
+describe('theme store', () => {
+  it('boots on the default built-in and lists the built-ins first', () => {
+    const store = useThemeStore()
+    expect(store.current).toBe(DEFAULT_THEME_ID)
+    expect(store.active.id).toBe(DEFAULT_THEME_ID)
+    expect(store.themes.slice(0, BUILTIN_THEMES.length)).toEqual(BUILTIN_THEMES)
+    expect(store.isCustom).toBe(false)
+  })
+
+  it('selects only a theme it knows', () => {
+    const store = useThemeStore()
+    store.select('mono')
+    expect(store.active.name).toBe('Mono')
+    store.select('nope')
+    expect(store.current).toBe('mono')
+  })
+
+  it('stores an imported document under a name and switches to it', () => {
+    const store = useThemeStore()
+    const theme = store.addCustom('  Ocean ', { version: 1, colors: { primary: 'cyan' } })
+    expect(theme.name).toBe('Ocean')
+    expect(store.current).toBe(theme.id)
+    expect(store.isCustom).toBe(true)
+    expect(store.active.doc.colors?.primary).toBe('cyan')
+  })
+
+  it('names an unnamed import after its position', () => {
+    const store = useThemeStore()
+    expect(store.addCustom('', { version: 1 }).name).toBe('Theme 1')
+    expect(store.addCustom('   ', { version: 1 }).name).toBe('Theme 2')
+  })
+
+  it('disambiguates a name a built-in or an earlier import already uses', () => {
+    const store = useThemeStore()
+    expect(store.addCustom('Mono', { version: 1 }).name).toBe('Mono (2)')
+    expect(store.addCustom('mono', { version: 1 }).name).toBe('mono (3)')
+    expect(store.addCustom('Ocean', { version: 1 }).name).toBe('Ocean')
+    expect(store.addCustom('Ocean', { version: 1 }).name).toBe('Ocean (2)')
+  })
+
+  it('falls back to the default when the active custom theme is removed or was never restored', () => {
+    const store = useThemeStore()
+    const theme = store.addCustom('Gone', { version: 1 })
+    store.removeCustom(theme.id)
+    expect(store.current).toBe(DEFAULT_THEME_ID)
+    expect(store.custom).toEqual([])
+
+    // A persisted pick naming a theme that no longer exists resolves to a real document.
+    store.current = 'custom-stale'
+    expect(store.active.id).toBe(DEFAULT_THEME_ID)
+  })
+})

package/app/stores/theme.ts

@@ -0,0 +1,87 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import { BUILTIN_THEMES, DEFAULT_THEME_ID, type NamedTheme } from '~/utils/theme/builtins'
+import type { ThemeDoc } from '~/utils/theme/doc'
+
+/**
+ * The user's theme choice and their imported themes, persisted in this browser like the language
+ * pick (`stores/locale.ts`). Colour MODE (light / dark / system) is NOT here: `@nuxtjs/color-mode`
+ * owns that preference and its own storage, and the two are orthogonal (every theme has both
+ * modes), so the switcher reads mode from `useColorMode()` and theme from this store.
+ *
+ * `custom` holds whole documents rather than the editor links they came from, so a theme keeps
+ * working when the editor changes its link encoding, and so the persisted blob is exactly what the
+ * applier reads (no decode on boot).
+ */
+export const useThemeStore = defineStore(
+  'theme',
+  () => {
+    const current = ref<string>(DEFAULT_THEME_ID)
+    const custom = ref<NamedTheme[]>([])
+
+    const themes = computed<readonly NamedTheme[]>(() => [...BUILTIN_THEMES, ...custom.value])
+
+    // `?? the default` because the restored id is untrusted input: a persisted pick can name a
+    // custom theme that was removed, or an id a later build renamed, and the app must still boot
+    // on a real document rather than on `undefined`.
+    const active = computed<NamedTheme>(
+      () =>
+        themes.value.find((theme) => theme.id === current.value) ??
+        themes.value.find((theme) => theme.id === DEFAULT_THEME_ID) ??
+        BUILTIN_THEMES[0]!,
+    )
+    const isCustom = computed(() => custom.value.some((theme) => theme.id === current.value))
+
+    function select(id: string) {
+      if (themes.value.some((theme) => theme.id === id)) current.value = id
+    }
+
+    /**
+     * A display name no other theme (built-in or imported) already uses. Ids never collide (an
+     * import gets a generated one), so the name is the only thing two entries could share, and
+     * two menu rows both reading "Mono" tell the user nothing. The first duplicate becomes
+     * "Mono (2)", the next "Mono (3)", the file-manager convention. Exposed so the import dialog
+     * can show the name that WILL be used while the user is still typing, rather than surprising
+     * them after the save.
+     */
+    function uniqueName(requested: string): string {
+      const taken = new Set(themes.value.map((theme) => theme.name.toLowerCase()))
+      if (!taken.has(requested.toLowerCase())) return requested
+      for (let n = 2; ; n++) {
+        const candidate = `${requested} (${n})`
+        if (!taken.has(candidate.toLowerCase())) return candidate
+      }
+    }
+
+    /** Store an imported document under a name and switch to it. Returns the new theme. */
+    function addCustom(name: string, doc: ThemeDoc): NamedTheme {
+      const theme: NamedTheme = {
+        id: `custom-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+        name: uniqueName(name.trim() || `Theme ${custom.value.length + 1}`),
+        doc,
+      }
+      custom.value = [...custom.value, theme]
+      current.value = theme.id
+      return theme
+    }
+
+    /** Drop an imported theme; the default takes over if it was the active one. */
+    function removeCustom(id: string) {
+      custom.value = custom.value.filter((theme) => theme.id !== id)
+      if (current.value === id) current.value = DEFAULT_THEME_ID
+    }
+
+    return {
+      current,
+      custom,
+      themes,
+      active,
+      isCustom,
+      uniqueName,
+      select,
+      addCustom,
+      removeCustom,
+    }
+  },
+  { persist: { pick: ['current', 'custom'] } },
+)

package/app/types/domain.ts

@@ -169,6 +169,25 @@ export interface AgentArchetype {
    * which is every built-in kind.
    */
   binaryOutput?: boolean
+  /**
+   * The registered EXTERNAL executor this kind's work runs on, when it runs on one at all.
+   *
+   * Carried onto the archetype for the reason {@link binaryOutput} is: the pipeline builder and
+   * every run view resolve a step's meta through `agentKindMeta`, not through the snapshot, so a
+   * fact a card has to state cannot live only on the wire entry. What it states is the thing a
+   * person composing a pipeline most needs to see (which of these steps leaves the platform),
+   * and what a run view needs to explain a step with no token usage beside it.
+   *
+   * `label` is absent when the kind declares a delegated surface whose executor THIS build no
+   * longer registers, which is a real state (a deployment can stop registering one while runs that
+   * used it are still on the board) and renders as the id rather than as a normal step.
+   */
+  delegatedExecutor?: {
+    id: string
+    label?: string
+    description?: string
+    telemetry?: 'not-reported' | 'self-reported'
+  }
   /**
    * The platform dispatches this kind for a flow of its own, so the builder palette never offers
    * it as a placeable block (`narrowAgentPalette` drops it). It still resolves through

package/app/types/execution.ts

@@ -120,6 +120,10 @@ export type {
   RunEnvironment,
   RunContainer,
   RunContainerStatus,
+  // The DELEGATED sibling: the external work a step dispatched, and what the platform can see of it.
+  RunDelegation,
+  RunDelegationAttempt,
+  RunDelegationStatus,
   HumanTestRound,
   HumanTestStepState,
   VisualConfirmStepState,

package/app/utils/agentOutput.ts

@@ -79,7 +79,7 @@ const md = new MarkdownIt({
 }).use(sourceLinePlugin)
 
 const HEADINGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6'])
-const LINK_CLASS = 'text-indigo-300 underline decoration-indigo-500/40 hover:text-indigo-200'
+const LINK_CLASS = 'text-primary underline decoration-primary/40 hover:decoration-primary'
 
 // A second markdown-it instance for INLINE prose rendering (a rationale, a synthesis,
 // a summary) — the same secure config as `md` (html: false, so raw HTML is escaped and

package/app/utils/binaryOutput.ts

@@ -401,37 +401,37 @@ export const BINARY_OUTPUT_STATE_KEYS: Record<
 > = {
   'not-started': {
     icon: 'i-lucide-clock',
-    tone: 'text-slate-400',
+    tone: 'text-muted',
     summary: 'binaryOutput.state.notStarted.summary',
     detail: 'binaryOutput.state.notStarted.detail',
   },
   configured: {
     icon: 'i-lucide-hourglass',
-    tone: 'text-slate-300',
+    tone: 'text-toned',
     summary: 'binaryOutput.state.configured.summary',
     detail: 'binaryOutput.state.configured.detail',
   },
   undeclared: {
     icon: 'i-lucide-circle-help',
-    tone: 'text-amber-300',
+    tone: 'text-app-warning-300',
     summary: 'binaryOutput.state.undeclared.summary',
     detail: 'binaryOutput.state.undeclared.detail',
   },
   'parse-failed': {
     icon: 'i-lucide-file-warning',
-    tone: 'text-amber-300',
+    tone: 'text-app-warning-300',
     summary: 'binaryOutput.state.parseFailed.summary',
     detail: 'binaryOutput.state.parseFailed.detail',
   },
   'declared-none': {
     icon: 'i-lucide-circle-slash',
-    tone: 'text-slate-300',
+    tone: 'text-toned',
     summary: 'binaryOutput.state.declaredNone.summary',
     detail: 'binaryOutput.state.declaredNone.detail',
   },
   stored: {
     icon: 'i-lucide-package-check',
-    tone: 'text-emerald-300',
+    tone: 'text-app-success-300',
     summary: 'binaryOutput.state.stored.summary',
     detail: '',
   },

package/app/utils/bootstrapSteps.ts

@@ -24,37 +24,37 @@ export interface BootstrapStepStyle {
 export const BOOTSTRAP_STEP_STYLE: Record<BootstrapStepState, BootstrapStepStyle> = {
   pending: {
     icon: 'i-lucide-circle',
-    iconClass: 'text-slate-500',
-    labelClass: 'text-slate-500',
+    iconClass: 'text-dimmed',
+    labelClass: 'text-dimmed',
   },
   running: {
     icon: 'i-lucide-loader-circle',
-    iconClass: 'animate-spin text-amber-400',
-    labelClass: 'text-amber-100',
+    iconClass: 'animate-spin text-app-warning-400',
+    labelClass: 'text-app-warning-100',
   },
   awaiting_review: {
     icon: 'i-lucide-user-check',
-    iconClass: 'text-amber-400',
-    labelClass: 'text-amber-100',
+    iconClass: 'text-app-warning-400',
+    labelClass: 'text-app-warning-100',
   },
   done: {
     icon: 'i-lucide-check-circle-2',
-    iconClass: 'text-emerald-400',
-    labelClass: 'text-slate-400',
+    iconClass: 'text-app-success-400',
+    labelClass: 'text-muted',
   },
   failed: {
     icon: 'i-lucide-alert-triangle',
-    iconClass: 'text-rose-400',
-    labelClass: 'text-rose-200',
+    iconClass: 'text-app-error-400',
+    labelClass: 'text-app-error-200',
   },
   stopped: {
     icon: 'i-lucide-circle-stop',
-    iconClass: 'text-slate-400',
-    labelClass: 'text-slate-300',
+    iconClass: 'text-muted',
+    labelClass: 'text-toned',
   },
   unknown: {
     icon: 'i-lucide-help-circle',
-    iconClass: 'text-slate-400',
-    labelClass: 'text-slate-400',
+    iconClass: 'text-muted',
+    labelClass: 'text-muted',
   },
 }