diff --git a/optional-skills/creative/hyperframes/SKILL.md b/optional-skills/creative/hyperframes/SKILL.md index 926358e515..809a42052b 100644 --- a/optional-skills/creative/hyperframes/SKILL.md +++ b/optional-skills/creative/hyperframes/SKILL.md @@ -132,16 +132,18 @@ Use `npx hyperframes add ` to install shader transitions (`flas - **Marker-style highlighting:** highlight, circle, burst, scribble, sketchout effects for text emphasis are deterministic CSS+GSAP — see `references/features.md#marker-highlighting`. Fully seekable, no animated SVG filters. - **Scene transitions:** every multi-scene composition MUST use transitions (no jump cuts). Pick from CSS primitives (push slide, blur crossfade, zoom through, staggered blocks) or shader transitions (`flash-through-white`, `liquid-wipe`, `cross-warp-morph`, `chromatic-split`, etc.) via `npx hyperframes add`. Mood and energy tables live in `references/features.md#transitions`. Do not mix CSS and shader transitions in the same composition. -### 7. Lint, preview, render +### 7. Lint, validate, inspect, preview, render ```bash npx hyperframes lint # catches missing data-composition-id, overlapping tracks, unregistered timelines +npx hyperframes validate # WCAG contrast audit at 5 timestamps +npx hyperframes inspect # visual layout audit — overflow, off-frame elements, occluded text npx hyperframes preview # live browser preview npx hyperframes render --quality draft --output draft.mp4 # fast iteration npx hyperframes render --quality high --output final.mp4 # final delivery ``` -`hyperframes validate` runs a WCAG contrast audit — screenshots at 5 timestamps, samples pixels behind every text element, warns on <4.5:1 ratios. +`hyperframes validate` samples background pixels behind every text element and warns on contrast ratios below 4.5:1 (or 3:1 for large text). `hyperframes inspect` is the layout-side companion — runs the page at multiple timestamps and flags issues that a static lint can't see (a caption that wraps past the safe area only at 4.5s, a card that overflows when its title is the longest variant, an element that ends up behind a transition shader). Run `inspect` especially on compositions with speech bubbles, cards, captions, or tight typography. ### 8. Website-to-video (if the user gives a URL) @@ -164,7 +166,7 @@ Use the 7-step capture-to-video workflow in [references/website-to-video.md](ref Before and after rendering: -1. **Lint + validate pass:** `npx hyperframes lint --strict && npx hyperframes validate` (WCAG contrast audit at 5 timestamps — see troubleshooting.md if warnings appear). +1. **Lint + validate + inspect pass:** `npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect` (lint catches structural issues, validate catches contrast, inspect catches visual layout / overflow issues — see troubleshooting.md if warnings appear). 2. **Animation choreography** — for new compositions or significant animation changes, run the animation map. `npx hyperframes init` copies the skill scripts into the project, so the path is project-local: ```bash node skills/hyperframes/scripts/animation-map.mjs \ @@ -181,7 +183,7 @@ If `hyperframes render` fails, run `npx hyperframes doctor` and attach its outpu ## References - [composition.md](references/composition.md) — data attributes, timeline contract, non-negotiable rules, typography/asset rules -- [cli.md](references/cli.md) — every CLI command (init, capture, lint, validate, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark) +- [cli.md](references/cli.md) — every CLI command (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark) - [gsap.md](references/gsap.md) — GSAP core API for HyperFrames (tweens, eases, stagger, timelines, matchMedia) - [features.md](references/features.md) — captions, TTS, audio-reactive, marker highlighting, transitions (load on demand) - [website-to-video.md](references/website-to-video.md) — 7-step capture-to-video workflow diff --git a/optional-skills/creative/hyperframes/references/cli.md b/optional-skills/creative/hyperframes/references/cli.md index 5f44cc5530..4ffd74ccf7 100644 --- a/optional-skills/creative/hyperframes/references/cli.md +++ b/optional-skills/creative/hyperframes/references/cli.md @@ -8,8 +8,9 @@ Everything runs through `npx hyperframes` (or the globally-installed `hyperframe 2. **Write** — author HTML composition (see `composition.md`) 3. **Lint** — `npx hyperframes lint` 4. **Validate** — `npx hyperframes validate` (WCAG contrast audit) -5. **Preview** — `npx hyperframes preview` -6. **Render** — `npx hyperframes render` +5. **Inspect** — `npx hyperframes inspect` (visual layout audit) +6. **Preview** — `npx hyperframes preview` +7. **Render** — `npx hyperframes render` Always lint before preview/render — catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. @@ -60,6 +61,20 @@ npx hyperframes validate --no-contrast # skip while iterating Seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and warns on contrast ratios below 4.5:1 (normal text) or 3:1 (large text — 24px+, or 19px+ bold). Run before final render. +## inspect + +```bash +npx hyperframes inspect # visual layout audit at 5 timestamps +npx hyperframes inspect ./my-project # specific project +npx hyperframes inspect --json # agent-readable findings +npx hyperframes inspect --samples 15 # denser timeline sweep +npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps +``` + +Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. Reports overflow, off-frame elements, occluded text, contrast warnings, and per-timestamp layout summaries — catches issues that pure timeline lint can't see (e.g., a caption that wraps past the safe area only at a specific timestamp). + +`npx hyperframes layout` is a compatibility alias for the same visual inspection pass. + ## preview ```bash