@stephen-netu/design-system 0.1.0

package/src/spatial/ForceCanvas.svelte

@@ -0,0 +1,289 @@
+<script lang="ts">
+  // ForceCanvas — d3-force simulation for a single zone
+  // wt-901: Per-zone semantic gravity, wall forces, cell entry velocity
+  //
+  // Wraps d3-force (not force-graph library) for direct control over forces.
+  // Each zone gets an independent simulation. Cells cluster by semantic similarity.
+  //
+  // S-02: No Math.random — d3-force uses internal PRNG seeded by node index.
+  //       Integer permille for weights.
+  // S-05: Simulation bounded by maxIterations (default 300). alpha decay ensures halt.
+
+  import { onMount, onDestroy } from 'svelte';
+  import type { ForceCell, ForceLink, ForceCanvasConfig, CellPosition } from './force-canvas-types.js';
+  import {
+    cosineSimilarity,
+    semanticSpringLength,
+    weightToRadius,
+  } from './force-canvas-types.js';
+
+  // ── Props ────────────────────────────────────────────────────────────────
+
+  interface Props {
+    /** Cells to position in this zone */
+    cells: ForceCell[];
+    /** Zone width in px */
+    width: number;
+    /** Zone height in px */
+    height: number;
+    /** Configuration overrides */
+    config?: ForceCanvasConfig;
+    /** Whether simulation is active. Default true. Set false for Scelle zones. */
+    active?: boolean;
+    /** Callback with updated cell positions on each tick */
+    onPositionsUpdate?: (positions: CellPosition[]) => void;
+    /** Callback when a cell is clicked */
+    onCellClick?: (cell: ForceCell) => void;
+    /** Monotonic tick counter (passed from parent for deterministic pulse). */
+    tick?: number;
+  }
+
+  let {
+    cells,
+    width,
+    height,
+    config,
+    active = true,
+    onPositionsUpdate,
+    onCellClick,
+    tick = 0,
+  }: Props = $props();
+
+  // ── Config defaults ──────────────────────────────────────────────────────
+
+  const chargeStrength = $derived(config?.chargeStrength ?? -80);
+  const collisionPadding = $derived(config?.collisionPadding ?? 4);
+  const wallMargin = $derived(config?.wallMargin ?? 20);
+  const wallStrength = $derived(config?.wallStrength ?? 0.3);
+  const minSpringLength = $derived(config?.minSpringLength ?? 30);
+  const maxSpringLength = $derived(config?.maxSpringLength ?? 200);
+  const maxIterations = $derived(config?.maxIterations ?? 300);
+  const velocityDecay = $derived(config?.velocityDecay ?? 0.4);
+  const entryVelocity = $derived(config?.entryVelocity ?? 0.1);
+
+  // ── Simulation state ─────────────────────────────────────────────────────
+
+  let simulation: any = null; // d3-force simulation
+  let positions: CellPosition[] = $state([]);
+
+  // ── Build semantic links from embeddings ─────────────────────────────────
+
+  function buildSemanticLinks(cells: ForceCell[]): ForceLink[] {
+    const links: ForceLink[] = [];
+    const SIMILARITY_THRESHOLD = 0.3;
+
+    for (let i = 0; i < cells.length; i++) {
+      for (let j = i + 1; j < cells.length; j++) {
+        const sim = cosineSimilarity(cells[i].embedding, cells[j].embedding);
+        if (sim > SIMILARITY_THRESHOLD) {
+          links.push({
+            source: cells[i].id,
+            target: cells[j].id,
+            distance: 1 - sim,
+          });
+        }
+      }
+    }
+    return links;
+  }
+
+  // ── Wall force (custom d3 force) ─────────────────────────────────────────
+
+  function createWallForce(w: number, h: number, margin: number, strength: number) {
+    let nodes: ForceCell[] = [];
+
+    function force(alpha: number) {
+      for (const node of nodes) {
+        const x = node.x ?? 0;
+        const y = node.y ?? 0;
+        const r = weightToRadius(node.weight);
+
+        // Left wall
+        if (x - r < margin) {
+          node.vx = (node.vx ?? 0) + (margin - x + r) * strength * alpha;
+        }
+        // Right wall
+        if (x + r > w - margin) {
+          node.vx = (node.vx ?? 0) - (x + r - w + margin) * strength * alpha;
+        }
+        // Top wall
+        if (y - r < margin) {
+          node.vy = (node.vy ?? 0) + (margin - y + r) * strength * alpha;
+        }
+        // Bottom wall
+        if (y + r > h - margin) {
+          node.vy = (node.vy ?? 0) - (y + r - h + margin) * strength * alpha;
+        }
+      }
+    }
+
+    force.initialize = (n: ForceCell[]) => { nodes = n; };
+    return force;
+  }
+
+  // ── Initialize / update simulation ───────────────────────────────────────
+
+  async function initSimulation() {
+    if (!active || cells.length === 0) {
+      positions = [];
+      onPositionsUpdate?.([]);
+      return;
+    }
+
+    const d3 = await import('d3-force');
+
+    const links = buildSemanticLinks(cells);
+
+    // Place new cells near center with slight offset
+    const cx = width / 2;
+    const cy = height / 2;
+    for (const cell of cells) {
+      if (cell.x === undefined) {
+        cell.x = cx + (cell.index ?? 0) * 3;
+        cell.y = cy + (cell.index ?? 0) * 2;
+        // Entry velocity: nudge away from center
+        if (entryVelocity > 0) {
+          const angle = ((cell.index ?? 0) / Math.max(1, cells.length)) * Math.PI * 2;
+          cell.vx = Math.cos(angle) * entryVelocity * 100;
+          cell.vy = Math.sin(angle) * entryVelocity * 100;
+        }
+      }
+    }
+
+    simulation?.stop();
+
+    simulation = d3
+      .forceSimulation(cells as any)
+      .alphaDecay(0.02)
+      .velocityDecay(velocityDecay)
+      .force(
+        'charge',
+        d3.forceManyBody().strength(chargeStrength)
+      )
+      .force(
+        'collision',
+        d3.forceCollide<ForceCell>()
+          .radius((d) => weightToRadius(d.weight) + collisionPadding)
+      )
+      .force(
+        'link',
+        d3
+          .forceLink(links as any)
+          .id((d: any) => d.id)
+          .distance((link: any) =>
+            semanticSpringLength(1 - link.distance, minSpringLength, maxSpringLength)
+          )
+          .strength(0.5)
+      )
+      .force('center', d3.forceCenter(cx, cy).strength(0.03))
+      .force('wall', createWallForce(width, height, wallMargin, wallStrength))
+      .on('tick', () => {
+        positions = cells.map((cell) => ({
+          cell,
+          x: cell.x ?? 0,
+          y: cell.y ?? 0,
+          radius: weightToRadius(cell.weight),
+        }));
+        onPositionsUpdate?.(positions);
+      });
+
+    // S-05: bound total iterations
+    simulation.stop();
+    for (let i = 0; i < maxIterations && simulation.alpha() > simulation.alphaMin(); i++) {
+      simulation.tick();
+    }
+
+    // After initial settle, switch to live ticking
+    simulation.restart();
+  }
+
+  // ── Lifecycle ────────────────────────────────────────────────────────────
+
+  onMount(() => {
+    initSimulation();
+  });
+
+  onDestroy(() => {
+    simulation?.stop();
+    simulation = null;
+  });
+
+  // ── React to cell changes ────────────────────────────────────────────────
+
+  let prevCellIds = '';
+  $effect(() => {
+    const ids = cells.map((c) => c.id).sort().join(',');
+    if (ids !== prevCellIds) {
+      prevCellIds = ids;
+      initSimulation();
+    }
+  });
+
+  // React to zone resize
+  $effect(() => {
+    if (simulation && (width || height)) {
+      simulation.force('center')?.x(width / 2).y(height / 2);
+      simulation.force('wall', createWallForce(width, height, wallMargin, wallStrength));
+      simulation.alpha(0.3).restart();
+    }
+  });
+
+  // ── Pin/unpin API ────────────────────────────────────────────────────────
+
+  export function pinCell(cellId: string, x: number, y: number) {
+    const cell = cells.find((c) => c.id === cellId);
+    if (cell) {
+      cell.fx = x;
+      cell.fy = y;
+      simulation?.alpha(0.1).restart();
+    }
+  }
+
+  export function unpinCell(cellId: string) {
+    const cell = cells.find((c) => c.id === cellId);
+    if (cell) {
+      cell.fx = null;
+      cell.fy = null;
+      simulation?.alpha(0.3).restart();
+    }
+  }
+
+  export function reheat(alpha = 0.5) {
+    simulation?.alpha(alpha).restart();
+  }
+</script>
+
+<!-- ForceCanvas is headless — it computes positions, doesn't render DOM.
+     The parent reads positions via onPositionsUpdate and renders cells at those coords.
+     This is a div solely for lifecycle binding. -->
+<div class="force-canvas" style:display="contents">
+  {#each positions as pos (pos.cell.id)}
+    <slot name="cell" {pos}>
+      <!-- Default: colored circle at computed position -->
+      <!-- svelte-ignore a11y_no_static_element_interactions -->
+      <div
+        class="force-cell-default"
+        style:left="{pos.x - pos.radius}px"
+        style:top="{pos.y - pos.radius}px"
+        style:width="{pos.radius * 2}px"
+        style:height="{pos.radius * 2}px"
+        onclick={() => onCellClick?.(pos.cell)}
+      ></div>
+    </slot>
+  {/each}
+</div>
+
+<style>
+  .force-cell-default {
+    position: absolute;
+    border-radius: 50%;
+    background: var(--color-accent, #b87333);
+    opacity: 0.7;
+    cursor: pointer;
+    transition: opacity 0.1s;
+  }
+
+  .force-cell-default:hover {
+    opacity: 1;
+  }
+</style>

package/src/spatial/LodRenderer.svelte

@@ -0,0 +1,334 @@
+<script lang="ts">
+  // LodRenderer — 4-level LOD rendering with cross-fade transitions
+  // wt-902: The signature visual system — recursive zoom experience
+  //
+  // Renders each cell at the appropriate LOD level based on current zoom.
+  // Manages cross-fade transitions between levels (300ms default).
+  // Parent provides render callbacks per level; LodRenderer manages which shows.
+  //
+  // L0 (>0.8x): Full cell — editable, titlebar, resize handles
+  // L1 (0.4x-0.8x): Compact — title + type icon + first-line preview
+  // L2 (0.15x-0.4x): Chip — colored circle, 2-letter abbrev
+  // L3 (<0.15x): Pixel field — cells dissolve into color mosaic
+  //
+  // S-02: Transition timing from monotonic tick counter, not wall-clock.
+  // S-05: Bounded cell count. No unbounded iteration.
+
+  import type { Snippet } from 'svelte';
+  import type { CellPosition } from './force-canvas-types.js';
+  import type { LodLevel, LodRendererConfig, CellLodState } from './lod-types.js';
+  import { zoomToLod, DEFAULT_LOD_THRESHOLDS, chipAbbrev } from './lod-types.js';
+
+  // ── Props ────────────────────────────────────────────────────────────────
+
+  interface Props {
+    /** Cell positions from ForceCanvas */
+    positions: CellPosition[];
+    /** Current camera zoom factor (0–∞, 1.0 = default) */
+    zoom: number;
+    /** Container width in px */
+    width: number;
+    /** Container height in px */
+    height: number;
+    /** Camera pan offset X */
+    panX?: number;
+    /** Camera pan offset Y */
+    panY?: number;
+    /** Config overrides */
+    config?: LodRendererConfig;
+
+    // ── Level render callbacks (snippets) ──────────────────────────────
+
+    /** L0: Full cell editor view */
+    renderL0?: Snippet<[CellPosition, LodLevel]>;
+    /** L1: Compact card view */
+    renderL1?: Snippet<[CellPosition, LodLevel]>;
+    /** L2: Dot/chip view */
+    renderL2?: Snippet<[CellPosition, LodLevel]>;
+    /** L3 renders as a full-zone pixel field — no per-cell callback.
+     *  Instead, the parent provides an L3 overlay snippet. */
+    renderL3?: Snippet<[CellPosition[], number]>; // positions[], zoom
+
+    /** Click handler — forwarded from individual cells */
+    onCellClick?: (cellId: string, level: LodLevel) => void;
+  }
+
+  let {
+    positions,
+    zoom,
+    width,
+    height,
+    panX = 0,
+    panY = 0,
+    config,
+    renderL0,
+    renderL1,
+    renderL2,
+    renderL3,
+    onCellClick,
+  }: Props = $props();
+
+  // ── Config ───────────────────────────────────────────────────────────────
+
+  const thresholds = $derived(config?.thresholds ?? DEFAULT_LOD_THRESHOLDS);
+  const crossFadeDuration = $derived(config?.crossFadeDuration ?? 300);
+
+  // ── Current LOD level ────────────────────────────────────────────────────
+
+  const currentLod = $derived(zoomToLod(zoom, thresholds));
+
+  // ── Per-cell LOD state for cross-fade ────────────────────────────────────
+
+  // Map<cellId, CellLodState> — tracks transition state per cell
+  let lodStates: Map<string, CellLodState> = $state(new Map());
+  let animFrameId: number | null = null;
+
+  // Update LOD states when level changes
+  $effect(() => {
+    const level = currentLod;
+    const now = performance.now();
+    let needsAnimation = false;
+
+    for (const pos of positions) {
+      const existing = lodStates.get(pos.cell.id);
+
+      if (!existing) {
+        // New cell — no transition
+        lodStates.set(pos.cell.id, {
+          cellId: pos.cell.id,
+          currentLevel: level,
+          previousLevel: null,
+          transitionProgress: null,
+          transitionStart: null,
+        });
+      } else if (existing.currentLevel !== level) {
+        // Level changed — start cross-fade
+        lodStates.set(pos.cell.id, {
+          cellId: pos.cell.id,
+          currentLevel: level,
+          previousLevel: existing.currentLevel,
+          transitionProgress: 0,
+          transitionStart: now,
+        });
+        needsAnimation = true;
+      }
+    }
+
+    // Clean up cells that no longer exist
+    const activeIds = new Set(positions.map((p) => p.cell.id));
+    for (const id of lodStates.keys()) {
+      if (!activeIds.has(id)) lodStates.delete(id);
+    }
+
+    if (needsAnimation) startAnimation();
+  });
+
+  function startAnimation() {
+    if (animFrameId !== null) return;
+    animFrameId = requestAnimationFrame(animateTransitions);
+  }
+
+  function animateTransitions() {
+    const now = performance.now();
+    let anyActive = false;
+
+    for (const [id, state] of lodStates) {
+      if (state.transitionProgress === null || state.transitionStart === null) continue;
+
+      const elapsed = now - state.transitionStart;
+      const progress = Math.min(1, elapsed / crossFadeDuration);
+
+      lodStates.set(id, { ...state, transitionProgress: progress });
+
+      if (progress < 1) {
+        anyActive = true;
+      } else {
+        // Transition complete — clear previous level
+        lodStates.set(id, {
+          ...state,
+          previousLevel: null,
+          transitionProgress: null,
+          transitionStart: null,
+        });
+      }
+    }
+
+    if (anyActive) {
+      animFrameId = requestAnimationFrame(animateTransitions);
+    } else {
+      animFrameId = null;
+    }
+  }
+
+  // ── Helpers ──────────────────────────────────────────────────────────────
+
+  function getOpacity(cellId: string, forLevel: 'current' | 'previous'): number {
+    const state = lodStates.get(cellId);
+    if (!state || state.transitionProgress === null) {
+      return forLevel === 'current' ? 1 : 0;
+    }
+    // ease-out cubic
+    const t = state.transitionProgress;
+    const eased = 1 - Math.pow(1 - t, 3);
+    return forLevel === 'current' ? eased : 1 - eased;
+  }
+
+  function getLodState(cellId: string): CellLodState | undefined {
+    return lodStates.get(cellId);
+  }
+
+  // ── Cleanup ──────────────────────────────────────────────────────────────
+
+  import { onDestroy } from 'svelte';
+
+  onDestroy(() => {
+    if (animFrameId !== null) cancelAnimationFrame(animFrameId);
+  });
+</script>
+
+<div
+  class="lod-renderer"
+  style:width="{width}px"
+  style:height="{height}px"
+>
+  <div
+    class="lod-viewport"
+    style:transform="translate({panX}px, {panY}px) scale({zoom})"
+    style:transform-origin="0 0"
+  >
+    {#if currentLod === 3 && renderL3}
+      <!-- L3: pixel field — render full-zone overlay -->
+      <div class="lod-l3-field" style:width="{width / zoom}px" style:height="{height / zoom}px">
+        {@render renderL3(positions, zoom)}
+      </div>
+    {:else}
+      <!-- L0/L1/L2: per-cell rendering -->
+      {#each positions as pos (pos.cell.id)}
+        {@const state = getLodState(pos.cell.id)}
+        {@const isTransitioning = state?.transitionProgress !== null && state?.transitionProgress !== undefined}
+
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <div
+          class="lod-cell"
+          style:left="{pos.x - pos.radius}px"
+          style:top="{pos.y - pos.radius}px"
+          onclick={() => onCellClick?.(pos.cell.id, currentLod)}
+          data-lod={currentLod}
+          data-cell-id={pos.cell.id}
+        >
+          <!-- Current level -->
+          <div
+            class="lod-layer lod-current"
+            style:opacity={getOpacity(pos.cell.id, 'current')}
+          >
+            {#if currentLod === 0 && renderL0}
+              {@render renderL0(pos, currentLod)}
+            {:else if currentLod === 1 && renderL1}
+              {@render renderL1(pos, currentLod)}
+            {:else if currentLod === 2 && renderL2}
+              {@render renderL2(pos, currentLod)}
+            {:else}
+              <!-- Fallback: chip -->
+              <div
+                class="lod-chip"
+                style:width="{pos.radius * 2}px"
+                style:height="{pos.radius * 2}px"
+              >
+                <span class="lod-chip-label">{chipAbbrev(pos.cell.label)}</span>
+              </div>
+            {/if}
+          </div>
+
+          <!-- Previous level (cross-fade out) -->
+          {#if isTransitioning && state?.previousLevel !== null}
+            <div
+              class="lod-layer lod-previous"
+              style:opacity={getOpacity(pos.cell.id, 'previous')}
+            >
+              {#if state.previousLevel === 0 && renderL0}
+                {@render renderL0(pos, state.previousLevel)}
+              {:else if state.previousLevel === 1 && renderL1}
+                {@render renderL1(pos, state.previousLevel)}
+              {:else if state.previousLevel === 2 && renderL2}
+                {@render renderL2(pos, state.previousLevel)}
+              {:else}
+                <div
+                  class="lod-chip"
+                  style:width="{pos.radius * 2}px"
+                  style:height="{pos.radius * 2}px"
+                >
+                  <span class="lod-chip-label">{chipAbbrev(pos.cell.label)}</span>
+                </div>
+              {/if}
+            </div>
+          {/if}
+        </div>
+      {/each}
+    {/if}
+  </div>
+</div>
+
+<style>
+  .lod-renderer {
+    position: relative;
+    overflow: hidden;
+  }
+
+  .lod-viewport {
+    position: absolute;
+    top: 0;
+    left: 0;
+    will-change: transform;
+  }
+
+  .lod-cell {
+    position: absolute;
+    cursor: pointer;
+  }
+
+  .lod-layer {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    will-change: opacity;
+  }
+
+  .lod-previous {
+    pointer-events: none;
+  }
+
+  /* ── L2 chip fallback ──────────────────────────────────────────── */
+
+  .lod-chip {
+    border-radius: 50%;
+    background: var(--color-accent, #b87333);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0.85;
+    transition: opacity 0.1s;
+  }
+
+  .lod-chip:hover {
+    opacity: 1;
+  }
+
+  .lod-chip-label {
+    font-family: var(--font-mono, monospace);
+    font-size: 9px;
+    font-weight: 600;
+    color: var(--color-text-primary, #e8e0d0);
+    letter-spacing: 0.5px;
+    user-select: none;
+  }
+
+  /* ── L3 field ──────────────────────────────────────────────────── */
+
+  .lod-l3-field {
+    position: absolute;
+    top: 0;
+    left: 0;
+  }
+</style>