frameyard 0.2.0 → 0.4.0

package/skills/frameyard/references/common-mistakes.md

@@ -0,0 +1,59 @@
+# Common mistakes
+
+## Using the old authoring model
+
+- **JavaScript composition modules / `defineComposition`** were removed in 0.4. A composition is a `.html` document listed in `video.config.js`.
+- **`data-frameyard-*`** media attributes were removed in 0.4. Use `data-fy-*`.
+
+## Document structure
+
+- Missing `<!doctype html>` or missing/multiple `<fy-composition>` roots.
+- Missing `width`, `height`, `fps`, or `duration-in-frames` on the root.
+- Missing the `data-fy="props"` block when the composition relies on default props.
+- Visual content outside `<fy-composition>`; it is not captured.
+- Using `<base>`, refresh/CSP meta tags, `<iframe>`, `<object>`, or `<embed>`.
+
+## Bindings
+
+- Unknown `data-fy-*` attribute, usually a typo such as `data-fy-txt`.
+- A binding path that does not exist in the resolved props. Check the `BINDING_PATH_MISSING` warning and its suggestion.
+- Using `data-fy-repeat` on a normal element instead of `<template>`.
+- Nesting `data-fy-repeat`; use a controller for nested data.
+- Putting `data-fy-if` or `data-fy-text` on a repeat template.
+- Putting `data-fy-text` on an `<img>` or another void element.
+- Expecting bindings to update every frame or to re-bind controller-created DOM.
+
+## Timing
+
+- Writing seconds where frames are required, or frames where seconds are required.
+  - `data-fy-start` and `data-fy-anim-start`/`duration` are frames.
+  - `data-fy-trim`/`duration` are seconds.
+- Using CSS `animation-delay`/`duration` in seconds and expecting the declarative scheduler to ignore its own attributes. `data-fy-anim-*` overrides the shorthand's delay/duration.
+- Adding `data-fy-anim-*` without a CSS animation; this produces `ANIMATION_NOT_FOUND`.
+- Using multiple animations on an element with one declarative schedule.
+
+## Controllers
+
+- Declaring both inline source and `src` on the same controller.
+- Declaring more than one controller.
+- Making `update()` async; do asynchronous work in `mount()`.
+- Leaving module-scope state behind in `dispose()`.
+- Writing a literal `</script>` inside inline controller source; escape it.
+- Importing libraries from executable `<script>` tags; import them from the controller instead.
+- Using `Math.random()`, `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions.
+
+## Media and transcripts
+
+- Using remote, live, or unseekable media sources.
+- Using `<source>` or `<track>` children; use a local `src` and `<fy-transcript>`.
+- Adding or changing media in `update()`; prepare it in the document or in `mount()`.
+- Calling `play()`, `pause()`, or setting `currentTime` on a video.
+- Assuming media/transcript `src` is document-relative. It is project-root-relative.
+- Assuming the controller `src` is project-root-relative. It is document-relative.
+
+## Validation
+
+- Replacing `check` with a single `still`.
+- Ignoring warnings or `diagnostics` in `--json` output.
+- Claiming success after a nonzero exit, a missing still, or skipped visual inspection.
+- Using `--overwrite` or `--force` without permission.

package/skills/frameyard/references/controllers.md

@@ -0,0 +1,126 @@
+# Controllers
+
+A composition controller is optional JavaScript for what HTML and CSS cannot express: Canvas 2D, WebGL, karaoke, complex computed motion, or data-driven DOM. It is the only executable code in a composition.
+
+## Inline or external
+
+Inline for a small, single-use controller:
+
+```html
+<script type="text/fy-controller">
+export default {
+  mount({ root, props }) {
+    // create canvases, query elements, load data
+  },
+  update({ frame, props, root }) {
+    // synchronous and seek-safe
+  },
+  dispose() {
+    // release module-scope state and listeners
+  },
+};
+</script>
+```
+
+External for reuse, tests, or a large controller:
+
+```html
+<script type="text/fy-controller" src="./hello.controller.js"></script>
+```
+
+```js
+export default {
+  mount({ root, props }) {},
+  update({ frame, props, root }) {},
+  dispose() {},
+};
+```
+
+Exactly one controller is allowed. Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
+
+## Lifecycle
+
+- `mount({ root, props })` runs once per load and may be asynchronous. Use it to query the root, create canvases, and start loading local data.
+- `update({ frame, props, root })` runs on every seek. It must be synchronous and seek-safe: derive the frame from `frame` and `props` only.
+- `dispose()` releases resources and resets module-scope state. The host calls it before remounting or disposing the document.
+- `validateProps(props)` is optional and synchronous. Return an array of human-readable errors, or `void`.
+- A validation-only controller may export just `validateProps`.
+
+Keep mutable state in module scope, never on `this`. The controller module is imported once per document; `load` remounts it without re-importing, so `dispose` must reset module state.
+
+## Props validation
+
+```html
+<script type="text/fy-controller">
+export default {
+  validateProps(props) {
+    const errors = [];
+    if (typeof props.title !== "string") errors.push("title must be a string");
+    return errors;
+  },
+};
+</script>
+```
+
+Validation runs before the old mount is disposed. Invalid props reject `load` with `PROPS_INVALID` and keep the current composition mounted.
+
+## Canvas and WebGL
+
+```js
+let canvas;
+let context;
+
+export default {
+  mount({ root }) {
+    canvas = root.querySelector("#field");
+    context = canvas.getContext("2d");
+  },
+  update({ frame }) {
+    context.clearRect(0, 0, canvas.width, canvas.height);
+    context.fillStyle = frame % 2 === 0 ? "#101820" : "#203040";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+  },
+  dispose() {
+    canvas = undefined;
+    context = undefined;
+  },
+};
+```
+
+Redraw WebGL from the current frame; do not depend on the previous drawing buffer. Production pins SwiftShader.
+
+## Randomness and clocks
+
+Import `random` from `frameyard/runtime`:
+
+```js
+import { random } from "frameyard/runtime";
+
+const x = random("star:17:x") * 1920;
+```
+
+Never use `Math.random()`, `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions as animation inputs. The host diagnoses common cases in `mount` and `update`.
+
+## Media
+
+Prefer declarative `<video>`/`<audio>` elements with `data-fy-*` attributes. The host pauses and seeks them; do not call `play()`, `pause()`, or set `currentTime` in `update()`. Media created by the controller is allowed in `mount`; media added or changed in `update` cannot be prepared without network access.
+
+Media and transcript `src` values resolve from the project root. The controller `src` resolves relative to the composition document.
+
+## Karaoke
+
+Read the declared transcript JSON, convert source milliseconds to frames, and render the active segment or word from `frame`:
+
+```js
+const FPS = 30;
+const clipStartFrame = 30;
+const trimStart = 0.25;
+
+function wordProgress(word, frame) {
+  const start = clipStartFrame + (word.startMs / 1000 - trimStart) * FPS;
+  const end = clipStartFrame + (word.endMs / 1000 - trimStart) * FPS;
+  return Math.max(0, Math.min(1, (frame - start) / Math.max(1, end - start)));
+}
+```
+
+Never interpolate segment timings to fake word timings.

