Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(output): schema-ready OutputPanel + frontend UI migration RFC
trohitg4cb3dd98f9d6
diff --git a/client/package.json b/client/package.jsonindex 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.tsxnew file mode 100644index 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.tsxindex 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+ <OutputPanelresults={combinedResults}onClear={onClearResults}selectedNode={selectedNode}diff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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++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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonindex 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.yamlindex 02079eec..e8322e54 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -18,8 +18,8 @@ importers:specifier: ^7.0.3version: 7.0.3edgymeow:- specifier: ^0.0.18- version: 0.0.18+ specifier: ^0.0.19+ version: 0.0.19rimraf:specifier: ^6.0.1version: 6.1.2@@ -68,6 +68,9 @@ importers:'@types/styled-components':specifier: ^5.1.34version: 5.1.36+ '@uiw/react-json-view':+ specifier: 2.0.0-alpha.41+ version: 2.0.0-alpha.41(@babel/[email protected])([email protected]([email protected]))([email protected])'@vitejs/plugin-react':specifier: ^5.0.0@@ -119,9 +122,6 @@ importers:react-js-cron:specifier: ^5.2.0version: 5.2.0([email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])- react-json-view-lite:- specifier: ^2.5.0- version: 2.5.0([email protected])react-markdown:specifier: ^10.1.0version: 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}+ '@uiw/[email protected]':+ resolution: {integrity: sha512-botRpQ5AgymYEsqXSdT2/1LefAJEYfMntvdnx1SqhTQCTW9HygeFZXx9inkYqUmiQZ3+0QlZnodjBvwnUfZhVA==}+ peerDependencies:+ '@babel/runtime': '>=7.10.0'+ react: '>=18.0.0'+ react-dom: '>=18.0.0'+'@ungap/[email protected]':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.0eslint-visitor-keys: 4.2.1+ '@uiw/[email protected](@babel/[email protected])([email protected]([email protected]))([email protected])':+ 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.0gopd: 1.2.0dependencies:chalk: 5.6.2commander: 11.1.0@@ -9195,10 +9202,6 @@ snapshots:react: 19.2.1react-dom: 19.2.1([email protected])- dependencies:- react: 19.2.1-dependencies:'@babel/runtime': 7.28.4