mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 03:06:41 +00:00
docs(cli,skills): teach check as the canonical verification gate
Scaffolded projects' npm run check now invokes the single check command instead of chaining lint, validate, and inspect (three Chrome boots become one). The CLI skill, its correctness reference, the entry skill's capability map, README/docs catalog rows, the Mintlify CLI page (new check section, deprecation banner on inspect), template CLAUDE/AGENTS (byte-identical), root CLAUDE/AGENTS, and every creation-workflow skill that taught the old sequence all point at check. snapshot keeps its standalone sections; validate/inspect stay documented as deprecated aliases with their check equivalents.
This commit is contained in:
Miguel Angel Simon Sierra
@@ -51,7 +51,7 @@ After creating or editing any `.html` composition:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint # Static HTML structure check
|
||||
npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets)
|
||||
npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
|
||||
```
|
||||
|
||||
Both must pass before previewing or considering work complete.
|
||||
|
||||
@@ -39,7 +39,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
|
||||
- `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion.
|
||||
- `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.
|
||||
- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk.
|
||||
- `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
|
||||
- `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
|
||||
- `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream.
|
||||
- `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.
|
||||
|
||||
@@ -81,7 +81,7 @@ After creating or editing any `.html` composition:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint # Static HTML structure check
|
||||
npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets)
|
||||
npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
|
||||
```
|
||||
|
||||
Both must pass before previewing or considering work complete.
|
||||
|
||||
@@ -90,7 +90,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
|
||||
| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. |
|
||||
| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. |
|
||||
| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
|
||||
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). |
|
||||
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). |
|
||||
| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. |
|
||||
| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
|
||||
|
||||
|
||||
@@ -141,7 +141,7 @@ Not everything belongs in the registry. The bar is production quality.
|
||||
<Step title="Validate">
|
||||
```bash
|
||||
hyperframes lint
|
||||
hyperframes validate
|
||||
hyperframes check
|
||||
npx oxfmt your-block.html
|
||||
```
|
||||
</Step>
|
||||
|
||||
@@ -165,7 +165,7 @@ Three checks before delivery:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint # static HTML structure checks
|
||||
npx hyperframes validate # loads in headless Chrome, catches runtime errors
|
||||
npx hyperframes check # one browser session: runtime errors, layout, motion, contrast
|
||||
npx hyperframes snapshot my-video --at 2.9,10.4 # PNGs at beat midpoints
|
||||
```
|
||||
|
||||
|
||||
@@ -268,7 +268,7 @@ Things that cause friction (or wrong output):
|
||||
- **Don't ask for React / Vue components.** Hyperframes compositions are plain HTML with `data-*` attributes and a GSAP timeline. Asking for "a React component for the intro" forces the agent to translate later.
|
||||
- **Don't ask for 4K or 60fps unless you need it.** Defaults (1920×1080, 30fps) render fast and look great. Higher specs slow rendering meaningfully.
|
||||
- **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.).
|
||||
- **Don't paste long error logs into the prompt without context.** Run `npx hyperframes lint` and `npx hyperframes validate` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems).
|
||||
- **Don't paste long error logs into the prompt without context.** Run `npx hyperframes check` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems).
|
||||
- **Don't assume the agent knows your assets.** Mention file paths explicitly (`assets/intro.mp4`, `assets/logo.png`) — the agent will check what's there but a hint speeds it up.
|
||||
|
||||
## Recommended workflow
|
||||
|
||||
@@ -99,7 +99,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
|
||||
| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. |
|
||||
| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. |
|
||||
| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
|
||||
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). |
|
||||
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). |
|
||||
| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. |
|
||||
| `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ Before showing or rendering a project:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
npx hyperframes render --quality standard --output review.mp4
|
||||
```
|
||||
|
||||
@@ -174,8 +174,8 @@ I moved the hero title and resized the CTA manually in Studio. Inspect the chang
|
||||
| `npx hyperframes capture https://example.com` | Capture a website as source material for a video |
|
||||
| `npx hyperframes preview` | Open the live Studio preview |
|
||||
| `npx hyperframes lint` | Catch structural mistakes before preview or render |
|
||||
| `npx hyperframes validate` | Run the composition in headless Chrome to catch runtime errors |
|
||||
| `npx hyperframes inspect` | Find text overflow and layout problems across the timeline |
|
||||
| `npx hyperframes check` | Run the composition in headless Chrome to catch runtime errors |
|
||||
| `npx hyperframes check` | Find text overflow and layout problems across the timeline |
|
||||
| `npx hyperframes snapshot --at 1,3,5` | Save PNG checks at exact timestamps |
|
||||
| `npx hyperframes render --output final.mp4` | Render the video |
|
||||
| `npx hyperframes publish` | Upload the project and get a shareable HyperFrames URL |
|
||||
@@ -278,9 +278,9 @@ For editor-facing changes, keep `npx hyperframes preview` running, then have the
|
||||
| --- | --- |
|
||||
| Preview will not start | `npx hyperframes doctor` |
|
||||
| Port already in use | `npx hyperframes preview --port 4567` |
|
||||
| Render fails | `npx hyperframes lint` then `npx hyperframes validate` |
|
||||
| Render fails | `npx hyperframes lint` then `npx hyperframes check` |
|
||||
| Need exact frame checks | `npx hyperframes snapshot --at 1,2.5,5` |
|
||||
| Text overflows in the frame | `npx hyperframes inspect` |
|
||||
| Text overflows in the frame | `npx hyperframes check` |
|
||||
| Final render is too slow | Try `--quality draft`, reduce image sizes, or lower `--fps` |
|
||||
| Need to share editable project | `npx hyperframes publish` |
|
||||
|
||||
|
||||
@@ -520,6 +520,34 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o
|
||||
|
||||
The linter detects missing attributes, missing adapter libraries (GSAP, Lottie, Three.js), structural problems, and more. See [Common Mistakes](/guides/common-mistakes) for details on each rule.
|
||||
|
||||
### `check`
|
||||
|
||||
The browser verification gate: everything the old `validate` → `inspect` → `snapshot` loop did, in **one** command with one browser session:
|
||||
|
||||
```bash
|
||||
npx hyperframes check [dir]
|
||||
npx hyperframes check [dir] --json # {ok, lint, runtime, layout, motion, contrast, snapshots}
|
||||
npx hyperframes check [dir] --snapshots # annotated overview frames + per-finding crops
|
||||
npx hyperframes check [dir] --at 1.5,4,7.25
|
||||
npx hyperframes check [dir] --strict # exit non-zero on warnings too
|
||||
```
|
||||
|
||||
`check` runs the linter first (browser skipped entirely on lint errors), then loads the bundled composition once and sweeps one seek grid running every audit per sample: runtime console errors and failed requests, layout defects (overflow, clipping, held overlaps, occlusion), `*.motion.json` sidecar assertions, and WCAG AA contrast.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--json` | Aggregated machine-readable envelope; every finding carries selector, `data-*` identity, source file, bbox, and sample time |
|
||||
| `--snapshots` | Write overview frames (annotated with labeled finding boxes when there are errors) plus `finding-NN-<code>.png` crops |
|
||||
| `--samples` / `--at` / `--at-transitions` | Control the seek grid (default 9 samples; `--at-transitions` adds tween boundaries) |
|
||||
| `--tolerance` | Allowed overflow in px before reporting (default 2) |
|
||||
| `--timeout` | Initial settle budget in ms (default 3000) |
|
||||
| `--no-contrast` | Skip the WCAG audit while iterating |
|
||||
| `--strict` | Exit non-zero on warnings too (default: only errors) |
|
||||
| `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` | Opt-in band gate: flags content whose center sits inside the fractional band (optional `severity`, `seek`) |
|
||||
| `--frame-check` | Opt-in media out-of-frame detection (img/svg/video/canvas) |
|
||||
|
||||
Contrast failures are **errors** and include the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color. Severity is persistence-aware: single-sample transients demote to info, held findings gate the exit code, and a frozen timeline on a 3s+ composition fails with `sweep_static`.
|
||||
|
||||
### `beats`
|
||||
|
||||
Detect the beats in a composition's music track and write them to a beat file the Studio uses to draw beat guides on the timeline:
|
||||
@@ -549,6 +577,8 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o
|
||||
|
||||
### `inspect`
|
||||
|
||||
<Warning>Deprecated: use [`check`](#check) — it covers this layout sweep plus runtime, motion, and contrast in one browser session. `inspect` keeps working and marks `_meta.deprecated: true` in JSON output.</Warning>
|
||||
|
||||
Inspect rendered visual layout across the composition timeline:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -50,8 +50,7 @@ describe("hyperframes init flag rename", () => {
|
||||
expect(pkg.type).toBe("module");
|
||||
expect(pkg.scripts).toMatchObject({
|
||||
dev: "npx --yes hyperframes preview",
|
||||
check:
|
||||
"npx --yes hyperframes lint && npx --yes hyperframes validate && npx --yes hyperframes inspect",
|
||||
check: "npx --yes hyperframes check",
|
||||
render: "npx --yes hyperframes render",
|
||||
publish: "npx --yes hyperframes publish",
|
||||
});
|
||||
@@ -84,8 +83,7 @@ describe("hyperframes init flag rename", () => {
|
||||
};
|
||||
expect(pkg.scripts).toMatchObject({
|
||||
dev: "npx --yes hyperframes preview",
|
||||
check:
|
||||
"npx --yes hyperframes lint && npx --yes hyperframes validate && npx --yes hyperframes inspect",
|
||||
check: "npx --yes hyperframes check",
|
||||
render: "npx --yes hyperframes render",
|
||||
publish: "npx --yes hyperframes publish",
|
||||
});
|
||||
|
||||
@@ -224,9 +224,7 @@ function hyperframesScript(command: string): string {
|
||||
function buildPackageScripts(): Record<string, string> {
|
||||
return {
|
||||
dev: hyperframesScript("preview"),
|
||||
check:
|
||||
`${hyperframesScript("lint")} && ${hyperframesScript("validate")} && ` +
|
||||
`${hyperframesScript("inspect")}`,
|
||||
check: hyperframesScript("check"),
|
||||
render: hyperframesScript("render"),
|
||||
publish: hyperframesScript("publish"),
|
||||
};
|
||||
|
||||
@@ -33,7 +33,7 @@ The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-
|
||||
|
||||
```bash
|
||||
npm run dev # start the preview server (long-running — keep it alive in background)
|
||||
npm run check # lint + validate + inspect
|
||||
npm run check # lint + runtime + layout + motion + contrast (one command)
|
||||
npm run render # render to MP4
|
||||
npm run publish # publish and get a shareable link
|
||||
npx hyperframes lint --verbose # include info-level findings
|
||||
@@ -76,7 +76,7 @@ After creating or editing any `.html` composition, **always** run the full check
|
||||
npm run check
|
||||
```
|
||||
|
||||
Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering.
|
||||
Fix all errors before presenting the result. Warnings should be reviewed before rendering.
|
||||
|
||||
## Key Rules
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-
|
||||
|
||||
```bash
|
||||
npm run dev # start the preview server (long-running — keep it alive in background)
|
||||
npm run check # lint + validate + inspect
|
||||
npm run check # lint + runtime + layout + motion + contrast (one command)
|
||||
npm run render # render to MP4
|
||||
npm run publish # publish and get a shareable link
|
||||
npx hyperframes lint --verbose # include info-level findings
|
||||
@@ -76,7 +76,7 @@ After creating or editing any `.html` composition, **always** run the full check
|
||||
npm run check
|
||||
```
|
||||
|
||||
Fix all errors before presenting the result. Inspect warnings should be reviewed before rendering.
|
||||
Fix all errors before presenting the result. Warnings should be reviewed before rendering.
|
||||
|
||||
## Key Rules
|
||||
|
||||
|
||||
+16
-16
@@ -6,43 +6,43 @@
|
||||
"files": 144
|
||||
},
|
||||
"faceless-explainer": {
|
||||
"hash": "09bc257e79dabebc",
|
||||
"hash": "a09191a97564b114",
|
||||
"files": 18
|
||||
},
|
||||
"figma": {
|
||||
"hash": "99538ee56a4ca553",
|
||||
"hash": "0e6e96f5a76ff824",
|
||||
"files": 2
|
||||
},
|
||||
"general-video": {
|
||||
"hash": "67f3dae100541eed",
|
||||
"hash": "1aed9f4f68414a45",
|
||||
"files": 1
|
||||
},
|
||||
"hyperframes": {
|
||||
"hash": "132596767485f923",
|
||||
"hash": "fce43b4c3355cde9",
|
||||
"files": 1
|
||||
},
|
||||
"hyperframes-animation": {
|
||||
"hash": "16ecdf00cf5cebf1",
|
||||
"hash": "b982a1af9821e326",
|
||||
"files": 99
|
||||
},
|
||||
"hyperframes-cli": {
|
||||
"hash": "9544d2cee786ebaf",
|
||||
"hash": "f1c8c70693101e59",
|
||||
"files": 7
|
||||
},
|
||||
"hyperframes-core": {
|
||||
"hash": "511a6283a5dbd7ea",
|
||||
"hash": "507aecd0bb312a94",
|
||||
"files": 14
|
||||
},
|
||||
"hyperframes-creative": {
|
||||
"hash": "d60c84ddca9ea6db",
|
||||
"hash": "3e5bcbf46dc14427",
|
||||
"files": 69
|
||||
},
|
||||
"hyperframes-keyframes": {
|
||||
"hash": "555c0cd491c40cea",
|
||||
"hash": "040453e302a0e15b",
|
||||
"files": 3
|
||||
},
|
||||
"hyperframes-registry": {
|
||||
"hash": "e3b389526834109d",
|
||||
"hash": "5f49178cc43e100b",
|
||||
"files": 10
|
||||
},
|
||||
"media-use": {
|
||||
@@ -50,19 +50,19 @@
|
||||
"files": 122
|
||||
},
|
||||
"motion-graphics": {
|
||||
"hash": "0f1ac928e387a74c",
|
||||
"hash": "dafcdce07d221aa4",
|
||||
"files": 23
|
||||
},
|
||||
"music-to-video": {
|
||||
"hash": "5bb405421a7e19ba",
|
||||
"hash": "ccb6181af8bcef09",
|
||||
"files": 132
|
||||
},
|
||||
"pr-to-video": {
|
||||
"hash": "a93fde2b33b26e75",
|
||||
"hash": "21dcf8aa94fc1033",
|
||||
"files": 22
|
||||
},
|
||||
"product-launch-video": {
|
||||
"hash": "14404973ef5d38a0",
|
||||
"hash": "158398dbfc4ab652",
|
||||
"files": 20
|
||||
},
|
||||
"remotion-to-hyperframes": {
|
||||
@@ -70,7 +70,7 @@
|
||||
"files": 70
|
||||
},
|
||||
"slideshow": {
|
||||
"hash": "114b57cf22b39068",
|
||||
"hash": "0f0364c54f77cb9b",
|
||||
"files": 2
|
||||
},
|
||||
"talking-head-recut": {
|
||||
@@ -78,7 +78,7 @@
|
||||
"files": 27
|
||||
},
|
||||
"website-to-video": {
|
||||
"hash": "79af52a847abaa43",
|
||||
"hash": "e8143700c50b7469",
|
||||
"files": 32
|
||||
}
|
||||
}
|
||||
|
||||
@@ -177,9 +177,9 @@ Inject transitions, run checks, pause for review, then render.
|
||||
|
||||
`npx hyperframes lint`
|
||||
|
||||
`npx hyperframes validate`
|
||||
`npx hyperframes check`
|
||||
|
||||
`npx hyperframes inspect`
|
||||
`npx hyperframes check`
|
||||
|
||||
`npx hyperframes snapshot --at <frame-midpoints>`
|
||||
|
||||
|
||||
@@ -95,7 +95,7 @@ No REST equivalent exists. You drive the MCP tools, then hand output to the pure
|
||||
2b. **Validate against ground truth before calling it done — mandatory**: `export_video` on the cohort's `rootNodeId` gives Figma's own render of the timeline. Run `node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y` — it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR (calibrated: faithful ≈ 20+, diverging ≈ 5). Measure `--crop` from the render's actual card edges, don't guess. FAIL means re-check the translation, not the threshold.
|
||||
3. `motionToGsap(doc)` → `emitTimelineScript(spec)` → inject as a `<script>` after the GSAP + CustomEase CDN tags. Paused, finite, registered on `window.__timelines` with a literal key.
|
||||
4. Untranslatable track (shader-driven, unsupported prop, complex masks) → bake: `export_video` → freeze MP4 → embed as `<video class="clip">`. Exception: shader-driven tracks — figma's export path flattens shaders to the base color (see Shaders below), so a bake there silently loses the shader; ask the user for a native figma export instead. Always say which path you used and why. Named eases outside the mapped set fall back to linear — the mapping table lives in `motionEase.ts`; flag the fallback to the user when it fires.
|
||||
5. Run `npx hyperframes lint && npx hyperframes validate` before calling it done.
|
||||
5. Run `npx hyperframes check` before calling it done.
|
||||
|
||||
## Shaders (Phase 5 — mostly manual)
|
||||
|
||||
|
||||
@@ -136,9 +136,9 @@ Then read `audio_meta.json`: mount each `voices[].path` + (`bgm.path`, `sfx[]`)
|
||||
|
||||
## Output checklist → `hyperframes-cli`
|
||||
|
||||
- [ ] `npx hyperframes lint` and `npx hyperframes validate` pass (block on results)
|
||||
- [ ] `npx hyperframes check` pass (block on results)
|
||||
- [ ] design adherence verified if a spec (`frame.md` / `design.md`) exists — checklist in `hyperframes-creative/references/design-adherence.md`
|
||||
- [ ] `npx hyperframes inspect` passes, or every overflow is intentionally marked
|
||||
- [ ] `npx hyperframes check` passes, or every overflow is intentionally marked
|
||||
- [ ] contrast warnings addressed; for multi-scene work, review the animation map (`hyperframes-animation/scripts/animation-map.mjs`)
|
||||
- [ ] deliver the preview; render to MP4 only on explicit request
|
||||
- [ ] surface the preview **only at handoff** (it is the stable, final preview); don't pop one mid-build — build-phase snapshots are headless
|
||||
|
||||
@@ -105,7 +105,7 @@ After editing a composition that uses Anime.js:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
## Credits And References
|
||||
|
||||
@@ -132,7 +132,7 @@ After editing CSS animation compositions:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
## Credits And References
|
||||
|
||||
@@ -105,7 +105,7 @@ After editing a Lottie composition:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
## Credits And References
|
||||
|
||||
@@ -120,7 +120,7 @@ After editing a Three.js composition:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
## Credits And References
|
||||
|
||||
@@ -90,7 +90,7 @@ After editing a WAAPI composition:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
## Credits And References
|
||||
|
||||
@@ -325,4 +325,4 @@ For a single kinetic phrase that "zooms past," keep the streak slightly visible
|
||||
- `/hyperframes-animation` — `out`-family easing, proxy-driven `onUpdate` attribute tweens, and locked-envelope coordination (`../../adapters/gsap-easing-and-stagger.md`)
|
||||
- `/hyperframes-creative` — `references/typography.md` (embedded display face for a text streak), `references/video-composition.md` (solid field behind the smear)
|
||||
- `/hyperframes-core` — composition wiring, determinism (finite tweens, no `Math.random`)
|
||||
- `/hyperframes-cli` — `hyperframes lint` / `hyperframes validate` (validate catches a missing `#streak-blur` node or an unreferenced filter)
|
||||
- `/hyperframes-cli` — `hyperframes lint` / `hyperframes check` (validate catches a missing `#streak-blur` node or an unreferenced filter)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: hyperframes-cli
|
||||
description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, compare, grade-compare, preview, play, render, publish, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies / sites`).
|
||||
description: HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, render, publish, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background (validate/inspect/layout are deprecated aliases covered by check), or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies / sites`).
|
||||
---
|
||||
|
||||
# HyperFrames CLI
|
||||
@@ -11,18 +11,17 @@ Everything runs through `npx hyperframes` unless project instructions specify a
|
||||
|
||||
1. **Scaffold** — `npx hyperframes init my-video` (or `capture` from a URL). `init` also checks the installed skills against the latest on GitHub and updates the global set if any are out of date. The `--skip-skills` flag is currently neutered (temporary, while the skills.sh registry catches up), so every `init` runs this check and pulls our latest skills regardless.
|
||||
2. **Write** — author HTML composition (see the `hyperframes-core` skill)
|
||||
3. **Lint** — `npx hyperframes lint`
|
||||
4. **Validate** — `npx hyperframes validate` (runtime errors + contrast)
|
||||
5. **Visual inspect** — `npx hyperframes inspect`
|
||||
6. **Preview / edit** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
|
||||
7. **Render** — pick the variant:
|
||||
3. **Lint** — `npx hyperframes lint` (static, fast — run it early while iterating)
|
||||
4. **Check** — `npx hyperframes check` (the browser gate; add `--snapshots` for annotated frames + per-finding crops)
|
||||
5. **Preview / edit** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
|
||||
6. **Render** — pick the variant:
|
||||
- Iterate: `npx hyperframes render --quality draft`
|
||||
- Deliver: `npx hyperframes render --quality high --output out.mp4`
|
||||
- CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
|
||||
- Cloud (long / large): `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
|
||||
8. **Report feedback** — after verifying the output, `npx hyperframes feedback --rating <1-5> --comment "..."` once per task (see Agent Conventions).
|
||||
7. **Report feedback** — after verifying the output, `npx hyperframes feedback --rating <1-5> --comment "..."` once per task (see Agent Conventions).
|
||||
|
||||
Run lint, validate, and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `validate` loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. `inspect` seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas — and, when a `*.motion.json` sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.
|
||||
Run `check` before preview. It runs the linter first (and skips the browser entirely on lint errors), then does everything the old validate → inspect → snapshot sequence did in **one** browser session and one seek pass: runtime console errors and failed requests, layout defects (text spilling out of bubbles/containers or off canvas, held overlaps, occlusion), motion-sidecar verification (`*.motion.json` — entrances under seek, stagger order, in-frame, liveness), and WCAG contrast. Contrast failures are errors and carry the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color, so most contrast fixes need no screenshot. Every finding carries a selector, `data-*` identity, composition source file, bbox, and sample time — jump straight to the HTML. Single-sample transients demote to info; findings held across samples gate the exit code (`--strict` gates warnings too). `validate`, `inspect`, and `layout` still work but are deprecated aliases of parts of `check`.
|
||||
|
||||
For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec. To compare agent-authored candidate variants, use `npx hyperframes compare <path...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json]` to render each composition through its own runtime, assemble one labeled sheet, inspect it side by side, and choose. For color-grade selection, use the color-specific sibling `npx hyperframes grade-compare --for <frame> --grades grades.json` (or `--luts a.cube,b.cube`) to render every grading candidate through the real WebGL grading runtime into one labeled PNG before choosing the winner.
|
||||
|
||||
@@ -34,6 +33,7 @@ Cross-cutting rules that hold for every command:
|
||||
- **`doctor --json` always exits 0**, even when the environment is broken. Gate on the payload's `ok` field: `npx hyperframes doctor --json | jq -e '.ok' > /dev/null`. This insulates pipelines from CLI release churn.
|
||||
- **Non-TTY mode is auto-detected.** When `stdout` is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; `init` then **requires `--example`**. Pass `--non-interactive` to force this mode even on a TTY.
|
||||
- **CI gating on render**: `--strict` fails on lint errors, `--strict-all` fails on warnings too, `--strict-variables` fails on undeclared `--variables` keys.
|
||||
- **Correlate a verify loop with `HYPERFRAMES_RUN_ID`.** Orchestrators driving the CLI per task/design element should set this env var once per unit of work; every command invocation attaches it to telemetry, and `check` emits a per-gate breakdown, making roundtrips-per-task measurable.
|
||||
- **Paths in `--json` are redacted** — `$HOME` becomes the literal `$HOME` so output is safe to paste into bug reports and agent contexts.
|
||||
- **Render is user-gated.** Never auto-render once the checks pass. Pause at `preview`, tell the user the video is editable in Studio, and render only after they approve.
|
||||
- **Use Studio context for user-directed edits.** When the user says "this selected element", "the thing I clicked", "current selection", or similar, ask them to select it in Studio, then run `npx hyperframes preview --context --json --context-fields selection`. Use the returned `selection.target.hfId` / `selector`, `selection.sourceFile`, `selection.currentTime`, and `selection.thumbnailUrl` to anchor the edit. If `selection` is `null` and `errors.selection.code` is `no-selection`, ask the user to click the element and rerun; do not guess from screenshots.
|
||||
@@ -46,7 +46,7 @@ Cross-cutting rules that hold for every command:
|
||||
| Want to… | Read |
|
||||
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
||||
| Scaffold a project (`init`, `capture`, `skills`) | `references/init-and-scaffold.md` |
|
||||
| Check correctness (`lint`, `validate`, `inspect`, `snapshot`) | `references/lint-validate-inspect.md` |
|
||||
| Check correctness (`lint`, `check`, `snapshot`, deprecated `validate`/`inspect`) | `references/lint-validate-inspect.md` |
|
||||
| Preview or render (`preview`, `play`, `render`, `publish`) | `references/preview-render.md` |
|
||||
| Diagnose the environment (`doctor`, `browser`) | `references/doctor-browser.md` |
|
||||
| Cloud render on AWS Lambda (`lambda deploy / sites / render / progress / destroy / policies`) | `references/lambda.md` |
|
||||
@@ -75,18 +75,15 @@ See `references/lambda.md` for prerequisites, all 6 subcommands (`deploy`, `site
|
||||
|
||||
## Minimum Completion Gate
|
||||
|
||||
### Static gates
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
Add `inspect` for layout-sensitive work and `render --strict` in CI to fail on lint errors.
|
||||
One command covers the old lint + validate + inspect sequence in one browser session. Add `--strict` to gate warnings and `render --strict` in CI to fail on lint errors. `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` and `--frame-check` add opt-in band/bounds gates for pipelines that need them.
|
||||
|
||||
### Visual smoke test — required when the project uses sub-compositions
|
||||
|
||||
`lint` / `validate` / `inspect` evaluate each composition **in isolation**. They never load `index.html` and mount sub-compositions via `data-composition-src`, so they cannot catch cross-file mount failures (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The only gate that catches them is one that actually loads `index.html` and seeks the timeline.
|
||||
The audits evaluate the bundled composition; they cannot catch every cross-file mount failure when `index.html` mounts sub-compositions via `data-composition-src` (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The gate that catches those is one that actually loads `index.html` the way `render` does and seeks the timeline.
|
||||
|
||||
Use `hyperframes snapshot` — it loads the project the same way `render` does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:
|
||||
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# lint, validate, inspect, snapshot
|
||||
# lint, check, snapshot
|
||||
|
||||
The correctness pipeline. Run in this order: `lint` (static, fast) → `validate` (runtime, headless Chrome) → `inspect` (layout sweep). `snapshot` is a separate utility for capturing still frames.
|
||||
The correctness pipeline: `lint` (static, fast) while iterating, then `check` (one browser session: runtime + layout + motion + contrast) as the gate. `snapshot` is the standalone utility for capturing still frames and zoomed crops. `validate`, `inspect`, and `layout` still run but are deprecated: `check` covers all of them in one invocation.
|
||||
|
||||
## Discipline (motion-heavy work)
|
||||
|
||||
When the composition is animation-driven, run the checks before you reach for `preview` or `render`:
|
||||
|
||||
- Run `lint` after the first HTML pass — earlier, not later.
|
||||
- Capture `snapshot` at meaningful timeline states; look at the PNGs.
|
||||
- Inspect snapshots _before_ tuning automated warnings — your eye catches what the auditor misses.
|
||||
- Treat layout warnings as defects unless a snapshot proves the overflow is intentional, in which case mark it with `data-layout-allow-overflow`.
|
||||
- State motion intent in a `*.motion.json` sidecar so `inspect` checks it automatically — entrances firing under seek, stagger order, in-frame, liveness. This is the closest automated proxy for "watch the MP4" and catches render-≠-preview bugs the eye misses (see **Motion verification** below).
|
||||
- Run `lint` after the first HTML pass, earlier rather than later.
|
||||
- Run `check --snapshots` at the first full pass: the overview frames and per-finding crops show you what the auditor saw.
|
||||
- Look at the PNGs before tuning automated warnings: your eye catches what the auditor misses, and the auditor catches what your eye misses.
|
||||
- Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion`.
|
||||
- State motion intent in a `*.motion.json` sidecar so `check` verifies it automatically (entrances firing under seek, stagger order, in-frame, liveness). This is the closest automated proxy for "watch the MP4" and catches render-vs-preview bugs the eye misses (see **Motion verification** below).
|
||||
|
||||
## lint
|
||||
|
||||
@@ -21,9 +21,9 @@ npx hyperframes lint --verbose # info-level findings
|
||||
npx hyperframes lint --json # machine-readable
|
||||
```
|
||||
|
||||
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). Catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, and unregistered timelines.
|
||||
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). Catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, unregistered timelines, and GSAP/CSS transform conflicts.
|
||||
|
||||
**Blind spot — media inside a sub-composition (not yet a lint rule).** A `<video>`/`<audio>` inside a `compositions/*.html` `<template>` (or nested in a wrapper `<div>` anywhere) is never seeked/decoded and renders blank/black; `lint`/`validate`/`inspect` all pass. Media must be a direct child of the host root (`index.html`) — see `hyperframes-core` → `variables-and-media.md`. Until a rule exists, check manually before render:
|
||||
**Blind spot — media inside a sub-composition (not yet a lint rule).** A `<video>`/`<audio>` inside a `compositions/*.html` `<template>` (or nested in a wrapper `<div>` anywhere) is never seeked/decoded and renders blank/black; the automated checks all pass. Media must be a direct child of the host root (`index.html`) — see `hyperframes-core` → `variables-and-media.md`. Until a rule exists, check manually before render:
|
||||
|
||||
```bash
|
||||
grep -nE '<(video|audio)\b' compositions/*.html # expect NO matches; media belongs in index.html
|
||||
@@ -31,63 +31,56 @@ grep -nE '<(video|audio)\b' compositions/*.html # expect NO matches; media bel
|
||||
|
||||
A non-empty result is a defect. Then `snapshot` each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a bug, not a placeholder — treat it as render-blocking).
|
||||
|
||||
## validate
|
||||
## check
|
||||
|
||||
```bash
|
||||
npx hyperframes validate # current directory
|
||||
npx hyperframes validate ./my-project # specific project
|
||||
npx hyperframes validate --json # agent-readable findings
|
||||
npx hyperframes validate --timeout 5000 # ms to wait for scripts (default 3000)
|
||||
npx hyperframes validate --no-contrast # skip WCAG contrast audit while iterating
|
||||
npx hyperframes check # current directory: the full browser gate
|
||||
npx hyperframes check ./my-project # specific project
|
||||
npx hyperframes check --json # agent-readable envelope {ok, lint, runtime, layout, motion, contrast, snapshots}
|
||||
npx hyperframes check --snapshots # also write overview frames (annotated) + per-finding crops
|
||||
npx hyperframes check --samples 15 # denser timeline sweep (default 9)
|
||||
npx hyperframes check --at 1.5,4,7.25 # explicit hero-frame timestamps
|
||||
npx hyperframes check --at-transitions # also sample every tween start/end boundary
|
||||
npx hyperframes check --tolerance 4 # allowed overflow px before reporting (default 2)
|
||||
npx hyperframes check --timeout 5000 # ms for the initial settle (default 3000)
|
||||
npx hyperframes check --no-contrast # skip the WCAG audit while iterating
|
||||
npx hyperframes check --strict # exit non-zero on warnings too (default: only errors)
|
||||
```
|
||||
|
||||
Static lint is fast but blind to runtime failures. `validate` loads the composition in headless Chrome, plays through it, and reports:
|
||||
One command, one Chrome boot. `check` runs the linter first and skips the browser entirely when lint reports errors. Then it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample:
|
||||
|
||||
- JavaScript console errors and unhandled exceptions
|
||||
- Failed network requests (media-file `ERR_ABORTED` filtered out)
|
||||
- WCAG AA contrast violations on visible text — sampled at 5 timestamps across the timeline. Disable with `--no-contrast`.
|
||||
- **Runtime**: JavaScript console errors, unhandled exceptions, failed network requests (media-file `ERR_ABORTED` filtered out), HTTP 4xx/5xx.
|
||||
- **Layout**: text extending outside its container or the canvas, text clipped by its own box, held text overlaps and occlusion (with an approximate covered fraction), children escaping clipping containers.
|
||||
- **Motion**: `*.motion.json` sidecar assertions against the same seeked timeline (see below).
|
||||
- **Contrast**: WCAG AA on visible text, sampled at 5 grid points. Failures are **errors** and each finding carries the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color in the same palette direction, so most contrast fixes need no screenshot at all.
|
||||
|
||||
**Fixing contrast warnings** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold):
|
||||
Every finding carries a selector, the element's `data-*` identity, the composition source file, a bbox, and the sample time: jump straight from the JSON to the HTML you must edit and re-run.
|
||||
|
||||
- On dark backgrounds, brighten the failing color until it clears the threshold; on light backgrounds, darken it.
|
||||
- Stay within the palette family — don't invent a new color, adjust the existing one.
|
||||
- Re-run `validate` until clean.
|
||||
**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, and a held `content_overlap` is an error. If a 3s+ composition shows zero geometry change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass.
|
||||
|
||||
Run `validate` before `inspect` when an animation has scripts, fetched data, or theming. Combine with `render --strict` in CI.
|
||||
**Escape hatches** (mark intent in the HTML, then re-run):
|
||||
|
||||
## inspect
|
||||
- `data-layout-allow-overflow` — overflow is intentional (entrance/exit travel).
|
||||
- `data-layout-allow-overlap` — deliberate text layering (e.g. a demo cursor label over a heading).
|
||||
- `data-layout-allow-occlusion` — an element is meant to cover text.
|
||||
- `data-layout-ignore` — decorative element that should never be audited.
|
||||
|
||||
**Opt-in pipeline gates** (used by orchestrators; off by default):
|
||||
|
||||
```bash
|
||||
npx hyperframes inspect # inspect rendered layout over the timeline
|
||||
npx hyperframes inspect ./my-project # specific project
|
||||
npx hyperframes inspect --json # agent-readable findings (schemaVersion, samples, issues, bboxes)
|
||||
npx hyperframes inspect --samples 15 # denser timeline sweep (default 9)
|
||||
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
|
||||
npx hyperframes inspect --tolerance 4 # allowed overflow in px before reporting (default 2)
|
||||
npx hyperframes inspect --strict # exit non-zero on warnings too (default: only errors)
|
||||
npx hyperframes check --caption-zone "x0=0;y0=.82;x1=1;y1=1;severity=error;seek=.25,1"
|
||||
npx hyperframes check --frame-check # media (img/svg/video/canvas) out-of-frame detection
|
||||
```
|
||||
|
||||
Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
|
||||
`--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags content whose center sits inside the band. `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
|
||||
|
||||
- Text extending outside the nearest visual container or bubble
|
||||
- Text clipped by its own fixed-width/fixed-height box
|
||||
- Text extending outside the composition canvas
|
||||
- Children escaping clipping containers
|
||||
**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply it or adjust within the palette family, then re-run `check`.
|
||||
|
||||
Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows.
|
||||
## Motion verification (`*.motion.json` sidecar)
|
||||
|
||||
**Escape hatches:**
|
||||
`check` verifies **motion intent** against the same seeked timeline the renderer uses — the closest automated proxy for "render the MP4 and watch it". It catches render-vs-preview bugs layout sampling can't: an entrance reveal the seek lands past, a broken stagger order, an element drifting off-frame mid-tween, a frozen shot.
|
||||
|
||||
- `data-layout-allow-overflow` — mark an element or ancestor when overflow is intentional for an entrance/exit animation.
|
||||
- `data-layout-ignore` — mark a decorative element that should never be audited.
|
||||
|
||||
`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
|
||||
|
||||
### Motion verification (`*.motion.json` sidecar)
|
||||
|
||||
`inspect` also checks **motion intent** against the same seeked timeline the renderer uses — the closest automated proxy for "render the MP4 and watch it". It catches render-≠-preview bugs layout sampling can't: an entrance reveal the seek lands past, a broken stagger order, an element drifting off-frame mid-tween, a frozen shot.
|
||||
|
||||
Drop a `*.motion.json` sidecar next to the composition (matching the html basename when several compositions share a dir). `inspect` discovers it automatically — no flag, no authoring-framework changes. With no sidecar, `inspect` behaves exactly as before.
|
||||
Drop a `*.motion.json` sidecar next to the composition (matching the html basename when several compositions share a dir). `check` discovers it automatically — no flag, no authoring-framework changes. With no sidecar, `check` behaves exactly as before.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -108,7 +101,7 @@ Drop a `*.motion.json` sidecar next to the composition (matching the html basena
|
||||
| `staysInFrame(selector)` | once visible, its box leaves the canvas — `motion_off_frame` |
|
||||
| `keepsMoving(withinSelector?)` | a fully-static window exceeds `maxStaticSec` (default 2s) — `motion_frozen` |
|
||||
|
||||
`duration`, `withinSelector`, and `maxStaticSec` are optional. Findings are **errors by default** (a failed assertion fails the run, like a layout error — `--strict` still gates warnings) and appear in the same human and `--json` output as layout findings. A selector that matches nothing is reported as `motion_selector_missing` rather than silently passing — so a typo'd selector fails loudly. Use this in the feedback loop instead of eyeballing the render: assert what the motion is supposed to do, and let `inspect` tell you when the seek diverges from intent.
|
||||
`duration`, `withinSelector`, and `maxStaticSec` are optional. Findings are **errors by default** and appear in the same human and `--json` output as layout findings. A selector that matches nothing is reported as `motion_selector_missing` rather than silently passing — a typo'd selector fails loudly. Use this in the feedback loop instead of eyeballing the render: assert what the motion is supposed to do, and let `check` tell you when the seek diverges from intent.
|
||||
|
||||
## snapshot
|
||||
|
||||
@@ -118,7 +111,7 @@ npx hyperframes snapshot ./my-project # specific project
|
||||
npx hyperframes snapshot --frames 10 # evenly-spaced N frames
|
||||
```
|
||||
|
||||
Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory.
|
||||
Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory. Not deprecated: it remains the standalone capture utility, while `check --snapshots` covers the gate's needs (overview frames annotated with labeled finding boxes, plus `finding-NN-<code>.png` crops for every error finding with a bbox).
|
||||
|
||||
### Zooming into a reported finding
|
||||
|
||||
@@ -132,4 +125,13 @@ npx hyperframes snapshot --zoom "100,50,400,300" --zoom-scale 2 # or an exact
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
`--zoom` takes a CSS selector or an exact `x,y,w,h` pixel region and always produces a real high-density crop (a raised `deviceScaleFactor`, never CSS zoom or a viewport resize), so the composition's layout — and its render determinism — is untouched. A selector matching nothing is a loud error, not a silent full-frame fallback.
|
||||
`--zoom` takes a CSS selector or an exact `x,y,w,h` pixel region and always produces a real high-density crop (a raised `deviceScaleFactor`, never CSS zoom or a viewport resize), so the composition's layout — and its render determinism — is untouched. A selector matching nothing is a loud error, not a silent full-frame fallback, and a frame where the target has no visible box (collapsed or animated off-canvas) is skipped with a note instead of written as a sliver.
|
||||
|
||||
## Deprecated: validate, inspect, layout
|
||||
|
||||
All three keep working, print a deprecation notice on stderr, and mark `_meta.deprecated: true` in `--json`. Their functionality lives in `check`:
|
||||
|
||||
- `validate` (runtime errors + contrast) → `check` (contrast failures are now gating errors with fix payloads, not warnings).
|
||||
- `inspect` / `layout` (layout sweep + motion sidecar) → `check` (same flags: `--samples`, `--at`, `--at-transitions`, `--tolerance`, `--strict`).
|
||||
|
||||
Migrate scripts by replacing the sequence with the single `check` invocation; scaffolded projects' `npm run check` already points there.
|
||||
|
||||
@@ -73,8 +73,8 @@ Surfaced here; full rationale in the linked reference. Do not violate:
|
||||
Use `hyperframes-cli` for command details
|
||||
|
||||
- [ ] `npx hyperframes lint` passes (0 errors)
|
||||
- [ ] `npx hyperframes validate` passes (0 console errors)
|
||||
- [ ] `npx hyperframes inspect` passes (0 errors)
|
||||
- [ ] `npx hyperframes check` passes (0 console errors)
|
||||
- [ ] `npx hyperframes check` passes (0 errors)
|
||||
- [ ] Projects with sub-compositions: `npx hyperframes snapshot --at <midpoints>` and eyeball each frame
|
||||
- [ ] `npx hyperframes preview` for review (the user can edit anything in Studio's timeline)
|
||||
- [ ] `npx hyperframes render` only after the user approves
|
||||
|
||||
@@ -55,7 +55,7 @@ See `sub-compositions.md` for the full wiring pattern.
|
||||
|
||||
- `id="root"` — template convention used by scaffolds and the transition catalog so CSS can target the composition root with `#root` instead of `[data-composition-id="main"]`. Not required by the runtime, but consistent with the rest of the ecosystem.
|
||||
- `class="clip"` — required runtime visibility marker on visible timed elements (`<div>`, `<img>`, …). See Clip Attributes above.
|
||||
- `data-layout-allow-overflow` — tells `hyperframes inspect` that overflow on this element (or its descendants) is intentional. Notes:
|
||||
- `data-layout-allow-overflow` — tells `hyperframes check` that overflow on this element (or its descendants) is intentional. Notes:
|
||||
- `inspect` measures `getBoundingClientRect` at sampled timestamps, not rendered pixels — `overflow: hidden` clips the visual but does **not** suppress an `inspect` overflow finding. This attribute is the escape hatch; CSS overflow is not.
|
||||
- Can be set on the composition **root** as well as on any child. When the cited offender is `div.<comp>-root inside div.<comp>-root` (the root reports its own children's union as overflowing), the fix goes on the root, not on individual text descendants — shrinking font sizes will not converge.
|
||||
- In a multi-scene `group_wN.html` (continue runs), every scene-local element stays in the DOM during the other scenes' time windows; the layout-box union almost always overflows the canvas during morph seams. Mark the root and every scene-local primary/supporting element with this attribute **at construction**, not after `inspect` flags it.
|
||||
|
||||
@@ -104,9 +104,7 @@ v4 + render-mode footguns. Every bullet is a hard rule:
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes inspect
|
||||
npx hyperframes check
|
||||
|
||||
# Render proof — frame 0 must NOT flash unstyled content. Preview alone can hide this.
|
||||
npx hyperframes render . --workers 1 --quality draft --output tailwind-proof.mp4
|
||||
@@ -122,4 +120,4 @@ When Tailwind styles don't apply in a render, check in order:
|
||||
4. No v3 directives (`@tailwind base/components/utilities`) in the file?
|
||||
5. Tokens moved from `tailwind.config.js` to `@theme` (or `@config` reference for v3 migration)?
|
||||
6. Every render-critical class appears as a complete static token (no `bg-${color}-500` style assembly)?
|
||||
7. Re-run `npx hyperframes validate`, then the render proof above.
|
||||
7. Re-run `npx hyperframes check`, then the render proof above.
|
||||
|
||||
@@ -27,7 +27,7 @@ If the content genuinely calls for one of these — centered layout for a solemn
|
||||
- Match light/dark to content: food, wellness, kids → light. Tech, cinema, finance → dark.
|
||||
- One accent hue. Same background across all scenes.
|
||||
- Tint neutrals toward your accent (even subtle warmth/coolness beats dead gray).
|
||||
- **Contrast:** enforced by `hyperframes validate` (WCAG AA). Text must be readable with decoratives removed.
|
||||
- **Contrast:** enforced by `hyperframes check` (WCAG AA). Text must be readable with decoratives removed.
|
||||
- Declare palette up front. Don't invent colors per-element.
|
||||
|
||||
## Background Layer
|
||||
|
||||
@@ -183,7 +183,7 @@ Keyframe camera position, camera target, object transform, material opacity, sha
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
npx hyperframes keyframes .
|
||||
npx hyperframes keyframes . --json
|
||||
npx hyperframes keyframes . --runtime all
|
||||
|
||||
@@ -98,7 +98,7 @@ Apply the correct template based on type. See [templates.md](templates.md) for c
|
||||
|
||||
```bash
|
||||
hyperframes lint # 0 errors required
|
||||
hyperframes validate --no-contrast # 0 console errors required
|
||||
hyperframes check --no-contrast # 0 console errors required
|
||||
```
|
||||
|
||||
### Step 5: Preview
|
||||
@@ -157,7 +157,7 @@ gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-
|
||||
## Quality Gate
|
||||
|
||||
- [ ] `hyperframes lint` → 0 errors
|
||||
- [ ] `hyperframes validate` → 0 console errors
|
||||
- [ ] `hyperframes check` → 0 console errors
|
||||
- [ ] `npx oxfmt --check` passes
|
||||
- [ ] `registry/registry.json` updated with new entry
|
||||
- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
|
||||
|
||||
@@ -32,7 +32,7 @@ Atomic capabilities you load **on demand** — not full workflows; they never ow
|
||||
| **Author seek-safe keyframes** — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth, plus `hyperframes keyframes` diagnostics | `/hyperframes-keyframes` |
|
||||
| **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive | `/hyperframes-creative` |
|
||||
| **Media** — resolve/generate BGM, SFX, image, icon, brand logo, voice, color grade, LUT; TTS voiceover, transcription, background removal, captions; cross-project reuse | `/media-use` |
|
||||
| **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor | `/hyperframes-cli` |
|
||||
| **CLI dev loop** — init, lint, check, snapshot, preview, render, publish, doctor | `/hyperframes-cli` |
|
||||
| **Install registry blocks / components** (`hyperframes add`) | `/hyperframes-registry` |
|
||||
| **Import Figma content** — assets, tokens, components, storyboards→reconstructed motion (REST/CLI); Motion (MCP), shaders (MCP source / native export) | `/figma` |
|
||||
|
||||
|
||||
@@ -134,7 +134,7 @@ Dispatch a subagent. prompt = full `agents/builder.md` + dispatch context (`shot
|
||||
### Step 6 — Verify (Bash → repair subagent on failure)
|
||||
|
||||
```bash
|
||||
(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)
|
||||
(cd "$PROJECT_DIR" && npx hyperframes check .)
|
||||
```
|
||||
|
||||
exit 0 → done. On lint/inspect errors, dispatch the repair subagent (`agents/finalize.md`: snapshot QA + one in-place fix pass + re-render). Never change a fixed duration in repair.
|
||||
|
||||
@@ -33,7 +33,7 @@ Build the **hero-frame end-state** in CSS first (flex + padding; never absolute
|
||||
|
||||
## Critical correctness (GSAP / seek)
|
||||
|
||||
Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`). One motif per scene. Run `hyperframes inspect` for overflow / collisions.
|
||||
Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`). One motif per scene. Run `hyperframes check` for overflow / collisions.
|
||||
|
||||
## Verify-fix
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Snapshot visual QA + one in-place fix pass + render. Dispatched only when Step 6
|
||||
|
||||
## Flow
|
||||
|
||||
1. **Snapshots** — `npx hyperframes inspect . --at <beat times>`; eyeball for: overflow / off-canvas, text collisions, empty frames, wrong content, motion that doesn't read.
|
||||
1. **Snapshots** — `npx hyperframes check . --at <beat times> --snapshots`; eyeball for: overflow / off-canvas, text collisions, empty frames, wrong content, motion that doesn't read.
|
||||
2. **One in-place repair pass** — `Edit` `compositions/index.html` for the visible issues. **Never change a fixed `data-duration`** (timing is set upstream; changing it breaks assembly). Re-run `lint`/`inspect`.
|
||||
3. **Render** — `(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q <quality> -o ./renders/video.mp4)` (add `--format webm` for an alpha overlay export). Verify the mp4 exists + duration matches.
|
||||
|
||||
|
||||
@@ -34,5 +34,5 @@ Root `#stage` (`data-composition-id`) needs `position: relative; width: <W>px; h
|
||||
- **Count-ups** tween a proxy via `onUpdate`; they only render when the host advances the timeline **with events enabled** (`tl.time()` / non-suppressed seek). A bare `seek(t, true)` freezes them at 0 — the HF render host must seek with events on. _(Eval finding.)_
|
||||
- Clamp at tween bounds; don't let a spring overshoot past a held value.
|
||||
- Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`).
|
||||
- One motif per scene. Run `hyperframes inspect`; mark intentional overflow `data-layout-allow-overflow="true"`.
|
||||
- One motif per scene. Run `hyperframes check`; mark intentional overflow `data-layout-allow-overflow="true"`.
|
||||
- **Palette discipline**: define all colors in one `palette` object / CSS custom properties — no inline hex scattered through the markup (for `asset-fusion`, eyedropper the palette from the asset).
|
||||
|
||||
@@ -146,7 +146,7 @@ Goal: Verify the assembled video, get user approval, and render the final MP4.
|
||||
Run the CLI on the **assembled project** — that's the correct unit (the per-frame workers couldn't run it). `lint` checks structure, `validate` runs headless Chrome (catching JS errors and missing assets), `inspect` snapshots frames.
|
||||
|
||||
```bash
|
||||
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
|
||||
( cd "$PROJECT_DIR" && npx hyperframes check . )
|
||||
```
|
||||
|
||||
Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval (autonomous mode: ask the one kept question — "preview first, or render?" — then deliver the MP4 with the contact sheet):
|
||||
|
||||
@@ -207,9 +207,9 @@ Inject transitions, run checks, pause for review, then render.
|
||||
|
||||
`npx hyperframes lint`
|
||||
|
||||
`npx hyperframes validate`
|
||||
`npx hyperframes check`
|
||||
|
||||
`npx hyperframes inspect`
|
||||
`npx hyperframes check`
|
||||
|
||||
`npx hyperframes snapshot --at <frame-midpoints>`
|
||||
|
||||
|
||||
@@ -182,9 +182,9 @@ Inject transitions, run checks, pause for review, then render.
|
||||
|
||||
`npx hyperframes lint`
|
||||
|
||||
`npx hyperframes validate`
|
||||
`npx hyperframes check`
|
||||
|
||||
`npx hyperframes inspect`
|
||||
`npx hyperframes check`
|
||||
|
||||
`npx hyperframes snapshot --at <frame-midpoints>`
|
||||
|
||||
|
||||
@@ -544,7 +544,7 @@ npx hyperframes lint
|
||||
Then run runtime validation:
|
||||
|
||||
```bash
|
||||
npx hyperframes validate
|
||||
npx hyperframes check
|
||||
```
|
||||
|
||||
Treat lint errors and validation `StaticGuard` contract messages as blockers even if a command exits successfully. Fix the file and rerun until lint reports `0 error(s)` and validation reports no runtime errors.
|
||||
|
||||
@@ -107,7 +107,7 @@ Lint, validate, take snapshots scaled to video length (formula: `max(beats × 3,
|
||||
|
||||
**Deliver something you're proud of.** Before handing off, ask yourself: would I post this on social media with my name on it? If not, fix what's wrong.
|
||||
|
||||
**Gate:** `npx hyperframes lint` and `npx hyperframes validate` pass with zero errors, and the final response includes the active Studio project URL.
|
||||
**Gate:** `npx hyperframes check` pass with zero errors, and the final response includes the active Studio project URL.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user