dsh-hyperframes 0.1.1 → 0.3.0

package/skills/hyperframes-creative/references/motion-principles.md

@@ -0,0 +1,151 @@
+# Motion Principles
+
+## Contents
+
+- Guardrails
+- What you do not do without being told
+- Visual composition
+- Image motion treatment
+- Load-bearing GSAP rules
+
+## Guardrails
+
+You know these rules but you violate them. Stop.
+
+- **Don't use the same ease on every tween.** You default to `power2.out` on everything. Vary eases like you vary font weights — no more than 2 independent tweens with the same ease in a scene.
+- **Don't use the same speed on everything.** You default to 0.4-0.5s for everything. The slowest scene should be 3× slower than the fastest. Vary duration deliberately.
+- **Don't enter everything from the same direction.** You default to `y: 30, opacity: 0` on every element. Vary: from left, from right, from scale, opacity-only, letter-spacing.
+- **Don't use the same stagger on every scene.** Each scene needs its own rhythm.
+- **Don't use ambient zoom on every scene.** Pick different ambient motion per scene: slow pan, subtle rotation, scale push, color shift, or nothing. Stillness after motion is powerful.
+- **Don't start at t=0.** Offset the first animation 0.1-0.3s. Zero-delay feels like a jump cut.
+
+## What You Don't Do Without Being Told
+
+### Easing is emotion, not technique
+
+The transition is the verb. The easing is the adverb. A slide-in with `expo.out` = confident. With `sine.inOut` = dreamy. With `elastic.out` = playful. Same motion, different meaning. Choose the adverb deliberately.
+
+**Direction rules — these are not optional:**
+
+- `.out` for elements entering. Starts fast, decelerates. Feels responsive. This is your default.
+- `.in` for elements leaving. Starts slow, accelerates away. Throws them off.
+- `.inOut` for elements moving between positions.
+
+You get this backwards constantly. Ease-in for entrances feels sluggish. Ease-out for exits feels reluctant.
+
+### Speed communicates weight
+
+- Fast (0.15-0.3s) — energy, urgency, confidence
+- Medium (0.3-0.5s) — professional, most content
+- Slow (0.5-0.8s) — gravity, luxury, contemplation
+- Very slow (0.8-2.0s) — cinematic, emotional, atmospheric
+
+### Scene structure: build / breathe / resolve
+
+Every scene has three phases. You dump everything in the build and leave nothing for breathe or resolve.
+
+- **Build (0-30%)** — elements enter, staggered. Don't dump everything at once.
+- **Breathe (30-70%)** — content visible, alive with ONE ambient motion.
+- **Resolve (70-100%)** — exit or decisive end. Exits are faster than entrances.
+
+### Transitions are meaning
+
+- **Crossfade** = "this continues"
+- **Hard cut** = "wake up" / disruption
+- **Slow dissolve** = "drift with me"
+
+You crossfade everything. Use hard cuts for disruption and register shifts.
+
+### Choreography is hierarchy
+
+The element that moves first is perceived as most important. Stagger in order of importance, not DOM order. Don't wait for completion — overlap entries. Total stagger sequence under 500ms regardless of item count.
+
+### Asymmetry
+
+Entrances need longer than exits. A card takes 0.4s to appear but 0.25s to disappear.
+
+## Visual Composition
+
+You build for the web. Video frames are not pages.
+
+- **Two focal points minimum per scene.** The eye needs somewhere to travel. Never a single text block floating in empty space.
+- **Fill the frame.** Hero text: 60-80% of width. You will try to use web-sized elements. Don't.
+- **Three layers minimum per scene.** Background treatment (glow, oversized faded type, color panel). Foreground content. Accent elements (dividers, labels, data bars).
+- **Background is not empty.** Radial glows, oversized faded type bleeding off-frame, subtle border panels, hairline rules. Pure solid #000 reads as "nothing loaded."
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web pattern.
+- **Split frames.** Data panel on the left, content on the right. Top bar with metadata, full-width below. Zone-based layouts, not centered stacks.
+- **Use structural elements.** Rules, dividers, border panels. They create paths for the eye and animate well (scaleX from 0).
+- **Connector lines earn their place.** Any beam, rail, scan line, or drawn underline must be able to name its start anchor, its end anchor (real elements, not empty space), and its job — revealing, routing, validating, or emphasizing something. A line the frame can lose without losing meaning is decoration: cut it. An edge-lit component (a card's top highlight, a state dot) usually reads as more designed than a free-floating arc.
+
+## Image Motion Treatment
+
+Never embed a raw flat image. Every image must have motion treatment:
+
+- **Perspective tilt**: use `gsap.set(el, { transformPerspective: 1200, rotationY: -8 })` + `box-shadow` — creates depth. Do NOT use CSS `transform: perspective(...)` as GSAP will overwrite it.
+- **Slow zoom (Ken Burns)**: GSAP `scale: 1` → `1.04` over beat duration — makes photos cinematic
+- **Device frame**: Wrap in a laptop/phone shape using CSS `border-radius` and `box-shadow`
+- **Floating UI**: Extract a key element and animate it at a different z-depth for parallax
+- **Scroll reveal**: Clip the image to a viewport window and animate `y` position
+
+## Load-Bearing GSAP Rules
+
+Rules below came out of two independent website capture builds (2026-04-20) where compositions lint-clean and still ship broken — elements that never appear, ambient motion that doesn't scrub, entrance tweens that silently kill their target. The linter cannot catch these; the rules must be followed by the author.
+
+- **No iframes for captured content.** Iframes do not seek deterministically with the timeline — the capture engine cannot scrub inside them, so they appear frozen (or blank) in the rendered output. If the source you're stylizing is a live web app, use the screenshots from `capture/` as stacked panels or layered images, not live embeds.
+
+- **Never overlap conflicting transform tweens on the same element.** Sequential, non-overlapping transform phases are valid. The dangerous case is concurrent tweens or `from()` tweens whose `immediateRender` states overwrite one another: for example, a `y` entrance plus a simultaneous `scale` Ken Burns tween on the same `<img>`. The element can remain invisible or offscreen with no lint warning. Fix the overlap in one of two ways:
+
+  ```html
+  <!-- BAD: two transforms on one element -->
+  <img class="hero" src="..." />
+  <script>
+    tl.from(".hero", { y: 50, opacity: 0, duration: 0.6 }, 0);
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // kills the entrance
+  </script>
+
+  <!-- GOOD option A: combine into one tween -->
+  <script>
+    tl.fromTo(
+      ".hero",
+      { y: 50, opacity: 0, scale: 1.0 },
+      { y: 0, opacity: 1, scale: 1.04, duration: beat, ease: "none" },
+      0,
+    );
+  </script>
+
+  <!-- GOOD option B: split across parent + child -->
+  <div class="hero-wrap"><img class="hero" src="..." /></div>
+  <script>
+    tl.fromTo(".hero-wrap", { y: 50, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6 }, 0); // entrance on parent
+    tl.to(".hero", { scale: 1.04, duration: beat }, 0); // Ken Burns on child
+  </script>
+  ```
+
+- **Prefer `tl.fromTo()` over `tl.from()` inside `.clip` scenes.** `gsap.from()` sets `immediateRender: true` by default, which writes the "from" state at timeline construction — before the `.clip` scene's `data-start` is active. Elements can flash visible, start from the wrong position, or skip their entrance entirely when the scene is seeked non-linearly (which the capture engine does). Explicit `fromTo` makes the state at every timeline position deterministic:
+
+  ```js
+  // BRITTLE: immediateRender interacts badly with scene boundaries
+  tl.from(el, { opacity: 0, y: 50, duration: 0.6 }, t);
+
+  // DETERMINISTIC: state is defined at both ends, no immediateRender surprise
+  tl.fromTo(el, { opacity: 0, y: 50 }, { opacity: 1, y: 0, duration: 0.6 }, t);
+  ```
+
+- **Ambient pulses must attach to the seekable `tl`, never bare `gsap.to()`.** Auras, shimmers, gentle float loops, logo breathing — all of these must be added to the scene's timeline, not fired standalone. Standalone tweens run on wallclock time and do not scrub with the capture engine, so the effect is absent in the rendered video even though it looks correct in the studio preview:
+
+  ```js
+  // BAD: lives outside the timeline, never renders in capture
+  gsap.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 });
+
+  // GOOD: seekable, deterministic, renders
+  tl.to(".aura", { scale: 1.08, yoyo: true, repeat: 5, duration: 1.2 }, 0);
+  ```
+
+- **Hard-kill exiting inner elements at a scene boundary, not the `.clip` itself.** A non-clip element or wrapper whose visibility changes at a beat boundary may need a deterministic zero-duration `tl.set()` kill after its fade, because a later tween or sibling `immediateRender` can resurrect it. This is the explicit-boundary exception to the ban on raw `visibility` tweens. HyperFrames alone controls `.clip` lifecycle; never apply this pattern to the clip container.
+
+  ```js
+  tl.to(innerEl, { opacity: 0, duration: 0.3 }, beatEnd);
+  tl.set(innerEl, { opacity: 0, visibility: "hidden" }, beatEnd + 0.3); // non-clip kill
+  ```
+
+These are the exact rules with the exact code examples — don't summarize or shorten them. They exist because compositions that lint clean still ship broken without them.

package/skills/{website-to-hyperframes/references/step-3-script.md → hyperframes-creative/references/narration.md}

@@ -1,10 +1,6 @@
-# Step 3: Write the Narration Script
+# Narration & Script
 
-**Before writing, re-read DESIGN.md** — specifically the Overview and Components sections. The script should reference real product features, real stats, and real components that the website highlights. Use exact numbers from `capture/extracted/visible-text.txt`.
-
-The script is the backbone. Everything downstream — scene durations, animation timing, beat pacing — comes from the narration. Write it before the storyboard.
-
-Save as `SCRIPT.md` in the project directory.
+How to write narration scripts for video compositions. Read when the composition includes voiceover or TTS.
 
 ## Pacing
 
@@ -26,7 +22,7 @@ Write like a person, not a brochure:
 
 Write what you want the voice to say. TTS reads literally.
 
-| On the website | Write in script as                |
+| In the product | Write in script as                |
 | -------------- | --------------------------------- |
 | 135+           | more than one hundred thirty five |
 | $1.9T          | nearly two trillion dollars       |
@@ -40,11 +36,11 @@ The visual can show the exact figure while the voice rounds it.
 
 ## Structure
 
-For product videos from a website capture:
+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 website.
+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.

package/skills/hyperframes-creative/references/prompt-expansion.md

@@ -0,0 +1,68 @@
+# Prompt Expansion
+
+Run on every composition. Expansion is not about lengthening a short prompt — it's about grounding the user's intent against the design spec (`frame.md` or `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 the design spec (`frame.md` or `design.md`, if present) and produces output that cites its exact values.
+
+## Prerequisites
+
+Read before generating:
+
+- the design spec — `frame.md` → `design.md` → `DESIGN.md` (read the first that exists) — extract brand colors, fonts, mood, and constraints. The expansion cites these exact values (hex codes, font names); it does not invent new ones.
+- `references/beat-direction.md` — per-beat planning format (concept, mood, choreography verbs, transitions, depth layers, rhythm). The expansion outputs each scene using this format.
+- `references/video-composition.md` — video-medium rules for density, scale, and color presence. The expansion applies these automatically.
+- `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 no design spec (`frame.md` or `design.md`) exists 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 the design spec — 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 the design spec'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`. Use `references/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 treatment, MG content, and FG accents or structural details as the concept needs. Use `video-composition.md` to choose density; do not force an element count or invent content to fill one.
+   - **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 the design spec'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.

package/skills/hyperframes-creative/references/story-spine.md

@@ -0,0 +1,43 @@
+# Story spine — value-first narrative doctrine
+
+Applies to the narrated, story-driven creation workflows — `/product-launch-video`, `/pr-to-video`, `/faceless-explainer`, and `/general-video` when the piece tells a story. It does **not** apply to `/music-to-video` (the track drives the arc), `/motion-graphics` (no narration — motion is the message), `/embedded-captions` and `/talking-head-recut` (the footage's story is already fixed), or `/slideshow` (the presenter owns the story). Do not force these rules onto an exempt workflow.
+
+Each workflow's own story-design reference owns its archetypes, beat sequences, and frame vocabulary. This file owns four cross-workflow rules about **order** and **justification** — the reverse iceberg: lead with why it's valuable, not with what it is or how it was made.
+
+## 1. The hook speaks the viewer's language
+
+The first beat answers "why should I care" in **outcome language** — what the viewer gains, avoids, or finally understands. Subject-internal vocabulary is banned in the hook: file / function / API names for a code change; a feature list for a product; the source article's section headings for an explainer. Numbers are welcome only when they carry stakes ("40% faster cold starts"), never inventory ("23 files changed").
+
+## 2. Reverse iceberg — value before evidence
+
+The value claim (the brief's `message`) lands **by the second beat**. Everything after it is evidence in service of that claim — the diff, the mechanism, the feature demo, the site's screenshots. Implementation is the footnote of the story, not the spine.
+
+Self-check on the finished beat list:
+
+- Delete every evidence beat — the remaining beats must still state the value on their own.
+- Delete the value beats — if the video still seems to work, it was a feature tour / diff readout, not a story.
+
+Structure is value-first; the **voice** stays whatever the workflow prescribes (a PR video keeps its plain, no-hype developer voice — leading with value is an ordering decision, not a marketing register).
+
+## 3. The storyboard is a proposal, not a listing
+
+When Step 3 presents the plan (a checkpoint gate — `hyperframes-core/references/brief-contract.md` § 1):
+
+- Open by echoing the strategy line: **"This video tells [audience] that [message]."**
+- Present the frames as a markdown table, one row per frame:
+
+  | Frame            | Beat      | On screen                                               | Why                             |
+  | ---------------- | --------- | ------------------------------------------------------- | ------------------------------- |
+  | 01 — Not anymore | hook · 9s | States the old pain and resolves it in the same breath. | Lands the value claim in beat 1 |
+
+  **Why** is the frame's job in the story (from its `narrativeRole`), traced back to the message — a frame whose why cannot be traced to the message is a frame to cut, not to decorate.
+
+- Recommendations keep their receipts (brief-contract § 3): the archetype choice, the beat count, and any beat the user might question each state their basis.
+
+The proposal shape — echo line → frame table → style / duration footer → "approve or adjust" — is the cheapest place to iterate: a frame change here costs 30 seconds; the same change after build costs minutes.
+
+## 4. Visuals point back to the source
+
+When the piece derives from concrete source material — a PR, a repo, an article, a product page — mine that material for the visual vocabulary before inventing any: its phrases, entities, verbs, and recurring motifs are the props. Each frame's key visual should be traceable to a specific line of the source, the same way its **Why** traces to the message: real filenames over generic file icons, the product's own numbers over invented ones, the article's own metaphor over a stock one.
+
+Self-check per visual: if the prop could appear unchanged in another product's video, it didn't come from the source. Swap it for something only this subject could produce before decorating it.

package/skills/{hyperframes → hyperframes-creative}/references/typography.md

@@ -1,6 +1,49 @@
 # Typography
 
-The compiler embeds supported fonts — just write `font-family` in CSS.
+The compiler **pre-bundles a fixed set** of fonts (the table below) — write one of those families in `font-family` and it renders deterministically, offline, with no setup and no warning. A name _outside_ that set is **not silently dropped**: if it's a real Google font the compiler fetches it from Google Fonts at **build time** and embeds it, so it _does_ render — but that implicit path (a) trips a `font_family_without_font_face` lint warning, and (b) is **fail-closed in distributed/cloud renders** — if Google is unreachable the render _errors_ rather than quietly substituting a system font. Beyond that, **local renders auto-capture fonts you actually have**: a family installed on your machine, a local `@font-face` path, or an external CDN stylesheet all get compressed to woff2 and inlined at build time. So a name on **neither** the bundle **nor** Google Fonts only truly falls back to a generic system font when it's _also_ not installed locally and not declared in an `@font-face` — and even that logs a compiler warning. **One caveat**: distributed/cloud (Lambda) renders disable system-font capture, so don't rely on a locally-installed-only font for those. So don't assume an un-bundled display name will Just Work: for anything that must render predictably, pick a bundled family below **or embed your own `@font-face`** (see "Finding Fonts").
+
+## Contents
+
+- Fonts that embed (auto-resolve)
+- Banned fonts
+- Guardrails
+- What you do not do without being told
+- Finding fonts
+- Selection thinking
+- Similar-font pairing
+- Dark backgrounds
+- OpenType features for data
+
+## Fonts That Embed (auto-resolve)
+
+These **18 families** are the ones the renderer **pre-bundles** — embedded as local data URIs with no network fetch, so they render offline and deterministically with zero setup, no lint warning, and no fail-closed fetch risk. Write any of them as a `font-family` and it renders; **only the listed weights exist** (asking for a weight a family doesn't ship gives a synthetic/fallback weight, not a real cut). (Any _other_ real Google font still works via the implicit build-time fetch described in the intro — but only these render with none of those caveats.)
+
+| Family            | Weights         | Role              |
+| ----------------- | --------------- | ----------------- |
+| Inter             | 400 · 700 · 900 | sans (body/UI)    |
+| Roboto            | 400 · 700 · 900 | sans              |
+| Open Sans         | 400 · 700       | sans              |
+| Lato              | 400 · 700 · 900 | sans              |
+| Nunito            | 400 · 700 · 900 | sans (rounded)    |
+| Montserrat        | 400 · 700 · 900 | geometric sans    |
+| Poppins           | 400 · 700 · 900 | geometric sans    |
+| Outfit            | 400 · 700 · 900 | geometric sans    |
+| Oswald            | 400 · 700       | condensed sans    |
+| **League Gothic** | **400 only**    | condensed display |
+| **Archivo Black** | **400 only**    | heavy display     |
+| Playfair Display  | 400 · 700 · 900 | serif (display)   |
+| EB Garamond       | 400 · 700       | serif (text)      |
+| Space Mono        | 400 · 700       | mono              |
+| IBM Plex Mono     | 400 · 700       | mono              |
+| JetBrains Mono    | 400 · 700       | mono              |
+| Source Code Pro   | 400 · 700       | mono              |
+| Noto Sans JP      | 400 · 700       | CJK (Japanese)    |
+
+> ⚠ **League Gothic and Archivo Black ship weight 400 ONLY** — they are already heavy/condensed display faces. Do not request `font-weight: 700/900` on them.
+
+**Aliases** — these common names resolve to an embedded family, so you may safely write them: `Helvetica Neue` / `Helvetica` / `Arial` → Inter · `Futura` / `DIN Alternate` / `Arial Black` → Montserrat · `Bebas Neue` → League Gothic · `Segoe UI` → Roboto · `Courier New` / `Courier` → JetBrains Mono · `Garamond` → EB Garamond. (This is why a "safe" `Helvetica Neue` stack always renders — it maps to embedded Inter.)
+
+**Reconciling with the Banned list below:** several embedded families (Inter, Roboto, Open Sans, Lato, Nunito, Poppins, Outfit, Playfair Display, EB Garamond) are _also_ on the Banned monoculture list — they render fine but read as generic. The families that are **embedded AND not banned** — your safe-and-distinctive picks — are: **Montserrat, Oswald, League Gothic, Archivo Black, Space Mono, IBM Plex Mono, JetBrains Mono, Source Code Pro, Noto Sans JP**. Reach for these (or a non-bundled font you've confirmed via the Finding-Fonts step). A non-bundled name isn't guaranteed-broken — a real Google font is auto-fetched and embedded — but it carries a lint warning and a fail-closed fetch in cloud renders, so for anything that must render predictably, **embed it yourself via `@font-face`** (see "Finding Fonts") rather than relying on the implicit fetch.
 
 ## Banned
 
@@ -17,7 +60,7 @@ You know these rules but you violate them. Stop.
 - **Don't pair two sans-serifs.** You do this constantly — one for headlines, one for body. Cross the boundary: serif + sans, or sans + mono.
 - **One expressive font per scene.** You pick two interesting fonts trying to make it "better." One performs, one recedes.
 - **Weight contrast must be extreme.** You default to 400 vs 700. Video needs 300 vs 900. The difference must be visible in motion at a glance.
-- **Video sizes, not web sizes.** Body: 20px minimum. Headlines: 60px+. Data labels: 16px. You will try to use 14px. Don't.
+- **Video sizes, not web sizes.** Full-screen viewing (YouTube / website embed): body 20px minimum, headlines 60px+, data labels 16px. **In-feed viewing** (destination = X / LinkedIn / Instagram feed — `hyperframes-core/references/brief-contract.md` § 2): the video plays small inside a scrolling feed, so scale up — body ≥32px, headlines ≥90px, data labels ≥24px (first-pass values; calibrate against real renders). You will try to use 14px. Don't.
 
 ## What You Don't Do Without Being Told
 

package/skills/hyperframes-creative/references/video-composition.md

@@ -0,0 +1,63 @@
+# Video Composition
+
+Video frames are not web pages. Use these rules for design-led compositions while respecting the requested format, brand, and scope. Minimal technical compositions and intentionally sparse formats may need less detail.
+
+## The Design Spec Is Brand, Not Layout
+
+The design spec (`frame.md` or `design.md`) defines what the brand looks like: colors, fonts, personality, constraints. It does NOT define how to compose a video frame. Use brand colors at video-appropriate intensity — not at web-UI opacity.
+
+**Strict from the design spec:** hex values (including background color), font families, weight relationships, Do's and Don'ts. If the user chose a light canvas, use a light canvas. If they chose dark, use dark. Do not override their palette.
+
+**Adapt for video:** type sizes, spacing, decorative opacity, border weight, component treatments. A web UI card at `border: 1px solid #e2e3e6` with `box-shadow: 0 2px 4px rgba(0,0,0,0.06)` is invisible on video. The brand color is sacred; the application is yours.
+
+## Density
+
+Choose density from the message and format. A brand or sizzle frame often needs several visual roles to feel produced; a lower-third, logo sting, or static title may need only a few.
+
+For a scene that should feel layered, plan these roles:
+
+- **Background treatment** — radial glow, oversized ghost type, color panel, grain, grid, or an intentionally flat field justified by the concept.
+- **Midground content** — the actual message. Cards, stats, code blocks, images.
+- **Foreground accents** — dividers, labels, data bars, registration marks, monospace metadata. The details that make it feel produced, not generated.
+
+For produced marketing frames, roughly 6–10 visual roles can be a useful starting point, not a contract. Add decoration only when it reinforces hierarchy, motion, or the concept. Decorative treatment must not become new user-facing content, new scenes, or unrequested claims.
+
+## Color Presence
+
+Muted is fine. Flat is not. Every scene should have at least one color that pulls the eye.
+
+- Brand accent should be VISIBLE — not a 5% opacity glow lost in compression. 15-25% for atmospheric, full saturation for focal elements.
+- **Light canvases work differently than dark.** On dark: accent glows pop naturally. On light: use bolder borders (2px+ solid), stronger structural elements (rules, dividers), and full-saturation accent hits. Light backgrounds need texture (subtle grain, patterns) to avoid the "blank slide" feel. Don't switch to dark — make light cinematic.
+- **No full-screen linear gradients on dark backgrounds.** They band visibly under H.264 compression. Use a radial gradient, a solid fill, or solid + localized glow instead.
+- Tint neutrals toward the brand hue. Dead gray reads as undesigned.
+
+## Scale
+
+Web sizes are invisible on video. Everything scales up.
+
+| Element            | Web     | Video    |
+| ------------------ | ------- | -------- |
+| Headlines          | 32-48px | 64-120px |
+| Body text          | 14-16px | 28-42px  |
+| Labels             | 12px    | 18-24px  |
+| Decorative opacity | 3-8%    | 12-25%   |
+| Borders            | 1px     | 2-4px    |
+| Padding            | 16-32px | 60-140px |
+
+If you're writing a font-size under 24px in a video composition, justify it. If you're writing decorative opacity under 10%, it's invisible.
+
+## Motion Intensity
+
+Subtle reads as static at 30fps. Err toward more movement than feels safe.
+
+- Every decorative element should have ambient motion: breathe, drift, pulse, orbit. Static decoratives feel dead.
+- Vary motion per scene — don't repeat the same ambient pattern.
+- Scene entrances should use 3+ different eases and directions. If every element enters from `y: 30, opacity: 0`, the scene has no choreography.
+
+## Frame Composition
+
+- **Two focal points minimum.** The eye needs somewhere to travel.
+- **Fill the frame.** Hero text: 60-80% of frame width.
+- **Anchor to edges.** Pin content to left/top or right/bottom. Centered-and-floating is a web layout pattern.
+- **Split frames.** Data panel left, content right. Top bar with metadata, full-width below. Zone-based layouts over centered stacks.
+- **Structural elements.** Rules, dividers, border panels. They create visual paths and animate well (`scaleX: 0` → `1`).