fix(skills): use published HyperShader runtime

packages/cli/src/commands/websiteToVideoSkillContent.test.ts

@@ -0,0 +1,25 @@
+// @vitest-environment node
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const REPO_ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..", "..");
+const read = (...parts: string[]): string => readFileSync(join(REPO_ROOT, ...parts), "utf8");
+
+describe("website-to-video public install guidance", () => {
+  it("sources the HyperShader browser bundle from the published package", () => {
+    const build = read("skills", "website-to-video", "references", "step-5-build.md");
+
+    expect(build).toContain("@hyperframes/shader-transitions");
+    expect(build).toContain("node_modules/@hyperframes/shader-transitions/dist/index.global.js");
+    expect(build).not.toContain("cp packages/shader-transitions/dist/index.global.js");
+  });
+
+  it("does not present registry showcase blocks as the reusable HyperShader runtime", () => {
+    const storyboard = read("skills", "website-to-video", "references", "step-3-storyboard.md");
+
+    expect(storyboard).toContain("showcase blocks are standalone demos");
+    expect(storyboard).not.toContain("find the actual shader name used in `HyperShader.init()`");
+  });
+});

skills/website-to-video/references/step-3-storyboard.md

@@ -137,7 +137,7 @@ npx hyperframes catalog --type block 2>/dev/null | head -40
 
 There might be VFX blocks available (vfx-liquid-glass, vfx-iphone-device, vfx-shatter, vfx-portal, etc.), use them for hero treatments instead of basic perspective tilt. You need to install any you want with `npx hyperframes add <name>`. Don't use too many shaders — maximum 2 per video unless user wants differently.
 
-**Shader transitions — block name ≠ shader name.** When you run the commands above and see `domain-warp-dissolve` in `registry/blocks/`, the HyperShader runtime name is `domain-warp` (without "-dissolve"). After installing a block, open its showcase HTML (`compositions/<block-name>.html`) and find the actual shader name used in `HyperShader.init()`. That is what you put in the storyboard. Then delete the showcase file — it's a demo only and will pollute your compositions/ directory with lint warnings.
+**Shader transitions — block name ≠ shader name.** Registry showcase blocks are standalone demos, not the reusable HyperShader runtime, and their HTML may implement the effect directly without calling `HyperShader.init()`. Use the canonical block-to-shader mapping in `skills/hyperframes-registry/references/discovery.md` when writing the storyboard. For example, the `domain-warp-dissolve` block maps to the `domain-warp` runtime name. Installing a showcase is optional visual reference only; if you install one, remove its composition afterward so it does not create unrelated lint warnings.
 
 ## Asset Audit — REQUIRED before writing beats (non-skippable)
 
@@ -303,8 +303,9 @@ Each beat is a WORLD, not a layout. Write what the viewer EXPERIENCES before you
 - **Mechanical:** TYPES ON, CLICKS, LOCKS IN, SNAPS, STEPS
 
 **Transition decision matrix** — shader vs CSS vs hard cut:
-| Shader transition for | CSS crossfade for | Hard cut for |
-|---|---|---|
+
+| Shader transition for                     | CSS crossfade for                                 | Hard cut for                                      |
+| ----------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
 | Hero reveals, logo unveils, "wow" moments | Continuous motion between beats, editorial pacing | Rapid-fire lists, percussive edits, comedy timing |
 
 1–2 shader transitions per video (hero + CTA). Too many flatten their impact. Mix shader and CSS crossfade in one HyperShader composition by omitting `shader` on any transition entry.

skills/website-to-video/references/step-5-build.md

@@ -188,10 +188,12 @@ If the storyboard says "slow" or "cinematic": build each beat as a sub-compositi
 
 For videos with sub-composition beats and scene transitions, `index.html` MUST use `HyperShader.init()`. This is the entire scene orchestration layer. Do NOT try to use registry block sub-compositions (e.g. `compositions/domain-warp-dissolve.html`) for transitions — those are standalone showcase demos, not how HyperShader works in multi-scene compositions.
 
-Copy the local shader build first:
+Install the separately published runtime package and copy its browser bundle into the project. Do not copy from `packages/shader-transitions` — that path exists only inside a HyperFrames source checkout and is absent from the public `hyperframes` CLI package.
 
 ```bash
-cp packages/shader-transitions/dist/index.global.js <project-dir>/hyper-shader-local.js
+cd <project-dir>
+npm install --no-save --package-lock=false @hyperframes/shader-transitions
+cp node_modules/@hyperframes/shader-transitions/dist/index.global.js hyper-shader-local.js
 ```
 
 Full working `index.html` pattern — every field matters: