docs(skills): document variables system in SKILL.md + docs (PR 4/4) by jrusso1020 · Pull Request #603 · heygen-com/hyperframes

jrusso1020 · 2026-05-03T00:56:00Z

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

Doc-only PR — no source code, no tests.
Format check passes via bunx oxfmt --check on the touched markdown files.
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

jrusso1020 · 2026-05-03T01:23:37Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

jrusso1020 · 2026-05-03T16:30:46Z

-  data-variable-values='{"title":"Hello","color":"#ff4d4f"}'
-></div>
+<!-- compositions/card.html -->
+<html data-composition-variables='[


this is data-composition-variables but it says data-variable-values is this correct?

Good catch — data-variable-values (per-instance host override) and data-composition-variables (declaration on <html> root) are different attributes and the prose conflated them. Fixed in e5cbfe9: replaced the intro sentence with a two-bullet list naming each attribute and its role, then a follow-up explaining where the CLI --variables fits.

jrusso1020 · 2026-05-03T16:31:13Z


 **Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.

+**Parametrized renders:** declare variables on `<html data-composition-variables='[...]'>` and read them inside the composition with `window.__hyperframes.getVariables()`. Override at render time with `--variables '{"title":"Q4 Report"}'`. Missing keys fall through to declared defaults, so the same composition runs unchanged in dev preview and in production renders. See the `hyperframes` skill for the full pattern.


same comment here

Same fix in e5cbfe9: rewrote the parametrized-renders paragraph so declaration (data-composition-variables) and CLI override (--variables) are distinct sentences. The per-instance data-variable-values attribute is parenthetical with a forward reference to the hyperframes skill where the full pattern lives.

James pointed out (compositions.md:33, SKILL.md:121) that the prose referenced `data-variable-values` while the example below showed `data-composition-variables`, leaving readers to wonder if the two names referred to the same thing. They don't: one declares, the other overrides per-instance. Both are now named at first mention and the declare-vs-override split is called out explicitly. - packages/cli/src/docs/compositions.md: replaced the single intro sentence with a two-bullet list ("data-composition-variables declares, data-variable-values overrides per-instance") and a follow-up explaining where the CLI fits in. - skills/hyperframes-cli/SKILL.md: rewrote the parametrized-renders paragraph so declaration (data-composition-variables) and override (--variables) are distinct sentences, with the per-instance attribute parenthetical for completeness. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Follow-up on the PR #603 review. The previous fix named both attributes but didn't make their distinct shapes / roles obvious; a reader could still wonder "are these two views of the same data?". Now the doc opens with the shape contrast (array of declarations vs object of values) and the section closes with a numbered precedence layering so the merge order is unambiguous. - compositions.md: replaced the bullet list with a shape-first description ("JSON array of declarations" vs "JSON object keyed by variable id"), an explicit "they aren't redundant" line, and a numbered list of the three precedence layers (declared default → host data-variable-values → CLI --variables). - skills/hyperframes-cli/SKILL.md: highlighted the same shape contrast inside the parametrized-renders paragraph (declarations array vs values object). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

James pointed out (compositions.md:33, SKILL.md:121) that the prose referenced `data-variable-values` while the example below showed `data-composition-variables`, leaving readers to wonder if the two names referred to the same thing. They don't: one declares, the other overrides per-instance. Both are now named at first mention and the declare-vs-override split is called out explicitly. - packages/cli/src/docs/compositions.md: replaced the single intro sentence with a two-bullet list ("data-composition-variables declares, data-variable-values overrides per-instance") and a follow-up explaining where the CLI fits in. - skills/hyperframes-cli/SKILL.md: rewrote the parametrized-renders paragraph so declaration (data-composition-variables) and override (--variables) are distinct sentences, with the per-instance attribute parenthetical for completeness. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Follow-up on the PR #603 review. The previous fix named both attributes but didn't make their distinct shapes / roles obvious; a reader could still wonder "are these two views of the same data?". Now the doc opens with the shape contrast (array of declarations vs object of values) and the section closes with a numbered precedence layering so the merge order is unambiguous. - compositions.md: replaced the bullet list with a shape-first description ("JSON array of declarations" vs "JSON object keyed by variable id"), an explicit "they aren't redundant" line, and a numbered list of the three precedence layers (declared default → host data-variable-values → CLI --variables). - skills/hyperframes-cli/SKILL.md: highlighted the same shape contrast inside the parametrized-renders paragraph (declarations array vs values object). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

