@visualli/core 0.1.1

package/src/config/blobShapes.ts

@@ -0,0 +1,146 @@
+export interface BlobPoint { x: number; y: number }
+export type BlobShape = BlobPoint[];
+
+// ── Blob Layer Config ─────────────────────────────────────────────────────────
+
+export const BLOB_LAYER_CONFIG = [
+  { opacity: 0.3, rotation: -15, scaleUp: 1.30, strokeWidth: 3, dash: [6, 4] },  // Layer #3 (outermost)
+  { opacity: 0.4, rotation: -10, scaleUp: 1.20, strokeWidth: 1, dash: undefined }, // Layer #2
+  { opacity: 0.5, rotation: -5,  scaleUp: 1.10, strokeWidth: 2, dash: undefined }, // Layer #1
+] as const;
+
+export const NODE_LAYER_CONFIG = { opacity: 1, rotation: 0, strokeWidth: 3 } as const;
+
+// ── Blob Shapes ───────────────────────────────────────────────────────────────
+
+export const ALL_BLOB_SHAPES: ReadonlyArray<BlobShape> = [
+  // Shape 0 · Blob 1
+  [
+    { x: 1.12, y: 0 }, { x: 0.86, y: 0.56 }, { x: 0.46, y: 0.94 }, { x: -0.08, y: 1.06 },
+    { x: -0.68, y: 0.82 }, { x: -0.96, y: 0.08 }, { x: -0.55, y: -0.82 }, { x: 0.04, y: -1.02 },
+    { x: 0.72, y: -0.8 }, { x: 1.08, y: -0.38 },
+  ],
+  // Shape 1 · Blob 2
+  [
+    { x: -0.489, y: -0.625 }, { x: -0.384, y: -0.716 }, { x: -0.285, y: -0.792 }, { x: -0.189, y: -0.855 },
+    { x: -0.090, y: -0.903 }, { x:  0.014, y: -0.932 }, { x:  0.129, y: -0.940 }, { x:  0.255, y: -0.924 },
+    { x:  0.412, y: -0.876 }, { x:  0.516, y: -0.832 }, { x:  0.612, y: -0.780 }, { x:  0.695, y: -0.725 },
+    { x:  0.767, y: -0.666 }, { x:  0.830, y: -0.606 }, { x:  0.885, y: -0.546 }, { x:  0.933, y: -0.486 },
+    { x:  0.979, y: -0.425 }, { x:  1.006, y: -0.385 }, { x:  1.034, y: -0.334 }, { x:  1.058, y: -0.276 },
+    { x:  1.078, y: -0.209 }, { x:  1.092, y: -0.133 }, { x:  1.101, y: -0.046 }, { x:  1.102, y:  0.052 },
+    { x:  1.094, y:  0.173 }, { x:  1.083, y:  0.244 }, { x:  1.063, y:  0.324 }, { x:  1.034, y:  0.401 },
+    { x:  0.996, y:  0.477 }, { x:  0.948, y:  0.549 }, { x:  0.889, y:  0.617 }, { x:  0.820, y:  0.681 },
+    { x:  0.735, y:  0.741 }, { x:  0.658, y:  0.783 }, { x:  0.569, y:  0.822 }, { x:  0.474, y:  0.855 },
+    { x:  0.372, y:  0.882 }, { x:  0.265, y:  0.904 }, { x:  0.156, y:  0.920 }, { x:  0.046, y:  0.931 },
+    { x: -0.069, y:  0.938 }, { x: -0.155, y:  0.935 }, { x: -0.250, y:  0.919 }, { x: -0.346, y:  0.890 },
+    { x: -0.443, y:  0.851 }, { x: -0.539, y:  0.800 }, { x: -0.633, y:  0.738 }, { x: -0.723, y:  0.667 },
+    { x: -0.808, y:  0.585 }, { x: -0.882, y:  0.501 }, { x: -0.944, y:  0.421 }, { x: -0.994, y:  0.343 },
+    { x: -1.034, y:  0.267 }, { x: -1.064, y:  0.192 }, { x: -1.085, y:  0.120 }, { x: -1.097, y:  0.042 },
+    { x: -1.102, y:  0.001 }, { x: -1.090, y: -0.243 }, { x: -1.050, y: -0.365 }, { x: -0.990, y: -0.441 },
+    { x: -0.911, y: -0.479 }, { x: -0.819, y: -0.499 }, { x: -0.715, y: -0.517 }, { x: -0.605, y: -0.551 },
+  ],
+  // Shape 2 · Blob 3
+  [
+    { x:  0.003, y: -0.970 }, { x:  0.163, y: -0.984 }, { x:  0.286, y: -1.028 }, { x:  0.389, y: -1.096 },
+    { x:  0.488, y: -1.174 }, { x:  0.597, y: -1.210 }, { x:  0.728, y: -1.165 }, { x:  0.867, y: -1.036 },
+    { x:  0.996, y: -0.839 }, { x:  1.098, y: -0.590 }, { x:  1.158, y: -0.304 }, { x:  1.153, y:  0.012 },
+    { x:  1.080, y:  0.336 }, { x:  0.944, y:  0.639 }, { x:  0.756, y:  0.889 }, { x:  0.484, y:  1.072 },
+    { x:  0.339, y:  1.079 }, { x:  0.219, y:  1.051 }, { x:  0.131, y:  0.994 }, { x:  0.059, y:  0.939 },
+    { x:  0.008, y:  0.915 }, { x: -0.105, y:  0.931 }, { x: -0.176, y:  0.965 }, { x: -0.249, y:  1.005 },
+    { x: -0.345, y:  1.039 }, { x: -0.497, y:  1.055 }, { x: -0.672, y:  1.032 }, { x: -0.817, y:  0.952 },
+    { x: -0.945, y:  0.810 }, { x: -1.054, y:  0.600 }, { x: -1.160, y:  0.302 }, { x: -1.187, y: -0.011 },
+    { x: -1.165, y: -0.326 }, { x: -1.097, y: -0.599 }, { x: -0.991, y: -0.838 }, { x: -0.852, y: -0.912 },
+    { x: -0.695, y: -0.958 }, { x: -0.530, y: -0.988 }, { x: -0.357, y: -0.992 }, { x: -0.180, y: -0.983 },
+  ],
+  // Shape 3 · Blob 4
+  [
+    { x: -0.734, y: -1.127 }, { x: -0.656, y: -1.146 }, { x: -0.567, y: -1.142 }, { x: -0.468, y: -1.115 },
+    { x: -0.358, y: -1.079 }, { x: -0.238, y: -1.034 }, { x: -0.107, y: -0.989 }, { x:  0.035, y: -0.953 },
+    { x:  0.188, y: -0.929 }, { x:  0.325, y: -0.916 }, { x:  0.484, y: -0.896 }, { x:  0.650, y: -0.854 },
+    { x:  0.811, y: -0.770 }, { x:  0.955, y: -0.631 }, { x:  1.068, y: -0.422 }, { x:  1.138, y: -0.126 },
+    { x:  1.152, y:  0.272 }, { x:  1.121, y:  0.451 }, { x:  1.046, y:  0.602 }, { x:  0.928, y:  0.727 },
+    { x:  0.767, y:  0.833 }, { x:  0.565, y:  0.925 }, { x:  0.323, y:  1.001 }, { x:  0.042, y:  1.075 },
+    { x: -0.277, y:  1.142 }, { x: -0.368, y:  1.147 }, { x: -0.475, y:  1.136 }, { x: -0.589, y:  1.104 },
+    { x: -0.704, y:  1.050 }, { x: -0.815, y:  0.973 }, { x: -0.913, y:  0.871 }, { x: -0.993, y:  0.746 },
+    { x: -1.048, y:  0.593 }, { x: -1.109, y:  0.298 }, { x: -1.145, y:  0.018 }, { x: -1.154, y: -0.243 },
+    { x: -1.135, y: -0.482 }, { x: -1.085, y: -0.695 }, { x: -1.003, y: -0.874 }, { x: -0.886, y: -1.020 },
+  ],
+  // Shape 4 · Blob 5
+  [
+    { x: -0.734, y:  1.127 }, { x: -0.656, y:  1.146 }, { x: -0.567, y:  1.142 }, { x: -0.468, y:  1.115 },
+    { x: -0.358, y:  1.079 }, { x: -0.238, y:  1.034 }, { x: -0.107, y:  0.989 }, { x:  0.035, y:  0.953 },
+    { x:  0.188, y:  0.929 }, { x:  0.325, y:  0.916 }, { x:  0.484, y:  0.896 }, { x:  0.650, y:  0.854 },
+    { x:  0.811, y:  0.770 }, { x:  0.955, y:  0.631 }, { x:  1.068, y:  0.422 }, { x:  1.138, y:  0.126 },
+    { x:  1.152, y: -0.272 }, { x:  1.121, y: -0.451 }, { x:  1.046, y: -0.602 }, { x:  0.928, y: -0.727 },
+    { x:  0.767, y: -0.833 }, { x:  0.565, y: -0.925 }, { x:  0.323, y: -1.001 }, { x:  0.042, y: -1.075 },
+    { x: -0.277, y: -1.142 }, { x: -0.368, y: -1.147 }, { x: -0.475, y: -1.136 }, { x: -0.589, y: -1.104 },
+    { x: -0.704, y: -1.050 }, { x: -0.815, y: -0.973 }, { x: -0.913, y: -0.871 }, { x: -0.993, y: -0.746 },
+    { x: -1.048, y: -0.593 }, { x: -1.109, y: -0.298 }, { x: -1.145, y: -0.018 }, { x: -1.154, y:  0.243 },
+    { x: -1.135, y:  0.482 }, { x: -1.085, y:  0.695 }, { x: -1.003, y:  0.874 }, { x: -0.886, y:  1.020 },
+  ],
+  // Shape 5 · Blob 6
+  [
+    { x:  0.001, y: -1.006 }, { x:  0.134, y: -1.001 }, { x:  0.262, y: -1.024 },
+    { x:  0.382, y: -1.073 }, { x:  0.498, y: -1.107 }, { x:  0.614, y: -1.105 },
+    { x:  0.733, y: -1.049 }, { x:  0.850, y: -0.932 }, { x:  0.953, y: -0.755 },
+    { x:  1.030, y: -0.529 }, { x:  1.067, y: -0.265 }, { x:  1.054, y:  0.018 },
+    { x:  0.986, y:  0.300 }, { x:  0.868, y:  0.557 }, { x:  0.715, y:  0.766 },
+    { x:  0.550, y:  0.909 }, { x:  0.396, y:  0.984 }, { x:  0.262, y:  1.005 },
+    { x:  0.148, y:  1.003 }, { x:  0.037, y:  1.008 }, { x: -0.083, y:  1.040 },
+    { x: -0.220, y:  1.118 }, { x: -0.360, y:  1.192 }, { x: -0.500, y:  1.234 },
+    { x: -0.650, y:  1.175 }, { x: -0.810, y:  1.045 }, { x: -0.990, y:  0.855 },
+    { x: -1.140, y:  0.610 }, { x: -1.240, y:  0.330 }, { x: -1.270, y:  0.040 },
+    { x: -1.275, y: -0.250 }, { x: -1.225, y: -0.500 }, { x: -1.080, y: -0.720 },
+    { x: -0.890, y: -0.920 }, { x: -0.734, y: -1.053 }, { x: -0.614, y: -1.112 },
+    { x: -0.498, y: -1.127 }, { x: -0.381, y: -1.110 }, { x: -0.261, y: -1.095 },
+    { x: -0.133, y: -1.058 }, { x:  0.001, y: -1.010 }, { x:  0.134, y: -1.001 },
+  ],
+];
+
+export const ACTIVE_BLOB_TYPES: ReadonlyArray<number> = [0, 1, 2, 3, 4, 5];
+
+/**
+ * Per-shape text x-offset as a fraction of baseRadiusX.
+ * Compensates for visually asymmetric blobs. Positive = right, negative = left.
+ */
+export const BLOB_TEXT_OFFSETS: ReadonlyArray<number> = [0, 0, 0, 0, 0, -0.10];
+
+/**
+ * Deterministic pseudo-random blob-type selector per tree level.
+ * Root level (0) always uses shape 0; consecutive levels use different shapes.
+ */
+export function getBlobTypeForLayer(level: number): number {
+  const numTypes = ACTIVE_BLOB_TYPES.length;
+  if (numTypes <= 1) return ACTIVE_BLOB_TYPES[0] ?? 0;
+  let currentType = 0;
+  for (let i = 1; i <= level; i++) {
+    const pseudoRandom = Math.floor(Math.abs(Math.sin((i + 1) * 12.9898) * 43758.5453));
+    const stepOffset = (pseudoRandom % (numTypes - 1)) + 1;
+    currentType = (currentType + stepOffset) % numTypes;
+  }
+  return ACTIVE_BLOB_TYPES[currentType];
+}
+
+/**
+ * Draw the blob path onto a canvas context (centered at 0,0).
+ * Uses closed quadratic bezier curves through midpoints of control points.
+ */
+export function drawBlobPath(
+  ctx: { beginPath(): void; moveTo(x: number, y: number): void; quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void; closePath(): void },
+  radiusX: number,
+  radiusY: number,
+  blobType: number,
+): void {
+  const srcPts = ALL_BLOB_SHAPES[blobType] ?? ALL_BLOB_SHAPES[0];
+  const pts = srcPts.map(p => ({ x: p.x * radiusX, y: p.y * radiusY }));
+  ctx.beginPath();
+  const last  = pts[pts.length - 1];
+  const first = pts[0];
+  ctx.moveTo((last.x + first.x) / 2, (last.y + first.y) / 2);
+  for (let i = 0; i < pts.length; i++) {
+    const curr = pts[i];
+    const next = pts[(i + 1) % pts.length];
+    ctx.quadraticCurveTo(curr.x, curr.y, (curr.x + next.x) / 2, (curr.y + next.y) / 2);
+  }
+  ctx.closePath();
+}

