frameyard 0.2.0 → 0.4.0

package/dist/runtime/media.js

@@ -0,0 +1,307 @@
+import { FrameyardError } from "../errors.js";
+import { frameToSeconds } from "./clock.js";
+const MEDIA_TIMEOUT_MS = 30_000;
+const TIME_EPSILON = 0.0005;
+const preparedMedia = new WeakMap();
+const preparedStates = new Set();
+const pendingPreparation = new WeakMap();
+const VIDEO_MIME_TYPES = {
+    ".mov": "video/quicktime",
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+    ".ogv": "video/ogg",
+    ".webm": "video/webm",
+};
+function mediaSource(video) {
+    const direct = video.getAttribute("src");
+    if (direct !== null && direct.trim().length > 0) {
+        return direct.trim();
+    }
+    const source = video.querySelector("source[src]");
+    const nested = source?.getAttribute("src");
+    if (nested !== null && nested !== undefined && nested.trim().length > 0) {
+        return nested.trim();
+    }
+    return "";
+}
+/** Converts a composition-relative media reference to a normalized project path. */
+export function normalizeMediaSource(raw) {
+    if (raw.length === 0) {
+        throw new FrameyardError("MEDIA_INVALID", "An embedded video must have a non-empty src attribute.");
+    }
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(raw) || raw.startsWith("//") || raw.startsWith("\\")) {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video source must be a local project-relative file, not "${raw}".`);
+    }
+    let pathValue = raw.split(/[?#]/, 1)[0] ?? "";
+    pathValue = pathValue.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (pathValue.startsWith("./")) {
+        pathValue = pathValue.slice(2);
+    }
+    if (pathValue.length === 0 || pathValue.split("/").includes("..") || pathValue.includes("\0")) {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video source must stay inside the project, not "${raw}".`);
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathValue);
+    }
+    catch {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video source is not a valid URL path: "${raw}".`);
+    }
+    if (decoded.length === 0 || decoded.split("/").includes("..") || decoded.includes("\0")) {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video source must stay inside the project, not "${raw}".`);
+    }
+    return decoded;
+}
+function videoUrl(pathValue) {
+    return new URL(`/${pathValue}`, window.location.origin);
+}
+function waitForEvent(video, event, message, code = "MEDIA_INVALID") {
+    return new Promise((resolve, reject) => {
+        let timer;
+        function finish() {
+            video.removeEventListener(event, onEvent);
+            video.removeEventListener("error", onError);
+            clearTimeout(timer);
+        }
+        function onEvent() {
+            finish();
+            resolve();
+        }
+        function onError() {
+            finish();
+            reject(new FrameyardError(code, `${message}${video.error?.message ? `: ${video.error.message}` : ""}`));
+        }
+        timer = setTimeout(() => {
+            finish();
+            reject(new FrameyardError(code, `${message} Timed out after ${MEDIA_TIMEOUT_MS / 1000}s.`));
+        }, MEDIA_TIMEOUT_MS);
+        video.addEventListener(event, onEvent, { once: true });
+        video.addEventListener("error", onError, { once: true });
+    });
+}
+async function prepareVideo(video, owner) {
+    const raw = mediaSource(video);
+    const source = normalizeMediaSource(raw);
+    const spec = mediaSpec(video);
+    const existing = preparedMedia.get(video);
+    if (existing && existing.owner === owner && existing.source === source) {
+        return existing;
+    }
+    if (existing) {
+        preparedMedia.delete(video);
+        preparedStates.delete(existing);
+        URL.revokeObjectURL(existing.objectUrl);
+    }
+    let response;
+    try {
+        response = await fetch(videoUrl(source), { cache: "no-store" });
+    }
+    catch (error) {
+        throw new FrameyardError("ASSET_NOT_FOUND", `Could not load embedded video asset "${source}".`, {
+            cause: error,
+        });
+    }
+    if (!response.ok) {
+        throw new FrameyardError("ASSET_NOT_FOUND", `Could not load embedded video asset "${source}" (HTTP ${response.status}).`);
+    }
+    const blob = await response.blob();
+    if (blob.size === 0) {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video asset "${source}" is empty.`);
+    }
+    const extension = source.slice(source.lastIndexOf(".")).toLowerCase();
+    const type = blob.type || VIDEO_MIME_TYPES[extension] || "video/webm";
+    const videoBlob = blob.type === type ? blob : blob.slice(0, blob.size, type);
+    const objectUrl = URL.createObjectURL(videoBlob);
+    const authorMuted = video.muted;
+    for (const nested of Array.from(video.querySelectorAll("source"))) {
+        nested.remove();
+    }
+    const loaded = waitForEvent(video, "loadeddata", `Embedded video asset "${source}" could not be decoded.`);
+    video.preload = "auto";
+    video.playsInline = true;
+    video.pause();
+    video.muted = true;
+    video.src = objectUrl;
+    video.load();
+    try {
+        await loaded;
+        if (!Number.isFinite(video.duration) || video.duration <= 0 || video.seekable.length === 0) {
+            throw new FrameyardError("MEDIA_INVALID", `Embedded video asset "${source}" is not seekable.`);
+        }
+    }
+    catch (error) {
+        URL.revokeObjectURL(objectUrl);
+        throw error;
+    }
+    const state = { element: video, owner, source, objectUrl, spec, authorMuted };
+    preparedMedia.set(video, state);
+    preparedStates.add(state);
+    return state;
+}
+async function prepareOrGet(video, owner) {
+    const ready = preparedMedia.get(video);
+    if (ready && ready.owner === owner) {
+        return ready;
+    }
+    const pending = pendingPreparation.get(video);
+    if (pending) {
+        return pending;
+    }
+    const preparation = prepareVideo(video, owner);
+    pendingPreparation.set(video, preparation);
+    try {
+        return await preparation;
+    }
+    finally {
+        pendingPreparation.delete(video);
+    }
+}
+/** Loads every embedded video into memory before frame production begins. */
+export async function prepareMedia(container) {
+    const videos = Array.from(container.querySelectorAll("video"));
+    await Promise.all(videos.map((video) => prepareOrGet(video, container)));
+}
+function integerAttribute(element, name, fallback) {
+    const raw = element.getAttribute(name);
+    if (raw === null || raw.trim().length === 0) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video ${name} must be a non-negative integer.`);
+    }
+    return value;
+}
+function secondsAttribute(element, name, fallback, allowZero) {
+    const raw = element.getAttribute(name);
+    if (raw === null || raw.trim().length === 0) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || (!allowZero && value === 0)) {
+        throw new FrameyardError("MEDIA_INVALID", `Embedded video ${name} must be ${allowZero ? "a non-negative" : "a positive"} number of seconds.`);
+    }
+    return value;
+}
+function volumeAttribute(element) {
+    const raw = element.getAttribute("data-fy-volume");
+    if (raw === null || raw.trim().length === 0) {
+        return Math.max(0, Math.min(1, element.volume));
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new FrameyardError("MEDIA_INVALID", "Embedded video data-fy-volume must be between 0 and 1.");
+    }
+    return value;
+}
+function mediaSpec(element) {
+    const startFrame = integerAttribute(element, "data-fy-start", 0);
+    const trimStart = secondsAttribute(element, "data-fy-trim", 0, true);
+    const durationRaw = element.getAttribute("data-fy-duration");
+    const trimDuration = durationRaw === null || durationRaw.trim().length === 0
+        ? undefined
+        : secondsAttribute(element, "data-fy-duration", 0, false);
+    const spec = {
+        startFrame,
+        trimStart,
+        volume: volumeAttribute(element),
+    };
+    if (trimDuration !== undefined) {
+        spec.trimDuration = trimDuration;
+    }
+    return spec;
+}
+function seekTarget(video, spec, frame, fps) {
+    const localSeconds = frameToSeconds(frame, fps) - spec.startFrame / fps;
+    const usedSeconds = spec.trimDuration === undefined
+        ? Math.max(0, localSeconds)
+        : Math.min(spec.trimDuration, Math.max(0, localSeconds));
+    const target = spec.trimStart + usedSeconds;
+    const duration = Number.isFinite(video.duration) ? Math.max(0, video.duration) : target;
+    return Math.min(target, Math.max(0, duration - TIME_EPSILON));
+}
+async function seekVideo(video, frame, fps) {
+    const state = preparedMedia.get(video);
+    if (!state) {
+        throw new FrameyardError("MEDIA_INVALID", "Embedded video elements must be created in mount(); videos added during update() cannot be prepared without network access.");
+    }
+    if (!video.paused) {
+        video.pause();
+    }
+    if (video.readyState < HTMLMediaElement.HAVE_CURRENT_DATA) {
+        await waitForEvent(video, "loadeddata", "Embedded video is not ready for frame production.");
+    }
+    const target = seekTarget(video, state.spec, frame, fps);
+    if (video.seeking) {
+        await waitForEvent(video, "seeked", "Embedded video could not finish an earlier seek.", "MEDIA_SEEK_FAILED");
+    }
+    if (!video.seeking && Math.abs(video.currentTime - target) < TIME_EPSILON) {
+        return;
+    }
+    const seeked = waitForEvent(video, "seeked", "Embedded video could not seek to the requested frame.", "MEDIA_SEEK_FAILED");
+    try {
+        video.currentTime = target;
+    }
+    catch (error) {
+        throw new FrameyardError("MEDIA_SEEK_FAILED", `Embedded video could not seek to ${target.toFixed(3)}s: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    await seeked;
+}
+async function nextPaint() {
+    await new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+/**
+ * Seeks every embedded video to the requested composition frame and waits for
+ * the browser to present the result. This is the asynchronous half of a seek;
+ * composition update() stays synchronous.
+ */
+export async function settleMedia(container, frame, fps) {
+    const videos = Array.from(container.querySelectorAll("video"));
+    if (videos.length === 0) {
+        return;
+    }
+    await Promise.all(videos.map((video) => seekVideo(video, frame, fps)));
+    await nextPaint();
+}
+/** Describes the audio contributed by unmuted embedded videos for preview and FFmpeg. */
+export function describeMediaAudio(container) {
+    const clips = [];
+    for (const video of Array.from(container.querySelectorAll("video"))) {
+        const state = preparedMedia.get(video);
+        if (!state || state.authorMuted || video.getAttribute("data-fy-audio") === "off") {
+            continue;
+        }
+        const spec = state.spec;
+        if (spec.volume === 0) {
+            continue;
+        }
+        const clip = {
+            src: state.source,
+            startFrame: spec.startFrame,
+            trimStart: spec.trimStart,
+            volume: spec.volume,
+        };
+        if (spec.trimDuration !== undefined) {
+            clip.trimDuration = spec.trimDuration;
+        }
+        clips.push(Object.freeze(clip));
+    }
+    return Object.freeze(clips);
+}
+/** Releases object URLs and media resources owned by the runtime. */
+export function releaseMedia(container) {
+    for (const state of Array.from(preparedStates)) {
+        if (state.owner !== container) {
+            continue;
+        }
+        preparedStates.delete(state);
+        preparedMedia.delete(state.element);
+        state.element.pause();
+        URL.revokeObjectURL(state.objectUrl);
+        state.element.removeAttribute("src");
+        state.element.load();
+    }
+}
+//# sourceMappingURL=media.js.map

package/dist/runtime/media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.js","sourceRoot":"","sources":["../../src/runtime/media.ts"],"names":[],"mappings":"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"}

package/dist/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AA8JA,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBzE;AAED,eAAO,MAAM,aAAa,UAKzB,CAAC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAyPA,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBzE;AAED,eAAO,MAAM,aAAa,UAKzB,CAAC"}

package/dist/scaffold.js

@@ -5,22 +5,100 @@ 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.
 - \`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
+
+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
 
-\`width\`, \`height\`, \`fps\`, and \`durationInFrames\` are fixed composition metadata. Do not derive them from props.
+- 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, 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> --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> --out <file.mp4> [--concurrency <n>] --json\`.
+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
 
@@ -34,27 +112,9 @@ npx frameyard render hello --props props/hello.json --out hello.mp4 --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.
+- 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 from the current frame.
-
-## 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.
-- 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.
@@ -63,6 +123,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
@@ -87,58 +149,87 @@ 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`,
+    "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.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CA0DwB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CAsHwB,OAAO,kFAAkF,OAAO;CAC5I,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BtB,CAAC;AAEF,MAAM,kBAAkB,GAA2B;IACjD,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,4CAA4C;CAC7C,CAAC"}