docs(registry): use the installed launcher in block guides (#8101)

This commit is contained in:
terencecho
2026-11-17 20:01:35 +00:00
committed by GitHub
parent 88ba1b4d7c
commit 1c99314a62
13 changed files with 98 additions and 14 deletions
+3 -1
View File
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
+3 -1
View File
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
+3 -1
View File
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
@@ -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
+3 -1
View File
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
+2
View File
@@ -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
+3 -1
View File
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"` in the project directory. Use the absolute path to your installed HyperFrames skills for `<SKILLS>`. 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
+1 -4
View File
@@ -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).
@@ -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
@@ -0,0 +1,5 @@
# Render
```sh
npx --yes hyperframes@0.8.12 render
```
+65 -3
View File
@@ -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 "<SKILLS>/hyperframes/scripts/plugin-cli.mjs"'));
assert.equal(firstMatch(skill, /^npx hyperframes render '([^']+)'/m), target);
});
}