fix(skills): use published HyperShader runtime

This commit is contained in:
Miguel Ángel
2026-07-13 14:43:49 +00:00
parent 758a6d2152
commit a88d016e3c
3 changed files with 33 additions and 5 deletions
@@ -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()`");
});
});
@@ -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.
@@ -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: