From eee496b4a8b5a4fb0e0653aee015188f5056441f Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Mon, 3 Aug 2026 02:53:52 -0700 Subject: [PATCH] docs: add canonical reference project --- .gitattributes | 7 + .gitignore | 9 + examples/docs-reference-project/.gitignore | 6 + .../.media/audio/bgm/bgm_001.wav | 3 + .../.media/audio/sfx/sfx_001.mp3 | 3 + .../.media/audio/sfx/sfx_002.mp3 | 3 + .../.media/audio/sfx/sfx_003.mp3 | 3 + .../.media/audio/sfx/sfx_004.mp3 | 3 + .../.media/audio/voice/voice_001.wav | 3 + .../.media/images/image_001.png | Bin 0 -> 21297 bytes .../docs-reference-project/.media/index.md | 10 + .../.media/manifest.jsonl | 7 + examples/docs-reference-project/AGENTS.md | 95 ++ examples/docs-reference-project/BRIEF.md | 90 ++ examples/docs-reference-project/CLAUDE.md | 95 ++ examples/docs-reference-project/README.md | 170 +++ examples/docs-reference-project/SCRIPT.md | 70 ++ examples/docs-reference-project/STORYBOARD.md | 89 ++ .../docs-reference-project/VERIFICATION.md | 285 +++++ .../docs-reference-project/assets/bgm.wav | 3 + .../assets/example-com.png | Bin 0 -> 21297 bytes .../assets/narration.wav | 3 + .../assets/sfx-tick.mp3 | 3 + .../assets/sfx-whoosh.mp3 | 3 + .../capture/extracted/animations.json | 12 + .../capture/extracted/asset-descriptions.md | 22 + .../capture/extracted/design-styles.json | 38 + .../capture/extracted/fonts-manifest.json | 9 + .../capture/extracted/page.html | 11 + .../capture/extracted/tokens.json | 47 + .../capture/extracted/visible-text.txt | 3 + .../capture/screenshots/contact-sheet.jpg | Bin 0 -> 9300 bytes .../capture/screenshots/full-page.png | Bin 0 -> 21297 bytes .../capture/screenshots/scroll-000.png | Bin 0 -> 21297 bytes .../compositions/captions.html | 241 ++++ examples/docs-reference-project/frame.md | 101 ++ .../docs-reference-project/hyperframes.json | 13 + examples/docs-reference-project/index.html | 370 ++++++ .../docs-reference-project/live/index.html | 1088 +++++++++++++++++ .../docs-reference-project/live/poster.jpg | Bin 0 -> 91798 bytes .../live/reference-project-v2.mp4 | 3 + examples/docs-reference-project/meta.json | 5 + examples/docs-reference-project/package.json | 11 + .../snapshots/contact-sheet-1.jpg | Bin 0 -> 128728 bytes .../snapshots/contact-sheet-2.jpg | Bin 0 -> 182399 bytes .../snapshots/contact-sheet-3.jpg | Bin 0 -> 39929 bytes .../docs-reference-project/transcript.json | 87 ++ scripts/docs/bundle-live-reference.mjs | 22 + 48 files changed, 3046 insertions(+) create mode 100644 examples/docs-reference-project/.gitignore create mode 100644 examples/docs-reference-project/.media/audio/bgm/bgm_001.wav create mode 100644 examples/docs-reference-project/.media/audio/sfx/sfx_001.mp3 create mode 100644 examples/docs-reference-project/.media/audio/sfx/sfx_002.mp3 create mode 100644 examples/docs-reference-project/.media/audio/sfx/sfx_003.mp3 create mode 100644 examples/docs-reference-project/.media/audio/sfx/sfx_004.mp3 create mode 100644 examples/docs-reference-project/.media/audio/voice/voice_001.wav create mode 100644 examples/docs-reference-project/.media/images/image_001.png create mode 100644 examples/docs-reference-project/.media/index.md create mode 100644 examples/docs-reference-project/.media/manifest.jsonl create mode 100644 examples/docs-reference-project/AGENTS.md create mode 100644 examples/docs-reference-project/BRIEF.md create mode 100644 examples/docs-reference-project/CLAUDE.md create mode 100644 examples/docs-reference-project/README.md create mode 100644 examples/docs-reference-project/SCRIPT.md create mode 100644 examples/docs-reference-project/STORYBOARD.md create mode 100644 examples/docs-reference-project/VERIFICATION.md create mode 100644 examples/docs-reference-project/assets/bgm.wav create mode 100644 examples/docs-reference-project/assets/example-com.png create mode 100644 examples/docs-reference-project/assets/narration.wav create mode 100644 examples/docs-reference-project/assets/sfx-tick.mp3 create mode 100644 examples/docs-reference-project/assets/sfx-whoosh.mp3 create mode 100644 examples/docs-reference-project/capture/extracted/animations.json create mode 100644 examples/docs-reference-project/capture/extracted/asset-descriptions.md create mode 100644 examples/docs-reference-project/capture/extracted/design-styles.json create mode 100644 examples/docs-reference-project/capture/extracted/fonts-manifest.json create mode 100644 examples/docs-reference-project/capture/extracted/page.html create mode 100644 examples/docs-reference-project/capture/extracted/tokens.json create mode 100644 examples/docs-reference-project/capture/extracted/visible-text.txt create mode 100644 examples/docs-reference-project/capture/screenshots/contact-sheet.jpg create mode 100644 examples/docs-reference-project/capture/screenshots/full-page.png create mode 100644 examples/docs-reference-project/capture/screenshots/scroll-000.png create mode 100644 examples/docs-reference-project/compositions/captions.html create mode 100644 examples/docs-reference-project/frame.md create mode 100644 examples/docs-reference-project/hyperframes.json create mode 100644 examples/docs-reference-project/index.html create mode 100644 examples/docs-reference-project/live/index.html create mode 100644 examples/docs-reference-project/live/poster.jpg create mode 100644 examples/docs-reference-project/live/reference-project-v2.mp4 create mode 100644 examples/docs-reference-project/meta.json create mode 100644 examples/docs-reference-project/package.json create mode 100644 examples/docs-reference-project/snapshots/contact-sheet-1.jpg create mode 100644 examples/docs-reference-project/snapshots/contact-sheet-2.jpg create mode 100644 examples/docs-reference-project/snapshots/contact-sheet-3.jpg create mode 100644 examples/docs-reference-project/transcript.json create mode 100644 scripts/docs/bundle-live-reference.mjs diff --git a/.gitattributes b/.gitattributes index 1774de7285..008fcbdb62 100644 --- a/.gitattributes +++ b/.gitattributes @@ -51,3 +51,10 @@ registry/**/*.html linguist-vendored # Documentation videos are shipped from the repo and include full journey films. # Keep binary masters out of the Git object store while preserving their paths. docs/**/*.mp4 filter=lfs diff=lfs merge=lfs -text + +# The documentation Reference Project ships real voice, music, and source +# media. Keep its binary assets out of the Git object store while preserving a +# complete, cloneable example. +examples/docs-reference-project/**/*.wav filter=lfs diff=lfs merge=lfs -text +examples/docs-reference-project/**/*.mp3 filter=lfs diff=lfs merge=lfs -text +examples/docs-reference-project/**/*.mp4 filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore index 52719ff212..125416d1ba 100644 --- a/.gitignore +++ b/.gitignore @@ -97,6 +97,8 @@ examples/* !examples/k8s-jobs/** !examples/gcp-cloud-run !examples/gcp-cloud-run/** +!examples/docs-reference-project +!examples/docs-reference-project/** # …but never the local smoke run's build/render artifacts. examples/gcp-cloud-run/scripts/gcp-smoke-artifacts/ packages/studio/data/ @@ -181,3 +183,10 @@ tmp/ # Local editor settings .zed/ + +# Keep the documentation Reference Project complete. Several generic scratch +# rules above also match legitimate directories inside this one real example; +# this final negation restores it, while the project's own .gitignore still +# excludes renders, work files, and individual snapshot frames. +!examples/docs-reference-project/ +!examples/docs-reference-project/** diff --git a/examples/docs-reference-project/.gitignore b/examples/docs-reference-project/.gitignore new file mode 100644 index 0000000000..f0de91ced1 --- /dev/null +++ b/examples/docs-reference-project/.gitignore @@ -0,0 +1,6 @@ +.work/ +.hyperframes/ +.transcode-cache/ +node_modules/ +renders/ +snapshots/frame-*.png diff --git a/examples/docs-reference-project/.media/audio/bgm/bgm_001.wav b/examples/docs-reference-project/.media/audio/bgm/bgm_001.wav new file mode 100644 index 0000000000..1e84467a0e --- /dev/null +++ b/examples/docs-reference-project/.media/audio/bgm/bgm_001.wav @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8935eb87c960b062ad9c42bce3f4e12408f389dfb82acba986999e62db76fe5b +size 1920078 diff --git a/examples/docs-reference-project/.media/audio/sfx/sfx_001.mp3 b/examples/docs-reference-project/.media/audio/sfx/sfx_001.mp3 new file mode 100644 index 0000000000..0dbe2e6e22 --- /dev/null +++ b/examples/docs-reference-project/.media/audio/sfx/sfx_001.mp3 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3d889ca2011181a932477408b46ded66549a3179a7183d7735af55b819ee4640 +size 30240 diff --git a/examples/docs-reference-project/.media/audio/sfx/sfx_002.mp3 b/examples/docs-reference-project/.media/audio/sfx/sfx_002.mp3 new file mode 100644 index 0000000000..33d3469f19 --- /dev/null +++ b/examples/docs-reference-project/.media/audio/sfx/sfx_002.mp3 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:745ecbd9ddd273d48e6bd9f4511dda08a91514d39bd9c989aa92773a4946c369 +size 7584 diff --git a/examples/docs-reference-project/.media/audio/sfx/sfx_003.mp3 b/examples/docs-reference-project/.media/audio/sfx/sfx_003.mp3 new file mode 100644 index 0000000000..4472244764 --- /dev/null +++ b/examples/docs-reference-project/.media/audio/sfx/sfx_003.mp3 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c2efd9d902a59bf9ec5019035d7deadd17762136896b6e3cb6dd99ea50997a30 +size 18390 diff --git a/examples/docs-reference-project/.media/audio/sfx/sfx_004.mp3 b/examples/docs-reference-project/.media/audio/sfx/sfx_004.mp3 new file mode 100644 index 0000000000..92bf41da61 --- /dev/null +++ b/examples/docs-reference-project/.media/audio/sfx/sfx_004.mp3 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:075e17bdac5c13662a1c9530050e0046f81d4138e00eb3bf30427a7b4404103d +size 11702 diff --git a/examples/docs-reference-project/.media/audio/voice/voice_001.wav b/examples/docs-reference-project/.media/audio/voice/voice_001.wav new file mode 100644 index 0000000000..3b3c135118 --- /dev/null +++ b/examples/docs-reference-project/.media/audio/voice/voice_001.wav @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4fca03080a6626474df0deda3f6b1b679321a4b6c813ec2876ac8baae476fd49 +size 614478 diff --git a/examples/docs-reference-project/.media/images/image_001.png b/examples/docs-reference-project/.media/images/image_001.png new file mode 100644 index 0000000000000000000000000000000000000000..1d17d46b2985f1a52a6bc3bd44992d05403206a0 GIT binary patch literal 21297 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 P`)zH*TNO7S{Qds{<;IGL literal 0 HcmV?d00001 diff --git a/examples/docs-reference-project/.media/index.md b/examples/docs-reference-project/.media/index.md new file mode 100644 index 0000000000..f1c5e7a594 --- /dev/null +++ b/examples/docs-reference-project/.media/index.md @@ -0,0 +1,10 @@ +# .media · 7 assets + +id type dur dims path description +bgm_001 bgm — — .media/audio/bgm/bgm_001.wav bgm.wav +image_001 image — — .media/images/image_001.png full-page.png +sfx_001 sfx 1.4s — .media/audio/sfx/sfx_001.mp3 A quick, airy synthesized whoosh rapidly sweeps past. +sfx_002 sfx 0.2s — .media/audio/sfx/sfx_002.mp3 A very brief, sharp click. +sfx_003 sfx — — .media/audio/sfx/sfx_003.mp3 whoosh-short.mp3 +sfx_004 sfx — — .media/audio/sfx/sfx_004.mp3 click-soft.mp3 +voice_001 voice — — .media/audio/voice/voice_001.wav narration.wav diff --git a/examples/docs-reference-project/.media/manifest.jsonl b/examples/docs-reference-project/.media/manifest.jsonl new file mode 100644 index 0000000000..4ffd2972c5 --- /dev/null +++ b/examples/docs-reference-project/.media/manifest.jsonl @@ -0,0 +1,7 @@ +{"id":"bgm_001","type":"bgm","path":".media/audio/bgm/bgm_001.wav","source":"ingested","description":"bgm.wav","provenance":{"provider":"local","from":"/Users/ularkimsanov/Desktop/HYPERFRAMES-JOURNEY-FILMS-V1/quickstart/example-intro/assets/bgm.wav"}} +{"id":"image_001","type":"image","path":".media/images/image_001.png","source":"ingested","description":"full-page.png","provenance":{"provider":"local","from":"./capture/screenshots/full-page.png"}} +{"id":"sfx_001","type":"sfx","path":".media/audio/sfx/sfx_001.mp3","source":"search","description":"A quick, airy synthesized whoosh rapidly sweeps past.","duration":1.4,"provenance":{"provider":"heygen.audio.sounds","prompt":"short soft airy whoosh for a panel sliding into frame","authMethod":"api_key","track_id":"a4855a82116cd4cc","score":0.7158975005149841,"query":"short soft airy whoosh for a panel sliding into frame"}} +{"id":"sfx_002","type":"sfx","path":".media/audio/sfx/sfx_002.mp3","source":"search","description":"A very brief, sharp click.","duration":0.2,"provenance":{"provider":"heygen.audio.sounds","prompt":"soft muted click, a single restrained UI tick","authMethod":"api_key","track_id":"cf8c57bb210753f6","score":0.6379230618476868,"query":"soft muted click, a single restrained UI tick"}} +{"id":"sfx_003","type":"sfx","path":".media/audio/sfx/sfx_003.mp3","source":"ingested","description":"whoosh-short.mp3","provenance":{"provider":"local","from":"/Users/ularkimsanov/.claude/skills/media-use/audio/assets/sfx/whoosh-short.mp3"}} +{"id":"sfx_004","type":"sfx","path":".media/audio/sfx/sfx_004.mp3","source":"ingested","description":"click-soft.mp3","provenance":{"provider":"local","from":"/Users/ularkimsanov/.claude/skills/media-use/audio/assets/sfx/click-soft.mp3"}} +{"id":"voice_001","type":"voice","path":".media/audio/voice/voice_001.wav","source":"ingested","description":"narration.wav","provenance":{"provider":"local","from":"./assets/narration.wav"}} diff --git a/examples/docs-reference-project/AGENTS.md b/examples/docs-reference-project/AGENTS.md new file mode 100644 index 0000000000..5c8126aeb2 --- /dev/null +++ b/examples/docs-reference-project/AGENTS.md @@ -0,0 +1,95 @@ +# HyperFrames Composition Project + +## Skills — USE THESE FIRST + +**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions. + +**Doing anything with HyperFrames?** Start at `/hyperframes` — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), confirms your brief up front (the intent layer), and routes every "make me a…" request (a video, a deck, a composition port) to the right workflow. Read it first, especially when there's no project context to orient you. The workflows it routes to: + +- `/product-launch-video` — any **website** URL or brief / script → a product launch / SaaS / promo video, or a site tour / showcase featuring the site's own captured visuals. +- `/faceless-explainer` — arbitrary text (topic / article / notes), **no URL, no website capture** → 60-90s faceless explainer. +- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched. +- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.) +- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor). +- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`. +- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. +- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. +- `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes authoring flow, any length. + +**Porting an existing composition?** `/remotion-to-hyperframes` translates a Remotion (React) composition into HyperFrames HTML — a source migration, separate from the creation workflows above. + +The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-keyframes`, `/hyperframes-creative`, `/hyperframes-cli`, `/media-use`, `/hyperframes-registry`, `/figma`) and the full capability map live inside `/hyperframes` — it is the single source of truth for which skill handles which intent. + +**Changing how real footage or images look or reveal?** Load `/media-use` and read its `references/media-treatments.md` before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” It governs how footage is treated, never whether media may be used. Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays. + +> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`. + +> **Skill missing or stale?** Run `npx hyperframes skills update ` to install/refresh +> the specific skill you need (the `/hyperframes` router does this automatically before +> entering a workflow), or bare `npx hyperframes skills update` to refresh the core set plus +> everything already installed — neither pulls the full set. Restart the agent session so +> newly installed skills load. + +## Commands + +```bash +npm run dev # start the preview server (long-running — keep it alive in background) +npm run check # lint + runtime + layout + motion + contrast (one command) +npm run render # render to MP4 +npm run publish # publish and get a shareable link +npx hyperframes lint --verbose # include info-level findings +npx hyperframes lint --json # machine-readable output for CI +npx hyperframes docs # reference docs in terminal +``` + +> **`npm run dev` is a long-running server, not a one-shot command.** It blocks until stopped. +> In Claude Code, always run it with `run_in_background: true`. Never run it as a foreground +> command — it will time out and the server will die, breaking the browser preview. + +> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. To move up: `npx hyperframes@latest upgrade --project . --check` (shows the delta), then `npx hyperframes@latest upgrade --project .` to rewrite the pins. Always unpinned — the pinned script re-runs the old version against itself. + +## Documentation + +**For quick reference**, use the local CLI docs command (no network required): + +```bash +npx hyperframes docs +``` + +Topics: `data-attributes`, `gsap`, `compositions`, `rendering`, `examples`, `troubleshooting` + +**For full documentation**, discover pages via the machine-readable index — do NOT guess URLs: + +``` +https://hyperframes.heygen.com/llms.txt +``` + +## Project Structure + +- `index.html` — main composition (root timeline) +- `compositions/` — sub-compositions referenced via `data-composition-src` +- `meta.json` — project metadata (id, name) +- `transcript.json` — whisper word-level transcript (if generated) + +## Linting — ALWAYS RUN AFTER CHANGES + +After creating or editing any `.html` composition, **always** run the full check before considering the task complete: + +```bash +npm run check +``` + +Fix all errors before presenting the result. Warnings should be reviewed before rendering. + +## Key Rules + +1. Every timed element needs `data-start`, `data-duration`, and `data-track-index` +2. Elements with timing **MUST** have `class="clip"` — the framework uses this for visibility control +3. Timelines must be paused and registered on `window.__timelines`: + ```js + window.__timelines = window.__timelines || {}; + window.__timelines["composition-id"] = gsap.timeline({ paused: true }); + ``` +4. Videos use `muted` with a separate `