@visualli/core 0.1.1

package/src/parser/mindmapUtils.ts

@@ -0,0 +1,76 @@
+// ─── Mindmap Tree Utilities ───────────────────────────────────────────────────
+
+import type { MindMapNode, TopLevelConnection } from '../types/mindmap.js';
+
+/** Flatten a nested MindMapNode tree into a depth-first array. */
+export function flattenNodes(nodes: MindMapNode[]): MindMapNode[] {
+  const result: MindMapNode[] = [];
+  const traverse = (list: MindMapNode[]) => {
+    for (const n of list) {
+      result.push(n);
+      if (n.children) traverse(n.children);
+    }
+  };
+  traverse(nodes);
+  return result;
+}
+
+/**
+ * Return nodes visible at the given zoom level.
+ *
+ * At lower zoom values only top-level nodes are shown; each 5% zoom increment
+ * reveals one additional hierarchy level.
+ */
+export function getVisibleNodes(
+  nodes: MindMapNode[],
+  zoom: number,
+  focusedNode?: string,
+): MindMapNode[] {
+  const flat = flattenNodes(nodes);
+
+  if (focusedNode) {
+    const focused = flat.find(n => n.id === focusedNode);
+    if (focused) {
+      return focused.children ? [focused, ...focused.children] : [focused];
+    }
+  }
+
+  // Map zoom to max visible level (level 0 at ≤70%, +1 level per 5% increment)
+  if (zoom <= 0.70) return flat.filter(n => n.level === 0);
+  const maxLevel = Math.floor((zoom - 0.70) / 0.05);
+  return flat.filter(n => n.level <= maxLevel);
+}
+
+/** Build parent→child connection pairs from the node tree. */
+export function getNodeConnections(
+  nodes: MindMapNode[],
+): Array<{ from: MindMapNode; to: MindMapNode; label?: string }> {
+  const flat = flattenNodes(nodes);
+  const result: Array<{ from: MindMapNode; to: MindMapNode; label?: string }> = [];
+  for (const n of flat) {
+    if (!n.parent) continue;
+    const parent = flat.find(p => p.id === n.parent);
+    if (parent) result.push({ from: parent, to: n, label: n.relationshipLabel });
+  }
+  return result;
+}
+
+/** Resolve top-level cross-connections to node pairs. */
+export function getTopLevelConnections(
+  nodes: MindMapNode[],
+  topLevelConnections: TopLevelConnection[],
+): Array<{ from: MindMapNode; to: MindMapNode; label: string }> {
+  const flat = flattenNodes(nodes);
+  const result: Array<{ from: MindMapNode; to: MindMapNode; label: string }> = [];
+  for (const conn of topLevelConnections) {
+    const from = flat.find(n => n.id === conn.from);
+    const to   = flat.find(n => n.id === conn.to);
+    if (from && to) result.push({ from, to, label: conn.label ?? '' });
+  }
+  return result;
+}
+
+/** Euclidean distance between two world-space points. */
+export function calculateDistance(x1: number, y1: number, x2: number, y2: number): number {
+  return Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2);
+}

package/src/parser/visualliConverter.ts

