@visualli/core 0.1.1

package/src/constants/renderConfig.ts

@@ -0,0 +1,134 @@
+// ─── Render Configuration ─────────────────────────────────────────────────────
+
+import type { RenderConfig } from '../types/mindmap.js';
+import {
+  FPS_TARGET,
+  MEMORY_TARGET_MB,
+  QUALITY_HIGH,
+  QUALITY_MEDIUM,
+  QUALITY_LOW,
+  NODE_COUNT_THRESHOLDS,
+} from './performanceConstants.js';
+
+// ── Defaults ──────────────────────────────────────────────────────────────────
+
+export const DEFAULT_RENDER_CONFIG: RenderConfig = {
+  renderMode:    'canvas',
+  qualityLevel:  'high',
+  cullingEnabled: false,
+  fpsTarget:     FPS_TARGET,
+  memoryLimit:   MEMORY_TARGET_MB,
+};
+
+export const SIMPLIFIED_RENDER_CONFIG: RenderConfig = {
+  renderMode:    'simplified',
+  qualityLevel:  'low',
+  cullingEnabled: true,
+  fpsTarget:     30,
+  memoryLimit:   400,
+};
+
+// ── Quality Map ───────────────────────────────────────────────────────────────
+
+export const QUALITY_SETTINGS = {
+  high:   QUALITY_HIGH,
+  medium: QUALITY_MEDIUM,
+  low:    QUALITY_LOW,
+} as const;
+
+// ── Feature Flags ─────────────────────────────────────────────────────────────
+
+export const FEATURE_FLAGS = {
+  viewportCulling:        true,
+  spatialIndexing:        true,
+  shadows:                true,
+  bezierCurves:           true,
+  animations:             true,
+  branchBadges:           true,
+  autoQualityAdjustment:  true,
+  performanceMonitoring:  true,
+  performanceToasts:      true,
+  debugOverlay:           false,
+  showFPS:                false,
+  showMemory:             false,
+  showVisibleCount:       false,
+} as const;
+
+// ── Render Modes ──────────────────────────────────────────────────────────────
+
+export type RenderMode     = RenderConfig['renderMode'];
+export type QualityLevel   = RenderConfig['qualityLevel'];
+
+export const RENDER_MODES = {
+  canvas: {
+    name:        'Canvas',
+    description: 'Full Konva canvas rendering with all features',
+    features:    { culling: true, shadows: true, bezierCurves: true, animations: true },
+  },
+  simplified: {
+    name:        'Simplified',
+    description: 'Reduced feature set for low-end devices',
+    features:    { culling: true, shadows: false, bezierCurves: false, animations: false },
+  },
+} as const;
+
+export const QUALITY_LEVELS = {
+  high:   { name: 'High',   description: 'All visual features enabled',              targetFPS: 60, features: QUALITY_HIGH   },
+  medium: { name: 'Medium', description: 'Shadows disabled, other features enabled', targetFPS: 60, features: QUALITY_MEDIUM },
+  low:    { name: 'Low',    description: 'Minimal visual features, max performance', targetFPS: 30, features: QUALITY_LOW    },
+} as const;
+
+// ── Auto-Adjustment Helpers ───────────────────────────────────────────────────
+
+export function getOptimalQualityLevel(
+  currentFPS: number,
+  currentQuality: QualityLevel,
+): QualityLevel {
+  if (currentFPS < 45 && currentQuality === 'high')   return 'medium';
+  if (currentFPS < 30 && currentQuality === 'medium') return 'low';
+  if (currentFPS > 58 && currentQuality === 'low')    return 'medium';
+  if (currentFPS > 58 && currentQuality === 'medium') return 'high';
+  return currentQuality;
+}
+
+export function getRenderConfigForQuality(quality: QualityLevel): Partial<RenderConfig> {
+  return { qualityLevel: quality, fpsTarget: QUALITY_LEVELS[quality].targetFPS };
+}
+
+export function isFeatureEnabled(
+  featureName: keyof typeof FEATURE_FLAGS,
+  config: RenderConfig,
+): boolean {
+  if (!FEATURE_FLAGS[featureName]) return false;
+
+  const qs = QUALITY_SETTINGS[config.qualityLevel];
+  switch (featureName) {
+    case 'shadows':      return qs.shadows;
+    case 'bezierCurves': return qs.bezierCurves;
+    case 'animations':   return qs.animations;
+    default:             return FEATURE_FLAGS[featureName] as boolean;
+  }
+}
+
+// ── Device Detection ──────────────────────────────────────────────────────────
+
+/**
+ * Recommend a render config based on detected device memory (browser only).
+ * Falls back to SIMPLIFIED_RENDER_CONFIG when the Performance Memory API is
+ * unavailable or memory is constrained.
+ */
+export function getRecommendedRenderConfig(): RenderConfig {
+  if (typeof performance === 'undefined' || !(performance as unknown as Record<string, unknown>)['memory']) {
+    return SIMPLIFIED_RENDER_CONFIG;
+  }
+
+  const memory = (performance as unknown as Record<string, unknown>)['memory'] as Record<string, number>;
+  if (memory?.['jsHeapSizeLimit'] && memory['jsHeapSizeLimit'] < 512 * 1024 * 1024) {
+    return SIMPLIFIED_RENDER_CONFIG;
+  }
+
+  return DEFAULT_RENDER_CONFIG;
+}
+
+/** Re-export so consumers need only one import. */
+export { NODE_COUNT_THRESHOLDS };