James pointed out (compositions.md:33, SKILL.md:121) that the prose referenced `data-variable-values` while the example below showed `data-composition-variables`, leaving readers to wonder if the two names referred to the same thing. They don't: one declares, the other overrides per-instance. Both are now named at first mention and the declare-vs-override split is called out explicitly. - packages/cli/src/docs/compositions.md: replaced the single intro sentence with a two-bullet list ("data-composition-variables declares, data-variable-values overrides per-instance") and a follow-up explaining where the CLI fits in. - skills/hyperframes-cli/SKILL.md: rewrote the parametrized-renders paragraph so declaration (data-composition-variables) and override (--variables) are distinct sentences, with the per-instance attribute parenthetical for completeness. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Follow-up on the PR #603 review. The previous fix named both attributes but didn't make their distinct shapes / roles obvious; a reader could still wonder "are these two views of the same data?". Now the doc opens with the shape contrast (array of declarations vs object of values) and the section closes with a numbered precedence layering so the merge order is unambiguous. - compositions.md: replaced the bullet list with a shape-first description ("JSON array of declarations" vs "JSON object keyed by variable id"), an explicit "they aren't redundant" line, and a numbered list of the three precedence layers (declared default → host data-variable-values → CLI --variables). - skills/hyperframes-cli/SKILL.md: highlighted the same shape contrast inside the parametrized-renders paragraph (declarations array vs values object). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Distribution PR for the variables feature stack: tells agents how to declare, read, and override variables across the four authoring surfaces. skills/hyperframes/SKILL.md: - Added data-variable-values + data-composition-variables to the data-attributes tables (host element + <html> root respectively). - New "Variables (Parametrized Compositions)" section right after "Composition Structure". Three-step pattern (declare / read / override), full worked example with enum variable, sub-comp per-instance pattern with two hosts sharing a source, and rules of thumb (always provide defaults; read once, not in frame loops; use --strict-variables in CI; type validation behavior). skills/hyperframes-cli/SKILL.md: - Added --variables, --variables-file, --strict-variables to the render flag table. - Short paragraph below the table explaining the parametrized-render pattern with a forward reference to the hyperframes skill. docs/packages/core.mdx: - Added a code snippet showing getVariables<T>() inside a composition and validateVariables/formatVariableValidationIssue for tooling. packages/cli/src/docs/compositions.md (the in-CLI `npx hyperframes docs compositions` content): - Replaced the hand-rolled JSON.parse(host.dataset.variableValues) pattern with the modern getVariables() pattern. This is PR 4 of the 4-PR stack. The openai/plugins mirror is a separate follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

James pointed out (compositions.md:33, SKILL.md:121) that the prose referenced `data-variable-values` while the example below showed `data-composition-variables`, leaving readers to wonder if the two names referred to the same thing. They don't: one declares, the other overrides per-instance. Both are now named at first mention and the declare-vs-override split is called out explicitly. - packages/cli/src/docs/compositions.md: replaced the single intro sentence with a two-bullet list ("data-composition-variables declares, data-variable-values overrides per-instance") and a follow-up explaining where the CLI fits in. - skills/hyperframes-cli/SKILL.md: rewrote the parametrized-renders paragraph so declaration (data-composition-variables) and override (--variables) are distinct sentences, with the per-instance attribute parenthetical for completeness. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Follow-up on the PR #603 review. The previous fix named both attributes but didn't make their distinct shapes / roles obvious; a reader could still wonder "are these two views of the same data?". Now the doc opens with the shape contrast (array of declarations vs object of values) and the section closes with a numbered precedence layering so the merge order is unambiguous. - compositions.md: replaced the bullet list with a shape-first description ("JSON array of declarations" vs "JSON object keyed by variable id"), an explicit "they aren't redundant" line, and a numbered list of the three precedence layers (declared default → host data-variable-values → CLI --variables). - skills/hyperframes-cli/SKILL.md: highlighted the same shape contrast inside the parametrized-renders paragraph (declarations array vs values object). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jrusso1020 · 2026-05-04T20:33:36Z

Merge activity

May 4, 8:33 PM UTC: @jrusso1020 merged this pull request with Graphite.

