Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 0 additions & 22 deletions .github/workflows/ci.yml

This file was deleted.

2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
| Command | Purpose |
| :--- | :--- |
| `loop new <dir> [--template html\|code-diff\|shader]` | Scaffold a clean `scene.html` / `shader.frag` starter with `showcase.json` / `brief.json` |
| `loop diff <dir> [--range <a..b> \| --staged \| --file <patch>]` | Generate a dual-theme PR code-diff animation directly from real `git diff` output |
| `loop term <dir> --cmd "<command>" [--label "<text>"]` | Record real CLI command output into a dual-theme animated terminal showcase |
| `loop sheet <dir>` | Render a numbered contact sheet (`sheet.png`) |
| `loop story <dir>` | Render Frame `0` + step midpoints into `storyboard.png` for cold reading |
| `loop seam <dir\|video>` | Measure wrap-seam RMS delta, duplicate frames, and flicker (works on projects or external videos via `ffmpeg`) |
Expand Down
130 changes: 91 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<h1 align="center">Loop Studio</h1>

<p align="center">
<strong>Deterministic HTML/WebGL2 browser capture, dual-theme dark/light README &amp; PR motion, and doc-drift auditing for coding agents.</strong>
<strong>Turn real <code>git diff</code>s, CLI output, HTML/SVG diagrams, and WebGL2 shaders into verified, dual-theme dark/light README &amp; PR animations.</strong>
</p>

<p align="center">
Expand All @@ -17,7 +17,7 @@
</p>

<p align="center">
<em>Switch GitHub between Dark and Light mode to see the <code>&lt;picture&gt;</code> embed adapt automatically — rendered from plain HTML/CSS/SVG (<a href="./examples/ui-showcase"><code>examples/ui-showcase</code></a>), 240 frames @ 24 fps, <code>seamScore: 1.04</code>, <code>699 KB</code> dark / <code>752 KB</code> light.</em>
<em>Switch GitHub between Dark and Light mode to watch every <code>&lt;picture&gt;</code> embed below adapt automatically — rendered from plain HTML/CSS/SVG (<a href="./examples/ui-showcase"><code>examples/ui-showcase</code></a>), 240 frames @ 24 fps, <code>seamScore: 1.04</code>, <code>699 KB</code> dark / <code>752 KB</code> light.</em>
</p>

---
Expand All @@ -26,19 +26,20 @@

GitHub READMEs and PR descriptions strip JavaScript, CSS animations, and Lottie embeds—only animated images (`WebP` / `GIF`) or uploaded `<video>` work. Existing alternatives each break down in predictable ways:

| Capability | **Loop Studio (`v2.0`)** | **Generative Video (Veo / Sora)** | **Remotion / Motion Canvas** | **Raw Playwright Screen Capture** |
| Capability | **Loop Studio (`v2.0`)** | **Generative Video (Veo / Sora)** | **Remotion / Motion Canvas** | **Raw Playwright / VHS Capture** |
| :--- | :--- | :--- | :--- | :--- |
| **Crisp code, CLI & UI typography** | **Real browser DOM + SVG + WebGL2** | Garbles code & UI labels | React DOM | Real browser DOM |
| **Zero `npm install` in non-JS repos** | **Yes** (single CLI, macOS WebKit / Chrome CDP) | API / cloud | Requires 300 MB+ React bundler | Requires Playwright + timing glue |
| **Crisp code, CLI & UI typography** | **Real browser DOM + SVG + WebGL2** | Garbles code & UI labels | React DOM | Browser / terminal capture |
| **Generate directly from `git diff` or CLI cmd** | **`loop diff` & `loop term` (1 command)** | No | Manual React authoring | Manual tape / script |
| **Zero `npm install` in non-JS repos** | **Yes** (Node 18+ + macOS WebKit / Chrome CDP) | API / cloud | 300 MB+ React bundler | Go/ttyd/Playwright setup |
| **Frame-exact loop seam (`phase ∈ [0,1)`)** | **Frozen clocks + synchronous phase step** | Temporal flicker / jump | Manual frame math | Wall-clock jitter & dropped frames |
| **Dark + Light GitHub `<picture>` themes** | **1 flag (`--themes dark,light`)** + auto contrast | Single raster video | Manual duplicate setups | Manual dual recordings |
| **Dark + Light GitHub `<picture>` themes** | **1 flag (`--themes dark,light`)** + auto contrast | Single raster video | Duplicate setups | Single colorscheme |
| **Verifies WCAG contrast, 400px width & doc drift** | **Built-in `loop audit` CI gate** | None | None | None |

---

## Where Loop Studio Shines

