npm - hyperframes - Versions diffs - 0.4.38 → 0.5.0-alpha.10 - Mend

hyperframes 0.4.38 → 0.5.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/dist/cli.js +765 -524
package/dist/skills/hyperframes/SKILL.md +29 -80
package/dist/skills/hyperframes/house-style.md +1 -3
package/dist/skills/hyperframes/references/motion-principles.md +0 -73
package/dist/skills/hyperframes/visual-styles.md +107 -339
package/dist/studio/assets/index-DKaNgV2Z.css +1 -0
package/dist/studio/assets/index-peNJzL-4.js +105 -0
package/dist/studio/index.html +2 -2
package/package.json +1 -1
package/dist/skills/hyperframes/references/beat-direction.md +0 -102
package/dist/skills/hyperframes/references/design-picker.md +0 -117
package/dist/skills/hyperframes/references/narration.md +0 -92
package/dist/skills/hyperframes/references/prompt-expansion.md +0 -68
package/dist/skills/hyperframes/references/techniques.md +0 -387
package/dist/skills/hyperframes/references/video-composition.md +0 -62
package/dist/skills/hyperframes/templates/design-picker.html +0 -1432
package/dist/studio/assets/index-18P_dZeo.js +0 -93
package/dist/studio/assets/index-BLrgRQSu.css +0 -1

package/dist/studio/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-18P_dZeo.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BLrgRQSu.css">
+    <script type="module" crossorigin src="/assets/index-peNJzL-4.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DKaNgV2Z.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.4.38",
+  "version": "0.5.0-alpha.10",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",

package/dist/skills/hyperframes/references/beat-direction.md DELETED Viewed

