@stephen-netu/design-system 0.1.0 → 0.2.1

package/src/n3-force-graph/types.ts

@@ -1,94 +0,0 @@
-// N3 Force Graph — Types
-// Pure TypeScript — no Svelte, no DOM dependencies
-// S-02: all health values are integer permille (0–1000)
-
-// Re-export shared graph primitives from n1
-export type { GraphNode, GraphEdge, GraphSnapshot } from '../n1-flow-canvas/types.js';
-
-// === Force Graph Node (extends GraphNode with health/visual data) ===
-
-export interface ForceGraphNode {
-  id: string;
-  label: string;
-  /** Node category for visual differentiation */
-  type: 'app' | 'adr' | 'domain' | string;
-  /** Health score in permille (0–1000). 0 = critical, 1000 = healthy. */
-  health: number;
-  /** Node visual weight — controls circle radius. Default 1. */
-  weight?: number;
-  /** Optional: pinned position (drag-to-pin). Set fx/fy to pin. */
-  fx?: number;
-  fy?: number;
-  /** Arbitrary domain data for tooltip/detail rendering */
-  data?: Record<string, unknown>;
-  // d3-force internal (populated by simulation)
-  x?: number;
-  y?: number;
-  vx?: number;
-  vy?: number;
-  index?: number;
-}
-
-export interface ForceGraphLink {
-  id: string;
-  source: string;
-  target: string;
-  /** Edge rendering mode */
-  mode: 'active' | 'stub' | 'wired';
-  /** Optional label (e.g. dependency name) */
-  label?: string;
-}
-
-// === Health Node Config ===
-
-export interface HealthNodeConfig {
-  /** Base circle radius in px. Default 6. */
-  baseRadius?: number;
-  /** Whether to animate pulse on healthy nodes. Default true. */
-  pulseEnabled?: boolean;
-  /** Pulse amplitude (scale factor above 1.0). Default 0.02. */
-  pulseAmplitude?: number;
-}
-
-// === Animated Edge Config ===
-
-export interface AnimatedEdgeConfig {
-  /** Marching-ants dash length. Default 8. */
-  dashLength?: number;
-  /** Marching-ants gap length. Default 4. */
-  gapLength?: number;
-  /** Animation speed (px/frame). Default 0.5. */
-  marchSpeed?: number;
-}
-
-// === Graph Data (input to ForceGraph) ===
-
-export interface ForceGraphData {
-  nodes: ForceGraphNode[];
-  links: ForceGraphLink[];
-}
-
-// === Tooltip ===
-
-export interface TooltipPosition {
-  x: number;
-  y: number;
-  visible: boolean;
-}
-
-// === Health → Color mapping (integer permille thresholds) ===
-
-/** Map health permille to CSS color string. Pure function, no side effects. */
-export function healthToColor(permille: number): string {
-  if (permille >= 800) return '#27ae60'; // green — healthy
-  if (permille >= 500) return '#f39c12'; // amber — partial
-  if (permille >= 200) return '#c0392b'; // red — blocked/stub-heavy
-  return '#3a3a3a';                       // dark — no data / dead
-}
-
-/** Map health permille to glow opacity (0.0–0.4). Healthy = brighter glow. */
-export function healthToGlow(permille: number): number {
-  if (permille >= 800) return 0.3;
-  if (permille >= 500) return 0.15;
-  return 0.0; // No glow for unhealthy/dead
-}

package/src/n4-adaptive-manifold/classifier.ts

