dsh-hyperframes 0.3.2 → 0.4.0

package/skills/hyperframes-animation/references/motion-blur.md

@@ -0,0 +1,133 @@
+# Motion blur — shutter smear on any animated element
+
+## Read this part before you blur anything
+
+Blur is not polish. It is the smear a real shutter leaves while the subject
+crosses the frame, so it only reads as correct when the subject crosses enough
+of the frame to have smeared. Applied to motion that was never fast enough, it
+reads as a soft, cheap render: the eye sees mush where it expected an edge.
+
+Do not blur:
+
+| Case                                             | Why                                                                                                    | Do instead                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------- |
+| Travel under about one element-width per frame   | The copies pile up inside the element's own silhouette, so the result is a softer element, not a smear | Leave it sharp                      |
+| A fade, a color change, a blur-in, a filter beat | Nothing reaches `transform`, so there is no trajectory to integrate and no smear to draw               | Leave it sharp                      |
+| Text meant to be read at that moment             | A smeared word is an unreadable word, which is usually the opposite of the brief                       | Blur the approach, land sharp, hold |
+| A slow drift, a parallax layer, a breathing loop | Below the half-pixel deadband it renders sharp anyway; above it, it looks like a mistake               | Leave it sharp                      |
+| The whole scene, or a container of many elements | Cost is the copies of an entire subtree, and a container that never moves smears nothing inside it     | Point it at the element that moves  |
+
+Blur the beats that snap: a slam, a whip, a hard cut in position, a spin, a
+scale punch. One to three of them in a composition, not every tween.
+
+## Two routes, and they are not interchangeable
+
+| Route                                   | What it is                                                                                                       | Use when                                                                                                             |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| The `motion-blur` registry component    | A DOM shutter synthesised in the page: N+1 additively blended copies of the element along its sampled trajectory | You want the smear visible in the preview, on selected elements, authored per element                                |
+| The engine's `motionBlur` render option | The renderer integrates real sub-frame samples of the whole frame                                                | You want every moving thing smeared, including canvas, video and transformed ancestors, and only in the final render |
+
+The component smears what a `transform` can express, on the elements you mark.
+The engine smears the frame. The component is the one an agent authors; the
+engine option is a render-time decision and shows nothing in a preview.
+
+## The contract: one attribute
+
+Paste the component's snippet into the composition, then mark the element:
+
+```html
+<div id="root" data-composition-id="hero" data-duration="4" data-fps="30">
+  <div id="slam" data-hf-motion-blur></div>
+  <div id="title" data-hf-motion-blur='{"shutterAngle": 360}'></div>
+</div>
+```
+
+Nothing to call and no ordering to get right. A marked element is attached as
+soon as its composition's timeline is registered, and the registry is also
+polled for about eight seconds after load, so a composition that mounts
+asynchronously is picked up too. An element takes the timeline registered under
+the `data-composition-id` of its nearest ancestor carrying that attribute, so a
+sub-composition's targets follow that sub-composition.
+
+Empty attribute means defaults. Any other value must parse as a JSON object, so
+it needs double quotes on the keys. A value that parses to something else,
+`null` or a bare number, warns and is skipped rather than quietly taken as
+defaults.
+
+`attachMotionBlur(target, timeline, options)` is for an element created later
+than that window. It has an ordering contract, after every tween so the
+timeline's final duration is known, and getting it wrong is silent. For markup
+that is already in the document, use the attribute.
+
+## Options
+
+| Option            | Default                                                      | Meaning                                                                                                                                                |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `shutterAngle`    | 720                                                          | Degrees of the frame interval the shutter is open. 720 is two frames, measured off a real After Effects export. 360 is one frame. 0 disables the smear |
+| `shutterPhase`    | -360                                                         | Degrees the window start sits from the frame time. -360 centres the window on the frame                                                                |
+| `samplesPerFrame` | 16                                                           | Sub-intervals of the window, so this many plus one copies, each at 1 over this many opacity. Max 64                                                    |
+| `fps`             | the `data-fps` of the target's own composition root, else 30 | Composition frame rate. Pass it explicitly when rendering with an fps override                                                                         |
+
+A key that is none of these four, and a value that is not a finite number, are
+both refused by name rather than read as defaults. `{"shutterAngle": "720deg"}`
+is a refusal, not a 720 degree shutter.
+
+There is no axis, no strength and no radius. The smear is the trajectory,
+integrated; its extent is speed times shutter time and is not a free parameter.
+A template that passes `axis`, `blurMax` or `blurScale` carries an older fork of
+this snippet and its options do nothing in the current one.
+
+## The failure modes are all silent
+
+Every one of these renders a plausible-looking sharp element and reports
+nothing except where noted:
+
+| Symptom                                                                  | Cause                                                                                                               | Fix                                                                                  |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Console warns that no composition registered a timeline for an element   | The element is outside every `data-composition-id`, or that composition never registers a timeline                  | Put it inside the composition's root, or register the timeline                       |
+| Console warns the attribute is not JSON                                  | Single quotes, unquoted keys, a trailing comma                                                                      | Double-quoted JSON, or an empty attribute for defaults                               |
+| Console warns the attribute is not a JSON object                         | `null`, a bare number, a quoted string, an array                                                                    | An object, or an empty attribute for defaults                                        |
+| Console warns the attribute names no such option                         | A misspelled key, for example `samplesperframe`                                                                     | Use one of the four names above, case-sensitive                                      |
+| Console warns the attribute needs a number for an option                 | A quoted or unit-suffixed value, for example `"720deg"`                                                             | A bare JSON number                                                                   |
+| Console warns it cannot blur a target inside another target              | Both an element and one of its ancestors carry the attribute                                                        | Mark one of them, the one that moves                                                 |
+| Console warns one call cannot blur compositions at different frame rates | One `attachMotionBlur` call named elements in two compositions whose `data-fps` differ                              | One call per composition                                                             |
+| Console warns a second timeline registered for an element                | The same `data-composition-id` key was registered twice with different timelines; the copies still follow the first | Register once per composition                                                        |
+| No smear, no warning                                                     | The beat animates `left`, `top`, `width` or `height`; the snippet reads the resolved `transform`                    | Animate `x`, `y`, `scale`, `rotation`                                                |
+| No smear on a container's children                                       | The marked element does not move; its children do                                                                   | Mark the elements that move                                                          |
+| A smear that lags the element                                            | A transformed ancestor is doing the moving                                                                          | Move the element itself, or use the engine route                                     |
+| Blur only on the first frame, or never in a preview                      | The host never seeks the timeline                                                                                   | HyperFrames seeks every frame; a paused timeline nobody seeks shows nothing          |
+| A smear left behind in the old parent                                    | The target was reparented after attaching; the group stays where it was inserted and is never moved                 | Do not reparent a blurred element. Animate `x`/`y` instead, or attach after the move |
+| A selector stops matching after attaching                                | A copy keeps the element's classes, because a class rule is the only thing that can style a copy's pseudo-elements  | Address the element by id or by reference, never by a class a copy also carries      |
+
+## Cost
+
+Each target costs N+1 copies of its whole subtree. Those are restyled on attach
+and on resize, and re-transformed every frame, and the timeline is seeked N+1
+times per frame to sample the trajectory. At the default 16 that is 17 copies
+and 17 seeks per target per frame. Three marked elements is fine. Thirty is a
+different render.
+
+Drop `samplesPerFrame` before you drop the effect: 8 halves the cost and the
+staircase is still smooth on a fast beat.
+
+## The numbers, so you can argue with them
+
+The defaults are measured against a 1920x1080 30 fps After Effects export of
+translating text, not chosen. In that export the outermost trailing copy sits
+exactly at the previous frame's position and the outermost leading copy exactly
+at the next frame's, with 8 evenly spaced copies between on each side: a window
+of two frames, phase minus one frame, 16 sub-intervals. The staircase across a
+stroke steps by 0.063 plus or minus 0.002 of the sharp text intensity, a flat
+1/16 per copy with no taper toward the window edges. Triangle weighting scores
+1.6 dB worse against the same export.
+
+Per-beat PSNR against that reference, sharp render versus this component:
+translate +3.38 dB, scale +0.62, rotate X +0.43, rotate Y +0.84, rotate Z
++1.15. A beat that only scales or only rotates smears, which the earlier
+SVG-filter stage could not do.
+
+## See also
+
+`../../registry/components/motion-blur/motion-blur.html` is the snippet and its
+full header. `shutter-slam` is the same model as an installable component: the
+After Effects reference case, six beats, elastic to the container.

