Skip to content

Self-improving AI Employees for everyone

docs(frontend): correct stale statements in frontend and theme docs

trohitg0c65ffad8a74
diff --git a/client/src/contexts/WebSocketContext.tsx b/client/src/contexts/WebSocketContext.tsx
index f6b25126..fc473be3 100644
--- a/client/src/contexts/WebSocketContext.tsx
+++ b/client/src/contexts/WebSocketContext.tsx
@@ -836,7 +836,8 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chi
// without limit; retries normally arrive close together.
const processedCloudEventsRef = useRef<Set<string>>(new Set());
// Pending-send queue for backpressure + replay across reconnects.
- // Drained inside `ws.onopen` after the init burst. Source of truth
+ // Drained inside `ws.onopen` by `drainPendingSends`, immediately before
+ // `setIsReady(true)` (Wave 32 removed the init burst). Source of truth
// for currentWorkflowId is `useAppStore.getState().currentWorkflow?.id`
// (read via Zustand's documented escape hatch in non-React listeners).
const pendingSendQueueRef = useRef<Array<QueuedSend>>([]);
@@ -2140,7 +2141,8 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chi
// `['openai', 'anthropic', 'gemini', 'google_maps', 'android_remote']`.
// Those probes were redundant — credential state has TWO authoritative
// sources already:
- // 1. The backend's `initial_status` broadcast (handled at line ~638)
+ // 1. The backend's `initial_status` broadcast (the `initial_status`
+ // case in `handleMessage`)
// pushes the full `api_keys` map on every reconnect.
// 2. The catalogue (TanStack Query `useCatalogueQuery`) carries the
// `provider.stored` flag for every provider; refetched via the
diff --git a/client/src/hooks/useSound.ts b/client/src/hooks/useSound.ts
index 66b39991..4bca999f 100644
--- a/client/src/hooks/useSound.ts
+++ b/client/src/hooks/useSound.ts
@@ -1,7 +1,8 @@
/**
* useSound — React glue for the per-theme WebAudio engine.
*
- * `useSoundSync()` mounts once at the Dashboard root. It:
+ * `useSoundSync()` mounts once in the app shell (`ShellEffects` in
+ * app/AppShell.tsx), so it runs on both Home and the editor. It:
* - mirrors the `soundEnabled` Zustand slice into `Sounds.setEnabled()`
* - reads `--sound-pack` from `:root` after every theme change and
* calls `Sounds.setPack(...)` so the active pack tracks the active
@@ -78,7 +79,7 @@ function patchToast(): void {
}) as typeof originalError;
}
-/** Mount once at the Dashboard root. */
+/** Mount once, in the app shell (`ShellEffects` in app/AppShell.tsx). */
export function useSoundSync(): void {
const { theme } = useTheme();
const enabled = useAppStore((s) => s.soundEnabled);
diff --git a/client/src/index.css b/client/src/index.css
index 992c21b2..305d4b10 100644
--- a/client/src/index.css
+++ b/client/src/index.css
@@ -173,9 +173,12 @@
* `:root[data-theme="..."]`; these `@theme inline` aliases give
* Tailwind classes that resolve against whichever theme is active.
*
- * Note: full-colour values (not HSL triplets), so `bg-bg-app/50`
- * alpha composition does NOT work — use `--bg-overlay` or the
- * shadcn alias (`bg-background/50`) when you need alpha. */
+ * Note: full-colour values (not HSL triplets), so `/opacity` does
+ * compile here too: `bg-bg-app/50` becomes
+ * `color-mix(in oklab, var(--bg-app) 50%, transparent)` behind an
+ * `@supports` guard. Opacity arithmetic at call sites is still
+ * forbidden by the frontend rules — use `--bg-overlay` or a named
+ * `-soft` / `-tint` token when you need alpha. */
--color-bg-app: var(--bg-app);
--color-bg-panel: var(--bg-panel);
--color-bg-canvas: var(--bg-canvas);
diff --git a/client/src/lib/queryClient.ts b/client/src/lib/queryClient.ts
index 1d142c95..f10dbe4b 100644
--- a/client/src/lib/queryClient.ts
+++ b/client/src/lib/queryClient.ts
@@ -47,11 +47,12 @@ queryClient.setQueryDefaults(['nodeGroups'], {
gcTime: GC_TIME.FOREVER,
});
-// Credential values are persisted via PersistQueryClient (see
-// queryPersist.ts whitelist). Same hydration trap as nodeSpec: the
-// per-call FOREVER staleTime did not prevent gcTime: 5min eviction, so
-// credential panel form fields silently went blank after idle. Anchor
-// the contract at the prefix root.
+// Credential values are NOT persisted (removed from the queryPersist.ts
+// whitelist: they hold decrypted API keys, which must never reach
+// localStorage). The in-memory entry still needs FOREVER: the per-call
+// FOREVER staleTime did not prevent gcTime: 5min eviction, so credential
+// panel form fields silently went blank after idle. Anchor the contract
+// at the prefix root.
queryClient.setQueryDefaults(['credentialValues'], {
staleTime: STALE_TIME.FOREVER,
gcTime: GC_TIME.FOREVER,
diff --git a/client/src/lib/queryPersist.ts b/client/src/lib/queryPersist.ts
index 9c504da4..6c8290a6 100644
--- a/client/src/lib/queryPersist.ts
+++ b/client/src/lib/queryPersist.ts
@@ -9,10 +9,12 @@
* compile-time constant (see vite.config.js). Bumping the version
* automatically purges stale persisted entries on next load.
*
- * Filter: only queries declaring staleTime: STALE_TIME.FOREVER are
- * persisted. Those carry data that only changes with a backend deploy
- * (NodeSpec catalogue, node groups). High-frequency / per-session
- * queries (status, parameters) are not persisted.
+ * Filter: only successfully resolved queries whose key starts with a
+ * prefix in PERSISTED_KEY_PREFIXES (nodeSpec, node groups) are persisted.
+ * Those carry data that only changes with a backend deploy. High-frequency
+ * / per-session queries (status, parameters) are not persisted. Each
+ * persisted prefix also needs a FOREVER setQueryDefaults in queryClient.ts,
+ * because hydration applies the client's default options.
*
* References:
* https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient
@@ -56,14 +58,12 @@ export const queryBuster = APP_VERSION;
export const queryPersistMaxAge = 24 * 60 * 60 * 1000;
/**
- * Filter predicate: only persist queries that declare
- * `staleTime: Infinity`. That is our project-wide marker for
- * "data only changes with a backend deploy" (catalogues, node specs,
- * node groups). High-frequency or per-session data stays in memory.
- *
- * The key is a defensive string-prefix match in addition to staleTime
- * so a future regression to the staleTime config does not silently
- * start persisting noisy keys.
+ * Filter predicate: persist a query only when its key's first element is
+ * in this allowlist AND it resolved successfully. The allowlist names the
+ * data that only changes with a backend deploy (node specs, node groups);
+ * high-frequency or per-session data stays in memory. The predicate does
+ * not read staleTime, so a new prefix here must be paired with a
+ * setQueryDefaults entry in queryClient.ts.
*/
const PERSISTED_KEY_PREFIXES = [
'nodeSpec',
diff --git a/docs-internal/design-system/IMPLEMENTATION.md b/docs-internal/design-system/IMPLEMENTATION.md
index 9938c53a..d6f27410 100644
--- a/docs-internal/design-system/IMPLEMENTATION.md
+++ b/docs-internal/design-system/IMPLEMENTATION.md
@@ -80,7 +80,7 @@ color: var(--action-run-ink); /* readable accent */
```
### Type
-`--font-sans: 'Geist'` (display = body) · `--font-mono: 'JetBrains Mono'` (counts, state, timestamps — the "machine voice").
+`--font-sans: 'Geist'` (display = body) · `--font-mono` (counts, state, timestamps — the "machine voice"): the live light / dark themes use the system mono stack `ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace` (`client/src/themes/light.css`, `dark.css`); JetBrains Mono is only a skin mono (Cyber, Edo, Rot). This bundle's `tokens/typography.css` still leads with `'JetBrains Mono'` — the live theme files win.
Scale (14px base, dense desktop): `--text-2xs 11` `--text-xs 12` `--text-sm 13` `--text-base 14` `--text-md 16` `--text-lg 18` `--text-xl 24` `--text-2xl 32` `--text-3xl 44`.
Weights: 400 body / 500 UI labels / 600 headings & buttons. Sentence case; uppercase + `--tracking-label .04em` only in the status bar and micro-labels.
diff --git a/docs-internal/design-system/guidelines/THEMES.md b/docs-internal/design-system/guidelines/THEMES.md
index 16ed11fc..90f5af70 100644
--- a/docs-internal/design-system/guidelines/THEMES.md
+++ b/docs-internal/design-system/guidelines/THEMES.md
@@ -1,6 +1,6 @@
# OpenCompany theming architecture — analysis
-Source: `client/src/themes/*.css` + `client/src/index.css` in https://github.com/zeenie-ai/OpenCompany (full copies in `reference/themes/`). The app ships **12 themes**: 2 canonical (light, dark) + 10 "skins" (Renaissance, Greek, Edo, Steampunk, Atomic, Cyber, Wasteland, Rot, Plague, Surveillance).
+Source: `client/src/themes/*.css` + `client/src/index.css` in https://github.com/zeenie-ai/OpenCompany (the live files are authoritative; the `reference/themes/` snapshots were retired — see its README). The app ships **12 themes**: 2 canonical (light, dark) + 10 "skins" (Renaissance, Greek, Edo, Steampunk, Atomic, Cyber, Wasteland, Rot, Plague, Surveillance).
## 1. How it works — a four-layer contract
@@ -28,10 +28,10 @@ Beyond color: **typeface trio, base font size (13–15px), letter case, tracking
| **Edo** | washi + sumi-e | rice paper | vermillion #b41e1e · sumi ink · bamboo · sakura | Shippori Mincho ×2 / JetBrains | none·.06em | all 0 | 90/220/520 organic | ink | vermillion |
| **Steampunk** | Verne submarine | oiled leather | brass #d8a848 · copper #b8602a · rust | IM Fell English SC / IM Fell / Special Elite | UPPER·.10em | 2/4/8 | 110/240/480 mechanical | clockwork | copper |
| **Atomic** | 1962 Eames | cream cardstock | atomic orange #e85a26 · turquoise #3a9aa0 · mustard | Bevan / Lato / Space Mono | UPPER·.06em | 0/2/4 (pill 999) | 100/200/380 bouncy (1.6 overshoot) | vibraphone | turquoise |
-| **Cyber** | Neuromancer market | void #050010 | neon magenta #f51eb6 · cyan #1dd9e5 · green · yellow | Major Mono Display / JetBrains ×2 (13px) | UPPER·.18em | all 0 | 60/120/240 `steps()` glitch | terminal | neon cyan |
+| **Cyber** | Neuromancer market | void #050010 | neon magenta #f51eb6 · cyan #1dd9e5 · green · yellow | Space Mono / JetBrains ×2 (13px) | UPPER·.18em | all 0 | 60/120/240 `steps()` glitch | terminal | neon cyan |
| **Wasteland** | Mad Max scrap | irradiated dust | ochre #e88a28 · rust #8a3a18 · rad-yellow #c8d038 · bone | Special Elite ×2 / VT323 | UPPER·.10em | all 0 | 60/180/320 jittery | scrap | rad yellow |
| **Rot** | mossy crypt | charcoal green | moss #78c878 · candle #e8a838 · bone · crypt brown | Pirata One / EB Garamond / JetBrains | none·.04em | 1/2/4 | 140/320/680 drift (slowest) | crypt | moss phosphor |
-| **Plague** | 1349 quarantine notice | bleached linen | dried blood #783c28 · bile #98a838 · crow black | UnifrakturCook / EB Garamond / Special Elite | UPPER·.06em | all 0 | 100/220/460 stiff | bell | bile red |
+| **Plague** | 1349 quarantine notice | bleached linen | dried blood #783c28 · bile #98a838 · crow black | Cinzel / EB Garamond / Special Elite | UPPER·.06em | all 0 | 100/220/460 stiff | bell | bile red |
| **Surveillance** | 1970s panopticon | institutional grey | REC red #e82626 · phosphor #6acc6a · amber | Anonymous Pro / IBM Plex Mono ×2 (13px) | UPPER·.10em | all 0 | 60/140/240 `linear` scanline | telex | REC red |
Special hardware: **Cyber** ships custom crosshair + bracket cursors and full-frame CRT flicker/roll keyframes; **Surveillance** ships a REC-red reticle cursor and a 1920×1080 CCTV crosshair canvas overlay; **Renaissance** ships a quill cursor, fleur-de-lis canvas tile and the only non-`none` `--ornament-frame` (triple gilded inset); **Steampunk** draws bolt-pattern canvas tiles and rivets nodes with pseudo-elements.
@@ -46,4 +46,4 @@ Special hardware: **Cyber** ships custom crosshair + bracket cursors and full-fr
## 5. Status in THIS design system
-`tokens/colors.css` encodes the two canonical themes (light `:root`, dark `.dark`). The 10 skins are **documented + sourced** (`reference/themes/`) but not yet expressed as token scopes here. To port one: copy its layer-2 block into a `[data-theme="X"]` scope in `tokens/`, map its accents onto the action/node role triplets, and load its Google Fonts (all skin fonts are on Google Fonts — same delivery as production). Visual comparison: `guidelines/theme-matrix.html`.
+`tokens/colors.css` encodes the two canonical themes (light `:root`, dark `.dark`). The 10 skins are **documented** here and sourced from the live `client/src/themes/` files, but not yet expressed as token scopes here. (Cyber and Plague display faces are the legibility substitutions Space Mono and Cinzel; the handoff's Major Mono Display and UnifrakturCook are not shipped.) To port one: copy its layer-2 block into a `[data-theme="X"]` scope in `tokens/`, map its accents onto the action/node role triplets, and load its Google Fonts (all skin fonts are on Google Fonts — same delivery as production). Visual comparison: `guidelines/theme-matrix.html`.
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index ac98c7dd..47f048d3 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -9,7 +9,7 @@ Post-migration (2026-04-14). Single source of truth for the current frontend.
- **React 19 + Vite 7**, type-checked by **TypeScript 7** (the native Go compiler, exact-pinned `7.0.2` in the **root** `devDependencies`). The client keeps `typescript@^5.9.3` only because typescript-eslint's peer range excludes 6/7 — it is not the gate. With the **React Compiler** (`[email protected]`, `target: '19'`, scoped to all of `src/` except `components/ui/`).
- **Tailwind v4** via `@tailwindcss/vite` + `@import "tailwindcss"` in [src/index.css](../client/src/index.css). Tokens defined in the same CSS file via `@theme inline` (no `tailwind.config.js` colors block).
- **shadcn/ui** via the canonical CLI (`bun x shadcn@latest add` — bun's `npx` equivalent; npm is not part of the toolchain). All primitives live under [client/src/components/ui/](../client/src/components/ui/) as first-class repo files we can edit.
-- **Radix UI** is the primitive engine shadcn uses (Dialog, Accordion, Select, Switch, Tabs, Tooltip, Popover, Dropdown, AlertDialog, Collapsible, Progress, Slider, Label, Checkbox).
+- **Radix UI** is the primitive engine shadcn uses (Dialog, Accordion, Select, Switch, Tabs, Tooltip, Dropdown, AlertDialog, Collapsible, Progress, Slider, Label, Checkbox, Toggle, ToggleGroup). There is no Popover primitive; add one with the CLI if a surface needs it.
- **Forms**: react-hook-form + zod via shadcn's `Form` composition. Per-form schemas live colocated with the form (e.g. `credentials/panels/schemas/email.ts`); tiny forms use inline zod.
- **Toasts**: `sonner` imported directly at call-sites. The shadcn `<Toaster />` wrapper (at [components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx)) is patched to read our `ThemeContext` instead of `next-themes`. Normal mode has a second toaster, one bottom-centre pill at a time (`pillToast()` in [features/home/ui/pillToast.tsx](../client/src/features/home/ui/pillToast.tsx)).
- **Two screens**: Normal mode (Home, [features/home/](../client/src/features/home/)) and Dev mode (the workflow editor, `Dashboard.tsx`), both lazy chunks switched by the app shell in [app/](../client/src/app/). See [Normal Mode](./normal_mode.md).
@@ -308,10 +308,11 @@ All under [components/ui/](../client/src/components/ui/). Editable — add varia
| Concern | Primitive | Notes |
|---|---|---|
-| Button | `Button` (CVA) | Variants: `default | secondary | ghost | outline | destructive | link`. Sizes: `default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg` |
+| Button | `Button` (CVA) | Variants: `default | secondary | ghost | outline | destructive | link` + Normal-mode `invert | quiet | chip` (ours). Sizes: `default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg` + `pill | chip` (ours) |
| Badge | `Badge` | + `success | warning | info` (ours) |
| Alert | `Alert + AlertTitle + AlertDescription` | + `success | warning | info` (ours) |
-| Overlay | `Dialog`, `AlertDialog`, `Popover`, `Tooltip`, `DropdownMenu` | Radix |
+| Overlay | `Dialog`, `AlertDialog`, `Tooltip`, `DropdownMenu` | Radix |
+| Toggle | `Toggle`, `ToggleGroup + ToggleGroupItem` | Radix. Variants `default | segmented | chips` (ours) |
| Disclosure | `Accordion`, `Collapsible`, `Tabs` | Radix |
| Inputs | `Input`, `Textarea`, `Select`, `Switch`, `Checkbox`, `Slider`, `Label` | Radix (Select/Switch/Checkbox/Slider) |
| Cards | `Card + CardHeader/Title/Description/Content/Footer` | Layout primitive |
diff --git a/docs-internal/performance.md b/docs-internal/performance.md
index c1a58c8c..5e0878c7 100644
--- a/docs-internal/performance.md
+++ b/docs-internal/performance.md
@@ -199,7 +199,7 @@ is idle in this window; the cost lives on the frontend. Likely
contributors:
1. **TanStack Query auth-bootstrap retry budget** ([client/src/contexts/AuthContext.tsx](../client/src/contexts/AuthContext.tsx) + [client/src/lib/connectionConfig.ts](../client/src/lib/connectionConfig.ts)). The `AUTH_RETRY` envelope (BASE 50 ms, CAP 4000 ms, MAX_ATTEMPTS 7) covers the typical 4 s backend cold-start window in 4-5 attempts. If the backend finishes mid-retry-cycle, the next jittered draw can land 1-3 s after readiness.
-2. **React Strict Mode dual-mount** in dev. The 100 ms `setTimeout` guard in the connect effect at [WebSocketContext.tsx:3558](../client/src/contexts/WebSocketContext.tsx#L3558) absorbs the bulk; remaining cost is React reconciliation + babel-plugin-react-compiler overhead on first render.
+2. **React Strict Mode dual-mount** in dev. The 100 ms `connectTimeout` guard in `WebSocketProvider`'s auth-gated connect effect ([WebSocketContext.tsx](../client/src/contexts/WebSocketContext.tsx)) absorbs the bulk; remaining cost is React reconciliation + babel-plugin-react-compiler overhead on first render.
3. **PartySocket upgrade handshake**. Sub-100 ms in normal cases; would only matter on slow networks.
To attribute definitively: add `console.time('auth.queryFn')` / `console.timeLog('auth.queryFn')` markers and a corresponding pair around `connect()`. Not blocking — the contract this layer was meant to fix (the +12 s disconnect-reconnect cycle) is resolved.
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 691379c8..f33e710d 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -102,7 +102,7 @@ Surface hierarchy across themes; every theme assigns these in its `:root[data-th
| `tracking-[var(--type-tracking-display)]` | `--type-tracking-display` | Letter-spacing for display headings |
| `[text-transform:var(--type-uppercase)]` | `--type-uppercase` | Theme-driven uppercase / capitalize / none |
-**Note**: values are hex + `color-mix()`. Tailwind v4 composes `/opacity` via `color-mix` for any colour format, so `bg-bg-app/50` *does* work — but prefer a named token (`--bg-overlay`, a `-soft`/`-tint` variant) over ad-hoc surface alpha.
+**Note**: values are hex + `color-mix()`. Tailwind v4 composes `/opacity` via `color-mix` for any colour format, so `bg-bg-app/50` *does* compile and work (to `color-mix(in oklab, var(--bg-app) 50%, transparent)` behind an `@supports` guard) — but opacity arithmetic at call sites is forbidden by the frontend rules; use a named token (`--bg-overlay`, a `-soft`/`-tint` variant) instead.
### 2. shadcn semantic tokens (preserved for primitives)
@@ -278,7 +278,7 @@ the surrounding chrome. Every other surface uses Tailwind + tokens. New themes c
### Done
- **`--node-pulse-color` contract** — executing-node glow color is independent of `--node-color` (the plugin accent). Each decorated skin overrides `--node-pulse-color` to its highest-contrast accent (light/dark deliberately keep the base.css `var(--info)` fallback) (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine `--lapis-bright`, Atomic turquoise, etc.) so the glow stays visible against any canvas background. Defined in [base.css](../client/src/themes/base.css) at `:root`, overridden in each per-theme file. The executing keyframes (`node-pulse` + per-theme `cyber-pulse-exec` / `surv-pulse-exec` / `ren-pulse-exec`) and the per-theme `--pulse-keyframe` / `--pulse-duration` / `--pulse-timing` tokens live in [animations.css](../client/src/themes/animations.css); base.css's `.sq-node[data-executing] .sq-node-box` / `.react-flow__node.executing .{sq-node-box,node}` rule reads `var(--pulse-keyframe, node-pulse)`, so a theme picks its pulse by overriding ONE token (Cyber → `cyber-pulse-exec`, Surveillance → `surv-pulse-exec`, Renaissance → `ren-pulse-exec`) — no high-specificity per-theme animation rule. `node-pulse` is a triple-layer expanding box-shadow (12px ring + 32px mid halo + 56px outer halo) consuming `var(--node-pulse-color)` + the shared `--tint-pulse-*` alphas. Trigger nodes use a separate continuous `.opencompany-trigger-armed` "listening" heartbeat (`trigger-listening` keyframe) while waiting, plus `.opencompany-bolt` on the ⚡ badge — distinct from the one-shot execution pulse. **Never animate `opacity` on whole-node selectors** — it fades the node icon + content, not just the glow.
-- **`data-page-hidden` animation pause** — [Dashboard.tsx](../client/src/Dashboard.tsx) mounts a `visibilitychange` listener that toggles `data-page-hidden` on `<html>`; [base.css](../client/src/themes/base.css) declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important; }`. Without this, paused CSS keyframes accumulate frames in the compositor queue while the tab is hidden; on tab return all 50+ executing nodes' triple-layer pulses + Cyber's full-viewport `cyber-flicker` / `cyber-roll` resume simultaneously, stalling the GPU compositor 100-200ms and blocking input dispatch (first-click-feels-frozen pattern). The unpause is deferred via `requestAnimationFrame` so input dispatch wins the frame before composite resumes.
+- **`data-page-hidden` animation pause** — `usePageActivitySync()` ([app/usePageActivitySync.ts](../client/src/app/usePageActivitySync.ts)), mounted once in [AppShell.tsx](../client/src/app/AppShell.tsx)'s `ShellEffects` so it covers both screens, listens to `visibilitychange` plus window `blur` / `focus` and toggles `data-page-hidden` on `<html>`; [base.css](../client/src/themes/base.css) declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important; }`. Without this, paused CSS keyframes accumulate frames in the compositor queue while the tab is hidden; on tab return all 50+ executing nodes' triple-layer pulses + Cyber's full-viewport `cyber-flicker` / `cyber-roll` resume simultaneously, stalling the GPU compositor 100-200ms and blocking input dispatch (first-click-feels-frozen pattern). The unpause is deferred two `requestAnimationFrame` ticks so input dispatch wins the frame before composite resumes.
- **Parameter panel theme contract** — MasterSkillEditor, OutputPanel, MiddleSection, ParameterPanel removed `useAppTheme()`. Every surface renders against Tailwind tokens + new-contract CSS custom props. Section headers carry the display-typography triplet (`font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)] text-fg-default`); action buttons use `<ActionButton intent="run|stop|save|config|tools">`; backgrounds use `bg-bg-elevated` / `bg-bg-panel` / `bg-bg-input` from the surface tier table above. EditableNodeLabel emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire under either topology. Per-theme scrollbar webkit rules (`::-webkit-scrollbar-thumb` etc.) declared in all 12 themes — gold (Renaissance), square-cornered (Atomic / Edo / Greek / Wasteland / Plague), metallic (Steampunk), phosphor (Rot), neon (Cyber), REC-red (Surveillance), shadcn neutral (Light / Dark).
- **Canvas-node class topology alignment** (W26) — TriggerNode, StartNode, ToolkitNode migrated from `.node` (rectangular spec-card) topology to `.sq-node` / `.sq-node-box` (square-icon node) topology so per-theme decorations (Steampunk brass rivets, Edo hanko seal, Surveillance REC LED, Renaissance gold emblem) reach them. Status pips, gear buttons, and React Flow handles on every node component now carry `.sq-node-pip` / `.sq-node-gear` / `.sq-node-handle.in/.out` (square nodes) or `.node-pip` / `.node-gear` / `.node-handle.in/.out` (rectangular nodes — AIAgentNode, TeamMonitorNode; the former `GenericNode` was retired with the spec-driven canvas). Pip background is data-driven via `data-status="idle | executing | waiting | success | error"` — base.css picks the colour from shadcn semantic tokens; per-theme files override. Inline JS-computed `backgroundColor` / `border` / `animation` on these elements stripped — CSS owns visuals. Cyber's `.node-trigger` rule extended to dual-target both rectangular and square topologies (`.sq-node.node-trigger .sq-node-box`). Orphan `.node-output` rule removed. EditableNodeLabel now emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire. StartNode reads `nodeColor` from `definition?.defaults?.color` instead of hardcoded `theme.dracula.cyan`.
- **Audio fix** (W20) — `--sound-pack: chime` typo in `light.css` + `dark.css` was silently falling through to `'none'` (`chime` not in the engine's pack registry), making sound silent for the most-used themes. Renamed `light` → `parchment`, `dark` → `terminal`. Added `Sounds.unlock()` exported from [lib/sound.ts](../client/src/lib/sound.ts) plus a one-shot `pointerdown / keydown / touchstart` capture-phase listener in `useSoundSync()` ([hooks/useSound.ts](../client/src/hooks/useSound.ts)) so the AudioContext resumes on the user's first gesture (Chrome / Safari autoplay policy compliance).
@@ -291,7 +291,7 @@ the surrounding chrome. Every other surface uses Tailwind + tokens. New themes c
- **ThemeProvider** ([client/src/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx)) — 12-way `ThemeName`, `DARK_FAMILY` ⊃ `{dark, cyber, wasteland, rot, surveillance, steampunk}`, legacy `darkMode` localStorage migration on first load
- **ThemeSwitcher** — DropdownMenu grouped into System / Utopian / Dystopian sections, all 12 themes
- **Tailwind v4 `@theme inline`** exposing new-contract utilities (`bg-bg-app`, `text-fg-default`, `border-border-default`, `font-display`, `font-body`, `rounded-pill`)
-- **Decorative wrappers** — Dashboard root carries `app-frame`, the React Flow host carries `canvas-host` (aliased as `canvas` so handoff selectors resolve), every Modal carries `modal-frame`. Per-theme CSS targets these classes for outer ornaments (gilded corners, scanlines, riveted borders, REC dot, etc.)
+- **Decorative wrappers** — the app shell root ([AppShell.tsx](../client/src/app/AppShell.tsx)) carries `app-frame`, the React Flow host carries `canvas-host` (aliased as `canvas` so handoff selectors resolve), every Modal carries `modal-frame`. Per-theme CSS targets these classes for outer ornaments (gilded corners, scanlines, riveted borders, REC dot, etc.)
- **Per-component structural classNames** (W15) — every chrome / interactive / canvas component carries the handoff selector co-class so per-theme decorative rules resolve without component-level branching. See [Per-component decorations](#per-component-decorations) for the full list.
- **Per-theme decorative CSS** (W16) — every per-component rule from `design_handoff_machinaos_themes/themes/*.css` is now ported into `client/src/themes/<theme>.css`. Each theme owns its panel textures, canvas decorations, node pseudo-element overlays, and keyframes. CSS bundle: 145 KB → 244 KB (+99 KB).
- **Selection state** (W17, shipped as part of W15) — every canvas node component carries the `selected` co-class when React Flow's `selected` prop is true, activating per-theme selection effects (cyber-blink on Cyber sq-nodes, hanko seal on Edo sq-nodes, etc.).
@@ -463,7 +463,7 @@ The hover delegate uses `mouseover` on capture phase + a `relatedTarget` filter
`patchToast()` wraps sonner's `toast.success` / `toast.error` once at module load; the guard flag prevents Strict-Mode double-wrap. `withSound(event, handler)` is the convenience HOC exported from [useSound.ts](../client/src/hooks/useSound.ts) for `run` / `save` semantics — fires the sound, then defers to the original handler.
Wiring summary:
-1. Mount `useSoundSync()` once at the Dashboard root — done in [Dashboard.tsx](../client/src/Dashboard.tsx).
+1. Mount `useSoundSync()` once at the app shell — done in [AppShell.tsx](../client/src/app/AppShell.tsx)'s `ShellEffects`, so it runs on both Home and the editor.
2. Settings panel ships an Audio section with a Switch bound to `useAppStore.soundEnabled`.
Adding a new sound event: extend `SoundEvent` in `lib/sound.ts`, add an entry per pack, fire `play('<event>')` from the handler.
@@ -521,7 +521,7 @@ cd client && bun run dev
1. `<html data-theme="light">` — clean default, near-white surfaces
2. `<html data-theme="dark">` — neutral slate + Dracula
3. `<html data-theme="renaissance">` — parchment, gold accents, Cinzel headings
-4. `<html data-theme="cyber">` — neon over void, JetBrains Mono everywhere
+4. `<html data-theme="cyber">` — neon over void, Space Mono headings, JetBrains Mono body + code
Build + typecheck must stay clean: