frameyard 0.2.0 → 0.4.0

package/docs/migration-0.4.md

@@ -0,0 +1,279 @@
+# Migrating to Frameyard 0.4
+
+0.4 replaces JavaScript composition modules with declarative HTML documents. The CLI commands, props files, audio and transcript asset formats, rendering pipeline, and determinism guarantees are unchanged. This guide maps the old authoring surface to the new one.
+
+## 1. Change the config entry
+
+Before:
+
+```js
+export default {
+  compositions: {
+    hello: "./compositions/hello.js",
+  },
+};
+```
+
+After:
+
+```js
+export default {
+  compositions: {
+    hello: "./compositions/hello.html",
+  },
+};
+```
+
+Entries must be `.html`. There is still no directory scanning.
+
+## 2. Move metadata and defaults into the document
+
+Before:
+
+```js
+export default defineComposition({
+  width: 1280,
+  height: 720,
+  fps: 30,
+  durationInFrames: 150,
+  defaultProps: { title: "Hello", accent: "#b8f36b" },
+  // ...
+});
+```
+
+After:
+
+```html
+<fy-composition width="1280" height="720" fps="30" duration-in-frames="150">
+  <!-- composition content -->
+</fy-composition>
+
+<script type="application/json" data-fy="props">
+{ "title": "Hello", "accent": "#b8f36b" }
+</script>
+```
+
+## 3. Move markup out of `mount()`
+
+Before:
+
+```js
+mount({ container }) {
+  container.innerHTML = "<h1 id='title'></h1>";
+  title = container.querySelector("#title");
+}
+```
+
+After:
+
+```html
+<h1 data-fy-text="title"></h1>
+```
+
+The controller remains available for DOM that must be created per frame or from data that CSS cannot express.
+
+## 4. Replace `update()` with bindings and CSS
+
+Before:
+
+```js
+update({ frame, props }) {
+  title.textContent = props.title;
+  const intro = Math.min(1, frame / 24);
+  title.style.opacity = String(intro);
+  title.style.transform = `translateY(${(1 - intro) * 28}px)`;
+  sweep.style.width = `${(frame / 149) * 100}%`;
+}
+```
+
+After:
+
+```html
+<h1 class="title"
+    data-fy-text="title"
+    data-fy-anim-start="0"
+    data-fy-anim-duration="24"></h1>
+<div class="sweep" style="width: calc(var(--fy-progress) * 100%)"></div>
+```
+
+```css
+.title {
+  animation: fade-up 1s ease-out both;
+}
+
+@keyframes fade-up {
+  from { opacity: 0; transform: translateY(28px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+```
+
+Use `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` for frame-based scheduling. Use `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, and `--fy-duration` for computed CSS values. If the motion cannot be expressed in CSS, move it to the controller.
+
+## 5. Replace prop-driven DOM with bindings
+
+| Old | New |
+| --- | --- |
+| `el.textContent = props.title` | `data-fy-text="title"` |
+| `el.setAttribute("src", props.image)` | `data-fy-attr-src="image"` |
+| `el.classList.toggle("active", props.isActive)` | `data-fy-class-active="isActive"` |
+| `if (props.show) ...` | `data-fy-if="show"` |
+| `props.items.map(...)` | `<template data-fy-repeat="items">...</template>` |
+| `container.style.setProperty("--accent", props.accent)` | `style="color: var(--fy-prop-accent)"` |
+
+Bindings resolve dot paths such as `user.name`. They apply once per load; props are immutable. `data-fy-repeat` provides `item` and `index` in the cloned scope and sets `--fy-index`; nested repeats are not supported.
+
+## 6. Move audio and transcripts to HTML
+
+Before:
+
+```js
+audio: [
+  {
+    src: "assets/voice.wav",
+    startFrame: 30,
+    trimStart: 0.25,
+    trimDuration: 4.2,
+    volume: 0.8,
+  },
+],
+transcripts: [
+  { src: "assets/voice.transcript.json", words: true },
+],
+```
+
+After:
+
+```html
+<audio src="assets/voice.wav"
+       data-fy-start="30"
+       data-fy-trim="0.25"
+       data-fy-duration="4.2"
+       data-fy-volume="0.8"></audio>
+
+<fy-transcript src="assets/voice.transcript.json" words></fy-transcript>
+```
+
+Audio, video, and `<fy-transcript>` `src` values resolve from the project root. The controller `src` and ordinary HTML assets (`img`, stylesheets) resolve relative to the composition document.
+
+## 7. Rename media attributes
+
+All `data-frameyard-*` media attributes become `data-fy-*`:
+
+| Old | New |
+| --- | --- |
+| `data-frameyard-start` | `data-fy-start` |
+| `data-frameyard-trim` | `data-fy-trim` |
+| `data-frameyard-duration` | `data-fy-duration` |
+| `data-frameyard-volume` | `data-fy-volume` |
+| `data-frameyard-audio` | `data-fy-audio` |
+
+## 8. Move imperative code into a controller
+
+Before:
+
+```js
+export default defineComposition({
+  // metadata, defaults, audio, transcripts
+  mount({ container, props }) { /* ... */ },
+  update({ frame, props }) { /* ... */ },
+  dispose() { /* ... */ },
+  validateProps(props) { /* ... */ },
+});
+```
+
+After — inline for a small, single-use controller:
+
+```html
+<script type="text/fy-controller">
+export default {
+  validateProps(props) { /* ... */ },
+  mount({ root, props }) { /* ... */ },
+  update({ frame, props, root }) { /* ... */ },
+  dispose() { /* ... */ },
+};
+</script>
+```
+
+After — external for a reusable or complex controller:
+
+```html
+<script type="text/fy-controller" src="./hello.controller.js"></script>
+```
+
+```js
+export default {
+  validateProps(props) { /* ... */ },
+  mount({ root, props }) { /* ... */ },
+  update({ frame, props, root }) { /* ... */ },
+  dispose() { /* ... */ },
+};
+```
+
+A composition has exactly one controller. Inline keeps the composition in one file and is the default for small, single-use controllers. Extract to an external module when the controller grows, is reused, needs separate imports or tests, or drives Canvas 2D, WebGL, or karaoke. The host serves inline source through a virtual module URL, so relative imports and `import.meta.url` behave as they do in an external module.
+
+Inline source is raw text inside `<script>`; a literal `</script>` in a string must be escaped as `<\/script>`. If the controller contains HTML strings or grows large, prefer an external module.
+
+The controller is for Canvas 2D, WebGL, karaoke, arrays that exceed `data-fy-repeat`, and per-frame computation CSS cannot express. It has no metadata, defaults, audio, or transcripts. `mount()` may be asynchronous; `update()` and `validateProps()` are synchronous and seek-safe.
+
+## 9. Remove executable scripts and inline handlers
+
+Only the controller, inline or external, may execute. Remove `<script type="module">` blocks and `on*` attributes; import libraries from the controller instead. JSON data blocks (`type="application/json"`) and the `text/fy-controller` block are allowed. `javascript:` URLs and unsupported visual elements inside the composition (`iframe`, `object`, `embed`) are rejected. The preview's own host iframe is not a composition element.
+
+## 10. Validation and diagnostics
+
+`check`, `still`, and `render` run a Node-side static composition validation before Chromium. It catches metadata, root/controller count, default-props JSON, unknown `data-fy-*` attributes, missing binding paths, repeat misuse, animation attributes, executable scripts, inline handlers, `javascript:` URLs, unsupported visual elements, and missing audio/transcript references.
+
+Errors and warnings are structured:
+
+```json
+{
+  "code": "BINDING_PATH_MISSING",
+  "message": "data-fy-text references prop \"titel\", which is not in the resolved props.",
+  "details": {
+    "path": "compositions/hello.html",
+    "line": 12,
+    "column": 5,
+    "element": "h1",
+    "attribute": "data-fy-text",
+    "value": "titel",
+    "suggestion": "title"
+  }
+}
+```
+
+`check` exits nonzero on static errors without launching Chromium. Warnings allow frame evaluation but should be treated as actionable. `check`, `still`, and `render` JSON results now include `entry`, `controller`, and top-level `warnings`.
+
+Props domain validation remains controller-only in 0.4. If an HTML-only composition needs required or typed props, add a tiny inline controller with `validateProps`:
+
+```html
+<script type="text/fy-controller">
+export default {
+  validateProps(props) {
+    return typeof props.title === "string" ? [] : ["title must be a string"];
+  },
+};
+</script>
+```
+
+## 11. Update preview and render expectations
+
+No command changes. Preview loads the composition in a same-origin iframe; `check`, `still`, and `render` navigate directly to the same document. The composition host is injected by the server, so keep composition entries listed in `video.config.js` and run through `frameyard dev` or `frameyard render`, not `file://`.
+
+## Migration checklist
+
+- [ ] Change `video.config.js` entries to `.html`.
+- [ ] Move metadata to `<fy-composition>`.
+- [ ] Move `defaultProps` to the `data-fy="props"` JSON block.
+- [ ] Move `mount()` markup into the document.
+- [ ] Replace text, attribute, and class assignments with `data-fy-*` bindings.
+- [ ] Replace conditionals and loops with `data-fy-if` and `data-fy-repeat`.
+- [ ] Use the controller for nested data; nested `data-fy-repeat` is rejected.
+- [ ] Replace `update()` motion with CSS animations, `data-fy-anim-*`, and frame-state variables.
+- [ ] Move Canvas 2D, WebGL, karaoke, and complex computation into a controller.
+- [ ] Choose an inline or external controller; keep exactly one per composition.
+- [ ] If props need domain validation, add an inline `validateProps` controller.
+- [ ] Move `audio` and `transcripts` to `<audio>` and `<fy-transcript>`.
+- [ ] Rename `data-frameyard-*` media attributes to `data-fy-*`.
+- [ ] Remove executable scripts, inline handlers, `javascript:` URLs, and unsupported visual elements inside the composition.
+- [ ] Run `check`; treat static errors and warnings as actionable.
+- [ ] Inspect representative stills and render.