package/skills/frameyard/references/deterministic-authoring.md

@@ -1,6 +1,6 @@
-# Deterministic authoring
+# Deterministic HTML authoring
 
-Frameyard compositions are ordinary native JavaScript ES modules. The preview server injects an import map for `frameyard` and `frameyard/runtime`; do not add a bundling step or import from `node_modules` in composition code.
+Frameyard compositions are full HTML documents. The preview server injects the framework import map and composition host; do not add a bundling step. Optional controllers are native JavaScript modules that import bare `frameyard/runtime`.
 
 ## Project configuration
 
@@ -9,50 +9,125 @@ Frameyard compositions are ordinary native JavaScript ES modules. The preview se
 ```js
 export default {
   compositions: {
-    hello: "./compositions/hello.js",
+    hello: "./compositions/hello.html",
   },
 };
 ```
 
-There is no directory scanning. A new composition file is invisible until it is listed.
+There is no directory scanning. A new composition document is invisible until it is listed. Entries must be `.html` files; JavaScript composition modules are rejected.
 
 ## Composition shape
 
-```js
-import { defineComposition } from "frameyard";
-import { random } from "frameyard/runtime";
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script type="application/json" data-fy="props">
+    { "title": "Hello", "accent": "#b8f36b" }
+    </script>
+    <style>
+      @keyframes fade-up {
+        from { opacity: 0; transform: translateY(24px); }
+        to { opacity: 1; transform: translateY(0); }
+      }
+      #title { animation: fade-up 1s ease-out both; }
+    </style>
+  </head>
+  <body>
+    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
+      <h1 id="title"
+          data-fy-text="title"
+          data-fy-anim-start="0"
+          data-fy-anim-duration="30"></h1>
+      <div style="width: calc(var(--fy-progress) * 100%)"></div>
+    </fy-composition>
+  </body>
+</html>
+```
 
