@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/hyperframes/references/review.md

@@ -0,0 +1,51 @@
+# Review
+
+You wrote the timeline, so you know what happens; the viewer sees it once, at full speed, often on a phone. Review is how you see the film as they will: as a harsh motion director, not a proud author. `check` catches what is broken; this pass catches what is weak. Run it after `check` passes, on every new film and on any edit that changes timing or layout, before you reply or render.
+
+## 1. Measure, then look
+
+1. `npx hyperframes check --json`. Besides errors it warns on craft it can measure: a line on screen too briefly to read (`line_unread`), more than 3 s with nothing changing (`dead_stretch`), text under 2.6% of the frame's short side (`text_below_floor`), an empty first frame (`first_frame_empty`, the thumbnail on social players), a film over 15 s with no sound (`film_silent`). A warning is a question, not a rule: fix it, or keep it on purpose and say why in the note (a deliberate hold carries `data-hold`).
+2. `npx hyperframes snapshot --review` writes three sheets: each scene just after it starts and at its middle, plus each `data-beat`, a strip across every cut (−0.2 s to +0.2 s), and the beat frames at phone width (360 px). Open all three.
+3. Motion between the beats: `snapshot --range START,END --frames 8` around the hero move and the payoff; `keyframes --shot` for a path that must arc or land.
+4. The rendered file: `npx hyperframes audio <video> --json` shows whether sound is there, where it hits and how loud it is. You cannot hear it; say so.
+
+Trust the numbers over your eye where they disagree: a clipped label or a 0.6 s line looks fine on a contact sheet.
+
+## 2. What to look for
+
+First, describe each beat frame in one sentence as a stranger would, naming every object; an object you would have to explain ("those bars are mirrors") is a P0. Then read the beat frames in order: do they tell a story a stranger follows, each one causing the next? Compare each with its shot in `SPEC.md`; what does not match is a note. Then name every default the frames show (`spec.md` "BANNED by default", or one not on the list yet), add each to the BANNED line, and fix them before anything else.
+
+Then go through the sheets once per question:
+
+| Question                      | What it catches                                                                                                                                    |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Does it read as what it is?   | A shape that reads as another object, a material that reads as plastic, a product screen that reads as a mockup, a face or mascot that reads wrong |
+| Does the subject separate?    | Subject and ground too close in value, two focal points in one frame, the eye with nowhere to go                                                   |
+| Framing and contact           | Crops, text at the edge or under platform UI, collisions at a seam, things floating that should touch                                              |
+| Timing as a first-time viewer | A read shorter than its words (`story.md` §6), something that pops on with no move, a jump at a cut, everything moving at once on one curve        |
+| Tells                         | Which items of `story.md` §8 and `motion.md` "Defaults that look generated" are on screen                                                          |
+| The pictures alone            | With the words covered, do the beat frames still tell the storyline?                                                                               |
+| The phone sheet               | Can every line meant to be read be read at 360 px?                                                                                                 |
+
+## 3. Notes and fixes
+
+Write each problem as one line: `t=4.2s · where · problem → exact change · what stays`. Rank them:
+
+- **P0** breaks the read or the contract: unreadable, wrong, broken, a tell in the hero shot.
+- **P1** weakens the film: a dead stretch, a soft payoff, a seam that jumps.
+- **P2** polish.
+
+Fix every P0 and the P1s worth their time: text first, then timing, then detail. Then snapshot only what you changed, once. A second pass only when a P0 is still open. Never score the film out of 10: a score finds nothing to fix. When a fix does not hold, snapshot the frames on either side of the problem, list every difference, and change only the line that causes it. A film that feels busy: remove a third of the motion and keep the moves that lead the eye.
+
+A fresh pair of eyes, when your host can start a sub-agent: give it only `STORYBOARD.md` and the three sheets, ask for P0 and P1 lines in the format above, and keep editing to yourself. Commit or copy the project before you fix, so a fix that makes things worse can be rolled back.
+
+## 4. The delivery note
+
+Write `REVIEW.md` at the project root and put its short form in your reply:
+
+- the creative calls you made, and the storylines you did not build;
+- what you measured and what you only looked at; what nobody checked (the sound was measured, not heard);
+- the weakest shot, and what you would change with more time;
+- warnings you kept on purpose, and why.
+
+The next turn reads it before changing anything.

