@stephen-netu/design-system 0.1.0 → 0.2.0

package/src/spatial/SnapZoomCamera.svelte

@@ -1,185 +0,0 @@
-<script lang="ts">
-  // SnapZoomCamera — viewport camera with snap-zoom transitions
-  // wt-903: Camera state + wheel zoom + pinch zoom + snap-zoom to target
-  //
-  // Provides camera state (zoom, panX, panY) to child content.
-  // Handles mouse wheel zoom, trackpad pinch, and programmatic snap-zoom.
-  //
-  // S-02: Easing from rAF tick, not wall-clock.
-  // S-05: Animation bounded (maxDuration).
-
-  import type { Snippet } from 'svelte';
-  import { onDestroy } from 'svelte';
-  import type { CameraState, SnapZoomTarget, CameraConfig } from './camera-types.js';
-  import { DEFAULT_CAMERA_CONFIG } from './camera-types.js';
-
-  // ── Props ────────────────────────────────────────────────────────────────
-
-  interface Props {
-    /** Container width */
-    width: number;
-    /** Container height */
-    height: number;
-    /** Camera configuration */
-    config?: CameraConfig;
-    /** Content to render inside the camera viewport */
-    children: Snippet<[CameraState]>;
-    /** Callback when camera state changes */
-    onCameraChange?: (state: CameraState) => void;
-  }
-
-  let {
-    width,
-    height,
-    config,
-    children,
-    onCameraChange,
-  }: Props = $props();
-
-  // ── Config ───────────────────────────────────────────────────────────────
-
-  const minZoom = $derived(config?.minZoom ?? DEFAULT_CAMERA_CONFIG.minZoom);
-  const maxZoom = $derived(config?.maxZoom ?? DEFAULT_CAMERA_CONFIG.maxZoom);
-  const zoomSpeed = $derived(config?.zoomSpeed ?? DEFAULT_CAMERA_CONFIG.zoomSpeed);
-  const snapDuration = $derived(config?.snapDuration ?? DEFAULT_CAMERA_CONFIG.snapDuration);
-
-  // ── Camera state ─────────────────────────────────────────────────────────
-
-  let zoom = $state(1.0);
-  let panX = $state(0);
-  let panY = $state(0);
-
-  const cameraState: CameraState = $derived({ zoom, panX, panY });
-
-  $effect(() => {
-    onCameraChange?.(cameraState);
-  });
-
-  // ── Wheel zoom ───────────────────────────────────────────────────────────
-
-  function handleWheel(e: WheelEvent) {
-    e.preventDefault();
-
-    // Determine zoom center (pointer position relative to container)
-    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
-    const mx = e.clientX - rect.left;
-    const my = e.clientY - rect.top;
-
-    // Content point under pointer before zoom
-    const cx = (mx - panX) / zoom;
-    const cy = (my - panY) / zoom;
-
-    // Compute new zoom
-    const delta = -e.deltaY * zoomSpeed;
-    const newZoom = Math.max(minZoom, Math.min(maxZoom, zoom * (1 + delta)));
-
-    // Adjust pan so content point stays under pointer
-    panX = mx - cx * newZoom;
-    panY = my - cy * newZoom;
-    zoom = newZoom;
-  }
-
-  // ── Pan (middle mouse or shift+drag) ─────────────────────────────────────
-
-  let isPanning = $state(false);
-  let panStart = { x: 0, y: 0, panX: 0, panY: 0 };
-
-  function handlePointerDown(e: PointerEvent) {
-    // Middle mouse button or shift+left click
-    if (e.button === 1 || (e.button === 0 && e.shiftKey)) {
-      e.preventDefault();
-      isPanning = true;
-      panStart = { x: e.clientX, y: e.clientY, panX, panY };
-      (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
-    }
-  }
-
-  function handlePointerMove(e: PointerEvent) {
-    if (!isPanning) return;
-    panX = panStart.panX + (e.clientX - panStart.x);
-    panY = panStart.panY + (e.clientY - panStart.y);
-  }
-
-  function handlePointerUp() {
-    isPanning = false;
-  }
-
-  // ── Snap-zoom API ────────────────────────────────────────────────────────
-
-  let animFrameId: number | null = null;
-
-  export function snapTo(target: SnapZoomTarget) {
-    if (animFrameId !== null) cancelAnimationFrame(animFrameId);
-
-    const duration = target.duration ?? snapDuration;
-    const startZoom = zoom;
-    const startPanX = panX;
-    const startPanY = panY;
-
-    // Target: center the point in the viewport at the target zoom
-    const targetPanX = width / 2 - target.x * target.zoom;
-    const targetPanY = height / 2 - target.y * target.zoom;
-
-    const startTime = performance.now();
-
-    function animate() {
-      const elapsed = performance.now() - startTime;
-      const t = Math.min(1, elapsed / duration);
-      // ease-out cubic
-      const eased = 1 - Math.pow(1 - t, 3);
-
-      zoom = startZoom + (target.zoom - startZoom) * eased;
-      panX = startPanX + (targetPanX - startPanX) * eased;
-      panY = startPanY + (targetPanY - startPanY) * eased;
-
-      if (t < 1) {
-        animFrameId = requestAnimationFrame(animate);
-      } else {
-        animFrameId = null;
-      }
-    }
-
-    animFrameId = requestAnimationFrame(animate);
-  }
-
-  export function resetCamera() {
-    snapTo({ x: 0, y: 0, zoom: 1.0 });
-  }
-
-  export function getState(): CameraState {
-    return { zoom, panX, panY };
-  }
-
-  // ── Cleanup ──────────────────────────────────────────────────────────────
-
-  onDestroy(() => {
-    if (animFrameId !== null) cancelAnimationFrame(animFrameId);
-  });
-</script>
-
-<!-- svelte-ignore a11y_no_static_element_interactions -->
-<div
-  class="snap-zoom-camera"
-  style:width="{width}px"
-  style:height="{height}px"
-  onwheel={handleWheel}
-  onpointerdown={handlePointerDown}
-  onpointermove={handlePointerMove}
-  onpointerup={handlePointerUp}
-  onpointercancel={handlePointerUp}
->
-  {@render children(cameraState)}
-</div>
-
-<style>
-  .snap-zoom-camera {
-    position: relative;
-    overflow: hidden;
-    cursor: grab;
-    touch-action: none;
-  }
-
-  .snap-zoom-camera:active {
-    cursor: grabbing;
-  }
-</style>

package/src/spatial/camera-types.ts

@@ -1,45 +0,0 @@
-// SnapZoomCamera — viewport camera types
-// wt-903 implementation is Sonnet; types defined here for interface clarity.
-// S-02: No wall-clock for easing — use requestAnimationFrame tick count.
-
-/** Camera state */
-export interface CameraState {
-  /** Current zoom factor (1.0 = default, higher = zoomed in) */
-  zoom: number;
-  /** Pan offset X in px */
-  panX: number;
-  /** Pan offset Y in px */
-  panY: number;
-}
-
-/** Snap-zoom target: center on a point at a specific zoom level */
-export interface SnapZoomTarget {
-  /** Target center X (in content coords, before zoom) */
-  x: number;
-  /** Target center Y (in content coords, before zoom) */
-  y: number;
-  /** Target zoom level */
-  zoom: number;
-  /** Easing duration in ms. Default 400. */
-  duration?: number;
-}
-
-/** Camera configuration */
-export interface CameraConfig {
-  /** Minimum zoom. Default 0.05. */
-  minZoom?: number;
-  /** Maximum zoom. Default 4.0. */
-  maxZoom?: number;
-  /** Zoom speed (scroll wheel multiplier). Default 0.001. */
-  zoomSpeed?: number;
-  /** Snap-zoom easing duration in ms. Default 400. */
-  snapDuration?: number;
-}
-
-/** Default camera config */
-export const DEFAULT_CAMERA_CONFIG: Required<CameraConfig> = {
-  minZoom: 0.05,
-  maxZoom: 4.0,
-  zoomSpeed: 0.001,
-  snapDuration: 400,
-};

package/src/spatial/content-proportional-bsp.ts

@@ -1,253 +0,0 @@
-// Content-Proportional BSP — Zone sizing based on Pretext-measured content
-// Zones split proportionally to their content area, not equally
-// Tiny zones become "colored blocks" (indicators) when below minContentThreshold
-
-import { measureBlock, type BlockMetrics } from '../x0-enchanted-blocks/core/block-layout.js';
-import type { BspNode, ZoneLeaf, SplitDirection, ZoneTilerConfig } from './zone-tiler-types.js';
-
-/** Content metadata attached to zones for proportional sizing */
-export interface ContentZone {
-  zone: ZoneLeaf;
-  content: string;
-  metrics?: BlockMetrics;
-  /** Effective area (width × height) for split ratio calculation */
-  contentArea: number;
-  /** When true, zone renders as compact indicator block */
-  isMinimized: boolean;
-}
-
-/** Configuration for content-proportional layout */
-export interface ProportionalBspConfig extends ZoneTilerConfig {
-  /** Minimum content area (px²) before zone becomes minimized block. Default: 10000 (100×100) */
-  minContentThreshold?: number;
-  /** Minimum zone dimension even for content-rich zones. Default: 80px */
-  absoluteMinZoneSize?: number;
-  /** Font for Pretext measurement. Default: system font */
-  measureFont?: string;
-  /** Max width constraint for content measurement. Default: 400px */
-  maxContentWidth?: number;
-}
-
-/** Build a BSP tree with splits proportional to content areas */
-export function buildProportionalBsp(
-  zones: ContentZone[],
-  direction: SplitDirection = 'horizontal',
-  config: ProportionalBspConfig = {}
-): BspNode {
-  const { minContentThreshold = 10000 } = config;
-  
-  // Measure all content
-  const measured = zones.map(z => ({
-    ...z,
-    metrics: measureBlock(z.content, config.measureFont, config.maxContentWidth),
-  }));
-  
-  // Calculate content areas
-  const withAreas = measured.map(z => {
-    const area = z.metrics ? z.metrics.idealWidth * z.metrics.height : 0;
-    return {
-      ...z,
-      contentArea: area,
-      isMinimized: area < minContentThreshold,
-    };
-  });
-  
-  // Separate minimized blocks from full zones
-  const fullZones = withAreas.filter(z => !z.isMinimized);
-  const minimizedBlocks = withAreas.filter(z => z.isMinimized);
-  
-  if (fullZones.length === 0) {
-    // All zones minimized — build equal BSP for colored blocks
-    return buildEqualBsp(minimizedBlocks.map(z => z.zone), direction);
-  }
-  
-  // Build proportional tree for full zones
-  let tree = buildWeightedBsp(fullZones, direction);
-  
-  // Add minimized blocks as a separate region if any exist
-  if (minimizedBlocks.length > 0) {
-    const minimizedTree = buildEqualBsp(minimizedBlocks.map(z => z.zone), 
-      direction === 'horizontal' ? 'vertical' : 'horizontal');
-    
-    // Split to add minimized region (small portion)
-    tree = {
-      kind: 'split',
-      direction,
-      ratio: 0.85, // 85% to full zones, 15% to minimized
-      first: tree,
-      second: minimizedTree,
-    };
-  }
-  
-  return tree;
-}
-
-/** Build BSP with splits weighted by content area */
-function buildWeightedBsp(zones: ContentZone[], direction: SplitDirection): BspNode {
-  if (zones.length === 0) {
-    throw new Error('Cannot build BSP from empty zones');
-  }
-  if (zones.length === 1) {
-    return zones[0].zone;
-  }
-  
-  // Sort by content area descending
-  const sorted = [...zones].sort((a, b) => b.contentArea - a.contentArea);
-  const totalArea = sorted.reduce((sum, z) => sum + z.contentArea, 0);
-  
-  // Find split point that balances area on each side
-  let accumulated = 0;
-  let splitIndex = 0;
-  const halfArea = totalArea / 2;
-  
-  for (let i = 0; i < sorted.length; i++) {
-    accumulated += sorted[i].contentArea;
-    if (accumulated >= halfArea) {
-      splitIndex = i + 1;
-      break;
-    }
-  }
-  
-  // Ensure at least one zone on each side
-  splitIndex = Math.max(1, Math.min(splitIndex, sorted.length - 1));
-  
-  const firstGroup = sorted.slice(0, splitIndex);
-  const secondGroup = sorted.slice(splitIndex);
-  
-  // Calculate split ratio based on area proportions
-  const firstArea = firstGroup.reduce((sum, z) => sum + z.contentArea, 0);
-  const ratio = firstArea / totalArea;
-  
-  // Recursively build subtrees
-  const firstNode = firstGroup.length === 1 
-    ? firstGroup[0].zone 
-    : buildWeightedBsp(firstGroup, flipDirection(direction));
-    
-  const secondNode = secondGroup.length === 1
-    ? secondGroup[0].zone
-    : buildWeightedBsp(secondGroup, flipDirection(direction));
-  
-  return {
-    kind: 'split',
-    direction,
-    ratio: Math.max(0.1, Math.min(0.9, ratio)), // Clamp between 10-90%
-    first: firstNode,
-    second: secondNode,
-  };
-}
-
-/** Build equal-split BSP (for minimized blocks) */
-function buildEqualBsp(zones: ZoneLeaf[], direction: SplitDirection): BspNode {
-  if (zones.length === 0) {
-    throw new Error('Cannot build BSP from empty zones');
-  }
-  if (zones.length === 1) {
-    return zones[0];
-  }
-  
-  const mid = Math.floor(zones.length / 2);
-  const firstGroup = zones.slice(0, mid);
-  const secondGroup = zones.slice(mid);
-  
-  const firstNode = firstGroup.length === 1
-    ? firstGroup[0]
-    : buildEqualBsp(firstGroup, flipDirection(direction));
-    
-  const secondNode = secondGroup.length === 1
-    ? secondGroup[0]
-    : buildEqualBsp(secondGroup, flipDirection(direction));
-  
-  return {
-    kind: 'split',
-    direction,
-    ratio: 0.5,
-    first: firstNode,
-    second: secondNode,
-  };
-}
-
-/** Alternate split direction */
-function flipDirection(d: SplitDirection): SplitDirection {
-  return d === 'horizontal' ? 'vertical' : 'horizontal';
-}
-
-/** Calculate zone sizing infographic data */
-export function generateSizingInfographic(
-  zones: ContentZone[],
-  containerWidth: number,
-  containerHeight: number,
-  config: ProportionalBspConfig = {}
-): SizingInfo[] {
-  const { minContentThreshold = 10000 } = config;
-  
-  return zones.map(z => {
-    const metrics = measureBlock(z.content, config.measureFont, config.maxContentWidth);
-    const area = metrics.idealWidth * metrics.height;
-    const isMinimized = area < minContentThreshold;
-    
-    // Calculate what fits
-    const fits: string[] = [];
-    if (metrics.lineCount >= 1) fits.push('Title');
-    if (metrics.lineCount >= 3) fits.push('Preview');
-    if (metrics.lineCount >= 8) fits.push('Full content');
-    if (area > minContentThreshold) fits.push('Edit mode');
-    
-    return {
-      zoneId: z.zone.id,
-      contentArea: area,
-      lines: metrics.lineCount,
-      isMinimized,
-      fits,
-      recommendedSize: isMinimized ? '40×40' : `${Math.round(metrics.idealWidth)}×${Math.round(metrics.height)}`,
-    };
-  });
-}
-
-/** Infographic data for each zone */
-export interface SizingInfo {
-  zoneId: string;
-  contentArea: number;
-  lines: number;
-  isMinimized: boolean;
-  fits: string[];
-  recommendedSize: string;
-}
-
-/**
- * Predict proportional split ratio based on actual content areas
- * Used to avoid static 50/50 splits
- */
-export function calculateProportionalRatio(
-  firstContent: string,
-  secondContent: string,
-  config: ProportionalBspConfig = {}
-): number {
-  const m1 = measureBlock(firstContent, config.measureFont, config.maxContentWidth);
-  const m2 = measureBlock(secondContent, config.measureFont, config.maxContentWidth);
-  
-  const area1 = m1.idealWidth * m1.height;
-  const area2 = m2.idealWidth * m2.height;
-  
-  if (area1 + area2 === 0) return 0.5;
-  
-  const ratio = area1 / (area1 + area2);
-  return Math.max(0.1, Math.min(0.9, ratio));
-}
-
-import { splitZone } from './zone-tiler-types.js';
-
-/** 
- * Split a leaf zone into two zones using text measurement to proportionalize the ratio 
- */
-export function splitZoneProportional(
-  root: BspNode,
-  targetId: string,
-  direction: SplitDirection,
-  newZone: ZoneLeaf,
-  targetContent: string,
-  newZoneContent: string,
-  config?: ProportionalBspConfig
-): BspNode {
-  const ratio = calculateProportionalRatio(targetContent, newZoneContent, config);
-  return splitZone(root, targetId, direction, newZone, ratio);
-}

package/src/spatial/force-canvas-types.ts

@@ -1,102 +0,0 @@
-// ForceCanvas — d3-force simulation types for spatial content layout
-// S-02: Integer permille for weights. Monotonic counter for tick. No Math.random.
-// S-05: Simulation has bounded iteration count per tick.
-
-/** A cell in the force simulation */
-export interface ForceCell {
-  id: string;
-  label: string;
-  /** Content type for visual differentiation */
-  contentType: 'text' | 'code' | 'url' | 'image' | 'filepath';
-  /** Visual weight — controls rendered size. Integer permille (0–1000). */
-  weight: number;
-  /** Embedding vector for semantic distance computation. Null = no embedding yet. */
-  embedding: number[] | null;
-  /** Pinned position (user-placed). Set fx/fy to pin. */
-  fx?: number | null;
-  fy?: number | null;
-  /** Arbitrary data for rendering */
-  data?: Record<string, unknown>;
-  // d3-force internal (populated by simulation)
-  x?: number;
-  y?: number;
-  vx?: number;
-  vy?: number;
-  index?: number;
-}
-
-/** Semantic link between cells (derived from embedding distance) */
-export interface ForceLink {
-  source: string;
-  target: string;
-  /** Semantic distance (0 = identical, 1 = unrelated). Drives spring length. */
-  distance: number;
-}
-
-/** ForceCanvas configuration */
-export interface ForceCanvasConfig {
-  /** Charge strength (repulsion between cells). Default -80. */
-  chargeStrength?: number;
-  /** Collision radius padding in px. Default 4. */
-  collisionPadding?: number;
-  /** Wall force margin in px (repulsion from zone boundary). Default 20. */
-  wallMargin?: number;
-  /** Wall force strength. Default 0.3. */
-  wallStrength?: number;
-  /** Minimum spring length (px) for highly similar content. Default 30. */
-  minSpringLength?: number;
-  /** Maximum spring length (px) for unrelated content. Default 200. */
-  maxSpringLength?: number;
-  /** Maximum simulation iterations per tick. Default 300. S-05 bound. */
-  maxIterations?: number;
-  /** Velocity decay (0–1). Default 0.4. Higher = more friction. */
-  velocityDecay?: number;
-  /** Initial velocity for newly added cells. Default 0.1. */
-  entryVelocity?: number;
-}
-
-/** Computed cell position for rendering */
-export interface CellPosition {
-  cell: ForceCell;
-  x: number;
-  y: number;
-  radius: number;
-}
-
-// ── Semantic distance → spring length ──────────────────────────────────────
-
-/** Convert cosine similarity to spring length.
- *  similarity 1.0 → minSpringLength, similarity 0.0 → maxSpringLength */
-export function semanticSpringLength(
-  similarity: number,
-  minLength: number,
-  maxLength: number
-): number {
-  const clamped = Math.max(0, Math.min(1, similarity));
-  return maxLength - clamped * (maxLength - minLength);
-}
-
-/** Compute cosine similarity between two embedding vectors.
- *  Returns 0 if either vector is null or empty. */
-export function cosineSimilarity(a: number[] | null, b: number[] | null): number {
-  if (!a || !b || a.length === 0 || b.length === 0 || a.length !== b.length) return 0;
-
-  let dot = 0;
-  let magA = 0;
-  let magB = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-    magA += a[i] * a[i];
-    magB += b[i] * b[i];
-  }
-
-  const denom = Math.sqrt(magA) * Math.sqrt(magB);
-  return denom === 0 ? 0 : dot / denom;
-}
-
-/** Weight permille → rendered radius in px */
-export function weightToRadius(permille: number, baseRadius = 8): number {
-  // weight 500 → baseRadius, scales sqrt for area proportionality
-  const normalized = Math.max(100, Math.min(1000, permille)) / 500;
-  return baseRadius * Math.sqrt(normalized);
-}

