Single-pass authoring under-decorates when a composition has more than one
scene. The eval run showed p1 branch (3 scenes, single-pass with expansion)
regressing vs main on background-layer density — the authoring agent
followed the expansion's scene-element list literally and omitted the
house-style atmosphere stack (ghost type, radial glow, framing rules).
Giving each scene its own subagent via the multi-scene pipeline keeps
per-scene density and decoration consistent, because each fragment agent
reads house-style.md and applies "2–5 decoratives per scene" to its one
scene without competing for context.
The threshold is now "2 or more scenes". Single-pass is reserved for true
one-scene compositions (title cards, standalone overlays).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The parallel fan-out in Phase 1 and Phase 2b requires the Agent/Task tool,
which in Claude Code is only available to the top-level conversation agent.
Dispatched subagents cannot spawn further subagents, so they can't drive the
parallel pipeline.
Add guidance in SKILL.md and references/multi-scene.md:
- Top-level agent: run the full parallel pipeline
- Nested subagent: author fragments sequentially, still run through the
assembler and lint gates, note the constraint in the final report
This surfaced in eval runs where the skill was invoked from a nested
general-purpose subagent and the multi-scene dispatch silently fell back to
serial authoring with no indication to the caller.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Scaffold and scene subagents have no dependency — scenes don't read
the scaffold, they only need the fragment spec, design.md, and their
prompt section. Dispatch all at the same time. Assembly waits for both.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Extract getSceneElements() into lint/utils.ts (was copy-pasted 4x)
- Consolidate triple zero-detection in late_init_set to single parseFloat
- Fix double regex in scene_position_override (single .match() call)
- Remove dead stripWrapperTags from assembler (validation rejects first)
- Remove WHAT comments, keep WHY comments
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Scene fragments with <style>/<script> wrappers around their CSS/GSAP
sections caused nested tags in the assembled output, rendering raw code
visibly on screen. The assembler now:
- Rejects fragments with <style>/<script> tags (prohibited pattern)
- Strips wrapper tags as safety net during split (defense in depth)
Also adds <style> to the fragment spec's prohibited list in multi-scene.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The scaffold's scene divs include data-start, data-duration, and
data-track-index attributes. The assembler regex only matched
<div id="sceneN" class="scene"> exactly. Changed to [^>]* to allow
any additional attributes before the closing >.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Eval gate now explicitly requires:
- Step 1 (format): runs immediately as each scene lands, not batched
- Step 2 (content): checks against expanded prompt, design.md, GSAP targets
- FAIL handling with max 2 retries before escalation
Assembly gate now requires assembleScenes() from @hyperframes/core/assemble
instead of manual stitching. The function validates fragments, splits on
markers, injects into scaffold, and verifies div balance.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds @hyperframes/core/assemble with assembleScenes() — a deterministic
function that validates scene fragments against the spec, splits on
markers, and injects into the scaffold. No AI in the assembly loop.
The scaffold must include three markers:
- <!-- SCENE N CONTENT --> in each empty scene div
- /* SCENE STYLES */ in the <style> block
- // SCENE TWEENS in the <script> block
Fragment validation catches: duplicate/missing markers, wrong order,
prohibited patterns (script tags, DOCTYPE, tl.from, etc). Div balance
is verified post-assembly. Errors abort with specific file + message.
Also updates multi-scene.md Phase 1 (scaffold markers) and Phase 3
(use assembleScenes instead of manual stitching).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The studio API's walkDir scans all HTML files in a project directory.
Scene fragments in .hyperframes/scenes/ and the design picker in
.hyperframes/pick-design.html are build artifacts, not compositions.
Linting them produces false errors (missing data-composition-id, etc).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds prohibited patterns observed in Void Hunter assembly:
- <script> tags in GSAP section (causes nested script parse errors)
- CSS transform on GSAP-animated elements (destroys centering)
- Bare class names without s{N}- prefix (cross-scene collisions)
- Contrast requirement (4.5:1 WCAG AA) for text elements
- Scaffold must add visibility kill for every scene including last
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Moves format rules from prose in the subagent prompt to a formal spec
at the top of multi-scene.md. Both subagents and evaluators reference
the same contract. Evaluators now run format checks as a gate before
content checks — malformed fragments fail instantly. Assembly becomes
split-inject-done with no parsing or stripping.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Keep our categorized reference structure (workflow/authoring/media)
while incorporating items from main (captions, css-patterns, transitions).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three blocking gates in multi-scene builds:
1. Eval gate: all scenes must have PASS eval before assembly
2. Lint gate: 0 errors required after assembly before serving
3. Validate gate: run after lint, report contrast warnings
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The orchestrating agent skipped the eval step because it was buried in
a reference file. Moved the eval requirement into SKILL.md as a
BLOCKING GATE with explicit "do NOT assemble without eval files" and
"if you find yourself about to assemble without evals, STOP."
This addresses the core harness engineering insight: agents skip their
own evaluation step unless it's mechanically enforced. Advisory
instructions are insufficient.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add prompt cookbook + prompting guide for AI agents
Addresses user feedback that there's no guidance on how to actually
prompt Claude Code (or other agents) once the hyperframes skills are
installed. Adds copy-pasteable example prompts in the README and
quickstart, a new prompting guide page, and a starter-prompt nudge in
the `hyperframes init` output.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(prompting): add vocabulary tables, rules, and TTS voice guide
Merges the best content from the internal prompt guide into
prompting.mdx: easing vocabulary, caption tone table, transition
energy matrix, audio-reactive frequency mapping, marker highlight
modes, TTS voice recommendations, rendering quality presets, and
framework rules (technical requirements vs best practices).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(prompting): rename page title to "Prompt Guide"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: remove greensock/gsap-skills dependency, fix Math.random nuance
The bundled skills/gsap/ already covers the GSAP surface needed for
HyperFrames compositions. Installing greensock/gsap-skills on top adds
a competing full-ecosystem skill that's mostly irrelevant (ScrollTrigger,
Draggable, SplitText, etc.) and can confuse agents about which GSAP
context to load.
Also adds seeded-PRNG nuance to the Math.random() rule in the prompt
guide (matching the skill's actual guidance).
Removed from: skills.ts, README, AGENTS.md, shared AGENTS.md/CLAUDE.md,
and prompting.mdx.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: require minimal reproduction link in bug report template
Adds a required "Link to reproduction" input field asking users to push
a minimal repro to a public GitHub repo (scaffolded via
`hyperframes init repro --non-interactive --example blank`).
Also consolidates the OS/Node/FFmpeg/version fields into a single
"Environment" field using `npx hyperframes info` output — fewer fields
to fill, more consistent data.
Follows the same pattern as Next.js and Gatsby issue templates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(issue-template): use hyperframes doctor for environment info
`hyperframes info` only prints project metadata (resolution, duration,
elements). `hyperframes doctor` prints the full environment: version,
Node.js, FFmpeg, Chrome, memory, disk, Docker — everything needed to
diagnose bugs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(prompting): mention validate alongside lint in anti-patterns
Per Vance's review comment — validate catches runtime errors (JS
exceptions, missing assets, contrast) that lint doesn't.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: replace libretto example URL with hyperframes repo
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Picker subagent was using npx hyperframes preview which blocks. Now
instructs: use python3 http.server in background, parent handles
serving. Subagents should not start servers.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Expanded prompts are hundreds of lines — dumping them into conversation
overwhelms the user. Now writes to .hyperframes/expanded-prompt.md and
tells the user the file path with a short summary (scene count, duration).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
SKILL.md was 436 lines with large blocks that only run conditionally.
Extracted to reference files loaded on demand:
- references/prompt-expansion.md (32 lines) — sparse prompt → full production prompt
- references/design-picker.md (38 lines) — visual picker workflow + token system
- references/multi-scene.md (55 lines) — 4-phase subagent pipeline + evaluation
SKILL.md: 436 → 358 lines. References section reorganized into
workflow/authoring/media categories. Stale references removed
(shader-setup.md, shader-transitions.md, marker-highlight.md).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New Step 0a runs before the design picker when the user's prompt is a
brief description rather than a detailed scene-by-scene breakdown.
Expands "make me a trailer about an alien on a spaceship" into a full
production prompt with: style block, global animation rules, scene-by-
scene breakdown with specific elements and transitions, recurring motifs,
pacing curve, and negative prompt.
The user reviews and approves the expanded prompt before proceeding to
Step 0b (design picker) and Step 1 (plan/build).
This implements the "planner expands a 1-4 sentence prompt into a full
spec" pattern from harness engineering research. The expansion is better
informed after the design picker because it knows the visual system.
Reordered: Step 0a (expand) → Step 0b (design.md) → Step 1 (plan/build).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Phase 2b evaluates each scene as soon as its file appears — not after
all scenes finish. Evaluator checks prompt adherence, design compliance,
rule compliance, and density. Failed scenes get re-dispatched with
feedback. The pipeline streams instead of batching.
This implements the generator-evaluator pattern from harness engineering
literature: "separating the agent doing the work from the agent judging
it is a strong lever."
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- `_setupParentMedia()` (added in #266) was stripping `data-start`, `data-duration`, and `src` from audio/video elements inside the composition iframe
- The runtime's `syncRuntimeMedia` queries `audio[data-start]` to find media clips — removing these attributes made the runtime unable to find, sync, or play audio
- Result: silent audio in studio preview and any context where `__player.play()` is called directly (not through the web component)
## Fix
- Keep all iframe media attributes intact so the runtime can track time position and manage playback
- When parent-frame media `play()` succeeds (mobile use case), mute the iframe copies via `volume = 0` to prevent double audio
- On desktop and in the studio (which calls `__player.play()` directly), the runtime's own media sync handles playback normally
## Test plan
- [x] 21 player unit tests pass
- [x] Verified with John Wu's slideshow project: audio element preserves `data-start`, `data-duration`, `src` after runtime init
- [x] Verified runtime `syncRuntimeMedia` finds and plays audio (currentTime advances in sync with timeline)
- [x] Build passes (lint, format, typecheck)
The picker generates design.md and copies it to clipboard, but the agent
had no instruction to ask the user to paste it back. Now Step 0 says:
"Copy the design.md from the picker and paste it here." Agent saves
the pasted content to design.md and proceeds.
Also removes the hardcoded markdown template — the picker generates
the format dynamically based on user selections.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three new rules that catch the bugs we hit building a 9-scene composition:
1. tl_from_in_multiscene (warning) — flags tl.from() in multi-scene
compositions. Should use tl.set()+tl.to() instead. tl.from() causes
elements to flash visible before their entrance animation.
2. late_init_set (warning) — flags tl.set({ opacity: 0 }) at time > 0.
Init sets must fire at time 0 so elements are hidden before any
transition reveals the scene.
3. scene_position_override (error) — flags #sceneN { position: relative }
which overrides the scaffold's position: absolute and pushes scenes
off-screen. This was the root cause of blank scenes.
Replaces missing_immediate_render_false which is now obsolete — the
correct pattern avoids tl.from() entirely rather than patching it with
immediateRender: false.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Setting initial hidden state at scene start time (e.g., t=5.0) causes
a flash — the transition reveals the scene at t=4.85 but elements are
still visible until the tl.set fires at t=5.0. Moving all init tl.set
calls to time 0 ensures elements are hidden from the start of the
timeline, long before any transition reveals them.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
tl.from() in multi-scene compositions causes elements to flash visible
at their CSS default state before the entrance animation fires. The
correct pattern is:
tl.set("#el", { opacity: 0, y: 30 }, sceneStart) // hide at scene start
tl.to("#el", { opacity: 1, y: 0, duration: 0.4 }, tweenStart) // animate in
This replaces the previous immediateRender: false guidance which only
partially solved the problem.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Scene subagents were setting position: relative on #sceneN containers,
overriding the scaffold's position: absolute. This caused scenes to
stack vertically instead of overlapping, making them appear off-screen.
Added instruction: subagents must NOT set position, top, left, width,
height, opacity, or z-index on the scene container — the scaffold owns
those. Only style elements inside the scene.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
In multi-scene compositions sharing a single GSAP timeline, tl.from()
and tl.fromTo() default to immediateRender: true — rendering their FROM
state at time 0. This makes elements in hidden scenes (opacity: 0)
invisible when the transition reveals them.
New lint rule detects tl.from/tl.fromTo calls targeting elements inside
hidden scene divs without immediateRender: false, and emits a warning
with a fix hint.
Also updates SKILL.md multi-scene build instructions to include the
immediateRender requirement in subagent instructions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Single-agent builds produce shallow results on complex compositions —
detail drops as context fills with boilerplate. For 4+ scenes, the skill
now directs a three-phase approach:
Phase 1 (Scaffold): Parent builds HTML skeleton, timeline backbone,
transitions, global CSS. Scene divs left empty.
Phase 2 (Scene subagents): One agent per scene, dispatched in parallel.
Each receives design.md + global animation rules + that scene's prompt.
Entire context focused on making ONE scene rich — parallax, micro-
animations, kinetic typography, ambient motion.
Phase 3 (Assembly): Parent collects scene payloads, injects into
scaffold, merges styles and tweens, resolves conflicts, runs lint.
Mirrors HeyGen Video Agent architecture (storybase → scene generator →
draft builder) and harness engineering principle (one task per session).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Agents were sharing localhost URLs without confirming the server was
actually running. Now Step 0 instructs: curl the URL first, only share
the link if it returns 200.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Step 0 now instructs the agent to read typography.md, house-style.md, and
motion-principles.md BEFORE generating picker options. All generated
architectures, palettes, and type pairings must comply with:
- Banned font list
- Cross-category pairing requirement
- Weight contrast rules
- Video-sized text minimums
- Lazy default avoidance (no gradient text, no pure black/white, etc.)
Without this, the picker generated options that contradicted the established
stylistic guardrails.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The agent reads design.md in Step 0 but had no instruction to reference
it during construction. Now explicitly states: use only values from
design.md, don't invent new ones. If design.md has fields we didn't
define (user-added sections), follow those too. Fall back to house-style
only for values the design.md doesn't cover.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds a design picker HTML template that agents generate and serve when
no design.md exists in a project. Users configure their visual direction
by picking independently from 7 categories:
- Theme (dark / light / full palette)
- Structure (architecture with preview_html using {{token}} placeholders)
- Color palette (accent colors, with background variety instruction)
- Typography (headline + body pairing)
- Corners (sharp / slight / rounded / pill)
- Density (tight / normal / generous)
- Depth (flat / subtle / layered — accent glow on dark, drop shadow on light)
Split-panel layout: options scroll on the left, live preview updates on
the right. All 7 selections combine into a design.md with: mood, theme,
structure, colors, typography, corners, spacing, depth, components, and
do's/don'ts. Generated as editable markdown in a modal with clipboard copy.
Architecture previews use {{token}} placeholders so agents generate
prompt-specific architectures without hardcoded switch cases.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The `Copy page` dropdown panel rendered with a transparent background in
light mode because `docs/custom.css` defined `--background-light: #ffffff`
on `:root`. Mintlify's Maple theme owns that variable as a Tailwind color
(space-separated RGB used via `rgb(var(--background-light)/<alpha>)`), so
the hex override produced invalid CSS like `rgb(#ffffff/1)` and the
dropdown's `bg-background-light` class fell back to transparent. Dark
mode was unaffected because the dropdown panel uses `bg-background-dark`,
which custom.css didn't redefine.
Namespaced every custom variable with `--hf-` to make collisions
impossible, and updated the two consumers (`pre`, `::selection`, link
color in custom.css; `.tpl-card:hover` border in template-gallery.css).
* chore(skills): remove 1,685 lines of redundant and irrelevant skill content
- Remove 5 GSAP references irrelevant to HyperFrames (scrolltrigger,
plugins, react, frameworks, utils) — no scroll, no frameworks, no
interactive plugins in video compositions
- Remove shader-setup.md and shader-transitions.md — duplicated by
@hyperframes/shader-transitions package (packages/shader-transitions/)
- Remove marker-highlight.md and examples.md — JS library docs superseded
by css-patterns.md (deterministic, GSAP-driven, fully seekable)
- Trim CLAUDE.md to dev-only instructions — move product docs (transcription,
TTS, player) to skills where they belong
- Deduplicate house-style.md typography/motion sections — point to
dedicated references instead of repeating rules
- Clean up stale references to deleted files across SKILL.md and catalog.md
- Update gsap skill description to reflect HyperFrames-only scope
Skills: 5,230 → 3,714 lines (29% reduction)
CLAUDE.md: 204 → 50 lines (75% reduction)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(skills): update broken marker-highlight.md references in captions.md
Point to css-patterns.md instead of deleted marker-highlight.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(skills): update stale shader CSS rule to reference package API
BG_COLOR was from the old manual setup. Now it's bgColor in the
@hyperframes/shader-transitions init() config.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(skills): address 6 doc gaps surfaced by eval agents
P0: Document HyperShader as IIFE global name in shader-transitions README
P1: Replace async fetch() with sync XHR in effects.md audio data loading
(fetch violates synchronous timeline construction rule in SKILL.md)
P1: Change <div> to <span> in css-patterns.md marker highlight patterns
(<div> inside <p> is invalid HTML, breaks layout in inline contexts)
P2: Clarify bgColor as fallback color in shader-transitions README
P2: Add data-start to Composition Clips table in SKILL.md
(root composition element needs data-start="0", linter enforces it)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(templates): update init templates to match trimmed skill scope
- Remove ScrollTrigger/plugins/React/Vue/Svelte from gsap skill description
- Replace class="clip" with accurate pattern examples in skill intro text
(class="clip" is still in Key Rules where it belongs)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(skills): remove contradictory 5:1 contrast threshold from house-style
house-style.md said 5:1 minimum, but hyperframes validate enforces
WCAG AA (4.5:1 normal text, 3:1 large text). Now defers to validate
instead of stating a conflicting number.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace all visual-style.md references with design.md, following the
pattern established by Google Stitch — a portable, machine-readable
design system file that AI agents consume for consistent output.
When no design.md exists in the project, the agent now asks the user
if they want to create one before building compositions:
- "Yes" → agent creates design.md with colors, typography, motion,
transitions, and mood for the project
- "No" → falls back to house-style.md defaults as before
The design.md format for HyperFrames extends Stitch's web-focused spec
with video/motion fields: energy level, ease vocabulary, entrance
patterns, transition types, and pacing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## What
Fixes the README skills table to match actual skill names, and moves two orphaned script directories into the `hyperframes` skill where they belong.
## Why
**README**: Listed `hyperframes-compose` and `hyperframes-captions` as separate skills — these don't exist. Captions/compose are part of the `hyperframes` skill. Also listed `gsap-core, gsap-timeline, gsap-plugins, ...` but the actual skill is just `gsap`. Missing `hyperframes-cli` entirely.
**Orphaned scripts**: `skills/hyperframes-animation-map/` and `skills/hyperframes-contrast/` had scripts but no `SKILL.md` — they looked like broken skills and wouldn't be installed by `npx skills add`. They're helper scripts invoked by the main `hyperframes` skill (SKILL.md already references them in the "Quality Checks" section). Moving them under `skills/hyperframes/scripts/` makes them part of the skill they belong to.
## How
**README skills table** — corrected to match the 4 actual skills:
- `hyperframes` (was `hyperframes-compose` + `hyperframes-captions`)
- `hyperframes-cli` (was missing)
- `hyperframes-registry` (unchanged)
- `gsap` (was `gsap-core, gsap-timeline, gsap-plugins, ...`)
**Script moves:**
- `skills/hyperframes-animation-map/scripts/animation-map.mjs` → `skills/hyperframes/scripts/`
- `skills/hyperframes-contrast/scripts/contrast-report.mjs` → `skills/hyperframes/scripts/`
- Removed empty `skills/hyperframes-animation-map/` and `skills/hyperframes-contrast/`
- Updated path references in SKILL.md, both script headers, and `contrast-audit.browser.js`
## Test plan
- [ ] `grep -r "hyperframes-animation-map\|hyperframes-contrast" --include="*.md" --include="*.mjs" --include="*.js" --include="*.ts" .` returns no results
- [ ] `ls skills/` shows only `gsap`, `hyperframes`, `hyperframes-cli`, `hyperframes-registry`
- [ ] README skills table matches `skills/*/SKILL.md` names
- [x] Documentation updated (if applicable)
## What
Restructures the Quickstart docs page to lead with AI agent onboarding as the recommended path, matching the README and homepage flow.
## Why
The README (PR #277) now leads with skills-first onboarding, but the Quickstart docs page still led with `npx hyperframes init`. This creates a consistency gap — someone clicking "Quickstart" from the README would see a different onboarding flow than what they just read.
## How
- **Option 1 (recommended)**: Install skills → prompt your agent → iterate by describing changes
- **Option 2**: Manual CLI setup (`hyperframes init` → preview → edit → render) — unchanged content, now under a sub-heading
- Added tip explaining why skills matter (framework-specific patterns)
- Notes that `hyperframes init` installs skills automatically
- "Next steps" cards now include the Catalog (50+ blocks) replacing the Compositions card
## Test plan
- [ ] Preview the Mintlify docs and verify the Quickstart page renders correctly
- [ ] Verify Option 1 flow reads naturally for someone new to HyperFrames
- [ ] Verify Option 2 manual flow is unchanged (same steps, same code examples)
- [ ] Verify all links resolve (Examples, Catalog, GSAP Animation, Rendering)
- [x] Documentation updated (if applicable)
## What
Adds `AGENTS.md` at two levels:
1. **Repo-level** (`/AGENTS.md`) — for contributors working on HyperFrames itself
2. **Project-level** (`packages/cli/src/templates/_shared/AGENTS.md`) — scaffolded into user projects by `hyperframes init`
Also replaces the previous `AGENTS.md → CLAUDE.md` symlink with a standalone file.
## Why
AGENTS.md is the emerging universal standard for AI coding tool configuration, supported by Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Codex (60K+ repos). Remotion already has one. For a project that positions itself as AI-native, this is a gap.
The project-level file (scaffolded by `init`) ensures every AI tool — not just Claude — gets framework context when working on a user's composition project. The symlink was replaced because symlinks are fragile on Windows and the content should differ (repo-level covers build/test, project-level covers composition rules).
## How
- **Repo-level AGENTS.md**: Build/test/lint commands, project structure, key conventions, skills install, doc links
- **Project-level AGENTS.md**: Composition-specific — skills, CLI commands, project structure, linting workflow, key rules, doc links
- **CLAUDE.md** remains for Claude-specific skill invocation syntax (slash commands)
## Test plan
- [ ] Verify AGENTS.md renders correctly on GitHub
- [ ] Verify no duplication with CLAUDE.md (AGENTS.md = universal basics, CLAUDE.md = Claude-specific slash commands)
- [ ] Manual testing performed
- [x] Documentation updated (if applicable)
## What
Restructures the README to lead with skills-first onboarding, adds a demo GIF, surfaces the catalog, fixes incorrect pnpm references in contributing docs, and corrects the HTML example to use actual attribute names.
## Why
The README told a CLI-first story while the homepage (hyperframes.heygen.com) tells an AI-agent-first story. For a project that brands itself "built for agents," the GitHub landing page should match. Additionally, 50+ catalog blocks were invisible from GitHub, the player and shader-transitions packages were missing from the packages table, and the contributing docs referenced pnpm while the repo uses bun.
## How
**README changes:**
- Quick Start restructured: skills install as Option 1 (recommended), manual CLI as Option 2
- Added demo GIF rendered with HyperFrames itself (HTML + GSAP composition → MP4 → GIF)
- Added Catalog section with install examples and link
- Added `@hyperframes/player` and `@hyperframes/shader-transitions` to packages table
- Added npm downloads badge
- Fixed HTML example: `data-track` → `data-track-index`, added missing `class="clip"` on img
- Condensed Skills section into a concise table
- Documentation link now points to `/introduction` (Mintlify docs) instead of the landing page
**testing-local-changes.mdx:**
- All `pnpm` references replaced with `bun` (14 occurrences)
- Path references updated from `hyperframes-oss` to `hyperframes`
## Test plan
- [ ] Verify README renders correctly on GitHub (logo, badges, GIF, tables, code blocks)
- [ ] Verify GIF loops and is readable at GitHub's default README width
- [ ] Verify all links resolve (docs site, catalog, packages, contributing)
- [ ] Read through testing-local-changes.mdx for any remaining pnpm references
- [x] Documentation updated (if applicable)
## Summary
Two new quality skills + CLI integration that give agents feedback loops they currently lack — pixel-level contrast auditing and structured animation analysis.
### What this unlocks for agents
**Agents can now catch accessibility failures that humans and LLMs consistently miss.** The contrast audit runs automatically on every `hyperframes validate` and reports WCAG AA violations as warnings. In the eval, 4 out of 5 palettes had failing contrast — every baseline composition shipped broken, every treatment composition caught and fixed it.
**Agents can now reason about animation choreography.** The animation map produces a structured JSON report with:
- Per-tween natural language summaries ("card1 slides 23px up over 0.5s, fades in, ends at (120, 200)")
- ASCII timeline showing the full choreography as a Gantt chart
- Stagger detection with actual intervals ("3 elements stagger at 120ms" — validates against brief specs)
- Dead zone detection (periods >1s with no animation — missing entrance or intentional hold?)
- Element lifecycles (first/last animation, final visibility — catches elements that enter but never exit)
- Scene snapshots at 5 timestamps (what's on screen at any moment)
### Changes
**Skills (new)**
- \`skills/hyperframes-contrast/\` — WCAG contrast audit skill + script
- \`skills/hyperframes-animation-map/\` — animation analysis skill + script
**CLI**
- \`hyperframes validate\` now runs contrast audit by default (warnings, not errors)
- \`hyperframes validate --no-contrast\` to skip
- \`hyperframes render --html-only\` compiles HTML without video encoding
- Browser-side WCAG code in \`contrast-audit.browser.js\`, inlined at build time via esbuild text loader
**Producer**
- Exported \`compileForRender\` for the \`--html-only\` flag
### Eval results
5 prompts x 2 arms = 10 compositions. Arm A = baseline skills. Arm B = +contrast +animation-map.
| Prompt | Failing color | Before | After |
|--------|--------------|--------|-------|
| Halflife | Cement on Ink | 2.98:1 | 5.33:1 |
| Meridian | Ash on Midnight | 2.08:1 | 5.44:1 |
| Typesmith | Pencil on Paper | 3.19:1 | 5.50:1 |
| Lattice | Gray-600 on Terminal | 2.59:1 | 7.50:1 |
Animation map correctly enumerated 142 tweens across 5 compositions, detected stagger groups, flagged pacing issues, and produced scene snapshots.
### Pitch video
https://itnjfahrnzqvcluhrtif.supabase.co/storage/v1/object/public/assets/uploads/8f043e1c-6882-4fa9-98fd-efb6b3583afa.mp4
### Dedicated evals
https://www.heygenverse.com/a/2cac956b-3d14-47bf-90e8-3c1f50e671f3
## Test plan
- [x] Eval: 10 compositions (5 baseline, 5 treatment), all rendered
- [x] Contrast audit caught 4/4 failing palettes, 0 missed
- [x] \`hyperframes validate\` shows contrast warnings by default (exit 0)
- [x] \`hyperframes validate --no-contrast\` skips audit
- [x] \`hyperframes validate --json\` includes contrast data
- [x] Animation map tested on 3 compositions (17, 27, 51 tweens)
- [x] Stagger detection, dead zones, snapshots, timeline all verified
- [x] \`bun run build\` passes
- [x] \`bun run lint\` passes (0 errors, 0 warnings, 0 skill lint issues)
Replace old text-only wordmarks and complex favicon with new HyperFrames
brand assets featuring the gradient icon. Add dark/light logo switching
to README via GitHub's <picture> element.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds `hyperframes catalog` for browsing the registry:
- Default: non-interactive table output (agent-friendly)
- --type block/component and --tag filters
- --json for machine-readable output
- --human-friendly for interactive picker that installs on select
Registered in cli.ts, help.ts, documented in docs/packages/cli.mdx.
## What
Add 28 transition blocks from the Hyperframe Template Structure catalog, bringing the registry to 53 total items.
### Shader transitions (14 blocks, WebGL, 4s each)
`domain-warp-dissolve`, `ridged-burn`, `whip-pan`, `sdf-iris`, `ripple-waves`, `gravitational-lens`, `cinematic-zoom`, `chromatic-radial-split`, `glitch`, `swirl-vortex`, `thermal-distortion`, `flash-through-white`, `cross-warp-morph`, `light-leak`
### CSS transition showcases (14 blocks, various durations)
`transitions-3d`, `transitions-blur`, `transitions-cover`, `transitions-destruction`, `transitions-dissolve`, `transitions-distortion`, `transitions-grid`, `transitions-light`, `transitions-mechanical`, `transitions-other`, `transitions-push`, `transitions-radial`, `transitions-scale`, `transitions-shader`
## Why
Phase D content accumulation. Transitions are the most-requested category for the catalog.
## How
- Shader transitions extracted from `shader-showcase.zip`, each a standalone HTML with WebGL shaders
- CSS transitions extracted from `showcase-bundle.zip`, each a standalone showcase page
- All tagged with `transition` + `shader` or `showcase` for catalog grouping
- Preview thumbnails generated for all 28 blocks
- Catalog pages + index regenerated
## Test plan
- [x] All 28 blocks produce preview thumbnails
- [x] `registry-item.json` validates for all blocks
- [x] Catalog pages generated (45 total items in catalog-index.json)
- [x] `oxfmt --check` passes
## What
New skill `hyperframes-registry` that teaches AI coding agents how to install and wire registry blocks and components into HyperFrames compositions.
### Skill structure
```
skills/hyperframes-registry/
SKILL.md — triggers, overview, quick reference
references/
install-locations.md — default paths, hyperframes.json config
wiring-blocks.md — iframe inclusion, data attributes, positioning
wiring-components.md — snippet merging (HTML, CSS, JS, timeline)
discovery.md — manifest reading, item fields, available items table
demo-html-pattern.md — why components ship demo.html, structure conventions
examples/
add-block.md — worked example: data-chart block install + wiring
add-component.md — worked example: shimmer-sweep component install + wiring
```
## Why
Phase B of the catalog plan (PR 10). Without this skill, agents using `hyperframes add` have to guess how to wire installed items into compositions. The skill encodes the iframe/snippet patterns so agents get it right on the first attempt.
## How
- SKILL.md frontmatter triggers on: `hyperframes add`, "block", "component", `hyperframes.json`
- References cover every step: discovery, install, wiring blocks (iframe), wiring components (snippet merge), and the demo.html convention
- Two worked examples walk through complete install-to-preview workflows
- Updated CLAUDE.md skills table + trigger rules, README.md skills table, docs/packages/cli.mdx
## Test plan
- [x] `scripts/lint-skills.ts` passes (checked 4 skill files, no issues)
- [x] `oxfmt --check` passes on all markdown files
- [x] SKILL.md frontmatter has valid `name` and `description`
- [x] All reference links in SKILL.md resolve to existing files
- [x] CLAUDE.md, README.md, and docs CLI page updated with new skill
Vance Ingalls