@visualli/core 0.1.1

package/src/performance/performanceMonitor.ts

@@ -0,0 +1,145 @@
+// ─── Performance Monitors ─────────────────────────────────────────────────────
+//
+// FPSMonitor     – tracks frame rate via requestAnimationFrame (browser)
+// MemoryMonitor  – polls performance.memory (Chrome)
+// PerformanceProfiler – mark / measure utility for arbitrary operations
+
+import {
+  FPS_TARGET,
+  FPS_SAMPLE_WINDOW,
+  MEMORY_CHECK_INTERVAL,
+} from '../constants/performanceConstants.js';
+
+// ── FPS Monitor ───────────────────────────────────────────────────────────────
+
+export class FPSMonitor {
+  private frameTimes: number[] = [];
+  private lastTime = 0;
+  private currentFPS = FPS_TARGET;
+  private rafId: number | null = null;
+
+  start(): void {
+    if (this.rafId !== null) return;
+
+    const measure = (ts: number) => {
+      if (this.lastTime > 0) {
+        this.frameTimes.push(ts - this.lastTime);
+        if (this.frameTimes.length > FPS_SAMPLE_WINDOW) this.frameTimes.shift();
+        this.currentFPS = this.calc();
+      }
+      this.lastTime = ts;
+      this.rafId = requestAnimationFrame(measure);
+    };
+
+    this.rafId = requestAnimationFrame(measure);
+  }
+
+  stop(): void {
+    if (this.rafId !== null) { cancelAnimationFrame(this.rafId); this.rafId = null; }
+  }
+
+  private calc(): number {
+    if (this.frameTimes.length === 0) return FPS_TARGET;
+    const avg = this.frameTimes.reduce((a, b) => a + b, 0) / this.frameTimes.length;
+    return Math.round(1000 / avg);
+  }
+
+  getFPS(): number { return this.currentFPS; }
+  getAverageFPS(): number { return this.currentFPS; }
+
+  getP95FrameTime(): number {
+    if (this.frameTimes.length === 0) return 0;
+    const sorted = [...this.frameTimes].sort((a, b) => a - b);
+    return sorted[Math.floor(sorted.length * 0.95)];
+  }
+
+  reset(): void { this.frameTimes = []; this.currentFPS = FPS_TARGET; }
+}
+
+// ── Memory Monitor ────────────────────────────────────────────────────────────
+
+export interface MemoryStats {
+  usedJSHeapSize:  number;
+  totalJSHeapSize: number;
+  jsHeapSizeLimit: number;
+  heapUsagePercent: number;
+}
+
+export class MemoryMonitor {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private current = 0;
+
+  start(onUpdate?: (mb: number) => void): void {
+    if (this.timer !== null) return;
+    this.timer = setInterval(() => {
+      this.current = this.measure();
+      onUpdate?.(this.current);
+    }, MEMORY_CHECK_INTERVAL);
+  }
+
+  stop(): void {
+    if (this.timer !== null) { clearInterval(this.timer); this.timer = null; }
+  }
+
+  private measure(): number {
+    const mem = (performance as unknown as Record<string, unknown>)['memory'] as Record<string, number> | undefined;
+    return mem ? mem['usedJSHeapSize'] / (1024 * 1024) : 0;
+  }
+
+  getMemoryMB(): number { return this.current; }
+
+  getStats(): MemoryStats | null {
+    const mem = (performance as unknown as Record<string, unknown>)['memory'] as Record<string, number> | undefined;
+    if (!mem) return null;
+    return {
+      usedJSHeapSize:   mem['usedJSHeapSize'],
+      totalJSHeapSize:  mem['totalJSHeapSize'],
+      jsHeapSizeLimit:  mem['jsHeapSizeLimit'],
+      heapUsagePercent: (mem['usedJSHeapSize'] / mem['jsHeapSizeLimit']) * 100,
+    };
+  }
+
+  static isSupported(): boolean {
+    return !!(performance as unknown as Record<string, unknown>)['memory'];
+  }
+}
+
+// ── Performance Profiler ──────────────────────────────────────────────────────
+
+export class PerformanceProfiler {
+  private marks: Map<string, number> = new Map();
+  private measures: Map<string, number[]> = new Map();
+
+  mark(label: string): void {
+    this.marks.set(label, performance.now());
+  }
+
+  measure(label: string): number {
+    const start = this.marks.get(label);
+    if (start === undefined) return 0;
+    const duration = performance.now() - start;
+    const list = this.measures.get(label) ?? [];
+    list.push(duration);
+    this.measures.set(label, list);
+    this.marks.delete(label);
+    return duration;
+  }
+
+  getAverage(label: string): number {
+    const list = this.measures.get(label);
+    if (!list?.length) return 0;
+    return list.reduce((a, b) => a + b, 0) / list.length;
+  }
+
+  getP95(label: string): number {
+    const list = this.measures.get(label);
+    if (!list?.length) return 0;
+    const sorted = [...list].sort((a, b) => a - b);
+    return sorted[Math.floor(sorted.length * 0.95)];
+  }
+
+  clear(label?: string): void {
+    if (label) { this.marks.delete(label); this.measures.delete(label); }
+    else { this.marks.clear(); this.measures.clear(); }
+  }
+}

