frameyard 0.3.0 → 0.5.0

package/skills/frameyard/references/bindings.md

@@ -0,0 +1,73 @@
+# Bindings
+
+Bindings map immutable props into the composition DOM once per load. They are explicit HTML attributes; there is no template expression language.
+
+## Attributes
+
+| Attribute | Effect |
+| --- | --- |
+| `data-fy-text="path"` | Sets `textContent`. |
+| `data-fy-attr-<name>="path"` | Sets an attribute. |
+| `data-fy-class-<name>="path"` | Toggles one class. |
+| `data-fy-if="path"` | Removes the element when false. |
+| `data-fy-repeat="path"` on `<template>` | Clones the template content for each array item. |
+
+```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>
+```
+
+## Paths
+
+- Dot-separated: `title`, `user.name`, `items.0.label`.
+- Numeric segments index arrays.
+- Only own properties are read. `__proto__`, `constructor`, and `prototype` are rejected.
+- Inside a repeat clone, `item` and `index` shadow props.
+- Missing paths are warnings. Text becomes empty, attributes/classes are removed, and `if` is false. A missing or non-array `repeat` path is an error.
+
+## Value coercion
+
+| Binding | Rule |
+| --- | --- |
+| `text` | Strings, numbers, and booleans are stringified; null/undefined become empty; objects/arrays warn and become empty. |
+| `attr` | `true` writes an empty attribute; `false`/null/undefined remove it; strings/numbers are stringified; objects/arrays warn and remove. |
+| `class` | JavaScript truthiness; objects/arrays warn and remove. |
+| `if` | JavaScript truthiness. Empty arrays are truthy. |
+| `repeat` | Must be an array; otherwise an error. |
+
+`data-fy-attr-on*` is rejected. A bound `href`/`src` that resolves to a `javascript:` URL is rejected.
+
+## Repeat scope
+
+```html
+<ul>
+  <template data-fy-repeat="items">
+    <li data-fy-text="item.label"></li>
+  </template>
+</ul>
+```
+
+- The `<template>` is replaced by the clones.
+- `--fy-index` is set on each top-level clone for CSS stagger.
+- Nested repeats are rejected. Use a controller for nested data.
+- A repeat template cannot also use `data-fy-if` or `data-fy-text`.
+
+## CSS variables
+
+Primitive top-level props are also set as `--fy-prop-<name>` on the composition root:
+
+```html
+<div style="background: var(--fy-prop-accent)"></div>
+```
+
+Booleans are `1`/`0`. Null, undefined, objects, and arrays are omitted. Bindings are applied before the controller mounts; controller-created DOM is not re-bound.
+
+## Ordering
+
+Bindings apply top-down: repeat, then `if`, then text/attribute/class. A removed element does not process its children. `data-fy-if` and `data-fy-text` on the composition root are errors.

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.
 
-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;
+## 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>
+```
+
+- 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>
+```
+
+External for a reusable or complex controller:
+
+```html
+<script type="text/fy-controller" src="./hello.controller.js"></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`.
+- 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,19 +140,17 @@ 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;
 ```
 
 ## 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 and WebGL must be redrawn from the current frame:
+Redraw Canvas 2D and WebGL from the current frame in the controller's `update()`:
 
 ```js
 update({ frame }) {
@@ -92,34 +165,52 @@ update({ frame }) {
 
 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
+## Embedded video and audio
 
-Place local `<video>` elements in `mount()` and let the runtime seek them:
+Declare local media in the composition document:
 
 ```html
 <video
   src="assets/clip.webm"
-  data-frameyard-start="30"
-  data-frameyard-trim="0.5"
-  data-frameyard-duration="4"
-  data-frameyard-volume="0.8"
+  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-frameyard-start` is the composition frame where the source starts. Default `0`.
-- `data-frameyard-trim` is seconds trimmed from the source start. Default `0`.
-- `data-frameyard-duration` optionally limits how many source seconds are used.
-- `data-frameyard-volume` sets embedded-audio volume from `0` to `1`. Default `1`.
+- `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.
 
-Do not call `play()`, `pause()`, or set `currentTime` in `update()`. Create video elements and set the `data-frameyard-*` attributes in `mount()`. Videos must be in the composition container's light DOM; shadow roots are not scanned. The runtime pauses every video, loads the complete local file during the loading phase, and seeks it after each `update()` before capture. Video sources must be local, seekable project files; live streams, remote URLs, and videos added or changed during `update()` are not supported.
+## Transcripts
+
+Declare canonical transcript requirements with:
+
+```html
+<fy-transcript src="assets/voice.transcript.json" words></fy-transcript>
+```
 
-An unmuted video's audio is extracted and mixed into the output timeline. Set `muted` or `data-frameyard-audio="off"` for a silent visual asset. The same start, trim, duration, and volume attributes place its audio.
+`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
 
@@ -128,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.