Skip to main content

hyperframes.inspect

Wrap upstream's hyperframes inspect as a structured pre-render diagnostic. Where hyperframes.lint catches STATIC issues from source files, this pack catches RUNTIME layout issues by loading the project in headless Chrome and sampling the DOM at specified (or auto-derived) timestamps. Same input shape as hyperframes.render — pass project_artifact_key OR composition_html. Soft-surface by default; pass strict:true to gate downstream packs.

Why this pack exists​

Lint catches "the audio is missing an id, that's silent in renders." Inspect catches "the caption fits at t=0 and t=5 but overflows its container at t=12.5 when an animation expands its parent." Both are pre-render — both run before burning the render budget. Inspect is the missing middle: source-level static checks (lint) + runtime layout sampling (inspect) + console-error audit (validate) form the three-pack pre-render validation suite.

Input schema​

FieldTypeRequiredDefaultNotes
project_artifact_keystringone-of—Project tarball.
composition_htmlstringone-of—Single-file index.html. Pass EXACTLY ONE.
samplesintegerno9 (CLI)Number of midpoint samples across the duration.
atstringno—Comma-separated explicit timestamps in seconds (e.g. "1.5,4,7.25").
toleranceintegerno2 (CLI)Allowed pixel overflow before reporting.
timeoutintegerno5000 (CLI)Ms to wait for runtime initialization.
max_issuesintegerno80 (CLI)Cap on returned issues after static-collapse.
at_transitionsbooleannofalseAlso sample every tween start/end boundary (catches transition-seam overlaps).
strictbooleannofalseAny error-severity issue → CodeArtifactFailed.

Output schema​

{
  "inspect": {
    "ok": false,
    "duration": 15,
    "error_count": 1,
    "warning_count": 1,
    "info_count": 0,
    "issue_count": 2,
    "total_issue_count": 2,
    "truncated": false,
    "sample_count": 5,
    "issues": [
      {
        "code": "text_box_overflow",
        "severity": "error",
        "time": 12.5,
        "selector": "div.wes-text-bottom",
        "containerSelector": "div.wes-container",
        "text": "and render.",
        "message": "Text extends outside its nearest visual/container box.",
        "fixHint": "Text is 259px x 55px..."
      }
    ]
  },
  "inspect_artifact_key": "hyperframes.inspect/abc123-inspect.json"
}

Issue fields preserve upstream camelCase verbatim (fixHint, containerSelector) so the codes stay stable across CLI version bumps.

Common findings​

CodeSeverityWhat it means
text_box_overflowerrorText extends outside its visual/container box at this timestamp. Fix: shrink text or expand container.
transition_overlapwarningSibling clips overlap at a transition seam. Fix: adjust data-start offsets or shorten exit tweens.
static_collapseinfoAn element collapses (width or height → 0) across N samples. Fix: explicit dimensions or min- constraints.

Example — at-transitions sampling​

For agent-authored compositions, the highest-leverage flag is at_transitions:true. It samples each tween's start AND end in addition to the default midpoints — catching the "fits at t=5 and t=10 but overlaps for 200ms at the t=7.5 transition seam" failures that midpoint sampling misses.

{
  "pack": "hyperframes.inspect",
  "input": {
    "project_artifact_key": "${steps.attach_audio.project_key}",
    "at_transitions": true,
    "strict": true
  }
}