SOVEREIGN_NOTEBOOK_UI_SPEC.md

# SOVEREIGN NOTEBOOK UI & ANIMATION SPEC

**Frontend/UX Engineer Specification**  
**Version**: 1.0  
**Status**: DESIGN COMPLETE  
**Date**: 2026-07-27  
**Authority**: Jessica (jessi@snapkitty.com)

---

## Executive Summary

The Sovereign Notebook is a cryptographically-sealed, reactive notebook interface that bridges:
- **Cell Editing**: Code, Markdown, Math (EmojiCode, HolyC, Python, JavaScript, Ada)
- **Execution Flow**: Isomorphic transformation pipeline (M1→M2→M3→Runtime→M5→M6)
- **Receipt Ledger**: WORM-sealed execution records with Ed25519 signatures
- **Dependency Graph**: Visual data flow between cells
- **Responsive Animations**: Unicode glyphs, hash chains, cryptographic locks

**Design Philosophy**: Minimal framework, vanilla Web Components, Canvas/SVG for animation, reactive state binding. Dark mode primary with light mode support.

---

## 1. LAYOUT & PANEL ARCHITECTURE

### 1.1 Desktop Layout (1440px+)

```
┌──────────────────────────────────────────────────────────────────────┐
│  HEADER: Notebook Title | Run | Interrupt | Save | Export | Verify  │
├──────────────────────────────────────────────────────────────────────┤
│ TOOLBAR: [⚡ EmojiCode] [Python] [Ada] [Math] | 🔍 Search           │
├──────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  MAIN CONTENT AREA (3 columns)                                        │
│                                                                        │
│  ┌─ LEFT SIDEBAR ────┬─ CENTER EDITOR ────────┬─ RIGHT PANEL ──────┐ │
│  │                   │                        │                    │ │
│  │ • Metadata        │  Cell 1 [CODE]        │ • WORM Ledger     │ │
│  │   - Cell count    │  ┌────────────────┐   │   ┌─────────────┐ │ │
│  │   - Depends on    │  │ ⚡ fn:1618     │   │   │ Receipt ID  │ │ │
│  │   - Trust level   │  └────────────────┘   │   │ ─────────── │ │ │
│  │                   │  ▶️ [Output]          │   │ Hash: 0xab  │ │ │
│  │ • Dep Graph       │                       │   │ Sig: Ed...  │ │ │
│  │   └─ Visual       │  Cell 2 [MARKDOWN]   │   │ Time: 10:30 │ │ │
│  │     grid          │  ┌────────────────┐   │   └─────────────┘ │ │
│  │                   │  │ # Results      │   │                    │ │
│  │ • Trust Policies  │  └────────────────┘   │ • Dependency Graph │ │
│  │   - Execute as    │                       │   (small visual)   │ │
│  │   - Verify with   │  Cell 3 [MATH]       │                    │ │
│  │   - Seal with     │  ┌────────────────┐   │ • Cell Cache      │ │
│  │                   │  │ ∑ λ(x)dx      │   │   - Hit ratio     │ │
│  │                   │  └────────────────┘   │   - Memory used   │ │
│  │                   │  ▶️ [Output]          │                    │ │
│  │                   │                       │                    │ │
│  └───────────────────┴────────────────────────┴────────────────────┘ │
│                                                                        │
├──────────────────────────────────────────────────────────────────────┤
│  FOOTER: Execution time | Cell count | Status | Connected to runtime│
└──────────────────────────────────────────────────────────────────────┘
```

### 1.2 Mobile Layout (< 768px)

```
┌─────────────────────────────┐
│ HEADER (compact)            │
├─────────────────────────────┤
│ TAB BAR: [Editor] [Ledger]  │
├─────────────────────────────┤
│                             │
│ MAIN CONTENT (single col)  │
│                             │
│ • Cell 1 (full width)       │
│ • Cell 2 (full width)       │
│                             │
├─────────────────────────────┤
│ BOTTOM SHEET: Metadata      │
└─────────────────────────────┘
```

---

## 2. UI COMPONENTS

### 2.1 Web Component Definitions

#### `<notebook-container>`

**Purpose**: Root container for entire notebook UI  
**Attributes**:
- `notebook-id` (string): UUID of notebook
- `mode` (enum): 'edit' | 'view' | 'locked'
- `theme` (enum): 'dark' | 'light'

**State**:
```typescript
interface NotebookContainerState {
  notebookId: string;
  title: string;
  cells: Cell[];
  executionQueue: ExecutionTask[];
  receipts: ReceiptRecord[];
  dependencyGraph: CellDependency[];
  metadata: {
    createdAt: number;
    modifiedAt: number;
    author: string;
    trustLevel: 'low' | 'medium' | 'high' | 'sovereign';
  };
}
```

**Events**:
- `cell:created` → new cell added
- `cell:executed` → cell completed execution
- `receipt:sealed` → receipt added to WORM
- `graph:updated` → dependency graph changed

---

#### `<notebook-cell>` (Base Class)

**Purpose**: Editable/viewable cell with multiple types  
**Attributes**:
- `cell-id` (string): UUID
- `cell-type` (enum): 'code' | 'markdown' | 'math'
- `language` (enum): 'emoji' | 'python' | 'holyc' | 'javascript' | 'ada'
- `readonly` (boolean): read-only mode