package/skills/hyperframes/references/runtimes.md

@@ -0,0 +1,69 @@
+# Animation runtimes
+
+HyperFrames seeks each frame on its own, so motion must be a function of time, never of the previous frame. Full GSAP reference: `npx hyperframes docs gsap`.
+
+## GSAP facts that bite
+
+- Register the timeline last. Building inside `document.fonts.ready.then(…)` or another async callback is fine if you register at the end of it; registering first renders blank (`gsap_timeline_registered_before_async_build`).
+- Place tweens at absolute seconds (`tl.to(el, {…}, 2.4)`). Set start states in the tween (`fromTo`), not in CSS.
+- Measure layout once before building tweens, never inside `onUpdate`.
+- Finite repeats only: `repeat: Math.max(0, Math.floor(duration / cycle) - 1)`.
+- Seed randomness with a small PRNG (mulberry32).
+- A scene's timeline can't reach elements outside its file, and two timelines must not animate the same property of one element.
+- Transforms on a `<span>` need `display: inline-block` or `block`.
+- Text that must fit a width: `window.__hyperframes.fitTextFontSize(text, { fontFamily, fontWeight, maxWidth })` returns `{ fontSize }`; `window.__hyperframes.pretext` measures text without a reflow.
+
+## Other runtimes
+
+| Runtime                      | Use for                           | How HyperFrames drives it                                                                        |
+| ---------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
+| CSS `@keyframes`             | Simple loops and decoration       | Found automatically; finite iterations, `animation-fill-mode: both`, `data-start` on the element |
+| WAAPI                        | Native keyframes                  | `element.animate(…, { fill: "both" })` then `pause()`; times are document time, so use `delay`   |
+| Lottie / dotLottie           | After Effects exports, characters | `autoplay: false`, always set `loop`, push the instance to `window.__hfLottie`                   |
+| anime.js v4                  | Existing anime code               | `autoplay: false`, push to `window.__hfAnime`, `anime.createSeededRandom`                        |
+| Three.js, WebGPU, p5, canvas | 3D and generative                 | Draw from `e.detail.time` in an `hf-seek` listener; set `data-duration` on the root              |
+
+Charts and map overlays: drive them from a GSAP tween's `onUpdate`, not the library's own transitions. A real place is shown on baked imagery, not drawn (`film.md` "Maps and real places"). Heavy setup (big meshes, shader compiles) registers a `window.__hf.buildReady["<key>"]` promise.
+
+## dotLottie browser setup
+
+Copy `dist/index.js` and `dist/dotlottie-player.wasm` from the same pinned
+`@lottiefiles/dotlottie-web` release (for example, 0.81.0) into the project's
+`lib/dotlottie-web/` directory. Its CommonJS entry cannot run as a classic
+browser script. Import the ESM entry and set the local WASM URL before creating
+the player, so rendering loads the SDK, WASM and animation from project files.
+
+```html
+<canvas id="anim" style="width:100%;height:100%"></canvas>
+<script type="module">
+  import { DotLottie } from "./lib/dotlottie-web/index.js";
+
+  DotLottie.setWasmUrl(new URL("./lib/dotlottie-web/dotlottie-player.wasm", import.meta.url).href);
+  const player = new DotLottie({
+    canvas: document.getElementById("anim"),
+    src: "assets/hello.lottie",
+    autoplay: false,
+    loop: false,
+    renderConfig: { autoResize: false, freezeOnOffscreen: false },
+  });
+  window.__hfLottie = window.__hfLottie || [];
+  window.__hfLottie.push(player);
+</script>
+```
+
+## The seek protocol
+
+```html
+<script>
+  function renderAt(t) {
+    /* draw the frame for t seconds from state derived from t alone */
+  }
+  window.addEventListener("hf-seek", (e) => {
+    renderAt(e.detail.time);
+    // async work (GPU submit, image decode): e.detail.waitUntil(promise), called synchronously
+  });
+  renderAt(0);
+</script>
+```
+
+No `requestAnimationFrame` loop or timer as the clock.

package/skills/hyperframes/references/skill-lifecycle.md