package/docs/v0.1-design.md

@@ -1,10 +1,10 @@
-# Frameyard v0.1 Design Baseline
+# Frameyard Design Baseline
 
 **Status:** Accepted
 **Initial acceptance:** 2026-10-27
-**Last design revision:** 2026-10-29
+**Last design revision:** 2026-10-30
 
-This document records the decisions confirmed during the initial design sessions. It defines the v0.1 product and architecture baseline; later changes should revise this document explicitly rather than silently broaden the scope.
+This document records the decisions confirmed during design sessions. It is the living product and architecture baseline; later changes revise this document explicitly rather than silently broaden the scope. The original v0.1 baseline has been revised through 0.4. Architecture decisions that changed the baseline are recorded in `docs/adr/`.
 
 ## 1. Product contract
 
@@ -12,10 +12,10 @@ Frameyard is a local-first, open-source framework for frontend developers and cr
 
 The initial use cases are product demos, social clips, animated diagrams, data visualizations, karaoke-style subtitles, and personalized videos. Optional local speech synthesis and transcription produce assets for these workflows. Professional long-form editing is outside the target audience.
 
-The core v0.1 success criterion is an end-to-end example in which a developer can:
+The core success criterion is an end-to-end example in which a developer can:
 
-1. Create a reusable 30-second, 1920×1080 composition.
-2. Animate it with HTML, CSS, SVG, JavaScript, and seek-safe Canvas 2D.
+1. Create a reusable 30-second, 1920×1080 HTML composition.
+2. Animate it with HTML, CSS, SVG, and, where needed, a seek-safe controller for Canvas 2D and WebGL.
 3. Supply JSON props and synchronized audio.
 4. Preview and scrub it interactively.
 5. Render it reproducibly to MP4 without dropped frames or timing drift.
