Skip to content

Commit cf7c1d7

Browse files
committed
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.
1 parent b218ee7 commit cf7c1d7

41 files changed

Lines changed: 164 additions & 141 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ After creating or editing any `.html` composition:
5151

5252
```bash
5353
npx hyperframes lint # Static HTML structure check
54-
npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets)
54+
npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
5555
```
5656

5757
Both must pass before previewing or considering work complete.

‎CLAUDE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
3939
- `/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.
4040
- `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.
4141
- `/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.
42-
- `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
42+
- `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
4343
- `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream.
4444
- `/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.
4545

@@ -81,7 +81,7 @@ After creating or editing any `.html` composition:
8181

8282
```bash
8383
npx hyperframes lint # Static HTML structure check
84-
npx hyperframes validate # Runtime check (headless Chrome — catches JS errors, missing assets)
84+
npx hyperframes check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
8585
```
8686

8787
Both must pass before previewing or considering work complete.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
9090
| `/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. |
9191
| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. |
9292
| `/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. |
93-
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). |
93+
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). |
9494
| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. |
9595
| `/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. |
9696

‎docs/contributing/catalog.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ Not everything belongs in the registry. The bar is production quality.
141141
<Step title="Validate">
142142
```bash
143143
hyperframes lint
144-
hyperframes validate
144+
hyperframes check
145145
npx oxfmt your-block.html
146146
```
147147
</Step>

‎docs/guides/pipeline.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ Three checks before delivery:
165165

166166
```bash
167167
npx hyperframes lint # static HTML structure checks
168-
npx hyperframes validate # loads in headless Chrome, catches runtime errors
168+
npx hyperframes check # one browser session: runtime errors, layout, motion, contrast
169169
npx hyperframes snapshot my-video --at 2.9,10.4 # PNGs at beat midpoints
170170
```
171171

‎docs/guides/prompting.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,7 @@ Things that cause friction (or wrong output):
268268
- **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.
269269
- **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.
270270
- **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.).
271-
- **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).
271+
- **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).
272272
- **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.
273273

274274
## Recommended workflow

‎docs/guides/skills.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
9999
| `/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. |
100100
| `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. |
101101
| `/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. |
102-
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). |
102+
| `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `check`, `snapshot`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). |
103103
| `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. |
104104
| `/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. |
105105

‎docs/guides/video-editor-cheatsheet.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Before showing or rendering a project:
2727

2828
```bash
2929
npx hyperframes lint
30-
npx hyperframes validate
30+
npx hyperframes check
3131
npx hyperframes render --quality standard --output review.mp4
3232
```
3333

@@ -174,8 +174,8 @@ I moved the hero title and resized the CTA manually in Studio. Inspect the chang
174174
| `npx hyperframes capture https://example.com` | Capture a website as source material for a video |
175175
| `npx hyperframes preview` | Open the live Studio preview |
176176
| `npx hyperframes lint` | Catch structural mistakes before preview or render |
177-
| `npx hyperframes validate` | Run the composition in headless Chrome to catch runtime errors |
178-
| `npx hyperframes inspect` | Find text overflow and layout problems across the timeline |
177+
| `npx hyperframes check` | Run the composition in headless Chrome to catch runtime errors |
178+
| `npx hyperframes check` | Find text overflow and layout problems across the timeline |
179179
| `npx hyperframes snapshot --at 1,3,5` | Save PNG checks at exact timestamps |
180180
| `npx hyperframes render --output final.mp4` | Render the video |
181181
| `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
278278
| --- | --- |
279279
| Preview will not start | `npx hyperframes doctor` |
280280
| Port already in use | `npx hyperframes preview --port 4567` |
281-
| Render fails | `npx hyperframes lint` then `npx hyperframes validate` |
281+
| Render fails | `npx hyperframes lint` then `npx hyperframes check` |
282282
| Need exact frame checks | `npx hyperframes snapshot --at 1,2.5,5` |
283-
| Text overflows in the frame | `npx hyperframes inspect` |
283+
| Text overflows in the frame | `npx hyperframes check` |
284284
| Final render is too slow | Try `--quality draft`, reduce image sizes, or lower `--fps` |
285285
| Need to share editable project | `npx hyperframes publish` |
286286

‎docs/packages/cli.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,34 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o
520520

521521
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.
522522

523+
### `check`
524+
525+
The browser verification gate: everything the old `validate` → `inspect` → `snapshot` loop did, in **one** command with one browser session:
526+
527+
```bash
528+
npx hyperframes check [dir]
529+
npx hyperframes check [dir] --json # {ok, lint, runtime, layout, motion, contrast, snapshots}
530+
npx hyperframes check [dir] --snapshots # annotated overview frames + per-finding crops
531+
npx hyperframes check [dir] --at 1.5,4,7.25
532+
npx hyperframes check [dir] --strict # exit non-zero on warnings too
533+
```
534+
535+
`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.
536+
537+
| Flag | Description |
538+
|------|-------------|
539+
| `--json` | Aggregated machine-readable envelope; every finding carries selector, `data-*` identity, source file, bbox, and sample time |
540+
| `--snapshots` | Write overview frames (annotated with labeled finding boxes when there are errors) plus `finding-NN-<code>.png` crops |
541+
| `--samples` / `--at` / `--at-transitions` | Control the seek grid (default 9 samples; `--at-transitions` adds tween boundaries) |
542+
| `--tolerance` | Allowed overflow in px before reporting (default 2) |
543+
| `--timeout` | Initial settle budget in ms (default 3000) |
544+
| `--no-contrast` | Skip the WCAG audit while iterating |
545+
| `--strict` | Exit non-zero on warnings too (default: only errors) |
546+
| `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` | Opt-in band gate: flags content whose center sits inside the fractional band (optional `severity`, `seek`) |
547+
| `--frame-check` | Opt-in media out-of-frame detection (img/svg/video/canvas) |
548+
549+
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`.
550+
523551
### `beats`
524552

525553
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
549577

550578
### `inspect`
551579

580+
<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>
581+
552582
Inspect rendered visual layout across the composition timeline:
553583

554584
```bash

‎packages/cli/src/commands/init.test.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,7 @@ describe("hyperframes init flag rename", () => {
5050
expect(pkg.type).toBe("module");
5151
expect(pkg.scripts).toMatchObject({
5252
dev: "npx --yes hyperframes preview",
53-
check:
54-
"npx --yes hyperframes lint && npx --yes hyperframes validate && npx --yes hyperframes inspect",
53+
check: "npx --yes hyperframes check",
5554
render: "npx --yes hyperframes render",
5655
publish: "npx --yes hyperframes publish",
5756
});
@@ -84,8 +83,7 @@ describe("hyperframes init flag rename", () => {
8483
};
8584
expect(pkg.scripts).toMatchObject({
8685
dev: "npx --yes hyperframes preview",
87-
check:
88-
"npx --yes hyperframes lint && npx --yes hyperframes validate && npx --yes hyperframes inspect",
86+
check: "npx --yes hyperframes check",
8987
render: "npx --yes hyperframes render",
9088
publish: "npx --yes hyperframes publish",
9189
});

0 commit comments

Comments
 (0)