@stephen-netu/design-system 0.1.0

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

@@ -0,0 +1,253 @@
+// 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

@@ -0,0 +1,102 @@
+// 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/index.ts

@@ -0,0 +1,15 @@
+// Spatial primitives — BSP zone tiling, force-directed layout, LOD rendering, snap-zoom camera
+// Consumed by Loge first; available to Atelier and future apps.
+
+export * from './zone-tiler-types.js';
+export * from './force-canvas-types.js';
+export * from './lod-types.js';
+export * from './camera-types.js';
+export * from './content-proportional-bsp.js';
+
+// Components are imported directly:
+//   import ZoneTiler from '@kos/design-system/spatial/ZoneTiler.svelte';
+//   import ForceCanvas from '@kos/design-system/spatial/ForceCanvas.svelte';
+//   import LodRenderer from '@kos/design-system/spatial/LodRenderer.svelte';
+//   import SnapZoomCamera from '@kos/design-system/spatial/SnapZoomCamera.svelte';
+//   import BspTilingCanvas from '@kos/design-system/spatial/BspTilingCanvas.svelte';

package/src/spatial/lod-types.ts

@@ -0,0 +1,70 @@
+// 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();
+}

package/src/spatial/zone-tiler-types.ts

@@ -0,0 +1,177 @@
+// ZoneTiler — BSP tree zone layout types
+// S-02: No HashMap/HashSet — use sorted arrays for zone lookup.
+// Pure TypeScript — no Svelte, no DOM.
+
+/** Privacy state matching Rust SealState enum */
+export type PrivacyState = 'ouvert' | 'scelle';
+
+/** Leaf node — a visible zone */
+export interface ZoneLeaf {
+  kind: 'leaf';
+  id: string;
+  label: string;
+  /** Optional tint for zone background. Ouvert zones derive color from content; Scelle uses fixed hazard treatment. */
+  colorTint?: string;
+  privacyState: PrivacyState;
+}
+
+/** Split direction */
+export type SplitDirection = 'horizontal' | 'vertical';
+
+/** Internal split node — divides space into two children */
+export interface ZoneSplit {
+  kind: 'split';
+  direction: SplitDirection;
+  /** Divider position as fraction (0–1) of parent dimension */
+  ratio: number;
+  first: BspNode;
+  second: BspNode;
+}
+
+/** A BSP tree node: either a leaf zone or a split */
+export type BspNode = ZoneLeaf | ZoneSplit;
+
+/** Computed zone rectangle (absolute pixel coords within container) */
+export interface ZoneRect {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  zone: ZoneLeaf;
+}
+
+/** Computed divider rectangle for hit-testing and rendering */
+export interface DividerRect {
+  /** Path from root to this split (for identity) */
+  path: string;
+  direction: SplitDirection;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Reference to parent split for ratio mutation */
+  splitRef: ZoneSplit;
+}
+
+/** ZoneTiler configuration */
+export interface ZoneTilerConfig {
+  /** Minimum zone dimension in px. Default 120. */
+  minZoneSize?: number;
+  /** Divider thickness in px. Default 6. */
+  dividerThickness?: number;
+  /** Divider hit-area expansion in px (each side). Default 4. */
+  dividerHitExpand?: number;
+}
+
+// ── BSP utilities ──────────────────────────────────────────────────────────
+
+/** Flatten a BSP tree into leaf zones with computed rectangles */
+export function flattenBsp(
+  node: BspNode,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  dividerThickness: number
+): { zones: ZoneRect[]; dividers: DividerRect[] } {
+  if (node.kind === 'leaf') {
+    return {
+      zones: [{ id: node.id, x, y, width: w, height: h, zone: node }],
+      dividers: [],
+    };
+  }
+
+  const dt = dividerThickness;
+  const { direction, ratio, first, second } = node;
+
+  let firstRect: { x: number; y: number; w: number; h: number };
+  let secondRect: { x: number; y: number; w: number; h: number };
+  let divider: DividerRect;
+
+  if (direction === 'horizontal') {
+    // Split left/right
+    const splitX = x + (w - dt) * ratio;
+    firstRect = { x, y, w: splitX - x, h };
+    secondRect = { x: splitX + dt, y, w: x + w - splitX - dt, h };
+    divider = {
+      path: `${x},${y}:h:${ratio.toFixed(4)}`,
+      direction,
+      x: splitX,
+      y,
+      width: dt,
+      height: h,
+      splitRef: node,
+    };
+  } else {
+    // Split top/bottom
+    const splitY = y + (h - dt) * ratio;
+    firstRect = { x, y, w, h: splitY - y };
+    secondRect = { x, y: splitY + dt, w, h: y + h - splitY - dt };
+    divider = {
+      path: `${x},${y}:v:${ratio.toFixed(4)}`,
+      direction,
+      x,
+      y: splitY,
+      width: w,
+      height: dt,
+      splitRef: node,
+    };
+  }
+
+  const a = flattenBsp(first, firstRect.x, firstRect.y, firstRect.w, firstRect.h, dt);
+  const b = flattenBsp(second, secondRect.x, secondRect.y, secondRect.w, secondRect.h, dt);
+
+  return {
+    zones: [...a.zones, ...b.zones],
+    dividers: [divider, ...a.dividers, ...b.dividers],
+  };
+}
+
+/** Find a zone leaf by id in the BSP tree */
+export function findZone(node: BspNode, id: string): ZoneLeaf | null {
+  if (node.kind === 'leaf') return node.id === id ? node : null;
+  return findZone(node.first, id) ?? findZone(node.second, id);
+}
+
+/** Create a default single-zone BSP tree */
+export function createDefaultBsp(id = 'main', label = 'Main'): ZoneLeaf {
+  return { kind: 'leaf', id, label, privacyState: 'ouvert' };
+}
+
+/** Split a leaf zone into two zones. Returns a new BSP tree (immutable). */
+export function splitZone(
+  root: BspNode,
+  targetId: string,
+  direction: SplitDirection,
+  newZone: ZoneLeaf,
+  ratio = 0.5
+): BspNode {
+  if (root.kind === 'leaf') {
+    if (root.id === targetId) {
+      return {
+        kind: 'split',
+        direction,
+        ratio,
+        first: root,
+        second: newZone,
+      };
+    }
+    return root;
+  }
+  return {
+    ...root,
+    first: splitZone(root.first, targetId, direction, newZone, ratio),
+    second: splitZone(root.second, targetId, direction, newZone, ratio),
+  };
+}
+
+/** Serialize BSP tree to JSON (for desk persistence) */
+export function serializeBsp(node: BspNode): string {
+  return JSON.stringify(node);
+}
+
+/** Deserialize BSP tree from JSON */
+export function deserializeBsp(json: string): BspNode {
+  return JSON.parse(json) as BspNode;
+}