**Subcomponents**:
- `<notebook-cell-editor>` — editable textarea with syntax highlighting
- `<notebook-cell-output>` — rendered output display
- `<notebook-cell-controls>` — run/delete/move buttons

**State**:
```typescript
interface Cell {
  id: string;
  type: 'code' | 'markdown' | 'math';
  language: Language;
  source: string;
  output: CellOutput | null;
  executionTime: number; // ms
  dependsOn: string[]; // cell IDs
  metadata: {
    createdAt: number;
    executedAt: number | null;
    executedBy: string;
    proof: ProofStatus;
  };
  sealStatus: 'pending' | 'sealed' | 'verified' | 'revoked';
}

interface CellOutput {
  type: 'text' | 'table' | 'graph' | 'math' | 'error';
  data: any;
  hash: string; // blake3
  receiptId: string | null;
}
```

---

#### `<cell-editor>`

**Purpose**: Monaco-like syntax highlighting for code cells  
**Attributes**:
- `language` (enum): programming language
- `theme` (enum): 'dark' | 'light'

**Features**:
- Syntax highlighting via Highlight.js
- Line numbers
- Code folding
- Inline error markers
- Autocomplete hints (from semantic registry)
- Undo/redo

**Keyboard Bindings**:
- `Shift+Enter` → run this cell
- `Ctrl+Enter` → run and select next
- `Ctrl+/` → toggle comment
- `Tab` → indent (4 spaces)
- `Escape` → exit edit mode

---

#### `<cell-output>`

**Purpose**: Render cell execution results  
**Supported Types**:

```
TEXT OUTPUT
┌─────────────────────────────┐
│ Output: 42                  │
│ Type: integer               │
│ Hash: 0xabcd...             │
└─────────────────────────────┘

TABLE OUTPUT
┌─────────────────────────────┐
│ col1  | col2  | col3        │
│ ─────────────────────────   │
│ val1  | val2  | val3        │
│ val4  | val5  | val6        │
└─────────────────────────────┘

GRAPH OUTPUT
┌─────────────────────────────┐
│  (rendered via D3/SVG)      │
│  • Scatter plot             │
│  • Bar chart                │
│  • Network graph            │
└─────────────────────────────┘

MATH OUTPUT
┌─────────────────────────────┐
│  ∑ λ(x)dx = 1618 (sealed)  │
│  Verified by: Lean4 ✓      │
└─────────────────────────────┘
```

**Renderers**:
- Text: plain or markdown-rendered
- Table: HTML table with sortable columns
- Graph: D3/Canvas visualization
- Math: MathJax/KaTeX rendering
- Error: syntax highlighted traceback

---

#### `<notebook-sidebar>`

**Purpose**: Left metadata and navigation panel  
**Sections**:

1. **Notebook Info**
   - Title (editable)
   - Cell count
   - Last modified
   - Total execution time

2. **Cell List** (scrollable)
   - Quick jump to cell
   - Execution status icon
   - Dependency count

3. **Dependency Graph** (miniature)
   - Small SVG visualization
   - Highlight current cell
   - Click to jump

4. **Trust Policies**
   - Execute as: [agent name]
   - Verify with: [verifier]
   - Seal with: [key fingerprint]

---

#### `<worm-ledger>`

**Purpose**: Right panel showing receipt chain  
**Display**:

```
WORM LEDGER VIEWER
─────────────────────────────

 Receipt #1          [▼]
 ├─ ID: 0xfab1...
 ├─ Event: Cell 2 execute
 ├─ Agent: builder
 ├─ Status: ✓ sealed
 ├─ Time: 10:30:45
 ├─ Hash: 0x7a8b...
 └─ Sig: Ed25519(0x1234...)

 Receipt #2          [▼]
 ├─ ID: 0xfab2...
 ├─ Event: Cell 3 verify
 ├─ ...

 [Load More ↓]
```

**Features**:
- Expandable receipt details
- Verify signature button
- Export receipt as JSON
- Copy hash to clipboard
- Filter by status/agent

---

#### `<execution-trace>`

**Purpose**: Animation overlay showing live execution flow  
**Display**:

```
EXECUTION TRACE (Canvas overlay, semi-transparent)
─────────────────────────────────────────────────────

Cell 1 ──→ [λ λ λ] ──→ Cell 2 ──→ [✓] ──→ OUTPUT
 Running     (0.2s)      Queued          Ready

Legend:
 ──→ data flow (animated arrow)
 λ   unicode glyph (flowing)
 ✓   completion marker
```

---

#### `<cryptographic-stamp>`

**Purpose**: Animated WORM seal effect  
**Visual**:

```
 🔐 SEALED
  ╱─────╲
 │ blake3 │  (rotating, glowing)
  ╲─────╱
   worm↻
```

**Animation**:
- Rotating background every 2s
- Blake3 hash scrolls
- Glow effect pulses
- Ed25519 signature in tooltip

---

### 2.2 CSS Architecture

#### File Structure
```
styles/
├── global.css              # resets, tokens, dark/light theme
├── components/
│  ├── notebook-cell.css
│  ├── cell-editor.css
│  ├── cell-output.css
│  ├── notebook-sidebar.css
│  ├── worm-ledger.css
│  └── execution-trace.css
├── animations.css          # keyframe definitions
├── layout.css              # grid, flexbox layouts
└── theme/
   ├── dark.css
   └── light.css
```

#### Design Tokens (CSS Variables)

```css
/* Color Palette */
--color-bg-primary: #070b1e;      /* dark navy */
--color-bg-secondary: #0f0f2e;    /* lighter navy */
--color-text-primary: #eef9ff;    /* light cyan */
--color-text-secondary: #a0a7d0;  /* muted blue */
--color-accent-cyan: #7ef9ff;     /* bright cyan */
--color-accent-magenta: #ff79dc;  /* magenta */
--color-accent-gold: #ffe98a;     /* gold */
--color-error: #ff4fd8;           /* bright magenta */
--color-success: #00d9a3;         /* teal */
--color-warning: #ffd86b;         /* orange */

/* Typography */
--font-mono: 'Fira Code', 'Courier New', monospace;
--font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-size-code: 14px;
--font-size-label: 12px;
--font-size-body: 16px;
--line-height-code: 1.6;

/* Spacing */
--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 16px;
--spacing-lg: 24px;
--spacing-xl: 32px;

/* Borders & Shadows */
--border-radius-sm: 4px;
--border-radius-md: 8px;
--border-radius-lg: 16px;
--shadow-sm: 0 2px 4px rgba(0,0,0,0.3);
--shadow-md: 0 8px 24px rgba(0,0,0,0.5);
--shadow-glow: 0 0 20px rgba(126,249,255,0.4);

/* Transitions */
--transition-fast: 150ms ease-out;
--transition-normal: 300ms ease-out;
--transition-slow: 600ms ease-out;
```

#### Component Styles (Example: Cell Editor)

```css
notebook-cell-editor {
  display: block;
  position: relative;
  background: var(--color-bg-secondary);
  border: 1px solid var(--color-accent-cyan);
  border-radius: var(--border-radius-md);
  overflow: hidden;
}

notebook-cell-editor .editor-wrapper {
  display: grid;
  grid-template-columns: auto 1fr;
  height: 200px;
  font-family: var(--font-mono);
  font-size: var(--font-size-code);
  line-height: var(--line-height-code);
}

notebook-cell-editor .line-numbers {
  background: var(--color-bg-primary);
  border-right: 1px solid var(--color-accent-cyan);
  padding: var(--spacing-sm);
  color: var(--color-text-secondary);
  user-select: none;
}

notebook-cell-editor .line-number {
  display: block;
  height: 1.6em;
  text-align: right;
  opacity: 0.5;
}

notebook-cell-editor textarea {
  background: transparent;
  color: var(--color-text-primary);
  border: none;
  outline: none;
  padding: var(--spacing-sm);
  font-family: inherit;
  font-size: inherit;
  resize: none;
  z-index: 2;
}

notebook-cell-editor .highlights {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  pointer-events: none;
  z-index: 1;
  overflow: hidden;
}

notebook-cell-editor .highlight-line {
  height: 1.6em;
  padding: var(--spacing-sm);
  font-family: var(--font-mono);
  white-space: pre;
  word-break: break-all;
}

/* Syntax highlighting */
.hljs-keyword { color: var(--color-accent-magenta); }
.hljs-string { color: var(--color-success); }
.hljs-number { color: var(--color-warning); }
.hljs-function { color: var(--color-accent-cyan); }
.hljs-comment { color: var(--color-text-secondary); opacity: 0.7; }

/* Focus state */
notebook-cell-editor:focus-within {
  box-shadow: 0 0 12px var(--color-accent-cyan);
  border-color: var(--color-accent-cyan);
}
```

---

## 3. ANIMATION ENGINE

### 3.1 Animation Categories

#### A. Execution Flow Animation

**Purpose**: Visualize data flowing between cells  
**Implementation**: Canvas + requestAnimationFrame

```javascript
class ExecutionFlowAnimator {
  constructor(canvas) {
    this.canvas = canvas;
    this.ctx = canvas.getContext('2d');
    this.particles = []; // flowing glyphs
    this.arrows = [];    // connection arrows
    this.isAnimating = false;
  }

  startExecution(fromCell, toCell) {
    // Start arrow from fromCell to toCell
    // Spawn unicode glyphs flowing along path
    // Duration: execution time + 0.5s decay
  }

  completeExecution(cellId) {
    // Show checkmark at cell
    // Fade out incoming arrows
    // Seal indicator appears
  }

  animate() {
    // Update particle positions
    // Render arrows and particles
    // Handle collisions/bunching
    if (this.isAnimating) requestAnimationFrame(() => this.animate());
  }
}
```

**Visual Details**:
- Arrow color: cyan to magenta gradient
- Unicode glyphs: λ, Ω, ∑, ⊕, φ, ∞ (50px size, semi-transparent)
- Speed: 200px/sec
- Trail effect: 0.3s fade tail

---

#### B. Dependency Graph Animation

**Purpose**: Show data dependencies between cells  
**Implementation**: D3.js force-directed graph or custom SVG

