Commit Graph
1268 Commits
Author SHA1 Message Date
ukimsanovandClaude Opus 4.7 3542a79b3a fix(skill): reconcile SFX drift tolerance to ±0.1s across script + prose
Vai (vanceingalls) caught a 10× tolerance mismatch between the script
and the prose. Rames confirmed as blocking:

  step-5-build.md:458 (per-beat evidence rule):  ±0.05s
  step-6-validate.md     (playback verification):  ±0.1s
  w2h-verify.mjs:29 (SFX_DRIFT_TOLERANCE_S):       0.5s

So an agent writing per-beat evidence at ±0.05s reports a 0.3s drift
as FAIL, while the script reports the same drift as PASS. The pasted-
verbatim report contradicts the agent's evidence block — exactly the
kind of internal contradiction this PR was built to eliminate.

Converged on ±0.1s everywhere:

- w2h-verify.mjs:29: SFX_DRIFT_TOLERANCE_S = 0.1 (3 frames at 30fps)
- step-5-build.md:458: ±0.05s → ±0.1s, with cross-reference noting it
  matches the script + step-6 playback floor

The other ±0.5s constants in step-6 are for total audio/video duration
and storyboard beat-range matching — those are coarser-grained timing
checks (not SFX-to-visual sync). Left as-is intentionally.

Regression check: huly-v3 now flags 4 SFX drifts instead of 3 — the
new one is glitch-1.mp3 at 0.20s drift (6 frames). The old 0.5s
tolerance was masking this real timing issue.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 12:15:39 -07:00
ukimsanovandClaude Opus 4.7 a5bc11632f fix(skill): address PR #1026 review — find $HOME, order-indep audioRegex, cached reads
Three issues from Miguel's + Rames's reviews:

**[Blocking] find / violates CLAUDE.md guidance (Miguel)**

CLAUDE.md says: "When running find, search from . (or a specific path),
not / — scanning the full filesystem can exhaust system resources on
large trees." I introduced 3 instances of `find /` in skill prose to
help sub-agents locate skill files from unknown CWDs. Replaced all 3
with `find "$HOME" ... -maxdepth 10`. Verified all 4 skill files
resolve correctly under $HOME on the testbed setup.

Files: step-3-storyboard.md (×2), step-5-build.md, step-6-validate.md.

**[Blocking] SFX audio regex assumed attribute ordering (Miguel + Rames)**

The v2 audioRegex required src= to appear lexically BEFORE data-start=
in the same <audio> tag. But capabilities.md:365 — in the same skill —
documents the canonical pattern with src= LAST:

  <audio id="..." data-start="..." data-duration="..." data-volume="..."
         data-track-index="..." src="...">

Real compositions following the docs would have audio tags that don't
match the regex → SFX reported as MISSING → false FAIL in the script
output → false alarm in the user-facing summary. Exactly what v2 was
supposed to fix.

Replaced with the same two-step shape that readBeatDurationsFromIndex
already uses correctly: match `<audio[^>]*?>` to grab the whole tag,
then extract src= and data-start= from the tag string with independent
regexes. Verified both attribute orderings (src first, src last) now
work via inline node test.

**[Minor] readBeatCompositions / readBeatDurationsFromIndex re-read on
every call (Rames)**

Added process-scoped caches to both helpers. The script is a one-shot
CLI so no invalidation needed — first call hits disk, subsequent calls
return the cached result. readBeatCompositions was called 3×,
readBeatDurationsFromIndex 2× — now 1× each.

**Regression checks**

- huly-v3: 4 PASS · 3 FAIL · 1 INFO (unchanged — same 3 real issues
  flagged: 48px wordmark, missing shaders, 3 SFX drifts)
- huly-launch-v4: 6 PASS · 0 FAIL · 2 INFO (unchanged)
- Lint + format: clean

2 files changed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 10:44:45 -07:00
ukimsanovandClaude Opus 4.7 f4a7961bc1 fix(skill): w2h-verify v2 — kill false positives from real-agent debrief
A fresh agent session ran the v1 verify script and the disclosure pasted
into their final summary showed 3 FAIL rows for things that weren't
actually defects:

  Headline font-size: flagged Beat 2 (wordmark SVG), Beat 3 (UI grid),
    Beat 5 (terminal). None of these legitimately have text headlines.
  Timeline coverage: flagged 5/6 beats because the script's regex only
    saw `tl.X(..., 2.5)` literal positions and missed forEach loops,
    variable-position tweens, and long-duration scaler tweens.
  Beat durations: flagged 2 beats because my "duration X.Xs near beat
    label" fallback false-matched non-beat durations
    (e.g., "shader runs — duration 0.7s" near a "Beat 1" mention).

The agent had to write ~5 paragraphs defensively justifying each false
FAIL. That's friction we can fix.

Tested against the agent's actual project (huly-launch-v4): went from
4 FAIL (3 false positives + 1 real bare-table parser miss) to 0 FAIL.
Also re-verified huly-v3 still correctly catches its 3 real issues
(48px wordmark, missing shaders, 3 SFX drifts) — no regression.

**Brand visuals check**

Switched from "≥30% asset usage" (gameable, rewards quantity over quality)
to "at least 1 beat references a captured hero/image/svg" — quality
signal that's cheap to satisfy when real, hard to fake. Excludes fonts,
logos, favicons, contact-sheets.

**Headline check**

Now only flags beats where the LARGEST font-size is in the 40–<80px
range — the "aspiring headline but too small" zone. Below 40px = beat
has no text headline by design (terminal, UI labels, SVG-only); skip.
≥80px = proper headline; pass. Eliminates the false positives on
SVG-dominated and UI-grid beats while still catching the real "headline
too small" failure (Beat 4 at 72px in this run; Beat 1 wordmark at 48px
in another).

**Timeline coverage check**

Three improvements:
1. Detects forEach loops + for-loops containing tl.X() calls — beats
   with these have events at positions the static parser can't read;
   mark as INFO-skipped rather than failed.
2. Detects long-duration tweens — if a single tween's duration covers
   ≥70% of the beat duration (camera dolly, breathing animation), the
   beat has full coverage via persistent motion; skip the position check.
3. New paren-balanced parser for extracting tl.X() position arguments —
   the v1 regex was matching `rgba(86,131,218,0.35)` and capturing 0.35
   as a tween position. The new parser walks paren depth and only
   captures top-level trailing numeric args. No more rgba false matches.

**Shader transitions check**

Two fixes:
1. Filter out inventory lines — lines listing 3+ shader names are
   "what's available," not "what's planned for use." Real use
   mentions one or two shaders per line.
2. Apply the same SFX-context exclusion to the declared side that the
   present-check side already had — "glitch" inside `sfx/glitch-1.mp3`
   no longer counts as a declared shader transition.

For huly-v3: was 6 declared (1 phantom from inventory + 5 + glitch
from SFX), now 2 declared (light-leak, cinematic-zoom) — matches the
storyboard's actual plan.

**Beat duration check**

1. Dropped the "duration X.Xs within 200 chars of beat label" fallback
   — too loose; matched shader durations, animation durations, anything
   labeled "duration". This was the source of the 0.70s misread in the
   debrief.
2. Added a bare-number timing-table parser for the format
   `| 1 | 0.00s | 5.20s | 5.20s | ... |` (with optional `>` blockquote
   prefix). Computes duration = end - start.
3. Added a negative lookahead so `\bB3\b` doesn't false-match "B3.1"
   sub-beats and grab the wrong row.
4. Filter buildBeatIds to only numbered beats — skips the root
   composition (`data-composition-id="main"`) so it doesn't inflate
   "parseable" count.

**Brand visuals + asset count**

Excluded fonts/ subdirectory (always-used via @font-face → would
always pass) and contact-sheet-*.jpg (pipeline outputs, not website
inputs). Both inflated the denominator and weakened the signal.

**Edge case fixes**

- Removed `basename` unused import (oxlint).
- Fixed shader-name substring overlap: longest-name-first matching so
  "cross-warp-morph" doesn't double-count as "cross-warp".
- SFX timestamps now collect ALL audio tags per file (multi-timestamp
  SFX like click×3); picks closest index timestamp to each storyboard
  timestamp instead of just keeping the last.

