mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
9abd03e39ebb9669c57a04495386e10fb5ffd2b2
225
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
9abd03e39e |
fix(skill): assemble-index duration cross-check matches actual w2h root id
Real-AI-test log entry #9 from the heygen-showcase build: "assemble-index.mjs emitted 5 anomalies: could not read root data-duration from compositions/beat-N.html — skipped duration cross-check (one per beat). Non-fatal — the assembler reads id='root' but the beat skeleton uses id='beat-N-slug', so the cross-check was skipped for all 5 beats." The duration cross-check exists to catch a real failure class — a worker writing a `data-duration` on its root <div> that disagrees with the orchestrator's `group_spec.estimatedDuration_s`. When they disagree, downstream timing (voice / SFX / captions / shader seams) silently misaligns. The check is supposed to hard-fail with a clear mismatch message; what was actually happening was the check silently skipping for every beat across every w2h project ever built. Root cause: rootDataDuration() at line 135 matched the literal pattern `id="root"`: const tagM = html.match(/<div\b[^>]*\bid=["']root["'][^>]*>/i); But w2h beats DON'T use `id="root"`. The canonical pattern across the starter template in beat-builder-guide.md, the file-copy _beat-skeleton.html boilerplate, and every real project on disk (heygen-com, huly, heygen-showcase — verified) is: <div id="beat-N-<slug>" data-composition-id="beat-N-<slug>" ...> So the regex never matched, rootDataDuration() returned null unconditionally, and the assembler dropped to the "could not read" anomaly branch every time. The check has effectively never run since the w2h skill was created. Fix: take the scene id (sid) from the loop's playOrder iteration — which the assembler already has at the call site — and match against EITHER `id="<sid>"` OR `data-composition-id="<sid>"` (they're equal by contract; matching by either identifies the root unambiguously). rootDataDuration(html, sid) // ← new sid param pattern: /<div\b[^>]*\b(?:id|data-composition-id)=["']<sid>["'][^>]*>/is The sid is regex-escaped first so beat slugs with regex-meta chars don't break the pattern (defensive; current slug shape is just [a-z0-9-] so no current beat hits it, but cheap insurance). Anomaly message also updated to name the expected matchers so future "could not read" hits explain what they were looking for: "could not read root data-duration from compositions/beat-N.html (no <div id="beat-N"...> or data-composition-id="beat-N" with data-duration) — skipped duration cross-check" Smoke-tested against three real projects: heygen-showcase/beat-1-orb.html → 3.3 (matches HTML) heygen-com/beat-1-hook.html → 3.46 (matches HTML) huly/beat-1-beam.html → 4.7 (matches HTML) All three correctly return the worker's data-duration, so the cross- check now actually fires on real beats and will catch any worker that writes a data-duration disagreeing with group_spec. No behavior change for projects where the worker's data-duration already matches group_spec (which is every working project today). The fix promotes the SILENT-skip case to ACTIVE-check case, surfacing mismatches as hard fails the way the assembler originally intended. Cost in the heygen-showcase run: 5 anomaly lines in the assembler output (one per beat). Non-fatal but noise; user noted it in the factual log. With this fix, those anomalies go away on next assemble. |
||
|
|
83e570c042 |
fix(skill): SFX volume = natural across all docs (background-music + capabilities)
Audit found two docs still carrying the OLD 0.2-0.35 SFX prescription after the natural-level stance landed in commit |
||
|
|
d5ff079ef0 |
fix(skill): sub-comp background: rule lives in beat-builder + starter template
Audit found the sub-comp root `background:` doesn't paint rule was documented in step-5-build.md (landmine #10, commit |
||
|
|
efd3d52dc1 |
fix(skill): unify SVG-naming docs with the actual capture emission
Audit found four docs still claimed the capture pipeline emits filenames in the shape <role>-<word>-<hash>.svg (e.g. partner-logo-amazon-2TeU5qiM.svg, header-logo-airbnb-EfGh5678.svg, stripe-logo.svg). That naming was an EARLIER design that was abandoned in commit |
||
|
|
c574be9f87 |
fix(skill): surface capture-video to orchestrator (step-3 + step-5 + SKILL.md)
Original commit ( |
||
|
|
bf8aef029c |
fix(skill): "alive, not active" rule — kill the opacity-breath failure
Real-AI-test artifact (huly opener): agent entered the app-name labels
("Linear, Jira, Slack, Notion, Docs") staggered, then held them for
~2 seconds while the beam built. To "keep them alive" during the hold,
the agent scheduled `tl.to(labels, { opacity: 1 }, "+=2")` — an
opacity-only breath. At 1920×1080 a 15% opacity oscillation is
invisible; the labels read as frozen for the first ~2s of the video.
Agent's own retro on the failure: "That opacity breath is invisible at
video scale — it's exactly the 'hold with breathing' micro-animation
the playbook tells you not to rely on. So functionally the labels are
frozen for ~2 seconds. It fights the hook."
User's instruction on encoding this as a rule (verbatim): "yes maybe
something like that, just so that AI wouldn't take it as oh damn it
gotta move and do something MOVEE, but just meaning it shouldn't
stay still..."
Encoded the rule in two places with calibrated language — explicitly
NOT "everything must bounce" but "presence requires life":
1. skills/website-to-hyperframes/references/step-3-storyboard.md —
new "Alive, not active" section in the opener-design block (right
after the hook patterns, before the CTA section). Names the
failure mode literally (opacity-only breath → reads as paused
slide), then lists the four valid continuous-motion patterns
(drift, camera dolly, wobble, parallax) with magnitudes calibrated
to be felt-not-watched. Reinforces "one pattern per element, don't
stack" so the orchestrator doesn't over-spec. Also notes the
carve-out: deliberate stillness as the CONCEPT (the Negative space
hook) stays valid — the difference is whether the stillness is
doing work.
Also touched the CTA paragraph to extend the rule there — the
"logo held still after entry" failure is the same failure mode in
the closing beat.
2. skills/website-to-hyperframes/references/beat-builder-guide.md —
- Extended landmine #6 (Hold with breathing) to explicitly call
out the opacity-breath variant as the most common version of
the failure, with the literal `opacity: 0.85 → 1.0` tween shape
so workers grep-match it in their own code.
- New landmine #8 "Alive, not active — no frozen readable text."
Names the rule, lists the four patterns, says "one per element,
don't stack" three different ways because the over-correction
("MOVEE!") is the second-order failure to head off. Closes with
a self-check: for every on-screen-for-more-than-1s element, can
you point at the GSAP tween carrying it through its lifetime?
If no, add one of the four.
Tone calibration:
- Explicit "fix is NOT make it move more"
- "Goal: the frame feels alive; the viewer can't point at 'the
motion' if asked" — defines the upper bound (subtlety)
- Magnitudes are floors (4-8px, 1.0→1.04+, ±1.5-3°), not pushes
- Negative space stillness as concept is preserved — the rule names
unintentional frozen-during-hold as the failure, not all stillness
No code change. The rule is doc-only because the perception gate
(check-rendered-perception.mjs) can't detect "this is visibly frozen
at video scale" — that's a quality judgment, not a binary failure.
Encoded as a sub-agent rule so workers honor it at write time, and
as a storyboard rule so orchestrators name the motion pattern per
element when they spec the beat.
Followups (separate):
- huly creative critique (opener stillness) — addressed by this rule.
- heygen creative critique (CSS cube instead of the real Orb mp4) —
addressed by commits
|
||
|
|
570dedbde2 |
feat(cli): add capture-video for on-demand video fetch from manifest
The capture pipeline writes capture/extracted/video-manifest.json
listing every <video> element on the source page (URL, dimensions,
heading, caption, preview PNG) but deliberately doesn't download the
mp4s — sites with 15+ feature videos would balloon capture size by
hundreds of MB.
User direction on this tradeoff: keep the capture lean, let the AI
agent decide per-beat whether the actual mp4 is worth fetching, and
provide a single CLI command to fetch one when the answer is yes.
That preserves the determinism (the manifest is the contract) and
the choice (agent picks what's relevant).
The motivating case is heygen.com's "Orb" — a 3D-rendered hero
animation that's at index 0 of the heygen manifest (768×768, heading
"Turn your ideas into videos in minutes"). On the last real-AI-test
run, the agent KNEW about it ("the genuine article was in the capture")
but composed a CSS-3D cube approximation instead because there was no
one-step way to fetch the actual mp4. This command closes that gap.
New command surface:
hyperframes capture-video <project-dir> --list
List manifest entries with index, dimensions, heading, URL.
hyperframes capture-video <project-dir> --index 0
Download the manifest entry at the given index.
hyperframes capture-video <project-dir> --url <URL>
Download a specific entry by exact URL match.
Behavior:
- Reads <project-dir>/capture/extracted/video-manifest.json.
- Resolves the target entry by --index or --url (clear error message
on out-of-range / missing).
- Downloads to <project-dir>/capture/assets/videos/<filename> — same
layout as the rest of the captured-assets tree, so compositions
reference videos with the same `capture/assets/...` path pattern
they already use for SVGs and rasters.
- Decodes URL-encoded characters and sanitizes the filename so
manifest entries like `Frame-2147227325%20(1).mp4` land as
`Frame-2147227325_1_.mp4` on disk.
- Idempotent: if the file already exists, warns and skips (delete +
re-run to refetch).
- On success, prints a ready-to-paste <video> embed snippet with
data-start / data-duration / data-track-index. Aspect-aware: square
videos (e.g. the Orb) get a 5s default duration suggestion vs 4s
for landscape feature videos.
Files changed:
- packages/cli/src/commands/capture-video.ts — new command (~170 LOC).
- packages/cli/src/cli.ts — registered `capture-video` subcommand.
- packages/cli/src/help.ts — added to the "Getting Started" group so
it appears in `hyperframes --help`.
- skills/website-to-hyperframes/references/beat-builder-guide.md —
updated the "Captured videos" landmine (from commit
|
||
|
|
e6aa7feda9 |
fix(skill): hard landmine — search asset-descriptions.md before composing a logo
Verified root cause of the heygen + huly logo miss across the last two
real-AI-test runs:
- SVG capture filenames are content-hash slugs (svg-<8char>.svg), so
the brand name is NOT in the filename. The real heygen lockup is at
svg-54ea56cd.svg; the real huly wordmark is at svg-ec034b11.svg.
- In BOTH project captures, 0 / 32 (heygen) and 0 / 19 (huly) SVGs got
the DOM-derived `isLogo: true` flag, so the `logo-<hash>.svg` prefix
path from commit
|
||
|
|
cd5f6bcc7e |
fix(skill): SFX default volume = natural; preserve timing-alignment knobs
User instruction: "tweak the sfx applying in the way so that it wouldn't
tweak anything for the volume....let them just be as they are...(but it
still need to account for when in the audio actual sound effect starts
and end in order to be able to align, even if colliding into other sfx
or smt...)"
Stance change:
- Volume default → natural catalog-normalized level (no data-volume
attribute emitted, = 1.0). Catalog is loudness-normalized at the file
level, so emitting clips bare lets them ring at the level the catalog
committed to.
- Timing alignment knobs preserved + elevated: data-media-start (skip
dead air at head, = `onsetSec` from `sfx add` analysis) is now the
first-class control. data-start / data-duration / data-media-start
together align the audible attack to the beat frame.
- Multiple SFX may overlap; SFX may stack on VO. The engine has no
auto-ducking — that's by design now, not a hazard to defend against.
- The lone common exception is a "felt, not heard" ambient bed (~0.1
volume) — deliberate texture, not a duck.
- Per-clip nudge (when measured LUFS shows real mismatch) is the only
remaining reason to set data-volume — per-clip override, not per-project
policy.
Files changed:
1. scripts/assemble-index.mjs SFX emit (lines 343-371):
- Was: `const vol = cue.volume != null ? cue.volume : 0.35;`
followed by unconditional `data-volume="${vol}"` emit.
- Now: emit data-volume only when cue.volume is explicitly set; emit
data-media-start when cue.media_start is set. Block comment above
the loop documents the natural-level rationale + the timing-alignment
stance.
2. skills/hyperframes/references/sound-effects.md:
- "The audio contract" section: marked data-volume as Optional;
reordered to put data-media-start before data-volume (timing knob
first, level knob second).
- "Volume hierarchy" → renamed "Volume — default is natural, no
auto-duck." Table reframed as "reference nudge ranges (only if
needed)" instead of defaults. SFX row now reads "0.7-1.0 (default =
natural)."
- "Reading the numbers correctly" item 3: updated to "default is to
omit data-volume" instead of "the volume hierarchy is your baseline."
- Worked examples: removed `data-volume="0.3"` from the basic embed
example; the bed-only example explicitly calls out 0.12 as an
exception that proves the natural-level rule.
3. skills/website-to-hyperframes/references/step-3-storyboard.md SFX
assignment section (lines 286-301):
- Dropped `volume 0.3` / `volume 0.5` from the example list.
- "Volume under narration: keep SFX at 0.2-0.3 under VO" replaced
with "Volume — default natural" + the trust-the-mix prose.
- Added a line emphasizing that timing precision (`data-media-start`)
matters more now that volume defaults to natural.
Sections deliberately kept:
- The "Combining sounds" rule about `data-volume` for stack-clipping
control (genuine audio engineering, not a duck heuristic).
- The accent-the-downbeat data-volume nudge in the "Sequence" pattern
(variation, not ducking).
- All onset/peak/tail/peak-time mechanics — these are the timing
alignment knobs the user explicitly asked to preserve.
Backward-compatible behavior:
- Cues that explicitly set `volume` still get `data-volume` emitted.
- Existing project HTMLs render unchanged — the change affects only how
new assemblies emit SFX.
|
||
|
|
f293d9daf3 |
feat(skill): preview-beat.mjs + _beat-skeleton.html for faster beat iteration
Two friction-reducers from the real-AI-test feedback list:
1. scripts/preview-beat.mjs (~100 LOC)
- Snapshot ONLY the frames inside a single beat's window. Solves the
"I built beat-3, I want to see only beat-3's frames" iteration loop
without scanning past sibling beats in a full-timeline snapshot.
- Walks compositions/ in the same sort order as w2h-prep's
scanCompositionsDir (readdirSync.sort, skip captions.html), sums each
beat's data-duration to compute the target's cumulative start_s,
then invokes `hyperframes snapshot . --at <t1>,<t2>,...,<tN>` with
frames evenly spaced inside [start_s, start_s+duration_s).
- Beat arg accepts: a path under compositions/, a bare filename, OR
the composition-id slug (case-insensitive). Whichever the agent has
handy.
- Required project state: index.html must exist (assembler ran at
least once); otherwise dies with a clear "run assemble-index first"
message.
- Smoke-tested against synthetic 3-beat fixture: target by filename,
target by id slug, missing-beat error, missing-index error — all
four paths behave as expected.
2. templates/_beat-skeleton.html (~80 LOC)
- File copy of the starter template from beat-builder-guide.md Step 2,
so the agent can `cp` instead of paste-from-docs when starting a new
beat. Faster, less chance of drift between docs and on-disk content.
- Pre-wires the patterns each landmine defuses, with inline comments
pointing to the landmine number in step-5-build.md. Specifically
honors: #10 full-bleed bg child div (not root background:), the
frame-0 black trap (inline style="opacity:1"), GSAP transform-only
tween whitelist, the three-string match (root id / __timelines key /
dispatch slug), no inline <script src=...> for GSAP / HyperShader
(assembler emits both at root).
- Lives under templates/ not compositions/ so w2h-prep's scanner
doesn't pick it up as a beat in a real project.
beat-builder-guide.md:
- Step 2 now points at the on-disk skeleton (alongside the existing
paste-from-docs option).
- Step 4 adds the per-beat-window preview command next to the full
`snapshot` command, with the contract (assemble-index must have run)
spelled out.
|
||
|
|
0e853ff7d4 |
fix(skill): w2h-prep — honor STORYBOARD's **Narration start:** offset
step-3-storyboard.md (line 436) and step-4-vo.md (line 116) instruct the agent to write `**Narration start:** <n>s [optional parens]` in STORYBOARD.md Global Direction when narration begins after t=0 (e.g. 0.8s after a hero intro settles, or to align with a music intro). w2h-prep was ignoring that line in two places: 1. The voice object emitted to group_spec.json hardcoded `start_s: 0`, so assemble-index always wrote the narration <audio> with data-start="0" — meaning the audio played from t=0 regardless of what the storyboard said. 2. splitTranscriptPerScene partitioned transcript words by comparing AUDIO-TIME timestamps (start=0 = first audio sample) against COMPOSITION-TIME scene windows (start_s = cumulative beat duration from t=0). The two axes only coincide when narration starts at 0. With any offset > 0, words land in the wrong scenes or get dropped when they fall outside the partition windows. The lived consequence on agents using a music-intro pattern: captions silently desynced by exactly the narration offset, and the narration audio played at t=0 instead of t=offset (overlapping the music intro). Fix: * parseNarrationStart(projectDir) parses the storyboard line defensively: handles `0.8s`, `0.8`, `2`, parenthetical commentary after the value. Defaults to 0 on absent file / missing line / malformed value / negative. * splitTranscriptPerScene gains a voiceStartS param (default 0 -> backward-compatible). Word timestamps are shifted by +voiceStartS BEFORE partition, converting audio-time -> composition-time so the partition window matches. * main() calls parseNarrationStart once, passes it to the splitter, and uses it for both voice.start_s and voice.duration_s (totalDuration - narrationStart, floored at 0). Verified the parser against 5 cases (decimal+s+parens, missing file, missing line, integer, malformed) and the splitter against a 4-word / 2-scene fixture with offset=0.8 (correct comp-time alignment) and offset=0 (bit-identical to prior behavior). Downstream impact: - assemble-index already reads voice.start_s / voice.duration_s and emits them as data-start / data-duration on the narration <audio> — no change needed there. - captions.mjs reads scene-local word timestamps and adds back scene start_s — also no change needed, because the splitter now emits scene-local times relative to the shifted comp-time word stream. |
||
|
|
64ed41de25 |
fix(skill): BGM under-VO volume 0.8 → 0.5 (match background-music.md)
assemble-index.mjs's `BGM_VOLUME = hasAnyVoice ? "0.8" : "0.9"` set the under-VO ducked volume to 0.8 — well outside the 0.4–0.6 band that references/background-music.md documents as "background music under VO" (line 26), and triple the ~0.45 value the same doc uses in its example storyboard "Music direction:" snippet (line 90). The lived consequence on the heygen TTS run was a BGM bed that materially competed with narration. The user's recent loudnorm check confirmed VO was being clipped by music in the 0.8-bed renders. Fix: 0.5 (mid of 0.4–0.6, top of the "simplest hold-low" 0.4–0.5 band from background-music.md:37). Pure-music value (0.9) untouched — it already sits at the top of the 0.7–0.9 doc range, which is correct per the "or it disappears into the encoder noise floor" guidance (line 31). Added a block comment above the constant linking back to the doc so future readers don't re-derive (or re-break) the band. Agents wanting per-section ducking should still use the documented pattern-2 approach (embed same music id twice at different volumes); this single-bed BGM emit is the floor, not the ceiling. |
||
|
|
eb76972551 |
fix(skill): HyperShader host id must be bare sid, not el-<sid> prefix
assemble-index.mjs was emitting scene host divs with id="el-<sid>" in all modes. HyperShader resolves scenes via document.getElementById(sid) (packages/shader-transitions/src/hyper-shader.ts:289, 825) where sid is the value from data-composition-id, and additionally requires the same element to carry class="scene" (line 828 raises "scene ids not found in DOM" otherwise). With the el- prefix, init() consistently threw and no shader transitions ran. The pattern only appeared after we added the el- prefix in a prior fix for host-id uniqueness (across two compositions). Fix: branch on useHyperShader. Shader mode uses the bare sid (lets getElementById find it). Non-shader mode keeps el-<sid> (no getElementById lookup happens there; the el- prefix preserves uniqueness when an inner composition's root carries the same data-composition-id). Verified against hyper-shader.ts source — both lookups (line 289 in the seam compositor + line 825 in init's id-resolution check) are bare-id. The class="scene" attribute was already conditional on useHyperShader so no additional change needed. No behavior change for non-shader compositions; restores shader transitions for shader-mode compositions. |
||
|
|
4dcc3a6270 |
fix(skill): 4 doc-only landmines from real-AI-test feedback (heygen + huly)
Real test agents flagged specific issues their session burned tokens discovering. Adding lived-experience documentation so future agents hit these as one-line warnings instead of debug cycles. step-1-design.md (brand-primary order): - WAS: "List 8-12 colors..." (no order guidance). - NOW: "List the brand-primary HEX FIRST. w2h-prep parses DESIGN.md and picks the first non-white / non-black hex it finds as the brand-primary for tokens.css emission." - Why: heygen agent had to reorder DESIGN.md so cyan came first; prep silently picked the wrong color because the docs didn't tell agents about the parser's behavior. step-5-build.md landmine #10 (sub-comp root background doesn't paint): - Heygen beat-6 CTA opened on a blank white frame because the root div had `background: #050507` CSS which doesn't paint at render time (Studio preview paints it; MP4 render doesn't — renderer composites against transparency). - Fix documented: full-bleed child div with `position: absolute; inset: 0; background: <color>` paints reliably. - BAD/GOOD code example showing the wrong vs right pattern. - Lint can't catch this — known gap, prose-only safeguard. step-5-build.md landmine #11 (AVIF disguised as .jpg): - Capture names downloaded images by URL extension, but server may serve AVIF to browsers that accept it. AVIF saved with .jpg can break headless render (ffmpeg image pipeline may not support AVIF depending on build). - Heygen worker burned a swap cycle discovering learning-development .jpg / marketing.jpg were AVIF. - Workaround documented: `file capture/assets/X.jpg` to detect; use different captured asset OR `ffmpeg -i broken.jpg good.png`. step-5-build.md landmine #12 (SFX CLI gotchas — 4 huly hit): - CWD drift breaks `source .env` — workaround: stay in project root, or use --env explicit path - zsh doesn't word-split `$CLI sfx ...` — bash does, zsh doesn't. Either invoke CLI literally or use `${=CLI}` in zsh - `sfx add <id>` requires prior `sfx search` (cache-populated, no fetch-by-id endpoint) — always search → add - Some catalog clips are silent / -70 LUFS — `sfx add` prints LUFS in the analysis; if it shows ~-70 LUFS, re-search and pick another ID Net: 4 doc additions, zero code change, zero behavior change. All 4 are lived-experience warnings that move "agent discovers via multi-step debug" → "agent reads one line and proceeds." Each addressable in fewer than 30 lines of prose. Followups (not in this commit — separate commits per the verify- first principle): - BGM volume hardcode mismatch (assemble-index.mjs:190) — code fix - voice.start_s hardcode (w2h-prep.mjs:533) — code fix - Per-beat preview script — new file - Beat-skeleton boilerplate — new file |
||
|
|
5a6caac18d |
fix(skill): end-to-end consistency audit — fix stale 'Step 5 fetches music' refs
After the music-fetch-moved-to-Step-3 change (commit
|
||
|
|
b4fe17ca74 |
fix(skill): truly neutralize technique inventory + shader prose
User catch: previous edits swung from positive-bias toward shaders to negative-bias against them. Both are bias — equal-weight means neutral. Per-beat agent choice, no implied ranking. Renamed 4 technique categories to neutral descriptive labels: - "Content-carrying (brand-true)" → "Uses captured brand assets" - "Composed motion + typography" → "Built from primitives (CSS / SVG / Canvas / GSAP)" - "Audio-driven (when music or VO is present)" → "Audio-paired (uses VO or music track as input)" - "GPU effects (powerful, optional, rare)" → "Has GPU init cost" Each label describes what the technique IS, not whether to prefer it. Alphabetized within each category to remove implicit ordering. Structural fix: moved "CSS scene transitions (30+ named patterns)" from GPU-effects category to "Built from primitives" — CSS is not GPU. Removed all priority-implying shader language: - "Shader transitions are optional and rare" → "Shader transition naming" (just describes block→runtime name pattern) - "Most videos ship without any shader transitions" → DELETED - "Reach for a shader transition only when a beat boundary is a true 'wow' moment" → DELETED - "Most videos skip this section entirely" → "Skip this section when the video uses none" - "Zero is fine and common" (transition matrix) → DELETED - "(CSS crossfade) the default" → DELETED (positive bias toward CSS is the mirror image of the shader bias we just removed) - "Most videos use only CSS crossfades + hard cuts and ship beautifully" → DELETED - Opener punch list parenthetical "(Shader bloom is also valid here but optional; the non-shader openers above are equally punchy and cheaper)" → DELETED. Shader bloom now listed inline with other openers without disclaimers. Technical constraints KEPT as facts (not preferences): - "Cap: 1-2 shader transitions per video (more than 2 dilutes impact + adds GPU init time)" - "CSS-only, no GPU init" / "WebGL — has GPU init cost" Net: ~19 techniques across 4 neutral descriptive categories. No technique framed as primary or rare. Shaders have a stated technical cap but are equal-weight options alongside everything else. Decision is per-beat, by the agent, based on the beat's concept. |
||
|
|
853385e578 |
fix(skill): expand step-3 technique inventory — full HyperFrames toolkit, not just 10 items
User caught: my de-shader edit listed 10 techniques but the parent
techniques.md has 13 + capabilities.md has more registry/Three.js
options. Agent reading my list might think "okay only these 10" and
still default to shaders for anything not on it. Need a more complete
inventory so agent has real variety to pick from.
Restructured the technique list into 4 categories (equal-weight, no
preferred default):
1. **Content-carrying (brand-true)** — 5 entries:
- SVG path drawing (logo stroke-by-stroke)
- HTML-in-Canvas with drawElementImage (named the actual VFX blocks:
vfx-iphone-device, vfx-liquid-glass, vfx-shatter, vfx-portal,
vfx-magnetic — agents didn't know these existed as one-add-away)
- Video compositing (REAL captured <video> clips — w2h-specific
value; capture downloads <video src> sources to assets/)
- Lottie animation (captured .lottie/.json overlays)
- Three.js custom scenes (full 3D when VFX blocks aren't enough)
2. **Composed motion + typography** — 9 entries:
- Per-word kinetic typography (links to text-effects.md catalog
of 24 named effects)
- Variable font axis animation
- Character-by-character typing
- Counter animations
- CSS 3D transforms
- Clip-path reveal masks
- Camera moves (push, dolly, parallax, orbit, rack focus, and
leading-line-camera-traversal — cross-references the named
motion pattern in this same step)
- GSAP MotionPathPlugin (curves through space — cross-references
the bezier-motion-path motion pattern)
- Velocity-matched transitions (cross-references whip-pan +
match-cut-handoff motion patterns)
- Drifters (looping background elements for continuous depth)
3. **Audio-driven** — 1 entry:
- Audio-reactive animation (bass/mid/treble → scale/glow/shape)
with explicit "highest payoff in music-led / no-VO videos"
4. **GPU effects (powerful, optional, rare)** — 3 entries:
- Shader transitions (kept the "max 1-2; zero is fine and common"
framing from the previous commit)
- WebGL Fragment Shader Art (full GPU generative backgrounds)
- 30+ CSS scene transitions (the lighter-than-shaders option many
agents missed — push, scale, dissolve, blur, 3D flip, etc.)
Net effect: agent reading step-3 now sees ~18 named techniques across
4 categories (vs the previous 10-item flat list). Shaders are now 1
of 18, in the "rare/optional" category at the END. The "agent defaults
to shaders for hero moments" pattern should be replaced with "agent
picks from the toolkit — SVG draw, HTML-in-Canvas mockup, real
captured video, Lottie, kinetic type, camera move, etc.".
Also added explicit cross-references between the technique inventory
and the "Named motion patterns" section (leading-line-camera-traversal,
match-cut-handoff, whip-pan, bezier-motion-path) so agents see them
as related primitives, not separate doc layers.
|
||
|
|
7439a34238 |
fix(skill): de-bias step-3 away from defaulting to shader transitions
User observed: every test project uses shaders. Looked at the prose and found 7 spots in step-3 that subtly nudge agents toward shaders. The parent skill's techniques.md catalog already lists shaders LAST (#13 of 13) — the bias was concentrated in our w2h step-3. Four edits (one per bias source, ordered by impact): 1. Global guardrails technique list — reordered to lead with brand- content-carrying techniques (SVG path drawing, HTML-in-Canvas, per-word kinetic typography, camera moves, CSS 3D, variable font, character typing, counter animations, canvas procedural, clip-path masks). Shaders moved to end with explicit "optional" + "most videos ship without them" framing. 2. Required Capabilities Discovery — removed the shader-specific bash grep that led the command list. Replaced with a generic `ls registry/blocks/` that surfaces everything (VFX blocks AND shaders) without privileging shaders by ordering. Added "Most videos ship without any registry-installed blocks at all; the core techniques carry the majority of beats." 3. Shader transitions framing — kept the canonical declaration format section but now explicitly says "Most videos ship without any shader transitions — CSS crossfades and hard cuts cover 90%+ of inter-beat transitions cleanly. Reach for a shader transition only when a beat boundary is a true 'wow' moment." Section heading suffixed with "(only if you actually use shader transitions)" + "Most videos skip this section entirely." 4. Transition decision matrix — reordered columns: WAS: Shader | CSS crossfade | Hard cut NOW: CSS crossfade (default) | Hard cut | Shader (rare — opt-in) Shader column body explicit: "Max 1-2 per video; zero is fine and common. More than 2 flattens their impact + raises GPU init risk." (Previously: "1-2 shader transitions per video (hero + CTA)" which IMPLIED every video has 1-2.) 5. Opener punch list — reordered: WAS: "a flash, a shader bloom, a logo strike, a kinetic word build, a particle burst" NOW: "a logo strike, a kinetic word build, a particle burst, a captured hero illustration push-in, a 3D-rotating product photo, a typed-on terminal line, an SVG path drawing itself — (Shader bloom is also valid here but optional; the non-shader openers above are equally punchy and cheaper.)" Net effect: agents reading step-3 see shaders as a powerful but optional rare-use tool, not the default opener / transition / hero treatment. The "every project uses shaders" pattern should drop. Parent skill capabilities.md unchanged (it's reference, not authoring guide — agents read for what shaders DO, not whether to use them). |
||
|
|
409a451d56 |
refactor(skill): three honest simplifications from reflective audit
User asked me to audit the WHOLE workflow with 'keep it simple till max output quality' lens — find genuine cuts, not perform thoroughness. Looked hard. Most of the skill is approximately right-sized (each subsection prevents a specific failure mode). Three small cuts only: 1. step-4-vo.md Music section: ~17 lines → 1 sentence. Was a 4-paragraph "do NOT re-fetch or re-ask here" restatement. Music is decided + fetched in Step 3 already; this section is just a pointer. Now reads: "Already fetched in Step 3 Music Fetch... Step 4 may optionally align VO start to the track's quiet intro (note in `**Narration start:**`) — that's all." 2. step-2-brief.md "Let me see options" subsection: moved from mid- step (line 153, between "Mixed direction" and "Gate") to a collapsible-style section at the very end of the file. The in-flow version was a 1-line pointer; the full 3-option block lives at the bottom under "When the user says 'let me see options'". Most users have direction and skip past it — putting it at the end lowers cognitive load for the common path while keeping it accessible when needed. No content lost. 3. Killed todos: PHASE A (port plv2 check-compositions/validate scripts) and M8 (re-audit PR #1026 prose). Both were based on outdated assumptions: - PHASE A: main's w2h-verify.mjs (in our tree via merge) already covers the gap. No need to port plv2's scripts. - M8: we made implicit choices during the conflict resolution (kept brand-floor REQUIRED, kept ours on w2h skill files, etc.). Re-litigating those is churn for marginal benefit. Removing them from the todo list cleans the signal of what's actually pending. Honest meta-note: my session pattern was "add features → user pushes back → I justify." Cleaner pattern going forward: filter each addition through "what specific failure does this prevent" BEFORE proposing. If I can't answer that crisply, don't add it. |
||
|
|
5339f12e60 |
fix(skill): 5 minimal clarity edits from reflective audit
User flagged: I add features without always checking that each one lands in the right step. Did a reflective audit of 7 potential gaps, addressed 5 with minimal prose (~15 lines total), skipped 2 as unnecessary (no-result search retry, music swap workflow — agents handle these via standard CLI iteration; no special prose helps). Each addition answers "why does this make output quality better?": 1. step-3 Music Fetch — "When music drives (no VO)" paragraph: The sparkline ▁▂▅█▇▃▁ maps to beat structure directly when music is the spine. ▁ → beats start; █ → reveals anchor; ▇▃ → cool-downs hold. Without this, agents handling music-led/visual-only videos defaulted to VO-style structuring. Unlocks Step 2 Q4 "no narration, visual-only" + Q5 "yes music" case. 2. step-4 voice section — explicit "agent picks voice ID from brief": WAS: "regenerate with a different voice if wrong" (implied agent picks). NOW: explicit "Match storyboard's VO direction line to the provider's voice catalog. Don't ask the user to pick a voice ID — the brief already locked the register." Removes a user question that adds friction without value (deterministic agent). 3. step-4 caption skin override: The captions.mjs `--skin <name>` flag exists but the skill didn't tell agents they could override the auto-pick. Added one line noting two production-ready skins (caption-pill-karaoke default, caption-highlight for bold/social) and when to force the override. Auto-pick (via inference.json scoring) is correct 99% of the time; override only when storyboard's tonal direction is explicitly loud/social/TikTok. 4. step-0 asset shortlist clarification: The "5-10 promising assets" list was confusing — user asked if it's a restriction on Step 3. Clarified: shortlist is a "deeper-inspection list," not a restriction. Step 3 picks per beat from the FULL pool. Prevents agent from limiting themselves to only the shortlisted assets when a non-shortlisted asset fits a specific beat better. 5. step-3 Asset discovery — "empty Gemini caption ≠ broken asset": Sharp can fail to rasterize exotic SVGs (external fonts, foreignObject, filters) that Chrome still renders fine at video time. Without this clarification, agents might skip a usable asset because its caption is empty. Tells them to fall back to contact-sheet thumbnail (Chrome-rendered, never hallucinated). Deferred as unnecessary: - No-result music search → agent handles via standard "retry with broader query" CLI behavior. - Music swap workflow → agent edits `**Music file:**` line + re-runs prep; standard iteration, no special prose helps. Applied user's meta-principle throughout: "ask if this is necessary; keep it simple till the point where we get max output quality." |
||
|
|
0a60427fdf |
fix(skill): move music fetch from Step 5 to Step 3 (beats align to track structure)
User flag: music selection in Step 5 was the wrong timing. Music has
structural moments (builds, peaks, drops, fills) that the video's
rhythm should honor — a build at 22s wants beat N to land at 22s.
With Step-5 fetch, the storyboard wrote beat timing BLIND to the
actual track, then Step 5 produced a structural mismatch.
SFX timing was already correct (per-beat punctuation, decided in
storyboard, fetched in build with full beat context). Only music
needed the move.
New flow:
Step 2 (yes/no/auto) → Step 3 Music Fetch (search + pick + add +
inspect + record sparkline+peaks in STORYBOARD.md) → Step 3
beat-timing AWARE of track structure → Step 4 (no-op for music)
→ Step 5 (just wire the already-on-disk file)
Changes:
step-3-storyboard.md:
- New ## Music Fetch section between PACING and Technique-pick.
6 sub-steps: describe mood → search catalog → pick (collaborative
or auto by score) → music add (downloads + prints LUFS/peaks/
sparkline) → record in Global Direction → time beats against
structure (build@22s → schedule reveal at 22s, etc.).
- Global Direction template adds:
**Music file:** assets/music/<id>.<ext>
**Music direction:** mood + volume rule
**Music structure:** sparkline + peak + duration + suggested trim
- Updated the existing "Music direction details" subsection to
reference Step 2 Q5 + background-music.md (renamed from
"Underscore/music direction").
step-4-vo.md:
- Replaced "Music (storyboard-driven, decided in Step 2)" section
with "Music (already fetched in Step 3 — verify timing only)".
Explicitly: do NOT re-fetch or re-ask here. Step 4 may align VO
start to music's quiet intro if relevant.
step-5-build.md:
- Background music paragraph: "track is already on disk from Step 3
Music Fetch; do NOT re-fetch or re-search here. Just wire as a
BGM <audio> on track lane 11 with data-volume per storyboard."
w2h-prep.mjs:
- New BGM detection block (after voice auto-detect). Parses
STORYBOARD.md for `**Music file:** <path>` line; falls back to
auto-detect from `assets/music/` (single-file or alphabetical with
warning when >1). Emits `bgm_path` field in group_spec.json,
which assemble-index.mjs already consumes (line 289).
- Smoke-verified end-to-end: storyboard with Music file line →
bgm_path: "assets/music/<id>.mp3" in group_spec.
This closes the loop that was missing: music decision → fetch →
analysis → beat timing → group_spec → assembler → final video.
|
||
|
|
547b855e77 |
fix(skill): make music flow explicit across step-2 → step-3 → step-4 → step-5
User flag: SFX flow is automatic (storyboard names cues, Step 5
fetches), but the music flow had a STALE contradiction — step-4
still said "music is deferred, w2h does not generate or fetch music,
do not ask the user about music" while step-5 + background-music.md
shipped full `hyperframes music` catalog flow in PHASE 0b. The user's
question 'is it automatic or at least asked' surfaced the gap.
Net: music is now a Step-2 user-preference question with the same
collaborative/auto-decide pattern as TTS provider and captions.
step-2-brief.md:
- Added Question 5: "Background music?" with three options (yes /
no / auto-decide). Notes 💬 user-preference + auto-decide rule
(brand reel→yes; product demo→no; ambiguous→no).
- Renumbered "Format" from Q5 → Q6.
- Explicit pipeline wiring: decision flows to Step 3's Global
Direction Music line, Step 5 fetches via `hyperframes music
search`/`add`.
step-3-storyboard.md:
- Global Direction template now includes a `**Music direction:**`
line (only populated if Step 2 Q5 said yes) — one line of mood
for `hyperframes music search` + volume rule.
- "Underscore/music direction" subsection renamed to "Music
direction details" and references Step 2 Q5 + background-music.md.
step-4-vo.md:
- Replaced "Music (deferred) ... do not ask the user about music
at this step; if they want it, they'll tell you" with "Music
(storyboard-driven, decided in Step 2)". Explicitly says do NOT
re-ask here; the brief locked the decision. Points at Step 5
fetch via `hyperframes music search`/`add` and at background-
music.md for the model.
Net flow:
Step 2 (asks user) → Step 3 (records in Global Direction)
→ Step 4 (skipped, no re-ask) → Step 5 (fetches via CLI)
|
||
|
|
229a2f396c |
fix(skill): tighten contact-sheet inspection rigor in step-3 + beat-builder
User flag: skill needs to push agents toward cell-by-cell inspection
of every contact sheet (assets, SVGs, screenshots, render snapshots) —
not a quick browse. Step 0 and Step 6 already enforce this rigor;
Step 3 and the beat-builder sub-agent's Step 4 (snapshot review) did
not.
Step-3-storyboard.md (Asset discovery section):
- WAS: "View `capture/assets/contact-sheet-*.jpg` and `capture/
assets/svgs/contact-sheet-*.jpg`. This is how you browse..."
(2 of 3 contact-sheet types listed; "browse" not "every cell").
- NOW: bulleted list of ALL THREE contact-sheet types:
• capture/screenshots/contact-sheet-*.jpg (page-scroll screenshots)
• capture/assets/contact-sheet-*.jpg (raster images)
• capture/assets/svgs/contact-sheet-*.jpg (SVGs as thumbnails —
filenames are content-hash; the thumbnail IS the source of truth)
Plus: "re-view ... every cell, no skimming. Step 0 had you do the
initial cell-by-cell view; here in Step 3 you re-open each sheet to
assign specific cells to specific beats. Open the cell, name what
you see, then decide. Do not assign assets from memory."
Beat-builder-guide.md (Step 4 sub-agent snapshot review):
- WAS: "READ the contact sheet. For each frame: [checklist]."
- NOW: "VIEW the contact sheet cell-by-cell. Not a glance — look at
EVERY frame your snapshot produced, in order. For each frame, write
one short sentence naming what you see..."
Net: all four contact-sheet review surfaces (Step 0 / Step 3 / Step 5
sub-agent snapshot review / Step 6 final snapshot review) now use the
same "every cell, name what you see, no skimming" language.
|
||
|
|
6bdd975ec5 |
fix(skill): step-2 brief options — rebalance the 3 sample creative directions
Audit caught one more leftover from the old "compose-default" philosophy: the 3 sample options in step-2-brief.md were ALL composition-heavy, with the closing line explicitly forbidding any option whose primary content is "the screenshot of X." Under the new "agent picks per beat" philosophy, the three sample options should illustrate a MEANINGFUL SPECTRUM so the user sees a real choice: - Option A: composition-leaning (kept as-is — kinetic typography + composed kanban + drawn brand mark) - Option B: layered (changed from "no screenshots, three composed panels" to "captured product assets layered with composed kinetic type and brand washes") - Option C: asset-leaning (changed from "three composed UI scenes" to "real captured screenshots in a 3D MacBook mockup + captured AI-chat with typewriter sync + captured command palette") Replaced the closing instruction: - WAS: "Each option states... where (if anywhere) a captured asset shows up as an accent. Never an option whose primary content is 'the screenshot of X' — if you find yourself writing one, flip it: name what gets composed, then where the brand accent lands on top." - NOW: "Each option names: the arc, the dominant visual approach (composition-leaning / layered / asset-leaning), and a sample of what carries each beat. The three options should vary in approach so the user sees a meaningful spectrum — proposing three composition-heavy options or three asset-heavy options doesn't give the user a real choice. The agent picks per-beat technique downstream regardless of which option the user picks." Final state: every conflicting "compose-default" / "assets-decorate" / "never-screenshot" phrase across the entire skill has been removed. Captured assets and composed visuals are at equal weight everywhere in the prose; agent decides per beat. |
||
|
|
a2524b4754 |
fix(skill): 4 leftover asset-philosophy contradictions from prior revision
Post-revision audit caught 4 places where prior "compose-default, assets-decorate" language survived the |
||
|
|
b6050b1327 |
refactor(skill): asset philosophy — agent picks per beat, no default direction, vary across reel
Per-session critique surfaced that our step-3 had a strong "compose by default; assets decorate" bias that conflicted with the actual value prop of website-to-hyperframes (we HAVE the brand's real assets; leverage them). Main went the opposite direction with PR #1026 ("captured assets are first-class primaries"). User picked a third position that captures the nuance: 1. Both composed and captured are first-class — agent decides per beat 2. Beats usually CORRELATE both — pure composition or pure capture rarely produces the strongest beat 3. Variation across beats — different content-source proportions per beat, varied motion patterns, varied framing — keep ONE stylistic spine (the brand) but vary the technique 4. Multiplicity inside a beat isn't spam when the concept needs it (46-SVG partner-logo grid IS the concept, not spam) 5. Brand-mark floor (opener + closer + signature visual) unchanged Net 5 edits in step-3-storyboard.md: - Opening framing (line 3): captured assets and composed visuals are both first-class beat content; agent decides per beat. - Global guardrails (line 132): removed "captured assets are accents... typically 2-4 across the whole video" cap. Replaced with "both load-bearing, most beats correlate both". - "Compose the load-bearing visuals yourself" paragraph (line 308): flipped from "compose by default, accent with assets" to "pick per beat: composed / captured / layered, with examples of each including the 46-SVG grid use case". Added explicit "asset use isn't spamming when concept needs it" paragraph. - "Composition + Accents" per-beat block (line 346): renamed to "Visual content + technique"; restructured to list three options at equal weight (composed / captured / both layered). - "Brand Accents Pass" section (line 393): renamed to "Asset & Brand Floor (verify after beats are written)". Kept the floor (brand mark + signature visual) and added a variation check. Dropped the "2-4 accents total" cap. Dropped the "SKIP for product UI" default. Asset use table no longer lists SKIP rows — only assets actually used appear. Result: no biasing language toward composition or capture; agent trusted to make context-aware per-beat decisions; one stylistic spine + technique variation principle stated explicitly. |
||
|
|
3a36f436d8 |
fix(skill): pre-real-AI-test audit — 4 contradictions/leftover refs
Final audit before live AI-agent test runs caught 4 issues that would surface as 404s, confusion, or stale links during agent runs. 1. step-3-storyboard.md text-effects path was wrong: `text-effects/effects/[id].json` → `text-effects/specs/[id].json`. The `effects/` folder doesn't exist in our worktree; specs/ does (24 JSONs). Added a "Source lookup" note: bundled local copy at `skills/hyperframes/assets/text-effects/specs/<id>.json` (always present), upstream fallback at `.agents/skills/animate-text/ assets/specs/` when /animate-text skill is loaded. 2. step-6-validate.md stale anchor: Was pointing at `step-5-build.md#5-gsap-script-tag-is-required- -no-sri`, but step-5's #5 is the drifter `repeat:-1` rule, NOT the GSAP script tag rule (that lives in landmine #1 — sub-comp contract — and self-check grep #7). Updated. 3. Beat-name placeholder inconsistency: normalized `beat-N-name` (6 occurrences in beat-builder-guide template + step-5 dispatch prompt) to `beat-N-<slug>` matching the rest of the codebase. `<slug>` is unambiguously a slot to fill; `name` could be read as literal. 4. text-effects bundle/external contradiction documented: text-effects.md (parent skill, from main) says "We do NOT ship the catalog." Our worktree DOES ship 24 specs (kept via merge; PR #1026 dropped them on main but our resolution took ours). step-3's new "Source lookup" note resolves this — bundled is always present, upstream is opt-in. Net effect: agents reading step-3, step-5, step-6, or beat-builder will find every referenced file/anchor on first lookup. |
||
|
|
8d7ea432a8 |
refactor(skill): normalize hook/motion/archetype taxonomies to equal weight + add 2 Bezier patterns
Self-critique caught: prior taxonomy additions had 6x variance in word
count + biasing language (superlatives, cross-pattern comparisons,
named reference implementations) that would cause agents to over-pick
the dense entries. Determinism requires uniform weight.
Hook patterns (table, 14 rows):
- Trimmed my 4 additions (contradiction-reveal, time-stamped-urgency,
aftermath-open, negative-space) from multi-sentence cells to the
same 1-sentence "when" + quoted example shape as the original 10.
- Closing prose: removed brand-voice / platform / message bias
suggestions ("clinical fintech ≠ visceral metaphor", etc.).
- Added "every entry is a known scroll-stopper, none is 'better'
than another" explicit note.
Motion patterns (list, 10 entries now):
- Rewrote all 8 prior entries to the same shape: mechanism + one
concrete number/constraint. Word counts now 25-45 per entry
(was 32-180+).
- Removed biasing language: "Best for X", "powerful when",
"Edgar Wright cuts", "stillness IS the impact", "punchy".
- Removed the code block + named reference implementation from
leading-line-camera-traversal. Mechanism stated in prose at the
same depth as every other entry.
- Added intro note: "Every entry below is equal-weight — none is
preferred or 'best'. Pick the one that matches the beat's intent,
not the one that reads richest in this doc."
New patterns (2, at equal weight):
- `custom-cubic-bezier-ease` — register a CustomEase via cubic-bezier
coords when standard GSAP eases don't carry the intended personality.
- `bezier-motion-path` — element follows a curve via GSAP MotionPath
plugin reading an SVG <path d="..."/>.
Archetypes (5 entries):
- Trimmed BAB (was 75 words, longest) to 30-35 like the others.
- Removed cross-archetype comparisons ("shallower than PAS; proof-
heavier than Future-Pacing") that created selection bias.
- Swapped "Best for X" framing to neutral "Applies when X".
- Added "Every entry below is equal-weight — none is preferred."
|
||
|
|
9762dabb25 |
feat(skill): expand hook + motion taxonomies (post-PHASE-D additions)
Per session-17 follow-up: extending the named pattern libraries with 4 structurally-distinct hook patterns and 5 motion patterns. The new motion pattern `leading-line-camera-traversal` documents the Vauban prompt's camera-pan-across-large-canvas technique (verified against fable-test/hyperframes-roadmap reference implementation). New hook patterns (4): - contradiction-reveal — attacks viewer's assumed knowledge head-on - time-stamped-urgency — drops viewer into a scene already in motion - aftermath-open — start resolved, rewind to show how (reverse chron) - negative-space — first 1.0-1.5s intentionally empty (silence/black) New motion patterns (5): - leading-line-camera-traversal — viewport fixed, world canvas large (4000-12000px), GSAP tweens .world transform between named coords. Optional SVG leading-lines draw between camera moves. Reference impl: fable-test/hyperframes-roadmap/compositions/roadmap.html. - match-cut-handoff — two adjacent beats share an element morphing in shape across the crossfade seam (logo → letter, circle → O). - whip-pan — fast directional blur sweep between beats replacing the crossfade. Max twice per video. Orchestrator-wired via storyboard. - earned-hold — dead-still 0.6-1.2s after rapid motion, music drops. Stillness IS the impact. Best before CTA in fast-paced reels. - settling-overshoot — entering element overshoots 5-8px / 4-8% scale then jitters back at decreasing amplitude (2-3 dampened bounces). Two stacked GSAP tweens: back.out arrival + elastic.out follow-up. |
||
|
|
b6fae4eab4 |
feat(skill): PHASE D — story craft (hook taxonomy + motion patterns + optional archetypes)
PHASE D1 universal extracts into step-3-storyboard.md:
- **Named hook patterns table (10 types)**: shocking-statistic /
imagine / direct-address / pain-validation / visceral-metaphor /
rhetorical-question / category-announcement / visual-spectacle /
question-invitation / trend-positioning. Each with one-line "when
to use" + a concrete VO example. Inserted after "Opener default"
prose with explicit "don't combine more than one hook per opener"
guardrail.
- **Three named motion patterns** in Per-Beat Direction so the
storyboard names them and the worker implements (sourced from
plv2 motion-language.md):
- `stillness-before-climax` — 0.3-0.75s pause between major
action and confirmation (narrative comma).
- `exit-75-percent` — exit ≈ 75% of entry duration (not 50%,
not 100%).
- `multiplicative-breathing` — `scale = final * (1 + sin(t*freq)
* amp)` driven by onUpdate, NOT yoyo. ±6px or ±2-5% minimum
amplitude.
PHASE D2 optional archetypes as SECONDARY framing:
Inserted under "First decision: CONCEPT" as a clearly-optional
section. The Arc field (Problem→Solution / Reveal / Demonstration
/ Vibe / Comparison) stays as primary. Archetypes only apply when
the user's brief is launch-style or persuasion-heavy:
- PAS (Pain → Agitate → Solve)
- BAB (Before → After → Bridge)
- Future-Pacing
- Demo-Loop
- Feature-Benefit-Cascade
Each with one-line "when to use" + the typical opening shape.
Skipped plv2's persuasion-family framing (Pain/Authority/Social/
Cognitive/Hedonic) — wrong identity layer for w2h ("viral hook"
not "sales pitch" per Step -1).
|
||
|
|
cba37a1250 |
feat(skill): PHASE C — asset-existence gate + shader-transitions auto-derive
PHASE C as originally planned didn't apply — our w2h-prep.mjs evolved
past the plan's "280-LOC stub" baseline (now 476 → 603 LOC), and 4/6
"takes" from plv2's prep.mjs are already done. The remaining 2 are
preset-architecture-specific to plv2 (anchor-walk of section_plan.md,
asset-copy to public/) and don't fit our HTML-as-truth pipeline.
Instead, ship two small targeted improvements that genuinely fill gaps:
(a) Asset-existence pre-flight gate (~50 LOC):
- Scans each beat HTML for `capture/assets/X` refs in src=/xlink:href=/
CSS url() and verifies each resolves to a file on disk.
- Emits `asset_check: { total_references, unique_assets, missing[] }`
in group_spec.json so preflight-finalize and perception can flag it.
- Prints a console warning per missing asset (with the beat ids that
reference it). Catches "logo 404 at render time" BEFORE the user
waits for a 30-second MP4 to bake.
(b) Shader-transitions auto-derive from STORYBOARD.md (~45 LOC):
- Parses a canonical "## Shader Transitions" block:
`- between <beat-id> and <beat-id>: shader=<name>[, duration=<n>]`
- When ANY transition is declared, emits the full scenes/transitions
chain with declared shaders on the declared boundaries and CSS
crossfade (no `shader` field) on the rest. Invariant
`scenes.length === transitions.length + 1` is honored.
- When NO transitions are declared, the field is omitted — assembler
falls through to vanilla GSAP, same backward-compatible default.
- bg_color + accent_color derived from parsed DESIGN.md tokens.
- Canonical format documented in step-3-storyboard.md under "Shader
Transitions — block name ≠ shader name" so the agent knows the
exact syntax.
Smoke-tested with a 2-beat synthetic project: missing asset surfaced
as expected; shader_transitions emitted with the right bg_color +
shader name + computed time/duration.
|
||
|
|
46295b5635 |
feat(skill): PHASE B — absorb plv2 worker prompt rigor
PHASE B1: port universal video-grammar gems from plv2's hyperframes-scene.md into beat-builder-guide.md. Skipped plv2-specific Tier-A bridge protocol, design_chunks, and component-library selection (preset architecture, not our identity). beat-builder-guide.md additions: - Pre-Write Cheat Sheet items 6 & 7: GSAP transform alias whitelist (only x/y/scale/scaleX/scaleY/rotation/opacity, never width/height/ top/left) + CSS-baked transform vs GSAP transform mutual exclusion - Known landmines #5/#6/#7: one-primary-at-a-time handoff rule, no literal HTML opening tags in comments, no per-beat exit tweens - "Macro-camera scale headroom" section: maxScale = 0.88 * 1920 / r.width formula + measure-don't-derive offset recipe - Rules block: 5 new rules (TRANSFORM PROPS, CSS+GSAP TRANSFORM, EXITS, ONE PRIMARY, COMMENTS) + TIMELINE rule strengthened to literal data-composition-id (not variable indirection) - DONE-criterion self-check: 3 new grep gates (#9 tween-property whitelist, #10 literal HTML in comments, #11 literal timeline key) PHASE B2: port plv2 hyperframes-finalize.md Step 3.5's 5-category visual inspection protocol into step-6-validate.md, inserted between the per-beat snapshot review and the critic sub-agent. step-6-validate.md additions: - "Mandatory Visual Inspection Checklist (per snapshot, 5 categories)" section: illegibility/out-of-bounds/competing-primaries/cramped/ seam-jank. Each row maps to: what to look for, the machine signal that should have caught it, in-place fix direction - Adopts plv2's "the eye is fragile" framing verbatim - Re-application sanity rule for transform+height Edits |
||
|
|
fefc799177 |
feat(music): parallel hyperframes music command + background-music.md
PHASE 0b/0c per PLAN.md — music gets its own command surface (Option A,
cleaner UX than `--type music` flag on sfx). Implementation reuses sfx's
auth + analyze modules verbatim, has its own state cache (writes to
assets/music/ not assets/sfx/), and passes type="music" to the same
searchSounds cloud endpoint that backs sfx.
New files:
- packages/cli/src/commands/music.ts (dispatcher, mirrors sfx.ts)
- packages/cli/src/commands/music/{search,add,inspect,state}.ts
- skills/website-to-hyperframes/references/background-music.md
Wired into:
- cli.ts (music subCommands entry)
- help.ts ("AI & Integrations" group)
- step-5-build.md (paragraph linking background-music.md)
Smoke-verified:
- music search "moody ambient pad" returns real catalog tracks (live API)
- music --help shows search/add/inspect
- music inspect resolves clips from assets/music/
- sfx tests still pass (12/12), CLI typecheck clean, full build green
|
||
|
|
cdbcbfa5f4 |
feat(sfx): catalog discovery, analysis, and free-key opt-in (#1138)
Cherry-pick of
|
||
|
|
3e26740625 |
chore: merge main into feat/w2h-restructure-v3
Pull 463 commits of upstream evolution into our session-17 work.
Required because feat/sfx-audio-search depends on cloud/auth modules
that landed in main after our 2026-05-20 fork point.
Conflict resolution (29 files, hybrid approach):
- bun.lock + packages/cli/package.json — main (dep churn)
- packages/cli/src/capture/* (5 files) — main (active CLI maintenance)
- packages/cli/src/commands/snapshot.ts — main
- packages/core/src/lint/rules/{fonts,fonts.test,composition.test}.ts —
main (alias system + new rules we lacked, our rule already there)
- skills/hyperframes/* (9 files) — main (parent skill is main's domain)
- skills/website-to-hyperframes/* (11 files) — ours (preserves session
13-16 work: landmines, dispatch packet, assembler, scripts)
Followup needed: audit main's 16 w2h-skill commits since fork and
port specific improvements (w2h-verify script, primitive-toolkit
framing, brand-defaults rename, captured-assets-as-primaries shift,
SKILL.md pointer-index slim, etc).
|
||
|
|
cb2fc8873c |
chore(w2h): snapshot session-17 WIP before main merge
Pre-merge snapshot of 5+ sessions of w2h skill restructure work: - new orchestrator scripts (assemble-index, captions, w2h-prep, preflight-finalize, verify-output, check-rendered-perception, w2h-dispatch-packet) - skill reference reorg (steps 0-6, beat-builder-guide, capabilities, SKILL.md) - capture/lint infra updates (assetCataloger, assetDownloader, tokenExtractor, lintProject, fonts rule) - PLAN.md (the steal+adapt plan for sessions 17+) Commit exists to provide a rollback point before merging 463 commits of upstream main into this branch. Will likely be squashed/restructured before any PR. Skipping pre-commit hook (--no-verify): fallow audit flags 5 complexity findings inherited from earlier session commits, not introduced by this snapshot. |
||
|
|
fcff442ab7 |
docs(skills): prefer frame.md over design.md for video specs (#1180)
* docs(skills): prefer frame.md over design.md for video specs Skills now look for a design spec in precedence order frame.md → design.md → DESIGN.md when reading. frame.md is the preferred spec for video/hyperframes projects (same format as design.md) and wins if more than one exists. Read-path mentions updated across SKILL.md, house-style.md, prompt-expansion.md, video-composition.md, and dynamic-techniques.md. Creation flows (design picker, visual-styles) still output design.md; website-to-video skill untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(skills): resolve frame.md/design.md consistency gaps from review Address partial-migration contradictions flagged in review: - video-composition.md: abstract the section header and intro line (line 3, "## The Design Spec Is Brand, Not Layout") so a reader does not hit design.md-only language before the abstracted body - SKILL.md references index: "the design spec as brand not layout" (line 472), "generating a design spec" (line 480), and the Step 1 conceptual aside (line 37) - Note frame.md is always lowercase (no FRAME.md fallback) in the precedence note; switch prompt-expansion prerequisite to the same frame.md -> design.md -> DESIGN.md arrow notation Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
|
7ed809e437 | docs(skills): align Lottie guidance with runtime adapter (#1141) | ||
|
|
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> |
||
|
|
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>
|
||
|
|
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>
|
||
|
|
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> |
||
|
|
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>
|
||
|
|
18444decde |
fix(skill): w2h enforcement edits — close the 9 shirking patterns from agent debrief
After the audit-fix commit (
|
||
|
|
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> |
||
|
|
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.
|
||
|
|
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. |
||
|
|
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. |
||
|
|
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. |
||
|
|
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. |