@@ -24,31 +24,36 @@ The agent-enabled success criterion additionally requires an agent using the off
 
 ## 2. Project and authoring model
 
-- Projects use ordinary HTML, CSS, static assets, and native JavaScript ES modules.
-- `video.config.js` explicitly lists composition module entry points. There is no directory-scanning discovery convention.
+- Projects use ordinary HTML, CSS, static assets, and native JavaScript controllers, either inline in a composition document or in external modules.
+- `video.config.js` explicitly lists `.html` composition entry points. There is no directory-scanning discovery convention.
 - A project may contain multiple compositions, each with a unique ID.
-- Each composition has fixed `width`, `height`, `fps`, and `durationInFrames` metadata. Props cannot change this metadata in v0.1.
-- A composition follows a `mount → update({ frame, props }) → dispose` lifecycle. Mounting creates the visual structure; updating makes that structure represent the requested frame.
-- `update()` must be seek-safe and synchronous. It cannot depend on previously visited frames.
-- Props are JSON-serializable, immutable, and fixed for one render. Composition defaults may be overridden by a JSON file or CLI option.
-- The core validates metadata and JSON-serializability. An optional composition-defined `validateProps()` hook handles domain-specific validation before loading.
-- User compositions are native JavaScript. The framework itself is authored in TypeScript and ships declarations, but v0.1 does not transpile user TypeScript.
+- A composition is a full HTML document with one `<fy-composition>` root. The root declares fixed `width`, `height`, `fps`, and `duration-in-frames` metadata. Props cannot change this metadata.
+- Default props are a JSON block, `<script type="application/json" data-fy="props">`. A render's JSON props merge shallowly over the defaults, are validated as JSON, deep-frozen, and fixed for the render.
+- Props bind into the document through explicit `data-fy-*` attributes: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat`. Primitive top-level props are also exposed as `--fy-prop-<name>` CSS custom properties. Bindings apply once per load; props are immutable.
+- CSS and the Web Animations API are the animation language. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation per element in composition frames.
+- An optional composition controller is declared with `<script type="text/fy-controller">`. It is either inline source or an external module referenced by `src`; a composition has exactly one controller. It may export `mount({ root, props })`, `update({ frame, props, root })`, `dispose()`, and `validateProps(props)`; at least one is required, and `mount` and `update` are optional for validation-only controllers. It has no metadata, default props, audio, or transcripts. Inline keeps small compositions in one file; external is for reuse, tests, and complex logic.
+- Inline controllers are the default for small, single-use controllers. Extract to an external module when the controller grows, is reused, needs separate imports or tests, or drives Canvas 2D, WebGL, or karaoke.
+- The controller is the only executable code in a composition document. Other executable `<script>` elements and inline `on*` handlers are rejected. Libraries are imported as ES modules from the controller.
+- `fy` is the authoring namespace: `fy-composition`, `fy-transcript`, `data-fy-*`, `--fy-*`, and `text/fy-controller`. `frameyard` remains the product, package, CLI, config, manifest, server-route, import-specifier, and error-code namespace.
+- User controllers are native JavaScript. The framework itself is authored in TypeScript and ships declarations, but 0.4 does not transpile user TypeScript.
 
 ## 3. Deterministic execution
 
 The only sources of animation state are the integer frame number and immutable props. Composition frame rate establishes the mapping between frames and time.
 
-- The runtime owns the frame clock and deterministic randomness.
-- CSS `@keyframes` and Web Animations API animations are paused and positioned from the shared frame clock.
-- JavaScript animation runs inside `update()`.
+- The runtime owns the frame clock and deterministic randomness. The controller imports `random("stable:key")` from `frameyard/runtime`.
+- CSS `@keyframes` and Web Animations API animations are paused and positioned from the shared frame clock. `data-fy-anim-*` attributes schedule one animation per element in composition frames; the runtime maps frames to milliseconds and sets the corresponding animation delay and duration.
+- The runtime sets `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames` on the composition root every seek. Authors use them for simple computed CSS values.
+- JavaScript animation runs in the controller's `update()`, which must be synchronous and seek-safe. It cannot depend on previously visited frames.
+- Declarative bindings apply once per load, before the controller mounts. Controller-created DOM is the controller's responsibility.
 - Independent `requestAnimationFrame` loops, timers, CSS transitions, wall-clock reads, and unseeded randomness are not supported animation drivers.
-- Deterministic random values are stateless and key-based, such as `random("star:17")`, so they do not depend on call order or rendering history.
-- Development mode provides best-effort diagnostics for forbidden clocks and randomness; it does not claim to police every third-party library perfectly.
-- Assets, remote data, images, fonts, generated audio, and transcripts are resolved during an explicit loading phase before frame production.
-- Required network access is limited to the loading phase. Network requests are blocked during frame capture.
-- AI model inference is never part of `mount()`, `update()`, or frame production.
-- v0.1 supports DOM, CSS, SVG, and Canvas 2D that is redrawn from the current frame.
-- Composition code is trusted local developer code. Frameyard does not claim to render untrusted compositions safely.
+- Development mode provides best-effort diagnostics for forbidden clocks and randomness in the controller; it does not claim to police every third-party library perfectly.
+- Assets, remote data, images, fonts, generated audio, and transcripts are resolved during an explicit loading phase before frame production. Network requests are blocked during frame capture.
+- AI model inference is never part of the loading phase, controller lifecycle, or frame production.
+- The baseline supports DOM, CSS, SVG, Canvas 2D, WebGL, and frame-seeked embedded video. Canvas 2D and WebGL are drawn from the current frame by the controller.
+- Embedded video and audio are declared in the composition HTML with `data-fy-*` attributes. The runtime loads local files during the loading phase, pauses them, and seeks video from the frame-derived source time before capture. An unmuted video contributes its audio track to the offline mix unless the composition opts out.
+- WebGL 1 and WebGL 2 canvases are captured through the normal screenshot path. Production sessions pin software WebGL so pixel output does not depend on the host GPU.
+- Compositions are trusted local developer code. Frameyard does not claim to render untrusted compositions safely.
 
 ### Reproducibility guarantee
 
@@ -58,7 +63,7 @@ Generated assets are covered once frozen. Frameyard does not promise that repeat
 
 ## 4. Preview and production rendering
 
-Preview and production execute the same composition bundle and browser runtime. They differ only in which component drives the frame clock and whether frames are captured.
+Preview and production execute the same composition document and browser host runtime. They differ only in which component drives the frame clock and whether frames are captured.
 
 The preview provides:
 
@@ -70,23 +75,30 @@ The preview provides:
 
 It is a developer inspection tool, not a visual composition editor.
 
+The preview server serves each composition HTML document at its project path and injects the framework import map and a host module into composition entries. The host reads the composition metadata, applies bindings, imports the controller from its `src` or from the inline block's virtual module URL, mounts it, and exposes a small `window.__fy` API. Preview loads the document in a same-origin iframe and drives that API. The iframe is not a security sandbox; compositions are trusted local code. The server runs the static composition validation described in §6 before serving a composition to the preview.
+
 Production rendering:
 
 1. Uses a pinned, Playwright-managed Chromium through the Chrome DevTools Protocol.
-2. Seeks explicitly to each requested frame.
-3. Waits for composition readiness.
-4. Captures the frame.
-5. Pipes frames to FFmpeg for encoding and audio muxing.
+2. Navigates directly to the composition document, waits for the host, and loads the render's props.
+3. Seeks explicitly to each requested frame.
+4. Waits for composition readiness, embedded media decode, and browser paint.
+5. Captures the frame.
+6. Pipes frames in timeline order to FFmpeg for encoding and audio muxing.
+
+`check` and `still` use the same host and capture path. `check` evaluates every frame without capturing or encoding. `still` captures one frame through the production path.
 
-The reference renderer is sequential and has no frame cache. Its design nevertheless permits future parallel and out-of-order rendering because each frame is independently seekable. Simple scenes target real-time preview, but v0.1 has no production rendering-speed guarantee; it reports progress, current frame, and elapsed time.
+The renderer is sequential by default and has no frame cache. Optional `--concurrency <n>` rendering, with `n` from 1 to 16, opens up to `n` independent browser sessions, each loading the same composition document and props from the same preview server. Workers seek and capture assigned frames, while a single ordered writer pipes them to FFmpeg with bounded lookahead. Parallelism therefore changes scheduling only: every frame remains derivable from its integer frame number and immutable props, and output order is unchanged. The default stays at one session for predictable resource use, and the upper bound limits accidental browser-process and memory growth. Simple scenes target real-time preview, but there is no production rendering-speed guarantee; the CLI reports progress, current frame, and elapsed time.
 
 ## 5. Audio and output
 
-Audio is a declarative timeline of clips. Each clip supports a source, start frame, source trim, and volume. Preview synchronizes this timeline in the browser; production mixes it offline with FFmpeg rather than treating live `<audio>` or Web Audio playback as the production source of truth.
+Audio is a declarative timeline of `<audio>` elements. Each element uses `data-fy-start` (composition frame), `data-fy-trim` (seconds from the source start), optional `data-fy-duration` (seconds to use), and `data-fy-volume` (0-1). Preview synchronizes this timeline in the browser; production mixes it offline with FFmpeg rather than treating live `<audio>` or Web Audio playback as the production source of truth. Unmuted embedded videos contribute their own audio tracks to the same mix, placed by the video's frame and trim attributes. Muting a video or setting `data-fy-audio="off"` keeps it visual-only.
+
+Audio, video, and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs (`img`, stylesheets) resolve relative to the composition document.
 
 Generated speech behaves like any other audio clip. Frameyard does not automatically time-stretch it, change composition duration, or regenerate it to fit. `check` reports clip durations and overrun warnings so users and agents can revise text, timing, or composition deliberately.
 
-v0.1 produces portable MP4 files with H.264 video and AAC audio. It exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments. Single-frame PNG output through `still` is a debugging artifact, not general image-sequence support.
+0.4 produces portable MP4 files with H.264 video and AAC audio. It exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments. Single-frame PNG output through `still` is a debugging artifact, not general image-sequence support.
 
 A render fails immediately on an uncaught exception, unhandled rejection, required-asset failure, or invalid composition output. Diagnostics identify the composition and, where applicable, the frame. The CLI exits nonzero, cleans temporary files, and never reports a partial video as successful. Existing output files are not overwritten unless explicitly requested.
 
@@ -94,36 +106,38 @@ A render fails immediately on an uncaught exception, unhandled rejection, requir
 
 Project and composition commands are:
 
-- `init`: scaffold a minimal project, including an agent guide (`AGENTS.md`) and a private `package.json` with pinned `dev`, `check`, `render`, and `still` scripts
+- `init`: scaffold a minimal HTML composition project, including an agent guide (`AGENTS.md`) and a private `package.json` with pinned `dev`, `check`, `render`, and `still` scripts
 - `dev`: start the preview
-- `render <composition-id> --props props.json --out video.mp4`: render a composition
-- `check <composition-id>`: validate configuration, props, assets, audio, and transcript requirements, then mount the composition and evaluate every frame without capturing or encoding
+- `render <composition-id> --props props.json --out video.mp4`: render a composition, optionally with `--concurrency <n>` from 1 to 16
+- `check <composition-id>`: run static composition validation, then validate configuration, props, assets, audio, and transcript requirements, load the composition, and evaluate every frame without capturing or encoding
 - `still <composition-id> --frame <n>`: capture one requested frame as PNG through the production rendering path
 - `doctor`: inspect core requirements and optional integrations without repairing or downloading anything
 
+`check`, `still`, and `render` run a Node-side static composition validation before launching Chromium. It validates metadata, the composition root, the controller declaration, default props, binding attributes and paths, animation attributes, scripts and event handlers, unsupported visual elements, and audio/transcript references. Diagnostics carry stable codes and optional source locations; `check` exits nonzero on static errors without starting a browser. `dev` runs the same validation on load and surfaces its diagnostics in the preview.
+
 Local asset-production commands are `tts` and `transcribe`. Every non-interactive command supports `--json` with stable result and error schemas. Structured results go to stdout; human diagnostics and inference progress go to stderr.
 
-The built-in server serves native ES modules and static assets and injects an import map for the framework runtime. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported.
+The built-in server serves native ES modules and static assets, injects an import map and composition host into composition entries, and serves an inline controller through a virtual module URL under the composition's directory. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported for deterministic preview or rendering. A composition document can still be opened directly as static HTML/CSS.
 
-v0.1 uses one repository and one publishable npm package with three internal layers:
+Frameyard uses one repository and one publishable npm package with three internal layers:
 
-1. Shared composition contracts
-2. Browser runtime
+1. Shared composition contracts and HTML binding/metadata parsing
+2. Browser host runtime
 3. Node-based CLI and renderer
 
 These layers have clean internal boundaries but no public plugin API. FFmpeg is discovered on the user's PATH and checked for required capabilities, with actionable installation and version diagnostics. The project supports the current active Node.js LTS; Linux is the reference and CI platform, while macOS and Windows remain best-effort until covered by real rendering tests.
 
 ## 7. Official agent skill
 
-Frameyard ships an optional, host-neutral agent skill with a `SKILL.md`, supporting references, and thin scripts. The npm package includes skill files matching its API version, and documentation explains host-specific installation or referencing. v0.1 does not add a skill-installer command.
+Frameyard ships an optional, host-neutral agent skill with a `SKILL.md`, supporting references, and thin scripts. The npm package includes skill files matching its API version, and documentation explains host-specific installation or referencing. 0.4 does not add a skill-installer command.
 
 The skill:
 
-- Uses the normal project format, composition API, and CLI available to humans.
-- Does not introduce an agent-only runtime, MCP server, hosted control plane, or parallel rendering API.
+- Uses the normal project format, HTML composition contract, optional controller, and CLI available to humans.
+- Does not introduce an agent-only runtime, MCP server, hosted control plane, or separate rendering API.
 - Triggers for Frameyard authoring and operation rather than claiming to be a general-purpose media-generation skill.
 - Uses Frameyard's audio wrappers instead of invoking `qwen-tts` or `whisper-cli` directly.
-- Includes references for deterministic authoring, audio assets, subtitle and karaoke recipes, JSON command results, and failure recovery.
+- Includes references for deterministic HTML authoring, bindings, animation scheduling, controller rules, static validation, structured diagnostics, common authoring mistakes, audio assets, subtitle and karaoke recipes, JSON command results, and failure recovery.
 - Invokes speech synthesis or transcription only when requested or explicitly approved as part of the brief.
 - Does not overwrite or regenerate existing generated assets without permission.
 - Runs `check`, inspects representative `still` images when the host supports image viewing, and discloses when visual inspection was impossible.
@@ -135,7 +149,7 @@ A successful agent workflow preserves and reports the source project, props, gen
 
 The `tts` command integrates [`qwentts.cpp`](https://github.com/ServeurpersoCom/qwentts.cpp) through its external `qwen-tts` executable. It does not link the native library or require the upstream server.
 
-v0.1 supports CustomVoice mode only:
+0.4 supports CustomVoice mode only:
 
 - A named speaker is required.
 - An optional style instruction and language may be supplied.
@@ -161,19 +175,19 @@ The canonical artifact is a versioned Frameyard JSON document containing:
 - Timed segments
 - Optional word timings
 
-All timestamps are integer milliseconds relative to the source audio, not composition frame numbers. Composition code converts them using the audio clip's start frame, source trim, and composition frame rate.
+All timestamps are integer milliseconds relative to the source audio, not composition frame numbers. The controller converts them using the audio clip's start frame, source trim, and composition frame rate.
 
-Compositions may declare required transcript assets with a `transcripts` field analogous to `audio`:
+Compositions declare required transcript assets with `<fy-transcript>` elements:
 
-```js
-transcripts: [{ src: "assets/voice.transcript.json", words: true }]
+```html
+<fy-transcript src="assets/voice.transcript.json" words></fy-transcript>
 ```
 
 `check` and production validate declared transcript files before frame production. `words: true` requires measured word timings and fails when they are unavailable; it never triggers interpolation.
 
 SRT and VTT are derived exports, not the canonical contract. Word-level karaoke requires actual word timings and fails validation when they are unavailable. Frameyard never fabricates word timings by interpolating segment timestamps and never executes Whisper's generated bash/FFmpeg karaoke script.
 