@@ -0,0 +1,49 @@
+# Skill installation and freshness
+
+Read this reference when installing or updating skills, diagnosing unexpected skill behavior, or running HyperFrames setup in CI.
+
+For a plugin installation, follow [plugin execution rules](plugin-installation.md); the plugin manager owns updates and every skill is bundled. The commands below apply only to standalone skills.
+
+- **Core set, installed eagerly:** `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry` and `/media-use`.
+- **On demand:** `/figma`, `/slideshow` and `/remotion-to-hyperframes`, installed with `npx hyperframes skills update <name>`.
+
+## What `init` does
+
+`npx hyperframes init` installs the core set when it is missing and leaves every skill that is already installed as it is: it never refreshes, replaces or removes one. Updating is `npx hyperframes skills update`, run by you. Offline or rate-limited checks degrade gracefully and do not fail project scaffolding.
+
+`--skip-skills` makes `init` leave skills alone. `HYPERFRAMES_SKIP_SKILLS=1` does the same for CI and tests.
+
+`HYPERFRAMES_SKIP_SKILLS=1` also makes `skills update` (bare or named) and bare `skills` exit 0 without installing, so an install pinned to one commit stays pinned.
+
+## Stale-skills notice
+
+After `render`, `lint` and `validate`, the CLI prints `N HyperFrames skills out of date or missing` to stderr when the cached check finds stale skills, so an agent run without a terminal sees it too. It is off in CI, in dev, with `HYPERFRAMES_NO_UPDATE_CHECK=1` and with `HYPERFRAMES_SKIP_SKILLS=1`, and runs with `--json` too, since it only writes stderr and leaves `--json` stdout untouched.
+
+## Diagnose and update
+
+```bash
+npx hyperframes skills check
+npx hyperframes skills check --json
+npx hyperframes skills update
+npx hyperframes skills update <name>
+npx hyperframes skills
+```
+
+- `skills check` exits non-zero when an installed skill is stale or the core set is incomplete. Skills available on demand but not installed are not failures.
+- Bare `skills update` refreshes the core set and the HyperFrames skills already installed. It never removes a skill, and it leaves a skill the install record attributes to another publisher alone, even when the name matches one of ours.
+- Named `skills update <name...>` also installs those named skills.
+- Bare `skills` installs the full published set explicitly.
+
+If the HyperFrames CLI is unavailable, use `npx skills add heygen-com/hyperframes --skill <name>` for one skill or `npx skills add heygen-com/hyperframes --all` for the full published set.
+
+The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Treat a failed update as a visible tool failure; do not continue from a remembered skill.
+
+## Keep the project's CLI current
+
+A scaffolded project pins `hyperframes@<version>` in its `package.json` scripts so renders stay reproducible; the pin never advances on its own, and a pinned run of an older CLI prints no warning about it. When resuming a project whose scripts carry a pin, probe once before the first render-affecting command:
+
+```bash
+npx hyperframes@latest upgrade --project . --check
+```
+
+The probe is read-only and reports the pin against the latest release; keep the explicit `.` — on older CLI releases a bare `--project` followed by another flag consumes that flag as its directory value. When it reports the project behind — or any CLI output already shows it (the stderr notice `This project pins hyperframes@… (latest …)`, or `_meta.updateAvailable: true` in a `--json` result from a pinned script) — apply with `npx hyperframes@latest upgrade --project .`, then verify with `npx hyperframes check`. A passing check confirms the project's compositions still validate on the new version — not that rendered output is frame-identical to the old pin — so a successful bump is never silent: name the old and new version in the run's summary. A project with no composition yet needs no verification. If the check fails, revert the `package.json` change, continue on the pinned version, and report which version the project stays on and why. Act on the signal rather than relaying it to the user; never leave a bumped pin unverified.

package/skills/hyperframes/references/sound.md

