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
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ Use the `loop` CLI (`npx loop` or `node tool/bin/loop.js`) for every stage of th

| Command | Purpose | Output |
| :--- | :--- | :--- |
| `loop new <dir> [--mode showcase\|ambient] [--style <id>] [--scene <id>]` | Scaffold a loop project with `brief.json` / `showcase.json`, `sketch.js`, and preview HTML | `<dir>/sketch.js`, `<dir>/index.html` |
| `loop new <dir> [--mode showcase\|ambient] [--style <id>] [--scene <id>] [--fps <n>]` | Scaffold a loop project with `brief.json` / `showcase.json`, `sketch.js`, and preview HTML | `<dir>/sketch.js`, `<dir>/index.html` |
| `loop sheet <dir> [--cols 4] [--every 8]` | Render every Nth frame into a numbered contact sheet for visual critique | `<dir>/sheet.png` |
| `loop story <dir>` | Render Frame `0` plus the midpoint frame of each step in `showcase.json` | `<dir>/storyboard.png` |
| `loop seam <dir>` | Measure frame-to-frame pixel deltas, last-to-first seam ratio, duplicate frames, and flicker | `<dir>/seam.json` |
| `loop legible <dir>` | Audit caption reading time, WCAG contrast (`>= 4.5:1`), safe margins, and phone-width readability | `<dir>/legible.json` |
| `loop source-check <dir> [--repo <path>]` | Verify every `file:line` citation in `showcase.json` exists in the target repository | `<dir>/sources.json` |
| `loop audit <dir>` | Run `seam`, `legible`, and `source-check` together as a unified quality gate | `<dir>/audit.json` |
| `loop render <dir> [--formats gif,mp4,webm,png]` | Render full-resolution `loop.gif` / `showcase.gif`, `poster.png`, and (when FFmpeg is available) `loop.mp4` & `loop.webm` | `<dir>/loop.gif`, `<dir>/poster.png` |
| `loop render <dir> [--fps <n>] [--formats gif,mp4,webp,webm,png\|all]` | Render full-resolution `loop.gif` / `showcase.gif`, `poster.png`, `loop.mp4` (FFmpeg or macOS AVFoundation), Animated WebP, and WebM at up to `60–120 fps` | `<dir>/loop.gif`, `<dir>/loop.mp4`, `<dir>/poster.png` |
| `loop serve <dir> [--port 4173]` | Launch interactive browser workbench with phase scrubber, seam oscilloscope, and mobile preview | `http://localhost:4173` |
| `loop doctor` | Check runtime capabilities (Pure-JS engine, Headless Chrome/Chromium, FFmpeg) | JSON / terminal diagnostic |

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,9 +206,9 @@ loop-studio/
| `loop legible <dir>` | Verify reading duration (`>= 0.5 + 0.3*words`), WCAG `4.5:1` contrast & phone margins | `legible.json` |
| `loop source-check <dir> [--repo <root>]` | Verify every `file:line` source citation in `showcase.json` exists | `sources.json` |
| `loop audit <dir> [--repo <root>]` | Run `seam`, `legible`, and `source-check` together as a single gate | `audit.json` |
| `loop render <dir>` | Render full-resolution `showcase.gif` / `loop.gif` and `poster.png` | `loop.gif`, `poster.png`, `seam.json` |
| `loop render <dir> [--fps <n>] [--formats gif,mp4,webp,webm,png\|all]` | Render full-resolution `showcase.gif` / `loop.gif`, `poster.png`, `loop.mp4` (`30–120 fps` via FFmpeg or macOS AVFoundation), Animated `.webp`, and `.webm` | `loop.gif`, `loop.mp4`, `poster.png`, `seam.json` |
| `loop serve <dir> [--port 4173]` | Launch interactive browser workbench with phase scrubber & 400px phone view | `http://localhost:4173` |
| `loop doctor` | Check runtime engines (SoftCanvas2D, GIF89a, PNG, FFmpeg, Chrome) | JSON diagnostic |
| `loop doctor` | Check runtime engines (SoftCanvas2D, GIF89a, PNG, macOS AVFoundation, Animated WebP, FFmpeg, Chrome) | JSON diagnostic |

---

Expand Down
4 changes: 2 additions & 2 deletions docs/tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ The `loop` command (`tool/bin/loop.js`) drives project scaffolding, preview cont
Verifies every `"source": "file:line"` in `showcase.json` exists in the repository and writes `<dir>/sources.json`.
7. `loop audit <dir> [--repo <root>]`
Runs `seam`, `legible`, and `source-check` together and writes `<dir>/audit.json`.
8. `loop render <dir>`
Renders all frames `0..N-1` at full resolution and outputs `showcase.gif` / `loop.gif` and `poster.png` (plus `loop.mp4` / `loop.webm` when FFmpeg is present).
8. `loop render <dir> [--fps <n>] [--formats gif,mp4,webp,webm,png|all] [--width <n>] [--height <n>]`
Renders all frames `0..N-1` at full resolution and outputs `showcase.gif` / `loop.gif`, `poster.png`, `loop.mp4` (via FFmpeg or native macOS AVFoundation at `30/60/120 fps`), Animated `.webp` (via `cwebp`+`webpmux` or FFmpeg), and `.webm` (when FFmpeg is present).
9. `loop serve <dir> [--port 4173]`
Opens the interactive browser workbench with phase scrubber and mobile width toggle.
10. `loop doctor`
Expand Down
12 changes: 9 additions & 3 deletions skills/loop-render/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,15 +59,21 @@ node tool/bin/loop.js audit <dir> --repo <repo-root>

### 8. Final Render (`loop render`)
Renders all $N$ frames (`0..N-1`) at full resolution and encodes:
- `loop.gif` (or `showcase.gif` in showcase mode) using adaptive 256-color quantization + LZW encoding (or FFmpeg two-pass `palettegen`/`paletteuse` when FFmpeg is installed)
- `loop.gif` (or `showcase.gif` in showcase mode) using adaptive 256-color quantization + LZW encoding (GIF89a frame delays use integer centiseconds, capping reliable browser playback at `50 fps` / `2 cs`)
- `poster.png` (Frame `0` at full resolution)
- `loop.mp4` / `showcase.mp4` (`H.264 yuv420p` when FFmpeg is installed)
- `loop.mp4` / `showcase.mp4` (`H.264 yuv420p` at exact requested `fps` — `24`, `30`, `60`, or `120 fps` — via **FFmpeg** or native **macOS AVFoundation**)
- `loop.webp` / `showcase.webp` (24-bit Animated WebP with exact millisecond frame timing at `30–60+ fps` via `cwebp`+`webpmux` or FFmpeg)
- `loop.webm` (`VP9` when FFmpeg is installed and `--formats webm` is requested)

```bash
node tool/bin/loop.js render <dir> --formats gif,png,mp4
node tool/bin/loop.js render <dir> --fps 60 --formats mp4,webp,gif,png
```

> [!TIP]
> **Choosing Frame Rates (`> 20 fps`)**:
> - For **GIFs**, use `20`, `25`, `30` (`3 cs` ≈ `33.3 fps`), or `50 fps` (`2 cs`, maximum reliable browser GIF speed).
> - For **true `30 / 60 / 120 fps` smooth video**, pass `--fps 60` with `--formats mp4,webp,png` (MP4 files are typically `4×–10×` smaller than GIFs with zero 256-color banding).

### 9. Live Interactive Workbench (`loop serve`)
Opens an interactive studio in the browser with a frame-exact phase scrubber, live seam-jump bar chart, mobile width toggle, and instant PNG/sheet export:
```bash
Expand Down
Loading
Loading