-The official skill documents seek-safe subtitle and karaoke recipes. Compositions retain responsibility for visual presentation; v0.1 has no built-in subtitle renderer and does not automatically burn captions into videos.
+The official skill documents seek-safe subtitle and karaoke recipes. Compositions retain responsibility for visual presentation; 0.4 has no built-in subtitle renderer and does not automatically burn captions into videos. Karaoke presentation uses the optional controller.
 
 ## 10. Generated assets and inference operation
 
@@ -198,10 +212,17 @@ Release documentation must identify the exact `qwentts.cpp` and `whisper.cpp` re
 
 Tests prioritize public behavior and end-to-end evidence over implementation-only unit coverage:
 
-- Sequential, individual, and random-order frame renders produce equivalent images.
+- HTML compositions validate metadata, default props, bindings, conditionals, repeats, and controller declarations, including inline/external parity and the exactly-one-controller rule.
+- Static composition validation catches metadata, root/controller count, binding, animation, script, element, and asset-reference errors before Chromium.
+- Diagnostics carry stable codes and source locations; JSON results expose the composition entry, controller declaration, and top-level diagnostics.
+- Sequential, individual, random-order, and parallel frame renders produce equivalent images.
 - Determinism checks compare captured pixels or stills; encoded MP4 bytes are not a reproducibility oracle.