@@ -0,0 +1,43 @@
+# Sound
+
+Sound is half of how a film feels, and the viewer notices a silent one before any frame. Every judge of frames misses it, so plan it on purpose.
+
+## 1. The default
+
+- **A film over about 15 s that tells something** (launch, explainer, recap, PR video) gets a music bed and sounds on its visible actions, unless the person asked for silence or it is made to play muted (a looping background, a feed that autoplays without sound: then the type and the pictures carry it alone).
+- **A voiceover** only when the request or the source calls for one (`SKILL.md`).
+- **Each storyline says its sound** in one line (`story.md` §2): the bed's feel and tempo, the one moment the music changes, which actions get effects, or silence and why.
+- **Short pieces** (a title card, a sting under 10 s, captions or overlays on footage that has its own sound) follow the request and the footage.
+
+## 2. The clock
+
+- **Narrated**: the voice is the clock. Time each beat's start to its anchor word; text lands on the word that says it.
+- **Music only**: the music is the clock. Land the payoff and the mark on its strong beats (`npx hyperframes beats`, then `film.md` "On music"); cuts follow the motion, not the drums.
+- Let the sound act out the story when it fits: the old way sits near silence, the music opens when the product appears; the music holds back until the payoff.
+
+## 3. Music
+
+The person's own track first, as given. Else search the catalog (`/media-use`, `bgm`) with the film's feel and tempo, not its subject ("tense minimal pulse building to a bright drop, 120 bpm"), and read a few results before keeping one. Enter at the track's strongest bar, not a quiet intro; end on a bar line with a short fade under the end card.
+
+With no music source (no `heygen` sign-in and no local model), deliver silent and say so in one line with how to add one. Do not spend the run building an audio chain or writing music in code: nobody can hear whether it is good.
+
+## 4. Effects
+
+Few and exact: every effect has a cause on screen, and too many read as a template.
+
+| Sound             | Only on                                        |
+| ----------------- | ---------------------------------------------- |
+| click             | a real cursor click on screen                  |
+| whoosh            | a scene cut, or a large card moving fast       |
+| soft key tick     | text arriving letter by letter or line by line |
+| pop               | a badge, chip or number landing                |
+| riser into impact | the payoff or the mark, once in the film       |
+
+- Place a clip so its peak lands one frame after its picture (light arrives before sound; a sound early feels wrong sooner than one late): `npx hyperframes audio <file> --json` reports where it hits, and most files peak after their start.
+- Each hit sits 3-6 dB over the bed; a bed with most of its energy under 150 Hz plays as nothing on a phone speaker.
+- Rotate two or three takes of a repeated sound; the same whoosh on every cut is the most common tell.
+- Over strong music, a typing-heavy film can drop the clicks and keys. No synthesised tones, chimes or dings.
+
+## 5. Levels
+
+Music under a voice sits around 0.14 volume; nothing clips (AI audio often does). Keep each file's true peak at −1 dBTP or lower and the mix around −16 to −14 LUFS for social, `npx hyperframes normalize-audio` to match levels (`/media-use`). Check the rendered file with `npx hyperframes audio <video> --json`: sound present, hits where the picture hits, loudness in range. Say in the delivery note that it was measured, not heard (`review.md` §4).

package/skills/hyperframes/references/spec.md