@@ -1,102 +0,0 @@
-# Beat Direction
-How to plan and direct individual scenes (beats) in a multi-scene composition. Read before writing any multi-scene video.
----
-## Per-Beat Direction
-Each beat is a WORLD, not a layout. Before writing CSS specs and GSAP instructions, describe what the viewer EXPERIENCES. The difference between a great storyboard and a mediocre one:
-**Mediocre:** "Dark navy background. '$1.9T' in white, 280px. Logo top-left. Wave image bottom-right."
-**Great:** "Camera is already mid-flight over a vast dark canvas. The gradient wave sweeps across the frame like aurora borealis — alive, shifting. '$1.9T' SLAMS into existence with such force the wave ripples in response. This isn't a slide — it's a moment."
-The first describes pixels. The second describes an experience. Write the second, then figure out the pixels.
-Each beat should have:
-### Concept
-The big idea for this beat in 2-3 sentences. What visual WORLD are we in? What metaphor drives it? What should the viewer FEEL? This is the most important part — everything else flows from it.
-### Mood direction
-Cultural and design references, not hex codes:
-- "Geometric, rhythmic, precise. Think Josef Albers or Bauhaus color studies."
-- "Warm workspace. Nice notebook energy, not technical blueprint."
-- "Cinematic title sequence. The kind of opening where you lean forward."
-### Animation choreography
-Specific motion verbs per element — not "it animates in" but HOW:
-| Energy        | Verbs                                         | Example                               |
-| ------------- | --------------------------------------------- | ------------------------------------- |
-| High impact   | SLAMS, CRASHES, PUNCHES, STAMPS, SHATTERS     | "$1.9T" SLAMS in from left at -5°     |
-| Medium energy | CASCADE, SLIDES, DROPS, FILLS, DRAWS          | Three cards CASCADE in staggered 0.3s |
-| Low energy    | types on, FLOATS, morphs, COUNTS UP, fades in | Counter COUNTS UP from 0 to 135K      |
-Every element gets a verb. If you can't name the verb, the element is not yet designed.
-### Transition
-How this beat hands off to the next. Specify the type and parameters.
-**When to pick which:**
-| Choose shader transition for                                                    | Choose CSS transition for                                                           | Choose hard cut for                                            |
-| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Reveals, big reaction shots, product/logo unveils, energy shifts, "wow" moments | Continuous camera-motion beats where the scene feels like one move broken into cuts | Rapid-fire lists, percussive edits on the beat, comedic timing |
-| Any moment the music/VO punctuates with a downbeat or SFX hit                   | Beats that ease from one composition into the next with shared motion vocabulary    | Sequences of 3+ quick tempo-matched switches                   |
-| Brand moments where the transition itself _is_ the visual                       | Minimal/editorial pacing                                                            | Anytime a 0.3-0.8s transition would feel too slow              |
-Rule of thumb: if the beat is the _centerpiece_ of the video, shader-transition into it. If the beat is connective tissue, CSS-transition. A brand reel of 5-7 beats usually wants 1-2 shader transitions (the hero reveal + the CTA) and the rest CSS or hard cuts — too many shader transitions flatten their impact.
-**CSS transitions** (choose from `skills/hyperframes/references/transitions/catalog.md`):
-- Velocity-matched upward: exit `y:-150, blur:30px, 0.33s power2.in` → entry `y:150→0, blur:30px→0, 1.0s power2.out`
-- Whip pan: exit `x:-400, blur:24px, 0.3s power3.in` → entry `x:400→0, blur:24px→0, 0.3s power3.out`
-- Blur through: exit `blur:20px, 0.3s` → entry `blur:20px→0, 0.25s power3.out`
-- Zoom through: exit `scale:1→1.2, blur:20px, 0.2s power3.in` → entry `scale:0.75→1, blur:20px→0, 0.5s expo.out`
-- Hard cut / smash cut (for rapid-fire sequences)
-**Shader transitions** (choose from `packages/shader-transitions/README.md`):
-- Cross-Warp Morph (organic, versatile) — 0.5-0.8s, power2.inOut
-- Cinematic Zoom (professional momentum) — 0.4-0.6s, power2.inOut
-- Gravitational Lens (otherworldly) — 0.6-1.0s, power2.inOut
-- Glitch (aggressive, high energy) — 0.3-0.5s
-- See `packages/shader-transitions/README.md` for the full API, available shaders, and setup
-### Depth layers
-What's in foreground, midground, and background. Every beat should have at least 2 layers:
-- "BG: dark navy fill + subtle radial glow. MG: stat cards with drop shadow. FG: brand logo bottom-right."
-### SFX cues
-What sounds at what moment:
-- "On the capture pulse — a soft, warm analog shutter click."
-- "Left side carries a faint low drone. On fold: drone cuts. Silence. Then a single clean chime."
----
-## Rhythm Planning
-Before writing HTML, declare your scene rhythm: which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern — fast-fast-SLOW-fast-SHADER-hold — before implementing.
-| Video type             | Typical rhythm pattern            |
-| ---------------------- | --------------------------------- |
-| Social ad (15s)        | hook-PUNCH-hold-CTA               |
-| Product demo (30-60s)  | slow-build-BUILD-PEAK-breathe-CTA |
-| Launch teaser (10-20s) | SLAM-proof-SLAM-hold              |
-| Brand reel (20-45s)    | drift-build-PEAK-drift-resolve    |
----
-## Velocity-Matched Transitions
-Exit the outgoing beat with an accelerating ease (power2.in or power3.in) plus a blur ramp. Enter the incoming beat with a decelerating ease (power2.out or power3.out) plus blur clear. The fastest point of both easing curves meets at the cut — the viewer perceives continuous camera motion, not two discrete animations. Match exit velocity to entry velocity within ~5% tolerance.

package/dist/skills/hyperframes/references/design-picker.md DELETED Viewed