```
 Cell1 ─────┐
            ├─→ Cell3 ─→ Cell5
 Cell2 ─────┤             ↓
            └─→ Cell4 ────┘
```

**Features**:
- Nodes: circles labeled with cell ID
- Edges: directed arrows
- Hover: highlight path to/from cell
- Click: jump to cell
- Animation: smooth force simulation

**Code Example**:
```javascript
class DependencyGraphVisualizer {
  constructor(svgElement) {
    this.svg = d3.select(svgElement);
    this.nodes = [];
    this.links = [];
    this.simulation = null;
  }

  update(cells, dependencies) {
    // Convert cells and dependencies to nodes/links
    // Run force simulation
    // Bind data and render
    // Add hover/click handlers
  }

  highlightPath(cellId) {
    // Dim non-related nodes
    // Highlight nodes on dependency path
    // Animate edges along path
  }
}
```

---

#### C. Receipt Chain Animation

**Purpose**: Visualize hash chain and sealing  
**Implementation**: SVG + Canvas for effects

```
Hash1 ──→ [blake3] ──→ Hash2 ──→ [blake3] ──→ Hash3
  ↓                      ↓                      ↓
[Ed25519]            [Ed25519]             [Ed25519]
  ↓                      ↓                      ↓
Sig1                  Sig2                  Sig3 [SEALED ✓]
```

**Animation Sequence**:
1. New receipt appears (fade in)
2. Hash scrolls left-to-right (1.5s)
3. Blake3 badge spins (rotation 360°)
4. Ed25519 signature glows (pulse effect)
5. Sealed checkmark animates (scale up)

**Code Structure**:
```javascript
class ReceiptChainAnimator {
  constructor(containerElement) {
    this.container = containerElement;
    this.receipts = []; // Array of ReceiptRecord
  }

  addReceipt(receipt) {
    // Create receipt element
    // Animate fade-in + scale
    // Animate hash scroll
    // Animate signature glow
    // Add to receipts array
  }

  animateHash(hashElement, hashValue) {
    // Scroll hash characters left-to-right
    // Duration: 1.5s
    // Monospace font, cyan color
  }

  animateSignature(sigElement) {
    // Glow pulse effect
    // Duration: 2s, repeat
    // Color: gold to magenta
  }
}
```

---

#### D. Unicode Glyph Animation

**Purpose**: Flowing mathematical symbols through cells  
**Implementation**: Canvas particles

```javascript
class UnicodeGlyphAnimator {
  constructor(canvas) {
    this.canvas = canvas;
    this.ctx = canvas.getContext('2d');
    this.glyphs = ['λ', 'Ω', '∑', '⊕', 'φ', '∞', '↔', '⇄', '∷', '⊗'];
  }

  spawnGlyph(startCell, endCell, duration) {
    // Create glyph particle
    // Interpolate position from start to end over duration
    // Fade in/out at edges
    // Rotate glyph during flight
  }

  render() {
    // Clear canvas
    // For each active glyph:
    //   - Compute position
    //   - Rotate based on velocity
    //   - Draw with alpha
    //   - Remove if expired
  }
}
```

**Glyph Semantics**:
- λ: lambda (function)
- Ω: omega (loop)
- ∑: summation
- ⊕: XOR operation
- φ: golden ratio
- ∞: infinity
- ↔: bidirectional
- ⇄: reversible

---

#### E. Cryptographic Seal Animation

**Purpose**: Rotating WORM seal effect on sealed cells  
**Implementation**: Canvas 2D transforms

```javascript
class CryptoSealAnimator {
  constructor(canvas, receiptId) {
    this.canvas = canvas;
    this.receiptId = receiptId;
    this.rotation = 0;
  }

  animate() {
    this.ctx.save();
    
    // Draw rotating circle
    this.ctx.translate(centerX, centerY);
    this.ctx.rotate(this.rotation);
    this.ctx.strokeStyle = 'rgba(255,233,138,0.8)';
    this.ctx.lineWidth = 3;
    this.ctx.beginPath();
    this.ctx.arc(0, 0, 30, 0, Math.PI * 2);
    this.ctx.stroke();
    
    // Draw scrolling hash
    this.ctx.rotate(-this.rotation);
    this.ctx.font = '12px monospace';
    this.ctx.fillStyle = 'rgba(255,233,138,0.6)';
    this.ctx.textAlign = 'center';
    this.ctx.fillText(this.receiptId.slice(0, 8) + '...', 0, -45);
    
    // Draw glow effect
    this.ctx.shadowColor = 'rgba(255,233,138,0.4)';
    this.ctx.shadowBlur = 20;
    this.ctx.arc(0, 0, 35, 0, Math.PI * 2);
    this.ctx.stroke();
    
    this.ctx.restore();
    
    this.rotation += 0.05; // ~2s per rotation
    requestAnimationFrame(() => this.animate());
  }
}
```

**Visual Appearance**:
- Rotating gold circle
- Blake3 hash scrolls around perimeter
- Inner glow pulses
- Semi-transparent overlay on cell

---

### 3.2 Keyframe Definitions (CSS)

