frameyard 0.0.0-stage → 0.2.0

package/dist/transcript.js

@@ -0,0 +1,130 @@
+import { isPlainObject } from "./contracts.js";
+import { FrameyardError } from "./errors.js";
+export const TRANSCRIPT_SCHEMA_VERSION = 1;
+const SHA256 = /^[a-f0-9]{64}$/i;
+function invalid(message) {
+    throw new FrameyardError("TRANSCRIPT_INVALID", message);
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        invalid(`${label} must be a non-empty string.`);
+    }
+    return value;
+}
+function requireMilliseconds(value, label) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        invalid(`${label} must be an integer milliseconds value greater than or equal to zero.`);
+    }
+    return value;
+}
+function parseTimedText(value, label) {
+    if (!isPlainObject(value)) {
+        invalid(`${label} must be a plain object.`);
+    }
+    const startMs = requireMilliseconds(value.startMs, `${label}.startMs`);
+    const endMs = requireMilliseconds(value.endMs, `${label}.endMs`);
+    if (endMs < startMs) {
+        invalid(`${label}.endMs must be greater than or equal to ${label}.startMs.`);
+    }
+    return {
+        startMs,
+        endMs,
+        text: requireString(value.text, `${label}.text`),
+    };
+}
+function parseTimedTextList(value, label) {
+    if (!Array.isArray(value)) {
+        invalid(`${label} must be an array.`);
+    }
+    const result = [];
+    let previousStart = -1;
+    for (const [index, item] of value.entries()) {
+        const parsed = parseTimedText(item, `${label}[${index}]`);
+        if (parsed.startMs < previousStart) {
+            invalid(`${label} must be ordered by startMs.`);
+        }
+        previousStart = parsed.startMs;
+        result.push(parsed);
+    }
+    return result;
+}
+/**
+ * Validates a canonical Frameyard transcript and returns a normalized copy.
+ * Timestamps stay in integer milliseconds relative to the source audio.
+ */
+export function parseTranscript(value, options = {}) {
+    if (!isPlainObject(value)) {
+        invalid("A transcript must be a plain JSON object.");
+    }
+    if (value.schemaVersion !== TRANSCRIPT_SCHEMA_VERSION) {
+        invalid(`Transcript schemaVersion must be ${TRANSCRIPT_SCHEMA_VERSION}; received ${String(value.schemaVersion)}.`);
+    }
+    if (typeof value.text !== "string") {
+        invalid("Transcript text must be a string.");
+    }
+    const source = value.source;
+    if (!isPlainObject(source)) {
+        invalid("Transcript source must be a plain object.");
+    }
+    const sourcePath = requireString(source.path, "Transcript source.path");
+    const sourceSha256 = requireString(source.sha256, "Transcript source.sha256");
+    if (!SHA256.test(sourceSha256)) {
+        invalid("Transcript source.sha256 must be a 64-character SHA-256 hex digest.");
+    }
+    const sourceBytes = source.bytes;
+    if (typeof sourceBytes !== "number" || !Number.isInteger(sourceBytes) || sourceBytes < 0) {
+        invalid("Transcript source.bytes must be a non-negative integer.");
+    }
+    const transcript = {
+        schemaVersion: TRANSCRIPT_SCHEMA_VERSION,
+        text: value.text,
+        source: {
+            path: sourcePath,
+            sha256: sourceSha256,
+            bytes: sourceBytes,
+        },
+        segments: parseTimedTextList(value.segments, "Transcript segments"),
+    };
+    if (value.language !== undefined) {
+        transcript.language = requireString(value.language, "Transcript language");
+    }
+    if (value.words !== undefined) {
+        const words = parseTimedTextList(value.words, "Transcript words");
+        for (const [index, word] of words.entries()) {
+            if (word.text.trim().length === 0) {
+                invalid(`Transcript words[${index}].text must be a non-empty string.`);
+            }
+        }
+        transcript.words = words;
+    }
+    if (options.requireWords && (transcript.words === undefined || transcript.words.length === 0)) {
+        throw new FrameyardError("TRANSCRIPT_WORDS_UNAVAILABLE", "This transcript has no measured word timings. Karaoke highlighting requires word timings; re-run `frameyard transcribe --words` against the source audio.");
+    }
+    return Object.freeze(transcript);
+}
+function timestamp(milliseconds, separator) {
+    const totalSeconds = Math.floor(milliseconds / 1000);
+    const ms = milliseconds % 1000;
+    const seconds = totalSeconds % 60;
+    const minutes = Math.floor(totalSeconds / 60) % 60;
+    const hours = Math.floor(totalSeconds / 3600);
+    const pad = (value, width = 2) => String(value).padStart(width, "0");
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}${separator}${pad(ms, 3)}`;
+}
+/** Renders the canonical transcript's segment timings as SRT. */
+export function transcriptToSrt(transcript) {
+    if (transcript.segments.length === 0) {
+        return "";
+    }
+    return `${transcript.segments
+        .map((segment, index) => `${index + 1}\n${timestamp(segment.startMs, ",")} --> ${timestamp(segment.endMs, ",")}\n${segment.text}`)
+        .join("\n\n")}\n`;
+}
+/** Renders the canonical transcript's segment timings as WebVTT. */
+export function transcriptToVtt(transcript) {
+    const cues = transcript.segments
+        .map((segment) => `${timestamp(segment.startMs, ".")} --> ${timestamp(segment.endMs, ".")}\n${segment.text}`)
+        .join("\n\n");
+    return cues.length === 0 ? "WEBVTT\n" : `WEBVTT\n\n${cues}\n`;
+}
+//# sourceMappingURL=transcript.js.map

package/dist/transcript.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.2.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.2.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/docs/adr/0001-keep-composition-authoring-web-native.md

@@ -0,0 +1,3 @@
+# Keep composition authoring web-native
+
+Frameyard will use ordinary HTML, CSS, and native JavaScript modules with a framework-agnostic composition lifecycle rather than coupling the core to React or another UI framework. This preserves the project's primary differentiator and avoids freezing a UI-framework dependency into the public composition contract; adapters may be added later without changing that contract.

package/docs/adr/0002-make-frame-and-props-the-only-animation-state.md

@@ -0,0 +1,3 @@
+# Make frame and props the only animation state
+
+Every composition frame must be seek-safe and derivable from its integer frame number and immutable props, with asynchronous work completed before frame production. Frameyard rejects wall-clock animation and history-dependent updates because deterministic seeking is what makes reliable scrubbing, independent frame rendering, and future parallelism possible.

package/docs/adr/0003-render-browser-frames-offline.md

@@ -0,0 +1,3 @@
+# Render browser frames offline
+
+Production rendering will drive pinned Chromium through explicit frame seeks, capture each frame, and encode frames and timeline audio with FFmpeg instead of recording real-time browser playback. This accepts slower sequential rendering in exchange for frame accuracy under load, reproducible visual state, and parity between preview and production composition behavior.

package/docs/adr/0004-produce-local-ai-assets-outside-rendering.md

@@ -0,0 +1,3 @@
+# Produce local AI assets outside rendering
+
+Frameyard integrates local speech synthesis and transcription as explicit CLI operations that freeze ordinary project assets before composition loading; model inference is never part of frame production. This separates variable model and hardware behavior from deterministic rendering and keeps the AI integrations optional, at the cost of requiring users and agents to manage generated inputs and their provenance explicitly.

package/docs/v0.1-design.md

@@ -0,0 +1,238 @@
+# Frameyard v0.1 Design Baseline
+
+**Status:** Accepted
+**Initial acceptance:** 2026-10-27
+**Last design revision:** 2026-10-29
+
+This document records the decisions confirmed during the initial design sessions. It defines the v0.1 product and architecture baseline; later changes should revise this document explicitly rather than silently broaden the scope.
+
+## 1. Product contract
+
+Frameyard is a local-first, open-source framework for frontend developers and creative coders who build short, parameterized videos with HTML, CSS, and JavaScript. AI agents can perform the same workflows on a user's behalf through an official skill. Its differentiator is web-native authoring combined with deterministic, frame-accurate output—not a React-centric composition model or a feature-for-feature clone of an existing tool.
+
+The initial use cases are product demos, social clips, animated diagrams, data visualizations, karaoke-style subtitles, and personalized videos. Optional local speech synthesis and transcription produce assets for these workflows. Professional long-form editing is outside the target audience.
+
+The core v0.1 success criterion is an end-to-end example in which a developer can:
+
+1. Create a reusable 30-second, 1920×1080 composition.
+2. Animate it with HTML, CSS, SVG, JavaScript, and seek-safe Canvas 2D.
+3. Supply JSON props and synchronized audio.
+4. Preview and scrub it interactively.
+5. Render it reproducibly to MP4 without dropped frames or timing drift.
+
+The agent-enabled success criterion additionally requires an agent using the official skill to create and preserve a valid source project, optionally produce local audio and transcript assets, validate and inspect the composition, render it, and report all resulting artifact paths without concealing validation failures or skipped visual review.
+
+## 2. Project and authoring model
+
+- Projects use ordinary HTML, CSS, static assets, and native JavaScript ES modules.
+- `video.config.js` explicitly lists composition module entry points. There is no directory-scanning discovery convention.
+- A project may contain multiple compositions, each with a unique ID.
+- Each composition has fixed `width`, `height`, `fps`, and `durationInFrames` metadata. Props cannot change this metadata in v0.1.
+- A composition follows a `mount → update({ frame, props }) → dispose` lifecycle. Mounting creates the visual structure; updating makes that structure represent the requested frame.
+- `update()` must be seek-safe and synchronous. It cannot depend on previously visited frames.
+- Props are JSON-serializable, immutable, and fixed for one render. Composition defaults may be overridden by a JSON file or CLI option.
+- The core validates metadata and JSON-serializability. An optional composition-defined `validateProps()` hook handles domain-specific validation before loading.
+- User compositions are native JavaScript. The framework itself is authored in TypeScript and ships declarations, but v0.1 does not transpile user TypeScript.
+
+## 3. Deterministic execution
+
+The only sources of animation state are the integer frame number and immutable props. Composition frame rate establishes the mapping between frames and time.
+
+- The runtime owns the frame clock and deterministic randomness.
+- CSS `@keyframes` and Web Animations API animations are paused and positioned from the shared frame clock.
+- JavaScript animation runs inside `update()`.
+- Independent `requestAnimationFrame` loops, timers, CSS transitions, wall-clock reads, and unseeded randomness are not supported animation drivers.
+- Deterministic random values are stateless and key-based, such as `random("star:17")`, so they do not depend on call order or rendering history.
+- Development mode provides best-effort diagnostics for forbidden clocks and randomness; it does not claim to police every third-party library perfectly.
+- Assets, remote data, images, fonts, generated audio, and transcripts are resolved during an explicit loading phase before frame production.
+- Required network access is limited to the loading phase. Network requests are blocked during frame capture.
+- AI model inference is never part of `mount()`, `update()`, or frame production.
+- v0.1 supports DOM, CSS, SVG, and Canvas 2D that is redrawn from the current frame.
+- Composition code is trusted local developer code. Frameyard does not claim to render untrusted compositions safely.
+
+### Reproducibility guarantee
+
+For the same composition revision, props, frame, assets, and pinned runtime/browser environment, Frameyard guarantees identical visual state. It does not promise bit-identical MP4 bytes, even across runs on the same machine; encoded output depends on the FFmpeg build, encoder threading, and runtime environment.
+
+Generated assets are covered once frozen. Frameyard does not promise that repeating speech synthesis or transcription produces identical artifacts across different binaries, models, parameters, or hardware.
+
+## 4. Preview and production rendering
+
+Preview and production execute the same composition bundle and browser runtime. They differ only in which component drives the frame clock and whether frames are captured.
+
+The preview provides:
+
+- Composition selection
+- JSON props editing
+- Play/pause and frame-accurate scrubbing
+- Current frame and time display
+- Audio controls
+
+It is a developer inspection tool, not a visual composition editor.
+
+Production rendering:
+
+1. Uses a pinned, Playwright-managed Chromium through the Chrome DevTools Protocol.
+2. Seeks explicitly to each requested frame.
+3. Waits for composition readiness.
+4. Captures the frame.
+5. Pipes frames to FFmpeg for encoding and audio muxing.
+
+The reference renderer is sequential and has no frame cache. Its design nevertheless permits future parallel and out-of-order rendering because each frame is independently seekable. Simple scenes target real-time preview, but v0.1 has no production rendering-speed guarantee; it reports progress, current frame, and elapsed time.
+
+## 5. Audio and output
+
+Audio is a declarative timeline of clips. Each clip supports a source, start frame, source trim, and volume. Preview synchronizes this timeline in the browser; production mixes it offline with FFmpeg rather than treating live `<audio>` or Web Audio playback as the production source of truth.
+
+Generated speech behaves like any other audio clip. Frameyard does not automatically time-stretch it, change composition duration, or regenerate it to fit. `check` reports clip durations and overrun warnings so users and agents can revise text, timing, or composition deliberately.
+
+v0.1 produces portable MP4 files with H.264 video and AAC audio. It exposes only a small set of validated encoding options, not arbitrary FFmpeg arguments. Single-frame PNG output through `still` is a debugging artifact, not general image-sequence support.
+
+A render fails immediately on an uncaught exception, unhandled rejection, required-asset failure, or invalid composition output. Diagnostics identify the composition and, where applicable, the frame. The CLI exits nonzero, cleans temporary files, and never reports a partial video as successful. Existing output files are not overwritten unless explicitly requested.
+
+## 6. CLI, tooling, and package boundaries
+
+Project and composition commands are:
+
+- `init`: scaffold a minimal project, including an agent guide (`AGENTS.md`) and a private `package.json` with pinned `dev`, `check`, `render`, and `still` scripts
+- `dev`: start the preview
+- `render <composition-id> --props props.json --out video.mp4`: render a composition
+- `check <composition-id>`: validate configuration, props, assets, audio, and transcript requirements, then mount the composition and evaluate every frame without capturing or encoding
+- `still <composition-id> --frame <n>`: capture one requested frame as PNG through the production rendering path
+- `doctor`: inspect core requirements and optional integrations without repairing or downloading anything
+
+Local asset-production commands are `tts` and `transcribe`. Every non-interactive command supports `--json` with stable result and error schemas. Structured results go to stdout; human diagnostics and inference progress go to stderr.
+
+The built-in server serves native ES modules and static assets and injects an import map for the framework runtime. It performs no dependency pre-bundling. Third-party libraries must initially be browser-ready ES modules referenced explicitly. Running through the CLI server is required; direct `file://` execution is unsupported.
+
+v0.1 uses one repository and one publishable npm package with three internal layers:
+
+1. Shared composition contracts
+2. Browser runtime
+3. Node-based CLI and renderer
+
+These layers have clean internal boundaries but no public plugin API. FFmpeg is discovered on the user's PATH and checked for required capabilities, with actionable installation and version diagnostics. The project supports the current active Node.js LTS; Linux is the reference and CI platform, while macOS and Windows remain best-effort until covered by real rendering tests.
+
+## 7. Official agent skill
+
+Frameyard ships an optional, host-neutral agent skill with a `SKILL.md`, supporting references, and thin scripts. The npm package includes skill files matching its API version, and documentation explains host-specific installation or referencing. v0.1 does not add a skill-installer command.
+
+The skill:
+
+- Uses the normal project format, composition API, and CLI available to humans.
+- Does not introduce an agent-only runtime, MCP server, hosted control plane, or parallel rendering API.
+- Triggers for Frameyard authoring and operation rather than claiming to be a general-purpose media-generation skill.
+- Uses Frameyard's audio wrappers instead of invoking `qwen-tts` or `whisper-cli` directly.
+- Includes references for deterministic authoring, audio assets, subtitle and karaoke recipes, JSON command results, and failure recovery.
+- Invokes speech synthesis or transcription only when requested or explicitly approved as part of the brief.
+- Does not overwrite or regenerate existing generated assets without permission.
+- Runs `check`, inspects representative `still` images when the host supports image viewing, and discloses when visual inspection was impossible.
+- Does not claim success when checks fail or rendering is partial.
+
+A successful agent workflow preserves and reports the source project, props, generated assets, provenance manifest, validation results, and final video path. The user must be able to inspect, modify, and reproduce the result rather than receiving only an opaque MP4.
+
+## 8. Local speech synthesis
+
+The `tts` command integrates [`qwentts.cpp`](https://github.com/ServeurpersoCom/qwentts.cpp) through its external `qwen-tts` executable. It does not link the native library or require the upstream server.
+
+v0.1 supports CustomVoice mode only:
+
+- A named speaker is required.
+- An optional style instruction and language may be supplied.
+- Reference-audio voice cloning and free-form VoiceDesign are deferred.
+- Text is supplied by `--text-file` or stdin.
+- Talker GGUF, codec GGUF, and output paths are required.
+- One invocation produces one frozen 24 kHz mono WAV from one complete text input.
+- Automatic long-text chunking, streaming, and alternative audio formats are deferred.
+
+Users acquire and provide models explicitly. Frameyard does not build `qwentts.cpp`, download or redistribute models, or imply that upstream code licenses settle model-weight licensing. Executable resolution uses an explicit option, then environment configuration, then PATH.
+
+## 9. Local transcription and timed text
+
+The `transcribe` command integrates [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp) through its external `whisper-cli` executable. Before transcription, Frameyard uses FFmpeg to normalize source audio or video to 16 kHz mono PCM WAV, avoiding dependence on optional upstream decoder builds and inconsistent input-format documentation.
+
+Users provide a Whisper GGML model explicitly. The command requires source and output paths and supports optional word timings through `--words` and derived subtitle exports through `--export srt,vtt`. Executable resolution follows the same option, environment, then PATH order as speech synthesis.
+
+The canonical artifact is a versioned Frameyard JSON document containing:
+
+- Full text
+- Source identity and content hash
+- Language when known
+- Timed segments
+- Optional word timings
+
+All timestamps are integer milliseconds relative to the source audio, not composition frame numbers. Composition code converts them using the audio clip's start frame, source trim, and composition frame rate.
+
+Compositions may declare required transcript assets with a `transcripts` field analogous to `audio`:
+
+```js
+transcripts: [{ src: "assets/voice.transcript.json", words: true }]
+```
+
+`check` and production validate declared transcript files before frame production. `words: true` requires measured word timings and fails when they are unavailable; it never triggers interpolation.
+
+SRT and VTT are derived exports, not the canonical contract. Word-level karaoke requires actual word timings and fails validation when they are unavailable. Frameyard never fabricates word timings by interpolating segment timestamps and never executes Whisper's generated bash/FFmpeg karaoke script.
+
+The official skill documents seek-safe subtitle and karaoke recipes. Compositions retain responsibility for visual presentation; v0.1 has no built-in subtitle renderer and does not automatically burn captions into videos.
+
+## 10. Generated assets and inference operation
+
+Speech synthesis and transcription are separate asset-production operations that complete before composition loading and rendering. Their outputs are ordinary local project assets. Once those assets are frozen, ordinary authoring, preview, checking, and rendering require neither AI executable nor model.
+
+Both integrations are optional and local-only, with no cloud fallback. Network activity needed to acquire tools or models is a separate explicit setup operation, never a hidden side effect of generation or rendering.
+
+Generated artifacts follow a shared contract:
+
+- Outputs are written atomically to explicit paths.
+- Existing outputs are not overwritten unless `--force` is supplied.
+- A versioned project-local provenance manifest records artifact content hashes, generator details, model identities, and parameters. The default manifest is `frameyard.assets.json` in the project root; `--manifest` selects another path.
+- Transcription provenance also identifies the source asset by content hash.
+- Partial operations leave neither apparently valid artifacts nor manifest entries.
+- `doctor` validates executables, model readability, capabilities, and supported integration versions without modifying the environment.
+
+Each operation runs one inference subprocess, and the official agent workflow executes inference sequentially to avoid unexpected CPU/GPU contention. There is no arbitrary fixed timeout. Cancellation terminates the child process and removes partial outputs.
+
+Release documentation must identify the exact `qwentts.cpp` and `whisper.cpp` revisions against which the wrappers are tested. Frameyard does not claim compatibility with arbitrary upstream revisions.
+
+## 11. Verification strategy
+
+Tests prioritize public behavior and end-to-end evidence over implementation-only unit coverage:
+
+- Sequential, individual, and random-order frame renders produce equivalent images.
+- Determinism checks compare captured pixels or stills; encoded MP4 bytes are not a reproducibility oracle.
+- Preview and renderer use the same runtime.
+- CSS, JavaScript, SVG, and Canvas animations seek correctly.
+- Asset and runtime failures produce nonzero CLI exits.
+- Rendered MP4 files have the expected dimensions, frame count, duration, and audio stream.
+- Golden-frame tests cover representative visual behavior.
+- `check` exercises every frame, and `still` follows the production capture path.
+- Normal CI uses fake `qwen-tts` and `whisper-cli` executables and small fixtures to verify arguments, artifacts, manifests, cancellation, and errors without model downloads or GPU hardware.
+- Real-model integration tests are explicitly opt-in and use documented upstream revisions.
+- Agent-workflow evaluations verify source preservation, provenance, validation, still inspection behavior, failure reporting, and final renders.
+
+## 12. Deferred from v0.1
+
+These are scope boundaries, not permanent rejections:
+
+- Visual editing, hosted rendering, collaboration, and asset marketplaces
+- Cloud generative-AI services, text-to-video generation, and image generation
+- `qwentts.cpp` reference-audio voice cloning and VoiceDesign
+- Automatic long-text chunking, streaming speech synthesis, and alternative generated-audio formats
+- Built-in subtitle rendering and automatic caption burn-in
+- Automatic upstream builds, model downloads, weight redistribution, and environment repair
+- Agent-only runtimes, MCP servers, hosted agent control planes, and host-specific skill installers
+- React or other UI-framework adapters in the core
+- Public plugin APIs and a broad integration ecosystem
+- Dynamic composition metadata derived from props
+- Embedded video, WebGL, live streams, and other independently timed visual content
+- Dynamic per-frame asset loading or AI inference
+- Parallel rendering and frame caches
+- Additional final-video formats, general image-sequence output, and arbitrary FFmpeg argument passthrough
+- Built-in TypeScript transpilation and npm dependency optimization
+- Rendering untrusted compositions
+- Bit-identical cross-platform encoded output or AI regeneration
+- A minimum production rendering-speed guarantee
+
+## 13. Release posture
+
+Frameyard is MIT-licensed. Initial releases use `0.x` versioning, and composition, configuration, CLI, JSON-result, transcript, and skill-contract changes are documented explicitly until those contracts stabilize.

package/examples/demo/README.md

@@ -0,0 +1,24 @@
+# Frameyard demo
+
+A 30-second, 1920×1080 composition that exercises the v0.1 core:
+
+- HTML and CSS layout, including seeked CSS keyframe animation
+- deterministic Canvas 2D starfield
+- SVG path drawing and data bars updated from the frame
+- JSON props for the title, subtitle, and accent color
+- a declarative audio timeline with repeated local chime clips
+
+From the repository root:
+
+```sh
+pnpm build
+node dist/cli.js check demo --project examples/demo
+node dist/cli.js still demo --frame 240 --project examples/demo --out demo-still.png
+node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json --out demo.mp4
+```
+
+Start the interactive preview with:
+
+```sh
+node dist/cli.js dev --project examples/demo
+```

package/examples/demo/compositions/demo.js

@@ -0,0 +1,206 @@
+import { defineComposition } from "frameyard";
+import { random } from "frameyard/runtime";
+
+let scene;
+let title;
+let subtitle;
+let kaption;
+let progress;
+let signalPath;
+let bars = [];
+let starfield;
+let stars;
+let context;
+let signalLength = 0;
+
+const STAR_COUNT = 130;
+const BAR_COUNT = 52;
+const BASELINE = 858;
+
+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() {
+  const svg = document.querySelector("#signal");
+  const group = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  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(--accent)");
+    rect.setAttribute("height", "0");
+    rect.setAttribute("y", String(BASELINE));
+    rect.setAttribute("opacity", "0");
+    group.append(rect);
+    bars.push({ element: rect, height });
+  }
+
+  svg.append(group);
+  return group;
+}
+
+function buildSignalPath() {
+  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 defineComposition({
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  durationInFrames: 900,
+  defaultProps: {
+    title: "Frameyard",
+    subtitle: "Deterministic video, authored with the web platform.",
+    accent: "#b8f36b",
+  },
+  validateProps(props) {
+    const errors = [];
+    if (typeof props.title !== "string" || props.title.length === 0) errors.push("title must be a non-empty string");
+    if (typeof props.subtitle !== "string") errors.push("subtitle must be a string");
+    if (typeof props.accent !== "string") errors.push("accent must be a string");
+    return errors;
+  },
+  audio: [
+    { src: "assets/chime.wav", startFrame: 18, volume: 0.5 },
+    { src: "assets/chime.wav", startFrame: 300, volume: 0.38 },
+    { src: "assets/chime.wav", startFrame: 600, volume: 0.42 },
+    { src: "assets/chime.wav", startFrame: 840, volume: 0.55 },
+  ],
+  mount({ container, props }) {
+    container.style.setProperty("--accent", props.accent);
+    container.innerHTML =
+      "<style>" +
+      "@keyframes orbit { from { transform: rotate(0deg) translateX(210px) rotate(0deg); } to { transform: rotate(360deg) translateX(210px) rotate(-360deg); } }" +
+      "@keyframes breathe { 0%, 100% { opacity: .35; transform: scale(1); } 50% { opacity: .7; transform: scale(1.12); } }" +
+      "#scene { position: relative; width: 100%; height: 100%; overflow: hidden; background: #080a0d; color: #eef2f7; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }" +
+      "#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(--accent); filter: blur(110px); opacity: .28; animation: orbit 30s linear infinite;" +
+      " }" +
+      "#glow { position: absolute; top: 8%; right: 6%; width: 280px; height: 280px; border-radius: 50%; background: var(--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,.14); }" +
+      "#eyebrow { position: absolute; top: 64px; left: 160px; font: 600 14px/1 ui-monospace, monospace; letter-spacing: .28em; text-transform: uppercase; color: var(--accent); }" +
+      "#meta { position: absolute; top: 64px; right: 160px; font: 500 14px/1 ui-monospace, monospace; letter-spacing: .12em; color: #788595; }" +
+      "#copy { position: absolute; left: 160px; top: 236px; width: 1320px; }" +
+      "#title { margin: 0; font-size: 156px; line-height: .92; letter-spacing: -.055em; font-weight: 680; }" +
+      "#subtitle { margin: 34px 0 0; max-width: 820px; font-size: 31px; line-height: 1.45; color: #96a2b2; font-weight: 420; }" +
+      "#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: .16em; color: #7e8b9b; }" +
+      "#caption strong { color: var(--accent); font-weight: 600; }" +
+      "#progress-track { position: absolute; left: 160px; right: 160px; bottom: 72px; height: 2px; background: rgba(255,255,255,.1); }" +
+      "#progress { position: absolute; inset: 0 auto 0 0; width: 0%; background: var(--accent); box-shadow: 0 0 18px var(--accent); }" +
+      "#vignette { position: absolute; inset: 0; background: radial-gradient(ellipse at center, transparent 48%, rgba(0,0,0,.42) 100%); pointer-events: none; }" +
+      "</style>" +
+      '<div id="scene">' +
+      '<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"></h1><p id="subtitle"></p></div>' +
+      '<svg id="signal" viewBox="0 0 1920 1080" fill="none" aria-hidden="true">' +
+      '<path id="signal-path" stroke="var(--accent)" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" opacity=".82"/>' +
+      "</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>";
+
+    scene = container.querySelector("#scene");
+    title = container.querySelector("#title");
+    subtitle = container.querySelector("#subtitle");
+    kaption = container.querySelector("#frame");
+    progress = container.querySelector("#progress");
+    signalPath = container.querySelector("#signal-path");
+    starfield = container.querySelector("#field");
+    context = starfield.getContext("2d");
+    makeStars();
+    buildBars();
+    buildSignalPath();
+    title.textContent = props.title;
+    subtitle.textContent = props.subtitle;
+  },
+  update({ frame, props }) {
+    const intro = easeOut(frame / 52);
+    const copyIntro = easeOut((frame - 26) / 62);
+    const signalReveal = easeOut((frame - 96) / 260);
+    const outro = 1 - clamp((frame - 824) / 70);
+    const total = 899;
+
+    scene.style.opacity = String(outro);
+    title.textContent = props.title;
+    subtitle.textContent = props.subtitle;
+    title.style.opacity = String(intro);
+    title.style.transform = "translateY(" + (1 - intro) * 46 + "px)";
+    subtitle.style.opacity = String(copyIntro);
+    subtitle.style.transform = "translateY(" + (1 - copyIntro) * 26 + "px)";
+    kaption.textContent = String(frame).padStart(3, "0");
+    progress.style.width = (frame / total) * 100 + "%";
+
+    const width = starfield.width;
+    const height = starfield.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));
+    }
+  },
+  dispose() {
+    scene = undefined;
+    title = undefined;
+    subtitle = undefined;
+    kaption = undefined;
+    progress = undefined;
+    signalPath = undefined;
+    starfield = undefined;
+    context = undefined;
+    bars = [];
+    stars = undefined;
+    signalLength = 0;
+  },
+});