-- Preview and renderer use the same runtime.
-- CSS, JavaScript, SVG, and Canvas animations seek correctly.
+- Preview and renderer use the same composition document and host runtime.
+- CSS, controller JavaScript, SVG, and Canvas animations seek correctly.
+- Frame-scheduled `data-fy-anim-*` animations and frame-state CSS variables produce the expected frames.
+- Embedded video and audio frames seek deterministically, including under parallel capture, and their audio appears in the offline mix.
+- WebGL canvases produce deterministic stills and rendered frames under the pinned software renderer.
+- Executable scripts other than the inline or external controller, inline event handlers, `javascript:` URLs, and unsupported visual elements are rejected.
 - Asset and runtime failures produce nonzero CLI exits.
 - Rendered MP4 files have the expected dimensions, frame count, duration, and audio stream.
 - Golden-frame tests cover representative visual behavior.
@@ -210,7 +231,7 @@ Tests prioritize public behavior and end-to-end evidence over implementation-onl
 - Real-model integration tests are explicitly opt-in and use documented upstream revisions.
 - Agent-workflow evaluations verify source preservation, provenance, validation, still inspection behavior, failure reporting, and final renders.
 
-## 12. Deferred from v0.1
+## 12. Deferred
 
 These are scope boundaries, not permanent rejections:
 