-let title;
+- `width`, `height`, `fps`, and `duration-in-frames` are fixed on the root.
+- The `data-fy="props"` block is a JSON object. External props merge shallowly over it and are deep-frozen.
+- There is exactly one `<fy-composition>` root, inside `<body>`.
+- A doctype is required. Unsupported document features such as `<base>`, refresh/CSP meta tags, `<iframe>`, `<object>`, and `<embed>` are rejected.
+
+## Bindings
+
+```html
+<h1 data-fy-text="title"></h1>
+<img data-fy-attr-src="image" data-fy-attr-alt="alt">
+<div data-fy-class-active="isActive"></div>
+<p data-fy-if="showSubtitle" data-fy-text="subtitle"></p>
+<template data-fy-repeat="items">
+  <span data-fy-text="item.label" data-fy-attr-data-index="index"></span>
+</template>
+```
 
-export default defineComposition({
-  width: 1920,
-  height: 1080,
-  fps: 30,
-  durationInFrames: 900,
-  defaultProps: { title: "Hello" },
-  validateProps(props) {
-    return typeof props.title === "string" ? [] : ["title must be a string"];
-  },
-  mount({ container, props }) {
-    container.innerHTML = "<h1 id='title'></h1>";
-    title = container.querySelector("#title");
-    title.textContent = props.title;
+- Paths are dot-separated (`user.name`, `items.0.label`); numeric segments index arrays.
+- `data-fy-text` sets `textContent`.
+- `data-fy-attr-<name>` sets an attribute; `true` writes an empty attribute, `false`/`null`/`undefined` remove it.
+- `data-fy-class-<name>` toggles one class.
+- `data-fy-if` removes the element when the value is false.
+- `data-fy-repeat` must be on a `<template>` and must reference an array. Each clone gets `item`, `index`, and `--fy-index`. Nested repeats are rejected; use a controller.
+- Bindings apply once per load, before the controller mounts. Controller-created DOM is not re-bound.
+- Missing paths warn and resolve to empty text, a removed attribute/class, or false for `if`.
+- Primitive top-level props are also exposed as `--fy-prop-<name>` CSS custom properties. Booleans are `1`/`0`; objects and arrays are omitted.
+
+## Animation
+
+CSS `@keyframes` and the Web Animations API are paused and seeked by the runtime inside the composition root.
+
+```css
+@keyframes fade-up {
+  from { opacity: 0; transform: translateY(24px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+#title { animation: fade-up 1s ease-out both; }
+```
+
+```html
+<h1 data-fy-anim-start="30" data-fy-anim-duration="60" data-fy-anim-easing="ease-out"></h1>
+```
+
+- `data-fy-anim-start` is a non-negative frame count. `data-fy-anim-duration` is a positive frame count. `data-fy-anim-easing` is a CSS easing.
+- One declarative animation per element. The CSS `animation` shorthand supplies keyframes, fill mode, and iteration count; the attributes override delay/duration/easing.
+- The root exposes `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames`. Use them in `calc()` for simple computed motion and progress bars.
+- Do not use CSS transitions. They are diagnosed as non-deterministic.
+
+## Controllers
+
+An optional controller handles Canvas 2D, WebGL, karaoke, and per-frame computation CSS cannot express.
+
+Inline for a small, single-use controller:
+
+```html
+<script type="text/fy-controller">
+export default {
+  mount({ root, props }) {
+    // query elements, create canvases, load data
   },
-  update({ frame, props }) {
-    title.textContent = props.title;
-    title.style.transform = `translateX(${random("title:" + frame) * 40}px)`;
+  update({ frame, props, root }) {
+    // synchronous and seek-safe
   },
   dispose() {
-    title = undefined;
+    // release module-scope state and listeners
   },
-});
+};
+</script>
 ```
 
-- `mount()` runs once and may await loading work.
-- `update({ frame, props })` is synchronous and seek-safe.
-- `dispose()` releases resources and module-scope references.
-- Props are JSON-serializable, deep-frozen, and merged shallowly over `defaultProps`.
-- Keep mutable state in module-scope variables, never on `this`.
+External for a reusable or complex controller:
+
+```html
+<script type="text/fy-controller" src="./hello.controller.js"></script>
+```
+
+- Exactly one controller is allowed. It may export `mount`, `update`, `dispose`, and `validateProps`; at least one is required. `mount` may be async; `update` and `validateProps` are synchronous.
+- A validation-only controller may export just `validateProps(props)`.
+- Inline source is served through a virtual module URL, so relative imports and `import.meta.url` work like an external module. A literal `</script>` inside inline source must be escaped.
+- The controller is the only executable code. Other executable `<script>` elements and `on*` handlers are rejected.
+- Controller `src` resolves relative to the composition document. Media and transcript `src` values resolve from the project root.
+- Keep mutable state in module scope, never on `this`. Reset it in `dispose()`.
 
 ## Forbidden animation inputs
 
@@ -65,33 +140,77 @@ Do not use any of these as animation state:
 - CSS transitions
 - state left from a previously visited frame
 
-Use `random("stable:key")` for deterministic randomness. The value depends only on the key, not call order.
+Use `random("stable:key")` from `frameyard/runtime` for deterministic randomness. The value depends only on the key, not call order.
 
 ```js
 import { random } from "frameyard/runtime";
 
-const x = random("star:17:x") * width;
+const x = random("star:17:x") * 1920;
 ```
 
-## CSS and Canvas
+## Canvas and WebGL
 
-CSS `@keyframes` and the Web Animations API are paused and seeked by the runtime inside the composition container. They are valid animation drivers. CSS transitions are diagnosed as non-deterministic and should not be used.
-
-Canvas 2D must be redrawn from the current frame:
+Redraw Canvas 2D and WebGL from the current frame in the controller's `update()`:
 
 ```js
 update({ frame }) {
   context.clearRect(0, 0, canvas.width, canvas.height);
   context.fillStyle = frame % 2 === 0 ? "#101820" : "#203040";
   context.fillRect(0, 0, canvas.width, canvas.height);
+
+  gl.clearColor(frame % 2 === 0 ? 0.1 : 0.2, 0.1, 0.13, 1);
+  gl.clear(gl.COLOR_BUFFER_BIT);
 }
 ```
 
+Do not preserve and accumulate WebGL drawing across frames unless that accumulation is itself deterministic. Production sessions use software WebGL so output does not depend on the host GPU.
+
+## Embedded video and audio
+
+Declare local media in the composition document:
+
+```html
+<video
+  src="assets/clip.webm"
+  data-fy-start="30"
+  data-fy-trim="0.5"
+  data-fy-duration="4"
+  data-fy-volume="0.8"
+></video>
+
+<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>
+```
+
+- `data-fy-start` is the composition frame where the source starts. Default `0`.
+- `data-fy-trim` is seconds trimmed from the source start. Default `0`.
+- `data-fy-duration` optionally limits how many source seconds are used.
+- `data-fy-volume` sets volume from `0` to `1`. Default `1`.
+
+Do not call `play()`, `pause()`, or set `currentTime` in a controller. Media must be in the light DOM; shadow roots are not scanned. Sources must be local project-relative files; live streams, remote URLs, `<source>` children, and `<track>` children are not supported. The runtime loads the complete file during the loading phase and seeks video after each `update()`.
+
+An unmuted video's audio is extracted and mixed into the output timeline. Set `muted` or `data-fy-audio="off"` for a silent visual asset.
+
+## Transcripts
+
+Declare canonical transcript requirements with:
+
+```html
+<fy-transcript src="assets/voice.transcript.json" words></fy-transcript>
+```
+
+`words` requires measured word timings. `check`, `still`, and `render` validate the transcript file. Visual presentation is the composition's responsibility; a controller can fetch the JSON and render timed text or karaoke. See [subtitles and karaoke](subtitles-karaoke.md).
+
 ## Loading assets
 
-Remote data, images, fonts, and other assets must resolve during `mount()` or before the first frame. The production browser blocks network requests after loading begins. A fetch from `update()` is a bug.
+Remote data, images, fonts, and other assets must resolve during the loading phase before frame production. The production browser blocks network requests after loading begins. A fetch from `update()` is a bug.
 
-Images inserted in `mount()` are awaited by the runtime. Static fonts should be loaded with `document.fonts.ready` or an explicit `FontFace` before frame production.
+Images declared in the document are awaited by the host. Static fonts should be loaded with `document.fonts.ready` or an explicit `FontFace` before frame production.
 
 ## Validation and inspection
 
@@ -100,8 +219,8 @@ npx frameyard check hello --json
 npx frameyard still hello --frame 42 --out hello-42.png --json
 ```
 
-`check` mounts the composition, evaluates every frame, and validates audio and declared transcripts without capturing or encoding. Do not replace it with a single still.
+`check` runs static validation before Chromium, then evaluates every frame and validates audio and declared transcripts without capturing or encoding. Read the structured `diagnostics` array. Do not replace `check` with a single still.
 
 ## Metadata is fixed
 
-`width`, `height`, `fps`, and `durationInFrames` cannot be derived from props. Choose a reusable resolution, frame rate, and duration; put variation in props. Frameyard does not change duration to fit audio.
+`width`, `height`, `fps`, and `duration-in-frames` cannot be derived from props. Choose a reusable resolution, frame rate, and duration; put variation in props. Frameyard does not change duration to fit audio.

package/skills/frameyard/references/diagnostics.md

@@ -0,0 +1,90 @@
+# Diagnostics
+
+Frameyard reports composition problems as structured diagnostics before and during frame production.
+
+## Static validation
+
+`check`, `still`, and `render` run a Node-side static composition validation before launching Chromium. `dev` runs it when a composition is requested. Static errors fail the command without starting a browser; warnings allow frame evaluation.
+
+Static validation covers:
+
+- doctype, root count, metadata, and default-props JSON
+- controller declaration and file existence
+- executable scripts, `on*` handlers, `javascript:` URLs, and unsupported visual elements
+- unknown `data-fy-*` attributes, binding paths, `if`/`repeat` placement, and animation attributes
+- audio/video/transcript references and ordinary image/stylesheet assets
+- visual content outside `<fy-composition>`
+
+## Diagnostic shape
+
+```json
+{
+  "severity": "warning",
+  "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"
+  }
+}
+```
+
+`details` may include `path`, `line`, `column`, `endLine`, `endColumn`, `element`, `attribute`, `value`, `suggestion`, `frame`, and `controller`.
+
+## Common codes
+
+| Code | Severity | Meaning |
+| --- | --- | --- |
+| `COMPOSITION_INVALID` | error | Missing/invalid doctype, root, metadata, or document structure |
+| `PROPS_INVALID` | error | Invalid default props JSON, invalid overrides, or `validateProps` failure |
+| `CONTROLLER_INVALID` | error | Missing/duplicate/both-inline-and-external controller, missing file, or invalid exports |
+| `BINDING_INVALID` | error | Unknown `data-fy-*` attribute or malformed binding path |
+| `BINDING_PATH_MISSING` | warning | A binding path is absent from the resolved props |
+| `BINDING_VALUE_INVALID` | warning | A text/attribute/class binding resolved to an object or array |
+| `BINDING_REPEAT_INVALID` | error | Repeat is not on `<template>`, or its path is missing/not an array |
+| `BINDING_REPEAT_NESTED` | error | Nested `data-fy-repeat` |
+| `BINDING_TARGET_INVALID` | error | `data-fy-text` on a void element or the root; invalid binding target |
+| `ANIMATION_INVALID` | error | Invalid `data-fy-anim-*` value |
+| `ANIMATION_NOT_FOUND` | warning | `data-fy-anim-*` is present but the element has no CSS animation |
+| `ANIMATION_MULTIPLE` | warning | Multiple animations on one declaratively scheduled element |
+| `SCRIPT_NOT_ALLOWED` | error | Executable `<script>` other than the controller |
+| `EVENT_HANDLER_NOT_ALLOWED` | error | Inline `on*` handler or `data-fy-attr-on*` |
+| `URL_NOT_ALLOWED` | error | `javascript:` URL |
+| `ELEMENT_NOT_SUPPORTED` | error | `iframe`, `object`, `embed`, `base`, refresh/CSP meta, `source`, `track`, or declarative shadow DOM |
+| `ELEMENT_UNKNOWN` | warning | Unknown `fy-*` element |
+| `CONTENT_OUTSIDE_ROOT` | warning | Visual content outside `<fy-composition>` |
+| `MEDIA_INVALID` | error | Invalid or missing audio/video source or attributes |
+| `TRANSCRIPT_INVALID` | error | Invalid or missing transcript source |
+| `ASSET_NOT_FOUND` | error | Missing image, stylesheet, media, or transcript file |
+| `AUDIO_WARNING` | warning | Audio timeline overrun or silent embedded media |
+| `TRANSCRIPT_WARNING` | warning | Empty transcript text or no timed segments |
+| `DETERMINISM_WARNING` | warning | Forbidden clock/randomness, CSS transition, or runtime diagnostic |
+| `COMPOSITION_NOT_READY` | error | `seek`/`settle` before a successful load |
+| `COMPOSITION_DISPOSED` | error | Operation after the host was disposed |
+
+## Results
+
+`check`, `still`, and `render` JSON results expose:
+
+- `entry`: project-relative HTML path
+- `controller`: `{ kind: "inline" }`, `{ kind: "external", src }`, or `null`
+- `diagnostics`: all static and runtime diagnostics, deduplicated
+
+`check` also exposes `metadata`, `framesChecked`, `audio.details`, and `transcripts.details`. `still` exposes `frame`, `path`, `width`, and `height`. `render` exposes the output path, dimensions, frame count, concurrency, bytes, and audio/transcript clip counts.
+
+Failures use the same envelope with `error.code`, `error.message`, optional `error.details`, and top-level `diagnostics`.
+
+## Working with diagnostics
+
+1. Run `npx frameyard check <id> --json`.
+2. Read every error first; fix the first one and rerun.
+3. Treat warnings as actionable. `BINDING_PATH_MISSING` is usually a typo; use the `suggestion` field.
+4. Use `details.path`, `line`, and `column` to edit the exact source.
+5. Re-run `check`, inspect representative stills, then render.
+
+Do not ignore a failing `check`, a missing still, or a nonzero render. Do not describe visual correctness you did not inspect.

package/skills/frameyard/references/failure-recovery.md

@@ -1,6 +1,6 @@
 # Failure recovery
 
-Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and only then render.
+Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and only then render. `check`, `still`, and `render` run static composition validation before Chromium; read the structured `diagnostics` array for source locations.
 
 ## Common codes
 
@@ -8,28 +8,52 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 | --- | --- | --- |
 | `USAGE` | Invalid flags or missing required arguments | Read `npx frameyard <command> --help`. |
 | `CONFIG_NOT_FOUND` | No `video.config.js` found | Run from the project root or pass `--project`. |
-| `CONFIG_INVALID` | Invalid config or composition entry | Fix `video.config.js`; entries must be explicit, local, and exist. |
+| `CONFIG_INVALID` | Invalid config or composition entry | Fix `video.config.js`; entries must be explicit, local, `.html`, and exist. |
 | `COMPOSITION_NOT_FOUND` | ID is not listed | Add the entry to `video.config.js`. |
-| `COMPOSITION_INVALID` | Invalid metadata or lifecycle shape | Fix metadata and ensure `update()` is synchronous. |
-| `COMPOSITION_ERROR` | Mount, update, or browser page error | Read the frame location in the message; remove forbidden clocks/randomness. |
+| `COMPOSITION_INVALID` | Invalid doctype, root, metadata, or document structure | Fix the composition document; check `details.line` and `details.attribute`. |
+| `COMPOSITION_ERROR` | Mount, update, or browser page error | Read the frame location; remove forbidden clocks/randomness or fix the controller. |
 | `COMPOSITION_UPDATE_ASYNC` | `update()` returned a promise | Move async work to `mount()`. |
-| `PROPS_INVALID` | Props are not JSON or fail `validateProps()` | Fix the props file or validator. |
-| `FRAME_OUT_OF_RANGE` | Frame is outside `0..durationInFrames - 1` | Choose a valid frame. |
-| `AUDIO_INVALID` | Bad clip or unreadable/unsupported audio | Use a local project-relative file with a decodable audio stream. |
+| `COMPOSITION_NOT_READY` | `seek`/`settle` before a successful load | Await `load`/`ready`. |
+| `COMPOSITION_DISPOSED` | Operation after host disposal | Reload the composition. |
+| `CONTROLLER_INVALID` | Missing, duplicate, or invalid controller declaration/file/exports | Keep exactly one inline or external controller; verify its exports and path. |
+| `BINDING_INVALID` | Unknown `data-fy-*` attribute or malformed path | Fix the attribute name or path. |
+| `BINDING_PATH_MISSING` | Binding path absent from resolved props | Fix the prop or path; use `details.suggestion`. |
+| `BINDING_VALUE_INVALID` | Object/array used where a primitive is required | Use a string/number/boolean or move the logic to a controller. |
+| `BINDING_REPEAT_INVALID` | Repeat not on `<template>`, or path missing/not an array | Use `<template data-fy-repeat="items">` with an array. |
+| `BINDING_REPEAT_NESTED` | Nested repeat | Use a controller for nested data. |
+| `BINDING_TARGET_INVALID` | `data-fy-text` on a void element or the root | Move the binding to a text container. |
+| `ANIMATION_INVALID` | Invalid `data-fy-anim-*` value | Use non-negative integer frames and a positive duration. |
+| `ANIMATION_NOT_FOUND` | `data-fy-anim-*` without a CSS animation | Add an `animation` shorthand or remove the attributes. |
+| `ANIMATION_MULTIPLE` | Multiple animations on one scheduled element | Use one animation or move scheduling to CSS/the controller. |
+| `SCRIPT_NOT_ALLOWED` | Executable script other than the controller | Move code into the controller. |
+| `EVENT_HANDLER_NOT_ALLOWED` | Inline `on*` handler or `data-fy-attr-on*` | Remove the handler; use a controller. |
+| `URL_NOT_ALLOWED` | `javascript:` URL | Use a safe URL. |
+| `ELEMENT_NOT_SUPPORTED` | `iframe`, `object`, `embed`, `base`, refresh/CSP meta, `source`, `track`, or declarative shadow DOM | Use supported DOM/SVG/canvas/video sources. |
+| `ELEMENT_UNKNOWN` | Unknown `fy-*` element | Use `fy-composition`/`fy-transcript` or a normal element. |
+| `CONTENT_OUTSIDE_ROOT` | Visual content outside `<fy-composition>` | Move it inside the root. |
+| `PROPS_INVALID` | Invalid props JSON or `validateProps()` failure | Fix the props file or validator. |
+| `FRAME_OUT_OF_RANGE` | Frame outside `0..durationInFrames - 1` | Choose a valid frame. |
+| `AUDIO_INVALID` | Bad clip or unreadable/unsupported audio | Use a local project-root-relative file with a decodable audio stream. |
+| `AUDIO_WARNING` | Audio timeline overrun or silent embedded media | Adjust timing/trim or remove the silent source. |
+| `MEDIA_INVALID` | Invalid media source or attributes | Use local, seekable files and valid `data-fy-*` values. |
+| `MEDIA_SEEK_FAILED` | Embedded video did not reach the requested time | Re-encode with a regular keyframe interval or replace the source. |
+| `TRANSCRIPT_INVALID` | Invalid/missing transcript declaration or JSON | Regenerate with `npx frameyard transcribe`; do not hand-edit timestamps. |
+| `TRANSCRIPT_WORDS_UNAVAILABLE` | Karaoke requested without measured word timings | Re-run transcription with `--words` or remove `words`. |
+| `TRANSCRIPT_WARNING` | Empty transcript text or no timed segments | Regenerate the transcript. |
 | `ASSET_NOT_FOUND` | Required file is missing or unreadable | Restore the asset, model, or text file. |
+| `DETERMINISM_WARNING` | Forbidden clock/randomness, CSS transition, or runtime warning | Derive state from `frame`/`props`; use `random("stable:key")`. |
 | `OUTPUT_EXISTS` | Output exists and replacement was not approved | Reuse it, choose another path, or pass `--overwrite`/`--force` with permission. |
 | `OUTPUT_FAILED` | An output or manifest could not be written atomically | Check directory permissions and free space; rerun. |
 | `EXECUTABLE_NOT_FOUND` | `qwen-tts` or `whisper-cli` could not be resolved | Pass `--executable`, set the environment variable, or fix `PATH`. |
 | `TTS_FAILED` | Speech synthesis failed or produced an invalid WAV | Read stderr; verify the talker/codec models and CLI compatibility. |
 | `TRANSCRIBE_FAILED` | Normalization or `whisper-cli` failed | Verify FFmpeg, the source media, and the Whisper model. |
-| `TRANSCRIPT_INVALID` | Canonical transcript JSON is malformed | Regenerate it with `npx frameyard transcribe`; do not hand-edit timestamps. |
-| `TRANSCRIPT_WORDS_UNAVAILABLE` | Karaoke requested without measured word timings | Re-run transcription with `--words` or remove `words: true`. |
 | `MANIFEST_INVALID` | Provenance manifest is corrupt or unsupported | Restore or regenerate the manifest; do not invent hashes. |
 | `FFMPEG_FAILED` | FFmpeg is missing, lacks encoders, or failed | Run `npx frameyard doctor --json`; install FFmpeg with libx264 and AAC. |
 | `FFPROBE_FAILED` | FFprobe is missing or failed | Install FFmpeg/FFprobe together. |
 | `BROWSER_FAILED` | Chromium could not start | Install the Playwright Chromium build. |
 | `RENDER_FAILED` | Capture or encoding failed | Read stderr; rerun `check` and a representative `still`. |
 | `CANCELLED` | The operation was interrupted | Rerun when ready. Partial outputs are removed. |
+| `INTERNAL` | Unexpected internal failure | Rerun with `FRAMEYARD_DEBUG=1` and report the stack. |
 
 ## Behavior to rely on
 
@@ -38,6 +62,8 @@ Do not claim success after a nonzero exit. Fix the cause, rerun `check`, and onl
 - Existing outputs are replaced only with `--overwrite` (renders/stills) or `--force` (generated assets).
 - Cancellation terminates the child inference process and cleans temporary work.
 - `check` validates every frame and declared transcripts without encoding.
+- Static validation failures exit before Chromium starts.
+- `check`, `still`, and `render` seek embedded videos and wait for decode before evaluating or capturing a frame.
 - `doctor` inspects but never repairs, downloads, or modifies the environment.
 
 ## When visual inspection is impossible
@@ -48,10 +74,10 @@ If the host cannot display images, say explicitly that representative stills cou
 
 Report all of:
 
-- source project path and composition entry;
+- source project path, composition entry, and controller;
 - props file or inline props used;
 - generated audio/transcript paths and provenance manifest path;
-- `check` result, including warnings;
+- `check` result, including diagnostics and warnings;
 - still paths and whether they were viewed;
 - final video path, frame count, and audio/transcript summary;
-- any skipped step or unresolved warning.
+- any skipped step or unresolved diagnostic.