@@ -0,0 +1,76 @@
+# The spec
+
+Adjectives are where the default look lives. Given "premium, modern, clean", the model fills every gap with its own defaults, and they look the same in every run: a dark void, a glow, small type floating in the middle, everything fading in. Every adjective you turn into a number is a decision taken back from those defaults.
+
+So before any scene, write `SPEC.md` at the project root: the film as a director's brief to yourself, with a number wherever you would have written an adjective. Build from it, check against it, and change it when a review changes the film.
+
+The spec serves the story, never the other way round (`story.md`). A look that turns the story's things into abstract shapes has failed, however striking the frame.
+
+## The template
+
+```text
+GOAL:    what the viewer feels or does at the end, one sentence
+OUTPUT:  HyperFrames, W x H, fps
+TIME:    seconds x fps = frames; BPM and frames per beat when there is music
+LOOK:    ground (hex, texture and its amount), ink, one accent and where it may appear;
+         display face + weight + size in px + tracking, body face the same;
+         the medium (paper and ink, photographs, product UI, glass, clay, 3D studio) with its numbers;
+         light and depth: shadow offset, blur and opacity, grain %, vignette %
+OBJECTS: every thing the story needs the viewer to recognise (a mirror, a clock, a phone, a person),
+         drawn with the material and details that make it read without a label: a mirror is
+         silvered glass with a bright edge and a mount, not a bar
+MOTION:  eases by role as named curves (enter, move, exit, camera); springs as damping ratio;
+         durations and staggers in frames
+SHOTS:   one line per shot: frame range, the one hero move, what the viewer reads (with its window),
+         the sound, and how it hands off to the next shot
+BANNED:  the defaults below, plus anything this film must not become
+QA:      the frames to check, and what each must show
+```
+
+## Turning words into numbers
+
+| The word  | Becomes                                                                                                                                |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| premium   | a material with numbers: satin paper with 2% grain, a product on a seamless sweep with a 0.55 contact shadow, chrome at roughness 0.05 |
+| modern    | a camera and a type system: a 30-frame push on one ease, a display face at 9% of the frame height with -2% tracking                    |
+| clean     | a grid and a ration: 12 columns, 96 px margins, the accent on one word per shot                                                        |
+| dynamic   | cuts on the beat, a layout change on the bar (every 4 beats), one hero move per shot                                                   |
+| playful   | springs at damping 0.45-0.6 on position and scale (never on opacity or colour), 10-30% exaggerated poses                               |
+| cinematic | a lens and a light: a 35 mm framing, a key from upper left, a rim from behind, 6% vignette                                             |
+
+## Composition numbers
+
+- The hero of a shot fills at least 40% of the frame's height or width. A small object in the middle of an empty frame is never a shot; push in, crop, or give it a world.
+- One hero move per shot. Secondary moves travel 50-70% as far, start 100-200 ms after it, and everything else holds still.
+- In a story film every shot moves the story: something happens that causes the next shot. Lines read as cause and effect ("so…", "which means…"), not slogans.
+- An information card (B-roll over a talking head, a data beat, a vertical explainer card) is different: its information is on screen within about 2.5 s, then it holds, so any paused frame reads as a finished poster.
+- Something new every 2-4 s across the film; a new layout every bar when there is music.
+- Text meant to be read: at least 28 px at 1080 (2.6% of the short side), held 0.5 s + 0.3 s a word. Too many words: cut words, never shrink type.
+
+## BANNED by default
+
+These are where generated video lands when nothing else is decided. Each is banned unless the brand's own material or the person's reference uses it, and then only as they use it:
+
+- a black or dark navy void as the ground, with small elements floating in its middle;
+- glow, bloom, neon, lens flares, glowing orbs and rings; floating particles as decoration;
+- purple or blue gradients, mesh gradients, glass cards;
+- a cream or off-white paper ground with a serif display, italic accent words, numbered "01 / 02" labels, small monospace caps labels, pill-shaped chips and buttons;
+- everything centred; everything fading in at once; every element fading and sliding up;
+- text that moves while it is read; titles that keep drifting after they land;
+- corner labels, frame borders, corner brackets, HUD readouts as decoration;
+- three cards in a row, KPI grids, a title over a dimmed screenshot;
+- the logo docked in a corner.
+
+After the first render, name every default it used anyway, from this list or not, add each to the film's BANNED line, and fix them. The list grows with every film.
+
+## A look built from a medium
+
+A look holds together when it is the rules of one medium, not a palette. A risograph look, for example, is five parts and nothing else:
+
+- **paper**: one flat colour with a fibre noise, no gradients;
+- **ink A**: every word that must be read and every structural line;
+- **ink B**: one fluorescent accent, one focus per frame (the number, the bar, the stamp);
+- **overprint**: where the inks overlap a third colour appears, and the B plate sits 3 px off register;
+- **halftone**: every gradient is dots.
+
+Motion comes from the same medium: the frame is printed, plate by plate, not faded in. Write any look this way: its parts, what each may carry, and how the medium itself moves (paper is cut and lifted, ink is printed, glass refracts, clay is pressed).

package/skills/hyperframes/references/story.md

