viewspec 0.1.0__tar.gz

viewspec-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,30 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: demos
+      - id: deployment
+        uses: actions/deploy-pages@v4

viewspec-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+!demos/vendor/pretext/dist/
+!demos/vendor/pretext/dist/*.mjs
+build/
+.eggs/
+*.egg
+.ruff_cache/
+.pytest_cache/
+output/
+viewspec_output/
+.venv/
+demos/server.*.log

viewspec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nxrobins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

viewspec-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: viewspec
+Version: 0.1.0
+Summary: Universal UI from semantic data. Describe what your data means — the compiler figures out how it looks.
+Project-URL: Homepage, https://github.com/nxrobins/viewspec
+Project-URL: Repository, https://github.com/nxrobins/viewspec
+Project-URL: Issues, https://github.com/nxrobins/viewspec/issues
+Author: Nigel Robinson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compiler,composition-ir,declarative,protobuf,semantic,ui,viewspec
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.11
+Requires-Dist: protobuf>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ViewSpec
+
+**Universal UI from semantic data.**
+
+ViewSpec is a declarative language for describing what data means. The compiler figures out how it looks. Every pixel has a birth certificate.
+
+🌐 **[viewspec.dev](https://viewspec.dev)** — Live demos and interactive playground
+
+```python
+from viewspec import ViewSpecBuilder, compile
+from viewspec.emitters.html_tailwind import HtmlTailwindEmitter
+
+builder = ViewSpecBuilder("invoice")
+table = builder.add_table("items", region="main", group_id="rows")
+table.add_row(label="Design System Audit", value="$4,200")
+table.add_row(label="Component Library", value="$8,500")
+table.add_row(label="API Integration", value="$3,100")
+
+ast = compile(builder.build_bundle())
+HtmlTailwindEmitter().emit(ast, "output/")
+
+# That's it. Full UI. Full provenance. No CSS.
+```
+
+## What ViewSpec Does
+
+**Before ViewSpec:** You manually bridge the gap between data and UI. Every component, every prop, every layout decision — hand-wired by a developer.
+
+**After ViewSpec:** You declare what the data means. The compiler determines the visual structure. Rendering is a pluggable backend.
+
+```
+Data → ViewSpec (semantic intent) → Compiler → CompositionIR → Emitter
+                                                                ├── HTML/Tailwind (shipped)
+                                                                ├── Canvas/Pretext
+                                                                ├── PDF
+                                                                ├── Native mobile
+                                                                └── Your custom emitter
+```
+
+## Three Invariants
+
+ViewSpec enforces three mathematical guarantees:
+
+1. **Exactly-once provenance.** Every data binding is routed exactly once. Nothing dropped. Nothing duplicated. Nothing hallucinated.
+
+2. **Semantic grouping.** Data is grouped by meaning, not by visual adjacency.
+
+3. **Strict ordering.** The original data order is preserved as a mathematical guarantee.
+
+## Install
+
+```bash
+pip install viewspec
+```
+
+Requires Python 3.11+.
+
+## Demos
+
+Six interactive demos at [viewspec.dev](https://viewspec.dev):
+
+| Demo | What it shows |
+|------|--------------|
+| [Same Data, Three Motifs](https://viewspec.dev/motif-switcher/) | One dataset → table, dashboard, or comparison. Change one parameter. |
+| [Provenance Inspector](https://viewspec.dev/provenance-inspector/) | Hover any element. Trace DOM → IR → binding → address → raw data. |
+| [Live Builder](https://viewspec.dev/live-builder/) | Browse ViewSpec JSON, IR tree, and rendered output in sync. |
+| [The Invariants](https://viewspec.dev/invariants/) | Watch the compiler enforce — and refuse — each guarantee. |
+| [15 Lines → Full UI](https://viewspec.dev/fifteen-lines/) | An invoice table builds itself from 15 lines of Python. |
+| [Style Derivation](https://viewspec.dev/style-derivation/) | Same structure, different feel. Toggle four visual presets. |
+
+Text rendering powered by [Pretext](https://github.com/chenglou/pretext) canvas surfaces.
+
+## Core Concepts
+
+### Semantic Substrate
+
+The raw data graph. Nodes with typed attributes, slots, and edges. This is WHAT the data is — no visual intent.
+
+```python
+builder = ViewSpecBuilder("my_view")
+builder.add_node("user_1", "person", attrs={"name": "Alice", "role": "Engineer"})
+builder.add_node("user_2", "person", attrs={"name": "Bob", "role": "Designer"})
+```
+
+### ViewSpec
+
+The declarative intent layer. Regions (WHERE data can go), bindings (WHICH data goes WHERE), motifs (HOW it should be structured), and styles (how it should FEEL).
+
+```python
+table = builder.add_table("team", region="main", group_id="members")
+table.add_row(label="Alice", value="Engineer")
+table.add_row(label="Bob", value="Designer")
+```
+
+### CompositionIR
+
+The compiler's output. A strict hierarchical tree of 12 UI primitives (`root`, `stack`, `grid`, `cluster`, `surface`, `text`, `label`, `value`, `badge`, `image_slot`, `rule`, `svg`) with full provenance tracking. Every IR node knows which semantic addresses and intent refs produced it.
+
+### Emitters
+
+Pluggable renderers that turn CompositionIR into concrete output. Subclass `EmitterPlugin`:
+
+```python
+from viewspec.emitters.base import EmitterPlugin
+
+class MyEmitter(EmitterPlugin):
+    def emit(self, ast_bundle, output_dir):
+        # Walk ast_bundle.result.root.root and produce output
+        ...
+```
+
+The included HTML/Tailwind emitter produces standalone HTML with full Tailwind styling, provenance data attributes on every DOM element, action event dispatch, and a JSON provenance manifest.
+
+## Motif Types
+
+| Builder | Motif | Use case |
+|---------|-------|----------|
+| `add_table()` | `table` | Tabular data with label-value rows |
+| `add_dashboard()` | `dashboard` | KPI cards with label-value pairs |
+| `add_outline()` | `outline` | Hierarchical outlines and trees |
+| `add_comparison()` | `comparison` | Side-by-side comparisons |
+
+Each builder returns a chained sub-builder. Compose them freely within a single ViewSpec.
+
+## Compilation
+
+### Reference Compiler (free, offline)
+
+Handles the four standard motifs locally. No API, no network, no LLM. Deterministic.
+
+```python
+ast = compile(builder.build_bundle())
+```
+
+### Hosted Compiler (api.viewspec.dev)
+
+For complex layouts, novel data shapes, and advanced derivation. The hosted compiler was **evolved** (not hand-written) using reinforcement learning:
+
+- **13/13** on a static validation suite
+- **50/50** on novel, randomized out-of-distribution layouts (one-shot)
+- **Level 2 derivation tokens** — data-aware emphasis, narrative routing, palette energy
+- **Zero LLM cost at runtime** — deterministic Python, ~3ms per compile
+
+```python
+from viewspec import compile_auto
+
+# Try local first, fall back to hosted for unsupported motifs
+ast = compile_auto(builder.build_bundle())
+```
+
+| Tier | Price | Hosted Calls/Day |
+|------|-------|-----------------|
+| Free | $0 | 500 |
+| Pro | $39/mo | 25,000 |
+| Scale | $99/mo | 250,000 |
+| Enterprise | Contact | Custom |
+
+## Wire Format
+
+Protocol Buffers for language-agnostic serialization. The same ViewSpec can be constructed in Python, Rust, Go, TypeScript, or any language with protobuf support.
+
+```python
+bundle = builder.build_bundle()
+json_data = bundle.to_json()           # JSON round-trip
+proto_bytes = bundle.to_proto().SerializeToString()  # Protobuf round-trip
+```
+
+## Examples
+
+See [`examples/`](examples/):
+
+- **`invoice_table.py`** — Build a table in 15 lines
+- **`kpi_dashboard.py`** — KPI dashboard with style tokens
+- **`comparison_view.py`** — Side-by-side comparison
+- **`emit_html.py`** — Load a compiled AST and emit HTML
+
+## License
+
+MIT

viewspec-0.1.0/README.md

@@ -0,0 +1,179 @@
+# ViewSpec
+
+**Universal UI from semantic data.**
+
+ViewSpec is a declarative language for describing what data means. The compiler figures out how it looks. Every pixel has a birth certificate.
+
+🌐 **[viewspec.dev](https://viewspec.dev)** — Live demos and interactive playground
+
+```python
+from viewspec import ViewSpecBuilder, compile
+from viewspec.emitters.html_tailwind import HtmlTailwindEmitter
+
+builder = ViewSpecBuilder("invoice")
+table = builder.add_table("items", region="main", group_id="rows")
+table.add_row(label="Design System Audit", value="$4,200")
+table.add_row(label="Component Library", value="$8,500")
+table.add_row(label="API Integration", value="$3,100")
+
+ast = compile(builder.build_bundle())
+HtmlTailwindEmitter().emit(ast, "output/")
+
+# That's it. Full UI. Full provenance. No CSS.
+```
+
+## What ViewSpec Does
+
+**Before ViewSpec:** You manually bridge the gap between data and UI. Every component, every prop, every layout decision — hand-wired by a developer.
+
+**After ViewSpec:** You declare what the data means. The compiler determines the visual structure. Rendering is a pluggable backend.
+
+```
+Data → ViewSpec (semantic intent) → Compiler → CompositionIR → Emitter
+                                                                ├── HTML/Tailwind (shipped)
+                                                                ├── Canvas/Pretext
+                                                                ├── PDF
+                                                                ├── Native mobile
+                                                                └── Your custom emitter
+```
+
+## Three Invariants
+
+ViewSpec enforces three mathematical guarantees:
+
+1. **Exactly-once provenance.** Every data binding is routed exactly once. Nothing dropped. Nothing duplicated. Nothing hallucinated.
+
+2. **Semantic grouping.** Data is grouped by meaning, not by visual adjacency.
+
+3. **Strict ordering.** The original data order is preserved as a mathematical guarantee.
+
+## Install
+
+```bash
+pip install viewspec
+```
+
+Requires Python 3.11+.
+
+## Demos
+
+Six interactive demos at [viewspec.dev](https://viewspec.dev):
+
+| Demo | What it shows |
+|------|--------------|
+| [Same Data, Three Motifs](https://viewspec.dev/motif-switcher/) | One dataset → table, dashboard, or comparison. Change one parameter. |
+| [Provenance Inspector](https://viewspec.dev/provenance-inspector/) | Hover any element. Trace DOM → IR → binding → address → raw data. |
+| [Live Builder](https://viewspec.dev/live-builder/) | Browse ViewSpec JSON, IR tree, and rendered output in sync. |
+| [The Invariants](https://viewspec.dev/invariants/) | Watch the compiler enforce — and refuse — each guarantee. |
+| [15 Lines → Full UI](https://viewspec.dev/fifteen-lines/) | An invoice table builds itself from 15 lines of Python. |
+| [Style Derivation](https://viewspec.dev/style-derivation/) | Same structure, different feel. Toggle four visual presets. |
+
+Text rendering powered by [Pretext](https://github.com/chenglou/pretext) canvas surfaces.
+
+## Core Concepts
+
+### Semantic Substrate
+
+The raw data graph. Nodes with typed attributes, slots, and edges. This is WHAT the data is — no visual intent.
+
+```python
+builder = ViewSpecBuilder("my_view")
+builder.add_node("user_1", "person", attrs={"name": "Alice", "role": "Engineer"})
+builder.add_node("user_2", "person", attrs={"name": "Bob", "role": "Designer"})
+```
+
+### ViewSpec
+
+The declarative intent layer. Regions (WHERE data can go), bindings (WHICH data goes WHERE), motifs (HOW it should be structured), and styles (how it should FEEL).
+
+```python
+table = builder.add_table("team", region="main", group_id="members")
+table.add_row(label="Alice", value="Engineer")
+table.add_row(label="Bob", value="Designer")
+```
+
+### CompositionIR
+
+The compiler's output. A strict hierarchical tree of 12 UI primitives (`root`, `stack`, `grid`, `cluster`, `surface`, `text`, `label`, `value`, `badge`, `image_slot`, `rule`, `svg`) with full provenance tracking. Every IR node knows which semantic addresses and intent refs produced it.
+
+### Emitters
+
+Pluggable renderers that turn CompositionIR into concrete output. Subclass `EmitterPlugin`:
+
+```python
+from viewspec.emitters.base import EmitterPlugin
+
+class MyEmitter(EmitterPlugin):
+    def emit(self, ast_bundle, output_dir):
+        # Walk ast_bundle.result.root.root and produce output
+        ...
+```
+
+The included HTML/Tailwind emitter produces standalone HTML with full Tailwind styling, provenance data attributes on every DOM element, action event dispatch, and a JSON provenance manifest.
+
+## Motif Types
+
+| Builder | Motif | Use case |
+|---------|-------|----------|
+| `add_table()` | `table` | Tabular data with label-value rows |
+| `add_dashboard()` | `dashboard` | KPI cards with label-value pairs |
+| `add_outline()` | `outline` | Hierarchical outlines and trees |
+| `add_comparison()` | `comparison` | Side-by-side comparisons |
+
+Each builder returns a chained sub-builder. Compose them freely within a single ViewSpec.
+
+## Compilation
+
+### Reference Compiler (free, offline)
+
+Handles the four standard motifs locally. No API, no network, no LLM. Deterministic.
+
+```python
+ast = compile(builder.build_bundle())
+```
+
+### Hosted Compiler (api.viewspec.dev)
+
+For complex layouts, novel data shapes, and advanced derivation. The hosted compiler was **evolved** (not hand-written) using reinforcement learning:
+
+- **13/13** on a static validation suite
+- **50/50** on novel, randomized out-of-distribution layouts (one-shot)
+- **Level 2 derivation tokens** — data-aware emphasis, narrative routing, palette energy
+- **Zero LLM cost at runtime** — deterministic Python, ~3ms per compile
+
+```python
+from viewspec import compile_auto
+
+# Try local first, fall back to hosted for unsupported motifs
+ast = compile_auto(builder.build_bundle())
+```
+
+| Tier | Price | Hosted Calls/Day |
+|------|-------|-----------------|
+| Free | $0 | 500 |
+| Pro | $39/mo | 25,000 |
+| Scale | $99/mo | 250,000 |
+| Enterprise | Contact | Custom |
+
+## Wire Format
+
+Protocol Buffers for language-agnostic serialization. The same ViewSpec can be constructed in Python, Rust, Go, TypeScript, or any language with protobuf support.
+
+```python
+bundle = builder.build_bundle()
+json_data = bundle.to_json()           # JSON round-trip
+proto_bytes = bundle.to_proto().SerializeToString()  # Protobuf round-trip
+```
+
+## Examples
+
+See [`examples/`](examples/):
+
+- **`invoice_table.py`** — Build a table in 15 lines
+- **`kpi_dashboard.py`** — KPI dashboard with style tokens
+- **`comparison_view.py`** — Side-by-side comparison
+- **`emit_html.py`** — Load a compiled AST and emit HTML
+
+## License
+
+MIT

viewspec-0.1.0/demos/CNAME

@@ -0,0 +1 @@
+viewspec.dev

viewspec-0.1.0/demos/SPEC-DEMO-FIFTEEN-LINES.md

@@ -0,0 +1,96 @@
+# Demo: 15 Lines → Full UI
+
+## What It Proves
+The ratio between intent and output is extreme. Fifteen lines of semantic description produces a complete, styled, provenance-tracked UI. No components. No layout code. No CSS.
+
+## Behavior
+
+Split screen. Left: Python code. Right: rendered output.
+
+The code appears line by line (typewriter effect, ~80ms per character, ~400ms pause between lines). As each semantically meaningful line completes, the rendered output on the right updates to include the new element. The build-up is progressive — the user watches the UI construct itself from semantic declarations.
+
+### The Code (15 lines)
+```python
+from viewspec import ViewSpecBuilder
+
+builder = ViewSpecBuilder("invoice")
+
+table = builder.add_table("items", region="main", group_id="rows")
+table.add_row(label="Design System Audit", value="$4,200")
+table.add_row(label="Component Library",   value="$8,500")
+table.add_row(label="API Integration",     value="$3,100")
+table.add_row(label="QA & Testing",        value="$2,800")
+table.add_row(label="Documentation",       value="$1,400")
+
+builder.add_style("s1", "items_row_5_label", "tone.muted")
+builder.add_style("s2", "items_row_5_value", "emphasis.high")
+
+bundle = builder.build_bundle()
+```
+
+### Progressive Reveal Steps
+Lines 1-2 (import + builder): Empty root container appears on right
+Line 4 (add_table): Table structure appears (empty, with header area)
+Lines 5-9 (add_row × 5): Each row appears as the line completes
+Lines 11-12 (add_style): The "Documentation" row's label dims and value bolds
+Line 14 (build_bundle): A "✓ Bundle Ready" badge animates in below the table, showing binding count and provenance status
+
+After the animation completes, a "Replay" button appears.
+
+## Implementation
+
+### Pre-generation
+Write a Python script (`demos/build_fifteen_lines.py`) that:
+1. Builds the full IntentBundle
+2. Hand-builds IR trees for each progressive step (empty, table shell, 1 row, 2 rows, ..., 5 rows, styled, final)
+3. Emits HTML fragments for each step
+4. Packages into `index.html` with typewriter JS
+
+### HTML Structure
+```html
+<div class="split-screen">
+  <div class="code-panel">
+    <div class="panel-header">
+      <span class="filename">invoice.py</span>
+      <span class="lang-badge">Python</span>
+    </div>
+    <pre><code id="code-display"></code></pre>
+  </div>
+  
+  <div class="output-panel">
+    <div class="panel-header">
+      <span class="filename">Rendered Output</span>
+      <span class="live-badge">● Live</span>
+    </div>
+    <div id="output-display"></div>
+  </div>
+</div>
+```
+
+### Styling
+- Code panel: dark (slate-900), monospace, syntax highlighting via CSS classes
+  - Keywords (from, import): blue-400
+  - Strings: green-400
+  - Method calls: teal-300
+  - Comments: slate-500
+- Output panel: light (slate-50), the normal emitter output
+- Split: 50/50 on desktop, stacked on mobile (code on top)
+- Cursor: blinking block cursor at end of current line during typing
+- "✓ Bundle Ready" badge: slides up, green background, shows "10 bindings | 5 nodes | full provenance"
+
+### JS (~80 lines)
+- Array of code lines with metadata: `{ text, delay, outputStep }`
+- Typewriter loop: character by character with configurable speed
+- On each `outputStep`, swap the output panel's innerHTML to the pre-generated fragment
+- Replay button resets and restarts
+- Skip button (subtle, bottom-right) jumps to final state
+
+## Output
+`demos/fifteen-lines/index.html` — single self-contained HTML file.
+
+## Quality Bar
+- The typing must feel natural (not robotic, slight variance in speed)
+- Syntax highlighting must be accurate for Python
+- The progressive reveal must feel like the UI is being BUILT, not just shown
+- The final state must be a genuinely good-looking invoice table
+- The ratio (15 lines → complete UI) must be felt, not just counted

viewspec-0.1.0/demos/SPEC-DEMO-INVARIANTS.md

@@ -0,0 +1,89 @@
+# Demo: The Invariants
+
+## What It Proves
+ViewSpec doesn't just produce correct UI — it refuses to produce incorrect UI. The three invariants (exactly-once provenance, semantic grouping, strict ordering) are enforced, visible, and unbreakable.
+
+## Behavior
+
+Three sections, each demonstrating one invariant being enforced. Each section has:
+- A title and one-sentence explanation
+- A "Valid" example (green border, renders correctly)
+- A "Violation" example (red border, shows the CompilerDiagnostic)
+- A toggle to flip between them
+
+### Section 1: Exactly-Once Provenance
+
+**Valid:** A table with 4 rows. Each binding routes exactly once. All data accounted for. A counter shows "4/4 bindings routed."
+
+**Violation:** Same table but one binding is duplicated (appears in two rows). The compiler catches it: `CompilerDiagnostic { severity: "error", code: "DUPLICATE_ROUTING", message: "Binding 'row_2_value' routed to multiple IR nodes" }`. The duplicate element renders with a red dashed border and an error badge.
+
+### Section 2: Semantic Grouping
+
+**Valid:** A dashboard with 3 cards. Each card's label and value are grouped by semantic boundary (same node). Groups are visually enclosed in surfaces.
+
+**Violation:** A label from card 1 is grouped with the value from card 2 (cross-group contamination). Diagnostic: `{ code: "GROUP_VIOLATION", message: "Binding 'card_1_label' grouped with non-sibling 'card_2_value'" }`. The mismatched elements highlight with connecting red lines.
+
+### Section 3: Strict Ordering
+
+**Valid:** A table where rows appear in the order they were declared in the substrate. Row 1 → Row 2 → Row 3 → Row 4.
+
+**Violation:** Rows reordered (Row 1 → Row 3 → Row 2 → Row 4). Diagnostic: `{ code: "ORDER_VIOLATION", message: "Binding 'row_3_label' precedes 'row_2_label' but was declared after it in the substrate" }`. The out-of-order rows get numbered badges showing declared order vs rendered order.
+
+## Implementation
+
+### Pre-generation
+Write a Python script (`demos/build_invariants.py`) that:
+1. For each invariant, builds a valid IntentBundle and a deliberately broken one
+2. Hand-builds correct IR trees for valid cases
+3. Hand-builds broken IR trees with `CompilerDiagnostic` entries for violation cases
+4. Emits both via `HtmlTailwindEmitter`
+5. Wraps in `index.html` with toggle JS
+
+### HTML Structure
+```html
+<section class="invariant">
+  <h2>Exactly-Once Provenance</h2>
+  <p>Every data binding is routed exactly once. Nothing dropped. Nothing duplicated.</p>
+  
+  <div class="toggle-group">
+    <button data-state="valid" class="active">✓ Valid</button>
+    <button data-state="violation">✗ Violation</button>
+  </div>
+  
+  <div class="demo-container">
+    <div class="state-valid active">
+      <!-- valid rendered HTML with green border -->
+      <div class="status-bar valid">✓ 4/4 bindings routed exactly once</div>
+    </div>
+    <div class="state-violation">
+      <!-- violation rendered HTML with red border -->
+      <div class="diagnostic">
+        <span class="severity error">ERROR</span>
+        <span class="code">DUPLICATE_ROUTING</span>
+        <span class="message">Binding 'row_2_value' routed to multiple IR nodes</span>
+      </div>
+    </div>
+  </div>
+</section>
+```
+
+### Styling
+- Valid state: thin green-500 left border on the container
+- Violation state: thin red-500 left border, diagnostic card below with monospace text
+- Error elements within violations: red dashed border, semi-transparent red overlay
+- Status bar: full-width bar below the rendered output showing pass/fail
+- Diagnostic cards styled like compiler output (dark bg, monospace, severity badge)
+- Subtle shake animation on the violation elements when toggled to (150ms, 2px)
+
+### JS (~30 lines)
+Per-section toggle between valid and violation states.
+
+## Output
+`demos/invariants/index.html` — single self-contained HTML file.
+
+## Quality Bar
+- The violations must look genuinely broken, not just annotated
+- The diagnostics must read like real compiler output
+- The valid examples must feel solid and trustworthy
+- The contrast between valid and violation should be visceral
+- Someone watching should think "I want my UI to have this"