diff --git a/packages/cli/src/docs/compositions.md b/packages/cli/src/docs/compositions.md index 5cd4cb9a2..79ef1c88f 100644 --- a/packages/cli/src/docs/compositions.md +++ b/packages/cli/src/docs/compositions.md @@ -26,12 +26,16 @@ Use `npx hyperframes compositions` to see all compositions in a project. ## Variables -Two attributes work together: +Two attributes with different shapes and different jobs: -- **`data-composition-variables`** on the `` root *declares* the variables (id, type, label, default). -- **`data-variable-values`** on a sub-comp host element *overrides* values for that one instance. +- **`data-composition-variables`** on the `` 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. -Inside any composition script, `window.__hyperframes.getVariables()` returns the merged result of declarations + overrides. CLI `npx hyperframes render --variables '{...}'` provides a top-level override that layers the same way. +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 diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index 399a35790..86c5f5a0b 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -118,7 +118,7 @@ npx hyperframes render --docker # byte-identical **Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery. -**Parametrized renders:** the composition declares its variables on the `` root with `data-composition-variables` (id/type/label/default per entry) and reads them in any script via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` 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 via `data-variable-values` — see the `hyperframes` skill.) +**Parametrized renders:** the composition declares its variables on the `` 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