```css
@keyframes fadeInScale {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes glowPulse {
  0%, 100% {
    box-shadow: 0 0 10px var(--color-accent-cyan);
  }
  50% {
    box-shadow: 0 0 30px var(--color-accent-magenta);
  }
}

@keyframes scrollHash {
  from {
    transform: translateX(-100%);
  }
  to {
    transform: translateX(100%);
  }
}

@keyframes rotateSeal {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

@keyframes flowingGlyph {
  0% {
    opacity: 0;
    transform: translate(0, 0);
  }
  10% {
    opacity: 1;
  }
  90% {
    opacity: 1;
  }
  100% {
    opacity: 0;
    transform: translate(var(--distance), 0);
  }
}

@keyframes highlightBorder {
  0%, 100% {
    border-color: var(--color-accent-cyan);
  }
  50% {
    border-color: var(--color-accent-magenta);
  }
}
```

---

## 4. STATE MANAGEMENT

### 4.1 Reactive State Architecture

**Pattern**: Simple event emitter + reactive getters

```typescript
class NotebookStore {
  private cells: Map<string, Cell> = new Map();
  private receipts: ReceiptRecord[] = [];
  private listeners: Map<string, Set<Callback>> = new Map();
  
  // Observable properties (via Proxy)
  public state: {
    cells: Cell[];
    receipts: ReceiptRecord[];
    executionQueue: ExecutionTask[];
    selectedCellId: string | null;
  };

  subscribe(event: string, callback: Callback) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Set());
    }
    this.listeners.get(event)!.add(callback);
    return () => this.listeners.get(event)!.delete(callback);
  }

  emit(event: string, data?: any) {
    this.listeners.get(event)?.forEach(cb => cb(data));
  }

  // Mutations
  addCell(cell: Cell) {
    this.cells.set(cell.id, cell);
    this.emit('cell:created', cell);
  }

  updateCellOutput(cellId: string, output: CellOutput) {
    const cell = this.cells.get(cellId);
    if (cell) {
      cell.output = output;
      this.emit('cell:updated', { cellId, output });
    }
  }

  addReceipt(receipt: ReceiptRecord) {
    this.receipts.push(receipt);
    this.emit('receipt:sealed', receipt);
  }

  // Queries
  getCellDependencies(cellId: string): string[] {
    const cell = this.cells.get(cellId);
    return cell?.dependsOn || [];
  }

  getDependencyGraph(): CellDependency[] {
    return Array.from(this.cells.values()).flatMap(cell =>
      cell.dependsOn.map(depId => ({ from: depId, to: cell.id }))
    );
  }

  getExecutionOrder(): string[] {
    // Topological sort of dependency graph
    const visited = new Set<string>();
    const order: string[] = [];

    const visit = (id: string) => {
      if (visited.has(id)) return;
      visited.add(id);
      const cell = this.cells.get(id);
      cell?.dependsOn.forEach(depId => visit(depId));
      order.push(id);
    };

    this.cells.forEach((_, id) => visit(id));
    return order;
  }
}

// Global singleton
export const notebook = new NotebookStore();
```

### 4.2 Component State Binding

**Pattern**: Web Components with reactive properties

```typescript
class NotebookCell extends HTMLElement {
  private _state: Cell = null;
  private unsubscribe: (() => void)[] = [];

  connectedCallback() {
    // Subscribe to cell updates
    this.unsubscribe.push(
      notebook.subscribe('cell:updated', (data) => {
        if (data.cellId === this._state.id) {
          this.render();
        }
      })
    );

    // Initial render
    this.render();
  }

  disconnectedCallback() {
    // Clean up subscriptions
    this.unsubscribe.forEach(fn => fn());
  }

  set state(cell: Cell) {
    this._state = cell;
    this.render();
  }

  get state(): Cell {
    return this._state;
  }

  private render() {
    // Update DOM based on state
    this.innerHTML = `
      <div class="cell">
        <div class="cell-header">
          ${this._state.type === 'code' ? '⚡' : '📝'} ${this._state.id}
        </div>
        <div class="cell-editor">
          ${this._state.source}
        </div>
        ${this._state.output ? `
          <div class="cell-output">
            ${this.renderOutput(this._state.output)}
          </div>
        ` : ''}
      </div>
    `;
  }

  private renderOutput(output: CellOutput): string {
    switch (output.type) {
      case 'text': return `<pre>${escapeHtml(output.data)}</pre>`;
      case 'table': return this.renderTable(output.data);
      case 'math': return `<div class="math">${output.data}</div>`;
      case 'error': return `<div class="error">${escapeHtml(output.data)}</div>`;
      default: return '';
    }
  }
}

customElements.define('notebook-cell', NotebookCell);
```

---

## 5. INTEGRATION POINTS

### 5.1 Runtime Communication

**Channel**: WebSocket or HTTP POST

