Merge branch 'heygen-com:main' into main

Author: lovicho

.github/workflows/ci.yml

@@ -218,6 +218,18 @@ jobs:
       - run: bun run --cwd packages/core build:hyperframes-runtime
       - run: bun run --filter '!@hyperframes/producer' test
 
+  sdk-tests:
+    name: "SDK: unit + contract + smoke"
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+      - run: bun install --frozen-lockfile
+      - run: bun run --filter @hyperframes/sdk test
+
   test-runtime-contract:
     name: "Test: runtime contract"
     needs: changes

Dockerfile.test

@@ -80,6 +80,7 @@ COPY packages/studio/package.json packages/studio/package.json
 COPY packages/shader-transitions/package.json packages/shader-transitions/package.json
 COPY packages/aws-lambda/package.json packages/aws-lambda/package.json
 COPY packages/gcp-cloud-run/package.json packages/gcp-cloud-run/package.json
+COPY packages/sdk/package.json packages/sdk/package.json
 RUN bun install --frozen-lockfile
 
 # Copy source

docs/changelog.mdx

@@ -8,6 +8,79 @@ 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.6.95"
+  description="Released - 2026-06-12"
+  tags={["Release", "Engine"]}
+>
+Engine: adaptive memory-aware encoding with system memory monitoring, chunked encoder improvements, and streaming encoder resilience.
+
+## Features
+
+- **Engine:** Adaptive memory-aware encoding with system memory monitoring and dynamic chunk sizing
+- **Engine:** Chunked encoder improvements for parallel coordination
+- **Engine:** Streaming encoder resilience with better error recovery
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.6.94...v0.6.95).
+</Update>
+
+<Update
+  label="HyperFrames v0.6.94"
+  description="Released - 2026-06-12"
+  tags={["Release", "Studio"]}
+>
+Remove off-screen element indicators for UX redesign. The NLELayout unclipped overlay split remains for selection handle interaction near composition edges.
+
+## Fixes
+
+- **Studio:** Remove off-screen element indicators (UX redesign pending) ([#1376](https://github.com/heygen-com/hyperframes/pull/1376))
+- **Studio:** Clean up unused `onSelectElementById` prop ([#1377](https://github.com/heygen-com/hyperframes/pull/1377))
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.6.93...v0.6.94).
+</Update>
+
+<Update
+  label="HyperFrames v0.6.93"
+  description="Released - 2026-06-12"
+  tags={["Release", "Studio"]}
+>
+Hotfix: disable keyframes feature flag by default. The flag was accidentally shipped as enabled in v0.6.92.
+
+## Fixes
+
+- **Studio:** Set `STUDIO_KEYFRAMES_ENABLED` default to `false`
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.6.92...v0.6.93).
+</Update>
+
+<Update
+  label="HyperFrames v0.6.92"
+  description="Released - 2026-06-12"
+  tags={["Release", "Studio", "Core"]}
+>
+Per-property-group keyframe architecture: the keyframe system redesign ships across 7 stacked PRs. Each GSAP tween now targets a single property group (position, scale, rotation, etc.), eliminating cross-property contamination during drag, resize, and gesture recording.
+
+## Features
+
+- **Core:** Per-property-group type system (`PropertyGroupName`, `PROPERTY_GROUPS`, `classifyPropertyGroup`) ([#1354](https://github.com/heygen-com/hyperframes/pull/1354))
+- **Core:** `split-into-property-groups` and `replace-with-keyframes` server mutations ([#1355](https://github.com/heygen-com/hyperframes/pull/1355))
+- **Core:** `delete-all-for-selector` atomic mutation for bulk animation removal
+- **Studio:** GSAP drag intercept enabled by default with per-property-group routing ([#1356](https://github.com/heygen-com/hyperframes/pull/1356))
+- **Studio:** Gesture recording merges into existing position tweens instead of replacing ([#1359](https://github.com/heygen-com/hyperframes/pull/1359))
+- **Studio:** Unclipped overlay for off-screen element interaction ([#1360](https://github.com/heygen-com/hyperframes/pull/1360))
+
+## Fixes
+
+- **Studio:** Keyframe cache tags with `propertyGroup` for group-aware operations ([#1357](https://github.com/heygen-com/hyperframes/pull/1357))
+- **Studio:** Property panel routes keyframe diamonds to correct animation per property ([#1358](https://github.com/heygen-com/hyperframes/pull/1358))
+- **Studio:** Context menus portaled to `document.body` with smart overflow positioning
+- **Studio:** Delete All Keyframes uses atomic server mutation (no stale ID race)
+- **Studio:** Block CSS drag on GSAP-animated elements to prevent keyframe corruption
+- **Studio:** `onMoveKeyframe` percentage-space conversion (clip-relative to tween-relative)
+
+[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.6.91...v0.6.92).
+</Update>
+
 <Update
   label="HyperFrames v0.6.91"
   description="Released - 2026-06-11"

packages/aws-lambda/package.json

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

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/cli",
-  "version": "0.6.91",
+  "version": "0.6.95",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",

packages/cli/src/background-removal/pipeline.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file complexity
 /**
  * Background-removal rendering pipeline.
  *
@@ -14,7 +15,7 @@
  */
 import { spawn } from "node:child_process";
 import { extname } from "node:path";
-import { hasFFmpeg, hasFFprobe } from "../whisper/manager.js";
+import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
 import { createSession, type Session } from "./inference.js";
 import { type Device, type ModelId } from "./manager.js";
 
@@ -263,8 +264,9 @@ export function resolveRenderTargets(
 }
 
 export async function render(options: RenderOptions): Promise<RenderResult> {
-  if (!hasFFmpeg() || !hasFFprobe()) {
-    throw new Error("ffmpeg and ffprobe are required. Install: brew install ffmpeg");
+  const ffmpegPath = findFFmpeg();
+  if (!ffmpegPath || !findFFprobe()) {
+    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);
   }
 
   const { format, bgFormat } = resolveRenderTargets(
@@ -291,7 +293,14 @@ export async function render(options: RenderOptions): Promise<RenderResult> {
 
   try {
     const start = Date.now();
-    const framesProcessed = await runPipeline(options, session, media, format, bgFormat);
+    const framesProcessed = await runPipeline(
+      options,
+      session,
+      media,
+      format,
+      bgFormat,
+      ffmpegPath,
+    );
     const durationSeconds = (Date.now() - start) / 1000;
     const avgMsPerFrame = framesProcessed ? (durationSeconds * 1000) / framesProcessed : 0;
 
@@ -321,8 +330,13 @@ interface FfmpegProc {
 type StdioFd = "ignore" | "pipe";
 type StdioTuple = [StdioFd, StdioFd, StdioFd];
 
-function spawnFfmpeg(args: string[], label: string, stdio: StdioTuple): FfmpegProc {
-  const proc = spawn("ffmpeg", args, { stdio });
+function spawnFfmpeg(
+  ffmpegPath: string,
+  args: string[],
+  label: string,
+  stdio: StdioTuple,
+): FfmpegProc {
+  const proc = spawn(ffmpegPath, args, { stdio });
   let stderrBuf = "";
   proc.stderr?.on("data", (d: Buffer) => {
     stderrBuf += d.toString();
@@ -343,19 +357,22 @@ async function runPipeline(
   media: MediaInfo,
   format: OutputFormat,
   bgFormat: OutputFormat | undefined,
+  ffmpegPath: string,
 ): Promise<number> {
   const { inputPath, outputPath, backgroundOutputPath } = options;
   const { width, height, fps, frameCount } = media;
   const frameBytes = width * height * 3;
   const quality = options.quality ?? DEFAULT_QUALITY;
 
   const decoder = spawnFfmpeg(
+    ffmpegPath,
     ["-loglevel", "error", "-i", inputPath, "-f", "rawvideo", "-pix_fmt", "rgb24", "-an", "-"],
     "ffmpeg decoder",
     ["ignore", "pipe", "pipe"],
   );
 
   const fg = spawnFfmpeg(
+    ffmpegPath,
     buildEncoderArgs(format, width, height, fps || 30, outputPath, quality),
     "ffmpeg encoder",
     ["pipe", "ignore", "pipe"],
@@ -364,6 +381,7 @@ async function runPipeline(
   const bg =
     backgroundOutputPath && bgFormat
       ? spawnFfmpeg(
+          ffmpegPath,
           buildEncoderArgs(bgFormat, width, height, fps || 30, backgroundOutputPath, quality),
           "ffmpeg background encoder",
           ["pipe", "ignore", "pipe"],

packages/cli/src/browser/ffmpeg.ts

@@ -1,8 +1,14 @@
+// fallow-ignore-file code-duplication
 import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 
-export function findFFmpeg(): string | undefined {
+export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH";
+export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
+
+function findOnPath(name: "ffmpeg" | "ffprobe"): string | undefined {
   try {
-    const cmd = process.platform === "win32" ? "where ffmpeg" : "which ffmpeg";
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
     const output = execSync(cmd, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -12,18 +18,37 @@ export function findFFmpeg(): string | undefined {
       .split(/\r?\n/)
       .map((s) => s.trim())
       .find(Boolean);
-    return first || undefined;
+    return first ? resolve(first) : undefined;
   } catch {
     return undefined;
   }
 }
 
+function findConfiguredBinary(
+  envName: string,
+  binaryName: "ffmpeg" | "ffprobe",
+): string | undefined {
+  const configured = process.env[envName]?.trim();
+  if (configured) return existsSync(configured) ? resolve(configured) : undefined;
+  return findOnPath(binaryName);
+}
+
+export function findFFmpeg(): string | undefined {
+  return findConfiguredBinary(FFMPEG_PATH_ENV, "ffmpeg");
+}
+
+export function findFFprobe(): string | undefined {
+  return findConfiguredBinary(FFPROBE_PATH_ENV, "ffprobe");
+}
+
 export function getFFmpegInstallHint(): string {
   switch (process.platform) {
     case "darwin":
       return "brew install ffmpeg";
     case "linux":
       return "sudo apt install ffmpeg";
+    case "win32":
+      return "Download the 64-bit Windows build from https://ffmpeg.org/download.html#build-windows and add its bin/ directory to PATH.";
     default:
       return "https://ffmpeg.org/download.html";
   }

packages/cli/src/browser/manager.test.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 /**
  * Browser-binary resolution tests for `findBrowser()`.
  *
@@ -72,30 +73,34 @@ function installFsMocks({ existing, dirs }: FsMockOptions) {
 function installPuppeteerBrowsersMock(
   opts: {
     installedInHfCache?: Array<{ browser: string; executablePath: string }>;
+    installResult?: { executablePath: string };
   } = {},
 ) {
   vi.doMock("@puppeteer/browsers", () => ({
     Browser: { CHROMEHEADLESSSHELL: "chrome-headless-shell" },
     detectBrowserPlatform: () => "linux",
     getInstalledBrowsers: vi.fn().mockResolvedValue(opts.installedInHfCache ?? []),
-    install: vi.fn(),
+    install: vi.fn().mockResolvedValue(opts.installResult ?? { executablePath: HF_BINARY }),
   }));
 }
 
 describe("findBrowser — cache resolution", () => {
   const origPlatform = process.platform;
+  const origArch = process.arch;
 
   beforeEach(() => {
     vi.resetModules();
     // Force Linux for the system-fallback warning assertions. The
     // `Object.defineProperty` dance is needed because `process.platform` is a
     // getter on Node — direct assignment is silently a no-op.
     Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    Object.defineProperty(process, "arch", { value: "x64", configurable: true });
     delete process.env["HYPERFRAMES_BROWSER_PATH"];
   });
 
   afterEach(() => {
     Object.defineProperty(process, "platform", { value: origPlatform, configurable: true });
+    Object.defineProperty(process, "arch", { value: origArch, configurable: true });
     vi.restoreAllMocks();
     vi.doUnmock("node:fs");
     vi.doUnmock("node:os");
@@ -117,6 +122,28 @@ describe("findBrowser — cache resolution", () => {
     expect(result).toEqual({ executablePath: HF_BINARY, source: "cache" });
   });
 
+  it("re-downloads when the hyperframes cache manifest points at a missing binary", async () => {
+    const redownloadedBinary = join(
+      HF_CACHE,
+      "chrome-headless-shell",
+      "linux-131.0.6778.85",
+      "chrome-headless-shell-linux64",
+      "redownloaded-chrome-headless-shell",
+    );
+    installFsMocks({ existing: new Set([HF_CACHE]) });
+    installPuppeteerBrowsersMock({
+      installedInHfCache: [{ browser: "chrome-headless-shell", executablePath: HF_BINARY }],
+      installResult: { executablePath: redownloadedBinary },
+    });
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const { findBrowser } = await import("./manager.js");
+    const result = await findBrowser();
+
+    expect(result).toEqual({ executablePath: redownloadedBinary, source: "download" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Cached binary missing"));
+  });
+
   it("falls back to the puppeteer-managed cache when hyperframes cache is empty", async () => {
     // Empty hyperframes cache, populated puppeteer cache — the regression
     // scenario from the hf#677 spike.