### 1. Dual-Theme PR Code Diffs & Migration Visuals
### 1. Real `git diff` -> Dual-Theme PR Code Diffs (`loop diff`)

<p align="center">
<picture>
Expand All @@ -48,47 +49,83 @@ GitHub READMEs and PR descriptions strip JavaScript, CSS animations, and Lottie
</picture>
</p>

Instead of recording a blurry QuickTime screencast for a PR or migration guide, author a single [`scene.html`](./examples/code-diff/scene.html) using `--loop-*` CSS variables and render both GitHub themes in one command:
Turn any branch diff, staged change, or `.patch` file into a syntax-highlighted, dark+light PR or migration visual—automatically grounded to the real changed `file:line` range and `"match"` symbol:

```bash
node ./tool/bin/loop.js audit ./examples/code-diff --repo . --themes dark,light
node ./tool/bin/loop.js render ./examples/code-diff --themes dark,light --formats webp,png --max-kb 1024
node ./tool/bin/loop.js diff ./pr-demo --range dev..HEAD
node ./tool/bin/loop.js audit ./pr-demo --repo . --themes dark,light
node ./tool/bin/loop.js render ./pr-demo --themes dark,light --formats webp,png --max-kb 1024
```

Output: `854 KB` dark / `906 KB` light Animated WebP (`seamScore: 0.472`) plus a copy-paste `<picture>` block.
*Shown: [`examples/code-diff`](./examples/code-diff) · `854 KB` dark / `906 KB` light · `seamScore: 0.472`.*

---

### 2. Source-Grounded Explainers That Catch Doc Drift
### 2. Real CLI Output -> Dual-Theme Terminal Sessions (`loop term`)

README diagrams silently rot when code changes. Every step in `showcase.json` cites a real repo-relative `file:line` range and optional `"match"` tokens checked within ±3 lines:
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/demos/cli-terminal-dark.webp">
<source media="(prefers-color-scheme: light)" srcset="./assets/demos/cli-terminal-light.webp">
<img alt="Loop CLI Audit Terminal Showcase (adapts automatically to GitHub dark and light mode)" src="./assets/demos/cli-terminal-dark.webp" width="800">
</picture>
</p>

