mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-02 20:18:35 +00:00
docs(skills): document variables system in SKILL.md + docs (PR 4/4) (#603)
## What Distribution PR for the variables feature stack. Tells agents how to declare, read, and override variables across the four authoring surfaces — the two skill files agents load (`hyperframes`, `hyperframes-cli`), the public docs (`docs/packages/core.mdx`), and the in-CLI docs (`npx hyperframes docs compositions`). This is **PR 4 of 4**, the final PR in the stack. Stacked on `feat/get-variables-validation` (PR #602). ## Why PRs 1–3 added the runtime helper, sub-comp scoping, and schema validation, but the only places that mention them are the docs in those PRs. Agents loading `/hyperframes` or `/hyperframes-cli` skills won't know the new attributes/flags exist. This PR closes the loop. ## How - **`skills/hyperframes/SKILL.md`** — new "Variables (Parametrized Compositions)" section right after "Composition Structure" with: declare/read/override pattern, full worked example (with enum), sub-comp per-instance pattern (two hosts sharing a source), rules of thumb (defaults always, read-once, `--strict-variables` in CI, type validation behavior). Also added `data-variable-values` + `data-composition-variables` rows to the existing data-attributes tables. - **`skills/hyperframes-cli/SKILL.md`** — added `--variables`, `--variables-file`, `--strict-variables` to the render flag table; short paragraph forwarding to the hyperframes skill for the full pattern. - **`docs/packages/core.mdx`** — added a code snippet showing `getVariables<T>()` and `validateVariables` / `formatVariableValidationIssue` for tooling that validates CLI / host overrides. - **`packages/cli/src/docs/compositions.md`** — replaced the obsolete `JSON.parse(host.dataset.variableValues)` example with the modern `getVariables()` pattern. The `openai/plugins` mirror is intentionally out of scope. Skills in this repo are the source of truth; the downstream mirror is updated after each release as a separate workflow. ## Test plan - [x] Doc-only PR — no source code, no tests. - [x] Format check passes via `bunx oxfmt --check` on the touched markdown files. - [x] Manual review confirms each example compiles in head against the runtime/CLI surface that PRs 1–3 ship. ## Backwards compatibility Doc-only — no behavior change. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
James Russo
@@ -130,6 +130,18 @@ const meta: CompositionMetadata = extractCompositionMetadata(htmlString);
|
||||
// data-composition-variables='[{"id":"title","label":"Title","type":"string","default":"Hello"}]'
|
||||
// >
|
||||
|
||||
// Read resolved variables inside a composition (declared defaults +
|
||||
// CLI overrides + per-instance host data-variable-values):
|
||||
import { getVariables } from '@hyperframes/core';
|
||||
const { title } = getVariables<{ title: string }>();
|
||||
|
||||
// Validate CLI / host overrides against the declared schema:
|
||||
import { validateVariables, formatVariableValidationIssue } from '@hyperframes/core';
|
||||
const issues = validateVariables({ title: 'Hello', count: 'three' }, meta.variables);
|
||||
for (const issue of issues) {
|
||||
console.warn(formatVariableValidationIssue(issue));
|
||||
}
|
||||
|
||||
// Generate HTML from structured data
|
||||
const html = generateHyperframesHtml(elements, {
|
||||
animations,
|
||||
|
||||
@@ -26,14 +26,42 @@ Use `npx hyperframes compositions` to see all compositions in a project.
|
||||
|
||||
## Variables
|
||||
|
||||
HyperFrames does not automatically bind `data-var-*` attributes into your composition DOM.
|
||||
Two attributes with different shapes and different jobs:
|
||||
|
||||
- **`data-composition-variables`** on the `<html>` root — a JSON **array of declarations** (`{id, type, label, default}` per entry). Defines the schema: which variables exist, what type they are, and what defaults to use when no override is provided.
|
||||
- **`data-variable-values`** on a sub-comp host element — a JSON **object keyed by variable id** (`{"title":"Pro","price":"$29"}`). Carries per-instance overrides for that one mount of the sub-composition.
|
||||
|
||||
They aren't redundant — one is "what variables does this composition have?" and the other is "what values should this particular embed use?" Inside any composition script, `window.__hyperframes.getVariables()` returns the merged result. Layering, lowest to highest precedence:
|
||||
|
||||
1. Declared defaults from `data-composition-variables`
|
||||
2. Per-instance overrides from the host's `data-variable-values` (sub-comp embeds only)
|
||||
3. CLI overrides from `npx hyperframes render --variables '{...}'` (top-level renders only)
|
||||
|
||||
```html
|
||||
<div
|
||||
data-composition-id="card"
|
||||
data-composition-src="compositions/card.html"
|
||||
data-variable-values='{"title":"Hello","color":"#ff4d4f"}'
|
||||
></div>
|
||||
<!-- compositions/card.html -->
|
||||
<html data-composition-variables='[
|
||||
{"id":"title","type":"string","label":"Title","default":"Hello"},
|
||||
{"id":"color","type":"color","label":"Color","default":"#111827"}
|
||||
]'>
|
||||
<body>
|
||||
<div data-composition-id="card" data-width="1920" data-height="1080">
|
||||
<h1 class="title"></h1>
|
||||
<script>
|
||||
const { title, color } = window.__hyperframes.getVariables();
|
||||
document.querySelector(".title").textContent = title;
|
||||
document.querySelector(".title").style.color = color;
|
||||
</script>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Read `data-variable-values` inside the nested composition and apply the values in your own script. Variable metadata for tooling is declared separately via `data-composition-variables` and read with `extractCompositionMetadata()`.
|
||||
```html
|
||||
<!-- index.html — embed twice with different per-instance values -->
|
||||
<div data-composition-id="card-pro" data-composition-src="compositions/card.html"
|
||||
data-variable-values='{"title":"Pro","color":"#ff4d4f"}'></div>
|
||||
<div data-composition-id="card-enterprise" data-composition-src="compositions/card.html"
|
||||
data-variable-values='{"title":"Enterprise","color":"#22c55e"}'></div>
|
||||
```
|
||||
|
||||
The runtime layers `data-variable-values` over the sub-comp's declared defaults on a per-instance basis. The same `getVariables()` call works at the top level too — the CLI flag `--variables` provides the override, declared `default`s fall through for missing keys.
|
||||
|
||||
@@ -101,20 +101,25 @@ npx hyperframes render --format webm # transparent WebM
|
||||
npx hyperframes render --docker # byte-identical
|
||||
```
|
||||
|
||||
| Flag | Options | Default | Notes |
|
||||
| -------------- | --------------------- | -------------------------- | --------------------------- |
|
||||
| `--output` | path | renders/name_timestamp.mp4 | Output path |
|
||||
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
|
||||
| `--quality` | draft, standard, high | standard | draft for iterating |
|
||||
| `--format` | mp4, webm | mp4 | WebM supports transparency |
|
||||
| `--workers` | 1-8 or auto | auto | Each spawns Chrome |
|
||||
| `--docker` | flag | off | Reproducible output |
|
||||
| `--gpu` | flag | off | GPU-accelerated encoding |
|
||||
| `--strict` | flag | off | Fail on lint errors |
|
||||
| `--strict-all` | flag | off | Fail on errors AND warnings |
|
||||
| Flag | Options | Default | Notes |
|
||||
| -------------------- | --------------------- | -------------------------- | ------------------------------------------------------------------ |
|
||||
| `--output` | path | renders/name_timestamp.mp4 | Output path |
|
||||
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
|
||||
| `--quality` | draft, standard, high | standard | draft for iterating |
|
||||
| `--format` | mp4, webm | mp4 | WebM supports transparency |
|
||||
| `--workers` | 1-8 or auto | auto | Each spawns Chrome |
|
||||
| `--docker` | flag | off | Reproducible output |
|
||||
| `--gpu` | flag | off | GPU-accelerated encoding |
|
||||
| `--strict` | flag | off | Fail on lint errors |
|
||||
| `--strict-all` | flag | off | Fail on errors AND warnings |
|
||||
| `--variables` | JSON object | — | Override variable values declared in `data-composition-variables` |
|
||||
| `--variables-file` | path | — | JSON file with variable values (alternative to `--variables`) |
|
||||
| `--strict-variables` | flag | off | Fail render on undeclared keys or type mismatches in `--variables` |
|
||||
|
||||
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
|
||||
|
||||
**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI **`--variables '{"title":"Q4 Report"}'`** is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with **`data-variable-values`** — same object shape, scoped to one mount of the sub-composition. See the `hyperframes` skill for the full pattern.)
|
||||
|
||||
## Transcription
|
||||
|
||||
```bash
|
||||
|
||||
@@ -148,13 +148,20 @@ Layered effects (glow behind text, shadow elements, background patterns) and z-s
|
||||
|
||||
### Composition Clips
|
||||
|
||||
| Attribute | Required | Values |
|
||||
| ---------------------------- | -------- | -------------------------------------------- |
|
||||
| `data-composition-id` | Yes | Unique composition ID |
|
||||
| `data-start` | Yes | Start time (root composition: use `"0"`) |
|
||||
| `data-duration` | Yes | Takes precedence over GSAP timeline duration |
|
||||
| `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) |
|
||||
| `data-composition-src` | No | Path to external HTML file |
|
||||
| Attribute | Required | Values |
|
||||
| ---------------------------- | -------- | ----------------------------------------------------------------- |
|
||||
| `data-composition-id` | Yes | Unique composition ID |
|
||||
| `data-start` | Yes | Start time (root composition: use `"0"`) |
|
||||
| `data-duration` | Yes | Takes precedence over GSAP timeline duration |
|
||||
| `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) |
|
||||
| `data-composition-src` | No | Path to external HTML file |
|
||||
| `data-variable-values` | No | JSON object of per-instance variable overrides on a sub-comp host |
|
||||
|
||||
On the root `<html>` element:
|
||||
|
||||
| Attribute | Required | Values |
|
||||
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `data-composition-variables` | No | JSON array of declared variables (id/type/label/default) — drives Studio editing UI and provides defaults for `getVariables()` |
|
||||
|
||||
## Composition Structure
|
||||
|
||||
@@ -184,6 +191,75 @@ Sub-composition structure:
|
||||
|
||||
Load in root: `<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`
|
||||
|
||||
## Variables (Parametrized Compositions)
|
||||
|
||||
Render the same composition with different content — title, theme color, prices, captions — without editing the source HTML.
|
||||
|
||||
**Three-step pattern:**
|
||||
|
||||
1. **Declare** variables on the composition's `<html>` root with `data-composition-variables`. Each entry needs `id`, `type` (one of `string`, `number`, `color`, `boolean`, `enum`), `label`, and `default`. Enum entries also need `options: [{value, label}, ...]`.
|
||||
2. **Read** the resolved values inside the composition's script with `window.__hyperframes.getVariables()`. Returns the merged result of declared defaults + per-instance overrides + CLI overrides.
|
||||
3. **Override** at render time with `npx hyperframes render --variables '{...}'` (top-level) or with `data-variable-values='{...}'` on the host element (per-instance for sub-comps).
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html
|
||||
data-composition-variables='[
|
||||
{"id":"title","type":"string","label":"Title","default":"Hello"},
|
||||
{"id":"theme","type":"enum","label":"Theme","default":"light","options":[
|
||||
{"value":"light","label":"Light"},
|
||||
{"value":"dark","label":"Dark"}
|
||||
]}
|
||||
]'
|
||||
>
|
||||
<body>
|
||||
<div data-composition-id="root" data-width="1920" data-height="1080">
|
||||
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
|
||||
<script>
|
||||
const { title, theme } = window.__hyperframes.getVariables();
|
||||
document.getElementById("hero").textContent = title;
|
||||
document.body.dataset.theme = theme;
|
||||
</script>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
```bash
|
||||
# Dev preview uses declared defaults
|
||||
npx hyperframes preview
|
||||
|
||||
# Render with overrides
|
||||
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4
|
||||
|
||||
# Or from a JSON file
|
||||
npx hyperframes render --variables-file ./vars.json
|
||||
```
|
||||
|
||||
**Sub-composition per-instance values:** the same `getVariables()` works inside sub-comps loaded via `data-composition-src`. Each host element passes its own values:
|
||||
|
||||
```html
|
||||
<div
|
||||
data-composition-id="card-pro"
|
||||
data-composition-src="compositions/card.html"
|
||||
data-variable-values='{"title":"Pro","price":"$29"}'
|
||||
></div>
|
||||
<div
|
||||
data-composition-id="card-enterprise"
|
||||
data-composition-src="compositions/card.html"
|
||||
data-variable-values='{"title":"Enterprise","price":"Custom"}'
|
||||
></div>
|
||||
```
|
||||
|
||||
The runtime layers each host's `data-variable-values` over the sub-comp's declared defaults on a per-instance basis, so the same source can be embedded multiple times with different content.
|
||||
|
||||
**Rules of thumb:**
|
||||
|
||||
- Always provide a sensible `default` for every declared variable. Dev preview uses defaults — without them, the composition won't render correctly until `--variables` is provided.
|
||||
- Read variables once at the top of the script (`const { title } = ...`), not inside frame loops or event handlers — `getVariables()` allocates a fresh object per call.
|
||||
- Use `--strict-variables` in CI to fail fast on undeclared keys or type mismatches.
|
||||
- Variable types are validated at render time. `string`, `number`, `boolean`, and `color` (hex string) check `typeof`; `enum` checks the value is in the declared `options`.
|
||||
|
||||
## Video and Audio
|
||||
|
||||
Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
|
||||
|
||||
Reference in New Issue
Block a user