Lint Validate Inspect

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 for early feedback. It is an iteration aid, not a separate final gate.
• 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 / data-layout-allow-caption-zone (caption band only).
• 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

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.

<video>/<audio> work at any nesting depth, including inside a compositions/*.html sub-composition or a wrapper <div>: the runtime discovers media with a flat DOM query and seeks/decodes it wherever it lives (packages/core/src/runtime/{media,startResolver}.ts). After a render, 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 real bug, not a placeholder).

check

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:

• 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.

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.

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, a held content_overlap is an error, and a held, partially-visible canvas_overflow breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (escaped_container, panel_out_of_canvas, connector_detached) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. 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. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they’re still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. Spread the reveal across the timeline or keep one continuously animated element alive (a blinking caret is idiomatic for code typing) — don’t bolt on a slow position drift just to appease the check.

Escape hatches (mark intent in the HTML, then re-run):

• 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). Applies only to the marked text block; it is not inherited. Mark the specific layering participant, never a scene/root wrapper, so unrelated descendant collisions remain auditable.
• data-layout-allow-occlusion — an element is meant to cover text.
• data-layout-allow-caption-zone — intentional lower-third / caption-band copy under --caption-zone. Applies to the marked element and every descendant (closest); silences only caption_zone_collision (not overflow/overlap/occlusion). Prefer the narrowest wrapper that owns the intentional band copy.
• data-layout-ignore — decorative element that should never be audited.

Opt-in pipeline gates (used by orchestrators; off by default):

--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 a text element’s DOM box (getBoundingClientRect) that overlaps the band. Waive intentional lower-third copy with data-layout-allow-caption-zone on the element or its nearest wrapper (see Escape hatches). --frame-check reports media elements breaching the canvas beyond max(120px, 6% of the min canvas dimension).

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.

Motion verification (*.motion.json sidecar)

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.

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.

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

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

hyperframes check --snapshots already writes a finding-NN-<code>.png crop for every error finding that carries a bbox, but the same zoom is available standalone once you know what to look at:

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