In-Browser Visualization

[flyingrobots]

Migrated from Method backlog

This issue was created from a legacy filesystem backlog card. GitHub Issues are now the live work tracker; repository docs remain Method evidence.

Source backlog: docs/method/backlog/up-next/PLATFORM_browser-visualization.md
Original lane: up-next
Original legend: PLATFORM

Original backlog card

In-Browser Visualization

Milestone: First Light | Priority: P1 | Repo: Echo

Historical note: This roadmap item predates the observation-first ABI v2
and the intent-shaped ABI v3 control-plane rewrite. It is retained as
planning archaeology, not as the current WASM API contract. The live public
boundary is documented in SPEC-0009 WASM ABI.

Historical First Light plan for a Canvas-based graph rewrite viewer. It
assumes an earlier step(...)-driven browser boundary that has since been
replaced.

T-4-2-1: Canvas graph renderer (static materialized reading)

User Story: As a user, I want to see the simulation's current graph-shaped reading rendered visually so that I can understand the entity structure at a glance.

Requirements:

• R1: Render nodes as circles and edges as directed lines on an HTML5 Canvas element.
• R2: Use a force-directed layout (simple spring-embedder, ~100 iterations on init) for automatic positioning.
• R3: Node labels show the TypeId short name. Edge labels show EdgeId type.
• R4: Pan and zoom via mouse drag / scroll wheel.
• R5: Accept graph-shaped reading data as a plain JS object (nodes array, edges array) produced by the WASM bridge drain_view_ops output.

Acceptance Criteria:

• AC1: Given a 20-node, 30-edge test fixture, the renderer draws all nodes and edges with no overlapping labels.
• AC2: Pan/zoom works with both mouse and trackpad gestures.
• AC3: Renderer handles an empty graph (0 nodes) without error.
• AC4: Rendering 500 nodes at 60fps (measured via requestAnimationFrame timing).

Definition of Done:

• Code reviewed and merged
• Tests pass (CI green)
• Documentation updated (if applicable)

Scope: Static graph rendering, layout, pan/zoom. Plain Canvas 2D, no WebGL.
Out of Scope: Animated transitions between ticks. Node selection/inspection panel. WebGL fallback.

Test Plan:

• Goldens: Screenshot snapshot test (Playwright) for a fixed 10-node graph fixture.
• Failures: Null/undefined graph data shows "No data" placeholder. Nodes with missing labels render as "(unknown)".
• Edges: Single-node graph. Graph with self-loops. Disconnected components.
• Fuzz/Stress: Render 2000-node random graph; frame time must stay below 32ms.

Blocked By: T-4-1-3
Blocking: T-4-2-2

Est. Hours: 6h
Expected Complexity: ~400 LoC (TypeScript/Canvas)

---

T-4-2-2: Live tick playback and rewrite animation

User Story: As a user, I want to step through ticks and see graph rewrites animate so that I can understand causal relationships between rules.

Requirements:

• R1: Play/Pause button drives the tick loop via bridge.step(1) per animation frame (or configurable tick rate).
• R2: "Step" button advances exactly one tick and re-renders.
• R3: Nodes/edges added in the current tick flash green; removed ones flash red and fade out over 300ms.
• R4: Current tick number and state_root hash displayed in a status bar.
• R5: ViewOps are drained after each tick and diffed against the previous frame to compute additions/removals.

Acceptance Criteria:

• AC1: Pressing "Step" once causes exactly one tick and the graph updates.
• AC2: Pressing "Play" advances ticks at the configured rate; "Pause" halts immediately.
• AC3: Added nodes are visually distinguishable from existing nodes for at least one render frame.
• AC4: Status bar shows tick number matching bridge.getHead().tick.

Definition of Done:

• Code reviewed and merged
• Tests pass (CI green)
• Documentation updated (if applicable)

Scope: Tick-driven re-rendering, add/remove animation hints, play/pause/step controls, status bar.
Out of Scope: Rewind/time-travel (TT2 track). Tick rate slider. Full rewrite trace visualization.

Test Plan:

• Goldens: Playwright test: click Step 3 times, assert status bar shows "Tick: 3".
• Failures: If WASM step returns error, show error toast and halt playback.
• Edges: Step when no pending rewrites (no-op tick, state_root unchanged). Rapid click on Step.
• Fuzz/Stress: Hold Play for 500 ticks; UI must remain responsive (no dropped frames beyond 5%).

Blocked By: T-4-2-1, T-4-1-2
Blocking: T-4-2-3

Est. Hours: 5h
Expected Complexity: ~300 LoC (TypeScript)

---

T-4-2-3: Node inspection panel

User Story: As a user, I want to click a node and see its properties, attachments, and connected edges so that I can debug simulation state.

Requirements:

• R1: Click a node in the Canvas to select it (highlighted ring).
• R2: Side panel displays: NodeId (hex truncated), TypeId name, attachment payload (if any, pretty-printed), list of inbound/outbound edges.
• R3: Click an edge in the panel to highlight it on the Canvas and navigate to the connected node.
• R4: Escape key or clicking empty space deselects.

Acceptance Criteria:

• AC1: Clicking a node opens the panel with correct NodeId and TypeId.
• AC2: Attachment payload renders as formatted JSON (or "none" if absent).
• AC3: Edge list entries are clickable and highlight the corresponding edge on Canvas.
• AC4: Panel closes on Escape key.

Definition of Done:

• Code reviewed and merged
• Tests pass (CI green)
• Documentation updated (if applicable)

Scope: Node selection, inspection panel, edge navigation.
Out of Scope: Editing node state from the panel. Multi-select. Search/filter.

Test Plan:

• Goldens: Playwright screenshot of inspection panel for a motion-rule node with AtomPayload.
• Failures: Click on empty canvas area shows no panel. Node with no edges shows "No edges" message.
• Edges: Node with 50+ edges (panel scrolls). Node with binary attachment (show hex dump, not garbage).
• Fuzz/Stress: Rapid click alternation between nodes; panel must not leak DOM elements.

Blocked By: T-4-2-2
Blocking: none

Est. Hours: 4h
Expected Complexity: ~250 LoC (TypeScript/HTML/CSS)

---

[coderabbitai]

🔗 Related PRs

#10 - docs(e2e): VitePress + Collision Tour + Playwright (split PR 4) [merged]
#113 - feat(benches): PR-12 — snapshot hash microbench (Closes #43) [merged]
#329 - Stack Witness 0001 fixture-backed jedit walking skeleton [merged]
#373 - chore: remove legacy ttd-browser surface [merged]
#380 - feat(core): expose retained evidence posture on readings [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[Huaian666]

In-browser visualization is such a powerful concept. The browser has become an incredible platform for data viz and interactive experiences.

I built an iOS app called Like Code that gives your HTML files a home on your phone. You write HTML yourself or use any AI to generate it, save it to your collection, and run it anytime with one tap - completely offline. Think of it as a personal collection of mini-apps and games. It is on the App Store, welcome to try it!