package/skills/hyperframes-animation/rules/cursor-click-ripple.md

@@ -89,7 +89,7 @@ tl.to(
 | RIPPLE_EASE                 | discrete choice             | `power2.out` standard ping · `power3.out` sharper attack · `expo.out` strong distant pulse                                             |
 | TARGET_X / TARGET_Y         | layout-derived              | must match the target's visual centroid — a 4 px miss reads as missing the button                                                      |
 
-Reference values: `../../examples/cta-orbit-collapse.html` — 0.5 s move on `back.out(1.3)`, click +0.2 s, press 0.08 s at 0.85/0.95, single ring to 5× over 0.7 s `power2.out`.
+Reference values: `../examples/cta-orbit-collapse.html` — 0.5 s move on `back.out(1.3)`, click +0.2 s, press 0.08 s at 0.85/0.95, single ring to 5× over 0.7 s `power2.out`.
 
 ## Critical Constraints
 

package/skills/hyperframes-animation/rules/dynamic-content-sequencing.md

@@ -134,7 +134,7 @@ Values: `HOLD_START` 0.8–1.2s; `DECAY` 0.75–0.88 (higher = longer runway bef
 | TAIL_PAD      | 0.0–1.0s              | quiet beat after the last entry; prefer 0 when the next composition owns the breath                                   |
 | CONTENT N     | 3–6 entries           | <3 isn't a sequence; >6 drags (accelerating cadence relaxes this — see above)                                         |
 
-Reference: `../../examples/messaging-multi-phrase.html`.
+Reference: `../examples/messaging-multi-phrase.html`.
 
 ## Critical Constraints
 

package/skills/hyperframes-animation/rules/hacker-flip-3d.md

@@ -108,7 +108,7 @@ charEls.forEach((el, i) => {
 | REVEAL_THRESHOLD | 0.5–0.7                         | lower reveals too early (no tension); higher reads as a hard end-reveal            |
 | FLICKER_RATE     | 3–6 frames per glyph swap       | <3 looks like noise; >6 looks like discrete typing                                 |
 
-Reference: `../../examples/proof-logo-chain.html` (163px, 0.55s, 0.033s, 0.6).
+Reference: `../examples/proof-logo-chain.html` (163px, 0.55s, 0.033s, 0.6).
 
 ## Critical Constraints
 

package/skills/hyperframes-animation/rules/kinetic-beat-slam.md

@@ -112,7 +112,7 @@ tl.to(
 ## Variations
 
 - **Entrance easing by attack character** — `power4.out` hard slam ⭐ default hit · `expo.out` hardest snap (side-snaps, whip-ins) · `back.out(2)` overshoot pop (accents only, not body words) · `circ.out` heavy rise with momentum. Use **at least 3 distinct easings** across the piece.
-- **Rhythm chrome alternatives** — a center beat bar or a `// label` monospace tag pulsing on-beat instead of the 5-tick metronome; mark any decorative that must survive a shader transition per `../../transitions/overview.md`.
+- **Rhythm chrome alternatives** — a center beat bar or a `// label` monospace tag pulsing on-beat instead of the 5-tick metronome; mark any decorative that must survive a shader transition per `../transitions/overview.md`.
 - **Finale dressing** — stack + accent underline sweep ([css-marker-patterns](css-marker-patterns.md)); don't just leave the last phrase sitting.
 
 ## Values
@@ -129,7 +129,7 @@ tl.to(
 - **One beat array, not scattered offsets** — every element times off `BEATS[]` / `PULSE`; this is the single biggest lever for "rhythmic".
 - **Different entrance per phrase** — a reused `punchIn()` for all lines is the flat-but-competent tell. Vary the motion axis, reuse the ease _family_.
 - **Finale repeat math**: `repeat: Math.max(0, Math.floor(dur / cycle) - 1)` — `Math.ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint rule; a negative repeat is read by GSAP as `-1` (infinite).
-- **No banned exit animations between scenes** — in a montage the _transition_ is the exit (`../../transitions/overview.md`); only a final scene may fade out.
+- **No banned exit animations between scenes** — in a montage the _transition_ is the exit (`../transitions/overview.md`); only a final scene may fade out.
 - **Display font must be embedded** or it silently falls back at render — Anton / Bebas-as-literal are NOT embedded (`Bebas Neue` aliases to League Gothic; verify in `typography.md`).
 
 ## See also

package/skills/hyperframes-animation/rules/motion-blur-streak.md

@@ -12,7 +12,7 @@ Real motion blur isn't available to a seeked renderer (it integrates over shutte
 - **(A) Directional SVG blur** — inline `<feGaussianBlur stdDeviation="X 0">` (X on the motion axis, 0 across it), tweened via a proxy. Cleanest; a true directional smear.
 - **(B) Echo / ghost trail** — 2–4 duplicates at decreasing opacity, offset backward along the motion vector, collapsing into the lead as it settles. No filter cost; a stylized "speed-line" trail.
 
-**Entrances and mid-shot moves only — never a mid-composition exit.** A blurred element fleeing off-frame mid-composition reads as a glitch; a hard exit between scenes is the transition's job (`../../transitions/overview.md`). One sanctioned scope extension: the envelope may ride the **camera wrapper** during a travel leg — see the Camera-Travel Carve-Out.
+**Entrances and mid-shot moves only — never a mid-composition exit.** A blurred element fleeing off-frame mid-composition reads as a glitch; a hard exit between scenes is the transition's job (`../transitions/overview.md`). One sanctioned scope extension: the envelope may ride the **camera wrapper** during a travel leg — see the Camera-Travel Carve-Out.
 
 ## How It Works
 

package/skills/hyperframes-animation/rules/vertical-spring-ticker.md

@@ -87,7 +87,7 @@ springs.forEach((spring, i) => {
 | STEP_SPACING  | 0.3–0.5s              | **≤ STEP_DUR** so springs overlap (additive); wider gaps read as a lazy linear scroll |
 | BOUNCE_FACTOR | 1.4–2.5               | 1.4 gentle click / 2.0 firm / 2.5+ casino spin-and-land for a climax step             |
 
-Reference: `../../examples/proof-logo-chain.html` (204px, 1 step, 0.45s).
+Reference: `../examples/proof-logo-chain.html` (204px, 1 step, 0.45s).
 
 ## Critical Constraints
 

package/skills/hyperframes-animation/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-animation/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-animation/techniques.md

@@ -197,7 +197,7 @@ Vector animations that play inside a composition. Use for logos, character anima
 </script>
 ```
 
-`autoplay: false` + `loop: false` + `window.__hfLottie.push()` are mandatory — HyperFrames seeks each registered player to composition time, so anything left on `autoplay`/`loop` runs in wall-clock and renders non-deterministically. The adapter seeks absolute time (no modulo loop, no playback-rate scaling): bake repeating cycles or non-default speed into the Lottie asset or an explicit timeline, then verify the render. Full contract + `.lottie`/dotLottie variant: `adapters/lottie.md`.
+`autoplay: false` + `window.__hfLottie.push()` are mandatory — HyperFrames seeks each registered player to composition time, so a player left on `autoplay` runs in wall-clock and renders non-deterministically. `loop: true` is seek-safe: the adapter wraps composition time into the animation's own length, so a short cycle repeats for the whole scene. There is no playback-rate scaling: bake non-default speed into the Lottie asset. Characters (walk cycles, mascots, gestures) and the full `.lottie`/dotLottie contract: `adapters/lottie.md`.
 
 ---
 

package/skills/hyperframes-animation/transitions/TRANSITION-REGISTRY.md

@@ -97,11 +97,11 @@ whitelist is a _scene-worker_ prompt rule only — it does not bind index.html).
       "note": "Directional. The injector picks __DX__/__DY__ from the direction and emits the horizontal OR vertical pair (not both).",
       "gsap_template_horizontal": [
         "tl.to(__OLD__, { x: __DX__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { x: __DXIN__, opacity: 1 }, { x: 0, opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ],
       "gsap_template_vertical": [
         "tl.to(__OLD__, { y: __DY__, duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { y: __DYIN__, opacity: 1 }, { y: 0, opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ]
     },
     {
@@ -128,7 +128,7 @@ whitelist is a _scene-worker_ prompt rule only — it does not bind index.html).
       "note": "Old compresses to a vertical line on the left edge; new expands from the right edge. Incoming starts off (scaleX 0) so its higher-track stacking is harmless.",
       "gsap_template": [
         "tl.to(__OLD__, { scaleX: 0, transformOrigin: \"left center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);",
-        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
+        "tl.fromTo(__NEW__, { scaleX: 0, transformOrigin: \"right center\", opacity: 1 }, { scaleX: 1, transformOrigin: \"right center\", opacity: 1, duration: __DUR__, ease: \"power3.inOut\" }, __T__);"
       ]
     }
   ],

package/skills/hyperframes-animation/transitions/css-push.md

@@ -6,7 +6,7 @@ Both scenes move together — new pushes old out.
 
 ```js
 tl.to(old, { x: -1920, duration: 0.5, ease: "power3.inOut" }, T);
-tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 0, duration: 0.5, ease: "power3.inOut" }, T);
+tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 0, opacity: 1, duration: 0.5, ease: "power3.inOut" }, T);
 ```
 
 ### Vertical Push
@@ -15,7 +15,7 @@ Same as push slide but vertical.
 
 ```js
 tl.to(old, { y: -1080, duration: 0.5, ease: "power3.inOut" }, T);
-tl.fromTo(new, { y: 1080, opacity: 1 }, { y: 0, duration: 0.5, ease: "power3.inOut" }, T);
+tl.fromTo(new, { y: 1080, opacity: 1 }, { y: 0, opacity: 1, duration: 0.5, ease: "power3.inOut" }, T);
 ```
 
 ### Elastic Push
@@ -24,7 +24,7 @@ Push with overshoot bounce on the incoming scene.
 
 ```js
 tl.to(old, { x: -1920, duration: 0.5, ease: "power3.in" }, T);
-tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 30, duration: 0.4, ease: "power4.out" }, T + 0.1);
+tl.fromTo(new, { x: 1920, opacity: 1 }, { x: 30, opacity: 1, duration: 0.4, ease: "power4.out" }, T + 0.1);
 tl.to(new, { x: -15, duration: 0.15, ease: "sine.inOut" }, T + 0.5);
 tl.to(new, { x: 0, duration: 0.1, ease: "sine.out" }, T + 0.65);
 ```
@@ -36,6 +36,6 @@ Old compresses, new expands from opposite side.
 ```js
 tl.to(old, { scaleX: 0, transformOrigin: "left center", duration: 0.4, ease: "power3.inOut" }, T);
 tl.fromTo(new, { scaleX: 0, transformOrigin: "right center", opacity: 1 },
-  { scaleX: 1, duration: 0.4, ease: "power3.inOut" }, T + 0.1);
+  { scaleX: 1, opacity: 1, duration: 0.4, ease: "power3.inOut" }, T + 0.1);
 tl.set(old, { opacity: 0 }, T + 0.5);
 ```

package/skills/hyperframes-audio/SKILL.md

@@ -13,6 +13,8 @@ description: >
   `/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 Audio
 
 A mix is a set of relationships, not a stack of processors. Two tracks that each
@@ -32,10 +34,11 @@ crossfade envelopes, track gain/track volume, volume and effect automation,
 ducking/voiceover carve, and the effect chain. `/media-use` owns sourcing,
 generation, and preprocessing.
 
-Constant `data-playback-rate` (`0.1..5`) is render-safe for picture and
+Constant `data-playback-rate` (`0.1..10`) is render-safe for picture and
 pitch-preserved sound when matching audio/video elements use the same timing,
-source offset, and rate. Source speed ramps are not supported because there is
-no rate envelope; preprocess a derived synchronized asset. HyperFrames does not
+source offset, and rate. A speed ramp is a `rate` lane in `data-automation`
+(see `docs/reference/speed-ramps`); it wins over the constant and keeps pitch
+in preview and render. HyperFrames does not
 provide automatic waveform sync or drift correction.
 For copyable cut/crossfade/retime recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`.
 
@@ -252,11 +255,7 @@ analysis time, so a clip added to the group later is covered without touching
 <audio id="vo-middle" data-audio-group="voiceover" …></audio>
 <audio id="vo-outro" data-audio-group="voiceover" …></audio>
 
-<audio
-  id="music"
-  data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.25}'
-  …
-></audio>
+<audio id="music" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.8}' …></audio>
 ```
 
 A `sources` list naming two or more plain clip ids instead of a group is caught
@@ -355,17 +354,26 @@ many bands, how wide, how far to favour intelligibility over raw voice energy,
 how far the level may drop, how far under the voice to aim. Those six move
 together in any real mix — a gentle carve is a shallow cut in few bands with
 little ducking, a hard one is deeper in more bands with more — so they are one
-relationship written once, in `carveProfile`. Default is `0.25` — a 6 dB dip in
-three bands with 6 dB of level room, audible without sounding like a hole. At
-`0.5` the dip reaches 10 dB, which is where a carve starts being heard as an
-effect rather than as room for the voice; above that is deliberate territory for
-a loud bed under a quiet voice. `0` is spectral only — one band, no level match
-at all.
-
-**Carve by default.** A bed playing under narration wants a carve; it is not a
-polish step to get to if there is time. Place both tracks, run the command below,
-listen. Skip it only when there is no narration for the music to sit under — a
-music video, a title card, a montage cut to the track.
+relationship written once, in `carveProfile`. `carve.mjs` defaults to `0.8` —
+six bands from 250 Hz to 2.5 kHz cut about 7 dB each and 15 dB at 1.6 kHz, with
+19 dB of level room — because a bed under narration has to get out of the way
+first and be music second; `0.25` (a 6 dB dip in three bands, 6 dB of room) kept
+the bed present but still let it fight the voice, and was judged too weak in
+practice. At `0.5` the dip reaches 10 dB, which is where a carve starts being
+heard as an effect rather than as room for the voice. Drop the strength when the
+bed is the point and the voice is sparse. `0` is spectral only — one band, no
+level match at all.
+
+**Carve by default — required whenever music plays under a voice.** A bed
+under any voice track (narration, avatar speech, interview, voiceover) gets a
+carve as part of finishing the mix, not as a polish step to get to if there is
+time. Place both tracks, run the command below (default strength `0.8`; add
+`--bed` / `--voice` when detection picks wrong), confirm the written
+`data-fx-carve`, `data-fx-chain` and `data-automation` with `npx hyperframes check`,
+and only then render. A volume duck on its own is not a finished mix: it leaves
+the voice and the bed fighting in the 1–3 kHz band and costs the bed all of its
+presence for the whole voiceover. Skip the carve only when there is no voice for
+the music to sit under — a music video, a title card, a montage cut to the track.
 
 **It always follows the voice.** There is no static mode: a fixed depth thins the
 bed through every pause, and once you have heard both there is no reason to want it.
@@ -399,9 +407,9 @@ dynamically at the default strength, and prints what it decided:
 ```
 bed    music-bed (name looks like music)
 voice  narration (only track left)
-carve  strength 0.25 dynamic
-bands  400Hz -6dB q1.4, 1000Hz -3dB q1.4, 1600Hz -3.17dB q1.4
-level  216-point envelope, floor -6 dB
+carve  strength 0.8 dynamic
+bands  250Hz -7.4dB q2.06, 400Hz -7.4dB q2.06, 630Hz -7.4dB q2.06, 1000Hz -7.4dB q2.06, 1600Hz -14.8dB q2.06, 2500Hz -7.4dB q2.06
+level  273-point envelope, floor -19.2 dB
 ```
 
 Name the tracks with `--bed` / `--voice` (repeatable) when the automatic choice is

package/skills/hyperframes-audio/scripts/carve.mjs

@@ -34,17 +34,20 @@ import { pathToFileURL } from "node:url";
  *  bands and envelopes come out the same either way. */
 const SAMPLE_RATE = 48000;
 
+/** Default carve strength. 0.25 kept the bed present but still fighting the voice. */
+export const DEFAULT_STRENGTH = 0.8;
+
 const usage = `carve.mjs --comp <file.html> [--bed <elementId>] [--voice <elementId> ...]
               [--strength 0..1] [--dry-run] [--core <dir>]
 
   --bed       id of the music track that gets carved   (detected if omitted)
   --voice     id of a voice to make room for; repeatable (detected if omitted)
-  --strength  how hard to carve, 0..1 (default 0.25)
+  --strength  how hard to carve, 0..1 (default ${DEFAULT_STRENGTH})
   --dry-run   report what it would write, touch nothing
   --core      directory to resolve @hyperframes/core from (default: the comp's)`;
 
-function parseArgs(argv) {
-  const args = { strength: 0.25, dryRun: false, voices: [] };
+export function parseArgs(argv) {
+  const args = { strength: DEFAULT_STRENGTH, dryRun: false, voices: [] };
   for (let i = 0; i < argv.length; i += 1) {
     const flag = argv[i];
     const next = () => {

package/skills/hyperframes-audio/scripts/carve.test.mjs

@@ -5,7 +5,13 @@ import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { carveSources, groupSourceRefusal, loadCore } from "./carve.mjs";
+import {
+  DEFAULT_STRENGTH,
+  carveSources,
+  groupSourceRefusal,
+  loadCore,
+  parseArgs,
+} from "./carve.mjs";
 
 const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -237,3 +243,12 @@ test("members is required, so dropping it cannot silently restore the group form
   assert.throws(() => carveSources(voices, bed("bgm", "music")), TypeError);
   assert.throws(() => groupSourceRefusal(voices, bed("bgm", "music")), TypeError);
 });
+
+test("the default strength is 0.8, and --strength still overrides it", () => {
+  // 0.25 left the bed audibly fighting the voice on narrated builds; a carve at
+  // the default has to already be a finished mix. Pinned so it cannot drift back
+  // unnoticed — core pins its own DEFAULT_CARVE the same way.
+  assert.equal(DEFAULT_STRENGTH, 0.8);
+  assert.equal(parseArgs(["--comp", "x.html"]).strength, 0.8);
+  assert.equal(parseArgs(["--comp", "x.html", "--strength", "0.25"]).strength, 0.25);
+});