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
40 changes: 25 additions & 15 deletions README.md

Large diffs are not rendered by default.

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
15 changes: 15 additions & 0 deletions gallery/api-pipeline-code/audit.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"id": "api-pipeline-code",
"title": "Phase Contract SDK Showcase (Code)",
"mode": "showcase",
"useCase": "SDK / library docs pairing live-stepping code with a synchronized state monitor",
"fps": 20,
"pass": true,
"seamScore": 1.006,
"duplicateFrames": 0,
"flickerScore": 0.08,
"legiblePass": true,
"sourcesPass": true,
"gifKB": 2343.8,
"totalFrames": 200
}
120 changes: 120 additions & 0 deletions gallery/api-pipeline-code/index.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Phase Contract SDK Showcase (Code) · Loop Studio</title>
<style>
:root {
--bg: #0E1120; --surface: #171B2E; --stage: #0A0C18; --ink: #E7E9F4;
--muted: #9BA1BC; --line: #2A3050; --accent: #FF6B9D; --spark: #7FA2FF;
--mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
}
body {
margin: 0; padding: 2rem 1rem; background: var(--bg); color: var(--ink);
font-family: system-ui, -apple-system, sans-serif;
}
.wrap { max-width: 56rem; margin: 0 auto; display: flex; flex-direction: column; gap: 1.25rem; }
header { display: flex; justify-content: space-between; align-items: baseline; flex-wrap: wrap; gap: 0.5rem; }
h1 { margin: 0; font-size: 1.35rem; font-weight: 700; }
.badge { font-family: var(--mono); font-size: 0.78rem; color: var(--spark); background: var(--surface); border: 1px solid var(--line); padding: 0.25rem 0.6rem; border-radius: 4px; }
.stage-box { border: 1px solid var(--line); border-radius: 8px; background: var(--stage); overflow: hidden; }
.canvas-holder { display: flex; justify-content: center; align-items: center; padding: 1rem; background: var(--stage); }
canvas { display: block; max-width: 100%; height: auto; border-radius: 4px; box-shadow: 0 8px 24px rgba(0,0,0,0.35); }
canvas.mobile-width { max-width: 400px; }
.transport {
display: flex; flex-wrap: wrap; align-items: center; gap: 0.75rem;
padding: 0.75rem 1rem; background: var(--surface); border-top: 1px solid var(--line);
}
button {
font: 500 0.82rem var(--mono); color: var(--ink); background: var(--bg);
border: 1px solid var(--line); border-radius: 4px; padding: 0.4rem 0.75rem; cursor: pointer;
}
button:hover { border-color: var(--accent); }
input[type="range"] { flex: 1 1 12rem; accent-color: var(--accent); }
output { font-family: var(--mono); font-size: 0.8rem; color: var(--muted); font-variant-numeric: tabular-nums; }
</style>
</head>
<body>
<div class="wrap">
<header>
<h1>Phase Contract SDK Showcase (Code)</h1>
<span class="badge" id="meta-badge">loading sketch.js...</span>
</header>
<div class="stage-box">
<div class="canvas-holder">
<canvas id="stage-canvas"></canvas>
</div>
<div class="transport">
<button type="button" id="play-btn">Pause</button>
<input type="range" id="scrubber" min="0" max="119" value="0" step="1">
<output id="readout">frame 000 / 120 · phase 0.00</output>
<button type="button" id="phone-btn">400px Phone View</button>
</div>
</div>
</div>
<script type="module">
import * as sketch from "./sketch.js";
import { createKit } from "./loop-kit.js";

const cv = document.getElementById("stage-canvas");
const ctx = cv.getContext("2d");
const playBtn = document.getElementById("play-btn");
const phoneBtn = document.getElementById("phone-btn");
const scrubber = document.getElementById("scrubber");
const readout = document.getElementById("readout");
const badge = document.getElementById("meta-badge");

const meta = sketch.meta || { seconds: 4, fps: 30, width: 640, height: 640 };
const totalFrames = Math.round((meta.seconds || 4) * (meta.fps || 30));
cv.width = meta.width || 640;
cv.height = meta.height || 640;
scrubber.max = String(totalFrames - 1);
badge.textContent = `${meta.mode || "loop"} · ${meta.seconds}s @ ${meta.fps}fps (${totalFrames}f) · ${cv.width}×${cv.height}`;

const kit = createKit({ showcase: sketch.showcase });
let frame = 0;
let playing = true;
let startedAt = null;

function drawFrame() {
const phase = frame / totalFrames;
sketch.render(ctx, phase, kit);
scrubber.value = String(frame);
readout.textContent = `frame ${String(frame).padStart(3, "0")} / ${totalFrames} · phase ${phase.toFixed(3)}`;
}

function tick(now) {
if (playing) {
if (startedAt === null) startedAt = now - (frame / totalFrames) * meta.seconds * 1000;
const u = (((now - startedAt) / 1000 / meta.seconds) % 1 + 1) % 1;
const nextF = Math.floor(u * totalFrames) % totalFrames;
if (nextF !== frame) {
frame = nextF;
drawFrame();
}
}
requestAnimationFrame(tick);
}

playBtn.addEventListener("click", () => {
playing = !playing;
startedAt = null;
playBtn.textContent = playing ? "Pause" : "Play";
});
phoneBtn.addEventListener("click", () => {
cv.classList.toggle("mobile-width");
});
scrubber.addEventListener("input", () => {
playing = false;
startedAt = null;
playBtn.textContent = "Play";
frame = parseInt(scrubber.value, 10) || 0;
drawFrame();
});

drawFrame();
requestAnimationFrame(tick);
</script>
</body>
</html>
71 changes: 71 additions & 0 deletions gallery/api-pipeline-code/legible.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
{
"pass": true,
"width": 800,
"height": 320,
"phoneWidth": 400,
"frame0ShowsAllStageLabels": true,
"stageLabelsChecked": 4,
"captions": [
{
"step": 1,
"caption": "declare duration and fps in meta",
"words": 6,
"chars": 32,
"windowSeconds": 2.5,
"requiredSeconds": 2.3,
"passReadingTime": true,
"contrastRatio": 14.25,
"passContrast": true,
"minEdgeMarginPx": 37,
"phoneFontPx": 6.5,
"passMobileWidth": true,
"pass": true
},
{
"step": 2,
"caption": "pass normalized phase to render()",
"words": 5,
"chars": 33,
"windowSeconds": 2.5,
"requiredSeconds": 2,
"passReadingTime": true,
"contrastRatio": 14.25,
"passContrast": true,
"minEdgeMarginPx": 37,
"phoneFontPx": 6.5,
"passMobileWidth": true,
"pass": true
},
{
"step": 3,
"caption": "convert phase to integer cycles",
"words": 5,
"chars": 31,
"windowSeconds": 2.5,
"requiredSeconds": 2,
"passReadingTime": true,
"contrastRatio": 14.25,
"passContrast": true,
"minEdgeMarginPx": 37,
"phoneFontPx": 6.5,
"passMobileWidth": true,
"pass": true
},
{
"step": 4,
"caption": "last frame meets frame 0 cleanly",
"words": 6,
"chars": 32,
"windowSeconds": 2.5,
"requiredSeconds": 2.3,
"passReadingTime": true,
"contrastRatio": 14.25,
"passContrast": true,
"minEdgeMarginPx": 37,
"phoneFontPx": 6.5,
"passMobileWidth": true,
"pass": true
}
],
"reasons": []
}
Binary file added gallery/api-pipeline-code/loop.gif
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 gallery/api-pipeline-code/poster.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading