Commit Graph
346 Commits
Author SHA1 Message Date
Vance IngallsandClaude Opus 4.6 39f363bad5 fix(core): allow extra attributes on scene divs in assembler regex
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>
2026-04-16 00:18:01 -07:00
Vance IngallsandClaude Opus 4.6 965000e2f2 docs(skills): strengthen eval gates with two-step async validation and assembler
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>
2026-04-16 00:02:07 -07:00
Vance IngallsandClaude Opus 4.6 d794b0088e feat(core): add deterministic scene assembler
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>
2026-04-15 23:43:28 -07:00
Vance IngallsandClaude Opus 4.6 4e17c2ad44 fix(core): exclude .hyperframes from studio lint file walk
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>
2026-04-15 23:34:34 -07:00
Vance IngallsandClaude Opus 4.6 76bdc706b3 docs(skills): add script tag, transform, contrast, and visibility rules to fragment spec
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>
2026-04-15 23:08:42 -07:00
Vance IngallsandClaude Opus 4.6 7337e4ff76 docs(skills): add strict scene fragment spec to multi-scene pipeline
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>
2026-04-15 23:05:12 -07:00
Vance IngallsandClaude Opus 4.6 e3a7ebdcf6 merge: resolve conflicts in SKILL.md references section
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>
2026-04-15 22:43:32 -07:00
Vance IngallsandClaude Opus 4.6 52b21edb81 fix(skills): add lint and validate as blocking gates alongside eval
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>
2026-04-15 22:41:56 -07:00
Vance IngallsandClaude Opus 4.6 317d322ace test(lint): add 11 test cases for 3 new multi-scene lint rules
All 33 tests pass (18 existing + 15 new).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 22:30:24 -07:00
Vance IngallsandClaude Opus 4.6 3f7043a6a8 fix(skills): make scene evaluation a blocking gate, not advisory
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>
2026-04-15 22:25:36 -07:00
James RussoandClaude Opus 4.6 237847e5c6 docs: add prompt cookbook + prompting guide for AI agents (#286)
* 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>
2026-04-15 22:22:46 -07:00
Vance IngallsandClaude Opus 4.6 bba8d7a7b6 fix: address PR review — lint bugs, picker crashes, pipeline gaps
Blockers:
- #2: late_init_set false positive on fractional opacity (0.5 matched as 0)
  Fixed: /opacity\s*:\s*0(?![.\d])/ negative lookahead
- #3: scene-1 prefix skip matches scene 10+ (s1- matches s10-)
  Fixed: extract full number and compare exactly

High severity:
- #4: autoAlpha not covered by late_init_set
  Fixed: checks both opacity and autoAlpha
- #5: al() crashes on non-hex colors (#fff shorthand, rgb(), null)
  Fixed: guard + shorthand expansion + NaN fallback
- #6: "Full palette" with null bg crashes isDark
  Fixed: null guard defaults to dark
- #7: template literals missed by tl_from_in_multiscene
  Fixed: regex includes backtick quotes

Medium:
- #9: no retry limit on eval failures → infinite loop
  Fixed: max 2 retries, then escalate to user
- #10: vague ID convention
  Fixed: explicit s{N}- prefix rule in multi-scene.md
- #11: visual-style.md backward compat
  Fixed: Step 0b checks both filenames
- #13: preview_html script injection
  Fixed: documented prohibition in design-picker.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 22:22:20 -07:00
Vance IngallsandClaude Opus 4.6 41789e057f fix(skills): don't start blocking servers in subagents
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>
2026-04-15 22:14:55 -07:00
Vance IngallsandClaude Opus 4.6 9750c024e9 fix(skills): simplify design picker prompt to yes/no question
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 22:03:46 -07:00
Vance IngallsandClaude Opus 4.6 09d14f64cf fix(skills): write expanded prompt to file, not chat
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>
2026-04-15 22:00:49 -07:00
Vance IngallsandClaude Opus 4.6 ee1ba17dff refactor(skills): extract conditional steps into reference files
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>
2026-04-15 21:52:41 -07:00
Vance IngallsandClaude Opus 4.6 a5d1f71971 feat(skills): add prompt expansion step for sparse user prompts
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>
2026-04-15 21:48:45 -07:00
Vance IngallsandClaude Opus 4.6 27de9c7573 feat(skills): add streaming scene evaluation in multi-scene builds
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>
2026-04-15 21:33:54 -07:00
Miguel Ángel a6ff9e2d9f fix(player): preserve iframe media attributes for runtime sync (#291)
## 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)
2026-04-16 06:20:28 +02:00
Vance IngallsandClaude Opus 4.6 810ca78001 fix(skills): instruct user to paste design.md back into conversation
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>
2026-04-15 21:02:48 -07:00
Vance IngallsandClaude Opus 4.6 edc38bc5fd feat(lint): add 3 multi-scene lint rules, replace immediateRender rule
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>
2026-04-15 20:48:43 -07:00
Vance IngallsandClaude Opus 4.6 84f5ff27e2 fix(skills): tl.set init calls must fire at time 0, not scene start
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>
2026-04-15 20:38:59 -07:00
Vance IngallsandClaude Opus 4.6 69a742a53b fix(skills): replace tl.from with tl.set+tl.to pattern for multi-scene builds
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>
2026-04-15 20:29:44 -07:00
Vance IngallsandClaude Opus 4.6 2db5f1f1a1 fix(skills): prevent scene CSS from overriding scaffold positioning
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>
2026-04-15 20:17:59 -07:00
Vance IngallsandClaude Opus 4.6 5176aea065 feat(lint): add missing_immediate_render_false rule for multi-scene compositions
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>
2026-04-15 19:31:32 -07:00
Vance IngallsandClaude Opus 4.6 cf3d5d7008 feat(skills): add multi-scene subagent build pattern for 4+ scene compositions
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>
2026-04-15 18:12:48 -07:00
Vance IngallsandClaude Opus 4.6 bad540e229 fix(skills): verify picker server responds before sharing URL with user
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>
2026-04-15 17:46:19 -07:00
Vance IngallsandClaude Opus 4.6 1add5955b2 fix(skills): require style reference compliance in design picker generation
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>
2026-04-15 17:32:29 -07:00
Vance IngallsandClaude Opus 4.6 c07dfed46c fix(skills): add instruction to follow design.md as source of truth during construction
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>
2026-04-15 17:07:52 -07:00
Vance IngallsandClaude Opus 4.6 2afb7aba3c feat(skills): add design.md picker template with mix-and-match visual configurator
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>
2026-04-15 16:55:43 -07:00
James Russo 87ce26de8a fix(docs): namespace custom CSS variables to prevent Mintlify collision (#285)
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).
2026-04-15 14:07:34 -07:00
James 0a3ca498ea chore: release v0.3.1 v0.3.1 2026-04-15 18:42:14 +00:00
Vance IngallsandClaude Opus 4.6 a262ad59f3 chore(skills): remove 1,685 lines of redundant skill content (#283)
* 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>
2026-04-15 10:51:10 -07:00
Vance IngallsandClaude Opus 4.6 0792ede4d2 feat(skills): adopt design.md as the project design system format
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>
2026-04-15 00:20:13 -07:00
James Russo acf8223171 fix(skills): correct README skills table and move orphaned scripts into hyperframes skill (#282)
## 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)
2026-04-14 20:41:54 -07:00
James Russo 26f6ef4252 docs(quickstart): add skills-first onboarding path (#279)
## 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)
2026-04-14 19:15:26 -07:00
James Russo 8551cffddd docs: add AGENTS.md for universal AI assistant configuration (#278)
## 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)
2026-04-14 19:13:26 -07:00
James Russo cd17074f3b docs: restructure README with skills-first quick start, demo GIF, catalog, and fix pnpm refs (#277)
## 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)
2026-04-14 19:10:44 -07:00
Miguel Ángel d3f2295d80 feat(skills): add contrast audit + animation map quality skills (#267)
## 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)
2026-04-15 03:09:56 +02:00
James RussoandClaude Opus 4.6 5b8207730d chore(docs): update logos, favicon, and README branding (#272)
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>
2026-04-14 17:15:32 -07:00
James Russo 13ab1932ad feat(cli): catalog browser command (#271)
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.
2026-04-14 16:46:42 -07:00
James Russo 9943091247 feat(registry): seed transition blocks — 14 shader + 14 CSS showcase (#270)
## 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
2026-04-14 16:32:27 -07:00
James Russo d37d738be9 feat(registry): seed blocks batch — social overlays, data viz, showcases (#269)
## What

Add 11 blocks from the Hyperframe Template Structure catalog, bringing the registry to 25 total items.

### Social overlays
| Block | Dimensions | Duration | Description |
|-------|-----------|----------|-------------|
| `instagram-follow` | 1080×1920 | 4.5s | Instagram follow overlay with profile card |
| `tiktok-follow` | 1080×1920 | 4.5s | TikTok follow overlay with profile card |
| `yt-lower-third` | 1920×1080 | 4.5s | YouTube subscribe lower third |
| `x-post` | 1920×1080 | 5s | X/Twitter post card with engagement |
| `reddit-post` | 1920×1080 | 5s | Reddit post card with upvotes |
| `spotify-card` | 1080×1920 | 5s | Spotify now-playing card |
| `macos-notification` | 1920×1080 | 5s | macOS notification banner |

### Data & visualization
| Block | Duration | Description |
|-------|----------|-------------|
| `ascii-dashboard` | 10s | Retro terminal-style data viz |
| `ascii-lightning` | 9s | ASCII art lightning bolt animation |

### Showcases
| Block | Duration | Description |
|-------|----------|-------------|
| `app-showcase` | 5.5s | Floating smartphone screens |
| `ui-3d-reveal` | 13s | Perspective 3D UI reveal |

## Why

Phase D content accumulation. The registry pipeline (PRs 6-10) is in place — this PR exercises it at scale.

## How

- Extracted from zip files in the Hyperframe Template Structure Notion doc
- Social overlays: single-file standalone HTML, copied directly
- Multi-file blocks (ascii-*, app-showcase, ui-3d-reveal): converted `<template>` sub-compositions to standalone HTML with proper `<!doctype>` wrappers
- All previews (PNG + MP4) rendered locally via `generate-catalog-previews.ts`
- Catalog MDX pages regenerated via `generate-catalog-pages.ts`
- `docs.json` updated with new catalog entries

## Test plan

- [x] All 11 blocks render to PNG + MP4 without errors
- [x] Catalog pages generated for all 17 items (14 blocks + 3 components)
- [x] `registry-item.json` files have correct dimensions, duration, tags
- [x] `oxfmt --check` passes on all files
2026-04-14 16:29:25 -07:00
James Russo 4bde66f532 feat(skills): hyperframes-registry skill (#261)
## 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
2026-04-14 16:27:24 -07:00
James Russo b32611c2c3 docs: codegen per-item MDX pages from registry (#263)
## What

Script that auto-generates per-item catalog documentation from `registry-item.json` manifests.

**New file:** `scripts/generate-catalog-pages.ts`

**Outputs:**
- `docs/catalog/blocks/<name>.mdx` — per-block detail page
- `docs/catalog/components/<name>.mdx` — per-component detail page
- `docs/public/catalog-index.json` — flat manifest for the grid page (constant-sized regardless of catalog size)
- Updates `docs/docs.json` with a Catalog tab containing Blocks + Components groups

## Why

Phase B of the catalog plan (PR 9). After this lands, future content PRs don't need to write MDX by hand — the script generates everything from `registry-item.json`.

## How

The script:
1. Walks `registry/blocks/*/registry-item.json` and `registry/components/*/registry-item.json`
2. **Wipes `docs/catalog/` before regenerating** — deleted items don't leave stale pages
3. Generates MDX per item with: title, description, tag badges, preview image, install command, details table, files table, usage hint, and related skill link
4. Emits `catalog-index.json` with `{name, type, title, description, tags, href, preview}` per item
5. Updates `docs.json` navigation — inserts or replaces the Catalog tab with current block/component page lists

Run before Mintlify builds: `npx tsx scripts/generate-catalog-pages.ts`

## Test plan

- [x] Script compiles — passes `lefthook` typecheck + lint + format
- [x] CONTRIBUTING.md documents the auto-generation workflow
- [ ] Full end-to-end test requires PRs 6+7 to merge first (items must exist in registry/)
2026-04-14 16:24:24 -07:00
James Russo ea6f949922 ci: render catalog previews on PR (#262)
## What

CI workflow that auto-renders preview thumbnails for new/changed registry blocks and components on pull requests.

**New files:**
- `scripts/generate-catalog-previews.ts` — catalog preview renderer supporting all three registry item types
- `.github/workflows/catalog-previews.yml` — GitHub Actions workflow triggered on PRs touching `registry/blocks/` or `registry/components/`

## Why

Phase B of the catalog plan (PR 8). After this lands, future block/component PRs don't need to manually generate preview images — CI handles it automatically.

## How

The preview script discovers items from the registry directory structure:
- **Examples**: renders `index.html` (same as the existing `generate-template-previews.ts`)
- **Blocks**: renders the block's standalone HTML file directly (e.g., `data-chart.html`)
- **Components**: renders the component's `demo.html` (the demo.html convention from PR 7)

The CI workflow:
1. Detects which blocks/components changed in the PR via `git diff`
2. Renders thumbnails for only the changed items (not the full catalog)
3. Uploads preview PNGs as artifacts

Output goes to `docs/images/catalog/<type>/<name>.{png,mp4}` (separate from the existing `docs/images/templates/` directory).

Supports CLI flags: `--only <name>`, `--type <example|block|component>`, `--skip-video`.

## Test plan

- [x] Script compiles and passes typecheck (`lefthook pre-commit` ran lint + typecheck + format)
- [x] Workflow YAML is valid (standard GitHub Actions syntax, follows existing ci.yml patterns)
- [ ] Full end-to-end test requires Chrome + FFmpeg (runs in CI, not testable locally without producer deps)
2026-04-14 16:21:23 -07:00
James Russo b0f754a7f7 feat(registry): seed components — grain-overlay, shimmer-sweep, grid-pixelate-wipe (#260)
## What

Three reusable effect components for the registry, each with a snippet HTML and companion `demo.html`:

| Component | Description |
|-----------|-------------|
| `grain-overlay` | Animated film grain texture overlay (CSS keyframes, extracted from warm-grain example) |
| `shimmer-sweep` | CSS gradient light sweep across text/elements, driven by GSAP custom property animation |
| `grid-pixelate-wipe` | Grid-based dissolve transition — screen breaks into 16×9 squares that scale in/out with stagger |

Establishes the `demo.html` convention in `CONTRIBUTING.md`.

## Why

Phase B of the catalog plan — seed the first components in the registry. Components are effect snippets that get merged into existing compositions (vs. blocks which are standalone sub-compositions).

## How

- **grain-overlay**: Extracted the grain texture pattern from the warm-grain example. Uses a 200% oversized tiled texture with `steps(1)` keyframe animation for the random-noise effect.
- **shimmer-sweep**: Original implementation using CSS custom properties (`--shimmer-pos`) animated by GSAP. The gradient mask uses `mix-blend-mode: overlay` for a natural light sweep. Auto-injects `.shimmer-mask` elements into `.shimmer-sweep-target` wrappers.
- **grid-pixelate-wipe**: Creates a 16×9 CSS Grid of cells, animated with GSAP stagger. Users drive `.grid-cell` `scale` directly in their timeline.

Simplify review addressed: scoped `.grain-texture` under `#grain-overlay`, scoped `.grid-cell` under `#grid-pixelate-overlay`, removed `window.gridPixelateIn/Out` globals in favor of direct GSAP patterns.

Each component ships a `demo.html` — a standalone composition that previews the effect and doubles as a fixture for the CI preview pipeline (PR 8).

## Test plan

- [x] `hyperframes add grain-overlay` installs to `compositions/components/grain-overlay.html`
- [x] `hyperframes add shimmer-sweep` installs to `compositions/components/shimmer-sweep.html`
- [x] `hyperframes add grid-pixelate-wipe` installs to `compositions/components/grid-pixelate-wipe.html`
- [x] All three return correct `--json` output with snippet and type info
- [x] `registry-item.json` files validate against the JSON Schema
- [x] `demo.html` files are self-contained with correct `data-composition-id` and `window.__timelines` registration
- [x] `oxfmt --check` and `oxlint` pass on all files
- [x] `CONTRIBUTING.md` documents the `demo.html` convention and registry item checklist
2026-04-14 16:18:22 -07:00
James Russo 4685e5cd74 feat(registry): seed blocks — data-chart, flowchart, logo-outro (#259)
Extract three standalone blocks from existing example templates:

- data-chart: Animated bar + line chart with staggered reveal (from nyt-graph)
- flowchart: Decision tree with SVG connectors and cursor interaction (from decision-tree)
- logo-outro: Cinematic logo reveal with tagline and URL pill (from product-promo)

Each block is a complete HTML composition installable via `hyperframes add <name>`.
Blocks render as iframes in host compositions.
2026-04-14 16:16:03 -07:00
James RussoandClaude Opus 4.6 b23b0751da fix(player): parent-frame media playback for mobile (#266)
* fix(player): parent-frame media playback for mobile

Mobile browsers block media.play() inside iframes when the user
gesture happened in the parent frame — postMessage doesn't transfer
user activation (per the User Activation v2 spec).

## Problem

The player renders compositions in a sandboxed iframe. When a user
taps play in the parent frame, the player sends a postMessage to the
iframe's runtime, which calls audio.play(). On mobile, this fails
silently because the iframe has no user activation context.

## Solution

The player now extracts ALL timed media elements (audio/video with
data-start) from the iframe's DOM (same-origin access), creates
parent-frame copies, and disables the iframe originals. On play(),
parentMedia.play() runs synchronously in the gesture call stack,
satisfying mobile autoplay policy.

### Generic media handling

- Finds all `audio[data-start], video[data-start]` in the iframe
- Creates a parent-frame copy for each (Audio or Video element)
- Preserves data-start offsets for correct seek positioning
- Strips data-start from iframe elements so the runtime ignores them
- Falls back to iframe media for cross-origin iframes

### `audio-src` attribute

Convenience for the common single-narration case. When set, the
player starts preloading audio immediately — before the iframe loads.
This eliminates the loading delay that caused jittery playback.

### No active sync

Both parent media and the GSAP timeline are real-time systems. When
started simultaneously, they naturally stay within ~10ms — no drift
correction needed. Active sync with coarse granularity (50ms polling)
caused MORE jitter than it prevented via repeated audio seeks.

## CI

- Added unified `test` job replacing separate per-package test jobs
- Added root `test` script: `bun run --filter '*' test`
- New packages with test scripts are automatically included
- Added happy-dom for player DOM tests

## Tests

- 10 new tests for parent-frame media: preloading, play, pause,
  seek, muted/rate sync, cleanup, attribute changes
- All 21 player tests pass

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(shader-transitions): pass CI when no test files exist

Add --passWithNoTests to vitest run so the unified test job
doesn't fail on packages that have a test script but no test
files yet.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cli): update tests for new id field and GSAP lint rule

- normalize.test.ts: loadTranscript now assigns id fields (w0, w1, etc.)
  to SRT/VTT results and empty string for words-json passthrough
- lintProject.test.ts: add GSAP CDN script to validHtml() fixture to
  satisfy the missing_gsap_script lint rule added in core

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(cli): add missing data-start/data-duration to validHtml fixture

The validHtml() test fixture was missing data-start and data-duration
attributes, triggering the root_composition_missing_data_start and
root_composition_missing_data_duration lint warnings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): fetch LFS objects for producer test job

Producer regression tests compare rendered output against reference MP4
files stored in git LFS. Without lfs: true, checkout fetches pointer
files instead of actual videos, causing "moov atom not found" errors.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: remove redundant test-producer job

The regression workflow already runs the same 28 producer fixtures
in a Docker container with prod-matching Chrome/fonts/ffmpeg, sharded
across 8 parallel matrix jobs with 40-min timeouts. The CI test-producer
job was a duplicate that ran on bare runners with worse determinism
and a 15-min timeout too short for all fixtures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-14 11:20:07 -07:00
James RussoandClaude Opus 4.6 9bf4956fae chore(shader-transitions): add to CI publish pipeline and README (#264)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 22:07:19 -07:00