@@ -218,15 +239,19 @@ These are scope boundaries, not permanent rejections:
 - Cloud generative-AI services, text-to-video generation, and image generation
 - `qwentts.cpp` reference-audio voice cloning and VoiceDesign
 - Automatic long-text chunking, streaming speech synthesis, and alternative generated-audio formats
-- Built-in subtitle rendering and automatic caption burn-in
+- Built-in subtitle rendering, automatic caption burn-in, and declarative karaoke elements
+- Nested `data-fy-repeat` scopes and a general template language
+- Declarative JSON Schema validation
+- Arbitrary executable scripts in composition HTML
 - Automatic upstream builds, model downloads, weight redistribution, and environment repair
 - Agent-only runtimes, MCP servers, hosted agent control planes, and host-specific skill installers
 - React or other UI-framework adapters in the core
 - Public plugin APIs and a broad integration ecosystem
 - Dynamic composition metadata derived from props
-- Embedded video, WebGL, live streams, and other independently timed visual content
+- Live streams, remote media, and other visual sources that cannot be deterministically seeked
 - Dynamic per-frame asset loading or AI inference
-- Parallel rendering and frame caches
+- Frame caches
+- Batch still capture; agents can run `still` once per representative frame
 - Additional final-video formats, general image-sequence output, and arbitrary FFmpeg argument passthrough
 - Built-in TypeScript transpilation and npm dependency optimization
 - Rendering untrusted compositions