```typescript
interface ExecutionRequest {
  cellId: string;
  source: string;
  language: Language;
  dependencies: string[];
  executorAgent: 'builder' | 'oracle' | 'sentinel';
}

interface ExecutionResponse {
  cellId: string;
  status: 'running' | 'success' | 'error' | 'timeout';
  output: CellOutput;
  executionTime: number;
  receiptId: string;
  wormHash: string;
}

class RuntimeBridge {
  async executeCell(req: ExecutionRequest): Promise<ExecutionResponse> {
    const response = await fetch('/api/execute', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(req),
    });

    const data = await response.json() as ExecutionResponse;
    
    // Update notebook state
    notebook.updateCellOutput(req.cellId, data.output);
    notebook.addReceipt({
      id: data.receiptId,
      eventId: req.cellId,
      hash: data.wormHash,
      timestamp: Date.now(),
    });

    return data;
  }

  async verifyReceipt(receiptId: string): Promise<boolean> {
    const response = await fetch(`/api/verify/${receiptId}`);
    return response.ok;
  }
}

export const runtime = new RuntimeBridge();
```

### 5.2 Animation Event Hooks

```typescript
// Listen to execution events and trigger animations
notebook.subscribe('cell:executing', (cellId) => {
  executionAnimator.startCell(cellId);
});

notebook.subscribe('cell:updated', ({ cellId, output }) => {
  executionAnimator.completeCell(cellId);
  
  // Update dependent cells' incoming arrows
  const deps = notebook.getDependencyGraph();
  deps.filter(d => d.from === cellId).forEach(d => {
    executionAnimator.startArrow(cellId, d.to);
  });
});

notebook.subscribe('receipt:sealed', (receipt) => {
  receiptAnimator.addReceipt(receipt);
});
```

---

## 6. INTERACTION PATTERNS

### 6.1 Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Shift+Enter` | Run current cell |
| `Ctrl+Enter` | Run and advance |
| `Ctrl+S` | Save notebook |
| `Ctrl+Z` / `Ctrl+Shift+Z` | Undo / Redo |
| `Ctrl+/` | Toggle comment |
| `Ctrl+H` | Open find/replace |
| `Ctrl+L` | Focus ledger |
| `Escape` | Exit edit mode |
| `Cmd+Click` | Multi-select cells |
| `Alt+Up/Down` | Move cell |

### 6.2 Mouse Gestures

- **Drag cell**: Reorder in notebook
- **Hover receipt**: Show full hash in tooltip
- **Right-click cell**: Context menu (delete/clone/move/seal)
- **Hover edge in graph**: Highlight dependency path
- **Click node in graph**: Jump to cell

### 6.3 Touch Gestures (Mobile)

- **Tap cell**: Enter edit mode
- **Swipe left**: Reveal delete/options
- **Pinch**: Zoom dependency graph
- **Long-press**: Context menu

---

## 7. DARK MODE & LIGHT MODE

### 7.1 Theme Variables

**Dark Theme** (default):
```css
[data-theme="dark"] {
  --color-bg-primary: #070b1e;
  --color-bg-secondary: #0f0f2e;
  --color-text-primary: #eef9ff;
  --color-accent-cyan: #7ef9ff;
}
```

**Light Theme**:
```css
[data-theme="light"] {
  --color-bg-primary: #f8f9fa;
  --color-bg-secondary: #ffffff;
  --color-text-primary: #1a1a2e;
  --color-accent-cyan: #0066cc;
}
```

### 7.2 Theme Switching

```typescript
class ThemeManager {
  static set(theme: 'dark' | 'light') {
    document.documentElement.setAttribute('data-theme', theme);
    localStorage.setItem('theme', theme);
    
    // Notify all listeners
    window.dispatchEvent(new CustomEvent('theme-changed', { detail: theme }));
  }

  static get(): 'dark' | 'light' {
    return localStorage.getItem('theme') as any || 'dark';
  }

  static auto() {
    const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    this.set(isDark ? 'dark' : 'light');
  }
}
```

---

## 8. PERFORMANCE OPTIMIZATION

### 8.1 Virtualization

For notebooks with 100+ cells:
- Only render visible cells in viewport
- Use `IntersectionObserver` to detect visibility
- Keep execution trace canvas at fixed size

```typescript
class VirtualNotebook {
  constructor(container: HTMLElement) {
    this.container = container;
    this.visibleRange = { start: 0, end: 10 };
    this.cellHeight = 200;
    
    this.observer = new IntersectionObserver(
      (entries) => this.updateVisibleRange(entries),
      { rootMargin: '200px' }
    );
  }

  render(cells: Cell[]) {
    const startIdx = Math.max(0, Math.floor(this.container.scrollTop / this.cellHeight) - 2);
    const endIdx = Math.min(cells.length, startIdx + 12);
    
    this.container.innerHTML = cells
      .slice(startIdx, endIdx)
      .map(cell => `<notebook-cell cell-id="${cell.id}"></notebook-cell>`)
      .join('');
  }
}
```

### 8.2 Canvas Optimization

- Use `OffscreenCanvas` for animations
- Render only changed regions
- Batch DOM updates

```javascript
class OptimizedAnimationEngine {
  constructor() {
    this.offscreen = new OffscreenCanvas(1440, 900);
    this.ctx = this.offscreen.getContext('2d');
    this.mainCanvas = document.querySelector('canvas');
  }

  render() {
    // Clear only changed regions
    this.ctx.clearRect(0, 0, 1440, 900);
    
    // Render to offscreen
    this.drawParticles();
    this.drawArrows();
    
    // Transfer to main canvas
    const bitmap = this.offscreen.convertToImageBitmap();
    const ctxMain = this.mainCanvas.getContext('2d');
    ctxMain.drawImage(bitmap, 0, 0);
  }
}
```