package/src/index.ts

@@ -0,0 +1,18 @@
+// ─── @visualli/core — Main Barrel Export ────────────────────────────────────
+//
+// Import from sub-paths for tree-shaking (e.g. `@visualli/core/layout`),
+// or use the main barrel for convenience.
+
+export * from './types/index.js';
+export * from './layout/index.js';
+export * from './parser/index.js';
+export * from './constants/index.js';
+export * from './viewport/index.js';
+export * from './performance/index.js';
+export * from './animations/index.js';
+export * from './spatial/index.js';
+export * from './stores/index.js';
+export * from './utils/navigation.js';
+export * from './rendering/culling.js';
+export * from './config/textScaling.js';
+export * from './config/blobShapes.js';

package/src/layout/circularLayout.ts

@@ -0,0 +1,95 @@
+// ─── Circular Layout Algorithm ────────────────────────────────────────────────
+//
+// Positions nodes in a uniform circle with equal angular spacing.
+// PATTERN : Uniform circular distribution (polar coordinates)
+// SPACING : Equal angular intervals (2π/n)
+// ORIGIN  : Configurable center (default 0, 0)
+// RADIUS  : Configurable percentage of container (default 13.5%)
+
+import type { FlatNode } from '../types/mindmap.js';
+
+export interface CircularLayoutOptions {
+  /** Radius as a fraction of the container's minimum dimension (0–1). Default: 0.135 */
+  radiusPercentage?: number;
+  /** Container width used to calculate absolute radius. Default: 2000 */
+  containerWidth?: number;
+  /** Container height used to calculate absolute radius. Default: 2000 */
+  containerHeight?: number;
+  /** World-space X of the circle centre. Default: 0 */
+  centerX?: number;
+  /** World-space Y of the circle centre. Default: 0 */
+  centerY?: number;
+}
+
+/**
+ * Apply circular layout to a set of nodes.
+ * Mutates the `x` / `y` properties of each node and returns the same array.
+ */
+export function applyCircularLayout(
+  nodes: FlatNode[],
+  options: CircularLayoutOptions = {},
+): FlatNode[] {
+  const {
+    radiusPercentage = 0.135,
+    containerWidth = 2000,
+    containerHeight = 2000,
+    centerX = 0,
+    centerY = 0,
+  } = options;
+
+  if (nodes.length === 0) return nodes;
+
+  if (nodes.length === 1) {
+    nodes[0].x = centerX;
+    nodes[0].y = centerY;
+    return nodes;
+  }
+
+  const radius = Math.min(containerWidth, containerHeight) * radiusPercentage;
+
+  // n=2 → horizontal; n≥3 → start at 12 o'clock
+  const startAngle = nodes.length === 2 ? 0 : -Math.PI / 2;
+  const angleStep = (2 * Math.PI) / nodes.length;
+
+  for (let i = 0; i < nodes.length; i++) {
+    const angle = startAngle + i * angleStep;
+    nodes[i].x = centerX + radius * Math.cos(angle);
+    nodes[i].y = centerY + radius * Math.sin(angle);
+  }
+
+  return nodes;
+}
+
+/**
+ * Calculate the minimum radius needed to prevent node boxes from overlapping.
+ *
+ * Uses the chord-length formula: `chord = 2r · sin(θ/2)`, solved for `r`.
+ */
+export function calculateMinimumRadius(
+  nodeCount: number,
+  nodeWidth = 200,
+  nodePadding = 150,
+): number {
+  if (nodeCount <= 1) return 0;
+  const angleStep = (2 * Math.PI) / nodeCount;
+  const minChordLength = nodeWidth + nodePadding;
+  return minChordLength / (2 * Math.sin(angleStep / 2));
+}
+
+/**
+ * Calculate the optimal radius percentage for a given node count,
+ * ensuring sufficient spacing for edge labels.
+ *
+ * @returns A value in [0.135, 0.45]
+ */
+export function calculateOptimalRadiusPercentage(
+  nodeCount: number,
+  containerWidth = 2000,
+  containerHeight = 2000,
+  nodeWidth = 200,
+  nodePadding = 120,
+): number {
+  const minRadius = calculateMinimumRadius(nodeCount, nodeWidth, nodePadding);
+  const minDimension = Math.min(containerWidth, containerHeight);
+  return Math.min(0.45, Math.max(0.135, minRadius / minDimension));
+}