package/src/config/textScaling.ts

@@ -0,0 +1,54 @@
+import { NODE_HEIGHT } from '../constants/performanceConstants.js';
+
+export const NODE_TEXT_BASE_FONT_PX = 28;
+export const DESCRIPTION_TEXT_BASE_FONT_PX = 12;
+export const CONTAINER_LABEL_BASE_FONT_PX = 24;
+export const EDGE_LABEL_BASE_FONT_PX = 18;
+export const OVERLAY_FONT_UPPER_BOOST_PX = 8;
+
+// Keep text away from blob edges
+const NODE_TEXT_SAFE_BLOB_FILL_RATIO = 0.88;
+
+/**
+ * Computes world-space text scale for node title:
+ * - inverse zoom for screen-space consistency
+ * - clamped so text stays inside the node blob with safe padding
+ *
+ * Matches visualli.ai's computeNodeTextWorldScale(nodeWidth, zoomLevel).
+ */
+export function computeNodeTextWorldScale(nodeWidth: number, zoomLevel: number): number {
+  const safeZoom = Math.max(zoomLevel, 0.0001);
+  const baseRadiusX = nodeWidth / 2;
+  const baseRadiusY = Math.max((NODE_HEIGHT * 1.6) / 2, baseRadiusX * 0.74);
+  const textNaturalWidth  = nodeWidth - 40;
+  const textNaturalHeight = NODE_HEIGHT - 20;
+
+  const maxScaleX = ((baseRadiusX * 2) * NODE_TEXT_SAFE_BLOB_FILL_RATIO) / Math.max(textNaturalWidth, 1);
+  const maxScaleY = ((baseRadiusY * 2) * NODE_TEXT_SAFE_BLOB_FILL_RATIO) / Math.max(textNaturalHeight, 1);
+  const fitScale  = Math.max(0.01, Math.min(maxScaleX, maxScaleY));
+
+  return Math.min(1 / safeZoom, fitScale);
+}
+
+/** Screen-space scale (zoom-adjusted) for text overlays. */
+export function computeNodeTextScreenScale(nodeWidth: number, zoomLevel: number): number {
+  return computeNodeTextWorldScale(nodeWidth, zoomLevel) * zoomLevel;
+}
+
+/**
+ * Screen-space overlay scale for description/semantic tooltips.
+ * - lower bound: 1x
+ * - upper bound: node-title-root + OVERLAY_FONT_UPPER_BOOST_PX
+ */
+export function computeOverlayScale(zoomLevel: number): number {
+  const safeZoom = Math.max(zoomLevel, 0.0001);
+  const inverseScale = 1 / safeZoom;
+  const maxScale = (NODE_TEXT_BASE_FONT_PX + OVERLAY_FONT_UPPER_BOOST_PX) / NODE_TEXT_BASE_FONT_PX;
+  return Math.min(Math.max(inverseScale, 1), maxScale);
+}
+
+/** Scale for edge path labels in screen pixels. */
+export function computeEdgeLabelScale(zoomLevel: number): number {
+  const safeZoom = Math.max(zoomLevel, 0.0001);
+  return Math.min(Math.max(EDGE_LABEL_BASE_FONT_PX / safeZoom, 10), 32);
+}

