Skip to content

Self-improving AI Employees for everyone

docs(frontend): Wave 2 - record schema-driven panel + uiHints + outputSchema patterns

trohitga64f7debe05e
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 9a1888c2..62debbe3 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -370,6 +370,59 @@ This is the rule that keeps the data layer schema-driven instead of imperatively
- After a mutation, **invalidate the corresponding query key**, don't manually patch a Zustand list. 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.
+## Schema-driven node + panel hints
+
+Wave 2 introduced two typed fields on `INodeTypeDescription` so panels and the inspector can make rendering decisions from the schema instead of `nodeDefinition.name === '…'` string compares.
+
+### `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 `false` (the panel renders normally). 14 flags today:
+
+| Flag | Read by | Effect |
+|---|---|---|
+| `hideInputSection` | `ParameterPanel`, `InputSection` | Skip the connected-inputs panel (start, skill, monitor) |
+| `hideOutputSection` | `ParameterPanel`, `OutputSection` | Skip the execution-results panel |
+| `hideRunButton` | `ParameterPanel` | Hide the Run button (skill / memory / tool nodes) |
+| `hasCodeEditor` | `MiddleSection` | Give the params block extra flex space for an embedded code editor |
+| `isMasterSkillEditor` | `MiddleSection` | Render the MasterSkillEditor split panel |
+| `isMemoryPanel` | `MiddleSection` | Render the memory markdown panel + token usage stats |
+| `isToolPanel` | `MiddleSection` | Surface the ToolSchemaEditor for connected services |
+| `isMonitorPanel` | `MiddleSection`, `ParameterPanel` | Render the team-monitor panel |
+| `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 |
+
+Adding new panel behaviour: add a flag to `INodeUIHints`, annotate the relevant node definitions, read the flag in the panel. Don't add another `nodeDefinition.name === '…'` branch.
+
+### `outputSchema` — runtime output shape for InputSection
+
+Defined on `INodeTypeDescription.outputSchema`. Plain primitive type names (`'string' | 'number' | 'boolean' | 'array' | 'object' | 'any'`) at leaves, or nested objects. `InputSection` reads this when populating the draggable variable list for downstream nodes. The legacy 350-line `sampleSchemas` map in `InputSection.tsx` is the fallback for nodes not yet annotated; new node definitions should set `outputSchema` directly.
+
+### Renderer registry shape (Phase 6 — pending)
+
+When the backend `get_node_spec` handler lands, the inspector will own a 4-file colocated layout under `client/src/components/inspector/`:
+
+```
+inspector/
+├── ParameterRenderer.tsx # dispatcher + 11 inline widgets + drag-drop wrapper + WIDGETS registry
+├── CollectionWidget.tsx # recursive (>150 LOC, independently testable)
+├── CodeWidget.tsx # CodeEditor + theme/toolbar plumbing
+└── types.ts # WidgetProps discriminated union, registry tester signature
+```
+
+The DIY widget registry (RHF + zod + a tester+rank dispatch) is modeled on n8n's monolithic `ParameterInput.vue`. Library-survey research preferred this over @jsonforms / @rjsf — bundle delta ≤ +50 KB gz vs +60–110 KB for any framework option, and shadcn theming would have to be hand-authored against any of them. `@rjsf/core` v6 + `@rjsf/shadcn` is the documented escape hatch if collection recursion bites.
+
+## Reusable component primitives (Wave 2)
+
+| File | When to use |
+|---|---|
+| [client/src/components/ui/action-button.tsx](../client/src/components/ui/action-button.tsx) | Colored "soft" toolbar button (Run / Save / Cancel / Reset / Stop). One `tone` prop drives bg/border/text against a fixed dracula palette via static Tailwind classes. Replaces the `actionButtonStyle(color, isDisabled)` style helper that was copy-pasted across 4 files. |
+| [client/src/components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx) | The `<Toaster />` mount — call `import { toast } from 'sonner'` directly at use sites; do not wrap. |
+| [client/src/components/ui/Modal.tsx](../client/src/components/ui/Modal.tsx) | Composition primitive on top of shadcn `<Dialog>`. Owns the recurring "title bar with centered headerActions and a close button + size-constrained content panel" 8 panels share. Not an antd facade. |
+| `client/src/components/ui/{button,input,select,switch,checkbox,form,…}.tsx` | shadcn-generated primitives. Add new ones via `npx shadcn@latest add <name>`. Don't re-implement what the registry ships. |
+
## Theme + canvas chrome
[index.css](../client/src/index.css) also styles React Flow, scrollbars, and dot grid against the CSS-var palette. No inline hex codes in theme-sensitive surfaces — everything references `hsl(var(--...))` so dark mode flips cleanly.
diff --git a/docs-internal/ui_migration_plan.md b/docs-internal/ui_migration_plan.md
index e0c80ca2..fd23bd2b 100644
--- a/docs-internal/ui_migration_plan.md
+++ b/docs-internal/ui_migration_plan.md
@@ -47,6 +47,34 @@ A second audit (3 parallel sub-agents) flagged tribal patterns that survived the
- Settings + onboarding share one cached server read (`['userSettings']`).
- WhatsApp group / channel / member selectors dispatch from `typeOptions.loadOptionsMethod` instead of parameter-name string compares — schema is the source of truth.
+## Wave 2 — schema-driven panels (April 2026)
+
+A second, deeper audit (4 parallel sub-agents — panel audit, library survey, NodeSpec mapping, system-design / file-organisation research) drove a focused Wave 2 against the heavy custom panels and the long-deferred renderer registry. Plan: same `typed-splashing-crown.md` plan file, replaced in place. Hard constraint: **minimise new files** — the research validated colocation (Kent C. Dodds, n8n's monolithic `ParameterInput.vue`, Robin Wieruch's split criteria) over per-widget files.
+
+| Wave 2 phase | Status | Commit | What it removes / introduces |
+|---|---|---|---|
+| 1 — `INodeUIHints` on node definitions | ✅ done | `0e816f3` | 5 panel files were branching on `nodeDefinition.name === '…'`. Now read 14 typed flags (`hideInputSection`, `hasCodeEditor`, `isMasterSkillEditor`, `isMemoryPanel`, `isToolPanel`, `isMonitorPanel`, `showLocationPanel`, `isAndroidToolkit`, `isChatTrigger`, `isConsoleSink`, `hasSkills`, …) from `nodeDefinition.uiHints`. Legacy name fallback retained for one release. |
+| 2 — `outputSchema` registry | ✅ done | `5d8d2b5` | The 350-line `sampleSchemas` map in `InputSection.tsx` was the largest schema-driven gap. New `outputSchema` field on `INodeTypeDescription`; `start`, `taskTrigger`, `chatTrigger`, `simpleMemory`, `python/javascript/typescriptExecutor` annotated as canaries. Legacy map kept as fallback. |
+| 3 — `ConsolePanel` state split | ✅ done | `cde8e6a` | 6 `useState` + 3 `useEffect` localStorage pairs and 2 imperative `addEventListener` resize chains collapsed into one zod-validated `consolePrefsSchema` + one inline `usePanelResize` hook. Both stay colocated at the top of `ConsolePanel.tsx`. |
+| 4 — Editor migrations to RHF + zod | ✅ done | `221848b`, `0c0e197` | `SkillEditorModal` (5 fields + manual `validateForm`) and `ToolSchemaEditor` (dynamic field-array) now run on `useForm` + `zodResolver` + `useFieldArray`. Per-field error messages live in the schema; dirty tracking is RHF-managed. Inputs / Selects / Switch / Checkbox from shadcn primitives. |
+| 5 — `ActionButton` cva helper | ✅ done | `8a68c09` | A 14-line `actionButtonStyle(color, isDisabled)` helper was copy-pasted across 4 files. New `client/src/components/ui/action-button.tsx` with a `tone` cva variant; `ParameterPanel`, `LocationParameterPanel`, `SettingsPanel` migrated. ~210 LOC of inline-style boilerplate gone. |
+| 6 — `ParameterRenderer` → renderer registry | ⏸ deferred | — | Library survey ran; recommended approach is **DIY** (RHF + zod + small `WIDGETS` registry) modeled on n8n's monolithic `ParameterInput.vue`, with `@rjsf/core` v6 + `@rjsf/shadcn` as the documented escape hatch. File budget: 4 files in `inspector/` (vs the original 16-file proposal — research validated the smaller layout). Blocks on backend `get_node_spec` WebSocket handler emitting `NodeSpec { jsonSchema, uiSchema, _uiHints? }`. |
+| 7 — Docs + guardrails | ✅ done (docs) | this commit | This section + frontend_architecture.md updates. ESLint rule + bundle-budget CI assertion deferred (need CI config touch). |
+
+**File budget actuals:** 1 new file across Wave 2 (`action-button.tsx`). All other phases used colocation or extended existing files (`useWorkflowsQuery.ts`, the relevant node definitions, `INodeProperties.ts`). The original draft of this plan proposed ~16 new files for the renderer phase alone — research-driven revision cut that to a 4-file colocated layout.
+
+**Wave 2 numbers:**
+- Hardcoded `nodeDefinition.name === '…'` outside whitelisted utility files: **0** (all panel-visibility checks read `uiHints` first; legacy fallbacks kept for nodes not yet annotated).
+- Hand-rolled forms with >3 fields: **2 → 0** (SkillEditorModal, ToolSchemaEditor — both on RHF + zod). MasterSkillEditor remains; it's a split-panel UI, not a single form.
+- `ConsolePanel` `useState` count: **13 → 7**.
+- `pnpm exec tsc --noEmit` green throughout all 6 commits.
+
+**What's still deferred (intentionally):**
+- Phase 6 — `ParameterRenderer` → DIY widget registry. Backend `get_node_spec` handler is the prerequisite. Frontend layout decided (4 files in `inspector/`); rollout shape decided (5 weekly slices behind `VITE_USE_NODESPEC` with parity test against legacy renderer).
+- Bulk Tailwind sweep of `GenericNode` / `BaseChatModelNode` inline `theme.dracula.*` refs. Visual-regression-prone; needs in-browser verification per file.
+- ESLint rule + bundle-budget CI assertion (Phase 7 leftovers). Both touch CI config, deferred together.
+- `MasterSkillEditor` RHF migration. The editor is a split-panel UI (skill list + content editor + folder dropdown + inline create/edit) — not the >3-field-form pattern Phase 4 targeted. The form-with-validation parts already moved to `SkillEditorModal`; the registry-style list view is genuinely different work.
+
## Context
The MachinaOs frontend was coupled to Ant Design (40 files, 187-line theme file, `ConfigProvider` at root). Pre-migration audit + research docs (now deleted; see git history under commit `4cb3dd9` if needed) prescribed shadcn/ui (canonical components copied via CLI registry) + Radix primitives + Tailwind 4 + JSON Forms for a schema-driven inspector. Phase 0/1 commits (`2209dba`, `7ac69fe`) included hand-written primitives and a toast facade — those got deleted as part of corrected Phase 0 (`cdeebb4`).