@visualli/core 0.1.7 → 0.2.0

package/src/parser/configUtils.ts

@@ -3,7 +3,15 @@
 // 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';
+import { LAYOUT_SPACING } from '../constants/layout.js';
+import { TOKENS, TOPICS } from '../theme/index.js';
+
+/** Light-theme fill of the topic used for a level (cycles through the design-system topics). */
+const levelColor = (level: number): string => TOKENS.light[`topic-${TOPICS[level % TOPICS.length]}`]!;
+
+type LevelColors = { level0: string; level1: string; level2: string; level3: string; [key: `level${number}`]: string };
+const levelColors = (count: number): LevelColors =>
+  Object.fromEntries(Array.from({ length: count }, (_, i) => [`level${i}`, levelColor(i)])) as LevelColors;
 
 export function createMindMapConfig(
   nodes: MindMapNode[],
@@ -22,12 +30,7 @@ export function createMindMapConfig(
     nodes,
     topLevelConnections,
     settings: {
-      defaultColors: {
-        level0: LEVEL_COLORS.level0,
-        level1: LEVEL_COLORS.level1,
-        level2: LEVEL_COLORS.level2,
-        level3: LEVEL_COLORS.level3,
-      },
+      defaultColors: levelColors(4),
       layout: {
         nodeSpacing: LAYOUT_SPACING.nodeSpacing,
         levelSpacing: LAYOUT_SPACING.levelSpacing,
@@ -70,7 +73,7 @@ function generateLevelNodes(
       level,
       x,
       y,
-      color: getColorForLevel(level),
+      color: levelColor(level),
       relationshipLabel: level > 0 ? 'child' : undefined,
       parent: parentId ?? undefined,
     };
@@ -109,17 +112,7 @@ export function generateSampleConfig(maxLevels = 9): MindMapConfig {
     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,
-      },
+      defaultColors: levelColors(9),
       layout: {
         nodeSpacing: LAYOUT_SPACING.nodeSpacing,
         levelSpacing: LAYOUT_SPACING.levelSpacing,

package/src/parser/visualliConverter.ts

@@ -7,6 +7,8 @@ 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 { ideaColor } from '../theme/index.js';
+import { approximateMeasure, ideaKindOf, ideaSize, type IdeaMeasure } from '../rendering/ideaSize.js';
 import { applyCircularLayout, calculateOptimalRadiusPercentage } from '../layout/circularLayout.js';
 import { applyLinearHorizontalLayout, applyLinearVerticalLayout } from '../layout/linearLayout.js';
 
@@ -57,26 +59,22 @@ export function resolveNodeOverlaps(nodes: FlatNode[], maxIterations = 10): void
   }
 }
 
-// ── Color Helpers ─────────────────────────────────────────────────────────────
+// ── Options ───────────────────────────────────────────────────────────────────
 
-const COLOR_PALETTE = [
-  '#12C7D3', '#325E8C', '#8A70A6', '#F54A57', '#FF6C4D',
-  '#F28C16', '#FFD347', '#12C7D3', '#7F7F7F', '#8D8D8D', '#12C7D3',
-];
+export interface ConvertOptions {
+  /** Measures label text in the idea face (the renderer's font engine); ideas are sized with the design system's
+   *  ideaSize. Defaults to an approximation (half an em per character) where no font engine exists. */
+  measure?: IdeaMeasure;
+  /** Label scale (comfort: larger text is 1.15); ideas grow to fit the larger label. */
+  labelScale?: number;
+}
 
-/**
- * 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];
+/** Whether a layer's ideas carry their own positions: every idea has one, and (with more than one idea) they aren't
+ *  all on the same spot (a placeholder). Then the file's positions are used as they are. */
+function hasFilePositions(layer: VisualliLayer): boolean {
+  const ps = layer.nodes.map((n) => n.position);
+  if (!ps.length || !ps.every((p) => p && Number.isFinite(p.x) && Number.isFinite(p.y))) return false;
+  return ps.length === 1 || ps.some((p) => p!.x !== ps[0]!.x || p!.y !== ps[0]!.y);
 }
 
 // ── Container-formation Layout ────────────────────────────────────────────────
@@ -137,35 +135,33 @@ function proxyRadial(proxies: Proxy[], radius = 500): void {
 
 // ── 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,
+  node: VisualliLayer['nodes'][number],
   layer: VisualliLayer,
-  color: string,
-  branchCount: number,
-  x = 0,
-  y = 0,
+  doc: VisualliDocument,
+  /** Position among the layer's ideas (file order): missing colours cycle the topics by it, and the first idea of the root radial layer is the root. */
+  siblingIndex: number,
+  opts: ConvertOptions,
 ): FlatNode {
+  const label = Array.isArray(node.data.label) ? (node.data.label as string[]).join(' ') : (node.data.label || 'Untitled');
+  const branchCount = countLayersBeneath(doc, node.id);
+  const kind = ideaKindOf(layer, siblingIndex);
+  const size = ideaSize(kind, label, opts.measure ?? approximateMeasure, opts.labelScale ?? 1);
+  const { topic, custom } = ideaColor(node.data.color, siblingIndex);
   return {
-    id: nodeId,
+    id: node.id,
     parentId: layer.parentNodeId ?? null,
-    x,
-    y,
+    x: node.position?.x ?? 0,
+    y: node.position?.y ?? 0,
     level: layer.level,
     title: label,
-    description: summary,
-    color,
-    width: calculateNodeWidth(label),
-    height: 80,
+    description: node.data.summary || '',
+    color: node.data.color ?? '',
+    ...(topic ? { topic } : {}),
+    ...(custom ? { custom } : {}),
+    kind,
+    width: size.width,
+    height: size.height,
     isExpanded: branchCount > 0,
     branchCount,
     createdAt: new Date(),
@@ -173,26 +169,8 @@ function makeFlatNode(
   };
 }
 
-function convertLayerWithContainers(
-  layer: VisualliLayer,
-  doc: VisualliDocument,
-): FlatNode[] {
+function layoutLayerWithContainers(layer: VisualliLayer, flatNodes: FlatNode[]): void {
   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: FlatNode) => [n.id, n]));
   const containerNodeIds = new Set<string>();
   const containerGroups = new Map<string, FlatNode[]>();
@@ -207,11 +185,8 @@ function convertLayerWithContainers(
   }
 
   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 n of flatNodes) {
+    if (!containerNodeIds.has(n.id)) proxies.push({ id: n.id, x: 0, y: 0, width: n.width, height: n.height });
   }
   for (const container of layer.containers) {
     const group = containerGroups.get(container.id);
@@ -234,60 +209,43 @@ function convertLayerWithContainers(
       if (fn) { fn.x = proxy.x; fn.y = proxy.y; }
     }
   }
+}
 
-  resolveNodeOverlaps(flatNodes);
-
-  return flatNodes;
+function layoutLayer(layer: VisualliLayer, flatNodes: FlatNode[]): void {
+  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,
+    });
+  }
 }
 
 /**
- * Convert a single layer to an array of FlatNode objects.
- * Layout algorithm is determined by `layer.layout` (default: radial).
+ * Convert a single layer to an array of FlatNode objects, each sized for its label
+ * (the design system's idea.ts) and coloured by its colour rule (color.ts).
+ * Positions: the file's own when its ideas carry them; otherwise the SDK lays the
+ * layer out by `layer.layout` (default radial) and container formations.
  */
 export function convertLayerToFlatNodes(
   layer: VisualliLayer,
   doc: VisualliDocument,
+  opts: ConvertOptions = {},
 ): 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,