---

## 9. ACCESSIBILITY

### 9.1 WCAG 2.1 AA Compliance

- **Semantic HTML**: Use proper heading hierarchy
- **Color Contrast**: All text ≥ 4.5:1 WCAG AA ratio
- **Keyboard Navigation**: All interactive elements keyboard-accessible
- **Screen Reader Support**: ARIA labels on animations, aria-live regions for status

### 9.2 ARIA Annotations

```html
<notebook-cell role="region" aria-label="Code cell 1" aria-live="polite">
  <div class="cell-header" aria-label="Cell 1: Execute status">
    ⚡ Cell 1
  </div>
  <cell-editor aria-label="Code editor"></cell-editor>
  <button aria-label="Run cell 1" aria-controls="cell-1-output">▶ Run</button>
  <cell-output id="cell-1-output" aria-live="assertive" aria-atomic="true"></cell-output>
</notebook-cell>
```

---

## 10. TESTING STRATEGY

### 10.1 Unit Tests (Vitest)

```typescript
// test/components/notebook-cell.test.ts
import { describe, it, expect } from 'vitest';
import { NotebookCell } from '../../src/components/notebook-cell';

describe('NotebookCell', () => {
  it('renders cell with code content', () => {
    const cell = document.createElement('notebook-cell');
    cell.state = {
      id: 'test-1',
      type: 'code',
      language: 'python',
      source: 'print("hello")',
      output: null,
      dependsOn: [],
      metadata: { createdAt: Date.now() },
    };
    
    expect(cell.innerHTML).toContain('print("hello")');
  });

  it('displays output when available', () => {
    const cell = document.createElement('notebook-cell');
    cell.state = {
      id: 'test-2',
      type: 'code',
      output: { type: 'text', data: 'hello' },
      // ... other props
    };
    
    expect(cell.innerHTML).toContain('hello');
  });
});
```

### 10.2 Integration Tests

```typescript
// test/integration/execution-flow.test.ts
import { notebook, runtime } from '../../src';

describe('Execution Flow', () => {
  it('executes cell and updates receipt ledger', async () => {
    const cell: Cell = {
      id: 'int-test-1',
      type: 'code',
      language: 'python',
      source: 'x = 42',
      output: null,
      dependsOn: [],
      metadata: { createdAt: Date.now() },
    };

    notebook.addCell(cell);
    const response = await runtime.executeCell({
      cellId: 'int-test-1',
      source: 'x = 42',
      language: 'python',
      dependencies: [],
      executorAgent: 'builder',
    });

    expect(response.status).toBe('success');
    expect(notebook.state.receipts.length).toBe(1);
  });
});
```

---

## 11. COMPONENT HIERARCHY

```
notebook-container
├── notebook-header
│   ├── notebook-title (editable)
│   ├── execution-controls (run/interrupt/save)
│   ├── export-menu
│   └── theme-switcher
├── notebook-toolbar
│   ├── language-selector
│   ├── cell-add-button
│   └── search-bar
├── notebook-layout (3-column grid)
│   ├── notebook-sidebar
│   │   ├── notebook-info
│   │   ├── cell-list (virtualized)
│   │   ├── dependency-graph-mini
│   │   └── trust-policies
│   ├── notebook-editor-area
│   │   ├── execution-trace-overlay (canvas)
│   │   └── notebook-cells (virtualized list)
│   │       ├── notebook-cell (repeated)
│   │       │   ├── cell-header
│   │       │   ├── cell-editor
│   │       │   ├── cell-controls
│   │       │   └── cell-output
│   │       └── cell-separator
│   └── worm-ledger
│       ├── ledger-header
│       ├── receipt-list (scrollable)
│       │   ├── receipt-item (repeated)
│       │   │   ├── receipt-header
│       │   │   ├── receipt-details (collapsible)
│       │   │   └── receipt-actions
│       │   └── load-more-button
│       └── ledger-filter
├── dependency-graph-viewer (modal, full-screen)
│   ├── graph-canvas
│   ├── graph-legend
│   └── graph-controls
└── notebook-footer
    ├── execution-stats
    ├── cell-count
    ├── runtime-status
    └── connection-indicator
```

---

## 12. DEVELOPMENT ROADMAP

### Phase 1: Foundation (Week 1-2)
- [ ] Web Component definitions (base classes)
- [ ] CSS architecture and design tokens
- [ ] Dark/light theme support
- [ ] Responsive layout (desktop + mobile)

### Phase 2: Core Components (Week 3-4)
- [ ] Cell editor with syntax highlighting
- [ ] Cell output display (text, table, error)
- [ ] Sidebar with metadata browser
- [ ] WORM ledger viewer

### Phase 3: Animation Engine (Week 5-6)
- [ ] Execution flow animation (Canvas)
- [ ] Dependency graph visualization (D3)
- [ ] Receipt chain animation
- [ ] Unicode glyph particles

