The runtime absorbed a series of authoring mistakes over time and `runtime/init.ts`
says so in its own comments, but the skills kept teaching the old rules. Four of
them actively cost an agent a failing run: add `crossorigin` (lint rejects it
unconditionally), never build a timeline inside `async` (lint calls that the
documented contract), never `gsap.set` later-scene clips (two fixHints instruct
exactly that), and 12 copyable media snippets with no `id`, which render silent.
Corrected in every place each claim appeared, including `hyperframes-animation`,
three workflow scripts, the scaffolded project instructions, the CLI `docs`
command, and the public docs site: `data-track-index` is a Studio display lane
the render never reads, `class="clip"` is a layout convention rather than a
visibility requirement, timed elements may nest, the visibility window is
half-open, sub-composition host dimensions are backfilled, and the root-fill rule
applies only to the layered-composite path.
Behaviour changes, each backed by a render rather than by reading code:
- `timeline_registry_missing_init` deleted. The runtime creates the registry
before any inline script; a composition without the guard line renders and
animates correctly.
- `video_nested_in_timed_element` kept, message corrected. A rendered repro shows
the nested-with-local-start case really does break, so the rule guards a real
defect, but nothing is "FROZEN": the extractor ignores the wrapper's offset
while visibility uses it, so the clip shows wrong frames and then vanishes.
- `mediaRenderIds` now stamps media whose source is a `<source>` child, closing a
duplicate-id gap the old `[src]`-only selector left open.
- Stale messages fixed on `subcomposition_root_styled_by_class` and
`deprecated_data_layer`.
`coreSkillContent.test.ts` pinned the literal sentence that made root
`data-start` look required, so it is narrowed to structure plus the regression it
genuinely catches.
Not covered, and flagged in the PR: the media global-vs-local start heuristic in
`runtime/init.ts` is the root cause behind the nested-video defect. Removing it
changes the meaning of existing compositions and needs its own deprecation.
- html-schema: the previous clause claimed a composition host's data-media-start is
never read. It is: readElementPlaybackStart (media.ts:16) resolves
data-playback-start ?? data-media-start and timeline.ts calls it on composition
clips. Rewrote to the accurate reason both reviewers gave — composition hosts are
only inspected by the playback-start-first readers, media-start works as a
fallback, but playback-start is what Studio writes/normalises to.
- motion test: pin the HoverVideo click-suppression (preventDefault +
stopPropagation). Removing it left the gate 12/12; now it fails. This is the bug
that escaped static review and only surfaced by driving the live preview.
- replica-compare: fold the visible 'Sound off/on' text into the aria-label so the
accessible name contains it (WCAG 2.5.3, Rames).
Round-5 findings from Magi and Rames.
- replica-compare: the offscreen teardown now resets muted (element + React state),
matching HoverVideo — a pair unmuted before it scrolled away no longer returns
reading 'Sound on' over a paused, sourceless pair (Magi blocker).
- Both controls' aria-labels now follow the mode: under reduced motion the button
plays/pauses the whole comparison, and when a preview is already autoplaying
muted the action is 'unmute', not 'play with sound' (self-review + Rames).
- Hardened the motion-suite assertion to scope 'startBoth' to toggleSound's body
(a defined-but-unused helper no longer satisfies it) and pin the offscreen
muted-reset transition (Rames mutation-test gap).
- html-schema: 'hyperframes validate' inspects <audio> only; note that no
media-start-only reader inspects a composition host, so the kind rule strands
nobody (Rames).
Per Rames: add the engine audio mixer (audioMixer.ts:350 -> ffmpeg -ss) to the
media-start-only readers — it's the live path that makes a lone data-playback-start
a shipped output bug (trimmed picture over untrimmed audio). 'Set one' isn't enough;
give the element-kind rule: <video>/<audio> use data-media-start, nested composition
uses data-playback-start (Studio writes it; it's the child-timeline offset). Also fix
editing-existing-videos.mdx, which offered both names as interchangeable for front
trim of a clip — the exact kind where they aren't.
- replica-compare: the voluntary control now starts and pauses BOTH films (not
just the reference), and the replica-sync effect attaches in view regardless of
the preference, so a reduced-motion visitor who presses play sees the whole
synchronized pair. Added a focused source-level assertion to the motion-check
suite (the repo has no React runtime harness for snippets).
- html-schema: describe each layer precisely instead of grouping the CLI —
timing compiler, HTML parser, producer audio, and 'hyperframes validate' read
only data-media-start; runtime, Studio and 'hyperframes snapshot' read
data-playback-start first (Studio also writes it).
Round-3 findings from Magi.
- edit-operations: dispatch() does not consult can() (session.ts:608 -> applyOp
with no validation; a no-timeline addGsapTween/addLabel is a no-op but a missing
target still writes via selector fallback). Use Rames's wording: call can() first
and skip on failure — no false 'applies nothing' guarantee.
- timing-and-animation: the second E_NO_GSAP_TIMELINE site — gated setGsapTween on
an error it cannot return and called shipped parser code 'a later phase'. Rewrote
to gate addGsapTween (which can return it); dropped the stale can() comment in
types.ts:595.
- html-schema: data-playback-start is read by runtime, Studio and CLI (Studio also
writes it, timelineEditingHelpers.ts); only the compile path is media-start only.
Document the layered precedence instead of calling it runtime-only.
Round-2 findings from Magi (#2/#3/#4) and Rames.
- edit-operations: E_NO_GSAP_TIMELINE is raised only by addGsapTween and addLabel
(mutate.ts:1747), not the set/remove tween ops; drop the false 'dispatch() still
applies structurally' claim (mutate.gsap.test.ts verifies zero patches); add the
requirement to the Labels section where addLabel lives.
- html-schema: data-media-start is read by parser + timing compiler + runtime;
data-playback-start is a runtime-only alias, so a lone playback-start doesn't
shift trim/split. Document the surfaces instead of claiming one universal value.
- testing-local-changes: bun unlink cleanup used a relative cd that resolves under
the video project; use an absolute checkout path.
Flagged by Magi (P1 #2/#3, P2 #7) and Rames.
**`bun unlink hyperframes` does not exist.** Bun answers "error: bun unlink
{packageName} not implemented yet" — I ran it. The command takes no package name;
it unregisters whatever directory you are standing in. The reader arrives at that
block having just been told to cd into a video project, so even the correct form
would unregister the wrong thing and leave the global link in place — which is
exactly the failure the same page's troubleshooting section then explains. The
page created the bug it diagnosed. Now `cd packages/cli && bun unlink`.
**`data-media-start` and `data-playback-start` are one value, not two features.**
The schema page gave them separate rows with different-sounding meanings, so a
reader would reasonably think they compose. Six read sites in core are all
`playbackStart ?? mediaStart` — runtime/media.ts:18 and :92, runtime/init.ts:751,
1993, 2928, 3010. One row now, alias named, and it says which wins.
**Canary rollouts contradicted itself.** Line 109 called enrolment a pure function
of `(feature, installId, percentage)`; line 195 said canaries bucket on a
dedicated `bucketSeed`, not the telemetry id. The second is right —
cli/src/telemetry/canary.ts:98 is `unitId: config.bucketSeed ?? config.anonymousId`.
Also on the Studio shortcuts page earlier: J/Shift+J for keyframe navigation,
Backspace to delete, and Ctrl+Y for redo were all missing.
## Summary
- replace the unsupported `data-var-*` example with the current `data-variable-values` pattern
- document that variable values are carried through but still applied manually inside the nested composition
- add matching reference notes in the data-attributes, HTML schema, core package, and CLI docs
## Verification
- `npx mintlify dev --port 3100`
- browser verification with `agent-browser` on `/concepts/compositions` and `/reference/html-schema`
- proof artifacts saved locally under `tmp/issue-416-docs/`
Major improvements across all 18 pages:
- Use Mintlify components: <Steps> for tutorials, <Tabs> for alternatives,
<CodeGroup> for multi-platform commands, <Tree> for directory structures,
<AccordionGroup> for FAQ/scannable content, <Mermaid> for diagrams
- Add filename annotations to all code blocks (e.g., ```html index.html)
- Add numbered comments inside multi-step code examples
- Show expected terminal output after CLI commands
- Add "When to use" / "When NOT to use" sections to all package pages
- Add "Next Steps" CardGroup to every page (no dead-end pages)
- Cross-link between pages at point of curiosity (not just "see also" dumps)
- Expand thin pages (engine, studio) with architecture details and examples
- Add decision guides (rendering modes, template selection)
- Use <Warning> and <Note> sparingly (max 2-3 per page)
Also adds DOCS_GUIDELINES.md at repo root with writing standards.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Miguel Ángel