@stephen-netu/design-system 0.1.0 → 0.2.1

package/src/x0-enchanted-blocks/ENCHANTED_BLOCKS_SPEC.md

@@ -1,457 +0,0 @@
-# Enchanted Blocks — Unified Spatial Content System
-
-## Problem Statement
-
-Three KOS apps hit the same wall: **content doesn't fit**, and **enrichment is one-way**.
-
-- **Ryu**: Task descriptions, daemon logs, and epistemic assay results overflow their containers. We gave up on rich task content.
-- **Atelier**: Notes can't display KVE bidirectional enrichment. The canvas is static, not living.
-- **Nodepad** (external research): Proved spatial research works—auto-classification, inferred connections, synthesis emergence—but we never integrated it.
-
-## Core Insight
-
-Content fitting is a **measurement problem**. Enrichment is a **rendering problem**. Both need:
-1. **Deterministic text layout** without DOM reflow (Pretext)
-2. **Adaptive card sizing** that grows/shrinks with content
-3. **Bidirectional value flow** between cards and the KVE
-4. **Three canonical views** for different cognitive modes
-
-## Architecture
-
-### New Module: `x0-enchanted-blocks`
-
-Location: `LEAP/design-system/src/x0-enchanted-blocks/`
-
-Exports:
-- `EnchantedBlock` — adaptive card component
-- `EnchantedCanvas` — spatial canvas with three view modes
-- `useBlockEnrichment` — KVE bidirectional hook
-- `BlockClassifier` — auto-type detection (14 types from nodepad)
-- `SynthesisEngine` — emergent bridging sentences
-
-### 1. Adaptive Block Sizing (Pretext Integration)
-
-```typescript
-// block-layout.ts — DOM-free measurement
-import { prepare, layout } from '@chenglou/pretext';
-
-export interface BlockMetrics {
-  minWidth: number;      // shrink-wrap width
-  idealWidth: number;    // optimal reading width (~65ch)
-  height: number;        // measured at target width
-  lineCount: number;     // for virtualization
-  hasOverflow: boolean;  // content exceeds max constraints
-}
-
-export function measureBlock(
-  content: string,
-  font: string,
-  maxWidth: number,
-  options?: { whiteSpace?: 'normal' | 'pre-wrap'; wordBreak?: 'normal' | 'keep-all' }
-): BlockMetrics {
-  const prepared = prepare(content, font, options);
-  const { height, lineCount } = layout(prepared, maxWidth, 1.6 /* lineHeight */);
-  
-  // Shrink-wrap: find tightest width that doesn't increase line count
-  const minWidth = measureNaturalWidth(prepared);
-  
-  return { minWidth, idealWidth: Math.min(520, maxWidth), height, lineCount, hasOverflow: height > 400 };
-}
-```
-
-**Used by:**
-- `EnchantedBlock.svelte` — auto-height cards with overflow indicators
-- `VirtualCanvas.svelte` — accurate scrollbar/track sizing
-- `KanbanColumn.svelte` — column height pre-calculation
-
-### 2. The 14 Block Types (Nodepad Classification)
-
-```typescript
-export type BlockType =
-  | 'claim'        // Asserted truth
-  | 'question'     // Open inquiry
-  | 'idea'         // Proposed concept
-  | 'task'         // Action item (Ryu integration)
-  | 'entity'       // Named thing (person, org, concept)
-  | 'quote'        // External citation
-  | 'reference'    // Link/pointer
-  | 'definition'   // Term explanation
-  | 'opinion'      // Subjective stance
-  | 'reflection'   // Self-aware musing
-  | 'narrative'    // Story/time sequence
-  | 'comparison'   // Side-by-side analysis
-  | 'thesis'       // Synthesized position
-  | 'general';     // Unclassified
-
-export interface EnchantedBlockData {
-  id: string;
-  type: BlockType;
-  content: string;           // Raw user input
-  annotation?: string;       // AI enrichment (what the note doesn't say)
-  provenance: ProvenanceChain; // From Ryu's epistemic system
-  connections: BlockConnection[]; // Inferred from content + KVE
-  createdAt: number;
-  modifiedAt: number;
-  // Spatial state (canvas view)
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
-}
-```
-
-**Visual encoding:**
-- Color border by type (brass/copper palette)
-- Icon badge (top-left)
-- Annotation appears on hover/focus (subtle expansion)
-- Connections shown as faint lines (opacity ∝ relevance)
-
-### 3. Three Canonical Views
-
-```typescript
-export type CanvasView = 'tiling' | 'kanban' | 'graph';
-
-// Tiling: BSP spatial layout (ZoneTiler)
-// - Blocks auto-size to content
-// - Drag dividers to resize zones
-// - Blocks reflow within zones
-
-// Kanban: Columnar by type
-// - Columns: [Unsorted | Claim | Question | Idea | Task | ...]
-// - Drag between columns = reclassify
-// - Column height = sum of measured block heights
-
-// Graph: Force-directed (N3 Force Graph)
-// - Nodes = blocks (sized by content)
-// - Edges = inferred connections
-// - Synthesis nodes emerge at high centrality
-```
-
-### 4. Bidirectional KVE Enrichment
-
-```typescript
-// useBlockEnrichment.ts — Svelte 5 runes
-import { prepareWithSegments, walkLineRanges } from '@chenglou/pretext';
-
-export function useBlockEnrichment(blockId: string) {
-  const enrichment = $state<EnrichmentState>({ status: 'idle' });
-  
-  // Outbound: Block content → KVE
-  async function contributeToKVE(content: string, type: BlockType) {
-    enrichment.status = 'contributing';
-    await ryu_knowledge_ingest({ 
-      content, 
-      type, 
-      provenance: { source: 'atelier', blockId } 
-    });
-    enrichment.status = 'idle';
-  }
-  
-  // Inbound: KVE → Block annotation
-  async function fetchEnrichment(content: string) {
-    enrichment.status = 'enriching';
-    const result = await ryu_knowledge_epistemic_detail({ content });
-    
-    // Annotation = "something the note doesn't already say"
-    enrichment.annotation = result.insights
-      .filter(i => !content.toLowerCase().includes(i.text.toLowerCase()))
-      .map(i => i.text)
-      .join(' · ');
-    
-    // Inferred connections to other blocks
-    enrichment.connections = result.related.map(r => ({
-      targetId: r.blockId,
-      strength: r.relevance,
-      type: r.relationType // 'supports', 'contradicts', 'extends', 'similar'
-    }));
-    
-    enrichment.status = 'idle';
-  }
-  
-  return { enrichment, contributeToKVE, fetchEnrichment };
-}
-```
-
-### 5. Synthesis Emergence
-
-When enough blocks accumulate (threshold: 5+ with connection density > 0.3), the canvas offers a **synthesis**:
-
-```typescript
-export interface Synthesis {
-  id: string;
-  type: 'thesis';
-  content: string; // Single sentence bridging tensions
-  bridges: string[]; // Block IDs that this synthesizes
-  confidence: number;
-}
-
-// Triggered by: canvas block count change + connection density check
-// Source: ryu_think({ context: blockIds, mode: 'synthesize' })
-// Presentation: Floating pill at canvas center, dismissable
-// Solidify: Click → creates new 'thesis' block, auto-connected to bridged blocks
-```
-
-### 6. Component: EnchantedBlock
-
-```svelte
-<!-- EnchantedBlock.svelte -->
-<script lang="ts">
-  import { measureBlock } from './block-layout.js';
-  import { useBlockEnrichment } from './useBlockEnrichment.svelte.js';
-  
-  interface Props {
-    block: EnchantedBlockData;
-    editable?: boolean;
-    maxWidth?: number;
-    onChange?: (block: EnchantedBlockData) => void;
-    onTypeChange?: (type: BlockType) => void;
-  }
-  
-  let { block, editable = false, maxWidth = 400, onChange, onTypeChange }: Props = $props();
-  
-  // DOM-free measurement
-  const metrics = $derived(measureBlock(
-    block.content,
-    '14px "Sovereign Sans"',
-    maxWidth,
-    { whiteSpace: 'pre-wrap' }
-  ));
-  
-  // KVE enrichment
-  const { enrichment, contributeToKVE, fetchEnrichment } = useBlockEnrichment(block.id);
-  
-  // Debounced enrichment on content change
-  $effect(() => {
-    if (block.content.length > 10) {
-      const timer = setTimeout(() => fetchEnrichment(block.content), 500);
-      return () => clearTimeout(timer);
-    }
-  });
-  
-  let isEditing = $state(false);
-  let isExpanded = $state(false);
-</script>
-
-<div 
-  class="enchanted-block type-{block.type}"
-  style:width="{metrics.idealWidth}px"
-  style:min-height="{Math.min(metrics.height, 200)}px"
-  class:expanded={isExpanded}
-  class:has-annotation={!!enrichment.annotation}
->
-  <!-- Type badge (click to reclassify) -->
-  <button class="type-badge" onclick={() => onTypeChange?.(nextType(block.type))}>
-    <Icon name={typeIcons[block.type]} />
-    <span class="type-label">{block.type}</span>
-  </button>
-  
-  <!-- Content -->
-  {#if isEditing}
-    <div 
-      contenteditable="true"
-      class="block-content editable"
-      bind:innerText={block.content}
-      onblur={() => { isEditing = false; contributeToKVE(block.content, block.type); }}
-    />
-  {:else}
-    <div 
-      class="block-content"
-      ondblclick={() => editable && (isEditing = true)}
-    >
-      {@html renderMarkdown(block.content)}
-    </div>
-  {/if}
-  
-  <!-- Annotation (appears on hover/focus) -->
-  {#if enrichment.annotation}
-    <div class="annotation" class:visible={isExpanded}>
-      <Icon name="Sparkles" />
-      <span>{enrichment.annotation}</span>
-    </div>
-  {/if}
-  
-  <!-- Overflow indicator -->
-  {#if metrics.hasOverflow}
-    <button class="expand-hint" onclick={() => isExpanded = !isExpanded}>
-      {isExpanded ? 'Collapse' : 'Expand'} ({metrics.lineCount} lines)
-    </button>
-  {/if}
-  
-  <!-- Connection handles (graph view only) -->
-  <div class="connection-handles">
-    {#each enrichment.connections as conn}
-      <div class="connection-handle" style="--strength: {conn.strength}">
-        <Icon name={relationIcons[conn.type]} />
-      </div>
-    {/each}
-  </div>
-</div>
-
-<style>
-  .enchanted-block {
-    position: relative;
-    background: var(--color-bg-elevated, #2a2a2a);
-    border-left: 3px solid var(--type-color, #b87333);
-    border-radius: var(--radius-md, 8px);
-    padding: var(--space-3, 12px);
-    transition: all 0.2s ease;
-  }
-  
-  .type-claim { --type-color: #d4943a; }
-  .type-question { --type-color: #6b8ce6; }
-  .type-idea { --type-color: #7cb97a; }
-  .type-task { --type-color: #b87333; }
-  /* ... etc for all 14 types */
-  
-  .annotation {
-    opacity: 0;
-    max-height: 0;
-    overflow: hidden;
-    transition: all 0.3s ease;
-    font-size: var(--text-xs, 11px);
-    color: var(--color-text-muted, #a09880);
-    font-style: italic;
-  }
-  
-  .enchanted-block:hover .annotation,
-  .annotation.visible {
-    opacity: 1;
-    max-height: 100px;
-    margin-top: var(--space-2, 8px);
-  }
-  
-  .expanded {
-    max-height: none;
-  }
-</style>
-```
-
-## Integration Points
-
-### Ryu Tasks
-
-Current: Task list with truncated descriptions.
-
-With Enchanted Blocks:
-- Tasks become `type: 'task'` blocks
-- Full descriptions visible via measured height
-- Epistemic assay results shown as annotations
-- Task connections = dependencies (inferred from content)
-
-### Atelier Notes
-
-Current: Static markdown notes.
-
-With Enchanted Blocks:
-- Notes auto-classify into 14 types
-- KVE enrichment appears as annotations
-- Bidirectional: notes contribute to KVE, KVE enriches notes
-- Three views: tiling (BSP), kanban (by type), graph (connections)
-
-### BlockWriter
-
-Current: Visual block-based writing with BSP zones.
-
-With Enchanted Blocks:
-- Each writing block is an EnchantedBlock
-- Content measurement prevents overflow
-- Synthesis emerges from connected blocks
-- Export to thesis/node with full provenance
-
-## Implementation Roadmap
-
-### Phase 1: Foundation (Week 1)
-- [ ] Add `@chenglou/pretext` dependency to design-system
-- [ ] Create `block-layout.ts` with measurement primitives
-- [ ] Create `EnchantedBlock.svelte` with auto-sizing
-
-### Phase 2: Classification (Week 2)
-- [ ] Implement 14-type classifier (local regex + LLM fallback)
-- [ ] Type badge UI with click-to-reclassify
-- [ ] Color palette per type (brass/copper variants)
-
-### Phase 3: Enrichment (Week 3)
-- [ ] `useBlockEnrichment` hook with KVE integration
-- [ ] Annotation display (hover/focus expansion)
-- [ ] Connection inference from `ryu_knowledge_epistemic_detail`
-
-### Phase 4: Canvas (Week 4)
-- [ ] `EnchantedCanvas.svelte` with three view modes
-- [ ] Tiling: integrate with existing ZoneTiler
-- [ ] Kanban: columnar layout with drag-to-reclassify
-- [ ] Graph: integrate with N3 Force Graph
-
-### Phase 5: Synthesis (Week 5)
-- [ ] Synthesis engine (density detection + `ryu_think`)
-- [ ] Floating thesis pill UI
-- [ ] Solidify flow (thesis block creation)
-
-## File Structure
-
-```
-src/x0-enchanted-blocks/
-├── index.ts                          # Public exports
-├── ENCHANTED_BLOCKS_SPEC.md          # This document
-├── 
-├── core/
-│   ├── block-layout.ts               # Pretext measurement
-│   ├── block-types.ts                # 14 types + icons
-│   ├── classifier.ts                 # Auto-type detection
-│   └── synthesis.ts                  # Emergence detection
-│
-├── components/
-│   ├── EnchantedBlock.svelte         # Adaptive card
-│   ├── EnchantedCanvas.svelte        # Three-view canvas
-│   ├── TypeBadge.svelte              # Clickable type indicator
-│   ├── Annotation.svelte             # Enrichment display
-│   └── ConnectionLine.svelte         # SVG connection
-│
-├── hooks/
-│   └── useBlockEnrichment.svelte.ts  # KVE bidirectional
-│
-└── views/
-    ├── TilingView.svelte             # BSP spatial (ZoneTiler)
-    ├── KanbanView.svelte             # Columnar by type
-    └── GraphView.svelte              # Force-directed (N3)
-```
-
-## Dependencies
-
-```json
-{
-  "dependencies": {
-    "@chenglou/pretext": "^1.0.0"
-  },
-  "peerDependencies": {
-    "svelte": "^5.0.0"
-  }
-}
-```
-
-## Success Metrics
-
-1. **No overflow**: 100% of blocks display full content without truncation
-2. **Enrichment coverage**: 80%+ of blocks have KVE annotations within 2s of edit
-3. **Synthesis quality**: User accepts 50%+ of suggested thesis statements
-4. **View switching**: <100ms to switch between tiling/kanban/graph
-5. **Measurement speed**: <16ms for blocks up to 1000 characters
-
-## KVE Integration Commands
-
-Leverages existing Ryu commands:
-- `ryu_knowledge_ingest` — outbound contribution
-- `ryu_knowledge_epistemic_detail` — inbound enrichment
-- `ryu_think` — synthesis generation
-- `ryu_knowledge_provenance_chain` — provenance display
-
-## Open Questions
-
-1. Should synthesis be automatic or user-triggered?
-2. How to handle very long content (>10k chars) in blocks?
-3. Should connections be editable or purely inferred?
-4. Export format: `.nodepad` JSON, `.md`, or KOS-native?
-
----
-
-*Spec version: 2026-04-09*
-*Status: Draft for review*

