# Sub-Compositions
A sub-composition is a separate HTML file embedded in a host composition. HyperFrames loads it, seeks it independently, and composites the result into the host at `data-start`.
## Host Wiring
In the host composition, the sub-composition appears as a clip with `data-composition-src`:
```html
```
- `data-composition-id` on the host must match the internal `data-composition-id` of the file at `data-composition-src`.
- The host clip needs its own `data-start`, `data-duration`, `data-track-index`, `data-width`, `data-height`.
## Sub-Composition File Structure
### Mental model — what the runtime actually does
When a host loads a sub-composition via `data-composition-src`, the runtime:
1. `fetch`es the HTML file.
2. Parses it with `DOMParser`.
3. **Finds the `` element and clones ONLY its contents into the host slot.**
4. Everything **outside** the `` (including the entire ``) is **discarded**.
So `` is not just a wrapper — it is the **transport container**. If a node needs to exist in the live render, it must be inside ``. Full stop.
### File shape
```html
```
Contrast with **standalone** compositions, which put the root directly in `` with no `` wrapper.
## Common pitfalls that pass static checks but break at render
`lint`, `validate`, and `inspect` evaluate each file in isolation. These two failures live in the **cross-file mount contract** and cannot be caught until the runtime actually tries to mount the sub-composition. Watch for them at author time and verify with the pre-render checklist below.
### Pitfall 1 — `
...
...
```
**Why this happens:** standard HTML conventions tell you to put `
```
**Why this happens:** when sub-compositions are inlined into one composited render, the compiler **scopes each file's CSS to its own `data-composition-id`** so scenes can't leak styles into each other — every rule `S` becomes `[data-composition-id=""] S` (a _descendant_ selector). A rule whose leftmost selector is the **root's own class** (`.frame`) therefore becomes `[data-composition-id=""] .frame`, which cannot match the root (the root _is_ the scoped element, not a descendant of it), so **every `.frame…` rule silently drops**. `#root` is special-cased by the scoper and keeps matching the root; plain descendant selectors (`.title`) match normally. The per-scene class namespace is also just redundant — the `data-composition-id` scope already isolates each scene's styles.
**Symptom:** _identical_ to Pitfall 1 — tiny unstyled text in the top-left, images at natural size, inline styles (e.g. a card background) the only thing surviving. The trap: this passes `lint`/`validate`/`inspect` (they evaluate the file in isolation, unscoped) **and looks perfect in `preview`** (Studio mounts each scene in its own iframe, also unscoped) — it only breaks in the composited MP4 render. Lint rule `subcomposition_root_styled_by_class` flags it; the registry blocks (e.g. `apple-money-count`) model the `#root` pattern.
### Verification checklist before render
```bash
# For every sub-composition file in compositions/:
# 1)