-      });
-    }
-  }
-
+  const flatNodes = layer.nodes.map((node, i) => makeFlatNode(node, layer, doc, i, opts));
+  if (flatNodes.length === 0 || hasFilePositions(layer)) return flatNodes;
+  for (const n of flatNodes) { n.x = 0; n.y = 0; }
+  if ((layer.containers ?? []).length > 0) layoutLayerWithContainers(layer, flatNodes);
+  else layoutLayer(layer, flatNodes);
   resolveNodeOverlaps(flatNodes);
-
   return flatNodes;
 }
 
@@ -295,11 +253,11 @@ export function convertLayerToFlatNodes(
  * 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 {
+export function convertVisualliToFlatNodes(doc: VisualliDocument, opts: ConvertOptions = {}): NodeMap {
   const map: NodeMap = new Map();
 
   for (const layer of doc.layers.values()) {
-    for (const node of convertLayerToFlatNodes(layer, doc)) {
+    for (const node of convertLayerToFlatNodes(layer, doc, opts)) {
       map.set(node.id, node);
     }
   }
@@ -320,9 +278,10 @@ export function convertVisualliToFlatNodes(doc: VisualliDocument): NodeMap {
  *
  * @param doc - Parsed .visualli document
  * @param layerId - Layer ID to extract
+ * @param opts - Text measurement and label scale for sizing ideas
  * @returns FlatNode array, or empty array if layer not found
  */
-export function getNodesForLayer(doc: VisualliDocument, layerId: string): FlatNode[] {
+export function getNodesForLayer(doc: VisualliDocument, layerId: string, opts: ConvertOptions = {}): FlatNode[] {
   const layer = doc.layers.get(layerId);
-  return layer ? convertLayerToFlatNodes(layer, doc) : [];
+  return layer ? convertLayerToFlatNodes(layer, doc, opts) : [];
 }

package/src/parser/visualliParser.ts

@@ -2,7 +2,7 @@
 //
 // Reads JSONL (JSON Lines) format and parses into a structured VisualliDocument.
 
-import type { VisualliDocument } from '../types/document.js';
+import type { VisualliDocument, SemanticAnchor } 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';
@@ -92,6 +92,14 @@ export function parseVisualliFile(content: string): VisualliDocument {
         break;
       }
 
+      case 'extension': {
+        const id = obj['id'];
+        if (typeof id === 'string') {
+          (doc.extensions ??= {})[id] = Array.isArray(obj['data']) ? (obj['data'] as unknown[]) : [];
+        }
+        break;
+      }
+
       default:
         // Unknown type — silently skip
         break;
@@ -148,6 +156,13 @@ export function loadVisualliFileFromFile(file: File): Promise<VisualliDocument>
 // ── Tree Helpers ──────────────────────────────────────────────────────────────
 
 /** Return all layers whose `parentNodeId` matches the given node ID. */
+/** Terms defined by the document's `semantic-anchors` extension (empty when absent). */
+export function getSemanticAnchors(doc: VisualliDocument): SemanticAnchor[] {
+  const raw = doc.extensions?.['semantic-anchors'];
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((a): a is SemanticAnchor => !!a && typeof (a as SemanticAnchor).word === 'string' && typeof (a as SemanticAnchor).description === 'string');
+}
+
 export function getChildLayers(
   doc: VisualliDocument,
   nodeId: string,

package/src/rendering/culling.ts

@@ -1,6 +1,7 @@
 import type { FlatNode, ViewportState } from '../types/index.js';
 import { RBushSpatialIndex } from '../spatial/spatialIndex.js';
 import { calculateViewportBounds } from '../viewport/viewportUtils.js';
+import { nodeBounds } from './nodeGeometry.js';
 
 export interface CullingOptions {
   nodes: FlatNode[];
@@ -16,6 +17,19 @@ export interface CullingOptions {
 
 const DEFAULT_SPATIAL_INDEX_THRESHOLD = 200;
 
+/**
+ * True when anything drawn for the node touches the viewport. Nodes are drawn
+ * CENTRED on (x, y) with rings and stroke around them, so the test uses the
+ * node's real visual bounds (not a top-left rectangle).
+ */
+export function intersectsViewport(
+  n: FlatNode,
+  bounds: { minX: number; minY: number; maxX: number; maxY: number },
+): boolean {
+  const b = nodeBounds(n);
+  return b.maxX >= bounds.minX && b.minX <= bounds.maxX && b.maxY >= bounds.minY && b.minY <= bounds.maxY;
+}
+
 /**
  * Returns the subset of nodes currently visible in the viewport.
  * Framework-agnostic logic for culling and spatial indexing.
@@ -45,12 +59,7 @@ export function getViewportVisibleNodes(options: CullingOptions): FlatNode[] {
   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,
-    );
+    return filtered.filter(n => intersectsViewport(n, bounds));
   }
 
   if (spatialIndex) {
@@ -62,10 +71,5 @@ export function getViewportVisibleNodes(options: CullingOptions): FlatNode[] {
   }
 
   // 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,
-  );
+  return filtered.filter(n => intersectsViewport(n, bounds));
 }

package/src/rendering/ideaSize.ts

@@ -0,0 +1,21 @@
+// ─── Idea size and label growth ──────────────────────────────────────────────
+//
+// The design system's idea.ts (copied verbatim into generated/geometry): an idea
+// grows to show its whole label, and labels grow a little when zoomed out. The
+// SDK only supplies the text measurement (its font engine) and picks the kind.
+
+import { IDEA, LABEL_GROWTH, ideaSize, labelGrowth, wrapLines, type IdeaKind } from '../generated/geometry/idea.js';
+import type { VisualliLayer } from '../types/layer.js';
+
+export { IDEA, LABEL_GROWTH, ideaSize, labelGrowth, wrapLines };
+export type { IdeaKind };
+
+/** Width in px of `text` in the idea label's face at `px` (the label's weight; readable type adds its tracking). */
+export type IdeaMeasure = (text: string, px: number) => number;
+
+/** Measurement without a font engine (server, tests): half an em per character. Renderers pass the real face. */
+export const approximateMeasure: IdeaMeasure = (text, px) => text.length * px * 0.5;
+
+/** The size kind of the `index`-th idea of a layer: the centre of the root radial layer is the root, the rest ideas. */
+export const ideaKindOf = (layer: Pick<VisualliLayer, 'level' | 'layout'>, index: number): IdeaKind =>
+  layer.level === 0 && (layer.layout ?? 'radial') === 'radial' && index === 0 ? 'root' : 'node';

package/src/rendering/nodeGeometry.ts

@@ -0,0 +1,97 @@
+// ─── Node & connector geometry ───────────────────────────────────────────────
+//
+// Thin layer over the design system's geometry (generated/geometry/blob.ts):
+// it chooses the radii, shapes, rings and endpoints for a FlatNode and never
+// re-implements outline or curve math. Pure functions, no DOM.
+
+import { BLOB_SHAPES, RINGS, SHAPE, arrowPath, blobPath, blobRadius, edgePath, shapeForLevel } from '../generated/geometry/blob.js';
+import { METRICS } from '../generated/designSystem.js';
+import type { FlatNode } from '../types/mindmap.js';
+
+// The design system's geometry is part of the public API (single source of truth).
+export { BLOB_SHAPES, RINGS, SHAPE, arrowPath, blobPath, blobRadius, edgePath, shapeForLevel };
+export { drawBlob } from '../generated/geometry/blob.js';
+
+/** Minimum a node needs to be drawn / connected. */
+export type NodeLike = Pick<FlatNode, 'x' | 'y' | 'width' | 'height' | 'level' | 'branchCount'>;
+
+export const MAX_RINGS = RINGS.length;
+const DEG = Math.PI / 180;
+
+/** Outline radii of an idea: half its size (sized for its label by the design system's idea.ts). */
+export function nodeRadii(n: Pick<FlatNode, 'width' | 'height'>): { rx: number; ry: number } {
+  return { rx: n.width / 2, ry: n.height / 2 };
+}
+
+/** Rings an idea shows: one per layer beneath it, at most 3. */
+export const ringCount = (branchCount: number | undefined): number => Math.max(0, Math.min(branchCount ?? 0, MAX_RINGS));
+
+/** The design system's ring recipes an idea shows, innermost first (index 0 = scale 1.1). */
+export const ringsFor = (branchCount: number | undefined): typeof RINGS => RINGS.slice(0, ringCount(branchCount));
+
+const shapeCache = new Map<number, number>();
+/** Outline shape for a layer level (memoised: shapeForLevel is O(level)). */
+export function shapeOfLevel(level: number): number {
+  let s = shapeCache.get(level);
+  if (s === undefined) { s = shapeForLevel(level); shapeCache.set(level, s); }
+  return s;
+}
+
+/** Largest distance from a blob's centre to any control point, in units of max(rx, ry). */
+const BLOB_MAX_NORM = Math.max(...BLOB_SHAPES.flatMap((s) => s.map(([x, y]) => Math.hypot(x!, y!))));
+
+/** Visual margin around an idea beyond its outline: stroke, hover lift and the node shadow. */
+const VISUAL_MARGIN = METRICS.nodeStroke * 2 + 24;
+
+/**
+ * Conservative world-space bounds of everything drawn for an idea (rings and
+ * stroke included). Ideas are drawn CENTRED on (x, y), so bounds are centred
+ * too. A circle bound is used so ring rotation can never push ink outside it.
+ */
+export function nodeBounds(n: NodeLike): { minX: number; minY: number; maxX: number; maxY: number } {
+  const { rx, ry } = nodeRadii(n);
+  const rings = ringCount(n.branchCount);
+  const scale = rings > 0 ? RINGS[rings - 1]!.scale : 1;
+  const r = BLOB_MAX_NORM * Math.max(rx, ry) * scale + VISUAL_MARGIN;
+  return { minX: n.x - r, minY: n.y - r, maxX: n.x + r, maxY: n.y + r };
+}
+
+/**
+ * Distance from an idea's centre to the outline connectors must clear, in the
+ * world direction `angle` (radians, y down). That is the outermost visible
+ * ring (rotated like the ring is drawn), or the body when there are no rings.
+ */
+export function outlineRadius(n: NodeLike, angle: number): number {
+  const { rx, ry } = nodeRadii(n);
+  const shape = shapeOfLevel(n.level);
+  const rings = ringCount(n.branchCount);
+  if (rings === 0) return blobRadius(shape, rx, ry, angle);
+  const ring = RINGS[rings - 1]!;
+  // The ring is the same blob scaled and rotated about the centre, so look up
+  // the radius in the ring's own frame.
+  return blobRadius(shape, rx * ring.scale, ry * ring.scale, angle - ring.rotate * DEG);
+}
+
+export interface ConnectorGeometry {
+  /** Start / end points: `edge-gap` outside the source / target outline. */
+  a: { x: number; y: number };
+  b: { x: number; y: number };
+  /** Cubic path data (SVG syntax) and the arrowhead direction, from the design system's edgePath. */
+  d: string;
+  angle: number;
+  /** Bow apex returned by edgePath, where the connector label sits. */
+  mid: { x: number; y: number };
+  /** Open arrowhead path data at b, from the design system's arrowPath. */
+  arrow: string;
+}
+
+/** Endpoints and curve of a connector between two ideas. */
+export function connectorGeometry(from: NodeLike, to: NodeLike, gap: number = METRICS.edgeGap): ConnectorGeometry {
+  const theta = Math.atan2(to.y - from.y, to.x - from.x);
+  const ra = outlineRadius(from, theta) + gap;
+  const rb = outlineRadius(to, theta + Math.PI) + gap;
+  const a = { x: from.x + Math.cos(theta) * ra, y: from.y + Math.sin(theta) * ra };
+  const b = { x: to.x - Math.cos(theta) * rb, y: to.y - Math.sin(theta) * rb };
+  const e = edgePath(a, b);
+  return { a, b, d: e.d, angle: e.angle, mid: e.mid, arrow: arrowPath(b, e.angle) };
+}

package/src/theme/index.ts

@@ -0,0 +1,136 @@
+// ─── Theme resolution ────────────────────────────────────────────────────────
+//
+// Everything visual comes from the generated design-system modules. This file
+// only decides WHICH of the 8 themes applies and resolves document colours with
+// the design system's colour rule. No colour literals live here.
+//
+// Dependencies: ../generated/designSystem.ts (generated from design-system/).
+
+import {
+  CANVAS_STYLE,
+  DESIGN_SYSTEM_VERSION,
+  METRICS,
+  METRICS_REDUCED_MOTION,
+  THEME_NAMES,
+  TOKENS,
+  TOPICS,
+  TYPE_STYLES,
+  type ThemeName,
+  type TopicName,
+} from '../generated/designSystem.js';
+import { TOPIC_ORDER, customColor, topicFor, topicFromName } from '../generated/geometry/color.js';
+
+export { topicFromName, customColor };
+
+export { CANVAS_STYLE, DESIGN_SYSTEM_VERSION, METRICS, METRICS_REDUCED_MOTION, THEME_NAMES, TOKENS, TOPICS, TYPE_STYLES };
+export type { ThemeName, TopicName };
+
+// ── Theme selection ───────────────────────────────────────────────────────────
+
+/** Theme families: each resolves to its light or dark member. */
+export type ThemeFamily = 'standard' | 'focus' | 'colorsafe' | 'contrast';
+
+/**
+ * Anything a consumer may pass as `theme`:
+ *  - one of the 8 design-system themes ('light', 'dark', 'focus-light', ...)
+ *  - a family name ('focus' | 'colorsafe' | 'contrast') -> light/dark per the reader's scheme
+ *  - 'auto' -> light/dark per prefers-color-scheme (contrast under forced-colors)
+ *
+ * 'light' | 'dark' | 'auto' are the pre-0.2 values, kept as aliases for one release.
+ */
+export type ThemeInput = ThemeName | 'auto' | 'focus' | 'colorsafe' | 'contrast';
+
+export interface ThemeEnv {
+  /** prefers-color-scheme: dark */
+  prefersDark?: boolean;
+  /** forced-colors: active (Windows high contrast etc.) */
+  forcedColors?: boolean;
+}
+
+const FAMILIES: ReadonlySet<string> = new Set(['focus', 'colorsafe', 'contrast']);
+
+export function isThemeName(v: unknown): v is ThemeName {
+  return typeof v === 'string' && (THEME_NAMES as readonly string[]).includes(v);
+}
+
+/** Resolve any accepted `theme` value to one concrete design-system theme. */
+export function resolveTheme(input: ThemeInput | undefined, env: ThemeEnv = {}): ThemeName {
+  const scheme = env.prefersDark ? 'dark' : 'light';
+  if (input === undefined || input === 'auto') return env.forcedColors ? (`contrast-${scheme}` as ThemeName) : scheme;
+  if (FAMILIES.has(input)) return `${input}-${scheme}` as ThemeName;
+  return isThemeName(input) ? input : 'light';
+}
+
+export const isDarkTheme = (name: ThemeName): boolean => name.endsWith('dark');
+export const isContrastTheme = (name: ThemeName): boolean => name.startsWith('contrast');
+export const isFocusTheme = (name: ThemeName): boolean => name.startsWith('focus');
+
+/** All tokens of a theme (already merged over the light defaults). */
+export const getTokens = (name: ThemeName): Readonly<Record<string, string>> => TOKENS[name];
+
+/** One token of a theme. Throws on an unknown key so typos fail loudly in tests. */
+export function token(name: ThemeName, key: string): string {
+  const v = TOKENS[name][key];
+  if (v === undefined) throw new Error(`Unknown design-system token "${key}"`);
+  return v;
+}
+
+// ── Comfort settings ──────────────────────────────────────────────────────────
+
+export interface Comfort {
+  /** Atkinson Hyperlegible for map labels instead of the handwritten faces (`data-type="readable"`). */
+  readableType?: boolean;
+  /** Larger UI and label text (`data-scale="lg"`). */
+  largerText?: boolean;
+  /** Skip transitions and reveal animations (`data-motion="reduced"`). 'system' follows prefers-reduced-motion. */
+  reducedMotion?: boolean | 'system';
+}
+
+export interface ResolvedComfort { readableType: boolean; largerText: boolean; reducedMotion: boolean }
+
+export function resolveComfort(c: Comfort | undefined, env: { prefersReducedMotion?: boolean } = {}): ResolvedComfort {
+  const rm = c?.reducedMotion;
+  return {
+    readableType: !!c?.readableType,
+    largerText: !!c?.largerText,
+    reducedMotion: rm === undefined || rm === 'system' ? !!env.prefersReducedMotion : rm,
+  };
+}
+
+/** Numeric design-system tokens (px / ms stripped). */
+export type Metrics = { readonly [K in keyof typeof METRICS]: number };
+
+/** Numeric tokens with the reduced-motion overrides applied when requested. */
+export function metricsFor(comfort: ResolvedComfort): Metrics {
+  return comfort.reducedMotion ? { ...METRICS, ...METRICS_REDUCED_MOTION } : METRICS;
+}
+
+/** Multiplier the spec applies to label sizes under `data-scale="lg"` (`--vi-label-scale`). */
+export const labelScale = (c: ResolvedComfort): number => (c.largerText ? 1.15 : 1);
+
+// ── Topic palette ─────────────────────────────────────────────────────────────
+
+export interface TopicStyle { topic: TopicName; fill: string; ring: string }
+
+/** Fill + ring colour of a topic in a theme. */
+export function topicStyle(theme: ThemeName, topic: TopicName): TopicStyle {
+  const t = TOKENS[theme];
+  return { topic, fill: t[`topic-${topic}`]!, ring: t[`topic-${topic}-ring`]! };
+}
+
+/** An idea's colour by the design system's colour rule (geometry/color.ts, verbatim): a topic name → that topic; no
+ *  colour → the topics in sibling order; any other colour → custom, drawn as given (customColor: the colour as the fill,
+ *  the fill darkened by CUSTOM.ringShade as the ring). A custom colour doesn't follow themes. */
+export interface IdeaColor { topic: TopicName | null; custom: { fill: string; ring: string | null } | null }
+
+export function ideaColor(color: string | null | undefined, siblingIndex: number): IdeaColor {
+  const topic = topicFor(color, siblingIndex);
+  return topic ? { topic, custom: null } : { topic: null, custom: customColor(color!) };
+}
+
+/** Fill + ring an idea is drawn with in a theme: its topic's, or its custom colour (ring: the `edge` token when the
+ *  colour has no darker shade, i.e. isn't a 6-digit hex). */
+export function ideaStyle(theme: ThemeName, c: { topic?: TopicName | null; custom?: IdeaColor['custom'] }): { fill: string; ring: string } {
+  if (c.custom) return { fill: c.custom.fill, ring: c.custom.ring ?? TOKENS[theme]['edge']! };
+  return topicStyle(theme, c.topic ?? TOPIC_ORDER[0]);
+}