package/src/layout/index.ts

@@ -0,0 +1,3 @@
+export * from './circularLayout.js';
+export * from './linearLayout.js';
+export * from './layoutUtils.js';

package/src/layout/layoutUtils.ts

@@ -0,0 +1,132 @@
+// ─── Layout Utilities ─────────────────────────────────────────────────────────
+//
+// Collision detection and force-based positioning for MindMapNode trees.
+
+import type { MindMapNode } from '../types/mindmap.js';
+
+export interface CollisionBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Axis-aligned bounding box for a node, expanded by a fixed padding. */
+export function getNodeBounds(node: MindMapNode): CollisionBox {
+  const baseWidth = Math.max(120, node.title.length * 8 + 40);
+  const baseHeight = Math.max(40, 32 + 16);
+  const padding = 20;
+  return {
+    x: node.x - baseWidth / 2 - padding,
+    y: node.y - baseHeight / 2 - padding,
+    width: baseWidth + padding * 2,
+    height: baseHeight + padding * 2,
+  };
+}
+
+export function checkCollision(box1: CollisionBox, box2: CollisionBox): boolean {
+  return !(
+    box1.x + box1.width < box2.x ||
+    box2.x + box2.width < box1.x ||
+    box1.y + box1.height < box2.y ||
+    box2.y + box2.height < box1.y
+  );
+}
+
+/**
+ * Iteratively resolve bounding-box collisions within each level.
+ * Nodes are pushed apart symmetrically until no overlaps remain
+ * or `maxIterations` is reached.
+ */
+export function resolveCollisions(nodes: MindMapNode[], maxIterations = 10): MindMapNode[] {
+  const result = [...nodes];
+
+  for (let iter = 0; iter < maxIterations; iter++) {
+    let hasCollisions = false;
+
+    const byLevel = result.reduce<Record<number, MindMapNode[]>>((acc, n) => {
+      (acc[n.level] ??= []).push(n);
+      return acc;
+    }, {});
+
+    for (const levelNodes of Object.values(byLevel)) {
+      for (let i = 0; i < levelNodes.length; i++) {
+        for (let j = i + 1; j < levelNodes.length; j++) {
+          const n1 = levelNodes[i];
+          const n2 = levelNodes[j];
+          if (!checkCollision(getNodeBounds(n1), getNodeBounds(n2))) continue;
+
+          hasCollisions = true;
+          const dx = n2.x - n1.x;
+          const dy = n2.y - n1.y;
+          const dist = Math.sqrt(dx * dx + dy * dy);
+
+          if (dist < 1) {
+            n2.x += 100;
+          } else {
+            const b1 = getNodeBounds(n1);
+            const b2 = getNodeBounds(n2);
+            const minSep = (b1.width + b2.width) / 2;
+            const overlap = minSep - dist + 20;
+            if (overlap > 0) {
+              const move = overlap / 2;
+              n1.x -= (dx / dist) * move;
+              n1.y -= (dy / dist) * move;
+              n2.x += (dx / dist) * move;
+              n2.y += (dy / dist) * move;
+            }
+          }
+        }
+      }
+    }
+
+    if (!hasCollisions) break;
+  }
+
+  return result;
+}
+
+/**
+ * Apply a lightweight repulsive force between same-level nodes that are
+ * closer than 300 px, then resolve remaining collisions.
+ */
+export function optimizeLayout(nodes: MindMapNode[]): MindMapNode[] {
+  const result = [...nodes];
+  const iterations = 5;
+  const repulsion = 1000;
+  const damp = 0.8;
+
+  for (let iter = 0; iter < iterations; iter++) {
+    const forces = new Map<string, { x: number; y: number }>();
+    result.forEach(n => forces.set(n.id, { x: 0, y: 0 }));
+
+    for (let i = 0; i < result.length; i++) {
+      for (let j = i + 1; j < result.length; j++) {
+        const n1 = result[i];
+        const n2 = result[j];
+        if (n1.level !== n2.level) continue;
+
+        const dx = n2.x - n1.x;
+        const dy = n2.y - n1.y;
+        const dist = Math.sqrt(dx * dx + dy * dy);
+        if (dist <= 0 || dist >= 300) continue;
+
+        const force = repulsion / (dist * dist);
+        const f1 = forces.get(n1.id)!;
+        const f2 = forces.get(n2.id)!;
+        f1.x -= (dx / dist) * force;
+        f1.y -= (dy / dist) * force;
+        f2.x += (dx / dist) * force;
+        f2.y += (dy / dist) * force;
+      }
+    }
+
+    result.forEach(n => {
+      const f = forces.get(n.id)!;
+      n.x += f.x * damp;
+      n.y += f.y * damp;
+    });
+  }
+
+  return resolveCollisions(result);
+}

