mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-09 03:16:38 +00:00
ae717331ce1920eee863ee4be439b21464b9f4e7
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 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> |
||
|
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.
|
||
|
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. |
||
|
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. |
||
|
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.
|