```json
{
"from": 8.0,
"to": 3.0,
"caption": "detect clock drift and random jitter",
"source": "tool/lib/harness.js:82-88",
"match": ["FIXED_EPOCH", "Math.random"]
}
Capture real command stdout and exit status into a crisp dark/light terminal animation—no `ttyd`, Go runtime, or hand-recorded QuickTime screencasts:

```bash
node ./tool/bin/loop.js term ./cli-demo --cmd "npm test" --label "npm test"
node ./tool/bin/loop.js render ./cli-demo --themes dark,light --formats webp
```

If someone refactors `FIXED_EPOCH` out of `tool/lib/harness.js`, `loop audit` fails CI immediately instead of shipping a lying README animation. Pair it with `loop story` + [`loop-cold-reader`](./agents/loop-cold-reader.md) (which inspects **only** `storyboard.png` with zero repo context) to verify a first-time visitor actually understands the animation.
*Shown: [`examples/cli-terminal`](./examples/cli-terminal) · `778 KB` dark / `863 KB` light · `seamScore: 0.472`.*

---

### 3. Animated SVG System Architecture & Dataflow Diagrams

<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/demos/architecture-flow-dark.webp">
<source media="(prefers-color-scheme: light)" srcset="./assets/demos/architecture-flow-light.webp">
<img alt="Animated SVG System Architecture Flow (adapts automatically to GitHub dark and light mode)" src="./assets/demos/architecture-flow-dark.webp" width="800">
</picture>
</p>

Replace static Mermaid boxes or broken dark-mode PNGs with animated SVG bezier topologies whose steps are tied directly to real implementation files via `file:line` + `"match"` checks:

*Shown: [`examples/architecture-flow`](./examples/architecture-flow) · `640 KB` dark / `688 KB` light · `seamScore: 1.073`, `flickerScore: 0.109`.*

---

### 3. Zero-Dependency WebGL2 Shaders & Interactive UI Walkthroughs
### 4. Quantitative Benchmark & Payload Comparisons

<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/demos/benchmark-compare-dark.webp">
<source media="(prefers-color-scheme: light)" srcset="./assets/demos/benchmark-compare-light.webp">
<img alt="README Asset Payload Benchmark Comparison (adapts automatically to GitHub dark and light mode)" src="./assets/demos/benchmark-compare-dark.webp" width="800">
</picture>
</p>

Ship clean, readable performance and bundle-size charts that animate smoothly across both GitHub themes and stay WCAG AA (`>= 4.5:1`) accessible at `400px` mobile width:

*Shown: [`examples/benchmark-compare`](./examples/benchmark-compare) · `529 KB` dark / `542 KB` light · `seamScore: 0.443`.*

---

### 5. Zero-Dependency WebGL2 Shaders

<table>
<tr>
<td width="340" align="center">
<img src="./assets/demos/shader-hero.webp" width="280" alt="WebGL2 GLSL Iridescent 3D SDF Torus">
</td>
<td>
<strong><code>examples/shader-hero</code> (WebGL2 GLSL · <code>761 KB</code> · <code>30 fps</code>)</strong><br><br>
Drop any <code>shader.frag</code> using <code>uniform float u_phase</code> and Loop Studio compiles, steps <code>0..N-1</code> on the GPU via macOS WebKit or Headless Chrome, verifies <code>seamScore: 0.951</code>, and encodes crisp Animated WebP or 60 fps MP4—zero Vite, Three.js, or bundler setup.<br><br>
<strong><a href="./examples/shader-hero"><code>examples/shader-hero</code></a> (WebGL2 GLSL · <code>761 KB</code> · <code>30 fps</code>)</strong><br><br>
Drop any <code>shader.frag</code> using <code>uniform float u_phase</code> and Loop Studio compiles, steps <code>0..N-1</code> on the GPU via macOS WebKit or Headless Chrome, verifies <code>seamScore: 0.951</code>, and encodes Animated WebP or 60 fps MP4—zero Vite, Three.js, or bundler setup.<br><br>
<ul>
<li><code>--loop-on-accent</code> &amp; <code>--loop-on-spark</code> automatically pick dark or light ink so CTA buttons stay WCAG <code>&gt;= 4.5:1</code> accessible in both themes.</li>
<li><code>--loop-on-accent</code> &amp; <code>--loop-on-spark</code> automatically pick dark or light ink so CTA buttons stay WCAG <code>&gt;= 4.5:1</code> in both themes.</li>
<li><code>loop legible</code> probes real rendered DOM bounding boxes, <code>scrollWidth</code> overflow, and <code>400px</code> mobile legibility.</li>
</ul>
</td>
Expand All @@ -97,18 +134,29 @@ If someone refactors `FIXED_EPOCH` out of `tool/lib/harness.js`, `loop audit` fa

---

### 4. Universal CI Gate for External Videos (Remotion, Playwright, After Effects)
### 6. Source-Drift Detection & Universal External Video CI Gate

Already rendering animations in Remotion, Motion Canvas, or After Effects? Point `loop seam` or `loop audit` at **any** `.mp4`, `.gif`, `.webp`, or `.webm` (decoded via `ffmpeg` when installed):
README visuals silently rot when code changes. Every step in `showcase.json` cites a repo-relative `file:line` range plus optional `"match"` tokens checked within ±3 lines:

```json
{
"from": 8.0,
"to": 3.0,
"caption": "detect clock drift and random jitter",
"source": "tool/lib/harness.js:82-88",
"match": ["FIXED_EPOCH", "Math.random"]
}
```

If someone refactors `FIXED_EPOCH` out of `tool/lib/harness.js`, `loop audit` fails CI immediately. Pair with `loop story` + [`loop-cold-reader`](./agents/loop-cold-reader.md) (inspecting **only** `storyboard.png` with zero repo context) to verify a first-time visitor understands the diagram.

Already rendering videos in **Remotion, Motion Canvas, Playwright, or After Effects**? Point `loop seam` or `loop audit` at **any** `.mp4`, `.gif`, `.webp`, or `.webm` (decoded via `ffmpeg` when installed):

```bash
node ./tool/bin/loop.js seam ./hero.mp4
node ./tool/bin/loop.js audit ./hero.webp --showcase ./showcase.json --repo . --max-kb 2048
```

- Detects broken wrap seams and duplicated end frames using lossy-codec RMS thresholds (`0.002` for MP4/WebP/WebM vs `0.0001` for lossless GIF).
- Enforces caption reading duration (`>= 0.5 + 0.3 * words` seconds), optional pixel `step.box` contrast checks, `--max-kb` payload budgets, and `file:line` + `"match"` source-drift checks (`0` pass, `1` fail, `2` missing `ffmpeg` or bad input).

---

## Install
Expand Down Expand Up @@ -141,16 +189,18 @@ npm test
## Quick Start

```bash
# 1. Scaffold an HTML/CSS/SVG starter (or --template code-diff | shader)
node ./tool/bin/loop.js new ./docs/demo --template code-diff
# Generate from a real git diff, real CLI command, or clean HTML/GLSL starter
node ./tool/bin/loop.js diff ./docs/demo --range dev..HEAD
node ./tool/bin/loop.js term ./docs/demo --cmd "npm test" --label "npm test"
node ./tool/bin/loop.js new ./docs/demo --template html