package/src/stores/vaultStore.svelte

@@ -0,0 +1,14 @@
+<script lang="ts" module>
+// Stub implementation for vault store
+export const vaultStore = {
+    async hasFileChangedExternally(_path: string): Promise<boolean> {
+        return false;
+    },
+    async getFileModifiedTime(_path: string): Promise<number> {
+        return Date.now();
+    },
+    updateFileState(_path: string, _content: string, _modifiedAt: number): void {
+        // Stub
+    }
+};
+</script>

package/src/t0-transport/connection.ts

@@ -0,0 +1,34 @@
+// Connection status tracking
+
+export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'error';
+
+export interface ConnectionTracker {
+  readonly state: ConnectionState;
+  subscribe(fn: (state: ConnectionState) => void): () => void;
+  setState(state: ConnectionState): void;
+}
+
+/**
+ * Track connection status to Tauri backend
+ */
+export function createConnectionTracker(): ConnectionTracker {
+  let state = $state<ConnectionState>('disconnected');
+  const subscribers = new Set<(state: ConnectionState) => void>();
+
+  function setState(newState: ConnectionState) {
+    state = newState;
+    subscribers.forEach(fn => fn(state));
+  }
+
+  function subscribe(fn: (state: ConnectionState) => void) {
+    subscribers.add(fn);
+    fn(state);
+    return () => subscribers.delete(fn);
+  }
+
+  return {
+    get state() { return state; },
+    setState,
+    subscribe,
+  };
+}