@@ -1,139 +0,0 @@
-// N4 TopologyClassifier — always returns manifold layout.
-// Pure function, no state. Deterministic given same input.
-// S-02: uses Map (ordered) for adjacency, not Set.
-
-import type {
-  ManifoldSnapshot,
-  LayoutAlgorithm,
-  ClassificationResult,
-  TopologyMetrics,
-} from './types.js';
-
-/** Number of consecutive matching classifications before suggesting. */
-export const STABILITY_TICKS = 3;
-
-export function classifyTopology(
-  snapshot: ManifoldSnapshot,
-): ClassificationResult {
-  // Manifold is the implemented layout algorithm.
-  // computeMetrics() is preserved for topology analysis.
-  const nodeCount = snapshot.nodes.length;
-  const edgeCount = snapshot.edges.length;
-  const edgeDensity = nodeCount > 0 ? edgeCount / nodeCount : 0;
-
-  return {
-    recommended: 'manifold',
-    confidence: 1.0,
-    reason: edgeCount === 0
-      ? 'manifold: sparse (no edges, S³ projection only)'
-      : `manifold: ${edgeCount} edges, density ${edgeDensity.toFixed(2)}`,
-    ranked: [{ algorithm: 'manifold' as LayoutAlgorithm, fitness: 1.0 }],
-    metrics: { nodeCount, edgeCount, edgeDensity, maxDepth: 0, rootCount: 0, cycleCount: 0, componentCount: 0, maxClusterSize: 0 },
-  };
-}
-
-// === Metrics computation (single pass, O(V+E)) ===
-
-export function computeMetrics(snapshot: ManifoldSnapshot): TopologyMetrics {
-  const nodeCount = snapshot.nodes.length;
-  const edgeCount = snapshot.edges.length;
-
-  if (nodeCount === 0) {
-    return { nodeCount: 0, edgeCount: 0, edgeDensity: 0, maxDepth: 0, rootCount: 0, cycleCount: 0, componentCount: 0, maxClusterSize: 0 };
-  }
-
-  // Note: "edgeDensity" here is edges/nodes (avg out-degree), NOT graph density (edges/(n*(n-1)/2)).
-  const edgeDensity = nodeCount > 0 ? edgeCount / nodeCount : 0;
-
-  // Build adjacency (directed) and undirected adjacency
-  // S-02: Map preserves insertion order (deterministic)
-  const adj = new Map<string, string[]>();
-  const uAdj = new Map<string, string[]>();
-  const inDegree = new Map<string, number>();
-
-  for (const n of snapshot.nodes) {
-    adj.set(n.id, []);
-    uAdj.set(n.id, []);
-    inDegree.set(n.id, 0);
-  }
-  for (const e of snapshot.edges) {
-    adj.get(e.source)?.push(e.target);
-    uAdj.get(e.source)?.push(e.target);
-    uAdj.get(e.target)?.push(e.source);
-    inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
-  }
-
-  // Roots: in-degree 0
-  let rootCount = 0;
-  for (const [, deg] of inDegree) {
-    if (deg === 0) rootCount++;
-  }
-
-  // Cycle detection via DFS (directed)
-  const WHITE = 0, GRAY = 1, BLACK = 2;
-  const color = new Map<string, number>();
-  for (const n of snapshot.nodes) color.set(n.id, WHITE);
-  let cycleCount = 0;
-
-  function dfs(nodeId: string): void {
-    color.set(nodeId, GRAY);
-    for (const neighbor of adj.get(nodeId) ?? []) {
-      const c = color.get(neighbor) ?? WHITE;
-      if (c === GRAY) { cycleCount++; }
-      else if (c === WHITE) { dfs(neighbor); }
-    }
-    color.set(nodeId, BLACK);
-  }
-
-  for (const n of snapshot.nodes) {
-    if (color.get(n.id) === WHITE) dfs(n.id);
-  }
-
-  // Max depth via BFS from roots (or all nodes if no roots)
-  let maxDepth = 0;
-  const depthVisited = new Map<string, boolean>();
-  const roots = snapshot.nodes.filter(n => (inDegree.get(n.id) ?? 0) === 0);
-  const bfsStart = roots.length > 0 ? roots : [snapshot.nodes[0]];
-
-  for (const root of bfsStart) {
-    if (depthVisited.get(root.id)) continue;
-    const queue: Array<{ id: string; depth: number }> = [{ id: root.id, depth: 0 }];
-    depthVisited.set(root.id, true);
-    while (queue.length > 0) {
-      const cur = queue.shift()!;
-      if (cur.depth > maxDepth) maxDepth = cur.depth;
-      for (const neighbor of adj.get(cur.id) ?? []) {
-        if (!depthVisited.get(neighbor)) {
-          depthVisited.set(neighbor, true);
-          queue.push({ id: neighbor, depth: cur.depth + 1 });
-        }
-      }
-    }
-  }
-
-  // Connected components via BFS on undirected graph
-  const compVisited = new Map<string, boolean>();
-  let componentCount = 0;
-  let maxClusterSize = 0;
-
-  for (const n of snapshot.nodes) {
-    if (compVisited.get(n.id)) continue;
-    componentCount++;
-    let clusterSize = 0;
-    const queue = [n.id];
-    compVisited.set(n.id, true);
-    while (queue.length > 0) {
-      const cur = queue.shift()!;
-      clusterSize++;
-      for (const nb of uAdj.get(cur) ?? []) {
-        if (!compVisited.get(nb)) {
-          compVisited.set(nb, true);
-          queue.push(nb);
-        }
-      }
-    }
-    if (clusterSize > maxClusterSize) maxClusterSize = clusterSize;
-  }
-
-  return { nodeCount, edgeCount, edgeDensity, maxDepth, rootCount, cycleCount, componentCount, maxClusterSize };
-}