package/src/layout/linearLayout.ts

@@ -0,0 +1,84 @@
+// ─── Linear Layout Algorithms ─────────────────────────────────────────────────
+//
+// Positions nodes in a straight line without overlap, with enough gap between
+// node edges for edge-label text to render cleanly.
+//
+//   linear-horizontal  → left-to-right along X-axis
+//   linear-vertical    → top-to-bottom along Y-axis
+
+import type { FlatNode } from '../types/mindmap.js';
+
+export interface LinearLayoutOptions {
+  /** Logical node width (px). Default: 200 */
+  nodeWidth?: number;
+  /** Logical node height (px). Default: 80 */
+  nodeHeight?: number;
+  /** Gap between node edges for horizontal layout (px). Default: 180 */
+  hGap?: number;
+  /** Gap between node edges for vertical layout (px). Default: 220 */
+  vGap?: number;
+  /** World X of the layout midpoint. Default: 0 */
+  centerX?: number;
+  /** World Y of the layout midpoint. Default: 0 */
+  centerY?: number;
+}
+
+/**
+ * Arrange nodes in a horizontal row (shared Y, varying X).
+ * Row is centred on (`centerX`, `centerY`).
+ */
+export function applyLinearHorizontalLayout(
+  nodes: FlatNode[],
+  options: LinearLayoutOptions = {},
+): FlatNode[] {
+  const { nodeWidth = 200, hGap = 180, centerX = 0, centerY = 0 } = options;
+
+  if (nodes.length === 0) return nodes;
+
+  if (nodes.length === 1) {
+    nodes[0].x = centerX;
+    nodes[0].y = centerY;
+    return nodes;
+  }
+
+  const spacing = nodeWidth + hGap;
+  const totalWidth = (nodes.length - 1) * spacing;
+  const startX = centerX - totalWidth / 2;
+
+  for (let i = 0; i < nodes.length; i++) {
+    nodes[i].x = startX + i * spacing;
+    nodes[i].y = centerY;
+  }
+
+  return nodes;
+}
+
+/**
+ * Arrange nodes in a vertical column (shared X, varying Y).
+ * Column is centred on (`centerX`, `centerY`).
+ */
+export function applyLinearVerticalLayout(
+  nodes: FlatNode[],
+  options: LinearLayoutOptions = {},
+): FlatNode[] {
+  const { nodeHeight = 80, vGap = 220, centerX = 0, centerY = 0 } = options;
+
+  if (nodes.length === 0) return nodes;
+
+  if (nodes.length === 1) {
+    nodes[0].x = centerX;
+    nodes[0].y = centerY;
+    return nodes;
+  }
+
+  const spacing = nodeHeight + vGap;
+  const totalHeight = (nodes.length - 1) * spacing;
+  const startY = centerY - totalHeight / 2;
+
+  for (let i = 0; i < nodes.length; i++) {
+    nodes[i].x = centerX;
+    nodes[i].y = startY + i * spacing;
+  }
+
+  return nodes;
+}

package/src/parser/configUtils.ts