@@ -0,0 +1,328 @@
+// ─── .visualli → FlatNode Converter ──────────────────────────────────────────
+//
+// Transforms the layer-based .visualli format into the flat Map<id, FlatNode>
+// structure consumed by the canvas renderer.
+
+import type { VisualliDocument } from '../types/document.js';
+import type { VisualliLayer } from '../types/layer.js';
+import type { FlatNode, NodeMap } from '../types/mindmap.js';
+import { countLayersBeneath } from './visualliParser.js';
+import { applyCircularLayout, calculateOptimalRadiusPercentage } from '../layout/circularLayout.js';
+import { applyLinearHorizontalLayout, applyLinearVerticalLayout } from '../layout/linearLayout.js';
+
+// ── Overlap Resolution ────────────────────────────────────────────────────────
+
+function doNodesOverlap(n1: FlatNode, n2: FlatNode, padding = 20): boolean {
+  return !(
+    n1.x + n1.width / 2 + padding < n2.x - n2.width / 2 - padding ||
+    n1.x - n1.width / 2 - padding > n2.x + n2.width / 2 + padding ||
+    n1.y + n1.height / 2 + padding < n2.y - n2.height / 2 - padding ||
+    n1.y - n1.height / 2 - padding > n2.y + n2.height / 2 + padding
+  );
+}
+
+/** Iteratively push overlapping nodes apart using symmetric force separation. */
+export function resolveNodeOverlaps(nodes: FlatNode[], maxIterations = 10): void {
+  const padding = 150;
+
+  for (let iter = 0; iter < maxIterations; iter++) {
+    let any = false;
+    for (let i = 0; i < nodes.length; i++) {
+      for (let j = i + 1; j < nodes.length; j++) {
+        const n1 = nodes[i];
+        const n2 = nodes[j];
+        if (!doNodesOverlap(n1, n2, padding)) continue;
+
+        any = 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 += n2.width / 2 + padding;
+          continue;
+        }
+
+        const minDist = (n1.width + n2.width) / 2 + padding;
+        if (dist < minDist) {
+          const push = (minDist - dist) / 2;
+          n1.x -= (dx / dist) * push;
+          n1.y -= (dy / dist) * push;
+          n2.x += (dx / dist) * push;
+          n2.y += (dy / dist) * push;
+        }
+      }
+    }
+    if (!any) break;
+  }
+}
+
+// ── Color Helpers ─────────────────────────────────────────────────────────────
+
+const COLOR_PALETTE = [
+  '#12C7D3', '#325E8C', '#8A70A6', '#F54A57', '#FF6C4D',
+  '#F28C16', '#FFD347', '#12C7D3', '#7F7F7F', '#8D8D8D', '#12C7D3',
+];
+
+/**
+ * Get a deterministic random color from palette based on node ID
+ */
+function getRandomColorForNode(nodeId: string): string {
+  // Simple hash function to convert string to number
+  let hash = 0;
+  for (let i = 0; i < nodeId.length; i++) {
+    hash = nodeId.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  
+  // Use absolute value and modulo to get palette index
+  const index = Math.abs(hash) % COLOR_PALETTE.length;
+  return COLOR_PALETTE[index];
+}
+
+// ── Container-formation Layout ────────────────────────────────────────────────
+
+interface Proxy { id: string; x: number; y: number; width: number; height: number }
+
+function applyFormation(nodes: FlatNode[], formation: string): void {
+  if (nodes.length === 0) return;
+  if (nodes.length === 1) { nodes[0].x = 0; nodes[0].y = 0; return; }
+  if (formation === 'linear-horizontal' || formation === 'linear') {
+    applyLinearHorizontalLayout(nodes, { centerX: 0, centerY: 0 });
+  } else if (formation === 'linear-vertical') {
+    applyLinearVerticalLayout(nodes, { centerX: 0, centerY: 0 });
+  } else {
+    const r = Math.max(250, nodes.length * 70);
+    const step = (2 * Math.PI) / nodes.length;
+    for (let i = 0; i < nodes.length; i++) {
+      nodes[i].x = r * Math.cos(i * step);
+      nodes[i].y = r * Math.sin(i * step);
+    }
+  }
+}
+
+function containerBBox(nodes: FlatNode[], padding: number): { width: number; height: number } {
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  for (const n of nodes) {
+    minX = Math.min(minX, n.x - n.width / 2);
+    maxX = Math.max(maxX, n.x + n.width / 2);
+    minY = Math.min(minY, n.y - n.height / 2);
+    maxY = Math.max(maxY, n.y + n.height / 2);
+  }
+  return { width: maxX - minX + padding * 2, height: maxY - minY + padding * 2 };
+}
+
+function proxyLinearH(proxies: Proxy[], gap = 180): void {
+  const total = proxies.reduce((s, p) => s + p.width, 0) + gap * (proxies.length - 1);
+  let x = -total / 2;
+  for (const p of proxies) { p.x = x + p.width / 2; p.y = 0; x += p.width + gap; }
+}
+
+function proxyLinearV(proxies: Proxy[], gap = 180): void {
+  const total = proxies.reduce((s, p) => s + p.height, 0) + gap * (proxies.length - 1);
+  let y = -total / 2;
+  for (const p of proxies) { p.x = 0; p.y = y + p.height / 2; y += p.height + gap; }
+}
+
+function proxyRadial(proxies: Proxy[], radius = 500): void {
+  if (proxies.length === 1) { proxies[0].x = 0; proxies[0].y = 0; return; }
+  // Start at top (12 o'clock) for n>=3, horizontal for n=2 (matches circular layout)
+  const startAngle = proxies.length === 2 ? 0 : -Math.PI / 2;
+  const step = (2 * Math.PI) / proxies.length;
+  for (let i = 0; i < proxies.length; i++) {
+    const angle = startAngle + i * step;
+    proxies[i].x = radius * Math.cos(angle);
+    proxies[i].y = radius * Math.sin(angle);
+  }
+}
+
+// ── Layer Conversion ──────────────────────────────────────────────────────────
+
+/**
+ * Calculate dynamic node width based on title length.
+ * Formula matches visualli.ai: max(200, title.length * 8 + 40)
+ */
+function calculateNodeWidth(title: string): number {
+  return Math.max(200, title.length * 8 + 40);
+}
+
+function makeFlatNode(
+  nodeId: string,
+  label: string,
+  summary: string,
+  layer: VisualliLayer,
+  color: string,
+  branchCount: number,
+  x = 0,
+  y = 0,
+): FlatNode {
+  return {
+    id: nodeId,
+    parentId: layer.parentNodeId ?? null,
+    x,
+    y,
+    level: layer.level,
+    title: label,
+    description: summary,
+    color,
+    width: calculateNodeWidth(label),
+    height: 80,
+    isExpanded: branchCount > 0,
+    branchCount,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function convertLayerWithContainers(
+  layer: VisualliLayer,
+  doc: VisualliDocument,
+): FlatNode[] {
+  const PADDING = 80;
+  const flatNodes: FlatNode[] = [];
+
+  for (const node of layer.nodes) {
+    const label = Array.isArray(node.data.label)
+      ? (node.data.label as string[]).join(' ')
+      : (node.data.label || 'Untitled');
+    const branchCount = countLayersBeneath(doc, node.id);
+    flatNodes.push(
+      makeFlatNode(
+        node.id, label, node.data.summary || '', layer,
+        node.data.color || getRandomColorForNode(node.id), branchCount,
+      ),
+    );
+  }
+
+  const byId = new Map(flatNodes.map(n => [n.id, n]));
+  const containerNodeIds = new Set<string>();
+  const containerGroups = new Map<string, FlatNode[]>();
+
+  for (const container of layer.containers) {
+    const group = container.nodes.map(id => byId.get(id)).filter((n): n is FlatNode => !!n);
+    if (!group.length) continue;
+    container.nodes.forEach(id => containerNodeIds.add(id));
+    const formation = ((container.data as unknown as Record<string, unknown> | undefined)?.['formation'] as string | undefined) ?? 'radial';
+    applyFormation(group, formation);
+    containerGroups.set(container.id, group);
+  }
+
+  const proxies: Proxy[] = [];
+  for (const node of layer.nodes) {
+    if (!containerNodeIds.has(node.id)) {
+      const nodeWidth = calculateNodeWidth(node.data.label);
+      proxies.push({ id: node.id, x: 0, y: 0, width: nodeWidth, height: 80 });
+    }
+  }
+  for (const container of layer.containers) {
+    const group = containerGroups.get(container.id);
+    if (!group?.length) continue;
+    const bbox = containerBBox(group, PADDING);
+    proxies.push({ id: `__c__${container.id}`, x: 0, y: 0, width: bbox.width, height: bbox.height });
+  }
+
+  const layout = layer.layout || 'radial';
+  if (layout === 'linear-horizontal') proxyLinearH(proxies, 180);
+  else if (layout === 'linear-vertical') proxyLinearV(proxies, 180);
+  else proxyRadial(proxies, 500);
+
+  for (const proxy of proxies) {
+    if (proxy.id.startsWith('__c__')) {
+      const group = containerGroups.get(proxy.id.slice(5));
+      group?.forEach(n => { n.x += proxy.x; n.y += proxy.y; });
+    } else {
+      const fn = byId.get(proxy.id);
+      if (fn) { fn.x = proxy.x; fn.y = proxy.y; }
+    }
+  }
+
+  resolveNodeOverlaps(flatNodes);
+
+  return flatNodes;
+}
+
+/**
+ * Convert a single layer to an array of FlatNode objects.
+ * Layout algorithm is determined by `layer.layout` (default: radial).
+ */
+export function convertLayerToFlatNodes(
+  layer: VisualliLayer,
+  doc: VisualliDocument,
+): FlatNode[] {
+  if ((layer.containers ?? []).length > 0) {
+    return convertLayerWithContainers(layer, doc);
+  }
+
+  const flatNodes: FlatNode[] = [];
+
+  for (const node of layer.nodes) {
+    const label = Array.isArray(node.data.label)
+      ? (node.data.label as string[]).join(' ')
+      : (node.data.label || 'Untitled');
+    const branchCount = countLayersBeneath(doc, node.id);
+    flatNodes.push(
+      makeFlatNode(
+        node.id, label, node.data.summary || '', layer,
+        node.data.color || getRandomColorForNode(node.id), branchCount,
+        0, 0,
+      ),
+    );
+  }
+
+  if (flatNodes.length > 0) {
+    const layout = layer.layout || 'radial';
+    if (layout === 'linear-horizontal') {
+      applyLinearHorizontalLayout(flatNodes, { centerX: 0, centerY: 0 });
+    } else if (layout === 'linear-vertical') {
+      applyLinearVerticalLayout(flatNodes, { centerX: 0, centerY: 0 });
+    } else {
+      const pct = calculateOptimalRadiusPercentage(flatNodes.length, 2000, 2000, 200, 30);
+      applyCircularLayout(flatNodes, {
+        radiusPercentage: pct,
+        containerWidth: 2000,
+        containerHeight: 2000,
+        centerX: 0,
+        centerY: 0,
+      });
+    }
+  }
+
+  resolveNodeOverlaps(flatNodes);
+
+  return flatNodes;
+}
+
+/**
+ * Convert an entire .visualli document to a flat NodeMap.
+ * All layers are converted and a children-index is built for O(1) tree traversal.
+ */
+export function convertVisualliToFlatNodes(doc: VisualliDocument): NodeMap {
+  const map: NodeMap = new Map();
+
+  for (const layer of doc.layers.values()) {
+    for (const node of convertLayerToFlatNodes(layer, doc)) {
+      map.set(node.id, node);
+    }
+  }
+
+  // Build children index
+  for (const node of map.values()) {
+    node.childrenIds = [];
+    for (const candidate of map.values()) {
+      if (candidate.parentId === node.id) node.childrenIds.push(candidate.id);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Get flat nodes for a specific layer only.
+ *
+ * @param doc - Parsed .visualli document
+ * @param layerId - Layer ID to extract
+ * @returns FlatNode array, or empty array if layer not found
+ */
+export function getNodesForLayer(doc: VisualliDocument, layerId: string): FlatNode[] {
+  const layer = doc.layers.get(layerId);
+  return layer ? convertLayerToFlatNodes(layer, doc) : [];
+}

package/src/parser/visualliParser.ts

@@ -0,0 +1,191 @@
+// ─── .visualli File Parser ────────────────────────────────────────────────────
+//
+// Reads JSONL (JSON Lines) format and parses into a structured VisualliDocument.
+
+import type { VisualliDocument } from '../types/document.js';
+import type { VisualliMeta } from '../types/meta.js';
+import type { VisualliLayer } from '../types/layer.js';
+import type { Layer } from '../types/schema.js';
+
+/**
+ * Convert schema Layer to VisualliLayer by ensuring required arrays exist.
+ */
+function toVisualliLayer(schemaLayer: Layer): VisualliLayer {
+  return {
+    type: 'layer',
+    id: schemaLayer.id,
+    level: schemaLayer.level,
+    parentLayerId: schemaLayer.parentLayerId,
+    parentNodeId: schemaLayer.parentNodeId,
+    layout: schemaLayer.layout,
+    nodes: schemaLayer.nodes ?? [],
+    connections: schemaLayer.connections ?? [],
+    containers: schemaLayer.containers ?? [],
+  };
+}
+
+export class VisualliParseError extends Error {
+  constructor(message: string, public readonly lineNumber?: number) {
+    super(message);
+    this.name = 'VisualliParseError';
+  }
+}
+
+/**
+ * Parse a .visualli file content (JSONL format) into a VisualliDocument.
+ *
+ * @throws VisualliParseError on malformed input
+ */
+export function parseVisualliFile(content: string): VisualliDocument {
+  const lines = content.trim().split('\n');
+
+  const doc: VisualliDocument = {
+    meta: null as unknown as VisualliMeta,
+    layers: new Map(),
+    layersByLevel: new Map(),
+    rootLayer: null,
+  };
+
+  let lineNumber = 0;
+
+  for (const line of lines) {
+    lineNumber++;
+    if (!line.trim()) continue;
+
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(line) as Record<string, unknown>;
+    } catch (err) {
+      throw new VisualliParseError(
+        `Failed to parse JSON at line ${lineNumber}: ${err}`,
+        lineNumber,
+      );
+    }
+
+    if (!obj['type']) {
+      throw new VisualliParseError(
+        `Missing 'type' field at line ${lineNumber}`,
+        lineNumber,
+      );
+    }
+
+    switch (obj['type']) {
+      case 'meta':
+        doc.meta = obj as unknown as VisualliMeta;
+        break;
+
+      case 'layer': {
+        // Convert schema Layer to VisualliLayer
+        const schemaLayer = obj as unknown as Layer;
+        const layer = toVisualliLayer(schemaLayer);
+        
+        doc.layers.set(layer.id, layer);
+
+        if (!doc.layersByLevel.has(layer.level)) {
+          doc.layersByLevel.set(layer.level, []);
+        }
+        doc.layersByLevel.get(layer.level)!.push(layer);
+
+        if (layer.level === 0) {
+          doc.rootLayer = layer;
+        }
+        break;
+      }
+
+      default:
+        // Unknown type — silently skip
+        break;
+    }
+  }
+
+  if (!doc.meta) throw new VisualliParseError('Missing required meta section');
+  if (!doc.rootLayer) throw new VisualliParseError('Missing root layer (level 0)');
+
+  return doc;
+}
+
+/**
+ * Fetch and parse a .visualli file from a URL.
+ *
+ * @throws VisualliParseError | Error
+ */
+export async function loadVisualliFile(url: string): Promise<VisualliDocument> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  return parseVisualliFile(await response.text());
+}
+
+/**
+ * Parse .visualli JSONL data as returned from the MongoDB `visualli` field.
+ *
+ * @throws VisualliParseError
+ */
+export function parseVisualliFromMongoDB(visualliJsonl: string): VisualliDocument {
+  if (!visualliJsonl || typeof visualliJsonl !== 'string') {
+    throw new VisualliParseError('Invalid visualli data: expected a JSONL string');
+  }
+  const trimmed = visualliJsonl.trim();
+  if (!trimmed) throw new VisualliParseError('Empty visualli data from MongoDB');
+  return parseVisualliFile(trimmed);
+}
+
+/**
+ * Parse a .visualli file from a browser `File` object.
+ * (Browser-only – requires `FileReader`.)
+ */
+export function loadVisualliFileFromFile(file: File): Promise<VisualliDocument> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = e => {
+      try {
+        resolve(parseVisualliFile(e.target?.result as string));
+      } catch (err) {
+        reject(err);
+      }
+    };
+    reader.onerror = () => reject(new Error('Failed to read file'));
+    reader.readAsText(file);
+  });
+}
+
+// ── Tree Helpers ──────────────────────────────────────────────────────────────
+
+/** Return all layers whose `parentNodeId` matches the given node ID. */
+export function getChildLayers(
+  doc: VisualliDocument,
+  nodeId: string,
+): VisualliLayer[] {
+  const result: VisualliLayer[] = [];
+  for (const layer of doc.layers.values()) {
+    if (layer.parentNodeId === nodeId) result.push(layer);
+  }
+  return result;
+}
+
+/**
+ * Count the maximum depth of layers beneath a node (its "magnitude").
+ * Returns 0 when the node has no child layers.
+ */
+export function countLayersBeneath(
+  doc: VisualliDocument,
+  nodeId: string,
+  visited = new Set<string>(),
+): number {
+  if (visited.has(nodeId)) return 0;
+  visited.add(nodeId);
+
+  const children = getChildLayers(doc, nodeId);
+  if (children.length === 0) return 0;
+
+  let maxDepth = 0;
+  for (const layer of children) {
+    let depth = 1;
+    for (const node of layer.nodes) {
+      depth = Math.max(depth, 1 + countLayersBeneath(doc, node.id, visited));
+    }
+    maxDepth = Math.max(maxDepth, depth);
+  }
+  return maxDepth;
+}

package/src/performance/index.ts

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