` -- Nested compositions (animations, grouped sequences)
+- **content** — text, shapes, images, video, audio, or another composition;
+- **time** — when each part starts and how long it remains;
+- **motion** — seekable animation tied to the same playhead.
-See the [HTML Schema Reference](/reference/html-schema) for the full list of attributes on each clip type.
+The main composition also defines the output frame and total duration.
-## Nested Compositions
+## When to create another composition
-You can embed one composition inside another in two ways: loading from an external file or defining it inline. External files are the recommended approach for reusable compositions.
+Separate a part when it has a clear job and can be understood on its own.
-
-
- Reference another HTML file with `data-composition-src`. The framework automatically fetches the file, extracts the `` content, mounts it, executes scripts, and registers the timeline.
+Good boundaries include:
- `data-composition-src` paths resolve relative to the **project root**, not the referencing file — a nested composition one level deep still writes `compositions/foo.html`, never `../compositions/foo.html`.
+- a complete scene;
+- a repeated title or caption treatment;
+- a product-demo sequence;
+- a visual reused in several places;
+- a complex section that is easier to review separately.
- ```html index.html
-
- ```
+Do not split every small element into its own file. Extra nesting makes a simple project harder to follow.
- Each external composition file wraps its content in a `` tag:
+## How nesting works
- ```html compositions/intro-anim.html
-
-
-
Welcome!
+The main composition gives each nested composition a place on its timeline:
-
-
-
-
- ```
-
- `data-playback-start` selects the child timeline time shown when the host begins. It defaults to `0`. A left trim or split advances this source-time offset by the elapsed host time multiplied by `data-playback-rate`, so the nested animation remains continuous instead of restarting.
-
-
- Define a nested composition directly inside the parent. This is simpler for one-off compositions that do not need to be reused.
-
- ```html index.html
-
- ```
-
- Inline compositions do not use `` tags or `data-composition-src`.
-
-
-
-### Project Structure
-
-
-
-
-
-
-
-
-
-
-## Two Layers: Primitives and Scripts
-
-Every composition has two layers:
-
-- **HTML** -- primitive clips (`video`, `img`, `audio`, nested compositions). The declarative structure: what plays, when, and on which track. Controlled by [data attributes](/concepts/data-attributes).
-- **Script** -- effects, transitions, dynamic DOM, canvas, SVG -- creative animation via [GSAP](/guides/gsap-animation). Scripts do **not** control media playback or clip visibility.
-
-
- Never use scripts to play/pause/seek media elements or to show/hide clips based on timing. The framework handles this automatically from data attributes. Scripts that duplicate this behavior will conflict with the framework. See [Common Mistakes](/guides/common-mistakes) for examples.
-
-
-## Variables
-
-HyperFrames does not automatically bind `data-var-*` attributes into your composition DOM or CSS.
-
-The supported pattern is:
-
-1. Declare the variables once on the sub-comp's composition root with `data-composition-variables` (id + type + default) — the `` element for a full-document composition, or the `[data-composition-id]` root element for a template / fragment sub-composition.
-2. Pass per-instance values on each composition host with `data-variable-values`.
-3. Read the resolved values inside the composition with `window.__hyperframes.getVariables()`. The runtime layers the host's `data-variable-values` over the declared defaults on a per-instance basis, so the same source can be embedded multiple times with different values.
-
-```html index.html
+```html
-
```
-```html compositions/card.html
-
-
-
-
-
-
-```
+## Decide where to make a change
-If you are building tooling on top of `@hyperframes/core`, the same `data-composition-variables` array is readable via `extractCompositionMetadata()` for Studio editing UI and analysis pipelines.
+- Edit the **nested composition** when the scene itself should change everywhere it is used.
+- Edit the **main composition** when only its placement, duration, or relationship to other scenes should change.
+- Ask the **agent** when a revision changes the story or crosses several compositions.
-## Listing Compositions
+In Studio, open or expand a nested scene when you need to work inside it, then use the breadcrumb to return to the parent sequence.
-Use the [CLI](/packages/cli) to see all compositions in a project:
+## Continue
-```bash
-npx hyperframes compositions
-```
-
-## Next Steps
-
-
-
- Full reference for timing, media, and composition attributes
-
-
- Add animations to your compositions with GSAP timelines
-
-
- Start from built-in examples for common video patterns
-
-
- Complete schema for authoring compositions
-
-
+Use [Variables](/concepts/variables) when the design should stay fixed while approved content changes. Use the [HTML schema](/reference/html-schema) when you need exact element and attribute rules.
diff --git a/docs/concepts/data-attributes.mdx b/docs/concepts/data-attributes.mdx
index 73d135c33..a71e3d452 100644
--- a/docs/concepts/data-attributes.mdx
+++ b/docs/concepts/data-attributes.mdx
@@ -1,111 +1,69 @@
---
-title: Data Attributes
-description: "Core attributes for controlling element timing and behavior."
+title: "Time elements with data attributes"
+sidebarTitle: "Data attributes"
+description: "Place clips on the HyperFrames timeline without putting timing logic in JavaScript."
---
-Hyperframes uses HTML data attributes to control timing, media playback, and [composition](/concepts/compositions) structure. These are the declarative building blocks of every video.
+HyperFrames keeps timing in HTML. A timed element normally needs a stable ID,
+a start, a duration, and a track:
-## Timing Attributes
-
-| Attribute | Example | Description |
-|-----------|---------|-------------|
-| `data-start` | `"0"` or `"intro"` | Start time in seconds, or a clip ID reference for [relative timing](#relative-timing) |
-| `data-duration` | `"5"` | Duration in seconds. Required for images and sub-compositions. Optional for video/audio (defaults to source duration). On the **root** composition it sets the total render length (see [Composition Attributes](#composition-attributes)). |
-| `data-track-index` | `"0"` | Timeline track number. Temporal ordering — groups clips into rows on the timeline. Clips on the same track cannot overlap. Does **not** control z-ordering (use CSS `z-index` for that). |
-
-## Media Attributes
-
-| Attribute | Example | Description |
-|-----------|---------|-------------|
-| `data-media-start` | `"2"` | Media playback offset / trim point in seconds. Default: `0` |
-| `data-playback-start` | `"2"` | Source-time offset in seconds for media wrappers and nested composition hosts. Missing values default to `0`; Studio writes this attribute when a composition is trimmed or split. |
-| `data-playback-rate` | `"1.5"` | Source playback multiplier, clamped to `0.1`–`5`. Source time advances by timeline elapsed time multiplied by the canonical rate; invalid values default to `1`. |
-| `data-volume` | `"0.8"` | Audio/video volume, 0 to 1 |
-| `data-has-audio` | `"true"` | Indicates video has an audio track |
-
-## Composition Attributes
-
-| Attribute | Example | Description |
-|-----------|---------|-------------|
-| `data-composition-id` | `"root"` | Unique ID for [composition](/concepts/compositions) wrapper (required on every composition) |
-| `data-width` | `"1920"` | Composition width in pixels |
-| `data-height` | `"1080"` | Composition height in pixels |
-| `data-duration` (root) | `"30"` | On the **root** composition, the total render length / frame count in seconds. Read once from the source HTML at compile time, like `data-width` / `data-height`, so a script or `hyperframes render --variables` cannot change it (author it directly, one value per output). If the root omits `data-duration`, and only then, the renderer derives the total length from the live DOM / timeline after scripts run. |
-| `data-composition-src` | `"./intro.html"` | Path to external [composition](/concepts/compositions) HTML file |
-| `data-variable-values` | `'{"title":"Hello"}'` | JSON object of values passed to a nested composition. Inside the sub-composition, read them via `window.__hyperframes.getVariables()` — the runtime layers these over the sub-comp's own `data-composition-variables` defaults and exposes the merged result on a per-instance basis (the same source can be embedded multiple times with different values). |
-| `data-composition-variables` | `'[{"id":"title","type":"string","label":"Title","default":"Hello"}]'` | JSON array of declared variables (`id`, `type`, `label`, `default`). Drives Studio editing UI and provides defaults read by `window.__hyperframes.getVariables()`. The CLI flag `hyperframes render --variables '
'` overrides these defaults at top-level render time; host elements override them per-instance via `data-variable-values`. |
-| `data-var-src` | `"heroImage"` | Binds the element's `src` to a declared variable — the runtime substitutes the value (URL string or image `{url}`) in preview and render; the authored `src` stays as the fallback. |
-| `data-var-text` | `"title"` | Binds the element's own text to a scalar variable. Element children (nested clips, animated spans) are preserved. Scalar variables are also applied as `--{id}` CSS custom properties on the composition root, so `color: var(--accent)` responds to overrides. |
-
-## Element Visibility
-
-Add `class="clip"` to all timed elements so the runtime can manage their visibility lifecycle:
-
-```html index.html
-
- Hello World
-
+```html
+
```
-## Relative Timing
+| Attribute | What it controls |
+| ------------------ | ------------------------------------------------ |
+| `data-start` | When the element enters the composition timeline |
+| `data-duration` | How long its timeline slot lasts |
+| `data-track-index` | Which timeline lane owns that slot |
-Instead of calculating absolute start times, a clip can reference another clip's `id` in its `data-start` attribute. This means "start when that clip ends":
+Add `class="clip"` to timed DOM and image elements so the runtime can control
+their visibility. Video visibility is managed by the media runtime; audio has
+no visual lifecycle.
-```html index.html
-
- Overlapping clips must be on different tracks -- clips on the same track cannot overlap in time.
-
+References resolve only inside the same composition. The referenced clip must
+have a known duration, and reference chains cannot contain a cycle.
-
- **Same composition only** -- references resolve within the clip's parent [composition](/concepts/compositions). You cannot reference a clip in a sibling or parent composition.
+## Media and nested compositions
- **No circular references** -- A cannot start after B if B starts after A. The resolver detects cycles and throws an error.
+Media can also declare a source offset, playback rate, and volume. A nested
+composition adds a source path and its own fixed timeline window. These are
+exact contracts rather than new timing models.
- **Referenced clip must have a known duration** -- either an explicit `data-duration` or a duration inferred from source media. If the referenced clip has no known duration, the reference cannot resolve.
-
- **Parsing rules** -- if the value is a valid number, it is treated as absolute seconds. Otherwise it is parsed as one of:
- - `` -- start when that clip ends
- - ` + ` -- start N seconds after that clip ends
- - ` - ` -- start N seconds before that clip ends
-
- **Chain length** -- references can chain (`A` -> `B` -> `C`), but deeply nested chains make the timeline harder to reason about. Keep chains under 3-4 levels for readability.
-
-
-## Next Steps
-
-
-
- How compositions use data attributes to define video structure
-
-
- Complete attribute reference with per-element details
-
-
- Animate elements alongside data-attribute-driven timing
-
-
- Pitfalls to avoid when setting up timing and attributes
-
-
+Use the [HTML schema reference](/reference/html-schema) for every supported
+attribute and element-specific rule. Use [Compositions](/concepts/compositions)
+to decide when a scene should become a separate composition.
diff --git a/docs/concepts/determinism.mdx b/docs/concepts/determinism.mdx
index bd42da7a5..87f9b6375 100644
--- a/docs/concepts/determinism.mdx
+++ b/docs/concepts/determinism.mdx
@@ -1,103 +1,72 @@
---
title: Deterministic Rendering
-description: "Same input, identical output. Every time."
+description: "Make every frame depend on the playhead, not the wall clock."
---
-Hyperframes is built around a core guarantee: **the same [composition](/concepts/compositions) always produces the same video**. This is what makes automated pipelines, CI testing, and AI-driven workflows reliable.
+HyperFrames renders by seeking to one frame at a time. A well-authored composition can therefore reproduce the same state whenever the renderer seeks to the same frame.
-## How It Works
+This is what makes a slow animation safe to render: the renderer does not need to play it in real time, and it does not drop frames when a frame takes longer to produce.
-The rendering pipeline is frame-by-frame and seek-driven. No realtime playback is involved -- every frame is independently seeked and captured.
+## The rendering model
-
-
- The [engine](/packages/engine) computes the time for each frame using integer math: `time = floor(frame) / fps`. There is no wall-clock dependency -- rendering is entirely decoupled from real time.
-
-
- The [frame adapter](/concepts/frame-adapters) receives a `seekFrame(frame)` call and deterministically positions all animations, DOM state, and canvas content to the exact frame. The adapter pauses all [GSAP](/guides/gsap-animation) timelines and seeks them to the computed time.
-
-
- Chrome's `HeadlessExperimental.beginFrame` API captures the pixel buffer for the current frame. This is a single, atomic operation -- no partial paints or race conditions.
-
-
- FFmpeg encodes the captured frames into the final MP4 video. Audio tracks from `` and `` elements are mixed in during this stage.
-
-
+For each output frame, HyperFrames:
-```mermaid
-graph LR
- A["Frame Clock
- Local rendering (without Docker) may show slight differences due to platform-specific font rendering and Chrome version. Use Docker mode when exact reproducibility matters.
-
-
-## For Adapter Authors
-
-If you are building a [frame adapter](/concepts/frame-adapters), your adapter must follow the determinism contract:
-
-- `seekFrame(frame)` must be idempotent -- same frame, same result
-- No side effects that depend on call order (must handle random access)
-- No async operations that resolve after the frame is "committed"
-- Clean lifecycle: `init` -> `seekFrame` (N times) -> `destroy`
-
-## Next Steps
+## Continue
-
- Build adapters that uphold the determinism contract
+
+ Choose local, Docker, batch, or cloud rendering.
-
- Render to MP4 locally or in Docker
-
-
- The full rendering pipeline that orchestrates deterministic output
-
-
- Pitfalls that break determinism and how to avoid them
+
+ Understand preview speed, capture cost, and render time.
diff --git a/docs/concepts/frame-adapters.mdx b/docs/concepts/frame-adapters.mdx
index 18c3679bb..463d0db9b 100644
--- a/docs/concepts/frame-adapters.mdx
+++ b/docs/concepts/frame-adapters.mdx
@@ -1,148 +1,73 @@
---
-title: Frame Adapters
-description: "Bring your own animation runtime to Hyperframes."
+title: "Frame adapters"
+description: "Connect a seekable animation timeline to a custom HyperFrames host."
---
-The Frame Adapter pattern is how Hyperframes supports multiple animation runtimes. The core question every adapter answers:
-
-> What should the screen look like at frame N?
-
-If a runtime can answer that, it can plug into Hyperframes.
-
- The Adapter API is currently at **v0** (experimental). Breaking changes are possible until v1. The core contract (seek-by-frame, deterministic output) is stable, but method signatures may evolve.
+ The exported `FrameAdapter` interface is experimental v0 API. Its signatures
+ may change before v1.
-## How It Works
+A frame adapter answers one question: what state should an animation have at frame N?
-The host application (the [engine](/packages/engine) or [producer](/packages/producer)) drives rendering by calling adapter methods in a strict sequence. The adapter never controls its own clock -- it only responds to seek commands.
+Most composition authors do not implement this interface. HyperFrames already seeks registered GSAP, CSS, Anime.js, Lottie, Three.js, Web Animations, and TypeGPU animation through its browser runtime. Use the [GSAP guide](/guides/gsap-animation) for the normal authoring path.
-```mermaid
-sequenceDiagram
- participant Host as Host (Engine)
- participant Adapter as Frame Adapter
- participant Chrome as Chrome / Browser
+Use `FrameAdapter` when you are building a custom host around a seekable animation object.
- Host->>Adapter: init(context)
- Adapter-->>Host: ready
- Host->>Adapter: getDurationFrames()
- Adapter-->>Host: 300 frames
+## Interface
- loop For each frame 0..300
- Host->>Host: normalize frame (clamp, floor)
- Host->>Adapter: seekFrame(frame)
- Adapter->>Chrome: Update DOM / canvas state
- Adapter-->>Host: done
- Host->>Chrome: Capture pixel buffer
- end
-
- Host->>Adapter: destroy()
- Adapter-->>Host: cleaned up
-```
-
-## Adapter API (v0)
-
-```typescript adapters/types.ts
-type FrameAdapterContext = {
- compositionId: string;
- fps: number;
- width: number;
- height: number;
- rootElement?: HTMLElement;
-};
+```ts
+import type { FrameAdapter, FrameAdapterContext } from "@hyperframes/core";
type FrameAdapter = {
id: string;
- init?: (ctx: FrameAdapterContext) => Promise | void;
+ init?: (context: FrameAdapterContext) => Promise | void;
getDurationFrames: () => number;
seekFrame: (frame: number) => Promise | void;
destroy?: () => Promise | void;
};
```
-## Required Semantics
+The context contains the composition ID, frame rate, dimensions, and optional root element.
-- `getDurationFrames()` must return a finite integer >= 0
-- `seekFrame(frame)` must support arbitrary seek order (forward, backward, random)
-- `seekFrame(frame)` must be idempotent for the same input frame
-- `seekFrame(frame)` must clamp internal time to the adapter's range
-- Adapters should be paused/seek-driven, not clock-driven
+## Adapt a GSAP timeline
-## Host Orchestration
+`@hyperframes/core` includes a helper for a GSAP-like timeline:
-The host normalizes frames before calling the adapter:
+```ts
+import { createGSAPFrameAdapter } from "@hyperframes/core";
-```typescript engine/render-loop.ts
-normalizedFrame = clamp(Math.floor(frame), 0, durationFrames);
+const adapter = createGSAPFrameAdapter({
+ id: "intro",
+ fps: 30,
+ timeline,
+});
+
+await adapter.init?.({
+ compositionId: "intro",
+ fps: 30,
+ width: 1920,
+ height: 1080,
+});
+
+await adapter.seekFrame(90); // three seconds
```
-A typical render loop:
+The helper pauses the timeline, derives its frame length, and converts each frame request to seconds.
-```typescript engine/render-loop.ts
-await adapter.init?.({ compositionId, fps, width, height, rootElement });
-const durationFrames = adapter.getDurationFrames();
+## Contract
-for (let frame = 0; frame <= durationFrames; frame += 1) {
- await adapter.seekFrame(frame);
- // capture pixel buffer for this frame
-}
+A custom adapter must:
-await adapter.destroy?.();
-```
+- return a finite, non-negative frame count;
+- support forward, backward, and random seeks;
+- return the same state when the same frame is requested again;
+- avoid wall-clock timers and unseeded randomness;
+- finish asynchronous work before the frame is captured;
+- release listeners and other resources in `destroy()`.
-## Determinism Contract
+The host still owns the capture and encoding pipeline. The adapter owns only the animation state.
-These rules are non-negotiable for any adapter. They are the foundation of Hyperframes' [deterministic rendering](/concepts/determinism) guarantee.
+## Continue
-- Canonical clock: `t = frame / fps`
-- No wall-clock dependencies (`Date.now`, drift-dependent logic)
-- No unseeded randomness
-- No render-time network fetches
-- Fixed output params (`fps`, `width`, `height`)
-- Finite duration only
-- Deterministic frame quantization before seek
-
-## Supported Runtimes
-
-First-party runtime adapters:
-
-All runtime adapters live in the `/hyperframes-animation` skill — invoke it for the runtime-specific seek API as well as motion rules, scene blueprints, and transitions.
-
-| Runtime | Seek Method | Skill |
-|---------|-------------|-------|
-| [GSAP](/guides/gsap-animation) | `timeline.totalTime(timeSeconds)` or `timeline.seek(timeSeconds)` | `/hyperframes-animation` |
-| Anime.js | `instance.seek(timeMs)` for animations registered on `window.__hfAnime` | `/hyperframes-animation` |
-| CSS keyframes | Browser `Animation.currentTime`, with paused negative-delay fallback | `/hyperframes-animation` |
-| Lottie / dotLottie | `goToAndStop(timeMs, false)`, raw-frame setters, or player seek APIs | `/hyperframes-animation` |
-| Three.js / WebGL | `hf-seek` events plus `window.__hfThreeTime` for deterministic scene rendering | `/hyperframes-animation` |
-| Web Animations API | `document.getAnimations()` and `animation.currentTime` | `/hyperframes-animation` |
-| TypeGPU / WebGPU | GPU compute shaders with deterministic seek via `hf-seek` events | `/hyperframes-animation` |
-
-Community adapters are welcome -- if it can seek by frame, it belongs in Hyperframes.
-
-## Conformance Tests
-
-Every adapter should pass these minimum tests:
-
-1. **Repeatability** -- seek same frame twice, get identical output
-2. **Random seek** -- seek order `[90, 10, 50, 10]` produces deterministic results
-3. **Bounds** -- negative and overflow frame values do not break
-4. **Duration** -- returned duration is a finite integer
-5. **Cleanup** -- no leaked timers/listeners after `destroy`
-
-## Next Steps
-
-
-
- Understand the determinism guarantees adapters must uphold
-
-
- See the first-party GSAP adapter in action
-
-
- The capture engine that drives adapters during rendering
-
-
- Build and contribute your own adapter
-
-
+Read [Deterministic rendering](/concepts/determinism) for the timing rules or [`@hyperframes/core`](/packages/core) for the package exports.
diff --git a/docs/concepts/variables.mdx b/docs/concepts/variables.mdx
index 407fb7609..344614386 100644
--- a/docs/concepts/variables.mdx
+++ b/docs/concepts/variables.mdx
@@ -1,383 +1,193 @@
---
-title: Variables
-description: "Parameterize compositions so the same source can render different content."
+title: "Reuse a design with variables"
+sidebarTitle: "Variables"
+description: "Change approved text, colors, media, and choices without rebuilding the composition."
---
-Variables let you declare named, typed slots in a composition and fill them at render time — from a parent composition, from the CLI, or from an API call. A card composition that takes `title` and `color` can be embedded a hundred times with a hundred different values without duplicating any HTML.
+Variables expose the parts of a composition that are meant to change. One
+customer card can accept a different name, logo, color, and plan while keeping
+the same layout and motion.
-## Declaring Variables
+Use a variable when the design should remain stable across versions. Make a
+normal source edit when the structure itself needs to change.
-Add `data-composition-variables` to a composition's declaration root. For a full-document composition that's the `` element; for a template / fragment sub-composition (which has no `` shell of its own) it's the composition root element — the `[data-composition-id]` div. Its value is a JSON array of variable declarations — one object per variable:
+
+
+
+
+
+ The same design with different values
+
+
+
Pro
-### Parameterizing media assets
+
-
-
-
-
-
-The runtime probes the DOM after your composition script runs, so a `` or `` `src` assigned at runtime from a variable is discovered and pre-extracted for the render. No extra wiring required — just set the `src` from your variable.
-
-
-The same pattern covers the three media element types:
-
-- **``** — assign from a string variable, but keep the timing attributes (`data-start`, `data-duration`, `data-track-index`, `data-has-audio`) on the element itself. The probe phase scans `video[data-start]` elements after your script runs and reads the resolved `src` for pre-extraction.
-- **``** — same as video. The audio is decoded during capture and mixed into the final output.
-
-Pass assets as URL references your composition resolves at render time; don't inline base64. URL-shaped assets travel cleanly through both the local renderer and the Lambda surface — see [Templates on Lambda](/deploy/templates-on-lambda#working-with-large-variables) for the 256 KiB execution-input cap on distributed renders.
-
-### Parameterizing media color grading
-
-Media color grading can also read exact variable references inside
-`data-color-grading`. Use `$name` or `${name}` as the entire value for a field;
-the runtime resolves it from the current composition's variables before applying
-the shader grading, finishing details, blur/pixelate effects, and optional LUT:
-
-```html compositions/hero.html
-
-
-
-
-
-
-```
-
-When the same composition is embedded multiple times, each host's
-`data-variable-values` can produce different grading without copying or rewriting
-the media element's `data-color-grading` JSON.
-
-### Swapping media: do you need to vary duration too?
-
-A common follow-up: if a variable swaps a `` to a different clip, does `data-duration` need to change too? Usually no. `data-duration` is optional on `` and `` — leave it off and the renderer ffprobes the source and uses its natural length:
-
-```html compositions/hero.html
-
-This live-DOM re-read applies to clip and media elements, **not** to the **root composition's own `data-duration`** (its total render length / frame count). The renderer reads the root `data-duration` once at compile time, before your scripts run, exactly like `data-width` / `data-height`. If the root element carries a static `data-duration`, a script (or a variable) that rewrites it afterward is ignored, and the render uses the compile-time value. To make total render length vary per render, author the root `data-duration` directly (one value per output) rather than trying to drive it from a script. See [What can't be a variable](#what-cant-be-a-variable).
-
+Use `window.__hyperframes.getVariables()` only when the result needs conditions,
+loops, or derived values:
-## What can't be a variable
-
-A small set of inputs are read once from the source HTML or from the CLI / SDK, with no live-DOM re-read — no script (and therefore no variable) can change them:
-
-| What | Mechanism (not a variable) |
-|------|----------------------------|
-| Composition dimensions | `data-width` / `data-height` on the composition element, parsed from the source HTML at compile time, not from the live DOM |
-| Root composition total duration | `data-duration` on the **root** composition element (the total render length / frame count), parsed from the source HTML at compile time. A static root `data-duration` is locked before scripts run, so neither a script nor a variable can change the render length. (A clip's own `data-duration` is different: it is re-read from the live DOM, as shown above.) |
-| Frame rate | `--fps` flag on `hyperframes render`, or `config.fps` in the SDK |
-| Output format / codec / quality | `--format` / `--codec` / `--quality` flags, or the SDK equivalents |
-| A sibling or parent composition's variables | Variables are per-composition; use [`data-variable-values`](#per-instance-overrides-sub-compositions) on each sub-comp host element to pass overrides |
-
-The deeper rule: variables are runtime values your script applies to the DOM. They can drive anything the renderer reads from the live DOM after that script runs: text, colors, media `src`, even clip `data-duration` as shown above. They can't change inputs the renderer reads once at compile time (composition dimensions, and the root composition's total duration / render length) or that live entirely outside the composition (CLI flags, encoder settings).
-
-## Reading Variables at Runtime
-
-Inside any composition script, call `window.__hyperframes.getVariables()` to get the resolved variable values. The return type is `Partial>` — use destructuring with defaults matching the declared `default` values:
-
-```html compositions/card.html
-
-
-
-
- `data-var-src` is only honored on media elements (`img`, `video`, `audio`,
- `source`) and only for safe URL protocols (`http(s):`, `blob:`, relative
- paths, and `data:image/…`). A binding on a script-executing tag such as
- ` 
+ 
+