Skip to content

Self-improving AI Employees for everyone

docs(frontend): fix client architecture, theme, and panel doc drift

trohitgc0b1855efeae
diff --git a/client/src/test/README.md b/client/src/test/README.md
index 192926e8..28ae614d 100644
--- a/client/src/test/README.md
+++ b/client/src/test/README.md
@@ -7,17 +7,14 @@ Locks in the user-facing invariants from [docs-internal/ARCHIVE/credentials_pane
```bash
cd client
npm install # picks up the new devDependencies
-npm run test # watch mode
-npm run test:run # one-shot
+npm run test # one-shot (vitest run)
+npm run test:watch # watch mode
npm run test:coverage # with v8 coverage report
```
## Layout
-| File | Locks in |
-|---|---|
-| `src/hooks/__tests__/useApiKeys.test.ts` | Hook routes to the correct WebSocket message types with the right payload shapes; failure paths return `{isValid: false, error}` without throwing |
-| `src/components/__tests__/CredentialsModal.test.tsx` | Modal renders correctly for representative providers; click → WS message dispatch chain |
+51 test files live beside their subjects, almost all under `__tests__/` directories, across adapters/, assets/icons/, components/ (and its subfolders auth/, onboarding/, parameterPanel/, parameterPanel/canvas/, ui/), contexts/, hooks/, lib/, store/, stores/, types/, utils/. Targeted subsets: `npm run test:credentials`, `npm run test:nodepanels`.
## Tooling
diff --git a/docs-internal/design-system/guidelines/THEMES.md b/docs-internal/design-system/guidelines/THEMES.md
index f9e8655f..16ed11fc 100644
--- a/docs-internal/design-system/guidelines/THEMES.md
+++ b/docs-internal/design-system/guidelines/THEMES.md
@@ -8,10 +8,10 @@ Every theme is **one CSS file, zero component changes**. The system is layered s
1. **`base.css` — neutral defaults on `:root`.** Space scale, radii, motion durations/eases, `--type-uppercase: none`, `--canvas-grid: none`, `--sound-pack: none`, cursor defaults, plus the *default node visuals* (gradient fill, accent border, hover lift, the 3-layer `node-pulse` keyframe). Any theme that omits a variable inherits these.
2. **New-contract tokens — full-color CSS vars, scoped `:root[data-theme="X"]`.** The ~40-variable contract every theme must fill: surfaces (`--bg-app/panel/canvas/elevated/input/hover/active/overlay`), borders (`-default/strong/focus` + `--ornament-frame`), foreground (`--fg-default/muted/faint` + four `--fg-on-*` contrast colors), 3 font slots, type scale/tracking/case, 4 radii, 3 durations + 2 eases + `--motion-style`, `--sound-pack`, `--node-pulse-color`, 2 cursors, 2 scrollbar colors, `--canvas-grid` (+opacity).
-3. **shadcn HSL bridge — the same palette re-declared as HSL triplets** (`--background: 28 41% 12%`) so every existing Tailwind utility (`bg-card`, `text-muted-foreground`, `bg-action-save-soft`) retints with zero call-site edits. Includes the six action-intent triplets (with per-theme alphas — e.g. Steampunk raises soft fill to 20–22% because brass needs more presence than Dracula neon) and `--tint-soft`/`--tint-border` alphas.
+3. **shadcn semantic bridge — the same palette re-declared under the shadcn token names as hex / `color-mix()`** (`--background: #0d0f13`) so every existing Tailwind utility (`bg-card`, `text-muted-foreground`, `bg-action-save-soft`) retints with zero call-site edits. `index.css`'s `@theme inline` maps `--color-X: var(--X)` with no `hsl()` wrapper. Includes the six action-intent roles (with per-theme alphas — e.g. Steampunk raises soft fill to 20–22% because brass needs more presence than Dracula neon) and `--tint-soft`/`--tint-border` alphas.
4. **Structural-class decorations.** Components carry stable hook classes — `.toolbar .sidebar .palette .canvas .statusbar .chat .modal .cmdk .node .sq-node-box .sq-node-gear .sq-node-pip .sq-node-label .wf-card .comp .cat .row .btn .action-btn .pip .ornament` — and themes attach material identity to them: vellum noise + gilded `ornament-frame` (Renaissance), riveted brass plates with `::before/::after` rivets (Steampunk), CRT flicker + rolling scanline + glitch-on-hover keyframes (Cyber), REC-LED blink (Surveillance). Decorations are *additive*; un-themed components still work from layers 1–3.
-**Key inversions worth copying:** color is bridged *twice* (full-color for new code, HSL triplets for legacy utilities); status pips read `data-status` attributes so themes restyle state without touching React; the executing pulse uses a *theme-chosen* `--node-pulse-color` (not the node's own accent) so the glow always contrasts with that theme's canvas; `prefers-reduced-motion` and a `data-page-hidden` animation-pause are handled globally in base.css.
+**Key inversions worth copying:** color is bridged *twice* (full-color for new code, shadcn-named hex aliases for legacy utilities); status pips read `data-status` attributes so themes restyle state without touching React; the executing pulse uses a *theme-chosen* `--node-pulse-color` (not the node's own accent) so the glow always contrasts with that theme's canvas; `prefers-reduced-motion` and a `data-page-hidden` animation-pause are handled globally in base.css.
## 2. What a theme is allowed to change
@@ -42,7 +42,7 @@ Special hardware: **Cyber** ships custom crosshair + bracket cursors and full-fr
- **Light skins keep dark text contrast ratios** (vellum/marble/washi/linen ≈ #f0e8d0 family with near-black ink); dark skins pick one luminous accent family and use the soft-tint discipline from light/dark.
- **Radius is the loudest single lever**: 8 of 10 skins flatten to ≤4px or 0; only light/dark/atomic keep pills. Sharp corners + uppercase + serif/mono display = instant "other era".
- **Motion personality is encoded in the *easing function*, not just speed**: `steps(4)` = digital strobe, `cubic-bezier(.34,1.6,.5,1)` = boomerang bounce, `linear` = machine scan, 680ms drift = crypt.
-- **The HSL bridge is the cost of Tailwind compat** — every theme declares its palette twice. New work should target the full-color contract only.
+- **The shadcn alias layer is the cost of Tailwind compat** — every theme declares its palette twice (new-contract names + shadcn names), both in hex. New work should target the full-color contract only.
## 5. Status in THIS design system
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index f6f63bea..e52702c9 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -2,7 +2,7 @@
Post-migration (2026-04-14). Single source of truth for the current frontend.
-> The pre-migration audit / research / RFC docs (`frontend_architecture_analysis.md`, `frontend_component_functionality_and_design.md`, `frontend_system_design_rfc.md`, `frontend_ui_framework_research.md`, `frontend_ui_stack_recommendation.md`) were deleted on 2026-04-14 — they're preserved in git history under commit `4cb3dd9` if you ever need to reference them. The migration log lives at [ui_migration_plan.md](./ui_migration_plan.md).
+> The pre-migration audit / research / RFC docs (`frontend_architecture_analysis.md`, `frontend_component_functionality_and_design.md`, `frontend_system_design_rfc.md`, `frontend_ui_framework_research.md`, `frontend_ui_stack_recommendation.md`) were deleted on 2026-04-14 — they're preserved in git history under commit `4cb3dd9` if you ever need to reference them. The migration log lives at [ui_migration_plan.md](./ARCHIVE/ui_migration_plan.md).
## TL;DR
@@ -64,12 +64,16 @@ client/src/
│ │ ├── alert.tsx # + success/warning/info variants we added
│ │ ├── accordion.tsx # Radix accordion
│ │ ├── dialog.tsx # Radix dialog (Modal.tsx re-exports via thin wrapper)
-│ │ ├── popover.tsx / tooltip.tsx / dropdown-menu.tsx
+│ │ ├── tooltip.tsx / dropdown-menu.tsx
│ │ ├── select.tsx # Radix select (no search; grouped items via SelectGroup/SelectLabel)
│ │ ├── input.tsx / textarea.tsx / switch.tsx / checkbox.tsx / label.tsx / slider.tsx
│ │ ├── collapsible.tsx / tabs.tsx / alert-dialog.tsx / card.tsx / progress.tsx
│ │ ├── form.tsx # react-hook-form + FormField/FormItem/FormControl/FormMessage
-│ │ └── sonner.tsx # Patched to read ThemeContext (not next-themes)
+│ │ ├── sonner.tsx # Patched to read ThemeContext (not next-themes)
+│ │ ├── ApiKeyInput.tsx # Composite: input + eye toggle + save/delete buttons
+│ │ ├── SettingsPanel.tsx # Shadcn Switch + Slider + Input
+│ │ ├── ConsolePanel.tsx # Chat + console + terminal + output
+│ │ └── TopToolbar.tsx # File menu + model picker + action buttons
│ │
│ ├── Modal.tsx (src/components/ui/Modal.tsx)
│ │ # Thin wrapper over shadcn Dialog; preserves the pre-migration
@@ -115,19 +119,12 @@ client/src/
│ │
│ ├── onboarding/
│ │ ├── OnboardingWizard.tsx # Custom step indicator (no antd Steps)
-│ │ └── steps/*.tsx # Welcome / Concepts / ApiKey / Canvas / GetStarted
-│ │
-│ ├── ui/
-│ │ ├── ApiKeyInput.tsx # Composite: input + eye toggle + save/delete buttons
-│ │ ├── SettingsPanel.tsx # Shadcn Switch + Slider + Input
-│ │ ├── ConsolePanel.tsx # Chat + console + terminal + output
-│ │ ├── Modal.tsx # Shadcn Dialog wrapper
-│ │ ├── NodeOutputPanel.tsx # Deleted (superseded by output/OutputPanel)
-│ │ └── TopToolbar.tsx # File menu + model picker + action buttons
+│ │ ├── GetStartedChecklist.tsx # Post-wizard checklist
+│ │ └── steps/ # WelcomeStep / HowItWorksStep / ConnectAIStep / TryItStep
│ │
│ ├── icons/ # AI provider icons (SVG data URIs)
│ ├── auth/ # Login page + protected route
-│ ├── SquareNode.tsx, StartNode.tsx, TriggerNode.tsx, GenericNode.tsx, AIAgentNode.tsx, WhatsAppNode.tsx, ModelNode.tsx
+│ ├── SquareNode.tsx, StartNode.tsx, TriggerNode.tsx, AIAgentNode.tsx, ToolkitNode.tsx, TeamMonitorNode.tsx
│ │ # React Flow nodes with lucide icons
│ └── APIKeyValidator.tsx # Shadcn Input + Button + Tooltip composition
│
@@ -154,12 +151,6 @@ client/src/
│ ├── useAppStore.ts # UI state (sidebar, palette, pro mode, persisted)
│ └── useCredentialRegistry.ts # UI-only: selectedId + paletteOpen + query
│
-├── lib/
-│ ├── queryClient.ts # Module-singleton QueryClient so imperative
-│ │ # code (Zustand actions) can invalidate without
-│ │ # going through React context.
-│ └── utils.ts # cn() = clsx + tailwind-merge (shadcn convention)
-│
├── styles/
│ └── theme.ts # `lightColors` / `darkColors` base packs +
│ # `dracula` / `solarized` constants. Read
@@ -177,11 +168,26 @@ client/src/
│
├── adapters/
│ └── nodeSpecToDescription.ts # Backend NodeSpec -> legacy INodeTypeDescription shape
+├── assets/icons/ # NodeIcon.tsx + themedGlyphs.ts + icon-ref resolver (index.ts)
+├── config/api.ts # Backend base-URL config (env-driven)
├── lib/
│ ├── nodeSpec.ts # TanStack-Query spec fetch, resolveNodeDescription, listCachedNodeSpecs
│ ├── aiModelProviders.ts # Frontend-only AI provider icon/credential map
-│ ├── queryClient.ts / queryConfig.ts / featureFlags.ts
-│ └── utils.ts
+│ ├── queryClient.ts # Module-singleton QueryClient (imperative invalidation without React context)
+│ ├── queryConfig.ts / featureFlags.ts
+│ ├── queryPersist.ts # localStorage persister + PERSISTED_KEY_PREFIXES whitelist
+│ ├── brandStorage.ts # Canonical browser-storage keys + pre-rebrand aliases
+│ ├── connectionConfig.ts # WS reconnect + auth-bootstrap backoff constants
+│ ├── workflowOps.ts # applyOperations for backend workflow-ops batches
+│ ├── canvasLock.ts # Server-owned can_edit capability -> canvas lock
+│ ├── sound.ts # WebAudio sound engine (10 packs)
+│ └── utils.ts # cn() = clsx + tailwind-merge (shadcn convention)
+├── schemas/workflowSchema.ts # Structural pre-flight for workflow export (backend is the schema authority)
+├── stores/
+│ ├── nodeStatusStore.ts # Per-workflow node statuses (slice-subscribed Zustand)
+│ └── canvasDockStore.ts # Docked Canvas sidebar state
+├── test/ # Vitest setup.ts, builders.ts, providers.tsx, README.md
+├── themes/ # base.css + animations.css + 12 per-theme CSS files
├── types/ # INodeProperties, NodeTypes, etc.
└── utils/ # formatters, apiKeySecurity, workflowExport, parameterSanitizer
```
@@ -357,13 +363,13 @@ components/credentials/CredentialsModal.tsx
- **DB is the single source of truth.** The retired `providers.tsx` static fallback is gone — `useCatalogueQuery` is the only source. Cold-boot with no IDB cache renders a `<Skeleton>` palette while the WS catalogue arrives; server-unreachable shows an explicit error state, never stale fallback data.
- **`provider.stored` is the canonical "do we have a credential for X?".** The retired `apiKeyStatuses[id].hasKey` mirror duplicated this answer with no synchronisation contract. Two new selector hooks (`useProviderStored(id)`, `useStoredProviderCount()`) read the catalogue. `apiKeyStatuses[id]` now narrowly carries the validation result (`valid`, `models`, `message`, `timestamp`).
-**App-wide query persistence ([client/src/lib/queryPersist.ts](../client/src/lib/queryPersist.ts)):** the QueryClient is wrapped in `<PersistQueryClientProvider>` ([main.tsx](../client/src/main.tsx)) with a localStorage persister + `__APP_VERSION__` buster + 24h SWR window. Only queries with key prefixes `nodeSpec` / `nodeGroups` / `skillContent` are dehydrated -- high-frequency / per-session queries stay in-memory. Hard refresh paints from cached specs **before** the WebSocket connects, so canvas nodes never flash placeholder icons. The credentials catalogue uses its own dedicated `idb-keyval` warm-start (above) because its payload is large enough that localStorage's 5-10MB cap is a real constraint. **Decrypted credential values are NOT persisted** (was the retired `'credentialValues'` prefix) per OWASP HTML5 Security Cheat Sheet / ASVS V9.9 — plaintext API keys in `localStorage` are readable via DevTools on shared / compromised browsers; the in-memory TanStack Query cache (`gcTime: ∞`) keeps the form populated for the session lifetime, on reload the panel refetches via WS.
+**App-wide query persistence ([client/src/lib/queryPersist.ts](../client/src/lib/queryPersist.ts)):** the QueryClient is wrapped in `<PersistQueryClientProvider>` ([main.tsx](../client/src/main.tsx)) with a localStorage persister + `__APP_VERSION__` buster + 24h SWR window. Only queries with key prefixes `nodeSpec` / `nodeGroups` are dehydrated -- high-frequency / per-session queries stay in-memory. Hard refresh paints from cached specs **before** the WebSocket connects, so canvas nodes never flash placeholder icons. The credentials catalogue uses its own dedicated `idb-keyval` warm-start (above) because its payload is large enough that localStorage's 5-10MB cap is a real constraint. **Decrypted credential values are NOT persisted** (was the retired `'credentialValues'` prefix) per OWASP HTML5 Security Cheat Sheet / ASVS V9.9 — plaintext API keys in `localStorage` are readable via DevTools on shared / compromised browsers; the in-memory TanStack Query cache (`gcTime: ∞`) keeps the form populated for the session lifetime, on reload the panel refetches via WS.
**`useNodeSpec` is a slice subscription, not a `useQuery`** ([client/src/lib/nodeSpec.ts](../client/src/lib/nodeSpec.ts)): reads via `useSyncExternalStore` filtered by `hashKey(['nodeSpec', type])`. Per-spec observer count is **0**; only the matching slot triggers a re-render. Lazy fetch is one-shot via `useEffect` gated on `isReady`. Do not re-introduce `useQuery(['nodeSpec', type])` -- N consumers create N observers, all woken on every cache write.
**Slice-subscribed cache entries MUST set `gcTime: GC_TIME.FOREVER`.** Slice subscribers don't register as TanStack observers, so without this override the cache entry is garbage-collected after the default `gcTime` (5 min) and every consumer reads `undefined`. The user-visible regression is "canvas nodes lose their icons / handles after idle." Applies to `fetchNodeSpec`, `fetchNodeGroups`, and the `useNodeGroups` `useQuery`; the persistor in `lib/queryPersist.ts` only handles cross-reload survival.
-**Anchor cache contracts at the prefix root via `setQueryDefaults`, not per-call options.** `PersistQueryClientProvider` hydrates entries from localStorage with the QueryClient's *default* options, so per-call `staleTime: FOREVER` does not stop `gcTime: 5min` eviction on hydration. Every persisted prefix must have a matching `queryClient.setQueryDefaults(['<prefix>'], { staleTime: FOREVER, gcTime: FOREVER })` declaration in [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts). The current canonical set is `['nodeSpec']`, `['nodeGroups']`, `['skillContent']`. The persistor whitelist in [client/src/lib/queryPersist.ts](../client/src/lib/queryPersist.ts) must mirror it; a string in the whitelist that doesn't match a real query key (the prior `'pluginCatalogue'` typo) is silently dead. `credentialCatalogue` is intentionally NOT in either list — it has its own `idb-keyval` warm-start. `credentialValues` keeps `gcTime: FOREVER` for the in-memory cache so the credentials form survives idle, but it is intentionally NOT persisted (OWASP — see "Persistence layers" above).
+**Anchor cache contracts at the prefix root via `setQueryDefaults`, not per-call options.** `PersistQueryClientProvider` hydrates entries from localStorage with the QueryClient's *default* options, so per-call `staleTime: FOREVER` does not stop `gcTime: 5min` eviction on hydration. Every persisted prefix must have a matching `queryClient.setQueryDefaults(['<prefix>'], { staleTime: FOREVER, gcTime: FOREVER })` declaration in [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts). The persisted set is `['nodeSpec']`, `['nodeGroups']`; both carry `setQueryDefaults`. `['skillContent']` and `['credentialValues']` carry `setQueryDefaults` for in-memory longevity only and are intentionally absent from the persistor whitelist. The persistor whitelist in [client/src/lib/queryPersist.ts](../client/src/lib/queryPersist.ts) must mirror it; a string in the whitelist that doesn't match a real query key (the prior `'pluginCatalogue'` typo) is silently dead. `credentialCatalogue` is intentionally NOT in either list — it has its own `idb-keyval` warm-start. `credentialValues` keeps `gcTime: FOREVER` for the in-memory cache so the credentials form survives idle, but it is intentionally NOT persisted (OWASP — see "Persistence layers" above).
**Component rules:**
- `PanelRenderer` lazy-loads each panel type so the initial JS payload doesn't grow linearly with provider count.
@@ -376,7 +382,7 @@ Currently a 2152-line switch on `parameter.type` ([client/src/components/Paramet
**Phase 6 plan:** replace with `@jsonforms/react` renderer registry. Requires backend to expose a `get_node_spec` WebSocket handler returning `NodeSpec { jsonSchema, uiSchema, _uiHints? }` per the RFC. Frontend will own the custom renderer set (one file per widget under `components/inspector/renderers/`) and route via JSON Forms' tester-based dispatch. Feature flag `VITE_USE_NODESPEC` gates the rollout; the old `ParameterRenderer` deletes once stable.
-See [ui_migration_plan.md](./ui_migration_plan.md) Phase 6.
+See [ui_migration_plan.md](./ARCHIVE/ui_migration_plan.md) Phase 6.
### Name-based magic in this file (read before naming a Params field)
@@ -458,7 +464,8 @@ See [media_transport.md](./media_transport.md).
Simple Memory parameters are refreshed from the backend's cleared-row
broadcast, and `compactionStats` caches are evicted. The old transcript stays
available only through the archived generation. See
- [Memory Lifecycle](memory_lifecycle.md#workflow-reset-archives-then-clears-memory).
+ [Memory Lifecycle](ARCHIVE/memory_lifecycle.md#workflow-reset-archives-then-clears-memory)
+ (archived; it describes the retired pre-RFC-0002 markdown memory model).
- **`currentWorkflowId` lives in `useAppStore` only.** Non-React listeners (WS handlers) read it via `useAppStore.getState().currentWorkflow?.id` -- the documented Zustand escape hatch (https://github.com/pmndrs/zustand#read-state-without-subscription). The previous `currentWorkflowIdRef` mirror inside WebSocketContext was a one-render-late copy that misrouted broadcasts during workflow switches. The push to `nodeStatusStore.setCurrentWorkflowId` is driven from a single `useEffect` in `Dashboard.tsx`.
## Ownership boundary: TanStack Query vs Zustand vs WebSocketContext
@@ -470,7 +477,7 @@ This is the rule that keeps the data layer schema-driven instead of imperatively
| **TanStack Query** | Anything the server has authoritative state for. List / single-record / settings reads. Mutations that change server state. | `useWorkflowsQuery`, `useNodeParamsQuery`, `useUserSettingsQuery`, `useCatalogueQuery`, `useSaveWorkflowMutation`, `useSaveNodeParamsMutation`, `useSaveUserSettingsMutation` |
| **Zustand** | UI-only state that survives navigation. The active edit buffer for the current workflow. Sidebar/panel visibility flags. | `useAppStore.currentWorkflow` (mutable buffer), `sidebarVisible`, `proMode`, `renamingNodeId`, `useCredentialRegistry.selectedId` |
| **`useState` / `useReducer`** | Per-component transient state. Form-field drafts. Hover/focus. | text-input drafts, dropdown-open, inline-edit toggles |
-| **`WebSocketContext`** | Raw WS connection, `sendRequest`, push-only broadcast slices (workflow progress, android/whatsapp/twitter status, console/terminal logs). The provider value is `useMemo`'d so unrelated state changes do not re-render every consumer. Exposes `isOpen` (socket open) and `isReady` (post init-burst) -- gate catalogue/spec queries on `isReady`. The init burst now runs **in parallel** via `Promise.allSettled` over named helpers (`probeApiKey`, `loadTerminalLogs`, `loadChatHistory`, `loadConsoleLogs`), each backed by a small `sendBurstRequest` factory that owns its own request id, message handler, and 5 s timeout. `drainPendingSends(ws)` still runs synchronously after the await and before `setIsReady(true)` so the queue replay ordering is preserved. Time-to-`isReady` is one wide round-trip rather than 8 sequential ones. Catalogue invalidation routes through `invalidateCatalogue(queryClient)` ([`hooks/useCatalogueQuery.ts`](../client/src/hooks/useCatalogueQuery.ts)) which debounces the refetch on a 300 ms trailing edge, so an oauth burst or multi-service reconnect collapses to one refetch instead of N. | `androidStatus`, `consoleLogs`, broadcast streams |
+| **`WebSocketContext`** | Raw WS connection, `sendRequest`, push-only broadcast slices (workflow progress, android/whatsapp/twitter status, console/terminal logs). The provider value is `useMemo`'d so unrelated state changes do not re-render every consumer. Exposes `isConnected` (socket open) and `isReady` (open + pending-send queue drained); gate catalogue/spec queries on `isReady`. `drainPendingSends(ws)` runs synchronously, then `setIsReady(true)` fires immediately; terminal/chat/console history restore is fire-and-forget in the background (Wave 32 removed the init-burst gate and the hardcoded `probeApiKey` loop). Catalogue invalidation routes through `invalidateCatalogue(queryClient)` ([`hooks/useCatalogueQuery.ts`](../client/src/hooks/useCatalogueQuery.ts)) which debounces the refetch on a 300 ms trailing edge, so an oauth burst or multi-service reconnect collapses to one refetch instead of N. | `androidStatus`, `consoleLogs`, broadcast streams |
| **`stores/nodeStatusStore.ts`** (Zustand) | Per-workflow node-execution statuses -- moved out of WebSocketContext so a status tick does not cascade through the React tree. `useNodeStatus(id)` is a slice selector; only the affected node's consumers re-render. Mirror this pattern for any new high-frequency push state. | `allStatuses[workflowId][nodeId]`, `currentWorkflowId` |
**Hard rules:**
@@ -479,7 +486,7 @@ This is the rule that keeps the data layer schema-driven instead of imperatively
- Imperative WebSocket request/response inside a component (`useEffect` + `sendRequest` + `setState`) is a code smell — wrap it in a `useQuery` hook. Inline the hook at the top of the consuming file when there's exactly one consumer (Wave 2/3 colocation rule); promote to `client/src/hooks/` when a second consumer appears. Phase-2 commit `b2b6fba` did this for `useParameterPanel` and `useOnboarding`; Wave 3 commits `2c5f227` / `7706afb` / `327f792` followed the same pattern inline inside MiddleSection / MasterSkillEditor / InputSection.
- After a mutation, **invalidate the corresponding query key**, don't manually patch a Zustand list or call a local refetch helper. Mutations that need it from non-React code use the `queryClient` singleton at [client/src/lib/queryClient.ts](../client/src/lib/queryClient.ts).
- Schema metadata for parameter behavior (selectors, validators, dynamic options) belongs in the node-definition `typeOptions`, NOT in `parameter.name === '...'` checks inside `ParameterRenderer`. Phase-5 commit `8353c48` introduced `typeOptions.loadOptionsMethod` for the WhatsApp selectors as the canonical pattern.
-- **Runtime output shapes for the Input panel's variable list live on the backend** via Pydantic models in `server/services/node_output_schemas.py`. The frontend fetches them lazy via `get_node_output_schema`; real execution data takes precedence. See the "Node output shape" section below and [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md).
+- **Runtime output shapes for the Input panel's variable list live on the backend** via Pydantic models in `server/services/node_output_schemas.py`. The frontend fetches them lazy via `get_node_output_schema`; real execution data takes precedence. See the "Node output shape" section below and [schema_source_of_truth_rfc.md](./ARCHIVE/schema_source_of_truth_rfc.md).
- **Never hand-roll a modal backdrop.** Destructive confirmations use `<AlertDialog>`; composite panels use the `Modal.tsx` primitive on top of shadcn `<Dialog>`. A raw `position: fixed; background: rgba(0,0,0,0.5)` in new code should not pass review.
## Schema-driven node + panel hints
@@ -488,7 +495,7 @@ Wave 2 introduced two typed fields on `INodeTypeDescription` so panels and the i
### `uiHints` — per-node panel visibility flags
-Defined on `INodeTypeDescription.uiHints` ([client/src/types/INodeProperties.ts](../client/src/types/INodeProperties.ts)). Each flag is consumed by exactly one panel and defaults to off (the panel renders normally). The current set (live list = the `known` set in `test_node_spec.py`):
+Defined on `INodeTypeDescription.uiHints` ([client/src/types/INodeProperties.ts](../client/src/types/INodeProperties.ts)). Each flag is consumed by exactly one panel and defaults to off (the panel renders normally). The current set (the backend `known` set in `server/tests/test_node_spec.py` must match `INodeUIHints`; a flag with no frontend consumer is dead weight and gets removed from both):
| Flag | Read by | Effect |
|---|---|---|
@@ -500,9 +507,9 @@ Defined on `INodeTypeDescription.uiHints` ([client/src/types/INodeProperties.ts]
| `isMemoryPanel` | `MiddleSection` | **Legacy.** The pre-RFC-0002 combined markdown/transcript panel. `simpleMemory` no longer declares it; kept while `normalize_workflow_graph` upgrades `input-memory` graphs |
| `isMemoryToolPanel` | `MiddleSection` | Render the durable Memory item browser (search, edit, forget, clear). Declared by `simpleMemory`, and selected *before* `isMemoryPanel` |
| `isContextPanel` | `MiddleSection` | Render the Context inspector (journal, active replay, fork/export/clear). Read-only: it observes the agent's journal and must never alter execution |
+| `isDataPanel` | `MiddleSection` | Render the Data node's mounts + read-only file browser (`DataPanel`). Declared by `dataSource`. |
| `requiresContext` | backend graph normalization | Declared in `STD_AGENT_HINTS`. Not a rendering flag — `normalize_workflow_graph` pairs every plugin carrying it with a Context companion, and `workflow_validator` enforces the topology |
| `systemManaged` | canvas | Marks the auto-created Context companion. The backend owns its lifecycle; the user does not add or delete it directly |
-| `isToolPanel` | `MiddleSection` | Surface the ToolSchemaEditor for connected services |
| `isMonitorPanel` | `MiddleSection`, `ParameterPanel` | Render the team-monitor panel |
| `isTodoEditor` | `MiddleSection` | Render the editable Current Todos manager (`writeTodos`) instead of the plain params list |
| `isTaskManagerPanel` | `MiddleSection` | Render the execution-scoped team task control panel |
@@ -510,7 +517,6 @@ Defined on `INodeTypeDescription.uiHints` ([client/src/types/INodeProperties.ts]
| `isGalleryPanel` | `MiddleSection` | Render the workspace file browser (breadcrumbs, grid/list, search, preview, upload, drag-to-parameter) instead of the plain params list. Declared by `gallery`, which pairs it with `hideInputSection` but **keeps** the Output section — unlike `processManager` it produces output worth seeing and dragging. The panel writes back to the node's own `path` / `selection` params, so what you browse is what the node emits. |
| `isCanvasPanel` | `MiddleSection`, `CanvasDock` | Render the pushed-content Canvas board instead of the plain params list. Declared by `canvas`. Double duty: the docked canvas sidebar also uses this flag to FIND Canvas nodes in the graph (`resolveNodeDescription(type)?.uiHints?.isCanvasPanel`) — never the type string. Pairs with an explicit `isConfigNode: False` because the `tool` group would auto-derive `True` while the node's `input-main` is real dataflow. See [canvas_node.md](./canvas_node.md). |
| `showLocationPanel` | `LocationParameterPanel` | Special-case panel for nodes with map preview |
-| `isAndroidToolkit` | `ToolSchemaEditor` | Toolkit aggregator (Android service hub) |
| `isChatTrigger` | `ConsolePanel` | This node is a chat-message target |
| `isConsoleSink` | `ConsolePanel` | This node consumes console output (filter source) |
| `hasSkills` | Agent panels | Connect the connected-skills section |
@@ -570,7 +576,7 @@ Frontend does **not** declare output shapes anymore. The backend owns them exclu
2. Backend-declared schema fetched on demand (fallback).
3. `{ data: 'any' }` empty state (final fallback — the legacy `sampleSchemas` map was deleted in Wave 3).
-**Adding a new node type's output shape:** define a Pydantic model in `node_output_schemas.py`, register it in `NODE_OUTPUT_SCHEMAS`. The frontend picks it up automatically — no client change, no rebuild. Research and rationale in [docs-internal/schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md).
+**Adding a new node type's output shape:** define a Pydantic model in `node_output_schemas.py`, register it in `NODE_OUTPUT_SCHEMAS`. The frontend picks it up automatically — no client change, no rebuild. Research and rationale in [docs-internal/schema_source_of_truth_rfc.md](./ARCHIVE/schema_source_of_truth_rfc.md).
**`jsonSchemaToShape` must resolve Pydantic's indirection.** `model_json_schema()` does not emit a flat `{field: {type}}` map: `Optional[X]` becomes `{anyOf: [<X>, {type: 'null'}]}` with **no top-level `type`**, and a nested `BaseModel` becomes `{$ref: '#/$defs/Name'}` with the body in `$defs`. A reader that only inspects `prop.type` types both as `'any'`. Since every field on the trigger output models is Optional, that mistyped *every* field and left nested blocks (`telegramReceive.media`, `whatsappReceive.group_info`) with no drillable leaves — the useful drag target is `media.file_id`, not `media`. `resolveSchemaNode` unwraps unions (first non-null branch) and follows local `#/$defs/` pointers, threading the expanded-ref chain through the mutual recursion so a self-referencing model cannot recurse until the stack blows and takes the panel with it. Locked by [jsonSchemaToShape.test.ts](../client/src/components/parameterPanel/__tests__/jsonSchemaToShape.test.ts).
@@ -628,7 +634,7 @@ The `OPENCOMPANY_INSTALLING=true` env var suppresses the recursive project posti
## Migration history (for context)
-This architecture is the post-migration state. Pre-migration was antd + `styled-components` + a custom theme.ts-driven palette. See [ui_migration_plan.md](./ui_migration_plan.md) for the phase-by-phase transition and the 17 commits that executed it.
+This architecture is the post-migration state. Pre-migration was antd + `styled-components` + a custom theme.ts-driven palette. See [ui_migration_plan.md](./ARCHIVE/ui_migration_plan.md) for the phase-by-phase transition and the 17 commits that executed it.
**`useAppTheme()` powers the canvas + maps surface across all 12 themes.** The hook returns a `theme` object with the legacy `Colors` shape (`theme.colors.X`, `theme.isDarkMode`) so existing call sites don't change. Under non-light/dark themes it merges a per-theme overlay (primary, focus, action palette, edge stroke / selection / executing / completed / error) on top of the chosen base pack (`lightColors` for utopian-bright themes, `darkColors` for dystopian / dark themes). Adding a new theme overlay is a single entry in the `THEME_OVERRIDES` map in [hooks/useAppTheme.ts](../client/src/hooks/useAppTheme.ts).
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index efd9f5c4..7518c816 100644
--- a/docs-internal/node_allowlist.md
+++ b/docs-internal/node_allowlist.md
@@ -60,7 +60,7 @@ Re-enable: drop the entries. The hook + filters are forward-compatible with empt
## What's currently disabled
-Nothing is blocklisted. All four disable lists (`disabled_groups`, `disabled_nodes`, `disabled_credential_categories`, `disabled_skill_folders`) are empty in the shipped `server/config/node_allowlist.json`; the `email` group + credential category that this section once listed as disabled are no longer blocked. The only active list is `enabled_nodes` — the positive allowlist that decides what normal mode shows (dev/pro mode bypasses it). Read the live entry count from the JSON rather than from this doc (51 at the time of writing).
+Nothing is blocklisted. All four disable lists (`disabled_groups`, `disabled_nodes`, `disabled_credential_categories`, `disabled_skill_folders`) are empty in the shipped `server/config/node_allowlist.json`; the `email` group + credential category that this section once listed as disabled are no longer blocked. The only active list is `enabled_nodes` — the positive allowlist that decides what normal mode shows (dev/pro mode bypasses it). Read the live entry count from the JSON rather than from this doc.
Android service nodes are enabled and connect directly to an agent's
`input-tools` handle. The Android Agent, Android credential category, and
diff --git a/docs-internal/node_panels.md b/docs-internal/node_panels.md
index b8eb1fec..b0e1eab2 100644
--- a/docs-internal/node_panels.md
+++ b/docs-internal/node_panels.md
@@ -161,7 +161,7 @@ isn't already present in `executionResults` (deduplicated via `JSON.stringify`).
than `success`/`error` (e.g. `running`) are ignored.
Rendering lives in [client/src/components/output/OutputPanel.tsx](../client/src/components/output/OutputPanel.tsx)
-(the active renderer — `ui/OutputDisplayPanel.tsx` is legacy and unimported). The Response
+(the active and only renderer; the former `ui/OutputDisplayPanel.tsx` was deleted). The Response
section picks, in order: `response` / `output` / `text` / `content` (prose keys), then an
object-typed `result` (the canonical payload key CLI nodes fill with server-side-parsed JSON —
arrays survive `unwrap` un-peeled and surface here), then `stdout`. Objects/arrays render in the
@@ -210,8 +210,8 @@ Locked in by the test suite at:
```bash
cd client
npm install
-npm run test:run -- src/hooks/__tests__/useDragVariable.test.ts \
- src/components/parameterPanel/__tests__
+npm run test -- src/hooks/__tests__/useDragVariable.test.ts \
+ src/components/parameterPanel/__tests__
```
Or use the dedicated script (added in `client/package.json`):
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 4a2e4765..77c842bd 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -229,7 +229,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.
-- **Parameter panel theme contract** — MasterSkillEditor, OutputPanel, MiddleSection, ToolSchemaEditor, 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).
+- **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).
- **Canvas-node visual contract** (W21) — every node component (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`; `GenericNode` at the time, since retired) stripped its inline `background` / `border` / `borderRadius` / `boxShadow` / `animation` props. Each now exposes the per-definition accent hex via `style={{ '--node-color': accentColor }}` on its outer wrapper. Visual styling lives in [base.css](../client/src/themes/base.css) defaults + per-theme overrides; `var(--node-color)` carries the plugin's `visuals.json` accent through CSS without fighting specificity. New `NodeStyle` helper type in [client/src/types/NodeTypes.ts](../client/src/types/NodeTypes.ts) (`React.CSSProperties & Record<\`--${string}\`, string | number>`) makes the inline custom-prop typecheck-clean.
@@ -249,7 +249,7 @@ the surrounding chrome. Every other surface uses Tailwind + tokens. New themes c
- **Success is a moment, not a state** — terminal node statuses persist in `nodeStatusStore` until the next run, so the static `--success` ring/stroke on `.react-flow__node.completed` (base.css) and `.react-flow__edge.completed` (styles/canvasAnimations.ts) previously left every completed agent/tool node and traversed edge glowing green indefinitely. Both are now one-shot fades (`node-completed-fade` in animations.css / `edgeCompletedFade`): hold the success token briefly, then settle back to the resting border/stroke. `prefers-reduced-motion` keeps the static ring (legible outcome, no motion). Error states deliberately stay painted until acted on.
- **Reduced-motion accessibility** (W19) — `@media (prefers-reduced-motion: reduce)` block in [client/src/themes/base.css](../client/src/themes/base.css) disables every keyframe across all themes. See [Reduced motion](#reduced-motion).
- **Sound throttling** (W19) — `type` and `hover` events throttled to a 30 ms last-fire window inside the engine to prevent OscillatorNode flooding. See [Throttling](#throttling).
-- **Migrated chrome**: TopToolbar, WorkflowSidebar, ComponentPalette + ComponentItem + CollapsibleSection, ConsolePanel chrome, SettingsPanel, Modal, ParameterPanel modal title, AIResultModal title, OutputDisplayPanel title, InputSection title
+- **Migrated chrome**: TopToolbar, WorkflowSidebar, ComponentPalette + ComponentItem + CollapsibleSection, ConsolePanel chrome, SettingsPanel, Modal, ParameterPanel modal title, AIResultModal title, InputSection title
- **New shell components**: StatusBar (fixed-bottom system line with WS connection / workflow / theme / clock), CommandPalette (`⌘K`), CommandPaletteHost (canonical command list with Workflow / Run / Open / View / Theme groups)
- **Google Fonts** — deferred-load `<link>` covers all 12 themes' typefaces (Cinzel, Cormorant Garamond, IM Fell English / SC, JetBrains Mono, VT323, Shippori Mincho, Sawarabi Mincho, Special Elite, Bevan, Lato, Pirata One, EB Garamond, Anonymous Pro, IBM Plex Mono, Courier Prime, Space Mono). Major Mono Display + UnifrakturCook were trimmed from the URL when the legibility substitutions landed (Cyber → Space Mono, Plague → Cinzel).
- **Sound contract** — [client/src/lib/sound.ts](../client/src/lib/sound.ts) ports the upstream WebAudio engine with all 10 packs (`parchment`, `marble`, `ink`, `clockwork`, `vibraphone`, `terminal`, `scrap`, `crypt`, `bell`, `telex`). [client/src/hooks/useSound.ts](../client/src/hooks/useSound.ts) reads `--sound-pack` from `:root` on theme change and mirrors the `soundEnabled` Zustand slice into `Sounds.setEnabled()`. Settings panel ships the toggle (Audio section). Persists to `localStorage['opencompany-sound']`; **default ON** (browsers gesture-gate WebAudio without a separate permission API — the AudioContext starts suspended and resumes on the user's first pointerdown / keydown / touchstart via `Sounds.unlock()`, registered as a one-shot capture-phase listener in `useSoundSync()`).
@@ -258,7 +258,7 @@ the surrounding chrome. Every other surface uses Tailwind + tokens. New themes c
### Deferred (future PRs)
- **`--*-soft` token family** — RESOLVED (theme fidelity pass): `--info-soft` / `--success-soft` / `--warning-soft` / `--danger-soft` (plus the `--danger` alias for `--destructive`) are now declared in `base.css` `:root` as `color-mix(in srgb, var(--X) var(--tint-semantic-soft), transparent)` with `--tint-semantic-soft: 15%` on the shared tint scale. The ~24 theme-rule references (greek, plague, rot, atomic, wasteland, surveillance) that previously computed to invalid-and-transparent now render their intended tinted fills. Themes may override any of them.
- **Edo / Steampunk / Atomic canvas-host pseudo-element decorations** — these themes' richer canvas overlays (Edo radial-gradient ink-wash mountain, Steampunk corner radial accents, Atomic dot constellation) are pseudo-element decorations rather than tileable `--canvas-grid` patterns; W24 ported the tileable layer only. Wire via `.canvas::before/::after` rules in a future pass if needed.
-- **Parameter panel internals** — RESOLVED: `ParameterRenderer`, `MiddleSection`, `MasterSkillEditor`, `ToolSchemaEditor` are fully on shadcn primitives + tokens (zero `useAppTheme` / `theme.colors`); section headers carry the display-typography triplet. The panel modal also picks up per-theme `.modal` / `.modal-head` / `.modal-title` decoration via `Modal.tsx`.
+- **Parameter panel internals** — RESOLVED: `ParameterRenderer`, `MiddleSection`, `MasterSkillEditor` are fully on shadcn primitives + tokens (zero `useAppTheme` / `theme.colors`); section headers carry the display-typography triplet. The panel modal also picks up per-theme `.modal` / `.modal-head` / `.modal-title` decoration via `Modal.tsx`.
- **Credentials modal sub-panels** — `OAuthPanel`, `EmailPanel`, `ApiKeyPanel`, `QrPairingPanel` headers same pattern.
## Per-component decorations