package/src/x0-enchanted-blocks/core/block-layout.ts

@@ -1,211 +0,0 @@
-// Block Layout Engine — DOM-free text measurement using Pretext
-// Provides accurate sizing for adaptive block rendering
-
-import { prepareWithSegments, layout, measureNaturalWidth as pretextMeasureNatural } from '@chenglou/pretext';
-
-/** Layout options for text measurement */
-export interface LayoutOptions {
-  /** White space handling: 'normal' (collapse) or 'pre-wrap' (preserve) */
-  whiteSpace?: 'normal' | 'pre-wrap';
-  /** Word breaking: 'normal' (break at word boundaries) or 'keep-all' (CJK/Hangul) */
-  wordBreak?: 'normal' | 'keep-all';
-}
-
-/** Metrics returned from block measurement */
-export interface BlockMetrics {
-  /** Minimum width before text wraps to additional lines (shrink-wrap) */
-  minWidth: number;
-  /** Optimal reading width (~65 characters) */
-  idealWidth: number;
-  /** Total height at the measured width */
-  height: number;
-  /** Number of lines at the measured width */
-  lineCount: number;
-  /** True if content exceeds reasonable display limits */
-  hasOverflow: boolean;
-  /** The font string used for measurement */
-  font: string;
-}
-
-/** Default font configuration matching KOS design system */
-export const DEFAULT_FONT = '14px "Sovereign Sans", system-ui, -apple-system, sans-serif';
-
-/** Default monospace font for code/preformatted content */
-export const DEFAULT_MONO_FONT = '13px "Sovereign Mono", "SF Mono", Monaco, "Cascadia Code", monospace';
-
-/** Ideal reading width in pixels (~65ch at 14px) */
-export const IDEAL_READING_WIDTH = 520;
-
-/** Maximum reasonable block height before overflow indicator */
-export const MAX_BLOCK_HEIGHT = 400;
-
-/** Maximum characters before overflow detection */
-export const MAX_CONTENT_LENGTH = 5000;
-
-/**
- * Measure block content using Pretext's DOM-free layout engine.
- * 
- * This function uses canvas-based text measurement for accurate sizing
- * without triggering DOM layout/reflow cycles.
- * 
- * @param content - The text content to measure
- * @param font - Font specification string (defaults to DEFAULT_FONT)
- * @param maxWidth - Maximum container width constraint
- * @param options - Layout options (whiteSpace, wordBreak)
- * @param lineHeight - Line height multiplier (default: 1.6)
- * @returns BlockMetrics with sizing information
- * 
- * @example
- * ```typescript
- * const metrics = measureBlock(
- *   'Task: Implement authentication system with OAuth2 support',
- *   '14px Inter',
- *   400,
- *   { whiteSpace: 'normal' }
- * );
- * // metrics.height → precise pixel height
- * // metrics.lineCount → number of wrapped lines
- * ```
- */
-export function measureBlock(
-  content: string,
-  font: string = DEFAULT_FONT,
-  maxWidth: number = IDEAL_READING_WIDTH,
-  options: LayoutOptions = {},
-  lineHeight: number = 1.6
-): BlockMetrics {
-  // SSR Safety: Pretext requires DOM/Canvas. Return safe defaults if run on server.
-  if (typeof window === 'undefined') {
-    return {
-      minWidth: 0,
-      idealWidth: Math.min(IDEAL_READING_WIDTH, maxWidth),
-      height: lineHeight * 14,
-      lineCount: 1,
-      hasOverflow: false,
-      font,
-    };
-  }
-
-  // Handle empty content
-  if (!content || content.length === 0) {
-    return {
-      minWidth: 0,
-      idealWidth: Math.min(IDEAL_READING_WIDTH, maxWidth),
-      height: lineHeight * 14, // One line height
-      lineCount: 1,
-      hasOverflow: false,
-      font,
-    };
-  }
-
-  // Truncate extremely long content to prevent performance issues
-  const truncatedContent = content.length > MAX_CONTENT_LENGTH 
-    ? content.slice(0, MAX_CONTENT_LENGTH) + '…'
-    : content;
-
-  // Prepare text for measurement (one-time work)
-  const prepared = prepareWithSegments(truncatedContent, font, {
-    whiteSpace: options.whiteSpace ?? 'normal',
-    wordBreak: options.wordBreak ?? 'normal',
-  });
-
-  // Measure at the target width
-  const { height, lineCount } = layout(prepared, maxWidth, lineHeight);
-
-  // Calculate shrink-wrap width (tightest fit)
-  const minWidth = pretextMeasureNatural(prepared);
-
-  // Determine ideal width (between min and max, capped at reading width)
-  const idealWidth = Math.min(
-    Math.max(minWidth, Math.min(IDEAL_READING_WIDTH, maxWidth)),
-    maxWidth
-  );
-
-  // Detect overflow conditions
-  const hasOverflow = height > MAX_BLOCK_HEIGHT || content.length > MAX_CONTENT_LENGTH;
-
-  return {
-    minWidth,
-    idealWidth,
-    height,
-    lineCount,
-    hasOverflow,
-    font,
-  };
-}
-
-/**
- * Quick measurement for content previews (truncated at first overflow).
- * Returns faster results for long content by sampling first N characters.
- */
-export function measureBlockPreview(
-  content: string,
-  font: string = DEFAULT_FONT,
-  maxWidth: number = IDEAL_READING_WIDTH,
-  maxLines: number = 10
-): BlockMetrics {
-  const previewLength = 1000; // Sample size for preview
-  const previewContent = content.length > previewLength
-    ? content.slice(0, previewLength) + '…'
-    : content;
-
-  const metrics = measureBlock(previewContent, font, maxWidth);
-  
-  // Cap line count for preview
-  if (metrics.lineCount > maxLines) {
-    const lineHeight = 1.6 * 14; // approximate
-    return {
-      ...metrics,
-      lineCount: maxLines,
-      height: maxLines * lineHeight,
-      hasOverflow: true,
-    };
-  }
-
-  return { ...metrics, hasOverflow: content.length > previewLength };
-}
-
-/**
- * Measure multiple blocks efficiently with shared font preparation.
- * Useful for virtualized lists where font is constant.
- */
-export function measureBlocksBatch(
-  contents: string[],
-  font: string = DEFAULT_FONT,
-  maxWidth: number = IDEAL_READING_WIDTH
-): BlockMetrics[] {
-  return contents.map(content => measureBlock(content, font, maxWidth));
-}
-
-/**
- * Calculate total canvas height for a collection of blocks.
- * Includes spacing between blocks.
- */
-export function calculateCanvasHeight(
-  metrics: BlockMetrics[],
-  spacing: number = 16,
-  padding: number = 24
-): number {
-  const contentHeight = metrics.reduce((sum, m) => sum + m.height, 0);
-  const spacingHeight = Math.max(0, metrics.length - 1) * spacing;
-  return padding * 2 + contentHeight + spacingHeight;
-}
-
-/**
- * Determine optimal column width for kanban-style layouts.
- * Balances content width against container constraints.
- */
-export function calculateOptimalColumnWidth(
-  allMetrics: BlockMetrics[],
-  containerWidth: number,
-  columnCount: number,
-  minColumnWidth: number = 280
-): number {
-  const maxContentWidth = Math.max(...allMetrics.map(m => m.minWidth));
-  const availableWidth = (containerWidth - (columnCount - 1) * 16) / columnCount;
-  
-  return Math.max(
-    minColumnWidth,
-    Math.min(maxContentWidth + 48, availableWidth) // +48 for padding
-  );
-}