@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/SKILL.director.md

@@ -550,6 +550,14 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 | `vidfarm clips scan --cloud <video\|--url <url>> [--tracer <id>]` | temp-file presign/PUT/finalize + `POST /clips/scan` + poll | BACKUP: run the hunt on the deployed pipeline (bills AWS compute only) |
 | `vidfarm clips search "…"` / `clips match "…"` / `clips list` / `clips sources` | (local library; NL→criteria via local agent or provider key) | search/reuse the clip library |
 | `vidfarm clips preset list\|run\|save` / `clips export <ids…> --to <dir>` | (local library) | saved queries; copy clip MP4s out |
+| `vidfarm lint <dir\|composition.html>` | (local static validation) | pre-publish composition check: timing, overlaps, preset names, media src |
+| `vidfarm stills <dir> [--at 0,2.5,…]` | (local in-process render of PNG frames) | visually verify an edit without a full render |
+| `vidfarm doctor` | (local environment triage) | check ffmpeg/node/keys/agent CLI/poisoned env before debugging anything else |
+| `vidfarm skills list\|add <name>\|update` | `GET /skill-pack/index.json` · `/skill-pack/:name/*` | install/refresh skill packs (see "Skill packs — import on demand") |
+| `vidfarm tts "…" --engine local` / `vidfarm stt <file> --engine whisper` | (keyless LOCAL engines: Kokoro-82M TTS, whisper.cpp STT) | narration + word-timestamp transcripts with zero keys and zero accounts |
+| `vidfarm remove-background <video\|image>` | (local ONNX matting — free) | transparent-subject media for occlusion captions/cutouts |
+| `vidfarm capture <url>` | (local headless-Chrome capture) | website screenshots/assets for website-to-video flows |
+| `vidfarm beats <audio>` | (local beat detection → JSON) | music beat timestamps to sync cuts/transitions/captions |
 
 **Frontend URLs are first-class output.** Every command that has a human-openable page (editor, discover, approved-post preview, share link) prints that prod frontend URL as a highlighted line. `render --wait` polls to completion and prints the final MP4 URL; `approve` prints the approved-post `share_url`. Add `--json` to any command for pure JSON (agent-friendly, no banners).
 
@@ -611,6 +619,35 @@ Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (b
 
 To *analyze* the source media locally (videos, transcript, recurring cast), read the `video-context.json` / `cast.json` routes, or pull a media URL with `vidfarm download <url>`.
 
+## Skill packs — import on demand (HyperFrames-grade authoring power)
+
+This skill stays lean on purpose. Deep authoring craft lives in **skill packs** — vidfarm-scrubbed snapshots of the HyperFrames skill suite plus vidfarm's own media pack — vendored on the Vidfarm host and installed only when a task needs them. Never install skills from upstream vendor orgs or third-party registries; the vidfarm mirror is the source (`vidfarm skills add <name>` fetches `GET /skill-pack/:name/*` with hash verification into `.agents/skills/` + a `.claude/skills/` link, pinned in `skills-lock.json`; `vidfarm skills list` shows what is available/installed; `vidfarm skills update` refreshes pins).
+
+Import by task:
+
+| When the task needs… | Install |
+|---|---|
+| the raw composition HTML contract (data-* attrs, tracks, clips, sub-compositions, determinism rules) | `vidfarm skills add hyperframes-core` |
+| motion design: animation rules, multi-phase scene blueprints, transition doctrine, runtime adapters (GSAP/Lottie/Three/Anime/CSS/WAAPI/TypeGPU) | `vidfarm skills add hyperframes-animation` |
+| seek-safe keyframe patterns (FLIP, paths, masks, SVG draw/morph, 3D depth) | `vidfarm skills add hyperframes-keyframes` |
+| creative direction: design specs, palettes, typography, house style, narration craft | `vidfarm skills add hyperframes-creative` |
+| the HyperFrames CLI dev loop (init/lint/validate/inspect/snapshot/preview/render) | `vidfarm skills add hyperframes-cli` |
+| narration/BGM/SFX/media resolution (the shared audio engine) | `vidfarm skills add vidfarm-media` |
+| embedded/cinematic captions with subject occlusion (32-identity catalog) | `vidfarm skills add embedded-captions` |
+| graphic overlay cards on existing talking-head footage | `vidfarm skills add talking-head-recut` |
+| a product launch/promo video end-to-end | `vidfarm skills add product-launch-video` |
+| a faceless topic explainer end-to-end | `vidfarm skills add faceless-explainer` |
+| a website tour/showcase video end-to-end | `vidfarm skills add website-to-video` |
+| a short motion graphic (kinetic type, stat hit, logo sting, lower-third) | `vidfarm skills add motion-graphics` |
+| an interactive slideshow/deck | `vidfarm skills add slideshow` |
+| any other multi-scene composition (fallback workflow) | `vidfarm skills add general-video` |
+
+Ground rules:
+
+- **Local coding agents** (Claude Code / Codex on a `vidfarm serve` box or a pulled fork) get the FULL packs — install, read, and follow them. Scripted/GSAP compositions authored this way render correctly through `vidfarm render` (local and cloud); note that the **web editor strips `<script>` on save**, so keep compositions that must round-trip through the browser editor declarative (the built-in Ken Burns / transitions / animated-captions vocabulary).
+- **The web copilot** never installs packs — it has a `load_skill` tool that reads the same content on demand from the vidfarm mirror. Nothing to do there; it is already wired.
+- Vidfarm-managed environments set `HYPERFRAMES_SKIP_SKILLS=1` and `HYPERFRAMES_NO_TELEMETRY=1`, so `npx hyperframes init` never overwrites the vidfarm-scrubbed packs and the bundled CLI never phones home. Do not run `hyperframes auth`, `hyperframes cloud`, `hyperframes publish`, `hyperframes play`, or `hyperframes feedback` — vidfarm's own render/share/telemetry surfaces cover all of them.
+
 ## What NOT to do
 
 - Do **not** manipulate composition HTML by string concatenation. Always parse, edit, and re-serialize the DOM. The editor and runtime rely on `data-start`, `data-duration`, `data-track-index`, `data-hf-id`, `data-composition-id` attributes being well-formed.

package/SKILL.platform.md

@@ -266,7 +266,7 @@ Configuration: `GHOSTCUT_KEY` and `GHOSTCUT_SECRET` env vars per stage. Pass-thr
 
 The chat model uses the **caller's provider keys**. No Vidfarm-owned model calls happen in this path.
 
-Beyond the Editor Action API, the chat harness registers shared tools defined in **two synced copies** (`src/app.ts` for the in-process dev server and `infra/lambda/editor-chat.ts` for the deployed Lambda — keep them in lockstep): `http_request` (allowlisted REST/primitive calls), `frontend_action` (tracer/thread state), `video_context`, and `browse_files`. `browse_files` reads **and writes** the caller's My Files library — `action=list`/`search`/`read`/`write`/`annotate`. `write` saves a text file (md/txt/csv/json/srt/vtt) via `POST /me/attachments/upload`, or **imports a durable media URL** into the library when `source_url` is passed (how a generated `character_sprite_card.png` gets persisted instead of stranding in a job result). `annotate` sets free-form metadata `notes` on any entry (`PATCH /me/attachments/:id`); notes are **vector-embedded server-side** (BYOK, same gemini→openai auto-pick seam as clip search; no key fail-softs to keyword-only) and `search` runs the hybrid keyword+semantic lookup over every file's name/folder/notes via `POST /me/attachments/search` — the My Files mirror of `/clips/search`. Write+annotate are what let the copilot persist Getting Started context (About.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) and character-consistency pairs (`about_character.md` + `character_sprite_card.png`) namescoped under a product/offer folder; the system prompt in `src/editor-chat.ts` drives when to save and annotate. The devcli mirrors are `vidfarm put-file [--notes]`, `annotate-file`, and `files --search`.
+Beyond the Editor Action API, the chat harness registers shared tools defined in **two synced copies** (`src/app.ts` for the in-process dev server and `infra/lambda/editor-chat.ts` for the deployed Lambda — keep them in lockstep): `http_request` (allowlisted REST/primitive calls), `frontend_action` (tracer/thread state), `video_context`, `load_skill`, and `browse_files`. `load_skill` is the copilot's knowledge-on-demand seam: it fetches vendored skill-pack content (SKILL.md or a reference file) from the host's public `/skill/:name` + `/skill-pack/:name/files/*` mirror routes (backed by `.agents/skills/`, shipped in the api Docker image), size-capped, with the pack catalog + one-liners defined once in `EDITOR_CHAT_SKILL_PACKS` (`src/editor-chat.ts`) and shared by both copies. The stream-loop guardrails (`redactUnverifiedJobIds`, `buildEditorChatGuardrailNotice`, async-job handoff text) also live in `src/editor-chat.ts` and are imported by both copies — never re-implement them locally. `editor_action`'s `replace_composition_html` is lint-gated in the tool `execute` via `src/services/composition-lint.ts` (a rejected result carries `rejected: true` + `lint_errors` and omits `action_type`, so the browser never applies it). `browse_files` reads **and writes** the caller's My Files library — `action=list`/`search`/`read`/`write`/`annotate`. `write` saves a text file (md/txt/csv/json/srt/vtt) via `POST /me/attachments/upload`, or **imports a durable media URL** into the library when `source_url` is passed (how a generated `character_sprite_card.png` gets persisted instead of stranding in a job result). `annotate` sets free-form metadata `notes` on any entry (`PATCH /me/attachments/:id`); notes are **vector-embedded server-side** (BYOK, same gemini→openai auto-pick seam as clip search; no key fail-softs to keyword-only) and `search` runs the hybrid keyword+semantic lookup over every file's name/folder/notes via `POST /me/attachments/search` — the My Files mirror of `/clips/search`. Write+annotate are what let the copilot persist Getting Started context (About.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) and character-consistency pairs (`about_character.md` + `character_sprite_card.png`) namescoped under a product/offer folder; the system prompt in `src/editor-chat.ts` drives when to save and annotate. The devcli mirrors are `vidfarm put-file [--notes]`, `annotate-file`, and `files --search`.
 
 ## Primitives
 
@@ -322,9 +322,14 @@ Per-stage config is loaded via `.env.<stage>`. Critical variables:
 - `GHOSTCUT_KEY`, `GHOSTCUT_SECRET` — GhostCut credentials
 - `RAPIDAPI_KEY` — shared RapidAPI credential used by the `video_download` and `image_remove_background` primitives. Same key is set in both `.env.staging` and `.env.production`.
 - Provider fallback keys for platform-owned features that don't have a caller yet (bootstrap only)
+- `HYPERFRAMES_NO_TELEMETRY=1` + `HYPERFRAMES_SKIP_SKILLS=1` — baked into every vidfarm-managed environment (api Docker image, CDK `hyperframesLambdaEnvironment`, devcli serve/spawns). The bundled hyperframes CLI defaults telemetry ON and auto-refreshes skills from its upstream GitHub org; these kill both. Never unset them, and never run `hyperframes auth`/`cloud`/`publish`/`play`/`feedback` — those are third-party account/hosting surfaces vidfarm replaces.
 
 Never commit `.env.staging` or `.env.production` — both are gitignored.
 
+## Skill packs (vendored mirror)
+
+`.agents/skills/` holds the vidfarm-scrubbed skill packs (the HyperFrames suite with every upstream-vendor dependency replaced by vidfarm primitives, plus `vidfarm-media` — the shared audio engine implementing the neutral `audio_request.json` → `audio_engine_meta.json` contract). `.claude/skills/*` are symlinks into it. The api serves the packs publicly: `GET /skill/:name` (SKILL.md), `GET /skill-pack/index.json` (catalog), `GET /skill-pack/:name/manifest.json` (file list + sha256), `GET /skill-pack/:name/files/<path>` (bytes, path-guarded) — `src/app.ts` next to `PUBLIC_SKILL_FILES`. Consumers: `vidfarm skills list|add|update` (devcli installer, writes `skills-lock.json` with reproducible folder hashes) and the web copilot's `load_skill` tool. When editing a pack, edit `.agents/skills/<name>` directly (the canonical copy), keep it free of upstream vendor accounts/endpoints, and re-run `vidfarm skills update`-side hash pinning as needed.
+
 ## Deployment
 
 CDK stacks are under `infra/cdk/`:

package/demo/dist/app.js

@@ -704,7 +704,8 @@ for myself`,y:43},{text:`1/10 when I chose
 myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-audio`,label:"Original audio",kind:"audio",mode:"both",start:0,duration:t.duration,track:1,z:1,viralNote:"Continuous source audio across scene cuts.",src:t.media.src,playbackStart:0,volume:1,muted:!1},...r.map((o,i)=>({...n,id:`${t.id}-caption-${10-i}`,label:`${10-i}/10 caption`,text:o.text,start:e[i],duration:e[i+1]-e[i],y:o.y}))]}function WX(t){if(t.media.type!=="video")return[];let e=T6(t.media.src);return[{id:`${t.id}-video`,label:e,kind:"video",mode:"both",start:0,duration:t.duration,track:0,z:0,viralNote:"Editable source visual track.",src:t.media.src},{id:`${t.id}-audio`,label:"Original audio",kind:"audio",mode:"both",start:0,duration:t.duration,track:1,z:1,viralNote:"Editable source audio track.",src:t.media.src,volume:1,muted:!1}]}function B1(t){return t.id==="slides"?GX():t.id==="simple-video"?qm.filter(e=>e.mode==="both"||e.mode==="publish"):t.id==="hard-video"?$X(t):t.id==="medium-easy-video"?qX(t):t.id==="medium-video-loop-split"?jX(t):t.id==="medium-video"?VX(t):WX(t)}function w6(t){return B1(t).reduce((e,n)=>Math.max(e,n.start+n.duration),t.duration)}function YX(t){let e=t.filter(n=>n.duration>0);for(let n=0;n<e.length;n+=1){let r=e[n];for(let o of e.slice(n+1))if(Yd(r,o))throw new Error(`Track collision: ${r.id} overlaps ${o.id} on track ${r.track}.`)}}function x6(t){return t.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;")}function He(t){return x6(String(t))}function Vt(t){return Number(t.toFixed(3)).toString()}function Lm(t){let e=t.fontSize??18,n=t.fontFamily??"TikTok Sans",r=t.fontWeight??Fs(n),o=["position:absolute",`left:${t.x??0}%`,`top:${t.y??0}%`,`width:${t.width??100}%`,`height:${t.height??100}%`,`z-index:${t.z}`,"opacity:1",`border-radius:${t.radius??0}px`,"overflow:hidden"];return(t.kind==="video"||t.kind==="image")&&o.push("object-fit:cover"),(t.kind==="text"||t.kind==="caption"||t.kind==="shape")&&o.push("display:flex","align-items:center","justify-content:center","padding:3px",`font-family:${zs(n)}, 'TikTok Sans', Montserrat, Abel`,`font-weight:${r}`,"line-height:1.48","text-align:center","text-transform:none",`font-size:${e}px`,`color:${t.color??"#ffffff"}`,"background:transparent"),o.join(";")}function KX(t){let e=[`id="${He(t.id)}"`,`data-hf-id="${He(t.id)}"`,`data-layer-mode="${He(t.mode)}"`,`data-layer-kind="${He(t.kind)}"`,`data-viral-note="${He(t.viralNote)}"`,`data-start="${Vt(t.start)}"`,`data-duration="${Vt(t.duration)}"`,`data-track-index="${t.track}"`,`data-label="${He(t.label)}"`];return(t.kind==="text"||t.kind==="caption"||t.kind==="shape")&&e.push(`data-text-background-style="${He(t.textBackgroundStyle??"highlight-solid")}"`,`data-text-background-color="${He(t.background??"#000000")}"`,`data-font-family="${He(t.fontFamily??"TikTok Sans")}"`),t.customHtml&&e.push('data-layer-format="html"'),(t.kind==="video"||t.kind==="audio")&&t.playbackStart!==void 0&&e.push(`data-media-start="${Vt(t.playbackStart)}"`,`data-playback-start="${Vt(t.playbackStart)}"`),e.join(" ")}function XX(t){let e=KX(t);if(t.kind==="video")return t.playbackStart!==void 0?`<div ${e} data-vf-timeline-proxy="video" data-src="${He(t.src??"")}" style="${He(Lm({...t,x:0,y:0,width:1,height:1}))};display:none;pointer-events:none;"></div>`:`<video ${e} src="${He(t.src??"")}" muted playsinline preload="auto" style="${He(Lm(t))}"></video>`;if(t.kind==="audio")return`<audio ${e} src="${He(t.src??"")}" data-timeline-role="music" data-volume="${Vt(t.volume??1)}" ${t.muted?"muted":""} preload="metadata"></audio>`;if(t.kind==="image")return`<img ${e} src="${He(t.src??"")}" alt="" style="${He(Lm(t))}" />`;if(t.customHtml)return`<div ${e} style="${He(Lm(t))}">${t.customHtml}</div>`;let n=t.text??t.label,r=S6(t.textBackgroundStyle??"highlight-solid",t.color??"#ffffff",t.background??"#000000",t.fontFamily??"TikTok Sans",t.fontWeight??Fs(t.fontFamily??"TikTok Sans")),o=E6(t.textBackgroundStyle??"highlight-solid");return`<div ${e} style="${He(Lm(t))}"><span data-vf-text-lines="true" style="${He(o)}"><span data-vf-text-inline="true" style="${He(r)}">${x6(n)}</span></span></div>`}function JX(t,e){return t==="shape"&&e?"HTML":t}function QX(t,e){return t==="shape"&&e?"HTML":t.slice(0,3).toUpperCase()}function ZX(t,e){if(t.media.type!=="video"||!e.some(o=>o.kind==="video"&&o.playbackStart!==void 0))return"";let r=["position:absolute","left:0%","top:0%","width:100%","height:100%","z-index:0","object-fit:cover","background:#050604"].join(";");return`<video data-vf-playback-source="true" src="${He(t.media.src)}" muted playsinline preload="auto" style="${He(r)}"></video>`}function A6(){return`<script>
 (() => {
   const root = document.querySelector("[data-composition-id]");
-  let duration = Number(root?.getAttribute("data-duration") || 0);
+  let declaredDuration = Number(root?.getAttribute("data-duration") || 0);
+  let duration = declaredDuration;
   let time = 0;
   let playing = false;
   let playbackRate = 1;
@@ -752,8 +753,8 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
     // The parent editor can live-swap the composition DOM (undo/redo). Re-read
     // everything derivable from the document so a swap never leaves the player
     // clamped to a stale duration or a stale authored-mute state.
-    duration = Number(root?.getAttribute("data-duration") || 0);
-    time = clampTime(time);
+    declaredDuration = Number(root?.getAttribute("data-duration") || 0);
+    duration = declaredDuration;
     clips = Array.from(document.querySelectorAll("[data-start]")).filter((node) => node !== root);
     for (const clip of clips) {
       if (clip instanceof HTMLMediaElement) {
@@ -776,6 +777,9 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
     activeVideoProxyKey = null;
     activeVideoProxyNode = null;
     hasVideoProxies = clips.some((clip) => clip instanceof Element && clip.getAttribute("data-vf-timeline-proxy") === "video");
+    ensureDuration();
+    time = clampTime(time);
+    discoverGeneralCssAnimations();
     apply(time, { forceSeek: true });
   }
 
@@ -848,6 +852,130 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
     }
   }
 
+  // Runtime-adapter bridge \u2014 mirrors the official @hyperframes/producer
+  // deterministic adapters so compositions driven by a registered GSAP
+  // timeline (window.__timelines), Anime.js (window.__hfAnime), Lottie
+  // (window.__hfLottie), or Three.js/TypeGPU (window.__hfThreeTime/
+  // __hfTypegpuTime + the hf-seek CustomEvent) scrub with the player instead
+  // of running on the wall clock. Everything is duck-typed and try/caught so
+  // a broken composition script never kills the apply loop.
+  function compositionTimeline() {
+    let registry = null;
+    try { registry = window.__timelines; } catch { return null; }
+    if (!registry || typeof registry !== "object") return null;
+    const compId = root?.getAttribute("data-composition-id") || "";
+    let timeline = compId ? registry[compId] : null;
+    if (!timeline) {
+      const keys = Object.keys(registry);
+      if (keys.length === 1) timeline = registry[keys[0]];
+    }
+    if (!timeline || typeof timeline.pause !== "function") return null;
+    if (typeof timeline.totalTime !== "function" && typeof timeline.seek !== "function") return null;
+    return timeline;
+  }
+
+  function timelineDuration(timeline) {
+    try {
+      const value = typeof timeline.duration === "function" ? Number(timeline.duration()) : Number(timeline.duration);
+      if (Number.isFinite(value) && value > 0) return value;
+    } catch {}
+    return 0;
+  }
+
+  function syncTimeline() {
+    const timeline = compositionTimeline();
+    if (!timeline) return;
+    try {
+      timeline.pause();
+      // Official gsap adapter seek: nudge to time+1ms with suppressed events,
+      // then land exactly, so gsap re-renders even when the target equals the
+      // timeline's current time.
+      if (typeof timeline.totalTime === "function") {
+        timeline.totalTime(time + 0.001, true);
+        timeline.totalTime(time, false);
+      } else {
+        timeline.seek(time, false);
+      }
+    } catch {}
+  }
+
+  function syncAnimeInstances() {
+    let instances = null;
+    try { instances = window.__hfAnime; } catch { return; }
+    if (!Array.isArray(instances) || instances.length === 0) return;
+    const ms = Math.max(0, time) * 1000;
+    for (const instance of instances) {
+      try {
+        if (instance && typeof instance.seek === "function") instance.seek(ms);
+      } catch {}
+    }
+  }
+
+  function syncLottiePlayers() {
+    let players = null;
+    try { players = window.__hfLottie; } catch { return; }
+    if (!Array.isArray(players) || players.length === 0) return;
+    const safe = Math.max(0, time);
+    for (const player of players) {
+      try {
+        if (!player || typeof player !== "object") continue;
+        if (typeof player.goToAndStop === "function") {
+          player.goToAndStop(safe * 1000, false);
+        } else if (typeof player.pause === "function" && ("totalFrames" in player || "duration" in player)) {
+          if (typeof player.setCurrentRawFrameValue === "function") {
+            const totalFrames = player.totalFrames ?? 0;
+            const frameRate = player.frameRate ?? 30;
+            if (totalFrames > 0) player.setCurrentRawFrameValue(Math.min(safe * frameRate, totalFrames - 1));
+          } else if (typeof player.seek === "function") {
+            player.seek(Math.min(100, (safe / (player.duration ?? 1)) * 100));
+          }
+        }
+      } catch {}
+    }
+  }
+
+  let lastDispatchedSeekTime = -1;
+  function syncSeekGlobals() {
+    const safe = Math.max(0, time);
+    try { window.__hfThreeTime = safe; } catch {}
+    try { window.__hfTypegpuTime = safe; } catch {}
+    // The official three/typegpu adapters dedupe the hf-seek dispatch on the
+    // last dispatched time.
+    if (safe === lastDispatchedSeekTime) return;
+    lastDispatchedSeekTime = safe;
+    try { window.dispatchEvent(new CustomEvent("hf-seek", { detail: { time: safe } })); } catch {}
+  }
+
+  function syncRuntimeAdapters() {
+    syncTimeline();
+    syncAnimeInstances();
+    syncLottiePlayers();
+    syncSeekGlobals();
+  }
+
+  // data-duration on the root is authoritative when present. Arbitrary
+  // compositions may omit it, so infer the duration from clip extents,
+  // preferring a registered GSAP timeline that reports a longer duration.
+  // Recomputed on every apply so a timeline registered after load still
+  // corrects the duration (and seek clamping) lazily.
+  function ensureDuration() {
+    if (declaredDuration > 0) {
+      duration = declaredDuration;
+      return;
+    }
+    let inferred = 0;
+    for (const clip of clips) {
+      const timing = readTiming(clip);
+      if (timing.end > inferred) inferred = timing.end;
+    }
+    const timeline = compositionTimeline();
+    if (timeline) {
+      const reported = timelineDuration(timeline);
+      if (reported > inferred) inferred = reported;
+    }
+    duration = inferred;
+  }
+
   function deriveTimelineTimeFromBackingVideo() {
     if (!(backingVideo instanceof HTMLVideoElement)) return null;
     if (activeVideoProxyNode instanceof Element && !activeVideoProxyNode.isConnected) {
@@ -1017,19 +1145,138 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
     }
   }
 
+  // Generalized CSS keyframe scrub \u2014 the preview twin of the official
+  // producer CSS adapter: every element whose computed animation-name is set
+  // gets its animations paused and scrubbed to the player time relative to
+  // the nearest ancestor-or-self [data-start] (0 when none). vf-* animations
+  // (Ken Burns, transitions, captions) keep their dedicated machinery above.
+  // Discovery is cached per refreshClips like the official adapter's discover
+  // pass; elements added by live patches are picked up on the next refresh.
+  // Each entry also caches its clip-relative start at discovery so the
+  // per-frame sync skips the ancestor walk; a re-parented or retimed element
+  // is likewise re-resolved on the next refreshClips discovery.
+  let generalCssEntries = [];
+
+  function discoverGeneralCssAnimations() {
+    generalCssEntries = [];
+    let nodes = [];
+    try { nodes = document.querySelectorAll("*"); } catch { return; }
+    for (const node of nodes) {
+      if (!(node instanceof HTMLElement) || typeof node.getAnimations !== "function") continue;
+      let names = "";
+      try { names = getComputedStyle(node).animationName || ""; } catch { continue; }
+      if (!names || names === "none") continue;
+      const expected = [];
+      for (const name of names.split(",")) {
+        const trimmed = name.trim();
+        if (!trimmed || trimmed === "none" || trimmed.indexOf("vf-") === 0) continue;
+        expected.push(trimmed);
+      }
+      if (expected.length) generalCssEntries.push({ el: node, names: expected, start: generalClipStartFor(node) });
+    }
+  }
+
+  function hasAnimationNamed(anims, name) {
+    for (const anim of anims) {
+      if (anim.animationName === name) return true;
+    }
+    return false;
+  }
+
+  function generalClipStartFor(node) {
+    const holder = node.closest("[data-start]");
+    return holder ? readNumberAttr(holder, ["data-start"], 0) : 0;
+  }
+
+  // Cycling animation-name through none re-creates dropped CSS animations
+  // declaratively (same trick as the caption resurrection above), preserving
+  // any authored inline animation-name.
+  function resurrectCssAnimations(node) {
+    try {
+      const inline = node.style.animationName;
+      node.style.animationName = "none";
+      void node.offsetWidth;
+      if (inline && inline !== "none") {
+        node.style.animationName = inline;
+      } else {
+        node.style.removeProperty("animation-name");
+      }
+    } catch {}
+  }
+
+  function scrubGeneralAnimation(anim, offsetMs) {
+    let target = offsetMs;
+    try {
+      const computed = anim.effect && typeof anim.effect.getComputedTiming === "function"
+        ? anim.effect.getComputedTiming()
+        : null;
+      const endTime = computed && typeof computed.endTime === "number" ? computed.endTime : NaN;
+      if (Number.isFinite(endTime) && offsetMs >= endTime) {
+        // Same Chrome guard as the caption scrub: paused fill:none/backwards
+        // animations pushed past their effect end are destroyed permanently,
+        // so park them at 0; fill:forwards/both hold their final keyframe at
+        // the clamped end. Infinite-iteration animations (endTime Infinity)
+        // take the raw clip-relative offset like the official CSS adapter \u2014
+        // the browser resolves the iteration phase.
+        target = computed.fill === "forwards" || computed.fill === "both" ? endTime : 0;
+      }
+    } catch {}
+    try {
+      anim.pause();
+      anim.currentTime = target;
+    } catch {}
+  }
+
+  function syncGeneralCssAnimations() {
+    for (const entry of generalCssEntries) {
+      const node = entry.el;
+      if (!node.isConnected) continue;
+      const offsetMs = Math.max(0, time - entry.start) * 1000;
+      let anims = [];
+      try { anims = node.getAnimations(); } catch { continue; }
+      let missing = null;
+      for (const name of entry.names) {
+        if (!hasAnimationNamed(anims, name)) (missing || (missing = [])).push(name);
+      }
+      if (missing) {
+        resurrectCssAnimations(node);
+        try { anims = node.getAnimations(); } catch { anims = []; }
+        // Names that still have no live animation (e.g. a display:none
+        // subtree) are dropped until the next discovery so a hidden element
+        // is not forced through a reflow every frame.
+        entry.names = entry.names.filter((name) => missing.indexOf(name) === -1 || hasAnimationNamed(anims, name));
+      }
+      for (const anim of anims) {
+        if (typeof anim.animationName !== "string" || anim.animationName.indexOf("vf-") === 0) continue;
+        scrubGeneralAnimation(anim, offsetMs);
+      }
+    }
+  }
+
   function apply(nextTime, options = {}) {
     const forceSeek = Boolean(options.forceSeek);
     const fromClock = Boolean(options.fromClock);
+    ensureDuration();
     time = clampTime(nextTime);
     let activeVideoProxy = null;
+    let activeVideoProxyStart = -Infinity;
     const transitionWindows = collectTransitionWindows();
     for (const clip of clips) {
       const timing = readTiming(clip);
       const hold = transitionHoldFor(clip, timing, transitionWindows);
-      const active = time >= timing.start && time < timing.end + hold;
+      // hyperframes-core clip windows are inclusive of both ends \u2014 the final
+      // frame holds.
+      const active = time >= timing.start && time <= timing.end + hold;
       if (clip instanceof HTMLElement && !(clip instanceof HTMLAudioElement)) {
         if (clip.getAttribute("data-vf-timeline-proxy") === "video") {
-          if (active) activeVideoProxy = clip;
+          // Clip windows are inclusive of both ends, so at an exact butt-cut
+          // the outgoing AND incoming proxies are both active. Prefer the
+          // greatest data-start (timeline order \u2014 the incoming clip wins);
+          // DOM order only breaks ties between equal starts.
+          if (active && timing.start >= activeVideoProxyStart) {
+            activeVideoProxy = clip;
+            activeVideoProxyStart = timing.start;
+          }
         } else {
           setVisibility(clip, active);
         }
@@ -1053,6 +1300,8 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
         }
       }
     }
+    syncGeneralCssAnimations();
+    syncRuntimeAdapters();
     if (backingVideo instanceof HTMLVideoElement) {
       applyMediaState(backingVideo);
       const shouldShowBackingVideo = !hasVideoProxies || Boolean(activeVideoProxy);
@@ -1161,10 +1410,45 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
       if (!playing) apply(time, { forceSeek: true });
     });
   }
+  window.addEventListener("load", () => {
+    // Composition scripts may register adapter instances (GSAP timelines,
+    // Lottie players, ...) or start CSS animations on the load event \u2014
+    // re-discover and re-scrub so late registrations preview correctly.
+    discoverGeneralCssAnimations();
+    if (!playing) apply(time, { forceSeek: true });
+  });
+
+  // Cache the parent frame's origin from the first accepted control message
+  // and pin all outbound postMessages to it. Falls back to document.referrer's
+  // origin so drag/select events still reach the editor before any control
+  // message has been received. Without pinning, sending "*" leaks preview
+  // frame coordinates and layer ids to any embedding third-party page.
+  let trustedParentOrigin = null;
+  try {
+    if (document.referrer) {
+      trustedParentOrigin = new URL(document.referrer).origin;
+    }
+  } catch {}
+  function parentTargetOrigin() {
+    return trustedParentOrigin || "*";
+  }
+  function postToParent(payload) {
+    if (!window.parent || window.parent === window) return;
+    try {
+      window.parent.postMessage(payload, parentTargetOrigin());
+    } catch {}
+  }
 
 		  window.addEventListener("message", (event) => {
+		    // Only accept messages from the direct parent frame. Blocks sibling
+		    // iframes and popups that could otherwise spoof play/pause/seek by
+		    // forging data.source.
+		    if (event.source !== window.parent) return;
 		    const data = event.data || {};
 		    if (data.type !== "control" && data.source !== "hf-parent") return;
+		    if (event.origin && event.origin !== "null") {
+		      trustedParentOrigin = event.origin;
+		    }
 	    if (data.action === "play") {
 	      window.__player.play();
 	    }
@@ -1206,11 +1490,11 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
 	    const target = selectTargetFromEvent(event);
 	    const rawId = target?.getAttribute("data-hf-id") || target?.id || null;
       const id = rawId === "source-video" ? null : rawId;
-	    window.parent?.postMessage({
+	    postToParent({
 	      source: "vidfarm-composition",
 	      action: "select-layer",
 	      id
-	    }, "*");
+	    });
     }
 
     function postPreviewContextMenu(event) {
@@ -1222,7 +1506,7 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
       const id = rawId === "source-video" ? null : rawId;
       const x = rect ? ((event.clientX - rect.left) / Math.max(1, rect.width)) * 100 : 12;
       const y = rect ? ((event.clientY - rect.top) / Math.max(1, rect.height)) * 100 : 70;
-      window.parent?.postMessage({
+      postToParent({
         source: "vidfarm-composition",
         action: "preview-context-menu",
         id,
@@ -1235,7 +1519,7 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
           width: 42,
           height: 12
         }
-      }, "*");
+      });
     }
 
     function frameFromNode(node) {
@@ -1338,13 +1622,13 @@ myself`,y:22}];return[...U1(t,e,r.map((o,i)=>`${10-i}/10 scene`)),{id:`${t.id}-a
     function postFrameDraft(node, phase) {
       const id = node.getAttribute("data-hf-id") || node.id || null;
       if (!id) return;
-      window.parent?.postMessage({
+      postToParent({
         source: "vidfarm-composition",
         action: "visual-frame-draft",
         phase,
         id,
         frame: frameFromNode(node)
-      }, "*");
+      });
     }
 
     let visualFrameDrag = null;