@omiron33/omi-neuron-web 0.2.21 → 0.2.22

package/README.md

@@ -12,6 +12,9 @@ If you are working inside this repo, also read `AGENTS.md` for execution rules,
 - A CLI that scaffolds configuration, Docker Postgres (pgvector), and Next.js route handlers.
 - A Node/Edge/Cluster data model, plus analysis and embeddings pipelines.
 - A React provider and hooks that wrap the API client.
+- **Static mode** (`StaticDataProvider`) for authored graphs without API/database dependency.
+- **Status-based node coloring** for workflow visualization (draft/active/complete/blocked/archived).
+- **Static cluster rendering** with convex hull boundaries around explicit node groups.
 
 ## Package entry points
 
@@ -99,6 +102,11 @@ export type {
 export * from './react/hooks';
 export { NeuronWebProvider } from './react/NeuronWebProvider';
 
+// Static mode (no API/database required)
+export { StaticDataProvider } from './react/StaticDataProvider';
+export type { StaticDataProviderProps } from './react/StaticDataProvider';
+export { StaticModeError } from './react/static/in-memory-api-client';
+
 // Version constant
 export { VERSION } from './version';
 ```
@@ -300,8 +308,17 @@ export default defineNeuronConfig({
 - analysis fields: `embedding`, `embeddingModel`, `embeddingGeneratedAt`, `clusterId`, `clusterSimilarity`
 - relationship counts: `connectionCount`, `inboundCount`, `outboundCount`
 - status: `analysisStatus`, `analysisError`
+- workflow status: `status?: NodeStatus` (for status-based coloring)
 - visualization hints: `tier`, `visualPriority`, `positionOverride`
 
+`NodeStatus` type (for workflow-based coloring):
+
+```ts
+export type NodeStatus = 'default' | 'draft' | 'active' | 'complete' | 'blocked' | 'archived';
+```
+
+When a node has a `status` set, it takes priority over domain-based coloring in visualization.
+
 Input types:
 
 - `NeuronNodeCreate` (minimal required fields: `label`; optional `slug`, `nodeType`, `domain`, `summary`, `description`, `content`, `metadata`, `tier`)
@@ -334,6 +351,21 @@ Visualization type: `NeuronVisualEdge` uses `from` and `to` slugs.
 - stats: `memberCount`, `avgSimilarity`, `cohesion`
 - metadata: `description`, `keywords`, `metadata`
 
+`NeuronVisualCluster` (for static/authored cluster visualization):
+
+```ts
+export interface NeuronVisualCluster {
+  id: string;
+  label: string;
+  nodeIds: string[];          // explicit node membership
+  color?: string;             // optional cluster color
+  position?: { x: number; y: number; z: number }; // optional fixed center
+  metadata?: Record<string, unknown>;
+}
+```
+
+Visual clusters render as convex hull boundaries around their member nodes with labels at the centroid.
+
 ### Analysis
 
 `AnalysisRun`, `AnalysisRequest`, `AnalysisResponse`, `AnalysisPipelineConfig` are in `src/core/types/analysis.ts`.
@@ -686,6 +718,128 @@ Notes:
 - Keep secrets server-side. Do not pass `OPENAI_API_KEY` (or database URLs) into client components.
 - Configure OpenAI + database access in your Next.js route handlers (see `docs/secure-nextjs-setup.md`).
 
+### StaticDataProvider (Standalone Mode)
+
+Use `StaticDataProvider` for static/authored graphs that don't require API or database connectivity. Perfect for:
+- Quest/narrative authoring tools
+- Documentation/knowledge graphs
+- Workflow/pipeline visualizers
+- Game skill trees
+- Org charts and hierarchies
+
+```tsx
+import { StaticDataProvider, NeuronWeb } from '@omiron33/omi-neuron-web';
+
+const nodes = [
+  { id: 'q001', label: 'Start Quest', domain: 'quest', status: 'complete' },
+  { id: 'q002', label: 'Find Artifact', domain: 'quest', status: 'active' },
+  { id: 'q003', label: 'Return Home', domain: 'quest', status: 'draft' },
+];
+
+const edges = [
+  { id: 'e1', from: 'q001', to: 'q002', relationshipType: 'leads_to' },
+  { id: 'e2', from: 'q002', to: 'q003', relationshipType: 'leads_to' },
+];
+
+const clusters = [
+  { id: 'act1', label: 'Act 1', nodeIds: ['q001', 'q002'], color: '#4a5568' },
+  { id: 'act2', label: 'Act 2', nodeIds: ['q003'], color: '#2d3748' },
+];
+
+export default function QuestGraph() {
+  return (
+    <StaticDataProvider
+      nodes={nodes}
+      edges={edges}
+      clusters={clusters}
+      mutableMode={false}
+    >
+      <NeuronWeb graphData={{ nodes, edges, clusters }} />
+    </StaticDataProvider>
+  );
+}
+```
+
+`StaticDataProviderProps`:
+
+```ts
+interface StaticDataProviderProps {
+  children: React.ReactNode;
+  nodes: (NeuronNode | NeuronVisualNode)[];
+  edges: (NeuronEdge | NeuronVisualEdge)[];
+  clusters?: NeuronVisualCluster[];
+  settings?: Partial<NeuronSettings>;
+  mutableMode?: boolean;  // if true, mutations modify in-memory store
+  onEvent?: (event: NeuronEvent) => void;
+  onError?: (error: Error, context: ErrorContext) => void;
+}
+```
+
+Behavior:
+- All hooks (`useNeuronNodes`, `useNeuronGraph`, etc.) work unchanged
+- Analysis and search methods throw `StaticModeError` (not available in static mode)
+- Context provides `isStaticMode: true` flag
+- Data updates via `updateData()` on the internal client or by passing new props
+
+### Status-based coloring
+
+Nodes with a `status` field render with status colors that override domain colors:
+
+```ts
+const DEFAULT_STATUS_COLORS = {
+  default: '#c0c5ff',   // Same as defaultDomainColor
+  draft: '#9ca3af',     // Gray
+  active: '#4ade80',    // Green
+  complete: '#60a5fa',  // Blue
+  blocked: '#f87171',   // Red
+  archived: '#6b7280',  // Dark gray
+};
+```
+
+Override via theme:
+
+```tsx
+<NeuronWeb
+  graphData={graphData}
+  theme={{
+    colors: {
+      statusColors: {
+        default: '#c0c5ff',
+        draft: '#888888',
+        active: '#00ff00',
+        complete: '#0088ff',
+        blocked: '#ff0000',
+        archived: '#444444',
+      },
+    },
+  }}
+/>
+```
+
+### Static clusters (convex hull visualization)
+
+Pass `clusters` in `graphData` to render convex hull boundaries around node groups:
+
+```tsx
+<NeuronWeb
+  graphData={{
+    nodes,
+    edges,
+    clusters: [
+      { id: 'cluster1', label: 'Group A', nodeIds: ['n1', 'n2', 'n3'], color: '#4a5568' },
+      { id: 'cluster2', label: 'Group B', nodeIds: ['n4', 'n5'], color: '#2d3748' },
+    ],
+  }}
+/>
+```
+
+Cluster rendering:
+- Computes 2D convex hull from projected node positions (Graham scan algorithm)
+- Renders semi-transparent mesh fill with border outline
+- Displays label at cluster centroid
+- Updates when node positions change (e.g., ambient motion)
+- Requires 3+ nodes to show hull; fewer shows only the label
+
 ### Hooks
 
 - `useNeuronContext()` -> access provider context.
@@ -729,6 +883,7 @@ export interface NeuronWebProps {
     nodes: NeuronVisualNode[];
     edges: NeuronVisualEdge[];
     storyBeats?: NeuronStoryBeat[];
+    clusters?: NeuronVisualCluster[];
   };
   fullHeight?: boolean;
   isFullScreen?: boolean;
@@ -1059,8 +1214,9 @@ Key behavior in `NeuronWeb`:
 Key internal modules:
 
 - `src/visualization/scene/scene-manager.ts` - sets up Three.js scene, camera, renderer, lights, starfield, labels.
-- `src/visualization/scene/node-renderer.ts` - renders nodes, labels, hover/selection states.
+- `src/visualization/scene/node-renderer.ts` - renders nodes, labels, hover/selection states, status-based coloring.
 - `src/visualization/scene/edge-renderer.ts` - renders edges, flow animations.
+- `src/visualization/scene/cluster-renderer.ts` - renders convex hull boundaries around static clusters.
 - `src/visualization/interactions/interaction-manager.ts` - hover/click/double-click handling.
 - `src/visualization/animations/animation-controller.ts` - camera focus/transition animations.
 - `src/visualization/layouts/fuzzy-layout.ts` - layout generation.

package/dist/{NeuronWebExplorer-lBM0Jcf9.d.ts → NeuronWebExplorer-CB7Vkkce.d.cts}

@@ -1,5 +1,5 @@
 import React__default from 'react';
-import { N as NeuronVisualNode, a as NeuronVisualEdge, b as NeuronNode, c as NeuronEdge, d as NodeTier } from './edge-U2Qgwg-K.js';
+import { N as NeuronVisualNode, a as NeuronVisualEdge, b as NeuronVisualCluster, c as NeuronNode, d as NeuronEdge, e as NodeStatus, f as NodeTier } from './cluster-CU_pBUcK.cjs';
 
 interface NeuronStoryBeat {
     id: string;
@@ -36,6 +36,8 @@ interface NeuronWebTheme {
         background: string;
         domainColors: Record<string, string>;
         defaultDomainColor: string;
+        /** Status-based node colors for workflow visualization */
+        statusColors?: Record<NodeStatus, string>;
         edgeDefault: string;
         edgeActive: string;
         edgeSelected: string;
@@ -283,6 +285,8 @@ interface NeuronWebProps {
         nodes: NeuronVisualNode[];
         edges: NeuronVisualEdge[];
         storyBeats?: NeuronStoryBeat[];
+        /** Static cluster definitions for visual grouping */
+        clusters?: NeuronVisualCluster[];
     };
     fullHeight?: boolean;
     isFullScreen?: boolean;

package/dist/{NeuronWebExplorer-7sRtXdqa.d.cts → NeuronWebExplorer-DFyhvtXO.d.ts}

@@ -1,5 +1,5 @@
 import React__default from 'react';
-import { N as NeuronVisualNode, a as NeuronVisualEdge, b as NeuronNode, c as NeuronEdge, d as NodeTier } from './edge-U2Qgwg-K.cjs';
+import { N as NeuronVisualNode, a as NeuronVisualEdge, b as NeuronVisualCluster, c as NeuronNode, d as NeuronEdge, e as NodeStatus, f as NodeTier } from './cluster-CU_pBUcK.js';
 
 interface NeuronStoryBeat {
     id: string;
@@ -36,6 +36,8 @@ interface NeuronWebTheme {
         background: string;
         domainColors: Record<string, string>;
         defaultDomainColor: string;
+        /** Status-based node colors for workflow visualization */
+        statusColors?: Record<NodeStatus, string>;
         edgeDefault: string;
         edgeActive: string;
         edgeSelected: string;
@@ -283,6 +285,8 @@ interface NeuronWebProps {
         nodes: NeuronVisualNode[];
         edges: NeuronVisualEdge[];
         storyBeats?: NeuronStoryBeat[];
+        /** Static cluster definitions for visual grouping */
+        clusters?: NeuronVisualCluster[];
     };
     fullHeight?: boolean;
     isFullScreen?: boolean;

package/dist/api/index.d.cts

@@ -1,7 +1,7 @@
-import { G as GraphStoreContext, N as NeuronConfig, a as GraphStore, E as EmbeddingProvider, S as SelectOptions, W as WhereClause, b as NeuronCluster, c as NeuronSettings, d as NeuronSettingsUpdate, A as AnalysisRun, e as SuggestedEdge, f as SuggestedEdgeCreate, g as SuggestedEdgeListParams, C as ConnectorType, I as IngestionSource, h as IngestionSourceItem, i as IngestionSyncRun, j as SyncRunStatus, k as GetGraphParams, l as ExpandGraphRequest, F as FindPathRequest, m as GetGraphResponse, n as ExpandGraphResponse, o as FindPathResponse } from '../query-helpers-DMnkjfO0.cjs';
-export { p as AnalysisRequest, q as AnalysisResponse, ac as ApiErrorResponse, T as ApproveSuggestionResponse, V as BulkApproveSuggestionsRequest, X as BulkApproveSuggestionsResponse, _ as BulkRejectSuggestionsRequest, $ as BulkRejectSuggestionsResponse, O as CancelAnalysisResponse, B as CreateEdgesRequest, H as CreateEdgesResponse, v as CreateNodesRequest, w as CreateNodesResponse, K as DeleteEdgeResponse, D as DeleteNodeResponse, a5 as FindSimilarOptions, a4 as FindSimilarRequest, a6 as FindSimilarResponse, M as GetAnalysisJobResponse, x as GetNodeResponse, a7 as GetSettingsResponse, t as GraphFilters, ad as HealthCheckResponse, y as ListEdgesParams, z as ListEdgesResponse, L as ListNodesParams, u as ListNodesResponse, Q as ListSuggestionsParams, R as ListSuggestionsResponse, s as PaginationMeta, r as PaginationParams, P as PostgresGraphStore, Y as RejectSuggestionRequest, Z as RejectSuggestionResponse, aa as ResetSettingsRequest, ab as ResetSettingsResponse, a3 as SearchResult, a1 as SemanticSearchOptions, a0 as SemanticSearchRequest, a2 as SemanticSearchResponse, J as UpdateEdgeRequest, U as UpdateNodeRequest, a8 as UpdateSettingsRequest, a9 as UpdateSettingsResponse } from '../query-helpers-DMnkjfO0.cjs';
+import { G as GraphStoreContext, N as NeuronConfig, a as GraphStore, E as EmbeddingProvider, S as SelectOptions, W as WhereClause, b as NeuronSettings, c as NeuronSettingsUpdate, A as AnalysisRun, d as SuggestedEdge, e as SuggestedEdgeCreate, f as SuggestedEdgeListParams, C as ConnectorType, I as IngestionSource, g as IngestionSourceItem, h as IngestionSyncRun, i as SyncRunStatus, j as GetGraphParams, k as ExpandGraphRequest, F as FindPathRequest, l as GetGraphResponse, m as ExpandGraphResponse, n as FindPathResponse } from '../query-helpers-CA23s1ct.cjs';
+export { o as AnalysisRequest, p as AnalysisResponse, ab as ApiErrorResponse, R as ApproveSuggestionResponse, T as BulkApproveSuggestionsRequest, V as BulkApproveSuggestionsResponse, Z as BulkRejectSuggestionsRequest, _ as BulkRejectSuggestionsResponse, M as CancelAnalysisResponse, z as CreateEdgesRequest, B as CreateEdgesResponse, u as CreateNodesRequest, v as CreateNodesResponse, J as DeleteEdgeResponse, D as DeleteNodeResponse, a4 as FindSimilarOptions, a3 as FindSimilarRequest, a5 as FindSimilarResponse, K as GetAnalysisJobResponse, w as GetNodeResponse, a6 as GetSettingsResponse, s as GraphFilters, ac as HealthCheckResponse, x as ListEdgesParams, y as ListEdgesResponse, L as ListNodesParams, t as ListNodesResponse, O as ListSuggestionsParams, Q as ListSuggestionsResponse, r as PaginationMeta, q as PaginationParams, P as PostgresGraphStore, X as RejectSuggestionRequest, Y as RejectSuggestionResponse, a9 as ResetSettingsRequest, aa as ResetSettingsResponse, a2 as SearchResult, a0 as SemanticSearchOptions, $ as SemanticSearchRequest, a1 as SemanticSearchResponse, H as UpdateEdgeRequest, U as UpdateNodeRequest, a7 as UpdateSettingsRequest, a8 as UpdateSettingsResponse } from '../query-helpers-CA23s1ct.cjs';
 import { D as Database } from '../database-B0vplyA4.cjs';
-import { b as NeuronNode, e as NeuronNodeCreate, f as NeuronNodeUpdate, c as NeuronEdge, g as NeuronEdgeCreate, h as NeuronEdgeUpdate } from '../edge-U2Qgwg-K.cjs';
+import { c as NeuronNode, g as NeuronNodeCreate, i as NeuronNodeUpdate, d as NeuronEdge, j as NeuronEdgeCreate, k as NeuronEdgeUpdate, h as NeuronCluster } from '../cluster-CU_pBUcK.cjs';
 import 'pg';
 
 type RouteHandler = (request: Request) => Promise<Response>;

package/dist/api/index.d.ts

@@ -1,7 +1,7 @@
-import { G as GraphStoreContext, N as NeuronConfig, a as GraphStore, E as EmbeddingProvider, S as SelectOptions, W as WhereClause, b as NeuronCluster, c as NeuronSettings, d as NeuronSettingsUpdate, A as AnalysisRun, e as SuggestedEdge, f as SuggestedEdgeCreate, g as SuggestedEdgeListParams, C as ConnectorType, I as IngestionSource, h as IngestionSourceItem, i as IngestionSyncRun, j as SyncRunStatus, k as GetGraphParams, l as ExpandGraphRequest, F as FindPathRequest, m as GetGraphResponse, n as ExpandGraphResponse, o as FindPathResponse } from '../query-helpers-BpVwXZJk.js';
-export { p as AnalysisRequest, q as AnalysisResponse, ac as ApiErrorResponse, T as ApproveSuggestionResponse, V as BulkApproveSuggestionsRequest, X as BulkApproveSuggestionsResponse, _ as BulkRejectSuggestionsRequest, $ as BulkRejectSuggestionsResponse, O as CancelAnalysisResponse, B as CreateEdgesRequest, H as CreateEdgesResponse, v as CreateNodesRequest, w as CreateNodesResponse, K as DeleteEdgeResponse, D as DeleteNodeResponse, a5 as FindSimilarOptions, a4 as FindSimilarRequest, a6 as FindSimilarResponse, M as GetAnalysisJobResponse, x as GetNodeResponse, a7 as GetSettingsResponse, t as GraphFilters, ad as HealthCheckResponse, y as ListEdgesParams, z as ListEdgesResponse, L as ListNodesParams, u as ListNodesResponse, Q as ListSuggestionsParams, R as ListSuggestionsResponse, s as PaginationMeta, r as PaginationParams, P as PostgresGraphStore, Y as RejectSuggestionRequest, Z as RejectSuggestionResponse, aa as ResetSettingsRequest, ab as ResetSettingsResponse, a3 as SearchResult, a1 as SemanticSearchOptions, a0 as SemanticSearchRequest, a2 as SemanticSearchResponse, J as UpdateEdgeRequest, U as UpdateNodeRequest, a8 as UpdateSettingsRequest, a9 as UpdateSettingsResponse } from '../query-helpers-BpVwXZJk.js';
+import { G as GraphStoreContext, N as NeuronConfig, a as GraphStore, E as EmbeddingProvider, S as SelectOptions, W as WhereClause, b as NeuronSettings, c as NeuronSettingsUpdate, A as AnalysisRun, d as SuggestedEdge, e as SuggestedEdgeCreate, f as SuggestedEdgeListParams, C as ConnectorType, I as IngestionSource, g as IngestionSourceItem, h as IngestionSyncRun, i as SyncRunStatus, j as GetGraphParams, k as ExpandGraphRequest, F as FindPathRequest, l as GetGraphResponse, m as ExpandGraphResponse, n as FindPathResponse } from '../query-helpers-CdDGFiK3.js';
+export { o as AnalysisRequest, p as AnalysisResponse, ab as ApiErrorResponse, R as ApproveSuggestionResponse, T as BulkApproveSuggestionsRequest, V as BulkApproveSuggestionsResponse, Z as BulkRejectSuggestionsRequest, _ as BulkRejectSuggestionsResponse, M as CancelAnalysisResponse, z as CreateEdgesRequest, B as CreateEdgesResponse, u as CreateNodesRequest, v as CreateNodesResponse, J as DeleteEdgeResponse, D as DeleteNodeResponse, a4 as FindSimilarOptions, a3 as FindSimilarRequest, a5 as FindSimilarResponse, K as GetAnalysisJobResponse, w as GetNodeResponse, a6 as GetSettingsResponse, s as GraphFilters, ac as HealthCheckResponse, x as ListEdgesParams, y as ListEdgesResponse, L as ListNodesParams, t as ListNodesResponse, O as ListSuggestionsParams, Q as ListSuggestionsResponse, r as PaginationMeta, q as PaginationParams, P as PostgresGraphStore, X as RejectSuggestionRequest, Y as RejectSuggestionResponse, a9 as ResetSettingsRequest, aa as ResetSettingsResponse, a2 as SearchResult, a0 as SemanticSearchOptions, $ as SemanticSearchRequest, a1 as SemanticSearchResponse, H as UpdateEdgeRequest, U as UpdateNodeRequest, a7 as UpdateSettingsRequest, a8 as UpdateSettingsResponse } from '../query-helpers-CdDGFiK3.js';
 import { D as Database } from '../database-B0vplyA4.js';
-import { b as NeuronNode, e as NeuronNodeCreate, f as NeuronNodeUpdate, c as NeuronEdge, g as NeuronEdgeCreate, h as NeuronEdgeUpdate } from '../edge-U2Qgwg-K.js';
+import { c as NeuronNode, g as NeuronNodeCreate, i as NeuronNodeUpdate, d as NeuronEdge, j as NeuronEdgeCreate, k as NeuronEdgeUpdate, h as NeuronCluster } from '../cluster-CU_pBUcK.js';
 import 'pg';
 
 type RouteHandler = (request: Request) => Promise<Response>;