@stephen-netu/design-system 0.1.0

package/src/x0-enchanted-blocks/components/NodepadBlock.svelte

@@ -0,0 +1,262 @@
+<script lang="ts">
+  // NodepadBlock — Flat, inline-editing block inspired by Nodepad spatial notes
+  // Key differences from bad first attempt:
+  // - NO nested card containers (single flat element)
+  // - NO edit mode toggle (just click and type)
+  // - NO collapse button (content flows naturally)
+  // - Stable cursor (no $effect overwriting content while typing)
+  
+  import { measureBlock, type BlockMetrics, DEFAULT_FONT } from '../core/block-layout.js';
+  import { 
+    type BlockType, 
+    type EnchantedBlockData,
+    BLOCK_TYPE_COLORS,
+    BLOCK_TYPE_ICONS,
+    classifyBlockHeuristic,
+  } from '../core/block-types.js';
+  
+  interface Props {
+    block: EnchantedBlockData;
+    maxWidth?: number;
+    onChange?: (content: string) => void;
+    onTypeChange?: (type: BlockType) => void;
+  }
+  
+  let { 
+    block, 
+    maxWidth = 320,
+    onChange,
+    onTypeChange,
+  }: Props = $props();
+  
+  // ── Stable Local State ─────────────────────────────────────────────────────
+  // CRITICAL: Local content copy prevents parent re-renders from resetting cursor
+  let localContent = $state('');
+  let isFocused = $state(false);
+  let hasUnsavedChanges = $state(false);
+  let contentEl: HTMLDivElement | undefined = $state();
+  
+  // Initialize content on mount (once only)
+  $effect(() => {
+    if (contentEl && localContent === '') {
+      localContent = block.content;
+      contentEl.innerText = block.content;
+    }
+  });
+  
+  // ── Derived ────────────────────────────────────────────────────────────────
+  const metrics = $derived<BlockMetrics>(
+    measureBlock(localContent, DEFAULT_FONT, maxWidth, { whiteSpace: 'pre-wrap' })
+  );
+  
+  const suggestedType = $derived(
+    block.type === 'general' && localContent.length > 10
+      ? classifyBlockHeuristic(localContent)
+      : null
+  );
+  
+  const displayType = $derived(suggestedType?.type ?? block.type);
+  const typeColor = $derived(BLOCK_TYPE_COLORS[displayType]);
+  const typeIcon = $derived(BLOCK_TYPE_ICONS[displayType]);
+  
+  // ── Handlers ─────────────────────────────────────────────────────────────────
+  function handleInput() {
+    if (!contentEl) return;
+    localContent = contentEl.innerText;
+    hasUnsavedChanges = true;
+    // Auto-save on input (debounced by parent or just stream it)
+    onChange?.(localContent);
+  }
+  
+  function handleFocus() {
+    isFocused = true;
+  }
+  
+  function handleBlur() {
+    isFocused = false;
+    hasUnsavedChanges = false;
+  }
+  
+  function cycleType() {
+    const types: BlockType[] = ['claim', 'question', 'idea', 'task', 'reference', 'general'];
+    const currentIndex = types.indexOf(block.type);
+    const nextType = types[(currentIndex + 1) % types.length];
+    onTypeChange?.(nextType);
+  }
+  
+  function handleKeydown(e: KeyboardEvent) {
+    // Tab inserts spaces
+    if (e.key === 'Tab') {
+      e.preventDefault();
+      document.execCommand('insertText', false, '  ');
+    }
+  }
+</script>
+
+<div
+  class="nodepad-block"
+  style:--type-color={typeColor}
+  style:max-width="{maxWidth}px"
+  class:suggested={!!suggestedType && block.type === 'general'}
+>
+  <!-- Header: Type indicator + ID -->
+  <div class="block-header">
+    <button class="type-chip" onclick={cycleType} title="Click to change type">
+      <span class="type-icon">{typeIcon}</span>
+      <span class="type-name">{displayType}</span>
+    </button>
+    <span class="block-id">{block.id}</span>
+  </div>
+  
+  <!-- Content: Always editable (like Nodepad) -->
+  <!-- CRITICAL: No {block.content} binding here - we set innerText manually to prevent cursor reset -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+  <div
+    bind:this={contentEl}
+    class="block-content"
+    contenteditable="true"
+    role="textbox"
+    aria-multiline="true"
+    tabindex="0"
+    oninput={handleInput}
+    onfocus={handleFocus}
+    onblur={handleBlur}
+    onkeydown={handleKeydown}
+  ></div>
+  
+  <!-- Footer: Annotation if present -->
+  {#if block.annotation}
+    <div class="block-annotation">
+      <span class="annotation-dot">•</span>
+      {block.annotation}
+    </div>
+  {/if}
+  
+  <!-- Saving indicator -->
+  {#if hasUnsavedChanges}
+    <div class="save-indicator">•</div>
+  {/if}
+</div>
+
+<style>
+  .nodepad-block {
+    /* FLAT: No nested containers, no card styling - just the essentials */
+    position: relative;
+    padding: 12px 14px;
+    background: var(--color-bg-elevated, #252422);
+    border-left: 3px solid var(--type-color, #b87333);
+    border-radius: 0 6px 6px 0;
+    /* CRITICAL: Constant dimensions - no size change on focus/hover */
+    transition: box-shadow 0.15s ease, border-color 0.15s ease;
+    box-sizing: border-box;
+  }
+  
+  .nodepad-block:hover {
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  }
+  
+  .nodepad-block:focus-within {
+    /* Use outline instead of border change to avoid layout shift */
+    outline: 2px solid color-mix(in srgb, var(--type-color, #b87333) 50%, transparent);
+    outline-offset: 2px;
+  }
+  
+  .nodepad-block.suggested {
+    border-left-style: dashed;
+  }
+  
+  /* Header */
+  .block-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 8px;
+    gap: 8px;
+  }
+  
+  .type-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    padding: 2px 8px;
+    background: color-mix(in srgb, var(--type-color, #b87333) 15%, transparent);
+    border: 1px solid color-mix(in srgb, var(--type-color, #b87333) 25%, transparent);
+    border-radius: 4px;
+    font-size: 11px;
+    font-weight: 500;
+    color: var(--type-color, #b87333);
+    cursor: pointer;
+    transition: all 0.15s ease;
+    font-family: inherit;
+  }
+  
+  .type-chip:hover {
+    background: color-mix(in srgb, var(--type-color, #b87333) 25%, transparent);
+    border-color: color-mix(in srgb, var(--type-color, #b87333) 50%, transparent);
+  }
+  
+  .type-icon {
+    font-size: 10px;
+  }
+  
+  .type-name {
+    text-transform: capitalize;
+  }
+  
+  .block-id {
+    font-size: 11px;
+    color: var(--color-text-muted, #706858);
+    font-family: var(--font-mono, monospace);
+  }
+  
+  /* Content - The key: just a contenteditable div, no wrapper, no truncation */
+  .block-content {
+    font-size: 14px;
+    line-height: 1.6;
+    color: var(--color-text-primary, #e8e4dc);
+    white-space: pre-wrap;
+    word-break: break-word;
+    min-height: 1.6em;
+    outline: none;
+    caret-color: var(--type-color, #b87333);
+  }
+  
+  .block-content:empty::before {
+    content: 'Click to add content...';
+    color: var(--color-text-muted, #706858);
+    font-style: italic;
+    pointer-events: none;
+  }
+  
+  /* Annotation */
+  .block-annotation {
+    margin-top: 8px;
+    padding-top: 8px;
+    border-top: 1px solid var(--color-border, #333);
+    font-size: 12px;
+    color: var(--color-text-secondary, #a09880);
+    font-style: italic;
+  }
+  
+  .annotation-dot {
+    color: var(--type-color, #b87333);
+    margin-right: 4px;
+  }
+  
+  /* Save indicator (subtle dot when typing) */
+  .save-indicator {
+    position: absolute;
+    top: 6px;
+    right: 6px;
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: var(--type-color, #b87333);
+    animation: pulse 1.5s infinite;
+  }
+  
+  @keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.4; }
+  }
+</style>

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

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

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

@@ -0,0 +1,227 @@
+// Block Types — 14 spatial research classifications
+// Based on Nodepad's auto-classification system
+
+/** The 14 types of enchanted blocks for spatial research */
+export type BlockType =
+  | 'claim'        // Asserted truth or proposition
+  | 'question'     // Open inquiry or research question
+  | 'idea'         // Proposed concept or hypothesis
+  | 'task'         // Action item or todo (Ryu integration)
+  | 'entity'       // Named thing (person, organization, concept)
+  | 'quote'        // External citation or verbatim excerpt
+  | 'reference'    // Link, pointer, or citation
+  | 'definition'   // Term explanation or glossary entry
+  | 'opinion'      // Subjective stance or perspective
+  | 'reflection'   // Self-aware musing or metacognition
+  | 'narrative'    // Story, timeline, or sequential account
+  | 'comparison'   // Side-by-side analysis or contrast
+  | 'thesis'       // Synthesized position or argument
+  | 'general';     // Unclassified or mixed content
+
+/** All block types as an array for iteration */
+export const ALL_BLOCK_TYPES: BlockType[] = [
+  'claim',
+  'question',
+  'idea',
+  'task',
+  'entity',
+  'quote',
+  'reference',
+  'definition',
+  'opinion',
+  'reflection',
+  'narrative',
+  'comparison',
+  'thesis',
+  'general',
+];
+
+/** Human-readable labels for each block type */
+export const BLOCK_TYPE_LABELS: Record<BlockType, string> = {
+  claim: 'Claim',
+  question: 'Question',
+  idea: 'Idea',
+  task: 'Task',
+  entity: 'Entity',
+  quote: 'Quote',
+  reference: 'Reference',
+  definition: 'Definition',
+  opinion: 'Opinion',
+  reflection: 'Reflection',
+  narrative: 'Narrative',
+  comparison: 'Comparison',
+  thesis: 'Thesis',
+  general: 'Note',
+};
+
+/** Lucide icon names for each block type */
+export const BLOCK_TYPE_ICONS: Record<BlockType, string> = {
+  claim: 'CheckCircle',      // Asserted truth
+  question: 'HelpCircle',    // Inquiry
+  idea: 'Lightbulb',         // Concept
+  task: 'CheckSquare',       // Action item
+  entity: 'Box',             // Named thing
+  quote: 'Quote',            // Citation
+  reference: 'Link',         // Pointer
+  definition: 'BookOpen',    // Explanation
+  opinion: 'MessageCircle',  // Subjective view
+  reflection: 'Mirror',      // Self-aware
+  narrative: 'ScrollText',   // Story
+  comparison: 'Scale',       // Analysis
+  thesis: 'GraduationCap',   // Synthesized argument
+  general: 'StickyNote',     // Default
+};
+
+/** 
+ * CSS color tokens for each block type.
+ * Uses KOS brass/copper palette with semantic differentiation.
+ * Format: HSL values for --type-color CSS custom property.
+ */
+export const BLOCK_TYPE_COLORS: Record<BlockType, string> = {
+  // Warm/assertive types (brass/gold variants)
+  claim: 'hsl(30, 60%, 55%)',      // Brass
+  thesis: 'hsl(25, 70%, 50%)',     // Copper
+  task: 'hsl(35, 55%, 50%)',       // Bronze
+  
+  // Cool/inquisitive types (muted complementary)
+  question: 'hsl(210, 50%, 60%)',  // Steel blue
+  idea: 'hsl(160, 45%, 50%)',      // Sage
+  opinion: 'hsl(280, 40%, 55%)',   // Muted purple
+  
+  // Reference/external types (neutral)
+  quote: 'hsl(0, 0%, 70%)',        // Silver
+  reference: 'hsl(200, 30%, 60%)', // Slate
+  definition: 'hsl(180, 35%, 55%)', // Teal
+  
+  // Process/meta types (warm earth)
+  reflection: 'hsl(45, 50%, 55%)', // Amber
+  narrative: 'hsl(20, 45%, 50%)',  // Terracotta
+  comparison: 'hsl(40, 45%, 50%)', // Gold ochre
+  
+  // Structural types
+  entity: 'hsl(220, 40%, 55%)',   // Denim
+  general: 'hsl(30, 40%, 50%)',    // Default brass
+};
+
+/** Get the next type in sequence (for cycling via click) */
+export function nextBlockType(current: BlockType): BlockType {
+  const idx = ALL_BLOCK_TYPES.indexOf(current);
+  return ALL_BLOCK_TYPES[(idx + 1) % ALL_BLOCK_TYPES.length];
+}
+
+/** Get the previous type in sequence */
+export function prevBlockType(current: BlockType): BlockType {
+  const idx = ALL_BLOCK_TYPES.indexOf(current);
+  return ALL_BLOCK_TYPES[(idx - 1 + ALL_BLOCK_TYPES.length) % ALL_BLOCK_TYPES.length];
+}
+
+/** 
+ * Simple heuristic classifier based on content patterns.
+ * Returns confidence score 0-1 alongside type.
+ */
+export function classifyBlockHeuristic(content: string): { type: BlockType; confidence: number } {
+  const lower = content.toLowerCase().trim();
+  
+  // Question detection
+  if (lower.match(/^(what|why|how|when|where|who|is\s+it|are\s+they|can\s+we|should\s+we)\b/i) || 
+      lower.endsWith('?')) {
+    return { type: 'question', confidence: 0.9 };
+  }
+  
+  // Task detection
+  if (lower.match(/^(todo|task|action|implement|fix|add|remove|update|create|build)\b/i) ||
+      lower.match(/\[x\]|\[ \]|\[-\]/)) {
+    return { type: 'task', confidence: 0.85 };
+  }
+  
+  // Quote detection
+  if (lower.startsWith('"') && lower.includes('"') ||
+      lower.startsWith('"') && lower.endsWith('"') ||
+      lower.match(/^as\s+\w+\s+said/i)) {
+    return { type: 'quote', confidence: 0.8 };
+  }
+  
+  // Definition detection
+  if (lower.match(/\bis\s+(defined\s+as|a\s+type\s+of|the\s+process\s+of)\b/i) ||
+      lower.match(/^\w+:\s+\w+/)) {
+    return { type: 'definition', confidence: 0.75 };
+  }
+  
+  // Claim detection (assertive language)
+  if (lower.match(/\b(is|are|will|must|should|always|never|proves|shows|demonstrates)\b/i) &&
+      !lower.endsWith('?')) {
+    return { type: 'claim', confidence: 0.7 };
+  }
+  
+  // Idea detection
+  if (lower.match(/\b(idea|concept|proposal|suggest|consider|perhaps|maybe|could|might)\b/i)) {
+    return { type: 'idea', confidence: 0.65 };
+  }
+  
+  // Reference detection
+  if (lower.match(/^(see|cf\.|refer\s+to|check\s+out|read|http|www\.|github\.com)/i)) {
+    return { type: 'reference', confidence: 0.8 };
+  }
+  
+  // Narrative detection (time words)
+  if (lower.match(/\b(then|next|after|before|finally|eventually|once|when\s+we)\b/i)) {
+    return { type: 'narrative', confidence: 0.6 };
+  }
+  
+  // Comparison detection
+  if (lower.match(/\b(vs|versus|compared\s+to|unlike|similarly|both|either|or)\b/i)) {
+    return { type: 'comparison', confidence: 0.65 };
+  }
+  
+  // Reflection detection (self-aware)
+  if (lower.match(/\b(i\s+think|i\s+wonder|i\s+realized|reflecting|thinking\s+about)\b/i)) {
+    return { type: 'reflection', confidence: 0.7 };
+  }
+  
+  // Opinion detection
+  if (lower.match(/\b(i\s+believe|in\s+my\s+opinion|personally|i\s+feel|i\s+prefer)\b/i)) {
+    return { type: 'opinion', confidence: 0.75 };
+  }
+  
+  // Entity detection (proper nouns, capitalized)
+  if (lower.match(/^[A-Z][a-z]+\s+(is|was|are|refers\s+to)/)) {
+    return { type: 'entity', confidence: 0.6 };
+  }
+  
+  return { type: 'general', confidence: 0.5 };
+}
+
+/** Core data structure for an enchanted block */
+export interface EnchantedBlockData {
+  id: string;
+  type: BlockType;
+  content: string;
+  
+  /** AI-generated annotation: "what the note doesn't say" */
+  annotation?: string;
+  
+  /** Epistemic provenance from KVE */
+  provenance?: {
+    source: string;
+    createdAt: number;
+    modifiedAt: number;
+    confidence?: number;
+  };
+  
+  /** Inferred connections to other blocks */
+  connections?: {
+    targetId: string;
+    strength: number; // 0.0 - 1.0
+    type: 'supports' | 'contradicts' | 'extends' | 'similar' | 'related';
+  }[];
+  
+  /** Spatial position (for canvas views) */
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  
+  /** Timestamps */
+  createdAt: number;
+  modifiedAt: number;
+}