ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(skills): teach agents the variables system across SKILL.md + docs

Browse Source 
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>
This commit is contained in:
James
2026-05-04 20:25:42 +00:00
committed by James Russo
co-authored by Claude Opus 4.7
parent 1c9d726b5e
commit 211a9214d0
4 changed files with 137 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/cli/src/docs/compositions.md
+26 -7
View File
@@ -26,14 +26,33 @@ Use `npx hyperframes compositions` to see all compositions in a project.
## Variables
HyperFrames does not automatically bind `data-var-*` attributes into your composition DOM.
Declare variables on the composition's `<html>` root, then read them inside any composition script with `window.__hyperframes.getVariables()`. Override per-instance via `data-variable-values` on the host element, or at render time via `npx hyperframes render --variables '{...}'`.
```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.