### Phase 4: State & Integration (Week 7-8)
- [ ] Reactive state management
- [ ] Runtime communication bridge
- [ ] Keyboard/mouse interactions
- [ ] Error handling and recovery

### Phase 5: Polish & Testing (Week 9-10)
- [ ] Performance optimization (virtualization)
- [ ] Accessibility audit (WCAG 2.1 AA)
- [ ] Unit tests (80%+ coverage)
- [ ] Integration tests
- [ ] End-to-end tests

### Phase 6: Deployment (Week 11-12)
- [ ] Production build and optimization
- [ ] Performance monitoring
- [ ] Browser compatibility testing
- [ ] Documentation and examples

---

## 13. FILE STRUCTURE

```
frontend/
├── index.html                      # Entry point
├── styles/
│   ├── global.css
│   ├── variables.css              # Design tokens
│   ├── animations.css
│   ├── layout.css
│   ├── theme/
│   │   ├── dark.css
│   │   └── light.css
│   └── components/
│       ├── notebook-cell.css
│       ├── cell-editor.css
│       ├── cell-output.css
│       ├── notebook-sidebar.css
│       ├── worm-ledger.css
│       └── execution-trace.css
├── src/
│   ├── index.ts                   # App entry
│   ├── store/
│   │   ├── notebook.store.ts      # Reactive state
│   │   └── theme.store.ts
│   ├── components/
│   │   ├── notebook-container.ts
│   │   ├── notebook-cell.ts
│   │   ├── cell-editor.ts
│   │   ├── cell-output.ts
│   │   ├── notebook-sidebar.ts
│   │   ├── worm-ledger.ts
│   │   └── notebook-header.ts
│   ├── animation/
│   │   ├── execution-flow.ts
│   │   ├── dependency-graph.ts
│   │   ├── receipt-chain.ts
│   │   ├── unicode-glyphs.ts
│   │   └── crypto-seal.ts
│   ├── services/
│   │   ├── runtime-bridge.ts      # API client
│   │   ├── theme-manager.ts
│   │   └── keyboard-handler.ts
│   ├── types/
│   │   ├── cell.ts
│   │   ├── receipt.ts
│   │   └── execution.ts
│   └── utils/
│       ├── dom-utils.ts
│       ├── animation-utils.ts
│       └── format-utils.ts
├── test/
│   ├── components/
│   │   └── notebook-cell.test.ts
│   ├── animation/
│   │   └── execution-flow.test.ts
│   ├── integration/
│   │   └── execution-flow.test.ts
│   └── e2e/
│       └── notebook.spec.ts
├── vitest.config.ts
├── tsconfig.json
├── package.json
└── README.md
```

---

## 14. KEY DESIGN DECISIONS

| Decision | Rationale |
|----------|-----------|
| **Web Components** (not React/Vue) | Lightweight, framework-agnostic, WASM-ready |
| **Canvas animations** | Better performance than DOM for particle systems |
| **CSS Variables for theming** | Dynamic theme switching without JS overhead |
| **D3 for graphs** | Mature, battle-tested force-directed layout |
| **Event emitter pattern** | Simple, explicit, easy to debug |
| **Virtualization for large notebooks** | Handle 1000+ cells efficiently |
| **Dark mode primary** | Sovereign aesthetic, reduced eye strain |
| **WCAG 2.1 AA from start** | Accessibility is not an afterthought |
| **TypeScript throughout** | Type safety, better IDE support, self-documenting |
| **Monospace Unicode symbols** | Aesthetic + semantic meaning for glyphs |

---

## 15. SUCCESS METRICS

- **Performance**: Animation frame rate ≥ 60fps (Cell 6 animation engine)
- **Responsiveness**: Cell execution trace appears within 100ms
- **Accessibility**: 100% keyboard navigable, 0 WCAG AA violations
- **Code Quality**: ≥80% test coverage, <10 code smells
- **User Experience**: Task completion time ≤ 5 minutes for common workflows

---

## APPENDIX A: SVG Animation Examples

See: `/WORM.svg` and `rowm_worm_morphing_notebook.svg` for reference animations

### WORM.svg Features:
- Rotating dashed border frame
- Animated Unicode streams (bidirectional)
- Particle glyph markers
- Notebook container with grid background
- Sealed cryptographic stamp
- Matrix-like aesthetic

---

## APPENDIX B: Integration with Isomorphic Shift Layer

The UI bridges the notebook to the formal isomorphic shift system:

```
User Input (EmojiCode cell)
         ↓
    M1: SurfaceInstruction → CanonicalInstruction [UI renders this]
         ↓
    M2: CanonicalInstruction → LogicTerm [UI queries from store]
         ↓
    M3: AuthorizedLogicDecision → RuntimeCommand [Animation triggers]
         ↓
   EXECUTION [Receipt LED indicator shows "running"]
         ↓
    M5: ExecutionEvent → LogicEventFact [Animation completes]
         ↓
    M6: ExecutionEvent → ReceiptRecord [WORM ledger updates]
         ↓
User sees: Output + Receipt + Seal animation
```

The UI is **purely presentational** — all authority/verification/sealing happens in the backend Prolog + Rust layer.

---

**Document Finalized**: 2026-07-27 14:30 UTC  
**Next Review**: After Phase 1 completion