From 21243b69573d67298da63d514bd59487847658ad Mon Sep 17 00:00:00 2001 From: James Date: Sun, 3 May 2026 16:38:18 +0000 Subject: [PATCH] docs: lead with shape contrast for variable attributes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- packages/cli/src/docs/compositions.md | 12 ++++++++---- skills/hyperframes-cli/SKILL.md | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) 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