package/src/constants/design.ts

@@ -0,0 +1,281 @@
+// ─── Design System Constants ──────────────────────────────────────────────────
+//
+// Single source of truth for all color tokens, typography, spacing, and
+// visual design constants used across the SDK and consuming apps.
+//
+// ## Color Priority
+//   1. Data file values (node.color, layer.backgroundColor)
+//   2. Fall back to these constants
+
+// ── Visualli Design System v2 ─────────────────────────────────────────────────
+
+export const DS_COLORS = {
+  light: {
+    bgApp:          '#F0EDE6',
+    bgSurface:      '#FAF8F4',
+    bgInput:        '#FFFFFF',
+    border:         '#DDD9D0',
+    borderDivider:  '#E8E4DC',
+    primary:        '#1B2D4F',
+    primaryHover:   '#243B68',
+    textPrimary:    '#1A1A18',
+    textSecondary:  '#6B6860',
+    textMuted:      '#747270',
+    textOnPrimary:  '#FAF8F4',
+    hoverItem:      'rgba(27,45,79,0.07)',
+    focusRing:      'rgba(27,45,79,0.40)',
+    btnMuted:       '#8E8C88',
+  },
+  dark: {
+    bgApp:          '#141412',
+    bgSurface:      '#1C1C1A',
+    bgInput:        '#262622',
+    border:         '#333330',
+    borderDivider:  '#2A2A28',
+    primary:        '#BB532D',
+    primaryHover:   '#CC6440',
+    textPrimary:    '#F0EDE6',
+    textSecondary:  '#B0ABA3',
+    textMuted:      '#8E8C88',
+    textOnPrimary:  '#FAF8F4',
+    hoverItem:      'rgba(198,94,56,0.12)',
+    focusRing:      'rgba(198,94,56,0.50)',
+    btnMuted:       '#4A4845',
+  },
+} as const;
+
+export const DS_TYPOGRAPHY = {
+  fontDisplay: "'Nunito', sans-serif",
+  fontBody:    "'Nunito Sans', sans-serif",
+  logo:     { size: '20px', weight: 800, letterSpacing: '0.04em' },
+  heading:  { size: '16px', weight: 700, letterSpacing: '-0.2px' },
+  cta:      { size: '11px', weight: 800, letterSpacing: '0.12em', transform: 'uppercase' as const },
+  body:     { size: '13px', weight: 400 },
+  input:    { size: '13px', weight: 300, style: 'italic' as const },
+  search:   { size: '12px', weight: 400 },
+  username: { size: '13px', weight: 600 },
+  avatar:   { size: '11px', weight: 700 },
+  footer:   { size: '12px', weight: 400 },
+  empty:    { size: '11px', weight: 300, style: 'italic' as const },
+} as const;
+
+export const DS_RADII = {
+  sidebar: 16,
+  input:   8,
+  cta:     7,
+  item:    6,
+  swatch:  10,
+} as const;
+
+// ── Brand Colors ──────────────────────────────────────────────────────────────
+
+export const BRAND_COLORS = {
+  primary: {
+    50:  '#EFF6FF',
+    100: '#DBEAFE',
+    200: '#BFDBFE',
+    300: '#93C5FD',
+    400: '#60A5FA',
+    500: '#3B82F6',
+    600: '#2563EB',
+    700: '#1D4ED8',
+    800: '#1E40AF',
+    900: '#1E3A8A',
+  },
+  secondary: {
+    50:  '#F0FDF4',
+    100: '#DCFCE7',
+    200: '#BBF7D0',
+    300: '#86EFAC',
+    400: '#4ADE80',
+    500: '#10B981',
+    600: '#059669',
+    700: '#047857',
+    800: '#065F46',
+    900: '#064E3B',
+  },
+  accent: {
+    purple: '#8B5CF6',
+    cyan:   '#06B6D4',
+    sky:    '#0EA5E9',
+    lime:   '#84CC16',
+    amber:  '#F59E0B',
+    red:    '#EF4444',
+  },
+} as const;
+
+// ── Level Colors ──────────────────────────────────────────────────────────────
+
+export const LEVEL_COLORS = {
+  level0: BRAND_COLORS.primary[500],
+  level1: BRAND_COLORS.primary[400],
+  level2: BRAND_COLORS.primary[300],
+  level3: BRAND_COLORS.primary[200],
+  level4: BRAND_COLORS.primary[300],
+  level5: BRAND_COLORS.primary[400],
+  level6: BRAND_COLORS.primary[500],
+  level7: BRAND_COLORS.primary[600],
+  level8: BRAND_COLORS.primary[700],
+} as const;
+
+export const LEVEL_COLOR_ARRAY = [
+  LEVEL_COLORS.level0,
+  LEVEL_COLORS.level1,
+  LEVEL_COLORS.level2,
+  LEVEL_COLORS.level3,
+  LEVEL_COLORS.level4,
+  LEVEL_COLORS.level5,
+  LEVEL_COLORS.level6,
+  LEVEL_COLORS.level7,
+  LEVEL_COLORS.level8,
+] as const;
+
+export const PARENT_FALLBACK_COLORS = [
+  '#12C7D3', '#325E8C', '#8A70A6', '#F54A57', '#FF6C4D',
+  '#F28C16', '#FFD347', '#7F7F7F', '#8D8D8D',
+] as const;
+
+export const SEMANTIC_COLORS = {
+  success: BRAND_COLORS.secondary[500],
+  error:   BRAND_COLORS.accent.red,
+  warning: BRAND_COLORS.accent.amber,
+  info:    BRAND_COLORS.primary[500],
+} as const;
+
+// ── Theme Colors ──────────────────────────────────────────────────────────────
+
+export const THEME_COLORS = {
+  light: {
+    background: { primary: '#FAF8F4', secondary: '#F0EDE6', tertiary: '#FFFFFF' },
+    text:       { primary: '#1A1A18', secondary: '#6B6860', tertiary: '#747270' },
+    border:     { primary: '#DDD9D0', secondary: '#E8E4DC' },
+  },
+  dark: {
+    background: { primary: '#1C1C1A', secondary: '#141412', tertiary: '#262622' },
+    text:       { primary: '#F0EDE6', secondary: '#B0ABA3', tertiary: '#8E8C88' },
+    border:     { primary: '#333330', secondary: '#2A2A28' },
+  },
+} as const;
+
+// ── Canvas Node Colors ────────────────────────────────────────────────────────
+
+export const CANVAS_COLORS = {
+  node: {
+    border:          '#FFFFFF',
+    titleColor:      '#1e1b4b',
+    badgeBackground: '#FFC107',
+    badgeStroke:     '#fcd34d',
+  },
+} as const;
+
+// ── Spacing ───────────────────────────────────────────────────────────────────
+
+export const SPACING = {
+  xs:   4,
+  sm:   8,
+  md:   16,
+  lg:   24,
+  xl:   32,
+  '2xl': 48,
+  '3xl': 64,
+  '4xl': 96,
+} as const;
+
+export const LAYOUT_SPACING = {
+  nodeSpacing:      200,
+  levelSpacing:     150,
+  containerPadding: 20,
+  gridSize:         50,
+} as const;
+
+// ── Typography ────────────────────────────────────────────────────────────────
+
+export const FONTS = {
+  primary:   "'Inter', sans-serif",
+  secondary: "'Poppins', sans-serif",
+  mono:      "'Roboto Mono', monospace",
+} as const;
+
+export const FONT_SIZES = {
+  xs:   '0.75rem',
+  sm:   '0.875rem',
+  base: '1rem',
+  lg:   '1.125rem',
+  xl:   '1.25rem',
+  '2xl': '1.5rem',
+  '3xl': '1.875rem',
+  '4xl': '2.25rem',
+} as const;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Get a level color, cycling back to level 0 for levels > 8. */
+export function getColorForLevel(level: number): string {
+  return LEVEL_COLOR_ARRAY[level % LEVEL_COLOR_ARRAY.length];
+}
+
+/**
+ * Darken a hex color by reducing HSL lightness.
+ * Returns a monochromatic darker version — used for border/stroke colors.
+ * Falls back to the original string if parsing fails.
+ */
+export function darkenHexColor(hex: string, amount: number = 0.22): string {
+  if (!hex || !hex.startsWith('#')) return hex;
+  let r: number, g: number, b: number;
+  if (hex.length === 4) {
+    r = parseInt(hex[1] + hex[1], 16);
+    g = parseInt(hex[2] + hex[2], 16);
+    b = parseInt(hex[3] + hex[3], 16);
+  } else if (hex.length === 7) {
+    r = parseInt(hex.slice(1, 3), 16);
+    g = parseInt(hex.slice(3, 5), 16);
+    b = parseInt(hex.slice(5, 7), 16);
+  } else {
+    return hex;
+  }
+  if (isNaN(r) || isNaN(g) || isNaN(b)) return hex;
+  const rn = r / 255, gn = g / 255, bn = b / 255;
+  const cmax = Math.max(rn, gn, bn), cmin = Math.min(rn, gn, bn);
+  const d = cmax - cmin;
+  const l = (cmax + cmin) / 2;
+  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+  let h = 0;
+  if (d !== 0) {
+    const seg = cmax === rn ? (gn - bn) / d : cmax === gn ? (bn - rn) / d + 2 : (rn - gn) / d + 4;
+    h = ((seg * 60) + 360) % 360;
+  }
+  const newL = Math.max(0, l - amount);
+  const c2 = (1 - Math.abs(2 * newL - 1)) * s;
+  const x2 = c2 * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m2 = newL - c2 / 2;
+  let r1 = 0, g1 = 0, b1 = 0;
+  if      (h < 60)  { r1 = c2; g1 = x2; b1 = 0; }
+  else if (h < 120) { r1 = x2; g1 = c2; b1 = 0; }
+  else if (h < 180) { r1 = 0;  g1 = c2; b1 = x2; }
+  else if (h < 240) { r1 = 0;  g1 = x2; b1 = c2; }
+  else if (h < 300) { r1 = x2; g1 = 0;  b1 = c2; }
+  else              { r1 = c2; g1 = 0;  b1 = x2; }
+  const toHex = (v: number) => Math.round((v + m2) * 255).toString(16).padStart(2, '0');
+  return `#${toHex(r1)}${toHex(g1)}${toHex(b1)}`;
+}
+
+export function getThemeBackground(
+  isDark: boolean,
+  variant: 'primary' | 'secondary' | 'tertiary' = 'primary',
+): string {
+  return isDark ? THEME_COLORS.dark.background[variant] : THEME_COLORS.light.background[variant];
+}
+
+export function getThemeText(
+  isDark: boolean,
+  variant: 'primary' | 'secondary' | 'tertiary' = 'primary',
+): string {
+  return isDark ? THEME_COLORS.dark.text[variant] : THEME_COLORS.light.text[variant];
+}
+
+export function getThemeBorder(
+  isDark: boolean,
+  variant: 'primary' | 'secondary' = 'primary',
+): string {
+  return isDark ? THEME_COLORS.dark.border[variant] : THEME_COLORS.light.border[variant];
+}