**Step 6 doc**

Updated the skill's "w2h-verify — the source of truth" section to
describe the new checks accurately and what failure mode each catches.

2 files changed, +486/-109. Format + lint clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 09:03:35 -07:00
ukimsanovandClaude Opus 4.7 190f1ec71a feat(skill): w2h-verify script + Step 6 DoD wiring — tooling-based enforcement
Three rounds of text-based enforcement plateaued. A third agent debrief
showed the same failures: 9% asset usage (vs ≥30% floor), shader
transitions declared in STORYBOARD.md but not in shipping index.html,
SFX timestamps drifted up to 12.4s, animation-map skipped, MP4 not
rendered, honest-disclosure section omitted from final summary.

The pattern is clear: language-only enforcement is selectively
interpretable by the agent under ship pressure. Move enforcement into
tooling — facts the agent can't fudge.

**New script: `skills/website-to-hyperframes/scripts/w2h-verify.mjs`**

Pure file-analysis script (no shell spawns). Computes six checks and
prints a PASS/FAIL/INFO table:

1. Asset usage — assets referenced in compositions ÷ assets captured;
   target ≥30%. Tested against videos/huly-v3: caught 6/74 = 8% FAIL.
2. Shader transitions consistency — STORYBOARD.md-declared shaders vs
   index.html. Longest-name matching to avoid substring false positives
   (cross-warp-morph not double-counted as cross-warp). Tested: caught
   6 declared / 1 present / 5 missing.
3. SFX timestamp drift — parses STORYBOARD.md table rows for
   `sfx/X.mp3` + time-with-`s`, parses index.html <audio data-start>,
   flags drift >0.5s. Tested: caught 12.4s drift on click.mp3 that
   the agent debrief didn't even mention.
4. animation-map.json existence — explicit file check.
5. Rendered MP4 existence — scans project root, output/, renders/.
6. Required artifacts — STORYBOARD.md, DESIGN.md, SCRIPT.md, index.html
   all present.

Exit code: 0 (all pass) or 1 (one or more fail). The script's output
becomes the Step 6 deliverable — paste verbatim into the user-facing
summary.

**Skill update: `step-6-validate.md`**

Adds `w2h-verify report` to the DoD checklist with the rule: paste the
FULL output verbatim into the final summary. Cherry-picking rows,
substituting adjectives for percentages, or omitting FAIL lines is
explicitly forbidden. If a row says FAIL, either fix it and re-run
until PASS or include the FAIL line verbatim in "What I did NOT
verify" with a one-sentence reason.

Test run against the project that prompted this:

```
SUMMARY: 1 PASS · 4 FAIL · 1 INFO
- Asset usage: FAIL 6/74 (8%) target ≥30%
- Shader transitions: FAIL 6 declared, 1 present, 5 missing
- SFX timestamps: FAIL 3 drifted >0.5s (max 12.4s)
- animation-map.json: FAIL missing
- Rendered MP4: INFO no .mp4 found
- Required artifacts: PASS
```

The agent could selectively ignore "the WCAG warnings are false
positives." The agent cannot selectively ignore a line that says
`6/74 (8%) — target ≥30%`.

2 files changed (+ 1 new script, ~330 lines). Format checks pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 00:45:42 -07:00
ukimsanovandClaude Opus 4.7 5594a8286c fix(skill): w2h enforcement round 2 — close the deeper shirking patterns
A second agent debrief (different session, with the prior enforcement edits
applied) revealed the most damning failure yet: the agent used 1 of 65
captured assets. They wrote their own "Asset Audit" table saying SKIP for
64 hero illustrations, brand SVGs, and signature visuals. The entire point
of capture is to USE the brand's assets — that gate was bypassed entirely.

The debrief also revealed 5 other patterns the prior enforcement missed.
This commit closes all 6.

**Pattern A — Asset Audit gate (step-3-storyboard.md)** — BIGGEST FIX

Adds a non-skippable Asset Audit section in Step 3 that requires viewing
every page of capture/assets/contact-sheet-*.jpg + svgs/contact-sheet-*.jpg,
pasting 5 distinctive assets per page (with descriptions of what's actually
pictured), and choosing USE/SKIP per asset with one-sentence justification
for each SKIP. Brand-defaults floor: at least one beat MUST use a captured
hero illustration/photograph/signature diagram — not just the logo. The
forbidden list explicitly calls out: reading asset-descriptions.md alone
without opening the contact sheets, and rebuilding signature graphics in
CSS when the brand's own SVG of that graphic is in capture/assets/.

**Pattern B — Auto mode scope (SKILL.md + step-2-brief.md)**

Clarifies that auto mode covers user-PREFERENCE gates (TTS provider,
voice, beat count, captions yes/no — where the agent decides on the
user's behalf) but NOT quality-VERIFICATION gates (Asset Audit, per-beat
HTML read, DoD checklist, honest disclosure). Adds explicit test for
distinguishing: if the answer changes the content of the video, it's a
preference; if the answer is "did the verification happen?", it's a
quality gate. The agent that skipped the captions question by reasoning
"auto mode says bias toward action" was misusing auto mode.

**Pattern C — 3-path audio/motion verification (step-6-validate.md)**

Replaces the prior "Path 1 or explicit deferred" with three explicit
paths: (1) Play preview in Playwright, (2) render low-res MP4 and read
frames at ≥5fps, or (3) explicit deferred disclosure with QUANTIFIED
coverage gap ("18/900 frames = 2% coverage"). The percentage in Path 3 is
mandatory — vague "deferred to user" was the loophole. Forbidden: claiming
"confirmed via snapshot" as audio/motion evidence; 18 PNGs from a 900-
frame video is 2% coverage, not verification.

**Pattern D — Sub-agent diagnoses are hypotheses (beat-builder-guide.md)**

When a sub-agent reports "this is a linter false positive" / "this is a
known bug", that is a HYPOTHESIS from one symptom — not a verified
finding. Before propagating the workaround to other beats, main agent
must EITHER read the source to confirm OR explicitly disclose the
unverified claim. The debrief showed the main agent applied beat-2's
"linter false positive" diagnosis to beat-4 without ever reading
packages/core/src/lint/utils.ts to confirm.

**Pattern E — Re-snapshot after parallel sub-agents (step-5-build.md)**

When sub-agents run in parallel, each snapshots a project where sibling
beats may not exist yet. Their snapshots at beat boundaries or during
shader transitions show the WRONG content (typically previous beat).
Required after all complete: a canonical project-wide snapshot via the
CLI — that's what Step 6's DoD uses. Sub-agents' intermediate snapshots
are sanity checks, not the deliverable.

**Pattern F — STORYBOARD.md must be updated when divergence accepted
(beat-builder-guide.md)**