… (PR 5/5) (#604) ## What End-to-end Docker regression test that exercises the **full variables chain** shipped in PRs #600-#603. Closes the loop between unit-tested seams and the actual rendered output. This is **PR 5 of 5**, the regression cap. Stacked on `feat/get-variables-skills` (PR #603). ## Why PRs 1-4 ship unit tests that cover the seams independently: - Engine: \`evaluateOnNewDocument\` injection (mocked Puppeteer) - Helper: \`getVariables()\` merge (jsdom) - CLI: \`parseVariablesArg\` validation (pure function) - Loader: \`__hfVariablesByComp\` population (jsdom) - Validator: \`validateVariables\` type-checking (pure) But none of those check that the chain actually works front-to-back inside the production Chrome+ffmpeg+harness combo. A type signature change on \`CaptureOptions.variables\`, a regression in \`evaluateOnNewDocument\` ordering, a bug in the runtime helper's attribute parsing — any of those could pass unit tests and silently render the wrong text. This regression catches it. ## How **Fixture** (\`packages/producer/tests/variables-prod/\`): - \`src/index.html\` — composition with three declared variables (\`title\`, \`subtitle\`, \`bgColor\`) read via \`window.__hyperframes.getVariables()\` and rendered as positioned text on a colored background. **No animation** — keeps the regression frame-stable so it isolates "did the variables flow through?" from motion concerns. - \`meta.json\` — tags \`[\"variables\", \"composition\"]\` (runs in the existing fast shard's tag filter, no workflow YAML changes needed). \`renderConfig.variables\` provides override values that the baseline reflects (\"Override Title\", \"Override subtitle\", \`#0a3d62\`). **If variables don't propagate**, the rendered frame shows declared defaults (\"Default Title\", black) — visibly different from the baseline, so PSNR fails on dozens of frames. - \`output/output.mp4\` — Docker-generated baseline per the project's CLAUDE.md golden-baseline rule. Host renders drift across Chrome/font versions and would fail PSNR even on green code. - \`src/silence.wav\` — copied from \`missing-host-comp-id\`'s silence track to satisfy the audio-correlation check. **Harness change** (\`packages/producer/src/regression-harness.ts\`): - \`TestMetadata.renderConfig\` gains an optional \`variables: Record<string, unknown>\` field, validated as a JSON object (not array, not null) in the \`meta.json\` validator. - The \`createRenderJob\` call site forwards \`renderConfig.variables\` to \`RenderConfig.variables\`, which the engine already consumes via \`evaluateOnNewDocument\` (PR #600). ## Test plan - [x] **\`docker:test variables-prod\` PASSED** — 100/100 visual checkpoints, audio correlation 1.000. - [x] **Defeated the bug it's meant to catch** — generated a baseline against an old image (without the harness change) and confirmed it shows defaults. After the harness change + image rebuild, the baseline correctly shows overrides. - [x] **CI auto-includes** — fast shard's \`--exclude-tags slow,render-compat,hdr\` lets \`[variables, composition]\` through. No \`.github/workflows/regression.yml\` edits needed. ## Backwards compatibility Additive. Existing fixtures don't set \`renderConfig.variables\` and behave identically. The harness validator only fires on the new field if it's present. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jrusso1020 mentioned this pull request May 3, 2026

test(producer): add variables-prod regression for the variables stack (PR 5/5) #604

Merged

3 tasks

This was referenced May 3, 2026

feat(core,cli): variable schema validation + lint rules (PR 3/4) #602

Merged

feat(core): scope getVariables() per sub-comp instance (PR 2/4) #601

Merged

feat(core,cli,engine,producer): getVariables() helper + --variables render flag (PR 1/4) #600

Merged

miguel-heygen approved these changes May 3, 2026

View reviewed changes

jrusso1020 commented May 3, 2026

View reviewed changes

vanceingalls approved these changes May 4, 2026

View reviewed changes

jrusso1020 force-pushed the feat/get-variables-validation branch from a10b3f6 to 239c3c8 Compare May 4, 2026 19:42

jrusso1020 force-pushed the feat/get-variables-skills branch from 5543921 to 10b96b8 Compare May 4, 2026 19:42

jrusso1020 force-pushed the feat/get-variables-validation branch 2 times, most recently from 366a64c to 09da5db Compare May 4, 2026 20:06

jrusso1020 force-pushed the feat/get-variables-skills branch from 10b96b8 to 4dea0a0 Compare May 4, 2026 20:06

jrusso1020 changed the base branch from feat/get-variables-validation to graphite-base/603 May 4, 2026 20:25

jrusso1020 and others added 2 commits May 4, 2026 20:25

jrusso1020 force-pushed the feat/get-variables-skills branch from 4dea0a0 to 524dbe0 Compare May 4, 2026 20:25

graphite-app Bot changed the base branch from graphite-base/603 to main May 4, 2026 20:26

jrusso1020 force-pushed the feat/get-variables-skills branch from 524dbe0 to 21243b6 Compare May 4, 2026 20:26

jrusso1020 merged commit 62c2589 into main May 4, 2026
30 checks passed

jrusso1020 deleted the feat/get-variables-skills branch May 4, 2026 20:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(skills): document variables system in SKILL.md + docs (PR 4/4)#603

docs(skills): document variables system in SKILL.md + docs (PR 4/4)#603
jrusso1020 merged 3 commits intomainfrom
feat/get-variables-skills

jrusso1020 commented May 3, 2026

Uh oh!

jrusso1020 commented May 3, 2026 •

edited

Loading

Uh oh!

jrusso1020 May 3, 2026

Uh oh!

jrusso1020 May 3, 2026

Uh oh!

jrusso1020 May 3, 2026

Uh oh!

jrusso1020 May 3, 2026

Uh oh!

Uh oh!

jrusso1020 commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Quality guidance: `draft` while iterating, `standard` for review, `high` for final delivery.

		Parametrized renders: declare variables on `<html data-composition-variables='[...]'>` and read them inside the composition with `window.__hyperframes.getVariables()`. Override at render time with `--variables '{"title":"Q4 Report"}'`. Missing keys fall through to declared defaults, so the same composition runs unchanged in dev preview and in production renders. See the `hyperframes` skill for the full pattern.

Conversation

jrusso1020 commented May 3, 2026

What

Why

How

Test plan

Backwards compatibility

Uh oh!

jrusso1020 commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jrusso1020 May 3, 2026

Choose a reason for hiding this comment

Uh oh!

jrusso1020 May 3, 2026

Choose a reason for hiding this comment

Uh oh!

jrusso1020 May 3, 2026

Choose a reason for hiding this comment

Uh oh!

jrusso1020 May 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrusso1020 commented May 4, 2026

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jrusso1020 commented May 3, 2026 •

edited

Loading