Merge main into feat/studio-webmcp-frame

Resolve conflicts from squash-merged #3515 (selection tools).
Branch retains frame + inspect tools from the stack.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: miga-heygen

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hyperframes",
   "description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
-  "version": "0.8.16",
+  "version": "0.8.20",
   "author": {
     "name": "HeyGen",
     "email": "hyperframes@heygen.com",

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hyperframes",
   "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
-  "version": "0.8.16",
+  "version": "0.8.20",
   "author": {
     "name": "HeyGen",
     "email": "hyperframes@heygen.com",

.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "hyperframes",
   "displayName": "HyperFrames by HeyGen",
   "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
-  "version": "0.8.16",
+  "version": "0.8.20",
   "author": {
     "name": "HeyGen",
     "email": "hyperframes@heygen.com"

docs/changelog.mdx

@@ -8,6 +8,77 @@ Recent HyperFrames releases, including user-facing features, fixes, and migratio
 
 {/* New release entries are prepended by `bun run changelog:draft <version> --write`. */}
 
+<Update
+  label="HyperFrames v0.8.20"
+  description="Released - 2026-08-30"
+  tags={["Release", "Studio"]}
+>
+Studio now separates blocked direct edits from real save failures and keeps the file and HTTP details needed to diagnose them.
+Repeated failures are grouped, and write tracking now works in more secure browser contexts.
+
+## Fixes
+
+- **Studio:** Correct save failure telemetry ([28be8dddfa](https://github.com/heygen-com/hyperframes/commit/28be8dddfacefe29b5e25ae2d36fd76ffe4c4852), [#3499](https://github.com/heygen-com/hyperframes/pull/3499)).
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.8.19...v0.8.20).
+</Update>
+
+<Update
+  label="HyperFrames v0.8.19"
+  description="Released - 2026-08-29"
+  tags={["Release", "Studio"]}
+>
+Export in Studio now renders the composition you have selected, not the project's root file. Multi-part projects can finally be exported without dropping to the CLI.
+
+## Fixes
+
+- **Studio:** Export the composition the user has selected ([b71f45981](https://github.com/heygen-com/hyperframes/commit/b71f45981c376d3b2b4ae8e07a0837f63a091a8c), [#3550](https://github.com/heygen-com/hyperframes/pull/3550)).
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.8.18...v0.8.19).
+</Update>
+
+<Update
+  label="HyperFrames v0.8.18"
+  description="Released - 2026-08-29"
+  tags={["Release", "Studio", "Core", "CLI"]}
+>
+Studio now switches the canvas and timeline for compositions stored anywhere in a project. Snapshots now preserve playback rate, nested-media timing, static compositions, and source files.
+
+## Fixes
+
+- **Studio:** Switch the canvas and timeline for compositions stored outside `compositions/` ([adf9b0cce](https://github.com/heygen-com/hyperframes/commit/adf9b0cceeb561fd5424e8cad73b781f5383a9ef)).
+- **Core:** Keep long nested videos visible when their local start precedes the host window ([3dc185623](https://github.com/heygen-com/hyperframes/commit/3dc18562323c9dd7dfa1f9416d90708677f3652b), [#3535](https://github.com/heygen-com/hyperframes/pull/3535)).
+- **CLI:** Capture the correct source frame for trimmed or accelerated videos ([d99eeef0b](https://github.com/heygen-com/hyperframes/commit/d99eeef0b27460683831664b4ac68f5cf4f700cd), [#3536](https://github.com/heygen-com/hyperframes/pull/3536)).
+- **CLI:** Reject keyframe-shot outputs that would overwrite the active composition source ([e4dabf830](https://github.com/heygen-com/hyperframes/commit/e4dabf830c6cf377734de043d5f5345bcefe7b02), [#3534](https://github.com/heygen-com/hyperframes/pull/3534)).
+- **CLI:** Allow intentional `data-no-timeline` compositions without false frozen-sweep errors ([b28747df0](https://github.com/heygen-com/hyperframes/commit/b28747df0f2db9c5e7148e188a6ce6b99bcdda85), [#3533](https://github.com/heygen-com/hyperframes/pull/3533)).
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.8.17...v0.8.18).
+</Update>
+
+<Update
+  label="HyperFrames v0.8.17"
+  description="Released - 2026-08-28"
+  tags={["Release", "Studio", "Producer", "Engine"]}
+>
+Studio now exposes live editing state to agentic browsers, including browsers without native WebMCP. Renders now fail instead of silently succeeding when sub-compositions, media extraction, or artifact validation break, while nested runtime videos keep distinct identities.
+
+## Features
+
+- **Studio:** Fall back to a WebMCP polyfill where the browser has none ([097d901d7](https://github.com/heygen-com/hyperframes/commit/097d901d703be01781a47f2a8aa2dc65e0a3e19e), [#3514](https://github.com/heygen-com/hyperframes/pull/3514)).
+- **Studio:** Expose Studio's live state to an agentic browser (WebMCP) ([94da403d6](https://github.com/heygen-com/hyperframes/commit/94da403d6d9e3bdf23665794572a90918832036d), [#3511](https://github.com/heygen-com/hyperframes/pull/3511)).
+
+## Fixes
+
+- **Producer:** Enforce video extraction failures by default (#3372) ([4d87f8bba](https://github.com/heygen-com/hyperframes/commit/4d87f8bbae3d4cda71f75fa33e8d48ce38a3afc7), [#3526](https://github.com/heygen-com/hyperframes/pull/3526)).
+- **Core,producer:** Stamp render ids on empty-src media and pair the snapshot by them ([9eb84c91b](https://github.com/heygen-com/hyperframes/commit/9eb84c91b6a785028d6bc4c122b633bda0741c7f), [#3513](https://github.com/heygen-com/hyperframes/pull/3513)).
+- **Engine:** Fail render on sub-composition script failures (#3352) ([e69be30e9](https://github.com/heygen-com/hyperframes/commit/e69be30e985a32a70d04de607763135884246193), [#3528](https://github.com/heygen-com/hyperframes/pull/3528)).
+- **Producer:** Assert render artifact duration and frame count before commit ([05275c1e8](https://github.com/heygen-com/hyperframes/commit/05275c1e8ce3bee6d331cca9ff9c8eec02c34977), [#3506](https://github.com/heygen-com/hyperframes/pull/3506)).
+- **Core:** Read CSS animation opacity through color grading's own hide (#3329) ([e5c7dc75e](https://github.com/heygen-com/hyperframes/commit/e5c7dc75e8ae7146d81d07e1f0e0731d4ad9eb6c), [#3507](https://github.com/heygen-com/hyperframes/pull/3507)).
+- **Studio:** Let a failed DOM edit report that it failed ([21bcd5745](https://github.com/heygen-com/hyperframes/commit/21bcd5745cc0d8bb4c51363ef4183b343cbbd169), [#3510](https://github.com/heygen-com/hyperframes/pull/3510)).
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.8.16...v0.8.17).
+</Update>
+
 <Update
   label="HyperFrames v0.8.16"
   description="Released - 2026-08-27"

packages/aws-lambda/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/aws-lambda",
-  "version": "0.8.16",
+  "version": "0.8.20",
   "description": "AWS Lambda adapter for HyperFrames distributed rendering — handler, client-side SDK, and CDK construct.",
   "repository": {
     "type": "git",

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.8.16",
+  "version": "0.8.20",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "license": "Apache-2.0",
   "repository": {

packages/cli/src/commands/check.test.ts

@@ -145,6 +145,7 @@ function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver
   return {
     initialize: vi.fn(async (_contrast: boolean) => undefined),
     getDuration: vi.fn(async () => 9),
+    hasNoTimelineDeclaration: vi.fn(async () => false),
     getTransitionBoundaries: vi.fn(async () => []),
     getCanvas: vi.fn(async () => ({ width: 1920, height: 1080 })),
     findAmbiguousSelectors: vi.fn(async (_selectors: string[]) => []),
@@ -1222,6 +1223,18 @@ describe("check pipeline", () => {
       ).toBe(true);
     });
 
+    it("does not flag intentional static content declared with data-no-timeline", async () => {
+      const driver = fakeDriver({
+        getDuration: vi.fn(async () => 6),
+        hasNoTimelineDeclaration: vi.fn(async () => true),
+        collectLayoutGeometry: vi.fn(async () => "frozen"),
+      });
+
+      const { report } = await runScenario(driver);
+
+      expect(report.layout.findings.some((finding) => finding.code === "sweep_static")).toBe(false);
+    });
+
     it("does not flag a 1.5s static title card — too short for the guard to apply", async () => {
       const driver = fakeDriver({
         getDuration: vi.fn(async () => 1.5),

packages/cli/src/commands/keyframes.test.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, linkSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";
@@ -28,6 +28,29 @@ describe("keyframes direct composition scope", () => {
 });
 
 describe("keyframes shot output", () => {
+  it("rejects an output path that would overwrite the composition source", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-shot-source-"));
+    const sourcePath = join(projectDir, "index.html");
+    writeFileSync(sourcePath, wrap(""));
+
+    expect(() => ensureShotOutputDir(sourcePath, sourcePath)).toThrow(
+      /must not overwrite the composition source/,
+    );
+    expect(readFileSync(sourcePath, "utf8")).toBe(wrap(""));
+  });
+
+  it("rejects an existing output alias that refers to the composition source", () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-shot-alias-"));
+    const sourcePath = join(projectDir, "index.html");
+    const aliasPath = join(projectDir, "shot.png");
+    writeFileSync(sourcePath, wrap(""));
+    linkSync(sourcePath, aliasPath);
+
+    expect(() => ensureShotOutputDir(aliasPath, sourcePath)).toThrow(
+      /must not overwrite the composition source/,
+    );
+  });
+
   it("creates a missing parent directory before writing --shot", () => {
     const projectDir = mkdtempSync(join(tmpdir(), "hf-keyframes-shot-dir-"));
     const outputDir = join(projectDir, "nested", "proofs");

packages/cli/src/commands/motionShot.ts

@@ -10,8 +10,8 @@
 // exactly what it's editing. All geometry + SVG live in ./motionShotLayout.ts
 // (pure, tested); this file only drives the browser and SAMPLES.
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { resolveDiagnosticNavigationTimeoutMs } from "../utils/renderArgs.js";
 import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
 import {
@@ -33,7 +33,25 @@ export interface ShotRequest {
   selector: string;
 }
 
-export function ensureShotOutputDir(outPath: string): void {
+function pathsReferToSameFile(firstPath: string, secondPath: string): boolean {
+  const first = resolve(firstPath);
+  const second = resolve(secondPath);
+  if (first === second) return true;
+  try {
+    const firstStat = statSync(first);
+    const secondStat = statSync(second);
+    return firstStat.dev === secondStat.dev && firstStat.ino === secondStat.ino;
+  } catch {
+    return false;
+  }
+}
+
+export function ensureShotOutputDir(outPath: string, sourcePath?: string): void {
+  if (sourcePath && pathsReferToSameFile(outPath, sourcePath)) {
+    throw new Error(
+      `--shot output must not overwrite the composition source: ${sourcePath}. Choose a separate .png path.`,
+    );
+  }
   mkdirSync(dirname(outPath), { recursive: true });
 }
 
@@ -644,7 +662,7 @@ export async function captureMotionPathShot(
   outPath: string,
   opts: ShotOptions = {},
 ): Promise<string> {
-  ensureShotOutputDir(outPath);
+  ensureShotOutputDir(outPath, resolve(projectDir, opts.entryFile ?? "index.html"));
   let requests = requestsIn;
   const samples = Math.max(1, Math.min(60, opts.samples ?? 9));
   const layout = opts.layout ?? "path";

packages/cli/src/commands/snapshot.test.ts

@@ -29,6 +29,7 @@ import snapshotCommand, {
   requireSnapshotFfmpeg,
   resolveSnapshotVideoClipStart,
   resolveSnapshotVideoFrameTime,
+  resolveSnapshotVideoPlaybackRate,
   tailFrameTime,
 } from "./snapshot.js";
 
@@ -262,6 +263,12 @@ describe("resolveSnapshotVideoClipStart", () => {
   });
 });
 
+describe("resolveSnapshotVideoPlaybackRate", () => {
+  it("prefers the authored data-playback-rate over the browser default", () => {
+    expect(resolveSnapshotVideoPlaybackRate({ authoredRate: "1.8", defaultRate: 1 })).toBe(1.8);
+  });
+});
+
 describe("computeSnapshotTimes (FINDING [7]: tail is always captured)", () => {
   it("default frames: last point is the readable tail, never exact duration", () => {
     const { times, appendedTail } = computeSnapshotTimes(8, { frames: 5 });