package/src/spatial/lod-types.ts

@@ -1,70 +0,0 @@
-// LodRenderer — Level of Detail types
-// S-02: Integer permille for health/weight. Deterministic tick counter for animation.
-// Pure TypeScript — no Svelte, no DOM.
-
-/** Discrete LOD levels */
-export type LodLevel = 0 | 1 | 2 | 3;
-
-/** Zoom thresholds for LOD transitions */
-export interface LodThresholds {
-  /** Zoom >= l0 → L0 (full). Default 0.8. */
-  l0: number;
-  /** Zoom >= l1 → L1 (compact). Default 0.4. */
-  l1: number;
-  /** Zoom >= l2 → L2 (dot/chip). Default 0.15. */
-  l2: number;
-  /** Zoom < l2 → L3 (pixel field). */
-}
-
-/** Default LOD thresholds matching ADR spec */
-export const DEFAULT_LOD_THRESHOLDS: LodThresholds = {
-  l0: 0.8,
-  l1: 0.4,
-  l2: 0.15,
-};
-
-/** LOD renderer configuration */
-export interface LodRendererConfig {
-  /** Zoom thresholds */
-  thresholds?: LodThresholds;
-  /** Cross-fade transition duration in ms. Default 300. */
-  crossFadeDuration?: number;
-}
-
-/** Per-cell LOD state tracked by the renderer */
-export interface CellLodState {
-  cellId: string;
-  /** Current active LOD level */
-  currentLevel: LodLevel;
-  /** Previous LOD level (for cross-fade) */
-  previousLevel: LodLevel | null;
-  /** Transition progress: 0 = showing previous, 1 = showing current. Null if not transitioning. */
-  transitionProgress: number | null;
-  /** Timestamp when transition started */
-  transitionStart: number | null;
-}
-
-/** Resolve zoom factor to LOD level */
-export function zoomToLod(zoom: number, thresholds: LodThresholds = DEFAULT_LOD_THRESHOLDS): LodLevel {
-  if (zoom >= thresholds.l0) return 0;
-  if (zoom >= thresholds.l1) return 1;
-  if (zoom >= thresholds.l2) return 2;
-  return 3;
-}
-
-/** LOD level descriptions for accessibility */
-export const LOD_DESCRIPTIONS: Record<LodLevel, string> = {
-  0: 'Full: editable cell with titlebar and resize handles',
-  1: 'Compact: title, type icon, first-line preview',
-  2: 'Chip: colored circle with abbreviation',
-  3: 'Pixel field: heat-mapped color mosaic',
-};
-
-/** L2 chip: 2-letter abbreviation from label */
-export function chipAbbrev(label: string): string {
-  const words = label.trim().split(/\s+/);
-  if (words.length >= 2) {
-    return (words[0][0] + words[1][0]).toUpperCase();
-  }
-  return label.slice(0, 2).toUpperCase();
-}