@@ -0,0 +1,103 @@
+# Story
+
+Read before building any video that tells something over about 15 s: a launch or promo, an explainer, a pull-request or changelog video, a recap, a music video with a narrative. Most weak films are good motion around no story: a list of features, three cards in a row, a logo, a URL.
+
+Skip it for an edit to an existing project, captions or overlays on footage, and a short single-idea piece (one kinetic line, a map move, a highlight on an image), where the request is the story. When the person gave a script, a storyboard or a reference film, follow theirs. The shape of each kind of film (launch, explainer, music, data, vertical, 3D, character) is in `types/`.
+
+## 1. The one thing
+
+- **What it is**, in one line: "You can now …" for a launch, the one idea the viewer must understand for an explainer, what changed and why it matters for a pull request. A whole release ("2.0", "what's new") is not one thing: take its headline.
+- **The one thing to remember** after the film ends, in the viewer's words, not the brand slogan.
+- **One viewer doing one real task**, from the moment they need it to the result. That task is the spine, and one real piece of data (a query, a file, a prompt, a number) travels through it from the hook to the payoff. An explainer's spine is one concrete example worked through.
+- Keep facts (what it does, real numbers, real labels) apart from creative choices (angle, tone, look). Every claim on screen traces to the source: the site, the PR, the docs or the person's words. Use the person's own copy verbatim.
+- What the source does not say stays unsaid: never derive a claim it did not make ("40 min to 2 min" is not "20× faster"), mark an example number as illustrative, and show a screen you cannot get as a labelled placeholder, not a drawn one.
+
+## 2. Three storylines, then one
+
+Write three. They are three different films, not three titles on one film: each has its own **world** (where it happens and what it looks like), its own **device** (what the story is) and its own **form** (how the camera and the cuts carry it). Sketch five or more ideas first, a line each pairing a device with a form (tables below); drop those the subject cannot carry well, and of the rest keep the three that differ most. Make one of the three the bold one you would not have picked first. Each says:
+
+- its name, its device and form in a few words, and in two sentences what the viewer sees and feels;
+- the first two seconds, exactly;
+- its beats in one line (`hook → … → end card`);
+- its look in one line: ground, type, the one material or treatment, taken from the subject or the brand (`look.md`);
+- its sound in one line (`sound.md` §1).
+
+The storylines are words: build nothing for any of them before one is picked. Pick a storyline for its story: the one a stranger would follow and remember, with people or a situation they know, ahead of the most striking picture. Picking a storyline picks its look and its sound. Then write the picked one as `SPEC.md`.
+
+Put your recommendation first, with the reason in one clause, and save all three in the project as `STORYLINES.md` so a later turn can switch.
+
+- **The person is there to answer:** show the three and stop once until they pick. A mix ("A's opening with C's middle") is one storyline. Ask nothing else unless only they can answer it (real screens you cannot capture, narrated or music only). State everything else in one assumption line: the length as a range, the aspect, music or voice, and every paid item (a HeyGen voice, an avatar, catalog music) with the free option beside it.
+- **They asked for the file or for no stops:** take your recommendation, build it, and name the other two in one line each in your reply.
+- With a storyboard (`storyboard.md`), the picked storyline becomes the board's frames.
+
+| Device                        | What the viewer sees                                                                    |
+| ----------------------------- | --------------------------------------------------------------------------------------- |
+| A moment in someone's day     | a person, a time stamp, the message that creates the need ("launch is tomorrow")        |
+| A character does the work     | a mascot or a cursor carries, drags, draws and reacts; every cut has a cause            |
+| The feature as the hook       | the feature happening to a recognisable image in the first half second                  |
+| The result first              | the finished output plays, then the camera pulls back to show where it came from        |
+| One object across apps        | the thing being made travels from one app into the product, which keeps working on it   |
+| Life before and after         | the old way as a scene (one person drowning in tabs), then the new way                  |
+| Type carries the argument     | giant kinetic type, colour fields and grids that cut on the beat                        |
+| A number lands                | one real number earned by a scene, then made physical                                   |
+| A question with the input     | "What if you could make a video from your ⟨website⟩?", the blank filled by a real input |
+| The object is the explanation | a machine or model whose working is the idea; the camera tours through it               |
+
+| Form                       | What the viewer sees                                                                         |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| One continuous take        | the camera never cuts; it pushes, pulls and travels from one world into the next             |
+| Object-to-object chain     | every shot ends on the thing that opens the next: a button becomes a card becomes a phone    |
+| An endless zoom            | the camera dives into a detail that turns out to be the next world, again and again          |
+| A flight through one world | a 3D set, a map or a desk the camera travels across; each idea is a stop on the route        |
+| Cut on the beat            | hard cuts on the music, type and colour fields changing every half beat                      |
+| Match cuts                 | one shape holds while everything around it changes: a circle becomes a lens, a wheel, a logo |
+| Split screen to one        | several panes play at once, then collapse into the one that matters                          |
+| One frame that rebuilds    | a single composition keeps rearranging itself and never leaves the frame                     |
+
+A pitch where all three are plain cuts between scenes has not tried the forms. Before and after: the new side moves calmly while the old side churns; never mock a named competitor. A recap asks one question first so each piece answers it.
+
+## 3. The hook
+
+The first two seconds are the densest of the film, and frame 0 is the thumbnail: never black, never a logo alone. Open on the feature working on something recognisable, a real moment that creates the need, a question with the input inside it, a sentence whose last word becomes the picture, or the bug itself. Then let the old way fail on screen (the wait, the wall of text, the wrong result) before the product brings relief; the proof is often the same shot improved in front of the viewer. Typing into a prompt box as the opener, with nothing else on screen, is the tell of a generated film; as a story step a few seconds in, it is fine.
+
+## 4. Beats
+
+A common shape for a launch of about 35 s; scale it, let the device bend it, and take another type's shape from its file in `types/`:
+
+| Beat     | Share | Job                                                                                       |
+| -------- | ----- | ----------------------------------------------------------------------------------------- |
+| Hook     | ~8%   | the world and the need, or the feature already working                                    |
+| Tension  | ~12%  | the old way failing on screen, or a gag                                                   |
+| Reveal   | ~8%   | the product or idea named as a title, about 20–30% in                                     |
+| Proof    | ~40%  | the real task in the real UI as 3–6 verbs (_paste, pick, watch it build, ship_), one each |
+| Payoff   | ~20%  | the output arrives, already moving: the biggest visual moment, once, 60–80% in            |
+| Claim    | ~8%   | the one thing, in one line                                                                |
+| End card | ~8%   | the mark carried in, the name and the call to action land and hold 2–3 s                  |
+
+In each verb beat keep only what the cursor touches and what proves the line; delete the rest of the screen. The process runs fast; the payoff plays at normal speed. Length follows the story (a feature launch is usually 20–45 s); a length in the request is a range, never padded.
+
+## 5. Worlds
+
+A film visits several worlds, each with its own background, light and scale (a desktop, the product on a brand gradient, a white void with a character, live action), never one dark canvas with small UI floating in it. Enter each world through an object already on screen: the thing clicked becomes the next shot. Keep one home stage to return to, one carrier the eye follows, and the palette and type constant across worlds.
+
+## 6. Copy and voice
+
+- Titles take at most 6 words a line, one line on screen at a time, no trailing periods; an explainer's lines may run to about 10. A line holds about 0.3 s a word plus 0.5 s, and the last line at least 2 s.
+- Show, don't list: no bullet slides or three-card rows. When similar things repeat, each gets its own idea and layout.
+- Real numbers only, from the source. The first line is never "Introducing", "Meet" or the logo; after the pain, "Introducing X" is fine. Never "unlock", "seamless", "supercharge", "game-changer", "revolutionize", "effortless", or "in seconds" unless measured.
+- Read the lines alone: a stranger gets the pitch. Watch the pictures alone: they tell the same story.
+- No voiceover unless the request or the source calls for one; then the screen never repeats the spoken sentence word for word. Without a voice, large titles and the product's own text carry the words, over music and effects (`sound.md`).
+
+## 7. The brand
+
+The mark lands once, with weight, usually on the end card; before it the brand shows only inside the product and the story, never docked small in a corner. The end card is built, not a still: the mark is carried in, typed or wiped in. The accent colour is rationed: one highlighted word, the payoff, the end card.
+
+## 8. Tells of a generated film
+
+The defaults a film falls into when nothing is decided are banned by name in `spec.md` ("BANNED by default"): a dark void with small things floating in it, glow and particles, the cream-paper-serif-mono-label look, everything fading and sliding up, three cards in a row, the docked logo. Beyond those, for a story:
+
+- every scene entering the same way, or the same move beat after beat;
+- side-by-side panels and floating cards standing in for a scene;
+- titles that keep sliding or shrinking after they land; breathing or floating loops standing in for motion on titles and UI (a character's idle breath is acting, `types/character.md`).
+
+When a first render shows any of them, name which, take the replacement from the subject, the brand or the medium, and add it to the BANNED line of `SPEC.md`.