Skip to content

Self-improving AI Employees for everyone

perf(client): persist NodeSpec catalogue + slice-subscription useNodeSpec + stable nodeTypes (Phase 1)

trohitge1eef1e80f27
diff --git a/client/package.json b/client/package.json
index 6b892898..74d1fce0 100644
--- a/client/package.json
+++ b/client/package.json
@@ -24,7 +24,9 @@
"@radix-ui/react-dialog": "^1.1.15",
"@radix-ui/react-slot": "^1.2.4",
"@tailwindcss/typography": "^0.5.19",
- "@tanstack/react-query": "^5",
+ "@tanstack/query-sync-storage-persister": "^5.100.2",
+ "@tanstack/react-query": "^5.100.2",
+ "@tanstack/react-query-persist-client": "^5.100.2",
"@types/google.maps": "^3.58.1",
"@types/node": "^24.3.1",
"@types/prismjs": "^1.26.5",
@@ -79,7 +81,7 @@
},
"devDependencies": {
"@tailwindcss/vite": "^4.2.2",
- "@tanstack/react-query-devtools": "^5.99.0",
+ "@tanstack/react-query-devtools": "^5.100.2",
"@testing-library/jest-dom": "^6.9.1",
"@testing-library/react": "^16.3.2",
"@testing-library/user-event": "^14.5.2",
diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsx
index baa35834..29f8076e 100644
--- a/client/src/Dashboard.tsx
+++ b/client/src/Dashboard.tsx
@@ -101,10 +101,12 @@ const createNodeTypes = (): Record<string, React.ComponentType<any>> => {
return types;
};
-// Create node types once at module load time
-const moduleNodeTypes = createNodeTypes();
-
-// Edge types configuration - enables conditional edge rendering
+// Edge types configuration - enables conditional edge rendering.
+// nodeTypes is built inside the component (see useMemo below) so the
+// build runs after PersistQueryClientProvider has hydrated the cache
+// from localStorage. A module-scope build runs at import time when
+// the cache is always empty, which forces React Flow to remount every
+// canvas node when prefetch lands (the "canvas-wide snap" symptom).
const moduleEdgeTypes = {
conditional: ConditionalEdge,
};
@@ -267,7 +269,7 @@ const DashboardContent: React.FC = () => {
} = useWorkflowManagement();
const { collapsedSections, searchQuery, setSearchQuery, toggleSection } = useComponentPalette();
- const { saveNodeParameters, getAllNodeParameters, executeWorkflow, deployWorkflow, cancelDeployment, nodeStatuses, deploymentStatus, workflowLock, isConnected, sendRequest } = useWebSocket();
+ const { saveNodeParameters, getAllNodeParameters, executeWorkflow, deployWorkflow, cancelDeployment, nodeStatuses, deploymentStatus, workflowLock, isConnected, isReady, sendRequest } = useWebSocket();
const applyUIDefaults = useAppStore((state) => state.applyUIDefaults);
// Workflows list: server-owned data, cached by TanStack Query.
@@ -392,9 +394,14 @@ const DashboardContent: React.FC = () => {
// completes, bumping `specsReady` flips the React Flow nodeTypes ref
// so spec.componentKind dispatch becomes effective (Wave 10.D step 2).
const hasPrefetchedSpecs = React.useRef(false);
- const [specsReady, setSpecsReady] = React.useState(false);
+ // Seed from the persisted cache. With PersistQueryClientProvider in
+ // place the cache is hydrated from localStorage before the first
+ // render, so a warm start can skip the cold→warm remount entirely.
+ const [specsReady, setSpecsReady] = React.useState(
+ () => listCachedNodeSpecs().length > 0,
+ );
React.useEffect(() => {
- if (!isConnected || hasPrefetchedSpecs.current) return;
+ if (!isReady || hasPrefetchedSpecs.current) return;
if (!featureFlags.nodeSpecBackend) {
// When the backend is disabled, mark ready so the legacy fallback
// dispatch runs without waiting on a never-completing prefetch.
@@ -403,7 +410,7 @@ const DashboardContent: React.FC = () => {
}
hasPrefetchedSpecs.current = true;
void prefetchAllNodeSpecs(sendRequest).finally(() => setSpecsReady(true));
- }, [isConnected, sendRequest]);
+ }, [isReady, sendRequest]);
// Update nodes with execution status classes
const styledNodes = React.useMemo(() => {
@@ -542,19 +549,12 @@ const DashboardContent: React.FC = () => {
const proOptions = React.useMemo(() => ({ hideAttribution: true }), []);
- // Wave 10.D step 2: nodeTypes dispatch map. Cold cache uses the
- // module-scope fallback (agents/skills/teamMonitor already correct via
- // hardcoded guards in createNodeTypes); post-prefetch we rebuild and
- // only swap the reference if any mapping genuinely differs, so React
- // Flow doesn't remount every canvas node for a no-op rebuild.
- const nodeTypes = React.useMemo(() => {
- if (!specsReady) return moduleNodeTypes;
- const fresh = createNodeTypes();
- for (const key of Object.keys(fresh)) {
- if (fresh[key] !== moduleNodeTypes[key]) return fresh;
- }
- return moduleNodeTypes;
- }, [specsReady]);
+ // Wave 10.D step 2: nodeTypes dispatch map. Built once per hydration
+ // pass — `specsReady` is seeded from the persisted cache, so warm
+ // starts get a populated map on the first render and no canvas-wide
+ // remount when prefetch lands. Cold first-ever visit still rebuilds
+ // when prefetch finishes (one-time cost per browser).
+ const nodeTypes = React.useMemo(() => createNodeTypes(), [specsReady]);
const edgeTypes = moduleEdgeTypes;
// Execute entire workflow from start node to end
diff --git a/client/src/lib/nodeSpec.ts b/client/src/lib/nodeSpec.ts
index 28a00574..6dedbe36 100644
--- a/client/src/lib/nodeSpec.ts
+++ b/client/src/lib/nodeSpec.ts
@@ -12,7 +12,8 @@
* See C:\\Users\\Tgroh\\.claude\\plans\\typed-splashing-crown.md.
*/
-import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useEffect, useSyncExternalStore } from 'react';
+import { hashKey, useQuery, type UseQueryResult } from '@tanstack/react-query';
import { nodeSpecToDescription, type NodeSpec } from '../adapters/nodeSpecToDescription';
import type { INodeTypeDescription } from '../types/INodeProperties';
import { featureFlags } from './featureFlags';
@@ -73,37 +74,45 @@ export function getCachedNodeSpec(nodeType: string): NodeSpec | null {
}
/**
- * Reactive spec subscription — tRPC `wsLink` / TanStack-Query+WS pattern.
+ * Reactive spec subscription via the QueryCache as an external store.
*
- * The `queryFn` sends a WS request whose Promise resolves via the
- * correlated response. TanStack auto-fires on mount, so cold-cache
- * renders are self-healing — no dependency on `prefetchAllNodeSpecs`
- * running first. When the prefetch does run (same queryKey), it warms
- * the cache and this hook reads from it instantly.
+ * Previous implementation opened a `useQuery` observer per call site;
+ * with ~80 palette items + N canvas nodes that produced 80+N observers,
+ * each woken up on every cache write. The slice-subscription pattern
+ * here re-renders only consumers of the *specific* spec key that
+ * changed — observer count drops to zero. Pattern documented at
+ * https://react.dev/reference/react/useSyncExternalStore and called
+ * out by TanStack's docs as the canonical escape hatch from useQuery.
*
- * References:
- * - TkDodo: https://tkdodo.eu/blog/using-web-sockets-with-react-query
- * - tRPC wsLink: https://trpc.io/docs/client/links/wsLink
+ * Cache population is owned by `prefetchAllNodeSpecs` (boot once) and
+ * the persisted localStorage hydration set up in lib/queryPersist.ts;
+ * a missing key triggers a one-shot lazy fetch via useEffect rather
+ * than a long-lived observer.
*/
export function useNodeSpec(nodeType: string | undefined | null): NodeSpec | null {
- const { sendRequest, isConnected } = useWebSocket();
- const { data } = useQuery<NodeSpec | null>({
- queryKey: nodeSpecQueryKey(nodeType ?? '__none__'),
- queryFn: async () => {
- if (!nodeType) return null;
- try {
- const response = await sendRequest('get_node_spec', { node_type: nodeType });
- return (response?.spec ?? null) as NodeSpec | null;
- } catch {
- return null;
- }
- },
- enabled: !!nodeType && isConnected,
- // Node specs only change with a backend deploy; dev restarts are
- // covered by the WS reconnect handler which invalidates ['nodeSpec'].
- staleTime: STALE_TIME.FOREVER,
- });
- return data ?? null;
+ const { sendRequest, isReady } = useWebSocket();
+ const key = nodeSpecQueryKey(nodeType ?? '__none__');
+
+ const targetHash = hashKey(key);
+ const subscribe = (onChange: () => void) => {
+ const unsub = queryClient.getQueryCache().subscribe((event) => {
+ if (event.query.queryHash === targetHash) onChange();
+ });
+ return unsub;
+ };
+
+ const getSnapshot = () =>
+ queryClient.getQueryData<NodeSpec | null>(key) ?? null;
+
+ const data = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+ useEffect(() => {
+ if (!nodeType || !isReady) return;
+ if (queryClient.getQueryData(key) !== undefined) return;
+ void fetchNodeSpec(nodeType, sendRequest);
+ }, [nodeType, isReady, sendRequest]);
+
+ return data;
}
/**
@@ -114,14 +123,14 @@ export function useNodeSpec(nodeType: string | undefined | null): NodeSpec | nul
* status-check pattern: check data first, error second, loading last.
*/
export function useNodeGroups(): UseQueryResult<Record<string, NodeGroupEntry>> {
- const { sendRequest, isConnected } = useWebSocket();
+ const { sendRequest, isReady } = useWebSocket();
return useQuery<Record<string, NodeGroupEntry>>({
queryKey: nodeGroupsQueryKey,
queryFn: async () => {
const response = await sendRequest('get_node_groups', {});
return (response?.groups ?? {}) as Record<string, NodeGroupEntry>;
},
- enabled: isConnected,
+ enabled: isReady,
staleTime: STALE_TIME.FOREVER,
});
}
diff --git a/client/src/lib/queryPersist.ts b/client/src/lib/queryPersist.ts
new file mode 100644
index 00000000..2f806e21
--- /dev/null
+++ b/client/src/lib/queryPersist.ts
@@ -0,0 +1,71 @@
+/**
+ * TanStack Query persistence wiring.
+ *
+ * Persists the in-memory query cache to localStorage so that on hard
+ * refresh the editor paints node specs / catalogues from last session
+ * instead of waiting for the WebSocket handshake + bulk fetch.
+ *
+ * Buster: tied to root package.json version via Vite's __APP_VERSION__
+ * compile-time constant (see vite.config.js). Bumping the version
+ * automatically purges stale persisted entries on next load.
+ *
+ * Filter: only queries declaring staleTime: STALE_TIME.FOREVER are
+ * persisted. Those carry data that only changes with a backend deploy
+ * (NodeSpec catalogue, node groups). High-frequency / per-session
+ * queries (status, parameters) are not persisted.
+ *
+ * References:
+ * https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient
+ * https://datatracker.ietf.org/doc/html/rfc5861 (stale-while-revalidate)
+ */
+
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+import type { Query } from '@tanstack/react-query';
+
+declare const __APP_VERSION__: string;
+
+const APP_VERSION =
+ typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.0.0';
+
+const STORAGE_KEY = 'machina-query-cache';
+
+export const queryPersister = createSyncStoragePersister({
+ storage: typeof window !== 'undefined' ? window.localStorage : undefined,
+ key: STORAGE_KEY,
+ // Throttle persistence writes so high-frequency cache mutations do
+ // not thrash localStorage. Default is 1000ms which is fine.
+});
+
+/**
+ * Buster string. Persisted cache from a different version is purged on
+ * load. Use the package.json version so a release bump implicitly
+ * invalidates everything.
+ */
+export const queryBuster = APP_VERSION;
+
+/**
+ * Persisted entries are valid for 24h. After that the cache is
+ * discarded on hydrate and refetched fresh. RFC 5861 SWR window.
+ */
+export const queryPersistMaxAge = 24 * 60 * 60 * 1000;
+
+/**
+ * Filter predicate: only persist queries that declare
+ * `staleTime: Infinity`. That is our project-wide marker for
+ * "data only changes with a backend deploy" (catalogues, node specs,
+ * node groups). High-frequency or per-session data stays in memory.
+ *
+ * The key is a defensive string-prefix match in addition to staleTime
+ * so a future regression to the staleTime config does not silently
+ * start persisting noisy keys.
+ */
+const PERSISTED_KEY_PREFIXES = ['nodeSpec', 'nodeGroups', 'pluginCatalogue'];
+
+export function shouldPersistQuery(query: Query): boolean {
+ const key = query.queryKey;
+ if (!Array.isArray(key) || typeof key[0] !== 'string') return false;
+ if (!PERSISTED_KEY_PREFIXES.includes(key[0])) return false;
+ // Only persist successfully resolved queries; do not write error or
+ // pending state to disk.
+ return query.state.status === 'success';
+}
diff --git a/client/src/main.tsx b/client/src/main.tsx
index def1e44d..959ba2c2 100644
--- a/client/src/main.tsx
+++ b/client/src/main.tsx
@@ -1,6 +1,6 @@
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
-import { QueryClientProvider } from '@tanstack/react-query'
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import './index.css'
import App from './App'
@@ -8,10 +8,24 @@ import { ThemeProvider } from './contexts/ThemeContext'
import { AuthProvider } from './contexts/AuthContext'
import { WebSocketProvider } from './contexts/WebSocketContext'
import { queryClient } from './lib/queryClient'
+import {
+ queryPersister,
+ queryBuster,
+ queryPersistMaxAge,
+ shouldPersistQuery,
+} from './lib/queryPersist'
createRoot(document.getElementById('root')!).render(
<StrictMode>
- <QueryClientProvider client={queryClient}>
+ <PersistQueryClientProvider
+ client={queryClient}
+ persistOptions={{
+ persister: queryPersister,
+ buster: queryBuster,
+ maxAge: queryPersistMaxAge,
+ dehydrateOptions: { shouldDehydrateQuery: shouldPersistQuery },
+ }}
+ >
<ThemeProvider>
<AuthProvider>
<WebSocketProvider>
@@ -22,6 +36,6 @@ createRoot(document.getElementById('root')!).render(
{import.meta.env.DEV && (
<ReactQueryDevtools initialIsOpen={false} buttonPosition="bottom-right" />
)}
- </QueryClientProvider>
+ </PersistQueryClientProvider>
</StrictMode>,
)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e356ab2e..557f7ee9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -10,7 +10,7 @@ importers:
dependencies:
agent-browser:
specifier: latest
- version: 0.25.5
+ version: 0.26.0
concurrently:
specifier: ^9.2.1
version: 9.2.1
@@ -43,7 +43,7 @@ importers:
'@lukemorales/query-key-factory':
specifier: ^1.3.4
- version: 1.3.4(@tanstack/[email protected])(@tanstack/[email protected]([email protected]))
+ version: 1.3.4(@tanstack/[email protected])(@tanstack/[email protected]([email protected]))
'@radix-ui/react-collapsible':
specifier: ^1.1.12
@@ -56,9 +56,15 @@ importers:
'@tailwindcss/typography':
specifier: ^0.5.19
version: 0.5.19([email protected])
+ '@tanstack/query-sync-storage-persister':
+ specifier: ^5.100.2
+ version: 5.100.2
'@tanstack/react-query':
- specifier: ^5
- version: 5.99.0([email protected])
+ specifier: ^5.100.2
+ version: 5.100.2([email protected])
+ '@tanstack/react-query-persist-client':
+ specifier: ^5.100.2
'@types/google.maps':
specifier: ^3.58.1
version: 3.58.1
@@ -190,8 +196,8 @@ importers:
specifier: ^4.2.2
'@tanstack/react-query-devtools':
- specifier: ^5.99.0
+ specifier: ^5.100.2
'@testing-library/jest-dom':
specifier: ^6.9.1
version: 6.9.1
@@ -2400,20 +2406,32 @@ packages:
peerDependencies:
vite: ^5.2.0 || ^6 || ^7 || ^8
- '@tanstack/[email protected]':
- resolution: {integrity: sha512-3Jv3WQG0BCcH7G+7lf/bP8QyBfJOXeY+T08Rin3GZ1bshvwlbPt7NrDHMEzGdKIOmOzvIQmxjk28YEQX60k7pQ==}
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-HzzOC7xgSfGGzZ1gTsFZqYz6rxGg3tYF77nTPctin+wEYYLNMP7LjwPVFALEGNdjxkHvcewh1EM5ywixeukS4w==}
- '@tanstack/[email protected]':
- resolution: {integrity: sha512-m4ufXaJ8FjWXw7xDtyzE/6fkZAyQFg9WrbMrUpt8ZecRJx58jiFOZ2lxZMphZdIpAnIeto/S8stbwLKLusyckQ==}
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-0vAp4Y9RyywcZ3gb+wFoiR+pEViDT2ZG/ZaUhn7zXHuUbxuAdeEKuhlh9SDW2vjsPdm9F2AWqplr/QxhOeoqEQ==}
- '@tanstack/[email protected]':
- resolution: {integrity: sha512-CqqX7LCU9yOfCY/vBURSx2YSD83ryfX+QkfkaKionTfg1s2Hdm572Ro99gW3QPoJjzvsj1HM4pnN4nbDy3MXKA==}
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-YbKwdY5FpBvPbsLPcp+Wc8+Q0xvAxyeExAy/4226nYcITw5paKoGb+gglRDiZxyOih19nOPKeOCoX5ZTCOoBFg==}
+
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-/rK8WkiW+9+7Kbu22aS7RNMma/i/xo++uTr4+OrXx1NH/ksQqyTyZA5Km1od7L9sVSFykiXAzZKKRmdgWFKa7g==}
+
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-PE5Pgotl8GKv4Mi0s4YiwTcA+evvb2fHMMWexJDx0D3EsBjtf3MbhYuv9kt+oBnbbsjQj4LJTza2PG2vw2pdOQ==}
+ peerDependencies:
+ '@tanstack/react-query': ^5.100.2
+ react: ^18 || ^19
+
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-uV6M79Dw8SO7u/Wa3oXunOE8P/ktu3LTYjVu9N5NS9kdha7RfMfPecGjq87BzYO2ihq4Y8uSDBk+YisW6+znIA==}
peerDependencies:
- '@tanstack/react-query': ^5.99.0
+ '@tanstack/react-query': ^5.100.2
react: ^18 || ^19
- '@tanstack/[email protected]':
- resolution: {integrity: sha512-OY2bCqPemT1LlqJ8Y2CUau4KELnIhhG9Ol3ZndPbdnB095pRbPo1cHuXTndg8iIwtoHTgwZjyaDnQ0xD0mYwAw==}
+ '@tanstack/[email protected]':
+ resolution: {integrity: sha512-MvvzPcurtzVh4EcbsTfI1BL5GOfdi1S0dk/qhigEghW07MvcHUl/dhfc1FT8hPEquuMtUC+IIAxC0bdmSp/7kA==}
peerDependencies:
react: ^18 || ^19
@@ -2798,8 +2816,8 @@ packages:
resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
engines: {node: '>= 14'}
- resolution: {integrity: sha512-i7ZHsnB0nZIfZoQj9xavTJNX9nckTVVcaaiWFAaOiEQgvGytzVjftA3PIdq0WiuGba8vsxsYH2XMHxs+9bJkIw==}
+ resolution: {integrity: sha512-pdqSfjwbFSp+qnwlb2g23e9wXveIOfMi19xpPA9xZUbzEAUp6W4YBZj6Ybj8z4M7WkcbGDDYc+oDIHDt9R3EDQ==}
hasBin: true
@@ -7806,10 +7824,10 @@ snapshots:
- supports-color
- vue
dependencies:
- '@tanstack/query-core': 5.99.0
- '@tanstack/react-query': 5.99.0([email protected])
+ '@tanstack/query-core': 5.100.2
+ '@tanstack/react-query': 5.100.2([email protected])
'@mdx-js/[email protected]':
dependencies:
@@ -9011,19 +9029,34 @@ snapshots:
tailwindcss: 4.2.2
- '@tanstack/[email protected]': {}
+ '@tanstack/[email protected]': {}
+
+ '@tanstack/[email protected]': {}
- '@tanstack/[email protected]': {}
+ '@tanstack/[email protected]':
+ dependencies:
+ '@tanstack/query-core': 5.100.2
+
+ '@tanstack/[email protected]':
+ dependencies:
+ '@tanstack/query-core': 5.100.2
+ '@tanstack/query-persist-client-core': 5.100.2
+
+ dependencies:
+ '@tanstack/query-devtools': 5.100.2
+ '@tanstack/react-query': 5.100.2([email protected])
+ react: 19.2.1
dependencies:
- '@tanstack/query-devtools': 5.99.0
- '@tanstack/react-query': 5.99.0([email protected])
+ '@tanstack/query-persist-client-core': 5.100.2
+ '@tanstack/react-query': 5.100.2([email protected])
react: 19.2.1
dependencies:
- '@tanstack/query-core': 5.99.0
+ '@tanstack/query-core': 5.100.2
react: 19.2.1
'@testing-library/[email protected]':
@@ -9501,7 +9534,7 @@ snapshots:
dependencies: