+```
diff --git a/packages/cli/src/docs/data-attributes.md b/packages/cli/src/docs/data-attributes.md
new file mode 100644
index 000000000..9eaf5d8ce
--- /dev/null
+++ b/packages/cli/src/docs/data-attributes.md
@@ -0,0 +1,22 @@
+# Data Attributes
+
+Core attributes for controlling element timing and behavior.
+
+## Timing
+- `data-start="0"` — Start time in seconds
+- `data-duration="5"` — Duration in seconds
+- `data-track-index="0"` — Timeline track number (controls z-ordering)
+
+## Media
+- `data-media-start="2"` — Media playback offset / trim point (seconds)
+- `data-volume="0.8"` — Audio/video volume, 0 to 1
+- `data-has-audio="true"` — Indicates video has an audio track
+
+## Composition
+- `data-composition-id="root"` — Unique ID for composition wrapper (required)
+- `data-width="1920"` — Composition width in pixels
+- `data-height="1080"` — Composition height in pixels
+- `data-composition-src="./intro.html"` — Nested composition source
+
+## Element Visibility
+Add `class="clip"` to timed elements so the runtime can manage their visibility lifecycle.
diff --git a/packages/cli/src/docs/gsap.md b/packages/cli/src/docs/gsap.md
new file mode 100644
index 000000000..4058cb4b5
--- /dev/null
+++ b/packages/cli/src/docs/gsap.md
@@ -0,0 +1,23 @@
+# GSAP Animation
+
+HyperFrames uses GSAP for animation. Timelines are paused and controlled by the runtime.
+
+## Setup
+```html
+
+
+```
+
+## Key Rules
+- Always create timelines with `{ paused: true }`
+- Register timelines on `window.__timelines` with the composition ID as key
+- Position parameter (3rd arg) sets absolute time: `tl.to(el, vars, 1.5)`
+- Supported methods: `set`, `to`, `from`, `fromTo`
+
+## Supported Properties
+opacity, x, y, scale, scaleX, scaleY, rotation, width, height, visibility
diff --git a/packages/cli/src/docs/rendering.md b/packages/cli/src/docs/rendering.md
new file mode 100644
index 000000000..1ae283aa4
--- /dev/null
+++ b/packages/cli/src/docs/rendering.md
@@ -0,0 +1,23 @@
+# Rendering
+
+Render compositions to MP4 with `npx hyperframes render`.
+
+## Local Mode (default)
+Uses Puppeteer (bundled Chromium) + system FFmpeg. Fast for iteration.
+Requires: FFmpeg installed (`brew install ffmpeg` or `apt install ffmpeg`).
+
+## Docker Mode (--docker)
+Deterministic output with exact Chrome version and fonts. For production.
+Requires: Docker installed and running.
+
+## Options
+- `-f, --fps` — 24, 30, or 60 (default: 30)
+- `-q, --quality` — draft, standard, high (default: standard)
+- `-w, --workers` — Parallel workers 1-8 (default: auto)
+- `--gpu` — Use GPU encoding (NVENC, VideoToolbox, VAAPI)
+- `-o, --output` — Custom output path
+
+## Tips
+- Use `draft` quality for fast previews during development
+- Use `npx hyperframes benchmark` to find optimal settings
+- 4 workers is usually the sweet spot for most compositions
diff --git a/packages/cli/src/docs/templates.md b/packages/cli/src/docs/templates.md
new file mode 100644
index 000000000..9a562b6db
--- /dev/null
+++ b/packages/cli/src/docs/templates.md
@@ -0,0 +1,15 @@
+# Templates
+
+Built-in templates available via `npx hyperframes init --template
`.
+
+## blank
+Empty 1920x1080 composition with GSAP timeline wired up. Start from scratch.
+
+## title-card
+Animated title and subtitle with GSAP fade-in/out. Good for intro cards.
+
+## video-edit
+Video element with trimming, audio, and track controls. Starting point for video editing.
+
+## Custom Templates
+Any directory with an `index.html` can serve as a template. Copy it manually or build your own init workflow.
diff --git a/packages/cli/src/docs/troubleshooting.md b/packages/cli/src/docs/troubleshooting.md
new file mode 100644
index 000000000..8fac30862
--- /dev/null
+++ b/packages/cli/src/docs/troubleshooting.md
@@ -0,0 +1,22 @@
+# Troubleshooting
+
+## "No composition found"
+Your directory needs an `index.html`. Run `npx hyperframes init` to create one.
+
+## "FFmpeg not found"
+Local rendering requires FFmpeg. Install it:
+- macOS: `brew install ffmpeg`
+- Ubuntu: `sudo apt install ffmpeg`
+- Windows: Download from https://ffmpeg.org/download.html
+
+## Lint errors
+Run `npx hyperframes lint` to check for common issues:
+- Missing `data-composition-id` on root element
+- Missing `class="clip"` on timed elements
+- Overlapping timelines or invalid data attributes
+
+## Preview not updating
+Make sure you're editing the `index.html` in the project directory. The preview server watches for file changes and auto-reloads.
+
+## Render looks different from preview
+Use `--docker` mode for deterministic output. Local renders may differ due to font availability and Chrome version.
diff --git a/packages/cli/src/templates/generators.ts b/packages/cli/src/templates/generators.ts
new file mode 100644
index 000000000..8d2657477
--- /dev/null
+++ b/packages/cli/src/templates/generators.ts
@@ -0,0 +1,14 @@
+export type TemplateId = "warm-grain" | "play-mode" | "swiss-grid" | "vignelli";
+
+export interface TemplateOption {
+ id: TemplateId;
+ label: string;
+ hint: string;
+}
+
+export const TEMPLATES: TemplateOption[] = [
+ { id: "warm-grain", label: "Warm Grain", hint: "Cream aesthetic with grain texture" },
+ { id: "play-mode", label: "Play Mode", hint: "Playful elastic animations" },
+ { id: "swiss-grid", label: "Swiss Grid", hint: "Structured grid layout" },
+ { id: "vignelli", label: "Vignelli", hint: "Bold typography with red accents" },
+];
diff --git a/packages/cli/src/templates/play-mode/compositions/captions.html b/packages/cli/src/templates/play-mode/compositions/captions.html
new file mode 100644
index 000000000..14f2a8fdd
--- /dev/null
+++ b/packages/cli/src/templates/play-mode/compositions/captions.html
@@ -0,0 +1,97 @@
+
+
+
diff --git a/packages/cli/src/templates/play-mode/compositions/intro.html b/packages/cli/src/templates/play-mode/compositions/intro.html
new file mode 100644
index 000000000..5ea591cab
--- /dev/null
+++ b/packages/cli/src/templates/play-mode/compositions/intro.html
@@ -0,0 +1,88 @@
+
+
+
+
HYPERFRAMES
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/play-mode/compositions/stats.html b/packages/cli/src/templates/play-mode/compositions/stats.html
new file mode 100644
index 000000000..d96b6acd3
--- /dev/null
+++ b/packages/cli/src/templates/play-mode/compositions/stats.html
@@ -0,0 +1,252 @@
+
+
+
+
+
+
+
+
+
47%
+
NEED MOTION GRAPHICS
+
+
+
+
+
+
+
+
+
+
+
+
+
62%
+
STRUGGLE WITH STATIC CONTENT
+
+
+
+
+
+
+
+
+
+
+
+
+
75%
+
LACK EDITING SKILLS
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/play-mode/index.html b/packages/cli/src/templates/play-mode/index.html
new file mode 100644
index 000000000..1e50e10d0
--- /dev/null
+++ b/packages/cli/src/templates/play-mode/index.html
@@ -0,0 +1,173 @@
+
+
+
+ Hyperframes - Play Mode
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/packages/cli/src/templates/swiss-grid/compositions/captions.html b/packages/cli/src/templates/swiss-grid/compositions/captions.html
new file mode 100644
index 000000000..f2594daf2
--- /dev/null
+++ b/packages/cli/src/templates/swiss-grid/compositions/captions.html
@@ -0,0 +1,95 @@
+
+
+
diff --git a/packages/cli/src/templates/swiss-grid/compositions/graphics.html b/packages/cli/src/templates/swiss-grid/compositions/graphics.html
new file mode 100644
index 000000000..64134a57a
--- /dev/null
+++ b/packages/cli/src/templates/swiss-grid/compositions/graphics.html
@@ -0,0 +1,198 @@
+
+
+
+
+
+
47%
+
NEED MOTION GRAPHICS
+
+
+
+
+
62%
+
LOSING ATTENTION
+
+
+
+
+
+
3 OF 4
+
LACK EDITING SKILLS
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/packages/cli/src/templates/swiss-grid/compositions/intro.html b/packages/cli/src/templates/swiss-grid/compositions/intro.html
new file mode 100644
index 000000000..dd89ed690
--- /dev/null
+++ b/packages/cli/src/templates/swiss-grid/compositions/intro.html
@@ -0,0 +1,114 @@
+
+
+
+
+
+
HYPERFRAMES
+ THE SURVEY FINDINGS
+
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/swiss-grid/index.html b/packages/cli/src/templates/swiss-grid/index.html
new file mode 100644
index 000000000..10a0e3bd8
--- /dev/null
+++ b/packages/cli/src/templates/swiss-grid/index.html
@@ -0,0 +1,172 @@
+
+
+
+ Swiss Grid - Hyperframes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/vignelli/compositions/overlays.html b/packages/cli/src/templates/vignelli/compositions/overlays.html
new file mode 100644
index 000000000..e2a13c7b1
--- /dev/null
+++ b/packages/cli/src/templates/vignelli/compositions/overlays.html
@@ -0,0 +1,271 @@
+
+
+
+
+
+
+
+
+
+
47%
+
Motion Graphics
+
+
+
+
+
+
+
+
62%
+
Static Content
+
+
+
+
+
+
+
+ 3 out of 4
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/vignelli/index.html b/packages/cli/src/templates/vignelli/index.html
new file mode 100644
index 000000000..f37079ff2
--- /dev/null
+++ b/packages/cli/src/templates/vignelli/index.html
@@ -0,0 +1,171 @@
+
+
+
+ Massimo Vignelli Video
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/warm-grain/compositions/graphics.html b/packages/cli/src/templates/warm-grain/compositions/graphics.html
new file mode 100644
index 000000000..e684da13d
--- /dev/null
+++ b/packages/cli/src/templates/warm-grain/compositions/graphics.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
47%
+
Need Motion Graphics
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/packages/cli/src/templates/warm-grain/compositions/intro.html b/packages/cli/src/templates/warm-grain/compositions/intro.html
new file mode 100644
index 000000000..dd1f549e8
--- /dev/null
+++ b/packages/cli/src/templates/warm-grain/compositions/intro.html
@@ -0,0 +1,77 @@
+
+
+
+
+
Hyperframes
+
Design simplified.
+
+
+
+
+
+
+
diff --git a/packages/cli/src/templates/warm-grain/index.html b/packages/cli/src/templates/warm-grain/index.html
new file mode 100644
index 000000000..93e29020d
--- /dev/null
+++ b/packages/cli/src/templates/warm-grain/index.html
@@ -0,0 +1,195 @@
+
+
+
+ Warm Grain - Hyperframes
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
).DOMParser = DOMParser;
+ }
+}
diff --git a/packages/cli/src/utils/mime.ts b/packages/cli/src/utils/mime.ts
new file mode 100644
index 000000000..e6234e06c
--- /dev/null
+++ b/packages/cli/src/utils/mime.ts
@@ -0,0 +1,21 @@
+export const MIME_TYPES: Record = {
+ ".html": "text/html",
+ ".css": "text/css",
+ ".js": "application/javascript",
+ ".json": "application/json",
+ ".svg": "image/svg+xml",
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+ ".gif": "image/gif",
+ ".webp": "image/webp",
+ ".mp4": "video/mp4",
+ ".webm": "video/webm",
+ ".mp3": "audio/mpeg",
+ ".wav": "audio/wav",
+ ".ogg": "audio/ogg",
+ ".woff2": "font/woff2",
+ ".woff": "font/woff",
+ ".ttf": "font/ttf",
+ ".ico": "image/x-icon",
+};
diff --git a/packages/cli/src/utils/producer.ts b/packages/cli/src/utils/producer.ts
new file mode 100644
index 000000000..cf5fa15ea
--- /dev/null
+++ b/packages/cli/src/utils/producer.ts
@@ -0,0 +1,7 @@
+/**
+ * Dynamically load the producer module. tsup inlines @hyperframes/producer
+ * via noExternal so this resolves in the published bundle.
+ */
+export async function loadProducer() {
+ return await import("@hyperframes/producer");
+}
diff --git a/packages/cli/src/utils/project.ts b/packages/cli/src/utils/project.ts
new file mode 100644
index 000000000..cf701a8e1
--- /dev/null
+++ b/packages/cli/src/utils/project.ts
@@ -0,0 +1,30 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { errorBox } from "../ui/format.js";
+
+export interface ProjectDir {
+ dir: string;
+ name: string;
+ indexPath: string;
+}
+
+export function resolveProject(dirArg: string | undefined): ProjectDir {
+ const dir = resolve(dirArg ?? ".");
+ const name = basename(dir);
+ const indexPath = resolve(dir, "index.html");
+
+ if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+ errorBox("Not a directory: " + dir);
+ process.exit(1);
+ }
+ if (!existsSync(indexPath)) {
+ errorBox(
+ "No composition found in " + dir,
+ "No index.html file found.",
+ "Run npx hyperframes init to create a new composition.",
+ );
+ process.exit(1);
+ }
+
+ return { dir, name, indexPath };
+}
diff --git a/packages/cli/src/version.ts b/packages/cli/src/version.ts
new file mode 100644
index 000000000..52c905c11
--- /dev/null
+++ b/packages/cli/src/version.ts
@@ -0,0 +1 @@
+export const VERSION = "0.1.0";
diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json
new file mode 100644
index 000000000..441b14aee
--- /dev/null
+++ b/packages/cli/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "outDir": "./dist",
+ "rootDir": "./src",
+ "declaration": true
+ },
+ "include": ["src"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
new file mode 100644
index 000000000..1f6d69589
--- /dev/null
+++ b/packages/cli/tsup.config.ts
@@ -0,0 +1,53 @@
+import { defineConfig } from "tsup";
+import { resolve } from "node:path";
+
+export default defineConfig({
+ entry: ["src/cli.ts"],
+ format: ["esm"],
+ outDir: "dist",
+ target: "node22",
+ platform: "node",
+ bundle: true,
+ splitting: false,
+ sourcemap: false,
+ clean: true,
+ banner: {
+ js: `import { createRequire as __hf_createRequire } from "node:module";
+import { fileURLToPath as __hf_fileURLToPath } from "node:url";
+import { dirname as __hf_dirname } from "node:path";
+const require = __hf_createRequire(import.meta.url);
+const __filename = __hf_fileURLToPath(import.meta.url);
+const __dirname = __hf_dirname(__filename);`,
+ },
+ external: [
+ "puppeteer-core",
+ "puppeteer",
+ "@puppeteer/browsers",
+ "open",
+ "hono",
+ "hono/*",
+ "@hono/node-server",
+ "cheerio",
+ "mime-types",
+ "adm-zip",
+ "esbuild",
+ ],
+ noExternal: [
+ "@hyperframes/core",
+ "@hyperframes/producer",
+ "@hyperframes/studio-backend",
+ "@hyperframes/engine",
+ "@clack/prompts",
+ "@clack/core",
+ "picocolors",
+ "linkedom",
+ "sisteransi",
+ "is-unicode-supported",
+ "citty",
+ ],
+ esbuildOptions(options) {
+ options.alias = {
+ "@hyperframes/producer": resolve(__dirname, "../producer/src/index.ts"),
+ };
+ },
+});
diff --git a/packages/core/README.md b/packages/core/README.md
new file mode 100644
index 000000000..0cd4fb4a9
--- /dev/null
+++ b/packages/core/README.md
@@ -0,0 +1,125 @@
+# HyperFrames Core
+
+> Create videos by writing HTML. The HTML is the source of truth - timing, layout, content. Scripts define how clips animate.
+
+HyperFrames Core is the foundational library for video composition. It defines the data attributes and HTML structure that represent video timelines, with GSAP animations to bring clips to life.
+
+Frame adapter direction:
+
+- [`../FRAME.md`](../FRAME.md) - repository-level frame model and deterministic renderer direction
+- [`adapters/README.md`](adapters/README.md) - adapter contract and contribution guide
+
+## Philosophy
+
+```
+HTML = Scene description (content, timing, layout)
+CSS = Styling
+JS = GSAP animations (motion)
+```
+
+Every element in the video timeline is represented as an HTML element with data attributes that define its position in time.
+
+---
+
+## Documentation
+
+### Schema
+
+The specification for valid HyperFrames HTML:
+
+- **[schema.md](docs/schema.md)** - Element types, data attributes, HTML patterns
+
+### Guides
+
+For AI agents and developers working with HyperFrames:
+
+| Document | Description |
+| --------------------------------------------------------- | -------------------------------------- |
+| [Cheat Sheet](docs/guides/cheat-sheet.md) | Quick reference for common actions |
+| [Position Guide](docs/guides/position.md) | Natural language → position mappings |
+| [Text Style Guide](docs/guides/text-style.md) | Natural language → text style mappings |
+| [Motion Design Guide](docs/guides/motion-design/guide.md) | Creating and editing motion designs |
+| [Caption Guide](docs/guides/motion-design/captions.md) | Adding captions to videos |
+
+---
+
+## Quick Start
+
+### Using the Editor (Recommended)
+
+```bash
+pnpm install
+pnpm dev
+```
+
+This starts the studio dev server.
+
+### Writing Compositions Manually
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+```
+
+---
+
+## Element Types
+
+| Type | HTML Tag | Purpose |
+| ----------- | ------------------------------- | -------------------- |
+| video | `` | Video clips |
+| image | `` | Text overlays |
+| audio | `
` | Music, sound effects |
+| composition | `` | Motion designs |
+
+## Data Attributes
+
+| Attribute | Purpose | Required |
+| ------------ | --------------------------------- | -------- |
+| `data-start` | When element appears (seconds) | Yes |
+| `data-end` | When element disappears (seconds) | No |
+| `data-name` | Display name in UI | No |
+| `data-layer` | Z-index for stacking | No |
+
+See [schema.md](docs/schema.md) for the complete reference.
+
+---
+
+**Remember:** HTML is the storyboard. CSS is the art direction. JS is just for motion.
diff --git a/packages/core/docs/common-mistakes.md b/packages/core/docs/common-mistakes.md
new file mode 100644
index 000000000..7924570ce
--- /dev/null
+++ b/packages/core/docs/common-mistakes.md
@@ -0,0 +1,73 @@
+# Common Mistakes
+
+Pitfalls that break HyperFrames compositions that can't be caught by the linter.
+
+> **Linter:** Run `lintHyperframeHtml()` on your composition to catch most issues automatically. The linter detects: missing timeline registration, unmuted video, nested video in timed elements, missing `class="clip"`, deprecated attribute names (`data-layer`, `data-end`), and missing dimensions. See `core/src/lint/` for the full rule list.
+
+---
+
+## 1. Animating video element dimensions with GSAP
+
+**Symptom:** Video frames stop updating, or browser performance drops.
+
+**Cause:** GSAP animating `width`, `height`, `top`, `left` directly on a `
` element can cause the browser to stop rendering frames.
+
+```js
+// BROKEN — animating video element dimensions
+tl.to("#el-video", { width: 500, height: 280, top: 700, left: 1400 }, 26);
+
+// FIXED — animate a wrapper div, video fills it at 100%
+tl.to("#pip-wrapper", { width: 500, height: 280, top: 700, left: 1400 }, 26);
+```
+
+Use a non-timed wrapper div for visual effects like picture-in-picture. Animate the wrapper; let the video fill it.
+
+---
+
+## 2. Controlling media playback in scripts
+
+**Symptom:** Audio/video playback is out of sync, or plays when it shouldn't.
+
+**Cause:** Calling `video.play()`, `video.pause()`, `audio.currentTime = ...` in your scripts. The framework owns all media playback.
+
+```js
+// BROKEN — conflicts with framework media sync
+document.getElementById("el-video").play();
+document.getElementById("el-audio").currentTime = 5;
+
+// FIXED — don't do this. The framework handles it.
+// Use GSAP for visual animations only:
+tl.to("#el-video", { opacity: 1, duration: 0.5 }, 0);
+```
+
+---
+
+## 3. Composition duration shorter than video
+
+**Symptom:** Video plays for a few seconds then stops. Timeline shows 8-10 seconds even though the video is minutes long.
+
+**Cause:** The composition duration equals the GSAP timeline duration, not `data-duration` on the video. If your last GSAP animation ends at 8 seconds, the composition is 8 seconds long.
+
+```js
+// BROKEN — timeline is only 8s long, video cuts off
+tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
+// Last tween ends at 7.8s → composition = 7.8s
+
+// FIXED — extend timeline to match video length
+tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
+tl.set({}, {}, 283); // ← extends timeline to 283 seconds
+```
+
+`tl.set({}, {}, TIME)` adds a zero-duration tween at the specified time, which extends the timeline without affecting any elements.
+
+---
+
+## Debugging checklist
+
+When something doesn't work, check in this order:
+
+1. Run the linter: `lintHyperframeHtml(html)` — catches most structural issues
+2. Is `window.__timelines[""]` registered? Does the key match `data-composition-id`?
+3. Are GSAP animations only on visual properties (opacity, transform, color)?
+4. Is the GSAP timeline long enough? (`tl.set({}, {}, DURATION)` at the end)
+5. Open browser console — runtime errors show up as `[Browser:ERROR]` or `[Browser:PAGEERROR]`
diff --git a/packages/core/docs/core.md b/packages/core/docs/core.md
new file mode 100644
index 000000000..c1ab6163c
--- /dev/null
+++ b/packages/core/docs/core.md
@@ -0,0 +1,532 @@
+# HyperFrames Schema
+
+Reference for generating and editing HyperFrames HTML compositions. This is your source of truth for how to author compositions.
+
+**New to HyperFrames?** Start with the [quickstart template](./quickstart-template.html) — a copy-paste composition with inline comments explaining every required piece. See [common mistakes](./common-mistakes.md) for pitfalls that break compositions.
+
+For Frame adapters and deterministic frame rendering direction, see [`../../FRAME.md`](../../FRAME.md) and [`../adapters/README.md`](../adapters/README.md).
+
+Producer-canonical parity note:
+
+- Producer render behavior is the source of truth for deterministic parity.
+- Preview should emulate producer seek semantics (`renderSeek`, frame quantization, readiness gates) in parity mode.
+- Non-parity smooth playback can exist, but parity mode is the correctness baseline.
+
+## Overview
+
+HyperFrames uses HTML as the source of truth for describing a video:
+
+- **HTML clips** = video, image, audio, composition
+- **Data attributes** = timing, metadata, styling
+- **CSS** = positioning and appearance
+- **GSAP timeline** = animations and playback sync
+
+### Framework-Managed Behavior
+
+The framework reads data attributes and automatically manages:
+
+- **Primitive clip timeline entries** — the framework reads `data-start`, `data-duration`, and `data-track-index` from primitive clips and adds them to the composition's GSAP timeline. You do not manually add primitive clips to the timeline in scripts.
+- **Media playback** (play, pause, seek) for `` and ``
+- **Clip lifecycle** — clips are **mounted** (made visible on screen) and **unmounted** (removed from screen) based on `data-start` and `data-duration`
+- **Timeline synchronization** (keeping media in sync with the GSAP master timeline)
+- **Media loading** — the framework waits for all media elements to load before resolving timing and starting playback
+
+Mounting and unmounting controls **presence**, not appearance. A clip that is mounted is on screen; a clip that is unmounted is not. Transitions (fade in, slide in, etc.) are separate — they are animated in scripts and happen _after_ a clip is mounted or _before_ it is unmounted.
+
+The framework does **not** handle transitions, effects, or visual animation — those are driven by GSAP in JavaScript.
+
+Do not manually call `video.play()`, `video.pause()`, set `audio.currentTime`, or mount/unmount clips in scripts. The framework owns media playback and clip lifecycle. Animating visual properties like `opacity` or `transform` for transitions is fine — that's what scripts are for.
+
+## Viewport
+
+Every composition must include `data-width` and `data-height` so scripts and CSS can reference concrete pixel dimensions for layout. Common sizes:
+
+- **Landscape**: `data-width="1920" data-height="1080"`
+- **Portrait**: `data-width="1080" data-height="1920"`
+
+e.g.,
+
+```html
+
+
+
+```
+
+Every composition's container is full-screen within the viewport by default. The framework applies full-screen sizing to composition containers automatically.
+
+To position or size individual clips (e.g., picture-in-picture, overlay placement), use standard CSS on the element.
+
+## Compositions
+
+A composition is the fundamental grouping unit in HyperFrames. Every clip — video, image, audio — must live inside a composition. The `index.html` file is itself a composition (the top-level one), and it can contain nested compositions within it. Any composition can be imported into another composition as a sub-composition — there is no special "root" type.
+
+A composition carries the same core attributes as any other clip (`id`, `data-start`, `data-track-index`), so it can be placed and timed on a timeline just like a video or image. A composition's length is determined by its GSAP timeline — there is no `data-duration` on compositions. This means compositions can be nested: a composition clip inside another composition behaves like a self-contained video within the parent timeline.
+
+### Composition File Structure
+
+**Each composition should be defined in its own HTML file.** This keeps compositions modular, reusable, and maintainable. The file contains the complete composition: HTML structure, inline styles, and script.
+
+```
+project/
+├── index.html # Root composition
+├── compositions/
+│ ├── intro-anim.html # Intro animation composition
+│ ├── caption-overlay.html # Caption composition
+│ └── outro-title.html # Outro composition
+```
+
+**Composition file format** (`compositions/intro-anim.html`):
+
+```html
+
+
+
+
Welcome!
+
Let's get started
+
+
+
+
+
+```
+
+### Loading Compositions
+
+Use the `data-composition-src` attribute to load a composition from an external HTML file. The framework will automatically fetch the template and instantiate it:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
` content
+3. Clone and mount it into the composition element
+4. Execute any `
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**Alternative approach** — Inline composition (useful for one-off custom compositions):
+
+```html
+
+
+
+```
+
+### When to create separate compositions
+
+- **Captions**: One composition for all captions, script manages word groups
+- **Emojis/Stickers**: One composition for the emoji layer
+- **Hooks/Titles**: One composition per distinct title sequence
+- **Overlays**: Group related overlays into compositions by purpose
+
+The composition appears in the timeline with its start time and duration (determined by its GSAP timeline). Everything inside is managed by the script but inherits the composition's timeline position.
+
+### Caption discoverability contract
+
+To make caption previews deterministic and easy to isolate in downstream UIs (timeline, mini-player, editor overlays), caption compositions should expose a stable root selector.
+
+Use these attributes on the caption root node:
+
+- `data-timeline-role="captions"` (required)
+- `data-caption-root="true"` (recommended)
+
+Example:
+
+```html
+
+```
+
+## Timeline Contract
+
+The framework initializes `window.__timelines = {}` before any scripts run. Every composition **must** have a script that creates a GSAP timeline and registers it:
+
+```js
+const tl = gsap.timeline({ paused: true });
+// ... add tweens, nested timelines, etc.
+window.__timelines[""] = tl;
+```
+
+### Rules
+
+- **Every composition needs a script** — at minimum, to create and register its timeline. A composition without a script has no timeline and cannot participate in the hierarchy.
+- **All timelines start paused** — create timelines with `{ paused: true }`. The top-level timeline is controlled externally by the frontend player or renderer.
+- **Framework auto-nests sub-timelines** — you do **not** need to manually add sub-composition timelines to the master timeline. The framework automatically nests any timeline registered in `window.__timelines` into its parent based on the composition's `data-start` attribute.
+- **Duration comes from the timeline** — a composition's duration is `tl.duration()`. The timeline is the sole source of truth; there is no `data-duration` on compositions.
+- **Timelines must be finite** — every timeline must have a finite duration. Infinite or indefinite timelines are not supported.
+
+### What NOT to do
+
+```js
+// UNNECESSARY - the framework does this automatically
+if (window.__timelines["captions"]) {
+ masterTL.add(window.__timelines["captions"], 0);
+}
+```
+
+Just register your timeline in `window.__timelines` and the framework handles the rest.
+
+## Output Checklist
+
+- [ ] Every composition has `data-width` and `data-height` attributes
+- [ ] Each reusable composition is in its own HTML file (in `compositions/` directory)
+- [ ] Compositions loaded via `data-composition-src` attribute
+- [ ] Each composition file uses `` tag to wrap its content
+- [ ] `window.__timelines` given all compositions' timelines
+- [ ] Complex/dynamic animations are handled by scripts in compositions
diff --git a/packages/core/docs/core_notes.md b/packages/core/docs/core_notes.md
new file mode 100644
index 000000000..00fc05287
--- /dev/null
+++ b/packages/core/docs/core_notes.md
@@ -0,0 +1,61 @@
+# Core Notes
+
+Extended design rationale and context for decisions in `core.md`. This file is for humans reviewing the design — it is not consumed by the LLM agent.
+
+## Interactive Compositions
+
+### Why `data-start="interactive"`
+
+We considered three alternatives:
+
+1. **`data-interactive` boolean attribute** — Keeps `data-start` clean, but then `data-start` must either be omitted (breaking the convention that every clip has `data-start`) or present but meaningless. Two attributes to express what one value handles.
+
+2. **Event-driven `data-start="on:click:#element"`** — More expressive and extensible to other events (`on:hover`, `on:end:#video`), but complex to parse, harder for an LLM to author correctly, and the trigger/target relationship is declared on the target which reads backwards.
+
+3. **`data-start="interactive"` (chosen)** — Reuses the existing `data-start` attribute with a new keyword value. Reads naturally: "when does this start?" → "interactively." One attribute, no ambiguity, easy to parse (`=== "interactive"` check).
+
+The tradeoff is that `data-start` is now overloaded (was purely numeric/reference, now has a keyword). We accepted this because the parsing is trivial and the readability gain is significant.
+
+### Why `window.__navigate()` instead of `data-goto`
+
+Navigation is behavior, not structure. The framework's philosophy separates these: HTML declares structure and timing, scripts handle behavior.
+
+A `data-goto="composition-id"` attribute on trigger elements would be declarative and concise, but limits what authors can do. With a runtime API, scripts can:
+
+- Add conditional logic (`if (score > 50) navigate('win') else navigate('lose')`)
+- Animate a transition before navigating
+- Add delays or timeouts
+- Chain multiple actions on a single click
+- Use any DOM event, not just clicks
+
+The trigger element is just normal HTML with a normal `addEventListener`. The LLM only needs to know `window.__navigate(id)` — plain JS.
+
+### Navigation Behavior: Replace
+
+When `__navigate()` is called:
+
+1. The currently active composition's timeline pauses
+2. The current composition hides (visibility/display)
+3. The target interactive composition shows
+4. The target's timeline seeks to 0 and plays
+
+We chose Replace (parent hides entirely) over Overlay (target plays on top) or Pause-and-branch (parent pauses, resumes when target ends) because it's the simplest mental model and matches how most interactive video works (YouTube branching, Netflix Bandersnatch).
+
+### Ownership Model
+
+Interactive compositions are children of the composition that branches to them in the DOM tree. The parent composition is the "root" of its branching experience — it owns its branches.
+
+However, `window.__navigate()` resolves composition IDs globally across the full tree, not scoped to the current parent. This means:
+
+- A deeply nested interactive composition can navigate to any other interactive composition by ID
+- A shared "game over" or "credits" composition can be reached from anywhere
+- Circular navigation is possible (A → B → A) — the framework does not prevent loops
+
+### Future Extensions
+
+These are not implemented but the design accommodates them without breaking changes:
+
+- **Overlay mode**: `window.__navigate(id, { mode: 'overlay' })` — target plays on top, parent pauses or continues
+- **History / back**: `window.__navigate('$back')` to return to the previous composition, `window.__navigateHistory` to read the stack
+- **Auto-advance / timeout**: Scripts can implement this today with `setTimeout(() => window.__navigate('default'), 10000)`. A declarative shorthand could be added later.
+- **Pause-and-branch**: `window.__navigate(id, { mode: 'branch' })` — parent pauses, resumes when target ends
diff --git a/packages/core/docs/quickstart-template.html b/packages/core/docs/quickstart-template.html
new file mode 100644
index 000000000..32fbf6a3a
--- /dev/null
+++ b/packages/core/docs/quickstart-template.html
@@ -0,0 +1,180 @@
+
+
+
+ My Video
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Hello World
+
+
` and ``
+- **Clip lifecycle** — clips are **mounted** (made visible on screen) and **unmounted** (removed from screen) based on `data-start` and `data-duration`
+- **Timeline synchronization** (keeping media in sync with the GSAP master timeline)
+- **Media loading** — the framework waits for all media elements to load before resolving timing and starting playback
+
+Mounting and unmounting controls **presence**, not appearance. A clip that is mounted is on screen; a clip that is unmounted is not. Transitions (fade in, slide in, etc.) are separate — they are animated in scripts and happen _after_ a clip is mounted or _before_ it is unmounted.
+
+The framework does **not** handle transitions, effects, or visual animation — those are driven by GSAP in JavaScript.
+
+Do not manually call `video.play()`, `video.pause()`, set `audio.currentTime`, or mount/unmount clips in scripts. The framework owns media playback and clip lifecycle. Animating visual properties like `opacity` or `transform` for transitions is fine — that's what scripts are for.
+
+## Viewport
+
+The root composition must declare its intended render dimensions using `data-width` and `data-height` attributes. Common sizes:
+
+- **Landscape**: `data-width="1920" data-height="1080"`
+- **Portrait**: `data-width="1080" data-height="1920"`
+
+e.g.,
+
+```html
+
+
+
+```
+
+Every composition's container is full-screen within the viewport by default. The framework applies full-screen sizing to composition containers automatically.
+
+To position or size individual clips (e.g., picture-in-picture, overlay placement), use standard CSS on the element.
+
+## Compositions
+
+A composition is the fundamental grouping unit in HyperFrames. Every clip — video, image, audio — must live inside a composition. The `index.html` file is itself a composition (the top-level one), and it can contain nested compositions within it. Any composition can be imported into another composition as a sub-composition — there is no special "root" type.
+
+A composition carries the same core attributes as any other clip (`id`, `data-start`, `data-track-index`), so it can be placed and timed on a timeline just like a video or image. A composition's length is determined by its GSAP timeline — there is no `data-duration` on compositions. This means compositions can be nested: a composition clip inside another composition behaves like a self-contained video within the parent timeline.
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
` — Video clips, B-roll, A-roll
+- `` — Music, sound effects
+- `` — Nested compositions (animations, grouped sequences)
+
+## HTML Attributes
+
+### All Clips
+
+- `id` — Unique identifier (e.g., "el-1")
+- `data-start` — Start time in seconds, or a clip `id` reference. See [Relative Timing](#relative-timing).
+- `data-duration` — Duration in seconds. Required for `
` clips. Optional for `
` and `` (defaults to the source media's full duration). Not used on compositions.
+- `data-track-index` — Timeline track number. Tracks serve two purposes: they determine visual layering (higher tracks render in front) and they group clips into rows on the timeline. Clips on the same track **cannot overlap in time**.
+
+### Media Clips (video, audio)
+
+- `data-media-start` — (optional) Playback begins at this time in the source file, in seconds. Defaults to `0`.
+
+### Composition Clips
+
+- `data-composition-id` — Unique composition ID
+
+> Compositions do **not** use `data-duration`. Their duration is determined by their GSAP timeline.
+
+## Relative Timing
+
+Instead of calculating absolute start times, a clip can reference another clip's `id` in its `data-start` attribute. This means "start when that clip ends." The referenced clip must be in the same composition and must have a known duration (either an explicit `data-duration` or an inferred duration from the source media).
+
+### Basic Sequential Clips
+
+```html
+`, ` + `, or ` - `
+
+## Video Clips
+
+Full-screen or positioned video clips. Videos sync their playback to the timeline position.
+
+```html
+
+
+
+```
+
+Inline scripts are fine when the script belongs to that composition. The JS file itself is the documentation for what a composition does — the schema doesn't need to describe its internals.
+
+The only required file is `index.html`. Every composition must have at least a script to create and register its GSAP timeline.
+
+### Top-Level Composition
+
+The top-level composition is the `index.html` entry point. It acts as the conductor — sequencing clips and placing sub-composition timelines into an overall master timeline. It can technically do anything in its script, but its primary purpose is high-level orchestration. Any composition can serve as a top-level composition or be nested into another — there is no structural difference.
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
"] = tl;
+```
+
+### Rules
+
+- **Every composition needs a script** — at minimum, to create and register its timeline. A composition without a script has no timeline and cannot participate in the hierarchy.
+- **All timelines start paused** — create timelines with `{ paused: true }`. The top-level timeline is controlled externally by the frontend player or renderer.
+- **Framework auto-nests sub-timelines** — you do **not** need to manually add sub-composition timelines to the master timeline. The framework automatically nests any timeline registered in `window.__timelines` into its parent based on the composition's `data-start` attribute.
+- **Duration comes from the timeline** — a composition's duration is `tl.duration()`. The timeline is the sole source of truth; there is no `data-duration` on compositions.
+
+### What NOT to do
+
+```js
+// UNNECESSARY - the framework does this automatically
+if (window.__timelines["captions"]) {
+ masterTL.add(window.__timelines["captions"], 0);
+}
+```
+
+Just register your timeline in `window.__timelines` and the framework handles the rest.
+
+## Output Checklist
+
+- [ ] Root composition has `data-width` and `data-height` attributes
+- [ ] `window.__timelines` given all compositions' timelines
+- [ ] Complex/dynamic animations are handled by scripts in compositions
diff --git a/packages/core/package.json b/packages/core/package.json
new file mode 100644
index 000000000..92590801d
--- /dev/null
+++ b/packages/core/package.json
@@ -0,0 +1,83 @@
+{
+ "name": "@hyperframes/core",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "exports": {
+ ".": {
+ "import": "./src/index.ts",
+ "types": "./src/index.ts"
+ },
+ "./lint": {
+ "import": "./src/lint/index.ts",
+ "types": "./src/lint/index.ts"
+ },
+ "./compiler": {
+ "import": "./src/compiler/index.ts",
+ "types": "./src/compiler/index.ts"
+ },
+ "./runtime": "./dist/hyperframe.runtime.iife.js"
+ },
+ "files": [
+ "dist",
+ "docs",
+ "README.md"
+ ],
+ "publishConfig": {
+ "access": "public",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "import": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+ },
+ "./lint": {
+ "import": "./dist/lint/index.js",
+ "types": "./dist/lint/index.d.ts"
+ },
+ "./compiler": {
+ "import": "./dist/compiler/index.js",
+ "types": "./dist/compiler/index.d.ts"
+ },
+ "./runtime": "./dist/hyperframe.runtime.iife.js"
+ }
+ },
+ "scripts": {
+ "build": "tsc && pnpm build:hyperframes-runtime",
+ "test": "vitest run",
+ "test:watch": "vitest",
+ "test:coverage": "vitest run --coverage",
+ "typecheck": "tsc --noEmit",
+ "lint:runtime-preview-guards": "tsx scripts/lint-runtime-preview-guards.ts",
+ "build:hyperframes-runtime": "tsx scripts/build-hyperframes-runtime-artifact.ts",
+ "build:hyperframes-runtime:modular": "SANDBOX_RUNTIME_VARIANT=modular tsx scripts/build-hyperframes-runtime-artifact.ts",
+ "build:hyperframe-runtime": "tsx scripts/build-hyperframes-runtime-artifact.ts",
+
+ "test:hyperframe-runtime-contract": "tsx scripts/test-hyperframe-runtime-contract.ts",
+ "test:hyperframe-runtime-behavior": "tsx scripts/test-hyperframe-runtime-behavior.ts",
+ "test:hyperframe-runtime-seek": "tsx scripts/test-hyperframe-runtime-seek.ts",
+ "test:hyperframe-runtime-duration-guards": "tsx scripts/test-hyperframe-runtime-duration-guards.ts",
+ "test:hyperframe-runtime-parity": "tsx scripts/test-hyperframe-runtime-parity.ts",
+ "test:hyperframe-runtime-security": "tsx scripts/test-hyperframe-runtime-security.ts",
+ "test:hyperframe-linter": "tsx scripts/test-hyperframe-linter.ts",
+ "test:hyperframe-runtime-ci": "pnpm build:hyperframes-runtime && pnpm test:hyperframe-runtime-contract && pnpm test:hyperframe-runtime-behavior && pnpm test:hyperframe-runtime-seek && pnpm test:hyperframe-runtime-duration-guards && pnpm test:hyperframe-runtime-parity && pnpm test:hyperframe-runtime-security",
+ "check:hyperframe-html": "tsx scripts/check-hyperframe-static.ts",
+ "debug:timeline": "tsx scripts/debug-timeline.ts",
+ "prepublishOnly": "pnpm build"
+ },
+ "optionalDependencies": {
+ "cheerio": "^1.2.0",
+ "esbuild": "^0.25.12"
+ },
+ "devDependencies": {
+ "@types/jsdom": "^28.0.0",
+ "@types/node": "^24.10.13",
+ "@vitest/coverage-v8": "^3.2.4",
+ "jsdom": "^29.0.0",
+ "tsx": "^4.21.0",
+ "typescript": "^5.0.0",
+ "vitest": "^3.2.4"
+ }
+}
diff --git a/packages/core/scripts/build-hyperframes-runtime-artifact.ts b/packages/core/scripts/build-hyperframes-runtime-artifact.ts
new file mode 100644
index 000000000..bf556cfc1
--- /dev/null
+++ b/packages/core/scripts/build-hyperframes-runtime-artifact.ts
@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildSync } from "esbuild";
+import {
+ HYPERFRAME_RUNTIME_ARTIFACTS,
+ HYPERFRAME_RUNTIME_CONTRACT,
+ loadHyperframeRuntimeSource,
+} from "../src/inline-scripts/hyperframe";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const distDir = resolve(thisDir, "../dist");
+const iifePath = resolve(distDir, HYPERFRAME_RUNTIME_ARTIFACTS.iife);
+const esmPath = resolve(distDir, HYPERFRAME_RUNTIME_ARTIFACTS.esm);
+const manifestPath = resolve(distDir, HYPERFRAME_RUNTIME_ARTIFACTS.manifest);
+
+const runtimeSource = `${loadHyperframeRuntimeSource()}\n`;
+const runtimeSha256 = createHash("sha256").update(runtimeSource, "utf8").digest("hex");
+const buildId = process.env.HYPERFRAME_RUNTIME_BUILD_ID?.trim() || "dev";
+const runtimeEntryPath = resolve(thisDir, "../src/runtime/entry.ts");
+const esmBuild = buildSync({
+ entryPoints: [runtimeEntryPath],
+ bundle: true,
+ write: false,
+ platform: "browser",
+ format: "esm",
+ target: ["es2020"],
+ minify: true,
+ legalComments: "none",
+});
+const esmSource = `${esmBuild.outputFiles[0]?.text ?? ""}\n`;
+
+const manifest = {
+ version: process.env.HYPERFRAME_RUNTIME_VERSION?.trim() || "0.1.0",
+ buildId,
+ sha256: runtimeSha256,
+ artifacts: {
+ iife: HYPERFRAME_RUNTIME_ARTIFACTS.iife,
+ esm: HYPERFRAME_RUNTIME_ARTIFACTS.esm,
+ },
+ contract: HYPERFRAME_RUNTIME_CONTRACT,
+};
+
+mkdirSync(distDir, { recursive: true });
+writeFileSync(iifePath, runtimeSource, "utf8");
+writeFileSync(esmPath, esmSource, "utf8");
+writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_artifacts_generated",
+ buildId,
+ distDir,
+ iifePath,
+ esmPath,
+ manifestPath,
+ sourceBytes: Buffer.byteLength(runtimeSource, "utf8"),
+ esmBytes: Buffer.byteLength(esmSource, "utf8"),
+ sha256: runtimeSha256,
+ }),
+);
diff --git a/packages/core/scripts/check-hyperframe-static.ts b/packages/core/scripts/check-hyperframe-static.ts
new file mode 100644
index 000000000..6fc4b0a54
--- /dev/null
+++ b/packages/core/scripts/check-hyperframe-static.ts
@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { lintHyperframeHtml } from "../src/lint/hyperframeLinter";
+import type { HyperframeLintResult } from "../src/lint/types";
+
+function formatHumanOutput(result: HyperframeLintResult, resolvedPath: string): string {
+ const lines = [
+ result.ok
+ ? `PASS ${resolvedPath} (${result.warningCount} warning${result.warningCount === 1 ? "" : "s"})`
+ : `FAIL ${resolvedPath} (${result.errorCount} error${result.errorCount === 1 ? "" : "s"}, ${result.warningCount} warning${result.warningCount === 1 ? "" : "s"})`,
+ ];
+
+ for (const finding of result.findings) {
+ lines.push(`- [${finding.severity.toUpperCase()}] ${finding.code}: ${finding.message}`);
+ if (finding.selector) {
+ lines.push(` selector: ${finding.selector}`);
+ }
+ if (finding.elementId) {
+ lines.push(` elementId: ${finding.elementId}`);
+ }
+ if (finding.fixHint) {
+ lines.push(` fix: ${finding.fixHint}`);
+ }
+ }
+
+ return lines.join("\n");
+}
+
+function main() {
+ const args = process.argv.slice(2);
+ const normalizedArgs = args[0] === "--" ? args.slice(1) : args;
+ const jsonOutput = normalizedArgs.includes("--json");
+ const positionalArgs = normalizedArgs.filter((arg) => arg !== "--json");
+ const inputPath = positionalArgs[0];
+ if (!inputPath) {
+ console.error(
+ "Usage: pnpm check:hyperframe-html [--json] \nExample: pnpm check:hyperframe-html core/src/tests/broken-video.html",
+ );
+ process.exit(2);
+ }
+
+ const resolvedPath = path.resolve(process.cwd(), inputPath);
+ if (!fs.existsSync(resolvedPath)) {
+ console.error(`File not found: ${resolvedPath}`);
+ process.exit(2);
+ }
+
+ const html = fs.readFileSync(resolvedPath, "utf-8");
+ const result = lintHyperframeHtml(html, { filePath: resolvedPath });
+
+ if (jsonOutput) {
+ console.log(JSON.stringify(result, null, 2));
+ process.exit(result.ok ? 0 : 1);
+ }
+
+ if (result.ok) {
+ console.log(formatHumanOutput(result, resolvedPath));
+ process.exit(0);
+ }
+
+ console.error(formatHumanOutput(result, resolvedPath));
+ process.exit(1);
+}
+
+main();
diff --git a/packages/core/scripts/debug-timeline.ts b/packages/core/scripts/debug-timeline.ts
new file mode 100644
index 000000000..4a5cd48ae
--- /dev/null
+++ b/packages/core/scripts/debug-timeline.ts
@@ -0,0 +1,297 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type AttrMap = Record;
+
+type ParsedTag = {
+ tagName: string;
+ attrs: AttrMap;
+ raw: string;
+};
+
+type TimelineClip = {
+ id: string | null;
+ label: string;
+ start: number;
+ duration: number;
+ track: number;
+ kind: "video" | "audio" | "image" | "element";
+ tagName: string | null;
+ compositionId: string | null;
+ compositionSrc: string | null;
+ assetUrl: string | null;
+ durationSource: "deterministic" | "fallback";
+};
+
+type TimelinePayload = {
+ source: "hf-preview";
+ type: "timeline";
+ durationInFrames: number;
+ clips: TimelineClip[];
+ scenes: [];
+ compositionWidth: number;
+ compositionHeight: number;
+};
+
+function parseNum(value: string | null | undefined): number | null {
+ if (value == null) return null;
+ const parsed = Number.parseFloat(String(value));
+ return Number.isFinite(parsed) ? parsed : null;
+}
+
+function parseArgs() {
+ const args = process.argv.slice(2);
+ const normalizedArgs = args[0] === "--" ? args.slice(1) : args;
+ const inputPath = normalizedArgs[0];
+ let forcedFps: number | null = null;
+ let forcedMaxDuration: number | null = null;
+ for (let i = 1; i < normalizedArgs.length; i += 1) {
+ const arg = normalizedArgs[i];
+ if (arg === "--fps" && normalizedArgs[i + 1]) {
+ forcedFps = parseNum(normalizedArgs[i + 1]);
+ i += 1;
+ continue;
+ }
+ if (arg === "--max-duration" && normalizedArgs[i + 1]) {
+ forcedMaxDuration = parseNum(normalizedArgs[i + 1]);
+ i += 1;
+ }
+ }
+ return { inputPath, forcedFps, forcedMaxDuration };
+}
+
+function parseAttributes(rawAttrs: string): AttrMap {
+ const attrs: AttrMap = {};
+ const attrRegex = /([^\s=/>]+)\s*=\s*("([^"]*)"|'([^']*)'|([^\s>]+))/g;
+ let match: RegExpExecArray | null = null;
+ while (true) {
+ match = attrRegex.exec(rawAttrs);
+ if (!match) break;
+ const key = match[1];
+ const value = match[3] ?? match[4] ?? match[5] ?? "";
+ attrs[key] = value;
+ }
+ return attrs;
+}
+
+function parseTags(html: string): ParsedTag[] {
+ const tags: ParsedTag[] = [];
+ const tagRegex = /<([a-zA-Z][\w:-]*)([^>]*)>/g;
+ let match: RegExpExecArray | null = null;
+ while (true) {
+ match = tagRegex.exec(html);
+ if (!match) break;
+ const raw = match[0];
+ if (raw.startsWith(" 0 ? fallbackDuration : 0;
+ const safeRaw = rawDuration != null && Number.isFinite(rawDuration) && rawDuration > 0 ? rawDuration : 0;
+ if (safeRaw > 0) return Math.min(safeRaw, maxDuration);
+ if (safeFallback > 0) return Math.min(safeFallback, maxDuration);
+ return 0;
+}
+
+function shouldIncludeTimelineNode(tag: ParsedTag, rootCompositionId: string | null): boolean {
+ const attrs = tag.attrs;
+ if (attrs["data-composition-id"] && rootCompositionId && attrs["data-composition-id"] === rootCompositionId) {
+ return false;
+ }
+ if (tag.tagName === "script" || tag.tagName === "style" || tag.tagName === "link" || tag.tagName === "meta") {
+ return false;
+ }
+ if ((attrs.class || "").split(/\s+/).includes("__preview_render_frame__")) return false;
+ if (attrs["data-start"] != null) return true;
+ if (attrs["data-track-index"] != null) return true;
+ if (attrs["data-composition-src"] != null) return true;
+ if (attrs["data-composition-id"] != null) return true;
+ return tag.tagName === "video" || tag.tagName === "audio" || tag.tagName === "img";
+}
+
+function inferClipDuration(tag: ParsedTag, start: number, maxDuration: number): number | null {
+ const attrs = tag.attrs;
+ const durationAttr = parseNum(attrs["data-duration"]);
+ if (durationAttr != null && durationAttr > 0) return normalizeDurationSeconds(durationAttr, null, maxDuration);
+
+ const endAttr = parseNum(attrs["data-end"]);
+ if (endAttr != null && endAttr > start) {
+ return normalizeDurationSeconds(endAttr - start, null, maxDuration);
+ }
+
+ if (tag.tagName === "video" || tag.tagName === "audio") {
+ const sourceDuration = parseNum(attrs["data-source-duration"]);
+ const playbackStart = parseNum(attrs["data-playback-start"]) ?? parseNum(attrs["data-playbackStart"]) ?? 0;
+ if (sourceDuration != null && sourceDuration > 0) {
+ return normalizeDurationSeconds(Math.max(0, sourceDuration - playbackStart), null, maxDuration);
+ }
+ }
+
+ if (attrs["data-composition-id"]) {
+ const sourceDuration = parseNum(attrs["data-source-duration"]);
+ if (sourceDuration != null && sourceDuration > 0) {
+ return normalizeDurationSeconds(sourceDuration, null, maxDuration);
+ }
+ }
+
+ return null;
+}
+
+function resolveNodeAssetUrl(tag: ParsedTag): string | null {
+ const attrs = tag.attrs;
+ return (
+ attrs.src ??
+ attrs["data-src"] ??
+ attrs["data-asset-src"] ??
+ attrs["data-video-src"] ??
+ attrs["data-image-src"] ??
+ null
+ );
+}
+
+function resolveRootTag(tags: ParsedTag[]): ParsedTag | null {
+ const explicitRoot = tags.find((tag) => tag.attrs["data-composition-id"] === "master");
+ if (explicitRoot) return explicitRoot;
+ return tags.find((tag) => tag.attrs["data-composition-id"] != null) ?? null;
+}
+
+function main() {
+ const { inputPath, forcedFps, forcedMaxDuration } = parseArgs();
+ if (!inputPath) {
+ console.error("Usage: pnpm debug:timeline [--fps 30] [--max-duration 1800]");
+ process.exit(2);
+ }
+
+ const resolvedPath = path.resolve(process.cwd(), inputPath);
+ if (!fs.existsSync(resolvedPath)) {
+ console.error(`File not found: ${resolvedPath}`);
+ process.exit(2);
+ }
+
+ const html = fs.readFileSync(resolvedPath, "utf-8");
+ const tags = parseTags(html);
+ const root = resolveRootTag(tags);
+ const rootCompositionId = root?.attrs["data-composition-id"] ?? null;
+
+ const maxDuration =
+ (forcedMaxDuration != null && forcedMaxDuration > 0
+ ? forcedMaxDuration
+ : extractWindowNumber(html, "window.__HF_MAX_DURATION_SEC")) ?? 1800;
+ const canonicalFps =
+ (forcedFps != null && forcedFps > 0
+ ? forcedFps
+ : (parseNum(root?.attrs["data-fps"]) ?? extractWindowNumber(html, "window.__HF_FPS"))) ?? 30;
+
+ const rootDurationRaw =
+ parseNum(root?.attrs["data-composition-duration"]) ??
+ parseNum(root?.attrs["data-duration"]) ??
+ parseNum(tags.find((tag) => tag.tagName === "html")?.attrs["data-composition-duration"] ?? null);
+ const rootDuration = normalizeDurationSeconds(rootDurationRaw, null, maxDuration);
+
+ const nodes = tags.filter((tag) => shouldIncludeTimelineNode(tag, rootCompositionId));
+ const clips: TimelineClip[] = [];
+ let maxEnd = 0;
+ let unresolvedClipCount = 0;
+
+ for (let i = 0; i < nodes.length; i += 1) {
+ const node = nodes[i];
+ const attrs = node.attrs;
+ const start = Math.max(0, parseNum(attrs["data-start"]) ?? 0);
+ const inferredDuration = inferClipDuration(node, start, maxDuration);
+ const hasDeterministicDuration = inferredDuration != null && inferredDuration > 0;
+ let duration = hasDeterministicDuration ? normalizeDurationSeconds(inferredDuration, 0, maxDuration) : 0;
+ let durationSource: "deterministic" | "fallback" = "deterministic";
+ if (duration <= 0 && rootDuration > start) {
+ duration = normalizeDurationSeconds(rootDuration - start, 0, maxDuration);
+ durationSource = "fallback";
+ }
+ if (duration <= 0) {
+ unresolvedClipCount += 1;
+ continue;
+ }
+ if (hasDeterministicDuration) {
+ const end = start + duration;
+ if (end > maxEnd) maxEnd = end;
+ }
+ const kind =
+ node.tagName === "video"
+ ? "video"
+ : node.tagName === "audio"
+ ? "audio"
+ : node.tagName === "img"
+ ? "image"
+ : "element";
+ const trackRaw = parseNum(attrs["data-track-index"]);
+ const track = trackRaw != null && Number.isFinite(trackRaw) ? Math.floor(trackRaw) : i;
+ clips.push({
+ id: attrs.id ?? null,
+ label: attrs["data-label"] ?? attrs["aria-label"] ?? attrs.id ?? kind,
+ start,
+ duration,
+ track,
+ kind,
+ tagName: node.tagName || null,
+ compositionId: attrs["data-composition-id"] ?? null,
+ compositionSrc: attrs["data-composition-src"] ?? null,
+ assetUrl: resolveNodeAssetUrl(node),
+ durationSource,
+ });
+ }
+
+ let effectiveDuration = 0;
+ if (maxEnd > 0) effectiveDuration = normalizeDurationSeconds(maxEnd, 0, maxDuration);
+ if (effectiveDuration <= 0) effectiveDuration = normalizeDurationSeconds(rootDuration, 1, maxDuration);
+ if (effectiveDuration <= 0) effectiveDuration = 1;
+
+ const compositionWidth = parseNum(root?.attrs["data-width"]) ?? 1920;
+ const compositionHeight = parseNum(root?.attrs["data-height"]) ?? 1080;
+ const payload: TimelinePayload = {
+ source: "hf-preview",
+ type: "timeline",
+ durationInFrames: Math.max(1, Math.round(effectiveDuration * canonicalFps)),
+ clips,
+ scenes: [],
+ compositionWidth,
+ compositionHeight,
+ };
+
+ const output = {
+ file: resolvedPath,
+ debug: {
+ canonicalFps,
+ maxDurationSeconds: maxDuration,
+ rootCompositionId,
+ rootDurationSeconds: rootDuration,
+ deterministicMaxEndSeconds: maxEnd,
+ effectiveDurationSeconds: effectiveDuration,
+ unresolvedClipCount,
+ clipCount: clips.length,
+ },
+ payload,
+ };
+
+ console.log(JSON.stringify(output, null, 2));
+}
+
+main();
diff --git a/packages/core/scripts/lint-runtime-preview-guards.ts b/packages/core/scripts/lint-runtime-preview-guards.ts
new file mode 100644
index 000000000..fdfc48155
--- /dev/null
+++ b/packages/core/scripts/lint-runtime-preview-guards.ts
@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+
+type GuardSpec = {
+ id: string;
+ description: string;
+ filePath: string;
+ pattern: RegExp;
+};
+
+type GuardCheckResult = {
+ passed: GuardSpec[];
+ failed: GuardSpec[];
+};
+
+const GUARD_SPECS: GuardSpec[] = [
+ {
+ id: "external_compositions_gate",
+ description: "Do not bind timelines before external compositions are loaded",
+ filePath: "src/runtime/init.ts",
+ pattern: /if\s*\(\s*!externalCompositionsReady\s*\)\s*return\s+false;/,
+ },
+ {
+ id: "usable_timeline_gate",
+ description: "Skip rebinding when current timeline is already usable",
+ filePath: "src/runtime/init.ts",
+ pattern: /if\s*\(\s*currentTimeline\s*&&\s*currentTimelineUsable\s*\)\s*return\s+false;/,
+ },
+ {
+ id: "child_timeline_activation",
+ description: "Force root child timelines active before composition binding",
+ filePath: "src/runtime/init.ts",
+ pattern: /timelineWithPaused\.paused\(false\)/,
+ },
+ {
+ id: "root_unusable_fallback",
+ description: "Fallback to composite timeline when root duration is unusable",
+ filePath: "src/runtime/init.ts",
+ pattern:
+ /if\s*\(\s*!isUsableTimelineDuration\(rootDurationSeconds\)\s*&&\s*rootChildCandidates\.length\s*>\s*0\s*\)/,
+ },
+ {
+ id: "loop_guard_rebind",
+ description: "Enable loop guard based timeline rebinding",
+ filePath: "src/runtime/init.ts",
+ pattern: /if\s*\(\s*rebindTimelineFromResolution\(resolution,\s*"loop_guard"\)\s*\)/,
+ },
+ {
+ id: "early_play_rebind_hold",
+ description: "Hold rebinding during first playback seconds",
+ filePath: "src/runtime/init.ts",
+ pattern: /shouldHoldRebindDuringEarlyPlay/,
+ },
+ {
+ id: "external_script_ordering",
+ description: "Inject external composition scripts with deterministic ordering",
+ filePath: "src/runtime/compositionLoader.ts",
+ pattern: /injectedScript\.async\s*=\s*false;/,
+ },
+ {
+ id: "external_script_load_wait",
+ description: "Await external composition script load before continuing",
+ filePath: "src/runtime/compositionLoader.ts",
+ pattern: /await\s+waitForExternalScriptLoad\(injectedScript\);/,
+ },
+];
+
+function resolveFilePath(relativePath: string): string {
+ return path.resolve(process.cwd(), relativePath);
+}
+
+function checkGuards(guards: GuardSpec[]): GuardCheckResult {
+ const passed: GuardSpec[] = [];
+ const failed: GuardSpec[] = [];
+
+ for (const guard of guards) {
+ const absolutePath = resolveFilePath(guard.filePath);
+ if (!fs.existsSync(absolutePath)) {
+ failed.push(guard);
+ continue;
+ }
+ const content = fs.readFileSync(absolutePath, "utf8");
+ if (guard.pattern.test(content)) {
+ passed.push(guard);
+ } else {
+ failed.push(guard);
+ }
+ }
+
+ return { passed, failed };
+}
+
+function main(): void {
+ const result = checkGuards(GUARD_SPECS);
+ if (result.failed.length === 0) {
+ console.log(
+ JSON.stringify({
+ event: "runtime_preview_guards_lint_passed",
+ checkedGuards: GUARD_SPECS.length,
+ }),
+ );
+ return;
+ }
+
+ console.error(
+ JSON.stringify({
+ event: "runtime_preview_guards_lint_failed",
+ checkedGuards: GUARD_SPECS.length,
+ missingGuards: result.failed.map((guard) => ({
+ id: guard.id,
+ filePath: guard.filePath,
+ description: guard.description,
+ })),
+ }),
+ );
+ process.exit(1);
+}
+
+main();
diff --git a/packages/core/scripts/test-hyperframe-linter.ts b/packages/core/scripts/test-hyperframe-linter.ts
new file mode 100644
index 000000000..6aa488c55
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-linter.ts
@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { lintHyperframeHtml } from "../src/lint/hyperframeLinter";
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+function testCleanFixturePasses() {
+ const fixturePath = path.join(ROOT, "src/tests/chat-project-9/index.html");
+ const html = fs.readFileSync(fixturePath, "utf8");
+ const result = lintHyperframeHtml(html, { filePath: fixturePath });
+
+ assert.equal(result.ok, true, "chat-project-9 should pass without lint errors");
+ assert.equal(result.errorCount, 0, "chat-project-9 should have zero lint errors");
+}
+
+function testDetectsMissingCompositionHostId() {
+ const html = `
+
+
+
+
+
+
+ `;
+
+ const result = lintHyperframeHtml(html);
+ const codes = result.findings.map((finding) => finding.code);
+
+ assert.equal(result.ok, false, "missing composition ids should fail lint");
+ assert.ok(codes.includes("root_missing_composition_id"));
+ assert.ok(codes.includes("host_missing_composition_id"));
+}
+
+function testDetectsOverlappingGsapTweens() {
+ const html = `
+
+
+
+
+
+
+ `;
+
+ const result = lintHyperframeHtml(html);
+ const overlapFinding = result.findings.find((finding) => finding.code === "overlapping_gsap_tweens");
+
+ assert.ok(overlapFinding, "expected an overlapping GSAP tween warning");
+ assert.equal(overlapFinding?.severity, "warning");
+}
+
+function testCliJsonOutput() {
+ const fixturePath = path.join(ROOT, "src/tests/chat-project-9/index.html");
+ const tsxBin = path.join(ROOT, "node_modules/.bin/tsx");
+ const stdout = execFileSync(tsxBin, ["scripts/check-hyperframe-static.ts", "--json", fixturePath], {
+ cwd: ROOT,
+ encoding: "utf8",
+ });
+ const payload = JSON.parse(stdout);
+
+ assert.equal(payload.ok, true);
+ assert.equal(typeof payload.errorCount, "number");
+ assert.ok(Array.isArray(payload.findings));
+}
+
+function main() {
+ testCleanFixturePasses();
+ testDetectsMissingCompositionHostId();
+ testDetectsOverlappingGsapTweens();
+ testCliJsonOutput();
+ console.log("hyperframe linter tests passed");
+}
+
+main();
diff --git a/packages/core/scripts/test-hyperframe-runtime-behavior.ts b/packages/core/scripts/test-hyperframe-runtime-behavior.ts
new file mode 100644
index 000000000..0ac5325f9
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-runtime-behavior.ts
@@ -0,0 +1,32 @@
+import { buildHyperframesRuntimeScript } from "../src/inline-scripts/hyperframesRuntime.engine";
+
+function assert(condition: unknown, message: string): void {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+const baseline = buildHyperframesRuntimeScript();
+const parityEnabled = buildHyperframesRuntimeScript({ defaultParityMode: true });
+const parityDisabled = buildHyperframesRuntimeScript({ defaultParityMode: false });
+const withSourceUrl = buildHyperframesRuntimeScript({
+ sourceUrl: "hyperframe.runtime.iife.js",
+});
+
+assert(baseline.includes("window.__player"), "Baseline runtime should include player contract");
+assert(parityEnabled.length > 0, "Parity-enabled build should produce non-empty runtime source");
+assert(parityDisabled.length > 0, "Parity-disabled build should produce non-empty runtime source");
+assert(
+ withSourceUrl.includes("//# sourceURL=hyperframe.runtime.iife.js"),
+ "Build with sourceUrl should append sourceURL comment",
+);
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_behavior_verified",
+ baselineBytes: baseline.length,
+ parityEnabledBytes: parityEnabled.length,
+ parityDisabledBytes: parityDisabled.length,
+ sourceUrlBytes: withSourceUrl.length,
+ }),
+);
diff --git a/packages/core/scripts/test-hyperframe-runtime-contract.ts b/packages/core/scripts/test-hyperframe-runtime-contract.ts
new file mode 100644
index 000000000..949cdfa75
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-runtime-contract.ts
@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadHyperframeRuntimeSource } from "../src/inline-scripts/hyperframe";
+
+function assert(condition: unknown, message: string): void {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+const runtimeSource = loadHyperframeRuntimeSource();
+
+const requiredSnippets = [
+ "window.__player",
+ "window.__playerReady",
+ "window.__renderReady",
+ "hf-preview",
+ "hf-parent",
+ "renderSeek",
+];
+
+for (const snippet of requiredSnippets) {
+ assert(runtimeSource.includes(snippet), `Runtime contract snippet missing: ${snippet}`);
+}
+
+const scriptDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
+const manifestPath = resolve(scriptDir, "../dist/hyperframe.manifest.json");
+try {
+ const manifestRaw = readFileSync(manifestPath, "utf8");
+ const manifest = JSON.parse(manifestRaw) as { artifacts?: { iife?: string; esm?: string } };
+ assert(Boolean(manifest.artifacts?.iife), "Manifest is missing iife artifact");
+ assert(Boolean(manifest.artifacts?.esm), "Manifest is missing esm artifact");
+} catch {
+ // Build may not have run yet; contract-only checks above still provide signal.
+}
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_contract_verified",
+ requiredSnippetsChecked: requiredSnippets.length,
+ }),
+);
diff --git a/packages/core/scripts/test-hyperframe-runtime-duration-guards.ts b/packages/core/scripts/test-hyperframe-runtime-duration-guards.ts
new file mode 100644
index 000000000..55c1e6df9
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-runtime-duration-guards.ts
@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function assert(condition: unknown, message: string): void {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const initPath = resolve(scriptDir, "../src/runtime/init.ts");
+const timelinePath = resolve(scriptDir, "../src/runtime/timeline.ts");
+
+const initSource = readFileSync(initPath, "utf8");
+const timelineSource = readFileSync(timelinePath, "utf8");
+
+// Guard against regressions where preview duration gets capped by earliest video.
+assert(!initSource.includes("resolveMainVideoDurationSeconds"), "init.ts should not use first-video duration helper");
+assert(
+ !initSource.includes("Math.max(0, Math.min(safeDuration, mediaFloor))"),
+ "init.ts should not hard-clamp safe duration to media floor",
+);
+assert(
+ initSource.includes("resolveMediaWindowDurationSeconds"),
+ "init.ts should compute media window duration across timed media",
+);
+
+// Timeline payload windowing should also avoid first-video truncation.
+assert(
+ !timelineSource.includes("resolveMainVideoWindowEndSeconds"),
+ "timeline.ts should not use first-video window end helper",
+);
+assert(
+ timelineSource.includes("resolveMediaWindowEndSeconds"),
+ "timeline.ts should compute media window end across timed media",
+);
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_duration_guards_verified",
+ initPath,
+ timelinePath,
+ }),
+);
diff --git a/packages/core/scripts/test-hyperframe-runtime-parity.ts b/packages/core/scripts/test-hyperframe-runtime-parity.ts
new file mode 100644
index 000000000..e2804b6e0
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-runtime-parity.ts
@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HYPERFRAME_RUNTIME_ARTIFACTS } from "../src/inline-scripts/hyperframe";
+
+function assert(condition: unknown, message: string): void {
+ if (!condition) throw new Error(message);
+}
+
+const scriptsDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
+const distDir = resolve(scriptsDir, "../dist");
+const iifePath = resolve(distDir, HYPERFRAME_RUNTIME_ARTIFACTS.iife);
+const manifestPath = resolve(distDir, HYPERFRAME_RUNTIME_ARTIFACTS.manifest);
+
+const iifeSource = readFileSync(iifePath, "utf8");
+const manifestRaw = readFileSync(manifestPath, "utf8");
+const manifest = JSON.parse(manifestRaw) as {
+ sha256?: string;
+ artifacts?: { iife?: string; esm?: string };
+};
+
+assert(iifeSource.length > 0, "IIFE runtime artifact is empty");
+assert(
+ manifest.artifacts?.iife === HYPERFRAME_RUNTIME_ARTIFACTS.iife,
+ "Manifest iife artifact name is not strict expected value",
+);
+assert(
+ manifest.artifacts?.esm === HYPERFRAME_RUNTIME_ARTIFACTS.esm,
+ "Manifest esm artifact name is not strict expected value",
+);
+assert(Boolean(manifest.artifacts?.iife), "Manifest missing iife artifact entry");
+assert(Boolean(manifest.artifacts?.esm), "Manifest missing esm artifact entry");
+
+const runtimeSha = createHash("sha256").update(iifeSource, "utf8").digest("hex");
+assert(runtimeSha === manifest.sha256, "Manifest sha256 does not match runtime artifact");
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_parity_verified",
+ bytes: iifeSource.length,
+ sha256: runtimeSha,
+ }),
+);
diff --git a/packages/core/scripts/test-hyperframe-runtime-security.ts b/packages/core/scripts/test-hyperframe-runtime-security.ts
new file mode 100644
index 000000000..6a2350071
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-runtime-security.ts
@@ -0,0 +1,96 @@
+function assert(condition: unknown, message: string): void {
+ if (!condition) {
+ throw new Error(message);
+ }
+}
+
+const ALLOWED_HOSTS = new Set(["runtime.example.com"]);
+const ALLOWED_PATH_PREFIX = "/static/hyperframes-runtime/";
+
+function isAllowedRuntimeUrl(candidate: string): boolean {
+ try {
+ const parsed = new URL(candidate);
+ return (
+ parsed.protocol === "https:" &&
+ ALLOWED_HOSTS.has(parsed.hostname.toLowerCase()) &&
+ parsed.pathname.startsWith(ALLOWED_PATH_PREFIX) &&
+ parsed.pathname.endsWith(".js")
+ );
+ } catch {
+ return false;
+ }
+}
+
+function isGuardedPreviewMessage(data: unknown): boolean {
+ if (!data || typeof data !== "object") {
+ return false;
+ }
+ const record = data as { source?: unknown; type?: unknown };
+ const source = typeof record.source === "string" ? record.source : null;
+ const type = typeof record.type === "string" ? record.type : null;
+ const guardedTypes = new Set([
+ "state",
+ "timeline",
+ "element-picked",
+ "element-picked-many",
+ "element-pick-candidates",
+ "pick-mode-cancelled",
+ ]);
+ if (!type || !guardedTypes.has(type)) {
+ return false;
+ }
+ return source === "hf-preview";
+}
+
+const allowedRuntimeFixtures = [
+ "https://runtime.example.com/static/hyperframes-runtime/hyperframe.runtime.iife.js",
+ "https://runtime.example.com/static/hyperframes-runtime/v2026.02.20/hyperframe.runtime.iife.js",
+];
+
+const blockedRuntimeFixtures = [
+ "http://runtime.example.com/static/hyperframes-runtime/hyperframe.runtime.iife.js",
+ "javascript:alert(1)",
+ "data:text/javascript,alert(1)",
+ "https://evil.example/static/hyperframes-runtime/hyperframe.runtime.iife.js",
+ "https://runtime.example.com/static/other/hyperframe.runtime.iife.js",
+ "https://runtime.example.com/static/hyperframes-runtime/hyperframe.runtime.iife.css",
+];
+
+for (const fixture of allowedRuntimeFixtures) {
+ assert(isAllowedRuntimeUrl(fixture), `Expected runtime URL to be allowed: ${fixture}`);
+}
+
+for (const fixture of blockedRuntimeFixtures) {
+ assert(!isAllowedRuntimeUrl(fixture), `Expected runtime URL to be blocked: ${fixture}`);
+}
+
+const allowedMessages = [
+ { type: "state", source: "hf-preview" },
+ { type: "timeline", source: "hf-preview" },
+ { type: "element-picked", source: "hf-preview" },
+];
+const blockedMessages = [
+ { type: "state", source: "hf-parent" },
+ { type: "timeline", source: "evil-origin" },
+ { type: "element-picked", source: "hf-parent" },
+ { type: "pick-mode-cancelled", source: null },
+ { type: "unknown-type", source: "hf-preview" },
+];
+
+for (const fixture of allowedMessages) {
+ assert(isGuardedPreviewMessage(fixture), `Expected message fixture to pass guard: ${JSON.stringify(fixture)}`);
+}
+
+for (const fixture of blockedMessages) {
+ assert(!isGuardedPreviewMessage(fixture), `Expected message fixture to fail guard: ${JSON.stringify(fixture)}`);
+}
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_security_fixtures_verified",
+ allowedRuntimeFixtures: allowedRuntimeFixtures.length,
+ blockedRuntimeFixtures: blockedRuntimeFixtures.length,
+ allowedMessages: allowedMessages.length,
+ blockedMessages: blockedMessages.length,
+ }),
+);
diff --git a/packages/core/scripts/test-hyperframe-runtime-seek.ts b/packages/core/scripts/test-hyperframe-runtime-seek.ts
new file mode 100644
index 000000000..34ed25c49
--- /dev/null
+++ b/packages/core/scripts/test-hyperframe-runtime-seek.ts
@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import { createGsapAdapter } from "../src/runtime/adapters/gsap";
+import { createRuntimePlayer } from "../src/runtime/player";
+import type { RuntimeTimelineLike } from "../src/runtime/types";
+
+type Call = {
+ method: "pause" | "seek" | "totalTime";
+ time?: number;
+ suppressEvents?: boolean;
+};
+
+function createTimeline(withTotalTime: boolean): { calls: Call[]; timeline: RuntimeTimelineLike } {
+ const calls: Call[] = [];
+ const timeline: RuntimeTimelineLike = {
+ play: () => undefined,
+ pause: () => {
+ calls.push({ method: "pause" });
+ },
+ seek: (timeSeconds: number, suppressEvents?: boolean) => {
+ calls.push({ method: "seek", time: timeSeconds, suppressEvents });
+ },
+ time: () => 0,
+ duration: () => 12,
+ add: () => undefined,
+ paused: () => undefined,
+ set: () => undefined,
+ };
+ if (withTotalTime) {
+ timeline.totalTime = (timeSeconds: number, suppressEvents?: boolean) => {
+ calls.push({ method: "totalTime", time: timeSeconds, suppressEvents });
+ };
+ }
+ return { calls, timeline };
+}
+
+function createPlayer(timeline: RuntimeTimelineLike) {
+ const deterministicSeekCalls: number[] = [];
+ const syncMediaCalls: number[] = [];
+ const renderFrameSeekCalls: number[] = [];
+ const player = createRuntimePlayer({
+ getTimeline: () => timeline,
+ setTimeline: () => undefined,
+ getIsPlaying: () => false,
+ setIsPlaying: () => undefined,
+ getPlaybackRate: () => 1,
+ setPlaybackRate: () => undefined,
+ getCanonicalFps: () => 30,
+ onSyncMedia: (timeSeconds) => {
+ syncMediaCalls.push(timeSeconds);
+ },
+ onStatePost: () => undefined,
+ onDeterministicSeek: (timeSeconds) => {
+ deterministicSeekCalls.push(timeSeconds);
+ },
+ onDeterministicPause: () => undefined,
+ onDeterministicPlay: () => undefined,
+ onRenderFrameSeek: (timeSeconds) => {
+ renderFrameSeekCalls.push(timeSeconds);
+ },
+ onShowNativeVideos: () => undefined,
+ getSafeDuration: () => 12,
+ });
+ return { player, deterministicSeekCalls, syncMediaCalls, renderFrameSeekCalls };
+}
+
+function testSeekUsesDeterministicGsapPath(): void {
+ const { calls, timeline } = createTimeline(true);
+ const { player, deterministicSeekCalls, syncMediaCalls, renderFrameSeekCalls } = createPlayer(timeline);
+ const quantizedTime = 2;
+
+ player.seek(2.017);
+
+ assert.deepEqual(
+ calls,
+ [{ method: "pause" }, { method: "totalTime", time: quantizedTime, suppressEvents: false }],
+ "player.seek() should use quantized totalTime() when available",
+ );
+ assert.deepEqual(
+ deterministicSeekCalls,
+ [quantizedTime],
+ "player.seek() should notify adapters with the quantized time",
+ );
+ assert.deepEqual(syncMediaCalls, [quantizedTime], "media sync should use quantized time");
+ assert.deepEqual(renderFrameSeekCalls, [quantizedTime], "render frame seek should use quantized time");
+}
+
+function testGsapAdapterPreservesTotalTime(): void {
+ const { calls, timeline } = createTimeline(true);
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+
+ adapter.seek({ time: 2.033333333333333 });
+
+ assert.deepEqual(
+ calls,
+ [{ method: "pause" }, { method: "totalTime", time: 2.033333333333333, suppressEvents: false }],
+ "GSAP adapter should not downgrade deterministic seeks back to seek()",
+ );
+}
+
+function testGsapAdapterFallsBackToSeek(): void {
+ const { calls, timeline } = createTimeline(false);
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+
+ adapter.seek({ time: 1.5 });
+
+ assert.deepEqual(
+ calls,
+ [{ method: "pause" }, { method: "seek", time: 1.5, suppressEvents: false }],
+ "GSAP adapter should keep working with timelines that only expose seek()",
+ );
+}
+
+testSeekUsesDeterministicGsapPath();
+testGsapAdapterPreservesTotalTime();
+testGsapAdapterFallsBackToSeek();
+
+console.log(
+ JSON.stringify({
+ event: "hyperframe_runtime_seek_verified",
+ assertions: 3,
+ }),
+);
diff --git a/packages/core/src/adapters/gsap.test.ts b/packages/core/src/adapters/gsap.test.ts
new file mode 100644
index 000000000..cf2b42e0e
--- /dev/null
+++ b/packages/core/src/adapters/gsap.test.ts
@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from "vitest";
+import { createGSAPFrameAdapter } from "./gsap.js";
+import type { FrameAdapter, FrameAdapterContext } from "./types.js";
+
+function makeMockTimeline(duration = 10, totalDuration?: number) {
+ return {
+ duration: vi.fn().mockReturnValue(duration),
+ totalDuration: totalDuration !== undefined ? vi.fn().mockReturnValue(totalDuration) : undefined,
+ seek: vi.fn(),
+ pause: vi.fn(),
+ };
+}
+
+describe("createGSAPFrameAdapter", () => {
+ it("returns a FrameAdapter with required properties", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ expect(adapter.id).toBe("gsap");
+ expect(typeof adapter.init).toBe("function");
+ expect(typeof adapter.getDurationFrames).toBe("function");
+ expect(typeof adapter.seekFrame).toBe("function");
+ });
+
+ it("uses custom id when provided", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ id: "custom-gsap", fps: 30, timeline });
+
+ expect(adapter.id).toBe("custom-gsap");
+ });
+
+ it("getDurationFrames returns correct frame count", () => {
+ const timeline = makeMockTimeline(10); // 10 seconds
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ // 10 seconds * 30 fps = 300 frames
+ expect(adapter.getDurationFrames()).toBe(300);
+ });
+
+ it("getDurationFrames uses totalDuration when available", () => {
+ const timeline = makeMockTimeline(5, 15); // duration=5, totalDuration=15
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ // Should use totalDuration (15) not duration (5)
+ // 15 seconds * 30 fps = 450 frames
+ expect(adapter.getDurationFrames()).toBe(450);
+ });
+
+ it("getDurationFrames returns 0 for zero-duration timeline", () => {
+ const timeline = makeMockTimeline(0);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ expect(adapter.getDurationFrames()).toBe(0);
+ });
+
+ it("init pauses the timeline", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ adapter.init!({} as FrameAdapterContext);
+
+ expect(timeline.pause).toHaveBeenCalled();
+ });
+
+ it("seekFrame seeks to the correct time in seconds", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ adapter.seekFrame(90); // Frame 90 at 30fps = 3 seconds
+
+ expect(timeline.seek).toHaveBeenCalledWith(3, false);
+ expect(timeline.pause).toHaveBeenCalled();
+ });
+
+ it("seekFrame clamps negative frames to 0", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ adapter.seekFrame(-5);
+
+ expect(timeline.seek).toHaveBeenCalledWith(0, false);
+ });
+
+ it("seekFrame handles non-finite frame numbers", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ adapter.seekFrame(NaN);
+
+ expect(timeline.seek).toHaveBeenCalledWith(0, false);
+ });
+
+ it("seekFrame handles Infinity", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ adapter.seekFrame(Infinity);
+
+ // Infinity is not finite, so it gets clamped to 0
+ expect(timeline.seek).toHaveBeenCalledWith(0, false);
+ });
+
+ it("works without pause method on timeline", () => {
+ const timeline = {
+ duration: vi.fn().mockReturnValue(5),
+ seek: vi.fn(),
+ // No pause method
+ };
+
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ // Should not throw
+ adapter.init!({} as FrameAdapterContext);
+ adapter.seekFrame(0);
+
+ expect(timeline.seek).toHaveBeenCalled();
+ });
+
+ it("getDurationFrames ceiling the frame count", () => {
+ const timeline = makeMockTimeline(1.05); // 1.05 seconds * 30 fps = 31.5 -> ceil = 32
+ const adapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ expect(adapter.getDurationFrames()).toBe(32);
+ });
+});
+
+describe("FrameAdapter type", () => {
+ it("adapter conforms to FrameAdapter interface", () => {
+ const timeline = makeMockTimeline(10);
+ const adapter: FrameAdapter = createGSAPFrameAdapter({ fps: 30, timeline });
+
+ expect(adapter.id).toBeDefined();
+ expect(adapter.getDurationFrames).toBeDefined();
+ expect(adapter.seekFrame).toBeDefined();
+ });
+});
diff --git a/packages/core/src/adapters/gsap.ts b/packages/core/src/adapters/gsap.ts
new file mode 100644
index 000000000..392ab2126
--- /dev/null
+++ b/packages/core/src/adapters/gsap.ts
@@ -0,0 +1,43 @@
+import type { FrameAdapter } from "./types";
+
+export interface GSAPTimelineLike {
+ // Base timeline span excluding repeats.
+ duration: () => number;
+ // Full span including repeats/yoyo when available.
+ totalDuration?: () => number;
+ seek: (timeInSeconds: number, suppressEvents?: boolean) => unknown;
+ pause?: () => unknown;
+}
+
+export interface CreateGSAPFrameAdapterOptions {
+ id?: string;
+ fps: number;
+ timeline: GSAPTimelineLike;
+}
+
+export function createGSAPFrameAdapter(options: CreateGSAPFrameAdapterOptions): FrameAdapter {
+ const { fps, timeline } = options;
+ const adapterId = options.id ?? "gsap";
+
+ const getDurationSeconds = (): number => {
+ const totalDuration = typeof timeline.totalDuration === "function" ? timeline.totalDuration() : timeline.duration();
+ return Number.isFinite(totalDuration) && totalDuration > 0 ? totalDuration : 0;
+ };
+
+ return {
+ id: adapterId,
+ init: () => {
+ timeline.pause?.();
+ },
+ getDurationFrames: () => {
+ const durationSeconds = getDurationSeconds();
+ return Math.max(0, Math.ceil(durationSeconds * fps));
+ },
+ seekFrame: (frame: number) => {
+ const clampedFrame = Number.isFinite(frame) ? Math.max(0, frame) : 0;
+ const targetSeconds = clampedFrame / fps;
+ timeline.pause?.();
+ timeline.seek(targetSeconds, false);
+ },
+ };
+}
diff --git a/packages/core/src/adapters/index.ts b/packages/core/src/adapters/index.ts
new file mode 100644
index 000000000..254c28bd5
--- /dev/null
+++ b/packages/core/src/adapters/index.ts
@@ -0,0 +1,3 @@
+export type { FrameAdapter, FrameAdapterContext } from "./types";
+export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./gsap";
+export { createGSAPFrameAdapter } from "./gsap";
diff --git a/packages/core/src/adapters/types.ts b/packages/core/src/adapters/types.ts
new file mode 100644
index 000000000..484064d21
--- /dev/null
+++ b/packages/core/src/adapters/types.ts
@@ -0,0 +1,15 @@
+export interface FrameAdapterContext {
+ compositionId: string;
+ fps: number;
+ width: number;
+ height: number;
+ rootElement?: HTMLElement;
+}
+
+export interface FrameAdapter {
+ id: string;
+ init?: (ctx: FrameAdapterContext) => Promise | void;
+ getDurationFrames: () => number;
+ seekFrame: (frame: number) => Promise | void;
+ destroy?: () => Promise | void;
+}
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
new file mode 100644
index 000000000..d46697372
--- /dev/null
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -0,0 +1,402 @@
+import { readFileSync, existsSync } from "fs";
+import { join, resolve, isAbsolute, sep } from "path";
+import * as cheerio from "cheerio";
+import { transformSync } from "esbuild";
+import { compileHtml, type MediaDurationProber } from "./htmlCompiler";
+import { validateHyperframeHtmlContract } from "./staticGuard";
+
+/** Resolve a relative path within projectDir, rejecting traversal outside it. */
+function safePath(projectDir: string, relativePath: string): string | null {
+ const resolved = resolve(projectDir, relativePath);
+ const normalizedBase = resolve(projectDir) + sep;
+ if (!resolved.startsWith(normalizedBase) && resolved !== resolve(projectDir)) return null;
+ return resolved;
+}
+
+const RUNTIME_BOOTSTRAP_ATTR = "data-hyperframes-preview-runtime";
+const DEFAULT_RUNTIME_SCRIPT_URL = "";
+
+function stripEmbeddedRuntimeScripts(html: string): string {
+ if (!html) return html;
+ const scriptRe = /]*>[\s\S]*?<\/script>/gi;
+ const runtimeSrcMarkers = [
+ "hyperframe.runtime.iife.js",
+ "hyperframe-runtime.modular-runtime.inline.js",
+ RUNTIME_BOOTSTRAP_ATTR,
+ ];
+ const runtimeInlineMarkers = [
+ "__hyperframeRuntimeBootstrapped",
+ "__hyperframeRuntime",
+ "__hyperframeRuntimeTeardown",
+ "window.__player =",
+ "window.__playerReady",
+ "window.__renderReady",
+ ];
+
+ const shouldStrip = (block: string): boolean => {
+ const lowered = block.toLowerCase();
+ for (const marker of runtimeSrcMarkers) {
+ if (lowered.includes(marker.toLowerCase())) return true;
+ }
+ for (const marker of runtimeInlineMarkers) {
+ if (block.includes(marker)) return true;
+ }
+ return false;
+ };
+
+ return html.replace(scriptRe, (block) => (shouldStrip(block) ? "" : block));
+}
+
+function getRuntimeScriptUrl(): string {
+ const configured = (process.env.HYPERFRAME_RUNTIME_URL || "").trim();
+ return configured || DEFAULT_RUNTIME_SCRIPT_URL;
+}
+
+function injectInterceptor(html: string): string {
+ const sanitized = stripEmbeddedRuntimeScripts(html);
+ if (sanitized.includes(RUNTIME_BOOTSTRAP_ATTR)) return sanitized;
+
+ const runtimeScriptUrl = getRuntimeScriptUrl().replace(/"/g, """);
+ const tag = ``;
+ if (sanitized.includes("")) {
+ return sanitized.replace("", `${tag}\n`);
+ }
+ const doctypeIdx = sanitized.toLowerCase().indexOf("= 0) {
+ const insertPos = sanitized.indexOf(">", doctypeIdx) + 1;
+ return sanitized.slice(0, insertPos) + tag + sanitized.slice(insertPos);
+ }
+ return tag + sanitized;
+}
+
+function isRelativeUrl(url: string): boolean {
+ if (!url) return false;
+ return !url.startsWith("http://") && !url.startsWith("https://") && !url.startsWith("//") && !url.startsWith("data:") && !isAbsolute(url);
+}
+
+function safeReadFile(filePath: string): string | null {
+ if (!existsSync(filePath)) return null;
+ try { return readFileSync(filePath, "utf-8"); } catch { return null; }
+}
+
+function safeReadFileBuffer(filePath: string): Buffer | null {
+ if (!existsSync(filePath)) return null;
+ try { return readFileSync(filePath); } catch { return null; }
+}
+
+function splitUrlSuffix(urlValue: string): { basePath: string; suffix: string } {
+ const queryIdx = urlValue.indexOf("?");
+ const hashIdx = urlValue.indexOf("#");
+ if (queryIdx < 0 && hashIdx < 0) return { basePath: urlValue, suffix: "" };
+ const cutIdx = queryIdx < 0 ? hashIdx : hashIdx < 0 ? queryIdx : Math.min(queryIdx, hashIdx);
+ return { basePath: urlValue.slice(0, cutIdx), suffix: urlValue.slice(cutIdx) };
+}
+
+function appendSuffixToUrl(baseUrl: string, suffix: string): string {
+ if (!suffix) return baseUrl;
+ if (suffix.startsWith("#")) return `${baseUrl}${suffix}`;
+ if (suffix.startsWith("?")) {
+ const queryWithOptionalHash = suffix.slice(1);
+ if (!queryWithOptionalHash) return baseUrl;
+ const hashIdx = queryWithOptionalHash.indexOf("#");
+ const queryPart = hashIdx >= 0 ? queryWithOptionalHash.slice(0, hashIdx) : queryWithOptionalHash;
+ const hashPart = hashIdx >= 0 ? queryWithOptionalHash.slice(hashIdx) : "";
+ if (!queryPart) return `${baseUrl}${hashPart}`;
+ const joiner = baseUrl.includes("?") ? "&" : "?";
+ return `${baseUrl}${joiner}${queryPart}${hashPart}`;
+ }
+ return baseUrl;
+}
+
+function guessMimeType(filePath: string): string {
+ const l = filePath.toLowerCase();
+ if (l.endsWith(".svg")) return "image/svg+xml";
+ if (l.endsWith(".json")) return "application/json";
+ if (l.endsWith(".txt")) return "text/plain";
+ if (l.endsWith(".xml")) return "application/xml";
+ return "application/octet-stream";
+}
+
+function shouldInlineAsDataUrl(filePath: string): boolean {
+ const l = filePath.toLowerCase();
+ return l.endsWith(".svg") || l.endsWith(".json") || l.endsWith(".txt") || l.endsWith(".xml");
+}
+
+function maybeInlineRelativeAssetUrl(urlValue: string, projectDir: string): string | null {
+ if (!urlValue || !isRelativeUrl(urlValue)) return null;
+ const { basePath, suffix } = splitUrlSuffix(urlValue.trim());
+ if (!basePath) return null;
+ const filePath = safePath(projectDir, basePath);
+ if (!filePath || !shouldInlineAsDataUrl(filePath)) return null;
+ const content = safeReadFileBuffer(filePath);
+ if (content == null) return null;
+ const mimeType = guessMimeType(filePath);
+ const dataUrl = `data:${mimeType};base64,${content.toString("base64")}`;
+ return appendSuffixToUrl(dataUrl, suffix);
+}
+
+function rewriteSrcsetWithInlinedAssets(srcsetValue: string, projectDir: string): string {
+ if (!srcsetValue) return srcsetValue;
+ return srcsetValue.split(",").map((rawCandidate) => {
+ const candidate = rawCandidate.trim();
+ if (!candidate) return candidate;
+ const parts = candidate.split(/\s+/);
+ if (parts.length === 0) return candidate;
+ const maybeInlined = maybeInlineRelativeAssetUrl(parts[0] ?? "", projectDir);
+ if (maybeInlined) parts[0] = maybeInlined;
+ return parts.join(" ");
+ }).join(", ");
+}
+
+function rewriteCssUrlsWithInlinedAssets(cssText: string, projectDir: string): string {
+ if (!cssText) return cssText;
+ return cssText.replace(
+ /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g,
+ (_full, quote: string, rawUrl: string) => {
+ const maybeInlined = maybeInlineRelativeAssetUrl((rawUrl || "").trim(), projectDir);
+ if (!maybeInlined) return _full;
+ return `url(${quote || ""}${maybeInlined}${quote || ""})`;
+ },
+ );
+}
+
+function enforceCompositionPixelSizing($: cheerio.CheerioAPI): void {
+ const compositionEls = $("[data-composition-id][data-width][data-height]").toArray();
+ if (compositionEls.length === 0) return;
+ const sizeMap = new Map();
+ for (const el of compositionEls) {
+ const compId = $(el).attr("data-composition-id");
+ const w = Number($(el).attr("data-width"));
+ const h = Number($(el).attr("data-height"));
+ if (compId && Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) {
+ sizeMap.set(compId, { w, h });
+ }
+ }
+ if (sizeMap.size === 0) return;
+ $("style").each((_, styleEl) => {
+ let css = $(styleEl).html() || "";
+ let modified = false;
+ for (const [compId, { w, h }] of sizeMap) {
+ const escaped = compId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ const blockRe = new RegExp(`(\\[data-composition-id=["']${escaped}["']\\]\\s*\\{)([^}]*)(})`, "g");
+ css = css.replace(blockRe, (_, open, body, close) => {
+ const newBody = body.replace(/(\bwidth\s*:\s*)100%/g, `$1${w}px`).replace(/(\bheight\s*:\s*)100%/g, `$1${h}px`);
+ if (newBody !== body) modified = true;
+ return open + newBody + close;
+ });
+ }
+ if (modified) $(styleEl).text(css);
+ });
+}
+
+function autoHealMissingCompositionIds($: cheerio.CheerioAPI): void {
+ const compositionIdRe = /data-composition-id=["']([^"']+)["']/gi;
+ const referencedIds = new Set();
+ $("style, script").each((_, el) => {
+ const text = ($(el).html() || "").trim();
+ if (!text) return;
+ let match: RegExpExecArray | null;
+ while ((match = compositionIdRe.exec(text)) !== null) {
+ const compId = (match[1] || "").trim();
+ if (compId) referencedIds.add(compId);
+ }
+ });
+ if (referencedIds.size === 0) return;
+
+ const existingIds = new Set();
+ $("[data-composition-id]").each((_, el) => {
+ const id = ($(el).attr("data-composition-id") || "").trim();
+ if (id) existingIds.add(id);
+ });
+
+ for (const compId of referencedIds) {
+ if (compId === "root" || existingIds.has(compId)) continue;
+ const candidates = [`${compId}-layer`, `${compId}-comp`, compId];
+ for (const targetId of candidates) {
+ const match = $(`#${targetId}`).first();
+ if (match.length > 0 && !match.attr("data-composition-id")) {
+ match.attr("data-composition-id", compId);
+ break;
+ }
+ }
+ }
+}
+
+function coalesceHeadStylesAndBodyScripts($: cheerio.CheerioAPI): void {
+ const headStyleEls = $("head style").toArray();
+ if (headStyleEls.length > 1) {
+ const importRe = /@import\s+url\([^)]*\)\s*;|@import\s+["'][^"']+["']\s*;/gi;
+ const imports: string[] = [];
+ const cssParts: string[] = [];
+ const seenImports = new Set();
+ for (const el of headStyleEls) {
+ const raw = ($(el).html() || "").trim();
+ if (!raw) continue;
+ const nonImportCss = raw.replace(importRe, (match) => {
+ const cleaned = match.trim();
+ if (!seenImports.has(cleaned)) { seenImports.add(cleaned); imports.push(cleaned); }
+ return "";
+ });
+ const trimmed = nonImportCss.trim();
+ if (trimmed) cssParts.push(trimmed);
+ }
+ const merged = [...imports, ...cssParts].join("\n\n").trim();
+ if (merged) {
+ $(headStyleEls[0]).text(merged);
+ for (let i = 1; i < headStyleEls.length; i++) $(headStyleEls[i]).remove();
+ }
+ }
+
+ const bodyInlineScripts = $("body script").toArray().filter((el) => {
+ const src = ($(el).attr("src") || "").trim();
+ if (src) return false;
+ const type = ($(el).attr("type") || "").trim().toLowerCase();
+ return !type || type === "text/javascript" || type === "application/javascript";
+ });
+ if (bodyInlineScripts.length > 0) {
+ const mergedJs = bodyInlineScripts.map((el) => ($(el).html() || "").trim()).filter(Boolean).join("\n;\n").trim();
+ for (const el of bodyInlineScripts) $(el).remove();
+ if (mergedJs) {
+ const stripped = stripJsCommentsParserSafe(mergedJs);
+ $("body").append(``);
+ }
+ }
+}
+
+function stripJsCommentsParserSafe(source: string): string {
+ if (!source) return source;
+ try {
+ const result = transformSync(source, { loader: "js", minify: false, legalComments: "none" });
+ return result.code.trim();
+ } catch { return source; }
+}
+
+export interface BundleOptions {
+ /** Optional media duration prober (e.g., ffprobe). If omitted, media durations are not resolved. */
+ probeMediaDuration?: MediaDurationProber;
+}
+
+/**
+ * Bundle a project's index.html into a single self-contained HTML file.
+ *
+ * - Compiles timing attributes and optionally resolves media durations
+ * - Injects the HyperFrames runtime script
+ * - Inlines local CSS and JS files
+ * - Inlines sub-composition HTML fragments (data-composition-src)
+ * - Inlines small textual assets as data URLs
+ */
+export async function bundleToSingleHtml(projectDir: string, options?: BundleOptions): Promise {
+ const indexPath = join(projectDir, "index.html");
+ if (!existsSync(indexPath)) throw new Error("index.html not found in project directory");
+
+ const rawHtml = readFileSync(indexPath, "utf-8");
+ const compiled = await compileHtml(rawHtml, projectDir, options?.probeMediaDuration);
+
+ const staticGuard = validateHyperframeHtmlContract(compiled);
+ if (!staticGuard.isValid) {
+ console.warn(`[StaticGuard] Invalid HyperFrame contract: ${staticGuard.missingKeys.join("; ")}`);
+ }
+
+ const withInterceptor = injectInterceptor(compiled);
+ const $ = cheerio.load(withInterceptor);
+
+ // Inline local CSS
+ const localCssChunks: string[] = [];
+ let cssAnchorPlaced = false;
+ $('link[rel="stylesheet"]').each((_, el) => {
+ const href = $(el).attr("href");
+ if (!href || !isRelativeUrl(href)) return;
+ const cssPath = safePath(projectDir, href);
+ const css = cssPath ? safeReadFile(cssPath) : null;
+ if (css == null) return;
+ localCssChunks.push(css);
+ if (!cssAnchorPlaced) { $(el).replaceWith(''); cssAnchorPlaced = true; } else { $(el).remove(); }
+ });
+ if (localCssChunks.length > 0) {
+ const $anchor = $('style[data-hf-bundled-local-css="1"]').first();
+ if ($anchor.length) $anchor.removeAttr("data-hf-bundled-local-css").text(localCssChunks.join("\n\n"));
+ else $("head").append(``);
+ }
+
+ // Inline local JS
+ const localJsChunks: string[] = [];
+ let jsAnchorPlaced = false;
+ $("script[src]").each((_, el) => {
+ const src = $(el).attr("src");
+ if (!src || !isRelativeUrl(src)) return;
+ const jsPath = safePath(projectDir, src);
+ const js = jsPath ? safeReadFile(jsPath) : null;
+ if (js == null) return;
+ localJsChunks.push(js);
+ if (!jsAnchorPlaced) { $(el).replaceWith(''); jsAnchorPlaced = true; } else { $(el).remove(); }
+ });
+ if (localJsChunks.length > 0) {
+ const $anchor = $('script[data-hf-bundled-local-js="1"]').first();
+ if ($anchor.length) $anchor.removeAttr("data-hf-bundled-local-js").text(localJsChunks.join("\n;\n"));
+ else $("body").append(``);
+ }
+
+ // Inline sub-compositions
+ const compStyleChunks: string[] = [];
+ const compScriptChunks: string[] = [];
+ $("[data-composition-src]").each((_, hostEl) => {
+ const src = $(hostEl).attr("data-composition-src");
+ if (!src || !isRelativeUrl(src)) return;
+ const compPath = safePath(projectDir, src);
+ const compHtml = compPath ? safeReadFile(compPath) : null;
+ if (compHtml == null) { console.warn(`[Bundler] Composition file not found: ${src}`); return; }
+
+ const $comp = cheerio.load(compHtml);
+ const compId = $(hostEl).attr("data-composition-id");
+ const $contentRoot = $comp("template").first();
+ const contentHtml = $contentRoot.length ? $contentRoot.html() || "" : $comp("body").html() || "";
+ const $content = cheerio.load(contentHtml);
+ const $innerRoot = compId ? $content(`[data-composition-id="${compId}"]`).first() : $content("[data-composition-id]").first();
+
+ $content("style").each((_, s) => { compStyleChunks.push($content(s).html() || ""); $content(s).remove(); });
+ $content("script").each((_, s) => {
+ compScriptChunks.push(`(function(){ try { ${$content(s).html() || ""} } catch (_err) { console.error('[HyperFrames] composition script error:', _err); } })();`);
+ $content(s).remove();
+ });
+
+ if ($innerRoot.length) {
+ const innerCompId = $innerRoot.attr("data-composition-id");
+ const innerW = $innerRoot.attr("data-width");
+ const innerH = $innerRoot.attr("data-height");
+ if (innerCompId && !$(hostEl).attr("data-composition-id")) $(hostEl).attr("data-composition-id", innerCompId);
+ if (innerW && !$(hostEl).attr("data-width")) $(hostEl).attr("data-width", innerW);
+ if (innerH && !$(hostEl).attr("data-height")) $(hostEl).attr("data-height", innerH);
+ $innerRoot.find("style, script").remove();
+ $(hostEl).html($innerRoot.html() || "");
+ } else {
+ $content("style, script").remove();
+ $(hostEl).html($content.html() || "");
+ }
+ $(hostEl).removeAttr("data-composition-src");
+ });
+
+ if (compStyleChunks.length) $("head").append(``);
+ if (compScriptChunks.length) $("body").append(``);
+
+ enforceCompositionPixelSizing($);
+ autoHealMissingCompositionIds($);
+ coalesceHeadStylesAndBodyScripts($);
+
+ // Inline textual assets
+ $("[src], [href], [poster], [xlink\\:href]").each((_, el) => {
+ for (const attr of ["src", "href", "poster", "xlink:href"] as const) {
+ const value = $(el).attr(attr);
+ if (!value) continue;
+ const inlined = maybeInlineRelativeAssetUrl(value, projectDir);
+ if (inlined) $(el).attr(attr, inlined);
+ }
+ });
+ $("[srcset]").each((_, el) => {
+ const srcset = $(el).attr("srcset");
+ if (srcset) $(el).attr("srcset", rewriteSrcsetWithInlinedAssets(srcset, projectDir));
+ });
+ $("style").each((_, el) => { $(el).text(rewriteCssUrlsWithInlinedAssets($(el).html() || "", projectDir)); });
+ $("[style]").each((_, el) => { $(el).attr("style", rewriteCssUrlsWithInlinedAssets($(el).attr("style") || "", projectDir)); });
+
+ return $.html();
+}
diff --git a/packages/core/src/compiler/htmlCompiler.ts b/packages/core/src/compiler/htmlCompiler.ts
new file mode 100644
index 000000000..4efc44659
--- /dev/null
+++ b/packages/core/src/compiler/htmlCompiler.ts
@@ -0,0 +1,90 @@
+import { resolve } from "path";
+import {
+ compileTimingAttrs,
+ injectDurations,
+ extractResolvedMedia,
+ clampDurations,
+ type ResolvedDuration,
+} from "./timingCompiler";
+
+/**
+ * Callback to probe media duration. If not provided, media duration resolution is skipped.
+ * Return duration in seconds, or 0 if unknown.
+ */
+export type MediaDurationProber = (src: string) => Promise;
+
+function resolveMediaSrc(src: string, projectDir: string): string {
+ return src.startsWith("http://") || src.startsWith("https://")
+ ? src
+ : resolve(projectDir, src);
+}
+
+/**
+ * Compile HTML with full duration resolution.
+ *
+ * 1. Static pass: compileTimingAttrs() adds data-end where data-duration exists
+ * 2. For unresolved video/audio (no data-duration): probe via probeMediaDuration, inject durations
+ * 3. For pre-resolved video/audio: validate data-duration against actual source, clamp if needed
+ *
+ * @param rawHtml - The raw HTML string
+ * @param projectDir - The project directory for resolving relative paths
+ * @param probeMediaDuration - Optional callback to probe media duration (e.g., via ffprobe)
+ */
+export async function compileHtml(
+ rawHtml: string,
+ projectDir: string,
+ probeMediaDuration?: MediaDurationProber,
+): Promise {
+ const { html: staticCompiled, unresolved } = compileTimingAttrs(rawHtml);
+ let html = staticCompiled;
+
+ if (!probeMediaDuration) return html;
+
+ // Phase 1: Resolve missing durations
+ const mediaUnresolved = unresolved.filter(
+ (el) => el.tagName === "video" || el.tagName === "audio",
+ );
+
+ if (mediaUnresolved.length > 0) {
+ const resolutions: ResolvedDuration[] = [];
+
+ for (const el of mediaUnresolved) {
+ if (!el.src) continue;
+ const src = resolveMediaSrc(el.src, projectDir);
+ const fileDuration = await probeMediaDuration(src);
+ if (fileDuration <= 0) continue;
+
+ const effectiveDuration = fileDuration - el.mediaStart;
+ resolutions.push({
+ id: el.id,
+ duration: effectiveDuration > 0 ? effectiveDuration : fileDuration,
+ });
+ }
+
+ if (resolutions.length > 0) {
+ html = injectDurations(html, resolutions);
+ }
+ }
+
+ // Phase 2: Validate pre-resolved media — clamp data-duration to actual source duration
+ const preResolved = extractResolvedMedia(html);
+ const clampList: ResolvedDuration[] = [];
+
+ for (const el of preResolved) {
+ if (!el.src) continue;
+ const src = resolveMediaSrc(el.src, projectDir);
+ const fileDuration = await probeMediaDuration(src);
+ if (fileDuration <= 0) continue;
+
+ const maxDuration = fileDuration - el.mediaStart;
+ if (maxDuration > 0 && el.duration > maxDuration) {
+ clampList.push({ id: el.id, duration: maxDuration });
+ }
+ }
+
+ if (clampList.length > 0) {
+ html = clampDurations(html, clampList);
+ }
+
+ return html;
+}
diff --git a/packages/core/src/compiler/index.ts b/packages/core/src/compiler/index.ts
new file mode 100644
index 000000000..feed7c1b6
--- /dev/null
+++ b/packages/core/src/compiler/index.ts
@@ -0,0 +1,24 @@
+// Timing compiler (browser-safe)
+export {
+ compileTimingAttrs,
+ injectDurations,
+ extractResolvedMedia,
+ clampDurations,
+ type UnresolvedElement,
+ type ResolvedDuration,
+ type ResolvedMediaElement,
+ type CompilationResult,
+} from "./timingCompiler";
+
+// HTML compiler (Node.js — requires fs)
+export { compileHtml, type MediaDurationProber } from "./htmlCompiler";
+
+// HTML bundler (Node.js — requires fs, cheerio, esbuild)
+export { bundleToSingleHtml, type BundleOptions } from "./htmlBundler";
+
+// Static guard
+export {
+ validateHyperframeHtmlContract,
+ type HyperframeStaticFailureReason,
+ type HyperframeStaticGuardResult,
+} from "./staticGuard";
diff --git a/packages/core/src/compiler/staticGuard.ts b/packages/core/src/compiler/staticGuard.ts
new file mode 100644
index 000000000..372d538b1
--- /dev/null
+++ b/packages/core/src/compiler/staticGuard.ts
@@ -0,0 +1,39 @@
+import { lintHyperframeHtml } from "../lint/hyperframeLinter";
+
+export type HyperframeStaticFailureReason =
+ | "missing_composition_id"
+ | "missing_composition_dimensions"
+ | "missing_timeline_registry"
+ | "invalid_script_syntax"
+ | "invalid_static_hyperframe_contract";
+
+export type HyperframeStaticGuardResult = {
+ isValid: boolean;
+ missingKeys: string[];
+ failureReason: HyperframeStaticFailureReason | null;
+};
+
+export function validateHyperframeHtmlContract(html: string): HyperframeStaticGuardResult {
+ const result = lintHyperframeHtml(html);
+ const missingKeys = result.findings
+ .filter((finding) => finding.severity === "error")
+ .map((finding) => finding.message);
+
+ if (missingKeys.length === 0) {
+ return { isValid: true, missingKeys: [], failureReason: null };
+ }
+
+ const joined = missingKeys.join(" ").toLowerCase();
+ let failureReason: HyperframeStaticFailureReason = "invalid_static_hyperframe_contract";
+ if (joined.includes("data-composition-id")) {
+ failureReason = "missing_composition_id";
+ } else if (joined.includes("data-width") || joined.includes("data-height")) {
+ failureReason = "missing_composition_dimensions";
+ } else if (joined.includes("window.__timelines")) {
+ failureReason = "missing_timeline_registry";
+ } else if (joined.includes("script syntax")) {
+ failureReason = "invalid_script_syntax";
+ }
+
+ return { isValid: false, missingKeys, failureReason };
+}
diff --git a/packages/core/src/compiler/timingCompiler.test.ts b/packages/core/src/compiler/timingCompiler.test.ts
new file mode 100644
index 000000000..13ec8ff73
--- /dev/null
+++ b/packages/core/src/compiler/timingCompiler.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect } from "vitest";
+import { compileTimingAttrs, injectDurations, extractResolvedMedia, clampDurations } from "./timingCompiler.js";
+
+describe("compileTimingAttrs", () => {
+ it("adds data-end when data-start and data-duration are present on a video", () => {
+ const html = '';
+ const { html: compiled, unresolved } = compileTimingAttrs(html);
+
+ expect(compiled).toContain('data-end="7"');
+ expect(compiled).toContain('data-has-audio="true"');
+ expect(unresolved).toHaveLength(0);
+ });
+
+ it("leaves data-end unchanged when already present", () => {
+ const html = '';
+ const { html: compiled, unresolved } = compileTimingAttrs(html);
+
+ expect(compiled).toContain('data-end="3"');
+ expect(compiled).not.toContain("data-duration");
+ expect(unresolved).toHaveLength(0);
+ });
+
+ it("marks video as unresolved when data-duration and data-end are missing", () => {
+ const html = '';
+ const { unresolved } = compileTimingAttrs(html);
+
+ expect(unresolved).toHaveLength(1);
+ expect(unresolved[0].id).toBe("v1");
+ expect(unresolved[0].tagName).toBe("video");
+ expect(unresolved[0].start).toBe(1);
+ });
+
+ it("compiles audio tags the same as video (minus data-has-audio)", () => {
+ const html = '';
+ const { html: compiled } = compileTimingAttrs(html);
+
+ expect(compiled).toContain('data-end="10"');
+ expect(compiled).not.toContain("data-has-audio");
+ });
+
+ it("detects unresolved div/section elements with data-start but no data-end", () => {
+ const html = '';
+ const { unresolved } = compileTimingAttrs(html);
+
+ expect(unresolved).toHaveLength(1);
+ expect(unresolved[0].id).toBe("comp1");
+ expect(unresolved[0].tagName).toBe("div");
+ expect(unresolved[0].compositionSrc).toBe("comp.html");
+ });
+
+ it("does not report div as unresolved when data-end is present", () => {
+ const html = '
';
+ const { unresolved } = compileTimingAttrs(html);
+
+ expect(unresolved).toHaveLength(0);
+ });
+});
+
+describe("injectDurations", () => {
+ it("adds data-duration and data-end for resolved elements", () => {
+ const html = '
';
+ const result = injectDurations(html, [{ id: "v1", duration: 4 }]);
+
+ expect(result).toContain('data-duration="4"');
+ expect(result).toContain('data-end="6"');
+ });
+
+ it("does not overwrite existing data-duration", () => {
+ const html = '';
+ const result = injectDurations(html, [{ id: "v1", duration: 10 }]);
+
+ // data-duration already present, should not be duplicated
+ expect(result).toContain('data-duration="3"');
+ });
+});
+
+describe("extractResolvedMedia", () => {
+ it("extracts video and audio elements with data-duration set", () => {
+ const html = [
+ '',
+ '',
+ '', // no duration
+ ].join("\n");
+
+ const resolved = extractResolvedMedia(html);
+
+ expect(resolved).toHaveLength(2);
+ expect(resolved[0].id).toBe("v1");
+ expect(resolved[0].tagName).toBe("video");
+ expect(resolved[0].duration).toBe(5);
+ expect(resolved[0].start).toBe(1);
+ expect(resolved[1].id).toBe("a1");
+ expect(resolved[1].tagName).toBe("audio");
+ expect(resolved[1].duration).toBe(10);
+ });
+
+ it("skips elements with invalid durations", () => {
+ const html = '';
+ const resolved = extractResolvedMedia(html);
+ expect(resolved).toHaveLength(0);
+ });
+});
+
+describe("clampDurations", () => {
+ it("replaces data-duration and recomputes data-end", () => {
+ const html = '';
+ const result = clampDurations(html, [{ id: "v1", duration: 5 }]);
+
+ expect(result).toContain('data-duration="5"');
+ expect(result).toContain('data-end="7"');
+ });
+});
diff --git a/packages/core/src/compiler/timingCompiler.ts b/packages/core/src/compiler/timingCompiler.ts
new file mode 100644
index 000000000..60a429a0d
--- /dev/null
+++ b/packages/core/src/compiler/timingCompiler.ts
@@ -0,0 +1,250 @@
+/**
+ * Timing Compiler
+ *
+ * Shared, pure HTML compilation that normalizes timing attributes.
+ * Works in both Node.js and browser (no dependencies, regex-based).
+ *
+ * Guarantees every timed element gets:
+ * - data-end (computed from data-start + data-duration when possible)
+ * - data-has-audio="true" on elements
+ *
+ * For elements without data-duration (e.g. videos relying on source duration),
+ * this compiler identifies them as "unresolved" so the caller can provide
+ * durations via an environment-specific resolver (ffprobe, el.duration, etc.)
+ * and call injectDurations() to complete the compilation.
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface UnresolvedElement {
+ id: string;
+ tagName: string;
+ src?: string;
+ start: number;
+ end?: number;
+ duration?: number;
+ mediaStart: number;
+ compositionSrc?: string;
+}
+
+export interface ResolvedDuration {
+ id: string;
+ duration: number;
+}
+
+export interface ResolvedMediaElement {
+ id: string;
+ tagName: string;
+ src?: string;
+ start: number;
+ duration: number;
+ mediaStart: number;
+}
+
+export interface CompilationResult {
+ html: string;
+ unresolved: UnresolvedElement[];
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function getAttr(tag: string, attr: string): string | null {
+ const match = tag.match(new RegExp(`${attr}=["']([^"']+)["']`));
+ return match ? match[1] ?? null : null;
+}
+
+function hasAttr(tag: string, attr: string): boolean {
+ return new RegExp(`${attr}=["']`).test(tag);
+}
+
+function injectAttr(tag: string, attr: string, value: string): string {
+ return tag.replace(/>$/, ` ${attr}="${value}">`);
+}
+
+// ── Core compilation ─────────────────────────────────────────────────────
+
+function compileTag(tag: string, isVideo: boolean): { tag: string; unresolved: UnresolvedElement | null } {
+ let result = tag;
+ let unresolved: UnresolvedElement | null = null;
+
+ const id = getAttr(result, "id");
+ const startStr = getAttr(result, "data-start");
+ const start = startStr !== null ? parseFloat(startStr) : 0;
+ const mediaStartStr = getAttr(result, "data-media-start");
+ const mediaStart = mediaStartStr ? parseFloat(mediaStartStr) : 0;
+
+ // 1. Compute data-end from data-start + data-duration
+ if (!hasAttr(result, "data-end")) {
+ const durationStr = getAttr(result, "data-duration");
+ if (durationStr !== null) {
+ const end = start + parseFloat(durationStr);
+ result = injectAttr(result, "data-end", String(end));
+ } else if (id) {
+ // No data-duration: mark as unresolved so caller can provide it
+ unresolved = {
+ id,
+ tagName: isVideo ? "video" : "audio",
+ src: getAttr(result, "src") ?? undefined,
+ start,
+ mediaStart,
+ };
+ }
+ }
+
+ // 2. Add data-has-audio="true" to elements
+ if (isVideo && !hasAttr(result, "data-has-audio")) {
+ result = injectAttr(result, "data-has-audio", "true");
+ }
+
+ return { tag: result, unresolved };
+}
+
+/**
+ * Compile timing attributes in HTML.
+ *
+ * Phase 1 (static): Adds data-end where data-duration exists,
+ * adds data-has-audio on videos.
+ *
+ * Returns the compiled HTML and a list of elements that could not be
+ * resolved statically (missing data-duration). The caller should resolve
+ * these via ffprobe / el.duration and call injectDurations().
+ */
+export function compileTimingAttrs(html: string): CompilationResult {
+ const unresolved: UnresolvedElement[] = [];
+
+ // Process tags
+ html = html.replace(/]*>/gi, (match) => {
+ const { tag, unresolved: u } = compileTag(match, true);
+ if (u) unresolved.push(u);
+ return tag;
+ });
+
+ // Process tags
+ html = html.replace(/]*>/gi, (match) => {
+ const { tag, unresolved: u } = compileTag(match, false);
+ if (u) unresolved.push(u);
+ return tag;
+ });
+
+ // Identify unresolved timed elements (divs with data-start but no data-end/data-duration)
+ // These are typically compositions whose duration depends on GSAP timelines
+ html.replace(/<(?:div|section)[^>]*>/gi, (match) => {
+ if (!hasAttr(match, "data-start")) return match;
+ if (hasAttr(match, "data-end") || hasAttr(match, "data-duration")) return match;
+
+ const id = getAttr(match, "id");
+ const compositionSrc = getAttr(match, "data-composition-src");
+ if (id) {
+ const startStr = getAttr(match, "data-start");
+ unresolved.push({
+ id,
+ tagName: "div",
+ start: startStr ? parseFloat(startStr) : 0,
+ mediaStart: 0,
+ compositionSrc: compositionSrc ?? undefined,
+ });
+ }
+
+ return match;
+ });
+
+ return { html, unresolved };
+}
+
+/**
+ * Inject resolved durations into compiled HTML.
+ *
+ * For each resolved element, adds data-duration and data-end attributes.
+ * Call this after resolving durations via ffprobe, el.duration, or
+ * GSAP timeline queries.
+ */
+export function injectDurations(html: string, resolutions: ResolvedDuration[]): string {
+ for (const { id, duration } of resolutions) {
+ // Match the element's opening tag by id
+ const idPattern = new RegExp(`(<[^>]*id=["']${escapeRegex(id)}["'][^>]*>)`, "gi");
+
+ html = html.replace(idPattern, (tag) => {
+ let result = tag;
+
+ // Add data-duration if missing
+ if (!hasAttr(result, "data-duration")) {
+ result = injectAttr(result, "data-duration", String(duration));
+ }
+
+ // Add data-end if missing
+ if (!hasAttr(result, "data-end")) {
+ const startStr = getAttr(result, "data-start");
+ const start = startStr ? parseFloat(startStr) : 0;
+ result = injectAttr(result, "data-end", String(start + duration));
+ }
+
+ return result;
+ });
+ }
+
+ return html;
+}
+
+function escapeRegex(str: string): string {
+ return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract video/audio elements that already have data-duration set.
+ * Used by callers to validate declared durations against actual source durations.
+ */
+export function extractResolvedMedia(html: string): ResolvedMediaElement[] {
+ const resolved: ResolvedMediaElement[] = [];
+
+ const mediaRegex = /<(?:video|audio)[^>]*>/gi;
+ let match: RegExpExecArray | null;
+ while ((match = mediaRegex.exec(html)) !== null) {
+ const tag = match[0];
+ const id = getAttr(tag, "id");
+ const durationStr = getAttr(tag, "data-duration");
+ if (!id || durationStr === null) continue;
+
+ const duration = parseFloat(durationStr);
+ if (!Number.isFinite(duration) || duration <= 0) continue;
+
+ const isVideo = /^]*id=["']${escapeRegex(id)}["'][^>]*>)`, "gi");
+
+ html = html.replace(idPattern, (tag) => {
+ // Replace data-duration value
+ tag = tag.replace(/data-duration=["'][^"']*["']/, `data-duration="${duration}"`);
+
+ // Recompute data-end from data-start + clamped duration
+ const startStr = getAttr(tag, "data-start");
+ const start = startStr ? parseFloat(startStr) : 0;
+ tag = tag.replace(/data-end=["'][^"']*["']/, `data-end="${start + duration}"`);
+
+ return tag;
+ });
+ }
+
+ return html;
+}
diff --git a/packages/core/src/core.types.ts b/packages/core/src/core.types.ts
new file mode 100644
index 000000000..80806c395
--- /dev/null
+++ b/packages/core/src/core.types.ts
@@ -0,0 +1,364 @@
+// ── Shared cross-package types ──────────────────────────────────────────────
+
+export type ExecutionMode = "planning" | "design" | "execution" | null;
+
+/** Video orientation / aspect ratio. */
+export type Orientation = "16:9" | "9:16";
+
+export interface Asset {
+ id: string;
+ url: string;
+ type: string;
+ is_reference?: boolean;
+ /** Duration in seconds for video/audio assets */
+ duration?: number;
+}
+
+// ── Timeline types ──────────────────────────────────────────────────────────
+
+export type TimelineElementType = "video" | "image" | "text" | "audio" | "composition";
+export type MediaElementType = "video" | "image" | "audio";
+
+export type CanvasResolution = "landscape" | "portrait";
+
+export const CANVAS_DIMENSIONS = {
+ landscape: { width: 1920, height: 1080 },
+ portrait: { width: 1080, height: 1920 },
+} as const;
+
+export interface TimelineElementBase {
+ id: string;
+ type: TimelineElementType;
+ name: string;
+ startTime: number;
+ duration: number;
+ zIndex: number;
+ x?: number;
+ y?: number;
+ scale?: number;
+ opacity?: number;
+}
+
+export interface TimelineMediaElement extends TimelineElementBase {
+ type: MediaElementType;
+ src: string;
+ mediaStartTime?: number;
+ sourceDuration?: number;
+ isAroll?: boolean;
+ sourceWidth?: number;
+ sourceHeight?: number;
+ volume?: number; // 0-1 (0% to 100%), default 1.0
+ hasAudio?: boolean; // For videos - indicates if video has audio track
+}
+
+export interface WaveformData {
+ peaks: number[];
+ duration: number;
+ sampleRate?: number;
+}
+
+export interface TimelineTextElement extends TimelineElementBase {
+ type: "text";
+ content: string;
+ color?: string;
+ fontSize?: number;
+ textShadow?: boolean;
+ fontFamily?: string;
+ fontWeight?: number;
+ textOutline?: boolean;
+ textOutlineColor?: string;
+ textOutlineWidth?: number;
+ textHighlight?: boolean;
+ textHighlightColor?: string;
+ textHighlightPadding?: number;
+ textHighlightRadius?: number;
+}
+
+export interface TimelineCompositionElement extends TimelineElementBase {
+ type: "composition";
+ src: string;
+ compositionId: string;
+ scale?: number;
+ sourceDuration?: number;
+ variableValues?: Record;
+ sourceWidth?: number;
+ sourceHeight?: number;
+}
+
+// Composition Variable Types
+export type CompositionVariableType = "string" | "number" | "color" | "boolean" | "enum";
+
+export interface CompositionVariableBase {
+ id: string;
+ type: CompositionVariableType;
+ label: string;
+ description?: string;
+}
+
+export interface StringVariable extends CompositionVariableBase {
+ type: "string";
+ default: string;
+ placeholder?: string;
+ maxLength?: number;
+}
+
+export interface NumberVariable extends CompositionVariableBase {
+ type: "number";
+ default: number;
+ min?: number;
+ max?: number;
+ step?: number;
+ unit?: string;
+}
+
+export interface ColorVariable extends CompositionVariableBase {
+ type: "color";
+ default: string;
+}
+
+export interface BooleanVariable extends CompositionVariableBase {
+ type: "boolean";
+ default: boolean;
+}
+
+export interface EnumVariable extends CompositionVariableBase {
+ type: "enum";
+ default: string;
+ options: { value: string; label: string }[];
+}
+
+export type CompositionVariable = StringVariable | NumberVariable | ColorVariable | BooleanVariable | EnumVariable;
+
+export interface CompositionSpec {
+ id: string;
+ duration: number;
+ variables: CompositionVariable[];
+}
+
+export function isStringVariable(v: CompositionVariable): v is StringVariable {
+ return v.type === "string";
+}
+
+export function isNumberVariable(v: CompositionVariable): v is NumberVariable {
+ return v.type === "number";
+}
+
+export function isColorVariable(v: CompositionVariable): v is ColorVariable {
+ return v.type === "color";
+}
+
+export function isBooleanVariable(v: CompositionVariable): v is BooleanVariable {
+ return v.type === "boolean";
+}
+
+export function isEnumVariable(v: CompositionVariable): v is EnumVariable {
+ return v.type === "enum";
+}
+
+export type TimelineElement = TimelineMediaElement | TimelineTextElement | TimelineCompositionElement;
+
+export function isTextElement(el: TimelineElement): el is TimelineTextElement {
+ return el.type === "text";
+}
+
+export function isMediaElement(el: TimelineElement): el is TimelineMediaElement {
+ return el.type === "video" || el.type === "image" || el.type === "audio";
+}
+
+export function isCompositionElement(el: TimelineElement): el is TimelineCompositionElement {
+ return el.type === "composition";
+}
+
+export interface MediaFile {
+ id: string;
+ name: string;
+ type: TimelineElementType;
+ src: string;
+ file?: File;
+ duration?: number;
+ compositionId?: string;
+ sourceWidth?: number; // Intrinsic width for compositions
+ sourceHeight?: number; // Intrinsic height for compositions
+}
+
+export const TIMELINE_COLORS: Record = {
+ video: "#ec4899",
+ image: "#3b82f6",
+ text: "#06b6d4",
+ audio: "#10b981",
+ composition: "#f97316",
+};
+
+export const DEFAULT_DURATIONS: Record = {
+ video: 5,
+ image: 5,
+ text: 2,
+ audio: 5,
+ composition: 5,
+};
+
+export interface CompositionAPI {
+ id: string;
+ duration: number;
+ seek(time: number): void;
+ getTime(): number;
+ getDuration(): number;
+}
+
+// ── Player API types (used by runtime) ────────────────────────────────────
+
+export interface PlayerAPI {
+ play(): void;
+ pause(): void;
+ seek(time: number): void;
+ getTime(): number;
+ getDuration(): number;
+ isPlaying(): boolean;
+ getMainTimeline(): unknown;
+ getElementBounds(elementId: string): void;
+ getElementsAtPoint(x: number, y: number): void;
+ setElementPosition(elementId: string, x: number, y: number): void;
+ previewElementPosition(elementId: string, x: number, y: number): void;
+ setElementKeyframes(
+ elementId: string,
+ keyframes: Array<{
+ id: string;
+ time: number;
+ properties: { x?: number; y?: number };
+ }> | null
+ ): void;
+ setElementScale(elementId: string, scale: number): void;
+ setElementFontSize(elementId: string, fontSize: number): void;
+ setElementTextContent(elementId: string, content: string): void;
+ setElementTextColor(elementId: string, color: string): void;
+ setElementTextShadow(elementId: string, enabled: boolean): void;
+ setElementTextFontWeight(elementId: string, weight: number): void;
+ setElementTextFontFamily(elementId: string, fontFamily: string): void;
+ setElementTextOutline(elementId: string, enabled: boolean, color?: string, width?: number): void;
+ setElementTextHighlight(elementId: string, enabled: boolean, color?: string, padding?: number, radius?: number): void;
+ setElementVolume(elementId: string, volume: number): void;
+ setStageZoom(scale: number, focusX: number, focusY: number): void;
+ getStageZoom(): { scale: number; focusX: number; focusY: number };
+ setStageZoomKeyframes(
+ keyframes: Array<{
+ id: string;
+ time: number;
+ zoom: { scale: number; focusX: number; focusY: number };
+ ease?: string;
+ }> | null
+ ): void;
+ getStageZoomKeyframes(): Array<{
+ id: string;
+ time: number;
+ zoom: { scale: number; focusX: number; focusY: number };
+ ease?: string;
+ }>;
+ addElement(data: AddElementData): boolean;
+ removeElement(elementId: string): boolean;
+ updateElementTiming(elementId: string, start?: number, end?: number): boolean;
+ setElementTiming(elementId: string, startTime: number, duration: number, mediaStartTime?: number): void;
+ updateElementSrc(elementId: string, src: string): boolean;
+ updateElementLayer(elementId: string, zIndex: number): boolean;
+ updateElementBasePosition(elementId: string, x?: number, y?: number, scale?: number): boolean;
+ markTimelineDirty(): void;
+ isTimelineDirty(): boolean;
+ rebuildTimeline(): void;
+ ensureTimeline(): void;
+ enableRenderMode(): void;
+ disableRenderMode(): void;
+ renderSeek(time: number): void;
+ getElementVisibility(elementId: string): { visible: boolean; opacity?: number };
+ getVisibleElements(): Array<{ id: string; tagName: string; start: number; end: number }>;
+ getRenderState(): { time: number; duration: number; isPlaying: boolean; renderMode: boolean; timelineDirty: boolean };
+}
+
+export interface AddElementData {
+ id: string;
+ type: "video" | "image" | "text" | "audio" | "composition";
+ name?: string;
+ src?: string;
+ content?: string;
+ start: number;
+ end: number;
+ zIndex?: number;
+ x?: number;
+ y?: number;
+ scale?: number;
+ fontSize?: number;
+ color?: string;
+ textShadow?: boolean;
+ fontWeight?: number;
+ textOutline?: boolean;
+ textOutlineColor?: string;
+ textOutlineWidth?: number;
+ textHighlight?: boolean;
+ textHighlightColor?: string;
+ textHighlightPadding?: number;
+ textHighlightRadius?: number;
+ compositionId?: string;
+ sourceWidth?: number;
+ sourceHeight?: number;
+ isAroll?: boolean;
+}
+
+export interface ValidationResult {
+ valid: boolean;
+ errors: string[];
+ warnings: string[];
+}
+
+export interface CompositionAsset {
+ id: string;
+ name: string;
+ type: "composition";
+ src: string;
+ duration: number;
+ compositionId: string;
+ thumbnail?: string;
+}
+
+export interface Keyframe {
+ id: string;
+ time: number;
+ properties: Partial;
+ ease?: string;
+}
+
+export interface KeyframeProperties {
+ x: number;
+ y: number;
+ opacity: number;
+ scale: number;
+ scaleX: number;
+ scaleY: number;
+ rotation: number;
+ width: number;
+ height: number;
+}
+
+export interface ElementKeyframes {
+ elementId: string;
+ keyframes: Keyframe[];
+}
+
+export interface StageZoom {
+ scale: number;
+ focusX: number;
+ focusY: number;
+}
+
+export interface StageZoomKeyframe {
+ id: string;
+ time: number;
+ zoom: StageZoom;
+ ease?: string;
+}
+
+export function getDefaultStageZoom(resolution: CanvasResolution): StageZoom {
+ const { width, height } = CANVAS_DIMENSIONS[resolution];
+ return {
+ scale: 1,
+ focusX: width / 2,
+ focusY: height / 2,
+ };
+}
diff --git a/packages/core/src/generators/hyperframes.test.ts b/packages/core/src/generators/hyperframes.test.ts
new file mode 100644
index 000000000..84430eebf
--- /dev/null
+++ b/packages/core/src/generators/hyperframes.test.ts
@@ -0,0 +1,296 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect } from "vitest";
+import { generateHyperframesHtml, generateGsapTimelineScript, generateHyperframesStyles } from "./hyperframes.js";
+import { GSAP_CDN } from "../templates/constants.js";
+import type { TimelineTextElement, TimelineMediaElement, TimelineCompositionElement } from "../core.types";
+
+function makeTextElement(overrides: Partial = {}): TimelineTextElement {
+ return {
+ id: "text-1",
+ type: "text",
+ name: "Title",
+ content: "Hello World",
+ startTime: 0,
+ duration: 5,
+ zIndex: 1,
+ ...overrides,
+ };
+}
+
+function makeVideoElement(overrides: Partial = {}): TimelineMediaElement {
+ return {
+ id: "vid-1",
+ type: "video",
+ name: "Background",
+ src: "video.mp4",
+ startTime: 0,
+ duration: 10,
+ zIndex: 0,
+ ...overrides,
+ };
+}
+
+describe("generateHyperframesHtml", () => {
+ it("generates valid HTML with proper data attributes", () => {
+ const elements = [makeTextElement()];
+ const html = generateHyperframesHtml(elements, 5);
+
+ expect(html).toContain("");
+ expect(html).toContain("data-composition-id=");
+ expect(html).toContain("data-composition-duration=");
+ expect(html).toContain('id="stage"');
+ expect(html).toContain('id="stage-zoom-container"');
+ });
+
+ it("includes element data attributes", () => {
+ const elements = [makeTextElement({ id: "my-text", startTime: 2, duration: 3 })];
+ const html = generateHyperframesHtml(elements, 5);
+
+ expect(html).toContain('id="my-text"');
+ expect(html).toContain('data-start="2"');
+ expect(html).toContain('data-end="5"');
+ expect(html).toContain('data-layer="1"');
+ });
+
+ it("includes GSAP CDN script tag when includeScripts is true", () => {
+ const elements = [makeTextElement()];
+ const html = generateHyperframesHtml(elements, 5, { includeScripts: true });
+
+ expect(html).toContain(``);
+ });
+
+ it("does NOT include GSAP CDN by default", () => {
+ const elements = [makeTextElement()];
+ const html = generateHyperframesHtml(elements, 5);
+
+ expect(html).not.toContain(GSAP_CDN);
+ });
+
+ it("includes timeline script when includeScripts is true", () => {
+ const elements = [makeTextElement()];
+ const html = generateHyperframesHtml(elements, 5, { includeScripts: true });
+
+ expect(html).toContain("gsap.timeline({ paused: true })");
+ });
+
+ it("generates GSAP timeline with visibility animations when includeScripts is true", () => {
+ const elements = [makeTextElement({ id: "el-1", startTime: 1, duration: 3 })];
+ const html = generateHyperframesHtml(elements, 5, { includeScripts: true });
+
+ // Default animations include visibility bookends
+ expect(html).toContain('tl.set("#el-1"');
+ expect(html).toContain('visibility: "hidden"');
+ expect(html).toContain('visibility: "visible"');
+ });
+
+ it("sets resolution data attribute", () => {
+ const elements = [makeTextElement()];
+
+ const landscapeHtml = generateHyperframesHtml(elements, 5, { resolution: "landscape" });
+ expect(landscapeHtml).toContain('data-resolution="landscape"');
+
+ const portraitHtml = generateHyperframesHtml(elements, 5, { resolution: "portrait" });
+ expect(portraitHtml).toContain('data-resolution="portrait"');
+ });
+
+ it("generates video elements with proper tags", () => {
+ const elements = [makeVideoElement()];
+ const html = generateHyperframesHtml(elements, 10);
+
+ expect(html).toContain(" {
+ const elements = [makeTextElement({ content: "My Content" })];
+ const html = generateHyperframesHtml(elements, 5);
+
+ expect(html).toContain("My Content
");
+ });
+
+ it("includes custom compositionId", () => {
+ const elements = [makeTextElement()];
+ const html = generateHyperframesHtml(elements, 5, { compositionId: "test-comp-123" });
+
+ expect(html).toContain('data-composition-id="test-comp-123"');
+ });
+
+ it("calculates total duration from elements if they exceed provided duration", () => {
+ const elements = [makeTextElement({ startTime: 0, duration: 15 })];
+ const html = generateHyperframesHtml(elements, 5);
+
+ expect(html).toContain('data-composition-duration="15"');
+ });
+
+ it("includes style tags when includeStyles is true", () => {
+ const elements = [makeTextElement()];
+ const html = generateHyperframesHtml(elements, 5, { includeStyles: true });
+
+ expect(html).toContain('`
+ : "",
+ customCss
+ ? ` `
+ : "",
+ ]
+ .filter(Boolean)
+ .join("\n")
+ : "";
+
+ const customStylesAttr = customStyles
+ ? ` data-custom-styles='${JSON.stringify(customStyles).replace(/'/g, "'")}'`
+ : "";
+
+ const resolutionAttr = ` data-resolution="${resolution}"`;
+
+ return `
+
+
+ ): string {
+ const sets: string[] = [];
+ const timeEpsilon = 0.001;
+
+ for (const el of elements) {
+ const elementKeyframes = keyframes?.[el.id];
+ const hasBaseKeyframe = elementKeyframes?.some(
+ (kf) =>
+ Math.abs(kf.time) <= timeEpsilon &&
+ (kf.properties.x !== undefined || kf.properties.y !== undefined || kf.properties.scale !== undefined),
+ );
+
+ const xVal = el.x ?? 0;
+ const yVal = el.y ?? 0;
+ const scaleVal = isMediaElement(el) ? (el.scale ?? 1) : 1;
+
+ // Audio elements don't need positioning
+ if (el.type === "audio") continue;
+
+ // Composition elements (motion designs) are full-screen overlays
+ // They don't need x/y/scale positioning - the HTML handles internal layout
+ if (isCompositionElement(el)) continue;
+
+ // Skip if element has a base keyframe that will handle positioning
+ if (hasBaseKeyframe) {
+ continue;
+ }
+
+ // Set position and scale (xPercent/yPercent applied at player init)
+ if (scaleVal !== 1) {
+ sets.push(` tl.set("#${el.id}", { x: ${xVal}, y: ${yVal}, scale: ${scaleVal} }, 0);`);
+ } else if (xVal !== 0 || yVal !== 0) {
+ sets.push(` tl.set("#${el.id}", { x: ${xVal}, y: ${yVal} }, 0);`);
+ }
+ }
+
+ return sets.length > 0 ? sets.join("\n") : "";
+}
+
+/**
+ * Generates visibility bookends for ALL elements to ensure they appear/disappear
+ * at the correct times. Elements with keyframes still need visibility bookends
+ * because keyframesToGsapAnimations only handles property animations, not visibility.
+ *
+ * If opacity keyframes exist, the first keyframe defines the base.
+ */
+function generateVisibilityForElementsWithoutKeyframes(
+ elements: TimelineElement[],
+ keyframes?: Record,
+): string {
+ const animations: string[] = [];
+
+ for (const el of elements) {
+ const elementKeyframes = keyframes?.[el.id];
+ const opacityKeyframes = elementKeyframes?.filter((kf) => kf.properties.opacity !== undefined) || [];
+ const start = el.startTime;
+ const end = el.startTime + el.duration;
+
+ const safeName = el.name.replace(/[\r\n]+/g, " ");
+ animations.push(` // ${safeName} (visibility)`);
+ animations.push(` tl.set("#${el.id}", { visibility: "hidden" }, 0);`);
+
+ let elementOpacity = el.opacity ?? 1;
+ if (opacityKeyframes.length > 0) {
+ const firstOpacityKeyframe = [...opacityKeyframes].sort((a, b) => a.time - b.time)[0];
+ if (firstOpacityKeyframe?.properties.opacity !== undefined) {
+ elementOpacity = firstOpacityKeyframe.properties.opacity;
+ }
+ }
+ // Only include opacity in visibility bookend if non-default or has opacity keyframes
+ const needsOpacity = elementOpacity !== 1 || opacityKeyframes.length > 0;
+ if (needsOpacity) {
+ animations.push(` tl.set("#${el.id}", { visibility: "visible", opacity: ${elementOpacity} }, ${start});`);
+ } else {
+ animations.push(` tl.set("#${el.id}", { visibility: "visible" }, ${start});`);
+ }
+
+ animations.push(` tl.set("#${el.id}", { visibility: "hidden" }, ${end});`);
+ }
+
+ return animations.length > 0 ? animations.join("\n") : "";
+}
+
+function generateDefaultGsapAnimations(
+ elements: TimelineElement[],
+ totalDuration: number,
+ stageZoomKeyframes?: StageZoomKeyframe[],
+ canvasWidth?: number,
+ canvasHeight?: number,
+): string {
+ if (elements.length === 0 && (!stageZoomKeyframes || stageZoomKeyframes.length === 0)) {
+ return `
+ const tl = gsap.timeline({ paused: true });
+ tl.to({}, { duration: ${totalDuration || 1} });
+ `;
+ }
+
+ const animations: string[] = [];
+
+ // First, set initial positions and scales for elements with x/y offsets or scale
+ const initialPositionSets = generateInitialPositionSets(elements);
+ if (initialPositionSets) {
+ animations.push(initialPositionSets);
+ }
+
+ for (const el of elements) {
+ const start = el.startTime;
+ const end = el.startTime + el.duration;
+
+ const safeName = el.name.replace(/[\r\n]+/g, " ");
+ const elementOpacity = el.opacity ?? 1;
+ animations.push(` // ${safeName}`);
+ animations.push(` tl.set("#${el.id}", { visibility: "hidden" }, 0);`);
+ // Only include opacity if non-default
+ if (elementOpacity !== 1) {
+ animations.push(` tl.set("#${el.id}", { visibility: "visible", opacity: ${elementOpacity} }, ${start});`);
+ } else {
+ animations.push(` tl.set("#${el.id}", { visibility: "visible" }, ${start});`);
+ }
+ animations.push(` tl.set("#${el.id}", { visibility: "hidden" }, ${end});`);
+ }
+
+ const mediaElements = elements.filter((el) => el.type === "video" || el.type === "audio");
+ const mediaSync =
+ mediaElements.length > 0
+ ? `
+ // Sync media playback
+ tl.eventCallback("onUpdate", function() {
+ const time = tl.time();
+ document.querySelectorAll("video[data-start], audio[data-start]").forEach(function(media) {
+ const start = parseFloat(media.dataset.start);
+ const end = parseFloat(media.dataset.end) || Infinity;
+ const mediaTime = time - start;
+ if (time >= start && time < end) {
+ if (Math.abs(media.currentTime - mediaTime) > 0.1) {
+ media.currentTime = mediaTime;
+ }
+ if (media.paused && !tl.paused()) {
+ media.play().catch(function() {});
+ }
+ } else if (!media.paused) {
+ media.pause();
+ }
+ });
+ });`
+ : "";
+
+ // Generate zoom animations if present
+ const zoomAnimations =
+ stageZoomKeyframes && stageZoomKeyframes.length > 0 && canvasWidth && canvasHeight
+ ? "\n" + generateZoomGsapAnimations(stageZoomKeyframes, canvasWidth, canvasHeight)
+ : "";
+
+ return `
+ const tl = gsap.timeline({ paused: true });
+${animations.join("\n")}
+ ${mediaSync}${zoomAnimations}
+ `;
+}
diff --git a/packages/core/src/index.test.ts b/packages/core/src/index.test.ts
new file mode 100644
index 000000000..4587b5f61
--- /dev/null
+++ b/packages/core/src/index.test.ts
@@ -0,0 +1,162 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest";
+import * as core from "./index.js";
+
+describe("@hyperframes/core public API exports", () => {
+ describe("type-related constants and utilities", () => {
+ it("exports CANVAS_DIMENSIONS", () => {
+ expect(core.CANVAS_DIMENSIONS).toBeDefined();
+ expect(core.CANVAS_DIMENSIONS.landscape).toEqual({ width: 1920, height: 1080 });
+ expect(core.CANVAS_DIMENSIONS.portrait).toEqual({ width: 1080, height: 1920 });
+ });
+
+ it("exports TIMELINE_COLORS", () => {
+ expect(core.TIMELINE_COLORS).toBeDefined();
+ expect(core.TIMELINE_COLORS.video).toBeDefined();
+ expect(core.TIMELINE_COLORS.image).toBeDefined();
+ expect(core.TIMELINE_COLORS.text).toBeDefined();
+ expect(core.TIMELINE_COLORS.audio).toBeDefined();
+ expect(core.TIMELINE_COLORS.composition).toBeDefined();
+ });
+
+ it("exports DEFAULT_DURATIONS", () => {
+ expect(core.DEFAULT_DURATIONS).toBeDefined();
+ expect(core.DEFAULT_DURATIONS.video).toBe(5);
+ expect(core.DEFAULT_DURATIONS.text).toBe(2);
+ });
+
+ it("exports type guard functions", () => {
+ expect(typeof core.isTextElement).toBe("function");
+ expect(typeof core.isMediaElement).toBe("function");
+ expect(typeof core.isCompositionElement).toBe("function");
+ });
+
+ it("exports getDefaultStageZoom", () => {
+ expect(typeof core.getDefaultStageZoom).toBe("function");
+ const zoom = core.getDefaultStageZoom("landscape");
+ expect(zoom.scale).toBe(1);
+ expect(zoom.focusX).toBe(960);
+ expect(zoom.focusY).toBe(540);
+ });
+
+ it("exports composition variable type guards", () => {
+ expect(typeof core.isStringVariable).toBe("function");
+ expect(typeof core.isNumberVariable).toBe("function");
+ expect(typeof core.isColorVariable).toBe("function");
+ expect(typeof core.isBooleanVariable).toBe("function");
+ expect(typeof core.isEnumVariable).toBe("function");
+ });
+ });
+
+ describe("template exports", () => {
+ it("exports generateBaseHtml", () => {
+ expect(typeof core.generateBaseHtml).toBe("function");
+ });
+
+ it("exports getStageStyles", () => {
+ expect(typeof core.getStageStyles).toBe("function");
+ });
+
+ it("exports template constants", () => {
+ expect(core.GSAP_CDN).toBeDefined();
+ expect(core.BASE_STYLES).toBeDefined();
+ expect(core.ELEMENT_BASE_STYLES).toBeDefined();
+ expect(core.MEDIA_STYLES).toBeDefined();
+ expect(core.TEXT_STYLES).toBeDefined();
+ expect(core.ZOOM_CONTAINER_STYLES).toBeDefined();
+ });
+ });
+
+ describe("parser exports", () => {
+ it("exports GSAP parser functions", () => {
+ expect(typeof core.parseGsapScript).toBe("function");
+ expect(typeof core.serializeGsapAnimations).toBe("function");
+ expect(typeof core.updateAnimationInScript).toBe("function");
+ expect(typeof core.addAnimationToScript).toBe("function");
+ expect(typeof core.removeAnimationFromScript).toBe("function");
+ expect(typeof core.getAnimationsForElement).toBe("function");
+ expect(typeof core.validateCompositionGsap).toBe("function");
+ expect(typeof core.keyframesToGsapAnimations).toBe("function");
+ expect(typeof core.gsapAnimationsToKeyframes).toBe("function");
+ });
+
+ it("exports GSAP constants", () => {
+ expect(core.SUPPORTED_PROPS).toBeDefined();
+ expect(Array.isArray(core.SUPPORTED_PROPS)).toBe(true);
+ expect(core.SUPPORTED_EASES).toBeDefined();
+ expect(Array.isArray(core.SUPPORTED_EASES)).toBe(true);
+ });
+
+ it("exports HTML parser functions", () => {
+ expect(typeof core.parseHtml).toBe("function");
+ expect(typeof core.updateElementInHtml).toBe("function");
+ expect(typeof core.addElementToHtml).toBe("function");
+ expect(typeof core.removeElementFromHtml).toBe("function");
+ expect(typeof core.validateCompositionHtml).toBe("function");
+ expect(typeof core.extractCompositionMetadata).toBe("function");
+ });
+ });
+
+ describe("generator exports", () => {
+ it("exports hyperframes generator functions", () => {
+ expect(typeof core.generateHyperframesHtml).toBe("function");
+ expect(typeof core.generateGsapTimelineScript).toBe("function");
+ expect(typeof core.generateHyperframesStyles).toBe("function");
+ });
+ });
+
+ describe("compiler exports", () => {
+ it("exports compiler functions", () => {
+ expect(typeof core.compileTimingAttrs).toBe("function");
+ expect(typeof core.injectDurations).toBe("function");
+ expect(typeof core.extractResolvedMedia).toBe("function");
+ expect(typeof core.clampDurations).toBe("function");
+ });
+ });
+
+ describe("lint exports", () => {
+ it("exports lintHyperframeHtml", () => {
+ expect(typeof core.lintHyperframeHtml).toBe("function");
+ });
+ });
+
+ describe("inline-script exports", () => {
+ it("exports hyperframe runtime artifacts", () => {
+ expect(core.HYPERFRAME_RUNTIME_ARTIFACTS).toBeDefined();
+ expect(core.HYPERFRAME_RUNTIME_CONTRACT).toBeDefined();
+ expect(typeof core.loadHyperframeRuntimeSource).toBe("function");
+ });
+
+ it("exports runtime contract constants", () => {
+ expect(core.HYPERFRAME_RUNTIME_GLOBALS).toBeDefined();
+ expect(core.HYPERFRAME_BRIDGE_SOURCES).toBeDefined();
+ expect(core.HYPERFRAME_CONTROL_ACTIONS).toBeDefined();
+ });
+
+ it("exports buildHyperframesRuntimeScript", () => {
+ expect(typeof core.buildHyperframesRuntimeScript).toBe("function");
+ });
+
+ it("exports MEDIA_VISUAL_STYLE_PROPERTIES", () => {
+ expect(core.MEDIA_VISUAL_STYLE_PROPERTIES).toBeDefined();
+ expect(Array.isArray(core.MEDIA_VISUAL_STYLE_PROPERTIES)).toBe(true);
+ expect(core.MEDIA_VISUAL_STYLE_PROPERTIES).toContain("width");
+ expect(core.MEDIA_VISUAL_STYLE_PROPERTIES).toContain("opacity");
+ expect(core.MEDIA_VISUAL_STYLE_PROPERTIES).toContain("transform");
+ });
+
+ it("exports copyMediaVisualStyles", () => {
+ expect(typeof core.copyMediaVisualStyles).toBe("function");
+ });
+
+ it("exports quantizeTimeToFrame", () => {
+ expect(typeof core.quantizeTimeToFrame).toBe("function");
+ });
+ });
+
+ describe("adapter exports", () => {
+ it("exports createGSAPFrameAdapter", () => {
+ expect(typeof core.createGSAPFrameAdapter).toBe("function");
+ });
+ });
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
new file mode 100644
index 000000000..76172e795
--- /dev/null
+++ b/packages/core/src/index.ts
@@ -0,0 +1,146 @@
+// Types
+export type {
+ ExecutionMode,
+ Orientation,
+ Asset,
+ TimelineElement,
+ TimelineElementBase,
+ TimelineMediaElement,
+ TimelineTextElement,
+ TimelineCompositionElement,
+ TimelineElementType,
+ MediaElementType,
+ CanvasResolution,
+ MediaFile,
+ CompositionAPI,
+ PlayerAPI,
+ AddElementData,
+ ValidationResult,
+ CompositionAsset,
+ Keyframe,
+ KeyframeProperties,
+ ElementKeyframes,
+ StageZoom,
+ StageZoomKeyframe,
+ CompositionVariableType,
+ CompositionVariableBase,
+ StringVariable,
+ NumberVariable,
+ ColorVariable,
+ BooleanVariable,
+ EnumVariable,
+ CompositionVariable,
+ CompositionSpec,
+ WaveformData,
+} from "./core.types";
+
+export {
+ CANVAS_DIMENSIONS,
+ TIMELINE_COLORS,
+ DEFAULT_DURATIONS,
+ isTextElement,
+ isMediaElement,
+ isCompositionElement,
+ getDefaultStageZoom,
+ isStringVariable,
+ isNumberVariable,
+ isColorVariable,
+ isBooleanVariable,
+ isEnumVariable,
+} from "./core.types";
+
+// Templates
+export { generateBaseHtml, getStageStyles } from "./templates/base";
+export {
+ GSAP_CDN,
+ BASE_STYLES,
+ ELEMENT_BASE_STYLES,
+ MEDIA_STYLES,
+ TEXT_STYLES,
+ ZOOM_CONTAINER_STYLES,
+} from "./templates/constants";
+
+// Parsers
+export type { GsapAnimation, GsapMethod, ParsedGsap } from "./parsers/gsapParser";
+
+export {
+ parseGsapScript,
+ serializeGsapAnimations,
+ updateAnimationInScript,
+ addAnimationToScript,
+ removeAnimationFromScript,
+ getAnimationsForElement,
+ validateCompositionGsap,
+ keyframesToGsapAnimations,
+ gsapAnimationsToKeyframes,
+ SUPPORTED_PROPS,
+ SUPPORTED_EASES,
+} from "./parsers/gsapParser";
+
+export type { ParsedHtml, CompositionMetadata } from "./parsers/htmlParser";
+
+export {
+ parseHtml,
+ updateElementInHtml,
+ addElementToHtml,
+ removeElementFromHtml,
+ validateCompositionHtml,
+ extractCompositionMetadata,
+} from "./parsers/htmlParser";
+
+// Generators
+export type { SerializeOptions } from "./generators/hyperframes";
+
+export {
+ generateHyperframesHtml,
+ generateGsapTimelineScript,
+ generateHyperframesStyles,
+} from "./generators/hyperframes";
+
+// Compiler (timing only — browser-safe, no cheerio/esbuild)
+export type { UnresolvedElement, ResolvedDuration, ResolvedMediaElement, CompilationResult } from "./compiler/timingCompiler";
+
+export { compileTimingAttrs, injectDurations, extractResolvedMedia, clampDurations } from "./compiler/timingCompiler";
+
+// Lint
+export type {
+ HyperframeLintSeverity,
+ HyperframeLintFinding,
+ HyperframeLintResult,
+ HyperframeLinterOptions,
+} from "./lint/types";
+export { lintHyperframeHtml } from "./lint/hyperframeLinter";
+
+// Inline scripts
+export {
+ HYPERFRAME_RUNTIME_ARTIFACTS,
+ HYPERFRAME_RUNTIME_CONTRACT,
+ loadHyperframeRuntimeSource,
+ type HyperframeRuntimeContract,
+} from "./inline-scripts/hyperframe";
+export {
+ HYPERFRAME_RUNTIME_GLOBALS,
+ HYPERFRAME_BRIDGE_SOURCES,
+ HYPERFRAME_CONTROL_ACTIONS,
+ type HyperframeControlAction,
+} from "./inline-scripts/runtimeContract";
+export {
+ buildHyperframesRuntimeScript,
+ type HyperframesRuntimeBuildOptions,
+} from "./inline-scripts/hyperframesRuntime.engine";
+export {
+ MEDIA_VISUAL_STYLE_PROPERTIES,
+ copyMediaVisualStyles,
+ quantizeTimeToFrame,
+ type MediaVisualStyleProperty,
+} from "./inline-scripts/parityContract";
+export type {
+ HyperframePickerApi,
+ HyperframePickerBoundingBox,
+ HyperframePickerElementInfo,
+} from "./inline-scripts/pickerApi";
+
+// Frame adapters
+export type { FrameAdapter, FrameAdapterContext } from "./adapters/types";
+export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./adapters/gsap";
+export { createGSAPFrameAdapter } from "./adapters/gsap";
diff --git a/packages/core/src/inline-scripts/hyperframe.ts b/packages/core/src/inline-scripts/hyperframe.ts
new file mode 100644
index 000000000..698783339
--- /dev/null
+++ b/packages/core/src/inline-scripts/hyperframe.ts
@@ -0,0 +1,22 @@
+import { buildHyperframesRuntimeScript } from "./hyperframesRuntime.engine";
+import { HYPERFRAME_BRIDGE_SOURCES, HYPERFRAME_RUNTIME_GLOBALS } from "./runtimeContract";
+
+export const HYPERFRAME_RUNTIME_ARTIFACTS = {
+ iife: "hyperframe.runtime.iife.js",
+ esm: "hyperframe.runtime.mjs",
+ manifest: "hyperframe.manifest.json",
+} as const;
+
+export type HyperframeRuntimeContract = {
+ globals: typeof HYPERFRAME_RUNTIME_GLOBALS;
+ messageSources: typeof HYPERFRAME_BRIDGE_SOURCES;
+};
+
+export const HYPERFRAME_RUNTIME_CONTRACT: HyperframeRuntimeContract = {
+ globals: HYPERFRAME_RUNTIME_GLOBALS,
+ messageSources: HYPERFRAME_BRIDGE_SOURCES,
+};
+
+export function loadHyperframeRuntimeSource(): string {
+ return buildHyperframesRuntimeScript();
+}
diff --git a/packages/core/src/inline-scripts/hyperframesRuntime.engine.ts b/packages/core/src/inline-scripts/hyperframesRuntime.engine.ts
new file mode 100644
index 000000000..cfa3f5ae5
--- /dev/null
+++ b/packages/core/src/inline-scripts/hyperframesRuntime.engine.ts
@@ -0,0 +1,37 @@
+import { buildSync } from "esbuild";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type HyperframesRuntimeBuildOptions = {
+ sourceUrl?: string;
+ defaultParityMode?: boolean;
+ minify?: boolean;
+};
+
+function applyDefaultParityMode(script: string, enabled: boolean): string {
+ const parityFlagPattern = /var\s+_parityModeEnabled\s*=\s*(?:true|false)\s*;/;
+ if (!parityFlagPattern.test(script)) return script;
+ return script.replace(parityFlagPattern, `var _parityModeEnabled = ${enabled ? "true" : "false"};`);
+}
+
+export function buildHyperframesRuntimeScript(options: HyperframesRuntimeBuildOptions = {}): string {
+ const entryPath = resolve(dirname(fileURLToPath(import.meta.url)), "../runtime/entry.ts");
+ const result = buildSync({
+ entryPoints: [entryPath],
+ bundle: true,
+ write: false,
+ platform: "browser",
+ format: "iife",
+ target: ["es2020"],
+ minify: options.minify ?? true,
+ legalComments: "none",
+ });
+ let script = result.outputFiles[0]?.text ?? "";
+ if (typeof options.defaultParityMode === "boolean") {
+ script = applyDefaultParityMode(script, options.defaultParityMode);
+ }
+ if (options.sourceUrl && options.sourceUrl.trim()) {
+ script = `${script}\n//# sourceURL=${options.sourceUrl.trim()}`;
+ }
+ return script;
+}
diff --git a/packages/core/src/inline-scripts/parityContract.test.ts b/packages/core/src/inline-scripts/parityContract.test.ts
new file mode 100644
index 000000000..58da0044e
--- /dev/null
+++ b/packages/core/src/inline-scripts/parityContract.test.ts
@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "./parityContract.js";
+
+describe("quantizeTimeToFrame", () => {
+ it("quantizes a time to the nearest frame boundary at 30fps", () => {
+ // 1.5s at 30fps = frame 45 => 45/30 = 1.5
+ expect(quantizeTimeToFrame(1.5, 30)).toBe(1.5);
+ });
+
+ it("floors to the previous frame boundary", () => {
+ // 1.51s at 30fps: floor(1.51*30 + 1e-9) = floor(45.3) = 45 => 45/30 = 1.5
+ expect(quantizeTimeToFrame(1.51, 30)).toBe(1.5);
+ });
+
+ it("handles exact frame boundaries", () => {
+ // 1.0s at 24fps: floor(1.0*24 + 1e-9) = 24 => 24/24 = 1.0
+ expect(quantizeTimeToFrame(1.0, 24)).toBe(1.0);
+ });
+
+ it("returns 0 for zero time", () => {
+ expect(quantizeTimeToFrame(0, 30)).toBe(0);
+ });
+
+ it("returns 0 for negative time", () => {
+ expect(quantizeTimeToFrame(-1, 30)).toBe(0);
+ });
+
+ it("defaults to 30fps for invalid fps", () => {
+ // When fps is invalid, safeFps falls back to 30
+ // quantizeTimeToFrame(1, 0) => floor(1*30+eps)/30 = 1
+ expect(quantizeTimeToFrame(1, 0)).toBe(1);
+ expect(quantizeTimeToFrame(1, NaN)).toBe(1);
+ expect(quantizeTimeToFrame(1, -10)).toBe(1);
+ });
+
+ it("handles NaN time gracefully", () => {
+ expect(quantizeTimeToFrame(NaN, 30)).toBe(0);
+ });
+
+ it("handles 60fps correctly", () => {
+ // 0.5s at 60fps: floor(0.5*60 + 1e-9) = 30 => 30/60 = 0.5
+ expect(quantizeTimeToFrame(0.5, 60)).toBe(0.5);
+ });
+});
+
+describe("MEDIA_VISUAL_STYLE_PROPERTIES", () => {
+ it("is a non-empty readonly array", () => {
+ expect(MEDIA_VISUAL_STYLE_PROPERTIES.length).toBeGreaterThan(0);
+ });
+
+ it("includes core layout properties", () => {
+ expect(MEDIA_VISUAL_STYLE_PROPERTIES).toContain("width");
+ expect(MEDIA_VISUAL_STYLE_PROPERTIES).toContain("height");
+ expect(MEDIA_VISUAL_STYLE_PROPERTIES).toContain("transform");
+ expect(MEDIA_VISUAL_STYLE_PROPERTIES).toContain("opacity");
+ });
+});
diff --git a/packages/core/src/inline-scripts/parityContract.ts b/packages/core/src/inline-scripts/parityContract.ts
new file mode 100644
index 000000000..a57165656
--- /dev/null
+++ b/packages/core/src/inline-scripts/parityContract.ts
@@ -0,0 +1,50 @@
+export const MEDIA_VISUAL_STYLE_PROPERTIES = [
+ "width",
+ "height",
+ "top",
+ "left",
+ "right",
+ "bottom",
+ "inset",
+ "object-fit",
+ "object-position",
+ "z-index",
+ "opacity",
+ "visibility",
+ "filter",
+ "mix-blend-mode",
+ "backdrop-filter",
+ "border-radius",
+ "overflow",
+ "clip-path",
+ "mask",
+ "mask-image",
+ "mask-size",
+ "mask-position",
+ "mask-repeat",
+ "transform",
+ "transform-origin",
+ "box-sizing",
+] as const;
+
+export type MediaVisualStyleProperty = (typeof MEDIA_VISUAL_STYLE_PROPERTIES)[number];
+
+export function quantizeTimeToFrame(timeSeconds: number, fps: number): number {
+ const safeFps = Number.isFinite(fps) && fps > 0 ? fps : 30;
+ const safeTime = Number.isFinite(timeSeconds) && timeSeconds > 0 ? timeSeconds : 0;
+ const frameIndex = Math.floor(safeTime * safeFps + 1e-9);
+ return frameIndex / safeFps;
+}
+
+export function copyMediaVisualStyles(
+ targetStyle: CSSStyleDeclaration,
+ sourceStyle: CSSStyleDeclaration,
+ properties: readonly string[] = MEDIA_VISUAL_STYLE_PROPERTIES,
+): void {
+ for (const property of properties) {
+ const value = sourceStyle.getPropertyValue(property);
+ if (value) {
+ targetStyle.setProperty(property, value);
+ }
+ }
+}
diff --git a/packages/core/src/inline-scripts/pickerApi.ts b/packages/core/src/inline-scripts/pickerApi.ts
new file mode 100644
index 000000000..5231bacb4
--- /dev/null
+++ b/packages/core/src/inline-scripts/pickerApi.ts
@@ -0,0 +1,34 @@
+export type HyperframePickerBoundingBox = {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+};
+
+export type HyperframePickerElementInfo = {
+ id: string | null;
+ tagName: string;
+ selector: string;
+ label: string;
+ boundingBox: HyperframePickerBoundingBox;
+ textContent: string | null;
+ src: string | null;
+ dataAttributes: Record;
+};
+
+export type HyperframePickerApi = {
+ enable: () => void;
+ disable: () => void;
+ isActive: () => boolean;
+ getHovered: () => HyperframePickerElementInfo | null;
+ getSelected: () => HyperframePickerElementInfo | null;
+ getCandidatesAtPoint: (clientX: number, clientY: number, limit?: number) => HyperframePickerElementInfo[];
+ pickAtPoint: (clientX: number, clientY: number, index?: number) => HyperframePickerElementInfo | null;
+ pickManyAtPoint: (clientX: number, clientY: number, indexes?: number[]) => HyperframePickerElementInfo[];
+};
+
+declare global {
+ interface Window {
+ __HF_PICKER_API?: HyperframePickerApi;
+ }
+}
diff --git a/packages/core/src/inline-scripts/runtimeContract.ts b/packages/core/src/inline-scripts/runtimeContract.ts
new file mode 100644
index 000000000..55d093490
--- /dev/null
+++ b/packages/core/src/inline-scripts/runtimeContract.ts
@@ -0,0 +1,24 @@
+export const HYPERFRAME_RUNTIME_GLOBALS = {
+ player: "__player",
+ playerReady: "__playerReady",
+ renderReady: "__renderReady",
+ timelines: "__timelines",
+ clipManifest: "__clipManifest",
+} as const;
+
+export const HYPERFRAME_BRIDGE_SOURCES = {
+ parent: "hf-parent",
+ preview: "hf-preview",
+} as const;
+
+export const HYPERFRAME_CONTROL_ACTIONS = [
+ "play",
+ "pause",
+ "seek",
+ "set-muted",
+ "set-playback-rate",
+ "enable-pick-mode",
+ "disable-pick-mode",
+] as const;
+
+export type HyperframeControlAction = (typeof HYPERFRAME_CONTROL_ACTIONS)[number];
diff --git a/packages/core/src/lint/hyperframeLinter.test.ts b/packages/core/src/lint/hyperframeLinter.test.ts
new file mode 100644
index 000000000..3a14dc691
--- /dev/null
+++ b/packages/core/src/lint/hyperframeLinter.test.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { lintHyperframeHtml } from "./hyperframeLinter.js";
+
+describe("lintHyperframeHtml", () => {
+ const validComposition = `
+
+
+
+
+
+
+`;
+
+ it("reports no errors for a valid composition", () => {
+ const result = lintHyperframeHtml(validComposition);
+ expect(result.ok).toBe(true);
+ expect(result.errorCount).toBe(0);
+ });
+
+ it("reports error when root is missing data-composition-id", () => {
+ const html = `
+
+
+
+`;
+ const result = lintHyperframeHtml(html);
+ const finding = result.findings.find((f) => f.code === "root_missing_composition_id");
+ expect(finding).toBeDefined();
+ expect(finding?.severity).toBe("error");
+ });
+
+ it("reports error when root is missing data-width or data-height", () => {
+ const html = `
+
+
+
+`;
+ const result = lintHyperframeHtml(html);
+ const finding = result.findings.find((f) => f.code === "root_missing_dimensions");
+ expect(finding).toBeDefined();
+ expect(finding?.severity).toBe("error");
+ });
+
+ it("reports error when timeline registry is missing", () => {
+ const html = `
+
+
+
+`;
+ const result = lintHyperframeHtml(html);
+ const finding = result.findings.find((f) => f.code === "missing_timeline_registry");
+ expect(finding).toBeDefined();
+ });
+
+ it("reports error for duplicate media ids", () => {
+ const html = `
+
+
+
+
+`;
+ const result = lintHyperframeHtml(html);
+ const finding = result.findings.find((f) => f.code === "duplicate_media_id");
+ expect(finding).toBeDefined();
+ expect(finding?.severity).toBe("error");
+ expect(finding?.elementId).toBe("v1");
+ });
+
+ it("reports error for composition host missing data-composition-id", () => {
+ const html = `
+
+
+
+`;
+ const result = lintHyperframeHtml(html);
+ const finding = result.findings.find((f) => f.code === "host_missing_composition_id");
+ expect(finding).toBeDefined();
+ });
+
+ it("attaches filePath to findings when option is set", () => {
+ const html = "
";
+ const result = lintHyperframeHtml(html, { filePath: "test.html" });
+ for (const finding of result.findings) {
+ expect(finding.file).toBe("test.html");
+ }
+ });
+
+ it("deduplicates identical findings", () => {
+ // Calling with the same HTML should not produce duplicate entries
+ const html = `
+
+
+
+`;
+ const result = lintHyperframeHtml(html);
+ const codes = result.findings.map((f) => `${f.code}|${f.message}`);
+ const uniqueCodes = [...new Set(codes)];
+ expect(codes.length).toBe(uniqueCodes.length);
+ });
+});
diff --git a/packages/core/src/lint/hyperframeLinter.ts b/packages/core/src/lint/hyperframeLinter.ts
new file mode 100644
index 000000000..ec34bea61
--- /dev/null
+++ b/packages/core/src/lint/hyperframeLinter.ts
@@ -0,0 +1,699 @@
+import { parseGsapScript } from "../parsers/gsapParser";
+import type { HyperframeLintFinding, HyperframeLinterOptions, HyperframeLintResult } from "./types";
+
+type OpenTag = {
+ raw: string;
+ name: string;
+ attrs: string;
+ index: number;
+};
+
+type ExtractedBlock = {
+ attrs: string;
+ content: string;
+ raw: string;
+ index: number;
+};
+
+type GsapWindow = {
+ targetSelector: string;
+ position: number;
+ end: number;
+ properties: string[];
+ overwriteAuto: boolean;
+ raw: string;
+};
+
+const TAG_PATTERN = /<([a-z][\w:-]*)(\s[^<>]*?)?>/gi;
+const STYLE_BLOCK_PATTERN = /]*)>([\s\S]*?)<\/style>/gi;
+const SCRIPT_BLOCK_PATTERN = /]*)>([\s\S]*?)<\/script>/gi;
+const COMPOSITION_ID_IN_CSS_PATTERN = /\[data-composition-id=["']([^"']+)["']\]/g;
+const TIMELINE_REGISTRY_INIT_PATTERN =
+ /window\.__timelines\s*=\s*window\.__timelines\s*\|\|\s*\{\}|window\.__timelines\s*=\s*\{\}|window\.__timelines\s*\?\?=\s*\{\}/i;
+const TIMELINE_REGISTRY_ASSIGN_PATTERN = /window\.__timelines\[[^\]]+\]\s*=/i;
+const INVALID_SCRIPT_CLOSE_PATTERN = /]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
+const WINDOW_TIMELINE_ASSIGN_PATTERN = /window\.__timelines\[\s*["']([^"']+)["']\s*\]\s*=\s*([A-Za-z_$][\w$]*)/i;
+
+const META_GSAP_KEYS = new Set(["duration", "ease", "repeat", "yoyo", "overwrite", "delay"]);
+
+export function lintHyperframeHtml(html: string, options: HyperframeLinterOptions = {}): HyperframeLintResult {
+ const source = html || "";
+ const filePath = options.filePath;
+ const findings: HyperframeLintFinding[] = [];
+ const seen = new Set();
+
+ const pushFinding = (finding: HyperframeLintFinding) => {
+ const dedupeKey = [
+ finding.code,
+ finding.severity,
+ finding.selector || "",
+ finding.elementId || "",
+ finding.message,
+ ].join("|");
+ if (seen.has(dedupeKey)) {
+ return;
+ }
+ seen.add(dedupeKey);
+ findings.push(filePath ? { ...finding, file: filePath } : finding);
+ };
+
+ const tags = extractOpenTags(source);
+ const styles = extractBlocks(source, STYLE_BLOCK_PATTERN);
+ const scripts = extractBlocks(source, SCRIPT_BLOCK_PATTERN);
+ const compositionIds = collectCompositionIds(tags);
+ const rootTag = findRootTag(source);
+ const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
+
+ if (!rootTag || !readAttr(rootTag.raw, "data-composition-id")) {
+ pushFinding({
+ code: "root_missing_composition_id",
+ severity: "error",
+ message: "Root composition is missing `data-composition-id`.",
+ elementId: rootTag ? readAttr(rootTag.raw, "id") || undefined : undefined,
+ fixHint: "Add a stable `data-composition-id` to the entry composition wrapper.",
+ snippet: truncateSnippet(rootTag?.raw || ""),
+ });
+ }
+
+ if (!rootTag || !readAttr(rootTag.raw, "data-width") || !readAttr(rootTag.raw, "data-height")) {
+ pushFinding({
+ code: "root_missing_dimensions",
+ severity: "error",
+ message: "Root composition is missing `data-width` or `data-height`.",
+ elementId: rootTag ? readAttr(rootTag.raw, "id") || undefined : undefined,
+ fixHint: "Set numeric `data-width` and `data-height` on the entry composition root.",
+ snippet: truncateSnippet(rootTag?.raw || ""),
+ });
+ }
+
+ if (!TIMELINE_REGISTRY_INIT_PATTERN.test(source) && !TIMELINE_REGISTRY_ASSIGN_PATTERN.test(source)) {
+ pushFinding({
+ code: "missing_timeline_registry",
+ severity: "error",
+ message: "Missing `window.__timelines` registration.",
+ fixHint: "Register each composition timeline on `window.__timelines[compositionId]`.",
+ });
+ }
+
+ if (INVALID_SCRIPT_CLOSE_PATTERN.test(source)) {
+ pushFinding({
+ code: "invalid_inline_script_syntax",
+ severity: "error",
+ message: "Detected malformed inline `` tag.",
+ });
+ }
+
+ for (const script of scripts) {
+ const attrs = script.attrs || "";
+ if (/\bsrc\s*=/.test(attrs) || /\btype\s*=\s*["']application\/json["']/.test(attrs)) {
+ continue;
+ }
+ const syntaxError = getInlineScriptSyntaxError(script.content);
+ if (!syntaxError) {
+ continue;
+ }
+ pushFinding({
+ code: "invalid_inline_script_syntax",
+ severity: "error",
+ message: `Inline script has invalid syntax: ${syntaxError}`,
+ fixHint: "Fix the inline script syntax before render verification.",
+ snippet: truncateSnippet(script.content),
+ });
+ }
+
+ for (const tag of tags) {
+ const src = readAttr(tag.raw, "data-composition-src");
+ if (!src) {
+ continue;
+ }
+ const compId = readAttr(tag.raw, "data-composition-id");
+ if (compId) {
+ continue;
+ }
+ pushFinding({
+ code: "host_missing_composition_id",
+ severity: "error",
+ message: `Composition host for "${src}" is missing \`data-composition-id\`.`,
+ elementId: readAttr(tag.raw, "id") || undefined,
+ fixHint: "Set `data-composition-id` on every `data-composition-src` host element.",
+ snippet: truncateSnippet(tag.raw),
+ });
+ }
+
+ const scopedCssCompositionIds = new Set();
+ for (const style of styles) {
+ for (const compId of extractCompositionIdsFromCss(style.content)) {
+ scopedCssCompositionIds.add(compId);
+ }
+ }
+
+ for (const compId of scopedCssCompositionIds) {
+ if (compositionIds.has(compId)) {
+ continue;
+ }
+ pushFinding({
+ code: "scoped_css_missing_wrapper",
+ severity: "warning",
+ message: `Scoped CSS targets composition "${compId}" but no matching wrapper exists in this HTML.`,
+ selector: `[data-composition-id="${compId}"]`,
+ fixHint: "Preserve the matching composition wrapper or align the CSS scope to an existing wrapper.",
+ });
+ }
+
+ const mediaById = new Map();
+ const mediaFingerprintCounts = new Map();
+ for (const tag of tags) {
+ if (!isMediaTag(tag.name)) {
+ continue;
+ }
+ const elementId = readAttr(tag.raw, "id");
+ if (elementId) {
+ const existing = mediaById.get(elementId) || [];
+ existing.push(tag);
+ mediaById.set(elementId, existing);
+ }
+ const fingerprint = [
+ tag.name,
+ readAttr(tag.raw, "src") || "",
+ readAttr(tag.raw, "data-start") || "",
+ readAttr(tag.raw, "data-duration") || "",
+ ].join("|");
+ mediaFingerprintCounts.set(fingerprint, (mediaFingerprintCounts.get(fingerprint) || 0) + 1);
+ }
+
+ for (const [elementId, mediaTags] of mediaById) {
+ if (mediaTags.length < 2) {
+ continue;
+ }
+ pushFinding({
+ code: "duplicate_media_id",
+ severity: "error",
+ message: `Media id "${elementId}" is defined multiple times.`,
+ elementId,
+ fixHint: "Give each media element a unique id so preview and producer discover the same media graph.",
+ snippet: truncateSnippet(mediaTags[0]?.raw || ""),
+ });
+ }
+
+ for (const [fingerprint, count] of mediaFingerprintCounts) {
+ if (count < 2) {
+ continue;
+ }
+ const [tagName, src, dataStart, dataDuration] = fingerprint.split("|");
+ pushFinding({
+ code: "duplicate_media_discovery_risk",
+ severity: "warning",
+ message: `Detected ${count} matching ${tagName} entries with the same source/start/duration.`,
+ fixHint: "Avoid duplicated media nodes that can be discovered twice during compilation.",
+ snippet: truncateSnippet(`${tagName} src=${src} data-start=${dataStart} data-duration=${dataDuration}`),
+ });
+ }
+
+ const classUsage = countClassUsage(tags);
+ for (const script of scripts) {
+ const localTimelineCompId = readRegisteredTimelineCompositionId(script.content);
+ const gsapWindows = extractGsapWindows(script.content);
+
+ for (let i = 0; i < gsapWindows.length; i++) {
+ const left = gsapWindows[i];
+ if (!left) continue;
+ if (left.end <= left.position) {
+ continue;
+ }
+ for (let j = i + 1; j < gsapWindows.length; j++) {
+ const right = gsapWindows[j];
+ if (!right) continue;
+ if (right.end <= right.position) {
+ continue;
+ }
+ if (left.targetSelector !== right.targetSelector) {
+ continue;
+ }
+ const overlapStart = Math.max(left.position, right.position);
+ const overlapEnd = Math.min(left.end, right.end);
+ if (overlapEnd <= overlapStart) {
+ continue;
+ }
+ if (left.overwriteAuto || right.overwriteAuto) {
+ continue;
+ }
+ const sharedProperties = left.properties.filter((prop) => right.properties.includes(prop));
+ if (sharedProperties.length === 0) {
+ continue;
+ }
+ pushFinding({
+ code: "overlapping_gsap_tweens",
+ severity: "warning",
+ message: `GSAP tweens overlap on "${left.targetSelector}" for ${sharedProperties.join(", ")} between ${overlapStart.toFixed(2)}s and ${overlapEnd.toFixed(2)}s.`,
+ selector: left.targetSelector,
+ fixHint: 'Shorten the earlier tween, move the later tween, or add `overwrite: "auto"`.',
+ snippet: truncateSnippet(`${left.raw}\n${right.raw}`),
+ });
+ }
+ }
+
+ if (!localTimelineCompId || localTimelineCompId === rootCompositionId) {
+ continue;
+ }
+ for (const window of gsapWindows) {
+ if (!isSuspiciousGlobalSelector(window.targetSelector)) {
+ continue;
+ }
+ const className = getSingleClassSelector(window.targetSelector);
+ if (className && (classUsage.get(className) || 0) < 2) {
+ continue;
+ }
+ pushFinding({
+ code: "suspicious_global_gsap_selector",
+ severity: "warning",
+ message: `Timeline "${localTimelineCompId}" uses a global selector "${window.targetSelector}" that may escape composition scope.`,
+ selector: window.targetSelector,
+ fixHint: `Scope the selector like \`[data-composition-id="${localTimelineCompId}"] ${window.targetSelector}\` or use a unique id.`,
+ snippet: truncateSnippet(window.raw),
+ });
+ }
+ }
+
+ // ── Composition pitfall checks ──────────────────────────────────────────
+
+ // #2: Video without muted attribute (audio should come from separate )
+ for (const tag of tags) {
+ if (tag.name !== "video") continue;
+ const hasMuted = /\bmuted\b/i.test(tag.raw);
+ if (!hasMuted && readAttr(tag.raw, "data-start")) {
+ const elementId = readAttr(tag.raw, "id") || undefined;
+ pushFinding({
+ code: "video_missing_muted",
+ severity: "error",
+ message: ` has data-start but is not muted. The framework expects video to be muted with a separate element for sound.`,
+ elementId,
+ fixHint:
+ "Add the `muted` attribute to the tag and use a separate element with the same src for audio playback.",
+ snippet: truncateSnippet(tag.raw),
+ });
+ }
+ }
+
+ // #3: Video nested inside a timed element (data-start on ancestor)
+ // Approximation: check if a appears inside another element with data-start
+ // by scanning for video tags whose raw position is between another timed element's open/close
+ const timedTagPositions: Array<{ name: string; start: number; id?: string }> = [];
+ for (const tag of tags) {
+ if (tag.name === "video" || tag.name === "audio") continue;
+ if (readAttr(tag.raw, "data-start")) {
+ timedTagPositions.push({ name: tag.name, start: tag.index, id: readAttr(tag.raw, "id") || undefined });
+ }
+ }
+ for (const tag of tags) {
+ if (tag.name !== "video") continue;
+ if (!readAttr(tag.raw, "data-start")) continue;
+ // Check if any timed non-media element appears before this video in the source
+ // and could be an ancestor (heuristic — not a full DOM parse)
+ for (const parent of timedTagPositions) {
+ if (parent.start < tag.index) {
+ // Check if there's a closing tag for the parent between parent.start and tag.index
+ const parentClosePattern = new RegExp(``, "gi");
+ const between = source.substring(parent.start, tag.index);
+ if (!parentClosePattern.test(between)) {
+ pushFinding({
+ code: "video_nested_in_timed_element",
+ severity: "warning",
+ message: ` with data-start appears to be nested inside <${parent.name}${parent.id ? ` id="${parent.id}"` : ""}> which also has data-start. This can break media sync.`,
+ elementId: readAttr(tag.raw, "id") || undefined,
+ fixHint:
+ "Move the to be a direct child of the stage, or remove data-start from the wrapper div (use it as a non-timed visual container).",
+ snippet: truncateSnippet(tag.raw),
+ });
+ break; // Only report once per video
+ }
+ }
+ }
+ }
+
+ // #4: Timed element missing visibility:hidden (no class="clip" or equivalent)
+ for (const tag of tags) {
+ if (tag.name === "audio" || tag.name === "script" || tag.name === "style") continue;
+ if (!readAttr(tag.raw, "data-start")) continue;
+ const classAttr = readAttr(tag.raw, "class") || "";
+ const styleAttr = readAttr(tag.raw, "style") || "";
+ const hasClip = classAttr.split(/\s+/).includes("clip");
+ const hasHiddenStyle = /visibility\s*:\s*hidden/i.test(styleAttr);
+ if (!hasClip && !hasHiddenStyle) {
+ const elementId = readAttr(tag.raw, "id") || undefined;
+ pushFinding({
+ code: "timed_element_missing_visibility_hidden",
+ severity: "warning",
+ message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-start but no class="clip" or visibility:hidden. The framework needs elements to start hidden so it can manage their lifecycle.`,
+ elementId,
+ fixHint: 'Add class="clip" to the element (with CSS: .clip { visibility: hidden; }).',
+ snippet: truncateSnippet(tag.raw),
+ });
+ }
+ }
+
+ // #5: Deprecated attribute names
+ for (const tag of tags) {
+ if (readAttr(tag.raw, "data-layer") && !readAttr(tag.raw, "data-track-index")) {
+ const elementId = readAttr(tag.raw, "id") || undefined;
+ pushFinding({
+ code: "deprecated_data_layer",
+ severity: "warning",
+ message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-layer instead of data-track-index.`,
+ elementId,
+ fixHint: "Replace data-layer with data-track-index. The runtime reads data-track-index.",
+ snippet: truncateSnippet(tag.raw),
+ });
+ }
+ if (readAttr(tag.raw, "data-end") && !readAttr(tag.raw, "data-duration")) {
+ const elementId = readAttr(tag.raw, "id") || undefined;
+ pushFinding({
+ code: "deprecated_data_end",
+ severity: "warning",
+ message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`,
+ elementId,
+ fixHint:
+ "Replace data-end with data-duration. The compiler generates data-end from data-duration automatically.",
+ snippet: truncateSnippet(tag.raw),
+ });
+ }
+ }
+
+ const errorCount = findings.filter((finding) => finding.severity === "error").length;
+ const warningCount = findings.length - errorCount;
+
+ return {
+ ok: errorCount === 0,
+ errorCount,
+ warningCount,
+ findings,
+ };
+}
+
+function extractOpenTags(source: string): OpenTag[] {
+ const tags: OpenTag[] = [];
+ let match: RegExpExecArray | null;
+ while ((match = TAG_PATTERN.exec(source)) !== null) {
+ const raw = match[0];
+ if (raw.startsWith("]*>([\s\S]*?)<\/body>/i);
+ const bodyContent = bodyMatch ? bodyMatch[1] ?? source : source;
+ const bodyTags = extractOpenTags(bodyContent);
+ for (const tag of bodyTags) {
+ if (["script", "style", "meta", "link", "title"].includes(tag.name)) {
+ continue;
+ }
+ return tag;
+ }
+ return null;
+}
+
+function readAttr(tagSource: string, attr: string): string | null {
+ if (!tagSource) {
+ return null;
+ }
+ const escaped = attr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ const match = tagSource.match(new RegExp(`\\b${escaped}\\s*=\\s*["']([^"']+)["']`, "i"));
+ return match?.[1] || null;
+}
+
+function collectCompositionIds(tags: OpenTag[]): Set {
+ const ids = new Set();
+ for (const tag of tags) {
+ const compId = readAttr(tag.raw, "data-composition-id");
+ if (compId) {
+ ids.add(compId);
+ }
+ }
+ return ids;
+}
+
+function extractCompositionIdsFromCss(css: string): string[] {
+ const ids = new Set();
+ let match: RegExpExecArray | null;
+ while ((match = COMPOSITION_ID_IN_CSS_PATTERN.exec(css)) !== null) {
+ if (match[1]) {
+ ids.add(match[1]);
+ }
+ }
+ return [...ids];
+}
+
+function getInlineScriptSyntaxError(source: string): string | null {
+ if (!source.trim()) {
+ return null;
+ }
+ try {
+ // eslint-disable-next-line no-new-func
+ new Function(source);
+ return null;
+ } catch (error) {
+ if (error instanceof Error) {
+ return error.message;
+ }
+ return String(error);
+ }
+}
+
+function isMediaTag(tagName: string): boolean {
+ return tagName === "video" || tagName === "audio" || tagName === "img";
+}
+
+function countClassUsage(tags: OpenTag[]): Map {
+ const counts = new Map();
+ for (const tag of tags) {
+ const classAttr = readAttr(tag.raw, "class");
+ if (!classAttr) {
+ continue;
+ }
+ for (const className of classAttr.split(/\s+/).filter(Boolean)) {
+ counts.set(className, (counts.get(className) || 0) + 1);
+ }
+ }
+ return counts;
+}
+
+function readRegisteredTimelineCompositionId(script: string): string | null {
+ const match = script.match(WINDOW_TIMELINE_ASSIGN_PATTERN);
+ return match?.[1] || null;
+}
+
+function extractGsapWindows(script: string): GsapWindow[] {
+ if (!/gsap\.timeline/.test(script)) {
+ return [];
+ }
+
+ const parsed = parseGsapScript(script);
+ if (parsed.animations.length === 0) {
+ return [];
+ }
+
+ const windows: GsapWindow[] = [];
+ const timelineVar = parsed.timelineVar;
+ const methodPattern = new RegExp(`${timelineVar}\\.(set|to|from|fromTo)\\s*\\(([^)]+(?:\\{[^}]*\\}[^)]*)+)\\)`, "g");
+
+ let match: RegExpExecArray | null;
+ let index = 0;
+ while ((match = methodPattern.exec(script)) !== null && index < parsed.animations.length) {
+ const raw = match[0];
+ const meta = parseGsapWindowMeta(match[1] ?? "", match[2] ?? "");
+ const animation = parsed.animations[index];
+ index += 1;
+ if (!animation) {
+ continue;
+ }
+ windows.push({
+ targetSelector: animation.targetSelector,
+ position: animation.position,
+ end: animation.position + meta.effectiveDuration,
+ properties: meta.properties.length > 0 ? meta.properties : Object.keys(animation.properties),
+ overwriteAuto: meta.overwriteAuto,
+ raw,
+ });
+ }
+
+ return windows;
+}
+
+function parseGsapWindowMeta(
+ method: string,
+ argsStr: string,
+): {
+ effectiveDuration: number;
+ properties: string[];
+ overwriteAuto: boolean;
+} {
+ const selectorMatch = argsStr.match(/^\s*["']([^"']+)["']\s*,/);
+ if (!selectorMatch) {
+ return { effectiveDuration: 0, properties: [], overwriteAuto: false };
+ }
+
+ const afterSelector = argsStr.slice(selectorMatch[0].length);
+ let properties: Record = {};
+ let fromProperties: Record = {};
+
+ if (method === "fromTo") {
+ const firstBrace = afterSelector.indexOf("{");
+ const firstEnd = findMatchingBrace(afterSelector, firstBrace);
+ if (firstBrace !== -1 && firstEnd !== -1) {
+ fromProperties = parseLooseObjectLiteral(afterSelector.slice(firstBrace, firstEnd + 1));
+ const secondPart = afterSelector.slice(firstEnd + 1);
+ const secondBrace = secondPart.indexOf("{");
+ const secondEnd = findMatchingBrace(secondPart, secondBrace);
+ if (secondBrace !== -1 && secondEnd !== -1) {
+ properties = parseLooseObjectLiteral(secondPart.slice(secondBrace, secondEnd + 1));
+ }
+ }
+ } else {
+ const braceStart = afterSelector.indexOf("{");
+ const braceEnd = findMatchingBrace(afterSelector, braceStart);
+ if (braceStart !== -1 && braceEnd !== -1) {
+ properties = parseLooseObjectLiteral(afterSelector.slice(braceStart, braceEnd + 1));
+ }
+ }
+
+ const duration = numberValue(properties.duration) || 0;
+ const repeat = numberValue(properties.repeat) || 0;
+ const yoyo = stringValue(properties.yoyo) === "true";
+ const cycleCount = repeat > 0 ? repeat + 1 : 1;
+ const effectiveDuration = duration * cycleCount * (yoyo ? 1 : 1);
+ const overwriteAuto = stringValue(properties.overwrite) === "auto";
+
+ const propertyNames = new Set();
+ for (const key of Object.keys(fromProperties)) {
+ if (!META_GSAP_KEYS.has(key)) {
+ propertyNames.add(key);
+ }
+ }
+ for (const key of Object.keys(properties)) {
+ if (!META_GSAP_KEYS.has(key)) {
+ propertyNames.add(key);
+ }
+ }
+
+ return {
+ effectiveDuration: method === "set" ? 0 : effectiveDuration,
+ properties: [...propertyNames],
+ overwriteAuto,
+ };
+}
+
+function parseLooseObjectLiteral(source: string): Record {
+ const result: Record = {};
+ const cleaned = source.replace(/^\{|\}$/g, "").trim();
+ if (!cleaned) {
+ return result;
+ }
+
+ const propertyPattern = /(\w+)\s*:\s*("[^"]*"|'[^']*'|true|false|-?[\d.]+|[a-zA-Z_][\w.]*)/g;
+ let match: RegExpExecArray | null;
+ while ((match = propertyPattern.exec(cleaned)) !== null) {
+ const key = match[1];
+ const rawValue = match[2];
+ if (!key || rawValue == null) {
+ continue;
+ }
+ if ((rawValue.startsWith('"') && rawValue.endsWith('"')) || (rawValue.startsWith("'") && rawValue.endsWith("'"))) {
+ result[key] = rawValue.slice(1, -1);
+ continue;
+ }
+ const numeric = Number(rawValue);
+ result[key] = Number.isFinite(numeric) ? numeric : rawValue;
+ }
+ return result;
+}
+
+function findMatchingBrace(source: string, startIndex: number): number {
+ if (startIndex < 0) {
+ return -1;
+ }
+ let depth = 0;
+ for (let i = startIndex; i < source.length; i++) {
+ if (source[i] === "{") {
+ depth += 1;
+ } else if (source[i] === "}") {
+ depth -= 1;
+ if (depth === 0) {
+ return i;
+ }
+ }
+ }
+ return -1;
+}
+
+function numberValue(value: string | number | undefined): number | null {
+ if (typeof value === "number") {
+ return value;
+ }
+ if (typeof value === "string" && value.trim()) {
+ const numeric = Number(value);
+ return Number.isFinite(numeric) ? numeric : null;
+ }
+ return null;
+}
+
+function stringValue(value: string | number | undefined): string | null {
+ if (typeof value === "string") {
+ return value;
+ }
+ if (typeof value === "number") {
+ return String(value);
+ }
+ return null;
+}
+
+function isSuspiciousGlobalSelector(selector: string): boolean {
+ if (!selector) {
+ return false;
+ }
+ if (selector.includes("[data-composition-id=")) {
+ return false;
+ }
+ if (selector.startsWith("#")) {
+ return false;
+ }
+ return selector.startsWith(".") || /^[a-z]/i.test(selector);
+}
+
+function getSingleClassSelector(selector: string): string | null {
+ const match = selector.trim().match(/^\.(?[A-Za-z0-9_-]+)$/);
+ return match?.groups?.name || null;
+}
+
+function truncateSnippet(value: string, maxLength = 220): string | undefined {
+ const normalized = value.replace(/\s+/g, " ").trim();
+ if (!normalized) {
+ return undefined;
+ }
+ if (normalized.length <= maxLength) {
+ return normalized;
+ }
+ return `${normalized.slice(0, maxLength - 3)}...`;
+}
diff --git a/packages/core/src/lint/index.ts b/packages/core/src/lint/index.ts
new file mode 100644
index 000000000..ec2a3926d
--- /dev/null
+++ b/packages/core/src/lint/index.ts
@@ -0,0 +1,7 @@
+export type {
+ HyperframeLintSeverity,
+ HyperframeLintFinding,
+ HyperframeLintResult,
+ HyperframeLinterOptions,
+} from "./types";
+export { lintHyperframeHtml } from "./hyperframeLinter";
diff --git a/packages/core/src/lint/types.ts b/packages/core/src/lint/types.ts
new file mode 100644
index 000000000..a612bcb3e
--- /dev/null
+++ b/packages/core/src/lint/types.ts
@@ -0,0 +1,23 @@
+export type HyperframeLintSeverity = "error" | "warning";
+
+export type HyperframeLintFinding = {
+ code: string;
+ severity: HyperframeLintSeverity;
+ message: string;
+ file?: string;
+ selector?: string;
+ elementId?: string;
+ fixHint?: string;
+ snippet?: string;
+};
+
+export type HyperframeLintResult = {
+ ok: boolean;
+ errorCount: number;
+ warningCount: number;
+ findings: HyperframeLintFinding[];
+};
+
+export type HyperframeLinterOptions = {
+ filePath?: string;
+};
diff --git a/packages/core/src/parsers/gsapParser.test.ts b/packages/core/src/parsers/gsapParser.test.ts
new file mode 100644
index 000000000..c5ddd8aa4
--- /dev/null
+++ b/packages/core/src/parsers/gsapParser.test.ts
@@ -0,0 +1,532 @@
+import { describe, it, expect } from "vitest";
+import {
+ parseGsapScript,
+ gsapAnimationsToKeyframes,
+ SUPPORTED_PROPS,
+ SUPPORTED_EASES,
+ serializeGsapAnimations,
+ validateCompositionGsap,
+ getAnimationsForElement,
+ keyframesToGsapAnimations,
+} from "./gsapParser.js";
+import type { GsapAnimation } from "./gsapParser.js";
+import type { Keyframe } from "../core.types";
+
+describe("parseGsapScript", () => {
+ it("parses a basic timeline with .to()", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, duration: 0.5 }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.timelineVar).toBe("tl");
+ expect(result.animations).toHaveLength(1);
+ expect(result.animations[0].method).toBe("to");
+ expect(result.animations[0].targetSelector).toBe("#el1");
+ expect(result.animations[0].properties.opacity).toBe(1);
+ expect(result.animations[0].duration).toBe(0.5);
+ expect(result.animations[0].position).toBe(0);
+ });
+
+ it("parses a timeline with .from()", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.from("#el2", { x: 100, duration: 1 }, 0.5);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations).toHaveLength(1);
+ expect(result.animations[0].method).toBe("from");
+ expect(result.animations[0].targetSelector).toBe("#el2");
+ expect(result.animations[0].properties.x).toBe(100);
+ expect(result.animations[0].duration).toBe(1);
+ expect(result.animations[0].position).toBe(0.5);
+ });
+
+ it("parses a timeline with .set()", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.set("#el3", { opacity: 0, x: 50 }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations).toHaveLength(1);
+ expect(result.animations[0].method).toBe("set");
+ expect(result.animations[0].targetSelector).toBe("#el3");
+ expect(result.animations[0].properties.opacity).toBe(0);
+ expect(result.animations[0].properties.x).toBe(50);
+ expect(result.animations[0].duration).toBeUndefined();
+ });
+
+ it("parses a timeline with .fromTo() and position offset", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.fromTo("#el4", { opacity: 0, x: 100 }, { opacity: 1, x: 200, duration: 1 }, 2);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations).toHaveLength(1);
+ const anim = result.animations[0];
+ expect(anim.method).toBe("fromTo");
+ expect(anim.targetSelector).toBe("#el4");
+ expect(anim.fromProperties).toBeDefined();
+ expect(anim.fromProperties?.opacity).toBe(0);
+ expect(anim.fromProperties?.x).toBe(100);
+ expect(anim.properties.opacity).toBe(1);
+ expect(anim.properties.x).toBe(200);
+ expect(anim.duration).toBe(1);
+ expect(anim.position).toBe(2);
+ });
+
+ it("parseObjectLiteral does not match negative numbers (known limitation)", () => {
+ // The regex in parseObjectLiteral only matches [\d.]+, not negative numbers.
+ // Negative values like x: -100 won't be parsed by the object literal parser.
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.fromTo("#el5", { opacity: 0, x: -100 }, { opacity: 1, x: 0, duration: 1 }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations).toHaveLength(1);
+ const anim = result.animations[0];
+ expect(anim.fromProperties).toBeDefined();
+ expect(anim.fromProperties?.opacity).toBe(0);
+ // -100 is not parseable by the regex, so x won't be in fromProperties
+ expect(anim.fromProperties?.x).toBeUndefined();
+ });
+
+ it("handles an empty script", () => {
+ const result = parseGsapScript("");
+
+ expect(result.animations).toHaveLength(0);
+ expect(result.timelineVar).toBe("tl");
+ expect(result.preamble).toBe("const tl = gsap.timeline({ paused: true });");
+ expect(result.postamble).toBe("");
+ });
+
+ it("extracts preamble correctly", () => {
+ const script = `
+ const myTl = gsap.timeline({ paused: true });
+ myTl.to("#el1", { opacity: 1, duration: 0.5 }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.timelineVar).toBe("myTl");
+ expect(result.preamble).toContain("const myTl = gsap.timeline");
+ });
+
+ it("extracts postamble correctly", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, duration: 0.5 }, 0);
+ console.log("done");
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.postamble).toContain('console.log("done");');
+ });
+
+ it("parses multiple animations", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.set("#el1", { opacity: 0 }, 0);
+ tl.to("#el1", { opacity: 1, duration: 0.5 }, 0);
+ tl.to("#el2", { x: 100, duration: 1 }, 1);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations).toHaveLength(3);
+ expect(result.animations[0].method).toBe("set");
+ expect(result.animations[1].method).toBe("to");
+ expect(result.animations[2].method).toBe("to");
+ });
+
+ it("filters out unsupported properties from animations", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, backgroundColor: "red", x: 50, duration: 0.5 }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations[0].properties.opacity).toBe(1);
+ expect(result.animations[0].properties.x).toBe(50);
+ // backgroundColor is not in SUPPORTED_PROPS, so it's filtered out
+ expect(result.animations[0].properties.backgroundColor).toBeUndefined();
+ });
+
+ it("extracts ease from properties", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, duration: 1, ease: "power2.out" }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.animations[0].ease).toBe("power2.out");
+ });
+
+ it("uses 'let' or 'var' for timeline declaration", () => {
+ const script = `
+ let timeline = gsap.timeline({ paused: true });
+ timeline.to("#el1", { opacity: 1, duration: 1 }, 0);
+ `;
+ const result = parseGsapScript(script);
+
+ expect(result.timelineVar).toBe("timeline");
+ expect(result.animations).toHaveLength(1);
+ });
+});
+
+describe("gsapAnimationsToKeyframes", () => {
+ it("converts animations to keyframes with element start offset", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 2,
+ properties: { x: 100, y: 200 },
+ },
+ {
+ id: "anim-2",
+ targetSelector: "#el1",
+ method: "to",
+ position: 3,
+ properties: { x: 300, y: 400 },
+ duration: 1,
+ ease: "power2.out",
+ },
+ ];
+
+ const keyframes = gsapAnimationsToKeyframes(animations, 2);
+
+ expect(keyframes).toHaveLength(2);
+ // First keyframe: time = 2 - 2 = 0
+ expect(keyframes[0].time).toBe(0);
+ expect(keyframes[0].properties.x).toBe(100);
+ expect(keyframes[0].properties.y).toBe(200);
+ // Second keyframe: time = 3 - 2 = 1
+ expect(keyframes[1].time).toBe(1);
+ expect(keyframes[1].properties.x).toBe(300);
+ expect(keyframes[1].ease).toBe("power2.out");
+ });
+
+ it("filters supported props only", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "to",
+ position: 0,
+ properties: { opacity: 1, x: 50, someUnsupportedProp: "value" } as Record,
+ duration: 1,
+ },
+ ];
+
+ const keyframes = gsapAnimationsToKeyframes(animations, 0);
+
+ expect(keyframes).toHaveLength(1);
+ expect(keyframes[0].properties.opacity).toBe(1);
+ expect(keyframes[0].properties.x).toBe(50);
+ // String values are skipped (typeof value !== "number" check)
+ expect((keyframes[0].properties as Record).someUnsupportedProp).toBeUndefined();
+ });
+
+ it("skips base set keyframes at time 0 when skipBaseSet is true", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 5,
+ properties: { x: 0, y: 0, scale: 1 },
+ },
+ {
+ id: "anim-2",
+ targetSelector: "#el1",
+ method: "to",
+ position: 6,
+ properties: { x: 100 },
+ duration: 1,
+ },
+ ];
+
+ const keyframes = gsapAnimationsToKeyframes(animations, 5, { skipBaseSet: true });
+
+ // The set at position 5 (time=0) with x=0, y=0, scale=1 (base values) should be skipped
+ expect(keyframes).toHaveLength(1);
+ expect(keyframes[0].id).toBe("anim-2");
+ });
+
+ it("does NOT skip set keyframes when they have non-base values", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 5,
+ properties: { x: 100, y: 0 },
+ },
+ ];
+
+ const keyframes = gsapAnimationsToKeyframes(animations, 5, { skipBaseSet: true });
+
+ // x=100 is non-base, so it should NOT be skipped
+ expect(keyframes).toHaveLength(1);
+ expect(keyframes[0].properties.x).toBe(100);
+ });
+
+ it("clamps negative time to zero by default", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 0,
+ properties: { opacity: 1 },
+ },
+ ];
+
+ // elementStartTime is 5, so relative time = 0 - 5 = -5
+ const keyframes = gsapAnimationsToKeyframes(animations, 5);
+
+ expect(keyframes[0].time).toBe(0); // Clamped to 0
+ });
+
+ it("adjusts x/y/scale relative to base values", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "to",
+ position: 2,
+ properties: { x: 150, y: 200, scale: 2 },
+ duration: 1,
+ },
+ ];
+
+ const keyframes = gsapAnimationsToKeyframes(animations, 0, {
+ baseX: 50,
+ baseY: 100,
+ baseScale: 2,
+ });
+
+ expect(keyframes[0].properties.x).toBe(100); // 150 - 50
+ expect(keyframes[0].properties.y).toBe(100); // 200 - 100
+ expect(keyframes[0].properties.scale).toBe(1); // 2 / 2
+ });
+});
+
+describe("keyframesToGsapAnimations", () => {
+ it("converts keyframes back to GSAP animations", () => {
+ const keyframes: Keyframe[] = [
+ { id: "kf-1", time: 0, properties: { opacity: 0 } },
+ { id: "kf-2", time: 1, properties: { opacity: 1 }, ease: "power2.out" },
+ ];
+
+ const animations = keyframesToGsapAnimations("el1", keyframes, 2);
+
+ expect(animations).toHaveLength(2);
+ expect(animations[0].method).toBe("set");
+ expect(animations[0].position).toBe(2); // elementStartTime + 0
+ expect(animations[0].properties.opacity).toBe(0);
+ expect(animations[1].method).toBe("to");
+ expect(animations[1].position).toBe(2); // position of prev keyframe
+ expect(animations[1].duration).toBe(1); // kf.time - prevKf.time
+ expect(animations[1].ease).toBe("power2.out");
+ });
+
+ it("applies base x/y/scale offsets", () => {
+ const keyframes: Keyframe[] = [
+ { id: "kf-1", time: 0, properties: { x: 10, y: 20, scale: 2 } },
+ ];
+
+ const animations = keyframesToGsapAnimations("el1", keyframes, 0, {
+ x: 50,
+ y: 100,
+ scale: 0.5,
+ });
+
+ expect(animations[0].properties.x).toBe(60); // baseX + value
+ expect(animations[0].properties.y).toBe(120); // baseY + value
+ expect(animations[0].properties.scale).toBe(1); // baseScale * value
+ });
+});
+
+describe("serializeGsapAnimations", () => {
+ it("serializes animations into a GSAP timeline script", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 0,
+ properties: { opacity: 0 },
+ },
+ {
+ id: "anim-2",
+ targetSelector: "#el1",
+ method: "to",
+ position: 0.5,
+ properties: { opacity: 1 },
+ duration: 0.5,
+ ease: "power2.out",
+ },
+ ];
+
+ const result = serializeGsapAnimations(animations);
+
+ expect(result).toContain("const tl = gsap.timeline({ paused: true });");
+ expect(result).toContain('tl.set("#el1"');
+ expect(result).toContain('tl.to("#el1"');
+ expect(result).toContain("opacity: 0");
+ expect(result).toContain("opacity: 1");
+ });
+
+ it("sorts animations by position", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-2",
+ targetSelector: "#el1",
+ method: "to",
+ position: 2,
+ properties: { opacity: 1 },
+ duration: 0.5,
+ },
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 0,
+ properties: { opacity: 0 },
+ },
+ ];
+
+ const result = serializeGsapAnimations(animations);
+
+ const setIdx = result.indexOf("tl.set");
+ const toIdx = result.indexOf("tl.to");
+ expect(setIdx).toBeLessThan(toIdx);
+ });
+
+ it("serializes fromTo animations correctly", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "fromTo",
+ position: 0,
+ properties: { opacity: 1 },
+ fromProperties: { opacity: 0 },
+ duration: 1,
+ },
+ ];
+
+ const result = serializeGsapAnimations(animations);
+ expect(result).toContain('tl.fromTo("#el1"');
+ });
+
+ it("uses custom timeline variable name", () => {
+ const animations: GsapAnimation[] = [
+ {
+ id: "anim-1",
+ targetSelector: "#el1",
+ method: "set",
+ position: 0,
+ properties: { opacity: 0 },
+ },
+ ];
+
+ const result = serializeGsapAnimations(animations, "myTimeline");
+ expect(result).toContain("const myTimeline = gsap.timeline({ paused: true });");
+ expect(result).toContain('myTimeline.set("#el1"');
+ });
+});
+
+describe("validateCompositionGsap", () => {
+ it("returns valid for clean scripts", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, duration: 1 }, 0);
+ `;
+ const result = validateCompositionGsap(script);
+ expect(result.valid).toBe(true);
+ expect(result.errors).toHaveLength(0);
+ });
+
+ it("detects forbidden patterns", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, duration: 1, onComplete: function() {} }, 0);
+ setTimeout(function() {}, 100);
+ `;
+ const result = validateCompositionGsap(script);
+ expect(result.valid).toBe(false);
+ expect(result.errors).toContain("onComplete callback not allowed");
+ expect(result.errors).toContain("setTimeout not allowed");
+ });
+
+ it("warns about yoyo and stagger", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to(".items", { x: 100, stagger: 0.1, yoyo: true, duration: 1 }, 0);
+ `;
+ const result = validateCompositionGsap(script);
+ expect(result.warnings).toContain("yoyo animations may behave unexpectedly when scrubbing");
+ expect(result.warnings).toContain("stagger animations may not serialize correctly");
+ });
+
+ it("detects infinite repeat", () => {
+ const script = `
+ const tl = gsap.timeline({ paused: true });
+ tl.to("#el1", { opacity: 1, duration: 1, repeat: -1 }, 0);
+ `;
+ const result = validateCompositionGsap(script);
+ expect(result.valid).toBe(false);
+ expect(result.errors).toContain("Infinite repeat (repeat: -1) not allowed");
+ });
+});
+
+describe("getAnimationsForElement", () => {
+ it("filters animations by element id", () => {
+ const animations: GsapAnimation[] = [
+ { id: "a1", targetSelector: "#el1", method: "set", position: 0, properties: { opacity: 0 } },
+ { id: "a2", targetSelector: "#el2", method: "to", position: 0, properties: { opacity: 1 }, duration: 1 },
+ { id: "a3", targetSelector: "#el1", method: "to", position: 1, properties: { opacity: 1 }, duration: 0.5 },
+ ];
+
+ const result = getAnimationsForElement(animations, "el1");
+ expect(result).toHaveLength(2);
+ expect(result.every((a) => a.targetSelector === "#el1")).toBe(true);
+ });
+
+ it("returns empty array when no animations match", () => {
+ const animations: GsapAnimation[] = [
+ { id: "a1", targetSelector: "#el1", method: "set", position: 0, properties: { opacity: 0 } },
+ ];
+
+ const result = getAnimationsForElement(animations, "el99");
+ expect(result).toHaveLength(0);
+ });
+});
+
+describe("SUPPORTED_PROPS", () => {
+ it("includes expected properties", () => {
+ expect(SUPPORTED_PROPS).toContain("opacity");
+ expect(SUPPORTED_PROPS).toContain("x");
+ expect(SUPPORTED_PROPS).toContain("y");
+ expect(SUPPORTED_PROPS).toContain("scale");
+ expect(SUPPORTED_PROPS).toContain("rotation");
+ expect(SUPPORTED_PROPS).toContain("width");
+ expect(SUPPORTED_PROPS).toContain("height");
+ });
+});
+
+describe("SUPPORTED_EASES", () => {
+ it("includes common easing functions", () => {
+ expect(SUPPORTED_EASES).toContain("none");
+ expect(SUPPORTED_EASES).toContain("power2.out");
+ expect(SUPPORTED_EASES).toContain("bounce.out");
+ expect(SUPPORTED_EASES).toContain("elastic.inOut");
+ });
+});
diff --git a/packages/core/src/parsers/gsapParser.ts b/packages/core/src/parsers/gsapParser.ts
new file mode 100644
index 000000000..6ea0949eb
--- /dev/null
+++ b/packages/core/src/parsers/gsapParser.ts
@@ -0,0 +1,508 @@
+import type { Keyframe, KeyframeProperties } from "../core.types";
+
+export type GsapMethod = "set" | "to" | "from" | "fromTo";
+
+export interface GsapAnimation {
+ id: string;
+ targetSelector: string;
+ method: GsapMethod;
+ position: number;
+ properties: Record;
+ fromProperties?: Record;
+ duration?: number;
+ ease?: string;
+}
+
+export interface ParsedGsap {
+ animations: GsapAnimation[];
+ timelineVar: string;
+ preamble: string;
+ postamble: string;
+}
+
+const GSAP_METHODS = new Set(["set", "to", "from", "fromTo"]);
+
+export const SUPPORTED_PROPS = [
+ "opacity",
+ "visibility",
+ "x",
+ "y",
+ "scale",
+ "scaleX",
+ "scaleY",
+ "rotation",
+ "autoAlpha",
+ "width",
+ "height",
+];
+
+export const SUPPORTED_EASES = [
+ "none",
+ "power1.in",
+ "power1.out",
+ "power1.inOut",
+ "power2.in",
+ "power2.out",
+ "power2.inOut",
+ "power3.in",
+ "power3.out",
+ "power3.inOut",
+ "power4.in",
+ "power4.out",
+ "power4.inOut",
+ "back.in",
+ "back.out",
+ "back.inOut",
+ "elastic.in",
+ "elastic.out",
+ "elastic.inOut",
+ "bounce.in",
+ "bounce.out",
+ "bounce.inOut",
+ "expo.in",
+ "expo.out",
+ "expo.inOut",
+];
+
+function parseObjectLiteral(str: string): Record {
+ const result: Record = {};
+
+ const cleaned = str.replace(/^\{|\}$/g, "").trim();
+ if (!cleaned) return result;
+
+ const propRegex = /(\w+)\s*:\s*("[^"]*"|'[^']*'|[\d.]+|[a-zA-Z_][\w.]*)/g;
+ let match;
+
+ while ((match = propRegex.exec(cleaned)) !== null) {
+ const key = match[1] ?? "";
+ let value: string | number = match[2] ?? "";
+
+ if (typeof value === "string") {
+ if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+ value = value.slice(1, -1);
+ } else if (!isNaN(Number(value))) {
+ value = Number(value);
+ }
+ }
+
+ result[key] = value;
+ }
+
+ return result;
+}
+
+function findMatchingBrace(str: string, startIndex: number): number {
+ let depth = 0;
+ for (let i = startIndex; i < str.length; i++) {
+ if (str[i] === "{") depth++;
+ else if (str[i] === "}") {
+ depth--;
+ if (depth === 0) return i;
+ }
+ }
+ return -1;
+}
+
+export function parseGsapScript(script: string): ParsedGsap {
+ const animations: GsapAnimation[] = [];
+ let idCounter = 0;
+
+ const timelineMatch = script.match(/(?:const|let|var)\s+(\w+)\s*=\s*gsap\.timeline/);
+ const timelineVar = timelineMatch ? timelineMatch[1] ?? "tl" : "tl";
+
+ const preambleMatch = script.match(
+ new RegExp(`^[\\s\\S]*?(?:const|let|var)\\s+${timelineVar}\\s*=\\s*gsap\\.timeline\\s*\\([^)]*\\)\\s*;?`),
+ );
+ const preamble = preambleMatch ? preambleMatch[0] : `const ${timelineVar} = gsap.timeline({ paused: true });`;
+
+ const methodPattern = new RegExp(`${timelineVar}\\.(set|to|from|fromTo)\\s*\\(([^)]+(?:\\{[^}]*\\}[^)]*)+)\\)`, "g");
+
+ let match;
+ while ((match = methodPattern.exec(script)) !== null) {
+ const rawMethod = match[1];
+ if (!rawMethod || !GSAP_METHODS.has(rawMethod)) continue;
+ const method: GsapMethod = rawMethod as GsapMethod;
+ const argsStr = match[2] ?? "";
+
+ const animation = parseGsapCall(method, argsStr, ++idCounter);
+ if (animation) {
+ animations.push(animation);
+ }
+ }
+
+ const lastAnimIdx = script.lastIndexOf(`${timelineVar}.`);
+ let postamble = "";
+ if (lastAnimIdx !== -1) {
+ const afterLastAnim = script.slice(lastAnimIdx);
+ const endOfCall = afterLastAnim.indexOf(";");
+ if (endOfCall !== -1) {
+ postamble = script.slice(lastAnimIdx + endOfCall + 1).trim();
+ }
+ }
+
+ return { animations, timelineVar, preamble, postamble };
+}
+
+function parseGsapCall(method: GsapMethod, argsStr: string, idNum: number): GsapAnimation | null {
+ const selectorMatch = argsStr.match(/^\s*["']([^"']+)["']\s*,/);
+ if (!selectorMatch) return null;
+
+ const targetSelector = selectorMatch[1] ?? "";
+ const afterSelector = argsStr.slice(selectorMatch[0].length);
+
+ let properties: Record = {};
+ let fromProperties: Record | undefined;
+ let position = 0;
+
+ if (method === "fromTo") {
+ const firstBrace = afterSelector.indexOf("{");
+ const firstEnd = findMatchingBrace(afterSelector, firstBrace);
+ if (firstBrace === -1 || firstEnd === -1) return null;
+
+ fromProperties = parseObjectLiteral(afterSelector.slice(firstBrace, firstEnd + 1));
+
+ const secondPart = afterSelector.slice(firstEnd + 1);
+ const secondBrace = secondPart.indexOf("{");
+ const secondEnd = findMatchingBrace(secondPart, secondBrace);
+ if (secondBrace === -1 || secondEnd === -1) return null;
+
+ properties = parseObjectLiteral(secondPart.slice(secondBrace, secondEnd + 1));
+
+ const afterProps = secondPart.slice(secondEnd + 1);
+ const posMatch = afterProps.match(/,\s*([\d.]+)/);
+ if (posMatch) position = parseFloat(posMatch[1] ?? "");
+ } else {
+ const braceStart = afterSelector.indexOf("{");
+ const braceEnd = findMatchingBrace(afterSelector, braceStart);
+
+ if (braceStart !== -1 && braceEnd !== -1) {
+ properties = parseObjectLiteral(afterSelector.slice(braceStart, braceEnd + 1));
+
+ const afterProps = afterSelector.slice(braceEnd + 1);
+ const posMatch = afterProps.match(/,\s*([\d.]+)/);
+ if (posMatch) position = parseFloat(posMatch[1] ?? "");
+ }
+ }
+
+ const duration = typeof properties.duration === "number" ? properties.duration : undefined;
+ const ease = typeof properties.ease === "string" ? properties.ease : undefined;
+
+ const filteredProps: Record = {};
+ for (const [key, value] of Object.entries(properties)) {
+ if (SUPPORTED_PROPS.includes(key)) {
+ filteredProps[key] = value;
+ }
+ }
+
+ let filteredFromProps: Record | undefined;
+ if (fromProperties) {
+ filteredFromProps = {};
+ for (const [key, value] of Object.entries(fromProperties)) {
+ if (SUPPORTED_PROPS.includes(key)) {
+ filteredFromProps[key] = value;
+ }
+ }
+ }
+
+ return {
+ id: `anim-${idNum}`,
+ targetSelector,
+ method,
+ position,
+ properties: filteredProps,
+ fromProperties: filteredFromProps,
+ duration,
+ ease,
+ };
+}
+
+export function serializeGsapAnimations(
+ animations: GsapAnimation[],
+ timelineVar = "tl",
+ options?: { includeMediaSync?: boolean },
+): string {
+ const sorted = [...animations].sort((a, b) => a.position - b.position);
+
+ const lines = sorted.map((anim) => {
+ const selector = `"${anim.targetSelector}"`;
+
+ const props: Record = { ...anim.properties };
+ if (anim.duration !== undefined) props.duration = anim.duration;
+ if (anim.ease) props.ease = anim.ease;
+
+ const propsStr = serializeObject(props);
+
+ switch (anim.method) {
+ case "set":
+ return ` ${timelineVar}.set(${selector}, ${propsStr}, ${anim.position});`;
+ case "to":
+ return ` ${timelineVar}.to(${selector}, ${propsStr}, ${anim.position});`;
+ case "from":
+ return ` ${timelineVar}.from(${selector}, ${propsStr}, ${anim.position});`;
+ case "fromTo": {
+ const fromStr = serializeObject(anim.fromProperties || {});
+ return ` ${timelineVar}.fromTo(${selector}, ${fromStr}, ${propsStr}, ${anim.position});`;
+ }
+ }
+ });
+
+ let mediaSync = "";
+ if (options?.includeMediaSync) {
+ mediaSync = `
+ // Sync media playback
+ ${timelineVar}.eventCallback("onUpdate", function() {
+ const time = ${timelineVar}.time();
+ document.querySelectorAll("video[data-start], audio[data-start]").forEach(function(media) {
+ const start = parseFloat(media.dataset.start);
+ const end = parseFloat(media.dataset.end) || Infinity;
+ const mediaTime = time - start;
+ if (time >= start && time < end) {
+ if (Math.abs(media.currentTime - mediaTime) > 0.1) {
+ media.currentTime = mediaTime;
+ }
+ if (media.paused && !${timelineVar}.paused()) {
+ media.play().catch(function() {});
+ }
+ } else if (!media.paused) {
+ media.pause();
+ }
+ });
+ });`;
+ }
+
+ return `
+ const ${timelineVar} = gsap.timeline({ paused: true });
+${lines.join("\n")}${mediaSync}
+ `;
+}
+
+function serializeObject(obj: Record): string {
+ const entries = Object.entries(obj).map(([key, value]) => {
+ if (typeof value === "string") {
+ return `${key}: "${value}"`;
+ }
+ return `${key}: ${value}`;
+ });
+ return `{ ${entries.join(", ")} }`;
+}
+
+export function updateAnimationInScript(script: string, animationId: string, updates: Partial): string {
+ const parsed = parseGsapScript(script);
+
+ const updated = parsed.animations.map((anim) => {
+ if (anim.id === animationId) {
+ return { ...anim, ...updates };
+ }
+ return anim;
+ });
+
+ return serializeGsapAnimations(updated, parsed.timelineVar);
+}
+
+export function addAnimationToScript(
+ script: string,
+ animation: Omit,
+): { script: string; id: string } {
+ const parsed = parseGsapScript(script);
+
+ const id = `anim-${Date.now()}`;
+ const newAnim: GsapAnimation = { ...animation, id };
+
+ parsed.animations.push(newAnim);
+
+ return {
+ script: serializeGsapAnimations(parsed.animations, parsed.timelineVar),
+ id,
+ };
+}
+
+export function removeAnimationFromScript(script: string, animationId: string): string {
+ const parsed = parseGsapScript(script);
+ const filtered = parsed.animations.filter((a) => a.id !== animationId);
+ return serializeGsapAnimations(filtered, parsed.timelineVar);
+}
+
+export function getAnimationsForElement(animations: GsapAnimation[], elementId: string): GsapAnimation[] {
+ const selector = `#${elementId}`;
+ return animations.filter((a) => a.targetSelector === selector);
+}
+
+export interface ValidationResult {
+ valid: boolean;
+ errors: string[];
+ warnings: string[];
+}
+
+const FORBIDDEN_GSAP_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+ { pattern: /\.call\s*\(/, message: "call() method not allowed" },
+ {
+ pattern: /\.add\s*\(\s*function/,
+ message: "add(function) not allowed",
+ },
+ {
+ pattern: /\.add\s*\(\s*\(/,
+ message: "add() with arrow function not allowed",
+ },
+ { pattern: /onComplete\s*:/, message: "onComplete callback not allowed" },
+ { pattern: /onStart\s*:/, message: "onStart callback not allowed" },
+ { pattern: /onUpdate\s*:/, message: "onUpdate callback not allowed" },
+ {
+ pattern: /onRepeat\s*:/,
+ message: "onRepeat callback not allowed",
+ },
+ {
+ pattern: /onReverseComplete\s*:/,
+ message: "onReverseComplete callback not allowed",
+ },
+ {
+ pattern: /repeat\s*:\s*-1/,
+ message: "Infinite repeat (repeat: -1) not allowed",
+ },
+ {
+ pattern: /Math\.random\s*\(/,
+ message: "Random values (Math.random) not allowed",
+ },
+ {
+ pattern: /Date\.now\s*\(/,
+ message: "Date-dependent values (Date.now) not allowed",
+ },
+ { pattern: /new\s+Date\s*\(/, message: "Date constructor not allowed" },
+ { pattern: /setTimeout\s*\(/, message: "setTimeout not allowed" },
+ { pattern: /setInterval\s*\(/, message: "setInterval not allowed" },
+ {
+ pattern: /requestAnimationFrame\s*\(/,
+ message: "requestAnimationFrame not allowed",
+ },
+];
+
+export function validateCompositionGsap(script: string): ValidationResult {
+ const errors: string[] = [];
+ const warnings: string[] = [];
+
+ for (const { pattern, message } of FORBIDDEN_GSAP_PATTERNS) {
+ if (pattern.test(script)) {
+ errors.push(message);
+ }
+ }
+
+ if (/yoyo\s*:\s*true/.test(script)) {
+ warnings.push("yoyo animations may behave unexpectedly when scrubbing");
+ }
+
+ if (/stagger\s*:/.test(script)) {
+ warnings.push("stagger animations may not serialize correctly");
+ }
+
+ return {
+ valid: errors.length === 0,
+ errors,
+ warnings,
+ };
+}
+
+export function keyframesToGsapAnimations(
+ elementId: string,
+ keyframes: Keyframe[],
+ elementStartTime: number,
+ base?: { x?: number; y?: number; scale?: number },
+): GsapAnimation[] {
+ const sorted = [...keyframes].sort((a, b) => a.time - b.time);
+ const animations: GsapAnimation[] = [];
+ const baseX = base?.x ?? 0;
+ const baseY = base?.y ?? 0;
+ const baseScale = base?.scale ?? 1;
+
+ sorted.forEach((kf, i) => {
+ const absoluteTime = elementStartTime + kf.time;
+ const isFirst = i === 0;
+
+ const prevKf = i > 0 ? sorted[i - 1] : null;
+ const duration = prevKf ? kf.time - prevKf.time : undefined;
+ const position = prevKf ? elementStartTime + prevKf.time : absoluteTime;
+
+ const properties: Record = {};
+ for (const [key, value] of Object.entries(kf.properties)) {
+ if (typeof value !== "number") continue;
+ if (key === "x") properties.x = baseX + value;
+ else if (key === "y") properties.y = baseY + value;
+ else if (key === "scale") properties.scale = baseScale * value;
+ else properties[key] = value;
+ }
+
+ animations.push({
+ id: `${elementId}-kf-${kf.id}`,
+ targetSelector: `#${elementId}`,
+ method: isFirst ? "set" : "to",
+ position,
+ properties,
+ duration: isFirst ? undefined : duration,
+ ease: kf.ease,
+ });
+ });
+
+ return animations;
+}
+
+export function gsapAnimationsToKeyframes(
+ animations: GsapAnimation[],
+ elementStartTime: number,
+ options?: {
+ baseX?: number;
+ baseY?: number;
+ baseScale?: number;
+ clampTimeToZero?: boolean;
+ skipBaseSet?: boolean;
+ },
+): Keyframe[] {
+ const validMethods: GsapMethod[] = ["set", "to", "from", "fromTo"];
+ const baseX = options?.baseX ?? 0;
+ const baseY = options?.baseY ?? 0;
+ const baseScale = options?.baseScale ?? 1;
+ const clampTimeToZero = options?.clampTimeToZero ?? true;
+ const skipBaseSet = options?.skipBaseSet ?? false;
+ const baseTimeEpsilon = 0.001;
+ const baseValueEpsilon = 0.00001;
+
+ return animations
+ .filter((a) => validMethods.includes(a.method))
+ .map((a) => {
+ const relativeTimeRaw = a.position - elementStartTime;
+ const time = clampTimeToZero ? Math.max(0, relativeTimeRaw) : relativeTimeRaw;
+
+ const properties: Partial = {};
+
+ for (const [key, value] of Object.entries(a.properties)) {
+ if (SUPPORTED_PROPS.includes(key) && typeof value === "number") {
+ if (key === "x") {
+ (properties as Record).x = value - baseX;
+ } else if (key === "y") {
+ (properties as Record).y = value - baseY;
+ } else if (key === "scale") {
+ (properties as Record).scale = baseScale !== 0 ? value / baseScale : value;
+ } else {
+ (properties as Record)[key] = value;
+ }
+ }
+ }
+
+ if (skipBaseSet && a.method === "set" && Math.abs(time) <= baseTimeEpsilon) {
+ const propKeys = Object.keys(properties);
+ const isOnlyBaseProps = propKeys.every((k) => k === "x" || k === "y" || k === "scale");
+ if (isOnlyBaseProps && propKeys.length > 0) {
+ const hasNonBaseOffset =
+ (properties.x !== undefined && Math.abs(properties.x) > baseValueEpsilon) ||
+ (properties.y !== undefined && Math.abs(properties.y) > baseValueEpsilon) ||
+ (properties.scale !== undefined && Math.abs(properties.scale - 1) > baseValueEpsilon);
+ if (!hasNonBaseOffset) {
+ return null;
+ }
+ }
+ }
+
+ const kf: Keyframe = { id: a.id, time, properties };
+ if (a.ease !== undefined) kf.ease = a.ease;
+ return kf;
+ })
+ .filter((kf): kf is Keyframe => kf !== null)
+ .sort((a, b) => a.time - b.time);
+}
diff --git a/packages/core/src/parsers/htmlParser.test.ts b/packages/core/src/parsers/htmlParser.test.ts
new file mode 100644
index 000000000..8be4dc2ad
--- /dev/null
+++ b/packages/core/src/parsers/htmlParser.test.ts
@@ -0,0 +1,525 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, it, expect } from "vitest";
+import { parseHtml, updateElementInHtml, addElementToHtml, removeElementFromHtml, validateCompositionHtml, extractCompositionMetadata } from "./htmlParser.js";
+
+describe("parseHtml", () => {
+ it("extracts elements with data-start and data-end", () => {
+ const html = `
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ expect(result.elements).toHaveLength(2);
+ expect(result.elements[0].id).toBe("text1");
+ expect(result.elements[0].startTime).toBe(0);
+ expect(result.elements[0].duration).toBe(5);
+ expect(result.elements[0].name).toBe("Title");
+ expect(result.elements[0].type).toBe("text");
+
+ expect(result.elements[1].id).toBe("text2");
+ expect(result.elements[1].startTime).toBe(2);
+ expect(result.elements[1].duration).toBe(5);
+ });
+
+ it("handles nested compositions", () => {
+ const html = `
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ expect(result.elements).toHaveLength(1);
+ expect(result.elements[0].type).toBe("composition");
+ expect(result.elements[0].id).toBe("comp1");
+ if (result.elements[0].type === "composition") {
+ expect(result.elements[0].compositionId).toBe("abc123");
+ expect(result.elements[0].src).toBe("/compositions/abc123");
+ }
+ });
+
+ it("extracts media elements (video, audio, img)", () => {
+ const html = `
+
+
+
+
+
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ expect(result.elements[0].x).toBe(100);
+ expect(result.elements[0].y).toBe(200);
+ expect(result.elements[0].scale).toBe(1.5);
+ expect(result.elements[0].opacity).toBe(0.8);
+ });
+
+ it("parses text element properties (color, fontSize, fontWeight, fontFamily)", () => {
+ const html = `
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ const textEl = result.elements[0];
+ expect(textEl.type).toBe("text");
+ if (textEl.type === "text") {
+ expect(textEl.color).toBe("red");
+ expect(textEl.fontSize).toBe(72);
+ expect(textEl.fontWeight).toBe(900);
+ expect(textEl.fontFamily).toBe("Montserrat");
+ }
+ });
+
+ it("parses media element properties (mediaStartTime, sourceDuration, volume)", () => {
+ const html = `
+
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ const vid = result.elements[0];
+ expect(vid.type).toBe("video");
+ if (vid.type === "video") {
+ expect(vid.mediaStartTime).toBe(5);
+ expect(vid.sourceDuration).toBe(30);
+ expect(vid.volume).toBe(0.5);
+ expect(vid.hasAudio).toBe(true);
+ }
+ });
+
+ it("extracts data-keyframes attribute", () => {
+ const keyframes = JSON.stringify([
+ { id: "kf1", time: 0, properties: { opacity: 0 } },
+ { id: "kf2", time: 1, properties: { opacity: 1 } },
+ ]);
+ const html = `
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ expect(result.keyframes["text1"]).toBeDefined();
+ expect(result.keyframes["text1"]).toHaveLength(2);
+ expect(result.keyframes["text1"][0].id).toBe("kf1");
+ });
+
+ it("parses stage zoom keyframes", () => {
+ const zoomKeyframes = JSON.stringify([
+ { id: "z1", time: 0, zoom: { scale: 1, focusX: 960, focusY: 540 } },
+ { id: "z2", time: 2, zoom: { scale: 2, focusX: 500, focusY: 300 } },
+ ]);
+ const html = `
+
+
+
+
+
+ `;
+ const result = parseHtml(html);
+
+ expect(result.stageZoomKeyframes).toHaveLength(2);
+ expect(result.stageZoomKeyframes[0].zoom.scale).toBe(1);
+ expect(result.stageZoomKeyframes[1].zoom.scale).toBe(2);
+ });
+
+ it("returns empty zoom keyframes when no zoom container exists", () => {
+ const html = `
+
+
+
+ `;
+ const result = parseHtml(html);
+ expect(result.stageZoomKeyframes).toHaveLength(0);
+ });
+});
+
+describe("updateElementInHtml", () => {
+ it("updates startTime and duration", () => {
+ const html = `
+
+
+`;
+
+ const updated = updateElementInHtml(html, "el1", { startTime: 2, duration: 3 });
+
+ expect(updated).toContain('data-start="2"');
+ expect(updated).toContain('data-end="5"'); // data-end gets set to start + duration
+ });
+
+ it("updates element name", () => {
+ const html = `
+
+
+`;
+
+ const updated = updateElementInHtml(html, "el1", { name: "New Name" });
+
+ expect(updated).toContain('data-name="New Name"');
+ });
+
+ it("returns original html when element not found", () => {
+ const html = `
+
+
+`;
+
+ const updated = updateElementInHtml(html, "nonexistent", { name: "Test" });
+
+ expect(updated).toBe(html);
+ });
+});
+
+describe("addElementToHtml", () => {
+ it("adds a new text element to the HTML", () => {
+ const html = `
+
+
+`;
+
+ const { html: updated, id } = addElementToHtml(html, {
+ type: "text",
+ name: "New Text",
+ content: "Hello!",
+ startTime: 1,
+ duration: 3,
+ zIndex: 1,
+ });
+
+ expect(id).toBeDefined();
+ expect(updated).toContain(`id="${id}"`);
+ expect(updated).toContain('data-start="1"');
+ expect(updated).toContain('data-end="4"');
+ expect(updated).toContain("Hello!");
+ });
+
+ it("adds a video element", () => {
+ const html = `
+
+
+`;
+
+ const { html: updated, id } = addElementToHtml(html, {
+ type: "video",
+ name: "My Video",
+ src: "video.mp4",
+ startTime: 0,
+ duration: 10,
+ zIndex: 0,
+ });
+
+ expect(updated).toContain(`id="${id}"`);
+ expect(updated).toContain("video.mp4");
+ });
+});
+
+describe("removeElementFromHtml", () => {
+ it("removes an element by id", () => {
+ const html = `
+
+
+`;
+
+ const updated = removeElementFromHtml(html, "el1");
+
+ expect(updated).not.toContain('id="el1"');
+ expect(updated).toContain('id="el2"');
+ });
+});
+
+describe("validateCompositionHtml", () => {
+ it("returns valid for a well-formed composition", () => {
+ const html = `
+
+
+
+
+`;
+
+ const result = validateCompositionHtml(html);
+ expect(result.valid).toBe(true);
+ expect(result.errors).toHaveLength(0);
+ });
+
+ it("reports error for missing composition-id", () => {
+ const html = `
+
+
+
+
+`;
+
+ const result = validateCompositionHtml(html);
+ expect(result.valid).toBe(false);
+ expect(result.errors).toContain("Missing data-composition-id attribute on element");
+ });
+
+ it("reports error for missing composition-duration", () => {
+ const html = `
+
+
+
+
+`;
+
+ const result = validateCompositionHtml(html);
+ expect(result.valid).toBe(false);
+ expect(result.errors).toContain("Missing data-composition-duration attribute on element");
+ });
+
+ it("reports error for missing #stage", () => {
+ const html = `
+
+
+`;
+
+ const result = validateCompositionHtml(html);
+ expect(result.valid).toBe(false);
+ expect(result.errors).toContain("Missing #stage element");
+ });
+
+ it("reports error for inline event handlers", () => {
+ const html = `
+
+
+
+
+`;
+
+ const result = validateCompositionHtml(html);
+ expect(result.valid).toBe(false);
+ expect(result.errors).toContain("Inline event handlers (onclick, onload, etc.) not allowed");
+ });
+});
+
+describe("extractCompositionMetadata", () => {
+ it("extracts composition id and duration", () => {
+ const html = `
+
+
+`;
+
+ const meta = extractCompositionMetadata(html);
+ expect(meta.compositionId).toBe("comp-abc");
+ expect(meta.compositionDuration).toBe(15.5);
+ });
+
+ it("returns null for missing metadata", () => {
+ const html = ``;
+
+ const meta = extractCompositionMetadata(html);
+ expect(meta.compositionId).toBeNull();
+ expect(meta.compositionDuration).toBeNull();
+ });
+
+ it("extracts composition variables", () => {
+ const variables = JSON.stringify([
+ { id: "title", type: "string", label: "Title", default: "Hello" },
+ { id: "count", type: "number", label: "Count", default: 5 },
+ ]);
+ const html = `
+
+
+`;
+
+ const meta = extractCompositionMetadata(html);
+ expect(meta.variables).toHaveLength(2);
+ expect(meta.variables[0].id).toBe("title");
+ expect(meta.variables[0].type).toBe("string");
+ expect(meta.variables[1].id).toBe("count");
+ expect(meta.variables[1].type).toBe("number");
+ });
+});
diff --git a/packages/core/src/parsers/htmlParser.ts b/packages/core/src/parsers/htmlParser.ts
new file mode 100644
index 000000000..9cd92e4f2
--- /dev/null
+++ b/packages/core/src/parsers/htmlParser.ts
@@ -0,0 +1,843 @@
+import type {
+ TimelineElement,
+ TimelineElementType,
+ TimelineMediaElement,
+ TimelineTextElement,
+ TimelineCompositionElement,
+ CanvasResolution,
+ Keyframe,
+ KeyframeProperties,
+ StageZoomKeyframe,
+ CompositionVariable,
+} from "../core.types";
+import { CANVAS_DIMENSIONS } from "../core.types";
+import {
+ parseGsapScript,
+ validateCompositionGsap,
+ gsapAnimationsToKeyframes,
+ getAnimationsForElement,
+} from "./gsapParser";
+import type { ValidationResult } from "./gsapParser";
+
+const MEDIA_TYPES = new Set(["video", "image", "audio"]);
+
+export interface ParsedHtml {
+ elements: TimelineElement[];
+ gsapScript: string | null;
+ styles: string | null;
+ resolution: CanvasResolution;
+ keyframes: Record;
+ stageZoomKeyframes: StageZoomKeyframe[];
+}
+
+function getElementType(el: Element): TimelineElementType | null {
+ const tag = el.tagName.toLowerCase();
+ if (tag === "video") return "video";
+ if (tag === "img") return "image";
+ if (tag === "audio") return "audio";
+ // Check for explicit data-type attribute first
+ const dataType = el.getAttribute("data-type");
+ if (dataType === "composition") return "composition";
+ if (dataType === "text") return "text";
+ // Fall back to tag-based detection for backwards compatibility
+ if (tag === "div" || tag === "p" || tag === "h1" || tag === "h2" || tag === "h3" || tag === "span") {
+ return "text";
+ }
+ return null;
+}
+
+function getElementName(el: Element): string {
+ const dataName = el.getAttribute("data-name");
+ if (dataName) return dataName;
+
+ const type = getElementType(el);
+ if (type === "text") {
+ const text = el.textContent?.trim().slice(0, 30) || "Text";
+ return text.length === 30 ? text + "..." : text;
+ }
+
+ const src = el.getAttribute("src");
+ if (src) {
+ const filename = src.split("/").pop() || src;
+ return filename.split("?")[0] ?? filename;
+ }
+
+ return el.id || el.className?.toString().split(" ")[0] || "Element";
+}
+
+function getZIndex(el: Element): number {
+ const dataLayer = el.getAttribute("data-layer");
+ if (dataLayer) return parseInt(dataLayer, 10) || 0;
+
+ const style = (el as HTMLElement).style?.zIndex;
+ if (style) return parseInt(style, 10) || 0;
+
+ return 0;
+}
+
+function parseResolutionFromCss(doc: Document, cssText: string | null): CanvasResolution {
+ const stage = doc.getElementById("stage") || doc.querySelector("#stage");
+ if (stage) {
+ const inlineStyle = (stage as HTMLElement).style;
+ if (inlineStyle?.width && inlineStyle?.height) {
+ const w = parseInt(inlineStyle.width, 10);
+ const h = parseInt(inlineStyle.height, 10);
+ if (w && h) {
+ return w > h ? "landscape" : "portrait";
+ }
+ }
+ }
+
+ if (cssText) {
+ const stageMatch = cssText.match(/#stage\s*\{[^}]*width:\s*(\d+)px[^}]*height:\s*(\d+)px[^}]*\}/);
+ if (stageMatch) {
+ const w = parseInt(stageMatch[1] ?? "", 10);
+ const h = parseInt(stageMatch[2] ?? "", 10);
+ return w > h ? "landscape" : "portrait";
+ }
+ const stageMatchReverse = cssText.match(/#stage\s*\{[^}]*height:\s*(\d+)px[^}]*width:\s*(\d+)px[^}]*\}/);
+ if (stageMatchReverse) {
+ const h = parseInt(stageMatchReverse[1] ?? "", 10);
+ const w = parseInt(stageMatchReverse[2] ?? "", 10);
+ return w > h ? "landscape" : "portrait";
+ }
+ }
+
+ return "portrait";
+}
+
+function parseResolutionFromHtml(doc: Document): CanvasResolution | null {
+ const htmlEl = doc.documentElement;
+ const resolutionAttr = htmlEl.getAttribute("data-resolution");
+ if (resolutionAttr === "landscape" || resolutionAttr === "portrait") {
+ return resolutionAttr;
+ }
+
+ const widthAttr = htmlEl.getAttribute("data-composition-width");
+ const heightAttr = htmlEl.getAttribute("data-composition-height");
+ if (widthAttr && heightAttr) {
+ const width = parseInt(widthAttr, 10);
+ const height = parseInt(heightAttr, 10);
+ if (width && height) {
+ return width > height ? "landscape" : "portrait";
+ }
+ }
+
+ return null;
+}
+
+export function parseHtml(html: string): ParsedHtml {
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+
+ const elements: TimelineElement[] = [];
+ const keyframes: Record = {};
+ let idCounter = 0;
+
+ const htmlEl = doc.documentElement;
+ const customStylesAttr = htmlEl.getAttribute("data-custom-styles");
+ let customStyles: string | null = null;
+ if (customStylesAttr) {
+ try {
+ customStyles = JSON.parse(customStylesAttr);
+ } catch {
+ customStyles = customStylesAttr;
+ }
+ }
+
+ const timedElements = doc.querySelectorAll("[data-start]");
+
+ timedElements.forEach((el) => {
+ const type = getElementType(el);
+ if (!type) return;
+
+ const start = parseFloat(el.getAttribute("data-start") || "0");
+ const dataEnd = el.getAttribute("data-end");
+
+ let duration: number;
+ if (dataEnd) {
+ duration = Math.max(0, parseFloat(dataEnd) - start);
+ } else {
+ duration = 5;
+ }
+
+ const id = el.id || `element-${++idCounter}`;
+ const name = getElementName(el);
+ const zIndex = getZIndex(el);
+
+ // Parse data-keyframes attribute if present
+ const keyframesAttr = el.getAttribute("data-keyframes");
+ if (keyframesAttr) {
+ try {
+ const parsedKeyframes = JSON.parse(keyframesAttr);
+ if (Array.isArray(parsedKeyframes) && parsedKeyframes.length > 0) {
+ keyframes[id] = parsedKeyframes;
+ }
+ } catch {
+ // skip invalid keyframes
+ }
+ }
+
+ // Parse transform properties (x, y, scale, opacity)
+ const xAttr = el.getAttribute("data-x");
+ const yAttr = el.getAttribute("data-y");
+ const scaleAttr = el.getAttribute("data-scale");
+ const opacityAttr = el.getAttribute("data-opacity");
+ const x = xAttr ? parseFloat(xAttr) : undefined;
+ const y = yAttr ? parseFloat(yAttr) : undefined;
+ const scale = scaleAttr ? parseFloat(scaleAttr) : undefined;
+ const opacity = opacityAttr ? parseFloat(opacityAttr) : undefined;
+
+ if (type === "text") {
+ const textEl = el.firstElementChild;
+ const content = textEl?.textContent || name;
+ const color = el.getAttribute("data-color") || undefined;
+ const fontSizeAttr = el.getAttribute("data-font-size");
+ const fontSize = fontSizeAttr ? parseInt(fontSizeAttr, 10) : undefined;
+ const fontWeightAttr = el.getAttribute("data-font-weight");
+ const fontWeight = fontWeightAttr ? parseInt(fontWeightAttr, 10) : undefined;
+ const fontFamily = el.getAttribute("data-font-family") || undefined;
+ const textShadowAttr = el.getAttribute("data-text-shadow");
+ const textShadow = textShadowAttr === "false" ? false : undefined;
+
+ // Parse outline properties
+ const textOutlineAttr = el.getAttribute("data-text-outline");
+ const textOutline = textOutlineAttr === "true" ? true : undefined;
+ const textOutlineColor = el.getAttribute("data-text-outline-color") || undefined;
+ const textOutlineWidthAttr = el.getAttribute("data-text-outline-width");
+ const textOutlineWidth = textOutlineWidthAttr ? parseInt(textOutlineWidthAttr, 10) : undefined;
+
+ // Parse highlight properties
+ const textHighlightAttr = el.getAttribute("data-text-highlight");
+ const textHighlight = textHighlightAttr === "true" ? true : undefined;
+ const textHighlightColor = el.getAttribute("data-text-highlight-color") || undefined;
+ const textHighlightPaddingAttr = el.getAttribute("data-text-highlight-padding");
+ const textHighlightPadding = textHighlightPaddingAttr ? parseInt(textHighlightPaddingAttr, 10) : undefined;
+ const textHighlightRadiusAttr = el.getAttribute("data-text-highlight-radius");
+ const textHighlightRadius = textHighlightRadiusAttr ? parseInt(textHighlightRadiusAttr, 10) : undefined;
+
+ const textElement: TimelineTextElement = {
+ id,
+ type: "text",
+ name,
+ content,
+ startTime: start,
+ duration,
+ zIndex,
+ x,
+ y,
+ scale,
+ opacity,
+ color,
+ fontSize,
+ fontWeight,
+ fontFamily,
+ textShadow,
+ textOutline,
+ textOutlineColor,
+ textOutlineWidth,
+ textHighlight,
+ textHighlightColor,
+ textHighlightPadding,
+ textHighlightRadius,
+ };
+ elements.push(textElement);
+ } else if (type === "composition") {
+ // Composition is a div container with iframe inside
+ const iframe = el.querySelector("iframe");
+ const src = iframe?.getAttribute("src") || el.getAttribute("src") || "";
+ const compositionId = el.getAttribute("data-composition-id") || "";
+ const sourceDurationAttr = el.getAttribute("data-source-duration");
+ const sourceDuration = sourceDurationAttr ? parseFloat(sourceDurationAttr) : undefined;
+ const sourceWidthAttr = el.getAttribute("data-source-width");
+ const sourceWidth = sourceWidthAttr ? parseInt(sourceWidthAttr, 10) : undefined;
+ const sourceHeightAttr = el.getAttribute("data-source-height");
+ const sourceHeight = sourceHeightAttr ? parseInt(sourceHeightAttr, 10) : undefined;
+
+ // Parse variable values if present
+ const variableValuesAttr = el.getAttribute("data-variable-values");
+ let variableValues: Record | undefined;
+ if (variableValuesAttr) {
+ try {
+ variableValues = JSON.parse(variableValuesAttr);
+ } catch {
+ // skip invalid variable values
+ }
+ }
+
+ const compositionElement: TimelineCompositionElement = {
+ id,
+ type: "composition",
+ name,
+ src,
+ compositionId,
+ startTime: start,
+ duration,
+ zIndex,
+ x,
+ y,
+ scale,
+ opacity,
+ sourceDuration,
+ sourceWidth,
+ sourceHeight,
+ variableValues,
+ };
+ elements.push(compositionElement);
+ } else {
+ if (!MEDIA_TYPES.has(type)) return;
+
+ const src = el.getAttribute("src") || "";
+ const mediaStartTimeAttr = el.getAttribute("data-media-start");
+ const mediaStartTime = mediaStartTimeAttr ? parseFloat(mediaStartTimeAttr) : undefined;
+ const sourceDurationAttr = el.getAttribute("data-source-duration");
+ const sourceDuration = sourceDurationAttr ? parseFloat(sourceDurationAttr) : undefined;
+ const isArollAttr = el.getAttribute("data-aroll");
+ const isAroll = isArollAttr === "true" ? true : undefined;
+ const volumeAttr = el.getAttribute("data-volume");
+ const volume = volumeAttr ? parseFloat(volumeAttr) : undefined;
+ const hasAudioAttr = el.getAttribute("data-has-audio");
+ const hasAudio = hasAudioAttr === "true" ? true : undefined;
+
+ const mediaElement: TimelineMediaElement = {
+ id,
+ type: type as "video" | "image" | "audio",
+ name,
+ src,
+ startTime: start,
+ duration,
+ zIndex,
+ x,
+ y,
+ scale,
+ opacity,
+ mediaStartTime,
+ sourceDuration,
+ isAroll,
+ volume,
+ hasAudio,
+ };
+ elements.push(mediaElement);
+ }
+ });
+
+ const scriptTags = doc.querySelectorAll("script");
+ let gsapScript: string | null = null;
+
+ for (const script of scriptTags) {
+ const src = script.getAttribute("src");
+ if (src && src.includes("gsap")) continue;
+
+ const content = script.textContent?.trim();
+ if (content && (content.includes("gsap") || content.includes("timeline"))) {
+ gsapScript = content;
+ break;
+ }
+ }
+
+ // Extract x/y positions and scale from GSAP script
+ if (gsapScript) {
+ const positionMap = extractPositionsFromGsap(gsapScript);
+ for (const element of elements) {
+ const pos = positionMap.get(element.id);
+ if (pos) {
+ if (pos.x !== undefined) element.x = pos.x;
+ if (pos.y !== undefined) element.y = pos.y;
+ if (
+ pos.scale !== undefined &&
+ (element.type === "video" || element.type === "image" || element.type === "composition")
+ ) {
+ (element as TimelineMediaElement | TimelineCompositionElement).scale = pos.scale;
+ }
+ }
+ }
+ }
+
+ // Normalize keyframes (clamp negative time, convert absolute -> relative if detected)
+ for (const element of elements) {
+ const elementKeyframes = keyframes[element.id];
+ if (!elementKeyframes || elementKeyframes.length === 0) continue;
+
+ const baseX = element.x ?? 0;
+ const baseY = element.y ?? 0;
+ const baseScale =
+ element.type === "video" || element.type === "image" || element.type === "composition"
+ ? ((element as TimelineMediaElement | TimelineCompositionElement).scale ?? 1)
+ : 1;
+
+ keyframes[element.id] = normalizeKeyframes(elementKeyframes, baseX, baseY, baseScale);
+ }
+
+ const styleTags = doc.querySelectorAll("style");
+ const allStyles =
+ Array.from(styleTags)
+ .map((s) => s.textContent?.trim())
+ .filter(Boolean)
+ .join("\n\n") || null;
+
+ const customStyleTags = Array.from(styleTags).filter((s) => s.getAttribute("data-hf-custom") === "true");
+ const customStylesFromTags =
+ customStyleTags
+ .map((s) => s.textContent?.trim())
+ .filter(Boolean)
+ .join("\n\n") || null;
+
+ const styles = customStyles ?? customStylesFromTags ?? null;
+
+ const resolution = parseResolutionFromHtml(doc) ?? parseResolutionFromCss(doc, allStyles);
+
+ // Extract keyframes from GSAP animations for elements that don't have data-keyframes
+ if (gsapScript) {
+ const parsed = parseGsapScript(gsapScript);
+ for (const element of elements) {
+ // Only extract from GSAP if we don't have explicit data-keyframes
+ if (keyframes[element.id]) continue;
+
+ const elementAnimations = getAnimationsForElement(parsed.animations, element.id);
+ if (elementAnimations.length > 0) {
+ const elementKeyframes = gsapAnimationsToKeyframes(elementAnimations, element.startTime, {
+ baseX: element.x ?? 0,
+ baseY: element.y ?? 0,
+ baseScale:
+ element.type === "video" || element.type === "image" || element.type === "composition"
+ ? ((element as TimelineMediaElement | TimelineCompositionElement).scale ?? 1)
+ : 1,
+ clampTimeToZero: true,
+ skipBaseSet: true,
+ });
+ if (elementKeyframes.length > 0) {
+ keyframes[element.id] = elementKeyframes;
+ }
+ }
+ }
+ }
+
+ // Parse stage zoom keyframes from zoom container
+ const stageZoomKeyframes = parseStageZoomKeyframes(doc);
+
+ return {
+ elements,
+ gsapScript,
+ styles,
+ resolution,
+ keyframes,
+ stageZoomKeyframes,
+ };
+}
+
+function parseStageZoomKeyframes(doc: Document): StageZoomKeyframe[] {
+ const zoomContainer = doc.getElementById("stage-zoom-container");
+ if (!zoomContainer) {
+ return [];
+ }
+
+ const zoomKeyframesAttr = zoomContainer.getAttribute("data-zoom-keyframes");
+ if (!zoomKeyframesAttr) {
+ return [];
+ }
+
+ try {
+ const parsed = JSON.parse(zoomKeyframesAttr);
+ if (Array.isArray(parsed)) {
+ return parsed.filter(
+ (kf): kf is StageZoomKeyframe =>
+ typeof kf === "object" &&
+ kf !== null &&
+ typeof kf.id === "string" &&
+ typeof kf.time === "number" &&
+ typeof kf.zoom === "object" &&
+ kf.zoom !== null &&
+ typeof kf.zoom.scale === "number" &&
+ typeof kf.zoom.focusX === "number" &&
+ typeof kf.zoom.focusY === "number",
+ );
+ }
+ } catch {
+ // skip invalid zoom keyframes
+ }
+
+ return [];
+}
+
+/**
+ * Extract x/y positions and scale from GSAP set() calls at position 0
+ * Returns a map of elementId -> { x, y, scale }
+ */
+function extractPositionsFromGsap(script: string): Map {
+ const positionMap = new Map();
+
+ try {
+ const parsed = parseGsapScript(script);
+
+ // Look for set() calls at position 0 with x/y/scale properties
+ for (const anim of parsed.animations) {
+ if (anim.method === "set" && anim.position === 0) {
+ // Extract element ID from selector (e.g., "#element-1" -> "element-1")
+ const selectorMatch = anim.targetSelector.match(/^#(.+)$/);
+ if (!selectorMatch) continue;
+
+ const elementId = selectorMatch[1] ?? "";
+ const x = typeof anim.properties.x === "number" ? anim.properties.x : undefined;
+ const y = typeof anim.properties.y === "number" ? anim.properties.y : undefined;
+ const scale = typeof anim.properties.scale === "number" ? anim.properties.scale : undefined;
+
+ // Only add to map if x, y, or scale is defined and non-default
+ if ((x !== undefined && x !== 0) || (y !== undefined && y !== 0) || (scale !== undefined && scale !== 1)) {
+ const existing = positionMap.get(elementId) || {};
+ positionMap.set(elementId, {
+ x: x !== undefined ? x : existing.x,
+ y: y !== undefined ? y : existing.y,
+ scale: scale !== undefined ? scale : existing.scale,
+ });
+ }
+ }
+ }
+ } catch {
+ // skip GSAP position parsing failure
+ }
+
+ return positionMap;
+}
+
+function normalizeKeyframes(keyframes: Keyframe[], baseX: number, baseY: number, baseScale: number): Keyframe[] {
+ const timeEpsilon = 0.001;
+ const valueEpsilon = 0.00001;
+
+ const hasBaseCheck = (value: number | undefined, base: number): boolean =>
+ value !== undefined && Math.abs(value - base) <= valueEpsilon && Math.abs(base) > valueEpsilon;
+
+ const timeZeroKeyframes = keyframes.filter((kf) => Math.abs(kf.time) <= timeEpsilon);
+
+ const treatAsAbsolute = timeZeroKeyframes.some((kf) => {
+ const props = kf.properties || {};
+ if (
+ hasBaseCheck(props.x, baseX) ||
+ hasBaseCheck(props.y, baseY) ||
+ (baseScale !== 1 && hasBaseCheck(props.scale, baseScale))
+ ) {
+ return true;
+ }
+ return false;
+ });
+
+ return keyframes.map((kf) => {
+ const normalizedProps: Partial = {};
+ for (const [key, value] of Object.entries(kf.properties || {})) {
+ if (typeof value !== "number") continue;
+ if (treatAsAbsolute && key === "x") {
+ normalizedProps.x = value - baseX;
+ } else if (treatAsAbsolute && key === "y") {
+ normalizedProps.y = value - baseY;
+ } else if (treatAsAbsolute && key === "scale") {
+ normalizedProps.scale = baseScale !== 0 ? value / baseScale : value;
+ } else {
+ (normalizedProps as Record)[key] = value;
+ }
+ }
+
+ return {
+ ...kf,
+ time: Math.max(0, kf.time),
+ properties: normalizedProps,
+ };
+ });
+}
+
+export function updateElementInHtml(html: string, elementId: string, updates: Partial): string {
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+
+ const el = doc.getElementById(elementId) || doc.querySelector(`[data-name="${elementId}"]`);
+ if (!el) return html;
+
+ if (updates.startTime !== undefined) {
+ el.setAttribute("data-start", String(updates.startTime));
+ if (el.hasAttribute("data-end") && updates.duration !== undefined) {
+ el.setAttribute("data-end", String(updates.startTime + updates.duration));
+ }
+ }
+
+ if (updates.duration !== undefined) {
+ const start = parseFloat(el.getAttribute("data-start") || "0");
+ el.setAttribute("data-end", String(start + updates.duration));
+ el.removeAttribute("data-duration"); // Clean up legacy
+ }
+
+ if (updates.name !== undefined) {
+ el.setAttribute("data-name", updates.name);
+ }
+
+ if (updates.zIndex !== undefined) {
+ el.setAttribute("data-layer", String(updates.zIndex));
+ }
+
+ // Handle media-specific property
+ if ("src" in updates && updates.src !== undefined) {
+ el.setAttribute("src", updates.src);
+ }
+
+ // Handle text-specific properties
+ if ("content" in updates && updates.content !== undefined) {
+ const textEl = el.firstElementChild;
+ if (textEl) {
+ textEl.textContent = updates.content;
+ }
+ }
+
+ if ("color" in updates && updates.color !== undefined) {
+ el.setAttribute("data-color", updates.color);
+ }
+
+ if ("fontSize" in updates && updates.fontSize !== undefined) {
+ el.setAttribute("data-font-size", String(updates.fontSize));
+ }
+
+ if ("textShadow" in updates) {
+ if (updates.textShadow === false) {
+ el.setAttribute("data-text-shadow", "false");
+ } else {
+ el.removeAttribute("data-text-shadow");
+ }
+ }
+
+ // Handle volume property for audio/video
+ if ("volume" in updates) {
+ if (updates.volume !== undefined && updates.volume !== 1) {
+ el.setAttribute("data-volume", String(updates.volume));
+ } else {
+ el.removeAttribute("data-volume");
+ }
+ }
+
+ // Handle hasAudio property for videos
+ if ("hasAudio" in updates) {
+ if (updates.hasAudio === true) {
+ el.setAttribute("data-has-audio", "true");
+ } else {
+ el.removeAttribute("data-has-audio");
+ }
+ }
+
+ return "\n" + doc.documentElement.outerHTML;
+}
+
+export function addElementToHtml(
+ html: string,
+ element: Omit & { id?: string },
+): { html: string; id: string } {
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+
+ // Prefer zoom container, fall back to stage, then container, then body
+ const container =
+ doc.querySelector("#stage-zoom-container") ||
+ doc.querySelector(".container") ||
+ doc.querySelector("#stage") ||
+ doc.body;
+
+ const id = element.id || `element-${Date.now()}`;
+
+ let newEl: Element;
+
+ switch (element.type) {
+ case "video": {
+ const mediaEl = element as TimelineMediaElement;
+ newEl = doc.createElement("video");
+ newEl.setAttribute("muted", "");
+ newEl.setAttribute("playsinline", "");
+ if (mediaEl.src) newEl.setAttribute("src", mediaEl.src);
+ if (mediaEl.volume !== undefined && mediaEl.volume !== 1) {
+ newEl.setAttribute("data-volume", String(mediaEl.volume));
+ }
+ if (mediaEl.hasAudio) {
+ newEl.setAttribute("data-has-audio", "true");
+ }
+ break;
+ }
+ case "image": {
+ const mediaEl = element as TimelineMediaElement;
+ newEl = doc.createElement("img");
+ if (mediaEl.src) newEl.setAttribute("src", mediaEl.src);
+ newEl.setAttribute("alt", element.name);
+ break;
+ }
+ case "audio": {
+ const mediaEl = element as TimelineMediaElement;
+ newEl = doc.createElement("audio");
+ if (mediaEl.src) newEl.setAttribute("src", mediaEl.src);
+ if (mediaEl.volume !== undefined && mediaEl.volume !== 1) {
+ newEl.setAttribute("data-volume", String(mediaEl.volume));
+ }
+ break;
+ }
+ case "text":
+ default: {
+ const textEl = element as TimelineTextElement;
+ newEl = doc.createElement("div");
+ const textContent = doc.createElement("div");
+ textContent.textContent = textEl.content || element.name;
+ newEl.appendChild(textContent);
+ if (textEl.color) {
+ newEl.setAttribute("data-color", textEl.color);
+ }
+ if (textEl.fontSize) {
+ newEl.setAttribute("data-font-size", String(textEl.fontSize));
+ }
+ break;
+ }
+ }
+
+ newEl.id = id;
+ newEl.setAttribute("data-start", String(element.startTime));
+ newEl.setAttribute("data-end", String(element.startTime + element.duration));
+ newEl.setAttribute("data-layer", String(element.zIndex));
+ newEl.setAttribute("data-name", element.name);
+
+ container.appendChild(newEl);
+
+ return {
+ html: "\n" + doc.documentElement.outerHTML,
+ id,
+ };
+}
+
+export function removeElementFromHtml(html: string, elementId: string): string {
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+
+ const el = doc.getElementById(elementId);
+ if (el) {
+ el.remove();
+ }
+
+ return "\n" + doc.documentElement.outerHTML;
+}
+
+export interface CompositionMetadata {
+ compositionId: string | null;
+ compositionDuration: number | null;
+ variables: CompositionVariable[];
+}
+
+export function extractCompositionMetadata(html: string): CompositionMetadata {
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+ const htmlEl = doc.documentElement;
+
+ const compositionId = htmlEl.getAttribute("data-composition-id");
+ const durationStr = htmlEl.getAttribute("data-composition-duration");
+ const compositionDuration = durationStr ? parseFloat(durationStr) : null;
+
+ const variables = parseCompositionVariables(htmlEl);
+
+ return {
+ compositionId,
+ compositionDuration: compositionDuration && isFinite(compositionDuration) ? compositionDuration : null,
+ variables,
+ };
+}
+
+function parseCompositionVariables(htmlEl: Element): CompositionVariable[] {
+ const variablesAttr = htmlEl.getAttribute("data-composition-variables");
+ if (!variablesAttr) {
+ return [];
+ }
+
+ try {
+ const parsed = JSON.parse(variablesAttr);
+ if (!Array.isArray(parsed)) {
+ return [];
+ }
+
+ return parsed.filter((v): v is CompositionVariable => {
+ if (typeof v !== "object" || v === null) return false;
+ if (typeof v.id !== "string" || typeof v.label !== "string") return false;
+ if (!["string", "number", "color", "boolean", "enum"].includes(v.type)) return false;
+
+ switch (v.type) {
+ case "string":
+ return typeof v.default === "string";
+ case "number":
+ return typeof v.default === "number";
+ case "color":
+ return typeof v.default === "string";
+ case "boolean":
+ return typeof v.default === "boolean";
+ case "enum":
+ return typeof v.default === "string" && Array.isArray(v.options);
+ default:
+ return false;
+ }
+ });
+ } catch {
+ return [];
+ }
+}
+
+export function validateCompositionHtml(html: string): ValidationResult {
+ const errors: string[] = [];
+ const warnings: string[] = [];
+
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+ const htmlEl = doc.documentElement;
+
+ const compositionId = htmlEl.getAttribute("data-composition-id");
+ if (!compositionId) {
+ errors.push("Missing data-composition-id attribute on element");
+ }
+
+ const durationStr = htmlEl.getAttribute("data-composition-duration");
+ if (!durationStr) {
+ errors.push("Missing data-composition-duration attribute on element");
+ } else {
+ const duration = parseFloat(durationStr);
+ if (!isFinite(duration) || duration <= 0) {
+ errors.push("data-composition-duration must be a positive finite number");
+ }
+ }
+
+ const stage = doc.getElementById("stage");
+ if (!stage) {
+ errors.push("Missing #stage element");
+ }
+
+ if (/\son\w+\s*=/i.test(html)) {
+ errors.push("Inline event handlers (onclick, onload, etc.) not allowed");
+ }
+
+ if (/javascript\s*:/i.test(html)) {
+ errors.push("javascript: URLs not allowed");
+ }
+
+ const scripts = doc.querySelectorAll("script");
+ if (scripts.length > 2) {
+ warnings.push("Multiple script tags detected - only GSAP CDN and main script expected");
+ }
+
+ const gsapScript = extractGsapScript(doc);
+ if (gsapScript) {
+ const gsapValidation = validateCompositionGsap(gsapScript);
+ errors.push(...gsapValidation.errors);
+ warnings.push(...gsapValidation.warnings);
+ }
+
+ return {
+ valid: errors.length === 0,
+ errors,
+ warnings,
+ };
+}
+
+function extractGsapScript(doc: Document): string | null {
+ const scripts = doc.querySelectorAll("script");
+ for (const script of scripts) {
+ const content = script.textContent || "";
+ if (content.includes("gsap.timeline") || content.includes(".set(") || content.includes(".to(")) {
+ return content;
+ }
+ }
+ return null;
+}
+
+export { CANVAS_DIMENSIONS };
diff --git a/packages/core/src/runtime/README.md b/packages/core/src/runtime/README.md
new file mode 100644
index 000000000..50474311d
--- /dev/null
+++ b/packages/core/src/runtime/README.md
@@ -0,0 +1,58 @@
+# Hyperframe Runtime Engine
+
+This folder owns the runtime that powers preview and producer parity.
+
+## Current Direction
+
+- Runtime source of truth is converging on `hyperframe.ts`.
+- Build produces:
+ - `dist/hyperframe.runtime.iife.js` (browser bootstrap)
+ - `dist/hyperframe.runtime.mjs` (tooling/tests)
+ - `dist/hyperframe.manifest.json` (version + sha256 + artifact map)
+- FE owns iframe runtime injection.
+- BE persists raw generated HTML without injecting runtime scripts.
+- Producer validates pinned runtime checksum from manifest before render.
+
+## Runtime Contract (Stable Surface)
+
+Globals:
+
+- `window.__player`
+- `window.__playerReady`
+- `window.__renderReady`
+- `window.__timelines`
+- `window.__clipManifest`
+
+postMessage:
+
+- parent -> runtime control:
+ - `source: "hf-parent"`
+ - `type: "control"`
+ - actions: `play`, `pause`, `seek`, `set-muted`, `set-playback-rate`, `enable-pick-mode`, `disable-pick-mode`
+- runtime -> parent events:
+ - `source: "hf-preview"`
+ - `type: "state"` and `type: "timeline"`
+
+Determinism baseline:
+
+- `renderSeek` is the producer-canonical seek path.
+- 30fps quantization and readiness gates are correctness requirements.
+
+## Build
+
+```bash
+pnpm -C core build:hyperframes-runtime
+```
+
+## Security Expectations
+
+- Runtime bootstrap URL must be version-pinned and host-allowlisted.
+- Iframe bridge payloads must be schema-validated.
+- Unsafe URL schemes (`javascript:` and unapproved `data:`) are rejected.
+- Fail closed if runtime bootstrap/handshake is not healthy.
+
+## Product Editing Model
+
+- Primary mode: prompt + element picking.
+- Secondary mode: manual precision controls.
+- Avoid timeline-first manual workflows as default product path.
diff --git a/packages/core/src/runtime/adapters/css.test.ts b/packages/core/src/runtime/adapters/css.test.ts
new file mode 100644
index 000000000..c4611c346
--- /dev/null
+++ b/packages/core/src/runtime/adapters/css.test.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createCssAdapter } from "./css";
+
+describe("css adapter", () => {
+ it("has correct name", () => {
+ expect(createCssAdapter().name).toBe("css");
+ });
+
+ it("discover finds elements with CSS animations", () => {
+ const el = document.createElement("div");
+ el.style.animationName = "fadeIn";
+ el.style.animationDuration = "1s";
+ document.body.appendChild(el);
+
+ const adapter = createCssAdapter();
+ adapter.discover();
+ // discover doesn't crash — that's the main assertion
+ document.body.removeChild(el);
+ });
+
+ it("seek sets animationDelay and pauses", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-start", "1");
+ el.style.animationName = "slide";
+ el.style.animationDuration = "2s";
+ document.body.appendChild(el);
+
+ // We need to mock getComputedStyle since jsdom doesn't compute animations
+ const origGetComputedStyle = window.getComputedStyle;
+ vi.spyOn(window, "getComputedStyle").mockImplementation((target) => {
+ const real = origGetComputedStyle(target);
+ return {
+ ...real,
+ animationName: target === el ? "slide" : "none",
+ } as CSSStyleDeclaration;
+ });
+
+ const adapter = createCssAdapter();
+ adapter.discover();
+ adapter.seek({ time: 3 });
+
+ expect(el.style.animationPlayState).toBe("paused");
+ // localTime = max(0, 3 - 1) = 2
+ expect(el.style.animationDelay).toBe("-2s");
+
+ document.body.removeChild(el);
+ vi.restoreAllMocks();
+ });
+
+ it("seek uses resolveStartSeconds when provided", () => {
+ const el = document.createElement("div");
+ el.style.animationName = "bounce";
+ document.body.appendChild(el);
+
+ vi.spyOn(window, "getComputedStyle").mockImplementation(() => {
+ return { animationName: "bounce" } as CSSStyleDeclaration;
+ });
+
+ const adapter = createCssAdapter({ resolveStartSeconds: () => 2 });
+ adapter.discover();
+ adapter.seek({ time: 5 });
+
+ expect(el.style.animationPlayState).toBe("paused");
+ // localTime = max(0, 5 - 2) = 3
+ expect(el.style.animationDelay).toBe("-3s");
+
+ document.body.removeChild(el);
+ vi.restoreAllMocks();
+ });
+
+ it("pause restores base play state", () => {
+ const el = document.createElement("div");
+ el.style.animationName = "spin";
+ el.style.animationPlayState = "running";
+ document.body.appendChild(el);
+
+ vi.spyOn(window, "getComputedStyle").mockImplementation(() => {
+ return { animationName: "spin" } as CSSStyleDeclaration;
+ });
+
+ const adapter = createCssAdapter();
+ adapter.discover();
+ adapter.seek({ time: 1 });
+ expect(el.style.animationPlayState).toBe("paused");
+
+ adapter.pause();
+ expect(el.style.animationPlayState).toBe("running");
+
+ document.body.removeChild(el);
+ vi.restoreAllMocks();
+ });
+
+ it("revert clears entries", () => {
+ const adapter = createCssAdapter();
+ adapter.revert!();
+ // Should not crash when seeking after revert
+ expect(() => adapter.seek({ time: 1 })).not.toThrow();
+ });
+});
diff --git a/packages/core/src/runtime/adapters/css.ts b/packages/core/src/runtime/adapters/css.ts
new file mode 100644
index 000000000..944a9fbf5
--- /dev/null
+++ b/packages/core/src/runtime/adapters/css.ts
@@ -0,0 +1,51 @@
+import type { RuntimeDeterministicAdapter } from "../types";
+
+export function createCssAdapter(params?: {
+ resolveStartSeconds?: (element: Element) => number;
+}): RuntimeDeterministicAdapter {
+ let entries: Array<{
+ el: HTMLElement;
+ baseDelay: string;
+ basePlayState: string;
+ }> = [];
+
+ return {
+ name: "css",
+ discover: () => {
+ entries = [];
+ const all = document.querySelectorAll("*");
+ for (const rawEl of all) {
+ if (!(rawEl instanceof HTMLElement)) continue;
+ const style = window.getComputedStyle(rawEl);
+ if (!style.animationName || style.animationName === "none") continue;
+ entries.push({
+ el: rawEl,
+ baseDelay: rawEl.style.animationDelay || "",
+ basePlayState: rawEl.style.animationPlayState || "",
+ });
+ }
+ },
+ seek: (ctx) => {
+ const time = Number(ctx.time) || 0;
+ for (const entry of entries) {
+ if (!entry.el.isConnected) continue;
+ const start = params?.resolveStartSeconds
+ ? params.resolveStartSeconds(entry.el)
+ : Number.parseFloat(entry.el.getAttribute("data-start") ?? "0") || 0;
+ const localTime = Math.max(0, time - start);
+ entry.el.style.animationPlayState = "paused";
+ entry.el.style.animationDelay = `-${localTime.toFixed(3)}s`;
+ }
+ },
+ pause: () => {
+ for (const entry of entries) {
+ if (!entry.el.isConnected) continue;
+ entry.el.style.animationPlayState = entry.basePlayState || "paused";
+ if (entry.baseDelay) entry.el.style.animationDelay = entry.baseDelay;
+ }
+ },
+ revert: () => {
+ entries = [];
+ },
+ };
+}
diff --git a/packages/core/src/runtime/adapters/gsap.test.ts b/packages/core/src/runtime/adapters/gsap.test.ts
new file mode 100644
index 000000000..3cd8ab30b
--- /dev/null
+++ b/packages/core/src/runtime/adapters/gsap.test.ts
@@ -0,0 +1,78 @@
+import { describe, it, expect, vi } from "vitest";
+import { createGsapAdapter } from "./gsap";
+import type { RuntimeTimelineLike } from "../types";
+
+function createMockTimeline(): RuntimeTimelineLike {
+ return {
+ play: vi.fn(),
+ pause: vi.fn(),
+ seek: vi.fn(),
+ totalTime: vi.fn(),
+ time: vi.fn(() => 0),
+ duration: vi.fn(() => 10),
+ add: vi.fn(),
+ paused: vi.fn(),
+ set: vi.fn(),
+ };
+}
+
+describe("gsap adapter", () => {
+ it("has correct name", () => {
+ const adapter = createGsapAdapter({ getTimeline: () => null });
+ expect(adapter.name).toBe("gsap");
+ });
+
+ it("seek uses totalTime when available", () => {
+ const timeline = createMockTimeline();
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+ adapter.seek({ time: 5 });
+ expect(timeline.pause).toHaveBeenCalled();
+ expect(timeline.totalTime).toHaveBeenCalledWith(5, false);
+ expect(timeline.seek).not.toHaveBeenCalled();
+ });
+
+ it("seek falls back to .seek() when totalTime is missing", () => {
+ const timeline = createMockTimeline();
+ (timeline as Record).totalTime = undefined;
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+ adapter.seek({ time: 3 });
+ expect(timeline.pause).toHaveBeenCalled();
+ expect(timeline.seek).toHaveBeenCalledWith(3, false);
+ });
+
+ it("seek clamps negative time to 0", () => {
+ const timeline = createMockTimeline();
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+ adapter.seek({ time: -5 });
+ expect(timeline.totalTime).toHaveBeenCalledWith(0, false);
+ });
+
+ it("seek handles NaN time", () => {
+ const timeline = createMockTimeline();
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+ adapter.seek({ time: NaN });
+ expect(timeline.totalTime).toHaveBeenCalledWith(0, false);
+ });
+
+ it("seek does nothing without timeline", () => {
+ const adapter = createGsapAdapter({ getTimeline: () => null });
+ expect(() => adapter.seek({ time: 5 })).not.toThrow();
+ });
+
+ it("pause pauses the timeline", () => {
+ const timeline = createMockTimeline();
+ const adapter = createGsapAdapter({ getTimeline: () => timeline });
+ adapter.pause();
+ expect(timeline.pause).toHaveBeenCalled();
+ });
+
+ it("pause does nothing without timeline", () => {
+ const adapter = createGsapAdapter({ getTimeline: () => null });
+ expect(() => adapter.pause()).not.toThrow();
+ });
+
+ it("discover is a no-op", () => {
+ const adapter = createGsapAdapter({ getTimeline: () => null });
+ expect(() => adapter.discover()).not.toThrow();
+ });
+});
diff --git a/packages/core/src/runtime/adapters/gsap.ts b/packages/core/src/runtime/adapters/gsap.ts
new file mode 100644
index 000000000..b21160f8f
--- /dev/null
+++ b/packages/core/src/runtime/adapters/gsap.ts
@@ -0,0 +1,28 @@
+import type { RuntimeDeterministicAdapter, RuntimeTimelineLike } from "../types";
+
+type GsapAdapterDeps = {
+ getTimeline: () => RuntimeTimelineLike | null;
+};
+
+export function createGsapAdapter(deps: GsapAdapterDeps): RuntimeDeterministicAdapter {
+ return {
+ name: "gsap",
+ discover: () => {},
+ seek: (ctx) => {
+ const timeline = deps.getTimeline();
+ if (!timeline) return;
+ timeline.pause();
+ const safeTime = Math.max(0, Number(ctx.time) || 0);
+ if (typeof timeline.totalTime === "function") {
+ timeline.totalTime(safeTime, false);
+ } else {
+ timeline.seek(safeTime, false);
+ }
+ },
+ pause: () => {
+ const timeline = deps.getTimeline();
+ if (!timeline) return;
+ timeline.pause();
+ },
+ };
+}
diff --git a/packages/core/src/runtime/adapters/lottie.test.ts b/packages/core/src/runtime/adapters/lottie.test.ts
new file mode 100644
index 000000000..6c8c12f36
--- /dev/null
+++ b/packages/core/src/runtime/adapters/lottie.test.ts
@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createLottieAdapter } from "./lottie";
+
+const lottieWindow = window as Window & {
+ lottie?: {
+ loadAnimation: (params: unknown) => unknown;
+ getRegisteredAnimations: () => unknown[];
+ };
+ __hfLottie?: unknown[];
+};
+
+function createLottieWebAnim(opts?: { totalFrames?: number; frameRate?: number }) {
+ return {
+ play: vi.fn(),
+ pause: vi.fn(),
+ stop: vi.fn(),
+ goToAndStop: vi.fn(),
+ goToAndPlay: vi.fn(),
+ totalFrames: opts?.totalFrames ?? 120,
+ frameRate: opts?.frameRate ?? 30,
+ };
+}
+
+function createDotLottiePlayer(opts?: { totalFrames?: number; frameRate?: number; duration?: number }) {
+ return {
+ play: vi.fn(),
+ pause: vi.fn(),
+ totalFrames: opts?.totalFrames ?? 60,
+ frameRate: opts?.frameRate ?? 30,
+ duration: opts?.duration ?? 2,
+ setCurrentRawFrameValue: vi.fn(),
+ seek: vi.fn(),
+ };
+}
+
+describe("lottie adapter", () => {
+ beforeEach(() => {
+ delete lottieWindow.lottie;
+ delete lottieWindow.__hfLottie;
+ });
+
+ afterEach(() => {
+ delete lottieWindow.lottie;
+ delete lottieWindow.__hfLottie;
+ });
+
+ it("has correct name", () => {
+ expect(createLottieAdapter().name).toBe("lottie");
+ });
+
+ describe("discover", () => {
+ it("auto-discovers lottie-web animations", () => {
+ const anim = createLottieWebAnim();
+ lottieWindow.lottie = {
+ loadAnimation: vi.fn(),
+ getRegisteredAnimations: () => [anim],
+ };
+ lottieWindow.__hfLottie = [];
+ const adapter = createLottieAdapter();
+ adapter.discover();
+ expect(lottieWindow.__hfLottie).toContain(anim);
+ });
+
+ it("does not duplicate existing animations", () => {
+ const anim = createLottieWebAnim();
+ lottieWindow.lottie = {
+ loadAnimation: vi.fn(),
+ getRegisteredAnimations: () => [anim],
+ };
+ lottieWindow.__hfLottie = [anim];
+ const adapter = createLottieAdapter();
+ adapter.discover();
+ expect(lottieWindow.__hfLottie).toHaveLength(1);
+ });
+
+ it("handles no global lottie", () => {
+ const adapter = createLottieAdapter();
+ expect(() => adapter.discover()).not.toThrow();
+ });
+ });
+
+ describe("seek", () => {
+ it("seeks lottie-web with goToAndStop in ms", () => {
+ const anim = createLottieWebAnim();
+ lottieWindow.__hfLottie = [anim];
+ const adapter = createLottieAdapter();
+ adapter.seek({ time: 2 });
+ expect(anim.goToAndStop).toHaveBeenCalledWith(2000, false);
+ });
+
+ it("seeks dotlottie-web v2 with setCurrentRawFrameValue", () => {
+ const player = createDotLottiePlayer({ totalFrames: 60, frameRate: 30 });
+ lottieWindow.__hfLottie = [player];
+ const adapter = createLottieAdapter();
+ adapter.seek({ time: 1 });
+ // frame = time * fps = 1 * 30 = 30
+ expect(player.setCurrentRawFrameValue).toHaveBeenCalledWith(30);
+ });
+
+ it("clamps frame to totalFrames - 1", () => {
+ const player = createDotLottiePlayer({ totalFrames: 60, frameRate: 30 });
+ lottieWindow.__hfLottie = [player];
+ const adapter = createLottieAdapter();
+ adapter.seek({ time: 10 }); // frame = 300, but totalFrames = 60
+ expect(player.setCurrentRawFrameValue).toHaveBeenCalledWith(59);
+ });
+
+ it("does nothing with no instances", () => {
+ const adapter = createLottieAdapter();
+ expect(() => adapter.seek({ time: 1 })).not.toThrow();
+ });
+
+ it("clamps negative time to 0", () => {
+ const anim = createLottieWebAnim();
+ lottieWindow.__hfLottie = [anim];
+ const adapter = createLottieAdapter();
+ adapter.seek({ time: -5 });
+ expect(anim.goToAndStop).toHaveBeenCalledWith(0, false);
+ });
+ });
+
+ describe("pause", () => {
+ it("pauses lottie-web animation", () => {
+ const anim = createLottieWebAnim();
+ lottieWindow.__hfLottie = [anim];
+ const adapter = createLottieAdapter();
+ adapter.pause();
+ expect(anim.pause).toHaveBeenCalled();
+ });
+
+ it("pauses dotlottie player", () => {
+ const player = createDotLottiePlayer();
+ lottieWindow.__hfLottie = [player];
+ const adapter = createLottieAdapter();
+ adapter.pause();
+ expect(player.pause).toHaveBeenCalled();
+ });
+ });
+
+ describe("play", () => {
+ it("plays lottie-web animation", () => {
+ const anim = createLottieWebAnim();
+ lottieWindow.__hfLottie = [anim];
+ const adapter = createLottieAdapter();
+ adapter.play!();
+ expect(anim.play).toHaveBeenCalled();
+ });
+ });
+
+ describe("revert", () => {
+ it("does not throw", () => {
+ const adapter = createLottieAdapter();
+ expect(() => adapter.revert!()).not.toThrow();
+ });
+ });
+});
diff --git a/packages/core/src/runtime/adapters/lottie.ts b/packages/core/src/runtime/adapters/lottie.ts
new file mode 100644
index 000000000..5870d56d6
--- /dev/null
+++ b/packages/core/src/runtime/adapters/lottie.ts
@@ -0,0 +1,202 @@
+import type { RuntimeDeterministicAdapter } from "../types";
+
+/**
+ * Lottie adapter for HyperFrames
+ *
+ * Supports lottie-web and @lottiefiles/dotlottie-web.
+ *
+ * ## Usage in a composition
+ *
+ * ### lottie-web (classic):
+ * ```html
+ *
+ *
+ *
+ * ```
+ *
+ * ### @lottiefiles/dotlottie-web:
+ * ```html
+ *
+ * ;
+}
diff --git a/packages/core/src/runtime/adapters/three.test.ts b/packages/core/src/runtime/adapters/three.test.ts
new file mode 100644
index 000000000..ac886f889
--- /dev/null
+++ b/packages/core/src/runtime/adapters/three.test.ts
@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createThreeAdapter } from "./three";
+
+const threeWindow = window as Window & { __hfThreeTime?: number };
+
+describe("three adapter", () => {
+ beforeEach(() => {
+ delete threeWindow.__hfThreeTime;
+ });
+
+ it("has correct name", () => {
+ expect(createThreeAdapter().name).toBe("three");
+ });
+
+ it("seek sets __hfThreeTime", () => {
+ const adapter = createThreeAdapter();
+ adapter.seek({ time: 5 });
+ expect(threeWindow.__hfThreeTime).toBe(5);
+ });
+
+ it("seek dispatches hf-seek custom event", () => {
+ const adapter = createThreeAdapter();
+ const handler = vi.fn();
+ window.addEventListener("hf-seek", handler);
+ adapter.seek({ time: 3 });
+ window.removeEventListener("hf-seek", handler);
+ expect(handler).toHaveBeenCalled();
+ const detail = (handler.mock.calls[0][0] as CustomEvent).detail;
+ expect(detail.time).toBe(3);
+ });
+
+ it("seek clamps negative time to 0", () => {
+ const adapter = createThreeAdapter();
+ adapter.seek({ time: -10 });
+ expect(threeWindow.__hfThreeTime).toBe(0);
+ });
+
+ it("pause retains last forced time", () => {
+ const adapter = createThreeAdapter();
+ adapter.seek({ time: 7 });
+ adapter.pause();
+ // Internal state preserved — no crash
+ expect(threeWindow.__hfThreeTime).toBe(7);
+ });
+
+ it("play releases forced time", () => {
+ const adapter = createThreeAdapter();
+ adapter.seek({ time: 7 });
+ adapter.play!();
+ // After play, forced time is released
+ });
+
+ it("revert resets all state", () => {
+ const adapter = createThreeAdapter();
+ adapter.seek({ time: 5 });
+ adapter.revert!();
+ // After revert, forcedTime and lastForcedTime are reset
+ });
+
+ it("discover is a no-op", () => {
+ const adapter = createThreeAdapter();
+ expect(() => adapter.discover()).not.toThrow();
+ });
+});
diff --git a/packages/core/src/runtime/adapters/three.ts b/packages/core/src/runtime/adapters/three.ts
new file mode 100644
index 000000000..49704e50c
--- /dev/null
+++ b/packages/core/src/runtime/adapters/three.ts
@@ -0,0 +1,33 @@
+import type { RuntimeDeterministicAdapter } from "../types";
+
+export function createThreeAdapter(): RuntimeDeterministicAdapter {
+ let forcedTime: number | null = null;
+ let lastForcedTime = 0;
+
+ return {
+ name: "three",
+ discover: () => {},
+ seek: (ctx) => {
+ forcedTime = Math.max(0, Number(ctx.time) || 0);
+ lastForcedTime = forcedTime;
+ window.__hfThreeTime = forcedTime;
+ try {
+ window.dispatchEvent(new CustomEvent("hf-seek", { detail: { time: forcedTime } }));
+ } catch {
+ // ignore custom event failures
+ }
+ },
+ pause: () => {
+ if (forcedTime == null) {
+ forcedTime = Math.max(0, lastForcedTime);
+ }
+ },
+ play: () => {
+ forcedTime = null;
+ },
+ revert: () => {
+ forcedTime = null;
+ lastForcedTime = 0;
+ },
+ };
+}
diff --git a/packages/core/src/runtime/adapters/waapi.test.ts b/packages/core/src/runtime/adapters/waapi.test.ts
new file mode 100644
index 000000000..65b1700e9
--- /dev/null
+++ b/packages/core/src/runtime/adapters/waapi.test.ts
@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createWaapiAdapter } from "./waapi";
+
+describe("waapi adapter", () => {
+ it("has correct name", () => {
+ expect(createWaapiAdapter().name).toBe("waapi");
+ });
+
+ it("seek pauses and sets currentTime on all animations", () => {
+ const mockAnim = { pause: vi.fn(), currentTime: 0 };
+ (document as any).getAnimations = vi.fn(() => [mockAnim]);
+
+ const adapter = createWaapiAdapter();
+ adapter.seek({ time: 2.5 });
+
+ expect(mockAnim.pause).toHaveBeenCalled();
+ expect(mockAnim.currentTime).toBe(2500); // seconds → ms
+
+ delete (document as any).getAnimations;
+ });
+
+ it("seek clamps negative time to 0", () => {
+ const mockAnim = { pause: vi.fn(), currentTime: 0 };
+ (document as any).getAnimations = vi.fn(() => [mockAnim]);
+
+ const adapter = createWaapiAdapter();
+ adapter.seek({ time: -3 });
+
+ expect(mockAnim.currentTime).toBe(0);
+ delete (document as any).getAnimations;
+ });
+
+ it("pause pauses all animations", () => {
+ const mockAnim = { pause: vi.fn(), currentTime: 0 };
+ (document as any).getAnimations = vi.fn(() => [mockAnim]);
+
+ const adapter = createWaapiAdapter();
+ adapter.pause();
+
+ expect(mockAnim.pause).toHaveBeenCalled();
+ delete (document as any).getAnimations;
+ });
+
+ it("handles missing getAnimations API", () => {
+ const original = document.getAnimations;
+ (document as Record).getAnimations = undefined;
+
+ const adapter = createWaapiAdapter();
+ expect(() => adapter.seek({ time: 1 })).not.toThrow();
+ expect(() => adapter.pause()).not.toThrow();
+
+ document.getAnimations = original;
+ });
+
+ it("handles animation that throws on pause", () => {
+ const mockAnim = {
+ pause: vi.fn(() => { throw new Error("invalid state"); }),
+ currentTime: 0,
+ };
+ (document as any).getAnimations = vi.fn(() => [mockAnim]);
+
+ const adapter = createWaapiAdapter();
+ expect(() => adapter.seek({ time: 1 })).not.toThrow();
+
+ delete (document as any).getAnimations;
+ });
+
+ it("discover is a no-op", () => {
+ const adapter = createWaapiAdapter();
+ expect(() => adapter.discover()).not.toThrow();
+ });
+});
diff --git a/packages/core/src/runtime/adapters/waapi.ts b/packages/core/src/runtime/adapters/waapi.ts
new file mode 100644
index 000000000..2df6da072
--- /dev/null
+++ b/packages/core/src/runtime/adapters/waapi.ts
@@ -0,0 +1,30 @@
+import type { RuntimeDeterministicAdapter } from "../types";
+
+export function createWaapiAdapter(): RuntimeDeterministicAdapter {
+ return {
+ name: "waapi",
+ discover: () => {},
+ seek: (ctx) => {
+ if (!document.getAnimations) return;
+ const timeMs = Math.max(0, (Number(ctx.time) || 0) * 1000);
+ for (const animation of document.getAnimations()) {
+ try {
+ animation.pause();
+ animation.currentTime = timeMs;
+ } catch {
+ // ignore animation edge-cases
+ }
+ }
+ },
+ pause: () => {
+ if (!document.getAnimations) return;
+ for (const animation of document.getAnimations()) {
+ try {
+ animation.pause();
+ } catch {
+ // ignore animation edge-cases
+ }
+ }
+ },
+ };
+}
diff --git a/packages/core/src/runtime/analytics.test.ts b/packages/core/src/runtime/analytics.test.ts
new file mode 100644
index 000000000..376e0f345
--- /dev/null
+++ b/packages/core/src/runtime/analytics.test.ts
@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { initRuntimeAnalytics, emitAnalyticsEvent } from "./analytics";
+
+describe("runtime analytics", () => {
+ let postMessage: ReturnType;
+
+ beforeEach(() => {
+ postMessage = vi.fn();
+ // Reset module state by re-init
+ initRuntimeAnalytics(postMessage);
+ });
+
+ it("emits analytics event via postMessage", () => {
+ emitAnalyticsEvent("composition_loaded");
+ expect(postMessage).toHaveBeenCalledWith({
+ source: "hf-preview",
+ type: "analytics",
+ event: "composition_loaded",
+ properties: {},
+ });
+ });
+
+ it("passes properties through", () => {
+ emitAnalyticsEvent("composition_played", { duration: 10, autoplay: true });
+ expect(postMessage).toHaveBeenCalledWith({
+ source: "hf-preview",
+ type: "analytics",
+ event: "composition_played",
+ properties: { duration: 10, autoplay: true },
+ });
+ });
+
+ it("does not throw when postMessage is not set", () => {
+ // Re-init with a function that we'll clear
+ initRuntimeAnalytics(null as unknown as (payload: unknown) => void);
+ expect(() => emitAnalyticsEvent("composition_paused")).not.toThrow();
+ });
+
+ it("does not throw when postMessage throws", () => {
+ postMessage.mockImplementation(() => {
+ throw new Error("channel closed");
+ });
+ expect(() => emitAnalyticsEvent("composition_seeked")).not.toThrow();
+ });
+
+ it("emits all event types", () => {
+ const events = [
+ "composition_loaded",
+ "composition_played",
+ "composition_paused",
+ "composition_seeked",
+ "composition_ended",
+ "element_picked",
+ ] as const;
+ for (const event of events) {
+ emitAnalyticsEvent(event);
+ }
+ expect(postMessage).toHaveBeenCalledTimes(events.length);
+ });
+});
diff --git a/packages/core/src/runtime/analytics.ts b/packages/core/src/runtime/analytics.ts
new file mode 100644
index 000000000..4d313ddb4
--- /dev/null
+++ b/packages/core/src/runtime/analytics.ts
@@ -0,0 +1,66 @@
+/**
+ * Runtime analytics — vendor-agnostic event emission.
+ *
+ * The runtime emits structured events via postMessage. The host application
+ * decides what to do with them: forward to PostHog, Mixpanel, Amplitude,
+ * a custom logger, or nothing at all.
+ *
+ * For session replay: initialize your analytics SDK (e.g. PostHog) only in
+ * the parent app with `recordCrossOriginIframes: true`. No SDK needs to run
+ * inside this iframe.
+ *
+ * ## Host app integration
+ *
+ * ```javascript
+ * window.addEventListener("message", (e) => {
+ * if (e.data?.source !== "hf-preview" || e.data?.type !== "analytics") return;
+ * const { event, properties } = e.data;
+ *
+ * // PostHog:
+ * posthog.capture(event, properties);
+ * // Mixpanel:
+ * mixpanel.track(event, properties);
+ * // Custom:
+ * myLogger.track(event, properties);
+ * });
+ * ```
+ */
+
+export type RuntimeAnalyticsEvent =
+ | "composition_loaded"
+ | "composition_played"
+ | "composition_paused"
+ | "composition_seeked"
+ | "composition_ended"
+ | "element_picked";
+
+export type RuntimeAnalyticsProperties = Record;
+
+// Stored reference to the postRuntimeMessage function, set during init.
+// Avoids a circular import between analytics ↔ bridge.
+let _postMessage: ((payload: unknown) => void) | null = null;
+
+export function initRuntimeAnalytics(postMessage: (payload: unknown) => void): void {
+ _postMessage = postMessage;
+}
+
+/**
+ * Emit an analytics event through the bridge.
+ * The host app receives it via postMessage and forwards to its analytics provider.
+ */
+export function emitAnalyticsEvent(
+ event: RuntimeAnalyticsEvent,
+ properties?: RuntimeAnalyticsProperties,
+): void {
+ if (!_postMessage) return;
+ try {
+ _postMessage({
+ source: "hf-preview",
+ type: "analytics",
+ event,
+ properties: properties ?? {},
+ });
+ } catch {
+ // Never let analytics failures affect the runtime
+ }
+}
diff --git a/packages/core/src/runtime/bridge.test.ts b/packages/core/src/runtime/bridge.test.ts
new file mode 100644
index 000000000..91ddd0120
--- /dev/null
+++ b/packages/core/src/runtime/bridge.test.ts
@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { installRuntimeControlBridge } from "./bridge";
+
+function createMockDeps() {
+ return {
+ onPlay: vi.fn(),
+ onPause: vi.fn(),
+ onSeek: vi.fn(),
+ onSetMuted: vi.fn(),
+ onSetPlaybackRate: vi.fn(),
+ onEnablePickMode: vi.fn(),
+ onDisablePickMode: vi.fn(),
+ };
+}
+
+function makeControlMessage(action: string, extra?: Record) {
+ return new MessageEvent("message", {
+ data: { source: "hf-parent", type: "control", action, ...extra },
+ });
+}
+
+describe("installRuntimeControlBridge", () => {
+ it("dispatches play command", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("play"));
+ expect(deps.onPlay).toHaveBeenCalledOnce();
+ });
+
+ it("dispatches pause command", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("pause"));
+ expect(deps.onPause).toHaveBeenCalledOnce();
+ });
+
+ it("dispatches seek command with frame and mode", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("seek", { frame: 150, seekMode: "drag" }));
+ expect(deps.onSeek).toHaveBeenCalledWith(150, "drag");
+ });
+
+ it("seek defaults frame to 0 and seekMode to commit", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("seek"));
+ expect(deps.onSeek).toHaveBeenCalledWith(0, "commit");
+ });
+
+ it("dispatches set-muted command", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("set-muted", { muted: true }));
+ expect(deps.onSetMuted).toHaveBeenCalledWith(true);
+ });
+
+ it("dispatches set-playback-rate command", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("set-playback-rate", { playbackRate: 2 }));
+ expect(deps.onSetPlaybackRate).toHaveBeenCalledWith(2);
+ });
+
+ it("defaults playbackRate to 1", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("set-playback-rate"));
+ expect(deps.onSetPlaybackRate).toHaveBeenCalledWith(1);
+ });
+
+ it("dispatches enable-pick-mode", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("enable-pick-mode"));
+ expect(deps.onEnablePickMode).toHaveBeenCalledOnce();
+ });
+
+ it("dispatches disable-pick-mode", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(makeControlMessage("disable-pick-mode"));
+ expect(deps.onDisablePickMode).toHaveBeenCalledOnce();
+ });
+
+ it("ignores messages from wrong source", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(new MessageEvent("message", {
+ data: { source: "other", type: "control", action: "play" },
+ }));
+ expect(deps.onPlay).not.toHaveBeenCalled();
+ });
+
+ it("ignores messages with wrong type", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(new MessageEvent("message", {
+ data: { source: "hf-parent", type: "state", action: "play" },
+ }));
+ expect(deps.onPlay).not.toHaveBeenCalled();
+ });
+
+ it("ignores null data", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ handler(new MessageEvent("message", { data: null }));
+ expect(deps.onPlay).not.toHaveBeenCalled();
+ });
+
+ it("handles flash-elements command without crashing", () => {
+ const deps = createMockDeps();
+ const handler = installRuntimeControlBridge(deps);
+ expect(() =>
+ handler(makeControlMessage("flash-elements", { selectors: [".test"], duration: 500 }))
+ ).not.toThrow();
+ });
+});
diff --git a/packages/core/src/runtime/bridge.ts b/packages/core/src/runtime/bridge.ts
new file mode 100644
index 000000000..7afa4a27d
--- /dev/null
+++ b/packages/core/src/runtime/bridge.ts
@@ -0,0 +1,101 @@
+import type { RuntimeBridgeControlMessage, RuntimeOutboundMessage } from "./types";
+
+type BridgeDeps = {
+ onPlay: () => void;
+ onPause: () => void;
+ onSeek: (frame: number, seekMode: "drag" | "commit") => void;
+ onSetMuted: (muted: boolean) => void;
+ onSetPlaybackRate: (rate: number) => void;
+ onEnablePickMode: () => void;
+ onDisablePickMode: () => void;
+};
+
+export function postRuntimeMessage(payload: RuntimeOutboundMessage): void {
+ try {
+ window.parent.postMessage(payload, "*");
+ } catch {
+ // Ignore cross-frame posting failures.
+ }
+}
+
+export function installRuntimeControlBridge(deps: BridgeDeps): (event: MessageEvent) => void {
+ const handler = (event: MessageEvent) => {
+ const data = event.data as Partial | null;
+ if (!data || data.source !== "hf-parent" || data.type !== "control") return;
+ const action = data.action;
+ if (action === "play") {
+ deps.onPlay();
+ return;
+ }
+ if (action === "pause") {
+ deps.onPause();
+ return;
+ }
+ if (action === "seek") {
+ deps.onSeek(Number(data.frame ?? 0), data.seekMode ?? "commit");
+ return;
+ }
+ if (action === "set-muted") {
+ deps.onSetMuted(Boolean(data.muted));
+ return;
+ }
+ if (action === "set-playback-rate") {
+ deps.onSetPlaybackRate(Number(data.playbackRate ?? 1));
+ return;
+ }
+ if (action === "enable-pick-mode") {
+ deps.onEnablePickMode();
+ return;
+ }
+ if (action === "disable-pick-mode") {
+ deps.onDisablePickMode();
+ return;
+ }
+ if (action === "flash-elements") {
+ // Briefly highlight elements — used by the chat-canvas bridge
+ // to show what changed after an agent edit
+ const selectors = (data as Record).selectors as string[] | undefined;
+ const duration = ((data as Record).duration as number) || 800;
+ if (selectors) {
+ flashElements(selectors, duration);
+ }
+ }
+ };
+ window.addEventListener("message", handler);
+ return handler;
+}
+
+/**
+ * Flash elements — briefly highlight them with a blue outline.
+ * Used by the chat-canvas bridge to show what changed after an agent edit.
+ */
+function flashElements(selectors: string[], duration: number): void {
+ if (!document.getElementById("__hf-flash-styles")) {
+ const style = document.createElement("style");
+ style.id = "__hf-flash-styles";
+ style.textContent = `
+ .__hf-flash {
+ outline: 2px solid rgba(59, 130, 246, 0.6) !important;
+ outline-offset: 2px !important;
+ animation: __hf-flash-pulse ${duration}ms ease-out forwards !important;
+ }
+ @keyframes __hf-flash-pulse {
+ 0% { outline-color: rgba(59, 130, 246, 0.8); }
+ 100% { outline-color: transparent; }
+ }
+ `;
+ document.head.appendChild(style);
+ }
+
+ for (const selector of selectors) {
+ try {
+ const els = document.querySelectorAll(selector);
+ els.forEach((el) => {
+ el.classList.add("__hf-flash");
+ setTimeout(() => el.classList.remove("__hf-flash"), duration);
+ });
+ } catch {
+ // Invalid selector — skip
+ }
+ }
+}
diff --git a/packages/core/src/runtime/compositionLoader.test.ts b/packages/core/src/runtime/compositionLoader.test.ts
new file mode 100644
index 000000000..19c8430f9
--- /dev/null
+++ b/packages/core/src/runtime/compositionLoader.test.ts
@@ -0,0 +1,224 @@
+import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
+import { loadExternalCompositions } from "./compositionLoader";
+
+// jsdom doesn't provide CSS.escape
+beforeAll(() => {
+ if (typeof globalThis.CSS === "undefined") {
+ (globalThis as any).CSS = {};
+ }
+ if (typeof CSS.escape !== "function") {
+ CSS.escape = (value: string) => value.replace(/([^\w-])/g, "\\$1");
+ }
+});
+
+describe("loadExternalCompositions", () => {
+ afterEach(() => {
+ document.body.innerHTML = "";
+ document.head.querySelectorAll("style").forEach((s) => s.remove());
+ vi.restoreAllMocks();
+ });
+
+ const defaultParams = {
+ injectedStyles: [] as HTMLStyleElement[],
+ injectedScripts: [] as HTMLScriptElement[],
+ parseDimensionPx: (v: string | null) => (v ? `${v}px` : null),
+ };
+
+ it("does nothing when no composition-src elements exist", async () => {
+ const fetchSpy = vi.spyOn(globalThis, "fetch");
+ await loadExternalCompositions({ ...defaultParams });
+ expect(fetchSpy).not.toHaveBeenCalled();
+ });
+
+ it("fetches and mounts external composition HTML", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/comp.html");
+ host.setAttribute("data-composition-id", "scene-1");
+ document.body.appendChild(host);
+
+ const compositionHtml = `
+
+
+
+ `;
+
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(compositionHtml, { status: 200 })
+ );
+
+ await loadExternalCompositions({ ...defaultParams });
+
+ const mountedParagraph = host.querySelector("p");
+
+ expect(mountedParagraph).toBeTruthy();
+ expect(mountedParagraph?.textContent).toBe("Hello World");
+ });
+
+ it("injects styles into document head", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/comp.html");
+ document.body.appendChild(host);
+
+ const compositionHtml = `
+
+
+ Styled
+
+ `;
+
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(compositionHtml, { status: 200 })
+ );
+
+ const injectedStyles: HTMLStyleElement[] = [];
+ await loadExternalCompositions({
+ ...defaultParams,
+ injectedStyles,
+ });
+
+ expect(injectedStyles.length).toBeGreaterThan(0);
+ });
+
+ it("calls onDiagnostic when fetch fails", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/broken.html");
+ host.setAttribute("data-composition-id", "broken");
+ document.body.appendChild(host);
+
+ vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("Network error"));
+
+ const onDiagnostic = vi.fn();
+ await loadExternalCompositions({
+ ...defaultParams,
+ onDiagnostic,
+ });
+
+ expect(onDiagnostic).toHaveBeenCalledWith(
+ expect.objectContaining({
+ code: "external_composition_load_failed",
+ details: expect.objectContaining({
+ hostCompositionSrc: "https://example.com/broken.html",
+ errorMessage: "Network error",
+ }),
+ })
+ );
+ });
+
+ it("calls onDiagnostic when HTTP response is not ok", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/404.html");
+ document.body.appendChild(host);
+
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response("Not Found", { status: 404 })
+ );
+
+ const onDiagnostic = vi.fn();
+ await loadExternalCompositions({
+ ...defaultParams,
+ onDiagnostic,
+ });
+
+ expect(onDiagnostic).toHaveBeenCalledWith(
+ expect.objectContaining({
+ code: "external_composition_load_failed",
+ })
+ );
+ });
+
+ it("uses local template when available", async () => {
+ const template = document.createElement("template");
+ template.id = "local-comp-template";
+ template.innerHTML = "From template
";
+ document.body.appendChild(template);
+
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/comp.html");
+ host.setAttribute("data-composition-id", "local-comp");
+ document.body.appendChild(host);
+
+ const fetchSpy = vi.spyOn(globalThis, "fetch");
+
+ await loadExternalCompositions({ ...defaultParams });
+
+ // Should use local template and not fetch
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(host.querySelector("p")?.textContent).toBe("From template");
+ });
+
+ it("skips hosts without data-composition-src value", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "");
+ document.body.appendChild(host);
+
+ const fetchSpy = vi.spyOn(globalThis, "fetch");
+ await loadExternalCompositions({ ...defaultParams });
+ expect(fetchSpy).not.toHaveBeenCalled();
+ });
+
+ it("clears host content before mounting", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/comp.html");
+ host.innerHTML = "Old content ";
+ document.body.appendChild(host);
+
+ const compositionHtml = `New
`;
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(compositionHtml, { status: 200 })
+ );
+
+ await loadExternalCompositions({ ...defaultParams });
+ expect(host.querySelector("span")).toBeNull();
+ });
+
+ it("handles inline scripts", async () => {
+ const host = document.createElement("div");
+ host.setAttribute("data-composition-src", "https://example.com/comp.html");
+ document.body.appendChild(host);
+
+ // Only inline scripts (no external src) to avoid waitForExternalScriptLoad timeout
+ const compositionHtml = `
+
+
+ With inline script
+
+ `;
+
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(
+ new Response(compositionHtml, { status: 200 })
+ );
+
+ const injectedScripts: HTMLScriptElement[] = [];
+ await loadExternalCompositions({
+ ...defaultParams,
+ injectedScripts,
+ });
+
+ expect(injectedScripts.length).toBeGreaterThan(0);
+ expect(injectedScripts[0].textContent).toContain("console.log");
+ });
+
+ it("handles multiple compositions in parallel", async () => {
+ const host1 = document.createElement("div");
+ host1.setAttribute("data-composition-src", "https://example.com/a.html");
+ document.body.appendChild(host1);
+
+ const host2 = document.createElement("div");
+ host2.setAttribute("data-composition-src", "https://example.com/b.html");
+ document.body.appendChild(host2);
+
+ vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+ const url = typeof input === "string" ? input : (input as Request).url;
+ if (url.includes("a.html")) {
+ return new Response("A
", { status: 200 });
+ }
+ return new Response("B
", { status: 200 });
+ });
+
+ await loadExternalCompositions({ ...defaultParams });
+ expect(host1.querySelector("p")?.textContent).toBe("A");
+ expect(host2.querySelector("p")?.textContent).toBe("B");
+ });
+});
diff --git a/packages/core/src/runtime/compositionLoader.ts b/packages/core/src/runtime/compositionLoader.ts
new file mode 100644
index 000000000..776f2dafe
--- /dev/null
+++ b/packages/core/src/runtime/compositionLoader.ts
@@ -0,0 +1,267 @@
+type LoadExternalCompositionsParams = {
+ injectedStyles: HTMLStyleElement[];
+ injectedScripts: HTMLScriptElement[];
+ parseDimensionPx: (value: string | null) => string | null;
+ onDiagnostic?: (payload: {
+ code: string;
+ details: Record;
+ }) => void;
+};
+
+type PendingScript =
+ | {
+ kind: "inline";
+ content: string;
+ type: string;
+ }
+ | {
+ kind: "external";
+ src: string;
+ type: string;
+ };
+
+const EXTERNAL_SCRIPT_LOAD_TIMEOUT_MS = 8000;
+const BARE_RELATIVE_PATH_RE = /^(?![a-zA-Z][a-zA-Z\d+\-.]*:)(?!\/\/)(?!\/)(?!\.\.?\/).+/;
+
+const waitForExternalScriptLoad = (
+ scriptEl: HTMLScriptElement,
+): Promise<{ status: "load" | "error" | "timeout"; elapsedMs: number }> =>
+ new Promise((resolve) => {
+ let settled = false;
+ const startedAt = Date.now();
+ let timeoutId: number | null = null;
+ const settle = (status: "load" | "error" | "timeout") => {
+ if (settled) return;
+ settled = true;
+ if (timeoutId != null) {
+ window.clearTimeout(timeoutId);
+ }
+ resolve({
+ status,
+ elapsedMs: Math.max(0, Date.now() - startedAt),
+ });
+ };
+ scriptEl.addEventListener("load", () => settle("load"), { once: true });
+ scriptEl.addEventListener("error", () => settle("error"), { once: true });
+ timeoutId = window.setTimeout(() => settle("timeout"), EXTERNAL_SCRIPT_LOAD_TIMEOUT_MS);
+ });
+
+function resetCompositionHost(host: Element) {
+ while (host.firstChild) {
+ host.removeChild(host.firstChild);
+ }
+ host.textContent = "";
+}
+
+function resolveScriptSourceUrl(scriptSrc: string, compositionUrl: URL | null): string {
+ const trimmedSrc = scriptSrc.trim();
+ if (!trimmedSrc) return scriptSrc;
+ try {
+ if (BARE_RELATIVE_PATH_RE.test(trimmedSrc)) {
+ // Composition payloads may use root-relative semantics without a leading slash.
+ return new URL(trimmedSrc, document.baseURI).toString();
+ }
+ if (compositionUrl) {
+ return new URL(trimmedSrc, compositionUrl).toString();
+ }
+ return new URL(trimmedSrc, document.baseURI).toString();
+ } catch {
+ return scriptSrc;
+ }
+}
+
+async function mountCompositionContent(params: {
+ host: Element;
+ hostCompositionId: string | null;
+ hostCompositionSrc: string;
+ sourceNode: ParentNode;
+ hasTemplate: boolean;
+ fallbackBodyInnerHtml: string;
+ compositionUrl: URL | null;
+ injectedStyles: HTMLStyleElement[];
+ injectedScripts: HTMLScriptElement[];
+ parseDimensionPx: (value: string | null) => string | null;
+ onDiagnostic?: (payload: {
+ code: string;
+ details: Record;
+ }) => void;
+}): Promise {
+ let innerRoot: Element | null = null;
+ if (params.hostCompositionId) {
+ const candidateRoots = Array.from(params.sourceNode.querySelectorAll("[data-composition-id]"));
+ innerRoot =
+ candidateRoots.find((candidate) => candidate.getAttribute("data-composition-id") === params.hostCompositionId) ??
+ null;
+ }
+ const contentNode = innerRoot ?? params.sourceNode;
+
+ const styles = Array.from(contentNode.querySelectorAll("style"));
+ for (const style of styles) {
+ const clonedStyle = style.cloneNode(true);
+ if (!(clonedStyle instanceof HTMLStyleElement)) continue;
+ document.head.appendChild(clonedStyle);
+ params.injectedStyles.push(clonedStyle);
+ }
+
+ const scripts = Array.from(contentNode.querySelectorAll("script"));
+ const scriptPayloads: PendingScript[] = [];
+ for (const script of scripts) {
+ const scriptType = script.getAttribute("type")?.trim() ?? "";
+ const scriptSrc = script.getAttribute("src")?.trim() ?? "";
+ if (scriptSrc) {
+ const resolvedSrc = resolveScriptSourceUrl(scriptSrc, params.compositionUrl);
+ scriptPayloads.push({
+ kind: "external",
+ src: resolvedSrc,
+ type: scriptType,
+ });
+ } else {
+ const scriptText = script.textContent?.trim() ?? "";
+ if (scriptText) {
+ scriptPayloads.push({
+ kind: "inline",
+ content: scriptText,
+ type: scriptType,
+ });
+ }
+ }
+ script.parentNode?.removeChild(script);
+ }
+ const remainingStyles = Array.from(contentNode.querySelectorAll("style"));
+ for (const style of remainingStyles) {
+ style.parentNode?.removeChild(style);
+ }
+
+ if (innerRoot) {
+ const imported = document.importNode(innerRoot, true) as HTMLElement;
+ const widthRaw = innerRoot.getAttribute("data-width");
+ const heightRaw = innerRoot.getAttribute("data-height");
+ const widthPx = params.parseDimensionPx(widthRaw);
+ const heightPx = params.parseDimensionPx(heightRaw);
+ imported.style.position = "relative";
+ imported.style.width = widthPx || "100%";
+ imported.style.height = heightPx || "100%";
+ if (widthPx) imported.style.setProperty("--comp-width", widthPx);
+ if (heightPx) imported.style.setProperty("--comp-height", heightPx);
+ if (widthRaw) params.host.setAttribute("data-width", widthRaw);
+ if (heightRaw) params.host.setAttribute("data-height", heightRaw);
+ if (widthPx && params.host instanceof HTMLElement) params.host.style.width = widthPx;
+ if (heightPx && params.host instanceof HTMLElement) params.host.style.height = heightPx;
+ params.host.appendChild(imported);
+ } else if (params.hasTemplate) {
+ params.host.appendChild(document.importNode(contentNode, true));
+ } else {
+ params.host.innerHTML = params.fallbackBodyInnerHtml;
+ }
+
+ for (const scriptPayload of scriptPayloads) {
+ const injectedScript = document.createElement("script");
+ if (scriptPayload.type) {
+ injectedScript.type = scriptPayload.type;
+ }
+ // Preserve deterministic script execution order across injected composition scripts.
+ injectedScript.async = false;
+ if (scriptPayload.kind === "external") {
+ injectedScript.src = scriptPayload.src;
+ } else if (scriptPayload.type.toLowerCase() === "module") {
+ injectedScript.textContent = scriptPayload.content;
+ } else {
+ injectedScript.textContent = `(function(){${scriptPayload.content}})();`;
+ }
+ document.body.appendChild(injectedScript);
+ params.injectedScripts.push(injectedScript);
+ if (scriptPayload.kind === "external") {
+ const loadResult = await waitForExternalScriptLoad(injectedScript);
+ if (loadResult.status !== "load") {
+ params.onDiagnostic?.({
+ code: "external_composition_script_load_issue",
+ details: {
+ hostCompositionId: params.hostCompositionId,
+ hostCompositionSrc: params.hostCompositionSrc,
+ resolvedScriptSrc: scriptPayload.src,
+ loadStatus: loadResult.status,
+ elapsedMs: loadResult.elapsedMs,
+ },
+ });
+ }
+ }
+ }
+}
+
+export async function loadExternalCompositions(params: LoadExternalCompositionsParams): Promise {
+ const hosts = Array.from(document.querySelectorAll("[data-composition-src]"));
+ if (hosts.length === 0) return;
+
+ await Promise.all(
+ hosts.map(async (host) => {
+ const src = host.getAttribute("data-composition-src");
+ if (!src) return;
+ let compositionUrl: URL | null = null;
+ try {
+ compositionUrl = new URL(src, document.baseURI);
+ } catch {
+ compositionUrl = null;
+ }
+ resetCompositionHost(host);
+ try {
+ const hostCompositionId = host.getAttribute("data-composition-id");
+ const localTemplate =
+ hostCompositionId != null
+ ? document.querySelector(`template#${CSS.escape(hostCompositionId)}-template`)
+ : null;
+ if (localTemplate) {
+ await mountCompositionContent({
+ host,
+ hostCompositionId,
+ hostCompositionSrc: src,
+ sourceNode: localTemplate.content,
+ hasTemplate: true,
+ fallbackBodyInnerHtml: "",
+ compositionUrl,
+ injectedStyles: params.injectedStyles,
+ injectedScripts: params.injectedScripts,
+ parseDimensionPx: params.parseDimensionPx,
+ onDiagnostic: params.onDiagnostic,
+ });
+ return;
+ }
+ const response = await fetch(src);
+ if (!response.ok) {
+ throw new Error(`HTTP ${response.status}`);
+ }
+ const html = await response.text();
+ const parser = new DOMParser();
+ const doc = parser.parseFromString(html, "text/html");
+ const template =
+ (hostCompositionId
+ ? doc.querySelector(`template#${CSS.escape(hostCompositionId)}-template`)
+ : null) ?? doc.querySelector("template");
+ const sourceNode = template ? template.content : doc.body;
+ await mountCompositionContent({
+ host,
+ hostCompositionId,
+ hostCompositionSrc: src,
+ sourceNode,
+ hasTemplate: Boolean(template),
+ fallbackBodyInnerHtml: doc.body.innerHTML,
+ compositionUrl,
+ injectedStyles: params.injectedStyles,
+ injectedScripts: params.injectedScripts,
+ parseDimensionPx: params.parseDimensionPx,
+ onDiagnostic: params.onDiagnostic,
+ });
+ } catch (error) {
+ params.onDiagnostic?.({
+ code: "external_composition_load_failed",
+ details: {
+ hostCompositionId: host.getAttribute("data-composition-id"),
+ hostCompositionSrc: src,
+ errorMessage: error instanceof Error ? error.message : "unknown_error",
+ },
+ });
+ // Keep host empty on load failures to avoid rendering escaped fallback HTML.
+ resetCompositionHost(host);
+ }
+ }),
+ );
+}
diff --git a/packages/core/src/runtime/entry.ts b/packages/core/src/runtime/entry.ts
new file mode 100644
index 000000000..f71c9effe
--- /dev/null
+++ b/packages/core/src/runtime/entry.ts
@@ -0,0 +1,24 @@
+import { initSandboxRuntimeModular } from "./init";
+
+type HyperframeWindow = Window & {
+ __hyperframeRuntimeBootstrapped?: boolean;
+};
+
+// Inline composition scripts can run before DOMContentLoaded.
+// Ensure timeline registry exists at script evaluation time.
+(window as HyperframeWindow).__timelines = (window as HyperframeWindow).__timelines || {};
+
+function bootstrapHyperframeRuntime(): void {
+ const win = window as HyperframeWindow;
+ if (win.__hyperframeRuntimeBootstrapped) {
+ return;
+ }
+ win.__hyperframeRuntimeBootstrapped = true;
+ initSandboxRuntimeModular();
+}
+
+if (document.readyState === "loading") {
+ document.addEventListener("DOMContentLoaded", bootstrapHyperframeRuntime, { once: true });
+} else {
+ bootstrapHyperframeRuntime();
+}
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
new file mode 100644
index 000000000..71f18f19d
--- /dev/null
+++ b/packages/core/src/runtime/init.ts
@@ -0,0 +1,1422 @@
+import { installRuntimeControlBridge, postRuntimeMessage } from "./bridge";
+import { initRuntimeAnalytics, emitAnalyticsEvent } from "./analytics";
+import { createCssAdapter } from "./adapters/css";
+import { createGsapAdapter } from "./adapters/gsap";
+import { createLottieAdapter } from "./adapters/lottie";
+import { createThreeAdapter } from "./adapters/three";
+import { createWaapiAdapter } from "./adapters/waapi";
+import { refreshRuntimeMediaCache, syncRuntimeMedia } from "./media";
+import { createPickerModule } from "./picker";
+import { createRuntimePlayer } from "./player";
+import { createRuntimeState } from "./state";
+import { collectRuntimeTimelinePayload } from "./timeline";
+import { createRuntimeStartTimeResolver } from "./startResolver";
+import { loadExternalCompositions } from "./compositionLoader";
+import type { RuntimeDeterministicAdapter, RuntimeJson, RuntimeTimelineLike } from "./types";
+import type { PlayerAPI } from "../core.types";
+
+export function initSandboxRuntimeModular(): void {
+ const state = createRuntimeState();
+ const runtimeWindow = window as Window & {
+ __hfRuntimeTeardown?: (() => void) | null;
+ };
+ let runtimeErrorListener: ((event: ErrorEvent) => void) | null = null;
+ let runtimeUnhandledRejectionListener: ((event: PromiseRejectionEvent) => void) | null = null;
+ const runtimeCleanupCallbacks: Array<() => void> = [];
+ const postedDiagnosticKeys = new Set();
+ let rootStageDiagnosticRafId: number | null = null;
+ if (typeof runtimeWindow.__hfRuntimeTeardown === "function") {
+ try {
+ runtimeWindow.__hfRuntimeTeardown();
+ } catch {
+ // keep runtime resilient across reinits
+ }
+ }
+ window.__timelines = window.__timelines || {};
+ const registerRuntimeCleanup = (callback: () => void) => {
+ runtimeCleanupCallbacks.push(callback);
+ };
+ const postRuntimeDiagnosticOnce = (code: string, details: Record, dedupeKey?: string) => {
+ const key = dedupeKey ?? `${code}:${JSON.stringify(details)}`;
+ if (postedDiagnosticKeys.has(key)) {
+ return;
+ }
+ postedDiagnosticKeys.add(key);
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code,
+ details,
+ });
+ };
+ const createPlayerApiCompat = (basePlayer: {
+ _timeline: RuntimeTimelineLike | null;
+ play: () => void;
+ pause: () => void;
+ seek: (timeSeconds: number) => void;
+ getTime: () => number;
+ getDuration: () => number;
+ isPlaying: () => boolean;
+ renderSeek: (timeSeconds: number) => void;
+ }): PlayerAPI => {
+ const defaultStageZoom: ReturnType = {
+ scale: 1,
+ focusX: 960,
+ focusY: 540,
+ };
+ const emptyStageZoomKeyframes: ReturnType = [];
+ const emptyVisibleElements: ReturnType = [];
+ const defaultRenderState: ReturnType = {
+ time: basePlayer.getTime(),
+ duration: basePlayer.getDuration(),
+ isPlaying: basePlayer.isPlaying(),
+ renderMode: false,
+ timelineDirty: false,
+ };
+ return {
+ play: basePlayer.play,
+ pause: basePlayer.pause,
+ seek: basePlayer.seek,
+ getTime: basePlayer.getTime,
+ getDuration: basePlayer.getDuration,
+ isPlaying: basePlayer.isPlaying,
+ getMainTimeline: () => null,
+ getElementBounds: () => {},
+ getElementsAtPoint: () => {},
+ setElementPosition: () => {},
+ previewElementPosition: () => {},
+ setElementKeyframes: () => {},
+ setElementScale: () => {},
+ setElementFontSize: () => {},
+ setElementTextContent: () => {},
+ setElementTextColor: () => {},
+ setElementTextShadow: () => {},
+ setElementTextFontWeight: () => {},
+ setElementTextFontFamily: () => {},
+ setElementTextOutline: () => {},
+ setElementTextHighlight: () => {},
+ setElementVolume: () => {},
+ setStageZoom: () => {},
+ getStageZoom: () => defaultStageZoom,
+ setStageZoomKeyframes: () => {},
+ getStageZoomKeyframes: () => emptyStageZoomKeyframes,
+ addElement: () => false,
+ removeElement: () => false,
+ updateElementTiming: () => false,
+ setElementTiming: () => {},
+ updateElementSrc: () => false,
+ updateElementLayer: () => false,
+ updateElementBasePosition: () => false,
+ markTimelineDirty: () => {},
+ isTimelineDirty: () => false,
+ rebuildTimeline: () => {},
+ ensureTimeline: () => {},
+ enableRenderMode: () => {},
+ disableRenderMode: () => {},
+ renderSeek: basePlayer.renderSeek,
+ getElementVisibility: () => ({ visible: false }),
+ getVisibleElements: () => emptyVisibleElements,
+ getRenderState: () => ({
+ ...defaultRenderState,
+ time: basePlayer.getTime(),
+ duration: basePlayer.getDuration(),
+ isPlaying: basePlayer.isPlaying(),
+ }),
+ };
+ };
+
+ const MIN_VALID_TIMELINE_DURATION_SECONDS = 1 / 60;
+ const TIMELINE_FLOOR_COVERAGE_RATIO = 0.75;
+ const LOOP_WRAP_PREVIOUS_TIME_THRESHOLD_SECONDS = 0.75;
+ const LOOP_WRAP_CURRENT_TIME_THRESHOLD_SECONDS = 0.35;
+ const LOOP_GUARD_SEEK_GRACE_PERIOD_MS = 900;
+ const LOOP_GUARD_CONSECUTIVE_WRAP_THRESHOLD = 3;
+ const PLAY_REBIND_HOLD_SECONDS = 2;
+ const METADATA_REBIND_MIN_DURATION_GAIN_SECONDS = 0.05;
+ const METADATA_REBIND_DEBOUNCE_MS = 100;
+ const MAX_DIAGNOSTIC_MESSAGE_LENGTH = 240;
+
+ const normalizeDiagnosticMessage = (value: unknown): string => {
+ if (value instanceof Error) {
+ return value.message || String(value);
+ }
+ if (typeof value === "string") {
+ return value;
+ }
+ try {
+ return JSON.stringify(value);
+ } catch {
+ return String(value ?? "");
+ }
+ };
+
+ const classifyRuntimeScriptFailure = (
+ rawMessage: string,
+ ): {
+ code: string;
+ category: string;
+ } => {
+ const message = rawMessage.toLowerCase();
+ if (message.includes("cannot read properties of null") || message.includes("cannot set properties of null")) {
+ return { code: "runtime_null_dom_access", category: "dom-null-access" };
+ }
+ if (message.includes("failed to execute 'queryselector'")) {
+ return { code: "runtime_invalid_selector", category: "selector-invalid" };
+ }
+ if (message.includes("is not defined")) {
+ return { code: "runtime_reference_missing", category: "reference-missing" };
+ }
+ return { code: "runtime_script_error", category: "script-error" };
+ };
+
+ const parseDimensionPx = (value: string | null): string | null => {
+ if (value == null || value.trim() === "") return null;
+ const parsed = Number.parseFloat(value);
+ if (!Number.isFinite(parsed) || parsed <= 0) return null;
+ return `${parsed}px`;
+ };
+
+ const resolveRootCompositionElement = (): HTMLElement | null => {
+ const mainComp = document.getElementById("main-comp");
+ if (mainComp instanceof HTMLElement && mainComp.hasAttribute("data-composition-id")) {
+ return mainComp;
+ }
+ const explicitRoot = document.querySelector('[data-composition-id][data-root="true"]');
+ if (explicitRoot instanceof HTMLElement) {
+ return explicitRoot;
+ }
+ const compositionNodes = Array.from(document.querySelectorAll("[data-composition-id]")) as HTMLElement[];
+ if (compositionNodes.length === 0) return null;
+ return (
+ compositionNodes.find((node) => !node.parentElement?.closest("[data-composition-id]")) ?? compositionNodes[0]
+ );
+ };
+
+ const applyCompositionSizing = () => {
+ const rootEl = resolveRootCompositionElement();
+ if (!rootEl) return;
+ const forcedWidth = parseDimensionPx(rootEl.getAttribute("data-width"));
+ const forcedHeight = parseDimensionPx(rootEl.getAttribute("data-height"));
+ if (forcedWidth) rootEl.style.width = forcedWidth;
+ if (forcedHeight) rootEl.style.height = forcedHeight;
+ if (forcedWidth) rootEl.style.setProperty("--comp-width", forcedWidth);
+ if (forcedHeight) rootEl.style.setProperty("--comp-height", forcedHeight);
+ };
+
+ const sanitizeCompositionDurationAttributes = () => {
+ const rootEl = resolveRootCompositionElement();
+ const compositionNodes = Array.from(
+ document.querySelectorAll("[data-composition-id][data-duration]"),
+ ) as HTMLElement[];
+ for (const node of compositionNodes) {
+ // Preserve explicit root duration so timeline payload can distinguish
+ // authored finite duration from loop-inflated timeline duration.
+ if (rootEl && node === rootEl) continue;
+ // Non-root compositions derive duration from timeline.
+ node.removeAttribute("data-duration");
+ }
+ };
+
+ const applyClipLayout = () => {
+ const rootEl = resolveRootCompositionElement();
+ if (!rootEl) return;
+ if (!rootEl.style.position) {
+ rootEl.style.position = "relative";
+ }
+ rootEl.style.overflow = "hidden";
+ const rootWidth = parseDimensionPx(rootEl.getAttribute("data-width"));
+ const rootHeight = parseDimensionPx(rootEl.getAttribute("data-height"));
+ if (rootWidth) rootEl.style.width = rootWidth;
+ if (rootHeight) rootEl.style.height = rootHeight;
+ const children = Array.from(rootEl.children) as HTMLElement[];
+ for (const el of children) {
+ const tag = el.tagName.toLowerCase();
+ if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") continue;
+ if (!el.hasAttribute("data-start")) continue;
+ const hasLegacyAnchoredDefaults =
+ (el.style.top === "0px" || el.style.top === "0") &&
+ (el.style.left === "0px" || el.style.left === "0") &&
+ el.style.width === "100%" &&
+ el.style.height === "100%";
+ const hasCenteringTransform = /translate\(\s*-50%\s*,\s*-50%\s*\)/.test(el.style.transform);
+ if (
+ hasLegacyAnchoredDefaults &&
+ hasCenteringTransform &&
+ !el.hasAttribute("data-width") &&
+ !el.hasAttribute("data-height")
+ ) {
+ const previousTop = el.style.top;
+ const previousLeft = el.style.left;
+ const previousWidth = el.style.width;
+ const previousHeight = el.style.height;
+ el.style.top = "";
+ el.style.left = "";
+ el.style.width = "";
+ el.style.height = "";
+ const clearedComputed = window.getComputedStyle(el);
+ const cssProvidesClipLayout =
+ clearedComputed.top !== "auto" ||
+ clearedComputed.bottom !== "auto" ||
+ clearedComputed.left !== "auto" ||
+ clearedComputed.right !== "auto" ||
+ clearedComputed.width !== "0px" ||
+ clearedComputed.height !== "0px";
+ if (!cssProvidesClipLayout) {
+ el.style.top = previousTop;
+ el.style.left = previousLeft;
+ el.style.width = previousWidth;
+ el.style.height = previousHeight;
+ }
+ }
+ const computed = window.getComputedStyle(el);
+ const computedPosition = computed.position;
+ // Root-level timed clips should stack in the same viewport layer.
+ // Relative positioning keeps clips in document flow and can push later
+ // compositions below the viewport (eg. checkerboard-style overlays).
+ const shouldForceAbsolute = computedPosition !== "absolute" && computedPosition !== "fixed";
+ if (shouldForceAbsolute) {
+ el.style.position = "absolute";
+ }
+ const hasExplicitVerticalAnchor =
+ Boolean(el.style.top) || Boolean(el.style.bottom) || computed.top !== "auto" || computed.bottom !== "auto";
+ if (!hasExplicitVerticalAnchor) {
+ el.style.top = "0";
+ }
+ const hasExplicitHorizontalAnchor =
+ Boolean(el.style.left) || Boolean(el.style.right) || computed.left !== "auto" || computed.right !== "auto";
+ if (!hasExplicitHorizontalAnchor) {
+ el.style.left = "0";
+ }
+ if (tag !== "audio") {
+ const forcedWidth = parseDimensionPx(el.getAttribute("data-width"));
+ const forcedHeight = parseDimensionPx(el.getAttribute("data-height"));
+ const hasMeaningfulComputedWidth = computed.width !== "0px" && computed.width !== "auto";
+ const hasMeaningfulComputedHeight = computed.height !== "0px" && computed.height !== "auto";
+ if (forcedWidth) {
+ if (!el.style.width && !hasMeaningfulComputedWidth) {
+ el.style.width = forcedWidth;
+ }
+ } else if (!el.style.width && computed.width === "0px") {
+ el.style.width = "100%";
+ }
+ if (forcedHeight) {
+ if (!el.style.height && !hasMeaningfulComputedHeight) {
+ el.style.height = forcedHeight;
+ }
+ } else if (!el.style.height && computed.height === "0px") {
+ el.style.height = "100%";
+ }
+ }
+ }
+ };
+
+ const resolveStartForElement = (element: Element, fallback = 0): number => {
+ const resolver = createRuntimeStartTimeResolver({
+ timelineRegistry: (window.__timelines ?? {}) as Record,
+ });
+ return resolver.resolveStartForElement(element, fallback);
+ };
+
+ const resolveDurationForElement = (element: Element): number | null => {
+ const resolver = createRuntimeStartTimeResolver({
+ timelineRegistry: (window.__timelines ?? {}) as Record,
+ });
+ return resolver.resolveDurationForElement(element);
+ };
+ let externalCompositionsReady = !document.querySelector("[data-composition-src]");
+
+ const getTimelineDurationSeconds = (timeline: RuntimeTimelineLike | null): number | null => {
+ if (!timeline || typeof timeline.duration !== "function") return null;
+ try {
+ const raw = Number(timeline.duration());
+ if (!Number.isFinite(raw)) return null;
+ return Math.max(0, raw);
+ } catch {
+ return null;
+ }
+ };
+
+ const isUsableTimelineDuration = (durationSeconds: number | null): durationSeconds is number =>
+ typeof durationSeconds === "number" &&
+ Number.isFinite(durationSeconds) &&
+ durationSeconds > MIN_VALID_TIMELINE_DURATION_SECONDS;
+
+ type TimelineResolution = {
+ timeline: RuntimeTimelineLike | null;
+ selectedTimelineIds?: string[];
+ selectedDurationSeconds?: number | null;
+ mediaDurationFloorSeconds?: number | null;
+ diagnostics?: {
+ code: string;
+ details: Record;
+ };
+ };
+
+ const resolveMediaElementDurationSeconds = (node: HTMLMediaElement): number | null => {
+ const declaredDuration = Number(node.getAttribute("data-duration"));
+ if (Number.isFinite(declaredDuration) && declaredDuration > 0) {
+ return declaredDuration;
+ }
+ const playbackStart = Number(
+ node.getAttribute("data-playback-start") ?? node.getAttribute("data-media-start") ?? "0",
+ );
+ const safePlaybackStart = Number.isFinite(playbackStart) ? Math.max(0, playbackStart) : 0;
+ if (Number.isFinite(node.duration) && node.duration > safePlaybackStart) {
+ return Math.max(0, node.duration - safePlaybackStart);
+ }
+ return null;
+ };
+
+ const resolveMediaWindowDurationSeconds = (): number | null => {
+ const mediaNodes = Array.from(
+ document.querySelectorAll("video[data-start], audio[data-start]"),
+ ) as HTMLMediaElement[];
+ if (mediaNodes.length === 0) return null;
+ let maxWindowEndSeconds = 0;
+ for (const node of mediaNodes) {
+ const start = resolveStartForElement(node, 0);
+ if (!Number.isFinite(start)) continue;
+ const duration = resolveMediaElementDurationSeconds(node);
+ if (duration == null || duration <= MIN_VALID_TIMELINE_DURATION_SECONDS) continue;
+ maxWindowEndSeconds = Math.max(maxWindowEndSeconds, Math.max(0, start) + duration);
+ }
+ return maxWindowEndSeconds > MIN_VALID_TIMELINE_DURATION_SECONDS ? maxWindowEndSeconds : null;
+ };
+
+ const resolveMediaDurationFloorSeconds = (): number | null => {
+ const mediaWindowDuration = resolveMediaWindowDurationSeconds();
+ if (
+ typeof mediaWindowDuration !== "number" ||
+ !Number.isFinite(mediaWindowDuration) ||
+ mediaWindowDuration <= MIN_VALID_TIMELINE_DURATION_SECONDS
+ ) {
+ return null;
+ }
+ return mediaWindowDuration;
+ };
+
+ const resolveMinCandidateDurationSeconds = (mediaDurationFloorSeconds: number | null): number => {
+ if (!isUsableTimelineDuration(mediaDurationFloorSeconds)) {
+ return MIN_VALID_TIMELINE_DURATION_SECONDS;
+ }
+ return Math.max(MIN_VALID_TIMELINE_DURATION_SECONDS, mediaDurationFloorSeconds * TIMELINE_FLOOR_COVERAGE_RATIO);
+ };
+
+ const getSafeTimelineDurationSeconds = (timeline: RuntimeTimelineLike | null, fallback = 0): number => {
+ const timelineDuration = getTimelineDurationSeconds(timeline);
+ const mediaFloor = resolveMediaDurationFloorSeconds();
+ const fallbackDuration = Number.isFinite(fallback) && fallback > MIN_VALID_TIMELINE_DURATION_SECONDS ? fallback : 0;
+ let safeDuration = 0;
+ // Timeline is the source of truth for authored composition duration.
+ if (isUsableTimelineDuration(timelineDuration)) {
+ safeDuration = Math.max(timelineDuration, fallbackDuration);
+ } else if (isUsableTimelineDuration(mediaFloor)) {
+ safeDuration = Math.max(mediaFloor, fallbackDuration);
+ } else {
+ safeDuration = fallbackDuration;
+ }
+ const hardDurationCap = Math.max(1, Number(state.maxTimelineDurationSeconds) || 1800);
+ return safeDuration > 0 ? Math.max(0, Math.min(safeDuration, hardDurationCap)) : 0;
+ };
+
+ const resolveRootTimelineFromDocument = (): TimelineResolution => {
+ const timelines = (window.__timelines ?? {}) as Record;
+ const startResolver = createRuntimeStartTimeResolver({ timelineRegistry: timelines });
+ const mediaDurationFloorSeconds = resolveMediaDurationFloorSeconds();
+ const minCandidateDurationSeconds = resolveMinCandidateDurationSeconds(mediaDurationFloorSeconds);
+ const resolveCompositionStartSeconds = (compositionId: string): number => {
+ const node = document.querySelector(`[data-composition-id="${CSS.escape(compositionId)}"]`) as Element | null;
+ if (!node) return 0;
+ return startResolver.resolveStartForElement(node, 0);
+ };
+ const createCompositeTimelineFromCandidates = (
+ candidates: Array<{ compositionId: string; timeline: RuntimeTimelineLike; durationSeconds: number }>,
+ ): RuntimeTimelineLike | null => {
+ const gsapApi = window.gsap;
+ if (!gsapApi || typeof gsapApi.timeline !== "function") return null;
+ const compositeTimeline = gsapApi.timeline({ paused: true }) as RuntimeTimelineLike;
+ for (const candidate of candidates) {
+ compositeTimeline.add(candidate.timeline, resolveCompositionStartSeconds(candidate.compositionId));
+ }
+ return compositeTimeline;
+ };
+ const createDurationFloorTimeline = (
+ durationSeconds: number,
+ existingRootTimeline: RuntimeTimelineLike | null,
+ ): RuntimeTimelineLike | null => {
+ if (!isUsableTimelineDuration(durationSeconds)) return null;
+ const gsapApi = window.gsap;
+ if (!gsapApi || typeof gsapApi.timeline !== "function") return null;
+ const fallbackTimeline = gsapApi.timeline({ paused: true }) as RuntimeTimelineLike;
+ if (existingRootTimeline) {
+ try {
+ fallbackTimeline.add(existingRootTimeline, 0);
+ } catch {
+ // keep fallback resilient if root add fails
+ }
+ }
+ const withTween = fallbackTimeline as RuntimeTimelineLike & {
+ to?: (target: object, vars: { duration?: number }) => unknown;
+ };
+ if (typeof withTween.to === "function") {
+ try {
+ withTween.to({}, { duration: durationSeconds });
+ } catch {
+ // no-op; if tween creation fails, caller will discard by unusable duration
+ }
+ }
+ return fallbackTimeline;
+ };
+ const addMissingChildCandidatesToRootTimeline = (
+ rootTimeline: RuntimeTimelineLike,
+ candidates: Array<{ compositionId: string; timeline: RuntimeTimelineLike; durationSeconds: number }>,
+ ): string[] => {
+ const rootWithChildren = rootTimeline as RuntimeTimelineLike & {
+ getChildren?: (...args: unknown[]) => unknown[];
+ };
+ if (typeof rootWithChildren.getChildren !== "function") return [];
+ try {
+ const existingChildren = rootWithChildren.getChildren(true, true, true) ?? [];
+ if (!Array.isArray(existingChildren)) return [];
+ const addedIds: string[] = [];
+ for (const candidate of candidates) {
+ const alreadyIncluded = existingChildren.some((child) => child === candidate.timeline);
+ if (alreadyIncluded) continue;
+ try {
+ const startSec = resolveCompositionStartSeconds(candidate.compositionId);
+ rootTimeline.add(candidate.timeline, startSec);
+ addedIds.push(candidate.compositionId);
+ } catch {
+ // ignore broken child add attempts
+ }
+ }
+ return addedIds;
+ } catch {
+ return [];
+ }
+ };
+ const rootCompositionNode = resolveRootCompositionElement();
+ const rootCompositionId = rootCompositionNode?.getAttribute("data-composition-id") ?? null;
+ if (!rootCompositionId) {
+ return { timeline: null };
+ }
+ const rootTimeline = timelines[rootCompositionId] ?? null;
+ const collectRootChildCandidates = (): Array<{
+ compositionId: string;
+ timeline: RuntimeTimelineLike;
+ durationSeconds: number;
+ }> => {
+ if (!rootCompositionNode) return [];
+ const seen = new Set();
+ const childNodes = Array.from(rootCompositionNode.querySelectorAll("[data-composition-id]"));
+ const candidates: Array<{ compositionId: string; timeline: RuntimeTimelineLike; durationSeconds: number }> = [];
+ for (const childNode of childNodes) {
+ const childId = childNode.getAttribute("data-composition-id");
+ if (!childId || childId === rootCompositionId) continue;
+ if (seen.has(childId)) continue;
+ seen.add(childId);
+ const candidateTimeline = timelines[childId] ?? null;
+ if (!candidateTimeline) continue;
+ if (typeof candidateTimeline.play !== "function" || typeof candidateTimeline.pause !== "function") {
+ continue;
+ }
+ const candidateDuration = getTimelineDurationSeconds(candidateTimeline);
+ candidates.push({
+ compositionId: childId,
+ timeline: candidateTimeline,
+ durationSeconds: candidateDuration ?? 0,
+ });
+ }
+ return candidates;
+ };
+ const rootChildCandidates = collectRootChildCandidates();
+ const ensureChildCandidatesActive = (
+ candidates: Array<{ compositionId: string; timeline: RuntimeTimelineLike; durationSeconds: number }>,
+ ): void => {
+ for (const candidate of candidates) {
+ const timelineWithPaused = candidate.timeline as RuntimeTimelineLike & {
+ paused?: (value?: boolean) => unknown;
+ };
+ if (typeof timelineWithPaused.paused !== "function") continue;
+ try {
+ timelineWithPaused.paused(false);
+ } catch {
+ // keep runtime resilient against timeline API quirks
+ }
+ }
+ };
+ if (rootChildCandidates.length > 0) {
+ ensureChildCandidatesActive(rootChildCandidates);
+ }
+ if (rootTimeline) {
+ const autoNestedChildren =
+ rootChildCandidates.length > 0
+ ? addMissingChildCandidatesToRootTimeline(rootTimeline, rootChildCandidates)
+ : [];
+ // Mark children as bound so the polling loop stops re-resolving
+ if (rootChildCandidates.length > 0 || !document.querySelector("[data-composition-id]:not([data-composition-id='" + rootCompositionId + "'])")) {
+ childrenBound = true;
+ }
+
+ // Force GSAP to render the current frame so child animations show their correct state.
+ // Without this, children added after the root was created may still show initial styles.
+ if (autoNestedChildren.length > 0) {
+ try {
+ const currentTime = rootTimeline.time();
+ rootTimeline.seek(currentTime, false); // false = don't suppress events
+ } catch { /* ignore */ }
+ }
+ const rootDurationSeconds = getTimelineDurationSeconds(rootTimeline);
+ if (!isUsableTimelineDuration(rootDurationSeconds) && rootChildCandidates.length > 0) {
+ const selectedTimelineIds = rootChildCandidates.map((candidate) => candidate.compositionId);
+ const compositeTimeline = createCompositeTimelineFromCandidates(rootChildCandidates);
+ const compositeDurationSeconds = getTimelineDurationSeconds(compositeTimeline);
+ if (compositeTimeline && isUsableTimelineDuration(compositeDurationSeconds)) {
+ return {
+ timeline: compositeTimeline,
+ selectedTimelineIds,
+ selectedDurationSeconds: compositeDurationSeconds,
+ mediaDurationFloorSeconds,
+ diagnostics: {
+ code: "root_timeline_unusable_fallback",
+ details: {
+ rootCompositionId,
+ rootDurationSeconds,
+ fallbackKind: "composite_by_root_children",
+ minCandidateDurationSeconds,
+ selectedDurationSeconds: compositeDurationSeconds,
+ mediaDurationFloorSeconds,
+ selectedTimelineIds,
+ autoNestedChildren,
+ },
+ },
+ };
+ }
+ const durationFloorTimeline = createDurationFloorTimeline(mediaDurationFloorSeconds ?? 0, rootTimeline);
+ const durationFloorSeconds = getTimelineDurationSeconds(durationFloorTimeline);
+ if (durationFloorTimeline && isUsableTimelineDuration(durationFloorSeconds)) {
+ return {
+ timeline: durationFloorTimeline,
+ selectedTimelineIds: [rootCompositionId],
+ selectedDurationSeconds: durationFloorSeconds,
+ mediaDurationFloorSeconds,
+ diagnostics: {
+ code: "root_timeline_unusable_media_floor_fallback",
+ details: {
+ rootCompositionId,
+ rootDurationSeconds,
+ fallbackKind: "media_duration_floor",
+ mediaDurationFloorSeconds,
+ selectedDurationSeconds: durationFloorSeconds,
+ selectedTimelineIds: [rootCompositionId],
+ autoNestedChildren,
+ },
+ },
+ };
+ }
+ }
+ if (!isUsableTimelineDuration(rootDurationSeconds) && rootChildCandidates.length === 0) {
+ const durationFloorTimeline = createDurationFloorTimeline(mediaDurationFloorSeconds ?? 0, rootTimeline);
+ const durationFloorSeconds = getTimelineDurationSeconds(durationFloorTimeline);
+ if (durationFloorTimeline && isUsableTimelineDuration(durationFloorSeconds)) {
+ return {
+ timeline: durationFloorTimeline,
+ selectedTimelineIds: [rootCompositionId],
+ selectedDurationSeconds: durationFloorSeconds,
+ mediaDurationFloorSeconds,
+ diagnostics: {
+ code: "root_timeline_unusable_media_floor_fallback",
+ details: {
+ rootCompositionId,
+ rootDurationSeconds,
+ fallbackKind: "media_duration_floor",
+ mediaDurationFloorSeconds,
+ selectedDurationSeconds: durationFloorSeconds,
+ selectedTimelineIds: [rootCompositionId],
+ },
+ },
+ };
+ }
+ }
+ return {
+ timeline: rootTimeline,
+ selectedTimelineIds: [rootCompositionId],
+ selectedDurationSeconds: rootDurationSeconds,
+ mediaDurationFloorSeconds,
+ diagnostics:
+ autoNestedChildren.length > 0
+ ? {
+ code: "root_timeline_auto_nested_children",
+ details: {
+ rootCompositionId,
+ selectedDurationSeconds: rootDurationSeconds,
+ autoNestedChildren,
+ },
+ }
+ : undefined,
+ };
+ }
+ if (rootChildCandidates.length > 0) {
+ const selectedTimelineIds = rootChildCandidates.map((candidate) => candidate.compositionId);
+ const compositeTimeline = createCompositeTimelineFromCandidates(rootChildCandidates);
+ const compositeDurationSeconds = getTimelineDurationSeconds(compositeTimeline);
+ if (compositeTimeline) {
+ return {
+ timeline: compositeTimeline,
+ selectedTimelineIds,
+ selectedDurationSeconds: compositeDurationSeconds,
+ mediaDurationFloorSeconds,
+ diagnostics: {
+ code: "root_timeline_missing_fallback",
+ details: {
+ rootCompositionId,
+ fallbackKind: "composite_by_root_children",
+ minCandidateDurationSeconds,
+ selectedDurationSeconds: compositeDurationSeconds,
+ mediaDurationFloorSeconds,
+ selectedTimelineIds,
+ },
+ },
+ };
+ }
+ }
+ return { timeline: null };
+ };
+
+ const syncCurrentTimeFromTimeline = () => {
+ const timeline = state.capturedTimeline;
+ if (!timeline || typeof timeline.time !== "function") return;
+ const nextTime = Number(timeline.time());
+ if (!Number.isFinite(nextTime)) return;
+ state.currentTime = Math.max(0, nextTime);
+ };
+
+ // Track whether child composition timelines have been added to the root.
+ // This prevents the polling loop from skipping rebind when TARGET_DURATION
+ // makes the root "usable" before children register. Assumption: child scripts
+ // must register timelines synchronously or in the immediate microtask queue
+ // (setTimeout(0)). Scripts using requestAnimationFrame or longer delays may
+ // not be discovered.
+ let childrenBound = false;
+ const bindRootTimelineIfAvailable = (): boolean => {
+ if (!externalCompositionsReady) return false;
+ const currentTimeline = state.capturedTimeline;
+ const currentDuration = getTimelineDurationSeconds(currentTimeline);
+ const currentTimelineUsable = isUsableTimelineDuration(currentDuration);
+ // Skip rebind ONLY if we already have a usable timeline AND children have been bound.
+ // Without childrenBound check, the TARGET_DURATION spacer makes the timeline "usable"
+ // before child composition timelines are added, causing them to never be discovered.
+ if (currentTimeline && currentTimelineUsable && childrenBound) return false;
+ const resolution = resolveRootTimelineFromDocument();
+ if (!resolution.timeline) return false;
+ if (currentTimeline && currentTimeline === resolution.timeline) {
+ if (typeof currentTimeline.timeScale === "function") {
+ currentTimeline.timeScale(state.playbackRate);
+ }
+ return false;
+ }
+ state.capturedTimeline = resolution.timeline;
+ if (typeof state.capturedTimeline.timeScale === "function") {
+ state.capturedTimeline.timeScale(state.playbackRate);
+ }
+ if (resolution.diagnostics) {
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: resolution.diagnostics.code,
+ details: resolution.diagnostics.details,
+ });
+ }
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: "timeline_bound",
+ details: {
+ selectedTimelineIds: resolution.selectedTimelineIds ?? [],
+ selectedDurationSeconds: resolution.selectedDurationSeconds ?? null,
+ mediaDurationFloorSeconds: resolution.mediaDurationFloorSeconds ?? null,
+ },
+ });
+ return true;
+ };
+
+ const emitRootStageLayoutDiagnostics = () => {
+ const rootNode = resolveRootCompositionElement();
+ if (!(rootNode instanceof HTMLElement)) {
+ return;
+ }
+ const rect = rootNode.getBoundingClientRect();
+ const declaredWidth = Number(rootNode.getAttribute("data-width"));
+ const declaredHeight = Number(rootNode.getAttribute("data-height"));
+ const computedStyle = window.getComputedStyle(rootNode);
+ const hasDeclaredDimensions =
+ Number.isFinite(declaredWidth) && declaredWidth > 0 && Number.isFinite(declaredHeight) && declaredHeight > 0;
+ const looksCollapsed =
+ rect.width <= 0 || rect.height <= 0 || rootNode.clientWidth <= 0 || rootNode.clientHeight <= 0;
+ if (!hasDeclaredDimensions || !looksCollapsed) {
+ return;
+ }
+ postRuntimeDiagnosticOnce(
+ "root_stage_layout_zero",
+ {
+ compositionId: rootNode.getAttribute("data-composition-id") ?? null,
+ declaredWidth,
+ declaredHeight,
+ rectWidth: Math.round(rect.width),
+ rectHeight: Math.round(rect.height),
+ clientWidth: rootNode.clientWidth,
+ clientHeight: rootNode.clientHeight,
+ display: computedStyle.display,
+ visibility: computedStyle.visibility,
+ overflow: computedStyle.overflow,
+ },
+ `root-stage-layout-zero:${rootNode.getAttribute("data-composition-id") ?? "unknown"}`,
+ );
+ };
+
+ const scheduleRootStageLayoutDiagnostics = () => {
+ if (state.tornDown) {
+ return;
+ }
+ if (rootStageDiagnosticRafId != null) {
+ window.cancelAnimationFrame(rootStageDiagnosticRafId);
+ }
+ rootStageDiagnosticRafId = window.requestAnimationFrame(() => {
+ rootStageDiagnosticRafId = null;
+ emitRootStageLayoutDiagnostics();
+ });
+ };
+
+ const installRuntimeErrorDiagnostics = () => {
+ runtimeErrorListener = (event: ErrorEvent) => {
+ const normalized = normalizeDiagnosticMessage(event.error ?? event.message).slice(
+ 0,
+ MAX_DIAGNOSTIC_MESSAGE_LENGTH,
+ );
+ if (!normalized) {
+ return;
+ }
+ const classified = classifyRuntimeScriptFailure(normalized);
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: classified.code,
+ details: {
+ category: classified.category,
+ message: normalized,
+ filename: event.filename || null,
+ line: Number.isFinite(event.lineno) ? event.lineno : null,
+ column: Number.isFinite(event.colno) ? event.colno : null,
+ },
+ });
+ };
+ runtimeUnhandledRejectionListener = (event: PromiseRejectionEvent) => {
+ const normalized = normalizeDiagnosticMessage(event.reason).slice(0, MAX_DIAGNOSTIC_MESSAGE_LENGTH);
+ if (!normalized) {
+ return;
+ }
+ const classified = classifyRuntimeScriptFailure(normalized);
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: `${classified.code}_unhandled_rejection`,
+ details: {
+ category: `${classified.category}-unhandled-rejection`,
+ message: normalized,
+ },
+ });
+ };
+ window.addEventListener("error", runtimeErrorListener);
+ window.addEventListener("unhandledrejection", runtimeUnhandledRejectionListener);
+ };
+
+ const installAssetFailureDiagnostics = () => {
+ const assetNodes = Array.from(document.querySelectorAll("img, video, audio, source, link[rel='stylesheet']"));
+ for (const node of assetNodes) {
+ const onError = () => {
+ if (!(node instanceof Element)) {
+ return;
+ }
+ const tagName = node.tagName.toLowerCase();
+ const assetUrl = node.getAttribute("src") ?? node.getAttribute("href") ?? node.getAttribute("poster") ?? null;
+ const diagnosticCode = tagName === "link" ? "runtime_stylesheet_load_failed" : "runtime_asset_load_failed";
+ postRuntimeDiagnosticOnce(
+ diagnosticCode,
+ {
+ tagName,
+ assetUrl,
+ currentSrc:
+ node instanceof HTMLImageElement || node instanceof HTMLMediaElement ? node.currentSrc || null : null,
+ readyState: node instanceof HTMLMediaElement ? node.readyState : null,
+ networkState: node instanceof HTMLMediaElement ? node.networkState : null,
+ },
+ `${diagnosticCode}:${tagName}:${assetUrl ?? "unknown"}`,
+ );
+ };
+ node.addEventListener("error", onError);
+ registerRuntimeCleanup(() => {
+ node.removeEventListener("error", onError);
+ });
+ }
+
+ const fontSet = document.fonts;
+ if (!fontSet) {
+ return;
+ }
+ void fontSet.ready
+ .then(() => {
+ if (state.tornDown) {
+ return;
+ }
+ const failedFamilies = Array.from(fontSet)
+ .filter((face) => face.status === "error")
+ .map((face) => face.family)
+ .filter((family) => Boolean(family))
+ .slice(0, 10);
+ if (failedFamilies.length === 0) {
+ return;
+ }
+ postRuntimeDiagnosticOnce(
+ "runtime_font_load_issue",
+ {
+ failedFamilies,
+ totalFaces: Array.from(fontSet).length,
+ },
+ `runtime-font-load-issue:${failedFamilies.join("|")}`,
+ );
+ })
+ .catch(() => {
+ // ignore font readiness failures
+ });
+ };
+
+ const rebindTimelineFromResolution = (resolution: TimelineResolution, reason: "loop_guard" | "manual"): boolean => {
+ if (!resolution.timeline) return false;
+ const previousTimeline = state.capturedTimeline;
+ if (previousTimeline && previousTimeline === resolution.timeline) {
+ return false;
+ }
+ const previousTime = Math.max(0, state.currentTime || 0);
+ const wasPlaying = state.isPlaying;
+ state.capturedTimeline = resolution.timeline;
+ if (typeof state.capturedTimeline.timeScale === "function") {
+ state.capturedTimeline.timeScale(state.playbackRate);
+ }
+ try {
+ state.capturedTimeline.pause();
+ state.capturedTimeline.seek(previousTime, false);
+ if (wasPlaying) {
+ state.capturedTimeline.play();
+ }
+ } catch {
+ // keep runtime resilient even if a timeline implementation throws
+ }
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: "timeline_loop_guard_rebind",
+ details: {
+ reason,
+ previousTime,
+ selectedTimelineIds: resolution.selectedTimelineIds ?? [],
+ selectedDurationSeconds: resolution.selectedDurationSeconds ?? null,
+ mediaDurationFloorSeconds: resolution.mediaDurationFloorSeconds ?? null,
+ },
+ });
+ return true;
+ };
+
+ let metadataRebindDebounceTimerId: number | null = null;
+ let metadataRebindApplied = false;
+ const metadataBoundMedia = new Set();
+
+ const scheduleMetadataDurationHydration = () => {
+ if (state.tornDown) return;
+ if (metadataRebindDebounceTimerId != null) {
+ window.clearTimeout(metadataRebindDebounceTimerId);
+ }
+ metadataRebindDebounceTimerId = window.setTimeout(() => {
+ if (state.tornDown) return;
+ metadataRebindDebounceTimerId = null;
+ const resolution = resolveRootTimelineFromDocument();
+ if (!resolution.timeline) return;
+ const hasResolvedMediaFloor = isUsableTimelineDuration(resolution.mediaDurationFloorSeconds ?? null);
+ if (!hasResolvedMediaFloor) return;
+ if (!state.capturedTimeline) {
+ if (bindRootTimelineIfAvailable()) {
+ postTimeline();
+ postState(true);
+ }
+ return;
+ }
+ if (metadataRebindApplied) return;
+ const currentDuration = getTimelineDurationSeconds(state.capturedTimeline);
+ const nextDuration = resolution.selectedDurationSeconds ?? getTimelineDurationSeconds(resolution.timeline);
+ const isBetterCandidate =
+ isUsableTimelineDuration(nextDuration) &&
+ (!isUsableTimelineDuration(currentDuration) ||
+ nextDuration >= currentDuration + METADATA_REBIND_MIN_DURATION_GAIN_SECONDS);
+ if (!isBetterCandidate) return;
+ if (rebindTimelineFromResolution(resolution, "manual")) {
+ metadataRebindApplied = true;
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code: "timeline_rebind_after_media_metadata",
+ details: {
+ previousDurationSeconds: currentDuration ?? null,
+ selectedDurationSeconds: nextDuration ?? null,
+ selectedTimelineIds: resolution.selectedTimelineIds ?? [],
+ mediaDurationFloorSeconds: resolution.mediaDurationFloorSeconds ?? null,
+ },
+ });
+ postTimeline();
+ postState(true);
+ }
+ }, METADATA_REBIND_DEBOUNCE_MS);
+ };
+
+ const unbindMediaMetadataListeners = () => {
+ for (const mediaEl of metadataBoundMedia) {
+ mediaEl.removeEventListener("loadedmetadata", scheduleMetadataDurationHydration);
+ mediaEl.removeEventListener("durationchange", scheduleMetadataDurationHydration);
+ }
+ metadataBoundMedia.clear();
+ };
+
+ const bindMediaMetadataListeners = () => {
+ if (state.tornDown) return;
+ const mediaEls = Array.from(document.querySelectorAll("video, audio")) as HTMLMediaElement[];
+ for (const mediaEl of mediaEls) {
+ if (metadataBoundMedia.has(mediaEl)) continue;
+ metadataBoundMedia.add(mediaEl);
+ mediaEl.addEventListener("loadedmetadata", scheduleMetadataDurationHydration);
+ mediaEl.addEventListener("durationchange", scheduleMetadataDurationHydration);
+ }
+ };
+
+ const syncMediaForCurrentState = () => {
+ const cache = refreshRuntimeMediaCache({
+ resolveStartSeconds: (element) => resolveStartForElement(element, 0),
+ });
+ syncRuntimeMedia({
+ clips: cache.mediaClips,
+ timeSeconds: state.currentTime,
+ playing: state.isPlaying,
+ playbackRate: state.playbackRate,
+ });
+ const rootCompId = document.querySelector("[data-composition-id]")?.getAttribute("data-composition-id") ?? null;
+ const visibilityNodes = Array.from(document.querySelectorAll("[data-start]"));
+ for (const rawNode of visibilityNodes) {
+ if (!(rawNode instanceof HTMLElement)) continue;
+ const tag = rawNode.tagName.toLowerCase();
+ if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") continue;
+
+ // Skip elements INSIDE sub-compositions — their visibility is managed by GSAP,
+ // not the global time-based adapter. Only manage visibility for:
+ // 1. Composition host elements (have data-composition-id themselves)
+ // 2. Direct children of root composition (audio, etc.)
+ // Skip: elements whose nearest composition ancestor is NOT the root
+ const ownCompId = rawNode.getAttribute("data-composition-id");
+ if (!ownCompId) {
+ // Not a composition host — check if it's inside a sub-composition
+ const parentComp = rawNode.closest("[data-composition-id]");
+ const parentCompId = parentComp?.getAttribute("data-composition-id") ?? null;
+ if (parentCompId && parentCompId !== rootCompId) continue;
+ }
+
+ const start = resolveStartForElement(rawNode, 0);
+ const duration = resolveDurationForElement(rawNode);
+ const end = duration != null && duration > 0 ? start + duration : Number.POSITIVE_INFINITY;
+ // For composition hosts, use the composition timeline's duration to compute end
+ let computedEnd = end;
+ const compId = rawNode.getAttribute("data-composition-id");
+ if (compId && !Number.isFinite(end)) {
+ const compTimeline = (window.__timelines ?? {})[compId];
+ if (compTimeline && typeof compTimeline.duration === "function") {
+ const compDur = compTimeline.duration();
+ if (compDur > 0) computedEnd = start + compDur;
+ }
+ }
+ const isVisibleNow = state.currentTime >= start && (Number.isFinite(computedEnd) ? state.currentTime < computedEnd : true);
+ rawNode.style.visibility = isVisibleNow ? "visible" : "hidden";
+ }
+ };
+
+ const postState = (force: boolean) => {
+ syncCurrentTimeFromTimeline();
+ const frame = Math.max(0, Math.round((state.currentTime || 0) * state.canonicalFps));
+ const now = Date.now();
+ const shouldPost =
+ force ||
+ frame !== state.bridgeLastPostedFrame ||
+ state.isPlaying !== state.bridgeLastPostedPlaying ||
+ state.bridgeMuted !== state.bridgeLastPostedMuted ||
+ now - state.bridgeLastPostedAt >= state.bridgeMaxPostIntervalMs;
+ if (!shouldPost) return;
+ state.bridgeLastPostedFrame = frame;
+ state.bridgeLastPostedPlaying = state.isPlaying;
+ state.bridgeLastPostedMuted = state.bridgeMuted;
+ state.bridgeLastPostedAt = now;
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "state",
+ frame,
+ isPlaying: state.isPlaying,
+ muted: state.bridgeMuted,
+ playbackRate: state.playbackRate,
+ });
+ };
+
+ const postTimeline = () => {
+ sanitizeCompositionDurationAttributes();
+ applyCompositionSizing();
+ applyClipLayout();
+ // Post resolved stage size so the parent can scale the iframe container
+ const stageSizeRootEl = resolveRootCompositionElement();
+ if (stageSizeRootEl) {
+ const w = parseDimensionPx(stageSizeRootEl.getAttribute("data-width"));
+ const h = parseDimensionPx(stageSizeRootEl.getAttribute("data-height"));
+ const width = w ? parseInt(w, 10) : 0;
+ const height = h ? parseInt(h, 10) : 0;
+ if (width > 0 && height > 0) {
+ postRuntimeMessage({ source: "hf-preview", type: "stage-size", width, height });
+ }
+ }
+ bindRootTimelineIfAvailable();
+ const payload = collectRuntimeTimelinePayload({
+ canonicalFps: state.canonicalFps,
+ maxTimelineDurationSeconds: state.maxTimelineDurationSeconds,
+ });
+ window.__clipManifest = payload;
+ postRuntimeMessage(payload);
+ scheduleRootStageLayoutDiagnostics();
+ };
+
+ const runAdapters = (method: "discover" | "pause" | "play", timeSeconds = 0) => {
+ for (const adapter of state.deterministicAdapters) {
+ try {
+ if (method === "discover") adapter.discover();
+ if (method === "pause") adapter.pause();
+ if (method === "play" && adapter.play) adapter.play();
+ } catch {
+ // keep runtime resilient against adapter-specific failures
+ }
+ if (method === "discover") {
+ try {
+ adapter.seek({ time: timeSeconds });
+ } catch {
+ // ignore seek bootstrap failures
+ }
+ }
+ }
+ };
+
+ if (!externalCompositionsReady) {
+ void loadExternalCompositions({
+ injectedStyles: state.injectedCompStyles,
+ injectedScripts: state.injectedCompScripts,
+ parseDimensionPx,
+ onDiagnostic: ({ code, details }) => {
+ postRuntimeMessage({
+ source: "hf-preview",
+ type: "diagnostic",
+ code,
+ details,
+ });
+ },
+ }).finally(() => {
+ externalCompositionsReady = true;
+ runAdapters("discover", state.currentTime);
+ bindMediaMetadataListeners();
+ installAssetFailureDiagnostics();
+ postTimeline();
+ postState(true);
+ });
+ }
+
+ const picker = createPickerModule({
+ postMessage: (payload) => postRuntimeMessage(payload),
+ });
+ picker.installPickerApi();
+
+ const applyPlaybackRate = (nextRate: number) => {
+ const parsed = Number(nextRate);
+ if (!Number.isFinite(parsed) || parsed <= 0) {
+ state.playbackRate = 1;
+ } else {
+ state.playbackRate = Math.max(0.1, Math.min(5, parsed));
+ }
+ if (state.capturedTimeline && typeof state.capturedTimeline.timeScale === "function") {
+ state.capturedTimeline.timeScale(state.playbackRate);
+ }
+ const mediaEls = document.querySelectorAll("video, audio");
+ for (const el of mediaEls) {
+ if (!(el instanceof HTMLMediaElement)) continue;
+ try {
+ el.playbackRate = state.playbackRate;
+ } catch {
+ // ignore unsupported values
+ }
+ }
+ };
+
+ const player = createRuntimePlayer({
+ getTimeline: () => state.capturedTimeline,
+ setTimeline: (timeline) => {
+ state.capturedTimeline = timeline;
+ },
+ getIsPlaying: () => state.isPlaying,
+ setIsPlaying: (playing) => {
+ state.isPlaying = playing;
+ },
+ getPlaybackRate: () => state.playbackRate,
+ setPlaybackRate: applyPlaybackRate,
+ getCanonicalFps: () => state.canonicalFps,
+ onSyncMedia: (timeSeconds, playing) => {
+ state.currentTime = Math.max(0, Number(timeSeconds) || 0);
+ state.isPlaying = playing;
+ syncMediaForCurrentState();
+ },
+ onStatePost: postState,
+ onDeterministicSeek: (timeSeconds) => {
+ for (const adapter of state.deterministicAdapters) {
+ try {
+ adapter.seek({ time: Number(timeSeconds) || 0 });
+ } catch {
+ // ignore adapter failure
+ }
+ }
+ },
+ onDeterministicPause: () => runAdapters("pause"),
+ onDeterministicPlay: () => runAdapters("play"),
+ onRenderFrameSeek: () => {},
+ onShowNativeVideos: () => {},
+ getSafeDuration: () => getSafeTimelineDurationSeconds(state.capturedTimeline, 0),
+ });
+
+ window.__player = createPlayerApiCompat(player);
+ (window as Window & { __playerReady?: boolean }).__playerReady = true;
+ (window as Window & { __renderReady?: boolean }).__renderReady = true;
+
+ // Wire analytics event emission through the bridge
+ initRuntimeAnalytics(postRuntimeMessage as (payload: unknown) => void);
+ emitAnalyticsEvent("composition_loaded", {
+ duration: player.getDuration(),
+ compositionId: document.querySelector("[data-composition-id]")?.getAttribute("data-composition-id") ?? null,
+ });
+
+ state.controlBridgeHandler = installRuntimeControlBridge({
+ onPlay: () => { player.play(); emitAnalyticsEvent("composition_played", { time: player.getTime() }); },
+ onPause: () => { player.pause(); emitAnalyticsEvent("composition_paused", { time: player.getTime() }); },
+ onSeek: (frame, _seekMode) => {
+ const time = Math.max(0, frame) / state.canonicalFps;
+ player.seek(time);
+ emitAnalyticsEvent("composition_seeked", { time });
+ },
+ onSetMuted: (muted) => {
+ state.bridgeMuted = muted;
+ const mediaEls = document.querySelectorAll("video, audio");
+ for (const el of mediaEls) {
+ if (!(el instanceof HTMLMediaElement)) continue;
+ el.muted = muted;
+ }
+ },
+ onSetPlaybackRate: (rate) => applyPlaybackRate(rate),
+ onEnablePickMode: () => picker.enablePickMode(),
+ onDisablePickMode: () => picker.disablePickMode(),
+ });
+
+ bindRootTimelineIfAvailable();
+ if (state.capturedTimeline) {
+ player._timeline = state.capturedTimeline;
+ }
+
+ // When the bundler inlines compositions, data-composition-src is removed so
+ // loadExternalCompositions() is skipped. But inline scripts registering child
+ // timelines in __timelines haven't executed yet (they run in the browser's next
+ // microtask). Defer a rebinding attempt to catch them.
+ if (externalCompositionsReady) {
+ setTimeout(() => {
+ const prevTimeline = state.capturedTimeline;
+ if (bindRootTimelineIfAvailable() && state.capturedTimeline !== prevTimeline) {
+ player._timeline = state.capturedTimeline;
+ }
+ // Re-run adapters to discover new elements
+ runAdapters("discover", state.currentTime);
+ postTimeline();
+ postState(true);
+ }, 0);
+ }
+
+ state.deterministicAdapters = [
+ createCssAdapter({
+ resolveStartSeconds: (element) => resolveStartForElement(element, 0),
+ }),
+ createWaapiAdapter(),
+ createGsapAdapter({ getTimeline: () => state.capturedTimeline }),
+ createThreeAdapter(),
+ createLottieAdapter(),
+ ] as RuntimeDeterministicAdapter[];
+ installRuntimeErrorDiagnostics();
+ runAdapters("discover");
+ bindMediaMetadataListeners();
+ if (state.timelinePollIntervalId) {
+ clearInterval(state.timelinePollIntervalId);
+ }
+ let timelinePollTick = 0;
+ let lastObservedTimelineTime: number | null = null;
+ let lastExplicitSeekAtMs = 0;
+ let loopGuardRebindTriggered = false;
+ let loopWrapCandidateCount = 0;
+ const markExplicitSeek = () => {
+ lastExplicitSeekAtMs = Date.now();
+ loopGuardRebindTriggered = false;
+ loopWrapCandidateCount = 0;
+ };
+ state.timelinePollIntervalId = setInterval(() => {
+ timelinePollTick += 1;
+ const shouldHoldRebindDuringEarlyPlay =
+ state.isPlaying &&
+ state.capturedTimeline != null &&
+ Math.max(0, state.currentTime || 0) < PLAY_REBIND_HOLD_SECONDS;
+ const timelineBoundThisTick = shouldHoldRebindDuringEarlyPlay ? false : bindRootTimelineIfAvailable();
+ if (state.capturedTimeline && !player._timeline) {
+ player._timeline = state.capturedTimeline;
+ }
+ if (timelineBoundThisTick || timelinePollTick % 20 === 0) {
+ postTimeline();
+ }
+ if (timelinePollTick % 10 === 0) {
+ bindMediaMetadataListeners();
+ }
+ syncCurrentTimeFromTimeline();
+ if (state.isPlaying && state.capturedTimeline) {
+ const currentObserved = Math.max(0, state.currentTime || 0);
+ const previousObserved = lastObservedTimelineTime;
+ const safeDuration = getSafeTimelineDurationSeconds(state.capturedTimeline, 0);
+ if (safeDuration > 0 && currentObserved >= safeDuration) {
+ player.pause();
+ player.seek(safeDuration);
+ lastObservedTimelineTime = safeDuration;
+ loopWrapCandidateCount = 0;
+ postState(true);
+ return;
+ }
+ const isWrapCandidate =
+ previousObserved != null &&
+ previousObserved >= LOOP_WRAP_PREVIOUS_TIME_THRESHOLD_SECONDS &&
+ currentObserved <= LOOP_WRAP_CURRENT_TIME_THRESHOLD_SECONDS;
+ if (isWrapCandidate) {
+ loopWrapCandidateCount += 1;
+ } else {
+ loopWrapCandidateCount = 0;
+ }
+ if (
+ !loopGuardRebindTriggered &&
+ loopWrapCandidateCount >= LOOP_GUARD_CONSECUTIVE_WRAP_THRESHOLD &&
+ Date.now() - lastExplicitSeekAtMs > LOOP_GUARD_SEEK_GRACE_PERIOD_MS
+ ) {
+ const resolution = resolveRootTimelineFromDocument();
+ if (rebindTimelineFromResolution(resolution, "loop_guard")) {
+ loopGuardRebindTriggered = true;
+ loopWrapCandidateCount = 0;
+ }
+ }
+ lastObservedTimelineTime = Math.max(0, state.currentTime || 0);
+ } else {
+ lastObservedTimelineTime = Math.max(0, state.currentTime || 0);
+ }
+ if (state.isPlaying) {
+ syncMediaForCurrentState();
+ }
+ postState(false);
+ }, 50);
+ postTimeline();
+ postState(true);
+
+ const originalSeek = player.seek;
+ player.seek = (timeSeconds: number) => {
+ markExplicitSeek();
+ originalSeek(timeSeconds);
+ };
+ const originalRenderSeek = player.renderSeek;
+ player.renderSeek = (timeSeconds: number) => {
+ markExplicitSeek();
+ originalRenderSeek(timeSeconds);
+ };
+
+ const teardown = () => {
+ if (state.tornDown) return;
+ state.tornDown = true;
+ if (state.timelinePollIntervalId) {
+ clearInterval(state.timelinePollIntervalId);
+ state.timelinePollIntervalId = null;
+ }
+ if (metadataRebindDebounceTimerId != null) {
+ window.clearTimeout(metadataRebindDebounceTimerId);
+ metadataRebindDebounceTimerId = null;
+ }
+ if (rootStageDiagnosticRafId != null) {
+ window.cancelAnimationFrame(rootStageDiagnosticRafId);
+ rootStageDiagnosticRafId = null;
+ }
+ unbindMediaMetadataListeners();
+ if (state.controlBridgeHandler) {
+ window.removeEventListener("message", state.controlBridgeHandler);
+ state.controlBridgeHandler = null;
+ }
+ if (runtimeErrorListener) {
+ window.removeEventListener("error", runtimeErrorListener);
+ runtimeErrorListener = null;
+ }
+ if (runtimeUnhandledRejectionListener) {
+ window.removeEventListener("unhandledrejection", runtimeUnhandledRejectionListener);
+ runtimeUnhandledRejectionListener = null;
+ }
+ if (state.beforeUnloadHandler) {
+ window.removeEventListener("beforeunload", state.beforeUnloadHandler);
+ state.beforeUnloadHandler = null;
+ }
+ picker.disablePickMode();
+ for (const adapter of state.deterministicAdapters) {
+ if (!adapter || typeof adapter.revert !== "function") continue;
+ try {
+ adapter.revert();
+ } catch {
+ // keep runtime resilient against adapter cleanup failures
+ }
+ }
+ state.deterministicAdapters = [];
+ for (const cleanup of runtimeCleanupCallbacks.splice(0)) {
+ try {
+ cleanup();
+ } catch {
+ // ignore cleanup failures
+ }
+ }
+ for (const styleEl of state.injectedCompStyles) {
+ try {
+ styleEl.remove();
+ } catch {
+ // ignore cleanup failures
+ }
+ }
+ state.injectedCompStyles = [];
+ for (const scriptEl of state.injectedCompScripts) {
+ try {
+ scriptEl.remove();
+ } catch {
+ // ignore cleanup failures
+ }
+ }
+ state.injectedCompScripts = [];
+ state.capturedTimeline = null;
+ if (runtimeWindow.__hfRuntimeTeardown === teardown) {
+ runtimeWindow.__hfRuntimeTeardown = null;
+ }
+ };
+ runtimeWindow.__hfRuntimeTeardown = teardown;
+ state.beforeUnloadHandler = teardown;
+ window.addEventListener("beforeunload", state.beforeUnloadHandler);
+}
diff --git a/packages/core/src/runtime/media.test.ts b/packages/core/src/runtime/media.test.ts
new file mode 100644
index 000000000..fd32fd596
--- /dev/null
+++ b/packages/core/src/runtime/media.test.ts
@@ -0,0 +1,171 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { refreshRuntimeMediaCache, syncRuntimeMedia } from "./media";
+import type { RuntimeMediaClip } from "./media";
+
+function createVideo(attrs: Record): HTMLVideoElement {
+ const el = document.createElement("video");
+ for (const [key, value] of Object.entries(attrs)) {
+ el.setAttribute(key, value);
+ }
+ // jsdom doesn't compute media duration, so we stub it
+ Object.defineProperty(el, "duration", { value: NaN, writable: true, configurable: true });
+ document.body.appendChild(el);
+ return el;
+}
+
+function createAudio(attrs: Record): HTMLAudioElement {
+ const el = document.createElement("audio");
+ for (const [key, value] of Object.entries(attrs)) {
+ el.setAttribute(key, value);
+ }
+ Object.defineProperty(el, "duration", { value: NaN, writable: true, configurable: true });
+ document.body.appendChild(el);
+ return el;
+}
+
+describe("refreshRuntimeMediaCache", () => {
+ afterEach(() => {
+ document.body.innerHTML = "";
+ });
+
+ it("finds video elements with data-start", () => {
+ createVideo({ "data-start": "0", "data-duration": "5" });
+ const result = refreshRuntimeMediaCache();
+ expect(result.timedMediaEls).toHaveLength(1);
+ expect(result.mediaClips).toHaveLength(1);
+ expect(result.videoClips).toHaveLength(1);
+ });
+
+ it("finds audio elements with data-start", () => {
+ createAudio({ "data-start": "2", "data-duration": "3" });
+ const result = refreshRuntimeMediaCache();
+ expect(result.timedMediaEls).toHaveLength(1);
+ expect(result.mediaClips).toHaveLength(1);
+ expect(result.videoClips).toHaveLength(0);
+ });
+
+ it("ignores media without data-start", () => {
+ document.body.appendChild(document.createElement("video"));
+ const result = refreshRuntimeMediaCache();
+ expect(result.timedMediaEls).toHaveLength(0);
+ });
+
+ it("calculates clip end from start + duration", () => {
+ createVideo({ "data-start": "2", "data-duration": "3" });
+ const result = refreshRuntimeMediaCache();
+ const clip = result.mediaClips[0];
+ expect(clip.start).toBe(2);
+ expect(clip.duration).toBe(3);
+ expect(clip.end).toBe(5);
+ });
+
+ it("uses media-start offset", () => {
+ createVideo({ "data-start": "0", "data-duration": "5", "data-media-start": "10" });
+ const result = refreshRuntimeMediaCache();
+ expect(result.mediaClips[0].mediaStart).toBe(10);
+ });
+
+ it("parses volume attribute", () => {
+ createVideo({ "data-start": "0", "data-duration": "5", "data-volume": "0.5" });
+ const result = refreshRuntimeMediaCache();
+ expect(result.mediaClips[0].volume).toBe(0.5);
+ });
+
+ it("handles missing volume gracefully", () => {
+ createVideo({ "data-start": "0", "data-duration": "5" });
+ const result = refreshRuntimeMediaCache();
+ expect(result.mediaClips[0].volume).toBeNull();
+ });
+
+ it("maxMediaEnd tracks highest clip end", () => {
+ createVideo({ "data-start": "0", "data-duration": "5" });
+ createVideo({ "data-start": "3", "data-duration": "10" });
+ const result = refreshRuntimeMediaCache();
+ expect(result.maxMediaEnd).toBe(13);
+ });
+
+ it("uses custom resolveStartSeconds", () => {
+ createVideo({ "data-start": "0", "data-duration": "5" });
+ const result = refreshRuntimeMediaCache({ resolveStartSeconds: () => 10 });
+ expect(result.mediaClips[0].start).toBe(10);
+ });
+
+ it("falls back to element.duration when data-duration missing", () => {
+ const el = createVideo({ "data-start": "0" });
+ Object.defineProperty(el, "duration", { value: 8, writable: true });
+ const result = refreshRuntimeMediaCache();
+ expect(result.mediaClips[0].duration).toBe(8);
+ });
+});
+
+describe("syncRuntimeMedia", () => {
+ function createMockClip(overrides?: Partial): RuntimeMediaClip {
+ const el = document.createElement("video") as HTMLVideoElement;
+ document.body.appendChild(el);
+ Object.defineProperty(el, "paused", { value: true, writable: true, configurable: true });
+ el.play = vi.fn(() => Promise.resolve());
+ el.pause = vi.fn();
+ Object.defineProperty(el, "currentTime", { value: 0, writable: true, configurable: true });
+ Object.defineProperty(el, "playbackRate", { value: 1, writable: true, configurable: true });
+ return {
+ el,
+ start: 0,
+ mediaStart: 0,
+ duration: 10,
+ end: 10,
+ volume: null,
+ ...overrides,
+ };
+ }
+
+ afterEach(() => {
+ document.body.innerHTML = "";
+ });
+
+ it("plays active clip when playing", () => {
+ const clip = createMockClip({ start: 0, end: 10 });
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 1 });
+ expect(clip.el.play).toHaveBeenCalled();
+ });
+
+ it("pauses active clip when not playing", () => {
+ const clip = createMockClip({ start: 0, end: 10 });
+ Object.defineProperty(clip.el, "paused", { value: false, writable: true });
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
+ expect(clip.el.pause).toHaveBeenCalled();
+ });
+
+ it("pauses inactive clip", () => {
+ const clip = createMockClip({ start: 5, end: 10 });
+ Object.defineProperty(clip.el, "paused", { value: false, writable: true });
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 2, playing: true, playbackRate: 1 });
+ expect(clip.el.pause).toHaveBeenCalled();
+ });
+
+ it("sets volume when clip has volume", () => {
+ const clip = createMockClip({ start: 0, end: 10, volume: 0.7 });
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
+ expect(clip.el.volume).toBe(0.7);
+ });
+
+ it("seeks when currentTime drifts > 0.3s", () => {
+ const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
+ Object.defineProperty(clip.el, "currentTime", { value: 0, writable: true });
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
+ expect(clip.el.currentTime).toBe(5);
+ });
+
+ it("does not seek when currentTime is close enough", () => {
+ const clip = createMockClip({ start: 0, end: 10, mediaStart: 0 });
+ Object.defineProperty(clip.el, "currentTime", { value: 5.1, writable: true });
+ const original = clip.el.currentTime;
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: false, playbackRate: 1 });
+ expect(clip.el.currentTime).toBe(original);
+ });
+
+ it("sets playbackRate", () => {
+ const clip = createMockClip({ start: 0, end: 10 });
+ syncRuntimeMedia({ clips: [clip], timeSeconds: 5, playing: true, playbackRate: 2 });
+ expect(clip.el.playbackRate).toBe(2);
+ });
+});
diff --git a/packages/core/src/runtime/media.ts b/packages/core/src/runtime/media.ts
new file mode 100644
index 000000000..9e2d47d9c
--- /dev/null
+++ b/packages/core/src/runtime/media.ts
@@ -0,0 +1,83 @@
+export type RuntimeMediaClip = {
+ el: HTMLVideoElement | HTMLAudioElement;
+ start: number;
+ mediaStart: number;
+ duration: number;
+ end: number;
+ volume: number | null;
+};
+
+export function refreshRuntimeMediaCache(params?: { resolveStartSeconds?: (element: Element) => number }): {
+ timedMediaEls: Array;
+ mediaClips: RuntimeMediaClip[];
+ videoClips: RuntimeMediaClip[];
+ maxMediaEnd: number;
+} {
+ const mediaEls = Array.from(document.querySelectorAll("video[data-start], audio[data-start]")) as Array<
+ HTMLVideoElement | HTMLAudioElement
+ >;
+ const mediaClips: RuntimeMediaClip[] = [];
+ const videoClips: RuntimeMediaClip[] = [];
+ let maxMediaEnd = 0;
+ for (const el of mediaEls) {
+ const start = params?.resolveStartSeconds
+ ? params.resolveStartSeconds(el)
+ : Number.parseFloat(el.dataset.start ?? "0");
+ if (!Number.isFinite(start)) continue;
+ const mediaStart = Number.parseFloat(el.dataset.playbackStart ?? el.dataset.mediaStart ?? "0") || 0;
+ let duration = Number.parseFloat(el.dataset.duration ?? "");
+ if ((!Number.isFinite(duration) || duration <= 0) && Number.isFinite(el.duration) && el.duration > 0) {
+ duration = Math.max(0, el.duration - mediaStart);
+ }
+ const end = Number.isFinite(duration) && duration > 0 ? start + duration : Number.POSITIVE_INFINITY;
+ const volumeRaw = Number.parseFloat(el.dataset.volume ?? "");
+ const clip: RuntimeMediaClip = {
+ el,
+ start,
+ mediaStart,
+ duration: Number.isFinite(duration) && duration > 0 ? duration : Number.POSITIVE_INFINITY,
+ end,
+ volume: Number.isFinite(volumeRaw) ? volumeRaw : null,
+ };
+ mediaClips.push(clip);
+ if (el.tagName === "VIDEO") videoClips.push(clip);
+ if (Number.isFinite(end)) maxMediaEnd = Math.max(maxMediaEnd, end);
+ }
+ return { timedMediaEls: mediaEls, mediaClips, videoClips, maxMediaEnd };
+}
+
+export function syncRuntimeMedia(params: {
+ clips: RuntimeMediaClip[];
+ timeSeconds: number;
+ playing: boolean;
+ playbackRate: number;
+}): void {
+ for (const clip of params.clips) {
+ const { el } = clip;
+ if (!el.isConnected) continue;
+ const relTime = params.timeSeconds - clip.start + clip.mediaStart;
+ const isActive = params.timeSeconds >= clip.start && params.timeSeconds < clip.end && relTime >= 0;
+ if (isActive) {
+ if (clip.volume != null) el.volume = clip.volume;
+ try {
+ el.playbackRate = params.playbackRate;
+ } catch {
+ // ignore unsupported playbackRate
+ }
+ if (Math.abs((el.currentTime || 0) - relTime) > 0.3) {
+ try {
+ el.currentTime = relTime;
+ } catch {
+ // ignore browser seek restrictions
+ }
+ }
+ if (params.playing && el.paused) {
+ void el.play().catch(() => {});
+ } else if (!params.playing && !el.paused) {
+ el.pause();
+ }
+ continue;
+ }
+ if (!el.paused) el.pause();
+ }
+}
diff --git a/packages/core/src/runtime/picker.test.ts b/packages/core/src/runtime/picker.test.ts
new file mode 100644
index 000000000..d5b0d58af
--- /dev/null
+++ b/packages/core/src/runtime/picker.test.ts
@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { createPickerModule } from "./picker";
+
+function createMockPostMessage() {
+ return vi.fn();
+}
+
+describe("createPickerModule", () => {
+ afterEach(() => {
+ document.body.innerHTML = "";
+ document.head.querySelectorAll("style").forEach(s => s.remove());
+ document.body.classList.remove("__hf-pick-active");
+ });
+
+ it("returns enablePickMode, disablePickMode, installPickerApi", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ expect(typeof picker.enablePickMode).toBe("function");
+ expect(typeof picker.disablePickMode).toBe("function");
+ expect(typeof picker.installPickerApi).toBe("function");
+ });
+
+ describe("enablePickMode / disablePickMode", () => {
+ it("adds and removes pick-active class on body", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.enablePickMode();
+ expect(document.body.classList.contains("__hf-pick-active")).toBe(true);
+
+ picker.disablePickMode();
+ expect(document.body.classList.contains("__hf-pick-active")).toBe(false);
+ });
+
+ it("injects and removes style element", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.enablePickMode();
+ const styles = document.head.querySelectorAll("style");
+ const hasPickStyle = Array.from(styles).some(s =>
+ s.textContent?.includes("__hf-pick-highlight")
+ );
+ expect(hasPickStyle).toBe(true);
+
+ picker.disablePickMode();
+ const stylesAfter = document.head.querySelectorAll("style");
+ const hasPickStyleAfter = Array.from(stylesAfter).some(s =>
+ s.textContent?.includes("__hf-pick-highlight")
+ );
+ expect(hasPickStyleAfter).toBe(false);
+ });
+
+ it("enabling twice is idempotent", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.enablePickMode();
+ picker.enablePickMode();
+ expect(document.body.classList.contains("__hf-pick-active")).toBe(true);
+ });
+
+ it("disabling when not active is safe", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ expect(() => picker.disablePickMode()).not.toThrow();
+ });
+ });
+
+ describe("installPickerApi", () => {
+ it("installs __HF_PICKER_API on window", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+ expect(api).toBeDefined();
+ expect(typeof api.enable).toBe("function");
+ expect(typeof api.disable).toBe("function");
+ expect(typeof api.isActive).toBe("function");
+ expect(typeof api.getHovered).toBe("function");
+ expect(typeof api.getSelected).toBe("function");
+ expect(typeof api.getCandidatesAtPoint).toBe("function");
+ expect(typeof api.pickAtPoint).toBe("function");
+ expect(typeof api.pickManyAtPoint).toBe("function");
+ });
+
+ it("isActive returns pick mode state", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+
+ expect(api.isActive()).toBe(false);
+ picker.enablePickMode();
+ expect(api.isActive()).toBe(true);
+ picker.disablePickMode();
+ expect(api.isActive()).toBe(false);
+ });
+
+ it("getCandidatesAtPoint returns empty for invalid coords", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+ expect(api.getCandidatesAtPoint(NaN, NaN)).toEqual([]);
+ expect(api.getCandidatesAtPoint(Infinity, 0)).toEqual([]);
+ });
+
+ it("pickAtPoint returns null for invalid coords", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+ expect(api.pickAtPoint(NaN, NaN)).toBeNull();
+ });
+
+ it("pickManyAtPoint returns empty for invalid coords", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+ expect(api.pickManyAtPoint(NaN, NaN)).toEqual([]);
+ });
+
+ it("getHovered returns null initially", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+ expect(api.getHovered()).toBeNull();
+ });
+
+ it("getSelected returns null initially", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const api = (window as any).__HF_PICKER_API;
+ expect(api.getSelected()).toBeNull();
+ });
+ });
+
+ describe("escape key handler", () => {
+ it("disables pick mode and posts cancel message on Escape", () => {
+ const postMessage = createMockPostMessage();
+ const picker = createPickerModule({ postMessage });
+ picker.enablePickMode();
+
+ document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+
+ expect(document.body.classList.contains("__hf-pick-active")).toBe(false);
+ expect(postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ source: "hf-preview",
+ type: "pick-mode-cancelled",
+ })
+ );
+ });
+
+ it("ignores non-Escape keys", () => {
+ const postMessage = createMockPostMessage();
+ const picker = createPickerModule({ postMessage });
+ picker.enablePickMode();
+
+ document.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+ expect(document.body.classList.contains("__hf-pick-active")).toBe(true);
+ });
+ });
+});
diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts
new file mode 100644
index 000000000..f45cb76d9
--- /dev/null
+++ b/packages/core/src/runtime/picker.ts
@@ -0,0 +1,257 @@
+import type { RuntimeJson, RuntimeOutboundMessage, RuntimePickerElementInfo } from "./types";
+
+type PickerModuleDeps = {
+ postMessage: (payload: RuntimeOutboundMessage) => void;
+};
+
+export type PickerModule = {
+ enablePickMode: () => void;
+ disablePickMode: () => void;
+ installPickerApi: () => void;
+};
+
+export function createPickerModule(deps: PickerModuleDeps): PickerModule {
+ let pickModeActive = false;
+ let pickModeHighlightEl: Element | null = null;
+ let pickModeStyleEl: HTMLStyleElement | null = null;
+ let pickLastHoveredInfo: RuntimePickerElementInfo | null = null;
+ let pickLastSelectedInfo: RuntimePickerElementInfo | null = null;
+
+ function emitPickerRuntimeEvent(eventName: string, detail: RuntimeJson): void {
+ try {
+ window.dispatchEvent(new CustomEvent(eventName, { detail }));
+ } catch {
+ // no-op in unsupported contexts
+ }
+ }
+
+ function setLastHoveredInfo(info: RuntimePickerElementInfo | null): void {
+ pickLastHoveredInfo = info;
+ emitPickerRuntimeEvent("hyperframe:picker:hovered", {
+ elementInfo: pickLastHoveredInfo,
+ isPickMode: pickModeActive,
+ timestamp: Date.now(),
+ });
+ }
+
+ function setLastSelectedInfo(info: RuntimePickerElementInfo | null): void {
+ pickLastSelectedInfo = info;
+ emitPickerRuntimeEvent("hyperframe:picker:selected", {
+ elementInfo: pickLastSelectedInfo,
+ isPickMode: pickModeActive,
+ timestamp: Date.now(),
+ });
+ }
+
+ function isPickableElement(el: Element | null): el is Element {
+ if (!el || el === document.body || el === document.documentElement) return false;
+ const tag = el.tagName.toLowerCase();
+ if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") return false;
+ if (el.classList.contains("__hf-pick-highlight")) return false;
+ return true;
+ }
+
+ function buildElementSelector(el: Element): string {
+ const htmlEl = el as HTMLElement;
+ if (htmlEl.id) return `#${htmlEl.id}`;
+ const compositionId = el.getAttribute("data-composition-id");
+ if (compositionId) return `[data-composition-id="${compositionId}"]`;
+ const compositionSrc = el.getAttribute("data-composition-src");
+ if (compositionSrc) return `[data-composition-src="${compositionSrc}"]`;
+ const track = el.getAttribute("data-track-index");
+ if (track) return `[data-track-index="${track}"]`;
+ const tag = el.tagName.toLowerCase();
+ const parent = el.parentElement;
+ if (!parent) return tag;
+ const siblings = parent.querySelectorAll(`:scope > ${tag}`);
+ if (siblings.length === 1) return tag;
+ for (let i = 0; i < siblings.length; i += 1) {
+ if (siblings[i] === el) return `${tag}:nth-of-type(${i + 1})`;
+ }
+ return tag;
+ }
+
+ function buildElementLabel(el: Element): string {
+ const tag = el.tagName.toLowerCase();
+ const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
+ const trimLabel = (value: string, maxChars: number) =>
+ value.length > maxChars ? `${value.slice(0, maxChars - 1)}…` : value;
+ if (tag === "h1" || tag === "h2" || tag === "h3") return "Heading";
+ if (tag === "p" || tag === "span" || tag === "div") return text.length > 0 ? trimLabel(text, 56) : "Text";
+ if (tag === "img") return "Image";
+ if (tag === "video") return "Video";
+ if (tag === "audio") return "Audio";
+ if (tag === "svg") return "Shape";
+ if (el.getAttribute("data-composition-src")) return "Composition";
+ if (tag === "section") return "Section";
+ return `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`;
+ }
+
+ function getPickCandidatesFromPoint(clientX: number, clientY: number, limit?: number): Element[] {
+ const maxCandidates = typeof limit === "number" && limit > 0 ? limit : 8;
+ let raw: Element[] = [];
+ if (document.elementsFromPoint) {
+ raw = document.elementsFromPoint(clientX, clientY);
+ } else if (document.elementFromPoint) {
+ const single = document.elementFromPoint(clientX, clientY);
+ raw = single ? [single] : [];
+ }
+ const dedupe: Record = {};
+ const candidates: Element[] = [];
+ for (let i = 0; i < raw.length; i += 1) {
+ const node = raw[i];
+ if (!isPickableElement(node)) continue;
+ const key = `${node.tagName}::${(node as HTMLElement).id || ""}::${i}`;
+ if (dedupe[key]) continue;
+ dedupe[key] = true;
+ candidates.push(node);
+ if (candidates.length >= maxCandidates) break;
+ }
+ return candidates;
+ }
+
+ function extractElementInfo(el: Element): RuntimePickerElementInfo {
+ const rect = el.getBoundingClientRect();
+ const dataAttributes: Record = {};
+ for (let i = 0; i < el.attributes.length; i += 1) {
+ const attr = el.attributes[i];
+ if (attr.name.startsWith("data-")) {
+ dataAttributes[attr.name] = attr.value;
+ }
+ }
+ const htmlEl = el as HTMLElement;
+ return {
+ id: htmlEl.id || null,
+ tagName: el.tagName.toLowerCase(),
+ selector: buildElementSelector(el),
+ label: buildElementLabel(el),
+ boundingBox: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+ textContent: el.textContent ? el.textContent.trim().slice(0, 200) : null,
+ src: el.getAttribute("src") || el.getAttribute("data-composition-src") || null,
+ dataAttributes,
+ };
+ }
+
+ function getPickInfosFromPoint(clientX: number, clientY: number, limit?: number): RuntimePickerElementInfo[] {
+ return getPickCandidatesFromPoint(clientX, clientY, limit).map(extractElementInfo);
+ }
+
+ function onPickMouseMove(event: MouseEvent): void {
+ if (!pickModeActive) return;
+ const candidates = getPickCandidatesFromPoint(event.clientX, event.clientY, 1);
+ const target = candidates[0] ?? (event.target instanceof Element ? event.target : null);
+ if (!isPickableElement(target)) return;
+ if (pickModeHighlightEl === target) return;
+ if (pickModeHighlightEl) {
+ pickModeHighlightEl.classList.remove("__hf-pick-highlight");
+ }
+ pickModeHighlightEl = target;
+ target.classList.add("__hf-pick-highlight");
+ const info = extractElementInfo(target);
+ setLastHoveredInfo(info);
+ deps.postMessage({ source: "hf-preview", type: "element-hovered", elementInfo: info });
+ }
+
+ function onPickClick(event: MouseEvent): void {
+ if (!pickModeActive) return;
+ event.preventDefault();
+ event.stopPropagation();
+ event.stopImmediatePropagation();
+ const infos = getPickInfosFromPoint(event.clientX, event.clientY, 8);
+ if (infos.length === 0) return;
+ setLastHoveredInfo(infos[0] ?? null);
+ deps.postMessage({
+ source: "hf-preview",
+ type: "element-pick-candidates",
+ candidates: infos,
+ selectedIndex: 0,
+ point: { x: event.clientX, y: event.clientY },
+ });
+ }
+
+ function onPickKeyDown(event: KeyboardEvent): void {
+ if (event.key !== "Escape") return;
+ disablePickMode();
+ deps.postMessage({ source: "hf-preview", type: "pick-mode-cancelled" });
+ }
+
+ function enablePickMode(): void {
+ if (pickModeActive) return;
+ pickModeActive = true;
+ pickModeStyleEl = document.createElement("style");
+ pickModeStyleEl.textContent = [
+ ".__hf-pick-highlight { outline: 2px solid #4f8cf7 !important; outline-offset: 2px; cursor: crosshair !important; }",
+ ".__hf-pick-active * { cursor: crosshair !important; }",
+ ].join("\n");
+ document.head.appendChild(pickModeStyleEl);
+ document.body.classList.add("__hf-pick-active");
+ document.addEventListener("mousemove", onPickMouseMove, true);
+ document.addEventListener("click", onPickClick, true);
+ document.addEventListener("keydown", onPickKeyDown, true);
+ emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: true, timestamp: Date.now() });
+ }
+
+ function disablePickMode(): void {
+ if (!pickModeActive) return;
+ pickModeActive = false;
+ if (pickModeHighlightEl) {
+ pickModeHighlightEl.classList.remove("__hf-pick-highlight");
+ pickModeHighlightEl = null;
+ }
+ if (pickModeStyleEl) {
+ pickModeStyleEl.remove();
+ pickModeStyleEl = null;
+ }
+ document.body.classList.remove("__hf-pick-active");
+ document.removeEventListener("mousemove", onPickMouseMove, true);
+ document.removeEventListener("click", onPickClick, true);
+ document.removeEventListener("keydown", onPickKeyDown, true);
+ emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: false, timestamp: Date.now() });
+ }
+
+ function installPickerApi(): void {
+ window.__HF_PICKER_API = {
+ enable: enablePickMode,
+ disable: disablePickMode,
+ isActive: () => pickModeActive,
+ getHovered: () => pickLastHoveredInfo,
+ getSelected: () => pickLastSelectedInfo,
+ getCandidatesAtPoint: (clientX, clientY, limit) =>
+ Number.isFinite(clientX) && Number.isFinite(clientY) ? getPickInfosFromPoint(clientX, clientY, limit) : [],
+ pickAtPoint: (clientX, clientY, index) => {
+ if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return null;
+ const infos = getPickInfosFromPoint(clientX, clientY, 8);
+ if (!infos.length) return null;
+ const safeIndex = Math.max(0, Math.min(infos.length - 1, Number(index ?? 0)));
+ const selected = infos[safeIndex] ?? null;
+ if (!selected) return null;
+ setLastSelectedInfo(selected);
+ deps.postMessage({ source: "hf-preview", type: "element-picked", elementInfo: selected });
+ disablePickMode();
+ return selected;
+ },
+ pickManyAtPoint: (clientX, clientY, indexes) => {
+ if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return [];
+ const infos = getPickInfosFromPoint(clientX, clientY, 8);
+ if (!infos.length) return [];
+ const selected: RuntimePickerElementInfo[] = [];
+ const rawIndexes = Array.isArray(indexes) ? indexes : [0];
+ for (const rawIndex of rawIndexes) {
+ const idx = Math.max(0, Math.min(infos.length - 1, Math.floor(Number(rawIndex))));
+ const info = infos[idx];
+ if (!info) continue;
+ const duplicate = selected.some((item) => item.selector === info.selector && item.tagName === info.tagName);
+ if (!duplicate) selected.push(info);
+ }
+ if (!selected.length) return [];
+ setLastSelectedInfo(selected[0] ?? null);
+ deps.postMessage({ source: "hf-preview", type: "element-picked-many", elementInfos: selected });
+ disablePickMode();
+ return selected;
+ },
+ };
+ emitPickerRuntimeEvent("hyperframe:picker:api-ready", { hasApi: true, timestamp: Date.now() });
+ }
+
+ return { enablePickMode, disablePickMode, installPickerApi };
+}
diff --git a/packages/core/src/runtime/player.test.ts b/packages/core/src/runtime/player.test.ts
new file mode 100644
index 000000000..14453585e
--- /dev/null
+++ b/packages/core/src/runtime/player.test.ts
@@ -0,0 +1,213 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createRuntimePlayer } from "./player";
+import type { RuntimeTimelineLike } from "./types";
+
+function createMockTimeline(opts?: { time?: number; duration?: number }): RuntimeTimelineLike {
+ const state = { time: opts?.time ?? 0, duration: opts?.duration ?? 10, paused: false };
+ return {
+ play: vi.fn(() => { state.paused = false; }),
+ pause: vi.fn(() => { state.paused = true; }),
+ seek: vi.fn((t: number) => { state.time = t; }),
+ totalTime: vi.fn((t: number) => { state.time = t; }),
+ time: vi.fn(() => state.time),
+ duration: vi.fn(() => state.duration),
+ add: vi.fn(),
+ paused: vi.fn((p?: boolean) => { if (p !== undefined) state.paused = p; }),
+ timeScale: vi.fn(),
+ set: vi.fn(),
+ };
+}
+
+function createMockDeps(timeline?: RuntimeTimelineLike | null) {
+ let isPlaying = false;
+ let playbackRate = 1;
+ return {
+ getTimeline: vi.fn(() => timeline ?? null),
+ setTimeline: vi.fn(),
+ getIsPlaying: vi.fn(() => isPlaying),
+ setIsPlaying: vi.fn((v: boolean) => { isPlaying = v; }),
+ getPlaybackRate: vi.fn(() => playbackRate),
+ setPlaybackRate: vi.fn((v: number) => { playbackRate = v; }),
+ getCanonicalFps: vi.fn(() => 30),
+ onSyncMedia: vi.fn(),
+ onStatePost: vi.fn(),
+ onDeterministicSeek: vi.fn(),
+ onDeterministicPause: vi.fn(),
+ onDeterministicPlay: vi.fn(),
+ onRenderFrameSeek: vi.fn(),
+ onShowNativeVideos: vi.fn(),
+ getSafeDuration: vi.fn(() => 10),
+ };
+}
+
+describe("createRuntimePlayer", () => {
+ describe("play", () => {
+ it("does nothing without a timeline", () => {
+ const deps = createMockDeps(null);
+ const player = createRuntimePlayer(deps);
+ player.play();
+ expect(deps.setIsPlaying).not.toHaveBeenCalled();
+ });
+
+ it("does nothing if already playing", () => {
+ const timeline = createMockTimeline();
+ const deps = createMockDeps(timeline);
+ deps.getIsPlaying.mockReturnValue(true);
+ const player = createRuntimePlayer(deps);
+ player.play();
+ expect(timeline.play).not.toHaveBeenCalled();
+ });
+
+ it("plays the timeline and updates state", () => {
+ const timeline = createMockTimeline({ time: 2, duration: 10 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ player.play();
+ expect(timeline.play).toHaveBeenCalled();
+ expect(deps.setIsPlaying).toHaveBeenCalledWith(true);
+ expect(deps.onDeterministicPlay).toHaveBeenCalled();
+ expect(deps.onShowNativeVideos).toHaveBeenCalled();
+ expect(deps.onStatePost).toHaveBeenCalledWith(true);
+ });
+
+ it("resets to 0 when at end of timeline", () => {
+ const timeline = createMockTimeline({ time: 10, duration: 10 });
+ const deps = createMockDeps(timeline);
+ deps.getSafeDuration.mockReturnValue(10);
+ const player = createRuntimePlayer(deps);
+ player.play();
+ expect(timeline.seek).toHaveBeenCalledWith(0, false);
+ expect(deps.onDeterministicSeek).toHaveBeenCalledWith(0);
+ });
+
+ it("sets timeScale to playbackRate", () => {
+ const timeline = createMockTimeline({ time: 0, duration: 10 });
+ const deps = createMockDeps(timeline);
+ deps.getPlaybackRate.mockReturnValue(2);
+ const player = createRuntimePlayer(deps);
+ player.play();
+ expect(timeline.timeScale).toHaveBeenCalledWith(2);
+ });
+ });
+
+ describe("pause", () => {
+ it("does nothing without a timeline", () => {
+ const deps = createMockDeps(null);
+ const player = createRuntimePlayer(deps);
+ player.pause();
+ expect(deps.setIsPlaying).not.toHaveBeenCalled();
+ });
+
+ it("pauses the timeline and syncs media", () => {
+ const timeline = createMockTimeline({ time: 5 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ player.pause();
+ expect(timeline.pause).toHaveBeenCalled();
+ expect(deps.setIsPlaying).toHaveBeenCalledWith(false);
+ expect(deps.onDeterministicSeek).toHaveBeenCalledWith(5);
+ expect(deps.onDeterministicPause).toHaveBeenCalled();
+ expect(deps.onSyncMedia).toHaveBeenCalledWith(5, false);
+ expect(deps.onRenderFrameSeek).toHaveBeenCalledWith(5);
+ expect(deps.onStatePost).toHaveBeenCalledWith(true);
+ });
+ });
+
+ describe("seek", () => {
+ it("does nothing without a timeline", () => {
+ const deps = createMockDeps(null);
+ const player = createRuntimePlayer(deps);
+ player.seek(5);
+ expect(deps.onDeterministicSeek).not.toHaveBeenCalled();
+ });
+
+ it("seeks to quantized time and pauses", () => {
+ const timeline = createMockTimeline({ duration: 10 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ player.seek(3);
+ expect(timeline.pause).toHaveBeenCalled();
+ expect(timeline.totalTime).toHaveBeenCalled();
+ expect(deps.setIsPlaying).toHaveBeenCalledWith(false);
+ expect(deps.onSyncMedia).toHaveBeenCalled();
+ expect(deps.onStatePost).toHaveBeenCalledWith(true);
+ });
+
+ it("clamps negative time to 0", () => {
+ const timeline = createMockTimeline({ duration: 10 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ player.seek(-5);
+ expect(deps.onDeterministicSeek).toHaveBeenCalledWith(0);
+ });
+
+ it("handles NaN time", () => {
+ const timeline = createMockTimeline({ duration: 10 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ player.seek(NaN);
+ expect(deps.onDeterministicSeek).toHaveBeenCalledWith(0);
+ });
+ });
+
+ describe("renderSeek", () => {
+ it("seeks deterministically for render pipeline", () => {
+ const timeline = createMockTimeline({ duration: 10 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ player.renderSeek(5);
+ expect(timeline.pause).toHaveBeenCalled();
+ expect(deps.setIsPlaying).toHaveBeenCalledWith(false);
+ expect(deps.onRenderFrameSeek).toHaveBeenCalled();
+ });
+ });
+
+ describe("getters", () => {
+ it("getTime returns timeline time", () => {
+ const timeline = createMockTimeline({ time: 7.5 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ expect(player.getTime()).toBe(7.5);
+ });
+
+ it("getDuration returns timeline duration", () => {
+ const timeline = createMockTimeline({ duration: 30 });
+ const deps = createMockDeps(timeline);
+ const player = createRuntimePlayer(deps);
+ expect(player.getDuration()).toBe(30);
+ });
+
+ it("getTime returns 0 without timeline", () => {
+ const deps = createMockDeps(null);
+ const player = createRuntimePlayer(deps);
+ expect(player.getTime()).toBe(0);
+ });
+
+ it("getDuration returns 0 without timeline", () => {
+ const deps = createMockDeps(null);
+ const player = createRuntimePlayer(deps);
+ expect(player.getDuration()).toBe(0);
+ });
+
+ it("isPlaying delegates to deps", () => {
+ const deps = createMockDeps(null);
+ deps.getIsPlaying.mockReturnValue(true);
+ const player = createRuntimePlayer(deps);
+ expect(player.isPlaying()).toBe(true);
+ });
+
+ it("setPlaybackRate delegates to deps", () => {
+ const deps = createMockDeps(null);
+ const player = createRuntimePlayer(deps);
+ player.setPlaybackRate(1.5);
+ expect(deps.setPlaybackRate).toHaveBeenCalledWith(1.5);
+ });
+
+ it("getPlaybackRate delegates to deps", () => {
+ const deps = createMockDeps(null);
+ deps.getPlaybackRate.mockReturnValue(2);
+ const player = createRuntimePlayer(deps);
+ expect(player.getPlaybackRate()).toBe(2);
+ });
+ });
+});
diff --git a/packages/core/src/runtime/player.ts b/packages/core/src/runtime/player.ts
new file mode 100644
index 000000000..7fcc38122
--- /dev/null
+++ b/packages/core/src/runtime/player.ts
@@ -0,0 +1,103 @@
+import type { RuntimePlayer, RuntimeTimelineLike } from "./types";
+import { quantizeTimeToFrame } from "../inline-scripts/parityContract";
+
+type PlayerDeps = {
+ getTimeline: () => RuntimeTimelineLike | null;
+ setTimeline: (timeline: RuntimeTimelineLike | null) => void;
+ getIsPlaying: () => boolean;
+ setIsPlaying: (playing: boolean) => void;
+ getPlaybackRate: () => number;
+ setPlaybackRate: (rate: number) => void;
+ getCanonicalFps: () => number;
+ onSyncMedia: (timeSeconds: number, playing: boolean) => void;
+ onStatePost: (force: boolean) => void;
+ onDeterministicSeek: (timeSeconds: number) => void;
+ onDeterministicPause: () => void;
+ onDeterministicPlay: () => void;
+ onRenderFrameSeek: (timeSeconds: number) => void;
+ onShowNativeVideos: () => void;
+ getSafeDuration?: () => number;
+};
+
+function seekTimelineDeterministically(
+ timeline: RuntimeTimelineLike,
+ timeSeconds: number,
+ canonicalFps: number,
+): number {
+ const quantized = quantizeTimeToFrame(timeSeconds, canonicalFps);
+ timeline.pause();
+ if (typeof timeline.totalTime === "function") {
+ timeline.totalTime(quantized, false);
+ } else {
+ timeline.seek(quantized, false);
+ }
+ return quantized;
+}
+
+export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {
+ return {
+ _timeline: null,
+ play: () => {
+ const timeline = deps.getTimeline();
+ if (!timeline || deps.getIsPlaying()) return;
+ const safeDuration = Math.max(0, Number(deps.getSafeDuration?.() ?? timeline.duration() ?? 0) || 0);
+ if (safeDuration > 0) {
+ const currentTime = Math.max(0, Number(timeline.time()) || 0);
+ if (currentTime >= safeDuration) {
+ timeline.pause();
+ timeline.seek(0, false);
+ deps.onDeterministicSeek(0);
+ deps.setIsPlaying(false);
+ deps.onSyncMedia(0, false);
+ deps.onRenderFrameSeek(0);
+ }
+ }
+ if (typeof timeline.timeScale === "function") {
+ timeline.timeScale(deps.getPlaybackRate());
+ }
+ timeline.play();
+ deps.onDeterministicPlay();
+ deps.setIsPlaying(true);
+ deps.onShowNativeVideos();
+ deps.onStatePost(true);
+ },
+ pause: () => {
+ const timeline = deps.getTimeline();
+ if (!timeline) return;
+ timeline.pause();
+ const time = Math.max(0, Number(timeline.time()) || 0);
+ deps.onDeterministicSeek(time);
+ deps.onDeterministicPause();
+ deps.setIsPlaying(false);
+ deps.onSyncMedia(time, false);
+ deps.onRenderFrameSeek(time);
+ deps.onStatePost(true);
+ },
+ seek: (timeSeconds: number) => {
+ const timeline = deps.getTimeline();
+ if (!timeline) return;
+ const safeTime = Math.max(0, Number(timeSeconds) || 0);
+ const quantized = seekTimelineDeterministically(timeline, safeTime, deps.getCanonicalFps());
+ deps.onDeterministicSeek(quantized);
+ deps.setIsPlaying(false);
+ deps.onSyncMedia(quantized, false);
+ deps.onRenderFrameSeek(quantized);
+ deps.onStatePost(true);
+ },
+ renderSeek: (timeSeconds: number) => {
+ const timeline = deps.getTimeline();
+ if (!timeline) return;
+ const quantized = seekTimelineDeterministically(timeline, timeSeconds, deps.getCanonicalFps());
+ deps.onDeterministicSeek(quantized);
+ deps.setIsPlaying(false);
+ deps.onSyncMedia(quantized, false);
+ deps.onRenderFrameSeek(quantized);
+ deps.onStatePost(true);
+ },
+ getTime: () => Number(deps.getTimeline()?.time() ?? 0),
+ getDuration: () => Number(deps.getTimeline()?.duration() ?? 0),
+ isPlaying: () => deps.getIsPlaying(),
+ setPlaybackRate: (rate: number) => deps.setPlaybackRate(rate),
+ getPlaybackRate: () => deps.getPlaybackRate(),
+ };
+}
diff --git a/packages/core/src/runtime/startResolver.test.ts b/packages/core/src/runtime/startResolver.test.ts
new file mode 100644
index 000000000..884307335
--- /dev/null
+++ b/packages/core/src/runtime/startResolver.test.ts
@@ -0,0 +1,225 @@
+import { describe, it, expect, afterEach, beforeAll } from "vitest";
+import { createRuntimeStartTimeResolver } from "./startResolver";
+
+// jsdom doesn't provide CSS.escape — polyfill it
+beforeAll(() => {
+ if (typeof globalThis.CSS === "undefined") {
+ (globalThis as any).CSS = {};
+ }
+ if (typeof CSS.escape !== "function") {
+ CSS.escape = (value: string) =>
+ value.replace(/([^\w-])/g, "\\$1");
+ }
+});
+
+describe("createRuntimeStartTimeResolver", () => {
+ afterEach(() => {
+ document.body.innerHTML = "";
+ });
+
+ describe("resolveStartForElement", () => {
+ it("resolves absolute numeric data-start", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-start", "5");
+ document.body.appendChild(el);
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveStartForElement(el)).toBe(5);
+ });
+
+ it("resolves zero start", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-start", "0");
+ document.body.appendChild(el);
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveStartForElement(el)).toBe(0);
+ });
+
+ it("returns fallback when no data-start", () => {
+ const el = document.createElement("div");
+ document.body.appendChild(el);
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveStartForElement(el, 3)).toBe(3);
+ });
+
+ it("resolves reference to another element (after end)", () => {
+ const a = document.createElement("div");
+ a.id = "scene-1";
+ a.setAttribute("data-start", "2");
+ a.setAttribute("data-duration", "3");
+ document.body.appendChild(a);
+
+ const b = document.createElement("div");
+ b.setAttribute("data-start", "scene-1");
+ document.body.appendChild(b);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ // scene-1 starts at 2, duration 3, so b starts at 2+3 = 5
+ expect(resolver.resolveStartForElement(b)).toBe(5);
+ });
+
+ it("resolves reference with positive offset", () => {
+ const a = document.createElement("div");
+ a.id = "intro";
+ a.setAttribute("data-start", "0");
+ a.setAttribute("data-duration", "5");
+ document.body.appendChild(a);
+
+ const b = document.createElement("div");
+ b.setAttribute("data-start", "intro + 2");
+ document.body.appendChild(b);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ // intro ends at 5, offset +2 → 7
+ expect(resolver.resolveStartForElement(b)).toBe(7);
+ });
+
+ it("resolves reference with negative offset", () => {
+ const a = document.createElement("div");
+ a.id = "scene-a";
+ a.setAttribute("data-start", "0");
+ a.setAttribute("data-duration", "10");
+ document.body.appendChild(a);
+
+ const b = document.createElement("div");
+ b.setAttribute("data-start", "scene-a - 3");
+ document.body.appendChild(b);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ // scene-a ends at 10, offset -3 → 7
+ expect(resolver.resolveStartForElement(b)).toBe(7);
+ });
+
+ it("clamps resolved start to 0", () => {
+ const a = document.createElement("div");
+ a.id = "clip";
+ a.setAttribute("data-start", "1");
+ a.setAttribute("data-duration", "2");
+ document.body.appendChild(a);
+
+ const b = document.createElement("div");
+ b.setAttribute("data-start", "clip - 100");
+ document.body.appendChild(b);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveStartForElement(b)).toBe(0);
+ });
+
+ it("handles circular references gracefully", () => {
+ const a = document.createElement("div");
+ a.id = "a";
+ a.setAttribute("data-start", "b");
+ document.body.appendChild(a);
+
+ const b = document.createElement("div");
+ b.id = "b";
+ b.setAttribute("data-start", "a");
+ document.body.appendChild(b);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ // Should not infinite loop — returns fallback
+ expect(resolver.resolveStartForElement(a)).toBeGreaterThanOrEqual(0);
+ expect(resolver.resolveStartForElement(b)).toBeGreaterThanOrEqual(0);
+ });
+
+ it("uses data-composition-id selector for lookup", () => {
+ const comp = document.createElement("div");
+ comp.setAttribute("data-composition-id", "hero");
+ comp.setAttribute("data-start", "0");
+ comp.setAttribute("data-duration", "5");
+ document.body.appendChild(comp);
+
+ const after = document.createElement("div");
+ after.setAttribute("data-start", "hero");
+ document.body.appendChild(after);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveStartForElement(after)).toBe(5);
+ });
+
+ it("returns fallback when reference target not found", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-start", "nonexistent");
+ document.body.appendChild(el);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveStartForElement(el, 0)).toBe(0);
+ });
+
+ it("caches resolved values (second call is same result)", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-start", "3.5");
+ document.body.appendChild(el);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ const first = resolver.resolveStartForElement(el);
+ const second = resolver.resolveStartForElement(el);
+ expect(first).toBe(second);
+ expect(first).toBe(3.5);
+ });
+ });
+
+ describe("resolveDurationForElement", () => {
+ it("resolves explicit data-duration", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-duration", "7");
+ document.body.appendChild(el);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveDurationForElement(el)).toBe(7);
+ });
+
+ it("resolves from data-end minus start", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-start", "2");
+ el.setAttribute("data-end", "8");
+ document.body.appendChild(el);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveDurationForElement(el)).toBe(6);
+ });
+
+ it("returns null when no duration info available", () => {
+ const el = document.createElement("div");
+ document.body.appendChild(el);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ expect(resolver.resolveDurationForElement(el)).toBeNull();
+ });
+
+ it("resolves from timeline registry for compositions", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-composition-id", "comp-1");
+ document.body.appendChild(el);
+
+ const mockTimeline = { duration: () => 12, time: () => 0, play: () => {}, pause: () => {}, seek: () => {}, add: () => {}, paused: () => {}, set: () => {} };
+ const resolver = createRuntimeStartTimeResolver({
+ timelineRegistry: { "comp-1": mockTimeline as any },
+ });
+ expect(resolver.resolveDurationForElement(el)).toBe(12);
+ });
+
+ it("prefers data-duration over timeline registry", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-composition-id", "comp-1");
+ el.setAttribute("data-duration", "5");
+ document.body.appendChild(el);
+
+ const mockTimeline = { duration: () => 12, time: () => 0, play: () => {}, pause: () => {}, seek: () => {}, add: () => {}, paused: () => {}, set: () => {} };
+ const resolver = createRuntimeStartTimeResolver({
+ timelineRegistry: { "comp-1": mockTimeline as any },
+ });
+ expect(resolver.resolveDurationForElement(el)).toBe(5);
+ });
+
+ it("caches duration results", () => {
+ const el = document.createElement("div");
+ el.setAttribute("data-duration", "4");
+ document.body.appendChild(el);
+
+ const resolver = createRuntimeStartTimeResolver({});
+ const first = resolver.resolveDurationForElement(el);
+ const second = resolver.resolveDurationForElement(el);
+ expect(first).toBe(second);
+ });
+ });
+});
diff --git a/packages/core/src/runtime/startResolver.ts b/packages/core/src/runtime/startResolver.ts
new file mode 100644
index 000000000..620a984a9
--- /dev/null
+++ b/packages/core/src/runtime/startResolver.ts
@@ -0,0 +1,151 @@
+import type { RuntimeTimelineLike } from "./types";
+
+type ReferenceExpression =
+ | {
+ kind: "absolute";
+ value: number;
+ }
+ | {
+ kind: "reference";
+ refId: string;
+ offset: number;
+ };
+
+function parseNumeric(value: string | null | undefined): number | null {
+ const parsed = Number(value);
+ return Number.isFinite(parsed) ? parsed : null;
+}
+
+function parseStartExpression(raw: string | null | undefined): ReferenceExpression | null {
+ const normalized = (raw ?? "").trim();
+ if (!normalized) return null;
+ const absolute = parseNumeric(normalized);
+ if (absolute != null) {
+ return { kind: "absolute", value: absolute };
+ }
+ const referenceMatch = normalized.match(/^([A-Za-z0-9_.:-]+)(?:\s*([+-])\s*([0-9]*\.?[0-9]+))?$/);
+ if (!referenceMatch) return null;
+ const refId = (referenceMatch[1] ?? "").trim();
+ if (!refId) return null;
+ const sign = referenceMatch[2] ?? "+";
+ const offsetRaw = referenceMatch[3] ?? "0";
+ const parsedOffset = Number.parseFloat(offsetRaw);
+ const offsetMagnitude = Number.isFinite(parsedOffset) ? Math.max(0, parsedOffset) : 0;
+ const offset = sign === "-" ? -offsetMagnitude : offsetMagnitude;
+ return { kind: "reference", refId, offset };
+}
+
+export function createRuntimeStartTimeResolver(params: {
+ timelineRegistry?: Record;
+}): {
+ resolveStartForElement: (element: Element, fallback?: number) => number;
+ resolveDurationForElement: (element: Element) => number | null;
+} {
+ const timelineRegistry = params.timelineRegistry ?? {};
+ const startCache = new WeakMap();
+ const durationCache = new WeakMap();
+ const visiting = new Set();
+
+ const findReferenceTarget = (refId: string): Element | null => {
+ const byId = document.getElementById(refId);
+ if (byId) return byId;
+ return (document.querySelector(`[data-composition-id="${CSS.escape(refId)}"]`) as Element | null) ?? null;
+ };
+
+ const resolveDurationForElement = (element: Element): number | null => {
+ const cached = durationCache.get(element);
+ if (cached !== undefined) return cached;
+ let resolved: number | null = null;
+ const durationAttr = parseNumeric(element.getAttribute("data-duration"));
+ if (durationAttr != null && durationAttr > 0) {
+ resolved = durationAttr;
+ }
+ if (resolved == null || resolved <= 0) {
+ const endAttr = parseNumeric(element.getAttribute("data-end"));
+ if (endAttr != null) {
+ const start = resolveStartForElementInternal(element, 0);
+ const delta = endAttr - start;
+ if (Number.isFinite(delta) && delta > 0) {
+ resolved = delta;
+ }
+ }
+ }
+ if ((resolved == null || resolved <= 0) && element instanceof HTMLMediaElement) {
+ const playbackStart =
+ parseNumeric(element.getAttribute("data-playback-start")) ??
+ parseNumeric(element.getAttribute("data-media-start")) ??
+ 0;
+ if (Number.isFinite(element.duration) && element.duration > playbackStart) {
+ resolved = element.duration - playbackStart;
+ }
+ }
+ if (resolved == null || resolved <= 0) {
+ const compositionId = element.getAttribute("data-composition-id");
+ if (compositionId) {
+ const timeline = timelineRegistry[compositionId] ?? null;
+ if (timeline && typeof timeline.duration === "function") {
+ try {
+ const timelineDuration = Number(timeline.duration());
+ if (Number.isFinite(timelineDuration) && timelineDuration > 0) {
+ resolved = timelineDuration;
+ }
+ } catch {
+ // ignore broken timeline impls
+ }
+ }
+ }
+ }
+ if (resolved != null && Number.isFinite(resolved) && resolved > 0) {
+ durationCache.set(element, resolved);
+ return resolved;
+ }
+ durationCache.set(element, null);
+ return null;
+ };
+
+ const resolveStartForElementInternal = (element: Element, fallback: number): number => {
+ const cached = startCache.get(element);
+ if (cached !== undefined) {
+ return cached == null ? fallback : cached;
+ }
+ if (visiting.has(element)) {
+ return fallback;
+ }
+ visiting.add(element);
+ try {
+ const expression = parseStartExpression(element.getAttribute("data-start"));
+ if (!expression) {
+ startCache.set(element, fallback);
+ return fallback;
+ }
+ if (expression.kind === "absolute") {
+ const absolute = Math.max(0, expression.value);
+ startCache.set(element, absolute);
+ return absolute;
+ }
+ const target = findReferenceTarget(expression.refId);
+ if (!target) {
+ startCache.set(element, fallback);
+ return fallback;
+ }
+ const targetStart = resolveStartForElementInternal(target, 0);
+ const targetDuration = resolveDurationForElement(target);
+ if (targetDuration == null || targetDuration <= 0) {
+ const unresolved = Math.max(0, targetStart + expression.offset);
+ startCache.set(element, unresolved);
+ return unresolved;
+ }
+ const resolved = Math.max(0, targetStart + targetDuration + expression.offset);
+ startCache.set(element, resolved);
+ return resolved;
+ } finally {
+ visiting.delete(element);
+ }
+ };
+
+ return {
+ resolveStartForElement: (element: Element, fallback = 0) =>
+ resolveStartForElementInternal(element, Math.max(0, fallback)),
+ resolveDurationForElement: (element: Element) => resolveDurationForElement(element),
+ };
+}
diff --git a/packages/core/src/runtime/state.test.ts b/packages/core/src/runtime/state.test.ts
new file mode 100644
index 000000000..b470dda04
--- /dev/null
+++ b/packages/core/src/runtime/state.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { createRuntimeState } from "./state";
+
+describe("createRuntimeState", () => {
+ it("returns a fresh state with correct defaults", () => {
+ const state = createRuntimeState();
+ expect(state.isPlaying).toBe(false);
+ expect(state.currentTime).toBe(0);
+ expect(state.canonicalFps).toBe(30);
+ expect(state.playbackRate).toBe(1);
+ expect(state.bridgeMuted).toBe(false);
+ expect(state.capturedTimeline).toBeNull();
+ expect(state.rafId).toBeNull();
+ expect(state.tornDown).toBe(false);
+ expect(state.maxTimelineDurationSeconds).toBe(1800);
+ expect(state.parityModeEnabled).toBe(true);
+ });
+
+ it("returns independent instances", () => {
+ const a = createRuntimeState();
+ const b = createRuntimeState();
+ a.isPlaying = true;
+ a.currentTime = 5;
+ expect(b.isPlaying).toBe(false);
+ expect(b.currentTime).toBe(0);
+ });
+
+ it("bridge state defaults are correct", () => {
+ const state = createRuntimeState();
+ expect(state.bridgeLastPostedFrame).toBe(-1);
+ expect(state.bridgeLastPostedAt).toBe(0);
+ expect(state.bridgeLastPostedPlaying).toBe(false);
+ expect(state.bridgeLastPostedMuted).toBe(false);
+ expect(state.bridgeMaxPostIntervalMs).toBe(80);
+ });
+
+ it("cached arrays start empty", () => {
+ const state = createRuntimeState();
+ expect(state.cachedTimedMediaEls).toEqual([]);
+ expect(state.cachedMediaClips).toEqual([]);
+ expect(state.cachedVideoClips).toEqual([]);
+ expect(state.injectedCompStyles).toEqual([]);
+ expect(state.injectedCompScripts).toEqual([]);
+ expect(state.deterministicAdapters).toEqual([]);
+ });
+
+ it("state is mutable", () => {
+ const state = createRuntimeState();
+ state.isPlaying = true;
+ state.currentTime = 12.5;
+ state.canonicalFps = 60;
+ state.tornDown = true;
+ expect(state.isPlaying).toBe(true);
+ expect(state.currentTime).toBe(12.5);
+ expect(state.canonicalFps).toBe(60);
+ expect(state.tornDown).toBe(true);
+ });
+});
diff --git a/packages/core/src/runtime/state.ts b/packages/core/src/runtime/state.ts
new file mode 100644
index 000000000..15c8b163f
--- /dev/null
+++ b/packages/core/src/runtime/state.ts
@@ -0,0 +1,66 @@
+import type { RuntimeDeterministicAdapter, RuntimeTimelineLike } from "./types";
+import type { RuntimeMediaClip } from "./media";
+
+export type RuntimeState = {
+ capturedTimeline: RuntimeTimelineLike | null;
+ isPlaying: boolean;
+ rafId: number | null;
+ currentTime: number;
+ deterministicAdapters: RuntimeDeterministicAdapter[];
+ parityModeEnabled: boolean;
+ canonicalFps: number;
+ bridgeMuted: boolean;
+ playbackRate: number;
+ bridgeLastPostedFrame: number;
+ bridgeLastPostedAt: number;
+ bridgeLastPostedPlaying: boolean;
+ bridgeLastPostedMuted: boolean;
+ bridgeMaxPostIntervalMs: number;
+ timelinePollIntervalId: ReturnType | null;
+ controlBridgeHandler: ((event: MessageEvent) => void) | null;
+ clampDurationLoggedRaw: number | null;
+ beforeUnloadHandler: (() => void) | null;
+ domReadyHandler: (() => void) | null;
+ injectedCompStyles: HTMLStyleElement[];
+ injectedCompScripts: HTMLScriptElement[];
+ cachedTimedMediaEls: Array;
+ cachedMediaClips: RuntimeMediaClip[];
+ cachedVideoClips: RuntimeMediaClip[];
+ cachedMediaTimelineDurationSeconds: number;
+ tornDown: boolean;
+ maxTimelineDurationSeconds: number;
+ nativeVisualWatchdogTick: number;
+};
+
+export function createRuntimeState(): RuntimeState {
+ return {
+ capturedTimeline: null,
+ isPlaying: false,
+ rafId: null,
+ currentTime: 0,
+ deterministicAdapters: [],
+ parityModeEnabled: true,
+ canonicalFps: 30,
+ bridgeMuted: false,
+ playbackRate: 1,
+ bridgeLastPostedFrame: -1,
+ bridgeLastPostedAt: 0,
+ bridgeLastPostedPlaying: false,
+ bridgeLastPostedMuted: false,
+ bridgeMaxPostIntervalMs: 80,
+ timelinePollIntervalId: null,
+ controlBridgeHandler: null,
+ clampDurationLoggedRaw: null,
+ beforeUnloadHandler: null,
+ domReadyHandler: null,
+ injectedCompStyles: [],
+ injectedCompScripts: [],
+ cachedTimedMediaEls: [],
+ cachedMediaClips: [],
+ cachedVideoClips: [],
+ cachedMediaTimelineDurationSeconds: 0,
+ tornDown: false,
+ maxTimelineDurationSeconds: 1800,
+ nativeVisualWatchdogTick: 0,
+ };
+}
diff --git a/packages/core/src/runtime/timeline.test.ts b/packages/core/src/runtime/timeline.test.ts
new file mode 100644
index 000000000..238e3eb21
--- /dev/null
+++ b/packages/core/src/runtime/timeline.test.ts
@@ -0,0 +1,276 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { collectRuntimeTimelinePayload } from "./timeline";
+
+describe("collectRuntimeTimelinePayload", () => {
+ afterEach(() => {
+ document.body.innerHTML = "";
+ delete (window as any).__timelines;
+ });
+
+ const defaultParams = { canonicalFps: 30, maxTimelineDurationSeconds: 1800 };
+
+ it("returns minimal payload for empty document", () => {
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.source).toBe("hf-preview");
+ expect(result.type).toBe("timeline");
+ expect(result.clips).toEqual([]);
+ expect(result.scenes).toEqual([]);
+ expect(result.durationInFrames).toBeGreaterThanOrEqual(1);
+ expect(result.compositionWidth).toBe(1920);
+ expect(result.compositionHeight).toBe(1080);
+ });
+
+ it("collects clips from elements with data-start and data-duration", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const clip = document.createElement("div");
+ clip.id = "text-1";
+ clip.setAttribute("data-start", "1");
+ clip.setAttribute("data-duration", "3");
+ clip.setAttribute("data-track-index", "0");
+ root.appendChild(clip);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips).toHaveLength(1);
+ expect(result.clips[0].id).toBe("text-1");
+ expect(result.clips[0].start).toBe(1);
+ expect(result.clips[0].duration).toBe(3);
+ expect(result.clips[0].kind).toBe("element");
+ });
+
+ it("identifies video clips by tag", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const video = document.createElement("video");
+ video.id = "v1";
+ video.setAttribute("data-start", "0");
+ video.setAttribute("data-duration", "5");
+ root.appendChild(video);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips[0].kind).toBe("video");
+ });
+
+ it("identifies audio clips by tag", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const audio = document.createElement("audio");
+ audio.id = "a1";
+ audio.setAttribute("data-start", "0");
+ audio.setAttribute("data-duration", "5");
+ root.appendChild(audio);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips[0].kind).toBe("audio");
+ });
+
+ it("identifies image clips by tag", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const img = document.createElement("img");
+ img.id = "img1";
+ img.setAttribute("data-start", "0");
+ img.setAttribute("data-duration", "5");
+ root.appendChild(img);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips[0].kind).toBe("image");
+ });
+
+ it("identifies composition clips", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "20");
+ document.body.appendChild(root);
+
+ const comp = document.createElement("div");
+ comp.id = "scene-1";
+ comp.setAttribute("data-composition-id", "scene-1");
+ comp.setAttribute("data-start", "0");
+ comp.setAttribute("data-duration", "10");
+ root.appendChild(comp);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips[0].kind).toBe("composition");
+ });
+
+ it("collects scenes from composition nodes", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "20");
+ document.body.appendChild(root);
+
+ const scene = document.createElement("div");
+ scene.setAttribute("data-composition-id", "scene-intro");
+ scene.setAttribute("data-start", "0");
+ scene.setAttribute("data-duration", "10");
+ scene.setAttribute("data-label", "Intro");
+ root.appendChild(scene);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.scenes).toHaveLength(1);
+ expect(result.scenes[0].id).toBe("scene-intro");
+ expect(result.scenes[0].label).toBe("Intro");
+ expect(result.scenes[0].start).toBe(0);
+ expect(result.scenes[0].duration).toBe(10);
+ });
+
+ it("skips caption and ambient compositions from scenes", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "20");
+ document.body.appendChild(root);
+
+ const caption = document.createElement("div");
+ caption.setAttribute("data-composition-id", "caption-1");
+ caption.setAttribute("data-start", "0");
+ caption.setAttribute("data-duration", "5");
+ root.appendChild(caption);
+
+ const ambient = document.createElement("div");
+ ambient.setAttribute("data-composition-id", "ambient-bg");
+ ambient.setAttribute("data-start", "0");
+ ambient.setAttribute("data-duration", "5");
+ root.appendChild(ambient);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.scenes).toHaveLength(0);
+ });
+
+ it("reads composition dimensions from root", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-width", "3840");
+ root.setAttribute("data-height", "2160");
+ root.setAttribute("data-duration", "5");
+ document.body.appendChild(root);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.compositionWidth).toBe(3840);
+ expect(result.compositionHeight).toBe(2160);
+ });
+
+ it("defaults composition dimensions to 1920x1080", () => {
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.compositionWidth).toBe(1920);
+ expect(result.compositionHeight).toBe(1080);
+ });
+
+ it("computes durationInFrames from max clip end", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const clip = document.createElement("div");
+ clip.setAttribute("data-start", "0");
+ clip.setAttribute("data-duration", "10");
+ root.appendChild(clip);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.durationInFrames).toBe(300); // 10s * 30fps
+ });
+
+ it("clamps duration to maxTimelineDurationSeconds", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "5000");
+ document.body.appendChild(root);
+
+ const clip = document.createElement("div");
+ clip.setAttribute("data-start", "0");
+ clip.setAttribute("data-duration", "5000");
+ root.appendChild(clip);
+
+ const result = collectRuntimeTimelinePayload({ canonicalFps: 30, maxTimelineDurationSeconds: 60 });
+ expect(result.durationInFrames).toBeLessThanOrEqual(60 * 30);
+ });
+
+ it("skips script/style/meta nodes", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const script = document.createElement("script");
+ script.setAttribute("data-start", "0");
+ script.setAttribute("data-duration", "5");
+ root.appendChild(script);
+
+ const style = document.createElement("style");
+ style.setAttribute("data-start", "0");
+ style.setAttribute("data-duration", "5");
+ root.appendChild(style);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips).toHaveLength(0);
+ });
+
+ it("resolves asset URLs from src attribute", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const img = document.createElement("img");
+ img.id = "hero";
+ img.setAttribute("src", "https://example.com/hero.jpg");
+ img.setAttribute("data-start", "0");
+ img.setAttribute("data-duration", "5");
+ root.appendChild(img);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips[0].assetUrl).toBe("https://example.com/hero.jpg");
+ });
+
+ it("uses label from data-timeline-label", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-duration", "10");
+ document.body.appendChild(root);
+
+ const clip = document.createElement("div");
+ clip.id = "clip-1";
+ clip.setAttribute("data-start", "0");
+ clip.setAttribute("data-duration", "5");
+ clip.setAttribute("data-timeline-label", "Hero Shot");
+ root.appendChild(clip);
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ expect(result.clips[0].label).toBe("Hero Shot");
+ });
+
+ it("handles timeline registry for composition duration", () => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ document.body.appendChild(root);
+
+ const comp = document.createElement("div");
+ comp.setAttribute("data-composition-id", "scene-1");
+ comp.setAttribute("data-start", "0");
+ root.appendChild(comp);
+
+ (window as any).__timelines = {
+ "main": { duration: () => 15, time: () => 0, play: () => {}, pause: () => {}, seek: () => {}, add: () => {}, paused: () => {}, set: () => {} },
+ "scene-1": { duration: () => 8, time: () => 0, play: () => {}, pause: () => {}, seek: () => {}, add: () => {}, paused: () => {}, set: () => {} },
+ };
+
+ const result = collectRuntimeTimelinePayload(defaultParams);
+ // scene-1 should get duration 8 from timeline registry
+ const sceneClip = result.clips.find(c => c.compositionId === "scene-1");
+ expect(sceneClip).toBeDefined();
+ expect(sceneClip?.duration).toBe(8);
+ });
+});
diff --git a/packages/core/src/runtime/timeline.ts b/packages/core/src/runtime/timeline.ts
new file mode 100644
index 000000000..5fce145a8
--- /dev/null
+++ b/packages/core/src/runtime/timeline.ts
@@ -0,0 +1,280 @@
+import type { RuntimeTimelineClip, RuntimeTimelineMessage, RuntimeTimelineScene, RuntimeTimelineLike } from "./types";
+import { createRuntimeStartTimeResolver } from "./startResolver";
+
+function parseNum(value: string | null | undefined): number | null {
+ const parsed = Number(value);
+ return Number.isFinite(parsed) ? parsed : null;
+}
+
+function toAbsoluteAssetUrl(rawValue: string | null | undefined): string | null {
+ const raw = String(rawValue ?? "").trim();
+ if (!raw) return null;
+ const lowered = raw.toLowerCase();
+ if (lowered.startsWith("data:") || lowered.startsWith("javascript:")) return null;
+ try {
+ return new URL(raw, document.baseURI).toString();
+ } catch {
+ return raw;
+ }
+}
+
+function resolveNodeAssetUrl(node: Element): string | null {
+ const src = node.getAttribute("src") ?? node.getAttribute("data-src");
+ if (src) return toAbsoluteAssetUrl(src);
+ const compositionSrc = node.getAttribute("data-composition-src");
+ if (compositionSrc) return toAbsoluteAssetUrl(compositionSrc);
+ const mediaDescendant = node.querySelector("img[src], video[src], audio[src], source[src]");
+ if (!mediaDescendant) return null;
+ return toAbsoluteAssetUrl(mediaDescendant.getAttribute("src"));
+}
+
+export function collectRuntimeTimelinePayload(params: {
+ canonicalFps: number;
+ maxTimelineDurationSeconds: number;
+}): RuntimeTimelineMessage {
+ const runtimeWindow = window as Window & {
+ __timelines?: Record;
+ };
+ const timelineRegistry = runtimeWindow.__timelines ?? {};
+ const startResolver = createRuntimeStartTimeResolver({
+ timelineRegistry,
+ });
+ const resolveTimelineDurationSeconds = (compositionId: string | null): number | null => {
+ if (!compositionId) return null;
+ const timeline = timelineRegistry[compositionId] ?? null;
+ if (!timeline || typeof timeline.duration !== "function") return null;
+ try {
+ const duration = Number(timeline.duration());
+ return Number.isFinite(duration) && duration > 0 ? duration : null;
+ } catch {
+ return null;
+ }
+ };
+ const resolveMediaElementDurationSeconds = (mediaEl: HTMLVideoElement | HTMLAudioElement): number | null => {
+ const declaredDuration = parseNum(mediaEl.getAttribute("data-duration"));
+ if (declaredDuration != null && declaredDuration > 0) {
+ return declaredDuration;
+ }
+ const playbackStart =
+ parseNum(mediaEl.getAttribute("data-playback-start")) ?? parseNum(mediaEl.getAttribute("data-media-start")) ?? 0;
+ if (Number.isFinite(mediaEl.duration) && mediaEl.duration > playbackStart) {
+ return Math.max(0, mediaEl.duration - playbackStart);
+ }
+ return null;
+ };
+ const resolveMediaWindowEndSeconds = (): number | null => {
+ const mediaNodes = Array.from(document.querySelectorAll("video[data-start], audio[data-start]")) as Array<
+ HTMLVideoElement | HTMLAudioElement
+ >;
+ if (mediaNodes.length === 0) return null;
+ let maxWindowEndSeconds = 0;
+ for (const mediaNode of mediaNodes) {
+ const start = startResolver.resolveStartForElement(mediaNode, 0);
+ if (!Number.isFinite(start)) continue;
+ const duration = resolveMediaElementDurationSeconds(mediaNode);
+ if (duration == null || duration <= 0) continue;
+ maxWindowEndSeconds = Math.max(maxWindowEndSeconds, Math.max(0, start) + duration);
+ }
+ return maxWindowEndSeconds > 0 ? maxWindowEndSeconds : null;
+ };
+ const isSceneLikeCompositionId = (compositionId: string): boolean => {
+ const normalized = compositionId.trim().toLowerCase();
+ if (!normalized || normalized === "main") return false;
+ if (normalized.includes("caption")) return false;
+ if (normalized.includes("ambient")) return false;
+ return true;
+ };
+ const resolveNearestCompositionContext = (
+ node: Element,
+ root: Element | null,
+ ): {
+ parentCompositionId: string | null;
+ compositionAncestors: string[];
+ inheritedStart: number | null;
+ inheritedDuration: number | null;
+ } => {
+ const ancestors: string[] = [];
+ let inheritedStart: number | null = null;
+ let inheritedDuration: number | null = null;
+ let parentCompositionId: string | null = null;
+ let cursor = node.parentElement;
+ while (cursor) {
+ const compositionId = cursor.getAttribute("data-composition-id");
+ if (compositionId) {
+ ancestors.push(compositionId);
+ if (!parentCompositionId && cursor !== root) {
+ parentCompositionId = compositionId;
+ }
+ if (inheritedStart == null) {
+ inheritedStart = startResolver.resolveStartForElement(cursor, 0);
+ }
+ if (inheritedDuration == null) {
+ inheritedDuration = parseNum(cursor.getAttribute("data-duration")) ?? null;
+ }
+ }
+ cursor = cursor.parentElement;
+ }
+ return {
+ parentCompositionId,
+ compositionAncestors: ancestors.reverse(),
+ inheritedStart,
+ inheritedDuration,
+ };
+ };
+
+ const root = document.querySelector("[data-composition-id]") as Element | null;
+ const rootCompositionId = root?.getAttribute("data-composition-id") ?? null;
+ const rootCompositionStart = root ? startResolver.resolveStartForElement(root, 0) : 0;
+ const mediaWindowEnd = resolveMediaWindowEndSeconds();
+ const mediaWindowDuration =
+ mediaWindowEnd != null ? Math.max(0, mediaWindowEnd - Math.max(0, rootCompositionStart)) : null;
+ const rootDurationFromTimeline = resolveTimelineDurationSeconds(rootCompositionId);
+ const rootDurationFromAttr = parseNum(root?.getAttribute("data-duration"));
+ const timelineDurationCandidate =
+ typeof rootDurationFromTimeline === "number" &&
+ Number.isFinite(rootDurationFromTimeline) &&
+ rootDurationFromTimeline > 0
+ ? rootDurationFromTimeline
+ : null;
+ const attrDurationCandidate =
+ typeof rootDurationFromAttr === "number" && Number.isFinite(rootDurationFromAttr) && rootDurationFromAttr > 0
+ ? rootDurationFromAttr
+ : null;
+ const mediaWindowDurationCandidate =
+ typeof mediaWindowDuration === "number" && Number.isFinite(mediaWindowDuration) && mediaWindowDuration > 0
+ ? mediaWindowDuration
+ : null;
+ const timelineLooksLoopInflated =
+ timelineDurationCandidate != null &&
+ mediaWindowDurationCandidate != null &&
+ timelineDurationCandidate > mediaWindowDurationCandidate + 1;
+ // Prefer explicit authored root duration first.
+ // If absent, guard against loop-inflated GSAP durations by trusting finite media window.
+ const preferredRootDuration =
+ attrDurationCandidate ??
+ (timelineLooksLoopInflated
+ ? mediaWindowDurationCandidate
+ : (timelineDurationCandidate ?? mediaWindowDurationCandidate));
+ const rootCompositionDuration =
+ preferredRootDuration != null ? Math.min(preferredRootDuration, params.maxTimelineDurationSeconds) : null;
+ const rootCompositionEnd = rootCompositionDuration != null ? rootCompositionStart + rootCompositionDuration : null;
+ const timelineWindowEnd =
+ rootCompositionEnd ??
+ (typeof mediaWindowEnd === "number" && Number.isFinite(mediaWindowEnd) && mediaWindowEnd > 0
+ ? mediaWindowEnd
+ : null);
+ const clampDurationToRootWindow = (start: number, duration: number): number => {
+ if (!Number.isFinite(duration) || duration <= 0) return 0;
+ if (timelineWindowEnd == null || !Number.isFinite(timelineWindowEnd)) return duration;
+ if (!Number.isFinite(start) || start >= timelineWindowEnd) return 0;
+ return Math.max(0, Math.min(duration, timelineWindowEnd - start));
+ };
+ const compositionNodes = Array.from(document.querySelectorAll("[data-composition-id]"));
+ const clips: RuntimeTimelineClip[] = [];
+ const scenes: RuntimeTimelineScene[] = [];
+ const nodes = Array.from(document.querySelectorAll("*"));
+ let maxEnd = 0;
+ for (let i = 0; i < nodes.length; i += 1) {
+ const node = nodes[i];
+ if (node === root) continue;
+ if (["SCRIPT", "STYLE", "LINK", "META", "TEMPLATE", "NOSCRIPT"].includes(node.tagName)) continue;
+ const compositionContext = resolveNearestCompositionContext(node, root);
+ const start = startResolver.resolveStartForElement(node, compositionContext.inheritedStart ?? 0);
+ const nodeCompositionId = node.getAttribute("data-composition-id");
+ let duration = parseNum(node.getAttribute("data-duration"));
+ if ((duration == null || duration <= 0) && nodeCompositionId && nodeCompositionId !== rootCompositionId) {
+ duration = resolveTimelineDurationSeconds(nodeCompositionId);
+ }
+ if ((duration == null || duration <= 0) && node instanceof HTMLMediaElement) {
+ const mediaStart =
+ parseNum(node.getAttribute("data-playback-start")) ?? parseNum(node.getAttribute("data-media-start")) ?? 0;
+ if (Number.isFinite(node.duration) && node.duration > 0) {
+ duration = Math.max(0, node.duration - mediaStart);
+ }
+ }
+ if (duration == null || duration <= 0) {
+ const inheritedDuration = compositionContext.inheritedDuration;
+ if (inheritedDuration != null && inheritedDuration > 0) {
+ const inheritedStart = compositionContext.inheritedStart ?? 0;
+ const inheritedEnd = inheritedStart + inheritedDuration;
+ duration = Math.max(0, inheritedEnd - start);
+ }
+ }
+ if (duration == null || duration <= 0) continue;
+ duration = clampDurationToRootWindow(start, duration);
+ if (duration <= 0) continue;
+ const end = start + duration;
+ maxEnd = Math.max(maxEnd, end);
+ const tag = node.tagName.toLowerCase();
+ const kind: RuntimeTimelineClip["kind"] =
+ nodeCompositionId && nodeCompositionId !== rootCompositionId
+ ? "composition"
+ : tag === "video"
+ ? "video"
+ : tag === "audio"
+ ? "audio"
+ : tag === "img"
+ ? "image"
+ : "element";
+ clips.push({
+ id: (node as HTMLElement).id || `__node__index_${i}`,
+ label:
+ node.getAttribute("data-timeline-label") ??
+ node.getAttribute("data-label") ??
+ node.getAttribute("aria-label") ??
+ (node as HTMLElement).id ??
+ (node as HTMLElement).className?.split(" ")[0] ??
+ kind,
+ start,
+ duration,
+ track:
+ Number.parseInt(node.getAttribute("data-track-index") ?? node.getAttribute("data-track") ?? String(i), 10) || 0,
+ kind,
+ tagName: tag,
+ compositionId: node.getAttribute("data-composition-id"),
+ compositionAncestors: compositionContext.compositionAncestors,
+ parentCompositionId: compositionContext.parentCompositionId,
+ nodePath: null,
+ compositionSrc: toAbsoluteAssetUrl(node.getAttribute("data-composition-src")),
+ assetUrl: resolveNodeAssetUrl(node),
+ timelineRole: node.getAttribute("data-timeline-role"),
+ timelineLabel: node.getAttribute("data-timeline-label"),
+ timelineGroup: node.getAttribute("data-timeline-group"),
+ timelinePriority: parseNum(node.getAttribute("data-timeline-priority")),
+ });
+ }
+ for (const compositionNode of compositionNodes) {
+ if (compositionNode === root) continue;
+ const compositionId = compositionNode.getAttribute("data-composition-id");
+ if (!compositionId || !isSceneLikeCompositionId(compositionId)) continue;
+ const start = startResolver.resolveStartForElement(compositionNode, 0);
+ const durationFromAttr = parseNum(compositionNode.getAttribute("data-duration"));
+ const durationFromTimeline = resolveTimelineDurationSeconds(compositionId);
+ const duration = durationFromAttr && durationFromAttr > 0 ? durationFromAttr : durationFromTimeline;
+ if (duration == null || duration <= 0) continue;
+ const clampedDuration = clampDurationToRootWindow(start, duration);
+ if (clampedDuration <= 0) continue;
+ scenes.push({
+ id: compositionId,
+ label: compositionNode.getAttribute("data-label") ?? compositionId,
+ start,
+ duration: clampedDuration,
+ thumbnailUrl: toAbsoluteAssetUrl(compositionNode.getAttribute("data-thumbnail-url")),
+ avatarName: null,
+ });
+ }
+ const safeDuration = Math.max(1, Math.min(maxEnd || 1, params.maxTimelineDurationSeconds));
+ const shouldEmitNonDeterministicInf = timelineLooksLoopInflated && attrDurationCandidate == null;
+ const durationInFrames = shouldEmitNonDeterministicInf
+ ? Number.POSITIVE_INFINITY
+ : Math.max(1, Math.round(safeDuration * Math.max(1, params.canonicalFps)));
+ return {
+ source: "hf-preview",
+ type: "timeline",
+ durationInFrames,
+ clips,
+ scenes,
+ compositionWidth: parseNum(root?.getAttribute("data-width")) ?? 1920,
+ compositionHeight: parseNum(root?.getAttribute("data-height")) ?? 1080,
+ };
+}
diff --git a/packages/core/src/runtime/types.ts b/packages/core/src/runtime/types.ts
new file mode 100644
index 000000000..7cfcf8a9e
--- /dev/null
+++ b/packages/core/src/runtime/types.ts
@@ -0,0 +1,203 @@
+export type RuntimeJson = string | number | boolean | null | RuntimeJson[] | { [key: string]: RuntimeJson };
+
+export type RuntimeBridgeControlAction =
+ | "play"
+ | "pause"
+ | "seek"
+ | "set-muted"
+ | "set-playback-rate"
+ | "enable-pick-mode"
+ | "disable-pick-mode"
+ | "flash-elements";
+
+export type RuntimeBridgeControlMessage = {
+ source: "hf-parent";
+ type: "control";
+ action: RuntimeBridgeControlAction;
+ frame?: number;
+ muted?: boolean;
+ playbackRate?: number;
+ seekMode?: "drag" | "commit";
+};
+
+export type RuntimeStateMessage = {
+ source: "hf-preview";
+ type: "state";
+ frame: number;
+ isPlaying: boolean;
+ muted: boolean;
+ playbackRate: number;
+};
+
+export type RuntimeTimelineClip = {
+ id: string | null;
+ label: string;
+ start: number;
+ duration: number;
+ track: number;
+ kind: "video" | "audio" | "image" | "element" | "composition";
+ tagName: string | null;
+ compositionId: string | null;
+ compositionAncestors: string[];
+ parentCompositionId: string | null;
+ nodePath: string | null;
+ compositionSrc: string | null;
+ assetUrl: string | null;
+ timelineRole: string | null;
+ timelineLabel: string | null;
+ timelineGroup: string | null;
+ timelinePriority: number | null;
+};
+
+export type RuntimeTimelineScene = {
+ id: string;
+ label: string;
+ start: number;
+ duration: number;
+ thumbnailUrl: string | null;
+ avatarName: string | null;
+};
+
+export type RuntimeTimelineMessage = {
+ source: "hf-preview";
+ type: "timeline";
+ durationInFrames: number;
+ clips: RuntimeTimelineClip[];
+ scenes: RuntimeTimelineScene[];
+ compositionWidth: number;
+ compositionHeight: number;
+};
+
+export type RuntimeDiagnosticMessage = {
+ source: "hf-preview";
+ type: "diagnostic";
+ code: string;
+ details: Record;
+};
+
+export type RuntimePickerBoundingBox = {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+};
+
+export type RuntimePickerElementInfo = {
+ id: string | null;
+ tagName: string;
+ selector: string;
+ label: string;
+ boundingBox: RuntimePickerBoundingBox;
+ textContent: string | null;
+ src: string | null;
+ dataAttributes: Record;
+};
+
+export type RuntimePickerHoveredMessage = {
+ source: "hf-preview";
+ type: "element-hovered";
+ elementInfo: RuntimePickerElementInfo;
+};
+
+export type RuntimePickerCandidatesMessage = {
+ source: "hf-preview";
+ type: "element-pick-candidates";
+ candidates: RuntimePickerElementInfo[];
+ selectedIndex: number;
+ point: { x: number; y: number };
+};
+
+export type RuntimePickerPickedMessage = {
+ source: "hf-preview";
+ type: "element-picked";
+ elementInfo: RuntimePickerElementInfo;
+};
+
+export type RuntimePickerPickedManyMessage = {
+ source: "hf-preview";
+ type: "element-picked-many";
+ elementInfos: RuntimePickerElementInfo[];
+};
+
+export type RuntimePickerCancelledMessage = {
+ source: "hf-preview";
+ type: "pick-mode-cancelled";
+};
+
+export type RuntimeStageSizeMessage = {
+ source: "hf-preview";
+ type: "stage-size";
+ width: number;
+ height: number;
+};
+
+/**
+ * Analytics events emitted by the runtime.
+ *
+ * The host app receives these via postMessage and forwards to its analytics
+ * provider (PostHog, Mixpanel, Amplitude, custom logging, etc.).
+ * No analytics SDK runs inside this iframe.
+ */
+export type RuntimeAnalyticsMessage = {
+ source: "hf-preview";
+ type: "analytics";
+ event:
+ | "composition_loaded"
+ | "composition_played"
+ | "composition_paused"
+ | "composition_seeked"
+ | "composition_ended"
+ | "element_picked";
+ properties: Record;
+};
+
+export type RuntimeOutboundMessage =
+ | RuntimeStateMessage
+ | RuntimeTimelineMessage
+ | RuntimeDiagnosticMessage
+ | RuntimePickerHoveredMessage
+ | RuntimePickerCandidatesMessage
+ | RuntimePickerPickedMessage
+ | RuntimePickerPickedManyMessage
+ | RuntimePickerCancelledMessage
+ | RuntimeStageSizeMessage
+ | RuntimeAnalyticsMessage;
+
+export type RuntimePlayer = {
+ _timeline: RuntimeTimelineLike | null;
+ play: () => void;
+ pause: () => void;
+ seek: (timeSeconds: number) => void;
+ renderSeek: (timeSeconds: number) => void;
+ getTime: () => number;
+ getDuration: () => number;
+ isPlaying: () => boolean;
+ setPlaybackRate: (rate: number) => void;
+ getPlaybackRate: () => number;
+};
+
+export type RuntimeTimelineLike = {
+ play: () => void;
+ pause: () => void;
+ seek: (timeSeconds: number, suppressEvents?: boolean) => void;
+ totalTime?: (timeSeconds: number, suppressEvents?: boolean) => void;
+ time: () => number;
+ duration: () => number;
+ add: (timeline: RuntimeTimelineLike, startAtSeconds: number) => void;
+ paused: (paused?: boolean) => void;
+ timeScale?: (rate: number) => void;
+ set: (target: RuntimeGsapSetTarget, vars: RuntimeGsapSetVars, atSeconds?: number) => void;
+};
+
+export type RuntimeDeterministicAdapter = {
+ name: string;
+ discover: () => void;
+ seek: (ctx: { time: number }) => void;
+ pause: () => void;
+ play?: () => void;
+ revert?: () => void;
+};
+
+export type RuntimeGsapSetTarget = string | Element | Element[] | null;
+
+export type RuntimeGsapSetVars = Record;
diff --git a/packages/core/src/runtime/window.d.ts b/packages/core/src/runtime/window.d.ts
new file mode 100644
index 000000000..cf9b10555
--- /dev/null
+++ b/packages/core/src/runtime/window.d.ts
@@ -0,0 +1,66 @@
+import type { RuntimeTimelineMessage, RuntimeTimelineLike } from "./types";
+import type { HyperframePickerApi } from "../inline-scripts/pickerApi";
+import type { PlayerAPI } from "../core.types";
+
+type ThreeClockLike = {
+ elapsedTime: number;
+ oldTime: number;
+ startTime: number;
+ getElapsedTime: () => number;
+ getDelta: () => number;
+};
+
+type ThreeAnimationMixerLike = {
+ setTime?: (time: number) => void;
+ update: (deltaTime: number) => ThreeAnimationMixerLike;
+};
+
+type ThreeLike = {
+ Clock?: {
+ prototype: ThreeClockLike;
+ };
+ AnimationMixer?: {
+ prototype: ThreeAnimationMixerLike;
+ };
+};
+
+declare global {
+ interface Window {
+ __timelines: Record;
+ __player?: PlayerAPI;
+ __clipManifest?: RuntimeTimelineMessage;
+ __playerReady?: boolean;
+ __renderReady?: boolean;
+ __HF_PARITY_MODE?: boolean;
+ __HF_FPS?: number;
+ __HF_MAX_DURATION_SEC?: number;
+ __hfThreeTime?: number;
+ __HF_PICKER_API?: HyperframePickerApi;
+ gsap?: {
+ timeline: (params?: { paused?: boolean }) => RuntimeTimelineLike;
+ ticker?: {
+ tick: () => void;
+ };
+ };
+ THREE?: ThreeLike;
+ /**
+ * Global lottie-web instance (set by including the lottie.min.js script).
+ * The adapter uses `lottie.getRegisteredAnimations()` for auto-discovery.
+ */
+ lottie?: {
+ loadAnimation: (params: unknown) => unknown;
+ getRegisteredAnimations: () => unknown[];
+ };
+ /**
+ * Lottie animation instances registered by compositions.
+ * The adapter seeks all instances when the player is seeked.
+ *
+ * Push your animation instance here after calling `lottie.loadAnimation()`:
+ * window.__hfLottie = window.__hfLottie || [];
+ * window.__hfLottie.push(anim);
+ */
+ __hfLottie?: unknown[];
+ }
+}
+
+export {};
diff --git a/packages/core/src/templates/base.test.ts b/packages/core/src/templates/base.test.ts
new file mode 100644
index 000000000..ec1b6b9fc
--- /dev/null
+++ b/packages/core/src/templates/base.test.ts
@@ -0,0 +1,114 @@
+import { describe, it, expect } from "vitest";
+import { generateBaseHtml, getStageStyles } from "./base.js";
+import {
+ GSAP_CDN,
+ BASE_STYLES,
+ ELEMENT_BASE_STYLES,
+ MEDIA_STYLES,
+ TEXT_STYLES,
+ ZOOM_CONTAINER_STYLES,
+} from "./constants.js";
+
+describe("generateBaseHtml", () => {
+ it("generates valid HTML structure with DOCTYPE", () => {
+ const html = generateBaseHtml();
+ expect(html).toContain("");
+ expect(html).toContain("");
+ expect(html).toContain("");
+ expect(html).toContain("");
+ expect(html).toContain("");
+ expect(html).toContain("");
+ });
+
+ it("includes #stage element", () => {
+ const html = generateBaseHtml();
+ expect(html).toContain('id="stage"');
+ });
+
+ it("includes #stage-zoom-container element", () => {
+ const html = generateBaseHtml();
+ expect(html).toContain('id="stage-zoom-container"');
+ });
+
+ it("defaults to portrait resolution", () => {
+ const html = generateBaseHtml();
+ expect(html).toContain('data-resolution="portrait"');
+ });
+
+ it("accepts landscape resolution", () => {
+ const html = generateBaseHtml("landscape");
+ expect(html).toContain('data-resolution="landscape"');
+ });
+
+ it("accepts portrait resolution explicitly", () => {
+ const html = generateBaseHtml("portrait");
+ expect(html).toContain('data-resolution="portrait"');
+ });
+
+ it("includes meta charset and viewport", () => {
+ const html = generateBaseHtml();
+ expect(html).toContain('charset="UTF-8"');
+ expect(html).toContain('name="viewport"');
+ });
+});
+
+describe("getStageStyles", () => {
+ it("returns landscape stage styles (1920x1080)", () => {
+ const styles = getStageStyles("landscape");
+ expect(styles).toContain("width: 1920px");
+ expect(styles).toContain("height: 1080px");
+ expect(styles).toContain("position: relative");
+ expect(styles).toContain("overflow: hidden");
+ });
+
+ it("returns portrait stage styles (1080x1920)", () => {
+ const styles = getStageStyles("portrait");
+ expect(styles).toContain("width: 1080px");
+ expect(styles).toContain("height: 1920px");
+ });
+
+ it("defaults to portrait", () => {
+ const styles = getStageStyles();
+ expect(styles).toContain("width: 1080px");
+ expect(styles).toContain("height: 1920px");
+ });
+});
+
+describe("constants", () => {
+ it("GSAP_CDN is a valid URL", () => {
+ expect(GSAP_CDN).toMatch(/^https:\/\//);
+ expect(GSAP_CDN).toContain("gsap");
+ expect(GSAP_CDN).toContain(".min.js");
+ });
+
+ it("BASE_STYLES contains reset styles", () => {
+ expect(BASE_STYLES).toContain("margin: 0");
+ expect(BASE_STYLES).toContain("padding: 0");
+ expect(BASE_STYLES).toContain("box-sizing: border-box");
+ });
+
+ it("ELEMENT_BASE_STYLES includes position and visibility", () => {
+ expect(ELEMENT_BASE_STYLES).toContain("position: absolute");
+ expect(ELEMENT_BASE_STYLES).toContain("visibility: hidden");
+ });
+
+ it("MEDIA_STYLES includes object-fit", () => {
+ expect(MEDIA_STYLES).toContain("object-fit: contain");
+ expect(MEDIA_STYLES).toContain("width: 100%");
+ expect(MEDIA_STYLES).toContain("height: 100%");
+ });
+
+ it("TEXT_STYLES includes font and alignment", () => {
+ expect(TEXT_STYLES).toContain("font-size: 48px");
+ expect(TEXT_STYLES).toContain("font-weight: bold");
+ expect(TEXT_STYLES).toContain("color: white");
+ expect(TEXT_STYLES).toContain("display: flex");
+ });
+
+ it("ZOOM_CONTAINER_STYLES includes transform-origin", () => {
+ expect(ZOOM_CONTAINER_STYLES).toContain("transform-origin: 0 0");
+ expect(ZOOM_CONTAINER_STYLES).toContain("position: absolute");
+ expect(ZOOM_CONTAINER_STYLES).toContain("inset: 0");
+ });
+});
diff --git a/packages/core/src/templates/base.ts b/packages/core/src/templates/base.ts
new file mode 100644
index 000000000..7e909d98d
--- /dev/null
+++ b/packages/core/src/templates/base.ts
@@ -0,0 +1,21 @@
+import { CANVAS_DIMENSIONS, type CanvasResolution } from "../core.types";
+
+export function generateBaseHtml(resolution: CanvasResolution = "portrait"): string {
+ return `
+
+
+ ();
+
+ function setEnv(key: string, value: string) {
+ savedEnv.set(key, process.env[key]);
+ process.env[key] = value;
+ }
+
+ beforeEach(() => {
+ savedEnv.clear();
+ });
+
+ afterEach(() => {
+ for (const [key, value] of savedEnv) {
+ if (value === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = value;
+ }
+ }
+ });
+
+ it("returns defaults when no overrides or env vars are set", () => {
+ const config = resolveConfig();
+ expect(config.fps).toBe(30);
+ expect(config.quality).toBe("standard");
+ expect(config.format).toBe("jpeg");
+ expect(config.jpegQuality).toBe(80);
+ expect(config.debug).toBe(false);
+ });
+
+ it("applies explicit overrides over defaults", () => {
+ const config = resolveConfig({ fps: 60, debug: true });
+ expect(config.fps).toBe(60);
+ expect(config.debug).toBe(true);
+ // Non-overridden fields remain at defaults
+ expect(config.quality).toBe("standard");
+ });
+
+ it("reads numeric env vars with PRODUCER_ prefix", () => {
+ setEnv("PRODUCER_MAX_WORKERS", "4");
+ setEnv("PRODUCER_CORES_PER_WORKER", "3");
+
+ const config = resolveConfig();
+ expect(config.concurrency).toBe(4);
+ expect(config.coresPerWorker).toBe(3);
+ });
+
+ it("reads boolean env vars (true/false strings)", () => {
+ setEnv("PRODUCER_DISABLE_GPU", "true");
+ setEnv("PRODUCER_ENABLE_BROWSER_POOL", "true");
+
+ const config = resolveConfig();
+ expect(config.disableGpu).toBe(true);
+ expect(config.enableBrowserPool).toBe(true);
+ });
+
+ it("treats non-'true' boolean env vars as false", () => {
+ setEnv("PRODUCER_DISABLE_GPU", "yes");
+
+ const config = resolveConfig();
+ expect(config.disableGpu).toBe(false);
+ });
+
+ it("explicit overrides take precedence over env vars", () => {
+ setEnv("PRODUCER_CORES_PER_WORKER", "5");
+
+ const config = resolveConfig({ coresPerWorker: 8 });
+ expect(config.coresPerWorker).toBe(8);
+ });
+
+ it("falls back to defaults for invalid numeric env vars", () => {
+ setEnv("PRODUCER_CORES_PER_WORKER", "not-a-number");
+
+ const config = resolveConfig();
+ expect(config.coresPerWorker).toBe(DEFAULT_CONFIG.coresPerWorker);
+ });
+
+ it("clamps chunkSizeFrames to minimum of 120", () => {
+ setEnv("PRODUCER_CHUNK_SIZE_FRAMES", "50");
+
+ const config = resolveConfig();
+ expect(config.chunkSizeFrames).toBe(120);
+ });
+
+ it("clamps frameDataUriCacheLimit to minimum of 32", () => {
+ setEnv("PRODUCER_FRAME_DATA_URI_CACHE_LIMIT", "10");
+
+ const config = resolveConfig();
+ expect(config.frameDataUriCacheLimit).toBe(32);
+ });
+});
diff --git a/packages/engine/src/config.ts b/packages/engine/src/config.ts
new file mode 100644
index 000000000..9813e53e7
--- /dev/null
+++ b/packages/engine/src/config.ts
@@ -0,0 +1,176 @@
+/**
+ * Engine Configuration
+ *
+ * Typed configuration for the rendering pipeline. Replaces the PRODUCER_*
+ * env var sprawl with a structured interface. Env vars still work as
+ * fallbacks for backward compatibility during migration.
+ */
+
+/**
+ * Full engine configuration. All fields are wired through the config
+ * object; env vars serve as backward-compatible fallbacks resolved
+ * in `resolveConfig()`.
+ */
+export interface EngineConfig {
+ // ── Rendering ────────────────────────────────────────────────────────
+ fps: 24 | 30 | 60;
+ quality: "draft" | "standard" | "high";
+ format: "jpeg" | "png";
+ jpegQuality: number;
+
+ // ── Parallelism ──────────────────────────────────────────────────────
+ /** Max worker count. "auto" uses CPU-based heuristic. */
+ concurrency: number | "auto";
+ /** CPU cores allocated per worker. */
+ coresPerWorker: number;
+ /** Minimum frames before parallel workers are used. */
+ minParallelFrames: number;
+ /** Frame count threshold for "large render" heuristics. */
+ largeRenderThreshold: number;
+
+ // ── Browser ──────────────────────────────────────────────────────────
+ chromePath?: string;
+ disableGpu: boolean;
+ enableBrowserPool: boolean;
+ browserTimeout: number;
+ protocolTimeout: number;
+ /** Expected Chromium major version (optional validation). */
+ expectedChromiumMajor?: number;
+ /** Force screenshot capture mode (skip BeginFrame even on Linux). */
+ forceScreenshot: boolean;
+
+ // ── Encoding ─────────────────────────────────────────────────────────
+ enableChunkedEncode: boolean;
+ chunkSizeFrames: number;
+ enableStreamingEncode: boolean;
+
+ // ── FFmpeg timeouts ──────────────────────────────────────────────────
+ /** Timeout for FFmpeg frame encoding (ms). Default: 600_000 */
+ ffmpegEncodeTimeout: number;
+ /** Timeout for FFmpeg mux/faststart processes (ms). Default: 300_000 */
+ ffmpegProcessTimeout: number;
+ /** Timeout for FFmpeg streaming encode (ms). Default: 600_000 */
+ ffmpegStreamingTimeout: number;
+
+ // ── Media ────────────────────────────────────────────────────────────
+ audioGain: number;
+ frameDataUriCacheLimit: number;
+
+ // ── Timeouts ─────────────────────────────────────────────────────────
+ playerReadyTimeout: number;
+ renderReadyTimeout: number;
+
+ // ── Runtime ──────────────────────────────────────────────────────────
+ /** Verify Hyperframe runtime SHA256 checksums. */
+ verifyRuntime: boolean;
+ /** Custom manifest path for Hyperframe runtime. */
+ runtimeManifestPath?: string;
+
+ // ── Debug ────────────────────────────────────────────────────────────
+ debug: boolean;
+}
+
+/** Default configuration — sensible for Hyperframes compositions. */
+export const DEFAULT_CONFIG: EngineConfig = {
+ fps: 30,
+ quality: "standard",
+ format: "jpeg",
+ jpegQuality: 80,
+
+ concurrency: "auto",
+ coresPerWorker: 2.5,
+ minParallelFrames: 120,
+ largeRenderThreshold: 1000,
+
+ disableGpu: false,
+ enableBrowserPool: false,
+ browserTimeout: 120_000,
+ protocolTimeout: 300_000,
+ forceScreenshot: false,
+
+ enableChunkedEncode: false,
+ chunkSizeFrames: 360,
+ enableStreamingEncode: false,
+
+ ffmpegEncodeTimeout: 600_000,
+ ffmpegProcessTimeout: 300_000,
+ ffmpegStreamingTimeout: 600_000,
+
+ audioGain: 1.35,
+ frameDataUriCacheLimit: 256,
+
+ playerReadyTimeout: 45_000,
+ renderReadyTimeout: 15_000,
+
+ verifyRuntime: true,
+
+ debug: false,
+};
+
+/**
+ * Resolve configuration by merging: defaults ← env vars ← explicit overrides.
+ * Env vars provide backward compatibility during migration; explicit config
+ * takes precedence over everything.
+ */
+export function resolveConfig(overrides?: Partial): EngineConfig {
+ const env = (key: string): string | undefined => process.env[key];
+ const envNum = (key: string, fallback: number): number => {
+ const raw = env(key);
+ if (raw === undefined || raw === "") return fallback;
+ const n = Number(raw);
+ return Number.isFinite(n) ? n : fallback;
+ };
+ const envBool = (key: string, fallback: boolean): boolean => {
+ const raw = env(key);
+ if (raw === undefined) return fallback;
+ return raw === "true";
+ };
+
+ // Env-var layer (backward compat)
+ const fromEnv: Partial = {
+ concurrency: env("PRODUCER_MAX_WORKERS") ? Number(env("PRODUCER_MAX_WORKERS")) : undefined,
+ coresPerWorker: envNum("PRODUCER_CORES_PER_WORKER", DEFAULT_CONFIG.coresPerWorker),
+ minParallelFrames: envNum("PRODUCER_MIN_PARALLEL_FRAMES", DEFAULT_CONFIG.minParallelFrames),
+ largeRenderThreshold: envNum("PRODUCER_LARGE_RENDER_THRESHOLD", DEFAULT_CONFIG.largeRenderThreshold),
+
+ chromePath: env("PRODUCER_HEADLESS_SHELL_PATH"),
+ disableGpu: envBool("PRODUCER_DISABLE_GPU", DEFAULT_CONFIG.disableGpu),
+ enableBrowserPool: envBool("PRODUCER_ENABLE_BROWSER_POOL", DEFAULT_CONFIG.enableBrowserPool),
+ browserTimeout: envNum("PRODUCER_PUPPETEER_LAUNCH_TIMEOUT_MS", DEFAULT_CONFIG.browserTimeout),
+ protocolTimeout: envNum("PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS", DEFAULT_CONFIG.protocolTimeout),
+ expectedChromiumMajor: env("PRODUCER_EXPECTED_CHROMIUM_MAJOR")
+ ? Number(env("PRODUCER_EXPECTED_CHROMIUM_MAJOR"))
+ : undefined,
+
+ forceScreenshot: envBool("PRODUCER_FORCE_SCREENSHOT", DEFAULT_CONFIG.forceScreenshot),
+
+ enableChunkedEncode: envBool("PRODUCER_ENABLE_CHUNKED_ENCODE", DEFAULT_CONFIG.enableChunkedEncode),
+ chunkSizeFrames: Math.max(120, envNum("PRODUCER_CHUNK_SIZE_FRAMES", DEFAULT_CONFIG.chunkSizeFrames)),
+ enableStreamingEncode: envBool("PRODUCER_ENABLE_STREAMING_ENCODE", DEFAULT_CONFIG.enableStreamingEncode),
+
+ ffmpegEncodeTimeout: envNum("FFMPEG_ENCODE_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegEncodeTimeout),
+ ffmpegProcessTimeout: envNum("FFMPEG_PROCESS_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegProcessTimeout),
+ ffmpegStreamingTimeout: envNum("FFMPEG_STREAMING_TIMEOUT_MS", DEFAULT_CONFIG.ffmpegStreamingTimeout),
+
+ audioGain: envNum("PRODUCER_AUDIO_GAIN", DEFAULT_CONFIG.audioGain),
+ frameDataUriCacheLimit: Math.max(
+ 32,
+ envNum("PRODUCER_FRAME_DATA_URI_CACHE_LIMIT", DEFAULT_CONFIG.frameDataUriCacheLimit),
+ ),
+
+ playerReadyTimeout: envNum("PRODUCER_PLAYER_READY_TIMEOUT_MS", DEFAULT_CONFIG.playerReadyTimeout),
+ renderReadyTimeout: envNum("PRODUCER_RENDER_READY_TIMEOUT_MS", DEFAULT_CONFIG.renderReadyTimeout),
+
+ verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",
+ runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),
+ };
+
+ // Remove undefined values so they don't override defaults
+ const cleanEnv = Object.fromEntries(Object.entries(fromEnv).filter(([, v]) => v !== undefined));
+
+ return {
+ ...DEFAULT_CONFIG,
+ ...cleanEnv,
+ ...overrides,
+ };
+}
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
new file mode 100644
index 000000000..18d327138
--- /dev/null
+++ b/packages/engine/src/index.ts
@@ -0,0 +1,154 @@
+/**
+ * @hyperframes/engine
+ *
+ * Seekable web page to video rendering engine.
+ * Framework-agnostic: works with GSAP, Lottie, Three.js, CSS animations,
+ * or any web content that implements the window.__hf seek protocol.
+ *
+ * ## Error Convention
+ *
+ * Engine services use three error strategies depending on the operation type:
+ *
+ * - **Orchestration services throw on failure.** Browser launch, session init,
+ * frame capture, and CDP operations propagate errors as thrown exceptions.
+ * Callers are expected to catch and handle (e.g. frameCapture, browserManager,
+ * screenshotService, videoFrameExtractor.extractVideoFramesRange).
+ *
+ * - **FFmpeg process wrappers return `{ success, error? }` result objects.**
+ * Encoding, muxing, audio mixing, and streaming encode operations never reject.
+ * They resolve with a result that includes `success: boolean` and an optional
+ * `error` string (e.g. chunkEncoder, audioMixer, streamingEncoder).
+ *
+ * - **Cleanup and teardown functions never throw.** Browser close, session close,
+ * temp directory removal, and resource release swallow errors via `.catch(() => {})`
+ * to avoid masking the original failure (e.g. releaseBrowser, closeCaptureSession,
+ * FrameLookupTable.cleanup).
+ *
+ * - **Optional lookups return `T | undefined` or `T | null`.**
+ * Functions that may legitimately find nothing (resolveHeadlessShellPath,
+ * getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
+ *
+ */
+
+// ── Protocol types ─────────────────────────────────────────────────────────────
+export type {
+ HfProtocol,
+ HfMediaElement,
+ CaptureOptions,
+ CaptureResult,
+ CaptureBufferResult,
+ CapturePerfSummary,
+} from "./types.js";
+
+// ── Configuration ──────────────────────────────────────────────────────────────
+export { resolveConfig, DEFAULT_CONFIG, type EngineConfig } from "./config.js";
+
+// ── Browser management ─────────────────────────────────────────────────────────
+export {
+ acquireBrowser,
+ releaseBrowser,
+ resolveHeadlessShellPath,
+ buildChromeArgs,
+ ENABLE_BROWSER_POOL,
+ type BuildChromeArgsOptions,
+ type CaptureMode,
+ type AcquiredBrowser,
+} from "./services/browserManager.js";
+
+// ── Frame capture pipeline ──────────────────────────────────────────────────────
+export {
+ createCaptureSession,
+ initializeSession,
+ closeCaptureSession,
+ captureFrame,
+ captureFrameToBuffer,
+ getCompositionDuration,
+ getCapturePerfSummary,
+ prepareCaptureSessionForReuse,
+ type CaptureSession,
+ type BeforeCaptureHook,
+} from "./services/frameCapture.js";
+
+// ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
+export {
+ beginFrameCapture,
+ pageScreenshotCapture,
+ getCdpSession,
+ injectVideoFramesBatch,
+ syncVideoFrameVisibility,
+ cdpSessionCache,
+ type BeginFrameResult,
+} from "./services/screenshotService.js";
+
+// ── Encoding ───────────────────────────────────────────────────────────────────
+export {
+ encodeFramesFromDir,
+ encodeFramesChunkedConcat,
+ muxVideoWithAudio,
+ applyFaststart,
+ detectGpuEncoder,
+ ENCODER_PRESETS,
+ type GpuEncoder,
+} from "./services/chunkEncoder.js";
+export type {
+ EncoderOptions,
+ EncodeResult,
+ MuxResult,
+} from "./services/chunkEncoder.types.js";
+
+export {
+ spawnStreamingEncoder,
+ createFrameReorderBuffer,
+ type StreamingEncoder,
+ type StreamingEncoderOptions,
+ type StreamingEncoderResult,
+ type FrameReorderBuffer,
+} from "./services/streamingEncoder.js";
+
+// ── Media processing ───────────────────────────────────────────────────────────
+export {
+ parseVideoElements,
+ extractVideoFramesRange,
+ extractAllVideoFrames,
+ getFrameAtTime,
+ createFrameLookupTable,
+ FrameLookupTable,
+ type VideoElement,
+ type ExtractedFrames,
+ type ExtractionOptions,
+ type ExtractionResult,
+} from "./services/videoFrameExtractor.js";
+
+export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
+
+export {
+ parseAudioElements,
+ processCompositionAudio,
+} from "./services/audioMixer.js";
+export type {
+ AudioElement,
+ AudioTrack,
+ MixResult,
+} from "./services/audioMixer.types.js";
+
+// ── Parallel rendering ─────────────────────────────────────────────────────────
+export {
+ calculateOptimalWorkers,
+ distributeFrames,
+ executeParallelCapture,
+ mergeWorkerFrames,
+ getSystemResources,
+ type WorkerTask,
+ type WorkerResult,
+ type ParallelProgress,
+} from "./services/parallelCoordinator.js";
+
+// ── File server ────────────────────────────────────────────────────────────────
+export { createFileServer, type FileServerOptions, type FileServerHandle } from "./services/fileServer.js";
+
+// ── Utilities ──────────────────────────────────────────────────────────────────
+export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
+
+export { extractVideoMetadata, extractAudioMetadata, type VideoMetadata, type AudioMetadata } from "./utils/ffprobe.js";
+
+export { downloadToTemp, isHttpUrl } from "./utils/urlDownloader.js";
diff --git a/packages/engine/src/services/audioMixer.ts b/packages/engine/src/services/audioMixer.ts
new file mode 100644
index 000000000..67c73e866
--- /dev/null
+++ b/packages/engine/src/services/audioMixer.ts
@@ -0,0 +1,392 @@
+/**
+ * Audio Mixer Service
+ *
+ * Processes and mixes audio tracks using FFmpeg.
+ */
+
+import { existsSync, mkdirSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { parseHTML } from "linkedom";
+import { extractAudioMetadata } from "../utils/ffprobe.js";
+import { downloadToTemp, isHttpUrl } from "../utils/urlDownloader.js";
+import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
+import { runFfmpeg } from "../utils/runFfmpeg.js";
+import type { AudioElement, AudioTrack, MixResult } from "./audioMixer.types.js";
+
+export type { AudioElement, AudioTrack, MixResult } from "./audioMixer.types.js";
+
+interface ExtractResult {
+ success: boolean;
+ outputPath: string;
+ durationMs: number;
+ error?: string;
+}
+
+export function parseAudioElements(html: string): AudioElement[] {
+ const elements: AudioElement[] = [];
+ const { document } = parseHTML(html);
+
+ // Parse elements
+ const audioEls = document.querySelectorAll("audio[id][src]");
+ for (const el of audioEls) {
+ const id = el.getAttribute("id");
+ const src = el.getAttribute("src");
+ if (!id || !src) continue;
+
+ const startAttr = el.getAttribute("data-start");
+ const endAttr = el.getAttribute("data-end");
+ const mediaStartAttr = el.getAttribute("data-media-start");
+ const layerAttr = el.getAttribute("data-layer");
+ const volumeAttr = el.getAttribute("data-volume");
+
+ elements.push({
+ id,
+ src,
+ start: startAttr ? parseFloat(startAttr) : 0,
+ end: endAttr ? parseFloat(endAttr) : 0,
+ mediaStart: mediaStartAttr ? parseFloat(mediaStartAttr) : 0,
+ layer: layerAttr ? parseInt(layerAttr) : 0,
+ volume: volumeAttr ? parseFloat(volumeAttr) : 1.0,
+ type: "audio",
+ });
+ }
+
+ // Parse elements with data-has-audio="true"
+ const videoEls = document.querySelectorAll('video[id][src][data-has-audio="true"]');
+ for (const el of videoEls) {
+ const id = el.getAttribute("id");
+ const src = el.getAttribute("src");
+ if (!id || !src) continue;
+
+ const startAttr = el.getAttribute("data-start");
+ const endAttr = el.getAttribute("data-end");
+ const mediaStartAttr = el.getAttribute("data-media-start");
+ const layerAttr = el.getAttribute("data-layer");
+ const volumeAttr = el.getAttribute("data-volume");
+
+ elements.push({
+ id: `${id}-audio`,
+ src,
+ start: startAttr ? parseFloat(startAttr) : 0,
+ end: endAttr ? parseFloat(endAttr) : 0,
+ mediaStart: mediaStartAttr ? parseFloat(mediaStartAttr) : 0,
+ layer: layerAttr ? parseInt(layerAttr) : 0,
+ volume: volumeAttr ? parseFloat(volumeAttr) : 1.0,
+ type: "video",
+ });
+ }
+
+ return elements;
+}
+
+async function extractAudioFromVideo(
+ videoPath: string,
+ outputPath: string,
+ options?: { startTime?: number; duration?: number },
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+ const outputDir = dirname(outputPath);
+ if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+ const args: string[] = ["-i", videoPath];
+ if (options?.startTime !== undefined) args.push("-ss", String(options.startTime));
+ if (options?.duration !== undefined) args.push("-t", String(options.duration));
+ args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", "-ac", "2", "-y", outputPath);
+
+ const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
+
+ if (signal?.aborted) {
+ return { success: false, outputPath, durationMs: result.durationMs, error: "Audio extract cancelled" };
+ }
+ if (!result.success) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: result.durationMs,
+ error: result.exitCode !== null ? `FFmpeg exited with code ${result.exitCode}` : result.stderr,
+ };
+ }
+ return { success: true, outputPath, durationMs: result.durationMs };
+}
+
+async function prepareAudioTrack(
+ srcPath: string,
+ outputPath: string,
+ mediaStart: number,
+ duration: number,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+ const outputDir = dirname(outputPath);
+ if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+ const args = [
+ "-ss",
+ String(mediaStart),
+ "-t",
+ String(duration),
+ "-i",
+ srcPath,
+ "-acodec",
+ "pcm_s16le",
+ "-ar",
+ "48000",
+ "-ac",
+ "2",
+ "-y",
+ outputPath,
+ ];
+
+ const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
+
+ if (signal?.aborted) {
+ return { success: false, outputPath, durationMs: result.durationMs, error: "Audio prepare cancelled" };
+ }
+ return {
+ success: result.success,
+ outputPath,
+ durationMs: result.durationMs,
+ error: !result.success
+ ? result.exitCode !== null
+ ? `FFmpeg exited with code ${result.exitCode}: ${result.stderr.slice(-200)}`
+ : result.stderr
+ : undefined,
+ };
+}
+
+async function generateSilence(
+ outputPath: string,
+ duration: number,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+ const outputDir = dirname(outputPath);
+ if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+ const args = [
+ "-f",
+ "lavfi",
+ "-i",
+ "anullsrc=r=48000:cl=stereo",
+ "-t",
+ String(duration),
+ "-acodec",
+ "pcm_s16le",
+ "-y",
+ outputPath,
+ ];
+
+ const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
+
+ if (signal?.aborted) {
+ return { success: false, outputPath, durationMs: result.durationMs, error: "Silence generation cancelled" };
+ }
+ return {
+ success: result.success,
+ outputPath,
+ durationMs: result.durationMs,
+ error: !result.success
+ ? result.exitCode !== null
+ ? `FFmpeg exited with code ${result.exitCode}`
+ : result.stderr
+ : undefined,
+ };
+}
+
+async function mixAudioTracks(
+ tracks: AudioTrack[],
+ outputPath: string,
+ totalDuration: number,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+ const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;
+
+ if (tracks.length === 0) {
+ const result = await generateSilence(outputPath, totalDuration, signal, config);
+ return {
+ success: result.success,
+ outputPath,
+ durationMs: result.durationMs,
+ tracksProcessed: 0,
+ error: result.error,
+ };
+ }
+
+ const outputDir = dirname(outputPath);
+ if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+ const inputs: string[] = [];
+ const filterParts: string[] = [];
+
+ tracks.forEach((track, i) => {
+ inputs.push("-i", track.srcPath);
+ const delayMs = Math.round(track.start * 1000);
+ const trimDuration = track.end - track.start;
+ filterParts.push(
+ `[${i}:a]atrim=0:${trimDuration},volume=${track.volume},adelay=${delayMs}|${delayMs},apad=whole_dur=${totalDuration}[a${i}]`,
+ );
+ });
+
+ const mixInputs = tracks.map((_, i) => `[a${i}]`).join("");
+ const weights = tracks.map(() => "1").join(" ");
+ const mixFilter = `${mixInputs}amix=inputs=${tracks.length}:duration=longest:dropout_transition=0:normalize=0:weights='${weights}'[mixed]`;
+ const postMixGainFilter = `[mixed]volume=${masterOutputGain}[out]`;
+ const fullFilter = [...filterParts, mixFilter, postMixGainFilter].join(";");
+
+ const args = [
+ ...inputs,
+ "-filter_complex",
+ fullFilter,
+ "-map",
+ "[out]",
+ "-acodec",
+ "aac",
+ "-b:a",
+ "192k",
+ "-t",
+ String(totalDuration),
+ "-y",
+ outputPath,
+ ];
+
+ const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
+
+ if (signal?.aborted) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: result.durationMs,
+ tracksProcessed: 0,
+ error: "Audio mix cancelled",
+ };
+ }
+ if (!result.success) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: result.durationMs,
+ tracksProcessed: 0,
+ error: result.exitCode !== null ? `FFmpeg exited with code ${result.exitCode}` : result.stderr,
+ };
+ }
+ return { success: true, outputPath, durationMs: result.durationMs, tracksProcessed: tracks.length };
+}
+
+export async function processCompositionAudio(
+ elements: AudioElement[],
+ baseDir: string,
+ workDir: string,
+ outputPath: string,
+ totalDuration: number,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const startMs = Date.now();
+ const tracks: AudioTrack[] = [];
+ const errors: string[] = [];
+
+ if (!existsSync(workDir)) mkdirSync(workDir, { recursive: true });
+
+ await Promise.all(
+ elements.map(async (element) => {
+ if (signal?.aborted) {
+ errors.push(`Cancelled: ${element.id}`);
+ return;
+ }
+ try {
+ let srcPath = element.src;
+ if (!srcPath.startsWith("/") && !isHttpUrl(srcPath)) {
+ srcPath = join(baseDir, srcPath);
+ }
+
+ if (isHttpUrl(srcPath)) {
+ try {
+ srcPath = await downloadToTemp(srcPath, workDir);
+ } catch (err: unknown) {
+ errors.push(`Download failed: ${element.id} — ${err instanceof Error ? err.message : String(err)}`);
+ return;
+ }
+ }
+
+ if (!existsSync(srcPath)) {
+ errors.push(`Source not found: ${element.id}`);
+ return;
+ }
+
+ // Fallback: if no duration was specified, probe the actual file
+ if (element.end - element.start <= 0) {
+ const metadata = await extractAudioMetadata(srcPath);
+ const effectiveDuration = metadata.durationSeconds - element.mediaStart;
+ element.end = element.start + (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
+ }
+
+ let audioSrcPath = srcPath;
+ if (element.type === "video") {
+ const extractedPath = join(workDir, `${element.id}-extracted.wav`);
+ const extractResult = await extractAudioFromVideo(
+ srcPath,
+ extractedPath,
+ {
+ startTime: element.mediaStart,
+ duration: element.end - element.start,
+ },
+ signal,
+ config,
+ );
+ if (!extractResult.success) {
+ errors.push(`Extract failed: ${element.id}`);
+ return;
+ }
+ audioSrcPath = extractedPath;
+ } else {
+ const trimmedPath = join(workDir, `${element.id}-trimmed.wav`);
+ const prepResult = await prepareAudioTrack(
+ srcPath,
+ trimmedPath,
+ element.mediaStart,
+ element.end - element.start,
+ signal,
+ config,
+ );
+ if (!prepResult.success) {
+ errors.push(`Prepare failed: ${element.id}`);
+ return;
+ }
+ audioSrcPath = trimmedPath;
+ }
+
+ tracks.push({
+ id: element.id,
+ srcPath: audioSrcPath,
+ start: element.start,
+ end: element.end,
+ mediaStart: element.mediaStart,
+ duration: element.end - element.start,
+ volume: element.volume || 1.0,
+ });
+ } catch (err: unknown) {
+ errors.push(`Error: ${element.id} — ${err instanceof Error ? err.message : String(err)}`);
+ }
+ }),
+ );
+
+ const mixResult = await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);
+
+ try {
+ rmSync(workDir, { recursive: true, force: true });
+ } catch {
+ /* ignore */
+ }
+
+ return {
+ ...mixResult,
+ durationMs: Date.now() - startMs,
+ error: errors.length > 0 ? `Warnings: ${errors.join(", ")}` : mixResult.error,
+ };
+}
diff --git a/packages/engine/src/services/audioMixer.types.ts b/packages/engine/src/services/audioMixer.types.ts
new file mode 100644
index 000000000..cdad89340
--- /dev/null
+++ b/packages/engine/src/services/audioMixer.types.ts
@@ -0,0 +1,28 @@
+export interface AudioElement {
+ id: string;
+ src: string;
+ start: number;
+ end: number;
+ mediaStart: number;
+ layer: number;
+ volume?: number;
+ type: "audio" | "video";
+}
+
+export interface AudioTrack {
+ id: string;
+ srcPath: string;
+ start: number;
+ end: number;
+ mediaStart: number;
+ duration: number;
+ volume: number;
+}
+
+export interface MixResult {
+ success: boolean;
+ outputPath: string;
+ durationMs: number;
+ tracksProcessed: number;
+ error?: string;
+}
diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts
new file mode 100644
index 000000000..c8998f2c8
--- /dev/null
+++ b/packages/engine/src/services/browserManager.ts
@@ -0,0 +1,219 @@
+/**
+ * Browser Manager
+ *
+ * Manages Puppeteer browser lifecycle: Chrome executable resolution,
+ * launch args, pooled browser acquisition/release.
+ */
+
+import type { Browser, PuppeteerNode } from "puppeteer-core";
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
+
+let _puppeteer: PuppeteerNode | undefined;
+
+async function getPuppeteer(): Promise {
+ if (_puppeteer) return _puppeteer;
+ try {
+ const mod = await import("puppeteer" as string);
+ _puppeteer = mod.default;
+ } catch {
+ const mod = await import("puppeteer-core");
+ _puppeteer = mod.default;
+ }
+ if (!_puppeteer) throw new Error("Neither puppeteer nor puppeteer-core found");
+ return _puppeteer;
+}
+
+// "beginframe" = atomic compositor control via HeadlessExperimental.beginFrame (Linux only)
+// "screenshot" = renderSeek + Page.captureScreenshot (all platforms)
+export type CaptureMode = "beginframe" | "screenshot";
+
+export interface AcquiredBrowser {
+ browser: Browser;
+ captureMode: CaptureMode;
+}
+
+/**
+ * Resolve chrome-headless-shell binary for deterministic BeginFrame rendering.
+ * Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,
+ * then scans Puppeteer's managed cache at ~/.cache/puppeteer/chrome-headless-shell/.
+ */
+export function resolveHeadlessShellPath(config?: Partial>): string | undefined {
+ if (config?.chromePath) {
+ return config.chromePath;
+ }
+ if (process.env.PRODUCER_HEADLESS_SHELL_PATH) {
+ return process.env.PRODUCER_HEADLESS_SHELL_PATH;
+ }
+ const baseDir = join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");
+ if (!existsSync(baseDir)) return undefined;
+ try {
+ const versions = readdirSync(baseDir).sort().reverse(); // newest first
+ for (const version of versions) {
+ const candidates = [
+ join(baseDir, version, "chrome-headless-shell-linux64", "chrome-headless-shell"),
+ join(baseDir, version, "chrome-headless-shell-mac-arm64", "chrome-headless-shell"),
+ join(baseDir, version, "chrome-headless-shell-mac-x64", "chrome-headless-shell"),
+ join(baseDir, version, "chrome-headless-shell-win64", "chrome-headless-shell.exe"),
+ ];
+ for (const binary of candidates) {
+ if (existsSync(binary)) return binary;
+ }
+ }
+ } catch {
+ // ignore
+ }
+ return undefined;
+}
+
+let pooledBrowser: Browser | null = null;
+let pooledBrowserRefCount = 0;
+let pooledCaptureMode: CaptureMode = "screenshot";
+
+// Preserve the producer-era export so re-export shims keep the same public API.
+export const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;
+
+export async function acquireBrowser(
+ chromeArgs: string[],
+ config?: Partial<
+ Pick
+ >,
+): Promise {
+ const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
+
+ if (enablePool && pooledBrowser) {
+ pooledBrowserRefCount += 1;
+ return { browser: pooledBrowser, captureMode: pooledCaptureMode };
+ }
+
+ // Config chromePath overrides env var / auto-detection.
+ const headlessShell = resolveHeadlessShellPath(config);
+
+ // BeginFrame requires chrome-headless-shell AND Linux (crashes on macOS/Windows).
+ const isLinux = process.platform === "linux";
+ const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
+ let captureMode: CaptureMode;
+ let executablePath: string | undefined;
+
+ if (headlessShell && isLinux && !forceScreenshot) {
+ captureMode = "beginframe";
+ executablePath = headlessShell;
+ } else {
+ // Screenshot mode with renderSeek: works on all platforms.
+ captureMode = "screenshot";
+ if (headlessShell && !isLinux) {
+ executablePath = headlessShell;
+ } else {
+ executablePath = undefined; // Puppeteer uses its bundled Chromium
+ }
+ }
+
+ const ppt = await getPuppeteer();
+ const browser = await ppt.launch({
+ headless: true,
+ args: chromeArgs,
+ defaultViewport: null,
+ executablePath,
+ timeout: config?.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
+ protocolTimeout: config?.protocolTimeout ?? DEFAULT_CONFIG.protocolTimeout,
+ });
+ if (enablePool) {
+ pooledBrowser = browser;
+ pooledBrowserRefCount = 1;
+ pooledCaptureMode = captureMode;
+ }
+ return { browser, captureMode };
+}
+
+export async function releaseBrowser(
+ browser: Browser,
+ config?: Partial>,
+): Promise {
+ const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
+ if (!enablePool) {
+ await browser.close().catch(() => {});
+ return;
+ }
+ if (pooledBrowser && pooledBrowser === browser) {
+ pooledBrowserRefCount = Math.max(0, pooledBrowserRefCount - 1);
+ if (pooledBrowserRefCount === 0) {
+ await browser.close().catch(() => {});
+ pooledBrowser = null;
+ }
+ return;
+ }
+ await browser.close().catch(() => {});
+}
+
+export interface BuildChromeArgsOptions {
+ width: number;
+ height: number;
+ captureMode?: CaptureMode;
+}
+
+export function buildChromeArgs(
+ options: BuildChromeArgsOptions,
+ config?: Partial>,
+): string[] {
+ // Chrome flags tuned for headless rendering performance.
+ // Based on Remotion's open-browser.ts flags with additions for our use case.
+ const chromeArgs = [
+ "--no-sandbox",
+ "--disable-setuid-sandbox",
+ "--disable-dev-shm-usage",
+ "--enable-webgl",
+ "--ignore-gpu-blocklist",
+ "--use-gl=angle",
+ "--use-angle=swiftshader",
+ "--font-render-hinting=none",
+ "--force-color-profile=srgb",
+ `--window-size=${options.width},${options.height}`,
+ // Remotion perf flags — prevent Chrome from throttling background tabs/timers
+ "--disable-background-timer-throttling",
+ "--disable-backgrounding-occluded-windows",
+ "--disable-renderer-backgrounding",
+ "--disable-background-media-suspend",
+ // Reduce overhead from unused Chrome features
+ "--disable-breakpad",
+ "--disable-component-extensions-with-background-pages",
+ "--disable-default-apps",
+ "--disable-extensions",
+ "--disable-hang-monitor",
+ "--disable-ipc-flooding-protection",
+ "--disable-popup-blocking",
+ "--disable-sync",
+ "--disable-component-update",
+ "--disable-domain-reliability",
+ "--disable-print-preview",
+ "--no-pings",
+ "--no-zygote",
+ // Memory
+ "--force-gpu-mem-available-mb=4096",
+ "--disk-cache-size=268435456",
+ // Disable features that add overhead
+ "--disable-features=AudioServiceOutOfProcess,IsolateOrigins,site-per-process,Translate,BackForwardCache,IntensiveWakeUpThrottling",
+ ];
+
+ // BeginFrame flags — only when using chrome-headless-shell on Linux
+ if (options.captureMode !== "screenshot") {
+ chromeArgs.push(
+ "--deterministic-mode",
+ "--enable-begin-frame-control",
+ "--disable-new-content-rendering-timeout",
+ "--run-all-compositor-stages-before-draw",
+ "--disable-threaded-animation",
+ "--disable-threaded-scrolling",
+ "--disable-checker-imaging",
+ "--disable-image-animation-resync",
+ "--enable-surface-synchronization",
+ );
+ }
+
+ const gpuDisabled = config?.disableGpu ?? DEFAULT_CONFIG.disableGpu;
+ if (gpuDisabled) {
+ chromeArgs.push("--disable-gpu");
+ }
+ return chromeArgs;
+}
diff --git a/packages/engine/src/services/chunkEncoder.test.ts b/packages/engine/src/services/chunkEncoder.test.ts
new file mode 100644
index 000000000..1628292c2
--- /dev/null
+++ b/packages/engine/src/services/chunkEncoder.test.ts
@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { ENCODER_PRESETS } from "./chunkEncoder.js";
+
+describe("ENCODER_PRESETS", () => {
+ it("has draft, standard, and high presets", () => {
+ expect(ENCODER_PRESETS).toHaveProperty("draft");
+ expect(ENCODER_PRESETS).toHaveProperty("standard");
+ expect(ENCODER_PRESETS).toHaveProperty("high");
+ });
+
+ it("draft uses ultrafast preset with high CRF", () => {
+ expect(ENCODER_PRESETS.draft.preset).toBe("ultrafast");
+ expect(ENCODER_PRESETS.draft.quality).toBeGreaterThan(ENCODER_PRESETS.standard.quality);
+ expect(ENCODER_PRESETS.draft.codec).toBe("h264");
+ });
+
+ it("high uses slow preset with low CRF for better quality", () => {
+ expect(ENCODER_PRESETS.high.preset).toBe("slow");
+ expect(ENCODER_PRESETS.high.quality).toBeLessThan(ENCODER_PRESETS.standard.quality);
+ expect(ENCODER_PRESETS.high.codec).toBe("h264");
+ });
+
+ it("standard sits between draft and high in quality", () => {
+ expect(ENCODER_PRESETS.standard.quality).toBeGreaterThan(ENCODER_PRESETS.high.quality);
+ expect(ENCODER_PRESETS.standard.quality).toBeLessThan(ENCODER_PRESETS.draft.quality);
+ });
+});
diff --git a/packages/engine/src/services/chunkEncoder.ts b/packages/engine/src/services/chunkEncoder.ts
new file mode 100644
index 000000000..bfb285b19
--- /dev/null
+++ b/packages/engine/src/services/chunkEncoder.ts
@@ -0,0 +1,399 @@
+/**
+ * Chunk Encoder Service
+ *
+ * Encodes captured frames into video using FFmpeg.
+ * Supports CPU (libx264) and GPU encoding.
+ */
+
+import { spawn } from "child_process";
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
+import { type GpuEncoder, getCachedGpuEncoder, getGpuEncoderName } from "../utils/gpuEncoder.js";
+import { runFfmpeg } from "../utils/runFfmpeg.js";
+import type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
+
+export type { EncoderOptions, EncodeResult, MuxResult } from "./chunkEncoder.types.js";
+
+export const ENCODER_PRESETS = {
+ draft: { preset: "ultrafast", quality: 28, codec: "h264" as const },
+ standard: { preset: "medium", quality: 23, codec: "h264" as const },
+ high: { preset: "slow", quality: 18, codec: "h264" as const },
+};
+
+// Re-export GPU utilities so existing consumers that import from chunkEncoder still work.
+export { detectGpuEncoder, type GpuEncoder } from "../utils/gpuEncoder.js";
+
+function buildEncoderArgs(
+ options: EncoderOptions,
+ inputArgs: string[],
+ outputPath: string,
+ gpuEncoder: GpuEncoder = null,
+): string[] {
+ const {
+ fps,
+ codec = "h264",
+ preset = "medium",
+ quality = 23,
+ bitrate,
+ pixelFormat = "yuv420p",
+ useGpu = false,
+ } = options;
+
+ const args: string[] = [...inputArgs, "-r", String(fps)];
+ const shouldUseGpu = useGpu && gpuEncoder !== null;
+
+ if (codec === "h264" || codec === "h265") {
+ if (shouldUseGpu) {
+ const encoderName = getGpuEncoderName(gpuEncoder, codec);
+ args.push("-c:v", encoderName);
+
+ switch (gpuEncoder) {
+ case "nvenc":
+ args.push("-preset", preset);
+ if (bitrate) args.push("-b:v", bitrate);
+ else args.push("-cq", String(quality));
+ break;
+ case "videotoolbox":
+ if (bitrate) args.push("-b:v", bitrate);
+ else {
+ const vtQuality = Math.max(0, Math.min(100, 100 - quality * 2));
+ args.push("-q:v", String(vtQuality));
+ }
+ args.push("-allow_sw", "1");
+ break;
+ case "vaapi":
+ args.unshift("-vaapi_device", "/dev/dri/renderD128");
+ args.push("-vf", "format=nv12,hwupload");
+ if (bitrate) args.push("-b:v", bitrate);
+ else args.push("-qp", String(quality));
+ break;
+ case "qsv":
+ args.push("-preset", preset);
+ if (bitrate) args.push("-b:v", bitrate);
+ else args.push("-global_quality", String(quality));
+ break;
+ }
+ } else {
+ const encoderName = codec === "h264" ? "libx264" : "libx265";
+ args.push("-c:v", encoderName, "-preset", preset);
+ if (bitrate) args.push("-b:v", bitrate);
+ else args.push("-crf", String(quality));
+ }
+ } else if (codec === "vp9") {
+ args.push("-c:v", "libvpx-vp9", "-b:v", bitrate || "0", "-crf", String(quality));
+ args.push("-deadline", preset === "ultrafast" ? "realtime" : "good");
+ } else if (codec === "prores") {
+ args.push("-c:v", "prores_ks", "-profile:v", preset, "-vendor", "apl0");
+ return [...args, "-y", outputPath];
+ }
+
+ if (gpuEncoder !== "vaapi") {
+ args.push("-pix_fmt", pixelFormat);
+ }
+
+ args.push("-y", outputPath);
+ return args;
+}
+
+export async function encodeFramesFromDir(
+ framesDir: string,
+ framePattern: string,
+ outputPath: string,
+ options: EncoderOptions,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const startTime = Date.now();
+
+ const outputDir = dirname(outputPath);
+ if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+ const files = readdirSync(framesDir).filter((f) => f.match(/\.(jpg|jpeg|png)$/i));
+ const frameCount = files.length;
+
+ if (frameCount === 0) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: Date.now() - startTime,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: "[FFmpeg] No frame files found in directory",
+ };
+ }
+
+ let gpuEncoder: GpuEncoder = null;
+ if (options.useGpu) {
+ gpuEncoder = await getCachedGpuEncoder();
+ }
+
+ const inputPath = join(framesDir, framePattern);
+ const inputArgs = ["-framerate", String(options.fps), "-i", inputPath];
+ const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
+
+ return new Promise((resolve) => {
+ const ffmpeg = spawn("ffmpeg", args);
+ let stderr = "";
+ const onAbort = () => {
+ ffmpeg.kill("SIGTERM");
+ };
+ if (signal) {
+ if (signal.aborted) {
+ ffmpeg.kill("SIGTERM");
+ } else {
+ signal.addEventListener("abort", onAbort, { once: true });
+ }
+ }
+
+ const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
+ const timer = setTimeout(() => {
+ ffmpeg.kill("SIGTERM");
+ }, encodeTimeout);
+
+ ffmpeg.stderr.on("data", (data) => {
+ stderr += data.toString();
+ });
+
+ ffmpeg.on("close", (code) => {
+ clearTimeout(timer);
+ if (signal) signal.removeEventListener("abort", onAbort);
+ const durationMs = Date.now() - startTime;
+ if (signal?.aborted) {
+ resolve({
+ success: false,
+ outputPath,
+ durationMs,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: "FFmpeg encode cancelled",
+ });
+ return;
+ }
+
+ if (code !== 0) {
+ resolve({
+ success: false,
+ outputPath,
+ durationMs,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: `FFmpeg exited with code ${code}`,
+ });
+ return;
+ }
+
+ const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
+ resolve({ success: true, outputPath, durationMs, framesEncoded: frameCount, fileSize });
+ });
+
+ ffmpeg.on("error", (err) => {
+ clearTimeout(timer);
+ if (signal) signal.removeEventListener("abort", onAbort);
+ resolve({
+ success: false,
+ outputPath,
+ durationMs: Date.now() - startTime,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: `[FFmpeg] ${err.message}`,
+ });
+ });
+ });
+}
+
+export async function encodeFramesChunkedConcat(
+ framesDir: string,
+ framePattern: string,
+ outputPath: string,
+ options: EncoderOptions,
+ chunkSizeFrames: number,
+ signal?: AbortSignal,
+): Promise {
+ const start = Date.now();
+ const files = readdirSync(framesDir)
+ .filter((f) => f.match(/\.(jpg|jpeg|png)$/i))
+ .sort();
+ if (files.length === 0) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: Date.now() - start,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: "[FFmpeg] No frame files found in directory",
+ };
+ }
+ const chunkSize = Math.max(30, Math.floor(chunkSizeFrames));
+ const chunkCount = Math.ceil(files.length / chunkSize);
+ const chunkDir = join(dirname(outputPath), "chunk-encode");
+ if (!existsSync(chunkDir)) mkdirSync(chunkDir, { recursive: true });
+ const chunkPaths: string[] = [];
+
+ for (let i = 0; i < chunkCount; i++) {
+ if (signal?.aborted) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: Date.now() - start,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: "Chunked encode cancelled",
+ };
+ }
+ const startNumber = i * chunkSize;
+ const framesInChunk = Math.min(chunkSize, files.length - startNumber);
+ const chunkPath = join(chunkDir, `chunk_${String(i).padStart(4, "0")}.mp4`);
+ const inputPath = join(framesDir, framePattern);
+ const inputArgs = [
+ "-framerate",
+ String(options.fps),
+ "-start_number",
+ String(startNumber),
+ "-i",
+ inputPath,
+ "-frames:v",
+ String(framesInChunk),
+ ];
+ let gpuEncoder: GpuEncoder = null;
+ if (options.useGpu) gpuEncoder = await getCachedGpuEncoder();
+ const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder);
+ const chunkResult = await new Promise<{ success: boolean; error?: string }>((resolve) => {
+ const ffmpeg = spawn("ffmpeg", args);
+ let stderr = "";
+ ffmpeg.stderr.on("data", (d) => {
+ stderr += d.toString();
+ });
+ ffmpeg.on("close", (code) => {
+ if (code === 0) resolve({ success: true });
+ else resolve({ success: false, error: `Chunk ${i} encode failed: ${stderr.slice(-400)}` });
+ });
+ ffmpeg.on("error", (err) => {
+ resolve({ success: false, error: `Chunk ${i} encode error: ${err.message}` });
+ });
+ });
+ if (!chunkResult.success) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: Date.now() - start,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: chunkResult.error,
+ };
+ }
+ chunkPaths.push(chunkPath);
+ }
+
+ const concatListPath = join(chunkDir, "concat-list.txt");
+ const concatInput = chunkPaths.map((path) => `file '${path.replace(/'/g, "'\\''")}'`).join("\n");
+ writeFileSync(concatListPath, concatInput, "utf-8");
+
+ const concatArgs = ["-f", "concat", "-safe", "0", "-i", concatListPath, "-c", "copy", "-y", outputPath];
+ const concatResult = await new Promise<{ success: boolean; error?: string }>((resolve) => {
+ const ffmpeg = spawn("ffmpeg", concatArgs);
+ let stderr = "";
+ ffmpeg.stderr.on("data", (d) => {
+ stderr += d.toString();
+ });
+ ffmpeg.on("close", (code) => {
+ if (code === 0) resolve({ success: true });
+ else resolve({ success: false, error: `Chunk concat failed: ${stderr.slice(-400)}` });
+ });
+ ffmpeg.on("error", (err) => {
+ resolve({ success: false, error: `Chunk concat error: ${err.message}` });
+ });
+ });
+
+ if (!concatResult.success) {
+ return {
+ success: false,
+ outputPath,
+ durationMs: Date.now() - start,
+ framesEncoded: 0,
+ fileSize: 0,
+ error: concatResult.error,
+ };
+ }
+
+ const fileSize = existsSync(outputPath) ? statSync(outputPath).size : 0;
+ return {
+ success: true,
+ outputPath,
+ durationMs: Date.now() - start,
+ framesEncoded: files.length,
+ fileSize,
+ };
+}
+
+export async function muxVideoWithAudio(
+ videoPath: string,
+ audioPath: string,
+ outputPath: string,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const outputDir = dirname(outputPath);
+ if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+ const args = [
+ "-i",
+ videoPath,
+ "-i",
+ audioPath,
+ "-c:v",
+ "copy",
+ "-c:a",
+ "aac",
+ "-b:a",
+ "192k",
+ "-shortest",
+ "-movflags",
+ "+faststart",
+ "-y",
+ outputPath,
+ ];
+
+ const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+ const result = await runFfmpeg(args, { signal, timeout: processTimeout });
+
+ if (signal?.aborted) {
+ return { success: false, outputPath, durationMs: result.durationMs, error: "FFmpeg mux cancelled" };
+ }
+ return {
+ success: result.success,
+ outputPath,
+ durationMs: result.durationMs,
+ error: !result.success
+ ? result.exitCode !== null
+ ? `FFmpeg exited with code ${result.exitCode}`
+ : `[FFmpeg] ${result.stderr}`
+ : undefined,
+ };
+}
+
+export async function applyFaststart(
+ inputPath: string,
+ outputPath: string,
+ signal?: AbortSignal,
+ config?: Partial>,
+): Promise {
+ const args = ["-i", inputPath, "-c", "copy", "-movflags", "+faststart", "-y", outputPath];
+
+ const processTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+ const result = await runFfmpeg(args, { signal, timeout: processTimeout });
+
+ if (signal?.aborted) {
+ return { success: false, outputPath, durationMs: result.durationMs, error: "FFmpeg faststart cancelled" };
+ }
+ return {
+ success: result.success,
+ outputPath,
+ durationMs: result.durationMs,
+ error: !result.success
+ ? result.exitCode !== null
+ ? `FFmpeg exited with code ${result.exitCode}`
+ : `[FFmpeg] ${result.stderr}`
+ : undefined,
+ };
+}
diff --git a/packages/engine/src/services/chunkEncoder.types.ts b/packages/engine/src/services/chunkEncoder.types.ts
new file mode 100644
index 000000000..9d36b4294
--- /dev/null
+++ b/packages/engine/src/services/chunkEncoder.types.ts
@@ -0,0 +1,27 @@
+export interface EncoderOptions {
+ fps: number;
+ width: number;
+ height: number;
+ codec?: "h264" | "h265" | "vp9" | "prores";
+ preset?: string;
+ quality?: number;
+ bitrate?: string;
+ pixelFormat?: string;
+ useGpu?: boolean;
+}
+
+export interface EncodeResult {
+ success: boolean;
+ outputPath: string;
+ durationMs: number;
+ framesEncoded: number;
+ fileSize: number;
+ error?: string;
+}
+
+export interface MuxResult {
+ success: boolean;
+ outputPath: string;
+ durationMs: number;
+ error?: string;
+}
diff --git a/packages/engine/src/services/fileServer.ts b/packages/engine/src/services/fileServer.ts
new file mode 100644
index 000000000..f57558e93
--- /dev/null
+++ b/packages/engine/src/services/fileServer.ts
@@ -0,0 +1,175 @@
+/**
+ * File Server
+ *
+ * Lightweight HTTP server that serves a project directory to headless Chrome.
+ * Optionally injects scripts into index.html on-the-fly (e.g. runtime, bridge).
+ * Framework-agnostic — the caller decides what scripts to inject.
+ */
+
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+
+const MIME_TYPES: Record = {
+ ".html": "text/html; charset=utf-8",
+ ".css": "text/css; charset=utf-8",
+ ".js": "application/javascript; charset=utf-8",
+ ".json": "application/json; charset=utf-8",
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+ ".gif": "image/gif",
+ ".svg": "image/svg+xml",
+ ".webp": "image/webp",
+ ".mp4": "video/mp4",
+ ".webm": "video/webm",
+ ".mp3": "audio/mpeg",
+ ".wav": "audio/wav",
+ ".ogg": "audio/ogg",
+ ".aac": "audio/aac",
+ ".woff": "font/woff",
+ ".woff2": "font/woff2",
+ ".ttf": "font/ttf",
+ ".otf": "font/otf",
+};
+
+function stripEmbeddedRuntimeScripts(html: string): string {
+ if (!html) return html;
+ const scriptRe = /]*>[\s\S]*?<\/script>/gi;
+ const runtimeSrcMarkers = [
+ "hyperframe.runtime.iife.js",
+ "hyperframes-runtime.modular.inline.js",
+ "data-hyperframes-preview-runtime",
+ ];
+ const runtimeInlineMarkers = [
+ "__hyperframeRuntimeBootstrapped",
+ "__hyperframeRuntime",
+ "__hyperframeRuntimeTeardown",
+ "window.__player =",
+ "window.__playerReady",
+ "window.__renderReady",
+ ];
+
+ const shouldStrip = (block: string): boolean => {
+ const lowered = block.toLowerCase();
+ for (const marker of runtimeSrcMarkers) {
+ if (lowered.includes(marker.toLowerCase())) {
+ return true;
+ }
+ }
+ for (const marker of runtimeInlineMarkers) {
+ if (block.includes(marker)) {
+ return true;
+ }
+ }
+ return false;
+ };
+
+ return html.replace(scriptRe, (block) => (shouldStrip(block) ? "" : block));
+}
+
+function injectScriptsIntoHtml(
+ html: string,
+ headScripts: string[],
+ bodyScripts: string[],
+ stripEmbedded: boolean,
+): string {
+ if (stripEmbedded) {
+ html = stripEmbeddedRuntimeScripts(html);
+ }
+
+ if (headScripts.length > 0) {
+ const headTags = headScripts.map((src) => ``).join("\n");
+ if (html.includes("")) {
+ html = html.replace("", () => `${headTags}\n`);
+ } else if (html.includes(" `${headTags}\n 0) {
+ const bodyTags = bodyScripts.map((src) => ``).join("\n");
+ if (html.includes("")) {
+ html = html.replace(" 
+
+
+