package/src/constants/index.ts

@@ -0,0 +1,3 @@
+export * from './performanceConstants.js';
+export * from './design.js';
+export * from './renderConfig.js';

package/src/constants/performanceConstants.ts

@@ -0,0 +1,157 @@
+// ─── Performance & Rendering Constants ───────────────────────────────────────
+
+// ── FPS ───────────────────────────────────────────────────────────────────────
+
+export const FPS_TARGET                 = 60;
+export const FPS_WARNING_THRESHOLD      = 45;
+export const FPS_CRITICAL_THRESHOLD     = 30;
+export const TARGET_FRAME_TIME          = 1000 / FPS_TARGET; // ~16.67 ms
+export const MAX_FRAME_TIME             = 18;                 // p95 threshold
+
+/** Legacy frame-rate targets kept for backward compatibility. */
+export const FPS_TARGETS = {
+  PAN_MIN:           30,
+  ZOOM_TARGET:       60,
+  WARNING_THRESHOLD: 20,
+} as const;
+
+// ── Timing Thresholds (ms) ────────────────────────────────────────────────────
+
+export const TIMING_THRESHOLDS = {
+  VIEWPORT_QUERY_MAX:    5,
+  SPATIAL_UPDATE_MAX:    10,
+  DRAG_RESPONSE_MAX:     16,
+  LOAD_5K_TARGET:        2000,
+  LOAD_10K_TARGET:       3000,
+  VIEWPORT_DEBOUNCE:     100,
+  SPATIAL_INDEX_BUILD:   50,
+} as const;
+
+// ── Memory Limits (MB) ────────────────────────────────────────────────────────
+
+export const MEMORY_TARGET_MB   = 500;
+export const MEMORY_WARNING_MB  = 600;
+export const MEMORY_CRITICAL_MB = 800;
+
+export const MEMORY_LIMITS = {
+  MAX_10K_NODES:       500,
+  MAX_GROWTH_PERCENT:  20,
+  WARNING_THRESHOLD:   400,
+} as const;
+
+// ── Viewport Culling ──────────────────────────────────────────────────────────
+
+export const VIEWPORT_MARGIN          = 0.1;
+export const MAX_VISIBLE_NODES        = 800;
+export const CULLING_QUERY_TIME_BUDGET = 5;
+
+// ── Spatial Index ─────────────────────────────────────────────────────────────
+
+export const RBUSH_MAX_ENTRIES        = 16;
+export const SPATIAL_INDEX_BUILD_BUDGET = 50;
+
+// ── Node Dimensions ───────────────────────────────────────────────────────────
+
+export const NODE_MIN_WIDTH    = 200;
+export const NODE_HEIGHT       = 80;
+export const NODE_PADDING      = 40;
+export const CHAR_WIDTH        = 8;
+export const TITLE_MAX_LENGTH  = 150;
+
+// ── Visual Styling ────────────────────────────────────────────────────────────
+
+export const CORNER_RADIUS         = 8;
+export const BORDER_WIDTH_NORMAL   = 2;
+export const BORDER_WIDTH_SELECTED = 3;
+
+export const COLOR_SELECTED      = '#1B2D4F';
+export const COLOR_BORDER_LIGHT  = '#4A3728';
+export const COLOR_BORDER_DARK   = '#FAF6F1';
+export const COLOR_DEFAULT_NODE  = '#FAF6F1';
+
+// ── Zoom Constraints ──────────────────────────────────────────────────────────
+
+export const ZOOM_MIN              = 0.05;
+export const ZOOM_MAX              = 5.0;
+export const ZOOM_DEFAULT          = 1.0;
+export const ZOOM_STEP             = 0.1;
+export const ZOOM_WHEEL_SENSITIVITY = 0.001;
+
+export const ZOOM_NAV_IN_THRESHOLD  = 2.7;
+export const ZOOM_NAV_OUT_THRESHOLD = 0.4;
+export const TEXT_LABEL_HIDE_BELOW_ZOOM = 0.3;
+
+// ── Quality Level Presets ─────────────────────────────────────────────────────
+
+export const QUALITY_HIGH = {
+  shadows:      true,
+  bezierCurves: true,
+  animations:   true,
+  textQuality:  'high'   as const,
+  antialiasing: true,
+};
+
+export const QUALITY_MEDIUM = {
+  shadows:      false,
+  bezierCurves: true,
+  animations:   true,
+  textQuality:  'medium' as const,
+  antialiasing: true,
+};
+
+export const QUALITY_LOW = {
+  shadows:      false,
+  bezierCurves: false,
+  animations:   false,
+  textQuality:  'low'    as const,
+  antialiasing: false,
+};
+
+// ── Performance Monitoring ────────────────────────────────────────────────────
+
+export const FPS_SAMPLE_WINDOW          = 60;
+export const FPS_UPDATE_INTERVAL        = 1000;
+export const MEMORY_CHECK_INTERVAL      = 5000;
+export const PERFORMANCE_TOAST_COOLDOWN = 10000;
+
+// ── Auto-Adjustment ───────────────────────────────────────────────────────────
+
+export const FPS_DOWNGRADE_THRESHOLD    = 45;
+export const FPS_UPGRADE_THRESHOLD      = 58;
+export const FPS_STABILIZATION_FRAMES   = 180;
+
+// ── Canvas Dimensions ─────────────────────────────────────────────────────────
+
+export const DEFAULT_CANVAS_WIDTH  = 1920;
+export const DEFAULT_CANVAS_HEIGHT = 1080;
+
+// ── Interaction ───────────────────────────────────────────────────────────────
+
+export const CLICK_THRESHOLD      = 5;
+export const DOUBLE_CLICK_DELAY   = 300;
+export const DRAG_START_DISTANCE  = 10;
+
+// ── Data Validation ───────────────────────────────────────────────────────────
+
+export const MAX_NODES                    = 20000;
+export const CIRCULAR_REFERENCE_MAX_DEPTH = 1000;
+
+// ── Debounce / Throttle ───────────────────────────────────────────────────────
+
+export const RESIZE_DEBOUNCE  = 300;
+export const SCROLL_THROTTLE  = 16;
+export const SEARCH_DEBOUNCE  = 500;
+
+/** Node count thresholds that gate optimisation strategies. */
+export const NODE_COUNT_THRESHOLDS = {
+  SPATIAL_INDEX_MIN:    100,
+  VIEWPORT_CULLING_MIN: 500,
+  CANVAS_RENDERING_MIN: 2000,
+  DOM_RENDERING_MAX:    5000,
+} as const;
+
+/** Viewport buffer configuration. */
+export const VIEWPORT_CONFIG = {
+  BUFFER_PERCENT:   0.2,
+  MIN_VISIBLE_NODES: 10,
+} as const;