When a sub-agent diverges from spec ("the real brand mark is lowercase
'huly' not uppercase 'HULY'") AND the main agent accepts the divergence,
the main agent MUST patch STORYBOARD.md to reflect reality. Otherwise
the spec lies and the next session reading it as ground truth gets the
wrong information. Examples covered: brand mark casing, cell size at
scale, SFX timing alignment.

6 files changed, +131/-11 (net +120 lines of enforcement).
Format checks pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 21:51:52 -07:00
ukimsanovandClaude Opus 4.7 18444decde fix(skill): w2h enforcement edits — close the 9 shirking patterns from agent debrief
After the audit-fix commit (e47bc6c6) landed clarity fixes, a real test run
revealed that the skill still got skipped at the gates that matter most.
The agent's honest debrief listed 9 distinct patterns where it judged
"deliver fast" over "verify what the skill said to verify."

This commit forces evidence at each of those gates so silent skips are no
longer possible without lying — at which point the gate fails by design.

**Patterns 1, 3, 8 — step-5-build.md**

- Pattern 1: "Read each beat HTML top-to-bottom" gate now requires a
  structured evidence block per beat with quoted CSS hex codes, headline
  font-size, captured asset paths, GSAP first/last events, and SFX trigger.
  "I read it and it looks fine" / "the sub-agent confirmed" are not
  acceptable. Snapshots are 3 frames out of 300+ in motion.
- Pattern 3: SFX timestamp computation rule. Every data-start MUST be
  computed (beat-local + beat global start = global timestamp), not
  estimated by eye. The agent typed `data-start="6.0"` for a storyboard
  moment at 5.0s — a 1-second drift, not a rounding error.
- Pattern 8: Recurring sub-agent workarounds must be surfaced under
  "Tooling issues encountered" — burying them means the next session
  hits the same bug.

**Patterns 2, 6, 7, 9 — step-6-validate.md**

- Pattern 2: WCAG contrast warnings now require per-warning verification
  with quoted validator output and opacity check at the sampled timestamp.
  Blanket dismissal as "mostly transition-window false positives" is
  explicitly forbidden.
- Pattern 6: animation-map.json check added to the DoD checklist —
  runs `skills/hyperframes/scripts/animation-map.mjs` and confirms
  per-beat event coverage.
- Pattern 7: Audio + motion verification is now a separate DoD item from
  snapshot verification. Snapshots are silent stills; you must actually
  play the preview and confirm SFX lands at storyboard timestamps within
  ±0.1s. CLI-only sessions must explicitly disclose this as deferred.
- Pattern 9: Honest disclosure section added — final user-facing summary
  MUST end with "What I verified" and "What I did NOT verify" blocks.
  "Looks great, ready to ship" with no disclosure now fails the gate.

**Patterns 4, 5 — beat-builder-guide.md**

- Pattern 4: Sub-agent FLAG protocol. Required phrasing for non-blocking
  issues is concrete and actionable with line numbers. Forbidden phrasing:
  "if X feels too long, you could...", "consider tweaking...", "might
  want to...". Main agent must address each FLAG or write a rejection.
- Pattern 5: Spec ambiguity escalation. If the storyboard names a
  transition without establishing the start state ("Row 1 transitions
  blue → orange" but Row 1's initial color isn't specified), sub-agent
  MUST flag it and ask for confirmation rather than guess. Picking an
  interpretation silently means the build "looks fine" while diverging
  from intent.

3 files changed, +170/-21 (net +149 lines of enforcement language).
Format checks pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 20:12:46 -07:00
ukimsanovandClaude Opus 4.7 e47bc6c6db fix(skill): w2h audit — resolve contradictions, path issues, missing fallbacks
10 fixes from an audit of skills/website-to-hyperframes/ targeting clarity for
AI agents following the pipeline. Each fix is a surgical edit; no behavior
changes for human readers.

**Critical contradictions resolved:**
- capabilities.md: `onUpdate`/`tl.call` was simultaneously documented as required
  (canvas/WebGL/typing patterns) and banned (determinism). Sub-agents reading
  the ban would silently strip working code from Canvas 2D and Three.js beats.
- step-1-design.md: Removed "Depth & Elevation" section template that the same
  file's Rules section forbade. Renumbered remaining sections (6→5).
- beat-builder-guide.md: Narrowed "no onUpdate for counters" rule so canvas
  rendering loops aren't caught by the prohibition.

**Path resolution fixes for sub-agents:**
Sub-agents run from `<project-dir>` (e.g. videos/foo/), not repo root, so
repo-relative paths like `skills/website-to-hyperframes/assets/sfx/manifest.json`
fail silently. Replaced with `find / -path ...` patterns that work from any CWD.
- step-3-storyboard.md: sfx/manifest.json + text-effects.md paths
- step-5-build.md: beat-builder-guide.md path

**Missing fallbacks added:**
- step-3-storyboard.md Gate: autonomous mode now propagates from Step 2 — gate
  no longer blocks on explicit approval when user said "surprise me".
- step-4-vo.md: timing-formula recalibration now has concrete steps for both
  "too short" (add pauses) and "too long" (cut highest-density beat).
- step-6-validate.md: agent-authored descriptions fallback when GEMINI_API_KEY
  is unavailable — DoD checklist no longer has a dead end.

**Quick Reference polish:**
- SKILL.md: step-1-design entry now mentions 50-line fast-path exception.

8 files changed, +32/-37 (net -5 lines). Format checks pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 17:57:08 -07:00
Ular Kimsanov 74b86f6cfa Merge pull request #1006 from heygen-com/feat/skill-hyperframes-core-v2
feat(skill): hyperframes core — remove prescriptive tables, reference text-effects (not vendor)
2026-05-21 13:09:13 -07:00
Ular Kimsanov b9e4ca169e Merge pull request #1005 from heygen-com/feat/skill-website-to-hyperframes-v2
feat(skill): website-to-hyperframes — concept-first authoring + per-beat read protocol
2026-05-21 12:43:40 -07:00
Miguel Ángel 4c358e6dcc Merge pull request #1001 from heygen-com/fix/sub-comp-t0-baseline-regen
test(producer): regenerate sub-comp-t0 baseline + add gsap_from_opacity_noop lint rule
2026-05-21 21:42:37 +02:00
Miguel Ángel 4c2a90a1be Merge pull request #1004 from heygen-com/feat/lint-rules-v2
feat(lint): font loading + invalid capture path composition rules
2026-05-21 21:33:38 +02:00
Miguel Ángel 37329b0ba1 Merge pull request #1000 from heygen-com/feat/studio-preserve-playhead
fix(studio): preserve playhead position on composition refresh
2026-05-21 21:29:32 +02:00
Miguel Ángel b58a81160e Merge pull request #933 from heygen-com/05-18-feat_registry_add_blend-difference_text_effect_component
feat(registry): add blend-difference text effect component
2026-05-21 21:28:56 +02:00
Miguel Ángel e2de547a28 feat(studio): auto-reveal source when selecting elements in Code tab
When the Code tab is active and a user clicks an element in the preview,
the code editor now auto-scrolls to the corresponding HTML source. This
removes the need for Alt+click — the existing click-to-source mechanism
fires automatically when the Code tab is already open.

- Add getTab() to LeftSidebarHandle for reading the active tab
- Add getSidebarTab getter to useDomEditSession
- Add effect that calls openSourceForSelection on selection change
  when Code tab is active
2026-05-21 15:25:51 -04:00
Miguel Ángel e0c3b283a0 test(producer): regenerate sub-comp-t0 baseline inside amd64 Docker
Previous baseline was generated on arm64 host, causing 87 failed
frames in CI (amd64). Regenerated with --platform linux/amd64 to
match CI's Chrome/FFmpeg pixel output.
2026-05-21 15:11:07 -04:00
Ular Kimsanov eb3c9d7e7f Merge pull request #1003 from heygen-com/feat/capture-pipeline-improvements-v2
feat(capture): pipeline improvements — contact sheets, design styles, snapshot
2026-05-21 11:28:51 -07:00
Miguel Ángel ee8dacab1e fix(lint): exclude gsap.fromTo() from gsap_from_opacity_noop rule
gsap.fromTo(target, fromVars, toVars) animates to toVars, not to
the current CSS value — so fromTo({opacity:0}, {opacity:1}) with
CSS opacity:0 is a legitimate 0→1 fade-in, not a noop. The rule
was false-positiving on these calls with error severity, which
would block the render pipeline.

Drop the fromTo branch from the trigger guard and add a test case
that proves fromTo does not fire.
2026-05-21 14:10:57 -04:00
ukimsanov 0253c2ccc8 fix(skill)!: reference pixel-point/animate-text — stop vendoring
Per James and Miguel's review feedback:
  James: "you can only reference the skill or recreate things"
  Miguel: "I'd just reference the skill without trying to copy
           everything"
  James: "we can't vendor their artifacts in our own repo"

The 48 vendored text-effects JSON files were direct copies from
pixel-point/animate-text (verified: typewriter.json matches the
upstream byte-for-byte at duration_ms: 240, stagger_ms: 46,
easing: steps(1, end)). That repo has no LICENSE file, so the
files default to "all rights reserved" — Apache 2.0 redistribution
in our repo is a compliance violation.

The earlier "rewrite from scratch" attempt produced JSON that
didn't render correctly (7 of 24 effects broke when I built a demo
HTML to validate them). Rather than keep iterating on a rewrite
that doesn't match the upstream's calibration, this commit drops
the vendored files entirely and updates skill prose to REFERENCE
the upstream skill instead.

### Changes

- Delete `skills/hyperframes/assets/text-effects/` (48 JSON files
  + the dual-directory structure, 8451 lines).
- Rewrite `skills/hyperframes/references/text-effects.md` as a
  reference page that:
  - Names pixel-point/animate-text as the source of truth
  - Explains why we don't ship the catalog (licensing gap)
  - Tells sub-agents to load `/animate-text` via Claude Code skill
    invocation or `npx skills add pixel-point/animate-text`
  - Lists the 24 effect IDs by category as vocabulary (so agents
    can name effects in STORYBOARD.md before loading the upstream)
  - Documents the fallback path: implement from name + GSAP
    knowledge if the upstream skill isn't available
- Update 5 cross-references to reframe the catalog as upstream-
  referenced instead of repo-bundled:
  - skills/hyperframes/references/techniques.md (TOC pointer)
  - skills/hyperframes/references/beat-direction.md (text-anim
    guidance bullet)
  - skills/website-to-hyperframes/references/capabilities.md
    (registry-overview entry)
  - skills/website-to-hyperframes/references/step-3-storyboard.md
    (storyboard template + Text Animations section format)
  - skills/website-to-hyperframes/references/beat-builder-guide.md
    (references table row)

### What sub-agents see

Before: read `text-effects.md` → see 24 named effects → read each
spec from in-repo `assets/text-effects/effects/<id>.json`.

After: read `text-effects.md` → see 24 named IDs and a load
instruction → invoke `/animate-text` (or `npx skills add
pixel-point/animate-text`) → read each spec from
`.agents/skills/animate-text/assets/effects/<id>.json` (the
upstream's own files, not vendored copies).

End-user UX cost: one extra `npx skills add` for projects that
want the deterministic catalog. Or accept the fallback where
sub-agents implement from effect name + GSAP knowledge — works
fine for simple effects, less ideal for the 3 layout-aware ones
(kinetic-center-build, short-slide-right, short-slide-down).

Net diff on #991: -8488 lines.
2026-05-21 11:09:31 -07:00
ukimsanov ae9bac69a0 chore(skill): audit cleanup — stale visual-vocabulary ref + 20→13 techniques count
Two follow-ups caught by a post-restructure audit pass:

- skills/hyperframes/references/transitions.md:46 had a parenthetical
  "(derived from visual-vocabulary.md)" pointing at a file deleted
  earlier in this stack. Drop the parenthetical; the surrounding
  sentence reads cleanly without it.
- skills/hyperframes/SKILL.md:476 still said "20 visual techniques"
  and listed 7 entries that the techniques.md trim removed (frosted
  glass, impact lines, device mockups, aurora gradients, floating
  particles, terminal UI, moodboard layouts). Updated to the actual
  13 primitive techniques + a pointer to registry/blocks/ for the
  pre-built UI templates that used to be conflated with techniques.
2026-05-21 11:09:30 -07:00
ukimsanov 40774cb3ec refactor(skill): trim techniques.md to actual techniques (13 from 20)
Removed 7 entries that are not techniques. They're either UI style
treatments, hand-rolled CSS templates, or named effects — different
kinds of artifacts that don't belong under the same "primitive
animation techniques" frame:

- 12. Frosted Glass Panels  → style treatment
- 15. Impact Line on Text Drop  → named effect
- 16. Device Mockups (Laptop + Phone)  → hand-rolled CSS template
- 17. Aurora Gradient Backgrounds  → style treatment
- 18. Floating Particles  → style treatment
- 19. Terminal UI with Typing  → hand-rolled CSS template
- 20. Moodboard / Editorial Layout  → hand-rolled layout

The 13 entries that remain (SVG drawing, Canvas 2D, CSS 3D, Per-Word
Kinetic Type, Lottie, Video Compositing, Char Typing, Variable Font,
MotionPath, Velocity-Matched Transitions, Audio-Reactive, Clip-Path
Reveal, WebGL Shader Art) are real primitives — animation building
blocks an agent composes into beats, not finished recipes to lift
verbatim.

Updated the header to say 13 and point at `registry/blocks/` for
pre-built UI templates instead of pretending they're techniques. ToC
table and section numbering both updated. Net: -361 / +6 lines.
2026-05-21 11:09:30 -07:00
ukimsanov e4a7229298 revert(skill): revert 4 hyperframes files + CLAUDE.md to main
Per review feedback, these 5 files should not change in this stack:

- visual-styles.md — keep main's existing version
- house-style.md — keep main's light/dark prescription
- references/typography.md — keep main's tone + Banned/Guardrails framing
- references/video-composition.md — keep main's density guidance
- CLAUDE.md — drop the local-CLI Capture/Snapshot section added in
  this branch; the local-CLI dev-instruction block for adding CLI
  commands stays (was already on main, unrelated to skill prose).

Net: removes ~545 lines of churn from PR #991's diff.
2026-05-21 11:09:30 -07:00
ukimsanov 425b077a17 fix(skill): audit-found bugs in hyperframes core examples
Three concrete bugs found while auditing PR #991:

1. html-in-canvas-patterns.md (#1 in catalog, 3D Rotation with Bloom):
   The code example used `new THREE.EffectComposer(renderer)` UMD-style
   namespace access while the ESM imports right below pull them in as
   bare named imports. Three.js r150+ removed the UMD `examples/js/`
   globals, so as written the example throws `TypeError:
   THREE.EffectComposer is not a constructor`. Switched to the bare
   names matching the imports. THREE.Vector2 stays as-is — Vector2 is
   on the THREE namespace.

2. techniques.md (#5, Lottie Animation): The CDN path
   `@lottiefiles/dotlottie-web/dist/dotlottie-player.js` returns 404.
   `@lottiefiles/dotlottie-web` is the JavaScript SDK, not a web
   component — its `main` is `dist/index.cjs`. The web-component
   package is `@lottiefiles/dotlottie-wc` and the custom element is
   `<dotlottie-wc>`, not `<dotlottie-player>`. Updated both.

3. techniques.md (5 occurrences across Lottie / lottie-web /
   Video / @font-face examples): asset paths used the `../capture/`
   pattern that PR #989's `invalid_capture_path` lint rule emits an
   error for. Replaced all with root-relative `capture/...`. PRs #989
   and #991 are no longer self-contradictory.
2026-05-21 11:09:30 -07:00
ukimsanov 0ba1df54ed feat(skill): hyperframes core — remove prescriptive tables, bundle text-effects
Rewrites the standalone `hyperframes` skill (the main authoring
skill used by every hyperframes user, not just the
website-to-hyperframes pipeline) to remove prescriptive lookup
tables that drove monoculture output, restore tone, and bundle
24 named text animation effects directly into the skill so
agents don't need a separate install.

This is a +9951/-567 change touching 61 files in `skills/hyperframes/`.
It deserves its own review separate from the capture pipeline and
the website-to-hyperframes pipeline because it affects every
hyperframes user — not just the website-to-video flow.

**Prescriptive tables removed / restructured**

External rater feedback across two rounds identified six lookup
tables agents were pasting wholesale as recipes:
- `visual-styles.md` YAML blocks — completely replaced. Old version
  had 8 styles with full YAML token blocks (colors / typography /
  motion / transition names). Agents copy-pasted. New version
  renames to actual design traditions (Swiss / Late-Modernist
  Editorial / Punk / Maximalist / Computational / Humanist /
  Vernacular / Cinematic) and replaces YAML with prose: "what it
  teaches / where it resonates / pitfalls when borrowing." No
  lookup table.
- `motion-principles.md` — complete rewrite. Old version opened
  every section with "You know these rules but violate them. Stop."
  / "You will try to use 14px. Don't." New version: "Common defaults
  that produce monoculture" framing. All load-bearing GSAP rules
  preserved verbatim (those are correct and critical).
- `beat-direction.md` rhythm table — removed. Replaced with
  questions that derive rhythm from brand + storyboard. Verb table
  regrouped by physical character (Impact / Directional / Reveals /
  Organic / Mechanical) without energy labels.
- `transitions.md` Energy → Transition table + Mood → Type table —
  removed named transitions, replaced with motion-quality
  descriptions (Soft/organic, Directional/purposeful,
  Percussive/instant). Mixing documented: CSS crossfade + shader
  in the same HyperShader composition (verified working).
- `dynamic-techniques.md` energy table — restructured with
  explanatory principles (highlight amplitude, exit style, cycle
  variation) before showing the table as calibration reference.
- `techniques.md` "When to Use What" table — deleted. Replaced
  with "choose techniques based on beat concept, not video genre."
- `typography.md` — "Guardrails / You know these rules but violate
  them" → "Defaults to watch for." Banned fonts gain a caveat:
  if the brand actually uses one of these fonts, use it.
- `video-composition.md` — fixed density contradiction
  ("8–10 visual elements" removed; sparse beats are intentional).

**Text-effects bundle (new)**

24 named text-animation effects shipped as paired specs:
- `assets/text-effects/effects/<id>.json` — GSAP-specific recipe
  agents can paste verbatim
- `assets/text-effects/specs/<id>.json` — portable motion contract
  (engine-agnostic, so the same effect can be re-implemented in any
  animation library)

Catalog at `references/text-effects.md`. Storyboards reference effects
by name (typewriter, kinetic-center-build, shimmer-sweep, …) instead
of saying "fades in," which produced inconsistent typography across
beats.

Effects organized by target:
- Per-character (7): soft-blur-in, per-character-rise, typewriter,
  bottom-up-letters, top-down-letters, stagger-from-{center,edges}
- Per-word (8): per-word-crossfade, spring-scale-in, shared-axis-y,
  blur-out-up, kinetic-center-build, short-slide-{right,down},
  depth-parallax-words
- Per-line (2): mask-reveal-up, line-by-line-slide
- Whole element (7): micro-scale-fade, shimmer-sweep, fade-through,
  shared-axis-{x,z}, scale-down-fade, focus-blur-resolve

Sources adapted from `pixel-point/animate-text`; copied into the
repo so users don't need a separate install.

**Misc cleanups**

- `house-style.md` — light/dark prescription removed; defer to brand.
- `prompt-expansion.md` — `design.md` → `DESIGN.md` casing fixed.
- `html-in-canvas-patterns.md` — Three.js 0.147.0 (legacy
  `examples/js/`) → 0.181.2 (`examples/jsm/` ESM imports);
  `Math.random()` in the shatter example → mulberry32 seeded PRNG
  so output is deterministic.

**.gitignore + CLAUDE.md**

- `.gitignore` catches per-brand video project directories agents
  leave at the repo root (`huly-*/`, `raycast-*/`, `*-demo-*/`,
  `test-runs/`, `test-outputs/`) plus the `videos/` folder
  conventions.
- `CLAUDE.md` documents the local CLI for `capture` + `snapshot`
  (since the published `npx hyperframes` doesn't yet include the
  capture pipeline improvements from this stack) and the local
  shader-transitions build copy convention.
2026-05-21 11:09:30 -07:00
ukimsanov 24aef5475c fix(skill): eval feedback — font src paths, WCAG pairings, flash-through-white regression
Five fixes from Ular's first-pass workflow run:

1. step-1-design.md Fonts section — sub-agents pointed @font-face for
   "ES Build Neutral" at the Inter .woff2 files because DESIGN.md
   only named families, never emitted exact src: paths. Now the
   Fonts section example shows per-family + per-weight file paths
   AND a copy-verbatim @font-face block sub-agents can paste, so
   there's no inference step. Adds an explicit narrative of the
   real failure mode and how to avoid it.

2. beat-builder-guide.md FONTS rule — was "brand fonts with
   capture/assets/fonts/ path need @font-face in <style>." Now:
   "copy the @font-face block VERBATIM from DESIGN.md. Do NOT guess
   which .woff2 file belongs to which family — capture filenames
   are content-hashed and there is no visible mapping. If DESIGN.md
   doesn't include exact src: paths per family, STOP and ask the
   main agent; never pair an arbitrary .woff2 with a family name
   from memory."

3. step-1-design.md Colors section — Sub-agents reproduced brand
   colors faithfully and hit WCAG AA failures on dark surfaces
   (#68686A on #18191B = 3.16:1). Now the Colors section example
   computes per-pairing contrast ratios with ✅/⚠/❌ markers,
   documents the dark-surface substitute color when the brand's own
   palette fails, and points at the /hyperframes-contrast skill for
   ratio computation. Sub-agents pick text colors by surface
   context, not by "this is the brand's secondary text color."

4. capabilities.md flash-through-white entry — the "ideal as
   invisible bridge at duration: 0.01" framing caused agents to
   scatter white flashes through every composition as transition
   bridges. The fix was documented in the branch's HANDOFF but
   never landed. Now: "Fade through white midpoint — a visible
   white flash between scenes. Use only when the brand specifically
   calls for a white-flash beat boundary; this is NOT a neutral
   'default' transition."

5. step-6-validate.md Warnings list — adds a paragraph on WCAG
   contrast false positives. The validator samples at fixed
   timestamps; elements at opacity:0 / mid-fade get measured as if
   fully visible, producing spurious failures. Tells the agent to
   verify visually before changing colors to clear a WCAG warning
   — bumping a color to fix a sampling artifact changes brand
   identity for no real benefit.
2026-05-21 11:08:52 -07:00
ukimsanov e5160b6022 chore(skill): brand-floor → brand-defaults; captured-asset-primary is normal
Second-batch audit cleanup after Ular's "logo isn't a requirement,
just a nice default" correction. Three related places still framed
captured-asset-primary beats as rare exceptions and the brand-floor
rules as hard MUSTs — both overstatements that contradict the rest
of the dial-back. Plus a TOC-only callout on capabilities.md.

- step-3:300 "for the RARE beat where a captured asset is the
  primary visual ... defaulted to the slideshow pattern this
  workflow exists to break" — rewritten. Captured-asset-primary
  beats are a normal valid choice. The narrow no-go is just pasting
  product-UI screenshots full-bleed.
- step-3:351 "Each one has a composed visual that carries it" —
  rewritten to "Each one has a primary visual that carries it
  (composed UI, captured asset, kinetic typography, WebGL, etc.)".
- step-3:353 "assets decorate concept-defined beats; they do not
  seed them" — kept "do not seed" (correct: don't write a beat
  because of a cool asset); dropped the "decorate" framing
  (overgeneralized — assets can be primary too).
- step-3 brand-inflection floor section: relabeled from "REQUIRED
  minimums" to "Brand defaults (nice-to-haves for most brand
  videos)". "MUST appear" softened to "for most brand videos,
  the logo lands in the opener and the closer" with explicit
  "skippable when the storyboard's concept calls for it" language.
- step-3:379 "The bar:" bullet: "brand-floor minimums ... the
  minimum, not the ceiling" → "brand-defaults section covers most
  brand videos but isn't a hard requirement."
- step-5:413 "Brand-floor check" section in the per-beat read
  protocol: relabeled "Brand-defaults check", reframed each item
  as a default not a fail-condition; agent checks against the
  storyboard's intent rather than enforcing a hard rule.
- capabilities.md top: added a "Scan the TOC; do NOT read this file
  linearly" callout — it's a 700+ line inventory; agents should
  jump to the section a beat needs, not read top-to-bottom.
2026-05-21 11:08:52 -07:00
ukimsanov d31ef3f15b chore(skill): audit cleanup — captured assets are first-class primaries
Three follow-ups caught by a post-restructure audit pass. All three
were places where the earlier "compose primary, asset is accent"
framing survived after the step-3 and step-5 paragraphs already got
the primitive-toolkit rewrite. Cleans up the contradiction so the
skill speaks with one voice: captured assets can be primary content;
the narrow no-go is just pasting product-UI screenshots.

- step-2-brief.md:80 — the "flip it" example said agents should
  reframe "the hero illustration centers the opener" into "kinetic
  typography ... hero illustration as ambient depth." That reverses
  the dial-back: captured illustrations CAN center an opener. The
  flip-it rule now applies narrowly to product-UI screenshots; for
  captured logos/illustrations/hero art, no flip is needed.
- step-2-brief.md:149 — option-template guidance said "primary
  content is 'the screenshot of X'" was forbidden. Narrowed to
  "primary content is a pasted product-UI screenshot." Other
  captured assets (SVG logos, illustrations, hero art) are valid
  primaries when the concept calls for them.
- step-3-storyboard.md:314 — Common-accent-uses bullet implied
  accents are always layered on "composed UI." Reframed: list
  accent uses for when the primary is something else; when the
  captured asset IS the primary (logo opener, hero parallax),
  document it under Composition, not Accents.
2026-05-21 11:08:52 -07:00
ukimsanov eed6dfb2f2 refactor(skill): primitive-toolkit framing across step-1, step-3, step-5
Cleans up two related overcorrections that crept across the skill
prose: (a) "compose UIs from divs/SVG/CSS" repeated 6+ times in
step-1, anchoring agents to website-shaped beats; (b) "every beat's
primary visual stays composed from divs / SVG / CSS / GSAP" and
"captured assets are accents — they decorate, they don't carry"
overstatements in step-3 and step-5 that contradicted the dial-back
done earlier in this stack.

The real framing: a beat composes from whatever primitives the scene
needs — HTML/CSS, SVG, captured assets, WebGL, Canvas, Three.js,
kinetic typography, Lottie — alone or in combination. They're inputs
to one output (the video frame). No rule maps intent → primitive.
The narrow no-go is one rule: never paste a product-UI screenshot as
load-bearing content (the slideshow pattern).

step-1-design.md (8 edits):
- L5 intro: drop "composed from divs/SVG/CSS at build time" detail.
- L7 length: drop "compose UIs from scratch (divs/SVG/CSS)" framing;
  merge L290's "over-investing in prose" caveat in.
- L97: "composing UIs from divs in Step 5" → "building beats".
- L161: "compose the X UI" → "a beat featuring the X".
- L290: duplicate length bullet — deleted.
- L293: "sub-agents compose UIs at build time from divs/SVG/CSS..."
  → "No separate Components section — Quick Reference is where
  components live."

step-3-storyboard.md (3 edits):
- L3 (intro): "alongside composed UIs" → "alongside composed beats".
- L276 ("Compose the load-bearing visuals yourself") paragraph
  replaced with the primitive-toolkit framing — toolkit is open, the
  only no-go is product-UI screenshots as load-bearing content.
- L381–383 ("The bar:") three bullets collapsed to one bullet:
  primary visuals use whatever combination the scene needs; accents
  are optional; brand-floor minimums are the minimum.

step-5-build.md (2 edits):
- L104 stacked-beats intro: "composed from divs, SVG, canvas, and
  CSS. Never a full-bleed screenshot." → "composes from whatever
  primitives the storyboard called for ... Narrow no-go: never a
  full-bleed product-UI screenshot as load-bearing content."
- L147: "Build the UI element from divs and CSS" → "Build the
  element from divs and CSS" — drops the UI bias since this rule
  applies only when the asset IS a product-UI screenshot.

Net result: "compose from divs/SVG/CSS" mentions drop from 10+ to 0
as a generalized framing; the term survives only in concrete
examples (e.g. "cards-as-divs" when the beat is specifically a
kanban demo) where divs/CSS IS the right answer.
2026-05-21 11:08:52 -07:00
ukimsanov 7f6bceb473 refactor(skill): step-0 owns capture, not analysis
Step 0 had bloated to 91 lines that did the work of Steps 1–3:
viewing contact sheets cell-by-cell, reading 8 data files, listing
promising assets, inferring product purpose / audience / value prop
/ brand voice. That meant the agent did all the heavy lifting
upfront, produced summaries that went stale before they were used,
and the actual "run the capture" instruction was buried.

Step 0 now owns only what Step 0 is: run the capture command,
sanity-check it succeeded, hand off. 91 → 55 lines.

Moved (composed into destination files, verified each was the right
home before adding):

- Read tokens.json + design-styles.json → step-1-design.md replaces
  the passive "you read these in Step 0" line with an active
  "Read these now — primary data source for Sections 3–6."
- Contact-sheet "every cell, name 5 assets per page" anti-glance
  prose → step-3-storyboard.md asset-discovery bullet (which already
  covered contact-sheet viewing generally, now strengthened with
  the anti-glance rule).
- Strategic site summary (product / audience / voice / value prop)
  → step-2-brief.md absorbed this; the brief itself IS the summary.
  Replaced "After presenting the site summary (from Step 0)" with
  step-2 grounding itself by reading DESIGN.md + asset-descriptions
  + visible-text directly.

Step 0's new structure:
- Run the capture (CLI command + project-dir convention) — unchanged
- Confirm it succeeded (1-line summary, error-out on bad capture)
- Reference table mapping each capture/ file to the step that
  first reads it (explicit "DO NOT read these here")
- Gate: capture exits 0 + counts non-zero
2026-05-21 11:08:52 -07:00
ukimsanov 7093ee900b refactor(skill): slim SKILL.md to step-pointer index, push to step files
SKILL.md grew to 192 lines from a 124-line baseline. Most of the
bloat was content duplicated in the step reference files it points
to. Removed 6 sections that duplicated step content, composed 2
small additions into the step files where they actually belonged.

Removed from SKILL.md (already covered elsewhere):

- "Take your time" / "Quality matters more than speed" paragraph
  — operational philosophy already implicit in step-6-validate's
  cell-by-cell review prose.
- "Creative Tension Principle" section — step-3-storyboard.md:21
  already has the exact "What makes this video different from a
  generic [video type] for any [industry] brand?" single-sentence
  test. Duplicate removed; storyboard is the right home.
- "Step -1: What we're actually making" (30 lines: anti-patterns,
  video grammar, shot framing, camera moves) — duplicates step-3-
  storyboard.md:197+ (shot types), :229–232 (anti-patterns), and
  beat-builder-guide.md:126+ (shot framing).
- "Sub-agent mode" + "No sub-agents" preamble — step-5-build.md:286
  –292 already handles both parallel and serial runtimes.
- "Image-viewing capability" warning — operationally implicit in
  step-0 ("View the contact sheets") and step-6 ("View snapshots/
  contact-sheet.jpg cell-by-cell").
- "User Interaction Points" table — redundant with the inline 💬
  markers on Steps 3 and 4.

Composed into step files (content that wasn't there yet):

- step-1-design.md "Target length" paragraph: added the fast-pacing
  / billboard-per-beat exception (50-line DESIGN.md is enough when
  beats are single hero elements on full-bleed backgrounds, not
  full UIs).
- step-2-brief.md "Surprise me" section: added the global-propagation
  rule — when the user signals autonomous mode at Step 2, every 💬
  gate downstream (Step 3 storyboard approval, Step 4 TTS choice) is
  also skipped.

Step 5 SKILL.md gate paragraph trimmed from a 6-clause description
of the per-beat read to one line that points at step-5-build.md
for the full checklist.

Updated the techniques.md reference counts from "20" to "13" in
SKILL.md, beat-builder-guide.md, and step-3-storyboard.md to match
the techniques.md trim in the upstream branch.

Net: SKILL.md 192 → 131 lines.
2026-05-21 11:08:51 -07:00
ukimsanov 051c9c9de4 chore(skill): drop visual-vocabulary.md + use published npx hyperframes
- Delete `references/visual-vocabulary.md` and scrub the four call
  sites that referenced it. The 6-axis lookup framing it introduced
  contradicted the rest of the skill's "design from the brand, not
  from a table" stance.
- Replace all `npx tsx packages/cli/src/cli.ts <cmd>` invocations
  with `npx hyperframes <cmd>` in step-0-capture.md, step-5-build.md,
  step-6-validate.md, and beat-builder-guide.md. The capture- and
  snapshot-pipeline improvements that previously required the local
  CLI now ship in the published CLI via the stack's PRs #987 and
  #988, so once the stack lands the published CLI is the right
  invocation for the skill prose.
- Remove the now-contradictory "ALWAYS use the local CLI — never
  npx hyperframes" warnings in step-0-capture.md and step-6-validate.md.
2026-05-21 11:08:51 -07:00
ukimsanov a1ffb6e7bf feat(skill): website-to-hyperframes — concept-first authoring + per-beat read protocol
Rewrite of the website-to-hyperframes skill that came out of 11
evaluation rounds. The honest read of those evals: prose-only
guidance had hit its ceiling — sub-agents kept reporting "0 errors,
looks good" without doing the work, producing slideshow-quality
videos with mismatched brand colors, missing logos, and beats that
didn't serve the storyboard. This restructure addresses the
failure modes that real videos showed, not theoretical ones.

**Step structure (replaces 7-step layout with concept-first 6-step)**

Old: capture → design → script → storyboard → vo → build → validate
New: capture → design → brief → storyboard → vo → build → validate

The brief step (Step 2) is new: a conversation-shaped step that
aligns message + audience + arc before any beat-writing happens.
Concept-first throughout — message → arc → beats that serve the arc
→ which assets and techniques bring each beat to life.

**Step 0 (capture)**

- "View the contact sheets — carefully, every cell, not a glance"
  closes the failure mode where agents reported "viewed the contact
  sheet" after one scroll and later wrote beats referencing assets
  that didn't exist or missed the brand logo.
- Names the right artifacts to read in order (tokens.json →
  design-styles.json → asset-descriptions.md → fonts-manifest.json),
  with read-on-demand guidance for the rest.

**Step 1 (design)**

- DESIGN.md authoring guide. Restored component CSS sections
  (Component Stylings, Spacing & Layout, Depth & Elevation) that
  earlier batches over-collapsed.

**Step 2 (brief)**

- Strategy/messaging step. Clear instruction for "Surprise me" /
  minimal direction: state the minimum context (where the video
  runs, who it's for) and proceed bold.

**Step 3 (storyboard + script)**

- Concept gate at the top — answer "what makes this video distinct"
  before writing beat 1.
- Brand-floor MUST rules (logo in opener + closer; signature visual
  somewhere in the video).
- Captured assets (SVG logos, illustrations, hero art, gradients)
  are first-class beat content alongside composed UIs — many of
  them carry beats outright. The constraint is only that you start
  from the message, not the asset inventory.

**Step 4 (vo)**

- TTS ranking: HeyGen first (auto word timestamps), ElevenLabs
  second, Kokoro free. Audio timing reconciliation gate: if actual
  audio duration ≠ storyboard planned ±15%, rescale beats or trim
  script before Step 5.

**Step 5 (build) + beat-builder-guide.md**

- Sub-agent template now pastes brand values inline rather than
  telling the sub-agent to re-read DESIGN.md. Targeted file reads
  with specific sections + line ranges.
- "Patterns that ARE shots" affirmative list (captured logo
  draw-on, hero illustration push-in, captured screenshot with
  parallax layers, kinetic typography over captured asset).
- Webpage-mimicry patterns (full CSS browser chrome, parked-camera
  composition, ±2px breathing motion) marked ⚠ rather than ❌ —
  fine when the storyboard genuinely calls for them as the subject.
- Required cinematography per beat: shot type, camera move, depth
  strategy, purpose.

**Step 6 (validate) — per-beat read protocol**

This replaces the previous "spawn verify-beats CLI" gate. A grep
of composition HTML can catch structural lies (missing hex codes,
wrong asset paths) but it can't catch boring beats, off-screen
logos, GSAP timelines that only cover the first 2 seconds, or
camera moves that don't match the storyboard. Those failures only
surface when somebody opens the file and reads it.

Per-beat verdict template names the brand hex codes used, captured
asset paths referenced, headline `font-size`, GSAP timeline
coverage, and storyboard alignment. Critic sub-agent scores a
"Captured asset utilization" dimension specifically so the eval
captures whether captured SVGs/illustrations carried beats or got
recreated as divs.

**Asset bundle**

- 20 Pixabay-licensed SFX files with `CREDITS.md` documenting
  provenance. SFX assignment moved to Step 3 (creative decision)
  so Step 5 implements rather than improvises.
- Capabilities reference + html-in-canvas-patterns updated:
  Three.js 0.181.2 + ESM jsm imports, mulberry32 seeded PRNG for
  deterministic shatter, 24-effect text-animation catalog
  referenced (catalog itself lands in the hyperframes-skill PR).
- Visual vocabulary rewritten: replaces user-word lookup tables
  with brand-first derivation across 6 axes; user words land as
  modifiers, not replacements.
2026-05-21 11:08:51 -07:00
ukimsanov 2c9544f6d4 feat(lint): font loading + invalid capture path composition rules
Two new composition lint rules catching failure modes that recurred
across the 11-round website-to-video eval. Both ship with vitest
coverage; total lint suite goes from 148 to 151 tests.

**`fonts.ts` (new) — two warnings**

- `google_fonts_import`: composition loads fonts from
  `fonts.googleapis.com` via `<link>` or `@import url(...)`. External
  font requests fail in sandboxed/offline renders and add latency.
  Fix hint points to root-relative `capture/assets/fonts/...woff2`
  with a local `@font-face` declaration.
- `font_family_without_font_face`: CSS uses a font-family that
  isn't declared with `@font-face` and isn't in the auto-bundled
  font set (Inter, JetBrains Mono, etc.). Text would silently fall
  back to system-ui — the visual fidelity loss the eval kept hitting.
  Fix hint points to the captured woff2 files.

**`composition.ts` invalid_capture_path (new) — one error**

Sub-compositions live in `compositions/` but get served with the
project root as their base URL. `<img src="../capture/...">` works
on disk but 404s in Studio and renders. Errors with a fix hint
saying replace `../capture/` with root-relative `capture/`.
Three vitest cases: `<img>` triggers, multi-occurrence url()s are
counted, root-relative paths stay clean. Registry source files and
installed blocks are exempted.

**Wiring**

`hyperframeLinter.ts` runs the new fonts rules alongside the existing
rule set; the composition rule was added inline so it picks up
automatically.
2026-05-21 11:08:38 -07:00
Miguel ÁngelandClaude Sonnet 4.6 9e51f5cfaa feat(lint): add gsap_from_opacity_noop rule — catch invisible elements
Detects when an element has CSS `opacity: 0` (inline or style block) AND
is targeted by gsap.from({opacity: 0}). Since from() animates FROM the
specified value TO the CSS value, this produces a 0→0 animation where
the element never becomes visible.

Root cause of all-black renders from the product-launch-video skill:
every text element had opacity:0 in CSS + gsap.from({opacity:0}),
making all text permanently invisible despite the timeline "working."

Fires as error (not warning) to block the render pipeline. Includes
actionable fix hint. 4 test cases: inline style, style block, clean
code (no false positive), and gsap.to() exit (no false positive).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-21 17:58:44 +00:00
ukimsanov 65c5209be8 chore(cli): bump sharp ^0.34.0 → ^0.34.5
Required by the contact-sheet pagination code added on this PR
(uses Sharp APIs that landed in 0.34.5). Originally bumped on
#987 by mistake — moved here per Copilot review.
2026-05-21 10:57:37 -07:00
ukimsanov 62b55171e9 feat(capture): pipeline improvements — contact sheets, design styles, snapshot
Capture pipeline work that came out of the 11-round website-to-video
eval branch. The wins that actually moved quality were the artifacts
agents read (contact sheets, design-styles) and the snapshot tool
visual-verification fixes; the rest are smaller follow-ons.

**Contact sheets (`contactSheet.ts`, new)**
- Replaces the embedded one-image-per-asset listing with paginated
  labeled grids (3-col screenshots / 4-col raster / 5-col SVG). Each
  page contains 9–15 cells with filename labels baked in via SVG
  text overlay (`escapeXml` covers `&<>"'`).
- `fit: "contain"` keeps every asset visible at its real aspect
  ratio; the old `fit: "cover"` cropped to the first image's box.
- Returns `string[]` (page paths) — single-page captures get one
  file, multi-page produce `contact-sheet-1.jpg`, `contact-sheet-2.jpg`,
  etc.
- `createSvgContactSheet` scans both `assets/svgs/` (inline-extracted
  SVGs) and `assets/` root (external SVGs from `<img src="*.svg">`)
  and de-dupes by filename. Sites with all-external SVGs (huly.io)
  now get coverage they previously didn't.

**Design styles extractor (`designStyleExtractor.ts`, new)**
- Walks the live DOM and reads computed styles to produce
  `extracted/design-styles.json`: typography hierarchy (every text
  role with exact font-size / weight / line-height / letter-spacing),
  button variants (background / padding / radius / shadow), card /
  container / nav styles, spacing scale with base unit, border-radius
  scale, box-shadow values with usage counts.
- Primary data source for DESIGN.md authoring at Step 1. Replaces
  the prior "guess from screenshots" workflow.

**Snapshot tool (`snapshot.ts`)**
- HyperShader pre-rendering used to swallow the entire snapshot
  capture window (every frame after the first showed the loading
  overlay or final-opacity-zero exit fades). Wait signal is now
  `window.__hf.shaderTransitions[].ready` (set after both warm and
  cold cache paths complete); local-time seek for sub-comps means
  exit fades read at their own t=0..duration, not global time.
- Gemini vision per-frame analysis runs by default (`descriptions.md`
  next to the contact sheet). `--describe "custom Q"` overrides the
  prompt; `--describe false` opts out.
- 3-column contact sheet generation for snapshot frames so reviewers
  see all beats at a glance.

**Screenshot capture (`screenshotCapture.ts`)**
- Replaces `querySelectorAll('*') + getComputedStyle` overlay scan
  with a TreeWalker that early-exits on cheap rect checks before
  reaching the expensive style read. Caps at 5000 elements per page.
- Cookie/consent dismissal selectors are scoped under cookie /
  consent / gdpr ancestors so we don't click "Accept invitation" or
  similar unrelated buttons.

**Agent prompt (`agentPromptGenerator.ts`)**
- Auto-discovers contact-sheet page count (matches base name plus
  paginated `-NNN` variants only, with regex escaping on the base
  name and numeric sort for 10+ pages).
- `inferColorRole`: classifies extracted hex colors as bg-dark /
  bg-light / accent / surface / neutral via luminance + saturation,
  so the agent prompt shows `#533AFD (accent)` instead of bare hex.
- `design-styles.json` row is gated on `existsSync` — the upstream
  write is wrapped in try/catch and may skip on failure, so the
  prompt only points to files actually on disk.

**Other CLI ergonomics**
- `cli.ts`: auto-load `.env` from CWD on startup so subcommands like
  `snapshot` don't need explicit `export GEMINI_API_KEY=…`. Handles
  `export FOO=bar`, quoted values, inline `# comments`.
- `commands/transcribe.ts`: default output dir is the input file's
  directory, not CWD. Stops the "wrote transcript.json somewhere
  unexpected" footgun.
- `assetDownloader.ts`: improved asset naming uses catalog context;
  de-duplicates inline SVG filenames.
- `contentExtractor.ts`: captions SVGs via Gemini (code-as-text) and
  integrates them into asset descriptions.
- `tokenExtractor.ts` + `types.ts`: SVG bounding box dimensions and
  new DesignStyles schema added.
2026-05-21 10:57:37 -07:00
Miguel Ángel afa6530a10 refactor(studio): remove dead crossfade scaffolding from NLEPreview
Follow-up to the playhead-preservation fix: clean up the now-unreachable
crossfade infrastructure that was only triggered by refreshKey changes.

- Remove retiringKey state, retiringTimerRef, handleNewPlayerLoad
- Remove the retiring Player render block and conditional onLoad/style
- Drop refreshKey from getPreviewPlayerKey signature and NLEPreviewProps
- Stop passing refreshKey from NLELayout to NLEPreview
- Update NLELayout comment to reflect current iframe.src reload model
- Simplify getPreviewPlayerKey test
2026-05-21 13:21:10 -04:00
Miguel ÁngelandClaude Sonnet 4.6 dc864f3e6c test(producer): regenerate sub-comp-t0 baseline + improve visual contrast
The text-rendering:geometricPrecision rule (b7bd9565) shifted glyph advances
~1% in headless Chrome. Baselines for png-sequence, heygen-promo-preview-assets,
and sub-composition-video were already regenerated — sub-comp-t0 was missed.

Also improves the fixture's visual contrast:
- Background: #07110d (near-black) → #0f172a (slate-900)
- Hook scene: background #1e293b, text #ef4444/#ffffff
- Later scene: background #334155, text #ffffff
- Absolute positioning for text elements (compiler inlines sub-comp
  content at intrinsic width, collapsing the flex container)

Baseline regenerated inside Dockerfile.test per CLAUDE.md. Test passes:
0 failed frames, 100/100 checkpoints green.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-21 17:19:02 +00:00
Ular Kimsanov 12808fd38f Merge pull request #987 from heygen-com/feat/capture-font-extractor
feat(capture): identify hashed fonts via OpenType name table
2026-05-21 10:09:25 -07:00
Miguel Ángel 1e9a175778 fix(studio): preserve playhead position on composition refresh
Stop NLEPreview from including refreshKey in the Player's React key.
Previously, a refreshKey change caused a full Player teardown + remount,
which destroyed the playback adapter before refreshPlayer() could save
the seek position — so the playhead always reset to 0:00.

Now refreshKey changes only trigger refreshPlayer()'s lightweight
iframe.src reload path, which correctly captures the current time via
saveSeekPosition() before reloading the iframe content.

Closes #996
2026-05-21 12:45:30 -04:00
Miguel Ángel 90a4e4b1c5 chore: bump version to 0.6.31 v0.6.31 2026-05-21 12:22:12 -04:00
Miguel Ángel 25d01db973 Merge pull request #999 from heygen-com/worktree-feat+studio-crash-stack-traces
feat(studio): add stack traces to error telemetry
2026-05-21 18:20:53 +02:00
Miguel Ángel 6a868b3787 feat(studio): add stack traces to all error telemetry events
Send `stack_trace` (up to 4KB) on crash, unhandled_error, and
unhandled_promise_rejection events so PostHog captures the full JS
call stack for debugging. Also bump `component_stack` from 500→2000
chars, and add `error_name` to promise rejections.
2026-05-21 12:18:55 -04:00
Miguel Ángel 6b541b7cf4 Merge pull request #997 from heygen-com/feat/studio-fullscreen-preview
feat(studio): fullscreen preview mode (F key)
2026-05-21 18:17:30 +02:00
Miguel Ángel 9e7eb10edd feat(studio): fullscreen preview mode (F key)
Add distraction-free fullscreen mode using the HTML5 Fullscreen API.
Press F to enter fullscreen (Esc to exit). When active, the composition
fills the screen — timeline, sidebars, and editing overlays are hidden
while all playback shortcuts (Space, J/K/L, arrows, etc.) remain
functional. A fullscreen toggle button is also added to player controls.

Closes #995
2026-05-21 11:11:28 -04:00
Miguel Ángel 114b83bbf6 chore: bump version to 0.6.30 v0.6.30 2026-05-21 00:05:27 -04:00
Miguel Ángel 099e1257ee Merge pull request #994 from heygen-com/worktree-feat-timeline-ui
feat(studio): timeline UI overhaul — flat clips, thumbnails, visual cleanup
2026-05-21 06:03:53 +02:00
Miguel Ángel 8c3dfb8d40 fix: format studio.css keyframes 2026-05-21 00:00:22 -04:00
Miguel Ángel 36898f7681 fix(studio): address timeline PR review — drop dead code, add fadeIn keyframes, compSrc test 2026-05-20 23:54:19 -04:00
Miguel Ángel ef2ff298b6 feat(studio): timeline UI overhaul — flat clips, unified color, working thumbnails
Visual redesign of the timeline:
- Flat solid clip backgrounds, no gradients or multi-layer shadows
- Unified neutral color palette — all clips use the same base color
- Clean 6px border-radius instead of organic asymmetric radii
- Single-line labels, no redundant tag badge or time range
- 3px teal accent stripe on the left edge of every clip
- Simplified trim handles (2px accent bars)

Thumbnail fixes:
- Fixed broken thumbnail URLs — compositionSrc was an absolute URL
  that got nested inside the preview/comp path. Now normalized to
  relative path before constructing the thumbnail URL
- Thumbnail background changed from #000 to #1c2028 so transparent
  overlay compositions render visible content against a matching
  dark background
- mix-blend-mode: lighten on thumbnail layer — dark backgrounds blend
  away, bright content shows through
- Removed double-label in CompositionThumbnail (was showing both a
  badge at top and text at bottom)
2026-05-20 23:54:19 -04:00
Miguel Ángel be9b61a8c9 Merge pull request #986 from heygen-com/fix/studio-edit-persistence-and-render-css
fix(studio): server-side DOM patching, render CSS scoping, and resilience
2026-05-21 05:53:32 +02:00