@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/hyperframes/SKILL.md

@@ -1,117 +0,0 @@
----
-name: hyperframes
-description: "Read first to make, edit, animate or render any video with AICUT (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: Apache-2.0
-source: "heygen-com/hyperframes"
----
-
-# AICUT
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules`plugin-installation.md` when this skill is inside a HyperFrames plugin.
-
-# HyperFrames
-
-HyperFrames renders HTML to video by seeking a paused timeline frame by frame, so every render is identical; the person edits the same files in the Studio preview. Use it unless another framework or a plain browser recording is asked for. Run the CLI as `npx hyperframes <command>` (`/hyperframes-cli`); at the start of a new video, `npx hyperframes usage --json` reports the person's remaining plan usage (say "unknown" when it is).
-
-`index.html` is the root composition: it declares the video's variables and mounts one scene per sub-composition from `compositions/`. Media and fonts live in `assets/`. A new project: `npx hyperframes init <dir>`. A website as the subject: `npx hyperframes capture <url> --json`.
-
-Build what was asked: no voiceover or captions and no new aspect ratio unless the request or the source calls for them; a film over ~15 s that tells something gets music and sound on its visible actions unless the person asked for silence (`references/sound.md`). A new video is 1920×1080 at 30 fps. A question, a hold or a loose idea gets an answer or a proposal, not an edit. Before hand-writing a named effect, transition, caption style, chart or card, search the registry (`/hyperframes-registry`). Any media (a presenter or avatar, footage, voice, music): `/media-use`, which says when HeyGen is needed and what is free. Show real things from their source (the product's screens, the brand's logo, a real place's imagery); draw only what has none.
-
-## Contract
-
-`npx hyperframes check --json` reports most violations with a `Fix:` line.
-
-1. Every timed element has `class="clip"`, `data-start` and `data-duration` in seconds, and shows over `[start, start + duration)`: land an end state just before its end. `data-track-index` is only a Studio lane; paint order is `z-index`.
-2. The video's length is the root's `data-duration`: overrun is cut, an early end holds the last frame.
-3. Each composition builds one paused timeline and registers it after its tweens: `window.__timelines["<data-composition-id>"] = tl`.
-4. No `Date.now()`, unseeded `Math.random()`, network fetches, timers or `repeat: -1`. Everything visible is a function of timeline time.
-5. Never tween `display`, `visibility` or `autoAlpha` on a `.clip`; animate a child.
-6. No CSS `transform` on an element GSAP transforms; animate transforms, not `left`/`top`/`width`/`height`.
-7. Never `play()`, `pause()` or seek media. A `<video>` keeps its sound with `data-has-audio="true"`, else it is `muted`; music, voice, replacement sound and J/L cuts are a separate `<audio>`.
-8. Every `<audio>` has an `id` or it is left out of the mix. No `crossorigin` on media. Time a `<video>` or its wrapper, never both.
-9. Only the bundled fonts (`references/format.md`) resolve by name; any other family needs `@font-face` to a file in `assets/fonts/`.
-10. Asset paths are root-relative (`assets/...`), in sub-compositions too.
-11. Grades, grain, blur and vignettes on footage go through `npx hyperframes media-treatment` (`/media-use`), never CSS filters.
-12. A scene file puts its styles, markup and scripts inside `<template>` and styles its root as `#root`. Intended overflow or overlap: `data-layout-allow-overflow`, `data-layout-allow-overlap`.
-
-## Keep it editable
-
-Studio edits the tags you write.
-
-- One scene per sub-composition, short readable ids; the root holds only scene hosts, media and audio.
-- Timed elements are written in the HTML, not made by script, each with a stable `id`.
-- Copy, brand colours and swappable media are variables (`data-var-text`, `data-var-src`, `var(--id)`).
-- One kind per track: `data-track-kind="graphics"` on scene and overlay hosts, `captions` on the one host that holds every caption group.
-- Content stays inside the 90% action-safe box, captions and key text inside 80% title-safe; Studio draws the guides, never add them.
-
-## Work loop
-
-- An existing project: `npx hyperframes timeline --json` shows what plays when; before any change, `npx hyperframes history --since mine --who <you>` shows what the person changed since your last turn: build on it (`/hyperframes-cli`).
-- A new film over ~15 s that tells something: its type's file (below), then `references/story.md`: three storylines that are three different films, in words only; the person picks unless they asked for the file or no stops. Then `SPEC.md` (`references/spec.md`): every adjective as a number, the defaults banned by name, the shots by frame.
-- After your last edit: `npx hyperframes check --json`; fix every error, weigh every warning. A film: `npx hyperframes snapshot --review` and `references/review.md`, ending in `REVIEW.md`. A small edit: snapshot what you changed (`--at`, `--range`, `--composition`) and look before you reply.
-- Render when the person approves the Studio preview, asks for the file or asks for no stops, after your check and review pass; otherwise stop at the preview and wait.
-
-## The HyperFrames desktop app
-
-Call it "the HyperFrames desktop app", never "Studio"; offer it as the better way to keep editing, not the only one.
-
-- Before the delivery render of a new video, open the Studio preview, even in no-questions mode, and say they can edit there. If `preview` printed "Keep editing by chatting with Framey", add that the **Edit with Framey** button opens the app.
-- After the delivery render, pass on its Framey line in your own words: offer to run the `hyperframes open` it names or give its download link; else say nothing (autonomous: the delivery note).
-- When any command says to run `catch-up`, run `npx hyperframes catch-up [dir]` before your next change; what it lists is their work, not a new request.
-
-## What to read
-
-| The request | Read |
-| --- | --- |
-| Launch, promo, feature | `references/types/launch.md` |
-| Explainer, tutorial | `references/types/explainer.md` |
-| Music video | `references/types/music.md` |
-| Chart, numbers | `references/types/data.md` |
-| Vertical or social clip | `references/types/vertical.md` |
-| 3D, simulation, generative | `references/types/3d.md` |
-| Character, mascot, story short | `references/types/character.md` |
-| A real place or map; a website, PR or script; kinetic type | `references/film.md` |
-| Captions; cards over a talking head | `references/captions.md`; `references/overlays.md` |
-| Motion: eases, titles, cuts, punch-ins, speed, holds | `references/motion.md` |
-| Scenes, attributes, media, lint; GSAP, Lottie, 3D, canvas | `references/format.md`; `references/runtimes.md` |
-
-Decks: `/slideshow`. Remotion source: `/remotion-to-hyperframes`. Figma: `/figma`. Installing, refreshing or upgrading skills and the pinned CLI: `references/skill-lifecycle.md`.
-
-## Source
-
-Rewritten for AICUT from [`heygen-com/hyperframes`](https://github.com/heygen-com/hyperframes)
-(Apache-2.0), skills/hyperframes/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
-
-The repository holds 26 skills; this is the one its entry stands for.

package/skills/hyperframes/references/captions.md

@@ -1,46 +0,0 @@
-# Captions
-
-## Words and timings
-
-- `npx hyperframes transcribe <file> --json` and a HeyGen voiceover (`/media-use`) give every word's start and end. Work from those as `[{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 }, …]`.
-- `npx hyperframes transcribe` defaults to the `small.en` whisper model, which **translates** non-English speech into English. Pass the model: `npx hyperframes transcribe <file> --model small.en` for English, `--model small --language <code>` otherwise, `--model medium.en` for speech over music. It writes `assets/transcript.json` (its JSON names the path) and overwrites it on the next run; `--to srt` or `--to vtt` writes a sidecar.
-- For Chinese, Japanese and other unspaced scripts, local transcription returns a whole sentence as one "word", sometimes in the other script (Traditional for Simplified speech). Split each segment's text into short phrases and spread its time across them by character count; check the characters against what is said.
-- Whisper invents "Thank you." over silence and repeats lines over a silent tail: drop words that start inside a final silence (`silencedetect=noise=-35dB:d=0.6`; real speech sits around −16 to −26 dB).
-- Never put two words in one timed entry, and match transcript words to caption words by position, not text, or a repeated word takes the wrong time.
-- Read the transcript before using it. More than 20% `♪` or `�` tokens, or nonsense words, means it failed: retry with a larger model, or take lyrics from the person. Drop non-word tokens before building groups.
-
-## Structure
-
-- One sub-composition host with `data-track-kind="captions"` holds every caption group, so Studio shows them on one captions track.
-- Ready-made styles: `npx hyperframes catalog --tag caption-style --json`. An installed one is source you can restyle.
-
-## Groups
-
-- 2–3 words for high energy, 3–5 conversational, 4–6 calm. Break at a sentence end, a pause of 150 ms or more, or the word limit.
-- One group visible at a time. A group opens at or before its first word's start and closes at or after its last word's end. A caption at exactly 0 s looks pre-existing: start 0.1–0.3 s in.
-- Every group ends with a hard kill after its exit, or a stale group can stay on screen:
-
-```js
-tl.to(group, { opacity: 0, duration: 0.12, ease: "power2.in" }, end - 0.12);
-tl.set(group, { opacity: 0, visibility: "hidden" }, end);
-```
-
-`tl.set` is an instant flip, so setting `visibility` on the group is fine; never tween it on a `.clip`.
-
-## Fit and place
-
-- Size each group to fit: `window.__hyperframes.fitTextFontSize(text, { fontFamily, fontWeight, maxWidth })` returns `{ fontSize }`. Defaults: `maxWidth` 1600 landscape, 900 portrait; base 78, minimum 42, step 2. When a word scales up for emphasis, divide `maxWidth` by that scale.
-- A full-width absolute container, centred with text alignment. Never `left: 50%; transform: translateX(-50%)`, which clips at the frame edges.
-- `overflow: visible`, not `hidden`, which cuts off scaled words and glows.
-- Landscape: 80–120 px from the bottom. Portrait: about 600–700 px from the bottom. Never over the speaker's face; inside the 80% title-safe box.
-- Position each group absolutely. In a flex column a group hidden with `visibility: hidden` still takes space, so the next one lands lower. In a stack that accumulates, groups in one block share one exit time, or the stack reflows.
-- Fade the group or its words, not both: the opacities multiply and read as a pop. A gradient or `background-clip: text` fill goes on the inner text span, not the transformed container.
-- Over footage, choose the blend by the brightness (0–255) behind the text: under 60 `screen`, 60–180 `overlay`, over 180 `normal` with opaque colour. Plain subtitles above brightness 60 get a scrim sized to the text (30–40%), never a full-width bar.
-- Footage may already carry burned-in subtitles only mid-clip: scan a 1 fps contact sheet before placing captions.
-
-## Text behind the speaker
-
-- Stack the video, then the captions, then a cutout of the person from `npx hyperframes remove-background` (`/media-use`), ordered by `z-index`. Shake or punch in the video and the cutout together in one wrapper.
-- `check` treats a `<video>` as opaque across its whole box, so a WebM cutout fails every caption behind it with `text_occluded`: put `data-layout-allow-occlusion` on the cutout and judge from `snapshot`.
-- A big word behind the head reads best 30–55% covered: under about 15% it floats, over about 65% it is eaten. Re-lay out when a content word is 80% covered, or two adjacent words 50% each. Measure the rendered word boxes against the matte over each caption's own time window (heads move: one clip went from y=224 to y=96 in 8 s); estimates from character widths were wrong both ways.
-- The matte model drops mic arms, lets large rigs near the body leak in, and flickers on held objects. Its first run downloads 168 MB, and it runs at about 2 fps at 1080p on CPU.

package/skills/hyperframes/references/film.md

@@ -1,48 +0,0 @@
-# Films from a source: measured facts
-
-What is specific to HyperFrames, or was measured on shipped films, when one video is made from a website, a script, a pull request, a music track, a real place or a short motion brief. The story comes first, from `story.md`; the shape of each kind of film is in `types/`. Motion craft is in `motion.md`, look in `look.md`, sound in `sound.md`, captions in `captions.md`.
-
-## Script and pacing
-
-- TTS reads about 2.2 words a second. Keep a scene to about 19 words (9 s); at most two scenes may reach 26 words (12 s). 30–90 s is about 155 words or fewer; a whole film about 400 at most.
-- A voiceover longer than its visuals makes the visuals pad with idle drift. Trim the script; never stretch the motion.
-- Everything on screen in the first quarter of a scene, then frozen, reads as a slideshow. Reveal each piece when the voiceover names it, across the back half of the scene; write the voiceover as separate phrases so it has cue points.
-- Up to about six short scenes, build them yourself in one context (about 9 min for five, against about 21 min split across sub-agents). Beyond that, give each worker two or three scenes and start them all at once; a second wave nearly doubles the time.
-
-## From a website
-
-- `npx hyperframes capture <url> --json` writes `screenshots/full-page.png`: a 1x plate of the whole page, taken after the scroll pass with sticky and fixed elements made static, pixel-exact for a 1920-wide viewport travelling down it. It is skipped above 16384 px tall (use `scroll-*.png`); pushing in past 1:1 needs its own 2x capture of that region.
-- To show the site as it is, use its screenshots. Rebuilding the page in HTML drifts from the real layout; rebuild only the part that moves, or overlay captured assets at measured positions.
-- `--capture-budget` (default 120000 ms) bounds work after navigation; `--timeout` bounds navigation only. Videos are not downloaded: `capture --video <dir> --list`, then `--index N`. `asset-descriptions.md` has vision captions only when `OPENROUTER_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set.
-- "very little text content" with an empty asset catalog means the capture is unusable even when it says `ok: true`. A `logo-*.svg` name is a guess from page structure, not proof.
-- Brand tokens: link blue `#0000EE` and status reds and greens are never the accent; the accent is the colour that recurs across the most roles. Icon fonts (Font Awesome, icomoon, webflow-icons) are never the display or body face; a captured monospace goes to the mono role. Use only weights the brand font ships, or 600/700 render as fake bold. Every preset has a light ground: for a dark brand, swap ground and ink.
-- Capture keeps each `@font-face` rule, `unicode-range` subsets included, in `extracted/page.html`; copying the font files alone loses which characters each covers. Name copied fonts by family, weight and style, or an upright and an italic "Regular" collide.
-
-## From a pull request
-
-- `gh pr view --json files` stops at about 100 files: page `gh api repos/{owner}/{repo}/pulls/N/files`.
-- The PR author only opened it: credit commit authors, by commit count (`commits[].authors[]`); skip bots, lockfiles and `dist/`. Reviewers come as logins; names via `gh api users/<login> --jq .name`. TTS reads `@handles` aloud, so speak names.
-- Never invent a version. Use the first non-draft release published at or after the merge; else the default branch's `package.json` version as "unreleased"; else only the PR URL.
-- Length from size (additions + deletions), as a ceiling: ≲50 lines 20–40 s, 50–200 40–70 s, 200–600 70–110 s, ≳600 lines or 25+ files 110–180 s.
-- Show 2–4 hunks of 4–12 lines; counts like +N/−M go on a stat card, not into the voiceover.
-- The `code-*` registry blocks (`npx hyperframes catalog --query code --json`) are 1920×1080 scenes driven by `window.__TOKENS` (Shiki tokens, `github-dark`; `fontStyle` bit 1 italic, bit 2 bold) and `window.__BLOCK` (`{id, effect, seq, line?, duration}`). `code-diff` and `code-morph` need at least two states; `code-highlight` counts lines from 0 and `code-scroll` from 1; `code-typing` types at a fixed speed, so check characters × speed against the scene's duration. They reserve no caption band: inset the panel when captions are on.
-
-## On music
-
-- Library music, HeyGen's included, comes as 15–30 s loops: loop the bed to the film with a 0.4 s fade-in and a 1.5 s fade-out. A track whose opening is a quiet build drains a short film: start from a stronger later section.
-- Trust beat times only on rhythmic stretches; on calm music the tracker invents a metronome, often at double tempo (`npx hyperframes beats` reports `bpmConfidence`). Cut there on phrase and energy changes; `npx hyperframes audio --only sections,onsets,moments --json` finds them.
-- A move that must land on a hit starts 40–190 ms early; a reaction starts 0–45 ms after. The hit itself is a 0 ms `tl.set`: easing a hit kills it. Scenes tile the track with no gaps.
-- A word meant to be read holds at least one beat. Any single treatment goes stale after about 6 s: lengthen a section with a hold or a new treatment, never by slowing tweens. On rhythmic sections give footage one clip per strong beat; on calm ones one slow push from 1.0 to 1.08.
-
-## Maps and real places
-
-- A real place (a city, a building, a route, a zoom from the globe to a street) is shown on real imagery. Vector outlines from Natural Earth or GeoJSON read as a diagram and lose the place; keep them for borders and labels drawn on top.
-- Live tiles change between renders, so bake the camera move to video with `scripts/bake-basemap.mjs` (MapLibre over Esri satellite or Carto tiles; writes an all-intra MP4 and `<NAME>-coords.json`). From space down to a street: `PROJECTION=globe FROM="lng,lat" CENTER="lng,lat" ZSTART=1.85 ZEND=16` (Earth in a starfield turns from FROM to CENTER, then dives); `--help` lists the rest. It needs network for the tiles and takes well under a second a frame, so bake once, keep the MP4, and run one bake at a time. Draw borders, pins and labels as a live SVG from those coordinates, animating them only while the camera holds.
-- Credit the imagery on screen ("Esri, Maxar, Earthstar Geographics" or "© CARTO, © OpenStreetMap") in small type on a soft dark backing, so it holds contrast over bright tiles; mark it `data-layout-ignore` so the type floor in `check` skips it.
-
-## Short motion pieces
-
-- Kinetic type takes 3–7 English words or 4–12 Chinese characters per scene. A count-up runs 1.2–1.6 s, then holds, landing on a downbeat or a hard stop.
-- A highlighter that wraps across lines: tween a custom property on a `background-size` band with `box-decoration-break: clone`. `getTotalLength()` can return 0 before layout; give line draw-ons a fallback.
-- Hide a round-capped line with a gap longer than the path (`stroke-dasharray="100 120"`, `stroke-dashoffset="110"` on `pathLength="100"`), not dash = gap = offset: that leaves a dot at the end on some curves.
-- A point in an image guessed directly misses by 16–24% of the frame. `scripts/locate.mjs` narrows it with a numbered 9×9 grid, then 6×6 on the crop, then a check render (about 2% error).

package/skills/hyperframes/references/format.md

@@ -1,158 +0,0 @@
-# Composition format
-
-The detail behind the contract in `SKILL.md`. Full references: `npx hyperframes docs compositions`, `docs data-attributes`, `docs troubleshooting`.
-
-## Shape of a project
-
-```html
-<!-- index.html: a normal document; declares variables, mounts scenes -->
-<html
-  data-composition-variables='[{"id":"headline","type":"string","label":"Headline","default":"…"}]'
->
-  <body>
-    <div
-      id="root"
-      data-composition-id="main"
-      data-start="0"
-      data-duration="12"
-      data-width="1920"
-      data-height="1080"
-    >
-      <div
-        id="intro"
-        data-composition-id="intro"
-        data-composition-src="compositions/intro.html"
-        data-start="0"
-        data-duration="4"
-        data-track-index="1"
-        data-width="1920"
-        data-height="1080"
-      ></div>
-    </div>
-    <script>
-      window.__timelines["main"] = gsap.timeline({ paused: true });
-    </script>
-  </body>
-</html>
-```
-
-```html
-<!-- compositions/intro.html: everything inside <template> -->
-<template>
-  <style>
-    #root {
-      position: absolute;
-      inset: 0;
-    }
-  </style>
-  <div id="root" data-composition-id="intro" data-width="1920" data-height="1080">
-    <h1 id="headline" class="clip" data-start="0.4" data-duration="3" data-var-text="headline">
-      …
-    </h1>
-  </div>
-  <script>
-    const tl = gsap.timeline({ paused: true });
-    tl.fromTo(
-      "#headline",
-      { opacity: 0, filter: "blur(8px)" },
-      { opacity: 1, filter: "blur(0px)", duration: 0.18, ease: "power4.out" },
-      0.4,
-    );
-    window.__timelines["intro"] = tl;
-  </script>
-</template>
-```
-
-- Give the host, the scene root and the timeline key the same id. A host id that differs from its scene's makes each render wait 45 s per scene, then show static frames. Styles and scripts outside `<template>` are dropped.
-- Size the scene root with `inset: 0`, never hard-coded pixels; the canvas is `data-width` × `data-height`.
-- Keep ids unique across the assembled page (prefix them: `#intro-title`). A scene's timeline can't reach elements outside its file.
-- Use `fromTo`, not `from`, inside a scene: the host re-seeks the scene each time it shows, and `from` records its start state once, so it drifts on seek-back.
-- Never `add()` a scene's timeline to the root's; the runtime drives each scene itself, and nesting seeks it twice.
-
-## Attributes you'll use most
-
-| Attribute                                      | Meaning                                                                                             |
-| ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `data-start`, `data-duration`                  | Seconds, local to the file that declares the element                                                |
-| `data-track-index`                             | Studio lane only; paint order is CSS `z-index`                                                      |
-| `data-track-kind`                              | `graphics` or `captions` on scene hosts (video and audio come from the tag)                         |
-| `data-composition-src`, `data-variable-values` | Mount a scene file; per-mount variable values (a JSON object)                                       |
-| `data-media-start`                             | Offset into the source media (a trim)                                                               |
-| `data-playback-rate`                           | Constant speed, 0.1–10                                                                              |
-| `data-has-audio="true"`                        | A `<video>` keeps its own sound; a timed `<video>` with neither this nor `muted` fails lint         |
-| `data-volume`, `data-fade-in`, `data-fade-out` | Gain (1 = 0 dB, up to 3.98 = +12 dB) and edge fades; envelopes use `data-automation` (`/media-use`) |
-| `data-link`, `data-sync-origin`                | A video and audio edited as one (see Linked clips)                                                  |
-| `data-hidden`                                  | Hidden in preview and render; reversible                                                            |
-| `data-no-timeline`                             | On the root of a still composition: no timeline to wait for                                         |
-
-## Variables
-
-- Declare an array of `{id, type, label, default}`: the video's own on `index.html`'s `<html>`, a scene or block file's on that file's `<html>` (or root element), where they stay inside each mount. Types: `string` (`placeholder`, `maxLength`), `number` (`min`, `max`, `step`, `unit`), `color`, `boolean`, `enum` (`options: [{value, label}]`).
-- Bind without script: `data-var-text="id"`, `data-var-src="id"` (keep a real fallback `src` on media with audio), `var(--id)` in CSS; for logic, `window.__hyperframes.getVariables()` once at init.
-- Values are an object keyed by id. A host's `data-variable-values` sets one mount; Studio's Variables panel and batch renders set only the root's variables, so to vary a block, change its host's values. Variables can't change the root's `data-duration`.
-
-## Fonts
-
-- Bundled, so they resolve by name: Inter, Montserrat, Outfit, Nunito, Oswald, League Gothic, Archivo Black, Space Mono, IBM Plex Mono, JetBrains Mono, EB Garamond, Playfair Display, Source Code Pro, Noto Sans JP, Roboto, Open Sans, Lato, Poppins. Common system fonts (Helvetica, Arial, Times, Menlo and the like) are swapped for the nearest of these.
-- The bundle only has Latin text at a few weights per family (Inter: 400, 700, 900). The compiler still fetches each of these families from Google Fonts for the other weights and scripts, and caches the result in `~/.cache/hyperframes/fonts`.
-- Any other family needs `@font-face` in the file that uses it, or lint fails `font_family_without_font_face`: `src: url('assets/fonts/x.woff2')` for a file in the project (a capture's own fonts, or one you download there), or `local('Exact Name')` for a font installed on this machine.
-
-## Timing and the timeline
-
-- A clip shows over `[start, start + duration)`: an end state landing exactly on its end is never rendered.
-- Only a composition's root timeline is paused; timelines nested inside it are not. Never `tl.play()`.
-- A scene's clock starts at 0 at its host's `data-start`; media `data-start` is local to its composition. `<video>` / `<audio>` without `data-duration` play their full length; an `<img>` without one lasts 3 s.
-- A host's `data-duration` is the scene's slot: a shorter scene timeline holds its last frame, and a slot shorter than the video goes blank when it ends.
-- Root children with `data-start` are laid out full-frame by the runtime; an untimed full-bleed background needs `position: absolute; inset: 0` or it collapses to nothing.
-- A fill on the composition root is dropped when the video has shader transitions or HDR media; put it on a full-bleed child.
-- `data-start="intro + 0.5"` starts after `intro` ends (spaces required). A typo, a missing id or a cycle silently resolves to 0, so snapshot what you time this way.
-- A clip nested inside another timed element counts its `data-start` from the composition, not from that element, and shows only while that element shows. `timeline` lists it under its parent and warns `never visible` when the windows miss (`lint`: `nested_clip_never_visible`).
-- `npx hyperframes timeline --json` lists every clip by kind with `absStart`, `absEnd`, `file`, `src`, `playbackRate`, `nested`, `host` and `durationSource`: read it instead of opening every file. It reads one level of nesting (a deeper scene shows `children=unread`); `laneError` means a `data-automation` or `data-fx-chain` that doesn't parse.
-
-## Adding media
-
-Write what a Studio drop writes, so the clip behaves like one the person dropped:
-
-- `id`, `class="clip"`, `data-start` (the playhead or the requested time, never a silent 0) and `data-track-index`. Video with sound: `playsinline data-has-audio="true"`; silent footage: `muted playsinline`. Audio: `data-volume="1"`.
-- Images and video fill the frame: `position: absolute; left: 0; top: 0`, width and height equal to the canvas, `object-fit: contain`.
-- `z-index` is the number of top-level clips already in that file plus one.
-- Raise the root's `data-duration` to cover the new clip's end, or it never plays.
-
-## Linked clips
-
-Studio's Detach audio writes a muted `<video>` and an `<audio>` of the same file sharing `data-link` and `data-sync-origin`; Studio moves, trims, splits and deletes them as one.
-
-- Prefer one `<video data-has-audio="true">`; link only when the sound needs its own track, volume or effects.
-- Every member keeps the same `data-start`, `data-duration`, `data-media-start` and `data-playback-rate`; retime them all together.
-- Unlink by removing `data-link` from every member. Leave `data-sync-origin` alone while they are still one source.
-
-## Layout audit opt-outs
-
-`check` measures boxes at sampled times; `overflow: hidden` does not silence a finding. Use the narrowest opt-out:
-
-| Attribute                        | Silences                                                                                                                 |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `data-layout-allow-overflow`     | Overflow on the element and every descendant, including text-clipping checks: keep it on the smallest decorative wrapper |
-| `data-layout-bleed="true"`       | One intentional crop of primary text                                                                                     |
-| `data-layout-allow-overlap`      | Deliberate text layering, on that block only (not inherited)                                                             |
-| `data-layout-allow-occlusion`    | An element meant to cover text                                                                                           |
-| `data-layout-allow-caption-zone` | Intentional copy in the caption band                                                                                     |
-| `data-layout-ignore`             | A decorative element never audited                                                                                       |
-
-## Lint errors you'll meet first
-
-| Rule                                                   | Fix                                                                                                    |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
-| `video_missing_muted`                                  | A timed `<video>` gets `data-has-audio="true"` or `muted`                                              |
-| `gsap_css_transform_conflict`                          | Set the start inside the tween (`gsap.fromTo`) instead of a CSS `transform`                            |
-| `gsap_animates_clip_element`                           | Animate a child of the `.clip`, or its `opacity`                                                       |
-| `video_nested_in_timed_element`                        | Time the `<video>` or its wrapper, not both                                                            |
-| `media_missing_id`, `media_crossorigin_breaks_preview` | Give every `<audio>` an `id`; drop `crossorigin`                                                       |
-| `gsap_timeline_registered_before_async_build`          | Register the timeline at the end of the async callback                                                 |
-| `standalone_composition_wrapped_in_template`           | Only scene files use `<template>`                                                                      |
-| `subcomposition_root_styled_by_class`                  | Style a scene's root as `#root`                                                                        |
-| `subcomposition_blanks_before_host`                    | Make the scene's slot span the time it should show                                                     |
-| `clip_ends_past_root_duration`                         | Raise the root's `data-duration`                                                                       |
-| `linked_clips_out_of_sync`, `linked_clip_orphan`       | Retime every linked member together; unlink from all of them                                           |
-| `sweep_static`                                         | A 3 s+ video with no visible change: spread the motion, or mark a still composition `data-no-timeline` |
-| `missing_data_no_timeline`                             | A root or host with no timeline: add `data-no-timeline`, or every render waits 45 s                    |

package/skills/hyperframes/references/look.md

@@ -1,69 +0,0 @@
-# The look
-
-Left alone, the same brief comes out with the same look run after run, and banning that look only moves it to the next default. Outside input breaks it, in this order: the project's design spec, a real brand, a reference image or film the person gave you, the subject's own world. Settle it before the first scene, as numbers in the LOOK line (below).
-
-## The project's design spec
-
-Read the first of `frame.md`, `design.md`, `DESIGN.md` at the project root that exists; ignore the rest.
-
-- **Frontmatter is normative**: `colors`, `typography`, `spacing`, `components`. Quote hex values, families and weights exactly; never round or invent them.
-- **The prose is intent**: what the look is for, Do's and Don'ts. Follow it for judgment, not values.
-- **Brand, not layout**: hex, fonts, weight relationships and Do's and Don'ts are strict; type sizes, spacing, border weight and decoration are yours to scale for video. A 1px border or a 6% shadow from a web page vanishes on screen.
-
-## From a brand
-
-- A website: `npx hyperframes capture <url> --json` writes screenshots, the copy (`extracted/visible-text.txt`), images, logos, `extracted/tokens.json` (colours, fonts) and `extracted/design-styles.json` under its output folder. Look at the screenshots before choosing anything. A capture that exits non-zero, prints `ok: false` or writes `BLOCKED.md` failed: take no brand data from its partial files.
-- Figma: `npx hyperframes figma tokens <fileKey>` (`/figma`).
-- Images the person attached: take palette and type from what you see.
-
-Use the brand's own fonts when the capture shipped their files or they are bundled (`format.md`); otherwise download the family's `.woff2` into `assets/fonts/` with an `@font-face`, or pick the closest bundled family and say so.
-
-## From a reference
-
-A reference film or image gives its grammar, never its content: shot lengths, how titles enter and leave, the transitions, the palette roles, the type's scale and weight. Snapshot it next to yours (`snapshot --at <t,…> --against ref.mp4`) and write the grammar down, marking what you measured apart from what you guessed.
-
-## Presets
-
-The presets are slide-deck looks: use one when the person names it, or for a deck (`/slideshow`), never as the fallback for a film without a brand. Each folder in `../assets/frame-presets/` holds a `FRAME.md` spec, a `caption-skin.html` and a `frame-showcase.html` contact sheet. To use one, copy its `FRAME.md` to the project root as `frame.md`, then read it as above; its fonts that aren't bundled need `@font-face` files. The two HTML files are reference code: read them for treatments, never mount them.
-
-| Preset              | Look                                                                                           |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| `biennale-yellow`   | Museum catalogue: parchment, deep indigo ink, solar-yellow blooms, Instrument Serif, hairlines |
-| `blockframe`        | Loud neobrutalist: 4px black borders, hard shadows, candy pastels, Inter 900 caps              |
-| `blue-professional` | Consulting restraint: cream canvas, one cobalt accent, Space Grotesk + Inter, tinted cards     |
-| `bold-poster`       | Vintage editorial poster: Shrikhand tilted display, Baskerville, tomato red, double borders    |
-| `broadside`         | Protest poster: ink-black and fire-orange planes, giant lowercase Barlow 900, mono chrome      |
-| `capsule`           | Friendly editorial: every container a pill, cream, nine candy accents, Bodoni Moda             |
-| `cartesian`         | Quiet catalogue: warm-stone palette, Playfair + Inter, taupe hairline grid, compass rings      |
-| `cobalt-grid`       | Two-colour risograph: cream paper, cobalt ink, graph-paper grid, Newsreader serif              |
-| `code-editorial`    | Developer brand book: warm paper, scarce terracotta, EB Garamond, navy code surface            |
-| `coral`             | Bold magazine: coral, ink and cream planes at hard edges, Bebas Neue, giant numerals           |
-| `creative-mode`     | Sparse neobrutalist: cream, 4px ink borders, Archivo Black caps, rationed accents              |
-| `daisy-days`        | Picture book: charcoal outlines, sunny pastels, Fredoka One, hand-drawn ornaments              |
-| `editorial-forest`  | Literary: green, pink and cream, Source Serif display, mono chrome, flat paper                 |
-
-## The LOOK line
-
-With no design spec, the look is the LOOK line of `SPEC.md` (`spec.md`), taken from the brand, the reference or the subject itself: its era, its materials, where it would be shown. Every part is a number (hex, px, %, a named face and weight), the ground and the hero come from a medium rather than from effects, and the BANNED line keeps it off the defaults. Inter, Space Grotesk, Instrument Serif, Geist and JetBrains Mono are where generated design lands; use them when the brand does, not by default. Copy the palette and the faces into the root variables below.
-
-## Video facts
-
-- Full-screen linear gradients on dark grounds band under H.264; use a radial gradient, a solid fill or a solid plus a local glow.
-- An accent at 5% opacity disappears in compression: 15–25% for atmosphere, full saturation for the focal element.
-
-## Make it re-brandable
-
-Declare palette and fonts as variables on the root `<html>` and use them everywhere, so the person can re-brand from Studio's Variables panel:
-
-```html
-<html
-  data-composition-variables='[
-  {"id":"color-ground","type":"color","label":"Background","default":"<ground from the plan>"},
-  {"id":"color-ink","type":"color","label":"Text","default":"<ink from the plan>"},
-  {"id":"color-accent","type":"color","label":"Accent","default":"<accent from the plan>"},
-  {"id":"font-display","type":"string","label":"Display font","default":"<display face from the plan>"}
-]'
-></html>
-```
-
-Reference them as `var(--color-accent)`; point a registry item's colour and font variables at the same values.

package/skills/hyperframes/references/motion.md

@@ -1,95 +0,0 @@
-# Motion
-
-## Motion craft
-
-Measured frame by frame from the official HyperFrames launch films. These are defaults: a reference the person gave, or a Moment that does otherwise on purpose, wins for its own beat.
-
-- **Moves**: a fast move takes 0.3–0.6 s and carries motion blur on its own ease, peaking at its fastest frame: 6–12 px on text-sized elements, 15–20 px full-frame, horizontal-only on a horizontal move. One move is one tween.
-- **Render-time blur**: for fast 2D movers, `data-motion-blur="on"` on the composition root smears them along their real path in preview and render (opt-in; also `data-motion-blur-shutter` for a longer smear, 360 is strong; `-events="on"` when the motion is set from a timeline callback such as a `render(t)` function). Suggest it when the person asks for blur or a filmic look and the piece moves fast. It picks how to draw on its own: a cheap per-element filter for translation, the truer capture for spins and zooms; it works over WebGL and in any Chrome, and is off only for HDR and distributed renders. Opt a subtree out with `data-motion-blur="off"`, e.g. a seam that already carries its own blur. After adding it run `hyperframes check`. Guide: /guides/motion-blur.
-- **Arrive slow, leave clean**: long-tailed ease-outs on arrivals; landing takes longer than leaving. An exit is one smooth motion, never slide, stop, then leave. Entrances that are too snappy read as glitches; slowing the whole video by about a second often fixes it.
-- **Ease by role**: an arrival lands on a long tail (`expo.out`, `power4.out`), a camera move or a colour flood eases both ways (`power2.inOut`), a zoom through or an exit accelerates (`power3.in`). The same `power2.out` at 0.5 s on everything is the flat default that makes a film feel generated. Linear only for rotation, progress and constant speed that is the point.
-- **Springs** are named by damping ratio: 1.0 never bounces, 0.7-0.85 reads premium, 0.4-0.6 playful, under 0.3 a cartoon. Position and size may bounce; opacity and colour never do. GSAP's `elastic.out(1, 0.5)` and `back.out(1.4)` are the nearest built-ins; a closed-form spring of `t` keeps any frame renderable on its own.
-- **Exits** are 40-50% shorter than their entrances. **Overlap**: the next element starts when the previous is 30-50% done; fully sequential looks robotic, all at once looks cheap. **Stagger**: letters a frame apart, words 60-120 ms, list items 40-80 ms.
-- **Beat grid**: frames per beat = fps × 60 / BPM; compute each beat from its index and round it, never add a rounded beat repeatedly (at 128 BPM and 30 fps that drifts 2 frames in 32 beats). Cut on the beat, change the layout on the bar.
-- **Cuts**: cut at the fastest frame of a move, with matching direction and speed on both sides. A click into a new screen is a match cut on the click's rebound; the new screen comes in slightly large and settles.
-- **Titles**: a landed title is dead still; the motion moves to the next element, the camera or the world behind. Vary the entrance within a film, never a fade and slide-up for each:
-  - per word: `blur(6px)` → 0 and opacity 0 → 1 in 0.13 s, 0.067 s apart, no translate;
-  - per word from light grey to ink, 0.07–0.1 s apart, no position change;
-  - the whole line blurring in, 8 px → 0 in 0.13–0.2 s;
-  - per letter for a name, 0.1 s apart, opacity 0.3 → 1 with a slight blur;
-  - behind the subject: the title between the plate and a matte of the person;
-  - one word of the sentence rolling through options like a slot machine, about 0.1 s a roll.
-- **Holds**: a line the viewer must read holds about 0.5 s plus 0.3 s a word, the film's last line at least 2 s; a one- or two-word chapter line may hold 0.4 s. Then exit with a blur-out and fade of 0.13–0.25 s, word by word, or with the scene's move.
-- **Title size**: 4–9% of the frame height, one or two lines; quiet lines at 2.5–4% against hero words that fill 60–90% of the width. One highlighted word in the accent colour, which carries meaning.
-- **Rhythm**: contrast speeds. Montages cut every 0.13–0.8 s; a demo holds one framing for 7–10 s while the UI acts; shots average 1.8–3 s with motion inside them. Hold 0.3–0.75 s before the payoff, which plays at normal speed.
-- **Continuous motion that works**: the product's UI working, footage playing, a character acting, a 3D world turning, a slow orbit of a background stage (3–5° a second).
-- **Defaults that look generated**: breathing, floating or pulsing loops standing in for motion on titles and UI; titles that keep sliding or scaling after they land; a slow creeping scale on a title or a slow push late in a scene; bounce on UI; click rings; every scene entering the same way; every element fading and sliding up. A character's idle and overshoot are acting, not these (`types/character.md`).
-
-## Transitions with a cause
-
-Use 3–5 kinds in a film, each caused by something on screen. Hard cuts belong inside a scene (punch-ins); at most a third of the seams between beats are hard cuts, and worlds never crossfade into each other. Measured on the official films:
-
-| Transition               | How it is built                                                                                                                                                                     |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Zoom through a button    | the camera tracks to the button with blur (0.6 s), then the button scales from ~8% to ~250% of the frame in 0.35 s, strong ease-in; its fill becomes the next frame                 |
-| Object becomes the world | a pill or card grows past the frame in 0.65 s, ease-in-out, its radius shrinking; what was around it blurs ~15 px and fades in 0.3 s; the new content fades in while it still grows |
-| Morph                    | one container widens into the next (icon card → prompt box, ~110 → ~880 px in 0.2 s `power3.out`) with a horizontal blur 12 → 0                                                     |
-| Carry across             | the result shrinks 1 → 0.6 with blur peaking at 6 px mid-move and lands inside the next app as it builds around it                                                                  |
-| Colour flood             | the hero object stays while the whole ground changes colour in ~0.4 s `power2.inOut`                                                                                                |
-| Whip                     | a horizontal or vertical smear of 0.13–0.3 s; the arriving element lands blurred and sharpens in ~0.13 s                                                                            |
-| Iris from the click      | `clip-path: circle()` opens from the clicked point onto the next world in 0.15 s                                                                                                    |
-| Dip cut                  | the outgoing frame darkens ~40% for 3 frames before a hard cut, so the cut reads as meant                                                                                           |
-| Blur swap on one stage   | out: opacity → 0 with ~8 px blur in 0.13–0.2 s; in: blur → 0 in 0.13 s; the ground never cuts                                                                                       |
-
-Registry versions: `npx hyperframes catalog --tag transition --json`.
-
-| The person says        | Change                                                                         |
-| ---------------------- | ------------------------------------------------------------------------------ |
-| "too fast"             | Slow every zoom and pan to 0.7× of its speed, nothing else                     |
-| "speed this up"        | Speed the content and shorten the beat by the same amount; later beats move up |
-| "the titles move"      | Land them, then hold them dead still until they leave                          |
-| "it feels like slides" | Enter the next scene through an object on screen; cut a move mid-flight        |
-
-## The right mechanism
-
-| Request                                 | Mechanism                                                                                                                  |
-| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Punch-in, zoom, pan, Ken Burns, reframe | Tween `scale` and `x`/`y` on a wrapper inside the clip, never on the timed media element; chain the states on one timeline |
-| Crop or mask reveal                     | Tween `clip-path` or a mask on an inner wrapper; source time is untouched                                                  |
-| Constant speed change                   | `data-playback-rate` on the media, 0.1–10 (picture and pitch-preserved sound)                                              |
-| Speed ramp                              | A `rate` lane in `data-automation` on the media (`t` in clip seconds, `v` 0.1–10); it overrides the constant rate          |
-| Hold or freeze                          | Hold a final frame or a finished scene; a freeze mid-source needs a still exported first and placed as its own clip        |
-
-Ready-made moves: `npx hyperframes catalog --tag camera --json`, or `catalog --query "<the move>" --tag motion-primitive --json`.
-
-## Seeing motion
-
-The whole-film pass (beat sheet, cuts, phone width, the craft warnings) is `review.md`. For one move:
-
-- `npx hyperframes keyframes --json [--selector '#id'] [--runtime all]` lists keyframes and motion paths (GSAP, CSS, anime.js): property, time, value, ease.
-- `npx hyperframes keyframes --shot motion.png --selector '#id'` draws the real element's samples over time with its path (9 samples; `--samples N`). `--layout strip` for motion in place, `--from`/`--to` for one stretch, `--angle iso|top|side|'yaw,pitch'` for 3D, `--ghost` for a `<canvas>`.
-- `npx hyperframes snapshot --range 2,4 --frames 8` samples one stretch; `--composition <id>` samples one scene; `--at <t,…>` exact instants; `--zoom '#id'` a sharp crop; `--angle iso` depth and overlap.
-- Against a reference video: `snapshot --at <t,…> --against ref.mp4` writes a side-by-side sheet.
-- Assert intent instead of eyeballing it: a `<name>.motion.json` next to the composition makes `check` verify it on the seeked timeline, as errors (`motion_appears_late`, `motion_out_of_order`, `motion_off_frame`, `motion_frozen`):
-
-```json
-{
-  "assertions": [
-    { "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 },
-    { "kind": "before", "a": "#headline", "b": "#cta" },
-    { "kind": "staysInFrame", "selector": ".card" },
-    { "kind": "keepsMoving", "withinSelector": ".scene" }
-  ]
-}
-```
-
-## Common faults
-
-| Symptom                          | Usual cause                                                                                                                                    |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Blank or frozen scene            | Timeline registered before an async build finished, `visibility` tweened on a `.clip`, or a host id that differs from its scene's timeline key |
-| Stutter or drift between renders | Layout measured in `onUpdate`, `requestAnimationFrame` or clock time; two timelines on one property                                            |
-| Jump at a cut                    | Outgoing and incoming states differ at the seam: snapshot just before and after it                                                             |
-| Ease looks off at a handoff      | Speeds don't match across the seam: mirror the ease (`power3.in` out, `power3.out` in)                                                         |
-
-Studio's keyframe diamonds and motion-path handles rewrite the GSAP script in the composition file, so the person may have changed motion since you wrote it.

package/skills/hyperframes/references/overlays.md

@@ -1,39 +0,0 @@
-# Cards over talking-head footage
-
-Designed cards, lower thirds and split layouts over a person speaking. Placement numbers are for 1920×1080 and 1080×1920; scale others.
-
-## Where the video sits
-
-| Layout                       | Landscape (x, y, w×h) | Portrait (x, y, w×h) |
-| ---------------------------- | --------------------- | -------------------- |
-| Split, video beside the card | 960, 0, 960×1080      | 0, 960, 1080×960     |
-| Stack, video above           | 14, 14, 1892×548      | 0, 0, 1080×844       |
-| Overlay                      | full frame            | full frame           |
-
-Picture-in-picture, 28 px from the edges (bottom-right: y = H − h − 28):
-
-| Canvas    | Source | Rectangle         |
-| --------- | ------ | ----------------- |
-| Landscape | 16:9   | 1432, 28, 460×258 |
-| Landscape | 9:16   | 1644, 28, 248×440 |
-| Portrait  | 16:9   | 690, 28, 360×203  |
-| Portrait  | 9:16   | 738, 28, 312×555  |
-
-- Card zones: a lower third is the bottom 30%; a side panel the right 42% (landscape) or bottom 40% (portrait). Glass card slots: 48, 460, 660×540 landscape; 24, 1280, 1032×564 portrait.
-- Portrait type is landscape × 1.3 (titles × 1.35, stats × 1.4); padding drops from 40–64 px to 24–36 px.
-- Size a rectangle to its source's aspect: `object-fit: cover` crops a portrait source in a landscape box.
-
-## Timing
-
-- Cards fade in over 0.4 s (`power2.out`) and out over 0.35 s (`power2.in`). Re-frame the video (0.5–0.7 s) only in a gap between cards; move it with transforms on a wrapper, not `left`/`top`/`width`/`height`.
-- A static card goes dead after about 8 s; past about 15 s it needs a staged reveal. As a starting density: one card per 6–8 s under a minute, 8–12 s up to 3 min, 12–20 s up to 10 min.
-- A transcript's last word can end past the media: clamp card ends and the root `data-duration` to the file's ffprobe length, or the render ends in black.
-
-## Pitfalls
-
-- Lower-third, overlay and picture-in-picture scenes need a transparent root, or they hide the speaker.
-- Glass over bright footage goes white on white: put a dark scrim behind it (about `rgba(0,0,0,.55)` fading out from the top, `.72` at the bottom) and a dark glass base such as `rgba(15,16,22,.78)` with `backdrop-filter: blur(22px)`.
-- More than 3 timed elements on one track warns `timeline_track_too_dense`: give each chapter its own sub-composition.
-- Footage with keyframes more than about 1 s apart freezes on seek: re-encode with `-g <fps>`.
-
-Text behind the speaker (a caption between the footage and a cutout of the person): `captions.md`.