frameyard 0.3.0 → 0.5.0

package/examples/webgl/compositions/webgl.controller.js

@@ -0,0 +1,200 @@
+const VERTEX_SHADER = `
+  attribute vec2 a_position;
+
+  void main() {
+    gl_Position = vec4(a_position, 0.0, 1.0);
+  }
+`;
+
+const FRAGMENT_SHADER = `
+  precision highp float;
+
+  uniform vec2 u_resolution;
+  uniform float u_frame;
+  uniform float u_duration;
+  uniform vec3 u_accent;
+
+  const float TAU = 6.28318530718;
+
+  float hash(vec2 p) {
+    return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+  }
+
+  void main() {
+    vec2 uv = gl_FragCoord.xy / u_resolution;
+    vec2 p = (gl_FragCoord.xy * 2.0 - u_resolution) / u_resolution.y;
+    float phase = (u_frame / max(u_duration, 1.0)) * TAU;
+
+    // A slow domain warp turns the contour field into a liquid surface.
+    vec2 q = p;
+    q.x += 0.045 * sin(p.y * 3.4 - phase * 0.8);
+    q.y += 0.10 * sin(p.x * 2.2 + phase * 0.55) + 0.035 * sin(p.x * 5.7 - phase * 0.9);
+
+    float terrain = q.y + 0.07 * sin(q.x * 3.6 + phase * 0.7) + 0.025 * sin(q.x * 8.4 - phase * 1.1);
+    float contour = abs(fract(terrain * 14.0 + phase * 0.5) - 0.5);
+    float line = smoothstep(0.455, 0.5, contour);
+    float glow = smoothstep(0.26, 0.5, contour);
+
+    vec3 ink = mix(vec3(0.016, 0.026, 0.038), vec3(0.035, 0.078, 0.085), uv.y);
+    vec3 color = ink;
+
+    float right = smoothstep(0.14, 0.66, uv.x);
+    color += u_accent * line * (0.10 + 0.38 * right);
+    color += u_accent * glow * 0.045 * right;
+
+    // A soft moving light and one thin orbit ring anchor the right side.
+    vec2 light = vec2(0.34 + 0.05 * cos(phase * 0.6), 0.06 + 0.04 * sin(phase * 0.45));
+    float radius = length(p - light);
+    float halo = 0.035 / (radius + 0.035);
+    vec3 white = mix(u_accent, vec3(0.92, 1.0, 0.98), 0.7);
+    color += white * halo * 0.42;
+
+    float ring = 1.0 - smoothstep(0.0, 0.007, abs(radius - 0.27 - 0.012 * sin(phase * 1.4)));
+    color += white * ring * 0.22;
+
+    // Static grain keeps the gradient from banding without adding temporal noise.
+    color += (hash(gl_FragCoord.xy) - 0.5) * 0.02;
+    float vignette = 1.0 - smoothstep(0.62, 1.28, length(p * vec2(0.86, 1.0)));
+    color *= 0.58 + 0.42 * vignette;
+
+    gl_FragColor = vec4(color, 1.0);
+  }
+`;
+
+let gl;
+let program;
+let buffer;
+let uniforms;
+let labels;
+let durationFrames = 360;
+let fps = 30;
+
+function compileShader(type, source) {
+  const shader = gl.createShader(type);
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (gl.getShaderParameter(shader, gl.COMPILE_STATUS) !== true) {
+    const log = gl.getShaderInfoLog(shader);
+    gl.deleteShader(shader);
+    throw new Error(log ?? "Could not compile the WebGL shader.");
+  }
+  return shader;
+}
+
+function linkProgram() {
+  const vertex = compileShader(gl.VERTEX_SHADER, VERTEX_SHADER);
+  const fragment = compileShader(gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
+  const next = gl.createProgram();
+  gl.attachShader(next, vertex);
+  gl.attachShader(next, fragment);
+  gl.linkProgram(next);
+  gl.detachShader(next, vertex);
+  gl.detachShader(next, fragment);
+  gl.deleteShader(vertex);
+  gl.deleteShader(fragment);
+  if (gl.getProgramParameter(next, gl.LINK_STATUS) !== true) {
+    const log = gl.getProgramInfoLog(next);
+    gl.deleteProgram(next);
+    throw new Error(log ?? "Could not link the WebGL program.");
+  }
+  return next;
+}
+
+function hexToRgb(value) {
+  const match = /^#([0-9a-f]{6})$/i.exec(typeof value === "string" ? value : "");
+  if (!match) {
+    return [0.47, 0.94, 0.78];
+  }
+  const number = Number.parseInt(match[1], 16);
+  return [((number >> 16) & 0xff) / 255, ((number >> 8) & 0xff) / 255, (number & 0xff) / 255];
+}
+
+export default {
+  validateProps(props) {
+    const errors = [];
+    for (const key of ["kicker", "title", "subtitle"]) {
+      if (typeof props[key] !== "string") {
+        errors.push(key + " must be a string");
+      }
+    }
+    if (typeof props.accent !== "string" || !/^#[0-9a-f]{6}$/i.test(props.accent)) {
+      errors.push("accent must be a #rrggbb color");
+    }
+    return errors;
+  },
+
+  mount({ root, props }) {
+    const canvas = root.querySelector("#field");
+    fps = Number(root.getAttribute("fps") ?? 30);
+    durationFrames = Number(root.getAttribute("duration-in-frames") ?? 360);
+
+    gl = canvas.getContext("webgl", {
+      alpha: false,
+      antialias: false,
+      depth: false,
+      stencil: false,
+      preserveDrawingBuffer: true,
+    });
+    if (!gl) {
+      throw new Error("WebGL is unavailable. The production renderer pins SwiftShader.");
+    }
+
+    program = linkProgram();
+    gl.useProgram(program);
+
+    buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    const position = gl.getAttribLocation(program, "a_position");
+    gl.enableVertexAttribArray(position);
+    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+
+    uniforms = {
+      frame: gl.getUniformLocation(program, "u_frame"),
+      resolution: gl.getUniformLocation(program, "u_resolution"),
+      duration: gl.getUniformLocation(program, "u_duration"),
+      accent: gl.getUniformLocation(program, "u_accent"),
+    };
+
+    const accent = hexToRgb(props.accent);
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    gl.uniform2f(uniforms.resolution, canvas.width, canvas.height);
+    gl.uniform1f(uniforms.duration, durationFrames);
+    gl.uniform3f(uniforms.accent, accent[0], accent[1], accent[2]);
+    gl.clearColor(0.016, 0.026, 0.038, 1);
+
+    labels = {
+      frame: root.querySelector("#frame"),
+      total: root.querySelector("#total"),
+      clock: root.querySelector("#clock"),
+    };
+    labels.total.textContent = String(durationFrames - 1).padStart(3, "0");
+  },
+
+  update({ frame }) {
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    gl.uniform1f(uniforms.frame, frame);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    labels.frame.textContent = String(frame).padStart(3, "0");
+    labels.clock.textContent = (frame / fps).toFixed(2) + " S";
+  },
+
+  dispose() {
+    if (gl) {
+      if (buffer) {
+        gl.deleteBuffer(buffer);
+      }
+      if (program) {
+        gl.deleteProgram(program);
+      }
+    }
+    gl = undefined;
+    program = undefined;
+    buffer = undefined;
+    uniforms = undefined;
+    labels = undefined;
+    durationFrames = 360;
+    fps = 30;
+  },
+};

package/examples/webgl/compositions/webgl.html

@@ -0,0 +1,215 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <script type="application/json" data-fy="props">
+      {
+        "kicker": "Shader Study / 001",
+        "title": "Liquid Light",
+        "subtitle": "A frame-driven WebGL field, resolved in software so every captured pixel stays reproducible.",
+        "accent": "#78f0c8"
+      }
+    </script>
+    <style>
+      @keyframes rise {
+        from {
+          opacity: 0;
+          transform: translateY(44px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+      @keyframes fade {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+      @keyframes draw {
+        from {
+          opacity: 0;
+          transform: scaleX(0);
+        }
+        to {
+          opacity: 1;
+          transform: scaleX(1);
+        }
+      }
+      html,
+      body,
+      fy-composition {
+        background: #060a0e;
+      }
+      #scene {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        background: #060a0e;
+        color: #edf6f3;
+        font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+      }
+      #field {
+        position: absolute;
+        inset: 0;
+        display: block;
+        width: 100%;
+        height: 100%;
+      }
+      #scrim {
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(
+          90deg,
+          rgba(4, 8, 11, 0.94) 0%,
+          rgba(4, 8, 11, 0.78) 34%,
+          rgba(4, 8, 11, 0.18) 66%,
+          rgba(4, 8, 11, 0) 100%
+        );
+      }
+      #vignette {
+        position: absolute;
+        inset: 0;
+        background: radial-gradient(ellipse at 60% 45%, transparent 34%, rgba(0, 0, 0, 0.46) 100%);
+        pointer-events: none;
+      }
+      #kicker {
+        position: absolute;
+        top: 72px;
+        left: 148px;
+        display: flex;
+        align-items: center;
+        gap: 16px;
+        font:
+          600 14px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.26em;
+        text-transform: uppercase;
+        color: var(--fy-prop-accent);
+        animation: fade 1s linear both;
+      }
+      #kicker::before {
+        content: "";
+        width: 8px;
+        height: 8px;
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 18px var(--fy-prop-accent);
+      }
+      #meta {
+        position: absolute;
+        top: 72px;
+        right: 148px;
+        text-align: right;
+        font:
+          500 13px/1.9 ui-monospace,
+          monospace;
+        letter-spacing: 0.12em;
+        color: #80908e;
+        animation: fade 1s linear both;
+      }
+      #meta strong {
+        color: #dce9e6;
+        font-weight: 500;
+      }
+      #title {
+        position: absolute;
+        top: 292px;
+        left: 148px;
+        width: 780px;
+        margin: 0;
+        font-size: 168px;
+        line-height: 0.88;
+        letter-spacing: -0.062em;
+        font-weight: 660;
+        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #subtitle {
+        position: absolute;
+        top: 604px;
+        left: 152px;
+        width: 720px;
+        margin: 0;
+        font-size: 30px;
+        line-height: 1.45;
+        font-weight: 420;
+        color: #96a7a3;
+        animation: rise 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #footer {
+        position: absolute;
+        left: 148px;
+        right: 148px;
+        bottom: 64px;
+        animation: fade 1s linear both;
+      }
+      #rule {
+        position: relative;
+        height: 1px;
+        background: rgba(237, 246, 243, 0.14);
+        transform-origin: left center;
+        animation: draw 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #progress {
+        position: absolute;
+        inset: 0 auto 0 0;
+        width: calc(var(--fy-progress) * 100%);
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 16px var(--fy-prop-accent);
+      }
+      #footer-row {
+        display: flex;
+        justify-content: space-between;
+        align-items: baseline;
+        gap: 24px;
+        margin-top: 18px;
+        font:
+          500 13px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.14em;
+        color: #758581;
+        animation: fade 1s linear both;
+      }
+      #footer-row strong {
+        color: var(--fy-prop-accent);
+        font-weight: 600;
+      }
+      #footer-meta {
+        display: flex;
+        gap: 28px;
+      }
+    </style>
+  </head>
+  <body>
+    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="360">
+      <div id="scene">
+        <canvas id="field" width="1920" height="1080"></canvas>
+        <div id="scrim"></div>
+        <div id="vignette"></div>
+        <div id="kicker" data-fy-text="kicker" data-fy-anim-start="0" data-fy-anim-duration="28"></div>
+        <div id="meta" data-fy-anim-start="18" data-fy-anim-duration="34">
+          <div><strong>WEBGL 1.0</strong> / SWIFTSHADER</div>
+          <div>1920 × 1080 · 30 FPS</div>
+          <div>12.00 S · 360 FRAMES</div>
+        </div>
+        <h1 id="title" data-fy-text="title" data-fy-anim-start="6" data-fy-anim-duration="56"></h1>
+        <p id="subtitle" data-fy-text="subtitle" data-fy-anim-start="34" data-fy-anim-duration="52"></p>
+        <div id="footer" data-fy-anim-start="28" data-fy-anim-duration="30">
+          <div id="rule" data-fy-anim-start="38" data-fy-anim-duration="60">
+            <div id="progress"></div>
+          </div>
+          <div id="footer-row" data-fy-anim-start="44" data-fy-anim-duration="30">
+            <span>FRAME <strong id="frame">000</strong> / <span id="total">359</span></span>
+            <span id="clock">0.00 S</span>
+            <span id="footer-meta"><span>FRAME-SEEKED</span><span>NO RAF</span></span>
+          </div>
+        </div>
+      </div>
+    </fy-composition>
+
+    <script type="text/fy-controller" src="./webgl.controller.js"></script>
+  </body>
+</html>

package/examples/webgl/props/webgl.json

@@ -0,0 +1,6 @@
+{
+  "kicker": "Shader Study / 001",
+  "title": "Liquid Light",
+  "subtitle": "A frame-driven WebGL field, resolved in software so every captured pixel stays reproducible.",
+  "accent": "#78f0c8"
+}

package/examples/webgl/video.config.js

@@ -0,0 +1,5 @@
+export default {
+  compositions: {
+    webgl: "./compositions/webgl.html",
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Local-first, deterministic video composition framework for HTML, CSS, and JavaScript.",
   "type": "module",
   "license": "MIT",
@@ -52,6 +52,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
+    "parse5": "^8.0.1",
     "playwright": "1.64.1"
   },
   "devDependencies": {
@@ -65,16 +66,19 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json",
+    "typecheck:browser": "tsc -p tsconfig.browser.json",
     "check:scripts": "node scripts/check-scripts.mjs",
     "lint": "oxlint",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm typecheck:test",
+    "check:static": "pnpm check:scripts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm typecheck:test && pnpm typecheck:browser",
+    "compare-stills": "node scripts/compare-stills.mjs",
     "check": "pnpm check:static && pnpm test",
     "test": "pnpm build && vitest run",
     "test:unit": "vitest run test/contracts.test.ts test/docs.test.ts test/random.test.ts test/release.test.ts test/scaffold.test.ts test/transcript.test.ts",
     "bench": "pnpm build && node scripts/bench-render.mjs",
     "set-version": "node scripts/set-version.mjs",
-    "verify-release": "node scripts/verify-release.mjs"
+    "verify-release": "node scripts/verify-release.mjs",
+    "retag-release": "node scripts/retag-release.mjs"
   }
 }

package/skills/frameyard/README.md

@@ -24,6 +24,10 @@ Run the CLI with `npx frameyard`. It resolves the latest published version; pin
 
 - `SKILL.md`: trigger description and operating workflow
 - `references/deterministic-authoring.md`
+- `references/bindings.md`
+- `references/controllers.md`
+- `references/diagnostics.md`
+- `references/common-mistakes.md`
 - `references/audio-assets.md`
 - `references/subtitles-karaoke.md`
 - `references/json-results.md`

package/skills/frameyard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: frameyard
-description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML, CSS, and native JavaScript. Use when a user asks to build or operate a Frameyard project, produce parameterized video, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
-frameyard-api-version: 0.3.0
+description: Create, validate, inspect, and render deterministic Frameyard videos authored with HTML, CSS, and an optional JavaScript controller. Use when a user asks to build or operate a Frameyard project, produce parameterized video, add a local TTS or transcription asset through Frameyard's wrappers, or diagnose a Frameyard render. Do not use for general-purpose media generation outside a Frameyard project.
+frameyard-api-version: 0.5.0
 ---
 
 # Frameyard
@@ -11,19 +11,19 @@ Use Frameyard's public project format and CLI. Do not introduce an agent-only ru
 ## First decisions
 
 1. Find the project: look for `video.config.js` from the working directory upward, or run `npx frameyard init <directory>` to scaffold one.
-2. Read the composition entry points listed in `video.config.js`. There is no directory scanning.
-3. Read the existing props file and composition source before changing behavior.
+2. Read the composition entry points listed in `video.config.js`. They are `.html` documents; there is no directory scanning.
+3. Read the composition HTML, its optional controller, and the props file before changing behavior.
 4. If the task needs speech or transcription, confirm that inference is requested or explicitly approved before producing assets.
 
 ## Workflow
 
-1. **Author** the composition with HTML, CSS, SVG, Canvas 2D, WebGL, embedded video, and native JavaScript ES modules. Keep `width`, `height`, `fps`, and `durationInFrames` fixed. Read [deterministic authoring](references/deterministic-authoring.md).
-2. **Provide props** as JSON. Validate domain-specific requirements with `validateProps()`.
+1. **Author** the composition as a full HTML document with one `<fy-composition>` root. Put metadata, default props, markup, CSS animation, bindings, audio, and transcripts in the document. Use an optional controller for Canvas 2D, WebGL, karaoke, or per-frame computation CSS cannot express. Read [deterministic authoring](references/deterministic-authoring.md), [bindings](references/bindings.md), and [controllers](references/controllers.md).
+2. **Provide props** as JSON. Validate domain-specific requirements with a controller's `validateProps()`.
 3. **Produce optional assets** with `npx frameyard tts` and `npx frameyard transcribe`, never with the upstream executables. Read [audio assets](references/audio-assets.md). Do not overwrite or regenerate existing generated assets without permission.
-4. **Validate** with `npx frameyard check <id> --json`. It evaluates every frame, checks audio and declared transcripts, and does not encode.
+4. **Validate** with `npx frameyard check <id> --json`. Static validation runs before Chromium; then every frame is evaluated. Read the structured `diagnostics` array. Read [diagnostics](references/diagnostics.md) and [common mistakes](references/common-mistakes.md).
 5. **Inspect** representative frames with `npx frameyard still <id> --frame <n> --out <file.png> --json`. View the PNGs when the host supports image viewing. If visual inspection is impossible, say so explicitly.
-6. **Render** with `npx frameyard render <id> --out <file.mp4> [--props <file>] [--concurrency <n>] --json`.
-7. **Report** the project path, composition entry, props, generated assets, provenance manifest, validation results, still paths and inspection status, final video path, and any failures.
+6. **Render** with `npx frameyard render <id> [--out <file.mp4>] [--props <file>] [--concurrency <n>] --json`. The default output is `out/<id>.mp4` in the project root.
+7. **Report** the project path, composition entry, controller, props, generated assets, provenance manifest, validation results, diagnostics, still paths and inspection status, final video path, and any failures.
 
 Never claim success when `check` fails, a still is missing, a render exits nonzero, or visual inspection was skipped. A partial or unpublished render is not a successful result.
 
@@ -32,24 +32,40 @@ Never claim success when `check` fails, a still is missing, a render exits nonze
 - Use `--json` for every non-interactive command. Parse stdout as the structured result; treat stderr as progress and diagnostics.
 - Keep the current output files unless the user explicitly approves replacement. Use `--force` only with that approval.
 - Use `--project <dir>` when not running from the project root.
+- `render` writes to `out/<id>.mp4` in the project root unless `--out` is passed. Explicit `--out` paths are relative to the current working directory.
 - Use `--concurrency <n>` only when faster local rendering is useful; the default is `1` and the maximum is `16`. It changes capture scheduling only, not composition behavior or output frame order.
 - Use `npx frameyard doctor --json` before reporting an environment problem. It inspects without repairing or downloading.
 - Read [JSON results](references/json-results.md) for result and error shapes, and [failure recovery](references/failure-recovery.md) for actionable error codes.
 
+## Authoring rules
+
+- A composition is a full HTML document with one `<fy-composition width height fps duration-in-frames>` root and a `data-fy="props"` default-props block.
+- Bindings are explicit: `data-fy-text`, `data-fy-attr-*`, `data-fy-class-*`, `data-fy-if`, and `data-fy-repeat` on `<template>`. Primitive top-level props are also `--fy-prop-<name>` CSS variables.
+- CSS `@keyframes` and the Web Animations API are seeked from the frame clock. `data-fy-anim-start`, `data-fy-anim-duration`, and `data-fy-anim-easing` schedule one animation per element in frames.
+- Frame-state variables on `:root`: `--fy-frame`, `--fy-time`, `--fy-progress`, `--fy-fps`, `--fy-duration`, and `--fy-duration-frames`.
+- A composition has exactly one optional controller, inline or external. It may export `mount`, `update`, `dispose`, and `validateProps`; at least one is required. Use inline for small controllers; extract to an external module for Canvas 2D, WebGL, karaoke, reuse, tests, or a large controller.
+- The controller is the only executable code. Other executable scripts and `on*` handlers are rejected.
+- Media and transcript `src` values resolve from the project root. The controller `src` and ordinary HTML asset URLs resolve relative to the composition document.
+- Embedded video/audio use `data-fy-start` (frames), `data-fy-trim` (seconds), optional `data-fy-duration` (seconds), and `data-fy-volume` (0-1). Transcripts use `<fy-transcript src words>`.
+
 ## Determinism guardrails
 
 - A frame may depend only on its integer `frame`, immutable `props`, and assets loaded before frame production.
 - Use `random("stable:key")` from `frameyard/runtime`; never use `Math.random()`.
 - Never use `Date.now()`, `performance.now()`, timers, independent `requestAnimationFrame` loops, or CSS transitions as animation inputs.
-- Finish remote data, fonts, and image loading during `mount()` or before the first frame. Network requests are blocked during frame capture.
+- Finish remote data, fonts, and image loading during the loading phase. Network requests are blocked during frame capture.
 - Keep `update({ frame, props })` synchronous and seek-safe. Do not carry state between frames.
-- Let the runtime seek embedded `<video>` elements. Do not play, pause, or set `currentTime` in `update()`; use the `data-frameyard-*` attributes described in [deterministic authoring](references/deterministic-authoring.md).
+- Let the runtime seek embedded `<video>` elements. Do not play, pause, or set `currentTime` in `update()`.
 - Redraw WebGL canvases from the current frame. Production pins software WebGL; do not depend on GPU-specific results or the previous frame's drawing buffer.
 - Do not run model inference inside `mount()`, `update()`, or frame production.
 
+## Diagnostics rule
+
+`check`, `still`, and `render` run static composition validation before Chromium. Errors fail before a browser starts; warnings allow frame evaluation. Every diagnostic has a stable `code`, a `message`, and optional `details` with source locations and suggestions. Treat warnings as actionable. Do not ignore `BINDING_PATH_MISSING`, `ANIMATION_NOT_FOUND`, `ANIMATION_MULTIPLE`, or `DETERMINISM_WARNING`.
+
 ## Subtitle and karaoke rule
 
-Use canonical transcripts produced by `npx frameyard transcribe`. Convert integer source-relative milliseconds to composition frames with the audio clip's `startFrame`, `trimStart`, and the composition `fps`. Karaoke highlighting requires actual `words` timings; never interpolate segment timings. Read [subtitles and karaoke](references/subtitles-karaoke.md).
+Use canonical transcripts produced by `npx frameyard transcribe`. Declare them with `<fy-transcript src="assets/voice.transcript.json" words>`. Convert integer source-relative milliseconds to composition frames with the audio clip's start frame, trim start, and the composition `fps`. Karaoke highlighting requires actual `words` timings; never interpolate segment timings. Read [subtitles and karaoke](references/subtitles-karaoke.md).
 
 ## CLI invocation
 
@@ -61,3 +77,15 @@ node scripts/frameyard.mjs check <id> --json   # fallback
 ```
 
 When the CLI version differs from `frameyard-api-version`, pin it with `npx frameyard@<version>`.
+
+## References
+
+- [Deterministic HTML authoring](references/deterministic-authoring.md)
+- [Bindings](references/bindings.md)
+- [Controllers](references/controllers.md)
+- [Diagnostics](references/diagnostics.md)
+- [Common mistakes](references/common-mistakes.md)
+- [Audio and generated assets](references/audio-assets.md)
+- [Subtitles and karaoke](references/subtitles-karaoke.md)
+- [JSON results](references/json-results.md)
+- [Failure recovery](references/failure-recovery.md)

package/skills/frameyard/references/audio-assets.md

@@ -1,25 +1,36 @@
 # Audio and generated assets
 
-Audio clips are a declarative timeline. Generated speech and transcripts are frozen local inputs produced before composition loading.
+Audio clips are a declarative `<audio>` timeline. Generated speech and transcripts are frozen local inputs produced before composition loading.
 
 ## Audio timeline
 
-```js
-audio: [
-  {
-    src: "assets/voice.wav", // project-relative local file
-    startFrame: 30,          // composition timeline position
-    trimStart: 0.25,         // seconds trimmed from the source
-    trimDuration: 4.2,       // optional seconds to use
-    volume: 0.8,             // 0..1
-  },
-];
+```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>
 ```
 
-- Placement is in composition frames.
-- Trimming is in seconds from the source.
+- `src` resolves from the project root.
+- `data-fy-start` is the composition timeline position in frames.
+- `data-fy-trim` is seconds trimmed from the source.
+- `data-fy-duration` optionally limits how many source seconds are used.
+- `data-fy-volume` is `0..1`.
 - Frameyard never time-stretches audio or changes composition duration to fit it.
-- `check` reports clip durations and overrun warnings.
+- `check` reports clip durations and overrun diagnostics.
+
+An unmuted `<video>` contributes its audio track to the same mix. Use `muted` or `data-fy-audio="off"` for a visual-only video.
+
+Declare required transcripts with:
+
+```html
+<fy-transcript src="assets/voice.transcript.json" words></fy-transcript>
+```
+
+`words` requires measured word timings. See [subtitles and karaoke](subtitles-karaoke.md).
 
 ## Local speech synthesis