claude-viz
Buffer invariance as architectural principle
Production-grade web component system for rendering Claude Code terminal output with lossless pipeline
Production-grade web component system for rendering Claude Code terminal output. Born from a critical data-corruption bug that demanded architectural rigor.
The Principle: Buffer Invariance
The rendering process must never modify the original text buffer.
This is the cornerstone. Previous iterations had a “TodoWrite Header Serialization Bug” where the rendering layer was coupled with data, allowing rendered content to corrupt source. The architecture now enforces strict separation.
Package Architecture
| Package | Purpose | Technology |
|---|---|---|
@claude-viz/parser | Text → semantic AST (pure, framework-agnostic) | TypeScript |
@claude-viz/renderer | Display-only web component | Lit |
@claude-viz/playground | Interactive editing application | React + Tiptap |
Key separation: Rendering and editing are fundamentally different problems. Two solutions for two use cases.
How It Differs
| Project | Approach | Tradeoff |
|---|---|---|
| ccviz | Quick POC, regex parsing | Fast to build, fragile |
| cc-prism | asciicast/asciinema playback | Great for sharing, not editing |
| claude-viz | Lossless pipeline, web components | Production-grade, more complex |
Web Component Value
The <claude-renderer> custom element provides:
- Framework-agnostic — Works in React, Vue, Angular, plain HTML
- Self-contained — Manages own logic and styling
- Portable — Drop into any web property
Specification-Driven Development
Formal specs before implementation:
specs/directory with detailed design docs- User stories and requirements
- Acceptance criteria for validation
CLAUDE.mdguidance for AI development
Technical Implementation
The playground’s Tiptap adapter injects a rawLine attribute into editor nodes. This attribute holds the original, unmodified line—the source of truth preserved even during interactive editing.
Raw Text → Parser (AST) → Renderer (display)
↘ Playground (edit with rawLine preservation)Key Insight
Evolution driven by production bugs.
A critical data-corruption bug directly led to this more robust, decoupled architecture. The investment in complexity was justified by the need for safety.