chore: merge main

Author: miguel-heygen

.gitattributes

@@ -1,3 +1,9 @@
+# Normalize text files to LF on checkout and in the repo, regardless of the
+# contributor's OS. Without this, files saved on Windows can land in PRs with
+# CRLF endings or a UTF-8 BOM, which makes every line differ at the byte level
+# and trips GitHub's "Binary file not shown" diff heuristic.
+* text=auto eol=lf
+
 # Golden baseline videos for regression tests
 packages/producer/tests/*/output/output.mp4 filter=lfs diff=lfs merge=lfs -text
 

packages/cli/src/cli.ts

@@ -1,5 +1,35 @@
 #!/usr/bin/env node
 
+// ── Worker entry path bootstrap (must run before any producer/engine load) ──
+// The hf#677 worker_threads pools (`pngDecodeBlitWorkerPool`,
+// `shaderTransitionWorkerPool`) live in the producer package and try to
+// resolve their worker entry by probing for sibling `.js` files next to
+// `import.meta.url`. When this CLI is bundled by tsup, the producer code is
+// inlined into `cli.js`, but `import.meta.url` resolves to the producer's
+// own dist path (NOT cli.js) on some module-graph layouts — so the sibling
+// probe lands in a directory that does not contain the bundled workers.
+// We emit the worker entries next to cli.js (see tsup.config.ts) and tell
+// the pools where to find them via the published env-var overrides. The
+// pools have an explicit `workerEntryPath` factory option as the canonical
+// API, but setting the env vars here covers every call site without having
+// to thread the path through the renderOrchestrator → captureHdrStage →
+// captureHdrHybridLoop chain.
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+(() => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const shader = join(here, "shaderTransitionWorker.js");
+  const png = join(here, "pngDecodeBlitWorker.js");
+  if (!process.env.HF_SHADER_WORKER_ENTRY && existsSync(shader)) {
+    process.env.HF_SHADER_WORKER_ENTRY = shader;
+  }
+  if (!process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY && existsSync(png)) {
+    process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY = png;
+  }
+})();
+
 // ── Fast-path exits ─────────────────────────────────────────────────────────
 // Check --version before importing anything heavy. This makes
 // `hyperframes --version` near-instant (~10ms vs ~80ms).

packages/core/src/runtime/init.test.ts

@@ -263,6 +263,58 @@ describe("initSandboxRuntimeModular", () => {
     expect(video.currentTime).toBe(9);
   });
 
+  it("updates visibility for timed elements inside nested compositions", () => {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "main");
+    root.setAttribute("data-root", "true");
+    root.setAttribute("data-start", "0");
+    root.setAttribute("data-width", "1920");
+    root.setAttribute("data-height", "1080");
+    document.body.appendChild(root);
+
+    const child = document.createElement("div");
+    child.setAttribute("data-composition-id", "nested");
+    child.setAttribute("data-start", "10");
+    child.setAttribute("data-duration", "10");
+    root.appendChild(child);
+
+    const sceneA = document.createElement("section");
+    sceneA.id = "scene-a";
+    sceneA.setAttribute("data-start", "0");
+    sceneA.setAttribute("data-duration", "4");
+    child.appendChild(sceneA);
+
+    const sceneB = document.createElement("section");
+    sceneB.id = "scene-b";
+    sceneB.setAttribute("data-start", "4");
+    sceneB.setAttribute("data-duration", "4");
+    child.appendChild(sceneB);
+
+    (window as Window & { __timelines?: Record<string, RuntimeTimelineLike> }).__timelines = {
+      main: createMockTimeline(20),
+      nested: createMockTimeline(8),
+    };
+
+    initSandboxRuntimeModular();
+
+    const player = (
+      window as Window & {
+        __player?: { seek: (timeSeconds: number) => void };
+      }
+    ).__player;
+    expect(player).toBeDefined();
+
+    player?.seek(11);
+
+    expect(sceneA.style.visibility).toBe("visible");
+    expect(sceneB.style.visibility).toBe("hidden");
+
+    player?.seek(15);
+
+    expect(sceneA.style.visibility).toBe("hidden");
+    expect(sceneB.style.visibility).toBe("visible");
+  });
+
   it("clamps nested media to the authored host window on seek", () => {
     const root = document.createElement("div");
     root.setAttribute("data-composition-id", "main");

packages/core/src/runtime/init.ts

@@ -1316,27 +1316,12 @@ export function initSandboxRuntimeModular(): void {
         postRuntimeMessage({ source: "hf-preview", type: "media-autoplay-blocked" });
       },
     });
-    const rootCompId =
-      document.querySelector("[data-composition-id]")?.getAttribute("data-composition-id") ?? null;
     const visibilityNodes = Array.from(document.querySelectorAll("[data-start]"));
     for (const rawNode of visibilityNodes) {
       if (!(rawNode instanceof HTMLElement)) continue;
       const tag = rawNode.tagName.toLowerCase();
       if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") continue;
 
-      // Skip elements INSIDE sub-compositions — their visibility is managed by GSAP,
-      // not the global time-based adapter. Only manage visibility for:
-      // 1. Composition host elements (have data-composition-id themselves)
-      // 2. Direct children of root composition (audio, etc.)
-      // Skip: elements whose nearest composition ancestor is NOT the root
-      const ownCompId = rawNode.getAttribute("data-composition-id");
-      if (!ownCompId) {
-        // Not a composition host — check if it's inside a sub-composition
-        const parentComp = rawNode.closest("[data-composition-id]");
-        const parentCompId = parentComp?.getAttribute("data-composition-id") ?? null;
-        if (parentCompId && parentCompId !== rootCompId) continue;
-      }
-
       const start = resolveStartForElement(rawNode, 0);
       let duration = resolveDurationForElement(rawNode);
       const compId = rawNode.getAttribute("data-composition-id");

packages/producer/README.md

@@ -106,6 +106,38 @@ This is not chroma keying. There is no green/blue background to remove and no "k
 
 Don't paint a fullscreen background in your HTML. The default body background is overridden to transparent automatically — any `body { background: ... }`, `#root { background: ... }`, or `[data-composition-id] { background: ... }` rule is force-overridden during alpha rendering. Backgrounds on inner elements (cards, scenes, components) are kept.
 
+## Distributed rendering
+
+For renders too large for a single machine, the producer ships a public set of distributed-render primitives. They are pure functions over local file paths — networking and orchestration live in adapter packages (Temporal, AWS Lambda + Step Functions, Cloud Run Jobs, K8s Jobs).
+
+```typescript
+import { plan, renderChunk, assemble } from "@hyperframes/producer/distributed";
+
+// Controller-side: produce a self-contained planDir + content-addressed planHash.
+const planResult = await plan(
+  projectDir,
+  { fps: 30, width: 1920, height: 1080, format: "mp4" },
+  "/tmp/plan",
+);
+
+// Worker-side: render one chunk. Byte-identical retries on the same
+// `(planDir, chunkIndex)` — Temporal / Step Functions retry policies are safe
+// to point at this.
+const chunk = await renderChunk("/tmp/plan", 0, "/tmp/chunks/0.mp4");
+
+// Controller-side: stitch chunks into the final deliverable.
+await assemble(
+  "/tmp/plan",
+  ["/tmp/chunks/0.mp4", "/tmp/chunks/1.mp4"],
+  "/tmp/plan/audio.aac",
+  "/tmp/output.mp4",
+);
+```
+
+The three activity functions plus their result types are also re-exported from `@hyperframes/producer` so callers that pin the main package don't need a separate subpath import. Supported formats: `mp4` SDR, `mov` ProRes 4444, and `png-sequence`. webm and HDR mp4 trip a typed `FormatNotSupportedInDistributedError` — use the in-process renderer (`executeRenderJob`) for those.
+
+See [`DISTRIBUTED-RENDERING-PLAN.md`](../../DISTRIBUTED-RENDERING-PLAN.md) for the full architecture.
+
 ## How it works
 
 1. **Serve** — spins up a local file server for the HTML composition

packages/producer/build.mjs

@@ -93,6 +93,23 @@ await Promise.all([
     entryPoints: ["src/services/shaderTransitionWorker.ts"],
     outfile: "dist/services/shaderTransitionWorker.js",
   }),
+  // `@hyperframes/producer/distributed` subpath — the public distributed
+  // render primitives (plan / renderChunk / assemble). Bundled as a
+  // separate entry so adopters that don't need the in-process renderer
+  // (Lambda chunk workers, CDK constructs, thin orchestrators) can import
+  // only this surface and skip the rest of the producer's dependency tree.
+  build({
+    bundle: true,
+    platform: "node",
+    target: "node22",
+    format: "esm",
+    external: ["puppeteer", "esbuild", "postcss"],
+    plugins: [workspaceAliasPlugin],
+    minify: false,
+    sourcemap: true,
+    entryPoints: ["src/distributed.ts"],
+    outfile: "dist/distributed.js",
+  }),
 ]);
 
 // Copy core runtime artifacts so the producer can find them at dist/

packages/producer/package.json

@@ -20,6 +20,10 @@
     },
     "./server": {
       "import": "./dist/public-server.js"
+    },
+    "./distributed": {
+      "import": "./dist/distributed.js",
+      "types": "./dist/distributed.d.ts"
     }
   },
   "publishConfig": {
@@ -40,10 +44,12 @@
     "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: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 ../..",
     "docker:test": "docker run --rm --security-opt seccomp=unconfined --shm-size=2g -v ./tests:/app/packages/producer/tests hyperframes-producer:test",
     "docker:test:update": "docker run --rm --security-opt seccomp=unconfined --shm-size=2g -v ./tests:/app/packages/producer/tests hyperframes-producer:test --update",
+    "docker:test:distributed": "docker run --rm --security-opt seccomp=unconfined --shm-size=2g -v ./tests:/app/packages/producer/tests hyperframes-producer:test --mode=distributed-simulated",
     "prepublishOnly": "echo skip"
   },
   "dependencies": {

packages/producer/src/distributed.ts

@@ -0,0 +1,78 @@
+/**
+ * `@hyperframes/producer/distributed` — the distributed render primitives.
+ *
+ * See `DISTRIBUTED-RENDERING-PLAN.md` for the full architecture. The three
+ * activities (`plan` → `renderChunk` × N → `assemble`) are pure functions
+ * over local file paths; networking + orchestration live in adapters.
+ *
+ * Adopters (AWS Lambda, Cloud Run Jobs, Temporal, K8s Jobs, plain SSH):
+ *
+ * ```ts
+ * import {
+ *   plan,
+ *   renderChunk,
+ *   assemble,
+ * } from "@hyperframes/producer/distributed";
+ *
+ * // Controller-side: produce a self-contained planDir + content-addressed planHash.
+ * const planResult = await plan(projectDir, config, planDir);
+ *
+ * // Worker-side: render one chunk. Byte-identical retries on the same
+ * // (planDir, chunkIndex) — Temporal / Step Functions retry policies are
+ * // safe to point at this.
+ * const chunk = await renderChunk(planDir, chunkIndex, outputChunkPath);
+ *
+ * // Controller-side: stitch chunks into the final deliverable.
+ * await assemble(planDir, chunkPaths, audioPath, outputPath);
+ * ```
+ *
+ * No networking, no AWS SDK, no Temporal SDK — those live in adapter
+ * packages. This module is library code only.
+ */
+
+// ── Plan (Activity A) ───────────────────────────────────────────────────────
+export {
+  // Functions
+  buildChunkSlices,
+  measurePlanDirBytes,
+  plan,
+  rejectUnsupportedDistributedFormat,
+  resolveChunkPlan,
+  // Types
+  type DistributedRenderConfig,
+  type PlanResult,
+  // Constants
+  DEFAULT_CHUNK_SIZE,
+  DEFAULT_MAX_PARALLEL_CHUNKS,
+  PLAN_DIR_SIZE_LIMIT_BYTES,
+  // Error codes + classes
+  FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED,
+  FormatNotSupportedInDistributedError,
+  PLAN_TOO_LARGE,
+  PlanTooLargeError,
+} from "./services/distributed/plan.js";
+
+// ── RenderChunk (Activity B) ────────────────────────────────────────────────
+export {
+  applyRuntimeEnvSnapshot,
+  readWebGlVendorInfoFromCanvas,
+  renderChunk,
+  // Types
+  type ChunkResult,
+  // Error codes + classes
+  FFMPEG_VERSION_MISMATCH,
+  PLAN_HASH_MISMATCH,
+  RenderChunkValidationError,
+} from "./services/distributed/renderChunk.js";
+
+// ── Assemble (Activity C) ───────────────────────────────────────────────────
+export { assemble, type AssembleResult } from "./services/distributed/assemble.js";
+
+// ── Plan-time shared types from `freezePlan` ───────────────────────────────
+// Re-exported so adopters that deserialize a planDir's `meta/encoder.json`
+// or `meta/chunks.json` see the same shapes the producer wrote them as.
+export type {
+  ChunkSliceJson,
+  CompositionMetadataJson,
+  LockedRenderConfig,
+} from "./services/render/stages/freezePlan.js";

packages/producer/src/index.ts

@@ -75,3 +75,18 @@ export {
   runHyperframeLint,
   type PreparedHyperframeLintInput,
 } from "./services/hyperframeLint.js";
+
+// ── Distributed render primitives ───────────────────────────────────────────
+// The full surface lives at `@hyperframes/producer/distributed`; we
+// additionally re-export the three activity functions + their result
+// types here so callers that pin `@hyperframes/producer` don't need a
+// separate subpath import.
+export {
+  assemble,
+  plan,
+  renderChunk,
+  type AssembleResult,
+  type ChunkResult,
+  type DistributedRenderConfig,
+  type PlanResult,
+} from "./distributed.js";