package/src/n4-adaptive-manifold/orchestrator.ts

@@ -1,301 +0,0 @@
-// N4 LayoutOrchestrator — Coordinates algorithm providers, manages transitions
-// Owns the current layout state and drives the TransitionAnimator.
-// Includes 500ms debounce and 3-tick stability before suggesting.
-
-import type {
-  AlgorithmProvider,
-  LayoutAlgorithm,
-  ManifoldSnapshot,
-  LayoutPreferences,
-  ClassificationResult,
-  LayoutSuggestion,
-  NodeLayout,
-} from './types.js';
-import { DEFAULT_LAYOUT_PREFERENCES } from './types.js';
-import { classifyTopology, STABILITY_TICKS } from './classifier.js';
-import { TransitionAnimator, EASING_FUNCTIONS } from './transition.js';
-
-/** Debounce interval matching REFLEX tick cadence. */
-const CLASSIFY_DEBOUNCE_MS = 500;
-
-export interface OrchestratorState {
-  /** Currently active layout algorithm. */
-  activeAlgorithm: LayoutAlgorithm;
-  /** Current node positions (interpolated during transition). */
-  positions: Map<string, NodeLayout>;
-  /** Current BFS order for edge reveal. */
-  bfsOrder: ReadonlyArray<string>;
-  /** Whether a transition is in progress. */
-  transitioning: boolean;
-  /** Last classification result. */
-  lastClassification: ClassificationResult | null;
-  /** Current suggestion (null if none, or dismissed/pinned). */
-  suggestion: LayoutSuggestion | null;
-}
-
-export type OrchestratorListener = (state: OrchestratorState) => void;
-
-export class LayoutOrchestrator {
-  private providers: Map<LayoutAlgorithm, AlgorithmProvider>;
-  private prefs: LayoutPreferences;
-  private animator: TransitionAnimator;
-  private listeners: OrchestratorListener[] = [];
-
-  // Current state
-  private _activeAlgorithm: LayoutAlgorithm = 'manifold';
-  private _positions: Map<string, NodeLayout> = new Map();
-  private _bfsOrder: ReadonlyArray<string> = [];
-  private _transitioning = false;
-  private _lastClassification: ClassificationResult | null = null;
-  private _suggestion: LayoutSuggestion | null = null;
-  private _abortTransition: (() => void) | null = null;
-
-  // Debounce state
-  private _debounceTimer: ReturnType<typeof setTimeout> | null = null;
-  private _pendingSnapshot: ManifoldSnapshot | null = null;
-  private _pendingWidth = 0;
-  private _pendingHeight = 0;
-
-  // 3-tick stability counter
-  private _stabilityAlgorithm: LayoutAlgorithm | null = null;
-  private _stabilityCount = 0;
-
-  constructor(
-    providers: AlgorithmProvider[],
-    prefs: LayoutPreferences = DEFAULT_LAYOUT_PREFERENCES,
-  ) {
-    this.providers = new Map();
-    for (const p of providers) {
-      this.providers.set(p.algorithm, p);
-    }
-    this.prefs = prefs;
-    this.animator = new TransitionAnimator();
-  }
-
-  get state(): OrchestratorState {
-    return {
-      activeAlgorithm: this._activeAlgorithm,
-      positions: this._positions,
-      bfsOrder: this._bfsOrder,
-      transitioning: this._transitioning,
-      lastClassification: this._lastClassification,
-      suggestion: this._suggestion,
-    };
-  }
-
-  /** Subscribe to state changes. Returns unsubscribe function. */
-  subscribe(listener: OrchestratorListener): () => void {
-    this.listeners.push(listener);
-    return () => {
-      this.listeners = this.listeners.filter(l => l !== listener);
-    };
-  }
-
-  private notify(): void {
-    const state = this.state;
-    for (const l of this.listeners) l(state);
-  }
-
-  /**
-   * Request layout for the given snapshot. Debounced to 500ms.
-   * If currently transitioning (AM-Morph), the request is queued.
-   */
-  requestLayout(
-    snapshot: ManifoldSnapshot,
-    canvasWidth: number,
-    canvasHeight: number,
-  ): void {
-    this._pendingSnapshot = snapshot;
-    this._pendingWidth = canvasWidth;
-    this._pendingHeight = canvasHeight;
-
-    // If transitioning, don't schedule — will pick up after morph completes
-    if (this._transitioning) return;
-
-    // Debounce
-    if (this._debounceTimer !== null) {
-      clearTimeout(this._debounceTimer);
-    }
-
-    // First layout (no positions yet) runs immediately
-    if (this._positions.size === 0) {
-      this.executeLayout();
-      return;
-    }
-
-    this._debounceTimer = setTimeout(() => {
-      this._debounceTimer = null;
-      this.executeLayout();
-    }, CLASSIFY_DEBOUNCE_MS);
-  }
-
-  private async executeLayout(): Promise<void> {
-    const snapshot = this._pendingSnapshot;
-    if (!snapshot || snapshot.nodes.length === 0) return;
-
-    const canvasWidth = this._pendingWidth;
-    const canvasHeight = this._pendingHeight;
-
-    // Abort any in-flight transition
-    this._abortTransition?.();
-
-    // Classify
-    const classification = classifyTopology(snapshot);
-    this._lastClassification = classification;
-
-    // Determine target algorithm
-    let targetAlgorithm: LayoutAlgorithm;
-    if (this.prefs.lockedAlgorithm !== null) {
-      targetAlgorithm = this.prefs.lockedAlgorithm;
-    } else {
-      targetAlgorithm = classification.recommended;
-    }
-
-    // Update suggestion with 3-tick stability
-    this.updateSuggestion(classification, targetAlgorithm);
-
-    const provider = this.providers.get(targetAlgorithm);
-    if (!provider) return;
-
-    // Compute target layout
-    const targetLayout = await provider.layout(snapshot, canvasWidth, canvasHeight);
-
-    // If no current positions or animation disabled, apply immediately
-    if (this._positions.size === 0 || !this.prefs.animate) {
-      this._activeAlgorithm = targetAlgorithm;
-      this._positions = targetLayout.positions;
-      this._bfsOrder = targetLayout.bfsOrder;
-      this._transitioning = false;
-      this.notify();
-      return;
-    }
-
-    // AM-Morph: animate from current → target
-    this._transitioning = true;
-    this._activeAlgorithm = targetAlgorithm;
-    this.notify();
-
-    const easing = EASING_FUNCTIONS[this.prefs.easing] ?? EASING_FUNCTIONS.easeInOutCubic;
-
-    await new Promise<void>((resolve) => {
-      let cancelled = false;
-      this._abortTransition = () => { cancelled = true; };
-
-      this.animator.animate(
-        this._positions,
-        targetLayout.positions,
-        this.prefs.morphDurationMs,
-        easing,
-        (frame) => {
-          if (cancelled) return;
-          this._positions = frame.positions;
-          this.notify();
-        },
-        () => {
-          this._abortTransition = null;
-          if (cancelled) {
-            resolve();
-            return;
-          }
-          this._positions = targetLayout.positions;
-          this._bfsOrder = targetLayout.bfsOrder;
-          this._transitioning = false;
-          this.notify();
-
-          // Check if a new snapshot arrived during the morph.
-          // Route through requestLayout (debounce) rather than calling executeLayout()
-          // directly — prevents unbounded promise chaining under fast data arrival.
-          if (this._pendingSnapshot !== snapshot) {
-            this.requestLayout(this._pendingSnapshot!, this._pendingWidth, this._pendingHeight);
-          }
-          resolve();
-        },
-      );
-    });
-  }
-
-  /** 3-tick stability: only suggest after classifier recommends the same alternative 3 times. */
-  private updateSuggestion(classification: ClassificationResult, currentTarget: LayoutAlgorithm): void {
-    if (this.prefs.lockedAlgorithm !== null) {
-      // User has pinned — no suggestions
-      this._suggestion = null;
-      return;
-    }
-
-    if (classification.recommended === currentTarget) {
-      // Classifier agrees with current — clear stability counter
-      this._stabilityAlgorithm = null;
-      this._stabilityCount = 0;
-      this._suggestion = null;
-      return;
-    }
-
-    // Classifier disagrees — track stability
-    if (this._stabilityAlgorithm === classification.recommended) {
-      this._stabilityCount++;
-    } else {
-      this._stabilityAlgorithm = classification.recommended;
-      this._stabilityCount = 1;
-    }
-
-    if (this._stabilityCount >= STABILITY_TICKS) {
-      this._suggestion = {
-        algorithm: classification.recommended,
-        confidence: classification.confidence,
-        reason: classification.reason,
-        dismissed: false,
-        pinned: false,
-      };
-    }
-  }
-
-  /** Accept a layout suggestion — switch to suggested algorithm. */
-  acceptSuggestion(): void {
-    if (!this._suggestion) return;
-    this._activeAlgorithm = this._suggestion.algorithm;
-    this._suggestion = null;
-    this._stabilityCount = 0;
-    if (this._pendingSnapshot) {
-      // Set transitioning before executeLayout so requestLayout calls that arrive
-      // before executeLayout's first await are queued rather than double-fired.
-      this._transitioning = true;
-      this.setPreferences({ lockedAlgorithm: this._activeAlgorithm });
-      this.executeLayout();
-    }
-  }
-
-  /** Dismiss a layout suggestion — keep current algorithm. */
-  dismissSuggestion(): void {
-    if (this._suggestion) {
-      this._suggestion = { ...this._suggestion, dismissed: true };
-    }
-    this._stabilityCount = 0;
-    this.notify();
-  }
-
-  /** Pin the current layout (disable auto-classification). */
-  pinLayout(): void {
-    this.prefs.lockedAlgorithm = this._activeAlgorithm;
-    this._suggestion = null;
-    this.notify();
-  }
-
-  /** Unpin — re-enable auto-classification. */
-  unpinLayout(): void {
-    this.prefs.lockedAlgorithm = null;
-    this._stabilityCount = 0;
-    this.notify();
-  }
-
-  /** Update preferences (e.g. user toggles animation). */
-  setPreferences(prefs: Partial<LayoutPreferences>): void {
-    this.prefs = { ...this.prefs, ...prefs };
-  }
-
-  /** Clean up. */
-  destroy(): void {
-    this._abortTransition?.();
-    if (this._debounceTimer !== null) clearTimeout(this._debounceTimer);
-    this.listeners = [];
-  }
-}

