dsh-hyperframes 0.3.2 → 0.4.0

package/skills/{hyperframes-core → hyperframes}/references/storyboard-format.md

@@ -2,7 +2,7 @@
 
 Defines the storyboard's **base data format** only: the `STORYBOARD.md` file shape and the `StoryboardManifest` it parses into. How a workflow _generates_ a storyboard lives in that workflow; the optional narration/TTS file (`SCRIPT.md`) is a separate concern owned by the TTS step, not here.
 
-A storyboard is the **plan layer** for a video — an ordered set of **frames** (key moments) in one markdown file. HyperFrames Studio renders it as a contact sheet (the Storyboard view, available by default in every Studio session). Parser: `@hyperframes/core/storyboard` → `StoryboardManifest`; read API: `GET /api/projects/<id>/storyboard`.
+A storyboard is the **plan layer** for a video — an ordered set of **frames** (key moments) in one markdown file. Parser: `@hyperframes/core/storyboard` → `StoryboardManifest`.
 
 ## Frontmatter (global direction)
 
@@ -53,41 +53,10 @@ StoryboardManifest {
 }
 ```
 
-The read API also adds `srcExists` per frame and attaches the optional `SCRIPT.md` payload when present.
-
 ## `SCRIPT.md` (out of scope here)
 
 Optional, free-form, **not parsed into the manifest** — the locked-narration file that drives TTS. Its format is defined in `references/script-format.md`, and it is absent for videos with no narration/TTS. The per-frame `voiceover` above is the storyboard's own narration guide.
 
-## Frame comments — `.hyperframes/frame-comments.json`
-
-The storyboard review's **structured feedback channel** — the file Studio's per-frame comment boxes write on submit (chat feedback follows the same rule — `brief-contract.md` § 1, the comments channel). Like `SCRIPT.md`, it is a sibling of the storyboard, not parsed into the manifest.
-
-```json
-{
-  "version": 1,
-  "pass": "sketch",
-  "submitted_at": "2026-07-09T12:04:00Z",
-  "comments": [
-    {
-      "frame": 3,
-      "src": "compositions/frames/03-mechanism.html",
-      "title": "Mechanism",
-      "text": "Swap the bar chart for a before/after slider."
-    }
-  ]
-}
-```
-
-| Field                    | Meaning                                                                                                             |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `pass`                   | which review the batch belongs to: `storyboard` (text layer) / `sketch` (static frames) / `final` (assembled video) |
-| `comments[].frame`       | the frame's 1-based `index` in the manifest — the key                                                               |
-| `comments[].src` `title` | copied from the frame at submit time — if frames get reordered after submit, the mismatch shows                     |
-| `comments[].text`        | the feedback, verbatim                                                                                              |
-
-Lifecycle — the whole contract: a workflow finding this file at a checkpoint treats it as the revision feedback — **revise exactly the frames named, delete the file, re-present**. Writers create it only on submit; it never lingers across rounds.
-
 ## Example
 
 ```markdown
@@ -125,6 +94,6 @@ The old way: prompt, wait, get something that misses. Establish the pain we remo
 ## Notes
 
 - A frame with `status: outline` and no built `src` renders as an outline placeholder.
-- `built` is the middle rung: the frame's HTML exists and its **layout is confirmed** (a wireframe sketch or better) — motion not yet added. Studio chips it blue.
-- The process that walks these statuses — plan, sketch, build, each pass reviewed on the board — is `review-loop.md`.
+- `built` is the middle rung: the frame's HTML exists and its **layout is confirmed** (a wireframe sketch or better) — motion not yet added. Nothing is drawn yet beyond the approved layout.
+- The process that walks these statuses — plan, sketch, build, each pass reviewed in chat and in `storyboard.html` — is `review-loop.md`.
 - Multi-line `voiceover` values collapse to one line on save.

package/skills/hyperframes/scripts/lib/frame-packets-core.mjs

