Skip to content

Self-improving AI Employees for everyone

feat(output): schema-ready OutputPanel + frontend UI migration RFC

trohitg4cb3dd98f9d6
diff --git a/client/package.json b/client/package.json
index c5ac02e1..7e54ee21 100644
--- a/client/package.json
+++ b/client/package.json
@@ -23,6 +23,7 @@
"@types/react": "^19.1.10",
"@types/react-dom": "^19.1.7",
"@types/styled-components": "^5.1.34",
+ "@uiw/react-json-view": "2.0.0-alpha.41",
"@vitejs/plugin-react": "^5.0.0",
"antd": "^5.27.4",
"autoprefixer": "^10.4.21",
@@ -40,7 +41,6 @@
"react-dom": "^19.1.1",
"react-hook-form": "^7",
"react-js-cron": "^5.2.0",
- "react-json-view-lite": "^2.5.0",
"react-markdown": "^10.1.0",
"react-simple-code-editor": "^0.14.1",
"react-virtuoso": "^4",
diff --git a/client/src/components/output/OutputPanel.tsx b/client/src/components/output/OutputPanel.tsx
new file mode 100644
index 00000000..8826e995
--- /dev/null
+++ b/client/src/components/output/OutputPanel.tsx
@@ -0,0 +1,174 @@
+/**
+ * OutputPanel — execution output display.
+ *
+ * Single component using antd (Collapse, Tag, Space) + ReactMarkdown
+ * + @uiw/react-json-view. No custom widgets, no registry, no schema
+ * renderer. Backend owns display logic via `_uiHints` (future);
+ * frontend is pure UI.
+ */
+
+import { Collapse, Tag, Space, Flex } from 'antd';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import remarkBreaks from 'remark-breaks';
+import JsonView from '@uiw/react-json-view';
+import { githubDarkTheme } from '@uiw/react-json-view/githubDark';
+import { githubLightTheme } from '@uiw/react-json-view/githubLight';
+import { useAppTheme } from '../../hooks/useAppTheme';
+import { ExecutionResult } from '../../services/executionService';
+import { Node } from 'reactflow';
+import { copyToClipboard } from '../../utils/formatters';
+
+/** Extract output data from ExecutionResult. */
+const getData = (r: ExecutionResult) =>
+ r.outputs ?? r.data ?? r.nodeData?.[0]?.[0]?.json ?? { success: r.success };
+
+/** Unwrap nested { result: {...} } from backend responses. */
+const unwrap = (d: any) =>
+ d?.result && typeof d.result === 'object' && !Array.isArray(d.result) ? d.result : d;
+
+/** Convert escaped newlines to real ones (same pattern as ConsolePanel). */
+const fmt = (s: string) => s.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+
+/** Tag color by field name. */
+const TAG_COLOR: Record<string, string> = {
+ model: 'purple', provider: 'cyan', agent_type: 'green',
+};
+
+interface Props {
+ results: ExecutionResult[];
+ onClear?: () => void;
+ selectedNode?: Node | null;
+}
+
+export default function OutputPanel({ results, onClear, selectedNode }: Props) {
+ const theme = useAppTheme();
+ const filtered = selectedNode ? results.filter(r => r.nodeId === selectedNode.id) : results;
+ const latest = filtered[0];
+
+ if (!latest) {
+ return (
+ <div style={{
+ width: '100%', height: '100%', display: 'flex',
+ alignItems: 'center', justifyContent: 'center',
+ color: theme.colors.textMuted, fontSize: theme.fontSize.sm,
+ }}>
+ No output yet. Run a node to see results.
+ </div>
+ );
+ }
+
+ const raw = getData(latest);
+ const data = unwrap(raw);
+ const response = data?.response ?? data?.output ?? data?.text ?? data?.content ?? data?.stdout;
+ const thinking = data?.thinking;
+ const metaTags = ['model', 'provider', 'agent_type'].filter(k => data?.[k]);
+
+ const items = [
+ response && {
+ key: 'response',
+ label: 'Response',
+ children: (
+ <div className="prose prose-sm dark:prose-invert max-w-none" style={{ whiteSpace: 'pre-wrap' }}>
+ <ReactMarkdown remarkPlugins={[remarkGfm, remarkBreaks]}>
+ {fmt(typeof response === 'string' ? response : JSON.stringify(response, null, 2))}
+ </ReactMarkdown>
+ </div>
+ ),
+ },
+ thinking && {
+ key: 'thinking',
+ label: 'Thinking',
+ children: (
+ <div className="prose prose-sm dark:prose-invert max-w-none" style={{ whiteSpace: 'pre-wrap', maxHeight: '300px', overflow: 'auto' }}>
+ <ReactMarkdown remarkPlugins={[remarkGfm, remarkBreaks]}>{fmt(thinking)}</ReactMarkdown>
+ </div>
+ ),
+ },
+ {
+ key: 'json',
+ label: (
+ <Space>
+ Raw JSON
+ <button
+ onClick={(e) => { e.stopPropagation(); copyToClipboard(raw, 'Copied!'); }}
+ style={{
+ fontSize: theme.fontSize.xs, cursor: 'pointer',
+ color: theme.dracula.cyan, background: 'none', border: 'none', padding: 0,
+ }}
+ >
+ Copy
+ </button>
+ </Space>
+ ),
+ children: (
+ <JsonView
+ value={raw}
+ collapsed={2}
+ displayDataTypes={false}
+ style={theme.isDarkMode ? githubDarkTheme : githubLightTheme}
+ />
+ ),
+ },
+ ].filter(Boolean) as any[];
+
+ return (
+ <div style={{
+ width: '100%', height: '100%', backgroundColor: theme.colors.backgroundPanel,
+ display: 'flex', flexDirection: 'column', overflow: 'hidden',
+ }}>
+ {/* Header */}
+ <Flex
+ align="center"
+ justify="space-between"
+ gap="small"
+ style={{
+ padding: `${theme.spacing.md} ${theme.spacing.lg}`,
+ borderBottom: `1px solid ${theme.colors.border}`,
+ backgroundColor: theme.colors.backgroundElevated,
+ flexShrink: 0,
+ }}
+ >
+ <Flex align="center" gap={4} wrap="wrap" flex="1 1 auto" style={{ minWidth: 0 }}>
+ <span style={{ fontSize: theme.fontSize.base, fontWeight: theme.fontWeight.semibold, color: theme.colors.text, marginRight: theme.spacing.xs }}>
+ Output
+ </span>
+ <Tag color={latest.success ? 'green' : 'red'}>{latest.success ? 'Success' : 'Error'}</Tag>
+ {latest.executionTime > 0 && <Tag>{(latest.executionTime / 1000).toFixed(1)}s</Tag>}
+ {metaTags.map(k => (
+ <Tag key={k} color={TAG_COLOR[k] || 'default'}>
+ {String(data[k]).replace(/_/g, ' ')}
+ </Tag>
+ ))}
+ </Flex>
+ {onClear && (
+ <button onClick={onClear} style={{
+ padding: `${theme.spacing.xs} ${theme.spacing.md}`,
+ fontSize: theme.fontSize.xs, cursor: 'pointer', flexShrink: 0,
+ color: theme.dracula.pink, backgroundColor: `${theme.dracula.pink}15`,
+ border: `1px solid ${theme.dracula.pink}40`, borderRadius: theme.borderRadius.sm,
+ }}>
+ Clear
+ </button>
+ )}
+ </Flex>
+
+ {/* Content */}
+ <div style={{ flex: 1, overflow: 'auto', padding: theme.spacing.lg }}>
+ {latest.error && (
+ <pre style={{
+ margin: `0 0 ${theme.spacing.md}`, padding: theme.spacing.md,
+ backgroundColor: `${theme.dracula.red}10`,
+ border: `1px solid ${theme.dracula.red}40`,
+ borderRadius: theme.borderRadius.md, borderLeft: `3px solid ${theme.dracula.red}`,
+ fontFamily: theme.fontFamily.mono, fontSize: theme.fontSize.sm,
+ color: theme.dracula.red, whiteSpace: 'pre-wrap', wordBreak: 'break-word',
+ }}>
+ {latest.error}
+ </pre>
+ )}
+ <Collapse defaultActiveKey={['response']} items={items} ghost />
+ </div>
+ </div>
+ );
+}
diff --git a/client/src/components/parameterPanel/OutputSection.tsx b/client/src/components/parameterPanel/OutputSection.tsx
index 64fc6c51..7e87d4d1 100644
--- a/client/src/components/parameterPanel/OutputSection.tsx
+++ b/client/src/components/parameterPanel/OutputSection.tsx
@@ -1,5 +1,5 @@
import React from 'react';
-import NodeOutputPanel from '../ui/NodeOutputPanel';
+import OutputPanel from '../output/OutputPanel';
import { useAppTheme } from '../../hooks/useAppTheme';
import { ExecutionResult } from '../../services/executionService';
import { Node } from 'reactflow';
@@ -71,7 +71,7 @@ const OutputSection: React.FC<OutputSectionProps> = ({
overflow: 'hidden',
position: 'relative'
}}>
- <NodeOutputPanel
+ <OutputPanel
results={combinedResults}
onClear={onClearResults}
selectedNode={selectedNode}
diff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.md
index 9aa6f7cf..69231268 100644
--- a/docs-internal/DESIGN.md
+++ b/docs-internal/DESIGN.md
@@ -14,6 +14,11 @@ Related docs:
- [current_system_architecture_analysis.md](current_system_architecture_analysis.md) - current frontend, backend, serving, and extension model audit
- [production_scale_architecture_research.md](production_scale_architecture_research.md) - source-backed research for a 1000+ node production architecture
- [config_driven_node_platform.md](config_driven_node_platform.md) - target config-driven node and panel platform design
+- [frontend_architecture_analysis.md](frontend_architecture_analysis.md) - current frontend shell, state, realtime, and editor audit
+- [frontend_component_functionality_and_design.md](frontend_component_functionality_and_design.md) - component and subsystem design notes for the current frontend
+- [frontend_system_design_rfc.md](frontend_system_design_rfc.md) - proposed frontend modularization RFC
+- [frontend_ui_framework_research.md](frontend_ui_framework_research.md) - primary-source research on modern UI runtimes, primitives, forms, and virtualization
+- [frontend_ui_stack_recommendation.md](frontend_ui_stack_recommendation.md) - recommended replacement stack and migration architecture for the frontend UI
---
diff --git a/docs-internal/frontend_architecture_analysis.md b/docs-internal/frontend_architecture_analysis.md
new file mode 100644
index 00000000..e7a2b5a4
--- /dev/null
+++ b/docs-internal/frontend_architecture_analysis.md
@@ -0,0 +1,441 @@
+# Frontend Architecture Analysis
+
+Last reviewed: 2026-04-13
+
+## Purpose
+
+This document records the current frontend architecture of MachinaOs as implemented in the repository today. It focuses on:
+
+- runtime and library stack
+- application shell and composition model
+- state ownership and data flow
+- node rendering and editor behavior
+- inspector, output, and credentials subsystems
+- main coupling points and architectural risks
+
+This is a current-state audit. For the target-state frontend design, see [frontend_system_design_rfc.md](frontend_system_design_rfc.md).
+
+---
+
+## Executive Summary
+
+The MachinaOs frontend is a fullscreen React Flow workspace implemented as a single protected application shell rather than a routed multi-page app.
+
+The core shape is:
+
+- `main.tsx` creates the provider stack
+- `App.tsx` applies theme and auth gating
+- `Dashboard.tsx` is the real application shell
+
+The architecture is partly modular and partly centralized:
+
+- modular in the sense that node families, panels, hooks, credentials, and outputs all have their own folders
+- centralized in the sense that `Dashboard.tsx` and `WebSocketContext.tsx` still carry a very large share of orchestration
+
+The frontend already contains strong building blocks for a large platform:
+
+- React Flow for graph authoring
+- Zustand for workflow and UI state
+- React Query for server-backed catalogue caching
+- a rich node-definition metadata model
+- a newer schema-driven output renderer
+- a more scalable credential-catalogue subsystem
+
+But the system is still limited by several code-owned boundaries:
+
+- node registration is TypeScript-driven rather than spec-driven
+- shell composition is too concentrated in `Dashboard.tsx`
+- realtime transport and business state are too concentrated in `WebSocketContext.tsx`
+- parameter and input panels still contain node-name-specific branching
+
+---
+
+## Technology Stack
+
+The frontend package lives in `client/` and is built on:
+
+- React 19
+- TypeScript
+- Vite
+- React Flow
+- Ant Design
+- Zustand
+- TanStack React Query
+- styled-components
+- Tailwind packages for supporting styles
+- cmdk, react-virtuoso, and fuzzysort for the credentials catalogue
+
+This is not a minimal SPA. It is a UI workbench with:
+
+- graph editing
+- websocket-backed execution
+- modal-heavy tooling
+- progressive onboarding
+- interactive credential configuration
+
+---
+
+## Boot and Provider Stack
+
+### Entrypoints
+
+The frontend startup path is:
+
+1. `client/src/main.tsx`
+2. `client/src/App.tsx`
+3. `client/src/Dashboard.tsx`
+
+### Provider order
+
+`main.tsx` currently mounts:
+
+- `QueryClientProvider`
+- `ThemeProvider`
+- `AuthProvider`
+- `WebSocketProvider`
+
+This order is meaningful:
+
+- React Query is global infrastructure for cache-backed data such as the credential catalogue
+- auth sits above realtime so the WebSocket connection can inherit auth state
+- the dashboard only renders inside that authenticated and themed runtime
+
+### App shell
+
+`App.tsx` is intentionally thin. It:
+
+- selects the Ant Design theme
+- wraps the app in `ProtectedRoute`
+- renders the dashboard fullscreen
+
+This keeps route-level complexity low, but it also means almost all feature boundaries are inside one workspace shell instead of multiple routes.
+
+---
+
+## Top-Level Layout Model
+
+### Dashboard as application shell
+
+`Dashboard.tsx` is the real app shell. It owns:
+
+- `ReactFlowProvider`
+- node and edge local state
+- toolbar wiring
+- workflow selection
+- import/export
+- run and deploy actions
+- debounced workflow persistence
+- viewport persistence
+- keyboard shortcuts
+- context menu behavior
+- modal visibility for settings, credentials, onboarding, and result views
+
+The rendered shell is broadly:
+
+- top toolbar
+- left workflow sidebar
+- center canvas
+- right component palette
+- bottom console panel
+- floating parameter panels and modal systems
+
+### Why this matters
+
+This gives the product a cohesive "single workspace" feel, but it also means one file is coordinating:
+
+- canvas concerns
+- workflow document concerns
+- execution concerns
+- persistence concerns
+- much of the app-level UI choreography
+
+That is the largest frontend coupling point today.
+
+---
+
+## State Ownership Model
+
+### 1. Zustand store
+
+`client/src/store/useAppStore.ts` is the main application store.
+
+It owns:
+
+- `currentWorkflow`
+- `savedWorkflows`
+- `hasUnsavedChanges`
+- workflow UI state keyed by workflow ID
+- sidebar/palette/console visibility
+- `proMode`
+- selected node compatibility state
+
+The important design choice is that workflow execution state is partially namespaced by workflow through `workflowUIStates`, but node selection is still also represented globally through `selectedNode`.
+
+### 2. Local React Flow state
+
+`Dashboard.tsx` keeps `nodes` and `edges` in local React Flow state for performance and editing responsiveness. Those local arrays are then synced back into the store on a debounce.
+
+So the frontend currently has two workflow topology representations:
+
+- live editing state in React Flow
+- durable workflow document state in Zustand and backend persistence
+
+This is a reasonable optimization, but it also creates a synchronization boundary that needs careful management.
+
+### 3. Local panel state
+
+Several feature areas keep working state locally:
+
+- `useParameterPanel.ts` keeps current parameter values and dirty state
+- credentials UI store keeps palette query and selection
+- modal and hover states are often local to each component
+
+This is generally the right choice, but because the app is modal-heavy, the number of active local state islands is growing.
+
+---
+
+## Data Flow and Backend Boundaries
+
+### REST responsibilities
+
+The frontend uses REST for:
+
+- auth lifecycle via `AuthContext`
+- workflow CRUD via `workflowApi`
+
+### WebSocket responsibilities
+
+The frontend uses `WebSocketContext` for almost everything else:
+
+- parameter loading and saving
+- node execution
+- whole-workflow execution
+- deployment and cancellation
+- logs and status broadcasts
+- provider status
+- Android and WhatsApp operations
+- memory and skill operations
+- variable and node output retrieval
+
+Operationally, the WebSocket context is both:
+
+- a request/response RPC layer
+- a subscription/broadcast layer
+
+This is effective, but it means one provider owns transport, message parsing, runtime state, and product-specific control-plane semantics.
+
+### React Query role
+
+React Query is not the dominant app data layer. It is currently used more selectively, especially for the credential-catalogue path:
+
+- server-owned catalogue
+- IndexedDB warm start
+- background revalidation
+
+This is a strong pattern and one of the cleaner frontend subsystems.
+
+---
+
+## Editor and Node Rendering System
+
+### Node registry
+
+The current registry is built from TypeScript modules:
+
+- `client/src/nodeDefinitions.ts`
+- `client/src/nodeDefinitions/*`
+- `client/src/types/INodeProperties.ts`
+
+This gives the system:
+
+- display name
+- icon
+- group/category
+- defaults
+- inputs and outputs
+- properties
+- credentials metadata
+- resource/operation metadata
+
+This is already a meaningful declarative model, but it is still code-owned and not yet a true external spec contract.
+
+### Node families
+
+The main node-rendering families are:
+
+- `GenericNode`
+- `SquareNode`
+- `TriggerNode`
+- `ModelNode`
+- `AIAgentNode`
+- `ToolkitNode`
+- `TeamMonitorNode`
+
+`Dashboard.tsx` computes `nodeTypes` using registry metadata plus many explicit type lists. That means node-family selection is only partially data-driven.
+
+### Edge rendering
+
+`ConditionalEdge.tsx` extends React Flow edge rendering with labeled branching behavior and inline condition editing.
+
+### Result
+
+The canvas is flexible and visually differentiated, but adding a new node or node family often still requires edits in:
+
+- node definitions
+- category exports
+- type buckets
+- dashboard node-family mapping
+
+---
+
+## Inspector and Parameter System
+
+### Main inspector flow
+
+The inspector stack is:
+
+- `ParameterPanel.tsx`
+- `useParameterPanel.ts`
+- `components/parameterPanel/ParameterPanelLayout.tsx`
+- `InputSection.tsx`
+- `MiddleSection.tsx`
+- `OutputSection.tsx`
+
+### Layout
+
+The current layout is a fixed three-column inspector:
+
+- left: upstream inputs and template variables
+- middle: editable node parameters and node-specific utilities
+- right: output view for the current node
+
+### Strength
+
+This is a strong UX model because it places:
+
+- inbound data
+- configuration
+- outbound data
+
+in one consistent workspace.
+
+### Weakness
+
+The layout is generic, but major parts of the middle and input sections are still heavily branched by node family or explicit node type:
+
+- memory nodes
+- master skill nodes
+- tool nodes
+- code editors
+- skill-capable agents
+
+This makes the inspector the main blocker to a truly config-driven node platform.
+
+---
+
+## Output Subsystem
+
+There are two output paths in the repo:
+
+- older UI output panels under `components/ui/`
+- newer schema-driven output panels under `components/output/`
+
+The newer subsystem is significantly cleaner:
+
+- `OutputPanel.tsx` extracts execution output
+- it reads `_uiHints` from the backend when present
+- `inferHints.ts` provides a fallback inference path
+- `SchemaRenderer.tsx` maps fields to widgets
+- widget resolution is isolated under `components/output/widgets/`
+
+This is the closest thing in the current frontend to a spec-driven rendering pipeline.
+
+The remaining limitation is that widget registration is still a closed union rather than an open extension registry.
+
+---
+
+## Credentials Subsystem
+
+The credentials system is now more modern than much of the rest of the frontend.
+
+Main pieces:
+
+- `components/credentials/CredentialsModal.tsx`
+- `CredentialsPalette.tsx`
+- `PanelRenderer.tsx`
+- `useCatalogueQuery.ts`
+- `useCredentialRegistry.ts`
+- panel implementations under `components/credentials/panels/`
+
+Important properties of this subsystem:
+
+- server-owned catalogue data
+- client fallback catalogue
+- IndexedDB warm start
+- React Query caching
+- lazy-loaded panel kinds
+- virtualized, fuzzy-search palette
+
+This is one of the best existing blueprints for how other frontend subsystems should evolve: small UI store, server-backed data, derived data in memoized views, and bounded rendering branches.
+
+---
+
+## Main Frontend Strengths
+
+- strong workspace-centric UX
+- rich node metadata model
+- flexible React Flow integration
+- clear split between auth/CRUD REST and realtime websocket operations
+- newer output subsystem is clean and generic
+- newer credentials subsystem is scalable and performance-aware
+- per-workflow execution state already exists conceptually
+
+---
+
+## Main Frontend Risks
+
+### 1. Oversized shell
+
+`Dashboard.tsx` is too large and too central.
+
+### 2. Oversized realtime provider
+
+`WebSocketContext.tsx` is too large and mixes:
+
+- transport
+- runtime state
+- product integrations
+- command methods
+- broadcast reconciliation
+
+### 3. Double workflow state
+
+React Flow local state and store state coexist for topology, which is necessary today but increases drift risk.
+
+### 4. Code-owned node registry
+
+Node metadata is rich, but still TypeScript-owned and not canonical across the platform.
+
+### 5. Inspector branching
+
+`ParameterRenderer`, `InputSection`, and `MiddleSection` still rely on many explicit node-type or node-family branches.
+
+### 6. Mixed old and new output paths
+
+The output subsystem has improved, but older output surfaces still exist and can drift.
+
+---
+
+## Immediate Conclusion
+
+The frontend is not a weak foundation. It already has enough structure to evolve into a large-scale node authoring platform.
+
+The path forward is not a rewrite of the visual shell. The path forward is to reduce central orchestration and move toward:
+
+- clearer feature boundaries
+- a smaller realtime core
+- a spec-driven node registry
+- generated inspector and output surfaces
+- more explicit extension points
+
+That target architecture is described in [frontend_system_design_rfc.md](frontend_system_design_rfc.md).
diff --git a/docs-internal/frontend_component_functionality_and_design.md b/docs-internal/frontend_component_functionality_and_design.md
new file mode 100644
index 00000000..622a7ddd
--- /dev/null
+++ b/docs-internal/frontend_component_functionality_and_design.md
@@ -0,0 +1,487 @@
+# Frontend Component Functionality And Design
+
+Last reviewed: 2026-04-13
+
+## Purpose
+
+This document describes the main frontend component families in MachinaOs, what each subsystem does, and how the current design is organized.
+
+It is intended as a practical engineering guide for contributors who need to understand:
+
+- which components make up the workspace shell
+- how node rendering works
+- how the inspector is built
+- how output and credentials rendering work
+- where the extensibility seams are today
+
+---
+
+## Component Taxonomy
+
+The frontend component tree can be understood in seven major groups:
+
+1. shell and workspace composition
+2. auth and onboarding
+3. node and edge rendering
+4. parameter and inspector surfaces
+5. output rendering
+6. credentials configuration
+7. shared UI primitives
+
+---
+
+## 1. Shell And Workspace Composition
+
+### `Dashboard.tsx`
+
+Primary responsibilities:
+
+- owns the React Flow workspace shell
+- wires local node and edge state
+- bridges toolbar, sidebar, palette, console, settings, onboarding, credentials, and modals
+- coordinates run, deploy, export, import, selection, and viewport behavior
+
+Design notes:
+
+- this is the de facto application coordinator
+- it is currently too large to be treated as a normal feature component
+- it should be thought of as a workspace orchestration layer, not a leaf UI module
+
+### `TopToolbar.tsx`
+
+Primary responsibilities:
+
+- workflow title editing
+- file menu actions
+- global run/deploy actions
+- theme toggle
+- credentials/settings entry points
+- global model selection
+
+Design notes:
+
+- mixes straightforward controls with higher-level workflow actions
+- contains global-model concerns that could become their own feature module over time
+
+### `WorkflowSidebar.tsx`
+
+Primary responsibilities:
+
+- render saved workflows
+- selection and deletion actions
+- current-workflow indication
+
+Design notes:
+
+- relatively self-contained
+- presentation-oriented, but still coupled to workflow summary shape and shell visibility state
+
+### `ComponentPalette.tsx`
+
+Primary responsibilities:
+
+- search node definitions
+- group nodes into categories
+- respect simple-mode vs pro-mode filtering
+- render draggable component items
+
+Design notes:
+
+- mostly data-driven
+- still embeds category semantics through `group[0]`, merged categories, and simple-mode filters
+
+### `ConsolePanel.tsx`
+
+Primary responsibilities:
+
+- display runtime logs and console outputs
+- surface backend activity inside the workspace
+
+Design notes:
+
+- important for observability in a graph-based tool
+- still coupled to websocket log shapes
+
+### `SettingsPanel.tsx`
+
+Primary responsibilities:
+
+- edit UI defaults and runtime preferences
+- store user-facing settings through backend-backed data
+
+Design notes:
+
+- modal-first settings surface
+- bound to shell-level commands rather than being route-isolated
+
+---
+
+## 2. Auth And Onboarding
+
+### `ProtectedRoute.tsx`
+
+Primary responsibilities:
+
+- gate the workspace behind auth state
+- switch between login and the app shell
+
+### `LoginPage.tsx`
+
+Primary responsibilities:
+
+- render the login/register entry flow
+
+### `OnboardingWizard.tsx` and onboarding steps
+
+Primary responsibilities:
+
+- first-run guidance
+- explain the canvas model
+- bridge new users into API keys and basic workflow concepts
+
+Design notes:
+
+- modal-based onboarding works with the single-workspace design
+- shell-coupled lifecycle means onboarding inherits dashboard complexity
+
+---
+
+## 3. Node And Edge Rendering
+
+### Design principle
+
+Node rendering is organized into visual families, but family selection still depends on both metadata and explicit node-type buckets.
+
+### `GenericNode.tsx`
+
+Role:
+
+- fallback renderer
+- generic handle and label rendering
+- lowest-common-denominator node UI
+
+Good for:
+
+- simple or not-yet-specialized node types
+
+### `SquareNode.tsx`
+
+Role:
+
+- general-purpose service/action node renderer
+- used across many categories such as utility, Google Workspace, filesystem, browser, proxy, and document nodes
+
+Design notes:
+
+- broadest renderer family
+- carries many special cases and status behaviors
+- effective, but increasingly overloaded
+
+### `TriggerNode.tsx`
+
+Role:
+
+- start and inbound-trigger family
+- output-only trigger-style visual language
+
+Design notes:
+
+- visually differentiated correctly
+- represents workflow entry semantics well
+
+### `ModelNode.tsx` and `BaseChatModelNode.tsx`
+
+Role:
+
+- circular AI-model family
+- provider-specific wrappers inject branding and provider metadata
+
+Design notes:
+
+- one of the cleaner renderer families because the provider-specific wrappers are thin
+
+### `AIAgentNode.tsx`
+
+Role:
+
+- primary agent-family renderer
+- multi-handle layout for tools, memory, skill, model, and task inputs
+- richer phase and execution-state presentation
+
+Design notes:
+
+- most expressive node renderer
+- also one of the most behavior-heavy visual components
+
+### `ToolkitNode.tsx`
+
+Role:
+
+- toolkit-style rendering for skill and tool-like nodes
+
+### `TeamMonitorNode.tsx`
+
+Role:
+
+- live status widget for team-monitoring behavior
+
+### `ConditionalEdge.tsx`
+
+Role:
+
+- branching edge UI with inline condition editing semantics
+
+Design notes:
+
+- edge customization is a useful differentiator in workflow tools
+- should remain bounded so the editor does not accumulate too many edge paradigms
+
+---
+
+## 4. Parameter And Inspector Surfaces
+
+### `ParameterPanel.tsx`
+
+Role:
+
+- top-level node inspector modal/surface
+- binds selected node, parameter state, execution results, and panel actions
+
+### `useParameterPanel.ts`
+
+Role:
+
+- load node parameters from backend
+- merge with node-definition defaults
+- track dirty state
+- save parameters back over WebSocket
+
+Design notes:
+
+- backend is the source of truth for node parameters
+- local hook state is only the working copy
+
+### `ParameterPanelLayout.tsx`
+
+Role:
+
+- fixed three-column shell
+
+Columns:
+
+- input data and available variables
+- editable parameter content
+- output for selected node
+
+Design notes:
+
+- consistent and understandable layout
+- not itself config-driven
+
+### `InputSection.tsx`
+
+Role:
+
+- show connected upstream nodes
+- show execution data when available
+- provide draggable variables for template insertion
+
+Design notes:
+
+- functionally useful
+- currently overloaded with config-handle detection, agent-specific rules, and large sample-schema logic
+
+### `MiddleSection.tsx`
+
+Role:
+
+- render parameters and node-specific tooling
+- host memory controls, skill connections, master-skill editing, tool schema editing, and compaction-related views
+
+Design notes:
+
+- this is the most feature-dense part of the inspector
+- many explicit branches are organized here because the node-definition schema is not yet expressive enough to generate them
+
+### `ParameterRenderer.tsx`
+
+Role:
+
+- core field renderer for node property definitions
+- supports string, options, code, file, collection, JSON, and several richer field types
+
+Design notes:
+
+- extremely important component
+- flexible, but switch-heavy
+- a future spec-driven platform should reduce the need for node-name-specific logic around it
+
+### `OutputSection.tsx`
+
+Role:
+
+- bridge execution results and websocket node status into the selected-node output panel
+
+Design notes:
+
+- currently combines local execution results with workflow-run output from websocket status
+- this is the right behavior for users, but it reveals that output state is still coming from multiple runtime channels
+
+---
+
+## 5. Output Rendering
+
+### New output subsystem
+
+The newer `components/output/*` stack is built around schema-driven rendering.
+
+Main components:
+
+- `OutputPanel.tsx`
+- `OutputCard.tsx`
+- `SchemaRenderer.tsx`
+- `widgets/*`
+- `utils/inferHints.ts`
+- `utils/resolveWidget.ts`
+- `utils/types.ts`
+
+### Current design
+
+The output pipeline is:
+
+1. extract output data from an execution result
+2. read backend `_uiHints` if present
+3. infer hints if backend hints are absent
+4. map fields to widgets
+5. render widgets lazily where appropriate
+
+### Why this subsystem is important
+
+This is the cleanest example in the frontend of:
+
+- generic rendering
+- schema-like output contracts
+- limited per-node branching
+
+### Limitation
+
+The widget registry is still closed. Extending output rendering still means code changes in the widget union and resolver.
+
+---
+
+## 6. Credentials Configuration
+
+### Main pieces
+
+- `CredentialsModal.tsx`
+- `CredentialsPalette.tsx`
+- `PanelRenderer.tsx`
+- `providers.tsx`
+- `catalogueAdapter.ts`
+- `useCatalogueQuery.ts`
+- `useCredentialRegistry.ts`
+- `panels/*`
+- `primitives/*`
+- `sections/*`
+
+### Current design
+
+The credentials system now follows a better frontend architecture than most of the rest of the app:
+
+- server owns catalogue data
+- IndexedDB provides warm-start caching
+- React Query owns remote cache state
+- a tiny Zustand store owns only UI state
+- palette rendering is virtualized
+- panels are lazy-loaded
+
+### Panel model
+
+Current panel kinds are bounded:
+
+- API key
+- OAuth
+- QR pairing
+- email
+
+This is already a config-driven renderer model, but still with a fixed set of panel classes.
+
+### Why this matters
+
+The credentials subsystem is the best template in the repo for how to scale a feature area without turning one provider into a giant store object.
+
+---
+
+## 7. Shared UI Primitives
+
+Important reusable shell primitives live under `components/ui/` and `components/shared/`.
+
+Examples:
+
+- `Modal.tsx`
+- `CollapsibleSection.tsx`
+- `ComponentItem.tsx`
+- `NodeContextMenu.tsx`
+- `ErrorBoundary.tsx`
+- `DataPanel.tsx`
+- `JSONTreeRenderer.tsx`
+
+These provide consistent workspace affordances, but they are still plain components rather than part of a formal design-system package.
+
+---
+
+## Hooks And Services
+
+### High-value hooks
+
+- `useWorkflowManagement.ts`
+- `useReactFlowNodes.ts`
+- `useComponentPalette.ts`
+- `useParameterPanel.ts`
+- `useCatalogueQuery.ts`
+- `useApiKeys.ts`
+
+### Important services
+
+- `workflowApi.ts`
+- `executionService.ts`
+- `dynamicParameterService.ts`
+
+### Design observation
+
+The frontend already has useful hook boundaries, but some of them are thin facades and some duplicate behavior.
+
+Example:
+
+- `useExecution.ts` and `executionService.ts` overlap significantly in websocket execution wrapping
+
+That is a signal that execution concerns need one canonical frontend boundary.
+
+---
+
+## Main Contribution Risks
+
+Contributors are most likely to break shared behavior when editing:
+
+- `Dashboard.tsx`
+- `WebSocketContext.tsx`
+- `ParameterRenderer.tsx`
+- `InputSection.tsx`
+- `MiddleSection.tsx`
+- node registry and node-definition buckets
+
+These are the current merge hotspots and architectural pressure points.
+
+---
+
+## Practical Conclusion
+
+The frontend already has the right feature areas, but the boundaries between them are still too implicit.
+
+In practical terms:
+
+- the credentials system shows how a scalable, cache-aware, feature-bounded subsystem can work
+- the output system shows how schema-driven rendering can replace node-type branching
+- the inspector and dashboard are where the next architectural work should focus
+
+The target-state boundary changes are defined in [frontend_system_design_rfc.md](frontend_system_design_rfc.md).
diff --git a/docs-internal/frontend_system_design_rfc.md b/docs-internal/frontend_system_design_rfc.md
new file mode 100644
index 00000000..e556b190
--- /dev/null
+++ b/docs-internal/frontend_system_design_rfc.md
@@ -0,0 +1,521 @@
+# Frontend System Design RFC
+
+Status: Proposed
+
+Last updated: 2026-04-13
+
+## Summary
+
+This RFC proposes a new frontend architecture for MachinaOs that keeps the current workspace-centric UX but reduces the main scaling problems in the codebase:
+
+- oversized shell orchestration
+- oversized realtime provider
+- code-owned node registration
+- inspector branching by node name
+- overlapping old and new rendering paths
+
+The proposed direction is:
+
+- keep the single-workspace product shape
+- split the shell into bounded feature modules
+- shrink the WebSocket layer into a transport and event core
+- make node UI metadata spec-driven
+- make inspector and output rendering primarily schema-driven
+- treat credentials as the reference pattern for scalable frontend subsystems
+
+Related docs:
+
+- [frontend_architecture_analysis.md](frontend_architecture_analysis.md)
+- [frontend_component_functionality_and_design.md](frontend_component_functionality_and_design.md)
+- [frontend_ui_framework_research.md](frontend_ui_framework_research.md)
+- [frontend_ui_stack_recommendation.md](frontend_ui_stack_recommendation.md)
+
+---
+
+## Context
+
+The current frontend works, but it is approaching the limits of what a central orchestrator plus many special cases can support comfortably.
+
+The current strengths should be preserved:
+
+- fullscreen workspace
+- React Flow editor
+- strong visual node families
+- consistent three-column inspector
+- realtime execution feedback
+- modal-based auxiliary tools
+
+The current pain points should not be preserved:
+
+- `Dashboard.tsx` as the universal coordinator
+- `WebSocketContext.tsx` as the universal control plane
+- TypeScript-owned node registry
+- explicit node-type buckets for rendering and inspector behavior
+- duplicated output surfaces
+
+---
+
+## Goals
+
+### Primary goals
+
+- preserve the current user-facing workspace model
+- make new node addition lower-touch on the frontend
+- isolate realtime transport from business-specific view state
+- reduce merge hotspots
+- improve large-graph performance headroom
+- make inspector, output, and docs more spec-driven
+
+### Non-goals
+
+- replacing React Flow
+- introducing a route-heavy app architecture
+- rewriting the app in one step
+- removing support for rich custom node families
+
+---
+
+## Current Problems
+
+### 1. Shell concentration
+
+`Dashboard.tsx` currently mixes:
+
+- shell composition
+- editor orchestration
+- workflow persistence choreography
+- run and deploy actions
+- keyboard shortcuts
+- viewport logic
+- modal coordination
+
+This makes the workspace hard to evolve safely.
+
+### 2. Realtime concentration
+
+`WebSocketContext.tsx` currently mixes:
+
+- websocket lifecycle
+- request-response tracking
+- broadcast reconciliation
+- execution APIs
+- deployment APIs
+- provider-specific status state
+- log and console streams
+
+This makes the realtime boundary too broad and too product-specific.
+
+### 3. Node platform concentration
+
+The current node model is rich but not canonical. Rendering still depends on:
+
+- node definition metadata
+- explicit type arrays
+- dashboard family mapping logic
+- inspector special cases
+
+This prevents the frontend from behaving like a true modular node platform.
+
+### 4. Inspector concentration
+
+`ParameterRenderer`, `InputSection`, and `MiddleSection` currently contain much of the platform-specific branching for:
+
+- memory nodes
+- skill nodes
+- tool nodes
+- code editors
+- compaction-related controls
+- agent-specific affordances
+
+This is the biggest blocker to config-driven node onboarding.
+
+---
+
+## Proposed Architecture
+
+### High-level module model
+
+The frontend should be reorganized into five major feature layers:
+
+1. shell layer
+2. editor layer
+3. node platform layer
+4. runtime layer
+5. feature subsystems
+
+### 1. Shell layer
+
+Responsibilities:
+
+- page-level composition
+- workspace chrome
+- modal routing
+- feature mounting
+
+Target modules:
+
+- `shell/WorkspaceShell`
+- `shell/Toolbar`
+- `shell/SidebarRail`
+- `shell/PaletteRail`
+- `shell/ConsoleDock`
+- `shell/ModalHost`
+
+Rule:
+
+The shell should compose feature modules, not implement their internal logic.
+
+### 2. Editor layer
+
+Responsibilities:
+
+- React Flow instance
+- node and edge local state
+- viewport state
+- selection state
+- keyboard shortcuts
+- drag/drop and clipboard behavior
+
+Target modules:
+
+- `editor/CanvasController`
+- `editor/NodeFamilyRegistry`
+- `editor/EdgeRegistry`
+- `editor/SelectionController`
+- `editor/ViewportController`
+
+Rule:
+
+The editor layer owns canvas concerns only. It should not directly own workflow persistence or feature-specific modal logic.
+
+### 3. Node platform layer
+
+Responsibilities:
+
+- canonical frontend node spec loading
+- palette generation
+- family selection
+- inspector schema generation
+- node docs/help metadata
+- output UI metadata
+
+Target modules:
+
+- `node-platform/spec-registry`
+- `node-platform/family-registry`
+- `node-platform/inspector-schema`
+- `node-platform/output-schema`
+
+Rule:
+
+The node platform layer should be driven by a canonical `NodeSpec`, not by scattered TypeScript registries and category arrays.
+
+### 4. Runtime layer
+
+Responsibilities:
+
+- websocket transport
+- request correlation
+- command APIs
+- event subscriptions
+- normalized runtime state caches
+
+Target modules:
+
+- `runtime/socket-client`
+- `runtime/command-api`
+- `runtime/event-store`
+- `runtime/selectors`
+
+Rule:
+
+Transport should not also be the top-level owner of product-specific derived state.
+
+### 5. Feature subsystems
+
+Responsibilities:
+
+- credentials
+- onboarding
+- settings
+- output
+- inspector extras such as memory or skills
+
+Rule:
+
+Each subsystem should own its own state shape and expose narrow integration points to the shell and node platform.
+
+---
+
+## Proposed Runtime Boundary
+
+### Current model
+
+One giant context provides:
+
+- connection management
+- command methods
+- subscription state
+- derived app state
+
+### Proposed model
+
+Split it into three parts:
+
+1. transport client
+2. command layer
+3. event store
+
+#### Transport client
+
+Owns:
+
+- socket connection lifecycle
+- reconnect policy
+- send and receive primitives
+
+#### Command layer
+
+Owns:
+
+- typed request APIs such as `executeNode`, `saveNodeParameters`, `deployWorkflow`
+
+#### Event store
+
+Owns:
+
+- normalized runtime state derived from broadcasts
+
+Benefits:
+
+- easier testing
+- easier memory management
+- smaller provider surface
+- clearer ownership
+
+---
+
+## Proposed NodeSpec Frontend Contract
+
+The frontend should consume a canonical spec with at least:
+
+- metadata
+- visual family
+- ports
+- parameters schema
+- UI schema
+- credential requirements
+- output UI hints
+- docs/help metadata
+
+### Why this matters
+
+With a canonical frontend spec:
+
+- palette generation becomes generic
+- node family selection becomes data-driven
+- inspector generation becomes mostly schema-driven
+- output rendering becomes more predictable
+- docs and help can be generated consistently
+
+### Immediate implication
+
+The current `nodeDefinitions` TypeScript registry should become an adapter layer, not the final source of truth.
+
+---
+
+## Proposed Inspector Design
+
+### Keep the three-column model
+
+The current inspector layout is good and should be preserved:
+
+- inputs
+- parameters
+- outputs
+
+### Change what drives each column
+
+#### Inputs column
+
+Should be driven by:
+
+- upstream port contracts
+- runtime data envelope
+- generic sample data fallback
+
+It should not need large hardcoded node-type maps.
+
+#### Parameters column
+
+Should be driven by:
+
+- `parametersSchema`
+- `uiSchema`
+- bounded extension hooks for special widgets
+
+#### Outputs column
+
+Should use the existing schema-driven output stack as the default path everywhere.
+
+### Extension points
+
+When generic schema rendering is not enough, use narrow extension points such as:
+
+- `InspectorAddonProvider`
+- `InputPreviewProvider`
+- `OutputWidgetProvider`
+
+This is better than embedding more node-name branches in shared components.
+
+---
+
+## Proposed Output Design
+
+The `components/output/*` stack should become the only output path.
+
+### Required moves
+
+1. retire legacy output surfaces under `components/ui/`
+2. move widget registration into a formal registry
+3. make `_uiHints` compatible with future `NodeSpec` output metadata
+4. keep the inference path as a fallback, not the primary contract
+
+### Result
+
+Output rendering becomes:
+
+- generic
+- extensible
+- more consistent across nodes
+
+---
+
+## Proposed Credentials Pattern As Reference Model
+
+The credentials subsystem should be treated as the reference implementation for scalable frontend feature design.
+
+Key properties worth copying:
+
+- server-owned data model
+- React Query ownership of remote cache
+- tiny local UI store
+- virtualized list for large datasets
+- lazy-loaded detail panels
+- fallback data path without coupling catalogue data into global state
+
+This pattern should inform future subsystems such as:
+
+- node docs catalogue
+- template library
+- generated node-spec browser
+
+---
+
+## Proposed File And Package Shape
+
+Suggested frontend reorganization:
+
+```text
+client/src/
+ shell/
+ editor/
+ runtime/
+ node-platform/
+ features/
+ credentials/
+ output/
+ onboarding/
+ settings/
+ inspector/
+ shared/
+```
+
+Suggested rules:
+
+- `shell/` composes features
+- `editor/` owns React Flow concerns
+- `runtime/` owns transport and live state
+- `node-platform/` owns spec consumption and rendering contracts
+- `features/` own their own state and presentation
+
+---
+
+## Migration Plan
+
+### Phase 1: Extract shell modules
+
+- split `Dashboard.tsx` into shell and editor controllers
+- keep behavior the same
+
+### Phase 2: Split realtime core
+
+- extract transport client from `WebSocketContext.tsx`
+- extract typed command APIs
+- isolate event-state normalization
+
+### Phase 3: Unify output rendering
+
+- standardize on `components/output/*`
+- route all output surfaces through the new stack
+
+### Phase 4: Introduce frontend `NodeSpec` adapter
+
+- map existing `nodeDefinitions` into a canonical spec shape
+- move family selection to spec metadata
+
+### Phase 5: Reduce inspector branching
+
+- drive more parameter UI from schema
+- move node-family extras into extension providers
+
+### Phase 6: Replace code-owned registry
+
+- load specs from a shared contract source
+- retire category arrays and type-bucket coupling over time
+
+This sequence keeps the app functional throughout the migration.
+
+---
+
+## Risks And Tradeoffs
+
+### Benefits
+
+- lower merge pressure
+- cleaner ownership
+- easier node onboarding
+- better large-graph performance headroom
+- easier testing of runtime and editor concerns separately
+
+### Costs
+
+- more modules and explicit boundaries
+- migration overhead
+- temporary adapter layers during transition
+- stronger schema discipline for node metadata
+
+These are acceptable costs if MachinaOs is intended to become a large platform rather than a feature-growing single shell.
+
+---
+
+## Open Questions
+
+1. Should selected-node state move fully into per-workflow UI state?
+2. Should React Query remain selective, or should more server-backed read models move into it?
+3. Which inspector behaviors truly need extension points, and which can be encoded in schema?
+4. Should the frontend load `NodeSpec` from a shared package, from the backend, or both?
+5. How much of `_uiHints` should be preserved as runtime override versus moved into static node metadata?
+
+---
+
+## Decision
+
+This RFC recommends that the next frontend architecture work should prioritize:
+
+1. shrinking `Dashboard.tsx`
+2. shrinking `WebSocketContext.tsx`
+3. standardizing on the new output subsystem
+4. introducing a canonical spec-driven node platform on the frontend
+
+That path preserves the current user experience while making the frontend easier to scale, document, and extend.
diff --git a/docs-internal/frontend_ui_framework_research.md b/docs-internal/frontend_ui_framework_research.md
new file mode 100644
index 00000000..6794ff5a
--- /dev/null
+++ b/docs-internal/frontend_ui_framework_research.md
@@ -0,0 +1,509 @@
+# Frontend UI Framework Research
+
+Status: Research
+
+Last updated: 2026-04-13
+
+## Purpose
+
+This document compares modern frontend runtimes, UI component systems, schema-driven form stacks, and virtualization tooling for a MachinaOs frontend refresh.
+
+The goal is not to pick the most fashionable stack. The goal is to pick the stack that best supports:
+
+- a visually strong workflow editor
+- 1000+ node authoring without UI collapse
+- lower memory pressure than the current mixed UI stack
+- schema-driven node onboarding
+- modular panels and extensions
+- a realistic migration path from the current codebase
+
+---
+
+## Current Frontend Snapshot
+
+The current client stack from `client/package.json` is:
+
+- `react` `19.1.1`
+- `vite` `7.1.2`
+- `antd` `5.27.4`
+- `reactflow` `11.11.4`
+- `tailwindcss` `4.1.13`
+- `styled-components` `6.1.19`
+- `zustand` `5.0.8`
+- `@tanstack/react-query` `5`
+- `react-virtuoso` `4`
+- `cmdk` `1`
+- limited `@radix-ui/react-dialog` and `@radix-ui/react-collapsible`
+
+Codebase coupling today:
+
+- `41` direct `antd` import sites in `client/src`
+- `36` direct `reactflow` import sites in `client/src`
+- `styled-components` is only used in one shared component, but the dependency is still installed globally
+- the app already has an emerging modern path in credentials and output rendering, while the rest of the shell is still largely Ant Design driven
+
+This means the frontend problem is not "React is too slow". The real problems are:
+
+- central orchestration in large shell files
+- an opinionated component library spread across many features
+- too much node-specific branching in inspector code
+- incomplete migration toward schema-driven rendering
+
+---
+
+## Evaluation Criteria
+
+### Runtime criteria
+
+- compatibility with React Flow style node editors
+- minimal rewrite risk
+- support for gradual adoption
+- good debugging and hiring profile
+- strong ecosystem for headless components, forms, virtualization, accessibility
+
+### UI-system criteria
+
+- can produce a strong custom visual language
+- does not force default enterprise chrome everywhere
+- supports accessible complex controls
+- supports open-code ownership for long-lived product teams
+- plays well with schema-driven rendering
+
+### Large-editor criteria
+
+- can keep rerenders narrow
+- can virtualize long palettes, trees, and result panes
+- can support panel composition from metadata instead of one-off code
+- can support collapse/group/subflow patterns for very large graphs
+
+---
+
+## Runtime Framework Comparison
+
+### React 19
+
+Why it is strong:
+
+- React Compiler is now production-ready, battle-tested on major apps at Meta, and can be adopted incrementally.
+- The current MachinaOs frontend is already React 19, so the migration cost is much lower than any rewrite.
+- The node-editor ecosystem is strongest here. React Flow's own current UI guidance is based on React 19, Tailwind 4, and `shadcn/ui`.
+- The schema-driven form and accessibility ecosystem is materially stronger in React than the alternatives.
+
+Why it matters for MachinaOs:
+
+- React is not the bottleneck. The architecture around it is the bottleneck.
+- React Compiler plus stricter store boundaries is a much cheaper and safer performance win than a full framework rewrite.
+
+Verdict:
+
+- Best fit for an existing large workflow editor.
+
+### Solid
+
+Why it is strong:
+
+- Solid's fine-grained reactivity updates only tracked consumers.
+- It is a real performance-oriented runtime, especially for large interactive surfaces.
+
+Why it is weaker for MachinaOs:
+
+- The existing frontend is already heavily invested in React Flow, React Query, Zustand patterns, and React-specific UI tooling.
+- Rebuilding the editor, panel system, and extension model in Solid would cost more engineering time than the performance gain is likely to justify.
+- The component, accessibility, and schema-form ecosystem is smaller for the exact kind of product MachinaOs is building.
+
+Verdict:
+
+- Strong greenfield option.
+- Not the right replacement path for this repo.
+
+### Svelte 5
+
+Why it is strong:
+
+- Svelte uses a compiler model, and Svelte 5 runes push reactivity further into the language.
+- The runtime model is lean and can feel excellent in highly interactive UIs.
+
+Why it is weaker for MachinaOs:
+
+- The React Flow ecosystem and surrounding tooling still makes React the safer editor platform.
+- Rebuilding the current node, credentials, inspector, and realtime stack in Svelte is a full rewrite, not a migration.
+- The schema-form and enterprise accessibility tooling story is weaker than React's.
+
+Verdict:
+
+- Attractive for new products.
+- Not the practical move for this codebase.
+
+### Qwik
+
+Why it is strong:
+
+- Qwik is optimized for resumability and aggressive code splitting.
+- It is very interesting for content-heavy or cold-start-sensitive apps.
+
+Why it is weaker for MachinaOs:
+
+- MachinaOs is not a marketing site or a document portal. It is a long-lived authenticated workspace with a hot editor session.
+- The main pain here is sustained editor complexity, not initial hydration cost.
+- The component and editor ecosystem is much less aligned with the current app.
+
+Verdict:
+
+- Architecturally interesting.
+- Poor fit for this workload.
+
+### Preact
+
+Why it is strong:
+
+- Preact is small and deliberately focused on size and performance.
+- It can alias React through `preact/compat`.
+
+Why it is weaker for MachinaOs:
+
+- The actual win over modern React 19 plus React Compiler is likely to be small relative to the migration and compatibility risk.
+- Preact's docs are explicit that compatibility is not identical to React and that some differences exist for size and performance reasons.
+- For a large node editor, ecosystem certainty matters more than theoretical framework footprint wins.
+
+Verdict:
+
+- Good for smaller apps or strict bundle budgets.
+- Not enough upside for this product.
+
+---
+
+## Runtime Recommendation
+
+Keep React.
+
+More specifically:
+
+- keep `React 19`
+- enable `React Compiler` progressively
+- keep the Vite-based setup
+- upgrade the editor stack to current React Flow generation instead of rewriting the runtime
+
+This is the only option that improves performance, preserves momentum, and keeps the editor ecosystem on the happy path at the same time.
+
+---
+
+## Component System Comparison
+
+### Ant Design
+
+Strengths:
+
+- broad enterprise component surface
+- mature ecosystem
+- strong theming and tokens
+
+Weaknesses for MachinaOs:
+
+- visually opinionated toward enterprise CRUD UIs
+- large spread across the codebase today
+- too easy to accumulate inconsistent shell chrome, forms, and modals that all look "default Ant"
+- not a great base for a distinctive node-editor product language
+
+Verdict:
+
+- Good for business apps.
+- Not the best long-term visual or architectural base for MachinaOs.
+
+### MUI
+
+Strengths:
+
+- broad surface area
+- mature docs and ecosystem
+- strong design-system history
+
+Weaknesses for MachinaOs:
+
+- still pushes the team toward a library-owned look unless heavily customized
+- the value over Ant Design is not large enough to justify a swap on its own
+- still not the best match for a fully owned workflow-editor visual language
+
+Verdict:
+
+- Better for product teams standardizing on Material patterns.
+- Not the right core bet here.
+
+### Mantine
+
+Strengths:
+
+- good developer experience
+- strong out-of-the-box aesthetics
+- official docs explicitly discuss style-performance tradeoffs and recommend CSS Modules for best performance
+
+Weaknesses for MachinaOs:
+
+- more opinionated and styled than a headless platform
+- would still leave the team adapting the design system around the editor rather than truly owning it
+
+Verdict:
+
+- Best "beautiful out of the box" option in the styled-library camp.
+- Still not my first choice for a large schema-driven editor platform.
+
+### Radix Primitives
+
+Strengths:
+
+- accessible primitives
+- composable
+- unstyled
+- widely used in modern design-system stacks
+
+Weaknesses for MachinaOs:
+
+- intentionally low-level
+- does not cover the entire complex-interaction surface on its own
+
+Verdict:
+
+- Good primitive layer.
+- Better as part of a composed stack than as the only answer.
+
+### Base UI
+
+Strengths:
+
+- unstyled React component library
+- tree-shakable single package
+- broad component surface
+- explicitly focused on accessibility, performance, and developer experience
+
+Weaknesses for MachinaOs:
+
+- younger ecosystem than some older incumbents
+- fewer ready-made "drop in" product examples than older styled libraries
+
+Verdict:
+
+- Excellent base for an owned product design system.
+
+### React Aria
+
+Strengths:
+
+- style-free
+- highly accessible
+- excellent for complex interactions
+- strong fit for collections, keyboard behavior, drag/drop, selection, overlays, and advanced inputs
+
+Weaknesses for MachinaOs:
+
+- not a batteries-included visual system
+- requires deliberate composition and styling
+
+Verdict:
+
+- Best used surgically for the hardest interactive widgets rather than as the sole component source.
+
+### shadcn/ui
+
+Strengths:
+
+- open-code ownership model
+- components are copied into the app and then owned by the team
+- aligns with how React Flow UI itself is now presented by the xyflow team
+
+Weaknesses for MachinaOs:
+
+- not a runtime library in the usual sense
+- quality depends on the team's own discipline once components are copied in
+
+Verdict:
+
+- Best distribution model for a product that wants beautiful custom UI without becoming hostage to a vendor library.
+
+---
+
+## Schema-Driven Form Stack Comparison
+
+### JSON Forms
+
+Why it fits:
+
+- built around JSON Schema and UI schema
+- supports layout metadata rather than just raw field generation
+- matches the need for inspector panels, grouped sections, tabs, and conditional controls
+
+Verdict:
+
+- Best foundation for a schema-driven node inspector in MachinaOs.
+
+### react-jsonschema-form
+
+Why it is weaker here:
+
+- its own docs position it as a good fit when you want to generate a form from a schema "sight unseen"
+- the same docs say that if you already know your data model and want a toolkit for it, you may want something else
+
+Verdict:
+
+- Useful for simpler admin forms.
+- Not my preferred core for a high-touch node inspector platform.
+
+---
+
+## Virtualization and Large-Surface Tooling
+
+### React Flow
+
+React Flow's current guidance for large graphs directly matches MachinaOs' pain points:
+
+- memoize custom node and edge components
+- avoid broad subscriptions to `nodes` and `edges`
+- store high-churn derived state separately
+- collapse large node trees
+- simplify heavy styles for very large diagrams
+
+React Flow 12 also adds documented SSR support, and the docs indicate the current ecosystem direction is React 19 + Tailwind 4 + `shadcn/ui`.
+
+Verdict:
+
+- Keep it.
+- Upgrade it.
+- Architect around its scaling guidance instead of replacing it.
+
+### TanStack Virtual
+
+Why it fits:
+
+- headless
+- flexible
+- works well when MachinaOs needs custom list, grid, and panel virtualization instead of opinionated list widgets
+
+Verdict:
+
+- Best default virtualization primitive.
+
+### React Virtuoso
+
+Why it still matters:
+
+- grouped variable-height lists are where it shines
+- current credentials palette usage is already a good example
+
+Verdict:
+
+- Keep where it is already the right fit.
+- Do not force it into every virtualized surface.
+
+---
+
+## High-Scale Architecture Patterns To Borrow
+
+### Backstage frontend extensions
+
+Backstage's frontend system is built from a tree of extensions with typed data flowing from child to parent through extension points.
+
+What to copy:
+
+- narrow extension points
+- typed contracts between features
+- plugin-like composition instead of one giant registry object
+
+### Kubernetes custom resources
+
+Kubernetes uses declarative custom resources and controllers to make systems modular without hardcoding everything into the core.
+
+What to copy:
+
+- versioned schema documents
+- declarative desired-state style metadata
+- separation between spec and controller/runtime behavior
+
+### JSON Schema
+
+JSON Schema gives MachinaOs the right foundation for:
+
+- node parameter contracts
+- output contracts
+- defaults and descriptions
+- modular schema composition
+- dialect/version declarations
+
+This is the right spec language for a config-driven node platform.
+
+---
+
+## Recommendation Summary
+
+### Best runtime choice
+
+- `React 19` with `React Compiler`
+
+### Best editor choice
+
+- `React Flow` on the current xyflow path, upgraded to current major
+
+### Best component strategy
+
+- replace Ant Design as the default component layer
+- adopt an owned design-system model built from `shadcn/ui` distribution plus headless primitives
+- use `Base UI` or `Radix` style primitives for most owned components
+- use `React Aria` for the hardest collection and accessibility-heavy widgets
+
+### Best schema-driven form strategy
+
+- `JSON Forms` with a custom MachinaOs renderer set
+
+### Best virtualization strategy
+
+- `TanStack Virtual` as the default primitive
+- keep `React Virtuoso` selectively where grouped variable-height behavior is already valuable
+
+### Best architectural pattern
+
+- Backstage-style extension points
+- Kubernetes-style declarative specs
+- JSON Schema as the canonical node and panel contract
+
+---
+
+## Final Decision
+
+The strongest path is not "rewrite the frontend in a faster framework".
+
+The strongest path is:
+
+1. keep React
+2. modernize the component model away from Ant Design
+3. keep and upgrade React Flow
+4. make node panels schema-driven
+5. move to owned UI code and narrow extension points
+
+That produces better UI, lower long-term memory overhead from excess component abstraction, easier node onboarding, and much lower migration risk than switching runtimes.
+
+---
+
+## Sources
+
+- [React Compiler introduction](https://react.dev/learn/react-compiler/introduction)
+- [React Compiler incremental adoption](https://react.dev/learn/react-compiler/incremental-adoption)
+- [React Compiler 1.0 blog post](https://react.dev/blog/2025/10/07/react-compiler-1)
+- [Solid reactivity docs](https://docs.solidjs.com/concepts/intro-to-reactivity)
+- [Svelte runes docs](https://svelte.dev/docs/svelte/what-are-runes)
+- [Qwik component overview](https://qwik.dev/docs/components/overview)
+- [Preact homepage](https://preactjs.com/)
+- [Preact differences to React](https://preactjs.com/guide/v10/differences-to-react/)
+- [Ant Design introduction](https://ant.design/docs/react/introduce/)
+- [Mantine getting started](https://mantine.dev/getting-started/)
+- [Mantine styles performance](https://mantine.dev/styles/styles-performance/)
+- [Base UI quick start](https://base-ui.com/react/overview/quick-start)
+- [React Aria overview](https://react-aria.adobe.com/)
+- [React Aria drag and drop](https://react-aria.adobe.com/useDrop)
+- [React Flow performance guidance](https://reactflow.dev/learn/advanced-use/performance)
+- [React Flow accessibility](https://reactflow.dev/learn/advanced-use/accessibility)
+- [React Flow UI tutorial](https://reactflow.dev/learn/tutorials/getting-started-with-react-flow-components)
+- [TanStack Virtual introduction](https://tanstack.com/virtual/v3/docs/introduction)
+- [Virtuoso grouped list API](https://virtuoso.dev/react-virtuoso/api-reference/grouped-virtuoso/)
+- [JSON Forms layouts](https://jsonforms.io/docs/uischema/layouts/)
+- [react-jsonschema-form introduction](https://rjsf-team.github.io/react-jsonschema-form/docs/)
+- [Backstage frontend extensions](https://backstage.io/docs/frontend-system/architecture/extensions/)
+- [Kubernetes custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+- [JSON Schema documentation](https://json-schema.org/docs)
+- [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference)
diff --git a/docs-internal/frontend_ui_stack_recommendation.md b/docs-internal/frontend_ui_stack_recommendation.md
new file mode 100644
index 00000000..683e3fb7
--- /dev/null
+++ b/docs-internal/frontend_ui_stack_recommendation.md
@@ -0,0 +1,570 @@
+# Frontend UI Stack Recommendation
+
+Status: Proposed
+
+Last updated: 2026-04-13
+
+## Executive Decision
+
+MachinaOs should not replace React.
+
+MachinaOs should replace the current default UI component model.
+
+The recommended target stack is:
+
+- `React 19` with progressive `React Compiler` rollout
+- `React Flow 12.x` as the node editor foundation
+- owned UI code via `shadcn/ui` distribution model
+- `Base UI` as the default primitive layer for common product components
+- `React Aria` for the hardest accessibility-heavy and collection-heavy widgets
+- `Tailwind CSS 4` plus CSS variables as the main styling system
+- `TanStack Virtual` as the default virtualization primitive
+- `React Virtuoso` kept only where grouped variable-height lists are already a strong fit
+- `JSON Forms` plus custom renderers as the schema-driven panel engine
+
+This gives MachinaOs:
+
+- better UI control than Ant Design
+- lower long-term component overhead
+- easier node onboarding through schemas
+- strong performance characteristics for large editor surfaces
+- a migration path that does not require rebuilding the product in another runtime
+
+---
+
+## Why This Stack Wins
+
+### 1. It keeps the editor on the strongest ecosystem path
+
+MachinaOs is a workflow editor, not a document site. The core editor dependency is `reactflow`, and the current xyflow ecosystem direction is clearly modern React plus owned UI components. Rewriting the runtime would throw away too much working surface area.
+
+### 2. It separates beautiful UI from library lock-in
+
+The current app mixes:
+
+- Ant Design
+- Tailwind
+- a small amount of Radix
+- a small amount of styled-components
+
+That creates visual inconsistency and architectural drift.
+
+The target stack moves to:
+
+- a small owned design system
+- headless primitives
+- CSS variables and utility-driven styling
+
+That is how the team gets better UI without tying the product to a monolithic component library.
+
+### 3. It makes schema-driven nodes realistic
+
+The current blocker to easy node onboarding is not the canvas. It is the inspector and surrounding panels. New nodes still pull too much TypeScript-owned logic into:
+
+- `Dashboard.tsx`
+- `ParameterRenderer.tsx`
+- `InputSection.tsx`
+- `MiddleSection.tsx`
+
+The target stack fixes that by making panels render from versioned metadata instead of from hardcoded branching.
+
+### 4. It scales better organizationally
+
+The architecture should optimize for many future node additions by multiple contributors. That requires:
+
+- narrow extension points
+- a canonical `NodeSpec`
+- owned UI components
+- renderer registries instead of switch statements
+
+---
+
+## Recommended Stack By Layer
+
+## 1. Runtime and App Foundation
+
+Recommended:
+
+- `React 19`
+- `React Compiler`
+- `Vite`
+- `TypeScript`
+
+Why:
+
+- minimal rewrite risk
+- strong current ecosystem fit
+- incremental rollout possible
+- no need to trade ecosystem maturity for framework novelty
+
+Do not do:
+
+- full runtime rewrite to Solid, Svelte, Qwik, or Preact
+
+Those are reasonable greenfield choices, but they are not the highest-leverage move for this repo.
+
+---
+
+## 2. Canvas and Graph Authoring
+
+Recommended:
+
+- `React Flow 12.x`
+
+Architecture rules:
+
+- keep React Flow state local to the editor module
+- keep selection and viewport state in tightly scoped stores
+- keep expensive node data out of broad subscriptions
+- add first-class group and subflow support
+- add explicit collapse and expand behavior for large graphs
+- push layout and heavy graph transforms off the main thread
+
+Why:
+
+- current React Flow guidance already matches the needs of 1000+ node graphs
+- current docs and UI examples are aligned with React 19 and `shadcn/ui`
+
+Do not do:
+
+- replace React Flow just to chase theoretical runtime savings
+
+---
+
+## 3. Product Design System
+
+Recommended:
+
+- `shadcn/ui` as the distribution and ownership model
+- `Base UI` as the default primitive layer
+- `React Aria` for advanced collection widgets and accessibility-heavy interactions
+- `Tailwind CSS 4` plus CSS variables for styling
+
+Why this composition is better than a single large library:
+
+- `shadcn/ui` gives the team source ownership
+- `Base UI` gives tree-shakable, accessible, unstyled building blocks
+- `React Aria` covers harder collection, keyboard, and drag/drop interactions
+- `Tailwind 4` keeps styling local, fast, and token-driven without another runtime styling layer
+
+What this should replace:
+
+- default use of `antd` components for shell, forms, cards, tabs, modals, inputs, and layout
+- remaining `styled-components` usage
+
+What can stay temporarily during migration:
+
+- existing Ant Design forms and simple panels until replacement slices are ready
+
+---
+
+## 4. Schema-Driven Panel Engine
+
+Recommended:
+
+- `JSON Forms`
+- custom MachinaOs renderer registry
+- JSON Schema plus UI schema as the canonical panel contract
+
+Why:
+
+- supports layout metadata, not just field generation
+- works with nested groups, tabs, arrays, conditional sections, defaults, and annotations
+- fits the existing direction already visible in the output subsystem
+
+Target contract layers:
+
+- `NodeSpec`
+- `ParameterSchema`
+- `UiSchema`
+- `OutputSchema`
+- `DocsSchema`
+
+### Proposed `NodeSpec` shape
+
+```json
+{
+ "apiVersion": "ui.machinaos.dev/v1",
+ "kind": "NodeSpec",
+ "metadata": {
+ "type": "gmail.send",
+ "version": "2.1.0",
+ "title": "Send Gmail",
+ "category": "Google"
+ },
+ "spec": {
+ "family": "action",
+ "icon": "gmail",
+ "capabilities": ["credentialed", "network"],
+ "parametersSchema": {
+ "type": "object",
+ "properties": {
+ "to": { "type": "string", "format": "email" },
+ "subject": { "type": "string" },
+ "body": { "type": "string" }
+ },
+ "required": ["to", "subject"]
+ },
+ "uiSchema": {
+ "type": "VerticalLayout",
+ "elements": [
+ { "type": "Control", "scope": "#/properties/to" },
+ { "type": "Control", "scope": "#/properties/subject" },
+ {
+ "type": "Control",
+ "scope": "#/properties/body",
+ "options": { "widget": "markdown-textarea" }
+ }
+ ]
+ },
+ "outputSchema": {
+ "type": "object",
+ "properties": {
+ "messageId": { "type": "string" },
+ "accepted": { "type": "boolean" }
+ }
+ }
+ }
+}
+```
+
+### Resulting frontend behavior
+
+From that one spec, the frontend should be able to generate:
+
+- palette entry
+- inspector form
+- docs panel
+- credential requirements
+- output renderer defaults
+- validation messages
+- analytics identifiers
+
+---
+
+## 5. Virtualization Strategy
+
+Recommended default:
+
+- `TanStack Virtual`
+
+Keep selectively:
+
+- `React Virtuoso` for grouped, variable-height, sticky-header lists such as the credentials picker
+
+Why:
+
+- TanStack Virtual is the better primitive when the team needs custom list behavior inside a complex product shell
+- Virtuoso remains a good specialized tool where its grouping model is already paying off
+
+Target virtualized surfaces:
+
+- node palette
+- search results
+- large schema sections
+- execution log panes
+- docs sidebars
+- asset or credential pickers
+
+---
+
+## Target Frontend Architecture
+
+## 1. Shell Layer
+
+Responsibilities:
+
+- app chrome
+- panel docking
+- modal routing
+- feature mounting
+
+Target modules:
+
+- `shell/WorkspaceShell`
+- `shell/Topbar`
+- `shell/LeftRail`
+- `shell/RightInspector`
+- `shell/BottomDock`
+- `shell/ModalHost`
+
+Rule:
+
+The shell composes features. It does not contain feature internals.
+
+## 2. Editor Layer
+
+Responsibilities:
+
+- React Flow instance
+- viewport
+- selection
+- node and edge registration
+- keyboard shortcuts
+
+Target modules:
+
+- `editor/CanvasController`
+- `editor/NodeRendererRegistry`
+- `editor/EdgeRendererRegistry`
+- `editor/SelectionStore`
+- `editor/ViewportStore`
+
+Rule:
+
+The editor owns graph interaction. It does not own inspector rules.
+
+## 3. Node Platform Layer
+
+Responsibilities:
+
+- spec loading
+- palette generation
+- inspector schema composition
+- docs metadata
+- output metadata
+
+Target modules:
+
+- `node-platform/specs`
+- `node-platform/palette`
+- `node-platform/forms`
+- `node-platform/output`
+- `node-platform/docs`
+
+Rule:
+
+Node behavior metadata must come from specs first, not from scattered TypeScript arrays.
+
+## 4. Runtime Layer
+
+Responsibilities:
+
+- websocket transport
+- command dispatch
+- event subscriptions
+- normalized execution state
+
+Target modules:
+
+- `runtime/socket`
+- `runtime/commands`
+- `runtime/events`
+- `runtime/selectors`
+
+Rule:
+
+Realtime transport should not also be the product's top-level business-state god object.
+
+## 5. Extension Layer
+
+Responsibilities:
+
+- register custom renderers
+- register custom widgets
+- register custom docs panels
+- register custom output renderers
+
+Target modules:
+
+- `extensions/forms`
+- `extensions/outputs`
+- `extensions/docs`
+- `extensions/node-families`
+
+Rule:
+
+Use Backstage-style extension points, not one giant mutable registry.
+
+---
+
+## Replacement Map From Current Stack
+
+### Replace now
+
+- `antd`
+- `styled-components`
+
+### Keep
+
+- `react`
+- `react-dom`
+- `vite`
+- `typescript`
+- `reactflow`
+- `zustand`
+- `@tanstack/react-query`
+- `cmdk`
+- `react-virtuoso` in limited targeted usage
+
+### Add
+
+- `@base-ui/react`
+- `react-aria` and related React Aria packages as needed
+- `@tanstack/react-virtual`
+- `@jsonforms/core`
+- `@jsonforms/react`
+- custom renderer package inside the repo
+- a shared token package for color, typography, spacing, radius, elevation, and motion
+
+### Introduce by policy, not just packages
+
+- all new shell and panel components must use the owned design system
+- all new node panels must be driven by schema plus renderer registry
+- no new Ant Design surfaces unless explicitly approved as stopgap work
+
+---
+
+## Migration Plan
+
+### Phase 0: Baseline and freeze
+
+- stop expanding Ant Design usage
+- document current component ownership
+- measure initial bundle and interaction baselines
+
+### Phase 1: Build the owned design system
+
+- establish tokens with CSS variables
+- add base primitives and shell components
+- rebuild shared modal, tabs, form field, select, combobox, tooltip, and panel primitives
+
+### Phase 2: Replace shell surfaces
+
+- top toolbar
+- main dialogs
+- settings panels
+- onboarding
+
+This gets visual consistency quickly without touching the node engine first.
+
+### Phase 3: Introduce schema-driven inspector
+
+- define `NodeSpec`
+- build JSON Forms renderer layer
+- migrate a small vertical slice of node families first
+- keep escape hatches for custom widgets
+
+Suggested first slices:
+
+- simple tool/action nodes
+- API credential nodes
+- scheduler nodes
+
+### Phase 4: Upgrade editor foundation
+
+- move from `reactflow` `11.11.4` to current 12.x generation
+- adopt current performance guidance
+- add grouping and collapse patterns
+
+### Phase 5: Remove old paths
+
+- retire `ParameterRenderer` branching where spec-driven renderers exist
+- retire old output rendering paths
+- retire remaining Ant Design dependencies
+
+---
+
+## UX Direction
+
+The target UX should not imitate a CRUD admin panel.
+
+It should feel like a focused visual tool:
+
+- docked workspace shell instead of page-like cards everywhere
+- compact but readable controls near the canvas
+- command-palette-first navigation for high-frequency actions
+- strong visual hierarchy between graph, inspector, output, and logs
+- progressive disclosure so complex node settings do not overwhelm the default view
+- motion used for orientation and state change, not decoration
+- color and iconography driven by node families and runtime status, not by generic library defaults
+
+Visual implementation rules:
+
+- use one token system for color, spacing, typography, radii, and elevation
+- prefer custom node chrome over generic card components
+- avoid mixing multiple visual idioms from different UI libraries
+- reserve dense data-table patterns for places where tabular analysis is actually required
+- keep node and panel visuals cheap enough for large counts: no heavy shadows, no excessive blur, no constant animation on many elements at once
+
+---
+
+## Risk Assessment
+
+### Main risk
+
+The main risk is not technical failure. The main risk is ending up with two parallel UI systems for too long.
+
+Mitigation:
+
+- freeze new Ant Design surface area
+- migrate by subsystem ownership
+- define one design-token source of truth early
+
+### Secondary risk
+
+Schema-driven systems can become too generic and fail to support rich node-specific UX.
+
+Mitigation:
+
+- allow renderer overrides and custom widgets
+- keep a deliberate escape hatch for specialized nodes
+- make declarative the default, not the only mode
+
+### Third risk
+
+React Flow performance issues can persist if store boundaries remain sloppy.
+
+Mitigation:
+
+- separate canvas state from workflow document state
+- move high-churn state out of broad React trees
+- audit selectors and rerender boundaries before blaming the runtime
+
+---
+
+## Success Criteria
+
+The migration is successful when:
+
+- new nodes can be onboarded mostly by adding spec files
+- the inspector no longer requires broad node-name branching
+- the shell no longer depends on Ant Design for core surfaces
+- the palette and large lists stay responsive at very high counts
+- the node editor supports grouping and collapse for large workflows
+- frontend contributors have a clear component ownership and extension model
+
+---
+
+## Recommended Final Pick
+
+If one concise answer is needed, it is this:
+
+Use `React 19 + React Compiler + React Flow 12 + shadcn ownership model + Base UI primitives + React Aria for advanced collections + Tailwind 4 + TanStack Virtual + JSON Forms`.
+
+That is the best balance of:
+
+- modern UI quality
+- editor performance
+- low migration risk
+- schema-driven extensibility
+- modular frontend architecture
+
+---
+
+## Sources
+
+- [docs-internal/frontend_ui_framework_research.md](frontend_ui_framework_research.md)
+- [React Compiler incremental adoption](https://react.dev/learn/react-compiler/incremental-adoption)
+- [React Compiler 1.0](https://react.dev/blog/2025/10/07/react-compiler-1)
+- [React Flow performance guidance](https://reactflow.dev/learn/advanced-use/performance)
+- [React Flow UI tutorial](https://reactflow.dev/learn/tutorials/getting-started-with-react-flow-components)
+- [Base UI quick start](https://base-ui.com/react/overview/quick-start)
+- [React Aria overview](https://react-aria.adobe.com/)
+- [Mantine styles performance](https://mantine.dev/styles/styles-performance/)
+- [TanStack Virtual introduction](https://tanstack.com/virtual/v3/docs/introduction)
+- [Virtuoso grouped list API](https://virtuoso.dev/react-virtuoso/api-reference/grouped-virtuoso/)
+- [JSON Forms layouts](https://jsonforms.io/docs/uischema/layouts/)
+- [Backstage frontend extensions](https://backstage.io/docs/frontend-system/architecture/extensions/)
+- [Kubernetes custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+- [JSON Schema reference](https://json-schema.org/understanding-json-schema/reference)
diff --git a/package.json b/package.json
index ee98db72..e9261e86 100644
--- a/package.json
+++ b/package.json
@@ -98,7 +98,7 @@
"rimraf": "^6.0.1",
"temporal-server": "^0.0.10",
"agent-browser": "latest",
- "edgymeow": "^0.0.18"
+ "edgymeow": "^0.0.19"
},
"pnpm": {
"peerDependencyRules": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 02079eec..e8322e54 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -18,8 +18,8 @@ importers:
specifier: ^7.0.3
version: 7.0.3
edgymeow:
- specifier: ^0.0.18
- version: 0.0.18
+ specifier: ^0.0.19
+ version: 0.0.19
rimraf:
specifier: ^6.0.1
version: 6.1.2
@@ -68,6 +68,9 @@ importers:
'@types/styled-components':
specifier: ^5.1.34
version: 5.1.36
+ '@uiw/react-json-view':
+ specifier: 2.0.0-alpha.41
'@vitejs/plugin-react':
specifier: ^5.0.0
@@ -119,9 +122,6 @@ importers:
react-js-cron:
specifier: ^5.2.0
- react-json-view-lite:
- specifier: ^2.5.0
- version: 2.5.0([email protected])
react-markdown:
specifier: ^10.1.0
version: 10.1.0(@types/[email protected])([email protected])
@@ -1710,6 +1710,13 @@ packages:
resolution: {integrity: sha512-VFlhGSl4opC0bprJiItPQ1RfUhGDIBokcPwaFH4yiBCaNPeld/9VeXbiPO1cLyorQi1G1vL+ecBk1x8o1axORA==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+ resolution: {integrity: sha512-botRpQ5AgymYEsqXSdT2/1LefAJEYfMntvdnx1SqhTQCTW9HygeFZXx9inkYqUmiQZ3+0QlZnodjBvwnUfZhVA==}
+ peerDependencies:
+ '@babel/runtime': '>=7.10.0'
+ react: '>=18.0.0'
+ react-dom: '>=18.0.0'
+
resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
@@ -2330,8 +2337,8 @@ packages:
resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
engines: {node: '>= 0.4'}
- resolution: {integrity: sha512-+iWozBpK7zOdOqvlFK9AaWKENzcaLdMzSOnivKIg5ynCIBMxUlUoTnGlwt6m8HpG4d30iI3OWA9jtyO4lBlS/A==}
+ resolution: {integrity: sha512-i5poUpZGPrCnaK5D10PlVg91fHdrpqdjwr7dV/MMlbDFHU2YhRWfZ91g6/+NjvcclMqs5ILU8OFWlIujYBGslw==}
engines: {node: '>=18.0.0'}
hasBin: true
@@ -3882,12 +3889,6 @@ packages:
react: '>=17.0.0'
react-dom: '>=17.0.0'
- resolution: {integrity: sha512-tk7o7QG9oYyELWHL8xiMQ8x4WzjCzbWNyig3uexmkLb54r8jO0yH3WCWx8UZS0c49eSA4QUmG5caiRJ8fAn58g==}
- engines: {node: '>=18'}
- peerDependencies:
- react: ^18.0.0 || ^19.0.0
-
resolution: {integrity: sha512-fzmrwMBNGIAiDIrdFMV3NvJhUNl01QC9EMcI8SP7osg51N4j+z6w4tx9i2yWxEEXZ2armLV6EtkFd3KST8PYiA==}
peerDependencies:
@@ -6391,6 +6392,12 @@ snapshots:
'@typescript-eslint/types': 8.54.0
eslint-visitor-keys: 4.2.1
+ dependencies:
+ '@babel/runtime': 7.28.4
+ react: 19.2.1
+ react-dom: 19.2.1([email protected])
+
'@ungap/[email protected]': {}
'@use-gesture/[email protected]': {}
@@ -7128,7 +7135,7 @@ snapshots:
es-errors: 1.3.0
gopd: 1.2.0
dependencies:
chalk: 5.6.2
commander: 11.1.0
@@ -9195,10 +9202,6 @@ snapshots:
react: 19.2.1
react-dom: 19.2.1([email protected])
- dependencies:
- react: 19.2.1
-
dependencies:
'@babel/runtime': 7.28.4