package/src/n4-adaptive-manifold/phase-theme.ts

@@ -1,92 +0,0 @@
-import type { PhaseTheme, PhaseVisualParams } from './types.js';
-
-const PHASES = ['seed', 'sprout', 'go', 'consult', 'weed', 'freeze', 'compost', 'prune'] as const;
-
-function resolvePhaseParams(
-  style: CSSStyleDeclaration,
-  phase: string,
-): PhaseVisualParams {
-  const get = (prop: string) =>
-    style.getPropertyValue(`--n4-phase-${phase}-${prop}`).trim();
-
-  return {
-    background: get('background') || '#1a1a1a',
-    brightness: parseFloat(get('brightness')) || 0.5,
-    indicatorIntensity: parseFloat(get('indicator-intensity')) || 0.5,
-    ambientPulseSpeed: parseFloat(get('pulse-speed')) || 3,
-    saturation: parseFloat(get('saturation')) || 0.8,
-  };
-}
-
-/**
- * Resolve PhaseTheme from CSS custom properties on a container element.
- * Re-call on data-theme or class mutation.
- */
-export function resolvePhaseTheme(el: HTMLElement): PhaseTheme {
-  const style = getComputedStyle(el);
-  const theme: Record<string, PhaseVisualParams> = {};
-  for (const phase of PHASES) {
-    theme[phase] = resolvePhaseParams(style, phase);
-  }
-  return theme as unknown as PhaseTheme;
-}
-
-/** Fallback theme if CSS tokens are not set */
-export const DEFAULT_PHASE_THEME: PhaseTheme = {
-  seed: {
-    background: '#1a1a1a',
-    brightness: 0.4,
-    indicatorIntensity: 0.3,
-    ambientPulseSpeed: 4,
-    saturation: 0.6,
-  },
-  sprout: {
-    background: '#1a1c1a',
-    brightness: 0.7,
-    indicatorIntensity: 0.7,
-    ambientPulseSpeed: 2.5,
-    saturation: 0.85,
-  },
-  go: {
-    background: '#1c1a18',
-    brightness: 1.0,
-    indicatorIntensity: 1.0,
-    ambientPulseSpeed: 1.5,
-    saturation: 1.0,
-  },
-  consult: {
-    background: '#1b1a1c',
-    brightness: 0.85,
-    indicatorIntensity: 0.85,
-    ambientPulseSpeed: 2.0,
-    saturation: 0.9,
-  },
-  weed: {
-    background: '#1c1b18',
-    brightness: 0.65,
-    indicatorIntensity: 0.6,
-    ambientPulseSpeed: 2.5,
-    saturation: 0.75,
-  },
-  freeze: {
-    background: '#1a1a1e',
-    brightness: 0.2,
-    indicatorIntensity: 0.1,
-    ambientPulseSpeed: 8,
-    saturation: 0.2,
-  },
-  compost: {
-    background: '#1a1a1a',
-    brightness: 0.25,
-    indicatorIntensity: 0.15,
-    ambientPulseSpeed: 6,
-    saturation: 0.3,
-  },
-  prune: {
-    background: '#1c1a1a',
-    brightness: 0.2,
-    indicatorIntensity: 0.1,
-    ambientPulseSpeed: 8,
-    saturation: 0.2,
-  },
-};