# 2. Generate storyboard.png for a zero-context cold read
# Build storyboard.png for a zero-context cold read
node ./tool/bin/loop.js story ./docs/demo

# 3. Audit seam, dual-theme WCAG contrast, mobile 400px layout, and source drift
# Audit seam, dual-theme WCAG contrast, mobile 400px layout, and source drift
node ./tool/bin/loop.js audit ./docs/demo --repo . --themes dark,light

# 4. Export dark/light WebP + PNG poster + copy-paste <picture> README snippet
# Export dark/light WebP + PNG poster + copy-paste <picture> README snippet
node ./tool/bin/loop.js render ./docs/demo --themes dark,light --formats webp,png --max-kb 2048
```

Expand All @@ -166,11 +216,11 @@ loop-studio/
├─ skills/
│ ├─ loop-studio/SKILL.md # Dual-theme HTML/WebGL2 README & PR motion workflow
│ └─ loop-audit/SKILL.md # Project & external video seam/contrast/drift audit
├─ examples/ # Source-only examples (code-diff, ui-showcase, shader-hero)
├─ assets/demos/ # Dual-theme README WebP demos (<4 MB total)
├─ examples/ # 6 source-only examples (ui-showcase, code-diff, cli-terminal, architecture-flow, benchmark-compare, shader-hero)
├─ assets/demos/ # Dual-theme README WebP demos
├─ tool/
│ ├─ bin/loop.js # `loop` CLI
│ ├─ lib/ # harness, webkit/chromium backends, analyzers, encoders, server
│ ├─ lib/ # generators (diff/term), harness, webkit/chromium backends, analyzers, encoders, server
│ ├─ scripts/ # macOS WKWebView & AVFoundation Swift runners
│ ├─ templates/ # `loop new` starters (html, code-diff, shader)
│ └─ test/run-evals.js # Core, negative-gate & browser integration test suite
Expand All @@ -183,6 +233,8 @@ loop-studio/

| Command | Description |
| :--- | :--- |
| `loop diff <dir> [--range <a..b> \| --staged \| --file <patch>]` | Generate a dual-theme syntax-highlighted PR code-diff scene from real `git diff` output |
| `loop term <dir> --cmd "<command>" [--label "<text>"] [--output "<lines>"]` | Capture real CLI output into a dual-theme animated terminal showcase |
| `loop new <dir> [--template html\|code-diff\|shader]` | Scaffold `scene.html` or `shader.frag`, `showcase.json` or `brief.json`, and `index.html` |
| `loop sheet <dir> [--every 8] [--cols 4]` | Render every Nth frame into a numbered contact sheet (`sheet.png`) |
| `loop story <dir>` | Render Frame `0` + step midpoints into `storyboard.png` |
Expand Down
Binary file added assets/demos/architecture-flow-dark.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/demos/architecture-flow-light.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/demos/benchmark-compare-dark.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/demos/benchmark-compare-light.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/demos/cli-terminal-dark.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/demos/cli-terminal-light.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 5 additions & 1 deletion docs/tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@ The `loop` CLI (`tool/bin/loop.js`) scaffolds HTML/GLSL loop scenes, drives dete

1. `loop new <dir> [--template html|code-diff|shader] [--palette <id>] [--force]`
Scaffolds a starter `scene.html` or `shader.frag`, `showcase.json` or `brief.json`, and `index.html` preview.
2. `loop sheet <dir> [--every <n>] [--cols 4] [--engine auto|webkit|chromium] [--theme <t>]`
2. `loop diff <dir> [--range <a..b> | --staged | --file <patch.diff>] [--repo <root>] [--title <text>] [--max-lines <n>]`
Parses a real unified git diff (or patch file) and generates a syntax-highlighted, dual-theme `scene.html` + `showcase.json` grounded to the changed `file:line` range and `"match"` symbol.
3. `loop term <dir> --cmd "<command>" [--label "<text>"] [--output "<lines>"] [--input <file>] [--repo <root>] [--title <text>]`
Executes a real CLI command (or reads output text) and generates a dual-theme animated terminal `scene.html` + `showcase.json` with typing, streaming output, and exit-status badge.
4. `loop sheet <dir> [--every <n>] [--cols 4] [--engine auto|webkit|chromium] [--theme <t>]`
Renders a numbered contact sheet into `<dir>/sheet.png`.
3. `loop story <dir> [--engine auto|webkit|chromium] [--theme <t>]`
Renders Frame `0` plus the midpoint of each step in `showcase.json` into `<dir>/storyboard.png` for cold reading.
Expand Down
Loading