@@ -1,117 +0,0 @@
-# Design Picker
-Two-phase visual picker: mood boards first (pick a complete direction), then fine-tune individual categories.
-## Prerequisites
-Read these before generating options — they define the rules your options must follow:
-- [typography.md](typography.md)
-- [../house-style.md](../house-style.md)
-- [video-composition.md](video-composition.md)
-- [../visual-styles.md](../visual-styles.md)
-- [beat-direction.md](beat-direction.md)
-## Building the picker
-1. Generate options **deeply contextual to the user's prompt**. Every category — not just architectures — must reflect the specific product, brand, audience, and mood. Generic options that could appear on any picker are a failure.
-   **Mood boards** — as many as the creative space warrants (4-8). Every board must tell a different STORY about the brand, not just reshuffle the same elements. Ask: "what are the genuinely different ways to position this product?" A cat food brand might be: playful chaos, premium positioning, comfort/cozy, social-native, flavor showcase, humor-led, sensory/appetizing. Each is a different narrative, not a different font on the same layout.
-   **Architectures** — one per mood board minimum, each visually distinct. Use `{{prompt_headline}}` and `{{prompt_sub}}` tokens. If the user provided media assets, use them as background images (use `url(path)` without quotes — single quotes inside `style='...'` break the attribute).
-   **Palettes** (5-6) — named after the brand's world, not generic moods. The palette names and colors should feel like they belong to THIS specific product. Always mix dark + light + tinted. **Every palette must be visually distinct at swatch size.** If two palettes share the same background lightness AND a similar accent hue, cut one. Test: would a user see the difference in a 14px swatch chip? If not, they're duplicates.
-   **Type pairings** (5-6) — **RUN the font discovery script from typography.md BEFORE generating pairings.** This is not optional. Download Google Fonts metadata, run the script, and pick from its output. You will otherwise reach for the same 8 fonts every time (Bricolage Grotesque, Instrument Serif, Fraunces, Archivo Black, DM Serif Display, Space Grotesk, Fredoka) — that's your training data default, not a contextual choice. Match the brand's energy and audience. Cross-category per typography.md (never two sans-serifs).
-2. `mkdir -p .hyperframes` then copy [../templates/design-picker.html](../templates/design-picker.html) to `.hyperframes/pick-design.html`.
-3. Replace these placeholders using Python (don't hand-escape quotes in sed):
-   - `__ARCHITECTURES_JSON__` — array of architecture objects
-   - `__PALETTES_JSON__` — array of palette objects
-   - `__TYPEPAIRS_JSON__` — array of type pairing objects
-   - `__MOODBOARDS_JSON__` — array of mood board objects (see format below)
-   - `__PROMPT_JSON__` — object with prompt context (see format below)
-### Architecture data format
-Each architecture object must include a `preview_html` field — the HTML that renders in the preview panel. Use token placeholders that the template replaces at runtime: `{{bg}}`, `{{fg}}`, `{{ac}}`, `{{mt}}`, `{{hf}}`, `{{hw}}`, `{{bf}}`, `{{bw}}`, `{{cr}}` (corner radius), `{{pad}}`, `{{gap}}`, `{{shadow}}`, `{{g}}` (grid line color), `{{fg3}}`/`{{fg6}}`/`{{fg8}}`/`{{fg15}}` (fg at opacity), `{{ac3}}`/`{{ac5}}`/`{{ac25}}` (accent at opacity).
-**Every token must be used.** Apply `{{cr}}` to all cards, buttons, and containers. Apply `{{shadow}}` to elevated elements (cards, buttons, code blocks). Apply `{{pad}}` and `{{gap}}` to control spacing. If a token isn't used in the preview_html, that option will have no visible effect.
-**Density matters.** Each architecture preview must include 15+ distinct elements to give the user a real sense of the layout. Include: headline, subhead, body paragraph, label/overline, stat with number, secondary stat, quote/testimonial, attribution, card with title+body, second card (different treatment), code/command block, primary button, secondary button, list or tags, accent divider/rule, and a data element (table row, progress bar, or chart).
-Optionally include `components` (component styling rules) and `dos` (do's and don'ts) as strings — these appear in the generated design.md.
-**Layout constraint:** All preview HTML must use percentage widths or `max-width: 100%`. Use `flex-wrap: wrap` on all flex rows. Absolute-positioned decoratives must stay within a parent with `overflow: hidden`.
-**Security:** Architecture `preview_html` must not contain `<script>` tags, event handlers (`onclick`, `onerror`, etc.), or `javascript:` URLs. It is injected via `innerHTML`.
-**Image URLs:** When using background images in `preview_html`, use `url(path/to/image.jpg)` WITHOUT quotes around the path. Single quotes like `url('path.jpg')` break because `preview_html` is inside a `style='...'` attribute — the inner single quotes terminate the outer attribute.
-**Palette variety:** Always include a mix of light, dark, and tinted backgrounds across the 6 palettes — even for calm/wellness prompts.
-### Example architecture object
-```json
-{
-  "name": "Editorial Stack",
-  "description": "Vertical rhythm with large type, pull quotes, and data callouts",
-  "tag": "editorial / longform / narrative",
-  "mood": "Confident, unhurried, typographically driven",
-  "preview_html": "<div style='background:{{bg}};color:{{fg}};padding:{{pad}};min-height:100vh;font-family:\"{{bf}}\",sans-serif;font-weight:{{bw}};'><div style='max-width:100%;display:flex;flex-direction:column;gap:{{gap}};'><div style='font-size:10px;text-transform:uppercase;letter-spacing:0.12em;color:{{mt}};'>Overline Label</div><div style='font-family:\"{{hf}}\",serif;font-weight:{{hw}};font-size:48px;line-height:1.1;letter-spacing:-0.02em;'>The Headline Goes Here</div><div style='font-size:20px;color:{{mt}};max-width:70%;line-height:1.5;'>Subheading text that introduces the narrative arc of this composition with enough words to fill two lines.</div><div style='font-size:15px;line-height:1.7;color:{{fg}};max-width:65%;'>Body paragraph with real sentences. The quick brown fox jumps over the lazy dog. This gives a sense of text density and reading rhythm at the chosen type size.</div><div style='display:flex;gap:{{gap}};flex-wrap:wrap;'><div style='background:{{fg6}};border-radius:{{cr}};padding:{{pad}};flex:1;min-width:200px;box-shadow:{{shadow}};'><div style='font-size:36px;font-family:\"{{hf}}\",serif;font-weight:{{hw}};color:{{ac}};'>2.4M</div><div style='font-size:12px;color:{{mt}};margin-top:4px;'>Primary Stat</div></div><div style='background:{{fg6}};border-radius:{{cr}};padding:{{pad}};flex:1;min-width:200px;box-shadow:{{shadow}};'><div style='font-size:36px;font-family:\"{{hf}}\",serif;font-weight:{{hw}};color:{{fg}};'>87%</div><div style='font-size:12px;color:{{mt}};margin-top:4px;'>Secondary Stat</div></div></div><div style='border-left:3px solid {{ac}};padding:12px {{pad}};background:{{ac3}};border-radius:0 {{cr}} {{cr}} 0;'><div style='font-size:18px;font-style:italic;color:{{fg}};line-height:1.5;'>\"A pull quote that captures the key insight of the piece.\"</div><div style='font-size:12px;color:{{mt}};margin-top:8px;'>— Attribution Name</div></div><div style='background:{{fg3}};border-radius:{{cr}};padding:{{pad}};box-shadow:{{shadow}};'><div style='font-size:14px;font-weight:{{hw}};margin-bottom:8px;'>Card Title</div><div style='font-size:13px;color:{{mt}};line-height:1.5;'>Card body text with a different treatment than the main content area.</div></div><div style='background:{{ac5}};border:1px solid {{ac25}};border-radius:{{cr}};padding:{{pad}};box-shadow:{{shadow}};'><div style='font-size:14px;font-weight:{{hw}};color:{{ac}};margin-bottom:8px;'>Accent Card</div><div style='font-size:13px;color:{{fg}};line-height:1.5;'>Second card with a tinted accent treatment for variety.</div></div><div style='font-family:monospace;font-size:13px;background:{{fg8}};border-radius:{{cr}};padding:{{pad}};color:{{fg15}};box-shadow:{{shadow}};'>$ hyperframes render --output video.mp4</div><div style='display:flex;gap:12px;flex-wrap:wrap;'><button style='background:{{ac}};color:{{bg}};border:none;padding:10px 24px;border-radius:{{cr}};font-size:14px;font-weight:600;box-shadow:{{shadow}};cursor:pointer;'>Primary Action</button><button style='background:transparent;color:{{fg}};border:1px solid {{fg15}};padding:10px 24px;border-radius:{{cr}};font-size:14px;cursor:pointer;'>Secondary</button></div><div style='display:flex;gap:8px;flex-wrap:wrap;'><span style='background:{{fg6}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{mt}};'>Tag One</span><span style='background:{{fg6}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{mt}};'>Tag Two</span><span style='background:{{ac5}};border-radius:100px;padding:4px 12px;font-size:11px;color:{{ac}};'>Accent Tag</span></div><div style='height:1px;background:linear-gradient(to right,{{ac25}},{{fg6}},{{ac25}});'></div><div style='display:flex;justify-content:space-between;font-size:12px;color:{{mt}};border-bottom:1px solid {{g}};padding:8px 0;'><span>Data row label</span><span style='color:{{fg}};font-weight:600;'>1,234</span></div></div></div>"
-}
-```
-### Mood board data format
-Each mood board pre-selects one option from each category. The user picks a mood board in Phase 1, then fine-tunes in Phase 2 with those selections pre-filled.
-```json
-{
-  "name": "Terminal Precision",
-  "description": "Code-forward, data-dense, CLI energy. Dark canvas, monospace body, sharp corners.",
-  "theme": "dark",
-  "arch_index": 0,
-  "palette_index": 0,
-  "type_index": 0,
-  "corners_index": 0,
-  "density_index": 0,
-  "depth_index": 1,
-  "easing_index": 0,
-  "corners": "0px",
-  "padding": "12px",
-  "gap": "8px",
-  "shadow": "0 2px 16px rgba(0,230,255,0.15)"
-}
-```
-Indices reference into the ARCHITECTURES, PALETTES, and TYPEPAIRS arrays. The template renders a mini preview of each mood board using its architecture's `preview_html` with the mood board's palette/type applied.
-### Prompt context data format
-```json
-{
-  "title": "AI Coding Assistant",
-  "headline": "Your Code, Understood.",
-  "subline": "An AI coding assistant that reads your entire codebase.",
-  "section_desc": "Layout options for your product launch"
-}
-```
-`title` appears in the Phase 1 header. `headline` and `subline` replace `{{prompt_headline}}` and `{{prompt_sub}}` in architecture preview_html so previews show real content.
-### Content tokens in preview_html
-In addition to the standard design tokens (`{{bg}}`, `{{fg}}`, `{{ac}}`, etc.), architecture `preview_html` can use:
-- `{{prompt_headline}}` — the user's actual headline text
-- `{{prompt_sub}}` — the user's actual subline text
-This makes previews contextual — the user sees their own content styled, not generic placeholders.
-## Serving and user selection
-4. Serve the file: `cd <project-dir> && python3 -m http.server 8723 &` (use port 8723 or any unused port above 8000; if the curl check fails, try the next port). Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8723/.hyperframes/pick-design.html` — only share the link if it returns 200. Do NOT use `npx hyperframes preview` for the picker — it blocks. Only start the HTTP server from the main conversation thread. If you are running as a dispatched task or subagent, return the file path and let the caller serve it.
-5. Once the user picks, tell them: "Copy the design.md from the picker and paste it here." The user pastes the markdown back into the conversation. Save it verbatim to `design.md` in the project root — it's already in spec format (YAML frontmatter + prose sections). After the user pastes, kill the background server: `kill %1` or `kill $(lsof -ti:8723)`. Then proceed with construction.
-The picker outputs a [google-labs-code/design.md](https://github.com/google-labs-code/design.md) spec-compliant file: YAML frontmatter with `colors`, `typography`, `rounded`, and `spacing` tokens, followed by `## Overview`, `## Colors`, `## Typography`, `## Layout`, `## Elevation`, `## Components`, and `## Do's and Don'ts` prose sections.

package/dist/skills/hyperframes/references/narration.md DELETED Viewed

@@ -1,92 +0,0 @@
-# Narration & Script
-How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS.
-## Pacing
-- **2.5 words per second** is natural speaking pace
-- 15s = ~37 words. 30s = ~75 words. 60s = ~150 words
-- Leave room for pauses. Silence between sentences is a feature, not dead air
-- The script should feel SHORTER than the video — visual breathing room matters
-## Tone
-Write like a person, not a brochure:
-- Use contractions: "it's", "you'll", "that's", "we've"
-- Vary sentence length — short punchy phrases mixed with longer flowing ones
-- Read it out loud. If it sounds robotic, rewrite it
-- Avoid jargon unless the audience expects it
-## Number Pronunciation
-Write what you want the voice to say. TTS reads literally.
-| In the product | Write in script as                |
-| -------------- | --------------------------------- |
-| 135+           | more than one hundred thirty five |
-| $1.9T          | nearly two trillion dollars       |
-| 99.999%        | ninety nine point nine percent    |
-| 200M+          | over two hundred million          |
-| 10x            | ten times                         |
-| API            | A P I                             |
-| stripe.com     | stripe dot com                    |
-The visual can show the exact figure while the voice rounds it.
-## Structure
-For product videos:
-1. **Hook** — what's surprising or impressive about this product? A bold claim, a provocative question, a contrast, or a striking number. This is the opening line. **Vary the hook type** — don't default to a stat every time.
-2. **Story** — what does the product do? Who uses it? Keep it concrete.
-3. **Proof** — stats, customer names, social proof. Real numbers from the product.
-4. **CTA** — what should the viewer do? "Start building at stripe dot com."
-Not every video needs all four. A 15-second social ad might be Hook + Proof + CTA. A 60-second product tour uses all four with more Story.
-## The Opening Line
-The most important sentence in the video. It must create tension, curiosity, or surprise in the first 3 seconds.
-Patterns that work:
-- **A bold claim**: "The financial infrastructure that powers the internet economy."
-- **A question that provokes**: "What if your database could think?"
-- **A contrast**: "Your AI agent already knows how to make videos. It just needs the right format."
-- **A number that shocks**: "Nearly two trillion dollars." (Use sparingly — not every video should open with a stat.)
-If the opening is generic ("Welcome to Stripe" / "Introducing our product"), start over.
-## Example
-From a 62-second product launch video (team reference):
-```
-Your AI agent already knows how to make videos.
-It just needs the right format.
-This is Hyperframes. An open source framework. HTML in, video out.
-A div is a keyframe. Data attributes are your timeline.
-CSS is your look. G-Sap is your animation engine.
-Anything a browser can render can be a frame in your video.
-CSS animations. G-Sap. Lottie. Shaders. Three.js.
-Drop in music, sound effects, footage — it all composes together.
-No new framework for the agent to learn.
-Just HTML.
-The agent writes it. The renderer captures every frame as MP4.
-It's deterministic. Identical outputs, every time.
-Give your agent the CLI. Tell it what to make.
-Watch it build.
-Hyperframes. Go make something.
-```
-Note: ~140 words for 62 seconds — that's 2.3 words/sec, leaving room for pauses and visual breathing.

package/dist/skills/hyperframes/references/prompt-expansion.md DELETED Viewed

@@ -1,68 +0,0 @@
-# Prompt Expansion
-Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against `design.md` and `house-style.md` and producing a consistent intermediate that every downstream agent reads the same way.
-Runs AFTER design direction is established (Step 1). The expansion consumes design.md (if present) and produces output that cites its exact values.
-## Prerequisites
-Read before generating:
-- `design.md` (if it exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
-- [beat-direction.md](beat-direction.md) — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
-- [video-composition.md](video-composition.md) — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
-- [../house-style.md](../house-style.md) — its rules for Background Layer (2-5 decoratives), Color, Motion, Typography apply to every scene. The expansion writes output that conforms to them.
-If `design.md` doesn't exist yet, run Step 1 (Design system) first. Expansion without a design context produces generic scene breakdowns that later agents ignore.
-## Why always run it
-**The expansion is never pass-through.** Every user prompt — no matter how detailed — is a _seed_. The expansion's job is to enrich it into a fully-realized per-scene production spec that the scene subagents can build from directly.
-Even a detailed 7-scene brief lacks things only the expansion adds:
-- **Atmosphere layers per scene** (required 2–5 from house-style: radial glows, ghost type, hairline rules, grain, thematic decoratives) — the user's prompt almost never lists these; expansion adds them.
-- **Secondary motion for every decorative** — breath, drift, pulse, orbit. A decorative without ambient motion feels dead.
-- **Micro-details that make a scene feel real** — registration marks, tick indicators, monospace coord labels, typographic accents, code snippets in the background, grid patterns. Things the user didn't think to request.
-- **Transition choreography at the object level** — not "crossfade" but "X expands outward and becomes Y". Specific duration, ease, and morph source/target.
-- **Pacing beats within each scene** — where tension builds, where a hold lets the viewer breathe, where the accent word lands.
-- **Exact hex values, typography parameters, ease choices** from design.md — no vagueness left for the scene subagent to guess.
-Expansion's job on a detailed prompt is not to summarize or pass through — it's to **take what the user wrote and make it richer**. The user's content stays; the atmosphere, ambient motion, and micro-details are added on top. That's what makes the difference between a scene that matches the brief and a scene that feels alive.
-The quality gap between a single-pass composition and a multi-scene-pipeline composition comes from this step. Expansion front-loads the richness so every scene subagent builds from a rich brief, not a terse one.
-**Do not skip. Do not pass through.** Single-scene compositions and trivial edits are the only exceptions.
-## What to generate
-Expand into a full production prompt with these sections:
-1. **Title + style block** — cite design.md's exact hex values, font names, and mood. Do NOT invent a palette — quote what the design provides.
-2. **Rhythm declaration** — name the scene rhythm before detailing any scene. Example: `hook-PUNCH-breathe-CTA` or `slow-build-BUILD-PEAK-breathe-CTA`. See [beat-direction.md](beat-direction.md) for rhythm templates by video type.
-3. **Global rules** — parallax layers, micro-motion requirements, transition style, primary + accent transitions. Match energy to mood (calm → slow eases, high → snappy eases).
-4. **Per-scene beats** — for each scene, use the beat-direction format:
-   - **Concept** — the big idea in 2-3 sentences. What visual WORLD? What metaphor? What should the viewer FEEL?
-   - **Mood direction** — cultural/design references, not hex codes. ("Bauhaus color studies", "cinematic title sequence", "editorial calm")
-   - **Depth layers** — BG (2-5 decoratives with ambient motion), MG (content), FG (accents, structural elements, micro-details). 8-10 total elements per scene per video-composition.md.
-   - **Animation choreography** — specific verbs per element. High: SLAMS, CRASHES. Medium: CASCADE, SLIDES. Low: floats, types on, counts up. Every element gets a verb. If you can't name the verb, the element is not yet designed.
-   - **Transition out** — shader or CSS, with specific type and parameters. Not "crossfade" but "blur crossfade, 0.4s, power2.inOut."
-5. **Recurring motifs** — visual threads across scenes from the brand palette.
-6. **Negative prompt** — what to avoid, informed by design.md's constraints if present.
-## Output
-Write the expanded prompt to `.hyperframes/expanded-prompt.md` in the project directory. Do NOT dump it into the chat — it will be hundreds of lines.
-Tell the user:
-> "I've expanded your prompt into a full production breakdown. Review it here: `.hyperframes/expanded-prompt.md`
->
-> It has [N] scenes across [duration] seconds with specific visual elements, transitions, and pacing. Edit anything you want, then let me know when you're ready to proceed."
-Only move to construction after the user approves or says to continue.