Merge remote-tracking branch 'upstream/main' into fix/ffprobe-robustness

# Conflicts:
#	packages/engine/src/utils/ffprobe.ts

Author: santhiprakash

.claude-plugin/plugin.json

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

.codex-plugin/plugin.json

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

.cursor-plugin/plugin.json

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

.fallowrc.jsonc

@@ -4,6 +4,7 @@
     "packages/producer/src/**/*.test.ts",
     "packages/aws-lambda/src/**/*.test.ts",
     "packages/gcp-cloud-run/src/**/*.test.ts",
+    "packages/gcp-cloud-run/terraform/*.test.ts",
     "packages/producer/src/regression-harness.ts",
     "packages/producer/src/regression-harness-distributed.test.ts",
     "packages/producer/src/regression-harness-lambda-local.ts",
@@ -397,6 +398,18 @@
     // require intrusive middleware changes beyond this PR's scope.
     "minLines": 6,
     "ignore": [
+      // AWS Lambda and GCP Cloud Run deliberately mirror the same distributed
+      // rendering lifecycle while retaining provider-specific SDK, storage, and
+      // retry semantics. The Plan v2 AWS adapter extends that existing symmetry;
+      // extracting a shared cloud abstraction would couple independent packages.
+      "packages/aws-lambda/src/handler.ts",
+      "packages/aws-lambda/src/s3Transport.ts",
+      // The GCP handler deliberately mirrors the AWS protocol lifecycle while
+      // retaining provider-specific GCS, HTTP, and Cloud Workflows semantics.
+      // Its tests also mirror the same wire-contract cases; a cross-provider
+      // test abstraction would hide the adapter boundary being asserted.
+      "packages/gcp-cloud-run/src/server.ts",
+      "packages/gcp-cloud-run/src/server.test.ts",
       // sourcePatcher.ts: pre-existing internal clones between the inline-style
       // and attribute tag-patchers; only the PatchOperation type gained two
       // optional fields here, but the line shift makes fallow re-flag them.

bun.lock

@@ -8,6 +8,63 @@ 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.72"
+  description="Released - 2026-07-26"
+  tags={["Release", "Producer", "Gcp Cloud Run", "AWS Lambda"]}
+>
+Distributed rendering now has a versioned Plan v2 contract with integrity-checked,
+content-addressed artifacts and a remote publisher seam for object-storage-backed
+workers, while retaining Plan v1 compatibility. This release also improves audio
+duration accuracy, diagnostics, deterministic media treatments, and animation tooling.
+
+## Features
+
+- **AWS Lambda:** Support plan protocol v2 ([5bf61d6df](https://github.com/heygen-com/hyperframes/commit/5bf61d6df0694c3077ecc7e84cd9d72f2029a5e6), [#2789](https://github.com/heygen-com/hyperframes/pull/2789))
+- **Producer:** Version distributed plan protocol ([f9f00b0ef](https://github.com/heygen-com/hyperframes/commit/f9f00b0efc2d1006967d5b2e0009ea3c3f6ed2e6), [#2777](https://github.com/heygen-com/hyperframes/pull/2777))
+- **Lint:** Dense motion re-sampling for content_overlap ([72e2f08f1](https://github.com/heygen-com/hyperframes/commit/72e2f08f15ceec105eb2bca6e9e35b8020e040be), [#2746](https://github.com/heygen-com/hyperframes/pull/2746))
+- **Studio:** Add keyframe ease editor ([c253dec23](https://github.com/heygen-com/hyperframes/commit/c253dec23b0a6f1ccfe49c17371fdc9823f73b4c))
+- **Core:** Add deterministic keyframe ease runtime ([5acbf240c](https://github.com/heygen-com/hyperframes/commit/5acbf240cbab38594d06b59b9ef7f2a4b37d31b7))
+- **Studio:** Add media treatment inspector ([39c2341c4](https://github.com/heygen-com/hyperframes/commit/39c2341c4d1edf52a00fb8db4a49553c739860cc))
+- **CLI:** Add agent-first media treatment tools ([4582881d0](https://github.com/heygen-com/hyperframes/commit/4582881d002c361afff59cc1c74ae072a50e17f7))
+- **Lint:** Add off_pivot_rotation hub-referenced layout check ([e710a1686](https://github.com/heygen-com/hyperframes/commit/e710a1686f2442b460ea4973dca0be97c81ef184), [#2744](https://github.com/heygen-com/hyperframes/pull/2744))
+- **Runtime:** Render media treatments deterministically ([944640c32](https://github.com/heygen-com/hyperframes/commit/944640c3283d604383fd437fcca8c63941d8e3d7))
+
+## Fixes
+
+- **Gcp Cloud Run:** Normalize v2 integrity codes ([0499a5cbc](https://github.com/heygen-com/hyperframes/commit/0499a5cbcb298c7dc4352a2d672b9e18c9db1d81), [#2790](https://github.com/heygen-com/hyperframes/pull/2790))
+- **Producer:** Document read-only plan hashing ([c6fdd9c01](https://github.com/heygen-com/hyperframes/commit/c6fdd9c0154aacef9e16ab9c89d3249d0ef5d356), [#2788](https://github.com/heygen-com/hyperframes/pull/2788))
+- **Producer:** Use portable audio padding filter ([3b9552ef9](https://github.com/heygen-com/hyperframes/commit/3b9552ef9db36b133485e4ce805892346e0b9006))
+- **Producer:** Normalize padded audio on sample timeline ([4b116b988](https://github.com/heygen-com/hyperframes/commit/4b116b98802c05f0eeb541878806692eea975541))
+- **Engine:** Stop mux at shortest normalized stream ([63bc525ca](https://github.com/heygen-com/hyperframes/commit/63bc525ca90b08356d50ebb41d4e15581c9d3470))
+- **Producer:** Preserve normalized audio mux duration ([532461599](https://github.com/heygen-com/hyperframes/commit/532461599b7518f4609002cdb314ff2ce9f3a70f))
+- **Render:** Cap final mux to video duration ([19258ea5b](https://github.com/heygen-com/hyperframes/commit/19258ea5ba47067e9d5756b122051c467ece0b04))
+- **Render:** Cap trimmed audio container duration ([afc4e96bb](https://github.com/heygen-com/hyperframes/commit/afc4e96bbed21dbcd29544a6be95d35db7dd4eed))
+- **Render:** Scope M4A priming preservation to trims ([9289551e9](https://github.com/heygen-com/hyperframes/commit/9289551e98958f006ec14af8ae9058096a4932fe))
+- **Render:** Preserve normalized M4A edit timing ([59c56d325](https://github.com/heygen-com/hyperframes/commit/59c56d325723bbcb7c54315023aedeb72b376cd8))
+- **Render:** Trim AAC packet padding exactly ([113a4985b](https://github.com/heygen-com/hyperframes/commit/113a4985b51bc1d77babe7113d6c96bbe46d41bf))
+- **Engine:** Preserve bounded ffprobe diagnostics ([8c5077068](https://github.com/heygen-com/hyperframes/commit/8c50770684bc87ca67592c45d4101e3c029193d2), [#2772](https://github.com/heygen-com/hyperframes/pull/2772))
+- **Audio:** Preserve causes and use portable padding ([37b88688e](https://github.com/heygen-com/hyperframes/commit/37b88688e7ae854e377c47fe3d9560ab0c930161), [#2769](https://github.com/heygen-com/hyperframes/pull/2769))
+- **Parsers:** Preserve duration-authored keyframe timing ([4bfbd89d6](https://github.com/heygen-com/hyperframes/commit/4bfbd89d633d5fd227023643db62d2a566984edb))
+- **Parsers:** Preserve authored keyframe intent ([d84e999f7](https://github.com/heygen-com/hyperframes/commit/d84e999f728e25cee15a71995805a52d0a7907c4))
+- **Studio:** Preserve composed media treatments ([d5c7d3ee1](https://github.com/heygen-com/hyperframes/commit/d5c7d3ee16c2db53b91c66353d4f6387fe23e920))
+- **Lint:** Drop false media_in_subcomposition rule ([e7f9918d2](https://github.com/heygen-com/hyperframes/commit/e7f9918d21f9fa57f1799c7b3ba38963cfcb52f1), [#2765](https://github.com/heygen-com/hyperframes/pull/2765))
+
+## Catalog
+
+- **Registry:** Add media treatment overlays ([b0d3164dd](https://github.com/heygen-com/hyperframes/commit/b0d3164ddb6177c6b31634f02a908fdae607850f))
+
+## Internal
+
+- **Producer:** Add remote-ready plan v2 publisher ([07f9a3de9](https://github.com/heygen-com/hyperframes/commit/07f9a3de954d663e61d0e7da233fe8d33a06a5f9), [#2792](https://github.com/heygen-com/hyperframes/pull/2792))
+- **Producer:** Remove stale audio concat remnants ([3ef194234](https://github.com/heygen-com/hyperframes/commit/3ef194234e6104664b8b1902ae916dd7480c3617))
+- **Render:** Cover duration-capped audio mux ([20188d637](https://github.com/heygen-com/hyperframes/commit/20188d637b51bed607593592469863ba189ea4ec))
+- **CLI:** Move render module collection outside hooks ([3b3d4f559](https://github.com/heygen-com/hyperframes/commit/3b3d4f559ca0b97a4d48d5dbaef10c296407c9cb), [#2780](https://github.com/heygen-com/hyperframes/pull/2780))
+- **Studio:** Simplify preview workspace layout ([bf47416e1](https://github.com/heygen-com/hyperframes/commit/bf47416e144bbd45c41375f357b229215aa11ccb))
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.7.71...v0.7.72).
+</Update>
+
 <Update
   label="HyperFrames v0.7.71"
   description="Released - 2026-07-24"

docs/changelog.mdx

@@ -75,6 +75,7 @@ aws stepfunctions start-execution \
   "ProjectS3Uri": "s3://${RENDER_BUCKET}/projects/my-project.tar.gz",
   "PlanOutputS3Prefix": "s3://${RENDER_BUCKET}/renders/$(date +%s)/",
   "OutputS3Uri": "s3://${RENDER_BUCKET}/output.mp4",
+  "PlanProtocol": "v1",
   "Config": {
     "fps": 30,
     "width": 1920,
@@ -91,6 +92,9 @@ EOF
 
 The Step Functions execution kicks off Plan, fans out RenderChunk via
 the Map state, and finally Assemble. Final mp4 lands at `OutputS3Uri`.
+`PlanProtocol` may be `"v1"` or `"v2"`; absent defaults to v1. V2 uses
+separate manifest and content-addressed artifact locators throughout the
+workflow and never places a v2 object in `PlanS3Uri`.
 
 ## Local invocation
 
@@ -119,13 +123,14 @@ the architecture works on a deployed Lambda — use the local smoke
 script:
 
 ```bash
-# All defaults (mp4-h264-sdr fixture, chunk counts 2/4/8, PSNR >= 40 dB).
+# Defaults use the fixture's meta.json minPsnr (30 dB for mp4-h264-sdr).
 ./scripts/smoke.sh
 
 # Customised:
 ./scripts/smoke.sh \
   --fixture mp4-h264-sdr \
   --chunk-counts 2,4,8,16 \
+  --plan-protocol both \
   --psnr-threshold 40 \
   --reserved-concurrency 8
 
@@ -141,7 +146,21 @@ per-run stack name, renders the fixture at each chunk count via the
 Step Functions state machine, PSNR-compares against the in-process
 baseline (which is git-LFS tracked under
 `packages/producer/tests/distributed/<fixture>/output/`), captures
-per-execution Step Functions history, and tears the stack down.
+per-execution Step Functions history, and tears the stack down. Use
+`--plan-protocol both` to run v1 and v2 through the same deployed Lambda
+package and baseline. Each v1/v2 pair is also gated directly on per-chunk
+hashes from Step Functions history, normalized decoded RGBA frame hashes,
+decoded 48 kHz stereo s16le PCM hashes and byte counts, normalized stream
+metadata, and duration. Encoded MP4 SHA equality is reported but is
+informational unless `--require-encoded-sha-equal` is set. The script
+assigns unique function/state-machine names, uses a
+dedicated temporary SAM artifact bucket, and removes render objects,
+retained buckets, the implicit Lambda log group, and deployment artifacts
+on teardown. Suspended-version buckets are purged in 1,000-entry batches,
+including concrete versions, null versions, and delete markers. It then
+verifies that the stack, both buckets, Lambda, state-machine, and both log
+groups are absent; an otherwise-successful run fails if cleanup cannot be
+proven.
 
 **Wall-clock methodology caveat (`eval.sh` only).** `eval.sh` reports a
 local-vs-Lambda "speedup" column. The local timing includes `bun` +
@@ -162,9 +181,11 @@ spend is roughly $0.10-$0.20 per pass before S3 transfer. Lower
 
 Outputs land under `<repo-root>/lambda-smoke-artifacts/`:
 
-- `results.json` — `chunkCount × wallClockMs × psnrAvgDb`
-- `renders/N<N>-output.mp4` — each rendered chunk count
-- `renders/N<N>-history.json` — full Step Functions execution history
+- `results.json` — `planProtocol × chunkCount × wallClockMs × psnrAvgDb`
+- `semantic-comparisons.json` — direct v1/v2 semantic gate results
+- `renders/<protocol>-N<N>-output.mp4` — each rendered variant
+- `renders/<protocol>-N<N>-history.json` — full Step Functions execution history
+- `renders/v1-v2-N<N>.*` — normalized frame hashes, ffprobe metadata, and comparison JSON
 
 Prerequisites: `aws` (v2), `sam` (≥ 1.100), `bun` (≥ 1.3), `ffmpeg`,
 `jq`, `zip`. AWS credentials come from the standard resolution chain

examples/aws-lambda/README.md

@@ -0,0 +1,11 @@
+{
+  "Action": "assemble",
+  "PlanProtocol": "v2",
+  "PlanV2ManifestS3Uri": "s3://example-bucket/renders/sample/v2/manifest.json",
+  "PlanV2ArtifactS3Prefix": "s3://example-bucket/renders/sample/v2/artifacts/sha256",
+  "PlanHash": "0000000000000000000000000000000000000000000000000000000000000000",
+  "ChunkS3Uris": ["s3://example-bucket/renders/sample/chunks/0000.mp4"],
+  "AudioS3Uri": null,
+  "OutputS3Uri": "s3://example-bucket/renders/sample/output.mp4",
+  "Format": "mp4"
+}

examples/aws-lambda/sample-events/assemble-v2.json

@@ -0,0 +1,15 @@
+{
+  "Action": "plan",
+  "PlanProtocol": "v2",
+  "ProjectS3Uri": "s3://example-bucket/projects/sample.tar.gz",
+  "PlanOutputS3Prefix": "s3://example-bucket/renders/sample/",
+  "Config": {
+    "fps": 30,
+    "width": 1920,
+    "height": 1080,
+    "format": "mp4",
+    "chunkSize": 240,
+    "maxParallelChunks": 8,
+    "runtimeCap": "lambda"
+  }
+}

examples/aws-lambda/sample-events/plan-v2.json

@@ -0,0 +1,10 @@
+{
+  "Action": "renderChunk",
+  "PlanProtocol": "v2",
+  "PlanV2ManifestS3Uri": "s3://example-bucket/renders/sample/v2/manifest.json",
+  "PlanV2ArtifactS3Prefix": "s3://example-bucket/renders/sample/v2/artifacts/sha256",
+  "PlanHash": "0000000000000000000000000000000000000000000000000000000000000000",
+  "ChunkIndex": 0,
+  "ChunkOutputS3Prefix": "s3://example-bucket/renders/sample/",
+  "Format": "mp4"
+}