@@ -235,4 +260,4 @@ These are scope boundaries, not permanent rejections:
 
 ## 13. Release posture
 
-Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and composition, configuration, CLI, JSON-result, transcript, and skill-contract changes are documented explicitly until those contracts stabilize.
+Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and composition, configuration, CLI, JSON-result, transcript, and skill-contract changes are documented explicitly until those contracts stabilize. 0.4.0 is a breaking authoring-model release: HTML documents replace JavaScript composition modules, and the `fy` namespace replaces `data-frameyard-*` authoring attributes. See [ADR 0007](./adr/0007-make-html-documents-the-composition-unit.md) and the [0.4 migration guide](./migration-0.4.md).

package/examples/demo/README.md

@@ -1,12 +1,16 @@
 # Frameyard demo
 
-A 30-second, 1920×1080 composition that exercises the v0.1 core:
+A 30-second, 1920×1080 HTML composition that exercises the current core:
 
 - HTML and CSS layout, including seeked CSS keyframe animation
-- deterministic Canvas 2D starfield
+- deterministic Canvas 2D starfield in an external controller
 - SVG path drawing and data bars updated from the frame
 - JSON props for the title, subtitle, and accent color
-- a declarative audio timeline with repeated local chime clips
+- an `<audio>` timeline with repeated local chime clips
+- frame-state CSS variables for the progress bar
+
+The composition lives in `compositions/demo.html`; the optional controller is
+`compositions/demo.controller.js`.
 
 From the repository root: