frameyard 0.2.0 → 0.4.0

package/examples/demo/compositions/demo.controller.js

@@ -0,0 +1,120 @@
+import { random } from "frameyard/runtime";
+
+const STAR_COUNT = 130;
+const BAR_COUNT = 52;
+const BASELINE = 858;
+
+let context;
+let signalPath;
+let signalBars;
+let frameLabel;
+let stars;
+let bars = [];
+let signalLength = 0;
+
+function clamp(value) {
+  return Math.max(0, Math.min(1, value));
+}
+
+function easeOut(value) {
+  const t = clamp(value);
+  return 1 - Math.pow(1 - t, 3);
+}
+
+function makeStars() {
+  stars = Array.from({ length: STAR_COUNT }, (_, index) => ({
+    x: random("star:" + index + ":x"),
+    y: random("star:" + index + ":y"),
+    radius: 0.6 + random("star:" + index + ":r") * 1.8,
+    speed: 6 + random("star:" + index + ":speed") * 34,
+    alpha: 0.12 + random("star:" + index + ":alpha") * 0.65,
+  }));
+}
+
+function buildBars(root) {
+  signalBars = root.querySelector("#signal-bars");
+  bars = [];
+
+  for (let index = 0; index < BAR_COUNT; index += 1) {
+    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+    const height = 24 + random("bar:" + index + ":height") * 176;
+    const x = 168 + index * 31;
+    rect.setAttribute("x", String(x));
+    rect.setAttribute("width", "15");
+    rect.setAttribute("rx", "7.5");
+    rect.setAttribute("fill", "var(--fy-prop-accent)");
+    rect.setAttribute("height", "0");
+    rect.setAttribute("y", String(BASELINE));
+    rect.setAttribute("opacity", "0");
+    signalBars.append(rect);
+    bars.push({ element: rect, height });
+  }
+}
+
+function buildSignalPath(root) {
+  signalPath = root.querySelector("#signal-path");
+  const points = [];
+  for (let index = 0; index <= 120; index += 1) {
+    const x = 160 + (index / 120) * 1600;
+    const wave = Math.sin(index / 7) * 38 + Math.sin(index / 17 + 1.4) * 22 + (random("signal:" + index) - 0.5) * 12;
+    points.push([x, 535 + wave]);
+  }
+  const d = points.map(([x, y], index) => (index === 0 ? "M" : "L") + x + " " + y).join(" ");
+  signalPath.setAttribute("d", d);
+  signalLength = signalPath.getTotalLength();
+  signalPath.style.strokeDasharray = String(signalLength);
+  signalPath.style.strokeDashoffset = String(signalLength);
+}
+
+export default {
+  mount({ root }) {
+    context = root.querySelector("#field").getContext("2d");
+    frameLabel = root.querySelector("#frame");
+    makeStars();
+    buildBars(root);
+    buildSignalPath(root);
+  },
+
+  update({ frame }) {
+    const intro = easeOut(frame / 52);
+    const signalReveal = easeOut((frame - 96) / 260);
+    const width = context.canvas.width;
+    const height = context.canvas.height;
+
+    context.clearRect(0, 0, width, height);
+    for (const star of stars) {
+      const drift = (frame * star.speed) % width;
+      const x = (star.x * width + drift) % width;
+      const y = star.y * height;
+      context.beginPath();
+      context.fillStyle = "rgba(214, 236, 255, " + star.alpha * (0.45 + 0.55 * intro) + ")";
+      context.arc(x, y, star.radius, 0, Math.PI * 2);
+      context.fill();
+    }
+
+    signalPath.style.strokeDashoffset = String(signalLength * (1 - signalReveal));
+    signalPath.style.opacity = String(0.18 + signalReveal * 0.64);
+
+    const barReveal = clamp((frame - 120) / 240);
+    for (let index = 0; index < bars.length; index += 1) {
+      const bar = bars[index];
+      const local = clamp(barReveal * BAR_COUNT - index);
+      const height = bar.height * local;
+      bar.element.setAttribute("height", height.toFixed(2));
+      bar.element.setAttribute("y", String(BASELINE - height));
+      bar.element.setAttribute("opacity", (0.25 + local * 0.62).toFixed(3));
+    }
+
+    frameLabel.textContent = String(frame).padStart(3, "0");
+  },
+
+  dispose() {
+    context = undefined;
+    signalPath = undefined;
+    signalBars = undefined;
+    frameLabel = undefined;
+    stars = undefined;
+    bars = [];
+    signalLength = 0;
+  },
+};

package/examples/demo/compositions/demo.html

@@ -0,0 +1,253 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <script type="application/json" data-fy="props">
+      {
+        "title": "Frameyard",
+        "subtitle": "Deterministic video, authored with the web platform.",
+        "accent": "#b8f36b"
+      }
+    </script>
+    <style>
+      @keyframes orbit {
+        from {
+          transform: rotate(0deg) translateX(210px) rotate(0deg);
+        }
+        to {
+          transform: rotate(360deg) translateX(210px) rotate(-360deg);
+        }
+      }
+      @keyframes breathe {
+        0%,
+        100% {
+          opacity: 0.35;
+          transform: scale(1);
+        }
+        50% {
+          opacity: 0.7;
+          transform: scale(1.12);
+        }
+      }
+      @keyframes title-in {
+        from {
+          opacity: 0;
+          transform: translateY(46px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+      @keyframes subtitle-in {
+        from {
+          opacity: 0;
+          transform: translateY(26px);
+        }
+        to {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+      @keyframes scene-out {
+        from {
+          opacity: 1;
+        }
+        to {
+          opacity: 0;
+        }
+      }
+      html,
+      body,
+      fy-composition {
+        background: #080a0d;
+      }
+      #scene {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+        background: #080a0d;
+        color: #eef2f7;
+        font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+        animation: scene-out 1s linear both;
+      }
+      #field {
+        position: absolute;
+        inset: 0;
+        width: 100%;
+        height: 100%;
+      }
+      #orb {
+        position: absolute;
+        top: 46%;
+        left: 38%;
+        width: 460px;
+        height: 460px;
+        margin: -230px 0 0 -230px;
+        border-radius: 50%;
+        background: var(--fy-prop-accent);
+        filter: blur(110px);
+        opacity: 0.28;
+        animation: orbit 30s linear infinite;
+      }
+      #glow {
+        position: absolute;
+        top: 8%;
+        right: 6%;
+        width: 280px;
+        height: 280px;
+        border-radius: 50%;
+        background: var(--fy-prop-accent);
+        filter: blur(90px);
+        animation: breathe 9s ease-in-out infinite;
+      }
+      #rail {
+        position: absolute;
+        top: 92px;
+        left: 160px;
+        right: 160px;
+        height: 1px;
+        background: rgba(255, 255, 255, 0.14);
+      }
+      #eyebrow {
+        position: absolute;
+        top: 64px;
+        left: 160px;
+        font:
+          600 14px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.28em;
+        text-transform: uppercase;
+        color: var(--fy-prop-accent);
+      }
+      #meta {
+        position: absolute;
+        top: 64px;
+        right: 160px;
+        font:
+          500 14px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.12em;
+        color: #788595;
+      }
+      #copy {
+        position: absolute;
+        left: 160px;
+        top: 236px;
+        width: 1320px;
+      }
+      #title {
+        margin: 0;
+        font-size: 156px;
+        line-height: 0.92;
+        letter-spacing: -0.055em;
+        font-weight: 680;
+        opacity: 0;
+        animation: title-in 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #subtitle {
+        margin: 34px 0 0;
+        max-width: 820px;
+        font-size: 31px;
+        line-height: 1.45;
+        color: #96a2b2;
+        font-weight: 420;
+        opacity: 0;
+        animation: subtitle-in 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #signal {
+        position: absolute;
+        left: 0;
+        bottom: 0;
+        width: 1920px;
+        height: 1080px;
+        overflow: visible;
+      }
+      #caption {
+        position: absolute;
+        left: 160px;
+        bottom: 92px;
+        font:
+          500 13px/1 ui-monospace,
+          monospace;
+        letter-spacing: 0.16em;
+        color: #7e8b9b;
+      }
+      #caption strong {
+        color: var(--fy-prop-accent);
+        font-weight: 600;
+      }
+      #progress-track {
+        position: absolute;
+        left: 160px;
+        right: 160px;
+        bottom: 72px;
+        height: 2px;
+        background: rgba(255, 255, 255, 0.1);
+      }
+      #progress {
+        position: absolute;
+        inset: 0 auto 0 0;
+        width: calc(var(--fy-progress) * 100%);
+        background: var(--fy-prop-accent);
+        box-shadow: 0 0 18px var(--fy-prop-accent);
+      }
+      #vignette {
+        position: absolute;
+        inset: 0;
+        background: radial-gradient(ellipse at center, transparent 48%, rgba(0, 0, 0, 0.42) 100%);
+        pointer-events: none;
+      }
+    </style>
+  </head>
+  <body>
+    <fy-composition width="1920" height="1080" fps="30" duration-in-frames="900">
+      <div id="scene" data-fy-anim-start="824" data-fy-anim-duration="70" data-fy-anim-easing="linear">
+        <canvas id="field" width="1920" height="1080"></canvas>
+        <div id="orb"></div>
+        <div id="glow"></div>
+        <div id="vignette"></div>
+        <div id="rail"></div>
+        <div id="eyebrow">Frameyard / Field Notes</div>
+        <div id="meta">1920×1080 · 30 FPS · 30.00 S</div>
+        <div id="copy">
+          <h1
+            id="title"
+            data-fy-text="title"
+            data-fy-anim-start="0"
+            data-fy-anim-duration="52"
+            data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+          ></h1>
+          <p
+            id="subtitle"
+            data-fy-text="subtitle"
+            data-fy-anim-start="26"
+            data-fy-anim-duration="62"
+            data-fy-anim-easing="cubic-bezier(0.215, 0.61, 0.355, 1)"
+          ></p>
+        </div>
+        <svg id="signal" viewBox="0 0 1920 1080" fill="none" aria-hidden="true">
+          <path
+            id="signal-path"
+            stroke="var(--fy-prop-accent)"
+            stroke-width="3"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            opacity=".82"
+          ></path>
+          <g id="signal-bars"></g>
+        </svg>
+        <div id="caption">FRAME <strong id="frame">000</strong> / 899 · SEEK-SAFE CANVAS + SVG + CSS</div>
+        <div id="progress-track"><div id="progress"></div></div>
+      </div>
+
+      <audio src="assets/chime.wav" data-fy-start="18" data-fy-volume="0.5"></audio>
+      <audio src="assets/chime.wav" data-fy-start="300" data-fy-volume="0.38"></audio>
+      <audio src="assets/chime.wav" data-fy-start="600" data-fy-volume="0.42"></audio>
+      <audio src="assets/chime.wav" data-fy-start="840" data-fy-volume="0.55"></audio>
+    </fy-composition>
+
+    <script type="text/fy-controller" src="./demo.controller.js"></script>
+  </body>
+</html>

package/examples/demo/video.config.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameyard",
-  "version": "0.2.0",
+  "version": "0.4.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,12 +66,17 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.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": "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/scaffold.test.ts test/transcript.test.ts",
+    "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"
+    "set-version": "node scripts/set-version.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.2.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.4.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, 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>] --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`.
+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,21 +32,39 @@ 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.
+- 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()`.
+- 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
 
@@ -58,3 +76,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
 

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.