@@ -0,0 +1,129 @@
+// ─── MindMapConfig Utilities ──────────────────────────────────────────────────
+//
+// Helpers for creating and generating MindMapConfig objects (pure data, no UI).
+
+import type { MindMapNode, MindMapConfig, TopLevelConnection } from '../types/mindmap.js';
+import { LEVEL_COLORS, LAYOUT_SPACING, getColorForLevel } from '../constants/design.js';
+
+export function createMindMapConfig(
+  nodes: MindMapNode[],
+  topLevelConnections: TopLevelConnection[],
+  title = 'Untitled Mindmap',
+): MindMapConfig {
+  const now = new Date().toISOString();
+  return {
+    metadata: {
+      title,
+      description: `Interactive mindmap with ${nodes.length} nodes`,
+      version: '1.0.0',
+      created: now,
+      lastModified: now,
+    },
+    nodes,
+    topLevelConnections,
+    settings: {
+      defaultColors: {
+        level0: LEVEL_COLORS.level0,
+        level1: LEVEL_COLORS.level1,
+        level2: LEVEL_COLORS.level2,
+        level3: LEVEL_COLORS.level3,
+      },
+      layout: {
+        nodeSpacing: LAYOUT_SPACING.nodeSpacing,
+        levelSpacing: LAYOUT_SPACING.levelSpacing,
+      },
+    },
+  };
+}
+
+// ── Sample Data Generator ─────────────────────────────────────────────────────
+
+function generateId(prefix: string, level: number, index: number): string {
+  return `${prefix}-l${level}-${index}`;
+}
+
+function generateLevelNodes(
+  parentId: string | null,
+  level: number,
+  maxLevels: number,
+  xOffset = 0,
+  yOffset = 0,
+): MindMapNode[] {
+  if (level >= maxLevels) return [];
+
+  const count = 5;
+  const levelSpacing = 200;
+  const nodeSpacing = 300;
+  const nodes: MindMapNode[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const nodeId = parentId
+      ? generateId(`${parentId}-${i}`, level, i)
+      : generateId('root', level, i);
+
+    const x = xOffset + (i - (count - 1) / 2) * nodeSpacing;
+    const y = yOffset + level * levelSpacing;
+
+    const node: MindMapNode = {
+      id: nodeId,
+      title: `Level ${level} Node ${i + 1}`,
+      level,
+      x,
+      y,
+      color: getColorForLevel(level),
+      relationshipLabel: level > 0 ? 'child' : undefined,
+      parent: parentId ?? undefined,
+    };
+
+    const children = generateLevelNodes(nodeId, level + 1, maxLevels, x, y + levelSpacing);
+    if (children.length > 0) node.children = children;
+
+    nodes.push(node);
+  }
+
+  return nodes;
+}
+
+/**
+ * Generate a sample MindMapConfig with `maxLevels` of hierarchy.
+ * Useful for testing and demos.
+ */
+export function generateSampleConfig(maxLevels = 9): MindMapConfig {
+  const nodes = generateLevelNodes(null, 0, maxLevels, 0, 0);
+
+  const topLevelConnections: TopLevelConnection[] = nodes.slice(0, -1).map((n, i) => ({
+    from: n.id,
+    to: nodes[i + 1].id,
+    label: 'related to',
+  }));
+
+  return {
+    metadata: {
+      id: `mindmap-${Date.now()}`,
+      title: 'Sample Mind Map',
+      description: 'A sample mind map',
+      version: '1.0.0',
+      created: new Date().toISOString(),
+      lastModified: new Date().toISOString(),
+    },
+    nodes,
+    topLevelConnections,
+    settings: {
+      defaultColors: {
+        level0: LEVEL_COLORS.level0,
+        level1: LEVEL_COLORS.level1,
+        level2: LEVEL_COLORS.level2,
+        level3: LEVEL_COLORS.level3,
+        level4: LEVEL_COLORS.level4,
+        level5: LEVEL_COLORS.level5,
+        level6: LEVEL_COLORS.level6,
+        level7: LEVEL_COLORS.level7,
+        level8: LEVEL_COLORS.level8,
+      },
+      layout: {
+        nodeSpacing: LAYOUT_SPACING.nodeSpacing,
+        levelSpacing: LAYOUT_SPACING.levelSpacing,
+      },
+    },
+  };
+}

package/src/parser/index.ts

@@ -0,0 +1,4 @@
+export * from './visualliParser.js';
+export * from './visualliConverter.js';
+export * from './mindmapUtils.js';
+export * from './configUtils.js';

package/src/parser/middleware.ts

@@ -0,0 +1,24 @@
+// ─── Middleware Types ──────────────────────────────────────────────────────────
+//
+// Defines the middleware system for transforming parsed JSONL data
+
+/**
+ * Raw node data from a single JSONL line before any transformation
+ */
+export type RawNodeData = Record<string, unknown>;
+
+/**
+ * Middleware function that can transform raw JSONL data
+ * - Return the transformed node to continue the pipeline
+ * - Return null to skip/filter this node
+ * - Can mutate the input or return a new object
+ */
+export type ParserMiddleware = (rawData: RawNodeData) => RawNodeData | null;
+
+/**
+ * Middleware context with document state (for advanced use cases)
+ */
+export interface ParserContext {
+  layers: Map<string, unknown>;
+  meta: unknown | null;
+}