@@ -0,0 +1,194 @@
+// Frame packets inline the storyboard frame, blueprint and cited recipes.
+// Workflow wrappers supply resource paths and workflow-specific sections.
+// The role combines the shared worker contract with the workflow delta.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function field(block, name) {
+  const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
+  return match?.[1]?.trim() ?? null;
+}
+
+export function splitFrames(storyboard) {
+  const matches = [...storyboard.matchAll(/^## Frame\s+([^\n]+)$/gm)];
+  return matches.map((match, index) => {
+    const start = match.index;
+    const end = matches[index + 1]?.index ?? storyboard.length;
+    return {
+      heading: match[1].trim(),
+      block: storyboard.slice(start, end).trim(),
+    };
+  });
+}
+
+export function frameId(frame) {
+  const src = field(frame.block, "src");
+  if (!src) throw new Error(`${frame.heading}: missing src`);
+  return basename(src).replace(/\.html?$/i, "");
+}
+
+export function selectedFile(path, heading) {
+  if (!path || !existsSync(path)) return "";
+  return `\n## ${heading}\n\n${readFileSync(path, "utf8").trim()}\n`;
+}
+
+function escapeRegExp(id) {
+  return id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function knownRuleIds(animationDir) {
+  const rulesDir = join(animationDir, "rules");
+  if (!existsSync(rulesDir)) {
+    console.warn(
+      `frame-packets: no rules dir at ${rulesDir} — packets will inline no motion recipes`,
+    );
+    return [];
+  }
+  return readdirSync(rulesDir)
+    .filter((name) => name.endsWith(".md"))
+    .map((name) => name.replace(/\.md$/, ""));
+}
+
+export function citedRules(block, ruleIds) {
+  const explicit = (field(block, "rules") ?? "")
+    .split(/[,\s]+/)
+    .map((rule) => rule.trim())
+    .filter(Boolean);
+  const mentioned = ruleIds.filter((id) =>
+    new RegExp(`(?<![\\w-])${escapeRegExp(id)}(?![\\w-])`, "i").test(block),
+  );
+  return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
+}
+
+// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
+// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
+// the filename. Parse the field into the id it names (or null for `compose`), so
+// no caller ever resolves a raw field value against the blueprints directory.
+export function blueprintId(block) {
+  const raw = field(block, "blueprint");
+  if (!raw) return null;
+  const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
+  return id && id.toLowerCase() !== "compose" ? id : null;
+}
+
+export function resourceSections(block, { animationDir, ruleIds, frameId }) {
+  let sections = "";
+  const blueprint = blueprintId(block);
+  if (blueprint) {
+    const blueprintsDir = join(animationDir, "blueprints");
+    const path = join(blueprintsDir, `${blueprint}.md`);
+    // An installed library must contain the named blueprint.
+    // An absent on-demand library warns, like missing motion rules.
+    if (!existsSync(blueprintsDir)) {
+      console.warn(
+        `frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
+      );
+    } else if (!existsSync(path)) {
+      throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
+    } else {
+      sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
+    }
+  }
+  for (const rule of citedRules(block, ruleIds)) {
+    sections += selectedFile(
+      join(animationDir, "rules", `${rule}.md`),
+      `Selected motion rule: ${rule}`,
+    );
+  }
+  return sections;
+}
+
+export function buildRolePayload({ corePath, deltaPath, outDir }) {
+  const core = readFileSync(corePath, "utf8").trim();
+  const delta = readFileSync(deltaPath, "utf8").trim();
+  const role = `${core}\n\n---\n\n${delta}\n`;
+  mkdirSync(outDir, { recursive: true });
+  const path = join(outDir, "_role.md");
+  writeFileSync(path, role);
+  return { path, bytes: Buffer.byteLength(role) };
+}
+
+export function buildFramePackets({
+  projectDir,
+  storyboardPath = join(projectDir, "STORYBOARD.md"),
+  outDir = join(projectDir, ".hyperframes", "frame-packets"),
+  maxPacketBytes = 48_000,
+  animationDir,
+  corePath,
+  deltaPath,
+  // Per-workflow hooks (all optional):
+  // designTruthLine(projectDir) -> the packet's design-truth input line
+  // validateFrame(frame, id)   -> throw to reject a frame before packing
+  // extraSections(block)       -> extra packet sections appended after the rule recipes
+  designTruthLine = (dir) => `- Design tokens: ${join(resolve(dir), "frame.md")}`,
+  validateFrame,
+  extraSections,
+}) {
+  const storyboard = readFileSync(storyboardPath, "utf8");
+  const frames = splitFrames(storyboard);
+  if (frames.length === 0) throw new Error("STORYBOARD.md has no frame blocks");
+  const ruleIds = knownRuleIds(animationDir);
+
+  const packets = frames.map((frame) => {
+    const id = frameId(frame);
+    if (validateFrame) validateFrame(frame, id);
+    const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
+    const bytes = Buffer.byteLength(packet);
+    if (bytes > maxPacketBytes) {
+      throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);
+    }
+    return { frameId: id, path: join(outDir, `${id}.md`), bytes, packet };
+  });
+
+  mkdirSync(outDir, { recursive: true });
+  for (const { path, packet } of packets) writeFileSync(path, packet);
+  buildRolePayload({ corePath, deltaPath, outDir });
+  return packets.map(({ packet: _packet, ...result }) => result);
+}
+
+export function flag(argv, name, fallback) {
+  const index = argv.indexOf(`--${name}`);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+}
+
+// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
+// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
+// a raw compare silently skips main() when invoked through any symlinked path.
+export function isMainModule(importMetaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+  } catch {
+    return false;
+  }
+}
+
+export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
+  const argv = process.argv.slice(2);
+  const projectDir = resolve(flag(argv, "project", "."));
+  const outDir = resolve(flag(argv, "out-dir", join(projectDir, ".hyperframes", "frame-packets")));
+  try {
+    const packets = build({
+      projectDir,
+      storyboardPath: resolve(flag(argv, "storyboard", join(projectDir, "STORYBOARD.md"))),
+      outDir,
+    });
+    const role = buildRole({ outDir });
+    console.log(`✓ frame packets: ${packets.length} bounded packet(s)`);
+    for (const packet of packets)
+      console.log(`  ${packet.frameId}: ${packet.bytes} bytes → ${packet.path}`);
+    console.log(`  worker role: ${role.bytes} bytes → ${role.path}`);
+  } catch (error) {
+    console.error(`✗ frame packets: ${error.message}`);
+    process.exit(1);
+  }
+}

package/skills/hyperframes/scripts/plugin-cli.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Run from the user's project; locate the release from this installed file.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = fileURLToPath(new URL("../../../", import.meta.url));
+const manifests = [
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "gemini-extension.json",
+];
+
+export function pluginVersion(pluginRoot = root) {
+  for (const path of manifests) {
+    const file = join(pluginRoot, path);
+    if (!existsSync(file)) continue;
+    const manifest = JSON.parse(readFileSync(file, "utf8"));
+    if (
+      manifest.name !== "hyperframes" ||
+      !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version ?? "")
+    ) {
+      throw new Error(`Invalid HyperFrames plugin release: ${file}`);
+    }
+    return manifest.version;
+  }
+  throw new Error(
+    "No HyperFrames plugin manifest found. Use the standalone skills installation instructions.",
+  );
+}
+
+export function invocation(
+  args,
+  {
+    version = pluginVersion(),
+    env = process.env,
+    platform = process.platform,
+    node = process.execPath,
+    pathExists = existsSync,
+  } = {},
+) {
+  if (args[0] === "skills")
+    throw new Error(
+      "Update HyperFrames through your agent's plugin manager; bundled skills are release-managed.",
+    );
+  const childEnv = {
+    ...env,
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: version,
+    HYPERFRAMES_PLUGIN_VERSION: version,
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+  };
+  if (args[0] === "--script") {
+    if (!args[1]) throw new Error("--script requires a Node script path.");
+    return { command: node, args: args.slice(1), env: childEnv };
+  }
+  const cliArgs = ["--yes", `hyperframes@${version}`, ...args];
+  if (platform !== "win32") return { command: "npx", args: cliArgs, env: childEnv };
+  const candidates = [
+    env.npm_execpath && win32.join(win32.dirname(env.npm_execpath), "npx-cli.js"),
+    win32.join(win32.dirname(node), "node_modules", "npm", "bin", "npx-cli.js"),
+  ].filter(Boolean);
+  const npx = candidates.find(pathExists);
+  if (!npx)
+    throw new Error(
+      "Cannot find npx-cli.js. Install Node.js with npm or run from an npm environment.",
+    );
+  return { command: node, args: [npx, ...cliArgs], env: childEnv };
+}
+
+if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+  try {
+    const command = invocation(process.argv.slice(2));
+    const result = spawnSync(command.command, command.args, {
+      env: command.env,
+      stdio: "inherit",
+      windowsHide: true,
+    });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/skills/hyperframes/scripts/plugin-cli.test.mjs

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import { invocation, pluginVersion } from "./plugin-cli.mjs";
+
+function fixture(t, manifest = "plugin.json", version = "1.2.3") {
+  const root = mkdtempSync(join(tmpdir(), "hf-plugin-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  mkdirSync(join(root, "skills/hyperframes/scripts"), { recursive: true });
+  mkdirSync(join(root, manifest, ".."), { recursive: true });
+  writeFileSync(join(root, manifest), JSON.stringify({ name: "hyperframes", version }));
+  const launcher = join(root, "skills/hyperframes/scripts/plugin-cli.mjs");
+  copyFileSync(new URL("./plugin-cli.mjs", import.meta.url), launcher);
+  return { root, launcher };
+}
+
+for (const manifest of [
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "gemini-extension.json",
+]) {
+  test(`locates ${manifest} without repository packages`, (t) => {
+    const { root } = fixture(t, manifest);
+    assert.equal(pluginVersion(root), "1.2.3");
+  });
+}
+
+test("rejects missing and floating plugin versions", (t) => {
+  const { root } = fixture(t, "plugin.json", "latest");
+  assert.throws(() => pluginVersion(root), /Invalid HyperFrames plugin release/);
+  rmSync(join(root, "plugin.json"));
+  assert.throws(() => pluginVersion(root), /No HyperFrames plugin manifest/);
+});
+
+test("pins CLI, suppresses standalone refresh, preserves unrelated environment", () => {
+  const result = invocation(["init", "project with spaces", "--non-interactive"], {
+    version: "1.2.3",
+    platform: "darwin",
+    env: { PATH: "/bin", HYPERFRAMES_SKIP_SKILLS: "0" },
+  });
+  assert.equal(result.command, "npx");
+  assert.deepEqual(result.args, [
+    "--yes",
+    "hyperframes@1.2.3",
+    "init",
+    "project with spaces",
+    "--non-interactive",
+  ]);
+  assert.deepEqual(result.env, {
+    PATH: "/bin",
+    HYPERFRAMES_SKIP_SKILLS: "1",
+    HYPERFRAMES_SKILL_PKG_VERSION: "1.2.3",
+    HYPERFRAMES_PLUGIN_VERSION: "1.2.3",
+    HYPERFRAMES_NO_UPDATE_CHECK: "1",
+  });
+  assert.throws(() => invocation(["skills", "update"], { version: "1.2.3" }), /plugin manager/);
+});
+
+test("Windows launches npx through Node without shell argument interpretation", () => {
+  const result = invocation(["render", "a & b"], {
+    version: "1.2.3",
+    platform: "win32",
+    node: String.raw`C:\Program Files\nodejs\node.exe`,
+    env: { npm_execpath: String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js` },
+    pathExists: (p) => p === String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npx-cli.js`,
+  });
+  assert.equal(result.command, String.raw`C:\Program Files\nodejs\node.exe`);
+  assert.deepEqual(result.args, [
+    String.raw`C:\Program Files\nodejs\node_modules\npm\bin\npx-cli.js`,
+    "--yes",
+    "hyperframes@1.2.3",
+    "render",
+    "a & b",
+  ]);
+  assert.throws(
+    () => invocation([], { version: "1.2.3", platform: "win32", env: {}, pathExists: () => false }),
+    /Cannot find npx/,
+  );
+});
+
+test("installed helper keeps cwd, arguments, release environment and exit code", (t) => {
+  const { root, launcher } = fixture(t);
+  const project = join(root, "user project");
+  mkdirSync(project);
+  const helper = join(root, "helper.mjs");
+  writeFileSync(
+    helper,
+    "console.log(JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2), skip: process.env.HYPERFRAMES_SKIP_SKILLS, version: process.env.HYPERFRAMES_SKILL_PKG_VERSION })); process.exit(7);",
+  );
+  const before = readFileSync(join(root, "plugin.json"), "utf8");
+  const result = spawnSync(
+    process.execPath,
+    [launcher, "--script", helper, "literal $value & spaces"],
+    { cwd: project, encoding: "utf8" },
+  );
+  assert.equal(result.status, 7, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), {
+    cwd: realpathSync(project),
+    args: ["literal $value & spaces"],
+    skip: "1",
+    version: "1.2.3",
+  });
+  assert.equal(readFileSync(join(root, "plugin.json"), "utf8"), before);
+});

package/skills/hyperframes-animation/SKILL.md

@@ -3,6 +3,8 @@ name: hyperframes-animation
 description: "All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic."
 ---
 
+**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 Animation
 
 All motion knowledge in one skill: **rules** (atomic recipes), **blueprints** (multi-phase scene templates), **transitions** (scene-to-scene), **techniques** (broader motion-design patterns), and **adapters** (per-runtime APIs).
@@ -30,6 +32,7 @@ Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.
 | Read one blueprint's full recipe                                               | `blueprints/<id>.md`                                |
 | Author a scene transition (CSS-driven, between two clips)                      | `transitions/overview.md`, `transitions/catalog.md` |
 | Look up a broader motion-design technique                                      | `techniques.md`                                     |
+| Motion blur — shutter smear on an element, and when not to use it              | `references/motion-blur.md`                         |
 | Analyze an existing composition's animation map                                | `scripts/animation-map.mjs`                         |
 | GSAP API — timeline / tweens / position parameters                             | `adapters/gsap.md`                                  |
 | GSAP — drop-in effect recipes                                                  | `rules/gsap-effects.md`                             |
@@ -37,6 +40,7 @@ Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.
 | GSAP — eases / stagger                                                         | `adapters/gsap-easing-and-stagger.md`               |
 | GSAP — timeline / labels                                                       | `adapters/gsap-timeline-and-labels.md`              |
 | Lottie / dotLottie (After Effects exports, `window.__hfLottie`)                | `adapters/lottie.md`                                |
+| Character animation (walk cycle, mascot, jointed puppet, gestures)             | `adapters/lottie.md` → Characters                   |
 | Three.js / WebGL (3D scenes, `AnimationMixer`, `hf-seek`)                      | `adapters/three.md`                                 |
 | Anime.js (`window.__hfAnime`)                                                  | `adapters/animejs.md`                               |
 | CSS keyframes (`animation-delay` / `play-state` / `fill-mode`)                 | `adapters/css-animations.md`                        |
@@ -48,7 +52,7 @@ Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.
 ## Picking a runtime
 
 - **GSAP** is the default for 95% of motion work — covers timeline orchestration, transforms, easing, stagger. All atomic rules in this skill are GSAP-based.
-- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports).
+- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports), including characters that walk, gesture or react.
 - **Three.js** for 3D scenes, camera motion, shader-driven visuals.
 - **Anime.js** for lightweight tweening when GSAP is overkill.
 - **CSS** for simple repeated motifs, decoration, shimmer — no JavaScript animation cost.

package/skills/hyperframes-animation/adapters/gsap.md

@@ -61,7 +61,7 @@ HyperFrames is stricter than vanilla GSAP. Animate only:
 - **Compositor-cheap**: `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`
 - **Visual fills**: `color`, `backgroundColor`, `borderColor`, `borderRadius`
 - **CSS variables**: `"--hue": 180` etc.
-- **Media `volume`** (on `<audio>` / `<video>`): animate for fades/ducking, e.g. `tl.to("#bgm", { volume: 0, duration: 1 }, "outro")`. The runtime probes these keyframes from the timeline and drives them in both preview and render (they match). This sets the _author_ volume; `data-volume` is the static baseline when no tween touches the element.
+- **Media `volume`** (on `<audio>` / `<video>`): do not tween it for fades or ducking; use the `data-automation` volume lane (`creator-editing-recipes.md` in `hyperframes-core`). A lane wins over a tween on the same element.
 - **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Equivalent to the `onUpdate`-proxy form in `../rules/counting-dynamic-scale.md`; prefer that proxy form for locale formatting (`toLocaleString`) or suffix logic, and pair it with a separate transform-scale tween when the number should grow.
 
 **Avoid** (use the transform alias instead):

package/skills/hyperframes-animation/adapters/lottie.md

@@ -11,7 +11,7 @@ HyperFrames can seek both `lottie-web` and dotLottie players through its `lottie
 
 - Load assets from local project files, usually under `assets/`.
 - Set `autoplay: false`.
-- Prefer `loop: false` unless the user explicitly wants a loop.
+- Use `loop: false` for a one-shot and `loop: true` for a cycle (walk, idle, spinner). A looping animation is seeked to composition time modulo its own length, so it keeps cycling for the whole scene; a one-shot holds its last frame. Always set `loop`: lottie-web treats a missing `loop` as `true`. A numeric `loop` count does not repeat under seeking; bake the repeats into the file.
 - Register every returned animation or player on `window.__hfLottie`.
 - Keep the Lottie container dimensions stable with CSS.
 
@@ -84,12 +84,25 @@ HyperFrames seeks them all to the same composition time.
 
 ## Composition Duration
 
-The render engine needs the composition's total length. GSAP timelines report duration automatically; a Lottie-only composition has no timeline object, so the runtime reads the registered animation's native length directly — `totalFrames / frameRate` for `lottie-web`, or the player's own `duration` for dotLottie. `data-duration` on the root element is optional for Lottie compositions: as long as every animation is registered on `window.__hfLottie` (per the contract above), the runtime has a finite duration to work with even when you set `loop: true`.
+The render engine needs the composition's total length. GSAP timelines report duration automatically; a Lottie-only composition has no timeline object, so the runtime reads the registered animation's native length directly — `totalFrames / frameRate` for `lottie-web`, or the player's own `duration` for dotLottie. `data-duration` on the root element is optional for Lottie compositions: as long as every animation is registered on `window.__hfLottie` (per the contract above), the runtime has a finite duration to work with. With `loop: true` that length is one cycle, so a looping Lottie in a longer scene needs `data-duration` or a GSAP timeline to set the scene length.
+
+## Characters
+
+For a character that walks, gestures or reacts (a mascot, a walk cycle, a jointed puppet), put the acting in one Lottie and the stage in GSAP:
+
+- **The Lottie owns the body.** Walk, stop, point and idle live in the file's own timeline, so limbs stay jointed and feet stay planted exactly as the animator made them.
+- **GSAP owns everything around it.** Cards, captions and camera moves go on the paused timeline, timed to the Lottie's beats. Read the beat times from the file's `markers` array (`tm` is in frames, divide by `fr`) or from the animator's notes.
+- **Every registered animation plays against composition time.** There is no per-animation start offset, so a gesture that should begin at 4 s must begin at 4 s inside its file. Author the whole performance as one Lottie, or offset the action inside the file, rather than stacking separate action files.
+- **A short cycle is fine.** A 1 s walk cycle with `loop: true` cycles for the whole scene. Move the character across the stage with GSAP `x` only if the cycle walks in place, and match the travel speed to the stride or the feet slide.
+- **License the character.** Use a file the user or their designer made, or one whose license allows redistribution, and say where it came from. Never ship a character ripped from a site.
+
+The `lottie-character-walk` registry block is a working example: a jointed flat character walks in on planted feet, stops, and points at a card that GSAP brings in on the point (`npx hyperframes add lottie-character-walk`).
 
 ## Good Uses
 
 - After Effects exports that are already known to render correctly in lottie-web.
 - Logo reveals, icon loops, decorative accents, and product UI motion.
+- Characters: walk cycles, mascots, gestures (see Characters above).
 - Translating Remotion Lottie usage into plain HyperFrames HTML.
 
 ## Avoid

package/skills/hyperframes-animation/adapters/three.md

@@ -87,6 +87,20 @@ For anything under `three/addons/`, use an importmap so bare specifiers resolve.
 
 Pin the `three` version in both entries to the same value. Mixing versions across the map and bare imports causes silent breakage.
 
+## Heavy Setup (Large Meshes, Shader Compiles)
+
+The runtime already waits for textures/models queued through Three's `DefaultLoadingManager` before publishing render-ready. It has no visibility into CPU-bound work you do yourself after assets load — building a large procedural mesh, compiling shaders, warming a pipeline. That work can leave the canvas blank for seconds after the runtime and player already say "ready".
+
+If your setup does this kind of work, register a promise on `window.__hf.buildReady` (declared-compute hold: runtime waits, player shows its loading state instead of a blank frame):
+
+```js
+window.__hf = window.__hf || {};
+window.__hf.buildReady = window.__hf.buildReady || {};
+window.__hf.buildReady["<your-piece-name>"] = buildScene(); // resolves once the scene is actually drawable
+```
+
+Register it synchronously, in the same script block that starts the build — same timing as `DefaultLoadingManager`, so the runtime's first readiness check already sees it. Only do this for setup an adapter cannot see; render-critical seeking still comes from `hf-seek`, not this hold. The key must be unique within the composition — a second registration under the same key silently replaces the first, dropping its hold.
+
 ## AnimationMixer Pattern
 
 For GLTF or authored clip animation, seek the mixer directly:

package/skills/hyperframes-animation/blueprints/titlecard-reveal.md

@@ -54,7 +54,7 @@ monochrome text-on-solid throughout.
 
 - gentle fade-in + subtle scale-up settle (Benefits Scene 2) → `rules/scale-swap-transition.md` (restrained in/settle; cross-reference the fade ease in `techniques.md`)
 - single slide-up crossfade between two centered lines (Benefits Scene 3) → `rules/discrete-text-sequence.md` (one line hands off to the next; translate-up + crossfade)
-- diagonal pill-wipe reveal (Social_Proof Scene 2) → `rules/techniques.md` (clip-path reveal masks — the wipe)
+- diagonal pill-wipe reveal (Social_Proof Scene 2) → `../techniques.md` (clip-path reveal masks — the wipe)
 - icon stroke draw-on (Social_Proof Scene 2) → `rules/svg-path-draw.md`
 - "[N]+ teams" count-up (Social_Proof Scene 3, optional) → `rules/counting-dynamic-scale.md`
 - logo + tagline spring-settle-and-hold (Social_Proof Scene 3) → `rules/spring-pop-entrance.md` (single soft settle; intentionally one beat, not a chain)