From 1c99314a62788cb960236102f2f7bc4e022fa178 Mon Sep 17 00:00:00 2001 From: terencecho <3916587+terencecho@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:01:35 +0000 Subject: [PATCH] docs(registry): use the installed launcher in block guides (#8101) --- registry/blocks/canopy-part-title/SKILL.md | 4 +- registry/blocks/code-slice-hero/SKILL.md | 4 +- registry/blocks/cuboid-carousel/SKILL.md | 4 +- .../frost-sequence-camera-orbit/SKILL.md | 4 +- .../source/README.md | 2 + registry/blocks/glass-shard-title/SKILL.md | 4 +- registry/blocks/godrays/source/README.md | 2 + registry/blocks/orbit-card/SKILL.md | 4 +- .../blocks/wireframe-portal-title/SKILL.md | 4 +- .../path-traced-3d/assets/vendor/README.md | 5 +- .../examples/path-traced-3d/source/README.md | 2 + .../fixtures/registry-pinned-command/SKILL.md | 5 ++ scripts/registry-skill-files.test.ts | 68 ++++++++++++++++++- 13 files changed, 98 insertions(+), 14 deletions(-) create mode 100644 scripts/fixtures/registry-pinned-command/SKILL.md diff --git a/registry/blocks/canopy-part-title/SKILL.md b/registry/blocks/canopy-part-title/SKILL.md index e592aa0b94..f2a2f443bd 100644 --- a/registry/blocks/canopy-part-title/SKILL.md +++ b/registry/blocks/canopy-part-title/SKILL.md @@ -17,6 +17,8 @@ Composition id: `canopy-part-title`. Duration 12 s at 30 fps, 1920×1080. ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add canopy-part-title`; by default the files above land under `compositions/canopy-part-title/`. Then mount the block from the host `index.html`: ```html @@ -34,7 +36,7 @@ Install with `npx hyperframes add canopy-part-title`; by default the files above Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/canopy-part-title/canopy-part-title.html' --variables '{"headline1":"Understory","headline2":"Move slowly"}' +npx hyperframes render 'compositions/canopy-part-title/canopy-part-title.html' --variables '{"headline1":"Understory","headline2":"Move slowly"}' ``` ## Variables diff --git a/registry/blocks/code-slice-hero/SKILL.md b/registry/blocks/code-slice-hero/SKILL.md index b80ca0bbfa..af26f6c11f 100644 --- a/registry/blocks/code-slice-hero/SKILL.md +++ b/registry/blocks/code-slice-hero/SKILL.md @@ -21,6 +21,8 @@ Composition id: `code-slice-hero`. Duration 8 s at 30 fps, 1920×1080. ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add code-slice-hero`; by default the files above land under `compositions/code-slice-hero/`. Then mount the block from the host `index.html`: ```html @@ -38,7 +40,7 @@ Install with `npx hyperframes add code-slice-hero`; by default the files above l Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/code-slice-hero/code-slice-hero.html' --variables '{"headline":"MAKE IT","reverseHeadline":"MATTER."}' +npx hyperframes render 'compositions/code-slice-hero/code-slice-hero.html' --variables '{"headline":"MAKE IT","reverseHeadline":"MATTER."}' ``` ## Variables diff --git a/registry/blocks/cuboid-carousel/SKILL.md b/registry/blocks/cuboid-carousel/SKILL.md index f6b88d97e6..6d7985953a 100644 --- a/registry/blocks/cuboid-carousel/SKILL.md +++ b/registry/blocks/cuboid-carousel/SKILL.md @@ -23,6 +23,8 @@ Composition id: `cuboid-carousel`. Duration 6.666666666666667 s at 30 fps, 1920 ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add cuboid-carousel`; by default the files above land under `compositions/cuboid-carousel/`. Then mount the block from the host `index.html`: ```html @@ -40,7 +42,7 @@ Install with `npx hyperframes add cuboid-carousel`; by default the files above l Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/cuboid-carousel/cuboid-carousel.html' --variables '{"cardsJson":"","heroCard":4}' +npx hyperframes render 'compositions/cuboid-carousel/cuboid-carousel.html' --variables '{"cardsJson":"","heroCard":4}' ``` ## Variables diff --git a/registry/blocks/frost-sequence-camera-orbit/SKILL.md b/registry/blocks/frost-sequence-camera-orbit/SKILL.md index a994b36609..e358fc0a4c 100644 --- a/registry/blocks/frost-sequence-camera-orbit/SKILL.md +++ b/registry/blocks/frost-sequence-camera-orbit/SKILL.md @@ -32,6 +32,8 @@ Composition id: `frost-sequence-rig`. Duration 22.5 s at 30 fps, 1920×1080. ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add frost-sequence-camera-orbit`; by default the files above land under `compositions/frost-sequence-camera-orbit/`. Then mount the block from the host `index.html`: ```html @@ -49,7 +51,7 @@ Install with `npx hyperframes add frost-sequence-camera-orbit`; by default the f Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/frost-sequence-camera-orbit/frost-sequence-camera-orbit.html' --variables '{"headline1":"Hard to|break.","headline2":"Easy to|remember."}' +npx hyperframes render 'compositions/frost-sequence-camera-orbit/frost-sequence-camera-orbit.html' --variables '{"headline1":"Hard to|break.","headline2":"Easy to|remember."}' ``` ## Variables diff --git a/registry/blocks/frost-sequence-camera-orbit/source/README.md b/registry/blocks/frost-sequence-camera-orbit/source/README.md index 44d754326e..ff49ca55df 100644 --- a/registry/blocks/frost-sequence-camera-orbit/source/README.md +++ b/registry/blocks/frost-sequence-camera-orbit/source/README.md @@ -7,6 +7,8 @@ lightweight WebGL editor helper, via `src/motion/editor.ts`). ## Build +Run these build commands from this source directory in a trusted checkout of the HyperFrames repository. Installed projects already contain the bundle. + ```sh npm install npm run build diff --git a/registry/blocks/glass-shard-title/SKILL.md b/registry/blocks/glass-shard-title/SKILL.md index 4086a6336a..82b51580b9 100644 --- a/registry/blocks/glass-shard-title/SKILL.md +++ b/registry/blocks/glass-shard-title/SKILL.md @@ -25,6 +25,8 @@ Composition id: `glass-shard-title`. Duration 12.16 s at 30 fps, 1920×1080. ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add glass-shard-title`; by default the files above land under `compositions/glass-shard-title/`. Then mount the block from the host `index.html`: ```html @@ -42,7 +44,7 @@ Install with `npx hyperframes add glass-shard-title`; by default the files above Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/glass-shard-title/glass-shard-title.html' --variables '{"headline":"Designed in glass","tileCount":8}' +npx hyperframes render 'compositions/glass-shard-title/glass-shard-title.html' --variables '{"headline":"Designed in glass","tileCount":8}' ``` ## Variables diff --git a/registry/blocks/godrays/source/README.md b/registry/blocks/godrays/source/README.md index ed35bd58c2..2ce961be0b 100644 --- a/registry/blocks/godrays/source/README.md +++ b/registry/blocks/godrays/source/README.md @@ -12,6 +12,8 @@ attribute picks the shader. ## Build +Run these build commands from this source directory in a trusted checkout of the HyperFrames repository. Installed projects already contain the bundle. + ```sh npm ci npm run build diff --git a/registry/blocks/orbit-card/SKILL.md b/registry/blocks/orbit-card/SKILL.md index b3f8616398..c09303fd09 100644 --- a/registry/blocks/orbit-card/SKILL.md +++ b/registry/blocks/orbit-card/SKILL.md @@ -25,6 +25,8 @@ Composition id: `orbit-card`. Duration 10 s at 30 fps, 1920×1080. ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add orbit-card`; by default the files above land under `compositions/orbit-card/`. Then mount the block from the host `index.html`: ```html @@ -42,7 +44,7 @@ Install with `npx hyperframes add orbit-card`; by default the files above land u Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/orbit-card/orbit-card.html' --variables '{"feature1Title":"Always in sync","feature1Desc":"Changes reach every screen the moment they happen."}' +npx hyperframes render 'compositions/orbit-card/orbit-card.html' --variables '{"feature1Title":"Always in sync","feature1Desc":"Changes reach every screen the moment they happen."}' ``` ## Variables diff --git a/registry/blocks/wireframe-portal-title/SKILL.md b/registry/blocks/wireframe-portal-title/SKILL.md index 76047a55a5..6646cb40b7 100644 --- a/registry/blocks/wireframe-portal-title/SKILL.md +++ b/registry/blocks/wireframe-portal-title/SKILL.md @@ -19,6 +19,8 @@ Composition id: `wireframe-portal-title`. Duration 8 s at 30 fps, 1920×1080. ## Install +For install and render commands, expand `npx hyperframes` to `node "/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for ``. If the launcher is missing, ask for the skill before proceeding. + Install with `npx hyperframes add wireframe-portal-title`; by default the files above land under `compositions/wireframe-portal-title/`. Then mount the block from the host `index.html`: ```html @@ -36,7 +38,7 @@ Install with `npx hyperframes add wireframe-portal-title`; by default the files Render with custom values by targeting the composition file directly: ```sh -npx --yes hyperframes@0.8.12 render 'compositions/wireframe-portal-title/wireframe-portal-title.html' --variables '{"title":"BREAKTHROUGH","replacementPhrase":"Lets do this sir!"}' +npx hyperframes render 'compositions/wireframe-portal-title/wireframe-portal-title.html' --variables '{"title":"BREAKTHROUGH","replacementPhrase":"Lets do this sir!"}' ``` ## Variables diff --git a/registry/examples/path-traced-3d/assets/vendor/README.md b/registry/examples/path-traced-3d/assets/vendor/README.md index f19dec8d48..144e163a3b 100644 --- a/registry/examples/path-traced-3d/assets/vendor/README.md +++ b/registry/examples/path-traced-3d/assets/vendor/README.md @@ -14,7 +14,4 @@ and `GradientEquirectTexture`. Built with esbuild 0.25.12 (`--bundle --format=esm --minify --target=es2020`). SHA-256 of the bundle: `a247cb7f88eff8b1d423a2892e5ca27c7d03d83939fe0ca6fa9a11c7f9f21fc9`. -To rebuild it, or to change the versions, use the `source/` folder of this example in the -HyperFrames repository -(https://github.com/heygen-com/hyperframes/tree/main/registry/examples/path-traced-3d/source): -`npm ci && npm run build`. The same pinned versions produce the same file. +To rebuild the bundle or update its dependencies, follow the [maintainer instructions in the HyperFrames repository](https://github.com/heygen-com/hyperframes/tree/main/registry/examples/path-traced-3d/source). diff --git a/registry/examples/path-traced-3d/source/README.md b/registry/examples/path-traced-3d/source/README.md index e533fca8a8..c11f5511e2 100644 --- a/registry/examples/path-traced-3d/source/README.md +++ b/registry/examples/path-traced-3d/source/README.md @@ -9,6 +9,8 @@ files listed in `../registry-item.json`. `package-lock.json` into `../assets/vendor/three-path-tracer.min.js`, and copies the three licence files beside it. +Run these build commands from this source directory in a trusted checkout of the HyperFrames repository. Installed projects already contain the bundle. + ```sh npm ci npm run build diff --git a/scripts/fixtures/registry-pinned-command/SKILL.md b/scripts/fixtures/registry-pinned-command/SKILL.md new file mode 100644 index 0000000000..b7a92541dc --- /dev/null +++ b/scripts/fixtures/registry-pinned-command/SKILL.md @@ -0,0 +1,5 @@ +# Render + +```sh +npx --yes hyperframes@0.8.12 render +``` diff --git a/scripts/registry-skill-files.test.ts b/scripts/registry-skill-files.test.ts index 4b8f844ede..5ce4673012 100644 --- a/scripts/registry-skill-files.test.ts +++ b/scripts/registry-skill-files.test.ts @@ -1,9 +1,10 @@ import assert from "node:assert/strict"; import { existsSync, readFileSync, readdirSync } from "node:fs"; -import { join } from "node:path"; +import { basename, dirname, join, relative } from "node:path"; import { test } from "node:test"; -const BLOCKS = join(import.meta.dirname, "..", "registry", "blocks"); +const REGISTRY = join(import.meta.dirname, "..", "registry"); +const BLOCKS = join(REGISTRY, "blocks"); interface ManifestFile { path: string; @@ -29,6 +30,66 @@ function firstMatch(text: string, pattern: RegExp): string | undefined { return text.match(pattern)?.[1]; } +function usesProjectPackageManager(markdown: string): boolean { + const commands = markdown + .replace(/\\\r?\n/g, "") + .matchAll(/\b(npx|npm|bunx)[ \t]+([-@\w./"']+)/g); + return Array.from(commands).some( + ([, runner, argument]) => runner !== "npx" || argument !== "hyperframes", + ); +} + +function registryCommandViolations(root: string): string[] { + const violations: string[] = []; + for (const entry of readdirSync(root, { recursive: true, withFileTypes: true })) { + if (!entry.isFile()) continue; + const path = join(entry.parentPath, entry.name); + const name = relative(root, path); + const contents = readFileSync(path); + // Commands also appear in manifest strings, templates and source comments. + if ( + contents.includes("hyperframes@") && + /\b(?:npx|npm|bunx|dlx)\b[^\r\n`]*?\bhyperframes@|\bhyperframes@[^\s`]+[ \t]+[\w-]+/.test( + contents.toString("utf8"), + ) + ) { + violations.push(name); + continue; + } + // Source READMEs document maintainer builds in a trusted checkout. + if ( + /\.mdx?$/i.test(entry.name) && + !(entry.name === "README.md" && basename(dirname(path)) === "source") && + usesProjectPackageManager(contents.toString("utf8")) + ) { + violations.push(name); + } + } + return violations.sort(); +} + +test("only the launcher shorthand is a registry package-runner example", () => { + assert.equal(usesProjectPackageManager("Run `npx hyperframes add orbit-card`."), false); + for (const command of [ + "npx --yes hyperframes render", + "npm exec hyperframes", + "bunx hyperframes render", + ]) { + assert.equal(usesProjectPackageManager(command), true, command); + } +}); + +test("registry instructions use the installed HyperFrames launcher", () => { + assert.deepEqual(registryCommandViolations(REGISTRY), []); +}); + +test("the registry check rejects a skill with a pinned render command", () => { + assert.deepEqual( + registryCommandViolations(join(import.meta.dirname, "fixtures", "registry-pinned-command")), + ["SKILL.md"], + ); +}); + const blocks = readdirSync(BLOCKS).filter((name) => existsSync(join(BLOCKS, name, "SKILL.md"))); for (const name of blocks) { @@ -52,6 +113,7 @@ for (const name of blocks) { const { files, skill } = readBlock(name); const target = files.find((file) => file.type === "hyperframes:composition")?.target; assert.equal(firstMatch(skill, /data-composition-src="([^"]+)"/), target); - assert.equal(firstMatch(skill, / render '([^']+)'/), target); + assert.ok(skill.includes('node "/hyperframes/scripts/plugin-cli.mjs"')); + assert.equal(firstMatch(skill, /^npx hyperframes render '([^']+)'/m), target); }); }