package/src/rendering/culling.ts

@@ -0,0 +1,71 @@
+import type { FlatNode, ViewportState } from '../types/index.js';
+import { RBushSpatialIndex } from '../spatial/spatialIndex.js';
+import { calculateViewportBounds } from '../viewport/viewportUtils.js';
+
+export interface CullingOptions {
+  nodes: FlatNode[];
+  viewport: ViewportState;
+  canvasWidth: number;
+  canvasHeight: number;
+  levelFilter?: number;
+  skipCulling?: boolean;
+  isDragging?: boolean;
+  spatialIndex?: RBushSpatialIndex | null;
+  spatialIndexThreshold?: number;
+}
+
+const DEFAULT_SPATIAL_INDEX_THRESHOLD = 200;
+
+/**
+ * Returns the subset of nodes currently visible in the viewport.
+ * Framework-agnostic logic for culling and spatial indexing.
+ */
+export function getViewportVisibleNodes(options: CullingOptions): FlatNode[] {
+  const {
+    nodes,
+    viewport,
+    canvasWidth,
+    canvasHeight,
+    levelFilter,
+    skipCulling = false,
+    isDragging = false,
+    spatialIndex,
+    spatialIndexThreshold = DEFAULT_SPATIAL_INDEX_THRESHOLD,
+  } = options;
+
+  const filtered = levelFilter !== undefined
+    ? nodes.filter(n => n.level === levelFilter)
+    : nodes;
+
+  if (filtered.length === 0) return [];
+
+  // During transitions or drags show all nodes to avoid partial layer appearance
+  if (skipCulling || isDragging) return filtered;
+
+  const bounds = calculateViewportBounds(viewport, canvasWidth, canvasHeight);
+
+  if (filtered.length < spatialIndexThreshold) {
+    return filtered.filter(n =>
+      n.x + n.width  >= bounds.minX &&
+      n.x            <= bounds.maxX &&
+      n.y + n.height >= bounds.minY &&
+      n.y            <= bounds.maxY,
+    );
+  }
+
+  if (spatialIndex) {
+    const nodeIds = spatialIndex.query({
+      minX: bounds.minX, minY: bounds.minY, maxX: bounds.maxX, maxY: bounds.maxY,
+    });
+    const idSet = new Set(nodeIds);
+    return filtered.filter(n => idSet.has(n.id));
+  }
+
+  // Fallback to simple filter if no index provided but threshold exceeded
+  return filtered.filter(n =>
+    n.x + n.width  >= bounds.minX &&
+    n.x            <= bounds.maxX &&
+    n.y + n.height >= bounds.minY &&
+    n.y            <= bounds.maxY,
+  );
+}

package/src/spatial/index.ts

@@ -0,0 +1 @@
+export * from './spatialIndex.js';

package/src/spatial/spatialIndex.ts

