frameyard 0.3.0 → 0.5.0

package/dist/scaffold.js

@@ -5,22 +5,101 @@ This project produces deterministic, parameterized video with Frameyard. Follow
 
 ## Project layout
 
-- \`video.config.js\` explicitly maps composition IDs to entry modules. There is no directory scanning; a new composition is invisible until it is listed.
-- \`package.json\` pins the CLI version in \`dev\`, \`check\`, \`render\`, and \`still\` scripts. Run \`dev\` with \`npm run dev\` or \`pnpm dev\`; for the others, pass the composition id: \`npm run check -- hello\` (npm) or \`pnpm check hello\` (pnpm).
-- \`compositions/\` contains native JavaScript ES modules. Import bare \`frameyard\` and \`frameyard/runtime\`; the preview server supplies the import map.
-- \`props/\` contains JSON props, merged shallowly over \`defaultProps\` and deep-frozen.
+- \`video.config.js\` explicitly maps composition IDs to \`.html\` composition documents. There is no directory scanning; a new composition is invisible until it is listed.
+- \`compositions/\` contains HTML/CSS compositions. An optional controller lives beside the document as a \`.controller.js\` module; import \`frameyard/runtime\` for \`random("stable:key")\` and other browser APIs.
+- \`props/\` contains JSON props, merged shallowly over the composition's \`data-fy="props"\` defaults and deep-frozen.
+- \`out/\` contains rendered MP4s and is gitignored. \`render\` writes \`out/<composition-id>.mp4\` by default.
 - \`assets/\` (create it when needed) contains audio, images, fonts, and generated assets.
+- \`package.json\` pins the CLI version in \`dev\`, \`check\`, \`render\`, and \`still\` scripts. Run \`dev\` with \`npm run dev\` or \`pnpm dev\`; for the others, pass the composition id: \`npm run check -- hello\` (npm) or \`pnpm check hello\` (pnpm).
+
+\`width\`, \`height\`, \`fps\`, and \`duration-in-frames\` are fixed on \`<fy-composition>\`. Do not derive them from props.
+
+## Composition skeleton
+
+\`\`\`html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script type="application/json" data-fy="props">{ "title": "Hello" }</script>
+  </head>
+  <body>
+    <fy-composition width="1280" height="720" fps="30" duration-in-frames="150">
+      <h1 data-fy-text="title"></h1>
+    </fy-composition>
+  </body>
+</html>
+\`\`\`
+
+## Bindings
+
+- \`data-fy-text="path"\` sets text content.
+- \`data-fy-attr-src="path"\` (and other \`data-fy-attr-*\` names) sets an attribute.
+- \`data-fy-class-active="path"\` toggles a class.
+- \`data-fy-if="path"\` removes the element when the value is false.
+- \`<template data-fy-repeat="items">\` clones its content for each item; use \`item\` and \`index\`, and style stagger with \`--fy-index\`.
+- Paths are dot-separated (\`user.name\`, \`items.0.label\`). Missing paths warn and resolve to an empty value.
+- Primitive top-level props are also available as \`--fy-prop-<name>\` CSS custom properties.
+
+## Animation
+
+- CSS \`@keyframes\` and Web Animations API animations are paused and seeked from the frame clock.
+- \`data-fy-anim-start\`, \`data-fy-anim-duration\`, and \`data-fy-anim-easing\` schedule one animation per element in composition frames. The CSS \`animation\` shorthand supplies keyframes and fill mode.
+- Frame-state variables are set on \`:root\`: \`--fy-frame\`, \`--fy-time\`, \`--fy-progress\`, \`--fy-fps\`, \`--fy-duration\`, and \`--fy-duration-frames\`.
+- Use \`--fy-progress\` for progress bars and \`--fy-frame\`/\`--fy-time\` in \`calc()\` for simple computed motion.
+- CSS transitions are not deterministic; do not use them.
+
+## Controller
 
-\`width\`, \`height\`, \`fps\`, and \`durationInFrames\` are fixed composition metadata. Do not derive them from props.
+Exactly one optional controller is allowed, inline or external:
+
+\`\`\`html
+<script type="text/fy-controller">
+export default {
+  mount({ root, props }) {},
+  update({ frame, props, root }) {},
+};
+</script>
+\`\`\`
+
+\`\`\`html
+<script type="text/fy-controller" src="./hello.controller.js"></script>
+\`\`\`
+
+- \`mount\` may be asynchronous; \`update\` and \`validateProps\` are synchronous and seek-safe; \`dispose\` releases resources.
+- Use inline for small, single-use controllers; extract to an external module for Canvas 2D, WebGL, karaoke, reuse, tests, or a large controller.
+- A controller may be validation-only and export just \`validateProps(props)\`.
+- The controller is the only executable code. Other scripts and \`on*\` handlers are rejected.
+- Controller-created DOM is not re-bound; declarative bindings apply once before \`mount\`.
+
+## Determinism rules
+
+- A frame may depend only on its integer \`frame\`, immutable \`props\`, and assets loaded before frame production.
+- Never use \`Math.random()\`, \`Date.now()\`, \`performance.now()\`, timers, independent \`requestAnimationFrame()\` loops, CSS transitions, or state left from a previously visited frame as animation inputs.
+- Use \`random("stable:key")\` from \`frameyard/runtime\` for randomness.
+- Load remote data, fonts, and images before frame production. Network requests are blocked during capture; a \`fetch()\` from \`update()\` is a bug.
+- Redraw Canvas 2D and WebGL from the current frame. Production pins software WebGL for reproducible pixels.
+- Embedded video and audio use local project files and \`data-fy-start\` (frames), \`data-fy-trim\` (seconds), optional \`data-fy-duration\` (seconds), and \`data-fy-volume\` (0-1). Let the runtime seek video; do not call \`play()\`, \`pause()\`, or set \`currentTime\` in \`update()\`.
+- Media and transcript \`src\` values resolve from the project root. The controller \`src\` and ordinary HTML asset URLs resolve relative to the composition document.
+
+## Audio and transcripts
+
+- Audio clips are \`<audio>\` elements placed by composition frames and trimmed by seconds. Frameyard does not time-stretch audio or change composition duration to fit it.
+- An unmuted embedded 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 \`<fy-transcript src="assets/voice.transcript.json" words></fy-transcript>\`.
+- Produce speech with \`npx frameyard tts\` and transcripts with \`npx frameyard transcribe\`; never call \`qwen-tts\` or \`whisper-cli\` directly, and never run inference inside a controller.
+- Do not overwrite or regenerate generated assets without explicit approval.
+- \`words\` requires measured word timings; never interpolate segment timings.
+- Commit \`frameyard.assets.json\` when present; do not edit hashes or manifest entries by hand.
 
 ## Agent workflow
 
-1. Read \`video.config.js\`, the composition source, and the props file before changing behavior.
-2. Author the composition or props with native HTML, CSS, SVG, Canvas 2D, WebGL, embedded video, and JavaScript. Do not add a bundling step.
-3. Validate every frame: \`npx frameyard check <id> --json\`. Use \`--props <file>\` to validate a specific props file.
+1. Read \`video.config.js\`, the composition HTML, the optional controller, and the props file before changing behavior.
+2. Author the composition with native HTML, CSS, SVG, Canvas 2D, WebGL, embedded video, and an optional controller. Do not add a bundling step.
+3. Validate every frame: \`npx frameyard check <id> --json\`. Static validation runs before Chromium and reports stable diagnostic codes with source locations. Use \`--props <file>\` to validate a specific props file.
 4. Inspect a representative frame: \`npx frameyard still <id> --frame <n> --out <file.png> --json\`, then view the PNG when the host supports images. State explicitly when visual inspection is not possible.
-5. Render: \`npx frameyard render <id> --props <file> --out <file.mp4> [--concurrency <n>] --json\`.
-6. Report the composition, props, validation result, still path and inspection status, video path, and any failure. Never claim success when \`check\` fails, a still is missing, or a render exits nonzero.
+5. Render: \`npx frameyard render <id> --props <file> [--concurrency <n>] --json\`. The video is written to \`out/<id>.mp4\` unless \`--out\` is passed.
+6. Report the composition, controller, props, validation result, diagnostics, still path and inspection status, video path, and any failure. Never claim success when \`check\` fails, a still is missing, or a render exits nonzero.
 
 ## Commands
 
@@ -29,35 +108,15 @@ npx frameyard dev
 npx frameyard doctor --json
 npx frameyard check hello --json
 npx frameyard still hello --frame 42 --out hello-42.png --json
-npx frameyard render hello --props props/hello.json --out hello.mp4 --json
+npx frameyard render hello --props props/hello.json --json
 \`\`\`
 
 - Use \`--json\` for non-interactive commands. Parse stdout as the structured result; treat stderr as progress and diagnostics.
 - Use \`--project <dir>\` when running outside the project root.
+- \`render\` writes to \`out/<id>.mp4\` in the project unless \`--out\` is passed. \`out/\` is gitignored.
 - Use \`--concurrency <n>\` for faster local rendering when useful; the default is \`1\` and the maximum is \`16\`. It changes capture scheduling only, not composition behavior or output frame order.
 - \`still\` and \`render\` replace existing outputs only with \`--overwrite\`. Generated assets are replaced only with \`--force\`, and only with user approval.
 
-## Determinism rules
-
-- A frame may depend only on its integer \`frame\`, immutable \`props\`, and assets loaded before frame production.
-- \`mount()\` may await loading work. \`update({ frame, props })\` is synchronous and seek-safe. \`dispose()\` releases resources.
-- Keep mutable state in module-scope variables, not on \`this\`.
-- Use \`random("stable:key")\` from \`frameyard/runtime\` for randomness.
-- Never use \`Math.random()\`, \`Date.now()\`, \`performance.now()\`, timers, independent \`requestAnimationFrame()\` loops, CSS transitions, or state left from a previously visited frame as animation inputs.
-- CSS \`@keyframes\` and the Web Animations API are valid; the runtime seeks them.
-- Load remote data, fonts, and images during \`mount()\` or before the first frame. Network requests are blocked during capture; a \`fetch()\` from \`update()\` is a bug.
-- Redraw Canvas 2D and WebGL from the current frame. Production pins software WebGL for reproducible pixels.
-- Embedded video must use a local project file in the composition container's light DOM and be created, with its \`data-frameyard-*\` attributes, in \`mount()\`. Let the runtime seek it; do not call \`play()\`, \`pause()\`, or set \`currentTime\` in \`update()\`. Use \`data-frameyard-start\` (frames), \`data-frameyard-trim\` (seconds), optional \`data-frameyard-duration\` (seconds), and optional \`data-frameyard-volume\` (0-1).
-
-## Audio and transcripts
-
-- Audio clips are placed by composition frames and trimmed by seconds. Frameyard does not time-stretch audio or change composition duration to fit it.
-- An unmuted embedded video contributes its audio track to the same mix; use \`muted\` or \`data-frameyard-audio="off"\` for a visual-only video.
-- Produce speech with \`npx frameyard tts\` and transcripts with \`npx frameyard transcribe\`; never call \`qwen-tts\` or \`whisper-cli\` directly, and never run inference inside \`mount()\` or \`update()\`.
-- Do not overwrite or regenerate generated assets without explicit approval.
-- \`words: true\` requires measured word timings; never interpolate segment timings.
-- Commit \`frameyard.assets.json\` when present; do not edit hashes or manifest entries by hand.
-
 The official \`frameyard\` agent skill contains the full host-neutral contract. Install it with \`npx skills add vladiantio/frameyard\` or see the \`skills/frameyard/\` directory in the \`frameyard\` npm package. This file is the project-local summary.
 
 This project was scaffolded with frameyard ${VERSION}. \`npx frameyard\` resolves the latest published version; run \`npx frameyard@${VERSION}\` when you need the CLI version that scaffolded the project.
@@ -66,6 +125,8 @@ const PROJECT_README = `# My Frameyard project
 
 Coding agents should read \`AGENTS.md\` for the project rules and the check, still, and render workflow.
 
+The composition is a plain HTML document at \`compositions/hello.html\`. Its metadata, default props, markup, CSS animation, and bindings live in that one file.
+
 Start the preview:
 
 \`\`\`sh
@@ -77,71 +138,103 @@ Validate and render:
 \`\`\`sh
 npx frameyard doctor
 npx frameyard check hello
-npx frameyard render hello --props props/hello.json --out hello.mp4
+npx frameyard render hello --props props/hello.json
 \`\`\`
 
+The video is written to \`out/hello.mp4\` in the project. Pass \`--out <file.mp4>\` to choose another path.
+
 Or run the pinned scripts from \`package.json\`:
 
 \`\`\`sh
 npm run dev
 npm run check -- hello
-npm run render -- hello --props props/hello.json --out hello.mp4
+npm run render -- hello --props props/hello.json
 npm run still -- hello --frame 42 --out hello-42.png
 \`\`\`
 `;
 const SCAFFOLD_TEMPLATES = {
-    "video.config.js": `export default {\n  compositions: {\n    hello: "./compositions/hello.js",\n  },\n};\n`,
+    ".gitignore": "out/\n",
+    "video.config.js": `export default {\n  compositions: {\n    hello: "./compositions/hello.html",\n  },\n};\n`,
     "props/hello.json": `${JSON.stringify({ title: "Hello, Frameyard", accent: "#b8f36b" }, null, 2)}\n`,
     "AGENTS.md": AGENTS_GUIDE,
     "README.md": PROJECT_README,
-    "compositions/hello.js": `import { defineComposition } from "frameyard";
-
-let title;
-let sweep;
-let glow;
-
-export default defineComposition({
-  width: 1280,
-  height: 720,
-  fps: 30,
-  durationInFrames: 150,
-  defaultProps: { title: "Hello, Frameyard", accent: "#b8f36b" },
-  validateProps(props) {
-    const errors = [];
-    if (typeof props.title !== "string") errors.push("title must be a string");
-    if (typeof props.accent !== "string") errors.push("accent must be a string");
-    return errors;
-  },
-  mount({ container, props }) {
-    container.style.setProperty("--accent", props.accent);
-    container.innerHTML =
-      '<style>' +
-      '#hello { position: relative; width: 100%; height: 100%; display: grid; place-items: center; overflow: hidden; background: #0b0d10; color: #e8edf3; font-family: Inter, system-ui, sans-serif; }' +
-      '#hello h1 { position: relative; margin: 0; font-size: 96px; letter-spacing: -0.04em; }' +
-      '#hello p { position: relative; margin: 18px 0 0; color: #8a97a6; font-size: 26px; }' +
-      '#glow { position: absolute; width: 520px; height: 520px; border-radius: 50%; background: var(--accent); filter: blur(120px); opacity: 0.16; }' +
-      '#sweep { position: absolute; left: 0; bottom: 0; width: 0%; height: 4px; background: var(--accent); }' +
-      '</style>' +
-      '<div id="hello"><div id="glow"></div><div style="position: relative; text-align: center"><h1 id="title"></h1><p>Deterministic video, authored on the web.</p></div><div id="sweep"></div></div>';
-    title = container.querySelector("#title");
-    sweep = container.querySelector("#sweep");
-    glow = container.querySelector("#glow");
-  },
-  update({ frame, props }) {
-    title.textContent = props.title;
-    const intro = Math.min(1, frame / 24);
-    title.style.opacity = String(intro);
-    title.style.transform = "translateY(" + (1 - intro) * 28 + "px)";
-    glow.style.transform =
-      "translate(" + Math.sin(frame / 26) * 120 + "px," + Math.cos(frame / 34) * 80 + "px)";
-    sweep.style.width = (frame / 149) * 100 + "%";
-  },
-  dispose() {
-    title = undefined;
-    sweep = undefined;
-    glow = undefined;
-  },
-});
+    "compositions/hello.html": `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <script type="application/json" data-fy="props">
+    { "title": "Hello, Frameyard", "accent": "#b8f36b" }
+    </script>
+    <style>
+      @keyframes fade-up {
+        from { opacity: 0; transform: translateY(28px); }
+        to { opacity: 1; transform: translateY(0); }
+      }
+      @keyframes drift {
+        from { transform: translate(-120px, -80px); }
+        to { transform: translate(120px, 80px); }
+      }
+      #hello {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        display: grid;
+        place-items: center;
+        overflow: hidden;
+        background: #0b0d10;
+        color: #e8edf3;
+        font-family: Inter, system-ui, sans-serif;
+      }
+      #hello h1 {
+        position: relative;
+        margin: 0;
+        font-size: 96px;
+        letter-spacing: -0.04em;
+        opacity: 0;
+        animation: fade-up 1s cubic-bezier(0.215, 0.61, 0.355, 1) both;
+      }
+      #hello p {
+        position: relative;
+        margin: 18px 0 0;
+        color: #8a97a6;
+        font-size: 26px;
+      }
+      #glow {
+        position: absolute;
+        left: 50%;
+        top: 50%;
+        width: 520px;
+        height: 520px;
+        margin: -260px 0 0 -260px;
+        border-radius: 50%;
+        background: var(--fy-prop-accent);
+        filter: blur(120px);
+        opacity: 0.16;
+        animation: drift 12s ease-in-out infinite alternate;
+      }
+      #sweep {
+        position: absolute;
+        left: 0;
+        bottom: 0;
+        width: calc(var(--fy-progress) * 100%);
+        height: 4px;
+        background: var(--fy-prop-accent);
+      }
+    </style>
+  </head>
+  <body>
+    <fy-composition width="1280" height="720" fps="30" duration-in-frames="150">
+      <div id="hello">
+        <div id="glow"></div>
+        <div style="position: relative; text-align: center">
+          <h1 id="title" data-fy-text="title" data-fy-anim-start="0" data-fy-anim-duration="24"></h1>
+          <p>Deterministic video, authored on the web.</p>
+        </div>
+        <div id="sweep"></div>
+      </div>
+    </fy-composition>
+  </body>
+</html>
 `,
 };
 // Keep the generated package name valid for npm and pnpm.
@@ -174,6 +267,6 @@ export const SCAFFOLD_NEXT = [
     "npx frameyard doctor",
     "npx frameyard dev",
     "npx frameyard check hello",
-    "npx frameyard render hello --out hello.mp4",
+    "npx frameyard render hello",
 ];
 //# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CA6DwB,OAAO,kFAAkF,OAAO;CAC5I,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BtB,CAAC;AAEF,MAAM,kBAAkB,GAA2B;IACjD,iBAAiB,EAAE,wFAAwF;IAC3G,kBAAkB,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;IACpG,WAAW,EAAE,YAAY;IACzB,WAAW,EAAE,cAAc;IAC3B,uBAAuB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgD1B;CACA,CAAC;AAEF,0DAA0D;AAC1D,SAAS,WAAW,CAAC,WAAmB;IACtC,MAAM,UAAU,GAAG,WAAW;SAC3B,WAAW,EAAE;SACb,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;SACb,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,CAAC,SAAS,CAC/B;YACE,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;YAC9B,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE;gBACP,GAAG,EAAE,uBAAuB,OAAO,MAAM;gBACzC,KAAK,EAAE,uBAAuB,OAAO,QAAQ;gBAC7C,MAAM,EAAE,uBAAuB,OAAO,SAAS;gBAC/C,KAAK,EAAE,uBAAuB,OAAO,QAAQ;aAC9C;SACF,EACD,IAAI,EACJ,CAAC,CACF,IAAI;QACL,GAAG,kBAAkB;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,sBAAsB;IACtB,mBAAmB;IACnB,2BAA2B;IAC3B,4CAA4C;CAC7C,CAAC"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CAwHwB,OAAO,kFAAkF,OAAO;CAC5I,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BtB,CAAC;AAEF,MAAM,kBAAkB,GAA2B;IACjD,YAAY,EAAE,QAAQ;IACtB,iBAAiB,EAAE,0FAA0F;IAC7G,kBAAkB,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;IACpG,WAAW,EAAE,YAAY;IACzB,WAAW,EAAE,cAAc;IAC3B,yBAAyB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6E5B;CACA,CAAC;AAEF,0DAA0D;AAC1D,SAAS,WAAW,CAAC,WAAmB;IACtC,MAAM,UAAU,GAAG,WAAW;SAC3B,WAAW,EAAE;SACb,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;SACb,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO;QACL,cAAc,EAAE,GAAG,IAAI,CAAC,SAAS,CAC/B;YACE,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;YAC9B,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE;gBACP,GAAG,EAAE,uBAAuB,OAAO,MAAM;gBACzC,KAAK,EAAE,uBAAuB,OAAO,QAAQ;gBAC7C,MAAM,EAAE,uBAAuB,OAAO,SAAS;gBAC/C,KAAK,EAAE,uBAAuB,OAAO,QAAQ;aAC9C;SACF,EACD,IAAI,EACJ,CAAC,CACF,IAAI;QACL,GAAG,kBAAkB;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,sBAAsB;IACtB,mBAAmB;IACnB,2BAA2B;IAC3B,4BAA4B;CAC7B,CAAC"}

package/dist/server/composition-html.d.ts

@@ -0,0 +1,20 @@
+export declare const FRAMEWORK_IMPORT_MAP: {
+    readonly frameyard: "/__frameyard/framework/index.js";
+    readonly "frameyard/runtime": "/__frameyard/framework/runtime/index.js";
+};
+export declare const COMPOSITION_HOST_SCRIPT_URL = "/__frameyard/framework/runtime/host.js";
+export declare const COMPOSITION_HOST_STYLE = "html, body { margin: 0; width: 100%; height: 100%; } fy-composition { display: block; width: 100%; height: 100%; } fy-composition[data-fy-pending] { visibility: hidden !important; }";
+export interface CompositionHostInjectionOptions {
+    html: string;
+    importMap?: Record<string, string>;
+    hostScriptUrl?: string;
+    styleText?: string;
+}
+/**
+ * Injects the framework import map, sizing style, and composition host into a
+ * composition document. The host script is a deferred module, so it runs after
+ * the document is parsed; author executable scripts are rejected by static
+ * validation before this function is called.
+ */
+export declare function injectCompositionHost(options: CompositionHostInjectionOptions): string;
+//# sourceMappingURL=composition-html.d.ts.map

package/dist/server/composition-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-html.d.ts","sourceRoot":"","sources":["../../src/server/composition-html.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB;;;CAGvB,CAAC;AAEX,eAAO,MAAM,2BAA2B,2CAA2C,CAAC;AAEpF,eAAO,MAAM,sBAAsB,0LACsJ,CAAC;AAE1L,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,+BAA+B,GAAG,MAAM,CA4BtF"}

package/dist/server/composition-html.js

@@ -0,0 +1,45 @@
+import { defaultTreeAdapter, html, parse, serialize } from "parse5";
+import { getElementByTagName } from "../html/parse.js";
+export const FRAMEWORK_IMPORT_MAP = {
+    frameyard: "/__frameyard/framework/index.js",
+    "frameyard/runtime": "/__frameyard/framework/runtime/index.js",
+};
+export const COMPOSITION_HOST_SCRIPT_URL = "/__frameyard/framework/runtime/host.js";
+export const COMPOSITION_HOST_STYLE = "html, body { margin: 0; width: 100%; height: 100%; } fy-composition { display: block; width: 100%; height: 100%; } fy-composition[data-fy-pending] { visibility: hidden !important; }";
+/**
+ * Injects the framework import map, sizing style, and composition host into a
+ * composition document. The host script is a deferred module, so it runs after
+ * the document is parsed; author executable scripts are rejected by static
+ * validation before this function is called.
+ */
+export function injectCompositionHost(options) {
+    const document = parse(options.html);
+    const head = getElementByTagName(document, "head");
+    if (!head) {
+        throw new Error("Composition document has no <head> element.");
+    }
+    const importMap = createElement("script", [
+        { name: "type", value: "importmap" },
+        { name: "data-fy-host", value: "" },
+    ]);
+    appendText(importMap, JSON.stringify({ imports: options.importMap ?? FRAMEWORK_IMPORT_MAP }));
+    const style = createElement("style", [{ name: "data-fy-host-style", value: "" }]);
+    appendText(style, options.styleText ?? COMPOSITION_HOST_STYLE);
+    const host = createElement("script", [
+        { name: "type", value: "module" },
+        { name: "src", value: options.hostScriptUrl ?? COMPOSITION_HOST_SCRIPT_URL },
+        { name: "data-fy-host", value: "" },
+    ]);
+    head.childNodes.unshift(importMap, style, host);
+    for (const child of [importMap, style, host]) {
+        child.parentNode = head;
+    }
+    return serialize(document);
+}
+function createElement(tagName, attrs) {
+    return defaultTreeAdapter.createElement(tagName, html.NS.HTML, attrs);
+}
+function appendText(element, value) {
+    defaultTreeAdapter.appendChild(element, defaultTreeAdapter.createTextNode(value));
+}
+//# sourceMappingURL=composition-html.js.map

package/dist/server/composition-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-html.js","sourceRoot":"","sources":["../../src/server/composition-html.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAoB,MAAM,kBAAkB,CAAC;AAEzE,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS,EAAE,iCAAiC;IAC5C,mBAAmB,EAAE,yCAAyC;CACtD,CAAC;AAEX,MAAM,CAAC,MAAM,2BAA2B,GAAG,wCAAwC,CAAC;AAEpF,MAAM,CAAC,MAAM,sBAAsB,GACjC,uLAAuL,CAAC;AAS1L;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAwC;IAC5E,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,QAAQ,EAAE;QACxC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE;QACpC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE;KACpC,CAAC,CAAC;IACH,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,SAAS,IAAI,oBAAoB,EAAE,CAAC,CAAC,CAAC;IAE9F,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,IAAI,sBAAsB,CAAC,CAAC;IAE/D,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE;QACnC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE;QACjC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,IAAI,2BAA2B,EAAE;QAC5E,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE;KACpC,CAAC,CAAC;IAEH,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAChD,KAAK,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;QAC7C,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,aAAa,CAAC,OAAe,EAAE,KAA6C;IACnF,OAAO,kBAAkB,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,UAAU,CAAC,OAAoB,EAAE,KAAa;IACrD,kBAAkB,CAAC,WAAW,CAAC,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AACpF,CAAC"}

package/dist/server/preview-html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview-html.d.ts","sourceRoot":"","sources":["../../src/server/preview-html.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,IAAI,MAAM,CA6N1C"}
+{"version":3,"file":"preview-html.d.ts","sourceRoot":"","sources":["../../src/server/preview-html.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,IAAI,MAAM,CAkO1C"}

package/dist/server/preview-html.js

@@ -148,7 +148,21 @@ export function renderPreviewHtml() {
       repeating-conic-gradient(#0d1014 0% 25%, #0b0d10 0% 50%) 50% / 24px 24px;
   }
   .stage-wrap { position: relative; flex: 0 0 auto; }
-  .stage { transform-origin: top left; overflow: hidden; background: #000; }
+  .stage-frame { position: absolute; top: 0; left: 0; border: 0; transform-origin: top left; background: #000; }
+  .diagnostics {
+    border: 1px solid var(--line);
+    background: var(--panel-2);
+    border-radius: 7px;
+    padding: 8px 10px;
+    max-height: 26vh;
+    overflow: auto;
+    font-family: var(--mono);
+    font-size: 11px;
+    line-height: 1.5;
+  }
+  .diagnostics .diagnostic { display: block; white-space: pre-wrap; }
+  .diagnostics .warning { color: #e8c76a; }
+  .diagnostics .error { color: var(--danger); }
   .transport {
     grid-row: 3;
     grid-column: 2;
@@ -170,18 +184,6 @@ export function renderPreviewHtml() {
   .audio { display: flex; align-items: center; gap: 7px; color: var(--muted); font-family: var(--mono); font-size: 11px; }
   .audio input[type="range"] { width: 72px; accent-color: var(--accent); }
 
-  body.render #app { display: block; height: auto; }
-  body.render .topbar, body.render .panel, body.render .transport { display: none; }
-  body.render .viewport {
-    position: fixed;
-    inset: 0;
-    display: block;
-    padding: 0;
-    overflow: hidden;
-    background: #000;
-  }
-  body.render .stage-wrap { position: absolute; inset: 0; width: auto !important; height: auto !important; }
-  body.render .stage { transform: none !important; }
 </style>
 </head>
 <body>
@@ -201,13 +203,16 @@ export function renderPreviewHtml() {
     </div>
     <button id="apply" class="primary" type="button">Apply props</button>
     <div id="error" class="error" role="alert" hidden></div>
+    <div id="diagnostics" class="diagnostics" hidden></div>
     <div class="hint">
       Frames are derived from <code>frame</code> and <code>props</code> only.
       Wall-clock animation and unseeded randomness are not deterministic.
     </div>
   </aside>
   <main id="viewport" class="viewport">
-    <div id="stage-wrap" class="stage-wrap"><div id="stage" class="stage"></div></div>
+    <div id="stage-wrap" class="stage-wrap">
+      <iframe id="stage-frame" class="stage-frame" title="Composition" hidden></iframe>
+    </div>
   </main>
   <footer class="transport">
     <button id="play" class="play" type="button" aria-label="Play">&#9654;</button>

package/dist/server/preview-html.js.map

@@ -1 +1 @@
-{"version":3,"file":"preview-html.js","sourceRoot":"","sources":["../../src/server/preview-html.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAC/B;IACE,OAAO,EAAE;QACP,SAAS,EAAE,iCAAiC;QAC5C,mBAAmB,EAAE,yCAAyC;KAC/D;CACF,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AAEF,MAAM,UAAU,iBAAiB;IAC/B,OAAO;;;;;;2BAMkB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAqN7B,CAAC;AACT,CAAC"}
+{"version":3,"file":"preview-html.js","sourceRoot":"","sources":["../../src/server/preview-html.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAC/B;IACE,OAAO,EAAE;QACP,SAAS,EAAE,iCAAiC;QAC5C,mBAAmB,EAAE,yCAAyC;KAC/D;CACF,EACD,IAAI,EACJ,CAAC,CACF,CAAC;AAEF,MAAM,UAAU,iBAAiB;IAC/B,OAAO;;;;;;2BAMkB,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA0N7B,CAAC;AACT,CAAC"}

package/dist/server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAMA,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAG1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA+JD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmG9F"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAQA,OAAO,EAAe,KAAK,OAAO,EAA2B,MAAM,eAAe,CAAC;AAInF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAyOD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC,CA+H9F"}

package/dist/server/server.js

@@ -1,10 +1,12 @@
 import { createReadStream } from "node:fs";
-import { stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { createServer } from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { FrameyardError } from "../errors.js";
+import { validateHtmlComposition } from "../html/validate.js";
 import { loadProject } from "../project.js";
+import { injectCompositionHost } from "./composition-html.js";
 import { renderPreviewHtml } from "./preview-html.js";
 const MIME_TYPES = {
     ".avif": "image/avif",
@@ -144,14 +146,76 @@ async function serveFile(request, response, base, relativePath) {
         .on("error", () => response.destroy())
         .pipe(response);
 }
+function sendHtml(response, status, body, headOnly = false) {
+    response.writeHead(status, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Length": Buffer.byteLength(body),
+        "Cache-Control": "no-store",
+    });
+    response.end(headOnly ? undefined : body);
+}
+function sendJavaScript(response, status, body, headOnly = false) {
+    response.writeHead(status, {
+        "Content-Type": "text/javascript; charset=utf-8",
+        "Content-Length": Buffer.byteLength(body),
+        "Cache-Control": "no-store",
+    });
+    response.end(headOnly ? undefined : body);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        switch (character) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            default:
+                return "&#39;";
+        }
+    });
+}
+function renderCompositionError(entry, diagnostics) {
+    const items = diagnostics
+        .map((diagnostic) => {
+        const location = diagnostic.details?.line ? ` at line ${diagnostic.details.line}` : "";
+        return `<li><code>${escapeHtml(diagnostic.code)}</code> ${escapeHtml(diagnostic.message)}${escapeHtml(location)}</li>`;
+    })
+        .join("");
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Frameyard composition error</title></head><body><h1>Composition error</h1><p>${escapeHtml(entry)}</p><ul>${items}</ul></body></html>`;
+}
+function publicController(controller) {
+    if (!controller) {
+        return null;
+    }
+    return controller.kind === "inline" ? { kind: "inline" } : { kind: "external", src: controller.src ?? "" };
+}
+async function buildProjectJson(project) {
+    const compositions = [];
+    for (const composition of project.compositions.values()) {
+        const result = await validateHtmlComposition({ projectRoot: project.root, entry: composition.entry });
+        compositions.push({
+            id: composition.id,
+            entry: composition.entry,
+            kind: "html",
+            metadata: result.info?.metadata ?? null,
+            controller: publicController(result.info?.controller ?? null),
+            diagnostics: result.diagnostics,
+        });
+    }
+    return { compositions };
+}
+function findCompositionForPath(project, pathname) {
+    return [...project.compositions.values()].find((composition) => `/${composition.entry}` === pathname);
+}
 export async function startPreviewServer(options) {
     const project = await loadProject(options.projectRoot);
     const frameworkDir = options.frameworkDir ?? path.join(fileURLToPath(new URL("../../", import.meta.url)), "dist");
     const host = options.host ?? "127.0.0.1";
     const html = renderPreviewHtml();
-    const projectJson = {
-        compositions: Array.from(project.compositions.values(), ({ id, entry }) => ({ id, entry })),
-    };
     const server = createServer((request, response) => {
         void (async () => {
             if (request.method !== "GET" && request.method !== "HEAD") {
@@ -159,9 +223,11 @@ export async function startPreviewServer(options) {
                 response.end();
                 return;
             }
+            let url;
             let pathname;
             try {
-                pathname = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname);
+                url = new URL(request.url ?? "/", "http://localhost");
+                pathname = decodeURIComponent(url.pathname);
             }
             catch {
                 sendJson(response, 400, { error: "Invalid URL" });
@@ -187,13 +253,35 @@ export async function startPreviewServer(options) {
                 return;
             }
             if (pathname === "/__frameyard/project.json") {
-                sendJson(response, 200, projectJson);
+                sendJson(response, 200, await buildProjectJson(project));
                 return;
             }
             if (pathname.startsWith("/__frameyard/framework/")) {
                 await serveFile(request, response, frameworkDir, pathname.slice("/__frameyard/framework/".length));
                 return;
             }
+            const composition = findCompositionForPath(project, pathname);
+            if (composition) {
+                const result = await validateHtmlComposition({ projectRoot: project.root, entry: composition.entry });
+                if (url.searchParams.has("__fy-controller")) {
+                    const controller = result.info?.controller;
+                    if (controller?.kind === "inline" && controller.source !== undefined) {
+                        sendJavaScript(response, 200, controller.source, request.method === "HEAD");
+                    }
+                    else {
+                        sendJson(response, 404, { error: "Composition has no inline controller." });
+                    }
+                    return;
+                }
+                const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+                if (errors.length > 0) {
+                    sendHtml(response, 500, renderCompositionError(composition.entry, result.diagnostics), request.method === "HEAD");
+                    return;
+                }
+                const source = await readFile(composition.absoluteEntry, "utf8");
+                sendHtml(response, 200, injectCompositionHost({ html: source }), request.method === "HEAD");
+                return;
+            }
             await serveFile(request, response, project.root, pathname.slice(1));
         })().catch((error) => {
             if (!response.headersSent) {