dsh-hyperframes 0.3.1 → 0.4.0

package/skills/hyperframes-creative/references/house-style.md

@@ -6,7 +6,7 @@ Creative direction for compositions when no design spec (`frame.md` or `design.m
 
 1. **Interpret the prompt.** Generate real content. A recipe lists real ingredients. A HUD has real readouts.
 2. **Pick a palette.** Light or dark? Declare bg, fg, accent before writing code.
-3. **Pick typefaces.** Run the font discovery script in [references/typography.md](references/typography.md) — or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.
+3. **Pick typefaces.** Run the font discovery script in [typography.md](typography.md) — or pick a font you already know that fits the theme. The script broadens your options; it's not the only source.
 
 ## Lazy Defaults to Question
 
@@ -18,7 +18,7 @@ These patterns are AI design tells — the first thing every LLM reaches for. If
 - Pure `#000` or `#fff` (tint toward your accent hue instead)
 - Identical card grids (same-size cards repeated)
 - Everything centered with equal weight (lead the eye somewhere)
-- Banned fonts (see [references/typography.md](references/typography.md) for full list)
+- Banned fonts (see [typography.md](typography.md) for full list)
 
 If the content genuinely calls for one of these — centered layout for a solemn closing, cards for a real product UI mockup, a banned font because it's the perfect thematic match — use it. The goal is intentionality, not avoidance.
 
@@ -48,26 +48,26 @@ All decoratives should have slow ambient GSAP animation — breathing, drift, pu
 
 ## Motion
 
-See [references/motion-principles.md](references/motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.
+See [motion-principles.md](motion-principles.md) for full rules. Quick: 0.3–0.6s, vary eases, combine transforms on entrances, overlap entries.
 
 ## Typography
 
-See [references/typography.md](references/typography.md) for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.
+See [typography.md](typography.md) for full rules. Quick: 700-900 headlines / 300-400 body, serif + sans (not two sans), 60px+ headlines / 20px+ body.
 
 ## Palettes
 
 Declare one background, one foreground, one accent before writing HTML.
 
-| Category          | Use for                                       | File                                                       |
-| ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
-| Bold / Energetic  | Product launches, social media, announcements | [palettes/bold-energetic.md](palettes/bold-energetic.md)   |
-| Warm / Editorial  | Storytelling, documentaries, case studies     | [palettes/warm-editorial.md](palettes/warm-editorial.md)   |
-| Dark / Premium    | Tech, finance, luxury, cinematic              | [palettes/dark-premium.md](palettes/dark-premium.md)       |
-| Clean / Corporate | Explainers, tutorials, presentations          | [palettes/clean-corporate.md](palettes/clean-corporate.md) |
-| Nature / Earth    | Sustainability, outdoor, organic              | [palettes/nature-earth.md](palettes/nature-earth.md)       |
-| Neon / Electric   | Gaming, tech, nightlife                       | [palettes/neon-electric.md](palettes/neon-electric.md)     |
-| Pastel / Soft     | Fashion, beauty, lifestyle, wellness          | [palettes/pastel-soft.md](palettes/pastel-soft.md)         |
-| Jewel / Rich      | Luxury, events, sophisticated                 | [palettes/jewel-rich.md](palettes/jewel-rich.md)           |
-| Monochrome        | Dramatic, typography-focused                  | [palettes/monochrome.md](palettes/monochrome.md)           |
+| Category          | Use for                                       | File                                                          |
+| ----------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| Bold / Energetic  | Product launches, social media, announcements | [palettes/bold-energetic.md](../palettes/bold-energetic.md)   |
+| Warm / Editorial  | Storytelling, documentaries, case studies     | [palettes/warm-editorial.md](../palettes/warm-editorial.md)   |
+| Dark / Premium    | Tech, finance, luxury, cinematic              | [palettes/dark-premium.md](../palettes/dark-premium.md)       |
+| Clean / Corporate | Explainers, tutorials, presentations          | [palettes/clean-corporate.md](../palettes/clean-corporate.md) |
+| Nature / Earth    | Sustainability, outdoor, organic              | [palettes/nature-earth.md](../palettes/nature-earth.md)       |
+| Neon / Electric   | Gaming, tech, nightlife                       | [palettes/neon-electric.md](../palettes/neon-electric.md)     |
+| Pastel / Soft     | Fashion, beauty, lifestyle, wellness          | [palettes/pastel-soft.md](../palettes/pastel-soft.md)         |
+| Jewel / Rich      | Luxury, events, sophisticated                 | [palettes/jewel-rich.md](../palettes/jewel-rich.md)           |
+| Monochrome        | Dramatic, typography-focused                  | [palettes/monochrome.md](../palettes/monochrome.md)           |
 
 Or derive from OKLCH — pick a hue, build bg/fg/accent at different lightnesses, tint everything toward that hue.

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

@@ -21,7 +21,7 @@ Structure is value-first; the **voice** stays whatever the workflow prescribes (
 
 ## 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):
+When Step 3 presents the plan (a checkpoint gate — `hyperframes/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:
@@ -34,6 +34,8 @@ When Step 3 presents the plan (a checkpoint gate — `hyperframes-core/reference
 
 - Recommendations keep their receipts (brief-contract § 3): the archetype choice, the beat count, and any beat the user might question each state their basis.
 
+How to write the storyboard itself, and the `storyboard.html` page it is reviewed on, is `storyboard-recipe.md`.
+
 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

package/skills/hyperframes-creative/references/storyboard-recipe.md

@@ -0,0 +1,57 @@
+# Storyboard recipe — plan a video like the launch films
+
+Applies wherever a run plans on a storyboard (`storyboard: yes` in `brief-contract.md`). This file owns **how to make the storyboard**: what goes in it, and the one HTML page the user reviews. `review-loop.md` owns when the user is asked; `storyboard-format.md` owns the `STORYBOARD.md` file the scripts parse; `story-spine.md` owns the order of the story. The method is distilled from the shipped launch films' storyboards (a header, a named spine, a beat list, a contact sheet, a review round) and how their handoffs describe them, plus a few rules (the held frame, the slideshow/screensaver bans, the caption keep-out) that show up consistently in the wider storyboard corpus even where a given launch film omits them. Nothing here is a Studio feature: the agent writes the storyboard, the user reads it in chat and in a browser.
+
+## 1. Open with the decisions, before any beat
+
+Message, audience, arc and format go in the `STORYBOARD.md` frontmatter (`storyboard-format.md`); the rest go in sections above the first `## Frame` heading. Frame packets take everything after a frame heading to the next one, so a section placed after the last frame leaks into that frame's packet. Repeat the first three in the chat proposal:
+
+- **Message**: one sentence, written as a claim, not a topic ("Close isn't final", not "About the inspector").
+- **Audience and arc**: who watches, and the arc named in one line (pain → turn → proof → logo, or the workflow's own archetype).
+- **Format**: aspect, target length, voiceover yes/no, music yes/no. Caption keep-out (content in the top ~83% when captions run).
+- **The spine**: the one device that threads every beat, named now, not discovered while building (a persistent window, a silent button that finally has sound, one background that leads every transition).
+- **Brand, from a capture**: palette by role with hex, three type roles (display, sans, mono) with sizes, radii and easings, each token noting where it came from. Take them from the real site or product, never from memory; `frame.md` holds them.
+- **Bans**: a short per-video "do not" list (no glow, no side-by-side explainer layouts, no fake product UI, no static endcard). Name two motion failures to avoid: the slideshow (every beat a fresh card) and the screensaver (motion that says nothing).
+- **Held frame**: allocate one beat on purpose where nothing moves and the line lands.
+
+## 2. The beat list
+
+One beat per idea, one focus per beat. Give each beat a short semantic name that will also be its composition filename.
+
+| Field       | Rule                                                                                                                                    |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Heading     | `NN — Name (start–end, ~dur)`, absolute times. Sum the durations and state the total; check it against the target length by arithmetic. |
+| Beat length | 1.5–3.5 s. A beat that must be read gets ~3 s; a beat that only hands off gets 1.5–2 s; a line of 5–7 words gets 2–2.5 s.               |
+| On screen   | What is visible, in concrete terms (the object, its count, its position), with every on-screen word verbatim in quotes.                 |
+| Voiceover   | Verbatim, or `onscreen` for silent films. Reveals land on the word or beat cue that names them.                                         |
+| Hero prop   | The object that persists, and the beat where it returns (callback). A callback beat states which earlier beat it answers.               |
+| Motion      | Named moves with easing and duration, from a small vocabulary. First visible motion within 0.2 s of the beat starting.                  |
+| Seam out    | The named transition into the next beat and its direction. One direction rule for the whole film (leftward is the default).             |
+| Audio cue   | Sound effect or music cue with its time, when the film has sound.                                                                       |
+| Constraint  | At least one explicit "no …" per beat that could go generic.                                                                            |
+| Why         | The beat's job in the story, traced to the message. A beat whose why cannot be traced is cut.                                           |
+
+Real product proof is real: a captured screen, the real command output, or a labelled placeholder beat that holds the slot. Never draw a vendor's UI in DOM. Where the film depicts something real, add a truthfulness line saying what is real.
+
+Craft devices that make a storyboard specific are taught with examples in `docs/prompting/storyboards.mdx` (breather, callback, two-color discipline) and `docs/prompting/motion.mdx` (hero prop, accumulation); use them by name.
+
+## 3. `storyboard.html`: the page the user reviews
+
+Write one self-contained HTML file in the project root, `storyboard.html`, from `STORYBOARD.md`. Tell the user the path and to open it in a browser. It is the review surface, and it must be beautiful enough to judge the film from.
+
+- **Header**: title with a version (`v1`), one-line dek, and a tag with resolution, length and beat count.
+- **Grid**: three columns of 16:9 cells (`aspect-ratio: 16 / 9`, `container-type: inline-size`, sizes in `cqw` so the sheet matches the build), chronological, grouped under an act bar when there are acts.
+- **Each cell** carries `id="frame-NN"` (the build reads its layout from there) and shows the beat's key moment drawn with the real words in the real fonts and brand colors, plain shapes for panels, charts and media, one accent on the focal. Then a label row (`NN · NAME` left, `id · start–end` right), a note that says what moves first and which way the seam goes (bold lead-in, one or two sentences), and a small chip naming the seam.
+- **Two closing cells**: a seam map (every seam on one strip) and a tokens cell (palette, type roles, bans).
+- **No motion, no scripts, no external assets.** Fonts are local `@font-face` or a system stack; images are inlined or relative. It must open from `file://`.
+
+A sketch is a few dozen lines of HTML per cell; the whole sheet lands in minutes. Sketch fidelity is the point: a reviewer reacts to placement, hierarchy and copy, which is why the build later dresses the layout and never redraws it.
+
+## 4. The review round
+
+1. Present the chat proposal (`story-spine.md` § 3), then the sheet.
+2. Record the user's notes verbatim under `## Changes from v1` and unresolved questions under `## Still open` (above the first frame), then bump the version and revise **only the beats named**.
+3. Repeat until the user says the layout is locked, then list what is locked under `## Locked` (above the first frame, same reason as § 1). Build only after the lock.
+4. When the build lands, the compositions are the truth: regenerate the timing table from `index.html` (and the transcript when there is voiceover) and update `STORYBOARD.md` and `storyboard.html` to match, because every launch film drifted from its storyboard. State the final length.
+
+Do not render until asked.

package/skills/hyperframes-creative/references/typography.md

@@ -60,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.** 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.
+- **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/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/scripts/package-loader.mjs

@@ -12,7 +12,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { basename, delimiter, dirname, join, parse, resolve } from "node:path";
+import { basename, delimiter, dirname, join, parse, resolve, win32 as win32Path } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -339,23 +339,54 @@ function ancestors(start) {
   return dirs;
 }
 
+export function resolveNpmSpawnCommand(
+  args,
+  platform = process.platform,
+  env = process.env,
+  nodeExecPath = process.execPath,
+  pathExists = existsSync,
+) {
+  if (platform !== "win32") {
+    return { cmd: "npm", args, opts: { stdio: "inherit" } };
+  }
+
+  const bundledNpmCli = win32Path.join(
+    win32Path.dirname(nodeExecPath),
+    "node_modules",
+    "npm",
+    "bin",
+    "npm-cli.js",
+  );
+  const npmCli = [env.npm_execpath, bundledNpmCli].find(
+    (candidate) => candidate && pathExists(candidate),
+  );
+  if (!npmCli) return null;
+  return {
+    cmd: env.npm_node_execpath || nodeExecPath,
+    args: [npmCli, ...args],
+    opts: { stdio: "inherit", windowsHide: true },
+  };
+}
+
 function bootstrapWithNpmInstall(packageNames) {
   const installRoot = mkdtempSync(join(tmpdir(), "hyperframes-skill-deps-"));
-  const installResult = spawnSync(
-    process.platform === "win32" ? "npm.cmd" : "npm",
-    [
-      "install",
-      "--silent",
-      "--no-audit",
-      "--no-fund",
-      "--ignore-scripts",
-      "--no-save",
-      "--prefix",
-      installRoot,
-      ...packageNames,
-    ],
-    { stdio: "inherit" },
-  );
+  const npmArgs = [
+    "install",
+    "--silent",
+    "--no-audit",
+    "--no-fund",
+    "--ignore-scripts",
+    "--no-save",
+    "--prefix",
+    installRoot,
+    ...packageNames,
+  ];
+  const npmCommand = resolveNpmSpawnCommand(npmArgs);
+  if (!npmCommand) {
+    rmSync(installRoot, { recursive: true, force: true });
+    throw new Error("Could not locate npm-cli.js for dependency bootstrap on Windows.");
+  }
+  const installResult = spawnSync(npmCommand.cmd, npmCommand.args, npmCommand.opts);
 
   if (installResult.error) throw installResult.error;
   if (installResult.status !== 0) {

package/skills/hyperframes-creative/scripts/package-loader.test.mjs

@@ -5,10 +5,62 @@ import { copyFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { resolveNpmSpawnCommand } from "./package-loader.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ENV = "HYPERFRAMES_SKILL_PKG_VERSION";
 
+test("resolveNpmSpawnCommand routes Windows npm through node and npm-cli.js", () => {
+  const npmCli = "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js";
+  const node = "C:\\Program Files\\nodejs\\node.exe";
+  const resolved = resolveNpmSpawnCommand(
+    ["install", "@hyperframes/producer@0.7.55", "value & calc"],
+    "win32",
+    { npm_execpath: npmCli, npm_node_execpath: node },
+    node,
+    (path) => path === npmCli,
+  );
+
+  assert.deepEqual(resolved, {
+    cmd: node,
+    args: [npmCli, "install", "@hyperframes/producer@0.7.55", "value & calc"],
+    opts: { stdio: "inherit", windowsHide: true },
+  });
+  assert.equal(resolved.opts.shell, undefined);
+});
+
+test("resolveNpmSpawnCommand finds npm-cli.js beside node for direct Windows runs", () => {
+  const node = "C:\\Program Files\\nodejs\\node.exe";
+  const npmCli = "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js";
+  const resolved = resolveNpmSpawnCommand(
+    ["install", "@hyperframes/producer@0.7.55"],
+    "win32",
+    {},
+    node,
+    (path) => path === npmCli,
+  );
+
+  assert.equal(resolved?.cmd, node);
+  assert.deepEqual(resolved?.args, [npmCli, "install", "@hyperframes/producer@0.7.55"]);
+});
+
+test(
+  "resolveNpmSpawnCommand launches the installed npm CLI on Windows",
+  { skip: process.platform !== "win32" },
+  () => {
+    const resolved = resolveNpmSpawnCommand(["--version"]);
+    assert.ok(resolved);
+
+    const result = spawnSync(resolved.cmd, resolved.args, {
+      encoding: "utf8",
+      windowsHide: true,
+    });
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout.trim(), /^\d+\./);
+  },
+);
+
 // (a) env override wins — no ancestor lookup, exact version echoed back.
 test("hyperframesPackageSpec: env override wins", async () => {
   const prev = process.env[ENV];

package/skills/hyperframes-keyframes/SKILL.md

@@ -9,6 +9,8 @@ description: >
   general video planning.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 # HyperFrames Keyframes
 
 Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.
@@ -34,8 +36,8 @@ fades use `/hyperframes-audio`.
 | Crop and mask reframe                   | Interpolate `clip-path` or a mask on an inner visual wrapper to crop/reframe without changing source time. Polygon keyframes can form a polygon/mask transition.                                                            |
 | Directional wipe cut or iris/reveal cut | Animate a mask/clip boundary across overlapping visual clips; `/hyperframes-animation` owns the handoff choreography.                                                                                                       |
 | Split-screen handoff                    | Keep both visual clips placed by core, then keyframe their inner crop/mask wrappers and divider geometry.                                                                                                                   |
-| Constant source retime                  | `/hyperframes-core` owns normalized `data-playback-rate` (`0.1..5`) for render-safe picture and pitch-preserved sound. It is constant for the whole media element.                                                          |
-| Source speed ramps                      | Not supported: there is no time-varying playback-rate envelope. Preprocess a derived media asset, then place it through core.                                                                                               |
+| Constant source retime                  | `/hyperframes-core` owns normalized `data-playback-rate` (`0.1..10`) for render-safe picture and pitch-preserved sound. It is constant for the whole media element.                                                         |
+| Source speed ramps                      | A `rate` lane in `data-automation` on the `<video>`/`<audio>` (`t` in clip seconds, `v` 0.1..10, log interpolation); it wins over the constant rate.                                                                        |
 | Freeze / hold                           | A visual pose, final source frame, or finished sub-composition can hold. Arbitrary mid-source freeze is not supported; preprocess a still/derived segment, place it as its own clip, then resume with another source range. |
 
 When editing picture and sound together, load `/hyperframes-core`, this skill for

package/skills/hyperframes-registry/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: hyperframes-registry
-description: Install, discover, and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).
+description: Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 # HyperFrames Registry
 
 The registry provides reusable blocks and components installable via `hyperframes add <name>`.

package/skills/hyperframes-registry/references/contributing.md

@@ -89,6 +89,12 @@ Apply the correct template based on type. See [templates.md](templates.md) for c
 
 #### All types
 
+- **Load files the block ships through `__hyperframes.assetUrl("assets/...")`** whenever a script
+  builds the path (textures, fonts, JSON, models). Attributes like `src` and `href` are rebased
+  when the block is mounted; strings in a script are not, so a bare `"assets/..."` 404s once the
+  block lives under `compositions/<name>/`. A separate `.js` file gets the URLs from the block's
+  inline script. A block whose assets install to the project's own `assets/` (target
+  `compositions/<name>.html`) keeps plain project-root paths; `assetUrl` would look beside the file.
 - **Placeholder content is monochrome** — read
   [placeholder-material.md](placeholder-material.md) before choosing a single colour. Stand-in
   screens, images, cards, avatars, logos and chart series use four alpha steps of the
@@ -118,9 +124,9 @@ hyperframes snapshot --at "1.0,3.0,5.0,7.0"
 npx hyperframes publish
 ```
 
-**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:
+**Catalog preview image** — For the default PNG preview, save your snapshot at `docs/images/catalog/{kind}/{name}.png` in the repository checkout (`{kind}` is `blocks` or `components`). After upload, the catalog serves it from `https://static.heygen.ai/hyperframes-oss/docs/images/catalog/{kind}/{name}.png`. If `registry-item.json` declares `preview`, the card uses its `poster` URL; a `preview` without `poster` has no image fallback.
 
-- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
+- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` from the repository root (requires AWS profile `engineering-767398024897`)
 - **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.
 
 ### Step 6: Ship

package/skills/hyperframes-registry/references/discovery.md

@@ -1,5 +1,7 @@
 # Registry discovery
 
+<!-- registry-items: allow=data-composition-id,data-start,data-track-index -->
+
 ## Use the catalog command first
 
 ```bash
@@ -54,7 +56,7 @@ Where `<type-dir>` is `examples`, `blocks`, or `components`.
 
 ### Blocks
 
-For an always-current list run `npx hyperframes catalog --type block`. The tables below group the 97 blocks by category. **Block name ≠ shader name**: shader-transition blocks (e.g. `domain-warp-dissolve`) wrap a HyperShader runtime whose internal name omits the `-dissolve`/`-warp` suffix — see the showcase HTML installed alongside the block for the canonical name.
+For an always-current list run `npx hyperframes catalog --type block`. **The search is the source of truth; the tables below are a hand-maintained sample and under-cover by design** — they group 97 of the registry's 180 blocks by category, so a block missing from them is not evidence the registry lacks it. Only an empty `npx hyperframes catalog --query "<what you want>" --json` is that evidence. Do not grow these tables toward the full set; search instead. **Block name ≠ shader name**: shader-transition blocks (e.g. `domain-warp-dissolve`) wrap a HyperShader runtime whose internal name omits the `-dissolve`/`-warp` suffix — see the showcase HTML installed alongside the block for the canonical name.
 
 #### Shader transitions (14)
 
@@ -101,15 +103,13 @@ Showcase compositions grouping multiple CSS / GSAP transition styles by family.
 
 WebGPU + html-in-canvas frosted-glass surfaces. **Require Brave / Chrome canary** with WebGPU enabled — set `PRODUCER_HEADLESS_SHELL_PATH` to point at the browser; engine auto-passes `--enable-unsafe-webgpu`. See `/hyperframes-animation` → `adapters/typegpu.md`.
 
-| Name                          | Description                                                                             |
-| ----------------------------- | --------------------------------------------------------------------------------------- |
-| `ios26-liquid-glass`          | 3D iPhone (GLTF) + iOS 26 home screen, glass app icons, shader wallpaper, notifications |
-| `macos-tahoe-liquid-glass`    | 3D MacBook (GLTF) + macOS Tahoe-style desktop, glass menu bar, Finder, dock             |
-| `liquid-glass-widgets`        | Frosted stat cards, showcase panel, pill chips over aurora shader                       |
-| `liquid-glass-notification`   | Frosted notification cards floating over aurora shader                                  |
-| `liquid-glass-context-menu`   | Frosted context-menu panel drifting over aurora shader                                  |
-| `liquid-glass-media-controls` | Frosted media-control panels spreading over aurora shader                               |
-| `vfx-liquid-glass`            | Bare VFX composition shell for liquid-glass effects                                     |
+| Name                        | Description                                                                             |
+| --------------------------- | --------------------------------------------------------------------------------------- |
+| `ios26-liquid-glass`        | 3D iPhone (GLTF) + iOS 26 home screen, glass app icons, shader wallpaper, notifications |
+| `macos-tahoe-liquid-glass`  | 3D MacBook (GLTF) + macOS Tahoe-style desktop, glass menu bar, Finder, dock             |
+| `liquid-glass-widgets`      | Frosted stat cards, showcase panel, pill chips over aurora shader                       |
+| `liquid-glass-notification` | Frosted notification cards floating over aurora shader                                  |
+| `vfx-liquid-glass`          | Bare VFX composition shell for liquid-glass effects                                     |
 
 #### VFX (6)
 
@@ -177,24 +177,11 @@ Platform-recognizable UI overlays. Stamp on top of a beat or use as a beat close
 
 A code/terminal window that **types a code or shell session per-character**. Theme = visual chrome only; structure, wiring, and install are identical across all 24 — pick one by name, wire it like any block (`data-composition-id` + `data-start` + `data-track-index`, see `wiring-blocks.md`). Two chrome families:
 
-**VS Code workbench (12)** — full editor chrome (activity bar, sidebar, tabs, integrated terminal, status bar). Theme variants: `code-snippet-dark-2026`, `code-snippet-dark-modern`, `code-snippet-dark-plus`, `code-snippet-light-2026`, `code-snippet-light-modern`, `code-snippet-light-plus`, `code-snippet-high-contrast`, `code-snippet-high-contrast-light`, `code-snippet-monokai`, `code-snippet-solarized-light`, `code-snippet-visual-studio-dark`, `code-snippet-visual-studio-light`.
-
 **Apple Terminal (12)** — macOS Terminal.app window typing a shell session. Profile = window colors:
 
-| Name                                         | Look                                     |
-| -------------------------------------------- | ---------------------------------------- |
-| `code-snippet-apple-terminal-basic`          | White bg, black text                     |
-| `code-snippet-apple-terminal-clear-dark`     | Semi-transparent dark bg                 |
-| `code-snippet-apple-terminal-clear-light`    | Semi-transparent light bg                |
-| `code-snippet-apple-terminal-grass`          | Black bg, green text                     |
-| `code-snippet-apple-terminal-homebrew`       | Black bg, bright green text, lime cursor |
-| `code-snippet-apple-terminal-man-page`       | Pale yellow bg, black text               |
-| `code-snippet-apple-terminal-novel`          | Warm parchment bg, dark brown text       |
-| `code-snippet-apple-terminal-ocean`          | Deep blue bg, white text                 |
-| `code-snippet-apple-terminal-pro`            | Black bg, grey text, lime cursor         |
-| `code-snippet-apple-terminal-red-sands`      | Deep red bg, sandy text                  |
-| `code-snippet-apple-terminal-silver-aerogel` | Dark grey bg, white text                 |
-| `code-snippet-apple-terminal-solid-colors`   | Deep purple bg, white text               |
+| Name                              | Look                             |
+| --------------------------------- | -------------------------------- |
+| `code-snippet-apple-terminal-pro` | Black bg, grey text, lime cursor |
 
 #### Code Animations (9)
 
@@ -202,14 +189,13 @@ The richer, motion-first counterpart to the static `code-snippet-*` window theme
 
 **DOM / text reveal (6):**
 
-| Name                  | Description                                                                                                                |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `code-typing`         | Token-streamed typing reveal, caret tracks the frontier (no CSS animation) — live-coding on screen                         |
-| `code-diff`           | An edit shown as a colored diff: removed lines collapse red, added expand green — before/after at line level               |
-| `code-morph`          | One snippet transforms into another, tokens glide between positions (Shiki Magic Move) — a refactor / one state to another |
-| `code-highlight`      | A highlight band sweeps a target line while surrounding context dims — spotlight one line                                  |
-| `code-scroll`         | Camera scrolls a long file to center + spotlight a target line — walk through a real module                                |
-| `code-snippet-flight` | Discrete snippets fly in from the side and assemble into a stacked program (block-level FLIP)                              |
+| Name             | Description                                                                                                                |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `code-typing`    | Token-streamed typing reveal, caret tracks the frontier (no CSS animation) — live-coding on screen                         |
+| `code-diff`      | An edit shown as a colored diff: removed lines collapse red, added expand green — before/after at line level               |
+| `code-morph`     | One snippet transforms into another, tokens glide between positions (Shiki Magic Move) — a refactor / one state to another |
+| `code-highlight` | A highlight band sweeps a target line while surrounding context dims — spotlight one line                                  |
+| `code-scroll`    | Camera scrolls a long file to center + spotlight a target line — walk through a real module                                |
 
 **GPU / WebGL hero reveals (3):** heavier, for a title-card / hero code moment.
 

package/skills/hyperframes-studio/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: hyperframes-studio
+description: >
+  Use when building or editing a HyperFrames project that people open in
+  Studio: how the timeline should be laid out so it reads well (one caption
+  track, one element kind per track, every scene a sub-composition) and where
+  captions and key content may sit (safe zones). Don't use for how to perform an
+  individual edit (split, trim, retime, volume, copy, swap): that is
+  `creator-editing-recipes.md` in `/hyperframes-core`.
+---
+
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
+# HyperFrames Studio conventions
+
+Studio draws one timeline row per top-level element. A project that follows the
+rules below opens as a short, readable timeline; one that does not opens as a wall
+of unlabeled rows the user cannot edit. These are conventions for what to build.
+For how to change a clip, follow `/hyperframes-core` `references/creator-editing-recipes.md`
+and never invent a different form of the same edit.
+
+## 1. Every scene is a sub-composition
+
+The root composition holds only timed hosts, media and audio. Any scene with nested
+structure (a div containing children, a title with a subtitle, a chart) is its own
+file loaded with `data-composition-src`, wiring in
+`references/sub-compositions.md`.
+
+Nested markup left inside the root does not become a row of its own. It hides inside
+one opaque row that cannot be trimmed or moved part by part.
+
+Author as if a structure lint rejects any violation.
+
+## 2. One caption track
+
+- All captions live on one track: a single sub-composition host (one `data-track-index`)
+  marked `data-track-kind="captions"` that carries every caption group in order.
+- Never one row per caption group, and never captions mixed onto a track with
+  another kind.
+- Word-timing rules are unchanged: see `/embedded-captions` and the `caption_*` lint rules.
+
+## 3. One element kind per track
+
+Group by kind so each row is one thing the user can select, mute or drag as a set.
+
+| Kind                                    | `data-track-kind`      |
+| --------------------------------------- | ---------------------- |
+| Base video / A-roll                     | `video` (from the tag) |
+| Scenes, overlays, graphics              | `graphics`             |
+| Captions                                | `captions`             |
+| Audio (voiceover, music, sound effects) | `audio` (from the tag) |
+
+Put `data-track-kind` on sub-composition hosts. Video and audio kinds come from the tag, so
+`<video>` and `<audio>` need no attribute. Give each kind its own `data-track-index`; the number
+is display only; it never changes what renders on top. Use CSS for
+layering.
+
+## 4. Safe zones
+
+Any ruler or safe-box overlay lives in the preview pane, never inside the composition, so
+do not add guide elements to the HTML.
+Both framings (wide and vertical) use the same two safe boxes, Premiere's defaults. The preview
+toggle draws them with a tick at the midpoint of every edge. Source:
+`ACTION_SAFE_PERCENT` and `TITLE_SAFE_PERCENT` in `packages/studio/src/utils/previewSafeMargins.ts`.
+
+| Box         | Share of the frame | Inset on every edge |
+| ----------- | ------------------ | ------------------- |
+| Action-safe | 90%                | 5%                  |
+| Title-safe  | 80%                | 10%                 |
+
+- Safe margins: everything visible stays inside the action-safe box (90%), and captions and key content stay inside the title-safe box (80%).
+- Two-up and 50/50 layouts keep each half's content inside the title-safe box.
+
+## Checking your work
+
+Run `hyperframes lint` and fix every finding. Then open the project in Studio and
+check that the timeline shows a base row, one row per scene host, one caption row and the audio rows.

package/skills/media-use/SKILL.md

@@ -3,30 +3,32 @@ name: media-use
 description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.
 ---
 
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+
 # media-use
 
 The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.
 
-First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `node <SKILL_DIR>/scripts/resolve.mjs --doctor`. Setup and providers: `references/setup-providers.md`.
+First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
 
 ## Resolve — the one verb
 
 ```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
+npx hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>
 ```
 
 Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search noise stays on disk.
 
-| Type    | One-line intent                                                                     |
-| ------- | ----------------------------------------------------------------------------------- |
-| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                      |
-| `sfx`   | sound effects (bundled 19-file library + catalog)                                   |
-| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                             |
-| `icon`  | icons, symbols (transparent)                                                        |
-| `logo`  | official brand marks (svgl → simple-icons → GitHub avatar → favicon; never redrawn) |
-| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro)                       |
-| `grade` | measured correction candidate; broad polish/stylization follows Media Treatments    |
-| `lut`   | user-provided or explicitly chosen reusable validated `.cube` file                  |
+| Type    | One-line intent                                                                  |
+| ------- | -------------------------------------------------------------------------------- |
+| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                   |
+| `sfx`   | sound effects (bundled 19-file library + catalog)                                |
+| `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
+| `icon`  | icons, symbols (transparent)                                                     |
+| `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |
+| `voice` | TTS voiceover (HeyGen free-usage path; optional local Kokoro)                    |
+| `grade` | measured correction candidate; broad polish/stylization follows Media Treatments |
+| `lut`   | user-provided or explicitly chosen reusable validated `.cube` file               |
 
 Before resolving fresh, list reusable candidates with `--candidates` and judge fit yourself — reuse rules, all flags, ingest (`--from`), and adopt are in `references/resolve.md`.
 

package/skills/media-use/audio/references/captions/authoring.md

@@ -1,5 +1,9 @@
 # Captions
 
+<!-- registry-items: allow=max-width,data-composition-src,hyperframes-registry,blend-mode,caption-style,font-family -->
+
+**The live search is the source of truth for what the registry has.** The table(s) below are a hand-maintained sample and under-cover by design: run `npx hyperframes catalog --query "<what you want>" --json` — it needs nothing installed — before concluding the registry lacks something. Item names here are checked against `registry/registry.json` by `bun run lint:skills`.
+
 Before authoring: confirm the transcript came from the right Whisper model. CLI default `small.en` silently translates non-English audio — see [`../transcribe.md`](../transcribe.md) → "Language Rule" and [`transcript-handling.md`](transcript-handling.md) for the mandatory quality check.
 
 Analyze spoken content to determine caption style. If user specifies a style, use that. Otherwise, detect tone from the transcript.

package/skills/media-use/audio/references/remove-background.md

@@ -1,6 +1,6 @@
 # Background Removal
 
-Make a transparent overlay (typical: a talking head over an arbitrary scene). Uses `u2net_human_seg` (MIT).
+Make a transparent overlay (typical: a talking head over an arbitrary scene). Uses `u2net_human_seg` (Apache-2.0).
 
 ```bash
 npx hyperframes remove-background subject.mp4 -o transparent.webm          # default: VP9 + alpha

package/skills/media-use/audio/references/tts-to-captions.md

@@ -14,9 +14,14 @@ node skills/media-use/audio/scripts/heygen-tts.mjs \
 
 `narration.words.json` is already in the `[{ id, text, start, end }]` shape the captions pipeline consumes — no separate transcribe pass.
 
-## Path B — ElevenLabs / Kokoro (TTS → Whisper)
+## Path B — Gemini / ElevenLabs / Kokoro (TTS → transcription)
 
-These providers don't return word data. Generate the audio, then transcribe:
+These adapters supply audio without word data. The shared audio engine runs
+transcription automatically when timings are absent. For Gemini, use the
+request in [Text to speech](tts.md#gemini-narration), then consume
+`audio_meta.json` → `voices[].words`.
+
+For a standalone local Kokoro generation, generate the audio, then transcribe:
 
 ```bash
 npx hyperframes tts script.txt --voice af_heart --output narration.wav
@@ -24,3 +29,7 @@ npx hyperframes transcribe narration.wav --model small.en   # voice af_heart is
 ```
 
 Whisper extracts precise word boundaries from the generated audio, so caption timing matches delivery without hand-tuning. Match `--model` to the voice's language (use `small.en` for `a`/`b` prefixes, `small --language <code>` otherwise). Then consume `transcript.json` via the caption references in `captions/`.
+
+For Gemini, verify that transcription preserved the script, especially names,
+numbers, and delivery pauses. If `words` is empty, resolve the transcription
+failure before captioning. Generate and align again after changing the read.