@@ -0,0 +1,83 @@
+// ─── Spatial Index ────────────────────────────────────────────────────────────
+//
+// RBush-backed R-tree for O(log n) viewport culling queries.
+// Wraps the `rbush` library with a typed, domain-specific interface.
+
+import RBush from 'rbush';
+
+export interface BoundingBox {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+interface SpatialItem extends BoundingBox {
+  nodeId: string;
+}
+
+export interface ISpatialIndex {
+  insert(nodeId: string, bounds: BoundingBox): void;
+  remove(nodeId: string, bounds: BoundingBox): void;
+  update(nodeId: string, oldBounds: BoundingBox, newBounds: BoundingBox): void;
+  query(bounds: BoundingBox): string[];
+  clear(): void;
+  size(): number;
+  bulkLoad(items: Array<{ nodeId: string; bounds: BoundingBox }>): void;
+}
+
+/**
+ * RBush-based spatial index for efficient viewport culling.
+ *
+ * - Insert / remove / update: O(log n)
+ * - Query:  O(log n + k)  where k = result count
+ * - Bulk load: O(n log n) — use instead of repeated inserts for initial load
+ */
+export class RBushSpatialIndex implements ISpatialIndex {
+  private tree: RBush<SpatialItem>;
+  private cache: Map<string, BoundingBox>;
+
+  constructor() {
+    this.tree  = new RBush<SpatialItem>();
+    this.cache = new Map();
+  }
+
+  insert(nodeId: string, bounds: BoundingBox): void {
+    this.tree.insert({ ...bounds, nodeId });
+    this.cache.set(nodeId, bounds);
+  }
+
+  remove(nodeId: string, bounds: BoundingBox): void {
+    this.tree.remove({ ...bounds, nodeId }, (a, b) => a.nodeId === b.nodeId);
+    this.cache.delete(nodeId);
+  }
+
+  update(nodeId: string, oldBounds: BoundingBox, newBounds: BoundingBox): void {
+    this.remove(nodeId, oldBounds);
+    this.insert(nodeId, newBounds);
+  }
+
+  query(bounds: BoundingBox): string[] {
+    return this.tree.search(bounds).map(item => item.nodeId);
+  }
+
+  clear(): void {
+    this.tree.clear();
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+
+  bulkLoad(items: Array<{ nodeId: string; bounds: BoundingBox }>): void {
+    const rbushItems = items.map(({ nodeId, bounds }) => ({ ...bounds, nodeId }));
+    this.tree.load(rbushItems);
+    for (const { nodeId, bounds } of items) this.cache.set(nodeId, bounds);
+  }
+
+  /** Return the cached bounding box for a node (undefined if not indexed). */
+  getBounds(nodeId: string): BoundingBox | undefined {
+    return this.cache.get(nodeId);
+  }
+}

package/src/stores/index.ts

@@ -0,0 +1,61 @@
+import { createStore } from 'zustand/vanilla';
+import type { NodeSelection, RenderConfig } from '../types/index.js';
+import {
+  DEFAULT_RENDER_CONFIG,
+  getOptimalQualityLevel,
+  getRenderConfigForQuality,
+  isFeatureEnabled,
+  FEATURE_FLAGS,
+} from '../constants/renderConfig.js';
+
+// ─── Selection Store ──────────────────────────────────────────────────────────
+
+export interface ISelectionStore extends NodeSelection {
+  select: (nodeId: string) => void;
+  clear:  () => void;
+  toggle: (nodeId: string) => void;
+  isSelected: (nodeId: string) => boolean;
+}
+
+export const selectionStore = createStore<ISelectionStore>((set, get) => ({
+  selectedId: null,
+  select: (nodeId) => set({ selectedId: nodeId }),
+  clear: () => set({ selectedId: null }),
+  toggle: (nodeId) => set((s) => ({ selectedId: s.selectedId === nodeId ? null : nodeId })),
+  isSelected: (nodeId) => get().selectedId === nodeId,
+}));
+
+// ─── Render Config Store ──────────────────────────────────────────────────────
+
+export interface IRenderConfigStore extends RenderConfig {
+  setQualityLevel:        (level: RenderConfig['qualityLevel']) => void;
+  setRenderMode:          (mode: RenderConfig['renderMode']) => void;
+  setCullingEnabled:      (enabled: boolean) => void;
+  autoAdjustQuality:      (currentFPS: number) => void;
+  autoAdjustQualityByMemory: (memoryMB: number) => void;
+  resetToDefaults:        () => void;
+  isFeatureEnabled:       (feature: keyof typeof FEATURE_FLAGS) => boolean;
+}
+
+export const renderConfigStore = createStore<IRenderConfigStore>((set, get) => ({
+  ...DEFAULT_RENDER_CONFIG,
+
+  setQualityLevel: (level) => set(getRenderConfigForQuality(level)),
+  setRenderMode:   (mode)  => set({ renderMode: mode }),
+  setCullingEnabled: (enabled) => set({ cullingEnabled: enabled }),
+
+  autoAdjustQuality: (fps) =>
+    set((s) => {
+      const q = getOptimalQualityLevel(fps, s.qualityLevel);
+      return q !== s.qualityLevel ? getRenderConfigForQuality(q) : s;
+    }),
+
+  autoAdjustQualityByMemory: (mb) =>
+    set((s) => {
+      const q = mb > 500 ? 'low' : mb > 400 && s.qualityLevel === 'high' ? 'medium' : s.qualityLevel;
+      return q !== s.qualityLevel ? getRenderConfigForQuality(q as RenderConfig['qualityLevel']) : s;
+    }),
+
+  resetToDefaults: () => set({ ...DEFAULT_RENDER_CONFIG }),
+  isFeatureEnabled: (feature) => isFeatureEnabled(feature, get()),
+}));

package/src/types/document.ts

@@ -0,0 +1,15 @@
+// ─── Core .visualli Document ───────────────────────────────────────────────────
+
+import type { VisualliMeta } from './meta.js';
+import type { VisualliLayer } from './layer.js';
+
+/** Parsed .visualli document structure. */
+export interface VisualliDocument {
+  meta: VisualliMeta;
+  /** Keyed by layer ID */
+  layers: Map<string, VisualliLayer>;
+  /** Quick lookup by level */
+  layersByLevel: Map<number, VisualliLayer[]>;
+  /** The level-0 layer */
+  rootLayer: VisualliLayer | null;
+}

package/src/types/index.ts

@@ -0,0 +1,17 @@
+// ─── Types Barrel Export ───────────────────────────────────────────────────────
+
+export * from './mindmap.js';
+export * from './meta.js';
+export * from './layer.js';
+export * from './document.js';
+// Re-export schema types for external use
+export {
+  type Meta,
+  type Node,
+  type Container,
+  type Layer,
+  type Connection,
+  type Extension,
+  type VisualliSpec011,
+  type VisualliFragment,
+} from './schema.js';

package/src/types/layer.ts

@@ -0,0 +1,67 @@
+// ─── Visualli Layer Types ──────────────────────────────────────────────────────
+//
+// These types extend the auto-generated schema types from bindings.
+// They provide stricter runtime guarantees (required arrays) and SDK-specific fields.
+
+import type { Layer, Node, Connection, Container } from './schema.js';
+
+/** Alias to schema Node type for SDK consistency */
+export type LayerNode = Node;
+
+/** Alias to schema Connection type for SDK consistency */
+export type LayerConnection = Connection;
+
+/** Alias to schema Container type for SDK consistency */
+export type LayerContainer = Container;
+
+/**
+ * SDK's stricter version of schema Layer.
+ * - Makes nodes/connections/containers required (always arrays, even if empty)
+ * - Adds SDK-specific `description` field
+ * - Explicitly types key fields to avoid 'unknown' from schema's index signature
+ */
+export interface VisualliLayer {
+  type: 'layer';
+  /** UUID of the layer */
+  id: string;
+  /** Hierarchy level (0 = root) */
+  level: number;
+  /** UUID of the parent layer */
+  parentLayerId?: string;
+  /** UUID of the specific node in parent layer */
+  parentNodeId?: string;
+  /** SDK-specific description field (not in schema) */
+  description?: string;
+  /** Spatial arrangement (inherits from schema) */
+  layout?: 'radial' | 'linear-horizontal' | 'linear-vertical';
+  /** Required array of nodes (schema has optional) */
+  nodes: LayerNode[];
+  /** Required array of connections (schema has optional) */
+  connections: LayerConnection[];
+  /** Required array of containers (schema has optional) */
+  containers: LayerContainer[];
+}
+
+/** Intermediate format for rendering – converts VisualliLayer to flat nodes. */
+export interface VisualliRenderNode {
+  id: string;
+  x: number;
+  y: number;
+  title: string;
+  summary: string;
+  level: number;
+  layerId: string;
+  layerLevel: number;
+  color: string;
+  width: number;
+  height: number;
+  branchCount: number;
+}
+
+export interface VisualliRenderConnection {
+  id: string;
+  from: string;
+  to: string;
+  label?: string;
+  style?: 'dashed' | 'solid';
+}

package/src/types/meta.ts

@@ -0,0 +1,9 @@
+// ─── Visualli Meta ─────────────────────────────────────────────────────────────
+//
+// VisualliMeta is an alias to the schema Meta type.
+// It's imported from the auto-generated bindings to ensure sync with schema changes.
+
+import type { Meta } from './schema.js';
+
+/** Alias to schema Meta type for SDK consistency */
+export type VisualliMeta = Meta;

package/src/types/mindmap.ts

@@ -0,0 +1,136 @@
+// ─── Mindmap Core Types ────────────────────────────────────────────────────────
+
+export interface MindMapNode {
+  id: string;
+  title: string;
+  level: number;
+  x: number;
+  y: number;
+  children?: MindMapNode[];
+  parent?: string;
+  color?: string;
+  relationshipLabel?: string;
+}
+
+/** Flat structure for performance-optimised storage (10K+ nodes). */
+export interface FlatNode {
+  // Identity
+  id: string;
+  parentId: string | null;
+  /** IDs of child nodes for quick tree traversal */
+  childrenIds?: string[];
+
+  // Position (world coordinates)
+  x: number;
+  y: number;
+  /** Alternative position format for compatibility */
+  position?: { x: number; y: number };
+  /** Depth in tree hierarchy */
+  level: number;
+
+  // Content
+  title: string;
+  description?: string;
+  /** Label describing relationship to parent */
+  relationshipLabel?: string;
+
+  // Visual
+  color: string;
+  width: number;
+  height: number;
+
+  // Expansion state (for hierarchical reveal)
+  /** Whether this node's children are visible */
+  isExpanded?: boolean;
+
+  // Metadata
+  branchCount?: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Map-based node storage for O(1) lookups. */
+export type NodeMap = Map<string, FlatNode>;
+
+/** Spatial bounds for RBush indexing. */
+export interface SpatialBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  nodeId: string;
+}
+
+/** Viewport state for camera position and zoom. */
+export interface ViewportState {
+  centerX: number;
+  centerY: number;
+  zoomLevel: number;
+  rotation: number;
+  visibleBounds: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+  };
+}
+
+/** Single-selection node state. */
+export interface NodeSelection {
+  selectedId: string | null;
+}
+
+/** Render configuration flags. */
+export interface RenderConfig {
+  renderMode: 'canvas' | 'simplified';
+  qualityLevel: 'high' | 'medium' | 'low';
+  cullingEnabled: boolean;
+  fpsTarget: number;
+  memoryLimit: number;
+}
+
+export interface MindMapData {
+  nodes: MindMapNode[];
+  connections: MindMapConnection[];
+}
+
+/** Simplified connection type for mindmap rendering (not to be confused with schema Connection) */
+export interface MindMapConnection {
+  from: string;
+  to: string;
+  level: number;
+  label?: string;
+}
+
+export interface TopLevelConnection {
+  from: string;
+  to: string;
+  label: string;
+}
+
+/** Complete mindmap configuration schema. */
+export interface MindMapConfig {
+  metadata: {
+    id?: string;
+    title: string;
+    description?: string;
+    version: string;
+    created: string;
+    lastModified: string;
+  };
+  nodes: MindMapNode[];
+  topLevelConnections: TopLevelConnection[];
+  settings?: {
+    defaultColors?: {
+      level0: string;
+      level1: string;
+      level2: string;
+      level3: string;
+      [key: `level${number}`]: string;
+    };
+    layout?: {
+      nodeSpacing: number;
+      levelSpacing: number;
+    };
+  };
+}

package/src/types/schema.ts

@@ -0,0 +1,36 @@
+// ─── Schema-aligned Types (JSON-schema surface) ────────────────────────────────
+//
+// These types are imported from the auto-generated bindings package.
+// The bindings are generated from visualli.schema.json via GitHub workflow.
+// DO NOT manually define schema types here - they come from @visualli/bindings.
+
+import type { VisualliMeta } from './meta.js';
+import type { VisualliLayer, LayerNode, LayerConnection, LayerContainer } from './layer.js';
+
+// ─── Import Generated Schema Types ────────────────────────────────────────────
+// These are auto-generated from visualli.schema.json
+import type {
+  Meta,
+  Node,
+  Connection,
+  Container,
+  Layer,
+  Extension,
+  VisualliSpec011,
+} from '@visualli/bindings';
+
+// ─── Re-exports ────────────────────────────────────────────────────────────────
+// Export the generated types from bindings
+export type { Meta, Node, Connection, Container, Layer, Extension, VisualliSpec011 };
+
+// Union type for JSONL fragments
+export type VisualliFragment = Meta | Layer;
+
+// Re-export domain types for convenience
+export type {
+  VisualliMeta,
+  VisualliLayer,
+  LayerNode,
+  LayerConnection,
+  LayerContainer,
+};