From ca6ac3352154753541ae1444f29f0862b699affc Mon Sep 17 00:00:00 2001
From: James <james.russo@heygen.com>
Date: Fri, 10 Jul 2026 09:32:38 -0700
Subject: [PATCH 01/24] fix(core): make timing masks safe for source loaders

---
 .../core/src/compiler/timingCompiler.test.ts     | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/packages/core/src/compiler/timingCompiler.test.ts b/packages/core/src/compiler/timingCompiler.test.ts
index cab293ebbd..aeb624370e 100644
--- a/packages/core/src/compiler/timingCompiler.test.ts
+++ b/packages/core/src/compiler/timingCompiler.test.ts
@@ -168,6 +168,22 @@ describe("compileTimingAttrs", () => {
     expect(compiled).toContain('id="hf-video-0"');
     expect(compiled).toContain('data-end="2"');
   });
+
+  it("preserves inert regions when compiled output is compiled again", () => {
+    const html = [
+      '<style>.hero::after { content: "$& $$ $` $\' <video>"; }</style>',
+      '<script>const markup = "$& $$ $` $\' <audio>";</script>',
+      '<video class="hero" src="a.mp4" data-start="0" data-duration="2">',
+    ].join("\n");
+
+    const first = compileTimingAttrs(html).html;
+    const second = compileTimingAttrs(first).html;
+
+    expect(second).toContain('<style>.hero::after { content: "$& $$ $` $\' <video>"; }</style>');
+    expect(second).toContain('<script>const markup = "$& $$ $` $\' <audio>";</script>');
+    expect(second).toContain('data-end="2"');
+    expect(second).not.toContain("HFMASK");
+  });
 });
 
 describe("injectDurations", () => {

From db21552dc33825e3661ca3621da3c52aa0180445 Mon Sep 17 00:00:00 2001
From: James <james.russo@heygen.com>
Date: Fri, 10 Jul 2026 09:47:22 -0700
Subject: [PATCH 02/24] test(producer): gate source tests by execution lane

---
 .github/workflows/ci.yml                      | 30 ++++++++
 bun.lock                                      | 27 +++----
 package.json                                  |  9 ++-
 packages/producer/package.json                | 15 +++-
 .../scripts/check-test-classification.mjs     |  9 +++
 packages/producer/scripts/run-test-lane.mjs   | 34 +++++++++
 .../producer/scripts/test-classification.mjs  | 74 +++++++++++++++++++
 .../scripts/test-classification.test.mjs      | 48 ++++++++++++
 packages/producer/src/regression-harness.ts   | 21 +++---
 .../deterministicFonts-failClosed.test.ts     |  3 +
 .../crossWorkerIdempotency.test.ts            |  3 +-
 .../services/distributed/renderChunk.test.ts  |  7 +-
 .../stages/captureStreamingStage.test.ts      | 25 ++++++-
 .../src/services/renderOrchestrator.test.ts   |  9 ++-
 .../tests/hdr-hlg-regression/README.md        |  4 +-
 .../producer/tests/hdr-regression/README.md   |  4 +-
 16 files changed, 285 insertions(+), 37 deletions(-)
 create mode 100644 packages/producer/scripts/check-test-classification.mjs
 create mode 100644 packages/producer/scripts/run-test-lane.mjs
 create mode 100644 packages/producer/scripts/test-classification.mjs
 create mode 100644 packages/producer/scripts/test-classification.test.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0ed4b23197..cc38804287 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -235,6 +235,36 @@ jobs:
       - run: bun run --cwd packages/core build:hyperframes-runtime
       - run: bun run --filter '!@hyperframes/producer' test
 
+  producer-source-tests:
+    name: "Producer: ${{ matrix.lane }} tests"
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        lane: [unit, integration]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          lfs: true
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+      - name: Install FFmpeg for integration tests
+        if: matrix.lane == 'integration'
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends ffmpeg
+      - uses: ./.github/actions/prepare-ffmpeg-bin
+      - run: bun install --frozen-lockfile
+      - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
+      - run: bun run --cwd packages/core build
+      - run: bun run --filter @hyperframes/engine build
+      - run: bun run producer:test:${{ matrix.lane }}
+
   # Tests under skills/**/*.test.mjs are bare `node --test` files with only
   # `node:` built-in imports. They aren't part of any workspace package, and
   # the main `Test` job's `code` path filter excludes `skills/**`, so without
diff --git a/bun.lock b/bun.lock
index c6eb53154d..4339fb118a 100644
--- a/bun.lock
+++ b/bun.lock
@@ -22,7 +22,7 @@
     },
     "packages/aws-lambda": {
       "name": "@hyperframes/aws-lambda",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.700.0",
         "@aws-sdk/client-sfn": "^3.700.0",
@@ -54,7 +54,7 @@
     },
     "packages/cli": {
       "name": "@hyperframes/cli",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "bin": {
         "hyperframes": "./dist/cli.js",
       },
@@ -103,7 +103,7 @@
     },
     "packages/core": {
       "name": "@hyperframes/core",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@chenglou/pretext": "^0.0.5",
         "@hyperframes/lint": "workspace:*",
@@ -128,7 +128,7 @@
     },
     "packages/engine": {
       "name": "@hyperframes/engine",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@hono/node-server": "^1.13.0",
         "@hyperframes/core": "workspace:^",
@@ -146,7 +146,7 @@
     },
     "packages/gcp-cloud-run": {
       "name": "@hyperframes/gcp-cloud-run",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@google-cloud/storage": "^7.14.0",
         "@google-cloud/workflows": "^4.2.0",
@@ -166,7 +166,7 @@
     },
     "packages/lint": {
       "name": "@hyperframes/lint",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@hyperframes/parsers": "workspace:*",
         "htmlparser2": "^10.1.0",
@@ -183,7 +183,7 @@
     },
     "packages/parsers": {
       "name": "@hyperframes/parsers",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@babel/parser": "^7.27.0",
         "acorn": "^8.17.0",
@@ -203,7 +203,7 @@
     },
     "packages/player": {
       "name": "@hyperframes/player",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
       },
@@ -218,7 +218,7 @@
     },
     "packages/producer": {
       "name": "@hyperframes/producer",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@fontsource/archivo-black": "^5.2.8",
         "@fontsource/eb-garamond": "^5.2.7",
@@ -258,11 +258,12 @@
         "esbuild": "^0.25.12",
         "tsx": "^4.21.0",
         "typescript": "^5.7.2",
+        "vitest": "^3.2.4",
       },
     },
     "packages/sdk": {
       "name": "@hyperframes/sdk",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
@@ -289,7 +290,7 @@
     },
     "packages/shader-transitions": {
       "name": "@hyperframes/shader-transitions",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "html2canvas": "^1.4.1",
       },
@@ -301,7 +302,7 @@
     },
     "packages/studio": {
       "name": "@hyperframes/studio",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.1",
         "@codemirror/commands": "^6.10.3",
@@ -349,7 +350,7 @@
     },
     "packages/studio-server": {
       "name": "@hyperframes/studio-server",
-      "version": "0.7.45",
+      "version": "0.7.48",
       "dependencies": {
         "@hyperframes/core": "workspace:*",
         "@hyperframes/parsers": "workspace:*",
diff --git a/package.json b/package.json
index 5535bb035e..12d17ffce3 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,14 @@
     "lint:fix": "oxlint --fix .",
     "check:tracked-artifacts": "node scripts/check-tracked-artifacts.mjs",
     "format": "oxfmt .",
-    "test": "bun run --filter '*' test",
+    "test": "bun run test:unit",
+    "test:unit": "bun run --filter '*' test",
+    "producer:test:classification": "bun run --cwd packages/producer test:classification",
+    "producer:test:unit": "bun run --cwd packages/producer test:unit",
+    "producer:test:unit:bun": "bun run --cwd packages/producer test:unit:bun",
+    "producer:test:unit:vitest": "bun run --cwd packages/producer test:unit:vitest",
+    "producer:test:integration": "bun run --cwd packages/producer test:integration",
+    "test:regression": "bun run --cwd packages/producer test:regression",
     "player:perf": "bun run --filter @hyperframes/player perf",
     "format:check": "oxfmt --check .",
     "knip": "knip",
diff --git a/packages/producer/package.json b/packages/producer/package.json
index 5d76636ea1..aa417d3912 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -43,8 +43,16 @@
     "check:runtime-conformance": "tsx src/runtime-conformance.ts",
     "benchmark": "tsx src/benchmark.ts",
     "bench:hdr": "tsx src/benchmark.ts --tags hdr",
-    "test": "tsx src/regression-harness.ts --exclude-tags transparency",
-    "test:update": "tsx src/regression-harness.ts --update --exclude-tags transparency",
+    "test": "bun run test:unit",
+    "test:classification": "node --test scripts/test-classification.test.mjs && node scripts/check-test-classification.mjs",
+    "test:unit": "bun run test:classification && node scripts/run-test-lane.mjs unit",
+    "test:unit:bun": "node scripts/run-test-lane.mjs unit bun",
+    "test:unit:vitest": "node scripts/run-test-lane.mjs unit vitest",
+    "test:integration": "bun run test:classification && node scripts/run-test-lane.mjs integration",
+    "test:integration:bun": "node scripts/run-test-lane.mjs integration bun",
+    "test:integration:vitest": "node scripts/run-test-lane.mjs integration vitest",
+    "test:regression": "tsx src/regression-harness.ts --exclude-tags transparency",
+    "test:regression:update": "tsx src/regression-harness.ts --update --exclude-tags transparency",
     "test:distributed": "tsx src/regression-harness.ts --exclude-tags transparency --mode=distributed-simulated",
     "test:transparency": "tsx src/transparency-test.ts",
     "docker:build:test": "docker build -f ../../Dockerfile.test -t hyperframes-producer:test ../..",
@@ -93,7 +101,8 @@
     "@webgpu/types": "^0.1.69",
     "esbuild": "^0.25.12",
     "tsx": "^4.21.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=22"
diff --git a/packages/producer/scripts/check-test-classification.mjs b/packages/producer/scripts/check-test-classification.mjs
new file mode 100644
index 0000000000..338c9b6333
--- /dev/null
+++ b/packages/producer/scripts/check-test-classification.mjs
@@ -0,0 +1,9 @@
+import { discoverProducerTests, summarizeTests } from "./test-classification.mjs";
+
+try {
+  const tests = discoverProducerTests();
+  console.log(JSON.stringify({ event: "producer_tests_classified", ...summarizeTests(tests) }));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
diff --git a/packages/producer/scripts/run-test-lane.mjs b/packages/producer/scripts/run-test-lane.mjs
new file mode 100644
index 0000000000..8c22ca09ec
--- /dev/null
+++ b/packages/producer/scripts/run-test-lane.mjs
@@ -0,0 +1,34 @@
+import { spawnSync } from "node:child_process";
+import { discoverProducerTests, PRODUCER_ROOT } from "./test-classification.mjs";
+
+const lane = process.argv[2];
+const requestedRunner = process.argv[3];
+if (lane !== "unit" && lane !== "integration") {
+  throw new Error("Usage: node scripts/run-test-lane.mjs <unit|integration> [bun|vitest]");
+}
+if (requestedRunner && requestedRunner !== "bun" && requestedRunner !== "vitest") {
+  throw new Error(`Unknown test runner: ${requestedRunner}`);
+}
+
+const tests = discoverProducerTests().filter(
+  (test) => test.lane === lane && (!requestedRunner || test.runner === requestedRunner),
+);
+
+function run(args) {
+  const result = spawnSync("bun", args, {
+    cwd: PRODUCER_ROOT,
+    env: { ...process.env, HYPERFRAMES_TEST_LANE: lane },
+    stdio: "inherit",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+const vitestFiles = tests.filter((test) => test.runner === "vitest").map((test) => test.file);
+if (vitestFiles.length > 0) run(["x", "vitest", "run", ...vitestFiles]);
+
+// Bun's mock.module registry is process-global. Run each file in a fresh
+// process so mocks from one source test cannot mutate another test's imports.
+for (const test of tests.filter((entry) => entry.runner === "bun")) {
+  run(["test", test.file]);
+}
diff --git a/packages/producer/scripts/test-classification.mjs b/packages/producer/scripts/test-classification.mjs
new file mode 100644
index 0000000000..aa6fc43365
--- /dev/null
+++ b/packages/producer/scripts/test-classification.mjs
@@ -0,0 +1,74 @@
+// fallow-ignore-file complexity
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PRODUCER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// These tests need host capabilities such as Chrome, ffmpeg, worker threads,
+// or local sockets. Keep the list explicit so a filename-only rename does not
+// make Git/fallow re-audit thousands of unchanged test lines as new code.
+const INTEGRATION_TEST_FILES = new Set([
+  "src/services/deterministicFonts-systemCapture.test.ts",
+  "src/services/distributed/assemble.test.ts",
+  "src/services/distributed/chunkBoundary.test.ts",
+  "src/services/distributed/crossWorkerIdempotency.test.ts",
+  "src/services/distributed/plan.test.ts",
+  "src/services/distributed/planSizeCap.test.ts",
+  "src/services/distributed/renderChunk.test.ts",
+  "src/services/fileServer.test.ts",
+  "src/services/healthWorker.test.ts",
+  "src/utils/audioRegression.test.ts",
+  "src/utils/streamDurationParity.test.ts",
+]);
+
+function collectTestFiles(directory, files = []) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = resolve(directory, entry.name);
+    if (entry.isDirectory()) collectTestFiles(entryPath, files);
+    else if (entry.isFile() && entry.name.endsWith(".test.ts")) files.push(entryPath);
+  }
+  return files;
+}
+
+export function classifyTestSource(filePath, source, integrationFiles = INTEGRATION_TEST_FILES) {
+  const importsBun = /\bfrom\s+["']bun:test["']/.test(source);
+  const importsVitest = /\bfrom\s+["']vitest["']/.test(source);
+  if (importsBun === importsVitest) {
+    const detail = importsBun ? "imports both bun:test and vitest" : "imports neither runner";
+    throw new Error(`${filePath}: ${detail}`);
+  }
+  return {
+    file: filePath,
+    runner: importsBun ? "bun" : "vitest",
+    lane: integrationFiles.has(filePath) ? "integration" : "unit",
+  };
+}
+
+export function discoverProducerTests(producerRoot = PRODUCER_ROOT) {
+  const srcDir = resolve(producerRoot, "src");
+  const files = collectTestFiles(srcDir).map((absolutePath) => ({
+    absolutePath,
+    filePath: relative(producerRoot, absolutePath).replaceAll("\\", "/"),
+  }));
+  const discoveredFiles = new Set(files.map((test) => test.filePath));
+  const staleEntries = [...INTEGRATION_TEST_FILES].filter((file) => !discoveredFiles.has(file));
+  if (staleEntries.length > 0) {
+    throw new Error(`Integration test manifest contains missing files: ${staleEntries.join(", ")}`);
+  }
+  return files
+    .map(({ absolutePath, filePath }) => {
+      return classifyTestSource(filePath, readFileSync(absolutePath, "utf8"));
+    })
+    .sort((left, right) => left.file.localeCompare(right.file));
+}
+
+export function summarizeTests(tests) {
+  const summary = {
+    total: tests.length,
+    unit: { bun: 0, vitest: 0 },
+    integration: { bun: 0, vitest: 0 },
+  };
+  for (const test of tests) summary[test.lane][test.runner] += 1;
+  return summary;
+}
diff --git a/packages/producer/scripts/test-classification.test.mjs b/packages/producer/scripts/test-classification.test.mjs
new file mode 100644
index 0000000000..75652df5ef
--- /dev/null
+++ b/packages/producer/scripts/test-classification.test.mjs
@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  classifyTestSource,
+  discoverProducerTests,
+  summarizeTests,
+} from "./test-classification.mjs";
+
+describe("producer test classification", () => {
+  it("classifies each supported runner into one lane", () => {
+    assert.deepEqual(classifyTestSource("src/a.test.ts", 'import { it } from "bun:test";'), {
+      file: "src/a.test.ts",
+      runner: "bun",
+      lane: "unit",
+    });
+    assert.deepEqual(
+      classifyTestSource(
+        "src/a.test.ts",
+        'import { it } from "vitest";',
+        new Set(["src/a.test.ts"]),
+      ),
+      { file: "src/a.test.ts", runner: "vitest", lane: "integration" },
+    );
+  });
+
+  it("rejects missing and ambiguous runner imports", () => {
+    assert.throws(() => classifyTestSource("src/a.test.ts", "export {};"), /neither runner/);
+    assert.throws(
+      () =>
+        classifyTestSource(
+          "src/a.test.ts",
+          'import { it } from "bun:test"; import { expect } from "vitest";',
+        ),
+      /both bun:test and vitest/,
+    );
+  });
+
+  it("classifies every current source test exactly once", () => {
+    const tests = discoverProducerTests();
+    assert.equal(new Set(tests.map((test) => test.file)).size, tests.length);
+    const summary = summarizeTests(tests);
+    assert.ok(summary.total > 0);
+    assert.equal(
+      summary.unit.bun + summary.unit.vitest + summary.integration.bun + summary.integration.vitest,
+      summary.total,
+    );
+  });
+});
diff --git a/packages/producer/src/regression-harness.ts b/packages/producer/src/regression-harness.ts
index 3f1101c619..d1c6dde2ef 100644
--- a/packages/producer/src/regression-harness.ts
+++ b/packages/producer/src/regression-harness.ts
@@ -1,3 +1,4 @@
+// fallow-ignore-file complexity
 import {
   existsSync,
   mkdirSync,
@@ -1510,12 +1511,14 @@ async function run(): Promise<void> {
   }
 }
 
-void run().catch((error) => {
-  console.error(
-    JSON.stringify({
-      event: "test_suite_fatal",
-      message: error instanceof Error ? error.message : String(error),
-    }),
-  );
-  process.exitCode = 1;
-});
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  void run().catch((error) => {
+    console.error(
+      JSON.stringify({
+        event: "test_suite_fatal",
+        message: error instanceof Error ? error.message : String(error),
+      }),
+    );
+    process.exitCode = 1;
+  });
+}
diff --git a/packages/producer/src/services/deterministicFonts-failClosed.test.ts b/packages/producer/src/services/deterministicFonts-failClosed.test.ts
index e64158da8a..d3860ed6f1 100644
--- a/packages/producer/src/services/deterministicFonts-failClosed.test.ts
+++ b/packages/producer/src/services/deterministicFonts-failClosed.test.ts
@@ -59,6 +59,7 @@ describe("injectDeterministicFontFaces — failClosedFontFetch: false (default)"
   it("swallows a network failure and returns the original HTML (no throw)", async () => {
     const result = await injectDeterministicFontFaces(HTML_REQUESTING_UNRESOLVED_FONT, {
       failClosedFontFetch: false,
+      allowSystemFontCapture: false,
       fetchImpl: makeFailingFetch(),
     });
     // No @font-face was injected because the fetch failed — but the call
@@ -69,6 +70,7 @@ describe("injectDeterministicFontFaces — failClosedFontFetch: false (default)"
   it("swallows a 404 response and returns the original HTML (no throw)", async () => {
     const result = await injectDeterministicFontFaces(HTML_REQUESTING_UNRESOLVED_FONT, {
       failClosedFontFetch: false,
+      allowSystemFontCapture: false,
       fetchImpl: makeHttp404Fetch(),
     });
     expect(result.includes("data-hyperframes-deterministic-fonts")).toBe(false);
@@ -77,6 +79,7 @@ describe("injectDeterministicFontFaces — failClosedFontFetch: false (default)"
   it("swallows a 5xx response and returns the original HTML (no throw)", async () => {
     const result = await injectDeterministicFontFaces(HTML_REQUESTING_UNRESOLVED_FONT, {
       failClosedFontFetch: false,
+      allowSystemFontCapture: false,
       fetchImpl: makeHttp503Fetch(),
     });
     expect(result.includes("data-hyperframes-deterministic-fonts")).toBe(false);
diff --git a/packages/producer/src/services/distributed/crossWorkerIdempotency.test.ts b/packages/producer/src/services/distributed/crossWorkerIdempotency.test.ts
index 4d3e7ba84a..219e76c563 100644
--- a/packages/producer/src/services/distributed/crossWorkerIdempotency.test.ts
+++ b/packages/producer/src/services/distributed/crossWorkerIdempotency.test.ts
@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication complexity
 /**
  * Cross-worker idempotency: rendering the same `(planDir, chunkIndex)` on two
  * different workers MUST produce byte-identical output. This is what makes a
@@ -41,7 +42,7 @@ const FIXTURE_HTML = `<!doctype html>
 <html>
 <head><meta charset="utf-8"><title>cross-worker idempotency fixture</title></head>
 <body style="margin:0;background:#000;color:#fff;font:32px sans-serif">
-  <div data-composition-id="root" data-width="160" data-height="120" data-duration="0.16667">
+  <div data-composition-id="root" data-no-timeline data-width="160" data-height="120" data-duration="0.16667">
     <p style="padding:1rem">chunk fixture</p>
   </div>
 </body>
diff --git a/packages/producer/src/services/distributed/renderChunk.test.ts b/packages/producer/src/services/distributed/renderChunk.test.ts
index e88230a705..d325aef137 100644
--- a/packages/producer/src/services/distributed/renderChunk.test.ts
+++ b/packages/producer/src/services/distributed/renderChunk.test.ts
@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication complexity
 /**
  * Unit tests for `services/distributed/renderChunk.ts`.
  *
@@ -41,7 +42,7 @@ const FIXTURE_HTML = `<!doctype html>
 <html>
 <head><meta charset="utf-8"><title>renderChunk fixture</title></head>
 <body style="margin:0;background:#000;color:#fff;font:32px sans-serif">
-  <div data-composition-id="root" data-width="160" data-height="120" data-duration="0.16667">
+  <div data-composition-id="root" data-no-timeline data-width="160" data-height="120" data-duration="0.16667">
     <p style="padding:1rem">chunk fixture</p>
   </div>
 </body>
@@ -134,7 +135,7 @@ beforeAll(async () => {
   planDir = join(runRoot, "plan");
   mkdirSync(planDir, { recursive: true });
   await plan(projectDir, { fps: 30, width: 160, height: 120, format: "png-sequence" }, planDir);
-});
+}, 30_000);
 
 afterAll(() => {
   rmSync(runRoot, { recursive: true, force: true });
@@ -331,7 +332,7 @@ describe("renderChunk() — variables threading", () => {
 <html data-composition-variables='{"color":"string"}'>
 <head><meta charset="utf-8"><title>renderChunk variables fixture</title></head>
 <body style="margin:0">
-  <div data-composition-id="root" data-width="160" data-height="120" data-duration="0.16667">
+  <div data-composition-id="root" data-no-timeline data-width="160" data-height="120" data-duration="0.16667">
     <div id="paint" style="width:160px;height:120px;background:#000"></div>
   </div>
   <script>
diff --git a/packages/producer/src/services/render/stages/captureStreamingStage.test.ts b/packages/producer/src/services/render/stages/captureStreamingStage.test.ts
index e41bc0972c..9ecd933a99 100644
--- a/packages/producer/src/services/render/stages/captureStreamingStage.test.ts
+++ b/packages/producer/src/services/render/stages/captureStreamingStage.test.ts
@@ -19,11 +19,14 @@ let failInitializeSession = false;
 let initializeSessionErrorMessage = "initialize failed";
 const browserConsoleBuffer = ["[FrameCapture:ERROR] page.goto failed"];
 const closeCaptureSession = mock(async () => {});
+class DrawElementVerificationError extends Error {}
 
 mock.module("@hyperframes/engine", () => ({
   calculateOptimalWorkers: () => 1,
   convertTransfer: () => {},
   captureFrame: async () => {},
+  captureFrameToBufferPipelined: async () => ({ encodeResult: { buffer: Buffer.from("frame") } }),
+  captureFramesBatchPipelined: async () => [],
   captureFrameToBuffer: async () => {
     if (failCaptureFrameToBuffer) {
       throw new Error("captureFrameToBuffer failed");
@@ -31,13 +34,23 @@ mock.module("@hyperframes/engine", () => ({
     return { buffer: Buffer.from("frame"), captureTimeMs: 1 };
   },
   closeCaptureSession,
-  createCaptureSession: async () => ({ isInitialized: false, browserConsoleBuffer }),
+  completeDeferredDrawElementInit: async () => {},
+  createCaptureSession: async () => ({
+    isInitialized: false,
+    browserConsoleBuffer,
+    options: { captureBeyondViewport: false },
+    workerEncodeEnabled: false,
+  }),
   createFrameReorderBuffer: () => ({
     waitForFrame: async () => {},
     advanceTo: () => {},
   }),
   distributeFrames: () => [],
+  distributeFramesInterleaved: () => [],
+  DrawElementVerificationError,
   executeParallelCapture: async () => {},
+  getCapturePerfSummary: () => ({}),
+  getFfmpegBinary: () => "ffmpeg",
   initializeSession: async (session: { isInitialized: boolean }) => {
     if (failInitializeSession) {
       throw new Error(initializeSessionErrorMessage);
@@ -52,12 +65,16 @@ mock.module("@hyperframes/engine", () => ({
   }),
   initTransparentBackground: async () => {},
   prepareCaptureSessionForReuse: () => {},
+  recaptureDrawElementFrameForVerify: async () => Buffer.from("frame"),
   spawnStreamingEncoder,
+  writeCapturedFrame: async () => {},
 }));
 
 mock.module("@hyperframes/core", () => ({
   CANVAS_DIMENSIONS: {},
+  checkOutputResolutionCompatibility: () => ({ ok: true }),
   fpsToNumber: () => 30,
+  redactTelemetryString: (value: string) => value,
 }));
 
 mock.module("../../renderOrchestrator.js", () => ({
@@ -67,6 +84,11 @@ mock.module("../../renderOrchestrator.js", () => ({
   resolveCompositeTransfer: () => "srgb",
 }));
 
+mock.module("../../hdrCompositor.js", () => ({
+  closeHdrVideoFrameSource: () => {},
+  resolveCompositeTransfer: () => "srgb",
+}));
+
 mock.module("./captureHdrResources.js", () => ({
   decodeHdrImageBuffers: () => new Map(),
   extractHdrVideoFrames: async () => new Map(),
@@ -79,6 +101,7 @@ mock.module("./captureHdrResources.js", () => ({
 }));
 
 mock.module("./captureHdrFrameShared.js", () => ({
+  ensureFrameWritten: () => {},
   partitionTransitionFrames: () => new Set(),
   shouldUseHybridLayeredPath: () => false,
 }));
diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
index 80a7346edb..20ccf03b86 100644
--- a/packages/producer/src/services/renderOrchestrator.test.ts
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -1165,10 +1165,15 @@ describe("resolveRenderWorkerCount", () => {
       debug: vi.fn(),
     };
 
+    const stableCfg = {
+      ...cfg,
+      concurrency: 2 as const,
+      largeRenderThreshold: 1_000,
+    };
     const workers = resolveRenderWorkerCount(
       180,
       undefined,
-      { ...cfg, forceScreenshot: true },
+      { ...stableCfg, forceScreenshot: true },
       {
         hasShaderTransitions: false,
         renderModeHints: { recommendScreenshot: false, reasons: [] },
@@ -1177,7 +1182,7 @@ describe("resolveRenderWorkerCount", () => {
       { multiplier: 1, reasons: [], p95Ms: 180 },
     );
 
-    expect(workers).toBe(6);
+    expect(workers).toBe(2);
     expect(log.warn).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/producer/tests/hdr-hlg-regression/README.md b/packages/producer/tests/hdr-hlg-regression/README.md
index 1c43340628..b8cff29d94 100644
--- a/packages/producer/tests/hdr-hlg-regression/README.md
+++ b/packages/producer/tests/hdr-hlg-regression/README.md
@@ -36,9 +36,9 @@ remuxed (no re-encode) so the HLG color tags survive verbatim.
 
 ```bash
 cd packages/producer
-bun run test hdr-hlg-regression
+bun run test:regression hdr-hlg-regression
 
-bun run test:update hdr-hlg-regression
+bun run test:regression:update hdr-hlg-regression
 ```
 
 In CI it runs in the `hdr` shard alongside `hdr-regression`
diff --git a/packages/producer/tests/hdr-regression/README.md b/packages/producer/tests/hdr-regression/README.md
index 0ca0739038..a9d343fd9d 100644
--- a/packages/producer/tests/hdr-regression/README.md
+++ b/packages/producer/tests/hdr-regression/README.md
@@ -35,8 +35,8 @@ python3 packages/producer/tests/hdr-regression/scripts/generate-hdr-photo-pq.py
 
 ```bash
 cd packages/producer
-bun run test hdr-regression
-bun run test:update hdr-regression
+bun run test:regression hdr-regression
+bun run test:regression:update hdr-regression
 ```
 
 In CI it runs in the `hdr` shard alongside `hdr-hlg-regression`

From 39655bba1d39e9f4c52c4857fbea912589029ed9 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 03:33:32 -0400
Subject: [PATCH 03/24] fix(core): capture authored inline opacity at parse
 time and follow source geometry

The color-grading engine hides its source element with inline
'opacity: 0 !important', so any code that later reads or re-captures the
element's opacity sees the hide instead of the authored value. Stamp the
authored inline opacity on every [data-color-grading] element at document
parse time (MutationObserver installed at runtime-bundle eval, before any
composition script runs) and prefer the stamp when hiding/restoring.

Also re-sync the grading canvas when the source's inline geometry mutates
(rAF-throttled style observer): a studio drag moves the source via its
transform, which fires no media event, so the visible canvas froze in
place until the next seek.
---
 packages/core/src/colorGrading.ts             | 12 +++
 .../core/src/runtime/colorGrading.test.ts     | 91 ++++++++++++++++++-
 packages/core/src/runtime/colorGrading.ts     | 89 +++++++++++++++++-
 packages/core/src/runtime/entry.ts            |  6 ++
 packages/core/src/runtime/picker.ts           |  2 +-
 5 files changed, 195 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/colorGrading.ts b/packages/core/src/colorGrading.ts
index d71ce17764..d5411e20a3 100644
--- a/packages/core/src/colorGrading.ts
+++ b/packages/core/src/colorGrading.ts
@@ -1,5 +1,17 @@
 export const HF_COLOR_GRADING_ATTR = "data-color-grading";
 
+// Runtime <-> studio contract attributes. The runtime grading engine writes
+// them; studio editing/soft-reload code reads them. Single owner — never
+// re-declare these literals elsewhere.
+/** Set on a graded source while its pixels render on the grading canvas. */
+export const COLOR_GRADING_SOURCE_HIDDEN_ATTR = "data-hf-color-grading-source-hidden";
+/**
+ * The element's AUTHORED inline opacity, stamped at document parse time before
+ * any animation engine mutates it ("" = authored none; attribute absent =
+ * never captured). See installAuthoredOpacityCapture in the runtime.
+ */
+export const COLOR_GRADING_AUTHORED_OPACITY_ATTR = "data-hf-authored-opacity";
+
 export const HF_COLOR_GRADING_CANVAS_ID_PREFIX = "__hf_color_grading_";
 
 export const HF_COLOR_GRADING_COLOR_SPACE = "rec709";
diff --git a/packages/core/src/runtime/colorGrading.test.ts b/packages/core/src/runtime/colorGrading.test.ts
index e3a3ce49df..cf3e0e048c 100644
--- a/packages/core/src/runtime/colorGrading.test.ts
+++ b/packages/core/src/runtime/colorGrading.test.ts
@@ -1,7 +1,11 @@
 // fallow-ignore-file code-duplication
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { HF_COLOR_GRADING_ATTR, serializeHfColorGrading } from "../colorGrading";
-import { createColorGradingRuntime, type RuntimeColorGradingApi } from "./colorGrading";
+import {
+  createColorGradingRuntime,
+  installAuthoredOpacityCapture,
+  type RuntimeColorGradingApi,
+} from "./colorGrading";
 
 let lastUniform1f: ReturnType<typeof vi.fn> | null = null;
 let lastUniform3f: ReturnType<typeof vi.fn> | null = null;
@@ -192,6 +196,60 @@ describe("createColorGradingRuntime", () => {
     runtime?.redraw();
   }
 
+  it("restores the authored inline opacity captured before animation transients", () => {
+    const video = makeDrawableVideo();
+    // Parse-time capture stamped the authored value; by hide time GSAP has
+    // already left a from()-tween transient (0) in the inline style.
+    video.setAttribute("data-hf-authored-opacity", "0.75");
+    video.style.opacity = "0";
+    startRuntimeWithVideo(video);
+
+    expect(video.style.getPropertyPriority("opacity")).toBe("important");
+
+    runtime?.destroy();
+    runtime = null;
+
+    // Restore must use the authored 0.75, not the GSAP transient 0.
+    expect(video.style.getPropertyValue("opacity")).toBe("0.75");
+    expect(video.style.getPropertyPriority("opacity")).toBe("");
+  });
+
+  it("restores no inline opacity when the authored capture recorded none", () => {
+    const video = makeDrawableVideo();
+    video.setAttribute("data-hf-authored-opacity", "");
+    video.style.opacity = "0";
+    startRuntimeWithVideo(video);
+
+    runtime?.destroy();
+    runtime = null;
+
+    expect(video.style.getPropertyValue("opacity")).toBe("");
+  });
+
+  it("re-syncs the graded canvas when the source's inline transform changes", async () => {
+    const { video } = startRuntimeWithVideo();
+    const drawsBefore = texImage2DCalls.length;
+
+    // Simulate a studio drag draft: only the inline transform moves.
+    video.style.transform = "translate(120px, 60px)";
+    await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+
+    expect(texImage2DCalls.length).toBeGreaterThan(drawsBefore);
+  });
+
+  it("does not redraw-loop on its own hide writes (opacity/visibility only)", async () => {
+    const { video } = startRuntimeWithVideo();
+    await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+    const drawsBefore = texImage2DCalls.length;
+
+    // drawEntry's own source-hide writes touch opacity — geometry unchanged.
+    video.style.opacity = "0.5";
+    await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+    await new Promise((resolve) => requestAnimationFrame(() => resolve(null)));
+
+    expect(texImage2DCalls.length).toBe(drawsBefore);
+  });
+
   it("re-hides source media after timeline visibility sync", () => {
     const { video, canvas } = startRuntimeWithVideo();
 
@@ -555,3 +613,34 @@ describe("createColorGradingRuntime", () => {
     expect(video.style.getPropertyValue("opacity")).toBe("0");
   });
 });
+
+describe("installAuthoredOpacityCapture", () => {
+  it("stamps graded elements at insertion and never overwrites the stamp", async () => {
+    installAuthoredOpacityCapture();
+    const el = document.createElement("img");
+    el.setAttribute(HF_COLOR_GRADING_ATTR, serializeHfColorGrading({ adjust: { exposure: 0.5 } }));
+    el.style.opacity = "0.98";
+    document.body.appendChild(el);
+    await Promise.resolve();
+    expect(el.getAttribute("data-hf-authored-opacity")).toBe("0.98");
+
+    // A re-insert after an animation engine mutated the element keeps the
+    // original capture (has-attribute guard).
+    el.style.opacity = "0";
+    el.remove();
+    document.body.appendChild(el);
+    await Promise.resolve();
+    expect(el.getAttribute("data-hf-authored-opacity")).toBe("0.98");
+    el.remove();
+  });
+
+  it("stamps an empty value for graded elements without an authored inline opacity", async () => {
+    installAuthoredOpacityCapture();
+    const el = document.createElement("img");
+    el.setAttribute(HF_COLOR_GRADING_ATTR, serializeHfColorGrading({ adjust: { exposure: 0.5 } }));
+    document.body.appendChild(el);
+    await Promise.resolve();
+    expect(el.getAttribute("data-hf-authored-opacity")).toBe("");
+    el.remove();
+  });
+});
diff --git a/packages/core/src/runtime/colorGrading.ts b/packages/core/src/runtime/colorGrading.ts
index 5b32c6c65f..75e85ebd89 100644
--- a/packages/core/src/runtime/colorGrading.ts
+++ b/packages/core/src/runtime/colorGrading.ts
@@ -6,6 +6,8 @@ import {
   normalizeHfColorGradingWithVariables,
   type HfColorGradingTarget,
   type NormalizedHfColorGrading,
+  COLOR_GRADING_SOURCE_HIDDEN_ATTR,
+  COLOR_GRADING_AUTHORED_OPACITY_ATTR,
 } from "../colorGrading";
 import {
   DEFAULT_MAX_CUBE_LUT_SIZE,
@@ -196,8 +198,51 @@ type LutCacheEntry =
 
 const LUT_CACHE = new Map<string, LutCacheEntry>();
 const COLOR_GRADING_CANVAS_ATTR = "data-hf-color-grading-canvas";
-const COLOR_GRADING_SOURCE_HIDDEN_ATTR = "data-hf-color-grading-source-hidden";
 const COLOR_GRADING_CANVAS_CLASS = "__hf_color_grading_canvas__";
+
+/**
+ * Capture each color-graded element's AUTHORED inline opacity before any
+ * animation engine can mutate it.
+ *
+ * The grading engine hides its source elements with `opacity: 0 !important`
+ * and mirrors their pixels onto a canvas — so at runtime, a graded element's
+ * inline/computed opacity no longer represents authored state. Everything that
+ * later re-reads element state (GSAP from()-tween re-initialization after an
+ * invalidate or a studio soft reload, restoring the source when grading is
+ * removed, lint/selection tooling) needs the authored value, and by then it is
+ * unrecoverable from the DOM. Stamp it onto the element as
+ * `data-hf-authored-opacity` (empty string = no authored inline opacity).
+ *
+ * Must be installed at runtime-bundle evaluation, while the document is still
+ * parsing: the runtime `<script>` sits in `<head>`, and the HTML parser
+ * performs a microtask checkpoint before executing each parser-inserted
+ * script, so the observer stamps every composition element before the
+ * composition's own inline animation script runs. The observer stays alive so
+ * late insertions (inlined sub-compositions) are stamped at insert time, and
+ * the has-attribute guard makes re-inserted (already-stamped) elements a no-op.
+ */
+export function installAuthoredOpacityCapture(): void {
+  if (typeof MutationObserver === "undefined" || typeof document === "undefined") return;
+  const root = document.documentElement;
+  if (!root) return;
+  const stamp = (el: Element): void => {
+    if (!(el instanceof HTMLElement)) return;
+    if (el.hasAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR)) return;
+    el.setAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR, el.style.opacity);
+  };
+  const scan = (node: Node): void => {
+    if (!(node instanceof Element)) return;
+    if (node.hasAttribute(HF_COLOR_GRADING_ATTR)) stamp(node);
+    for (const el of node.querySelectorAll(`[${HF_COLOR_GRADING_ATTR}]`)) stamp(el);
+  };
+  scan(root);
+  new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) scan(node);
+    }
+  }).observe(root, { childList: true, subtree: true });
+}
+
 // Map insertion order gives us simple FIFO eviction for authoring sessions that cycle LUTs.
 const MAX_LUT_CACHE_ENTRIES = 16;
 const DEFAULT_COMPARE: RuntimeColorGradingCompareState = {
@@ -1234,8 +1279,20 @@ function applyUniforms(
 
 function hideSourceElement(entry: ColorGradingEntry): void {
   if (!entry.sourceHidden) {
-    entry.sourceInlineOpacity = entry.element.style.getPropertyValue("opacity") || null;
-    entry.sourceInlineOpacityPriority = entry.element.style.getPropertyPriority("opacity");
+    // Prefer the parse-time authored capture: by the time the first hide runs,
+    // the inline opacity is usually an animation-engine transient (a from()
+    // tween's 0 at playhead 0), and restoring THAT when grading is removed
+    // would leave the element invisible. Fall back to the live inline value
+    // for documents loaded without the capture installed.
+    // `null` = never captured; "" = captured, authored none (store as null).
+    const authored = entry.element.getAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR);
+    if (authored !== null) {
+      entry.sourceInlineOpacity = authored === "" ? null : authored;
+      entry.sourceInlineOpacityPriority = "";
+    } else {
+      entry.sourceInlineOpacity = entry.element.style.getPropertyValue("opacity") || null;
+      entry.sourceInlineOpacityPriority = entry.element.style.getPropertyPriority("opacity");
+    }
   }
   entry.element.setAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR, "true");
   entry.element.style.setProperty("opacity", "0", "important");
@@ -1423,6 +1480,32 @@ function installEntryListeners(entry: ColorGradingEntry): void {
     entry.resizeObserver = new ResizeObserver(redraw);
     entry.resizeObserver.observe(entry.element);
   }
+  // A studio drag/nudge moves the source via its inline transform — no media
+  // event or ResizeObserver fires for that, so the graded canvas (the visible
+  // pixels) froze in place until the next seek while the invisible source
+  // followed the pointer. Track geometry-relevant inline style and re-sync the
+  // canvas, rAF-throttled. The signature guard keeps the opacity/visibility
+  // writes drawEntry itself makes (the source hide) from re-triggering a loop.
+  if (typeof MutationObserver !== "undefined") {
+    const geometrySignature = () => {
+      const s = entry.element.style;
+      return `${s.transform}|${s.translate}|${s.rotate}|${s.scale}|${s.left}|${s.top}|${s.width}|${s.height}`;
+    };
+    let lastGeometry = geometrySignature();
+    let framePending = false;
+    const styleObserver = new MutationObserver(() => {
+      if (framePending) return;
+      if (geometrySignature() === lastGeometry) return;
+      framePending = true;
+      requestAnimationFrame(() => {
+        framePending = false;
+        lastGeometry = geometrySignature();
+        drawEntry(entry);
+      });
+    });
+    styleObserver.observe(entry.element, { attributes: true, attributeFilter: ["style"] });
+    entry.cleanup.push(() => styleObserver.disconnect());
+  }
 }
 
 function destroyEntry(entry: ColorGradingEntry): void {
diff --git a/packages/core/src/runtime/entry.ts b/packages/core/src/runtime/entry.ts
index 3f04e4920a..5851da238b 100644
--- a/packages/core/src/runtime/entry.ts
+++ b/packages/core/src/runtime/entry.ts
@@ -1,4 +1,5 @@
 import { initSandboxRuntimeModular } from "./init";
+import { installAuthoredOpacityCapture } from "./colorGrading";
 import { fitTextFontSize } from "../text/fitTextFontSize";
 import { getVariables } from "./getVariables";
 
@@ -14,6 +15,11 @@ type HyperframeWindow = Window & {
 // Ensure timeline registry exists at script evaluation time.
 (window as HyperframeWindow).__timelines = (window as HyperframeWindow).__timelines || {};
 
+// Stamp color-graded elements with their authored inline opacity BEFORE the
+// composition's animation scripts (and the grading hide) mutate it — must run
+// at script evaluation time, while the document is still parsing.
+installAuthoredOpacityCapture();
+
 // Expose runtime helpers immediately so composition scripts can use them
 // before DOMContentLoaded (font sizing runs during script evaluation, and
 // getVariables is read by composition setup before the timeline is built).
diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts
index 0a34763cb0..e9ced66c27 100644
--- a/packages/core/src/runtime/picker.ts
+++ b/packages/core/src/runtime/picker.ts
@@ -17,7 +17,7 @@ const PICKER_BLOCK_SELECTOR = [
   "[data-hyperframes-picker-block]",
   "[data-hyper-shader-loading]",
 ].join(",");
-const COLOR_GRADING_SOURCE_HIDDEN_ATTR = "data-hf-color-grading-source-hidden";
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "../colorGrading";
 
 export type PickerModule = {
   enablePickMode: () => void;

From b9c899f873de55a215068011c64b4775c9343657 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 03:34:21 -0400
Subject: [PATCH 04/24] fix(studio): stop tween re-inits from baking runtime
 opacity transients
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Editing commits made elements vanish or dim permanently: invalidating the
whole timeline (or re-running the composition script on soft reload) made
GSAP re-capture tween bounds while runtime transients were live — the
grading hide's opacity 0, or a mid-flight tween value — so from()/to()
bounds got poisoned and the element rendered invisible from then on.

- patch only the edited tween in place, never timeline.invalidate()
- soft reload restores every animated element's authored inline opacity
  (after-write HTML first, parse-time stamp as fallback) before the script
  re-runs and re-captures
- a paired x/y commit whose second half is a no-op (changed=false) still
  applies its instant patch, so panel edits reflect without deselecting
---
 .../studio/src/hooks/gsapRuntimePatch.test.ts |  63 +++++++
 packages/studio/src/hooks/gsapRuntimePatch.ts |  36 +++-
 .../src/hooks/useGsapScriptCommits.test.tsx   | 165 +++++++++++-------
 .../studio/src/hooks/useGsapScriptCommits.ts  |  33 +++-
 packages/studio/src/utils/authoredOpacity.ts  |  28 +++
 packages/studio/src/utils/elementGsap.ts      |  31 ++++
 packages/studio/src/utils/gsapSoftReload.ts   |  60 ++++++-
 7 files changed, 342 insertions(+), 74 deletions(-)
 create mode 100644 packages/studio/src/utils/authoredOpacity.ts
 create mode 100644 packages/studio/src/utils/elementGsap.ts

diff --git a/packages/studio/src/hooks/gsapRuntimePatch.test.ts b/packages/studio/src/hooks/gsapRuntimePatch.test.ts
index bf999f9c8e..1a17f7e063 100644
--- a/packages/studio/src/hooks/gsapRuntimePatch.test.ts
+++ b/packages/studio/src/hooks/gsapRuntimePatch.test.ts
@@ -133,6 +133,69 @@ describe("patchRuntimeTweenInPlace — set tweens", () => {
   });
 });
 
+describe("patchRuntimeTweenInPlace — authored-opacity capture guard", () => {
+  function makeStampedEl(id: string, stamped: string | null, inlineOpacity: string) {
+    const style = new Map<string, string>([["opacity", inlineOpacity]]);
+    return {
+      el: {
+        id,
+        style: {
+          setProperty: (k: string, v: string) => void style.set(k, v),
+          removeProperty: (k: string) => void style.delete(k),
+        },
+        getAttribute: (name: string) => (name === "data-hf-authored-opacity" ? stamped : null),
+      },
+      style,
+    };
+  }
+
+  it("restores the stamped authored opacity before an opacity-touching patch", () => {
+    // Runtime transient (grading hide / mid-flight tween) baked into inline style.
+    const { el, style } = makeStampedEl("box", "0.75", "0");
+    const setTween = makeTween(
+      { vars: { opacity: 0.2, duration: 0 }, targetIds: ["box"], duration: 0 },
+      el,
+    );
+    const { iframe } = fakeIframe(el, [setTween]);
+
+    const ok = patchRuntimeTweenInPlace(iframe, "#box", {
+      kind: "set",
+      props: { opacity: 0.5 },
+    });
+
+    expect(ok).toBe(true);
+    // The re-init must capture the authored 0.75, not the transient 0.
+    expect(style.get("opacity")).toBe("0.75");
+    expect(setTween.vars.opacity).toBe(0.5);
+  });
+
+  it("removes inline opacity when the stamp recorded no authored value", () => {
+    const { el, style } = makeStampedEl("box", "", "0");
+    const setTween = makeTween(
+      { vars: { opacity: 0.2, duration: 0 }, targetIds: ["box"], duration: 0 },
+      el,
+    );
+    const { iframe } = fakeIframe(el, [setTween]);
+
+    patchRuntimeTweenInPlace(iframe, "#box", { kind: "set", props: { opacity: 0.5 } });
+
+    expect(style.has("opacity")).toBe(false);
+  });
+
+  it("leaves inline opacity alone for a position-only patch", () => {
+    const { el, style } = makeStampedEl("box", "0.75", "0");
+    const setTween = makeTween(
+      { vars: { x: 0, y: 0, duration: 0 }, targetIds: ["box"], duration: 0 },
+      el,
+    );
+    const { iframe } = fakeIframe(el, [setTween]);
+
+    patchRuntimeTweenInPlace(iframe, "#box", { kind: "set", props: { x: 10, y: 20 } });
+
+    expect(style.get("opacity")).toBe("0");
+  });
+});
+
 describe("patchRuntimeTweenInPlace — channel-aware set resolution", () => {
   it("patches the {x,y} set, not a co-located rotation-only set", () => {
     const el = { id: "dual" };
diff --git a/packages/studio/src/hooks/gsapRuntimePatch.ts b/packages/studio/src/hooks/gsapRuntimePatch.ts
index a95f248f9b..de2c6480e4 100644
--- a/packages/studio/src/hooks/gsapRuntimePatch.ts
+++ b/packages/studio/src/hooks/gsapRuntimePatch.ts
@@ -13,6 +13,7 @@
  * "Which tween" is resolved by the same all-timelines scan `readRuntimeKeyframes`
  * uses (`resolveRuntimeTween`), so read and write agree on the target.
  */
+import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "../utils/authoredOpacity";
 import {
   resolveRuntimeTween,
   type RuntimeTween,
@@ -235,6 +236,34 @@ function seekToCurrent(iframe: HTMLIFrameElement, timeline: RuntimeTimeline): vo
   player?.seek?.(Number.isFinite(currentTime) ? currentTime : 0);
 }
 
+/** Does this change touch the opacity channel (whose re-init reads inline style)? */
+function changeTouchesOpacity(change: RuntimeTweenChange): boolean {
+  if (change.kind === "set" || change.kind === "global-set")
+    return change.props.opacity !== undefined;
+  if (change.kind === "keyframes") return change.keyframes.some((step) => "opacity" in step);
+  return "opacity" in change.props;
+}
+
+/**
+ * A tween re-initialization (invalidate, or kill+recreate for keyframe-rebuild)
+ * captures opacity from the element's CURRENT inline style — for a color-graded
+ * source (hidden with `opacity: 0 !important`) or a mid-flight tween that's a
+ * runtime transient, not the authored value, and the capture makes it permanent.
+ * Restore the runtime's parse-time authored capture (data-hf-authored-opacity)
+ * first; the re-seek after the patch re-renders the animated value anyway.
+ * Duck-typed (no instanceof): the targets live in the preview iframe's realm.
+ */
+function restoreAuthoredOpacityForCapture(tween: RuntimeTween): void {
+  const targets = typeof tween.targets === "function" ? tween.targets() : [];
+  for (const target of targets ?? []) {
+    const el = target as HTMLElement | null;
+    if (!el?.style || typeof el.getAttribute !== "function") continue;
+    const authored = readStampedAuthoredOpacity(el);
+    if (authored === null) continue;
+    applyAuthoredInlineOpacity(el.style, authored);
+  }
+}
+
 /** Apply `change` to the resolved tween. `true` if applied, `false` to soft-reload.
  *  `global-set` is handled before this (no tween) and never reaches here. */
 function applyChange(tween: RuntimeTween, change: RuntimeTweenChange): boolean {
@@ -270,13 +299,18 @@ export function patchRuntimeTweenInPlace(
     if (!resolved) return false;
     const { tween, timeline } = resolved;
 
+    if (changeTouchesOpacity(change)) restoreAuthoredOpacityForCapture(tween);
     if (!applyChange(tween, change)) return false;
 
     // A rebuild already recreated the tween; set/keyframes mutate vars in place, so
     // invalidate to make GSAP re-read them on the next render. Either way, re-seek.
+    // Invalidate ONLY the edited tween — never the whole timeline. A timeline-wide
+    // invalidate re-initializes every from() tween against the CURRENT inline
+    // styles, and the color-grading engine hides its source elements with
+    // `opacity: 0 !important` — so every graded element's from(opacity) re-captures
+    // 0 as its end value and animates 0→0 forever (all graded elements vanish).
     if (change.kind !== "keyframe-rebuild") {
       tween.invalidate?.();
-      timeline.invalidate?.();
     }
     seekToCurrent(iframe, timeline);
     return true;
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
index ee192997f6..8416a4a08b 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
+++ b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
@@ -38,6 +38,19 @@ function result(over: Partial<MutationResult> = {}): MutationResult {
   return { ok: true, scriptText: "tl.set('#a',{})", ...over };
 }
 
+/** The canonical drag commit options every path-decision test drives with. */
+function dragOptions() {
+  return {
+    label: "drag",
+    softReload: true,
+    instantPatch: { selector: "#a", change: { kind: "set" as const, props: { x: 10 } } },
+  };
+}
+
+function syncDragPreview(res: MutationResult, reloadPreview: () => void) {
+  applyPreviewSync(FAKE_IFRAME, res, dragOptions(), reloadPreview);
+}
+
 describe("applyPreviewSync", () => {
   beforeEach(() => {
     patchRuntimeTweenInPlace.mockReset();
@@ -49,16 +62,7 @@ describe("applyPreviewSync", () => {
     patchRuntimeTweenInPlace.mockReturnValue(true);
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result(),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result(), reloadPreview);
 
     expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
       kind: "set",
@@ -73,20 +77,17 @@ describe("applyPreviewSync", () => {
     applySoftReload.mockReturnValue("applied");
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result({ scriptText: "SCRIPT" }),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
 
     // reloadPreview is wired as onAsyncFailure (3rd arg) so a MotionPath-plugin
     // CDN load failure escalates to a full reload — but it is NOT called eagerly.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      reloadPreview,
+      0,
+      undefined,
+    );
     expect(reloadPreview).not.toHaveBeenCalled();
     // A successful instant patch is the fast path; here it missed → fallback event.
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -100,20 +101,17 @@ describe("applyPreviewSync", () => {
     applySoftReload.mockReturnValue("verify-failed");
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
-      FAKE_IFRAME,
-      result({ scriptText: "SCRIPT" }),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
-      reloadPreview,
-    );
+    syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
 
     // U4: "verify-failed" is the TRANSIENT empty-timeline window — the live state
     // is correct, so we must NOT escalate to a full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      reloadPreview,
+      0,
+      undefined,
+    );
     expect(reloadPreview).not.toHaveBeenCalled();
     // Telemetry records the suppressed transient (escalated: false).
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -131,19 +129,16 @@ describe("applyPreviewSync", () => {
     applySoftReload.mockReturnValue("cannot-soft-reload");
     const reloadPreview = vi.fn();
 
-    applyPreviewSync(
+    syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
+
+    // Structural failure: the preview is genuinely stale/broken → full reload.
+    expect(applySoftReload).toHaveBeenCalledWith(
       FAKE_IFRAME,
-      result({ scriptText: "SCRIPT" }),
-      {
-        label: "drag",
-        softReload: true,
-        instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-      },
+      "SCRIPT",
       reloadPreview,
+      0,
+      undefined,
     );
-
-    // Structural failure: the preview is genuinely stale/broken → full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -167,7 +162,13 @@ describe("applyPreviewSync", () => {
     );
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      reloadPreview,
+      0,
+      undefined,
+    );
     expect(reloadPreview).not.toHaveBeenCalled();
     // "applied" emits no telemetry (only the failure paths do).
     expect(trackStudioEvent).not.toHaveBeenCalled();
@@ -185,7 +186,13 @@ describe("applyPreviewSync", () => {
     );
 
     // onAsyncFailure is wired, but the transient result does not trigger it.
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      reloadPreview,
+      0,
+      undefined,
+    );
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -204,7 +211,13 @@ describe("applyPreviewSync", () => {
       reloadPreview,
     );
 
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      reloadPreview,
+      0,
+      undefined,
+    );
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -291,6 +304,32 @@ function mockFetchResult(over: Partial<MutationResult> = {}): void {
 }
 
 describe("runCommit — instantPatch wiring", () => {
+  it("no-op commit with an instantPatch still patches the runtime (paired x/y commits)", async () => {
+    patchRuntimeTweenInPlace.mockReturnValue(true);
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+
+    await act(async () => {
+      await deps.api.commitMutation(
+        selection,
+        { type: "update-property", property: "y", value: 311 },
+        {
+          label: "Move layer",
+          softReload: true,
+          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 485, y: 311 } } },
+        },
+      );
+    });
+
+    // The file already matched (changed:false) but the runtime patch deferred
+    // from the paired first commit must still land.
+    expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
+      kind: "set",
+      props: { x: 485, y: 311 },
+    });
+    expect(deps.reloadPreview).not.toHaveBeenCalled();
+  });
+
   beforeEach(() => {
     patchRuntimeTweenInPlace.mockReset();
     applySoftReload.mockReset();
@@ -308,15 +347,7 @@ describe("runCommit — instantPatch wiring", () => {
     const deps = renderCommitHook();
 
     await act(async () => {
-      await deps.api.commitMutation(
-        selection,
-        { x: 10 },
-        {
-          label: "drag",
-          softReload: true,
-          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-        },
-      );
+      await deps.api.commitMutation(selection, { x: 10 }, dragOptions());
     });
 
     expect(fetch).toHaveBeenCalledTimes(1); // source mutation persisted
@@ -333,19 +364,17 @@ describe("runCommit — instantPatch wiring", () => {
     const deps = renderCommitHook();
 
     await act(async () => {
-      await deps.api.commitMutation(
-        selection,
-        { x: 10 },
-        {
-          label: "drag",
-          softReload: true,
-          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
-        },
-      );
+      await deps.api.commitMutation(selection, { x: 10 }, dragOptions());
     });
 
     expect(fetch).toHaveBeenCalledTimes(1);
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      deps.reloadPreview,
+      0,
+      "AFTER",
+    );
     expect(deps.reloadPreview).not.toHaveBeenCalled();
     expect(deps.onCacheInvalidate).toHaveBeenCalledTimes(1);
   });
@@ -360,7 +389,13 @@ describe("runCommit — instantPatch wiring", () => {
     });
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", deps.reloadPreview, 0);
+    expect(applySoftReload).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "SCRIPT",
+      deps.reloadPreview,
+      0,
+      "AFTER",
+    );
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.ts b/packages/studio/src/hooks/useGsapScriptCommits.ts
index e490f6ee5f..a28478acb4 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.ts
+++ b/packages/studio/src/hooks/useGsapScriptCommits.ts
@@ -66,12 +66,19 @@ function softReloadOrEscalate(
   scriptText: string,
   reloadPreview: () => void,
   origin: "preview_sync" | "sdk_refresh",
+  authoredHtml?: string,
 ): void {
   // Seek the rebuilt timeline to the studio's own authoritative scrub position,
   // not the iframe's raw `__player.getTime()` — see the comment in
   // applySoftReload for why the two can desync after a keyframe-node drag.
   const currentTime = usePlayerStore.getState().currentTime;
-  const result: SoftReloadResult = applySoftReload(iframe, scriptText, reloadPreview, currentTime);
+  const result: SoftReloadResult = applySoftReload(
+    iframe,
+    scriptText,
+    reloadPreview,
+    currentTime,
+    authoredHtml,
+  );
   if (result === "applied") return;
   trackStudioEvent("gsap_soft_reload_outcome", {
     origin,
@@ -116,7 +123,13 @@ export function applyPreviewSync(
     // already correct on screen, and a remount re-flashes the WebGL context AND
     // re-inlines subcomps (reverting their keyframes). The async MotionPath-plugin
     // load failure escalates separately via `onAsyncFailure`.
-    softReloadOrEscalate(iframe, result.scriptText, reloadPreview, "preview_sync");
+    softReloadOrEscalate(
+      iframe,
+      result.scriptText,
+      reloadPreview,
+      "preview_sync",
+      result.after ?? undefined,
+    );
   } else {
     reloadPreview();
   }
@@ -149,7 +162,19 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       if (options.skipReload) return;
       throw error;
     }
-    if (result.changed === false) return;
+    if (result.changed === false) {
+      // The FILE already matched, but a deferred instant patch may still be
+      // owed to the RUNTIME: paired commits (x with skipReload, then y carrying
+      // the patch for both) rely on the SECOND commit to sync the preview — if
+      // that half happens to be a no-op (a purely-horizontal drag or resize
+      // compensation), returning here would leave the runtime showing the old
+      // value while the file holds the new one. Patching in place is idempotent
+      // when the values truly match everywhere.
+      if (!options.skipReload && options.instantPatch) {
+        applyPreviewSync(previewIframeRef.current, result, options, reloadPreview);
+      }
+      return;
+    }
     domEditSaveTimestampRef.current = Date.now();
     if (result.before != null && result.after != null) {
       await editHistory.recordEdit({ label: options.label, kind: "manual", coalesceKey: options.coalesceKey, files: { [targetPath]: { before: result.before, after: result.after } } });
@@ -196,7 +221,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
         // plugin-CDN load error genuinely breaks the iframe → full reload. Per U4, a
         // synchronous "verify-failed" (transient empty __timelines) does NOT escalate,
         // but a "cannot-soft-reload" (structural failure) does.
-        softReloadOrEscalate(previewIframeRef.current, script, reloadPreview, "sdk_refresh");
+        softReloadOrEscalate(previewIframeRef.current, script, reloadPreview, "sdk_refresh", after);
       } else {
         reloadPreview();
       }
diff --git a/packages/studio/src/utils/authoredOpacity.ts b/packages/studio/src/utils/authoredOpacity.ts
new file mode 100644
index 0000000000..6a6b4998b0
--- /dev/null
+++ b/packages/studio/src/utils/authoredOpacity.ts
@@ -0,0 +1,28 @@
+/**
+ * Authored-opacity contract, studio side. The runtime stamps every graded
+ * element's authored inline opacity at document parse time (see
+ * installAuthoredOpacityCapture in @hyperframes/core); studio code that makes
+ * GSAP re-initialize tweens (soft reload, in-place patches) restores it so
+ * re-captures never bake a runtime transient in as a tween bound.
+ */
+import { COLOR_GRADING_AUTHORED_OPACITY_ATTR } from "@hyperframes/core/color-grading";
+
+interface AttributeReader {
+  getAttribute(name: string): string | null;
+}
+
+/**
+ * The stamped authored inline opacity. Three-state:
+ *   "0.98" — the authored value; "" — captured, authored none;
+ *   null — never captured (unknown).
+ * Duck-typed so iframe-realm elements (no shared HTMLElement) work.
+ */
+export function readStampedAuthoredOpacity(element: AttributeReader): string | null {
+  return element.getAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR);
+}
+
+/** Write an authored inline opacity back: "" removes the property, a value sets it. */
+export function applyAuthoredInlineOpacity(style: CSSStyleDeclaration, authored: string): void {
+  if (authored === "") style.removeProperty("opacity");
+  else style.setProperty("opacity", authored);
+}
diff --git a/packages/studio/src/utils/elementGsap.ts b/packages/studio/src/utils/elementGsap.ts
new file mode 100644
index 0000000000..e89b6f9864
--- /dev/null
+++ b/packages/studio/src/utils/elementGsap.ts
@@ -0,0 +1,31 @@
+/**
+ * GSAP access through an ELEMENT'S OWN window (the preview iframe's runtime),
+ * not the studio window. This is the single way studio gesture code touches an
+ * iframe element's GSAP position outside the commit pipeline — the resize
+ * anchor pin (apply + restore) and the post-commit live correction. The commit
+ * pipeline itself stays the owner of persisted values.
+ */
+type ElementGsapWindow = Window & {
+  gsap?: {
+    set?: (target: Element, vars: Record<string, number>) => void;
+    getProperty?: (target: Element, prop: string) => unknown;
+  };
+};
+
+function gsapOf(element: HTMLElement): ElementGsapWindow["gsap"] | undefined {
+  return (element.ownerDocument.defaultView as ElementGsapWindow | null)?.gsap;
+}
+
+/** Set the element's GSAP x/y. Returns false when no runtime is reachable. */
+export function setElementGsapPosition(element: HTMLElement, x: number, y: number): boolean {
+  const gsap = gsapOf(element);
+  if (!gsap?.set) return false;
+  gsap.set(element, { x, y });
+  return true;
+}
+
+/** The element's GSAP numeric property, or null when unreadable. */
+export function readElementGsapNumber(element: HTMLElement, prop: string): number | null {
+  const value = Number(gsapOf(element)?.getProperty?.(element, prop));
+  return Number.isFinite(value) ? value : null;
+}
diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.ts
index 1cea9b7897..a5f08eea31 100644
--- a/packages/studio/src/utils/gsapSoftReload.ts
+++ b/packages/studio/src/utils/gsapSoftReload.ts
@@ -1,3 +1,6 @@
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
+import { applyAuthoredInlineOpacity, readStampedAuthoredOpacity } from "./authoredOpacity";
+
 type IframeWindow = Window & {
   __timelines?: Record<string, { kill?: () => void; pause?: () => void }>;
   __player?: { getTime?: () => number; seek?: (t: number) => void };
@@ -176,6 +179,7 @@ export function applySoftReload(
   scriptText: string,
   onAsyncFailure?: () => void,
   currentTimeOverride?: number,
+  authoredHtml?: string,
 ): SoftReloadResult {
   if (!iframe || !scriptText) return "cannot-soft-reload";
 
@@ -227,6 +231,36 @@ export function applySoftReload(
   // full iframe reload that destroys the very WebGL context we're preserving.
   let deferredToAsync = false;
 
+  // Authored-opacity resolution for the restore loop below. Three-state:
+  //   "0.98" — the element's authored inline opacity
+  //   ""     — resolved, and the element has NO authored inline opacity
+  //   null   — unknown (no authored HTML supplied, element not found in it,
+  //            and no runtime parse-time stamp)
+  // The just-written file (`authoredHtml`) is the current truth; the runtime's
+  // parse-time stamp (data-hf-authored-opacity, installAuthoredOpacityCapture)
+  // covers elements the file lookup can't resolve. Parsed lazily, at most once.
+  let authoredDoc: Document | null | undefined;
+  const findAuthoredSource = (el: HTMLElement): Element | null => {
+    if (authoredDoc === undefined) {
+      try {
+        authoredDoc = authoredHtml
+          ? new DOMParser().parseFromString(authoredHtml, "text/html")
+          : null;
+      } catch {
+        authoredDoc = null;
+      }
+    }
+    if (!authoredDoc) return null;
+    const hfId = el.getAttribute("data-hf-id");
+    if (hfId) return authoredDoc.querySelector(`[data-hf-id="${hfId}"]`);
+    return el.id ? authoredDoc.getElementById(el.id) : null;
+  };
+  const readAuthoredOpacity = (el: HTMLElement): string | null => {
+    const source = findAuthoredSource(el);
+    if (source instanceof HTMLElement) return source.style.opacity;
+    return readStampedAuthoredOpacity(el);
+  };
+
   // fallow-ignore-next-line complexity
   const doReload = () => {
     const timelines = win.__timelines;
@@ -283,19 +317,37 @@ export function applySoftReload(
     // nukes the element's CSS base (position, width, height, etc.) from the
     // HTML `style=""` attribute. Save → clear → restore → strip `transform`.
     if (allTargets.length > 0 && win.gsap?.set) {
-      const saved: Array<[Element, string]> = [];
+      const saved: Array<[HTMLElement, string]> = [];
       for (const el of allTargets) {
         const s = (el as HTMLElement).style;
-        if (s?.cssText != null) saved.push([el, s.cssText]);
+        if (s?.cssText != null) saved.push([el as HTMLElement, s.cssText]);
       }
       try {
         win.gsap.set(allTargets, { clearProps: "all" });
       } catch {}
       for (const [el, css] of saved) {
-        const s = (el as HTMLElement).style;
-        if (!s) continue;
+        const s = el.style;
         s.cssText = css;
         s.removeProperty("transform");
+        // The restored cssText carries RUNTIME opacity, not authored opacity:
+        // a mid-flight tween's interpolated value, or the color-grading hide
+        // (`opacity: 0 !important`). The re-run script's tweens re-initialize
+        // against it — a from() captures it as its END, a to() as its START —
+        // turning the transient into the tween's permanent bound (dimmed or
+        // invisible elements). Put the AUTHORED inline opacity back; the seek
+        // below re-renders the correct animated value either way.
+        const authored = readAuthoredOpacity(el);
+        if (authored !== null) {
+          applyAuthoredInlineOpacity(s, authored);
+        } else if (
+          el.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR) &&
+          s.getPropertyValue("opacity") === "0" &&
+          s.getPropertyPriority("opacity") === "important"
+        ) {
+          // Authored value unknown, but this is definitely the grading hide —
+          // never let a from() capture 0; fall back to the CSS cascade.
+          s.removeProperty("opacity");
+        }
       }
     }
 

From 4be78e88bb58d528cf8d3f74f8d7dd0bafe89767 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 04:07:06 -0400
Subject: [PATCH 05/24] fix(studio): correct gesture commits for scaled and
 graded elements

- resize on a scale-driven element commits per-axis scale (scaleX/scaleY
  for non-uniform drags) with keyframe normalization to the longhands, and
  clears the width/height draft so size can't double-apply; the intercept
  moves to gsapResizeIntercept.ts
- the drop frame applies the corrected position synchronously in the same
  microtask chain as the soft reload (no network-window jump), and the
  draft pins the anchor through accumulated moves on scaled elements
- gesture size/position math divides by the element's own content scale
- convert-to-keyframes resolves current values through the property-group
  filter for ALL capture passes (opacity/rotationX from unrelated tweens
  no longer leak into a rotation commit), and a grading-hidden source's
  opacity is read from its canvas, not the inline hide
- canvas pointer-down confirms the hover target with a synchronous
  hit-test before starting a marquee (stale-hover race lost selections)
---
 .../components/editor/DomEditOverlay.test.ts  |  41 ++
 .../src/components/editor/DomEditOverlay.tsx  |  13 +-
 .../editor/domEditOverlayGestures.ts          |  41 +-
 .../editor/domEditOverlayStartGesture.ts      |  37 +-
 .../editor/useDomEditOverlayGestures.ts       |  55 ++-
 .../studio/src/hooks/gsapResizeIntercept.ts   | 379 ++++++++++++++++++
 .../studio/src/hooks/gsapRuntimeBridge.ts     | 229 +----------
 .../src/hooks/gsapRuntimeReaders.test.ts      | 111 +++++
 .../studio/src/hooks/gsapRuntimeReaders.ts    |  47 ++-
 .../studio/src/hooks/useGsapAwareEditing.ts   |   7 +-
 10 files changed, 703 insertions(+), 257 deletions(-)
 create mode 100644 packages/studio/src/hooks/gsapResizeIntercept.ts
 create mode 100644 packages/studio/src/hooks/gsapRuntimeReaders.test.ts

diff --git a/packages/studio/src/components/editor/DomEditOverlay.test.ts b/packages/studio/src/components/editor/DomEditOverlay.test.ts
index db1f2291bc..fbc8eccb26 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.test.ts
+++ b/packages/studio/src/components/editor/DomEditOverlay.test.ts
@@ -535,6 +535,47 @@ describe("resolveDomEditResizeGesture", () => {
     });
   });
 
+  it("divides the cursor delta by the element's content scale (rescaled element)", () => {
+    // Element renders at 2x via a GSAP scale: a 30px cursor delta must grow the
+    // CSS box by only 15px so the RENDERED box tracks the pointer 1:1.
+    const next = resolveDomEditResizeGesture({
+      originWidth: 480, // 240 css x 2 content scale (overlay px at editScale 1)
+      originHeight: 240,
+      actualWidth: 240,
+      actualHeight: 120,
+      scaleX: 1,
+      scaleY: 1,
+      contentScaleX: 2,
+      contentScaleY: 2,
+      dx: 30,
+      dy: 12,
+      uniform: false,
+    });
+    expect(next.width).toBe(255);
+    expect(next.height).toBe(126);
+    // The overlay box keeps tracking the raw cursor.
+    expect(next.overlayWidth).toBe(510);
+    expect(next.overlayHeight).toBe(252);
+  });
+
+  it("treats a missing/invalid content scale as 1 (unscaled element)", () => {
+    const next = resolveDomEditResizeGesture({
+      originWidth: 240,
+      originHeight: 120,
+      actualWidth: 240,
+      actualHeight: 120,
+      scaleX: 1,
+      scaleY: 1,
+      contentScaleX: 0,
+      contentScaleY: Number.NaN,
+      dx: 30,
+      dy: 12,
+      uniform: false,
+    });
+    expect(next.width).toBe(270);
+    expect(next.height).toBe(132);
+  });
+
   it("snaps width and height to the same value when Shift is held", () => {
     expect(
       resolveDomEditResizeGesture({
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index 737a474550..5b444a7c78 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -1,4 +1,5 @@
 import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
 import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
@@ -305,8 +306,18 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     const target = event.target as HTMLElement | null;
     if (target?.closest('[data-dom-edit-selection-box="true"]')) return;
 
-    // Start marquee if clicking on empty canvas (no element under pointer)
+    // Start marquee if clicking on empty canvas (no element under pointer).
+    // The hover selection is an ASYNC cache: on a fast click (or when the
+    // pointer was already resting over an element) it can still be empty while
+    // an element IS under the pointer — starting a marquee here would swallow
+    // the selection mousedown and the click would silently select nothing.
+    // Confirm emptiness with a fresh SYNCHRONOUS hit-test before committing.
     if (!hoverSelectionRef.current && onMarqueeSelectRef.current && compRect.width > 0) {
+      const iframe = iframeRef.current;
+      const freshTarget = iframe
+        ? getPreviewTargetFromPointer(iframe, event.clientX, event.clientY, activeCompositionPath)
+        : null;
+      if (freshTarget) return;
       const overlayEl = overlayRef.current;
       if (overlayEl) {
         const oRect = overlayEl.getBoundingClientRect();
diff --git a/packages/studio/src/components/editor/domEditOverlayGestures.ts b/packages/studio/src/components/editor/domEditOverlayGestures.ts
index 7f3c63c805..2abc793b65 100644
--- a/packages/studio/src/components/editor/domEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/domEditOverlayGestures.ts
@@ -39,6 +39,25 @@ export interface GestureState {
   actualRotation: number;
   editScaleX: number;
   editScaleY: number;
+  // Rendered-per-CSS-pixel factor of the element itself at gesture start (a GSAP
+  // scale() transform makes this > 1) — the resize draft divides by it so the box
+  // follows the cursor instead of overshooting by the live scale.
+  contentScaleX: number;
+  contentScaleY: number;
+  // Resize anchor pinning: with a live scale transform, growing the CSS box
+  // shifts the rendered box (scaling happens around the element center), so the
+  // un-dragged corner creeps during the draft. The move handler measures the
+  // gesture-start top-left drift each frame and counters it through the GSAP
+  // position channel; the pin accumulates so the correction converges.
+  // Present only on resize gestures.
+  resizeAnchor?: {
+    anchorX: number;
+    anchorY: number;
+    baseGsapX: number;
+    baseGsapY: number;
+    pinX: number;
+    pinY: number;
+  };
   manualEditDragToken?: string;
   snapContext?: SnapContext;
   lastSnappedDx?: number;
@@ -77,21 +96,31 @@ export function resolveDomEditResizeGesture(input: {
   actualHeight: number;
   scaleX: number;
   scaleY: number;
+  // Rendered-per-CSS-pixel factor of the element itself (its live GSAP scale).
+  // The CSS width/height the draft writes get multiplied by this on screen, so
+  // the cursor delta must be divided by it — otherwise the box outruns the
+  // pointer on a rescaled element and snaps back on release. Defaults to 1.
+  contentScaleX?: number;
+  contentScaleY?: number;
   dx: number;
   dy: number;
   uniform: boolean;
 }): { overlayWidth: number; overlayHeight: number; width: number; height: number } {
   const scaleX = input.scaleX > 0 ? input.scaleX : 1;
   const scaleY = input.scaleY > 0 ? input.scaleY : 1;
+  const contentScaleX =
+    input.contentScaleX !== undefined && input.contentScaleX > 0 ? input.contentScaleX : 1;
+  const contentScaleY =
+    input.contentScaleY !== undefined && input.contentScaleY > 0 ? input.contentScaleY : 1;
 
   if (input.uniform) {
-    const deltaX = input.dx / scaleX;
-    const deltaY = input.dy / scaleY;
+    const deltaX = input.dx / (scaleX * contentScaleX);
+    const deltaY = input.dy / (scaleY * contentScaleY);
     const delta = Math.abs(deltaX) >= Math.abs(deltaY) ? deltaX : deltaY;
     const side = Math.max(1, Math.max(input.actualWidth, input.actualHeight) + delta);
     return {
-      overlayWidth: Math.max(MIN_RESIZE_EDGE_PX, side * scaleX),
-      overlayHeight: Math.max(MIN_RESIZE_EDGE_PX, side * scaleY),
+      overlayWidth: Math.max(MIN_RESIZE_EDGE_PX, side * scaleX * contentScaleX),
+      overlayHeight: Math.max(MIN_RESIZE_EDGE_PX, side * scaleY * contentScaleY),
       width: side,
       height: side,
     };
@@ -100,8 +129,8 @@ export function resolveDomEditResizeGesture(input: {
   return {
     overlayWidth: Math.max(MIN_RESIZE_EDGE_PX, input.originWidth + input.dx),
     overlayHeight: Math.max(MIN_RESIZE_EDGE_PX, input.originHeight + input.dy),
-    width: Math.max(1, input.actualWidth + input.dx / scaleX),
-    height: Math.max(1, input.actualHeight + input.dy / scaleY),
+    width: Math.max(1, input.actualWidth + input.dx / (scaleX * contentScaleX)),
+    height: Math.max(1, input.actualHeight + input.dy / (scaleY * contentScaleY)),
   };
 }
 
diff --git a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
index f91a8a4347..636265e206 100644
--- a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
+++ b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
@@ -2,6 +2,7 @@
  * Gesture-begin functions: startGroupDrag and startGesture.
  * These are pure "start a new gesture" operations — no draft rect updates.
  */
+import { readElementGsapNumber } from "../../utils/elementGsap";
 import { type DomEditSelection } from "./domEditing";
 import {
   createManualOffsetDragMember,
@@ -120,8 +121,37 @@ export function startGesture(
   // `--hf-studio-rotation` CSS var (old projects), so a rotate gesture starts from the
   // element's actual visual angle and commits an absolute angle to the timeline.
   const rotation = { angle: readGsapRotation(sel.element) + readStudioRotation(sel.element).angle };
-  const actualWidth = size.width > 0 ? size.width : rect.width / rect.editScaleX;
-  const actualHeight = size.height > 0 ? size.height : rect.height / rect.editScaleY;
+  // The draft writes CSS width/height, so the resize base must be the CSS
+  // layout size. offsetWidth/Height are transform-free; the overlay-rect
+  // fallback (rect / editScale) includes the element's own GSAP scale and
+  // would make a rescaled element's draft grow from the RENDERED size.
+  const layoutWidth = sel.element.offsetWidth;
+  const layoutHeight = sel.element.offsetHeight;
+  const actualWidth =
+    size.width > 0 ? size.width : layoutWidth > 0 ? layoutWidth : rect.width / rect.editScaleX;
+  const actualHeight =
+    size.height > 0 ? size.height : layoutHeight > 0 ? layoutHeight : rect.height / rect.editScaleY;
+  // overlay rect = cssSize x contentScale x editScale, so the element's own
+  // render factor (its GSAP scale) falls out of the measured rect. 1 when
+  // unscaled or unmeasurable.
+  const rawContentScaleX = rect.width / (rect.editScaleX * actualWidth);
+  const rawContentScaleY = rect.height / (rect.editScaleY * actualHeight);
+  const contentScaleX =
+    Number.isFinite(rawContentScaleX) && rawContentScaleX > 0 ? rawContentScaleX : 1;
+  const contentScaleY =
+    Number.isFinite(rawContentScaleY) && rawContentScaleY > 0 ? rawContentScaleY : 1;
+  let resizeAnchor: GestureState["resizeAnchor"];
+  if (kind === "resize") {
+    const startBcr = sel.element.getBoundingClientRect();
+    resizeAnchor = {
+      anchorX: startBcr.x,
+      anchorY: startBcr.y,
+      baseGsapX: readElementGsapNumber(sel.element, "x") ?? 0,
+      baseGsapY: readElementGsapNumber(sel.element, "y") ?? 0,
+      pinX: 0,
+      pinY: 0,
+    };
+  }
   let initialPathOffset = captureStudioPathOffset(sel.element);
   let manualEditDragToken: string | undefined;
   let pathOffsetMember: ManualOffsetDragMember | undefined;
@@ -184,6 +214,9 @@ export function startGesture(
     actualRotation: rotation.angle,
     editScaleX: rect.editScaleX,
     editScaleY: rect.editScaleY,
+    contentScaleX,
+    contentScaleY,
+    resizeAnchor,
     manualEditDragToken,
     snapContext,
   };
diff --git a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
index bce380b309..83da0418e6 100644
--- a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
@@ -4,6 +4,7 @@
  * Owns: onPointerMove, onPointerUp, clearPointerState.
  * startGesture and startGroupDrag live in domEditOverlayStartGesture.ts.
  */
+import { setElementGsapPosition } from "../../utils/elementGsap";
 import type { RefObject } from "react";
 import { type DomEditSelection } from "./domEditing";
 import {
@@ -53,6 +54,13 @@ import {
   resolveEquidistanceGuides,
   SNAP_THRESHOLD_PX,
 } from "./snapEngine";
+/** Undo the resize draft's anchor pin: snap GSAP x/y back to the gesture base. */
+function restoreResizeAnchorPin(element: HTMLElement, g: GestureState): void {
+  const anchor = g.resizeAnchor;
+  if (!anchor || (anchor.pinX === 0 && anchor.pinY === 0)) return;
+  setElementGsapPosition(element, anchor.baseGsapX, anchor.baseGsapY);
+}
+
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
     opts.setOverlayRect(next);
@@ -175,7 +183,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         actualAngle: g.actualRotation,
         snap: e.shiftKey,
       });
-      if (!applyRotationDraftViaGsap(sel.element, rotated.angle)) {
+      const draftViaGsap = applyRotationDraftViaGsap(sel.element, rotated.angle);
+      if (!draftViaGsap) {
         applyStudioRotationDraft(sel.element, rotated);
       }
       return;
@@ -278,12 +287,35 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         actualHeight: g.actualHeight,
         scaleX: g.editScaleX,
         scaleY: g.editScaleY,
+        contentScaleX: g.contentScaleX,
+        contentScaleY: g.contentScaleY,
         dx,
         dy,
         uniform: e.shiftKey,
       });
       applyStudioBoxSizeDraft(sel.element, nextSize);
-
+      // Pin the gesture anchor (top-left): with a live scale transform, the CSS
+      // size change shifts the rendered box around the element center. Measure
+      // the drift of the gesture-start corner and counter it via GSAP x/y —
+      // accumulated onto the previous pin so the correction converges instead
+      // of oscillating. The release-time position compensation re-measures the
+      // drop, so the pin composes with the commit.
+      const anchor = g.resizeAnchor;
+      if (anchor) {
+        const pinned = sel.element.getBoundingClientRect();
+        const nextPinX = anchor.pinX + (anchor.anchorX - pinned.x);
+        const nextPinY = anchor.pinY + (anchor.anchorY - pinned.y);
+        if (
+          setElementGsapPosition(
+            sel.element,
+            anchor.baseGsapX + nextPinX,
+            anchor.baseGsapY + nextPinY,
+          )
+        ) {
+          anchor.pinX = nextPinX;
+          anchor.pinY = nextPinY;
+        }
+      }
       // Re-read BCR after applying dimensions. For elements with a GSAP
       // scale transform and centered transform-origin the visual top-left
       // drifts and the visual size diverges from the raw CSS size, so BCR
@@ -382,6 +414,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (g.kind === "resize" && movedDistance < BLOCKED_MOVE_THRESHOLD_PX) {
+      restoreResizeAnchorPin(sel.element, g);
       restoreStudioBoxSize(sel.element, g.initialBoxSize);
       endStudioManualEditGesture(sel.element, g.manualEditDragToken);
       if (box) {
@@ -411,7 +444,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           restoreStudioRotation(sel.element, g.initialRotation);
         }
       };
-      if (!hasDomEditRotationChanged(g.actualRotation, finalRotation.angle)) {
+      const rotationChanged = hasDomEditRotationChanged(g.actualRotation, finalRotation.angle);
+      if (!rotationChanged) {
         restoreRotation();
         endStudioManualEditGesture(sel.element, g.manualEditDragToken);
         return;
@@ -422,14 +456,17 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         applyStudioRotation(sel.element, finalRotation);
       }
       void Promise.resolve(opts.onRotationCommitRef.current(sel, finalRotation))
-        .catch(() => {
+        .catch((error) => {
+          console.error("rotate commit failed", error);
           if (
             g.manualEditDragToken &&
             isStudioManualEditGestureCurrent(sel.element, g.manualEditDragToken)
           )
             restoreRotation();
         })
-        .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
+        .finally(() => {
+          endStudioManualEditGesture(sel.element, g.manualEditDragToken);
+        });
     } else if (g.kind === "drag") {
       const dx = g.lastSnappedDx ?? e.clientX - g.startX;
       const dy = g.lastSnappedDy ?? e.clientY - g.startY;
@@ -469,12 +506,15 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       const finalSize = readStudioBoxSize(sel.element);
       applyStudioBoxSize(sel.element, finalSize);
       void Promise.resolve(opts.onBoxSizeCommitRef.current(sel, finalSize))
-        .catch(() => {
+        .catch((error) => {
+          console.error("resize commit failed", error);
           if (
             g.manualEditDragToken &&
             isStudioManualEditGestureCurrent(sel.element, g.manualEditDragToken)
-          )
+          ) {
+            restoreResizeAnchorPin(sel.element, g);
             restoreStudioBoxSize(sel.element, g.initialBoxSize);
+          }
         })
         .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
     }
@@ -494,6 +534,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "box-size" && sel) {
+      restoreResizeAnchorPin(sel.element, g);
       restoreStudioBoxSize(sel.element, g.initialBoxSize);
       endStudioManualEditGesture(sel.element, g.manualEditDragToken);
       restoreGestureOverlayRect(g);
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.ts b/packages/studio/src/hooks/gsapResizeIntercept.ts
new file mode 100644
index 0000000000..aee92be6f5
--- /dev/null
+++ b/packages/studio/src/hooks/gsapResizeIntercept.ts
@@ -0,0 +1,379 @@
+/**
+ * Resize-gesture GSAP intercept: routes a manual resize on a scale-driven
+ * element into scale commits (per-axis longhands for non-uniform drags, with
+ * keyframe normalization), then settles position synchronously so the drop
+ * frame can't jump. Split from gsapRuntimeBridge, which owns the shared
+ * group-tween resolution used by the drag/resize/rotate intercepts.
+ */
+import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { clearStudioBoxSize } from "../components/editor/manualEdits";
+import { setElementGsapPosition } from "../utils/elementGsap";
+import { usePlayerStore } from "../player/store/playerStore";
+import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeReaders";
+import {
+  commitStaticGsapPosition,
+  commitStaticGsapSize,
+  commitKeyframedSizeFromResize,
+  computeCurrentPercentage,
+  findSizeSetAnimation,
+  materializeIfDynamic,
+} from "./gsapDragCommit";
+import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
+import { pickClosestToPlayhead } from "./gsapPositionDetection";
+import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { selectorFromSelection } from "./gsapShared";
+import { roundTo3 } from "../utils/rounding";
+import { resolveGroupTween, POSITION_CHANNELS } from "./gsapRuntimeBridge";
+import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
+import { readGsapPositionFromIframe } from "./gsapPositionDetection";
+import { findExistingPositionWrite } from "./gsapDragCommit";
+import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
+
+const IDENTITY_ONE_PROPS = new Set(["opacity", "autoAlpha", "scale", "scaleX", "scaleY"]);
+
+/** Build identity (zero / one) values for each property in `source`. */
+function synthesizeIdentityProps(
+  source: Record<string, number | string>,
+): Record<string, number | string> {
+  const id: Record<string, number | string> = {};
+  for (const [k, v] of Object.entries(source)) {
+    if (typeof v === "number") id[k] = IDENTITY_ONE_PROPS.has(k) ? 1 : 0;
+    else id[k] = v;
+  }
+  return id;
+}
+
+// ── Resize intercept ──────────────────────────────────────────────────────
+
+// fallow-ignore-next-line complexity
+export async function tryGsapResizeIntercept(
+  selection: DomEditSelection,
+  size: { width: number; height: number },
+  animations: GsapAnimation[],
+  iframe: HTMLIFrameElement | null,
+  commitMutation: GsapDragCommitCallbacks["commitMutation"],
+  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
+): Promise<boolean> {
+  // If the element already has a scale-group tween, resize should modify scale
+  // (the user is resizing something whose visual size is driven by scale).
+  // Otherwise, use the size group (width/height).
+  const hasScaleGroup = animations.some((a) => a.propertyGroup === "scale");
+  const resizeGroup: PropertyGroupName = hasScaleGroup ? "scale" : "size";
+  const resolved = await resolveGroupTween(
+    resizeGroup,
+    animations,
+    selection,
+    commitMutation,
+    fetchFallbackAnimations,
+  );
+
+  let anim = resolved?.anim ?? null;
+  if (!anim || anim.method === "set") {
+    const sel = selectorFromSelection(selection);
+    if (!sel) return false;
+    const sizeSet = anim?.method === "set" ? anim : findSizeSetAnimation(animations, sel);
+
+    // If the element is animated (has a real tween, not just a static size
+    // hold), keyframe the size at the playhead so other keyframes keep theirs —
+    // instead of a global set that resizes every frame.
+    if (resizeGroup === "size") {
+      const animatedTween = pickClosestToPlayhead(
+        animations.filter((a) => a.method !== "set" && resolveTweenDuration(a) > 0),
+      );
+      if (animatedTween) {
+        const handled = await commitKeyframedSizeFromResize(
+          selection,
+          size,
+          sel,
+          sizeSet,
+          animatedTween,
+          { commitMutation, fetchAnimations: fetchFallbackAnimations },
+        );
+        if (handled) return true;
+      }
+    }
+
+    await commitStaticGsapSize(selection, size, sel, sizeSet, {
+      commitMutation,
+      fetchAnimations: fetchFallbackAnimations,
+    });
+    return true;
+  }
+
+  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
+  const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
+  if (activeKeyframePct != null) setActiveKeyframePct(null);
+  const coalesceKey = `gsap:resize:${anim.id}`;
+
+  const selector = selectorFromSelection(selection);
+  const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
+
+  let resizeProps: Record<string, number>;
+  let scaleDraftEl: HTMLElement | null = null;
+  let scaleDraftDropPoint: { x: number; y: number } | null = null;
+  let nonUniformScale = false;
+  if (resizeGroup === "scale") {
+    const el = iframe?.contentDocument?.querySelector(selector ?? "") as HTMLElement | null;
+    // The resize draft modifies el.style.width/height, so read the ORIGINAL
+    // dimensions saved by the draft system before it ran.
+    const origW = Number.parseFloat(el?.getAttribute("data-hf-studio-original-width") ?? "");
+    const origH = Number.parseFloat(el?.getAttribute("data-hf-studio-original-height") ?? "");
+    const cssW = Number.isFinite(origW) && origW > 0 ? origW : 200;
+    const cssH = Number.isFinite(origH) && origH > 0 ? origH : cssW;
+    // `size` is the draft's CSS box; on screen it is multiplied by the element's
+    // LIVE scale (the draft divides the cursor delta by it — see
+    // resolveDomEditResizeGesture). The committed keyframe REPLACES that live
+    // scale, so it must reproduce the rendered intent: css × live / original.
+    // Live scale is 1 on a fresh element (first resize), so this is a no-op there.
+    const rawLiveScaleX = readGsapProperty(iframe, selector ?? null, "scaleX") ?? 1;
+    const rawLiveScaleY = readGsapProperty(iframe, selector ?? null, "scaleY") ?? 1;
+    const liveScaleX = rawLiveScaleX > 0 ? rawLiveScaleX : 1;
+    const liveScaleY = rawLiveScaleY > 0 ? rawLiveScaleY : 1;
+    const newScaleX = roundTo3((size.width * liveScaleX) / cssW);
+    const newScaleY = roundTo3((size.height * liveScaleY) / cssH);
+    // A free-form corner drag is usually NON-uniform. A single `scale` value
+    // can't represent it — committing width-derived scale used to snap the
+    // height at drop. Commit scaleX/scaleY longhands instead; keep the uniform
+    // shorthand when the two agree (aspect-true drags, shift-drags).
+    nonUniformScale = Math.abs(newScaleX - newScaleY) > 0.01;
+    resizeProps = nonUniformScale ? { scaleX: newScaleX, scaleY: newScaleY } : { scale: newScaleX };
+    scaleDraftEl = el;
+    // Where the user DROPPED the box: the draft (anchor-pinned to the
+    // gesture-start top-left) is still applied here, so this rect is exactly
+    // what the preview showed at release. The committed scale renders around
+    // the element CENTER instead — the finalize step below measures that
+    // difference and compensates, so release matches the drop pixel-for-pixel
+    // regardless of live scale or repeat resizes.
+    if (el) {
+      const dropRect = el.getBoundingClientRect();
+      scaleDraftDropPoint = { x: dropRect.x, y: dropRect.y };
+    }
+  } else {
+    resizeProps = {
+      width: Math.round(size.width),
+      height: Math.round(size.height),
+    };
+  }
+  // Finalize a scale-route commit: tear down the gesture's inline width/height
+  // draft (leaving it applied compounds with the committed scale — the element
+  // jumps past the dragged size), then MEASURE where the committed scale
+  // actually rendered the box and shift the position hold by the residual so
+  // it lands back on the drop point. The compensation only applies to a STATIC
+  // position (a `tl.set` hold or none) — a keyframed position path has no
+  // single anchor to preserve, so it keeps the plain center-scale behavior.
+  // The size route commits the same width/height channels the draft wrote, so
+  // it needs none of this.
+  // ponytail: for a 3D-rotated element the rects are AABBs, so the anchor is
+  // approximate rather than corner-exact.
+  // fallow-ignore-next-line complexity
+  const finalizeScaleResizeCommit = async () => {
+    if (!scaleDraftEl) return;
+    clearStudioBoxSize(scaleDraftEl);
+    if (!scaleDraftDropPoint || !selector) return;
+    const hasLivePositionTween = hasNonHoldTweenForElement(
+      iframe,
+      selector,
+      undefined,
+      POSITION_CHANNELS,
+    );
+    if (hasLivePositionTween) {
+      return;
+    }
+    // The scale commit has rendered (instant patch or soft-reload seek) and the
+    // draft is cleared — this rect is where the element ACTUALLY sits now.
+    const post = scaleDraftEl.getBoundingClientRect();
+    const residual = { x: scaleDraftDropPoint.x - post.x, y: scaleDraftDropPoint.y - post.y };
+    if (!Number.isFinite(residual.x) || !Number.isFinite(residual.y)) return;
+    if (Math.abs(residual.x) < 0.5 && Math.abs(residual.y) < 0.5) return;
+    const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
+    // The ONE corrected position — rounded once so the live runtime and the
+    // persisted file agree exactly (commitStaticGsapPosition composes the same
+    // rounded value from this delta).
+    const corrected = {
+      x: Math.round(gsapPos.x + residual.x),
+      y: Math.round(gsapPos.y + residual.y),
+    };
+    // Correct the LIVE runtime NOW, synchronously: the soft reload above just
+    // rendered the committed scale around the element center — NOT at the drop
+    // point — and everything up to here runs in the same microtask chain as
+    // that reload, so no frame has painted the uncorrected position yet. The
+    // server persist below costs network round-trips; without this set, the
+    // element visibly sits at the wrong spot for those frames (the drop
+    // "jump"). The persisted commit re-applies the same values (idempotent).
+    setElementGsapPosition(scaleDraftEl, corrected.x, corrected.y);
+    // Re-fetch: the scale commit above just rewrote the script, so the caller's
+    // animation list (and its ids) may be stale for the position lookup.
+    const currentAnimations = fetchFallbackAnimations
+      ? await fetchFallbackAnimations()
+      : (resolved?.animations ?? animations);
+    const existingSet = findExistingPositionWrite(currentAnimations, selector);
+    // Delta chosen so the drag-path math composes back to exactly `corrected`
+    // (no drag scratch attrs exist during a resize, so base = gsapPos).
+    await commitStaticGsapPosition(
+      selection,
+      { x: corrected.x - gsapPos.x, y: corrected.y - gsapPos.y },
+      gsapPos,
+      selector,
+      existingSet,
+      {
+        commitMutation,
+        fetchAnimations: fetchFallbackAnimations,
+      },
+    );
+  };
+
+  // With auto-keyframe off (#1808), `anim` is already a real (non-"set")
+  // tween for this resize group, so nudge it as a whole rather than adding a
+  // keyframe at the playhead.
+  if (!usePlayerStore.getState().autoKeyframeEnabled) {
+    if (activeKeyframePct != null) setActiveKeyframePct(null);
+    await commitWholePropertyOffset(
+      selection,
+      anim,
+      resizeProps,
+      pct,
+      iframe,
+      { commitMutation, fetchAnimations: fetchFallbackAnimations },
+      "Resize animation",
+    );
+    await finalizeScaleResizeCommit();
+    return true;
+  }
+
+  const ct = usePlayerStore.getState().currentTime;
+  const ts = resolveTweenStart(anim);
+  const td = resolveTweenDuration(anim);
+  const outsideRange = ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01); // Convert flat tweens to keyframes only for in-range resizes.
+  // Outside-range uses the extend path which handles everything atomically.
+  if (!outsideRange) {
+    // fallow-ignore-next-line code-duplication
+    if (anim.hasUnresolvedKeyframes || anim.hasUnresolvedSelector) {
+      const newId = await materializeIfDynamic(anim, iframe, commitMutation, selection);
+      if (newId) anim = { ...anim, id: newId };
+    } else if (!anim.keyframes) {
+      const resolvedFromValues = selector
+        ? readAllAnimatedProperties(iframe, selector, anim)
+        : undefined;
+      await commitMutation(
+        selection,
+        { type: "convert-to-keyframes", animationId: anim.id, resolvedFromValues },
+        { label: "Convert to keyframes for resize", skipReload: true, coalesceKey },
+      );
+      if (fetchFallbackAnimations) {
+        const fresh = await fetchFallbackAnimations();
+        const refreshed = fresh.find(
+          (a) => a.targetSelector === anim!.targetSelector && a.keyframes,
+        );
+        if (refreshed) anim = refreshed;
+      }
+    }
+  }
+
+  // A NON-uniform scale must also take the full-rewrite path: it mixes
+  // scaleX/scaleY into a tween whose existing keyframes may carry the uniform
+  // `scale` shorthand, and GSAP's percentage keyframes animate each property
+  // name independently — a shorthand/longhand mix would leave the old `scale`
+  // sub-tween running against the new scaleX/scaleY. The rewrite below
+  // normalizes every keyframe to the longhands. For an in-range resize the
+  // min/max window math below degenerates to the tween's own start/duration,
+  // so timing is unchanged.
+  if ((outsideRange || nonUniformScale) && ts !== null) {
+    // For flat tweens, synthesize the keyframes from the tween's properties
+    const kfs =
+      anim.keyframes?.keyframes ??
+      (() => {
+        const fromProps =
+          anim.method === "from" || anim.method === "fromTo"
+            ? { ...anim.properties }
+            : synthesizeIdentityProps(anim.properties);
+        const toProps =
+          anim.method === "from"
+            ? synthesizeIdentityProps(anim.properties)
+            : { ...anim.properties };
+        return [
+          { percentage: 0, properties: fromProps },
+          { percentage: 100, properties: toProps },
+        ];
+      })();
+    const newStart = Math.min(ct, ts);
+    const newEnd = Math.max(ct, ts + td);
+    const newDuration = Math.max(0.01, newEnd - newStart);
+    const existingKfs = kfs;
+    const remapped: Array<{ percentage: number; properties: Record<string, number | string> }> = [];
+    for (const kf of existingKfs) {
+      const absTime = ts + (kf.percentage / 100) * td;
+      const newPct = Math.round(((absTime - newStart) / newDuration) * 1000) / 10;
+      const props = { ...kf.properties };
+      // Normalize the uniform `scale` shorthand to longhands when this commit
+      // writes scaleX/scaleY, so the tween never mixes the two forms.
+      if (nonUniformScale && "scale" in props) {
+        const uniform = props.scale;
+        if (typeof uniform === "number") {
+          props.scaleX = uniform;
+          props.scaleY = uniform;
+        }
+        delete props.scale;
+      }
+      // Only backfill properties that the animation already had (x, y, scale).
+      // Don't backfill width/height — they should only appear on the resize keyframe.
+      for (const k of Object.keys(resizeProps)) {
+        if (k in props) continue;
+        if (k === "width" || k === "height") continue;
+        props[k] = IDENTITY_ONE_PROPS.has(k) ? 1 : 0;
+      }
+      remapped.push({ percentage: newPct, properties: props });
+    }
+    const targetPct = Math.round(((ct - newStart) / newDuration) * 1000) / 10;
+    // An in-range rewrite can land on an existing keyframe's percentage —
+    // merge into it instead of emitting a duplicate step.
+    const collidingKf = remapped.find((kf) => Math.abs(kf.percentage - targetPct) < 0.05);
+    if (collidingKf) Object.assign(collidingKf.properties, resizeProps);
+    else remapped.push({ percentage: targetPct, properties: resizeProps });
+    remapped.sort((a, b) => a.percentage - b.percentage);
+
+    await commitMutation(
+      selection,
+      {
+        type: "replace-with-keyframes",
+        animationId: anim.id,
+        targetSelector: anim.targetSelector,
+        position: roundTo3(newStart),
+        duration: roundTo3(newDuration),
+        keyframes: remapped,
+      },
+      {
+        label: outsideRange
+          ? `Resize (extended to ${ct.toFixed(2)}s)`
+          : `Resize (keyframe ${Math.round(((ct - newStart) / newDuration) * 1000) / 10}%)`,
+        softReload: true,
+        coalesceKey,
+      },
+    );
+    await finalizeScaleResizeCommit();
+    return true;
+  }
+
+  const SIZE_PROPS = new Set(["width", "height"]);
+  const backfillDefaults: Record<string, number> = {};
+  for (const k of Object.keys(runtimeProps)) {
+    if (SIZE_PROPS.has(k)) continue;
+    backfillDefaults[k] = IDENTITY_ONE_PROPS.has(k) ? 1 : 0;
+  }
+
+  await commitMutation(
+    selection,
+    {
+      type: "add-keyframe",
+      animationId: anim.id,
+      percentage: pct,
+      properties: resizeProps,
+      backfillDefaults,
+    },
+    { label: `Resize (keyframe ${pct}%)`, softReload: true, coalesceKey },
+  );
+  await finalizeScaleResizeCommit();
+  return true;
+}
+
+// ── Rotation intercept ────────────────────────────────────────────────────
diff --git a/packages/studio/src/hooks/gsapRuntimeBridge.ts b/packages/studio/src/hooks/gsapRuntimeBridge.ts
index e328d5205e..601532300c 100644
--- a/packages/studio/src/hooks/gsapRuntimeBridge.ts
+++ b/packages/studio/src/hooks/gsapRuntimeBridge.ts
@@ -17,17 +17,14 @@ import { commitGsapPositionFromDrag } from "./gsapDragPositionCommit";
 import {
   commitStaticGsapPosition,
   commitStaticGsapRotation,
-  commitStaticGsapSize,
-  commitKeyframedSizeFromResize,
   commitWholePathOffset,
   computeCurrentPercentage,
   findExistingPositionWrite,
   findRotationSetAnimation,
-  findSizeSetAnimation,
   materializeIfDynamic,
 } from "./gsapDragCommit";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
-import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { resolveTweenDuration } from "../utils/globalTimeCompiler";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
 import { selectorFromSelection } from "./gsapShared";
 import {
@@ -36,12 +33,11 @@ import {
   readGsapPositionFromIframe,
 } from "./gsapPositionDetection";
 import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
-import { roundTo3 } from "../utils/rounding";
 
 // Position channels — used to scope the "has a live position tween?" check so a
 // sibling rotation/scale animation never forces a static position hold into the
 // keyframe branch (which corrupts it into a frozen duration-0 keyframed tween).
-const POSITION_CHANNELS = [
+export const POSITION_CHANNELS = [
   "x",
   "y",
   "xPercent",
@@ -67,7 +63,7 @@ const POSITION_CHANNELS = [
  *    re-fetch, then return the group tween
  * 3. null — caller must handle the missing-tween case
  */
-async function resolveGroupTween(
+export async function resolveGroupTween(
   group: PropertyGroupName,
   animations: GsapAnimation[],
   selection: DomEditSelection,
@@ -264,224 +260,6 @@ export { readGsapProperty, readAllAnimatedProperties };
 
 // ── Identity-prop synthesis ───────────────────────────────────────────────
 
-const IDENTITY_ONE_PROPS = new Set(["opacity", "autoAlpha", "scale", "scaleX", "scaleY"]);
-
-/** Build identity (zero / one) values for each property in `source`. */
-function synthesizeIdentityProps(
-  source: Record<string, number | string>,
-): Record<string, number | string> {
-  const id: Record<string, number | string> = {};
-  for (const [k, v] of Object.entries(source)) {
-    if (typeof v === "number") id[k] = IDENTITY_ONE_PROPS.has(k) ? 1 : 0;
-    else id[k] = v;
-  }
-  return id;
-}
-
-// ── Resize intercept ──────────────────────────────────────────────────────
-
-export async function tryGsapResizeIntercept(
-  selection: DomEditSelection,
-  size: { width: number; height: number },
-  animations: GsapAnimation[],
-  iframe: HTMLIFrameElement | null,
-  commitMutation: GsapDragCommitCallbacks["commitMutation"],
-  fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
-): Promise<boolean> {
-  // If the element already has a scale-group tween, resize should modify scale
-  // (the user is resizing something whose visual size is driven by scale).
-  // Otherwise, use the size group (width/height).
-  const hasScaleGroup = animations.some((a) => a.propertyGroup === "scale");
-  const resizeGroup: PropertyGroupName = hasScaleGroup ? "scale" : "size";
-  const resolved = await resolveGroupTween(
-    resizeGroup,
-    animations,
-    selection,
-    commitMutation,
-    fetchFallbackAnimations,
-  );
-
-  let anim = resolved?.anim ?? null;
-  if (!anim || anim.method === "set") {
-    const sel = selectorFromSelection(selection);
-    if (!sel) return false;
-    const sizeSet = anim?.method === "set" ? anim : findSizeSetAnimation(animations, sel);
-
-    // If the element is animated (has a real tween, not just a static size
-    // hold), keyframe the size at the playhead so other keyframes keep theirs —
-    // instead of a global set that resizes every frame.
-    if (resizeGroup === "size") {
-      const animatedTween = pickClosestToPlayhead(
-        animations.filter((a) => a.method !== "set" && resolveTweenDuration(a) > 0),
-      );
-      if (animatedTween) {
-        const handled = await commitKeyframedSizeFromResize(
-          selection,
-          size,
-          sel,
-          sizeSet,
-          animatedTween,
-          { commitMutation, fetchAnimations: fetchFallbackAnimations },
-        );
-        if (handled) return true;
-      }
-    }
-
-    await commitStaticGsapSize(selection, size, sel, sizeSet, {
-      commitMutation,
-      fetchAnimations: fetchFallbackAnimations,
-    });
-    return true;
-  }
-
-  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-  const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
-  if (activeKeyframePct != null) setActiveKeyframePct(null);
-  const coalesceKey = `gsap:resize:${anim.id}`;
-
-  const selector = selectorFromSelection(selection);
-  const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
-
-  let resizeProps: Record<string, number>;
-  if (resizeGroup === "scale") {
-    const el = iframe?.contentDocument?.querySelector(selector ?? "") as HTMLElement | null;
-    // The resize draft modifies el.style.width, so read the ORIGINAL width
-    // saved by the draft system before it ran.
-    const origW = Number.parseFloat(el?.getAttribute("data-hf-studio-original-width") ?? "");
-    const cssW = Number.isFinite(origW) && origW > 0 ? origW : 200;
-    const newScale = roundTo3(size.width / cssW);
-    resizeProps = { scale: newScale };
-  } else {
-    resizeProps = {
-      width: Math.round(size.width),
-      height: Math.round(size.height),
-    };
-  }
-
-  // With auto-keyframe off (#1808), `anim` is already a real (non-"set")
-  // tween for this resize group, so nudge it as a whole rather than adding a
-  // keyframe at the playhead.
-  if (!usePlayerStore.getState().autoKeyframeEnabled) {
-    if (activeKeyframePct != null) setActiveKeyframePct(null);
-    await commitWholePropertyOffset(
-      selection,
-      anim,
-      resizeProps,
-      pct,
-      iframe,
-      { commitMutation, fetchAnimations: fetchFallbackAnimations },
-      "Resize animation",
-    );
-    return true;
-  }
-
-  const ct = usePlayerStore.getState().currentTime;
-  const ts = resolveTweenStart(anim);
-  const td = resolveTweenDuration(anim);
-  const outsideRange = ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01); // Convert flat tweens to keyframes only for in-range resizes.
-  // Outside-range uses the extend path which handles everything atomically.
-  if (!outsideRange) {
-    // fallow-ignore-next-line code-duplication
-    if (anim.hasUnresolvedKeyframes || anim.hasUnresolvedSelector) {
-      const newId = await materializeIfDynamic(anim, iframe, commitMutation, selection);
-      if (newId) anim = { ...anim, id: newId };
-    } else if (!anim.keyframes) {
-      const resolvedFromValues = selector
-        ? readAllAnimatedProperties(iframe, selector, anim)
-        : undefined;
-      await commitMutation(
-        selection,
-        { type: "convert-to-keyframes", animationId: anim.id, resolvedFromValues },
-        { label: "Convert to keyframes for resize", skipReload: true, coalesceKey },
-      );
-      if (fetchFallbackAnimations) {
-        const fresh = await fetchFallbackAnimations();
-        const refreshed = fresh.find(
-          (a) => a.targetSelector === anim!.targetSelector && a.keyframes,
-        );
-        if (refreshed) anim = refreshed;
-      }
-    }
-  }
-
-  if (outsideRange && ts !== null) {
-    // For flat tweens, synthesize the keyframes from the tween's properties
-    const kfs =
-      anim.keyframes?.keyframes ??
-      (() => {
-        const fromProps =
-          anim.method === "from" || anim.method === "fromTo"
-            ? { ...anim.properties }
-            : synthesizeIdentityProps(anim.properties);
-        const toProps =
-          anim.method === "from"
-            ? synthesizeIdentityProps(anim.properties)
-            : { ...anim.properties };
-        return [
-          { percentage: 0, properties: fromProps },
-          { percentage: 100, properties: toProps },
-        ];
-      })();
-    const newStart = Math.min(ct, ts);
-    const newEnd = Math.max(ct, ts + td);
-    const newDuration = Math.max(0.01, newEnd - newStart);
-    const existingKfs = kfs;
-    const remapped: Array<{ percentage: number; properties: Record<string, number | string> }> = [];
-    for (const kf of existingKfs) {
-      const absTime = ts + (kf.percentage / 100) * td;
-      const newPct = Math.round(((absTime - newStart) / newDuration) * 1000) / 10;
-      const props = { ...kf.properties };
-      // Only backfill properties that the animation already had (x, y, scale).
-      // Don't backfill width/height — they should only appear on the resize keyframe.
-      for (const k of Object.keys(resizeProps)) {
-        if (k in props) continue;
-        if (k === "width" || k === "height") continue;
-        props[k] = IDENTITY_ONE_PROPS.has(k) ? 1 : 0;
-      }
-      remapped.push({ percentage: newPct, properties: props });
-    }
-    const targetPct = Math.round(((ct - newStart) / newDuration) * 1000) / 10;
-    remapped.push({ percentage: targetPct, properties: resizeProps });
-    remapped.sort((a, b) => a.percentage - b.percentage);
-
-    await commitMutation(
-      selection,
-      {
-        type: "replace-with-keyframes",
-        animationId: anim.id,
-        targetSelector: anim.targetSelector,
-        position: roundTo3(newStart),
-        duration: roundTo3(newDuration),
-        keyframes: remapped,
-      },
-      { label: `Resize (extended to ${ct.toFixed(2)}s)`, softReload: true, coalesceKey },
-    );
-    return true;
-  }
-
-  const SIZE_PROPS = new Set(["width", "height"]);
-  const backfillDefaults: Record<string, number> = {};
-  for (const k of Object.keys(runtimeProps)) {
-    if (SIZE_PROPS.has(k)) continue;
-    backfillDefaults[k] = IDENTITY_ONE_PROPS.has(k) ? 1 : 0;
-  }
-
-  await commitMutation(
-    selection,
-    {
-      type: "add-keyframe",
-      animationId: anim.id,
-      percentage: pct,
-      properties: resizeProps,
-      backfillDefaults,
-    },
-    { label: `Resize (keyframe ${pct}%)`, softReload: true, coalesceKey },
-  );
-  return true;
-}
-
-// ── Rotation intercept ────────────────────────────────────────────────────
-
 export async function tryGsapRotationIntercept(
   selection: DomEditSelection,
   angle: number,
@@ -517,7 +295,6 @@ export async function tryGsapRotationIntercept(
   // pointer sweep) or the inspector — so it IS the new rotation. No base re-add: the
   // gesture's live preview already gsap.set this value (single source of truth).
   const newRotation = Math.round(angle);
-
   // STATIC case (single source of truth = GSAP timeline): no rotation tween, so the
   // angle belongs in a `tl.set("#el",{rotation})`, not a keyframe conversion —
   // mirroring the static position set. Idempotent: re-rotate updates an existing
diff --git a/packages/studio/src/hooks/gsapRuntimeReaders.test.ts b/packages/studio/src/hooks/gsapRuntimeReaders.test.ts
new file mode 100644
index 0000000000..b65f59237e
--- /dev/null
+++ b/packages/studio/src/hooks/gsapRuntimeReaders.test.ts
@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import {
+  COLOR_GRADING_SOURCE_HIDDEN_ATTR,
+  HF_COLOR_GRADING_CANVAS_ID_PREFIX,
+} from "@hyperframes/core/color-grading";
+import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeReaders";
+
+/**
+ * Regression: converting a property-group tween to keyframes resolves "current
+ * values" via readAllAnimatedProperties. Two ways that used to bake garbage
+ * into the composition file:
+ *
+ * 1. The group filter only pruned the tween's OWN properties — the baseline
+ *    pass still captured every property ANY tween on the element touches, so
+ *    a rotation commit carried `opacity` from the intro from() tween.
+ * 2. `gsap.getProperty(el, "opacity")` on a color-grading source reads the
+ *    runtime hide (inline `opacity: 0 !important`), not the animated value —
+ *    so the captured opacity was the transient 0, which then animated 0 → 0
+ *    on the next full load and the element disappeared.
+ */
+
+function fakeIframe(
+  el: Element,
+  opts: { gsapValues: Record<string, number>; otherTweenVars?: Record<string, number> },
+): HTMLIFrameElement {
+  const children = opts.otherTweenVars
+    ? [{ targets: () => [el], vars: { duration: 0.8, ...opts.otherTweenVars } }]
+    : [];
+  return {
+    contentWindow: {
+      __timelines: { main: { getChildren: () => children } },
+      gsap: { getProperty: (_el: Element, prop: string) => opts.gsapValues[prop] ?? 0 },
+    },
+    contentDocument: document,
+  } as unknown as HTMLIFrameElement;
+}
+
+function rotationSetAnim(): GsapAnimation {
+  return {
+    id: "#clip-set-0-rotation",
+    targetSelector: "#clip",
+    method: "set",
+    properties: { rotation: 0 },
+  } as unknown as GsapAnimation;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("readAllAnimatedProperties group filter", () => {
+  it("keeps other tweens' out-of-group properties out of a grouped resolve", () => {
+    const el = document.createElement("div");
+    el.id = "clip";
+    document.body.appendChild(el);
+    const iframe = fakeIframe(el, {
+      gsapValues: { rotation: -28.1, opacity: 0, rotationX: 52, rotationY: -47 },
+      otherTweenVars: { opacity: 0, rotationX: 52, rotationY: -47 },
+    });
+
+    const result = readAllAnimatedProperties(iframe, "#clip", rotationSetAnim(), "rotation");
+
+    expect(result).toEqual({ rotation: -28.1 });
+  });
+});
+
+describe("color-grading opacity truth", () => {
+  function gradedElement(): HTMLElement {
+    const el = document.createElement("img");
+    el.id = "clip";
+    el.setAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR, "");
+    const canvas = document.createElement("canvas");
+    canvas.id = `${HF_COLOR_GRADING_CANVAS_ID_PREFIX}clip`;
+    canvas.style.opacity = "0.98";
+    document.body.append(el, canvas);
+    return el;
+  }
+
+  it("resolves opacity from the grading canvas, not the runtime hide", () => {
+    const el = gradedElement();
+    const iframe = fakeIframe(el, { gsapValues: { opacity: 0 } });
+    const anim = {
+      id: "#clip-from-200-visual",
+      targetSelector: "#clip",
+      method: "from",
+      properties: { opacity: 0.5 },
+    } as unknown as GsapAnimation;
+
+    const result = readAllAnimatedProperties(iframe, "#clip", anim);
+
+    expect(result.opacity).toBe(0.98);
+  });
+
+  it("readGsapProperty takes the same detour", () => {
+    const el = gradedElement();
+    const iframe = fakeIframe(el, { gsapValues: { opacity: 0 } });
+
+    expect(readGsapProperty(iframe, "#clip", "opacity")).toBe(0.98);
+  });
+
+  it("reads GSAP directly when the source is not grading-hidden", () => {
+    const el = document.createElement("div");
+    el.id = "clip";
+    document.body.appendChild(el);
+    const iframe = fakeIframe(el, { gsapValues: { opacity: 0.3 } });
+
+    expect(readGsapProperty(iframe, "#clip", "opacity")).toBe(0.3);
+  });
+});
diff --git a/packages/studio/src/hooks/gsapRuntimeReaders.ts b/packages/studio/src/hooks/gsapRuntimeReaders.ts
index 966a1b850d..3c78ec608b 100644
--- a/packages/studio/src/hooks/gsapRuntimeReaders.ts
+++ b/packages/studio/src/hooks/gsapRuntimeReaders.ts
@@ -3,9 +3,33 @@
  */
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { classifyPropertyGroup, type PropertyGroupName } from "@hyperframes/core/gsap-parser";
-import { getIframeGsap, queryIframeElement } from "./gsapShared";
+import {
+  COLOR_GRADING_SOURCE_HIDDEN_ATTR,
+  HF_COLOR_GRADING_CANVAS_ID_PREFIX,
+} from "@hyperframes/core/color-grading";
+import { getIframeGsap, queryIframeElement, type IframeGsap } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 
+/**
+ * The element's live value for `prop` as GSAP drives it. Opacity on a
+ * color-grading-hidden source needs a detour: the runtime hides the source
+ * with inline `opacity: 0 !important`, so computed opacity is the hide, not
+ * the animated value. The grading canvas mirrors the source's effective
+ * opacity every frame, so it is the truth for that one property — reading the
+ * raw 0 here is what bakes `opacity: 0` into committed keyframes.
+ */
+function readLiveGsapValue(gsap: IframeGsap, el: Element, prop: string): number {
+  if (prop === "opacity" && el.getAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR) != null && el.id) {
+    const canvas = el.ownerDocument.getElementById(HF_COLOR_GRADING_CANVAS_ID_PREFIX + el.id);
+    const win = el.ownerDocument.defaultView;
+    if (canvas && win) {
+      const val = Number(win.getComputedStyle(canvas).opacity);
+      if (Number.isFinite(val)) return val;
+    }
+  }
+  return Number(gsap.getProperty(el, prop));
+}
+
 export function readGsapProperty(
   iframe: HTMLIFrameElement | null,
   selector: string | null,
@@ -17,7 +41,7 @@ export function readGsapProperty(
   const el = queryIframeElement(iframe, selector);
   if (!el) return null;
   try {
-    const val = Number(gsap.getProperty(el, prop));
+    const val = readLiveGsapValue(gsap, el, prop);
     if (!Number.isFinite(val)) return null;
     return POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
   } catch {
@@ -77,15 +101,17 @@ export function readAllAnimatedProperties(
     for (const p of Object.keys(anim.properties)) propKeys.add(p);
   }
 
-  // When a group filter is specified, only keep properties belonging to that group.
-  if (group) {
-    for (const p of propKeys) {
-      if (classifyPropertyGroup(p) !== group) propKeys.delete(p);
-    }
+  // When a group filter is specified, only properties belonging to that group
+  // may enter the result — including the baseline passes below. The whole
+  // point of property-group tweens is that a rotation commit never carries
+  // opacity/rotationX/etc. captured from unrelated tweens on the element.
+  const inGroup = (p: string) => !group || classifyPropertyGroup(p) === group;
+  for (const p of propKeys) {
+    if (!inGroup(p)) propKeys.delete(p);
   }
 
   for (const prop of propKeys) {
-    const val = Number(gsap.getProperty(el, prop));
+    const val = readLiveGsapValue(gsap, el, prop);
     if (Number.isFinite(val)) {
       result[prop] = POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
     }
@@ -110,7 +136,7 @@ export function readAllAnimatedProperties(
           const vars = child.vars;
           if (!vars) continue;
           for (const k of Object.keys(vars)) {
-            if (!GSAP_CONFIG_KEYS.has(k)) otherTweenProps.add(k);
+            if (!GSAP_CONFIG_KEYS.has(k) && inGroup(k)) otherTweenProps.add(k);
           }
         }
       }
@@ -152,7 +178,7 @@ export function readAllAnimatedProperties(
   for (const [prop, defaultVal] of Object.entries(UNIVERSAL_BASELINE)) {
     if (prop in result) continue;
     if (!allTweenedProps.has(prop)) continue;
-    const val = Number(gsap.getProperty(el, prop));
+    const val = readLiveGsapValue(gsap, el, prop);
     if (Number.isFinite(val) && Math.round(val * 1000) !== Math.round(defaultVal * 1000)) {
       result[prop] = roundTo3(val);
     }
@@ -184,6 +210,7 @@ export function readAllAnimatedProperties(
   } catch {}
   for (const prop of COMPUTED_BASELINE) {
     if (prop in result) continue;
+    if (!inGroup(prop)) continue;
     if (otherTweenProps.has(prop)) continue;
     const gsapVal = Number(gsap.getProperty(el, prop));
     if (!Number.isFinite(gsapVal)) continue;
diff --git a/packages/studio/src/hooks/useGsapAwareEditing.ts b/packages/studio/src/hooks/useGsapAwareEditing.ts
index f695595a57..9e22897a1d 100644
--- a/packages/studio/src/hooks/useGsapAwareEditing.ts
+++ b/packages/studio/src/hooks/useGsapAwareEditing.ts
@@ -10,11 +10,8 @@
 import { useCallback } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import {
-  tryGsapDragIntercept,
-  tryGsapResizeIntercept,
-  tryGsapRotationIntercept,
-} from "./gsapRuntimeBridge";
+import { tryGsapDragIntercept, tryGsapRotationIntercept } from "./gsapRuntimeBridge";
+import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
 import {
   useGsapSaveFailureTelemetry,

From fc82ec22f53dd8bdfdd6db31591ce2d89bca5267 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 04:07:57 -0400
Subject: [PATCH 06/24] fix(studio): crop tool stands down for clips it cannot
 edit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The always-on crop lifted EVERY selected element's clip-path and restored
only what it could parse as a px inset — selecting an element with a
circle/polygon/percentage clip visually un-clipped it, and deselecting
deleted the authored clip outright.

readElementCropInsets is now tri-state (zeros = no clip, null = a clip
the tool can't represent): uneditable clips get no lift and no handles,
and the lift restores the pre-lift inline value verbatim unless a crop
gesture actually committed.
---
 .../components/editor/DomEditCropHandles.tsx  | 65 ++++++++++---------
 .../editor/domEditOverlayCrop.test.ts         | 47 ++++++++++++++
 .../components/editor/domEditOverlayCrop.ts   | 22 +++++--
 3 files changed, 98 insertions(+), 36 deletions(-)

diff --git a/packages/studio/src/components/editor/DomEditCropHandles.tsx b/packages/studio/src/components/editor/DomEditCropHandles.tsx
index 9f83a90ba7..746c774f94 100644
--- a/packages/studio/src/components/editor/DomEditCropHandles.tsx
+++ b/packages/studio/src/components/editor/DomEditCropHandles.tsx
@@ -77,36 +77,23 @@ export function DomEditCropHandles({
 }: DomEditCropHandlesProps) {
   const gestureRef = useRef<CropGestureState | null>(null);
   const [dragging, setDragging] = useState(false);
-  const [state, setState] = useState(() => {
-    const parsed = readElementCropInsets(selection.element);
-    return {
-      element: selection.element,
-      insets: {
-        top: parsed.top,
-        right: parsed.right,
-        bottom: parsed.bottom,
-        left: parsed.left,
-      } as ClipPathInsetSides,
-      radius: parsed.radius,
-    };
-  });
+  // readElementCropInsets returns null for a clip this tool can't represent
+  // (circle/polygon/non-px inset): the crop UI must fully stand down for that
+  // element — no lift, no handles — or select+deselect replaces the authored
+  // clip with an inset (or deletes it).
+  const cropStateFor = (element: HTMLElement) => {
+    const parsed = readElementCropInsets(element);
+    const { radius, ...insets } = parsed ?? { top: 0, right: 0, bottom: 0, left: 0, radius: 0 };
+    return { element, croppable: parsed !== null, insets: insets as ClipPathInsetSides, radius };
+  };
+  const [state, setState] = useState(() => cropStateFor(selection.element));
 
   // Re-sync when the selection targets a different element (reselect, or an
   // undo/redo that re-keys the node): read its committed crop before the lift
   // effect runs. Read inside the guard so a drag's per-frame setState doesn't
   // re-run getComputedStyle every frame.
   if (state.element !== selection.element) {
-    const liveInsets = readElementCropInsets(selection.element);
-    setState({
-      element: selection.element,
-      insets: {
-        top: liveInsets.top,
-        right: liveInsets.right,
-        bottom: liveInsets.bottom,
-        left: liveInsets.left,
-      },
-      radius: liveInsets.radius,
-    });
+    setState(cropStateFor(selection.element));
   }
 
   const hasCrop =
@@ -120,17 +107,28 @@ export function DomEditCropHandles({
   committedRef.current = hasCrop ? buildInsetClipPathSides(state.insets, state.radius) : null;
 
   // Lift the clip while the element is selected so the full content shows and the
-  // cropped-away area can be dimmed; restore the committed crop on deselect. Keyed
-  // on the element so switching selections restores the previous one. Runs after
-  // render, so the state re-sync above still reads the element's real committed clip.
+  // cropped-away area can be dimmed; restore on deselect. Keyed on the element so
+  // switching selections restores the previous one. Runs after render, so the
+  // state re-sync above still reads the element's real committed clip. Restore
+  // prefers the pre-lift inline value VERBATIM — the rebuilt inset only replaces
+  // it after a crop gesture actually commits, so a mere select+deselect can
+  // never reformat (or drop) what the author wrote.
   const liftedRef = useRef(false);
+  const preLiftInlineClipRef = useRef("");
+  const cropCommittedRef = useRef(false);
   useEffect(() => {
     const el = selection.element;
+    if (readElementCropInsets(el) === null) return;
+    preLiftInlineClipRef.current = el.style.getPropertyValue("clip-path");
+    cropCommittedRef.current = false;
     el.style.setProperty("clip-path", "none");
     liftedRef.current = true;
     return () => {
       liftedRef.current = false;
-      if (committedRef.current) el.style.setProperty("clip-path", committedRef.current);
+      const restore = cropCommittedRef.current
+        ? committedRef.current
+        : preLiftInlineClipRef.current || null;
+      if (restore) el.style.setProperty("clip-path", restore);
       else el.style.removeProperty("clip-path");
     };
   }, [selection.element]);
@@ -198,7 +196,12 @@ export function DomEditCropHandles({
     };
     void Promise.resolve(
       onStyleCommit?.("clip-path", buildInsetClipPathSides(state.insets, state.radius)),
-    ).then(reLift, reLift);
+    ).then(() => {
+      // Only a landed commit makes the rebuilt inset the restore value; a
+      // failed one keeps restoring the pre-lift clip.
+      cropCommittedRef.current = true;
+      reLift();
+    }, reLift);
   };
 
   const cancelCropGesture = (event: ReactPointerEvent<HTMLElement>) => {
@@ -212,6 +215,10 @@ export function DomEditCropHandles({
     setState((prev) => ({ ...prev, insets: gesture.startInsets }));
   };
 
+  // Uneditable clip (circle/polygon/non-px inset): the element renders exactly
+  // as authored and the crop tool shows nothing. All hooks above stay mounted.
+  if (!state.croppable) return null;
+
   return (
     <>
       {/* Dim the cropped-away area whenever the element is cropped and selected,
diff --git a/packages/studio/src/components/editor/domEditOverlayCrop.test.ts b/packages/studio/src/components/editor/domEditOverlayCrop.test.ts
index 2dd54f3579..a23abc0e74 100644
--- a/packages/studio/src/components/editor/domEditOverlayCrop.test.ts
+++ b/packages/studio/src/components/editor/domEditOverlayCrop.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import {
   cropRectFromInsets,
+  hugRectForElement,
+  readElementCropInsets,
   resolveCropInsetFromEdgeDrag,
   resolveCropInsetFromMoveDrag,
 } from "./domEditOverlayCrop";
@@ -104,3 +106,48 @@ describe("cropRectFromInsets", () => {
     expect(r.height).toBe(0);
   });
 });
+
+describe("readElementCropInsets tri-state", () => {
+  // Regression: a clip-path the crop tool can't represent (circle/polygon/
+  // non-px inset) used to parse to ZEROS — indistinguishable from "no crop" —
+  // so selecting lifted the clip and deselecting removed/replaced it: the
+  // authored circle clip was silently destroyed by a mere select+deselect.
+  const fakeEl = (inlineClip: string) =>
+    ({
+      style: { getPropertyValue: (p: string) => (p === "clip-path" ? inlineClip : "") },
+      ownerDocument: { defaultView: { getComputedStyle: () => ({ clipPath: "none" }) } },
+    }) as unknown as HTMLElement;
+
+  it("zeros for no clip", () => {
+    expect(readElementCropInsets(fakeEl(""))).toEqual({
+      top: 0,
+      right: 0,
+      bottom: 0,
+      left: 0,
+      radius: 0,
+    });
+  });
+
+  it("parses a px inset", () => {
+    expect(readElementCropInsets(fakeEl("inset(16px round 12px)"))).toEqual({
+      top: 16,
+      right: 16,
+      bottom: 16,
+      left: 16,
+      radius: 12,
+    });
+  });
+
+  it("null for a circle clip (uneditable, must not be lifted)", () => {
+    expect(readElementCropInsets(fakeEl("circle(50% at 50% 50%)"))).toBeNull();
+  });
+
+  it("null for a non-px inset (uneditable, must not be lifted)", () => {
+    expect(readElementCropInsets(fakeEl("inset(10%)"))).toBeNull();
+  });
+
+  it("hugRectForElement passes the rect through for uneditable clips", () => {
+    const rect = { left: 1, top: 2, width: 30, height: 40, editScaleX: 1, editScaleY: 1 };
+    expect(hugRectForElement(rect, fakeEl("circle(50%)"))).toEqual(rect);
+  });
+});
diff --git a/packages/studio/src/components/editor/domEditOverlayCrop.ts b/packages/studio/src/components/editor/domEditOverlayCrop.ts
index 7eba37ec45..4f0e7dd7fc 100644
--- a/packages/studio/src/components/editor/domEditOverlayCrop.ts
+++ b/packages/studio/src/components/editor/domEditOverlayCrop.ts
@@ -28,15 +28,21 @@ export function cropRectFromInsets(
   };
 }
 
-/** Current inset crop of an element (inline first, computed fallback), or zeros. */
-export function readElementCropInsets(element: HTMLElement): ClipPathInsetSides & {
-  radius: number;
-} {
+/**
+ * Current inset crop of an element (inline first, computed fallback).
+ * Zeros = no clip (croppable, nothing cropped yet). `null` = the element
+ * carries a clip-path this tool cannot represent (circle/polygon/non-px
+ * inset) — croppers must not lift, edit, or restore it, or the clip gets
+ * silently replaced or destroyed on deselect.
+ */
+export function readElementCropInsets(
+  element: HTMLElement,
+): (ClipPathInsetSides & { radius: number }) | null {
   const inline = element.style.getPropertyValue("clip-path").trim();
   const value =
     inline || element.ownerDocument.defaultView?.getComputedStyle(element).clipPath.trim() || "";
-  const parsed = parseInsetClipPathSides(value === "none" ? "" : value);
-  return parsed ?? { top: 0, right: 0, bottom: 0, left: 0, radius: 0 };
+  if (!value || value === "none") return { top: 0, right: 0, bottom: 0, left: 0, radius: 0 };
+  return parseInsetClipPathSides(value);
 }
 
 export interface CropInsetDragInput {
@@ -111,6 +117,8 @@ export function hugRectForElement(
   element: HTMLElement,
 ): CropScreenRect {
   const insets = readElementCropInsets(element);
-  if (insets.top <= 0 && insets.right <= 0 && insets.bottom <= 0 && insets.left <= 0) return rect;
+  // Uneditable clip (null) can't be hugged — show the full element rect.
+  if (!insets || (insets.top <= 0 && insets.right <= 0 && insets.bottom <= 0 && insets.left <= 0))
+    return rect;
   return cropRectFromInsets(rect, insets, rect.editScaleX, rect.editScaleY);
 }

From 945d18d2c015c8e8c4237e26320b7875c99ec5f5 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 04:08:00 -0400
Subject: [PATCH 07/24] fix(studio): route panel property commits to a
 group-owning set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

commitStaticSet merged every property into the FIRST set found for the
selector: a panel W edit on an element whose only set was positional
produced tl.set("#el",{x,y,width}) — a mixed-group set the split
machinery exists to prevent — labeled "Set 3D transform" in undo.

Commits now batch per property group into a set that owns that group
(exact group match, then a mixed set already carrying the group, then a
fresh off-timeline gsap.set), with undo labels derived from the group
(Move layer / Resize layer / Rotate layer / Set 3D transform).
---
 .../hooks/useAnimatedPropertyCommit.test.tsx  | 71 ++++++++++++++--
 .../src/hooks/useAnimatedPropertyCommit.ts    | 81 +++++++++++++++----
 2 files changed, 130 insertions(+), 22 deletions(-)

diff --git a/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx b/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx
index 038e03d219..f5eeed3d35 100644
--- a/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx
+++ b/packages/studio/src/hooks/useAnimatedPropertyCommit.test.tsx
@@ -39,15 +39,16 @@ type Commit = (
 ) => Promise<void>;
 
 /** Renders the hook and hands its commit function to the caller via a ref callback. */
-function renderCommitHook(
-  mutations: Array<Record<string, unknown>>,
+function renderHookWith(
+  animations: GsapAnimation[],
+  onMutation: (mutation: Record<string, unknown>, label: string) => void,
   onReady: (commit: Commit) => void,
 ) {
   function Harness() {
     const { commitAnimatedProperties } = useAnimatedPropertyCommit({
-      selectedGsapAnimations: [keyframedAnim],
-      gsapCommitMutation: async (_sel, mutation) => {
-        mutations.push(mutation);
+      selectedGsapAnimations: animations,
+      gsapCommitMutation: async (_sel, mutation, options) => {
+        onMutation(mutation, options.label);
       },
       addGsapAnimation: vi.fn(),
       convertToKeyframes: vi.fn(),
@@ -66,6 +67,13 @@ function renderCommitHook(
   return root;
 }
 
+function renderCommitHook(
+  mutations: Array<Record<string, unknown>>,
+  onReady: (commit: Commit) => void,
+) {
+  return renderHookWith([keyframedAnim], (mutation) => mutations.push(mutation), onReady);
+}
+
 // Regression (#1808): a "3D transform" / design-panel property edit on an
 // element that already has a keyframed tween is the ACTUAL path a manual
 // canvas nudge exercises (not the raw drag intercept) — with auto-keyframe
@@ -103,3 +111,56 @@ describe("useAnimatedPropertyCommit — autoKeyframeEnabled toggle (#1808)", ()
     act(() => root.unmount());
   });
 });
+
+// Regression: commitStaticSet picked the FIRST `set` for the selector with no
+// group check — a panel W edit on a static element merged `width` into the
+// POSITION set (`tl.set("#el",{x,y,width})`), a mixed-group set the split
+// machinery exists to prevent, labeled "Set 3D transform" in undo history.
+describe("commitStaticSet group routing", () => {
+  const positionSet = {
+    id: "#box-set-0-position",
+    targetSelector: "#box",
+    propertyGroup: "position",
+    method: "set",
+    properties: { x: 10, y: 20 },
+  } as unknown as GsapAnimation;
+
+  function renderStaticHook(
+    committed: Array<{ mutation: Record<string, unknown>; label: string }>,
+    onReady: (commit: Commit) => void,
+  ) {
+    return renderHookWith(
+      [positionSet],
+      (mutation, label) => committed.push({ mutation, label }),
+      onReady,
+    );
+  }
+
+  it("width edit creates a size set instead of contaminating the position set", async () => {
+    const committed: Array<{ mutation: Record<string, unknown>; label: string }> = [];
+    let commit!: Commit;
+    renderStaticHook(committed, (c) => (commit = c));
+    await act(async () => {
+      await commit(selection, { width: 500 });
+    });
+    const updates = committed.filter((c) => c.mutation.type === "update-properties");
+    expect(updates).toHaveLength(0);
+    const adds = committed.filter((c) => c.mutation.type === "add");
+    expect(adds).toHaveLength(1);
+    expect(adds[0]!.mutation.properties).toEqual({ width: 500 });
+    expect(adds[0]!.label).toBe("Resize layer");
+  });
+
+  it("x edit updates the position set with a Move label", async () => {
+    const committed: Array<{ mutation: Record<string, unknown>; label: string }> = [];
+    let commit!: Commit;
+    renderStaticHook(committed, (c) => (commit = c));
+    await act(async () => {
+      await commit(selection, { x: 400 });
+    });
+    const update = committed.find((c) => c.mutation.type === "update-properties");
+    expect(update).toBeDefined();
+    expect(update!.mutation.animationId).toBe("#box-set-0-position");
+    expect(update!.label).toBe("Move layer");
+  });
+});
diff --git a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
index a6ea2e308c..9e5914f100 100644
--- a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
+++ b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
@@ -103,6 +103,22 @@ async function maybeAutoKeyframeSet(
 
 type Commit = NonNullable<CommitAnimatedPropertyDeps["gsapCommitMutation"]>;
 
+/** Undo-history label for a static-set commit, from the group it writes. */
+const STATIC_SET_LABELS: Partial<Record<ReturnType<typeof classifyPropertyGroup>, string>> = {
+  position: "Move layer",
+  scale: "Resize layer",
+  size: "Resize layer",
+  rotation: "Rotate layer",
+  visual: "Set opacity",
+  other: "Set 3D transform",
+};
+
+function staticSetLabel(propEntries: [string, number | string][]): string {
+  const groups = new Set(propEntries.map(([k]) => classifyPropertyGroup(k)));
+  const only = groups.size === 1 ? [...groups][0] : undefined;
+  return (only && STATIC_SET_LABELS[only]) || "Set properties";
+}
+
 /** Merge ALL props into the static `set` in ONE commit (value-only, instant), then
  *  auto-keyframe. One mutation — a per-property loop would shift the set's
  *  group-derived id mid-way (e.g. reset adding `scale` to a rotation set), 404-ing
@@ -133,7 +149,11 @@ async function commitSetProps(
   await commit(
     selection,
     { type: "update-properties", animationId: setAnim.id, properties },
-    { label: "Set 3D transform", softReload: true, ...(instantPatch ? { instantPatch } : {}) },
+    {
+      label: staticSetLabel(propEntries),
+      softReload: true,
+      ...(instantPatch ? { instantPatch } : {}),
+    },
   );
   await maybeAutoKeyframeSet(selection, setAnim, animations, commit);
 }
@@ -152,22 +172,49 @@ async function commitStaticSet(
   commit: Commit,
 ): Promise<void> {
   if (!selector) return;
-  // Update an existing `set` in ONE batched commit — NEVER a flat `to`/`from`. A
-  // set's id is GROUP-derived, so a per-prop loop shifts it the instant a new-group
-  // prop lands (e.g. `scale` onto a rotation set), 404-ing the next prop; commitSetProps
-  // sends them together. A static element with no set gets a dedicated `set` carrying
-  // ALL props in ONE `add`.
-  const existingSet = animations.find((a) => a.method === "set" && a.targetSelector === selector);
-  if (existingSet) {
-    await commitSetProps(selection, existingSet, propEntries, selector, animations, commit);
-    return;
+  // One commit per PROPERTY GROUP, each into a set that owns that group — never a
+  // flat `to`/`from`, and never a foreign-group set (a width edit used to merge
+  // into the element's position set, producing a mixed set the split machinery
+  // exists to prevent). Within a group everything batches into ONE commit: a
+  // set's id is group-derived, so a per-prop loop would shift the id mid-way and
+  // 404 the next update.
+  const byGroup = new Map<string, [string, number | string][]>();
+  for (const entry of propEntries) {
+    const group = classifyPropertyGroup(entry[0]);
+    const batch = byGroup.get(group) ?? [];
+    batch.push(entry);
+    byGroup.set(group, batch);
+  }
+  const sets = animations.filter((a) => a.method === "set" && a.targetSelector === selector);
+  for (const [group, batch] of byGroup) {
+    const existingSet =
+      // A set already dedicated to this group wins; else a mixed set that
+      // already carries a property of this group (merging same-group values
+      // there beats spawning a second writer for the same channel).
+      sets.find((a) => a.propertyGroup === group) ??
+      sets.find((a) => Object.keys(a.properties).some((k) => classifyPropertyGroup(k) === group));
+    if (existingSet) {
+      await commitSetProps(selection, existingSet, batch, selector, animations, commit);
+    } else {
+      await addGlobalStaticSet(selection, batch, selector, commit);
+    }
   }
-  // Base `gsap.set` (off-timeline) — a static hold with no 0% keyframe marker, so
-  // adjusting a 3D transform on a non-keyframed element doesn't drop a keyframe on
-  // the timeline (matches the manual-drag UX). The global-set instant patch applies
-  // it straight to the element so the first edit shows with no soft-reload flash.
+}
+
+/**
+ * Base `gsap.set` (off-timeline) — a static hold with no 0% keyframe marker, so
+ * adjusting a 3D transform on a non-keyframed element doesn't drop a keyframe on
+ * the timeline (matches the manual-drag UX). The global-set instant patch applies
+ * it straight to the element so the first edit shows with no soft-reload flash.
+ */
+async function addGlobalStaticSet(
+  selection: DomEditSelection,
+  batch: [string, number | string][],
+  selector: string,
+  commit: Commit,
+): Promise<void> {
   const numericProps: SetPatchProps = {};
-  for (const [k, v] of propEntries) {
+  for (const [k, v] of batch) {
     if (typeof v === "number") numericProps[k as keyof SetPatchProps] = v;
   }
   await commit(
@@ -177,11 +224,11 @@ async function commitStaticSet(
       targetSelector: selector,
       method: "set",
       position: 0,
-      properties: Object.fromEntries(propEntries),
+      properties: Object.fromEntries(batch),
       global: true,
     },
     {
-      label: "Set 3D transform",
+      label: staticSetLabel(batch),
       softReload: true,
       ...(Object.keys(numericProps).length > 0
         ? {

From 0c81cacca09fdaa26d9023fa1a947619423d1e22 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 04:08:04 -0400
Subject: [PATCH 08/24] fix(parsers): never emit duplicate vars keys in either
 writer

A parsed timeline set carries immediateRender in extras; the recast
statement builder ALSO pushed the flag unconditionally, so every
split/re-add of a set wrote 'immediateRender: true, immediateRender:
true' into the file, doubling on each pass. Both writer twins (recast +
acorn) now emit each vars key exactly once, properties winning over
extras, and reconcileEditableProps skips newProps keys it already
preserved.
---
 packages/parsers/src/gsapParser.test.ts       | 21 ++++++++++++++
 packages/parsers/src/gsapParser.ts            | 16 ++++++++--
 .../src/gsapWriterAcorn.inline.test.ts        | 29 +++++++++++++++++++
 packages/parsers/src/gsapWriterAcorn.ts       | 14 +++++++--
 4 files changed, 75 insertions(+), 5 deletions(-)

diff --git a/packages/parsers/src/gsapParser.test.ts b/packages/parsers/src/gsapParser.test.ts
index 413fc53995..11b592f9ae 100644
--- a/packages/parsers/src/gsapParser.test.ts
+++ b/packages/parsers/src/gsapParser.test.ts
@@ -3026,3 +3026,24 @@ describe("single position write per element (consolidation)", () => {
     expect(parseGsapScript(out).animations.some((a) => "opacity" in a.properties)).toBe(true);
   });
 });
+
+describe("recast writer never doubles vars keys", () => {
+  // Regression: buildTweenStatementCode pushed `immediateRender: true` for
+  // every timeline set AND appended extras — a parsed set carries the flag in
+  // extras, so splitting a mixed set emitted
+  // `immediateRender: true, immediateRender: true` into the file.
+  const src = `window.__timelines = window.__timelines || {};
+const tl = gsap.timeline({ paused: true });
+tl.set("#a", { z: 0, rotationX: 5, immediateRender: true, scale: 1 }, 0);
+window.__timelines["main"] = tl;`;
+
+  it("split of a mixed set emits the flag once per group", () => {
+    const id = parseGsapScript(src).animations[0]!.id;
+    const { script: out } = splitIntoPropertyGroups(src, id);
+    const setLines = out.split("\n").filter((l) => l.includes("tl.set("));
+    expect(setLines.length).toBeGreaterThan(1);
+    for (const line of setLines) {
+      expect(line.match(/immediateRender/g) ?? []).toHaveLength(1);
+    }
+  });
+});
diff --git a/packages/parsers/src/gsapParser.ts b/packages/parsers/src/gsapParser.ts
index 4272ec0608..315c238c8f 100644
--- a/packages/parsers/src/gsapParser.ts
+++ b/packages/parsers/src/gsapParser.ts
@@ -1387,13 +1387,25 @@ function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation,
   if (anim.method !== "set" && anim.duration !== undefined) props.duration = anim.duration;
   if (anim.ease) props.ease = anim.ease;
   const entries = Object.entries(props).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
+  const emitted = new Set(Object.keys(props));
   // immediateRender forces GSAP to apply the set when added to the timeline,
   // not on the first seek — without it, tl.set at position 0 on a paused
   // timeline is invisible until the playhead moves past 0. A base `gsap.set`
-  // already runs immediately, so it doesn't need (or get) the flag.
-  if (anim.method === "set" && !anim.global) entries.push("immediateRender: true");
+  // already runs immediately, so it doesn't need (or get) the flag. A parsed
+  // set carries the flag in extras — never emit the same key twice.
+  if (
+    anim.method === "set" &&
+    !anim.global &&
+    !emitted.has("immediateRender") &&
+    !(anim.extras && "immediateRender" in anim.extras)
+  ) {
+    entries.push("immediateRender: true");
+    emitted.add("immediateRender");
+  }
   if (anim.extras) {
     for (const [k, v] of Object.entries(anim.extras)) {
+      if (emitted.has(k)) continue;
+      emitted.add(k);
       entries.push(`${safeKey(k)}: ${valueToCode(v as number | string)}`);
     }
   }
diff --git a/packages/parsers/src/gsapWriterAcorn.inline.test.ts b/packages/parsers/src/gsapWriterAcorn.inline.test.ts
index 4eaa4ca22a..30b1652426 100644
--- a/packages/parsers/src/gsapWriterAcorn.inline.test.ts
+++ b/packages/parsers/src/gsapWriterAcorn.inline.test.ts
@@ -101,3 +101,32 @@ window.__timelines["scene"] = gsap.timeline({ paused: true });`;
     expect(parseGsapScriptAcorn(out).animations).toHaveLength(2);
   });
 });
+
+describe("no duplicate vars keys on rewrite", () => {
+  const setSrc = `window.__timelines = window.__timelines || {};
+const tl = gsap.timeline({ paused: true });
+tl.set("#a", { z: 0, rotationX: 5, immediateRender: true }, 0);
+window.__timelines["main"] = tl;`;
+
+  it("update with immediateRender riding in newProps emits the key once", () => {
+    const id = parseGsapScriptAcorn(setSrc).animations[0]!.id;
+    // Studio paths that build props off live tween vars carry the flag along.
+    const out = updateAnimationInScript(setSrc, id, {
+      properties: { z: 0, rotationX: 9, immediateRender: "__raw:true" },
+    });
+    expect(out).toContain("rotationX: 9");
+    expect(out.match(/immediateRender/g)).toHaveLength(1);
+  });
+
+  it("addAnimationToScript dedupes a key present in both properties and extras", () => {
+    const { script: out } = addAnimationToScript(setSrc, {
+      targetSelector: "#b",
+      method: "set",
+      position: 0,
+      properties: { scale: 1, immediateRender: "__raw:true" },
+      extras: { immediateRender: "__raw:true" },
+    });
+    const setB = out.split("\n").find((l) => l.includes('"#b"'));
+    expect(setB?.match(/immediateRender/g)).toHaveLength(1);
+  });
+});
diff --git a/packages/parsers/src/gsapWriterAcorn.ts b/packages/parsers/src/gsapWriterAcorn.ts
index 29eabebef4..a0381e3241 100644
--- a/packages/parsers/src/gsapWriterAcorn.ts
+++ b/packages/parsers/src/gsapWriterAcorn.ts
@@ -59,7 +59,9 @@ function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation,
   const entries = Object.entries(props).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
   if (anim.extras) {
     for (const [k, v] of Object.entries(anim.extras)) {
-      entries.push(`${safeKey(k)}: ${valueToCode(v)}`);
+      // A key carried by both properties and extras (a set's parsed
+      // `immediateRender: true`) must emit once — properties win.
+      if (!(k in props)) entries.push(`${safeKey(k)}: ${valueToCode(v)}`);
     }
   }
   const objCode = `{ ${entries.join(", ")} }`;
@@ -263,10 +265,16 @@ function reconcileEditableProps(
   const overrides = nonEditableOverrides ?? {};
   const { entries, keys } = preservedEntries(objNode, source, isEditableVarKey, overrides);
   for (const [key, value] of Object.entries(overrides)) {
-    if (!keys.has(key)) entries.push(`${safeKey(key)}: ${valueToCode(value)}`);
+    if (!keys.has(key)) {
+      keys.add(key);
+      entries.push(`${safeKey(key)}: ${valueToCode(value)}`);
+    }
   }
   for (const [key, value] of Object.entries(newProps)) {
-    entries.push(`${safeKey(key)}: ${valueToCode(value)}`);
+    // A non-editable key riding along in newProps (immediateRender read off
+    // live tween vars) is already preserved above — emitting it again writes
+    // `immediateRender: true, immediateRender: true` into the file.
+    if (!keys.has(key)) entries.push(`${safeKey(key)}: ${valueToCode(value)}`);
   }
   ms.overwrite(objNode.start, objNode.end, `{ ${entries.join(", ")} }`);
 }

From 1a8d4ea2f0e09fc470b5ff7ec8e70710c326d9d4 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 04:08:07 -0400
Subject: [PATCH 09/24] fix(lint): anchor the opacity-zero probe so 0.98 stops
 matching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

gsap_from_opacity_noop matched 'opacity: 0' as a prefix — an authored
'opacity: 0.98' triggered the rule. One boundary-anchored predicate now
owns the exactly-zero test for both block and inline declarations,
including a block's last declaration without a trailing semicolon.

domEditingDom now imports the grading contract attribute from core
instead of re-declaring the literal.
---
 packages/lint/src/rules/gsap.test.ts          | 57 +++++++++++++++++++
 packages/lint/src/rules/gsap.ts               | 11 +++-
 .../src/components/editor/domEditingDom.ts    |  2 +-
 3 files changed, 67 insertions(+), 3 deletions(-)

diff --git a/packages/lint/src/rules/gsap.test.ts b/packages/lint/src/rules/gsap.test.ts
index 2715ff5a9c..cfefe769c3 100644
--- a/packages/lint/src/rules/gsap.test.ts
+++ b/packages/lint/src/rules/gsap.test.ts
@@ -1194,6 +1194,63 @@ describe("GSAP rules", () => {
     expect(finding).toBeDefined();
   });
 
+  it("errors when a style block's LAST declaration is opacity:0 without a semicolon", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="hero">Hello</div>
+  </div>
+  <style>
+    #hero { font-size: 200px; opacity: 0 }
+  </style>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#hero", { opacity: 0, duration: 0.25 }, 0.1);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeDefined();
+  });
+
+  it("does NOT error for inline opacity: 0.98 + gsap.from({opacity:0}) — fractional is not zero", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <img id="image-clip" style="opacity: 0.98; filter: blur(23px);" src="x.png">
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#image-clip", { opacity: 0, duration: 0.8 }, 0.2);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeUndefined();
+  });
+
+  it("still errors for inline opacity: 0 without a trailing semicolon", async () => {
+    const html = `
+<html><body>
+  <div data-composition-id="c1" data-width="1920" data-height="1080">
+    <div id="title" style="font-size: 120px; opacity: 0">Hello</div>
+  </div>
+  <script>
+    window.__timelines = window.__timelines || {};
+    const tl = gsap.timeline({ paused: true });
+    tl.from("#title", { opacity: 0, duration: 0.5 }, 0.2);
+    window.__timelines["c1"] = tl;
+  </script>
+</body></html>`;
+    const result = await lintHyperframeHtml(html);
+    const finding = result.findings.find((f) => f.code === "gsap_from_opacity_noop");
+    expect(finding).toBeDefined();
+  });
+
   it("does NOT error when gsap.from({opacity:0}) and CSS has no opacity:0", async () => {
     const html = `
 <html><body>
diff --git a/packages/lint/src/rules/gsap.ts b/packages/lint/src/rules/gsap.ts
index b54b7c8732..ec2e4c9b8a 100644
--- a/packages/lint/src/rules/gsap.ts
+++ b/packages/lint/src/rules/gsap.ts
@@ -1128,11 +1128,18 @@ export const gsapRules: LintRule<LintContext>[] = [
     const findings: HyperframeLintFinding[] = [];
     const cssOpacityZeroSelectors = new Set<string>();
 
+    // Single owner of "this declaration list sets opacity to EXACTLY zero" —
+    // boundary-anchored so `opacity: 0.98` never matches. Works for both a CSS
+    // block body (brace already stripped by the block regex) and an inline
+    // style attribute: the declaration ends at `;` or at end of input, which
+    // also catches a final declaration without a trailing semicolon.
+    const opacityExactlyZero = /opacity\s*:\s*0(?:\.0+)?\s*(?:;|$)/;
+
     for (const style of styles) {
       for (const [, selector, body] of style.content.matchAll(
         /([#.][a-zA-Z0-9_-]+)\s*\{([^}]+)\}/g,
       )) {
-        if (body && /opacity\s*:\s*0\s*[;}]/.test(body)) {
+        if (body && opacityExactlyZero.test(body)) {
           cssOpacityZeroSelectors.add((selector ?? "").trim());
         }
       }
@@ -1140,7 +1147,7 @@ export const gsapRules: LintRule<LintContext>[] = [
 
     for (const tag of tags) {
       const inlineStyle = readAttr(tag.raw, "style");
-      if (!inlineStyle || !/opacity\s*:\s*0/.test(inlineStyle)) continue;
+      if (!inlineStyle || !opacityExactlyZero.test(inlineStyle)) continue;
       const id = readAttr(tag.raw, "id");
       const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
       if (id) cssOpacityZeroSelectors.add(`#${id}`);
diff --git a/packages/studio/src/components/editor/domEditingDom.ts b/packages/studio/src/components/editor/domEditingDom.ts
index cfd3474458..82b5649789 100644
--- a/packages/studio/src/components/editor/domEditingDom.ts
+++ b/packages/studio/src/components/editor/domEditingDom.ts
@@ -28,7 +28,7 @@ export function isTextBearingTag(tagName: string): boolean {
   return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);
 }
 
-const COLOR_GRADING_SOURCE_HIDDEN_ATTR = "data-hf-color-grading-source-hidden";
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
 
 export function isElementVisibleThroughAncestors(el: HTMLElement): boolean {
   const win = el.ownerDocument.defaultView;

From e99caa89376ef96e6be8cd2822cd6d34b8711ec2 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 14:58:17 -0400
Subject: [PATCH 10/24] fix(studio): crop restore value is owned by the lifted
 element's gesture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The deselect restore read a ref recomputed from RENDER state — on a direct
A→B selection switch, state re-syncs to B before A's effect cleanup runs,
so after a committed crop gesture A was restored with B's crop string (or
lost its crop when B had none). The committed value is now written at
gesture-commit time (tri-state: none committed / crop removal / the exact
committed string), so cleanup never touches render state. Adds component
tests for lift/restore ordering, including the direct A→B switch and the
uneditable-clip stand-down.
---
 .../editor/DomEditCropHandles.test.tsx        | 86 +++++++++++++++++++
 .../components/editor/DomEditCropHandles.tsx  | 37 ++++----
 2 files changed, 107 insertions(+), 16 deletions(-)
 create mode 100644 packages/studio/src/components/editor/DomEditCropHandles.test.tsx

diff --git a/packages/studio/src/components/editor/DomEditCropHandles.test.tsx b/packages/studio/src/components/editor/DomEditCropHandles.test.tsx
new file mode 100644
index 0000000000..09c73deccd
--- /dev/null
+++ b/packages/studio/src/components/editor/DomEditCropHandles.test.tsx
@@ -0,0 +1,86 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import type { OverlayRect } from "./domEditOverlayGeometry";
+import { DomEditCropHandles } from "./DomEditCropHandles";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+const overlayRect: OverlayRect = {
+  left: 0,
+  top: 0,
+  width: 200,
+  height: 100,
+  editScaleX: 1,
+  editScaleY: 1,
+};
+
+function selectionFor(el: HTMLElement): DomEditSelection {
+  return { element: el, id: el.id, selector: `#${el.id}` } as unknown as DomEditSelection;
+}
+
+function makeEl(id: string, clip: string): HTMLElement {
+  const el = document.createElement("div");
+  el.id = id;
+  if (clip) el.style.setProperty("clip-path", clip);
+  document.body.append(el);
+  return el;
+}
+
+function render(el: HTMLElement): { root: Root; rerender: (next: HTMLElement) => void } {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const draw = (target: HTMLElement) =>
+    act(() => {
+      root.render(
+        <DomEditCropHandles
+          selection={selectionFor(target)}
+          overlayRect={overlayRect}
+          onStyleCommit={() => undefined}
+        />,
+      );
+    });
+  draw(el);
+  return { root, rerender: draw };
+}
+
+// Regression: the deselect restore used a ref recomputed from RENDER state — on
+// a direct A→B selection switch, state re-syncs to B before A's effect cleanup
+// runs, so A used to get B's crop string (or lose its crop entirely). The
+// restore value must be owned by A's own lift effect / crop gesture.
+describe("DomEditCropHandles clip lift/restore", () => {
+  it("lifts on select and restores the inline clip verbatim on unmount", () => {
+    const a = makeEl("a", "inset(16px round 12px)");
+    const { root } = render(a);
+    expect(a.style.getPropertyValue("clip-path")).toBe("none");
+    act(() => root.unmount());
+    expect(a.style.getPropertyValue("clip-path")).toBe("inset(16px round 12px)");
+  });
+
+  it("restores A's own clip when switching directly to B", () => {
+    const a = makeEl("a", "inset(16px)");
+    const b = makeEl("b", "inset(40px 8px 4px 2px)");
+    const { root, rerender } = render(a);
+    rerender(b);
+    // A got ITS clip back, not B's (and not removed); B is now lifted.
+    expect(a.style.getPropertyValue("clip-path")).toBe("inset(16px)");
+    expect(b.style.getPropertyValue("clip-path")).toBe("none");
+    act(() => root.unmount());
+    expect(b.style.getPropertyValue("clip-path")).toBe("inset(40px 8px 4px 2px)");
+  });
+
+  it("never lifts an uneditable clip and leaves it untouched across select/deselect", () => {
+    const a = makeEl("a", "circle(50% at 50% 50%)");
+    const { root } = render(a);
+    expect(a.style.getPropertyValue("clip-path")).toBe("circle(50% at 50% 50%)");
+    act(() => root.unmount());
+    expect(a.style.getPropertyValue("clip-path")).toBe("circle(50% at 50% 50%)");
+  });
+});
diff --git a/packages/studio/src/components/editor/DomEditCropHandles.tsx b/packages/studio/src/components/editor/DomEditCropHandles.tsx
index 746c774f94..7ccdaad3e2 100644
--- a/packages/studio/src/components/editor/DomEditCropHandles.tsx
+++ b/packages/studio/src/components/editor/DomEditCropHandles.tsx
@@ -84,7 +84,7 @@ export function DomEditCropHandles({
   const cropStateFor = (element: HTMLElement) => {
     const parsed = readElementCropInsets(element);
     const { radius, ...insets } = parsed ?? { top: 0, right: 0, bottom: 0, left: 0, radius: 0 };
-    return { element, croppable: parsed !== null, insets: insets as ClipPathInsetSides, radius };
+    return { element, croppable: parsed !== null, insets, radius };
   };
   const [state, setState] = useState(() => cropStateFor(selection.element));
 
@@ -102,32 +102,32 @@ export function DomEditCropHandles({
     state.insets.bottom > 0 ||
     state.insets.left > 0;
 
-  // Latest committed crop — re-applied to the element when the selection drops.
-  const committedRef = useRef<string | null>(null);
-  committedRef.current = hasCrop ? buildInsetClipPathSides(state.insets, state.radius) : null;
-
   // Lift the clip while the element is selected so the full content shows and the
   // cropped-away area can be dimmed; restore on deselect. Keyed on the element so
   // switching selections restores the previous one. Runs after render, so the
   // state re-sync above still reads the element's real committed clip. Restore
   // prefers the pre-lift inline value VERBATIM — the rebuilt inset only replaces
   // it after a crop gesture actually commits, so a mere select+deselect can
-  // never reformat (or drop) what the author wrote.
+  // never reformat (or drop) what the author wrote. Both refs are written only
+  // by THIS element's lift effect and crop gestures — never derived from render
+  // state, which by cleanup time already describes the NEXT selection (a direct
+  // A→B switch re-syncs state to B before A's cleanup runs).
   const liftedRef = useRef(false);
   const preLiftInlineClipRef = useRef("");
-  const cropCommittedRef = useRef(false);
+  // null = no crop gesture committed this selection; "" = committed a crop
+  // removal; anything else = the exact committed clip-path value.
+  const committedClipRef = useRef<string | null>(null);
   useEffect(() => {
     const el = selection.element;
     if (readElementCropInsets(el) === null) return;
     preLiftInlineClipRef.current = el.style.getPropertyValue("clip-path");
-    cropCommittedRef.current = false;
+    committedClipRef.current = null;
     el.style.setProperty("clip-path", "none");
     liftedRef.current = true;
     return () => {
       liftedRef.current = false;
-      const restore = cropCommittedRef.current
-        ? committedRef.current
-        : preLiftInlineClipRef.current || null;
+      const committed = committedClipRef.current;
+      const restore = committed !== null ? committed || null : preLiftInlineClipRef.current || null;
       if (restore) el.style.setProperty("clip-path", restore);
       else el.style.removeProperty("clip-path");
     };
@@ -194,12 +194,17 @@ export function DomEditCropHandles({
     const reLift = () => {
       if (liftedRef.current) el.style.setProperty("clip-path", "none");
     };
-    void Promise.resolve(
-      onStyleCommit?.("clip-path", buildInsetClipPathSides(state.insets, state.radius)),
-    ).then(() => {
+    const committedValue = buildInsetClipPathSides(state.insets, state.radius);
+    const cropped =
+      state.insets.top > 0 ||
+      state.insets.right > 0 ||
+      state.insets.bottom > 0 ||
+      state.insets.left > 0;
+    void Promise.resolve(onStyleCommit?.("clip-path", committedValue)).then(() => {
       // Only a landed commit makes the rebuilt inset the restore value; a
-      // failed one keeps restoring the pre-lift clip.
-      cropCommittedRef.current = true;
+      // failed one keeps restoring the pre-lift clip. Store the value itself —
+      // by deselect time, render state describes the next selection.
+      committedClipRef.current = cropped ? committedValue : "";
       reLift();
     }, reLift);
   };

From 11b4960be71bdbfd65b27390365e68c331a8b8b3 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 14:58:21 -0400
Subject: [PATCH 11/24] refactor: address review nits

- merge gsapResizeIntercept's duplicate module imports
- move the core-constant imports to the file headers (picker, domEditingDom)
- justify the cross-realm HTMLElement casts (iframe-realm nodes fail
  instanceof; access is duck-typed)
---
 packages/core/src/runtime/picker.ts                    | 2 +-
 packages/studio/src/components/editor/domEditingDom.ts | 3 +--
 packages/studio/src/hooks/gsapResizeIntercept.ts       | 9 +++++----
 packages/studio/src/utils/gsapSoftReload.ts            | 6 ++++--
 4 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts
index e9ced66c27..52921fb82e 100644
--- a/packages/core/src/runtime/picker.ts
+++ b/packages/core/src/runtime/picker.ts
@@ -1,4 +1,5 @@
 import type { RuntimeJson, RuntimeOutboundMessage, RuntimePickerElementInfo } from "./types";
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "../colorGrading";
 import { swallow } from "./diagnostics";
 
 type PickerModuleDeps = {
@@ -17,7 +18,6 @@ const PICKER_BLOCK_SELECTOR = [
   "[data-hyperframes-picker-block]",
   "[data-hyper-shader-loading]",
 ].join(",");
-import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "../colorGrading";
 
 export type PickerModule = {
   enablePickMode: () => void;
diff --git a/packages/studio/src/components/editor/domEditingDom.ts b/packages/studio/src/components/editor/domEditingDom.ts
index 82b5649789..b1f341ca70 100644
--- a/packages/studio/src/components/editor/domEditingDom.ts
+++ b/packages/studio/src/components/editor/domEditingDom.ts
@@ -3,6 +3,7 @@
  * selector utilities, and composition source resolution.
  * No imports from other domEditing* modules — safe to import from anywhere.
  */
+import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
 import { CURATED_STYLE_PROPERTIES } from "./domEditingTypes";
 
 // ─── Type guard ───────────────────────────────────────────────────────────────
@@ -28,8 +29,6 @@ export function isTextBearingTag(tagName: string): boolean {
   return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);
 }
 
-import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
-
 export function isElementVisibleThroughAncestors(el: HTMLElement): boolean {
   const win = el.ownerDocument.defaultView;
   if (!win) return true;
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.ts b/packages/studio/src/hooks/gsapResizeIntercept.ts
index aee92be6f5..9396384f2d 100644
--- a/packages/studio/src/hooks/gsapResizeIntercept.ts
+++ b/packages/studio/src/hooks/gsapResizeIntercept.ts
@@ -16,19 +16,18 @@ import {
   commitStaticGsapSize,
   commitKeyframedSizeFromResize,
   computeCurrentPercentage,
+  findExistingPositionWrite,
   findSizeSetAnimation,
   materializeIfDynamic,
 } from "./gsapDragCommit";
 import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
-import { pickClosestToPlayhead } from "./gsapPositionDetection";
+import { pickClosestToPlayhead, readGsapPositionFromIframe } from "./gsapPositionDetection";
+import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { selectorFromSelection } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 import { resolveGroupTween, POSITION_CHANNELS } from "./gsapRuntimeBridge";
 import { hasNonHoldTweenForElement } from "./gsapRuntimeKeyframes";
-import { readGsapPositionFromIframe } from "./gsapPositionDetection";
-import { findExistingPositionWrite } from "./gsapDragCommit";
-import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 
 const IDENTITY_ONE_PROPS = new Set(["opacity", "autoAlpha", "scale", "scaleX", "scaleY"]);
 
@@ -114,6 +113,8 @@ export async function tryGsapResizeIntercept(
   let scaleDraftDropPoint: { x: number; y: number } | null = null;
   let nonUniformScale = false;
   if (resizeGroup === "scale") {
+    // Iframe-realm element — instanceof HTMLElement fails across realms; the
+    // selector targets composition elements, and every use below is duck-typed.
     const el = iframe?.contentDocument?.querySelector(selector ?? "") as HTMLElement | null;
     // The resize draft modifies el.style.width/height, so read the ORIGINAL
     // dimensions saved by the draft system before it ran.
diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.ts
index a5f08eea31..f9f051fa84 100644
--- a/packages/studio/src/utils/gsapSoftReload.ts
+++ b/packages/studio/src/utils/gsapSoftReload.ts
@@ -319,8 +319,10 @@ export function applySoftReload(
     if (allTargets.length > 0 && win.gsap?.set) {
       const saved: Array<[HTMLElement, string]> = [];
       for (const el of allTargets) {
-        const s = (el as HTMLElement).style;
-        if (s?.cssText != null) saved.push([el as HTMLElement, s.cssText]);
+        // Iframe-realm node: instanceof HTMLElement fails across realms, and
+        // gsap targets() only yields elements here — style access is duck-typed.
+        const styled = el as HTMLElement;
+        if (styled.style?.cssText != null) saved.push([styled, styled.style.cssText]);
       }
       try {
         win.gsap.set(allTargets, { clearProps: "all" });

From f10ef8c64166fb6f8caec8cfd74acc365b843066 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 15:18:49 -0400
Subject: [PATCH 12/24] fix(studio): address review findings on graded-element
 editing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-ups (both reviewers, all findings):

- resize captures scope to the resize group: convert-to-keyframes
  resolvedFromValues and the whole-offset backfill pass the group filter,
  so an opacity-touching intro tween can't ride into a converted scale
  tween (the rotation fix's contract, now uniform across intercepts)
- commitStaticSet resolves every group's target set BEFORE committing and
  coalesces groups landing on the same legacy mixed set into one commit —
  the second commit can no longer chase a stale group-derived id
- installAuthoredOpacityCapture also stamps an element the moment it GAINS
  data-color-grading at runtime (attributeFilter), not just at insertion
- both writer twins now share the same emitted-set dedupe shape
- applySoftReload's positional tail becomes a SoftReloadOptions object
- readAllAnimatedProperties builds the group-filtered key set immutably
  instead of deleting from the set mid-iteration
- applyAuthoredInlineOpacity documents the priority-lossy round-trip
- the marquee hit-test reads activeCompositionPathRef like its neighbors

New tests: resize intercept (scale route + group filter + non-uniform
longhands), after-write-HTML / stamp / empty-stamp opacity restore, the
no-op-commit-with-missed-instant-patch soft-reload contract, and the
runtime-gained-grading stamp.
---
 .../core/src/runtime/colorGrading.test.ts     |  22 +++
 packages/core/src/runtime/colorGrading.ts     |  15 +-
 packages/parsers/src/gsapWriterAcorn.ts       |   8 +-
 .../src/components/editor/DomEditOverlay.tsx  |   7 +-
 .../src/hooks/gsapResizeIntercept.test.ts     | 129 ++++++++++++++++++
 .../studio/src/hooks/gsapResizeIntercept.ts   |   9 +-
 .../studio/src/hooks/gsapRuntimeReaders.ts    |  10 +-
 .../src/hooks/useAnimatedPropertyCommit.ts    |  37 +++--
 .../src/hooks/useGsapScriptCommits.test.tsx   |  97 ++++++-------
 .../studio/src/hooks/useGsapScriptCommits.ts  |  10 +-
 packages/studio/src/utils/authoredOpacity.ts  |   9 +-
 .../studio/src/utils/gsapSoftReload.test.ts   |  88 +++++++++++-
 packages/studio/src/utils/gsapSoftReload.ts   |  14 +-
 13 files changed, 367 insertions(+), 88 deletions(-)
 create mode 100644 packages/studio/src/hooks/gsapResizeIntercept.test.ts

diff --git a/packages/core/src/runtime/colorGrading.test.ts b/packages/core/src/runtime/colorGrading.test.ts
index cf3e0e048c..a02d6bdb30 100644
--- a/packages/core/src/runtime/colorGrading.test.ts
+++ b/packages/core/src/runtime/colorGrading.test.ts
@@ -643,4 +643,26 @@ describe("installAuthoredOpacityCapture", () => {
     expect(el.getAttribute("data-hf-authored-opacity")).toBe("");
     el.remove();
   });
+
+  it("stamps an already-inserted element the moment it GAINS grading at runtime", async () => {
+    installAuthoredOpacityCapture();
+    const el = document.createElement("img");
+    el.style.opacity = "0.9";
+    document.body.appendChild(el);
+    await Promise.resolve();
+    expect(el.hasAttribute("data-hf-authored-opacity")).toBe(false);
+
+    // Studio applies a preset to a previously ungraded element — no re-insert.
+    el.setAttribute(HF_COLOR_GRADING_ATTR, serializeHfColorGrading({ adjust: { exposure: 0.5 } }));
+    await Promise.resolve();
+    expect(el.getAttribute("data-hf-authored-opacity")).toBe("0.9");
+
+    // Later attribute rewrites (preset tweaks) never overwrite the stamp,
+    // even if a transient is live by then.
+    el.style.opacity = "0";
+    el.setAttribute(HF_COLOR_GRADING_ATTR, serializeHfColorGrading({ adjust: { exposure: 0.9 } }));
+    await Promise.resolve();
+    expect(el.getAttribute("data-hf-authored-opacity")).toBe("0.9");
+    el.remove();
+  });
 });
diff --git a/packages/core/src/runtime/colorGrading.ts b/packages/core/src/runtime/colorGrading.ts
index 75e85ebd89..8ec35806b6 100644
--- a/packages/core/src/runtime/colorGrading.ts
+++ b/packages/core/src/runtime/colorGrading.ts
@@ -239,8 +239,21 @@ export function installAuthoredOpacityCapture(): void {
   new MutationObserver((mutations) => {
     for (const mutation of mutations) {
       for (const node of mutation.addedNodes) scan(node);
+      // An element can also GAIN grading at runtime (studio applies a preset to
+      // a previously ungraded element). Stamp at that moment — strictly earlier
+      // than the engine's hide, so the captured value can never be worse than
+      // the hide-time fallback, and after a soft reload's authored restore it
+      // IS the authored value. stamp() is idempotent: an existing stamp wins.
+      if (mutation.type === "attributes" && mutation.target instanceof Element) {
+        if (mutation.target.hasAttribute(HF_COLOR_GRADING_ATTR)) stamp(mutation.target);
+      }
     }
-  }).observe(root, { childList: true, subtree: true });
+  }).observe(root, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: [HF_COLOR_GRADING_ATTR],
+  });
 }
 
 // Map insertion order gives us simple FIFO eviction for authoring sessions that cycle LUTs.
diff --git a/packages/parsers/src/gsapWriterAcorn.ts b/packages/parsers/src/gsapWriterAcorn.ts
index a0381e3241..556eecd093 100644
--- a/packages/parsers/src/gsapWriterAcorn.ts
+++ b/packages/parsers/src/gsapWriterAcorn.ts
@@ -57,11 +57,15 @@ function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation,
   if (anim.method !== "set" && anim.duration !== undefined) props.duration = anim.duration;
   if (anim.ease) props.ease = anim.ease;
   const entries = Object.entries(props).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
+  const emitted = new Set(Object.keys(props));
   if (anim.extras) {
     for (const [k, v] of Object.entries(anim.extras)) {
       // A key carried by both properties and extras (a set's parsed
-      // `immediateRender: true`) must emit once — properties win.
-      if (!(k in props)) entries.push(`${safeKey(k)}: ${valueToCode(v)}`);
+      // `immediateRender: true`) must emit once — properties win. Same
+      // dedupe shape as the recast twin (gsapParser.ts buildTweenStatementCode).
+      if (emitted.has(k)) continue;
+      emitted.add(k);
+      entries.push(`${safeKey(k)}: ${valueToCode(v)}`);
     }
   }
   const objCode = `{ ${entries.join(", ")} }`;
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index 5b444a7c78..c0adaef18c 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -315,7 +315,12 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     if (!hoverSelectionRef.current && onMarqueeSelectRef.current && compRect.width > 0) {
       const iframe = iframeRef.current;
       const freshTarget = iframe
-        ? getPreviewTargetFromPointer(iframe, event.clientX, event.clientY, activeCompositionPath)
+        ? getPreviewTargetFromPointer(
+            iframe,
+            event.clientX,
+            event.clientY,
+            activeCompositionPathRef.current,
+          )
         : null;
       if (freshTarget) return;
       const overlayEl = overlayRef.current;
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.test.ts b/packages/studio/src/hooks/gsapResizeIntercept.test.ts
new file mode 100644
index 0000000000..6a0d750883
--- /dev/null
+++ b/packages/studio/src/hooks/gsapResizeIntercept.test.ts
@@ -0,0 +1,129 @@
+// @vitest-environment happy-dom
+import { afterEach, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
+import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
+});
+
+/**
+ * Scale-route resize: an element whose visual size is driven by a scale-group
+ * tween. The intercept must (a) route the commit through SCALE, never
+ * width/height, and (b) resolve convert-to-keyframes from-values through the
+ * group filter — an opacity-touching intro tween on the same element must not
+ * ride into the converted keyframes (the disappearance bake class).
+ */
+function makeGradedElement(): HTMLElement {
+  const el = document.createElement("img");
+  el.id = "clip";
+  el.setAttribute("data-hf-studio-original-width", "640");
+  el.setAttribute("data-hf-studio-original-height", "360");
+  // Grading contract: source hidden, canvas carries effective opacity.
+  el.setAttribute("data-hf-color-grading-source-hidden", "");
+  const canvas = document.createElement("canvas");
+  canvas.id = "__hf_color_grading_clip";
+  canvas.style.opacity = "0.98";
+  document.body.append(el, canvas);
+  return el;
+}
+
+function fakeIframe(el: HTMLElement, gsapValues: Record<string, number>) {
+  // The element's OPACITY intro tween lives on the timeline: unfiltered
+  // capture would pick `opacity` up via the other-tween sweep.
+  const opacityIntro = { targets: () => [el], vars: { opacity: 0, duration: 0.8 } };
+  return {
+    contentWindow: {
+      __timelines: { main: { getChildren: () => [opacityIntro] } },
+      gsap: { getProperty: (_el: Element, prop: string) => gsapValues[prop] ?? 0 },
+    },
+    contentDocument: document,
+  } as unknown as HTMLIFrameElement;
+}
+
+function scaleFromTween(): GsapAnimation {
+  return {
+    id: "#clip-from-200-scale",
+    targetSelector: "#clip",
+    propertyGroup: "scale",
+    method: "from",
+    properties: { scale: 0.9 },
+    position: 0.2,
+    resolvedStart: 0.2,
+    duration: 0.8,
+  } as unknown as GsapAnimation;
+}
+
+function keyframedScaleFixture(): GsapAnimation {
+  return {
+    ...scaleFromTween(),
+    keyframes: {
+      keyframes: [
+        { percentage: 0, properties: { scale: 0.9 } },
+        { percentage: 100, properties: { scale: 1 } },
+      ],
+    },
+  } as unknown as GsapAnimation;
+}
+
+/** Drive one resize through the intercept, returning every committed mutation. */
+async function runResize(
+  el: HTMLElement,
+  iframe: HTMLIFrameElement,
+  size: { width: number; height: number },
+): Promise<Array<Record<string, unknown>>> {
+  const selection = { id: "clip", selector: "#clip", element: el } as unknown as DomEditSelection;
+  usePlayerStore.setState({ currentTime: 0.5 }); // inside the tween's range
+  const committed: Array<Record<string, unknown>> = [];
+  const commitMutation = vi.fn(async (_sel: unknown, mutation: Record<string, unknown>) => {
+    committed.push(mutation);
+  });
+  const handled = await tryGsapResizeIntercept(
+    selection,
+    size,
+    [scaleFromTween()],
+    iframe,
+    commitMutation as never,
+    async () => [keyframedScaleFixture()],
+  );
+  expect(handled).toBe(true);
+  return committed;
+}
+
+it("scale-route resize converts via the group filter and commits scale, not width/height", async () => {
+  const el = makeGradedElement();
+  const iframe = fakeIframe(el, { scale: 1, scaleX: 1, scaleY: 1, opacity: 0, rotation: 0 });
+  // uniform: 800/640 === 450/360
+  const committed = await runResize(el, iframe, { width: 800, height: 450 });
+
+  const convert = committed.find((m) => m.type === "convert-to-keyframes");
+  expect(convert).toBeDefined();
+  const fromValues = convert!.resolvedFromValues as Record<string, number>;
+  // Group filter: the opacity intro tween must NOT leak into the conversion.
+  expect(fromValues).not.toHaveProperty("opacity");
+  expect(fromValues).toHaveProperty("scale");
+
+  // Every committed property is scale-group — the resize never writes
+  // width/height for a scale-driven element (the double-apply bug class).
+  const allProps = committed.flatMap((m) => [
+    ...Object.keys((m.properties as Record<string, unknown>) ?? {}),
+    ...Object.keys((m.resolvedFromValues as Record<string, unknown>) ?? {}),
+  ]);
+  expect(allProps).not.toContain("width");
+  expect(allProps).not.toContain("height");
+  expect(allProps.some((p) => p === "scale" || p === "scaleX")).toBe(true);
+});
+
+it("non-uniform drag commits scaleX/scaleY longhands", async () => {
+  const el = makeGradedElement();
+  const iframe = fakeIframe(el, { scale: 1, scaleX: 1, scaleY: 1, opacity: 0 });
+  // scaleX 1.25 vs scaleY 1.0 → non-uniform
+  const committed = await runResize(el, iframe, { width: 800, height: 360 });
+
+  const serialized = JSON.stringify(committed);
+  expect(serialized).toContain("scaleX");
+  expect(serialized).toContain("scaleY");
+});
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.ts b/packages/studio/src/hooks/gsapResizeIntercept.ts
index 9396384f2d..e7cc476703 100644
--- a/packages/studio/src/hooks/gsapResizeIntercept.ts
+++ b/packages/studio/src/hooks/gsapResizeIntercept.ts
@@ -106,7 +106,12 @@ export async function tryGsapResizeIntercept(
   const coalesceKey = `gsap:resize:${anim.id}`;
 
   const selector = selectorFromSelection(selection);
-  const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
+  // Scope every capture to the resize group — same contract as the rotation
+  // intercept. Unfiltered, an opacity-touching intro tween on the element
+  // would ride into resize conversions/backfills (the Fix-2 bake class).
+  const runtimeProps = selector
+    ? readAllAnimatedProperties(iframe, selector, anim, resizeGroup)
+    : {};
 
   let resizeProps: Record<string, number>;
   let scaleDraftEl: HTMLElement | null = null;
@@ -254,7 +259,7 @@ export async function tryGsapResizeIntercept(
       if (newId) anim = { ...anim, id: newId };
     } else if (!anim.keyframes) {
       const resolvedFromValues = selector
-        ? readAllAnimatedProperties(iframe, selector, anim)
+        ? readAllAnimatedProperties(iframe, selector, anim, resizeGroup)
         : undefined;
       await commitMutation(
         selection,
diff --git a/packages/studio/src/hooks/gsapRuntimeReaders.ts b/packages/studio/src/hooks/gsapRuntimeReaders.ts
index 3c78ec608b..48d2ed3ffc 100644
--- a/packages/studio/src/hooks/gsapRuntimeReaders.ts
+++ b/packages/studio/src/hooks/gsapRuntimeReaders.ts
@@ -106,11 +106,9 @@ export function readAllAnimatedProperties(
   // point of property-group tweens is that a rotation commit never carries
   // opacity/rotationX/etc. captured from unrelated tweens on the element.
   const inGroup = (p: string) => !group || classifyPropertyGroup(p) === group;
-  for (const p of propKeys) {
-    if (!inGroup(p)) propKeys.delete(p);
-  }
+  const groupedPropKeys = new Set([...propKeys].filter(inGroup));
 
-  for (const prop of propKeys) {
+  for (const prop of groupedPropKeys) {
     const val = readLiveGsapValue(gsap, el, prop);
     if (Number.isFinite(val)) {
       result[prop] = POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
@@ -142,7 +140,7 @@ export function readAllAnimatedProperties(
       }
     }
   } catch {}
-  for (const p of propKeys) otherTweenProps.delete(p);
+  for (const p of groupedPropKeys) otherTweenProps.delete(p);
 
   // Tier 1: Transform + visual properties with universal CSS defaults.
   // Safe to compare against hardcoded values — these are always 0 or 1
@@ -174,7 +172,7 @@ export function readAllAnimatedProperties(
   // Collect all properties that ANY tween on this element explicitly targets.
   // Only capture baseline values for these — GSAP reports non-default values
   // (scaleZ=0, brightness=0) for untouched properties, polluting keyframes.
-  const allTweenedProps = new Set([...propKeys, ...otherTweenProps]);
+  const allTweenedProps = new Set([...groupedPropKeys, ...otherTweenProps]);
   for (const [prop, defaultVal] of Object.entries(UNIVERSAL_BASELINE)) {
     if (prop in result) continue;
     if (!allTweenedProps.has(prop)) continue;
diff --git a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
index 9e5914f100..e1cd37b967 100644
--- a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
+++ b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
@@ -186,19 +186,40 @@ async function commitStaticSet(
     byGroup.set(group, batch);
   }
   const sets = animations.filter((a) => a.method === "set" && a.targetSelector === selector);
+  // Resolve every group's target BEFORE committing anything, and coalesce
+  // groups that land on the SAME set into one commit: the `sets` snapshot is
+  // captured once, so if two groups resolved to one legacy mixed set, a first
+  // commit could re-shape it server-side and leave the second chasing a stale
+  // id (404 on legacy pre-split files).
+  const byTargetSet = new Map<GsapAnimation, [string, number | string][]>();
+  const newSetBatches: [string, number | string][][] = [];
   for (const [group, batch] of byGroup) {
-    const existingSet =
-      // A set already dedicated to this group wins; else a mixed set that
-      // already carries a property of this group (merging same-group values
-      // there beats spawning a second writer for the same channel).
-      sets.find((a) => a.propertyGroup === group) ??
-      sets.find((a) => Object.keys(a.properties).some((k) => classifyPropertyGroup(k) === group));
+    const existingSet = findGroupOwningSet(sets, group);
     if (existingSet) {
-      await commitSetProps(selection, existingSet, batch, selector, animations, commit);
+      byTargetSet.set(existingSet, [...(byTargetSet.get(existingSet) ?? []), ...batch]);
     } else {
-      await addGlobalStaticSet(selection, batch, selector, commit);
+      newSetBatches.push(batch);
     }
   }
+  for (const [targetSet, batch] of byTargetSet) {
+    await commitSetProps(selection, targetSet, batch, selector, animations, commit);
+  }
+  // Fresh adds don't reshape existing sets, so their ids can't go stale.
+  for (const batch of newSetBatches) {
+    await addGlobalStaticSet(selection, batch, selector, commit);
+  }
+}
+
+/**
+ * The set that owns a property group: one already dedicated to the group wins;
+ * else a mixed set that already carries a property of the group (merging
+ * same-group values there beats spawning a second writer for the channel).
+ */
+function findGroupOwningSet(sets: GsapAnimation[], group: string): GsapAnimation | undefined {
+  return (
+    sets.find((a) => a.propertyGroup === group) ??
+    sets.find((a) => Object.keys(a.properties).some((k) => classifyPropertyGroup(k) === group))
+  );
 }
 
 /**
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
index 8416a4a08b..2e867a4f4c 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
+++ b/packages/studio/src/hooks/useGsapScriptCommits.test.tsx
@@ -51,6 +51,14 @@ function syncDragPreview(res: MutationResult, reloadPreview: () => void) {
   applyPreviewSync(FAKE_IFRAME, res, dragOptions(), reloadPreview);
 }
 
+function expectSoftReloadedWith(onAsyncFailure: unknown, authoredHtml: string | undefined) {
+  expect(applySoftReload).toHaveBeenCalledWith(FAKE_IFRAME, "SCRIPT", {
+    onAsyncFailure,
+    currentTimeOverride: 0,
+    authoredHtml,
+  });
+}
+
 describe("applyPreviewSync", () => {
   beforeEach(() => {
     patchRuntimeTweenInPlace.mockReset();
@@ -81,13 +89,7 @@ describe("applyPreviewSync", () => {
 
     // reloadPreview is wired as onAsyncFailure (3rd arg) so a MotionPath-plugin
     // CDN load failure escalates to a full reload — but it is NOT called eagerly.
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      reloadPreview,
-      0,
-      undefined,
-    );
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     // A successful instant patch is the fast path; here it missed → fallback event.
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -105,13 +107,7 @@ describe("applyPreviewSync", () => {
 
     // U4: "verify-failed" is the TRANSIENT empty-timeline window — the live state
     // is correct, so we must NOT escalate to a full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      reloadPreview,
-      0,
-      undefined,
-    );
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     // Telemetry records the suppressed transient (escalated: false).
     expect(trackStudioEvent).toHaveBeenCalledWith(
@@ -132,13 +128,7 @@ describe("applyPreviewSync", () => {
     syncDragPreview(result({ scriptText: "SCRIPT" }), reloadPreview);
 
     // Structural failure: the preview is genuinely stale/broken → full reload.
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      reloadPreview,
-      0,
-      undefined,
-    );
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -162,13 +152,7 @@ describe("applyPreviewSync", () => {
     );
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      reloadPreview,
-      0,
-      undefined,
-    );
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     // "applied" emits no telemetry (only the failure paths do).
     expect(trackStudioEvent).not.toHaveBeenCalled();
@@ -186,13 +170,7 @@ describe("applyPreviewSync", () => {
     );
 
     // onAsyncFailure is wired, but the transient result does not trigger it.
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      reloadPreview,
-      0,
-      undefined,
-    );
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -211,13 +189,7 @@ describe("applyPreviewSync", () => {
       reloadPreview,
     );
 
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      reloadPreview,
-      0,
-      undefined,
-    );
+    expectSoftReloadedWith(reloadPreview, undefined);
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(trackStudioEvent).toHaveBeenCalledWith(
       "gsap_soft_reload_outcome",
@@ -330,6 +302,31 @@ describe("runCommit — instantPatch wiring", () => {
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 
+  it("no-op commit whose instant patch MISSES soft-reloads (never full-reloads)", async () => {
+    // Server contract: gsap-mutations returns scriptText on EVERY response,
+    // including changed:false — so the fallback re-runs the identical script
+    // ("applied") instead of escalating a genuine no-op to a full reload.
+    patchRuntimeTweenInPlace.mockReturnValue(false);
+    applySoftReload.mockReturnValue("applied");
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+
+    await act(async () => {
+      await deps.api.commitMutation(
+        selection,
+        { type: "update-property", property: "y", value: 311 },
+        {
+          label: "Move layer",
+          softReload: true,
+          instantPatch: { selector: "#a", change: { kind: "set", props: { x: 485, y: 311 } } },
+        },
+      );
+    });
+
+    expectSoftReloadedWith(deps.reloadPreview, "AFTER");
+    expect(deps.reloadPreview).not.toHaveBeenCalled();
+  });
+
   beforeEach(() => {
     patchRuntimeTweenInPlace.mockReset();
     applySoftReload.mockReset();
@@ -368,13 +365,7 @@ describe("runCommit — instantPatch wiring", () => {
     });
 
     expect(fetch).toHaveBeenCalledTimes(1);
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      deps.reloadPreview,
-      0,
-      "AFTER",
-    );
+    expectSoftReloadedWith(deps.reloadPreview, "AFTER");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
     expect(deps.onCacheInvalidate).toHaveBeenCalledTimes(1);
   });
@@ -389,13 +380,7 @@ describe("runCommit — instantPatch wiring", () => {
     });
 
     expect(patchRuntimeTweenInPlace).not.toHaveBeenCalled();
-    expect(applySoftReload).toHaveBeenCalledWith(
-      FAKE_IFRAME,
-      "SCRIPT",
-      deps.reloadPreview,
-      0,
-      "AFTER",
-    );
+    expectSoftReloadedWith(deps.reloadPreview, "AFTER");
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.ts b/packages/studio/src/hooks/useGsapScriptCommits.ts
index a28478acb4..cb088e3470 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.ts
+++ b/packages/studio/src/hooks/useGsapScriptCommits.ts
@@ -72,13 +72,11 @@ function softReloadOrEscalate(
   // not the iframe's raw `__player.getTime()` — see the comment in
   // applySoftReload for why the two can desync after a keyframe-node drag.
   const currentTime = usePlayerStore.getState().currentTime;
-  const result: SoftReloadResult = applySoftReload(
-    iframe,
-    scriptText,
-    reloadPreview,
-    currentTime,
+  const result: SoftReloadResult = applySoftReload(iframe, scriptText, {
+    onAsyncFailure: reloadPreview,
+    currentTimeOverride: currentTime,
     authoredHtml,
-  );
+  });
   if (result === "applied") return;
   trackStudioEvent("gsap_soft_reload_outcome", {
     origin,
diff --git a/packages/studio/src/utils/authoredOpacity.ts b/packages/studio/src/utils/authoredOpacity.ts
index 6a6b4998b0..53b3ede308 100644
--- a/packages/studio/src/utils/authoredOpacity.ts
+++ b/packages/studio/src/utils/authoredOpacity.ts
@@ -21,7 +21,14 @@ export function readStampedAuthoredOpacity(element: AttributeReader): string | n
   return element.getAttribute(COLOR_GRADING_AUTHORED_OPACITY_ATTR);
 }
 
-/** Write an authored inline opacity back: "" removes the property, a value sets it. */
+/**
+ * Write an authored inline opacity back: "" removes the property, a value sets
+ * it. Priority-lossy by design: the capture reads `style.opacity` (value only)
+ * and the write sets no priority, so an authored `opacity: X !important`
+ * round-trips as `opacity: X`. The only `!important` opacity in the pipeline
+ * is the color-grading runtime hide — a transient this contract exists to
+ * discard — and authored compositions don't `!important` their opacity.
+ */
 export function applyAuthoredInlineOpacity(style: CSSStyleDeclaration, authored: string): void {
   if (authored === "") style.removeProperty("opacity");
   else style.setProperty("opacity", authored);
diff --git a/packages/studio/src/utils/gsapSoftReload.test.ts b/packages/studio/src/utils/gsapSoftReload.test.ts
index 1576a8bc89..25e07edd97 100644
--- a/packages/studio/src/utils/gsapSoftReload.test.ts
+++ b/packages/studio/src/utils/gsapSoftReload.test.ts
@@ -107,7 +107,7 @@ describe("applySoftReload", () => {
     // async commit resolves. The rebuilt timeline must re-seek to the caller's
     // value, not the iframe's possibly-stale one.
     const { iframe, contentWindow } = buildMockIframe();
-    const result = applySoftReload(iframe, SCRIPT_TEXT, undefined, 0);
+    const result = applySoftReload(iframe, SCRIPT_TEXT, { currentTimeOverride: 0 });
     expect(result).toBe("applied");
     expect(contentWindow.__player.seek).toHaveBeenCalledWith(0);
   });
@@ -244,7 +244,7 @@ describe("applySoftReload", () => {
     (iframe.contentDocument as unknown as { head: unknown }).head = head;
 
     const onAsyncFailure = vi.fn();
-    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT, onAsyncFailure);
+    const result = applySoftReload(iframe, MOTION_PATH_SCRIPT_TEXT, { onAsyncFailure });
 
     // Optimistically "applied" (script will run once the plugin loads) — and the
     // script has NOT executed yet, so the timeline isn't rebound synchronously.
@@ -363,3 +363,87 @@ describe("ensureMotionPathPluginLoaded", () => {
     expect(appendedScripts).toHaveLength(2);
   });
 });
+
+// The authored-opacity restore: before the script re-runs (and its tweens
+// re-capture bounds), every animated element's inline opacity must be put back
+// to its AUTHORED value — from the after-write file HTML when provided, else
+// from the parse-time stamp. Otherwise a runtime transient (the color-grading
+// hide's 0, a mid-flight tween value) becomes a permanent tween bound.
+describe("applySoftReload authored-opacity restore", () => {
+  function buildIframeWithTarget(el: HTMLElement, overrides: Record<string, unknown> = {}) {
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent =
+      'const tl = gsap.timeline({ paused: true }); tl.to("#box", { opacity: 0.5 });';
+    const tl = {
+      kill: vi.fn(),
+      pause: vi.fn(),
+      getChildren: () => [{ targets: () => [el] }],
+    };
+    const contentWindow = {
+      gsap: { timeline: vi.fn(), set: vi.fn() },
+      __hfForceTimelineRebind: vi.fn(),
+      __timelines: { root: tl } as Record<string, unknown>,
+      __player: { getTime: () => 2.0, seek: vi.fn() },
+      __hfStudioManualEditsApply: vi.fn(),
+      ...overrides,
+    };
+    const container = document.createElement("div");
+    container.appendChild(scriptEl);
+    // Intercept only POST-SETUP appends: simulate the re-run script
+    // repopulating __timelines (as in buildMockIframe).
+    const realAppendChild = container.appendChild.bind(container);
+    container.appendChild = <T extends Node>(node: T): T => {
+      const result = realAppendChild(node);
+      if (node instanceof HTMLScriptElement && node.textContent?.includes("gsap.timeline")) {
+        contentWindow.__timelines.root = { kill: vi.fn(), pause: vi.fn() };
+      }
+      return result;
+    };
+    const contentDocument = {
+      querySelectorAll: (sel: string) => (sel === "script:not([src])" ? [scriptEl] : []),
+      createElement: (tag: string) => document.createElement(tag),
+      body: container,
+      head: document.createElement("div"),
+    };
+    return { iframe: { contentWindow, contentDocument } as unknown as HTMLIFrameElement };
+  }
+
+  /** Run one restore cycle over `el` and return the final inline opacity. */
+  function restoreOpacity(el: HTMLElement, authoredHtml?: string): string {
+    const { iframe } = buildIframeWithTarget(el);
+    expect(applySoftReload(iframe, SCRIPT_TEXT, authoredHtml ? { authoredHtml } : {})).toBe(
+      "applied",
+    );
+    return el.style.getPropertyValue("opacity");
+  }
+
+  it("restores opacity from the after-write HTML (matched by data-hf-id)", () => {
+    const el = document.createElement("img");
+    el.setAttribute("data-hf-id", "hf-1");
+    el.style.setProperty("opacity", "0", "important"); // the grading hide
+
+    const opacity = restoreOpacity(
+      el,
+      '<html><body><img data-hf-id="hf-1" style="opacity: 0.98"></body></html>',
+    );
+
+    expect(opacity).toBe("0.98");
+    expect(el.style.getPropertyPriority("opacity")).toBe("");
+  });
+
+  it("falls back to the parse-time stamp when no after-write HTML is given", () => {
+    const el = document.createElement("img");
+    el.setAttribute("data-hf-authored-opacity", "0.75");
+    el.style.opacity = "0.123"; // mid-flight tween transient
+
+    expect(restoreOpacity(el)).toBe("0.75");
+  });
+
+  it("an empty stamp (authored none) removes the inline opacity", () => {
+    const el = document.createElement("img");
+    el.setAttribute("data-hf-authored-opacity", "");
+    el.style.opacity = "0";
+
+    expect(restoreOpacity(el)).toBe("");
+  });
+});
diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.ts
index f9f051fa84..63012108ca 100644
--- a/packages/studio/src/utils/gsapSoftReload.ts
+++ b/packages/studio/src/utils/gsapSoftReload.ts
@@ -174,13 +174,21 @@ export type SoftReloadResult = "applied" | "verify-failed" | "cannot-soft-reload
  * caller should perform a full reload to recover. It never fires on the
  * synchronous paths.
  */
+export interface SoftReloadOptions {
+  /** Escalation for async plugin-load failures (e.g. MotionPath CDN error). */
+  onAsyncFailure?: () => void;
+  /** Seek target for the rebuilt timeline; defaults to the iframe player time. */
+  currentTimeOverride?: number;
+  /** After-write file HTML — the primary source for authored-opacity restore. */
+  authoredHtml?: string;
+}
+
 export function applySoftReload(
   iframe: HTMLIFrameElement | null,
   scriptText: string,
-  onAsyncFailure?: () => void,
-  currentTimeOverride?: number,
-  authoredHtml?: string,
+  options: SoftReloadOptions = {},
 ): SoftReloadResult {
+  const { onAsyncFailure, currentTimeOverride, authoredHtml } = options;
   if (!iframe || !scriptText) return "cannot-soft-reload";
 
   const win = iframe.contentWindow as IframeWindow | null;

From 42408be02b5a903b51b977a61ae48a94e0063398 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 15:34:41 -0400
Subject: [PATCH 13/24] fix(studio): draw the crop UI in the element's rotated
 frame
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Selecting a rotated (cropped) element appeared to straighten it: the crop
dim and dashed window were drawn on the axis-aligned bounding box, so the
bright window was a straight rectangle and the element's rotated corners
were masked to near-black — while the DOM transform was untouched.

clip-path applies in the element's LOCAL frame, before its transform, so
the crop visualization now renders inside a container rotated with the
element: readElementCropFrame decomposes the computed 2D matrix into
angle + per-axis scale (element scale finally factored into the px
mapping too) and 3D/unparseable transforms keep the axis-aligned
presentation. Pointer deltas rotate into the element frame before the
inset resolvers, so edge/pan drags track the rotated handles correctly.
---
 .../components/editor/DomEditCropHandles.tsx  | 72 ++++++++++-----
 .../editor/domEditOverlayCrop.test.ts         | 90 +++++++++++++++++++
 .../components/editor/domEditOverlayCrop.ts   | 88 ++++++++++++++++++
 3 files changed, 227 insertions(+), 23 deletions(-)

diff --git a/packages/studio/src/components/editor/DomEditCropHandles.tsx b/packages/studio/src/components/editor/DomEditCropHandles.tsx
index 7ccdaad3e2..7ac3b485b0 100644
--- a/packages/studio/src/components/editor/DomEditCropHandles.tsx
+++ b/packages/studio/src/components/editor/DomEditCropHandles.tsx
@@ -4,9 +4,11 @@ import type { OverlayRect } from "./domEditOverlayGeometry";
 import {
   type CropEdge,
   cropRectFromInsets,
+  readElementCropFrame,
   readElementCropInsets,
   resolveCropInsetFromEdgeDrag,
   resolveCropInsetFromMoveDrag,
+  rotateDeltaIntoFrame,
 } from "./domEditOverlayCrop";
 import { buildInsetClipPathSides, type ClipPathInsetSides } from "./clipPathHelpers";
 
@@ -17,6 +19,10 @@ interface CropGestureState {
   startY: number;
   startInsets: ClipPathInsetSides;
   didMove: boolean;
+  /** Element frame captured at gesture start: pointer deltas rotate into it. */
+  angleDeg: number;
+  scaleX: number;
+  scaleY: number;
 }
 
 interface DomEditCropHandlesProps {
@@ -133,11 +139,20 @@ export function DomEditCropHandles({
     };
   }, [selection.element]);
 
-  const scaleX = overlayRect.editScaleX > 0 ? overlayRect.editScaleX : 1;
-  const scaleY = overlayRect.editScaleY > 0 ? overlayRect.editScaleY : 1;
-  const width = overlayRect.width / scaleX;
-  const height = overlayRect.height / scaleY;
-  const cropRect = cropRectFromInsets(overlayRect, state.insets, scaleX, scaleY);
+  // The crop applies in the element's LOCAL frame (clip-path precedes the
+  // transform), so all crop UI is drawn inside a container rotated with the
+  // element — on a rotated element an axis-aligned dim visually "straightens"
+  // it by masking the rotated corners.
+  const frame = readElementCropFrame(selection.element, overlayRect);
+  const width = frame.width / frame.scaleX; // element CSS px
+  const height = frame.height / frame.scaleY;
+  // Crop rect in FRAME-LOCAL coordinates (origin = frame top-left).
+  const cropRect = cropRectFromInsets(
+    { left: 0, top: 0, width: frame.width, height: frame.height },
+    state.insets,
+    frame.scaleX,
+    frame.scaleY,
+  );
 
   const startCropGesture = (edge: CropEdge | "move", event: ReactPointerEvent<HTMLElement>) => {
     if (!onStyleCommit) return;
@@ -151,6 +166,9 @@ export function DomEditCropHandles({
       startY: event.clientY,
       startInsets: state.insets,
       didMove: false,
+      angleDeg: frame.angleDeg,
+      scaleX: frame.scaleX,
+      scaleY: frame.scaleY,
     };
     // Clip is already lifted by the selection effect; just flag the drag so the
     // rule-of-thirds grid shows.
@@ -162,12 +180,17 @@ export function DomEditCropHandles({
     if (!gesture || gesture.pointerId !== event.pointerId) return;
     event.preventDefault();
     event.stopPropagation();
+    const local = rotateDeltaIntoFrame(
+      event.clientX - gesture.startX,
+      event.clientY - gesture.startY,
+      gesture.angleDeg,
+    );
     const drag = {
       startInsets: gesture.startInsets,
-      deltaX: event.clientX - gesture.startX,
-      deltaY: event.clientY - gesture.startY,
-      scaleX,
-      scaleY,
+      deltaX: local.deltaX,
+      deltaY: local.deltaY,
+      scaleX: gesture.scaleX,
+      scaleY: gesture.scaleY,
     };
     const nextInsets =
       gesture.edge === "move"
@@ -225,24 +248,27 @@ export function DomEditCropHandles({
   if (!state.croppable) return null;
 
   return (
-    <>
+    <div
+      data-dom-edit-crop-frame="true"
+      className="pointer-events-none absolute"
+      style={{
+        left: frame.left,
+        top: frame.top,
+        width: frame.width,
+        height: frame.height,
+        transform: frame.angleDeg !== 0 ? `rotate(${frame.angleDeg}deg)` : undefined,
+      }}
+    >
       {/* Dim the cropped-away area whenever the element is cropped and selected,
-          so the hidden content is visible (ghosted) without dragging. */}
+          so the hidden content is visible (ghosted) without dragging. Clipped to
+          the element's own (rotated) box. */}
       {hasCrop && (
-        <div
-          className="pointer-events-none absolute overflow-hidden"
-          style={{
-            left: overlayRect.left,
-            top: overlayRect.top,
-            width: overlayRect.width,
-            height: overlayRect.height,
-          }}
-        >
+        <div className="pointer-events-none absolute inset-0 overflow-hidden">
           <div
             className="absolute"
             style={{
-              left: cropRect.left - overlayRect.left,
-              top: cropRect.top - overlayRect.top,
+              left: cropRect.left,
+              top: cropRect.top,
               width: cropRect.width,
               height: cropRect.height,
               boxShadow: "0 0 0 100000px rgba(8, 8, 12, 0.6)",
@@ -324,6 +350,6 @@ export function DomEditCropHandles({
           />
         );
       })}
-    </>
+    </div>
   );
 }
diff --git a/packages/studio/src/components/editor/domEditOverlayCrop.test.ts b/packages/studio/src/components/editor/domEditOverlayCrop.test.ts
index a23abc0e74..9831f06ed3 100644
--- a/packages/studio/src/components/editor/domEditOverlayCrop.test.ts
+++ b/packages/studio/src/components/editor/domEditOverlayCrop.test.ts
@@ -2,9 +2,11 @@ import { describe, expect, it } from "vitest";
 import {
   cropRectFromInsets,
   hugRectForElement,
+  readElementCropFrame,
   readElementCropInsets,
   resolveCropInsetFromEdgeDrag,
   resolveCropInsetFromMoveDrag,
+  rotateDeltaIntoFrame,
 } from "./domEditOverlayCrop";
 
 describe("resolveCropInsetFromEdgeDrag", () => {
@@ -151,3 +153,91 @@ describe("readElementCropInsets tri-state", () => {
     expect(hugRectForElement(rect, fakeEl("circle(50%)"))).toEqual(rect);
   });
 });
+
+// Regression: crop UI drawn on the axis-aligned bounding box visually
+// "straightens" a rotated element — the dim masks the rotated corners. The
+// frame gives the element's own box + rotation so the UI rotates with it.
+describe("readElementCropFrame", () => {
+  const overlayRect = { left: 100, top: 50, width: 220, height: 130, editScaleX: 1, editScaleY: 1 };
+
+  const fakeEl = (transform: string, offsetWidth = 200, offsetHeight = 100) =>
+    ({
+      offsetWidth,
+      offsetHeight,
+      ownerDocument: { defaultView: { getComputedStyle: () => ({ transform }) } },
+    }) as unknown as HTMLElement;
+
+  it("identity transform → the axis-aligned overlay rect", () => {
+    expect(readElementCropFrame(fakeEl("none"), overlayRect)).toEqual({
+      angleDeg: 0,
+      left: 100,
+      top: 50,
+      width: 220,
+      height: 130,
+      scaleX: 1,
+      scaleY: 1,
+    });
+  });
+
+  it("rotated element → its own box, centered on the AABB, with the angle", () => {
+    // rotate(30deg): matrix(cos, sin, -sin, cos, tx, ty)
+    const cos = Math.cos(Math.PI / 6);
+    const sin = Math.sin(Math.PI / 6);
+    const frame = readElementCropFrame(
+      fakeEl(`matrix(${cos}, ${sin}, ${-sin}, ${cos}, 10, 20)`),
+      overlayRect,
+    );
+    expect(frame.angleDeg).toBeCloseTo(30, 3);
+    expect(frame.width).toBeCloseTo(200, 3);
+    expect(frame.height).toBeCloseTo(100, 3);
+    // centered on the AABB center (210, 115)
+    expect(frame.left + frame.width / 2).toBeCloseTo(210, 3);
+    expect(frame.top + frame.height / 2).toBeCloseTo(115, 3);
+    expect(frame.scaleX).toBeCloseTo(1, 3);
+  });
+
+  it("scaled element → scale factored into px-per-element-px", () => {
+    const frame = readElementCropFrame(fakeEl("matrix(1.5, 0, 0, 2, 0, 0)"), overlayRect);
+    expect(frame.angleDeg).toBe(0);
+    expect(frame.scaleX).toBeCloseTo(1.5, 3);
+    expect(frame.scaleY).toBeCloseTo(2, 3);
+    expect(frame.width).toBeCloseTo(300, 3);
+    expect(frame.height).toBeCloseTo(200, 3);
+  });
+
+  it("3D transform falls back to the axis-aligned frame", () => {
+    const frame = readElementCropFrame(
+      fakeEl("matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1)"),
+      overlayRect,
+    );
+    expect(frame).toEqual({
+      angleDeg: 0,
+      left: 100,
+      top: 50,
+      width: 220,
+      height: 130,
+      scaleX: 1,
+      scaleY: 1,
+    });
+  });
+});
+
+describe("rotateDeltaIntoFrame", () => {
+  it("passes deltas through at 0deg", () => {
+    expect(rotateDeltaIntoFrame(10, 5, 0)).toEqual({ deltaX: 10, deltaY: 5 });
+  });
+
+  it("rotates a screen delta into a 90deg-rotated frame", () => {
+    // Element rotated +90°: dragging DOWN on screen moves along the element's +x.
+    const { deltaX, deltaY } = rotateDeltaIntoFrame(0, 10, 90);
+    expect(deltaX).toBeCloseTo(10, 6);
+    expect(deltaY).toBeCloseTo(0, 6);
+  });
+
+  it("round-trips a 30deg rotation", () => {
+    const local = rotateDeltaIntoFrame(7, -3, 30);
+    const back = rotateDeltaIntoFrame(local.deltaX, local.deltaY, -30);
+    expect(back.deltaX).toBeCloseTo(7, 6);
+    expect(back.deltaY).toBeCloseTo(-3, 6);
+  });
+});
diff --git a/packages/studio/src/components/editor/domEditOverlayCrop.ts b/packages/studio/src/components/editor/domEditOverlayCrop.ts
index 4f0e7dd7fc..cfff9daf42 100644
--- a/packages/studio/src/components/editor/domEditOverlayCrop.ts
+++ b/packages/studio/src/components/editor/domEditOverlayCrop.ts
@@ -122,3 +122,91 @@ export function hugRectForElement(
     return rect;
   return cropRectFromInsets(rect, insets, rect.editScaleX, rect.editScaleY);
 }
+
+/**
+ * The element's own (unrotated) box in overlay space, plus the rotation to
+ * apply when drawing crop UI over it. `clip-path` applies in the element's
+ * LOCAL frame — before its transform — so the crop dim/outline/handles must be
+ * drawn rotated with the element, not on its axis-aligned bounding box: an
+ * AABB-drawn dim visually "straightens" a rotated element by masking its
+ * corners (the crop window looks axis-aligned while the pixels are not).
+ *
+ * scaleX/scaleY are overlay px per element CSS px (element's own scale × the
+ * editor zoom), so element-space insets map straight onto the frame. Assumes
+ * the default 50%/50% transform-origin (the GSAP/studio convention). 3D or
+ * unparseable transforms fall back to the axis-aligned frame (angle 0, AABB
+ * box) — the pre-existing presentation.
+ */
+export interface CropFrame {
+  angleDeg: number;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+export function readElementCropFrame(
+  element: HTMLElement,
+  overlayRect: CropScreenRect & { editScaleX: number; editScaleY: number },
+): CropFrame {
+  const editX = overlayRect.editScaleX > 0 ? overlayRect.editScaleX : 1;
+  const editY = overlayRect.editScaleY > 0 ? overlayRect.editScaleY : 1;
+  const aabb: CropFrame = {
+    angleDeg: 0,
+    left: overlayRect.left,
+    top: overlayRect.top,
+    width: overlayRect.width,
+    height: overlayRect.height,
+    scaleX: editX,
+    scaleY: editY,
+  };
+  let transform = "";
+  try {
+    transform = element.ownerDocument.defaultView?.getComputedStyle(element).transform ?? "";
+  } catch {
+    return aabb;
+  }
+  if (!transform || transform === "none") return aabb;
+  const m = /^matrix\(([^)]+)\)$/.exec(transform);
+  if (!m) return aabb; // matrix3d or unparseable → axis-aligned fallback
+  const [a, b, c, d] = m[1]!.split(",").map((v) => Number.parseFloat(v));
+  if (![a, b, c, d].every(Number.isFinite)) return aabb;
+  const elScaleX = Math.hypot(a!, b!);
+  const det = a! * d! - b! * c!;
+  const elScaleY = elScaleX !== 0 ? det / elScaleX : 1;
+  if (elScaleX <= 0 || elScaleY <= 0) return aabb;
+  const angleDeg = (Math.atan2(b!, a!) * 180) / Math.PI;
+  const scaleX = elScaleX * editX;
+  const scaleY = elScaleY * editY;
+  const width = element.offsetWidth * scaleX;
+  const height = element.offsetHeight * scaleY;
+  if (!(width > 0) || !(height > 0)) return aabb;
+  // Rotation about the default center keeps the center invariant, so the
+  // local box is centered on the AABB center.
+  const cx = overlayRect.left + overlayRect.width / 2;
+  const cy = overlayRect.top + overlayRect.height / 2;
+  return {
+    angleDeg,
+    left: cx - width / 2,
+    top: cy - height / 2,
+    width,
+    height,
+    scaleX,
+    scaleY,
+  };
+}
+
+/** Rotate a screen-space pointer delta into the element's local frame. */
+export function rotateDeltaIntoFrame(
+  deltaX: number,
+  deltaY: number,
+  angleDeg: number,
+): { deltaX: number; deltaY: number } {
+  if (angleDeg === 0) return { deltaX, deltaY };
+  const rad = (-angleDeg * Math.PI) / 180;
+  const cos = Math.cos(rad);
+  const sin = Math.sin(rad);
+  return { deltaX: deltaX * cos - deltaY * sin, deltaY: deltaX * sin + deltaY * cos };
+}

From a83088c0a8e061b88ceae7bffdfbd0e6b31d58d6 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 11 Jul 2026 15:59:07 -0400
Subject: [PATCH 14/24] chore: release v0.7.53

---
 .claude-plugin/plugin.json               |  2 +-
 .codex-plugin/plugin.json                |  2 +-
 .cursor-plugin/plugin.json               |  2 +-
 docs/changelog.mdx                       | 36 ++++++++++++++++++++++++
 packages/aws-lambda/package.json         |  2 +-
 packages/cli/package.json                |  2 +-
 packages/core/package.json               |  2 +-
 packages/engine/package.json             |  2 +-
 packages/gcp-cloud-run/package.json      |  2 +-
 packages/lint/package.json               |  2 +-
 packages/parsers/package.json            |  2 +-
 packages/player/package.json             |  2 +-
 packages/producer/package.json           |  2 +-
 packages/sdk/package.json                |  2 +-
 packages/shader-transitions/package.json |  2 +-
 packages/studio-server/package.json      |  2 +-
 packages/studio/package.json             |  2 +-
 releases/v0.7.53.md                      | 35 +++++++++++++++++++++++
 18 files changed, 87 insertions(+), 16 deletions(-)
 create mode 100644 releases/v0.7.53.md

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 8de32b78ef..f3f932b3f3 100644
--- a/.claude-plugin/plugin.json
+++ b/.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-to-video capture for HyperFrames.",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "author": {
     "name": "HeyGen",
     "email": "hyperframes@heygen.com",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 8ec23b2c9e..a2f82af212 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
   "author": {
     "name": "HeyGen",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index cc13850366..aa8a208699 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "$schema": "https://cursor.com/schemas/cursor-plugin/plugin.json",
   "name": "hyperframes",
   "displayName": "HyperFrames by HeyGen",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
   "author": {
     "name": "HeyGen",
diff --git a/docs/changelog.mdx b/docs/changelog.mdx
index ddb0851332..f2e0cd6953 100644
--- a/docs/changelog.mdx
+++ b/docs/changelog.mdx
@@ -8,6 +8,42 @@ 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.7.53"
+  description="Released - 2026-07-11"
+  tags={["Release", "Studio", "Producer", "Core"]}
+>
+This release makes studio manual editing safe for color-graded compositions: edits no longer bake runtime opacity transients into tween bounds (the "element disappears after editing" bug), resize and rotate commit clean per-group values, selecting an element no longer rewrites or destroys its authored clip-path, and the crop tool draws in the element's rotated frame. The GSAP writers also stop accumulating duplicate keys in saved compositions.
+
+## Fixes
+
+- **Studio:** Draw the crop UI in the element's rotated frame ([39f33bd3a](https://github.com/heygen-com/hyperframes/commit/39f33bd3a3bcd2ea20980bca1e871bbc9c6592f3))
+- **Studio:** Address review findings on graded-element editing ([5d1cafff8](https://github.com/heygen-com/hyperframes/commit/5d1cafff8225177ee1ae99da85a0ce0ce4e5babd))
+- **Studio:** Crop restore value is owned by the lifted element's gesture ([b7fddd548](https://github.com/heygen-com/hyperframes/commit/b7fddd548acf1d268294a7fe71adc9a946ccaa40))
+- **Core:** Make timing masks safe for source loaders ([179c942cd](https://github.com/heygen-com/hyperframes/commit/179c942cd2bb3fb37236368fa33b16c4c1ad58a0))
+- **Lint:** Anchor the opacity-zero probe so 0.98 stops matching ([fe5296672](https://github.com/heygen-com/hyperframes/commit/fe529667283ad07a2f3cd8440e285ad3d0fc8937))
+- **Parsers:** Never emit duplicate vars keys in either writer ([90d77d016](https://github.com/heygen-com/hyperframes/commit/90d77d016ffb75264491bfebb4c227072904d63d))
+- **Studio:** Route panel property commits to a group-owning set ([066c3dae3](https://github.com/heygen-com/hyperframes/commit/066c3dae37bbe3397cfc35642076dd30da9743f3))
+- **Studio:** Crop tool stands down for clips it cannot edit ([cbfb6ba94](https://github.com/heygen-com/hyperframes/commit/cbfb6ba943ea458bb79f89bbc0611cd81c817831))
+- **Studio:** Correct gesture commits for scaled and graded elements ([3525c7ff5](https://github.com/heygen-com/hyperframes/commit/3525c7ff52139a5d63093f7a8863e7fb8ff980e6))
+- **Studio:** Stop tween re-inits from baking runtime opacity transients ([5cc14c222](https://github.com/heygen-com/hyperframes/commit/5cc14c2221bb6262ddd0631c9f2df1891f266217))
+- **Core:** Capture authored inline opacity at parse time and follow source geometry ([3147c8e06](https://github.com/heygen-com/hyperframes/commit/3147c8e063a72d999447aca8bb0528480bdcd043))
+- **Product Launch:** Hoist approved frame videos during assembly ([2aadf450e](https://github.com/heygen-com/hyperframes/commit/2aadf450e718497ac4b0edb7286cf4c8f3da06bc), [#2226](https://github.com/heygen-com/hyperframes/pull/2226))
+- **Hooks:** Scope pre-commit build check to target repo, fix stale symlinks ([522d7c93b](https://github.com/heygen-com/hyperframes/commit/522d7c93b7acb16c6ade1376040237ff615dca7b), [#2175](https://github.com/heygen-com/hyperframes/pull/2175))
+- **Lint:** Parse HTML structure without regex ([05c3b5503](https://github.com/heygen-com/hyperframes/commit/05c3b5503faf5da1efe5d64985b63db3f762f765), [#2223](https://github.com/heygen-com/hyperframes/pull/2223))
+- **Telemetry:** Expose stalled render stages ([87618eef4](https://github.com/heygen-com/hyperframes/commit/87618eef4c65aff78f99f94246c60114a579af0f), [#2220](https://github.com/heygen-com/hyperframes/pull/2220))
+- **Lint:** Flag digit-leading element ids ([d51fa7eba](https://github.com/heygen-com/hyperframes/commit/d51fa7eba2e369fd6212cdc59ebaef71e2024f7e), [#2222](https://github.com/heygen-com/hyperframes/pull/2222))
+- **CLI:** Correct strict warning hint ([5f22209a8](https://github.com/heygen-com/hyperframes/commit/5f22209a82afbdf3c2a8d1a788b94e9aeeaac689), [#2221](https://github.com/heygen-com/hyperframes/pull/2221))
+
+## Internal
+
+- Address review nits ([67cfae258](https://github.com/heygen-com/hyperframes/commit/67cfae2587e15b0dd6a064d9fdbd4790831905cf))
+- **Producer:** Gate source tests by execution lane ([9e7b11998](https://github.com/heygen-com/hyperframes/commit/9e7b11998cb2727b05337f9133eae4647c979644))
+- **Repo:** Forbid tracked generated artifacts ([585aa9f6b](https://github.com/heygen-com/hyperframes/commit/585aa9f6b24561fe45ea298787a291390ba8eea2))
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.7.52...v0.7.53).
+</Update>
+
 <Update
   label="HyperFrames v0.7.52"
   description="Released - 2026-07-11"
diff --git a/packages/aws-lambda/package.json b/packages/aws-lambda/package.json
index cdaf1d8f08..8fb311a769 100644
--- a/packages/aws-lambda/package.json
+++ b/packages/aws-lambda/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/aws-lambda",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "AWS Lambda adapter for HyperFrames distributed rendering — handler, client-side SDK, and CDK construct.",
   "repository": {
     "type": "git",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 5283fe7fb7..78d7d31bcf 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
diff --git a/packages/core/package.json b/packages/core/package.json
index 40f63d40b0..b7662086a5 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/core",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "",
   "repository": {
     "type": "git",
diff --git a/packages/engine/package.json b/packages/engine/package.json
index e4b0b86947..7e68edf0fb 100644
--- a/packages/engine/package.json
+++ b/packages/engine/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
diff --git a/packages/gcp-cloud-run/package.json b/packages/gcp-cloud-run/package.json
index 5b73c257a8..9cfa025fda 100644
--- a/packages/gcp-cloud-run/package.json
+++ b/packages/gcp-cloud-run/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/gcp-cloud-run",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Google Cloud Run + Workflows adapter for HyperFrames distributed rendering — request handler, client-side SDK, and Terraform module.",
   "repository": {
     "type": "git",
diff --git a/packages/lint/package.json b/packages/lint/package.json
index 58b3456fa5..75f7fb8894 100644
--- a/packages/lint/package.json
+++ b/packages/lint/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/lint",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
diff --git a/packages/parsers/package.json b/packages/parsers/package.json
index 772991744d..8615c3c3a3 100644
--- a/packages/parsers/package.json
+++ b/packages/parsers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/parsers",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
diff --git a/packages/player/package.json b/packages/player/package.json
index 6243e08a57..a674f0fc6e 100644
--- a/packages/player/package.json
+++ b/packages/player/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/player",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Embeddable web component for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/producer/package.json b/packages/producer/package.json
index aa417d3912..87fc51256e 100644
--- a/packages/producer/package.json
+++ b/packages/producer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index b8c101cbb2..9539cfd17e 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/sdk",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "Headless, framework-neutral HyperFrames composition editing engine",
   "repository": {
     "type": "git",
diff --git a/packages/shader-transitions/package.json b/packages/shader-transitions/package.json
index fa72e1e35e..c4eb410805 100644
--- a/packages/shader-transitions/package.json
+++ b/packages/shader-transitions/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/shader-transitions",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "WebGL shader transitions for HyperFrames compositions",
   "repository": {
     "type": "git",
diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json
index 31e70c7b46..f59b29739e 100644
--- a/packages/studio-server/package.json
+++ b/packages/studio-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio-server",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 44b738a19c..01c6217d7e 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.52",
+  "version": "0.7.53",
   "description": "",
   "repository": {
     "type": "git",
diff --git a/releases/v0.7.53.md b/releases/v0.7.53.md
new file mode 100644
index 0000000000..52c0ba81c7
--- /dev/null
+++ b/releases/v0.7.53.md
@@ -0,0 +1,35 @@
+# HyperFrames v0.7.53
+
+Released on 2026-07-11.
+
+This release makes studio manual editing safe for color-graded compositions: edits no longer bake runtime opacity transients into tween bounds (the "element disappears after editing" bug), resize and rotate commit clean per-group values, selecting an element no longer rewrites or destroys its authored clip-path, and the crop tool draws in the element's rotated frame. The GSAP writers also stop accumulating duplicate keys in saved compositions.
+
+## Fixes
+
+- **Studio:** Draw the crop UI in the element's rotated frame ([39f33bd3a](https://github.com/heygen-com/hyperframes/commit/39f33bd3a3bcd2ea20980bca1e871bbc9c6592f3))
+- **Studio:** Address review findings on graded-element editing ([5d1cafff8](https://github.com/heygen-com/hyperframes/commit/5d1cafff8225177ee1ae99da85a0ce0ce4e5babd))
+- **Studio:** Crop restore value is owned by the lifted element's gesture ([b7fddd548](https://github.com/heygen-com/hyperframes/commit/b7fddd548acf1d268294a7fe71adc9a946ccaa40))
+- **Core:** Make timing masks safe for source loaders ([179c942cd](https://github.com/heygen-com/hyperframes/commit/179c942cd2bb3fb37236368fa33b16c4c1ad58a0))
+- **Lint:** Anchor the opacity-zero probe so 0.98 stops matching ([fe5296672](https://github.com/heygen-com/hyperframes/commit/fe529667283ad07a2f3cd8440e285ad3d0fc8937))
+- **Parsers:** Never emit duplicate vars keys in either writer ([90d77d016](https://github.com/heygen-com/hyperframes/commit/90d77d016ffb75264491bfebb4c227072904d63d))
+- **Studio:** Route panel property commits to a group-owning set ([066c3dae3](https://github.com/heygen-com/hyperframes/commit/066c3dae37bbe3397cfc35642076dd30da9743f3))
+- **Studio:** Crop tool stands down for clips it cannot edit ([cbfb6ba94](https://github.com/heygen-com/hyperframes/commit/cbfb6ba943ea458bb79f89bbc0611cd81c817831))
+- **Studio:** Correct gesture commits for scaled and graded elements ([3525c7ff5](https://github.com/heygen-com/hyperframes/commit/3525c7ff52139a5d63093f7a8863e7fb8ff980e6))
+- **Studio:** Stop tween re-inits from baking runtime opacity transients ([5cc14c222](https://github.com/heygen-com/hyperframes/commit/5cc14c2221bb6262ddd0631c9f2df1891f266217))
+- **Core:** Capture authored inline opacity at parse time and follow source geometry ([3147c8e06](https://github.com/heygen-com/hyperframes/commit/3147c8e063a72d999447aca8bb0528480bdcd043))
+- **Product Launch:** Hoist approved frame videos during assembly ([2aadf450e](https://github.com/heygen-com/hyperframes/commit/2aadf450e718497ac4b0edb7286cf4c8f3da06bc), [#2226](https://github.com/heygen-com/hyperframes/pull/2226))
+- **Hooks:** Scope pre-commit build check to target repo, fix stale symlinks ([522d7c93b](https://github.com/heygen-com/hyperframes/commit/522d7c93b7acb16c6ade1376040237ff615dca7b), [#2175](https://github.com/heygen-com/hyperframes/pull/2175))
+- **Lint:** Parse HTML structure without regex ([05c3b5503](https://github.com/heygen-com/hyperframes/commit/05c3b5503faf5da1efe5d64985b63db3f762f765), [#2223](https://github.com/heygen-com/hyperframes/pull/2223))
+- **Telemetry:** Expose stalled render stages ([87618eef4](https://github.com/heygen-com/hyperframes/commit/87618eef4c65aff78f99f94246c60114a579af0f), [#2220](https://github.com/heygen-com/hyperframes/pull/2220))
+- **Lint:** Flag digit-leading element ids ([d51fa7eba](https://github.com/heygen-com/hyperframes/commit/d51fa7eba2e369fd6212cdc59ebaef71e2024f7e), [#2222](https://github.com/heygen-com/hyperframes/pull/2222))
+- **CLI:** Correct strict warning hint ([5f22209a8](https://github.com/heygen-com/hyperframes/commit/5f22209a82afbdf3c2a8d1a788b94e9aeeaac689), [#2221](https://github.com/heygen-com/hyperframes/pull/2221))
+
+## Internal
+
+- Address review nits ([67cfae258](https://github.com/heygen-com/hyperframes/commit/67cfae2587e15b0dd6a064d9fdbd4790831905cf))
+- **Producer:** Gate source tests by execution lane ([9e7b11998](https://github.com/heygen-com/hyperframes/commit/9e7b11998cb2727b05337f9133eae4647c979644))
+- **Repo:** Forbid tracked generated artifacts ([585aa9f6b](https://github.com/heygen-com/hyperframes/commit/585aa9f6b24561fe45ea298787a291390ba8eea2))
+
+## Full changelog
+
+https://github.com/heygen-com/hyperframes/compare/v0.7.52...v0.7.53

From 3e2cf63fd51685702b7f0338d8fe725ef8fb4b36 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 11:59:12 -0700
Subject: [PATCH 15/24] fix(producer,engine): gate drawelement on ancestor
 background-image + tail verify sample

---
 ...frameCapture-verifySampleFractions.test.ts | 36 +++++++++++
 packages/engine/src/services/frameCapture.ts  | 15 ++++-
 .../src/services/htmlCompiler.test.ts         | 60 ++++++++++++++++++
 .../producer/src/services/htmlCompiler.ts     | 62 +++++++++++++++++++
 .../services/render/stages/compileStage.ts    | 22 +++++++
 5 files changed, 194 insertions(+), 1 deletion(-)
 create mode 100644 packages/engine/src/services/frameCapture-verifySampleFractions.test.ts

diff --git a/packages/engine/src/services/frameCapture-verifySampleFractions.test.ts b/packages/engine/src/services/frameCapture-verifySampleFractions.test.ts
new file mode 100644
index 0000000000..a7da475e9b
--- /dev/null
+++ b/packages/engine/src/services/frameCapture-verifySampleFractions.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { computeDeVerifySampleFractions } from "./frameCapture.js";
+
+describe("computeDeVerifySampleFractions", () => {
+  it("pins the last sample at 95% so late-onset damage is sampled", () => {
+    const fractions = computeDeVerifySampleFractions(4);
+    expect(fractions).toEqual([0.25, 0.5, 0.75, 0.95]);
+  });
+
+  it("keeps the requested sample count", () => {
+    for (const k of [1, 2, 3, 4, 8]) {
+      expect(computeDeVerifySampleFractions(k)).toHaveLength(k);
+    }
+  });
+
+  it("uses only the tail sample when k is 1", () => {
+    expect(computeDeVerifySampleFractions(1)).toEqual([0.95]);
+  });
+
+  it("returns an empty grid when verification is disabled", () => {
+    expect(computeDeVerifySampleFractions(0)).toEqual([]);
+    expect(computeDeVerifySampleFractions(-2)).toEqual([]);
+  });
+
+  it("stays strictly increasing within (0, 1) for every supported k", () => {
+    for (let k = 1; k <= 8; k++) {
+      const fractions = computeDeVerifySampleFractions(k);
+      for (let i = 0; i < fractions.length; i++) {
+        const f = fractions[i] ?? 0;
+        expect(f).toBeGreaterThan(0);
+        expect(f).toBeLessThan(1);
+        if (i > 0) expect(f).toBeGreaterThan(fractions[i - 1] ?? 0);
+      }
+    }
+  });
+});
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 08055386c9..d6c20d6ba1 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -3107,6 +3107,19 @@ export async function getCompositionDuration(session: CaptureSession): Promise<n
  * init-time screenshot → the render falls back to the screenshot path (slower,
  * never wrong). Cost when passing: ~K×(seek+screenshot) ≈ 150–300ms at init.
  */
+/**
+ * Timeline fractions the self-verify samples. First k-1 evenly spaced, last
+ * pinned at 95%: late-onset damage (an end-of-comp reveal exposing pixels DE
+ * paints wrong) was invisible to the old (i+1)/(k+1) grid, whose final sample
+ * sat at 80% — measured miss: a body-gradient drop starting at ~79% of the
+ * timeline passed verification while the drained output bottomed at 30.9 dB.
+ */
+export function computeDeVerifySampleFractions(k: number): number[] {
+  if (k <= 0) return [];
+  if (k === 1) return [0.95];
+  return [...Array.from({ length: k - 1 }, (_, i) => (i + 1) / k), 0.95];
+}
+
 async function captureDeVerificationFrames(
   session: CaptureSession,
   page: Page,
@@ -3153,7 +3166,7 @@ async function captureDeVerificationFrames(
   // render (the detectCssEffectRisk lesson), and because DE frames and truth
   // would share the corruption, PSNR would pass on the damaged output.
   // Seeking 0 → ascending reproduces the render's own seek order.
-  const fractions = Array.from({ length: k }, (_, i) => (i + 1) / (k + 1));
+  const fractions = computeDeVerifySampleFractions(k);
   const seekTo = async (t: number): Promise<void> => {
     await page.evaluate((tt: number) => {
       const hf = (
diff --git a/packages/producer/src/services/htmlCompiler.test.ts b/packages/producer/src/services/htmlCompiler.test.ts
index 2fa6573ddc..55dcb47512 100644
--- a/packages/producer/src/services/htmlCompiler.test.ts
+++ b/packages/producer/src/services/htmlCompiler.test.ts
@@ -8,6 +8,7 @@ import {
   collectExternalAssets,
   compileForRender,
   injectSdkPositionEditsRenderScript,
+  detectAncestorBackgroundImage,
   detectRenderModeHints,
   detectShaderTransitionUsage,
   detectThreeDTransformUsage,
@@ -718,6 +719,65 @@ describe("detectThreeDTransformUsage", () => {
   });
 });
 
+describe("detectAncestorBackgroundImage", () => {
+  const wrap = (headCss: string, bodyAttrs = "", inner = "") =>
+    `<!doctype html><html><head><style>${headCss}</style></head><body${bodyAttrs ? ` ${bodyAttrs}` : ""}>` +
+    `<div id="root" data-composition-id="main" data-duration="10">${inner}</div></body></html>`;
+
+  it("detects a linear-gradient body background from a style rule", () => {
+    expect(
+      detectAncestorBackgroundImage(
+        wrap("body { background: linear-gradient(135deg, #1b2735, #090a0f); }"),
+      ),
+    ).toBe(true);
+  });
+
+  it("detects a url() background-image on html", () => {
+    expect(detectAncestorBackgroundImage(wrap('html { background-image: url("bg.png"); }'))).toBe(
+      true,
+    );
+  });
+
+  it("detects an inline gradient style on body", () => {
+    expect(
+      detectAncestorBackgroundImage(
+        wrap("", 'style="background: radial-gradient(circle, #111, #000)"'),
+      ),
+    ).toBe(true);
+  });
+
+  it("detects a class-selected wrapper between body and the root", () => {
+    const html =
+      "<!doctype html><html><head><style>.page-bg { background-image: linear-gradient(#111, #000); }</style></head>" +
+      '<body><div class="page-bg"><div data-composition-id="main" data-duration="10"></div></div></body></html>';
+    expect(detectAncestorBackgroundImage(html)).toBe(true);
+  });
+
+  it("ignores background-image on elements inside the composition root", () => {
+    expect(
+      detectAncestorBackgroundImage(
+        wrap(
+          "#hero { background-image: linear-gradient(#111, #000); }",
+          "",
+          '<div id="hero"></div>',
+        ),
+      ),
+    ).toBe(false);
+  });
+
+  it("ignores plain background-color ancestors", () => {
+    expect(detectAncestorBackgroundImage(wrap("html, body { background: #0d1117; }"))).toBe(false);
+  });
+
+  it("returns false without a composition root", () => {
+    expect(
+      detectAncestorBackgroundImage(
+        "<html><head><style>body { background: linear-gradient(#111, #000); }</style></head><body></body></html>",
+      ),
+    ).toBe(false);
+  });
+});
+
 describe("detectShaderTransitionUsage", () => {
   it("detects authored HyperShader initialization", () => {
     const html = `<!doctype html>
diff --git a/packages/producer/src/services/htmlCompiler.ts b/packages/producer/src/services/htmlCompiler.ts
index 37dd29cf81..65d20b1457 100644
--- a/packages/producer/src/services/htmlCompiler.ts
+++ b/packages/producer/src/services/htmlCompiler.ts
@@ -78,6 +78,8 @@ export interface CompiledComposition {
   usesThreeDTransforms: boolean;
   /** Author HTML/CSS use mix-blend-mode (pre-CDN-inline scan). */
   usesMixBlendMode: boolean;
+  /** Ancestors of the composition root carry a background-image (gradient/url). */
+  hasAncestorBackgroundImage: boolean;
 }
 
 /** Adapts linkedom's `parseHTML` to the `checkSubCompositionUsability` contract. */
@@ -324,6 +326,64 @@ function detectMixBlendModeUsage(html: string): boolean {
   return MIX_BLEND_MODE_PATTERN.test(html);
 }
 
+/** A background declaration whose value paints an image (gradient or url). */
+const BACKGROUND_IMAGE_DECL_PATTERN =
+  /(?:^|;|\{)\s*background(?:-image)?\s*:[^;}]*(?:\bgradient\s*\(|url\s*\()/i;
+
+/**
+ * Background-image signals on ancestors of the composition root.
+ * drawElementImage only paints the captured subtree; drawElementService's
+ * per-frame ancestor fill replicates what lies behind it by walking up the
+ * DOM for the nearest non-transparent `backgroundColor`. A background-IMAGE
+ * (linear-gradient, url) on <body>/<html>/a wrapper reads as transparent in
+ * that scan, so a deeper ancestor's solid color paints instead — measured:
+ * a body `linear-gradient` replaced by the html background color wherever
+ * the subtree left pixels uncovered (30.9 dB min vs baseline), and the
+ * damage can set in late enough to slip past the self-verify sample grid.
+ * Backgrounds on elements INSIDE the root are painted correctly and are
+ * deliberately not matched — this walks only the root's ancestor chain and
+ * the style rules that select into it.
+ */
+export function detectAncestorBackgroundImage(html: string): boolean {
+  const { document } = parseHTML(html);
+  const root = document.querySelector("[data-composition-id]");
+  if (!root) return false;
+  const ancestors: Element[] = [];
+  for (let el = root.parentElement; el; el = el.parentElement) ancestors.push(el);
+  if (document.documentElement && !ancestors.includes(document.documentElement)) {
+    ancestors.push(document.documentElement);
+  }
+  // Inline styles on the ancestor chain.
+  for (const el of ancestors) {
+    const style = el.getAttribute("style");
+    if (style && BACKGROUND_IMAGE_DECL_PATTERN.test(`{${style}}`)) return true;
+  }
+  // <style> rules: any rule carrying an image-painting background declaration
+  // whose selector resolves to an ancestor of the root. Selector matching goes
+  // through querySelectorAll so class/id/compound selectors on wrappers are
+  // covered, not just literal `body`/`html`.
+  for (const styleEl of document.querySelectorAll("style")) {
+    const css = styleEl.textContent ?? "";
+    for (const rule of css.matchAll(/([^{}]+)\{([^}]*)\}/g)) {
+      const [, selectorList = "", declarations = ""] = rule;
+      if (!BACKGROUND_IMAGE_DECL_PATTERN.test(`{${declarations}}`)) continue;
+      for (const selector of selectorList.split(",")) {
+        const sel = selector.trim();
+        if (!sel || sel.startsWith("@")) continue;
+        if (/^(?:html|:root)$/i.test(sel)) return true;
+        try {
+          for (const matched of document.querySelectorAll(sel)) {
+            if (ancestors.includes(matched)) return true;
+          }
+        } catch {
+          // Selector syntax linkedom can't parse (e.g. vendor pseudo) — skip.
+        }
+      }
+    }
+  }
+  return false;
+}
+
 const SHADER_TRANSITION_USAGE_PATTERN =
   /\b(?:(?:window|globalThis)\s*\.\s*)?HyperShader\s*\.\s*init\s*\(|\b__hf\s*\.\s*transitions\s*=/;
 
@@ -1706,6 +1766,7 @@ export async function compileForRender(
   // composition that loads GSAP from a CDN.
   const usesThreeDTransforms = detectThreeDTransformUsage(sanitizedHtml);
   const usesMixBlendMode = detectMixBlendModeUsage(sanitizedHtml);
+  const hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);
 
   const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
     injectTextRenderingRule(
@@ -1881,6 +1942,7 @@ export async function compileForRender(
     hasShaderTransitions,
     usesThreeDTransforms,
     usesMixBlendMode,
+    hasAncestorBackgroundImage,
   };
 }
 
diff --git a/packages/producer/src/services/render/stages/compileStage.ts b/packages/producer/src/services/render/stages/compileStage.ts
index a073209619..f9448f34ba 100644
--- a/packages/producer/src/services/render/stages/compileStage.ts
+++ b/packages/producer/src/services/render/stages/compileStage.ts
@@ -200,6 +200,28 @@ export async function runCompileStage(input: CompileStageInput): Promise<Compile
         "for this render. Capture uses the platform's baseline route.",
     );
   }
+  // Fast-capture ancestor-background-image gate, same shape as the gates above.
+  // drawElementService's per-frame ancestor fill replicates only the nearest
+  // non-transparent ancestor background-COLOR behind the captured subtree; a
+  // background-image (linear-gradient, url) on <body>/<html>/a wrapper reads
+  // as transparent there, so a deeper ancestor's solid color paints instead
+  // wherever the subtree leaves pixels uncovered (measured: body gradient
+  // replaced by html color, 30.9 dB min vs baseline — and late-onset, so the
+  // self-verify grid can miss it). HF_FAST_CAPTURE_ANCESTOR_BG=true bypasses
+  // for R&D.
+  if (
+    cfg.useDrawElement &&
+    process.env.HF_FAST_CAPTURE_ANCESTOR_BG !== "true" &&
+    compiled.hasAncestorBackgroundImage
+  ) {
+    cfg.useDrawElement = false;
+    deCompileGate = "ancestor_background_image";
+    log.info(
+      "[Render] Fast capture: composition root's ancestors (body/html/wrapper) carry a " +
+        "background-image — disabling drawElementImage for this render. Capture uses the " +
+        "platform's baseline route.",
+    );
+  }
   // Shader-transition comps: page-side compositing is the faster, purpose-built
   // path for them, and resolveConfig force-disables it whenever drawElement is
   // on. With drawElement default-on that trade is backwards — prefer page-side

From 860ad7dfcf92c5f2c8c8a23528467430a426a9f3 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 12:17:07 -0700
Subject: [PATCH 16/24] fix(producer): withhold de parallel router below a
 machine ram floor

---
 .../src/services/renderOrchestrator.test.ts   | 16 +++++++++++
 .../src/services/renderOrchestrator.ts        | 27 ++++++++++++++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
index 20ccf03b86..2f5d8cf044 100644
--- a/packages/producer/src/services/renderOrchestrator.test.ts
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -1763,12 +1763,28 @@ describe("shouldPreferParallelDrawElement (DE parallel router)", () => {
     probeDeGated: false,
     experimentalParallelDeOptIn: false,
     routerEnabled: true,
+    totalMemoryMb: 32768,
+    minMemoryMb: 24576,
   };
 
   it("routes an auto-resolved multi-worker render for an eligible long comp", () => {
     expect(shouldPreferParallelDrawElement(eligible)).toBe(true);
   });
 
+  it("withholds the parallel bet below the RAM floor (16 GB black-slab report)", () => {
+    expect(shouldPreferParallelDrawElement({ ...eligible, totalMemoryMb: 16384 })).toBe(false);
+  });
+
+  it("routes exactly at the RAM floor", () => {
+    expect(shouldPreferParallelDrawElement({ ...eligible, totalMemoryMb: 24576 })).toBe(true);
+  });
+
+  it("minMemoryMb <= 0 disables the RAM guard", () => {
+    expect(
+      shouldPreferParallelDrawElement({ ...eligible, totalMemoryMb: 8192, minMemoryMb: 0 }),
+    ).toBe(true);
+  });
+
   it("is disabled by default (routerEnabled: false is the shipped default)", () => {
     expect(shouldPreferParallelDrawElement({ ...eligible, routerEnabled: false })).toBe(false);
   });
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 2a493f566c..18ccdb5fef 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -76,6 +76,7 @@ import {
   isDrawElementVerificationError,
 } from "@hyperframes/engine";
 import { join, dirname, resolve } from "path";
+import { totalmem } from "node:os";
 import { randomUUID } from "crypto";
 import { fileURLToPath } from "url";
 import {
@@ -1130,6 +1131,10 @@ export function shouldPreferParallelDrawElement(args: {
   experimentalParallelDeOptIn: boolean;
   /** HF_DE_PARALLEL_ROUTER === "true" — the router's own kill switch, default off. */
   routerEnabled: boolean;
+  /** Machine RAM (os.totalmem, MB). */
+  totalMemoryMb: number;
+  /** RAM floor for routing; <=0 disables the guard. */
+  minMemoryMb: number;
 }): boolean {
   return (
     args.routerEnabled &&
@@ -1144,7 +1149,14 @@ export function shouldPreferParallelDrawElement(args: {
     !args.layeredOrEffectRoute &&
     !args.supersampling &&
     !args.probeDeGated &&
-    !args.experimentalParallelDeOptIn
+    !args.experimentalParallelDeOptIn &&
+    // RAM floor: routed parallel DE runs 3 concurrent hardware-GPU Chrome
+    // instances. On a 16 GB machine that produced vertical black slabs in the
+    // final MP4 (wild report, CLI 0.7.52) — compositor tiles evicted under
+    // GPU/memory pressure, and sampled self-verify can miss partial-frame
+    // damage. Single-worker DE (the inversion) stays available below the
+    // floor; only the parallel bet is withheld.
+    (args.minMemoryMb <= 0 || args.totalMemoryMb >= args.minMemoryMb)
   );
 }
 
@@ -1919,6 +1931,17 @@ export async function executeRenderJob(
     const deParallelMinFrames = Number.isFinite(deParallelMinFramesNum)
       ? deParallelMinFramesNum
       : 2000;
+    // RAM floor default 24 GB: the wild black-slab report was a 16 GB
+    // machine; every clean routed cohort in telemetry so far is >=24 GB.
+    // HF_DE_PARALLEL_MIN_MEM_MB overrides (0 disables the guard).
+    const deParallelMinMemRaw = process.env.HF_DE_PARALLEL_MIN_MEM_MB;
+    const deParallelMinMemNum =
+      deParallelMinMemRaw === undefined || deParallelMinMemRaw.trim() === ""
+        ? 24576
+        : Number(deParallelMinMemRaw);
+    const deParallelMinMemoryMb = Number.isFinite(deParallelMinMemNum)
+      ? deParallelMinMemNum
+      : 24576;
     const deParallelRouterEligible = shouldPreferParallelDrawElement({
       workerCount: WOULD_RESOLVE_MULTI_WORKER,
       requestedWorkers: job.config.workers,
@@ -1938,6 +1961,8 @@ export async function executeRenderJob(
         process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" ||
         process.env.HF_DE_PARALLEL_STREAM === "true",
       routerEnabled: deParallelRouterEnabled,
+      totalMemoryMb: Math.round(totalmem() / (1024 * 1024)),
+      minMemoryMb: deParallelMinMemoryMb,
     });
     // Declared ahead of resolution (assigned below, after calibration) so
     // captureStageObservationData can close over it for the calibration

From 2767f8168ef4bb3d6b404d7154c1d23c719f4189 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 12:21:08 -0700
Subject: [PATCH 17/24] fix(engine): densify drawelement self-verify with
 parallel worker count

---
 packages/engine/src/services/frameCapture.ts  |  4 ++-
 .../src/services/parallelCoordinator.test.ts  | 22 +++++++++++++++
 .../src/services/parallelCoordinator.ts       | 28 ++++++++++++++++++-
 packages/engine/src/types.ts                  | 10 +++++++
 4 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index d6c20d6ba1..fbde3e5c12 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -3125,7 +3125,9 @@ async function captureDeVerificationFrames(
   page: Page,
   logInitPhase: (phase: string) => void,
 ): Promise<void> {
-  const kRaw = Number(process.env.HF_DE_VERIFY ?? "4");
+  // Explicit HF_DE_VERIFY wins; otherwise the session's own sample count
+  // (raised by the parallel coordinator for multi-worker DE), then default 4.
+  const kRaw = Number(process.env.HF_DE_VERIFY ?? session.options.deVerifySamples ?? "4");
   const k = Number.isFinite(kRaw) ? Math.max(0, Math.min(8, Math.floor(kRaw))) : 4;
   if (k === 0 || process.env.HF_FORCE_DRAWELEMENT === "1") return;
   if (session.options.format === "png") return; // worker-encode drain (the consumer) is jpeg-only
diff --git a/packages/engine/src/services/parallelCoordinator.test.ts b/packages/engine/src/services/parallelCoordinator.test.ts
index ce86bbbecd..1c1a6952bf 100644
--- a/packages/engine/src/services/parallelCoordinator.test.ts
+++ b/packages/engine/src/services/parallelCoordinator.test.ts
@@ -6,6 +6,7 @@ import {
   selectWorkerDiagnostics,
   shouldDisableBrowserPoolForParallelWorker,
   shouldVerifyWorkerGpu,
+  resolveParallelDeVerifySamples,
 } from "./parallelCoordinator.js";
 import type { EngineConfig } from "../config.js";
 
@@ -176,3 +177,24 @@ describe("shouldVerifyWorkerGpu", () => {
     expect(shouldVerifyWorkerGpu(3, undefined)).toBe(false);
   });
 });
+
+describe("resolveParallelDeVerifySamples", () => {
+  it("densifies with worker count: 4 base + 2 per extra worker", () => {
+    expect(resolveParallelDeVerifySamples(undefined, 2)).toBe(6);
+    expect(resolveParallelDeVerifySamples(undefined, 3)).toBe(8);
+  });
+
+  it("clamps at the verify path's max of 8", () => {
+    expect(resolveParallelDeVerifySamples(undefined, 5)).toBe(8);
+    expect(resolveParallelDeVerifySamples(undefined, 16)).toBe(8);
+  });
+
+  it("leaves single-worker capture on the session default", () => {
+    expect(resolveParallelDeVerifySamples(undefined, 1)).toBeUndefined();
+    expect(resolveParallelDeVerifySamples(undefined, 0)).toBeUndefined();
+  });
+
+  it("passes a caller-set value through untouched", () => {
+    expect(resolveParallelDeVerifySamples(2, 3)).toBe(2);
+  });
+});
diff --git a/packages/engine/src/services/parallelCoordinator.ts b/packages/engine/src/services/parallelCoordinator.ts
index f2b766a49c..d2111a6903 100644
--- a/packages/engine/src/services/parallelCoordinator.ts
+++ b/packages/engine/src/services/parallelCoordinator.ts
@@ -459,6 +459,24 @@ async function executeWorkerTask(
   }
 }
 
+/**
+ * drawElement self-verify sample count for multi-worker capture. Each worker
+ * arms the same shared sample grid but drains only ~1/N of it, and N
+ * concurrent hardware-GPU browsers are exactly where compositor-tile damage
+ * shows up (wild 0.7.52 black-slab report) — so density rises with worker
+ * count: 4 base + 2 per extra worker, clamped to the verify path's max of 8.
+ * A caller-set value passes through untouched, and explicit HF_DE_VERIFY
+ * still overrides inside the session.
+ */
+export function resolveParallelDeVerifySamples(
+  callerValue: number | undefined,
+  workerCount: number,
+): number | undefined {
+  if (callerValue !== undefined) return callerValue;
+  if (workerCount <= 1) return undefined;
+  return Math.min(8, 4 + 2 * (workerCount - 1));
+}
+
 export async function executeParallelCapture(
   serverUrl: string,
   workDir: string,
@@ -499,12 +517,20 @@ export async function executeParallelCapture(
   };
 
   const parallel = tasks.length > 1;
+  const deVerifySamples = resolveParallelDeVerifySamples(
+    captureOptions.deVerifySamples,
+    tasks.length,
+  );
+  const workerCaptureOptions: CaptureOptions =
+    deVerifySamples === captureOptions.deVerifySamples
+      ? captureOptions
+      : { ...captureOptions, deVerifySamples };
   const results = await Promise.all(
     tasks.map((task) =>
       executeWorkerTask(
         task,
         serverUrl,
-        captureOptions,
+        workerCaptureOptions,
         createBeforeCaptureHook,
         signal,
         onFrameCaptured,
diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts
index fc267821fe..24507d7ea9 100644
--- a/packages/engine/src/types.ts
+++ b/packages/engine/src/types.ts
@@ -158,6 +158,16 @@ export interface CaptureOptions {
    * warmup loop).
    */
   lockWarmupTicks?: boolean;
+  /**
+   * drawElement self-verify ground-truth sample count for this session.
+   * Overrides the HF_DE_VERIFY default (4). The parallel coordinator raises
+   * it for multi-worker drawElement capture — N concurrent hardware-GPU
+   * browsers widen the damage surface (compositor tile eviction under
+   * GPU/memory pressure), and each worker only drains ~1/N of the shared
+   * sample grid, thinning effective coverage exactly when risk peaks.
+   * Clamped to 0..8 like the env knob; HF_DE_VERIFY, when set, still wins.
+   */
+  deVerifySamples?: number;
 }
 
 export interface CaptureVideoMetadataHint {

From 2731e31286996bfc4f00aca0b424d1627354e84e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 12:25:31 -0700
Subject: [PATCH 18/24] fix(cli): settle post-seek font subset loads before
 audit screenshots

---
 .../capture/captureCompositionFrame.test.ts   | 16 +++++++-
 .../src/capture/captureCompositionFrame.ts    | 41 +++++++++++++++----
 2 files changed, 47 insertions(+), 10 deletions(-)

diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.ts
index c2e83396cd..84bcb73be5 100644
--- a/packages/cli/src/capture/captureCompositionFrame.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts
@@ -47,15 +47,26 @@ afterEach(() => {
 });
 
 describe("seekCompositionTimeline", () => {
-  it("keeps the existing raced double-frame settle as the default", async () => {
+  it("keeps the raced double-frame settle and adds a bounded font wait by default", async () => {
     const { page, evaluate, waitForFunction } = fakeSeekPage();
 
     await seekCompositionTimeline(page, 1.25);
 
     expect(waitForFunction).not.toHaveBeenCalled();
-    expect(evaluate).toHaveBeenCalledTimes(2);
+    expect(evaluate).toHaveBeenCalledTimes(3);
     expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false);
     expect(evaluate.mock.calls[1]?.[0]).toContain("window.setTimeout(finish, 100)");
+    // Post-seek font settle: a seek can reveal glyphs whose unicode-range
+    // subsets only start loading after the next layout (CJK snapshot reports).
+    expect(evaluate).toHaveBeenNthCalledWith(3, expect.any(Function), 500);
+  });
+
+  it("waitForFontsMs: 0 disables the post-seek font wait", async () => {
+    const { page, evaluate } = fakeSeekPage();
+
+    await seekCompositionTimeline(page, 1.25, { waitForFontsMs: 0 });
+
+    expect(evaluate).toHaveBeenCalledTimes(2);
   });
 
   it("prefers renderSeek so the runtime synchronizes clip visibility", async () => {
@@ -128,6 +139,7 @@ describe("seekCompositionTimeline", () => {
       fallbackToBridgeAndTimelines: true,
       waitForPreferredSeekTargetMs: 500,
       animationFrameSettle: "none",
+      waitForFontsMs: 0,
       settleMs: 150,
     });
     await vi.advanceTimersByTimeAsync(150);
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index 2b0d164094..49c9af67b4 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -6,6 +6,7 @@ import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport
 const SHADER_TRANSITIONS_TIMEOUT_MS = 90_000;
 const CAPTURE_SETTLE_MS = 1500;
 const PREFERRED_SEEK_TARGET_WAIT_MS = 500;
+const DEFAULT_POST_SEEK_FONT_WAIT_MS = 500;
 
 // The audit-grade seek tuning shared by check and the deprecated inspect/layout:
 // bridge+timeline fallback, ordered double-rAF settle, bounded font wait, sleep.
@@ -257,8 +258,13 @@ export async function seekCompositionTimeline(
     );
   }
 
-  if (options.waitForFontsMs !== undefined) {
-    await waitForCompositionFonts(page, options.waitForFontsMs);
+  // On by default: every seek caller here is a visual-audit path (snapshot,
+  // check, compare, validate, layout) and a seek that reveals unrequested
+  // glyphs must not screenshot before their font subsets load. Costs one
+  // evaluate + one rAF when nothing is loading. Pass 0 to disable.
+  const waitForFontsMs = options.waitForFontsMs ?? DEFAULT_POST_SEEK_FONT_WAIT_MS;
+  if (waitForFontsMs > 0) {
+    await waitForCompositionFonts(page, waitForFontsMs);
   }
   if (options.settleMs !== undefined) {
     const settleMs = Math.max(0, options.settleMs);
@@ -299,12 +305,31 @@ export async function waitForCompositionFonts(
     .evaluate((ms: number) => {
       const fonts = Reflect.get(document, "fonts");
       if (typeof fonts !== "object" || fonts === null) return Promise.resolve();
-      const ready = Reflect.get(fonts, "ready");
-      if (!ready) return Promise.resolve();
-      return Promise.race([
-        Promise.resolve(ready).then(() => undefined),
-        new Promise<void>((resolve) => setTimeout(resolve, ms)),
-      ]);
+      // A seek can reveal glyphs whose font faces were never requested —
+      // CJK @font-face splits into unicode-range subsets that only load when
+      // first laid out. `fonts.ready` is already-resolved at that moment, so
+      // awaiting it immediately races the load request and screenshots blank
+      // glyphs (wild reports: Traditional Chinese / Microsoft YaHei check
+      // snapshots). Force a synchronous layout so pending subsets actually
+      // start loading, give the loader one frame to flip `fonts.status`,
+      // THEN await readiness.
+      void document.body?.offsetHeight;
+      return new Promise<void>((resolveWait) => {
+        const deadline = setTimeout(resolveWait, ms);
+        requestAnimationFrame(() => {
+          const status = Reflect.get(fonts, "status");
+          const ready = Reflect.get(fonts, "ready");
+          if (status !== "loading" || !ready) {
+            clearTimeout(deadline);
+            resolveWait();
+            return;
+          }
+          Promise.resolve(ready).then(() => {
+            clearTimeout(deadline);
+            resolveWait();
+          });
+        });
+      });
     }, timeoutMs)
     .catch(() => {});
 }

From 50cfd483ce698e49c0afbef90936c8ba49a07d63 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 12:28:34 -0700
Subject: [PATCH 19/24] feat(cli): preview --browser-no-gpu for gpu-unstable
 hosts

---
 packages/cli/src/commands/preview.ts       | 19 +++++++++++++++++++
 packages/cli/src/utils/openBrowser.test.ts | 13 +++++++++++++
 packages/cli/src/utils/openBrowser.ts      | 11 +++++++++++
 3 files changed, 43 insertions(+)

diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts
index 6edeec423a..b3f6cd5ed8 100644
--- a/packages/cli/src/commands/preview.ts
+++ b/packages/cli/src/commands/preview.ts
@@ -50,6 +50,7 @@ interface BrowserLaunchOptions {
   browserPath?: string;
   userDataDir?: string;
   remoteDebuggingPort?: number;
+  browserNoGpu?: boolean;
 }
 
 interface StudioLaunchOptions extends BrowserLaunchOptions {
@@ -142,6 +143,12 @@ export default defineCommand({
       type: "string",
       description: "Chromium remote debugging port (requires --browser-path and --user-data-dir)",
     },
+    "browser-no-gpu": {
+      type: "boolean",
+      default: false,
+      description:
+        "Launch the opened browser with --disable-gpu (requires --browser-path). For hosts where hardware acceleration crashes the graphics driver (e.g. NVIDIA Xid resets); with the system default browser use --no-open instead.",
+    },
   },
   async run({ args }) {
     const startPort = parseInt(args.port ?? "3002", 10);
@@ -239,6 +246,14 @@ export default defineCommand({
 
     const noOpen = !args.open;
     const browserPath = args["browser-path"] as string | undefined;
+    const browserNoGpu = !!args["browser-no-gpu"];
+    if (browserNoGpu && !browserPath) {
+      clack.log.error(
+        "--browser-no-gpu requires --browser-path (the system default browser cannot receive Chromium flags — use --no-open on GPU-unstable hosts)",
+      );
+      process.exitCode = 1;
+      return;
+    }
     const userDataDir = args["user-data-dir"] as string | undefined;
     let remoteDebuggingPort: number | undefined;
     try {
@@ -258,6 +273,7 @@ export default defineCommand({
         browserPath,
         userDataDir,
         remoteDebuggingPort,
+        browserNoGpu,
       });
     }
 
@@ -269,6 +285,7 @@ export default defineCommand({
         browserPath,
         userDataDir,
         remoteDebuggingPort,
+        browserNoGpu,
       });
     }
 
@@ -280,6 +297,7 @@ export default defineCommand({
       browserPath,
       userDataDir,
       remoteDebuggingPort,
+      browserNoGpu,
     });
   },
 });
@@ -641,6 +659,7 @@ function openStudioBrowser(url: string, projectName: string, options?: BrowserLa
     browserPath: options?.browserPath,
     userDataDir: options?.userDataDir,
     remoteDebuggingPort: options?.remoteDebuggingPort,
+    disableGpu: options?.browserNoGpu,
   });
 }
 
diff --git a/packages/cli/src/utils/openBrowser.test.ts b/packages/cli/src/utils/openBrowser.test.ts
index 3de1f307b4..7dbe859d4f 100644
--- a/packages/cli/src/utils/openBrowser.test.ts
+++ b/packages/cli/src/utils/openBrowser.test.ts
@@ -158,3 +158,16 @@ describe("validateRemoteDebuggingPortDeps", () => {
     ).toBe("--remote-debugging-port requires --browser-path");
   });
 });
+
+describe("buildBrowserArgs --disable-gpu", () => {
+  it("appends --disable-gpu before the url when disableGpu is set", () => {
+    expect(buildBrowserArgs("http://localhost:3002", { disableGpu: true })).toEqual([
+      "--disable-gpu",
+      "http://localhost:3002",
+    ]);
+  });
+
+  it("omits --disable-gpu by default", () => {
+    expect(buildBrowserArgs("http://localhost:3002", {})).toEqual(["http://localhost:3002"]);
+  });
+});
diff --git a/packages/cli/src/utils/openBrowser.ts b/packages/cli/src/utils/openBrowser.ts
index 1bb3ad9b33..0cde28af9d 100644
--- a/packages/cli/src/utils/openBrowser.ts
+++ b/packages/cli/src/utils/openBrowser.ts
@@ -4,6 +4,14 @@ export interface OpenBrowserOptions {
   browserPath?: string;
   userDataDir?: string;
   remoteDebuggingPort?: number;
+  /**
+   * Launch the browser with --disable-gpu. For hosts where hardware
+   * acceleration crashes the graphics driver (wild report: auto-opened
+   * preview triggered NVIDIA Xid 32 resets on NixOS). Only effective with
+   * `browserPath` — the `open`-package fallback launches the system default
+   * browser with no way to pass Chromium flags.
+   */
+  disableGpu?: boolean;
 }
 
 export function parseRemoteDebuggingPort(value: string | undefined): number | undefined {
@@ -52,6 +60,9 @@ export function buildBrowserArgs(url: string, options: OpenBrowserOptions): stri
   if (options.remoteDebuggingPort !== undefined && options.userDataDir) {
     args.push(`--remote-debugging-port=${options.remoteDebuggingPort}`);
   }
+  if (options.disableGpu) {
+    args.push("--disable-gpu");
+  }
   args.push(url);
   return args;
 }

From 2a17557ccc2d5e8b3ab2260991c9b167db1ab296 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 12:39:54 -0700
Subject: [PATCH 20/24] fix(producer): disk-headroom gate before hdr raw frame
 pre-extraction

---
 .../render/stages/captureHdrResources.test.ts | 28 +++++++
 .../render/stages/captureHdrResources.ts      | 79 ++++++++++++++++++-
 2 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 packages/producer/src/services/render/stages/captureHdrResources.test.ts

diff --git a/packages/producer/src/services/render/stages/captureHdrResources.test.ts b/packages/producer/src/services/render/stages/captureHdrResources.test.ts
new file mode 100644
index 0000000000..503b97f1ed
--- /dev/null
+++ b/packages/producer/src/services/render/stages/captureHdrResources.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { estimateHdrExtractionBytes } from "./captureHdrResources.js";
+
+describe("estimateHdrExtractionBytes", () => {
+  it("sums 6 bytes per pixel per frame across videos", () => {
+    // 10s @ 30fps of 1920x1080 = 300 frames * 1920*1080*6
+    expect(
+      estimateHdrExtractionBytes([{ durationSeconds: 10, width: 1920, height: 1080 }], 30),
+    ).toBe(300 * 1920 * 1080 * 6);
+  });
+
+  it("accumulates multiple videos and rounds frame counts up", () => {
+    const bytes = estimateHdrExtractionBytes(
+      [
+        { durationSeconds: 1.5, width: 100, height: 100 },
+        { durationSeconds: 0.05, width: 100, height: 100 },
+      ],
+      30,
+    );
+    expect(bytes).toBe((45 + 2) * 100 * 100 * 6);
+  });
+
+  it("treats negative durations as empty", () => {
+    expect(estimateHdrExtractionBytes([{ durationSeconds: -3, width: 100, height: 100 }], 30)).toBe(
+      0,
+    );
+  });
+});
diff --git a/packages/producer/src/services/render/stages/captureHdrResources.ts b/packages/producer/src/services/render/stages/captureHdrResources.ts
index 76129dd5fb..5683e0b17b 100644
--- a/packages/producer/src/services/render/stages/captureHdrResources.ts
+++ b/packages/producer/src/services/render/stages/captureHdrResources.ts
@@ -24,6 +24,7 @@ import {
   mkdtempSync,
   openSync,
   readFileSync,
+  statfsSync,
 } from "node:fs";
 import { join } from "node:path";
 import {
@@ -34,7 +35,7 @@ import {
   resampleRgb48leObjectFit,
   runFfmpeg,
 } from "@hyperframes/engine";
-import { fpsToFfmpegArg } from "@hyperframes/core";
+import { fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
 import type { ProducerLogger } from "../../../logger.js";
 import type { HdrImageBuffer, HdrVideoFrameSource } from "../../hdrCompositor.js";
 import type { HdrDiagnostics, RenderJob } from "../../renderOrchestrator.js";
@@ -164,6 +165,69 @@ export async function probeHdrExtractionDims(args: {
   }
 }
 
+/**
+ * Total bytes the raw rgb48le pre-extraction below will write: 6 bytes/px ×
+ * frame area × frame count, summed across HDR videos. Exposed for the
+ * disk-headroom gate — a plain iPhone HLG clip auto-detected as HDR filled a
+ * near-full disk with 16-bit raw frames before the user found --sdr (wild
+ * report, CLI 0.7.52), so the commitment must be checked and surfaced BEFORE
+ * FFmpeg starts writing.
+ */
+export function estimateHdrExtractionBytes(
+  videos: Array<{ durationSeconds: number; width: number; height: number }>,
+  fps: number,
+): number {
+  let total = 0;
+  for (const v of videos) {
+    const frames = Math.ceil(Math.max(0, v.durationSeconds) * fps);
+    total += frames * v.width * v.height * 6;
+  }
+  return total;
+}
+
+const HDR_EXTRACTION_HEADROOM_FRACTION = 0.9;
+const HDR_EXTRACTION_WARN_BYTES = 10e9;
+
+/**
+ * Disk-headroom gate for raw rgb48le pre-extraction: throws if the planned
+ * writes would consume more than 90% of free space at `framesDir`, warns
+ * above 10 GB either way. Fails fast with the --sdr escape hatch instead of
+ * running the disk to zero mid-extraction ("No space left on device", wild
+ * report: a plain iPhone HLG clip auto-detected as HDR). `statfsSync` errors
+ * (unsupported platform/filesystem) skip the gate silently — only the
+ * headroom violation itself is rethrown.
+ */
+function assertHdrExtractionDiskHeadroom(
+  framesDir: string,
+  plannedVideos: Array<{ durationSeconds: number; width: number; height: number }>,
+  fps: number,
+  log: ProducerLogger,
+): void {
+  const estimatedBytes = estimateHdrExtractionBytes(plannedVideos, fps);
+  try {
+    const stat = statfsSync(framesDir);
+    const freeBytes = stat.bavail * stat.bsize;
+    const estimatedGb = (estimatedBytes / 1e9).toFixed(1);
+    if (estimatedBytes > freeBytes * HDR_EXTRACTION_HEADROOM_FRACTION) {
+      throw new Error(
+        `HDR pre-extraction needs ~${estimatedGb} GB of raw 16-bit frames but only ` +
+          `${(freeBytes / 1e9).toFixed(1)} GB is free at ${framesDir}. ` +
+          `If the composition doesn't need HDR output, re-run with --sdr; ` +
+          `otherwise free up disk space and retry.`,
+      );
+    }
+    if (estimatedBytes > HDR_EXTRACTION_WARN_BYTES) {
+      log.warn(
+        `HDR pre-extraction will write ~${estimatedGb} GB of raw 16-bit frames ` +
+          `(pass --sdr to skip if HDR output isn't needed)`,
+        { estimatedBytes, freeBytes },
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("HDR pre-extraction needs")) throw err;
+  }
+}
+
 /**
  * Extract each HDR video into a raw rgb48le frame file via a single FFmpeg
  * pass per video, and open a file descriptor for each. Returns a map keyed
@@ -183,6 +247,19 @@ export async function extractHdrVideoFrames(args: {
   const { job, log, framesDir, composition, prep, width, height, abortSignal, hdrDiagnostics } =
     args;
   const out = new Map<string, HdrVideoFrameSource>();
+  mkdirSync(framesDir, { recursive: true });
+  const plannedVideos: Array<{ durationSeconds: number; width: number; height: number }> = [];
+  for (const [videoId] of prep.hdrVideoSrcPaths) {
+    const video = composition.videos.find((v) => v.id === videoId);
+    if (!video) continue;
+    const dims = prep.hdrExtractionDims.get(videoId) ?? { width, height };
+    plannedVideos.push({
+      durationSeconds: video.end - video.start,
+      width: dims.width,
+      height: dims.height,
+    });
+  }
+  assertHdrExtractionDiskHeadroom(framesDir, plannedVideos, fpsToNumber(job.config.fps), log);
   for (const [videoId, srcPath] of prep.hdrVideoSrcPaths) {
     const video = composition.videos.find((v) => v.id === videoId);
     if (!video) continue;

From bd0b3ecdadddffc5d52d92fb361fdd0162f298af Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Sat, 11 Jul 2026 13:55:01 -0700
Subject: [PATCH 21/24] refactor(producer): stop coupling the hdr disk-headroom
 gate's control flow to error-string matching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses non-blocking review feedback on #2256: the previous shape used
err.message.includes(...) inside a catch to distinguish a real headroom
violation from a statfsSync failure — a future message tweak would silently
fail open (statfs-unsupported and headroom-violation would take the same
code path). Now statfsSync failure returns early (skip the gate) and the
headroom check/throw happens in plain control flow outside any try/catch.
---
 .../render/stages/captureHdrResources.ts      | 40 ++++++++++---------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/packages/producer/src/services/render/stages/captureHdrResources.ts b/packages/producer/src/services/render/stages/captureHdrResources.ts
index 5683e0b17b..fd65930a75 100644
--- a/packages/producer/src/services/render/stages/captureHdrResources.ts
+++ b/packages/producer/src/services/render/stages/captureHdrResources.ts
@@ -204,27 +204,29 @@ function assertHdrExtractionDiskHeadroom(
   log: ProducerLogger,
 ): void {
   const estimatedBytes = estimateHdrExtractionBytes(plannedVideos, fps);
+  let freeBytes: number;
   try {
     const stat = statfsSync(framesDir);
-    const freeBytes = stat.bavail * stat.bsize;
-    const estimatedGb = (estimatedBytes / 1e9).toFixed(1);
-    if (estimatedBytes > freeBytes * HDR_EXTRACTION_HEADROOM_FRACTION) {
-      throw new Error(
-        `HDR pre-extraction needs ~${estimatedGb} GB of raw 16-bit frames but only ` +
-          `${(freeBytes / 1e9).toFixed(1)} GB is free at ${framesDir}. ` +
-          `If the composition doesn't need HDR output, re-run with --sdr; ` +
-          `otherwise free up disk space and retry.`,
-      );
-    }
-    if (estimatedBytes > HDR_EXTRACTION_WARN_BYTES) {
-      log.warn(
-        `HDR pre-extraction will write ~${estimatedGb} GB of raw 16-bit frames ` +
-          `(pass --sdr to skip if HDR output isn't needed)`,
-        { estimatedBytes, freeBytes },
-      );
-    }
-  } catch (err) {
-    if (err instanceof Error && err.message.includes("HDR pre-extraction needs")) throw err;
+    freeBytes = stat.bavail * stat.bsize;
+  } catch {
+    // statfs unsupported on this platform/filesystem — skip the gate.
+    return;
+  }
+  const estimatedGb = (estimatedBytes / 1e9).toFixed(1);
+  if (estimatedBytes > freeBytes * HDR_EXTRACTION_HEADROOM_FRACTION) {
+    throw new Error(
+      `HDR pre-extraction needs ~${estimatedGb} GB of raw 16-bit frames but only ` +
+        `${(freeBytes / 1e9).toFixed(1)} GB is free at ${framesDir}. ` +
+        `If the composition doesn't need HDR output, re-run with --sdr; ` +
+        `otherwise free up disk space and retry.`,
+    );
+  }
+  if (estimatedBytes > HDR_EXTRACTION_WARN_BYTES) {
+    log.warn(
+      `HDR pre-extraction will write ~${estimatedGb} GB of raw 16-bit frames ` +
+        `(pass --sdr to skip if HDR output isn't needed)`,
+      { estimatedBytes, freeBytes },
+    );
   }
 }
 

From 6683b4391e65ec68195960e69da3f2233e15deb4 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 11 Jul 2026 13:55:03 -0700
Subject: [PATCH 22/24] =?UTF-8?q?feat(studio):=20timeline=20leaf=20helpers?=
 =?UTF-8?q?=20=E2=80=94=20audio=20inspector,=20zoom=20math,=20UI=20prefs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What: extends three leaf modules to their final NLE-stack form, tests in the
same change: timelineInspector (isAudioTimelineElement, resolveBeatSourceTrack),
timelineZoom (zoom/pps math incl. computePinnedZoomPercent), and
studioUiPreferences (persisted editor prefs).

Why: leaf dependencies of the NLE timeline stack; landing them first keeps
the later glue PRs to wiring.

How: additive from the consumer side — every export main already uses is
unchanged (typecheck against main's consumers passes untouched); every new
export is exercised by a test in this PR.

Test plan: bunx vitest run on the three test files; tsc --noEmit in
packages/studio; fallow audit --base origin/main clean.
---
 .../player/components/timelineZoom.test.ts    |  67 ++++++++++
 .../src/player/components/timelineZoom.ts     |  51 ++++++++
 .../src/utils/studioUiPreferences.test.ts     |  38 ++++++
 .../studio/src/utils/studioUiPreferences.ts   |  27 ++++
 .../src/utils/timelineInspector.test.ts       | 121 ++++++++++++++++++
 .../studio/src/utils/timelineInspector.ts     |  33 ++++-
 6 files changed, 336 insertions(+), 1 deletion(-)
 create mode 100644 packages/studio/src/utils/timelineInspector.test.ts

diff --git a/packages/studio/src/player/components/timelineZoom.test.ts b/packages/studio/src/player/components/timelineZoom.test.ts
index 3e4a35cac5..8b2fc00572 100644
--- a/packages/studio/src/player/components/timelineZoom.test.ts
+++ b/packages/studio/src/player/components/timelineZoom.test.ts
@@ -1,12 +1,15 @@
 import { describe, expect, it } from "vitest";
 import {
   clampTimelineZoomPercent,
+  computePinnedZoomPercent,
   getNextTimelineZoomPercent,
   getPinchTimelineZoomPercent,
   getTimelinePixelsPerSecond,
   getTimelineZoomPercent,
   MAX_TIMELINE_ZOOM_PERCENT,
   MIN_TIMELINE_ZOOM_PERCENT,
+  timelineZoomPercentToSlider,
+  timelineSliderToZoomPercent,
 } from "./timelineZoom";
 
 describe("clampTimelineZoomPercent", () => {
@@ -81,3 +84,67 @@ describe("getPinchTimelineZoomPercent", () => {
     expect(getPinchTimelineZoomPercent(-10000, "manual", 100)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
   });
 });
+
+describe("timelineZoomPercentToSlider", () => {
+  it("maps min zoom to slider position 0", () => {
+    expect(timelineZoomPercentToSlider(MIN_TIMELINE_ZOOM_PERCENT)).toBeCloseTo(0, 5);
+  });
+
+  it("maps max zoom to slider position 100", () => {
+    expect(timelineZoomPercentToSlider(MAX_TIMELINE_ZOOM_PERCENT)).toBeCloseTo(100, 5);
+  });
+
+  it("maps 100% to the log midpoint between 10 and 2000", () => {
+    const expected = ((Math.log(100) - Math.log(10)) / (Math.log(2000) - Math.log(10))) * 100;
+    expect(timelineZoomPercentToSlider(100)).toBeCloseTo(expected, 3);
+  });
+});
+
+describe("timelineSliderToZoomPercent", () => {
+  it("maps slider 0 to min zoom", () => {
+    expect(timelineSliderToZoomPercent(0)).toBe(MIN_TIMELINE_ZOOM_PERCENT);
+  });
+
+  it("maps slider 100 to max zoom", () => {
+    expect(timelineSliderToZoomPercent(100)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
+  });
+});
+
+describe("computePinnedZoomPercent", () => {
+  it("returns 100 when current pps equals the fit pps (a no-op pin at the current fit)", () => {
+    expect(computePinnedZoomPercent(42, 42)).toBe(100);
+  });
+
+  it("reproduces the current pps: percent × fitPps / 100 === currentPps", () => {
+    const fitPps = 20;
+    const currentPps = 50; // user zoomed in 2.5×
+    const percent = computePinnedZoomPercent(currentPps, fitPps);
+    expect(percent).toBe(250);
+    // Round-trips through getTimelinePixelsPerSecond back to the on-screen pps.
+    expect(getTimelinePixelsPerSecond(fitPps, "manual", percent)).toBeCloseTo(currentPps, 5);
+  });
+
+  it("clamps a pin that would exceed the manual-zoom bounds", () => {
+    // currentPps 10000 / fitPps 1 = 1_000_000% → clamped to MAX.
+    expect(computePinnedZoomPercent(10000, 1)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
+    // Tiny ratio → clamped up to MIN.
+    expect(computePinnedZoomPercent(0.001, 1000)).toBe(MIN_TIMELINE_ZOOM_PERCENT);
+  });
+
+  it("falls back to 100 for unusable inputs (a safe no-op pin)", () => {
+    expect(computePinnedZoomPercent(Number.NaN, 20)).toBe(100);
+    expect(computePinnedZoomPercent(50, 0)).toBe(100);
+    expect(computePinnedZoomPercent(-5, 20)).toBe(100);
+    expect(computePinnedZoomPercent(50, Number.POSITIVE_INFINITY)).toBe(100);
+  });
+});
+
+describe("timelineZoomPercentToSlider / timelineSliderToZoomPercent round-trip", () => {
+  for (const percent of [10, 100, 500, 2000]) {
+    it(`round-trips ${percent}% within ±1%`, () => {
+      const slider = timelineZoomPercentToSlider(percent);
+      const back = timelineSliderToZoomPercent(slider);
+      expect(Math.abs(back - percent) / percent).toBeLessThan(0.01);
+    });
+  }
+});
diff --git a/packages/studio/src/player/components/timelineZoom.ts b/packages/studio/src/player/components/timelineZoom.ts
index 0ac4a92b27..15baa15667 100644
--- a/packages/studio/src/player/components/timelineZoom.ts
+++ b/packages/studio/src/player/components/timelineZoom.ts
@@ -18,6 +18,34 @@ export function getTimelineZoomPercent(zoomMode: ZoomMode, manualZoomPercent: nu
   return zoomMode === "fit" ? 100 : clampTimelineZoomPercent(manualZoomPercent);
 }
 
+/**
+ * The manual-zoom percent that, applied to `fitPixelsPerSecond`, reproduces the
+ * CURRENT on-screen pixels-per-second exactly. Used to PIN the timeline zoom on
+ * the first edit so a duration change (which recomputes fit-pps) no longer
+ * rescales every clip: we switch `zoomMode` to "manual" with this percent, so
+ * `getTimelinePixelsPerSecond` keeps returning today's pps regardless of the new
+ * fit basis.
+ *
+ * Since `pps = fitPps * (percent / 100)` in manual mode, and while fitting
+ * `pps === fitPps`, the pinned percent is `currentPps / fitPps * 100`. Clamped to
+ * the manual-zoom range so the pin can't land outside the slider's bounds; falls
+ * back to 100 (a no-op pin at the current fit) when either input is unusable.
+ */
+export function computePinnedZoomPercent(
+  currentPixelsPerSecond: number,
+  fitPixelsPerSecond: number,
+): number {
+  if (
+    !Number.isFinite(currentPixelsPerSecond) ||
+    currentPixelsPerSecond <= 0 ||
+    !Number.isFinite(fitPixelsPerSecond) ||
+    fitPixelsPerSecond <= 0
+  ) {
+    return 100;
+  }
+  return clampTimelineZoomPercent((currentPixelsPerSecond / fitPixelsPerSecond) * 100);
+}
+
 export function getTimelinePixelsPerSecond(
   fitPixelsPerSecond: number,
   zoomMode: ZoomMode,
@@ -47,3 +75,26 @@ export function getPinchTimelineZoomPercent(
   if (!Number.isFinite(deltaY) || deltaY === 0) return current;
   return clampTimelineZoomPercent(current * Math.exp(-deltaY * PINCH_ZOOM_SENSITIVITY));
 }
+
+const LOG_MIN = Math.log(MIN_TIMELINE_ZOOM_PERCENT);
+const LOG_MAX = Math.log(MAX_TIMELINE_ZOOM_PERCENT);
+
+/**
+ * Maps a zoom percent (10–2000) to a slider position (0–100) using a log scale.
+ * Log scale is used because the range spans 200×; linear would compress the
+ * low end (10–100%) into a tiny sliver of the slider.
+ */
+export function timelineZoomPercentToSlider(percent: number): number {
+  const clamped = clampTimelineZoomPercent(percent);
+  return ((Math.log(clamped) - LOG_MIN) / (LOG_MAX - LOG_MIN)) * 100;
+}
+
+/**
+ * Maps a slider position (0–100) to a zoom percent (10–2000) using a log scale.
+ * Inverse of `timelineZoomPercentToSlider`.
+ */
+export function timelineSliderToZoomPercent(slider: number): number {
+  const clampedSlider = Math.max(0, Math.min(100, slider));
+  const logValue = LOG_MIN + (clampedSlider / 100) * (LOG_MAX - LOG_MIN);
+  return clampTimelineZoomPercent(Math.exp(logValue));
+}
diff --git a/packages/studio/src/utils/studioUiPreferences.test.ts b/packages/studio/src/utils/studioUiPreferences.test.ts
index c5dbd50968..5e335cf5d3 100644
--- a/packages/studio/src/utils/studioUiPreferences.test.ts
+++ b/packages/studio/src/utils/studioUiPreferences.test.ts
@@ -50,3 +50,41 @@ describe("studio UI preferences", () => {
     });
   });
 });
+
+describe("timelineSnapEnabled preference", () => {
+  it("round-trips through storage", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences({ timelineSnapEnabled: false }, storage);
+    expect(readStudioUiPreferences(storage).timelineSnapEnabled).toBe(false);
+  });
+
+  it("ignores non-boolean values", () => {
+    const storage = createStorage();
+    storage.setItem("hf-studio-ui-preferences", JSON.stringify({ timelineSnapEnabled: "yes" }));
+    expect(readStudioUiPreferences(storage).timelineSnapEnabled).toBeUndefined();
+  });
+});
+
+describe("timeline zoom pin persistence", () => {
+  it("round-trips a pinned manual zoom (survives the post-edit reload)", () => {
+    const storage = createStorage();
+    writeStudioUiPreferences(
+      { timelineZoomMode: "manual", timelineManualZoomPercent: 250 },
+      storage,
+    );
+    const prefs = readStudioUiPreferences(storage);
+    expect(prefs.timelineZoomMode).toBe("manual");
+    expect(prefs.timelineManualZoomPercent).toBe(250);
+  });
+
+  it("ignores an invalid zoom mode and a non-finite percent", () => {
+    const storage = createStorage();
+    storage.setItem(
+      "hf-studio-ui-preferences",
+      JSON.stringify({ timelineZoomMode: "zoomy", timelineManualZoomPercent: "big" }),
+    );
+    const prefs = readStudioUiPreferences(storage);
+    expect(prefs.timelineZoomMode).toBeUndefined();
+    expect(prefs.timelineManualZoomPercent).toBeUndefined();
+  });
+});
diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 13804959a6..6548a58eba 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/src/utils/studioUiPreferences.ts
@@ -16,6 +16,18 @@ export interface StudioUiPreferences {
   gridVisible?: boolean;
   gridSpacing?: number;
   snapToGrid?: boolean;
+  /** Timeline magnet: snap clip drags/trims/drops to playhead, clip edges, and beats. */
+  timelineSnapEnabled?: boolean;
+  /** Transport + ruler readout mode: timecode or frame number. */
+  timeDisplayMode?: "time" | "frame";
+  /**
+   * Timeline zoom mode. Persisted so a zoom PINNED on the first edit survives the
+   * post-edit iframe reload — otherwise the store reset to "fit" and the duration
+   * change rescaled every clip (the blink-fix's rescale symptom).
+   */
+  timelineZoomMode?: "fit" | "manual";
+  /** Manual timeline zoom percent, paired with `timelineZoomMode: "manual"`. */
+  timelineManualZoomPercent?: number;
 }
 
 const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -88,6 +100,21 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
     if (typeof parsed.snapToGrid === "boolean") {
       preferences.snapToGrid = parsed.snapToGrid;
     }
+    if (typeof parsed.timelineSnapEnabled === "boolean") {
+      preferences.timelineSnapEnabled = parsed.timelineSnapEnabled;
+    }
+    if (parsed.timeDisplayMode === "time" || parsed.timeDisplayMode === "frame") {
+      preferences.timeDisplayMode = parsed.timeDisplayMode;
+    }
+    if (parsed.timelineZoomMode === "fit" || parsed.timelineZoomMode === "manual") {
+      preferences.timelineZoomMode = parsed.timelineZoomMode;
+    }
+    if (
+      typeof parsed.timelineManualZoomPercent === "number" &&
+      Number.isFinite(parsed.timelineManualZoomPercent)
+    ) {
+      preferences.timelineManualZoomPercent = parsed.timelineManualZoomPercent;
+    }
     return preferences;
   } catch {
     return {};
diff --git a/packages/studio/src/utils/timelineInspector.test.ts b/packages/studio/src/utils/timelineInspector.test.ts
new file mode 100644
index 0000000000..318f3cbb02
--- /dev/null
+++ b/packages/studio/src/utils/timelineInspector.test.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { isAudioTimelineElement, isMusicTrack, resolveBeatSourceTrack } from "./timelineInspector";
+import type { TimelineElement } from "../player";
+
+// Minimal element factory for tests
+function el(
+  overrides: Partial<
+    Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "duration">
+  >,
+): Pick<TimelineElement, "tag" | "src" | "id" | "domId" | "timelineRole" | "duration"> {
+  return {
+    tag: "audio",
+    src: "assets/track.mp3",
+    id: "el-1",
+    domId: "el-1",
+    timelineRole: undefined,
+    duration: 10,
+    ...overrides,
+  };
+}
+
+describe("isAudioTimelineElement", () => {
+  it("is true for audio tag", () => {
+    expect(isAudioTimelineElement(el({ tag: "audio" }))).toBe(true);
+  });
+
+  it("is true for music/sfx/narration semantic tags", () => {
+    expect(isAudioTimelineElement(el({ tag: "music" }))).toBe(true);
+    expect(isAudioTimelineElement(el({ tag: "sfx" }))).toBe(true);
+    expect(isAudioTimelineElement(el({ tag: "narration" }))).toBe(true);
+  });
+
+  it("is true for img/div with an audio src extension", () => {
+    expect(isAudioTimelineElement(el({ tag: "div", src: "assets/bg.mp3" }))).toBe(true);
+    expect(isAudioTimelineElement(el({ tag: "div", src: "assets/fx.wav" }))).toBe(true);
+  });
+
+  it("is false for video and image elements", () => {
+    expect(isAudioTimelineElement(el({ tag: "video", src: "assets/clip.mp4" }))).toBe(false);
+    expect(isAudioTimelineElement(el({ tag: "img", src: "assets/logo.svg" }))).toBe(false);
+  });
+
+  it("returns false for null/undefined", () => {
+    expect(isAudioTimelineElement(null)).toBe(false);
+    expect(isAudioTimelineElement(undefined)).toBe(false);
+  });
+});
+
+describe("isMusicTrack", () => {
+  it("is true when timelineRole is 'music'", () => {
+    expect(isMusicTrack(el({ timelineRole: "music" }))).toBe(true);
+  });
+
+  it("is false for explicit non-music roles", () => {
+    expect(isMusicTrack(el({ timelineRole: "sfx" }))).toBe(false);
+    expect(isMusicTrack(el({ timelineRole: "voiceover" }))).toBe(false);
+  });
+
+  it("matches music-like ids when no role is set", () => {
+    expect(isMusicTrack(el({ domId: "bgm", timelineRole: undefined }))).toBe(true);
+    expect(isMusicTrack(el({ domId: "background_music", timelineRole: undefined }))).toBe(true);
+    expect(isMusicTrack(el({ domId: "soundtrack", timelineRole: undefined }))).toBe(true);
+  });
+
+  it("is false for generic ids with no role", () => {
+    expect(isMusicTrack(el({ domId: "my_audio_file", timelineRole: undefined }))).toBe(false);
+    expect(isMusicTrack(el({ domId: "drop_1", timelineRole: undefined }))).toBe(false);
+  });
+
+  it("is false for non-audio elements even with a music-like id", () => {
+    expect(isMusicTrack(el({ tag: "img", src: "assets/logo.svg", domId: "bgm" }))).toBe(false);
+  });
+});
+
+describe("resolveBeatSourceTrack", () => {
+  it("returns null when there are no elements", () => {
+    expect(resolveBeatSourceTrack([])).toBeNull();
+  });
+
+  it("returns null when there are no audio elements", () => {
+    const elements = [el({ tag: "img", src: "assets/logo.png" })];
+    expect(resolveBeatSourceTrack(elements)).toBeNull();
+  });
+
+  it("returns isFallback=false for an explicitly tagged music track", () => {
+    const music = el({ timelineRole: "music" });
+    const result = resolveBeatSourceTrack([music]);
+    expect(result).not.toBeNull();
+    expect(result!.isFallback).toBe(false);
+    expect(result!.element).toBe(music);
+  });
+
+  it("prefers the explicit music track over a longer untagged clip", () => {
+    const music = el({ timelineRole: "music", duration: 30 });
+    const other = el({ id: "drop_1", domId: "drop_1", timelineRole: undefined, duration: 120 });
+    const result = resolveBeatSourceTrack([music, other]);
+    expect(result!.element).toBe(music);
+    expect(result!.isFallback).toBe(false);
+  });
+
+  it("falls back to the longest untagged audio clip when no music track exists", () => {
+    const short = el({ id: "drop_1", domId: "drop_1", duration: 5, timelineRole: undefined });
+    const long = el({ id: "drop_2", domId: "drop_2", duration: 60, timelineRole: undefined });
+    const result = resolveBeatSourceTrack([short, long]);
+    expect(result).not.toBeNull();
+    expect(result!.isFallback).toBe(true);
+    expect(result!.element).toBe(long);
+  });
+
+  it("excludes explicitly non-music roles (sfx, voiceover) from the fallback", () => {
+    const sfx = el({ id: "sfx_1", domId: "sfx_1", timelineRole: "sfx", duration: 30 });
+    const vo = el({ id: "vo_1", domId: "vo_1", timelineRole: "voiceover", duration: 20 });
+    expect(resolveBeatSourceTrack([sfx, vo])).toBeNull();
+  });
+
+  it("returns isFallback=true for an untagged clip with a non-music id", () => {
+    const clip = el({ id: "my_audio_file", domId: "my_audio_file", timelineRole: undefined });
+    const result = resolveBeatSourceTrack([clip]);
+    expect(result!.isFallback).toBe(true);
+  });
+});
diff --git a/packages/studio/src/utils/timelineInspector.ts b/packages/studio/src/utils/timelineInspector.ts
index b1297e1900..4a33e8fc2f 100644
--- a/packages/studio/src/utils/timelineInspector.ts
+++ b/packages/studio/src/utils/timelineInspector.ts
@@ -4,7 +4,7 @@ const AUDIO_TIMELINE_TAGS = new Set(["audio", "music", "sfx", "sound", "narratio
 const AUDIO_SOURCE_EXT_RE = /\.(aac|flac|m4a|mp3|ogg|opus|wav)(?:[?#].*)?$/i;
 const MUSIC_ID_RE = /\b(music|bgm|soundtrack|background[-_]?music)\b/i;
 
-function isAudioTimelineElement(
+export function isAudioTimelineElement(
   element: Pick<TimelineElement, "tag" | "src"> | null | undefined,
 ): boolean {
   if (!element) return false;
@@ -29,3 +29,34 @@ export function isMusicTrack(
   const id = element.domId ?? element.id ?? "";
   return MUSIC_ID_RE.test(id);
 }
+
+/**
+ * Resolve the best audio source for beat analysis. An explicitly tagged or
+ * named music track wins; when none is present (e.g. an audio file dropped
+ * from Finder with a generic id), the LONGEST untagged audio clip is used as a
+ * fallback. Ties on duration resolve to the FIRST such clip encountered (the loop
+ * keeps the current best on `>` only), i.e. discovery/DOM order wins.
+ * Returns the element and whether it was found via the fallback path.
+ *
+ * The `isMusicTrack` predicate is unchanged so beat-snap and drag-exclusion
+ * logic remain unaffected by this fallback.
+ */
+export function resolveBeatSourceTrack(
+  elements: readonly Pick<
+    TimelineElement,
+    "tag" | "src" | "id" | "domId" | "timelineRole" | "duration"
+  >[],
+): { element: (typeof elements)[number]; isFallback: boolean } | null {
+  const explicit = elements.find(isMusicTrack);
+  if (explicit) return { element: explicit, isFallback: false };
+
+  // Fallback: pick the longest audio clip (skipping explicitly non-music roles
+  // like "sfx" or "voiceover" to avoid triggering beat analysis on those).
+  let best: (typeof elements)[number] | null = null;
+  for (const el of elements) {
+    if (!isAudioTimelineElement(el)) continue;
+    if (el.timelineRole && el.timelineRole !== "music") continue;
+    if (!best || el.duration > best.duration) best = el;
+  }
+  return best ? { element: best, isFallback: true } : null;
+}

From 2c35874b3703d1e822c90d0073e6e5ec2d81aa43 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 11 Jul 2026 13:55:04 -0700
Subject: [PATCH 23/24] feat(studio): seek-restore contract for player reloads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What: useTimelineSyncCallbacks gains resolveReloadSeekTime and revealIframe —
the pure contract for where the playhead lands after a preview reload
(pending seek > deep-link seek > store playhead, clamped) and for undoing
refreshPlayer's iframe hide. Test suite included.

Why: the NLE editor reloads the preview on every committed edit; this
contract is the difference between "playhead restores" and "jumps to 0".

How: additive exports on an existing hook file; main's consumers unchanged.

Test plan: bunx vitest run useTimelineSyncCallbacks.test.ts; tsc --noEmit in
packages/studio; fallow audit clean.
---
 .../hooks/useTimelineSyncCallbacks.test.ts    | 219 ++++++++++++++++++
 .../player/hooks/useTimelineSyncCallbacks.ts  | 108 ++++++++-
 2 files changed, 323 insertions(+), 4 deletions(-)
 create mode 100644 packages/studio/src/player/hooks/useTimelineSyncCallbacks.test.ts

diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.test.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.test.ts
new file mode 100644
index 0000000000..1b0a9c710c
--- /dev/null
+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.test.ts
@@ -0,0 +1,219 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import {
+  resolveReloadSeekTime,
+  resolveTimelineTotalDuration,
+  revealIframe,
+} from "./useTimelineSyncCallbacks";
+import { readTimelineDurationFromDocument } from "../lib/timelineDOM";
+
+// Minimal stand-in — revealIframe only touches `style.visibility`. Avoids
+// depending on a DOM environment (this test file runs under node).
+function fakeIframe(visibility: string): HTMLIFrameElement {
+  return { style: { visibility } } as unknown as HTMLIFrameElement;
+}
+
+describe("revealIframe", () => {
+  it("clears a hidden iframe's visibility (undoes refreshPlayer's hide)", () => {
+    const iframe = fakeIframe("hidden");
+    revealIframe(iframe);
+    expect(iframe.style.visibility).toBe("");
+  });
+
+  it("leaves an already-visible iframe untouched (idempotent)", () => {
+    const iframe = fakeIframe("");
+    revealIframe(iframe);
+    expect(iframe.style.visibility).toBe("");
+  });
+
+  it("no-ops on a null iframe", () => {
+    expect(() => revealIframe(null)).not.toThrow();
+  });
+});
+
+describe("resolveReloadSeekTime", () => {
+  it("restores the pending seek saved by refreshPlayer (the primary reload path)", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 7.2,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: 20,
+      }),
+    ).toBe(7.2);
+  });
+
+  it("honors a deep-link seek request when no pending seek exists", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: null,
+        requestedSeek: 12.5,
+        storeCurrentTime: 0,
+        duration: 20,
+      }),
+    ).toBe(12.5);
+  });
+
+  it("THE BUG: a second overlapping reload (pending seek already consumed) restores the store playhead, not 0", () => {
+    // Drop → reload #1 consumes pendingSeek and seeks/syncs to 7.2. A staggered
+    // second reload (refreshPreviewDocumentVersion 80/300ms bumps) then finds the
+    // slot empty — the old code reset the playhead to 0 here.
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: null,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: 20,
+      }),
+    ).toBe(7.2);
+  });
+
+  it("fresh project load starts at 0 (store resets currentTime on project switch)", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: null,
+        requestedSeek: null,
+        storeCurrentTime: 0,
+        duration: 20,
+      }),
+    ).toBe(0);
+  });
+
+  it("clamps to duration when content shrank past the playhead (the one sanctioned move)", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 18,
+        requestedSeek: null,
+        storeCurrentTime: 18,
+        duration: 9,
+      }),
+    ).toBe(9);
+  });
+
+  it("a pending seek of 0 is an explicit position, not a missing value", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 0,
+        requestedSeek: 12,
+        storeCurrentTime: 5,
+        duration: 20,
+      }),
+    ).toBe(0);
+  });
+
+  it("returns the guarded target unclamped when the duration is non-finite (no seek(NaN))", () => {
+    // Mid-reload the adapter can report a NaN duration; Math.min(target, NaN) would
+    // be NaN and seek(NaN). The guarded target must pass through unclamped instead.
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 7.2,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: Number.NaN,
+      }),
+    ).toBe(7.2);
+    // A zero/negative duration is equally unusable — pass the target through.
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 7.2,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: 0,
+      }),
+    ).toBe(7.2);
+  });
+
+  it("guards against non-finite and negative targets", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: Number.NaN,
+        requestedSeek: null,
+        storeCurrentTime: 5,
+        duration: 20,
+      }),
+    ).toBe(0);
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: -3,
+        requestedSeek: null,
+        storeCurrentTime: 5,
+        duration: 20,
+      }),
+    ).toBe(0);
+  });
+});
+
+describe("resolveTimelineTotalDuration", () => {
+  it("THE BUG: a clip-manifest total shorter than the authored root duration never wins (stale '0:44/0:40')", () => {
+    // Fixture shape: root data-duration=44.5, furthest clip ends at 40. A runtime
+    // that measures the manifest from the furthest clip end reports 40s; playback
+    // still runs the full 44.5s, so the transport total must stay 44.5, not 40.
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 40,
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(44.5);
+  });
+
+  it("lets clips extend the total PAST the authored root (content can grow the timeline)", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 50,
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(50);
+  });
+
+  it("falls back to the manifest total when the root authors no duration", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 40,
+        authoredRootDurationSeconds: 0,
+      }),
+    ).toBe(40);
+  });
+
+  it("uses the authored root when the manifest is loop-inflated / non-finite", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: Number.POSITIVE_INFINITY,
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(44.5);
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 9000, // beyond the 7200s sanity cap
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(44.5);
+  });
+
+  it("returns 0 when neither source yields a usable duration", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: Number.NaN,
+        authoredRootDurationSeconds: -1,
+      }),
+    ).toBe(0);
+  });
+
+  it("floors the manifest at the authored root read from the fixture's DOM shape", () => {
+    // Reconstruct the fixture: root authored at 44.5s, last clip (v-letters)
+    // ends at 34 + 6 = 40s. readTimelineDurationFromDocument must report the
+    // authored 44.5, and flooring the 40s manifest total against it yields 44.5.
+    const doc = document.implementation.createHTMLDocument("fixture");
+    doc.body.innerHTML =
+      '<div id="main" data-composition-id="main" data-duration="44.5">' +
+      '<video class="clip" data-start="34" data-duration="6"></video>' +
+      "</div>";
+    const authoredRootDurationSeconds = readTimelineDurationFromDocument(doc);
+    expect(authoredRootDurationSeconds).toBe(44.5);
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 1200 / 30, // durationInFrames measured from clip end
+        authoredRootDurationSeconds,
+      }),
+    ).toBe(44.5);
+  });
+});
diff --git a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
index c943680b09..4992efb5c0 100644
--- a/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
+++ b/packages/studio/src/player/hooks/useTimelineSyncCallbacks.ts
@@ -19,6 +19,7 @@ import {
   createImplicitTimelineLayersFromDOM,
   buildStandaloneRootTimelineElement,
   getTimelineElementSelector,
+  readTimelineDurationFromDocument,
 } from "../lib/timelineDOM";
 import {
   normalizePreviewViewport,
@@ -41,6 +42,76 @@ interface UseTimelineSyncCallbacksParams {
   applyPreviewAudioState: () => void;
 }
 
+/**
+ * Where should the player seek when the preview (re)loads?
+ * Priority: explicit pending seek (saved by refreshPlayer right before a
+ * reload) → store-level seek request (deep-link `?t=` hydration) → the store's
+ * last known playhead. The last fallback makes the playhead RELOAD-INVARIANT:
+ * edits persist + reload the preview, sometimes more than once (App's
+ * refreshPreviewDocumentVersion staggers extra bumps at 80/300ms), and the
+ * consume-once pendingSeekRef meant any reload after the first found the slot
+ * empty and reset the playhead to 0 — the "dropped a file and the playhead
+ * jumped to 0" bug. Falling back to the store's playhead means every reload
+ * restores position; a fresh project load still starts at 0 because the store
+ * resets currentTime on project switch. Invariant: an edit NEVER moves the
+ * playhead (the clamp below is the one sanctioned move — content shrank past it).
+ */
+/**
+ * Undo the `visibility: hidden` that refreshPlayer sets across a full reload.
+ * Safe to call when the iframe was never hidden (idempotent no-op). Every reload
+ * completion + failure path funnels through here so the preview can never get
+ * stuck invisible.
+ */
+export function revealIframe(iframe: HTMLIFrameElement | null): void {
+  if (iframe && iframe.style.visibility === "hidden") {
+    iframe.style.visibility = "";
+  }
+}
+
+export function resolveReloadSeekTime(input: {
+  pendingSeek: number | null;
+  requestedSeek: number | null;
+  storeCurrentTime: number;
+  duration: number;
+}): number {
+  const target = input.pendingSeek ?? input.requestedSeek ?? input.storeCurrentTime;
+  if (!Number.isFinite(target) || target <= 0) return 0;
+  // Only clamp to duration when it's a usable positive number. A non-finite or
+  // non-positive duration (e.g. the adapter reports NaN mid-reload) would turn
+  // Math.min(target, NaN) into NaN and seek(NaN); return the guarded target
+  // unclamped instead so the playhead lands at the intended position.
+  if (!Number.isFinite(input.duration) || input.duration <= 0) return target;
+  return Math.min(target, input.duration);
+}
+
+/** Reject non-finite, non-positive, and absurdly large (loop-inflated) values. */
+function sanitizeDurationSeconds(value: number): number {
+  return Number.isFinite(value) && value > 0 && value < 7200 ? value : 0;
+}
+
+/**
+ * The transport TOTAL a clip-manifest message should write to the store.
+ *
+ * The manifest's `durationInFrames` measures the runtime timeline; some runtimes
+ * report only the furthest clip end and ignore the root composition's authored
+ * `data-duration`. When that manifest total is SHORTER than the authored root
+ * duration, writing it makes the readout stale (playback still runs the full
+ * authored window — the user saw "0:44/0:40" on a root authored at 44.5s whose
+ * last clip ends at 40s). The authored root duration is the floor for the total,
+ * so the readout can never sit below what the file declares. A manifest total
+ * that is LONGER (clips extend past the root) still wins — content can only grow
+ * the timeline, never shrink it below the authored window.
+ */
+export function resolveTimelineTotalDuration(input: {
+  manifestDurationSeconds: number;
+  authoredRootDurationSeconds: number;
+}): number {
+  return Math.max(
+    sanitizeDurationSeconds(input.manifestDurationSeconds),
+    sanitizeDurationSeconds(input.authoredRootDurationSeconds),
+  );
+}
+
 export function useTimelineSyncCallbacks({
   iframeRef,
   probeIntervalRef,
@@ -154,8 +225,14 @@ export function useTimelineSyncCallbacks({
       const rawDuration = data.durationInFrames / 30;
       // Clamp non-finite or absurdly large durations — the runtime can emit
       // Infinity when it detects a loop-inflated GSAP timeline without an
-      // explicit data-duration on the root composition.
-      const newDuration = Number.isFinite(rawDuration) && rawDuration < 7200 ? rawDuration : 0;
+      // explicit data-duration on the root composition. Floor the manifest total
+      // at the authored root `data-duration` so a runtime that measures only the
+      // furthest clip end (shorter than the authored window) can't leave a stale,
+      // too-short total in the transport (the "0:44/0:40" bug).
+      const newDuration = resolveTimelineTotalDuration({
+        manifestDurationSeconds: rawDuration,
+        authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
+      });
       const effectiveDuration = newDuration > 0 ? newDuration : usePlayerStore.getState().duration;
       const clampedEls =
         effectiveDuration > 0
@@ -218,12 +295,32 @@ export function useTimelineSyncCallbacks({
     // never reaches pendingSeekRef). Reconciling with the store here is what makes a
     // deep-linked `?t=` land instead of starting at 0.
     const storeSeek = usePlayerStore.getState().requestedSeekTime;
-    const seekTo = pendingSeekRef.current ?? storeSeek;
+    const startTime = resolveReloadSeekTime({
+      pendingSeek: pendingSeekRef.current,
+      requestedSeek: storeSeek,
+      storeCurrentTime: usePlayerStore.getState().currentTime,
+      duration: adapter.getDuration(),
+    });
     pendingSeekRef.current = null;
     if (storeSeek != null) usePlayerStore.getState().clearSeekRequest();
-    const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
 
+    // Force a REAL render at startTime, not a no-op. After a post-edit reload the
+    // freshly rebuilt GSAP timeline can already report being at `startTime`
+    // internally (the reload restores the same playhead), so a single
+    // `adapter.seek(startTime)` is a GSAP no-op — `tl.seek(t)` at the current time
+    // doesn't re-evaluate. That's why a just-dropped clip stayed invisible until
+    // the user nudged the playhead: its element's state was never applied at the
+    // restore position. Seeking to a DIFFERENT guard value first (a hair off, or 0
+    // when startTime is already ~0) guarantees the follow-up seek to `startTime`
+    // crosses a time boundary and re-renders every clip — including the new one.
+    const guardTime = startTime > 0.001 ? Math.max(0, startTime - 0.001) : 0.001;
+    adapter.seek(guardTime);
     adapter.seek(startTime);
+    // The correct frame is now rendered — reveal the iframe that refreshPlayer hid
+    // for the reload, so the user sees the restored frame directly (never the raw
+    // all-clips DOM). Cleared unconditionally: any later failure path must not leave
+    // the preview stuck invisible.
+    revealIframe(iframeRef.current);
     // Keep non-React listeners such as the capture link and time display in sync
     // with the initial adapter seek on iframe load.
     liveTime.notify(startTime);
@@ -332,6 +429,9 @@ export function useTimelineSyncCallbacks({
         trySettle();
       }
       window.removeEventListener("message", onMessage);
+      // Never leave the preview stuck invisible if the runtime never settled
+      // (initializeAdapter reveals on success; this covers the give-up case).
+      revealIframe(iframeRef.current);
     }, 5000) as unknown as ReturnType<typeof setInterval>;
   }, [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState]);
 

From db3b2241cb11767ee03b69b9ead31ba9f50ff420 Mon Sep 17 00:00:00 2001
From: ukimsanov <ular.kimsanov@heygen.com>
Date: Sat, 11 Jul 2026 13:55:05 -0700
Subject: [PATCH 24/24] feat(studio-server): files route extensions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What: the studio-server files route at its final NLE-stack form, with its
test suite (25 tests).

Why: standalone package seam — the server-side dependency of the studio
asset workflow, reviewable in isolation.

How: additive route behavior; existing route consumers unchanged.

Test plan: bunx vitest run src/routes/files.test.ts in packages/studio-server;
tsc --noEmit in packages/studio-server; fallow audit clean.
---
 .../studio-server/src/routes/files.test.ts    | 236 ++++++++++++++++++
 packages/studio-server/src/routes/files.ts    |  37 ++-
 2 files changed, 272 insertions(+), 1 deletion(-)

diff --git a/packages/studio-server/src/routes/files.test.ts b/packages/studio-server/src/routes/files.test.ts
index dfdcdcb9f8..90699abd5a 100644
--- a/packages/studio-server/src/routes/files.test.ts
+++ b/packages/studio-server/src/routes/files.test.ts
@@ -389,6 +389,145 @@ gsap.set("#box", { rotation: 45 });
     expect(payload.content).not.toContain("opacity");
   });
 
+  // ── Canvas z-order / patch-target regression suite ────────────────────────
+  // A right-click "move to back" on an id-less element (e.g. a caption `.sub`
+  // div) once serialized `target.id: null`, which findUnsafeDomPatchValues
+  // rejected as `body.target.id`, bricking the edit. The RULE: `target.id` is
+  // metadata, not a layout value — a null there is genuinely invalid and stays
+  // rejected; the fix is that the client omits an absent id instead of sending
+  // null, so the patch degrades to a hfId / selector + selectorIndex match.
+  it("rejects a null target.id in a DOM patch (documents the rule)", async () => {
+    const projectDir = createProjectDir();
+    writeFileSync(
+      join(projectDir, "index.html"),
+      '<div class="sub" style="z-index: 1">A</div><div class="sub" style="z-index: 2">B</div>',
+    );
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const before = readFileSync(join(projectDir, "index.html"), "utf-8");
+    const response = await app.request(
+      "http://localhost/projects/demo/file-mutations/patch-element/index.html",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          target: { id: null, selector: ".sub", selectorIndex: 1 },
+          operations: [{ type: "inline-style", property: "z-index", value: "0" }],
+        }),
+      },
+    );
+    const payload = (await response.json()) as { error?: string; fields?: string[] };
+
+    expect(response.status).toBe(400);
+    expect(payload.error).toContain("unsafe values");
+    expect(payload.fields).toContain("body.target.id");
+    expect(readFileSync(join(projectDir, "index.html"), "utf-8")).toBe(before);
+  });
+
+  it("z-reorder with an omitted id degrades to a selector patch (id-less element)", async () => {
+    const projectDir = createProjectDir();
+    writeFileSync(
+      join(projectDir, "index.html"),
+      '<div class="sub" style="z-index: 1">A</div><div class="sub" style="z-index: 2">B</div>',
+    );
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const response = await app.request(
+      "http://localhost/projects/demo/file-mutations/patch-element/index.html",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        // id omitted (undefined) — the fixed client shape for an id-less element.
+        body: JSON.stringify({
+          target: { selector: ".sub", selectorIndex: 1 },
+          operations: [{ type: "inline-style", property: "z-index", value: "0" }],
+        }),
+      },
+    );
+    const payload = (await response.json()) as { changed?: boolean; content?: string };
+
+    expect(response.status).toBe(200);
+    expect(payload.changed).toBe(true);
+    // The SECOND `.sub` (selectorIndex 1) is the one restacked, not the first.
+    expect(payload.content).toContain('<div class="sub" style="z-index: 1">A</div>');
+    expect(payload.content).toContain("z-index: 0");
+  });
+
+  it("duplicate-id document: a selector+index patch hits the right element, not a rejection", async () => {
+    const projectDir = createProjectDir();
+    // Two elements share id="main" AND class="root" (mirrors the user's project,
+    // where sub-compositions each carry id="main"). Match by selector + index.
+    writeFileSync(
+      join(projectDir, "index.html"),
+      '<div class="root" id="main" style="z-index: 5">first</div>' +
+        '<div class="root" id="main" style="z-index: 6">second</div>',
+    );
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const response = await app.request(
+      "http://localhost/projects/demo/file-mutations/patch-element/index.html",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          target: { selector: ".root", selectorIndex: 1 },
+          operations: [{ type: "inline-style", property: "z-index", value: "0" }],
+        }),
+      },
+    );
+    const payload = (await response.json()) as { changed?: boolean; content?: string };
+
+    expect(response.status).toBe(200);
+    expect(payload.changed).toBe(true);
+    // First "main" untouched; second one restacked.
+    expect(payload.content).toContain('<div class="root" id="main" style="z-index: 5">first</div>');
+    expect(payload.content).toContain("z-index: 0");
+  });
+
+  // Sibling canvas commits (position / size / text) carry real string ids like
+  // "v-hero" / "vo-part1" / "main". The guard must accept them — it only rejects
+  // null / non-finite numbers, never inspects the id string — so these never hit
+  // the z-order "unsafe values" variant.
+  it.each([
+    {
+      label: "position",
+      id: "v-hero",
+      op: { type: "inline-style", property: "left", value: "40px" },
+    },
+    {
+      label: "size",
+      id: "vo-part1",
+      op: { type: "inline-style", property: "width", value: "320px" },
+    },
+    {
+      label: "text",
+      id: "main",
+      op: { type: "text-content", property: "textContent", value: "Hi" },
+    },
+  ])("accepts a $label commit with a real fixture id ($id)", async ({ id, op }) => {
+    const projectDir = createProjectDir();
+    writeFileSync(join(projectDir, "index.html"), `<div id="${id}">x</div>`);
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const response = await app.request(
+      "http://localhost/projects/demo/file-mutations/patch-element/index.html",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ target: { id }, operations: [op] }),
+      },
+    );
+    const payload = (await response.json()) as { changed?: boolean; error?: string };
+
+    expect(response.status).toBe(200);
+    expect(payload.error).toBeUndefined();
+    expect(payload.changed).toBe(true);
+  });
+
   it("update-from-property returns 400 for a non-fromTo animation", async () => {
     const projectDir = createProjectDir();
     const TO_COMP = `<!DOCTYPE html><html><body><script data-hyperframes-gsap>
@@ -805,4 +944,101 @@ tl.to("#box", { opacity: 1, duration: 1 }, 0);
     // The variable target was not flattened to a string-literal selector
     expect(result.after).toContain("tl.to(kicker,");
   });
+
+  it("shift-positions-batch equals sequential single shifts (atomic multi-clip)", async () => {
+    const TWO_TWEENS = `<!DOCTYPE html><html><body><script data-hyperframes-gsap>
+const tl = gsap.timeline({ paused: true });
+tl.to("#a", { duration: 1, x: 100 }, 1);
+tl.to("#b", { duration: 1, x: 200 }, 2);
+</script></body></html>`;
+
+    const seqDir = createProjectDir();
+    writeHtml(seqDir, "seq.html", TWO_TWEENS);
+    const seqApp = new Hono();
+    registerFileRoutes(seqApp, createAdapter(seqDir));
+    await seqApp.request("http://localhost/projects/demo/gsap-mutations/seq.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "shift-positions", targetSelector: "#a", delta: 1 }),
+    });
+    const seqRes = await seqApp.request("http://localhost/projects/demo/gsap-mutations/seq.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "shift-positions", targetSelector: "#b", delta: 0.5 }),
+    });
+    const seqAfter = ((await seqRes.json()) as { after: string }).after;
+
+    const batchDir = createProjectDir();
+    writeHtml(batchDir, "batch.html", TWO_TWEENS);
+    const batchApp = new Hono();
+    registerFileRoutes(batchApp, createAdapter(batchDir));
+    const batchRes = await batchApp.request(
+      "http://localhost/projects/demo/gsap-mutations/batch.html",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          type: "shift-positions-batch",
+          shifts: [
+            { targetSelector: "#a", delta: 1 },
+            { targetSelector: "#b", delta: 0.5 },
+          ],
+        }),
+      },
+    );
+    const batch = (await batchRes.json()) as { ok: boolean; changed: boolean; after: string };
+
+    expect(batchRes.status).toBe(200);
+    expect(batch.ok).toBe(true);
+    expect(batch.changed).toBe(true);
+    // Batching #a then #b in one write == applying them as two sequential single shifts.
+    expect(batch.after).toBe(seqAfter);
+  });
+
+  it("reports no GSAP mutation for shift-positions-batch in a file with no GSAP script", async () => {
+    // Same contract as its shift-positions / scale-positions siblings: a file with
+    // no GSAP block is a no-op {ok, changed:false}, not a 400.
+    const projectDir = createProjectDir();
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const res = await app.request("http://localhost/projects/demo/gsap-mutations/index.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "shift-positions-batch",
+        shifts: [{ targetSelector: "#box", delta: 1 }],
+      }),
+    });
+    const result = (await res.json()) as { ok?: boolean; changed?: boolean; mutated?: boolean };
+
+    expect(res.status).toBe(200);
+    expect(result.ok).toBe(true);
+    expect(result.changed).toBe(false);
+    expect(result.mutated).toBe(false);
+  });
+
+  it("rejects a shift-positions-batch with a missing/non-array `shifts` field (400)", async () => {
+    const projectDir = createProjectDir();
+    writeHtml(
+      projectDir,
+      "comp.html",
+      `<!DOCTYPE html><html><body><script data-hyperframes-gsap>
+const tl = gsap.timeline({ paused: true });
+tl.to("#a", { duration: 1, x: 100 }, 1);
+</script></body></html>`,
+    );
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const res = await app.request("http://localhost/projects/demo/gsap-mutations/comp.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "shift-positions-batch" }),
+    });
+    const result = (await res.json()) as { error?: string };
+
+    expect(res.status).toBe(400);
+    expect(result.error).toContain("shifts");
+  });
 });
diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts
index 64124957c2..8ad12293ba 100644
--- a/packages/studio-server/src/routes/files.ts
+++ b/packages/studio-server/src/routes/files.ts
@@ -773,6 +773,13 @@ type GsapMutationRequest =
       targetSelector: string;
       delta: number;
     }
+  | {
+      // Batched shift: fold shiftPositionsInScript over N selectors in one write.
+      // Lets a multi-clip timeline move (ripple / insert) shift every affected
+      // clip's tweens atomically instead of one racing server round-trip per clip.
+      type: "shift-positions-batch";
+      shifts: Array<{ targetSelector: string; delta: number }>;
+    }
   | {
       type: "scale-positions";
       targetSelector: string;
@@ -815,6 +822,7 @@ const HOLD_SYNC_MUTATION_TYPES = new Set<string>([
   // Time-shift / time-scale tweens, which can move a keyframed position tween's start
   // across t=0, flipping hold need; stale holds are not repositioned by these ops.
   "shift-positions",
+  "shift-positions-batch",
   "scale-positions",
   // Retargets keyframed position tweens to a cloned element's selector; the old hold is
   // keyed to the prior selector, so holds must be rebuilt for the new target.
@@ -1101,6 +1109,14 @@ function executeGsapMutationAcorn(
       if (!targetSelector || !Number.isFinite(delta) || delta === 0) return block.scriptText;
       return shiftPositionsInScript(block.scriptText, targetSelector, delta);
     }
+    case "shift-positions-batch": {
+      let script = block.scriptText;
+      for (const s of body.shifts) {
+        if (!s.targetSelector || !Number.isFinite(s.delta) || s.delta === 0) continue;
+        script = shiftPositionsInScript(script, s.targetSelector, s.delta);
+      }
+      return script;
+    }
     case "scale-positions": {
       const { targetSelector, oldStart, oldDuration, newStart, newDuration } = body;
       if (
@@ -1463,6 +1479,15 @@ async function executeGsapMutationRecast(
       const { shiftPositionsInScript } = parser;
       return shiftPositionsInScript(block.scriptText, targetSelector, delta);
     }
+    case "shift-positions-batch": {
+      const { shiftPositionsInScript } = parser;
+      let script = block.scriptText;
+      for (const s of body.shifts) {
+        if (!s.targetSelector || !Number.isFinite(s.delta) || s.delta === 0) continue;
+        script = shiftPositionsInScript(script, s.targetSelector, s.delta);
+      }
+      return script;
+    }
     case "scale-positions": {
       const { targetSelector, oldStart, oldDuration, newStart, newDuration } = body;
       if (
@@ -2024,6 +2049,11 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
     if (unsafeFields.length > 0) {
       return rejectUnsafeMutationValues(c, unsafeFields);
     }
+    // Defensive shape guard: a malformed shift-positions-batch (missing/non-array
+    // `shifts`) would otherwise TypeError inside `for (const s of body.shifts)`.
+    if (body.type === "shift-positions-batch" && !Array.isArray(body.shifts)) {
+      return c.json({ error: "shift-positions-batch requires a `shifts` array" }, 400);
+    }
 
     let html = readFileSync(res.absPath, "utf-8");
     let block = extractGsapScriptBlock(html);
@@ -2046,7 +2076,12 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
       }
       block = extractGsapScriptBlock(html);
     }
-    if (!block && (body.type === "shift-positions" || body.type === "scale-positions")) {
+    if (
+      !block &&
+      (body.type === "shift-positions" ||
+        body.type === "scale-positions" ||
+        body.type === "shift-positions-batch")
+    ) {
       return c.json({
         ok: true,
         changed: false,