diff --git a/docs/guides/remove-background.mdx b/docs/guides/remove-background.mdx
index a7cb06bc7..334bb1163 100644
--- a/docs/guides/remove-background.mdx
+++ b/docs/guides/remove-background.mdx
@@ -80,6 +80,71 @@ npx hyperframes remove-background subject.mp4 -o transparent.mov # editi
npx hyperframes remove-background portrait.jpg -o cutout.png # still image
```
+## Layer separation: emit the cutout and the background plate together
+
+Pass `--background-output` (alias `-b`) to write a *second* transparent video alongside the cutout. Same source RGB, alpha is the *inverse* mask — opaque where the surroundings were, transparent where the subject is. The result is a clean two-layer separation in a single inference pass:
+
+```bash Terminal
+npx hyperframes remove-background subject.mp4 \
+ -o subject.webm \
+ --background-output plate.webm
+```
+
+| Output | Alpha | Use it as |
+| ------ | ----- | --------- |
+| `subject.webm` | Mask — subject opaque | Foreground layer (top of stack) |
+| `plate.webm` | `255 − mask` — subject region transparent | Background layer; place anything you want **under the subject's silhouette** between this and `subject.webm` |
+
+Both encoders share the source W/H/fps and your `--quality` preset, so the layers are pixel-aligned. Encode cost roughly doubles; segmentation cost is unchanged.
+
+
+**This is a hole-cut plate, not an inpainted clean plate.** The subject region in `plate.webm` is fully transparent — you have to composite something opaque under it (a graphic, a blurred copy, a different scene) to fill the hole. If you need an actual filled background where the subject was, use a video inpainter (LaMa, ProPainter, RunwayML Inpaint) — `remove-background` is not the right tool for that.
+
+
+### Hole-cut vs. clean plate — when does the difference matter?
+
+A **hole-cut plate** keeps the original surroundings and makes the subject region transparent. A **clean plate** fills the subject region with reconstructed background — produced by a separate inpainting model. Display each alone over black:
+
+| | Hole-cut plate (this command) | Clean plate (inpainted) |
+| --- | --- | --- |
+| Subject region | Transparent silhouette | Reconstructed background pixels |
+| What you see alone | A person-shaped hole | An empty room |
+| Cost | One inference pass, one extra ffmpeg encode | A second model (LaMa, ProPainter, E2FGVI) |
+| Tool | `remove-background --background-output` | Outside this CLI |
+
+The line is: **does anything ever need to be visible *through* the subject's silhouette where the subject used to be?**
+
+| Use case | What you need |
+| --- | --- |
+| Text/graphics live *between* the cutout and the plate (the example above) | **Hole-cut** — the graphics fill the hole. |
+| Composite the subject onto an unrelated scene | Neither. Just use `subject.webm`; the plate is irrelevant. |
+| Show "the room without the person" as a real background | **Clean plate** — a hole-cut plate would show a transparent void. |
+| Replace the person with a different subject (re-target) | **Clean plate** — the new subject needs real pixels under it. |
+| VFX rotoscoping / "remove an extra from this take" | **Clean plate** — the canonical inpainting use case. |
+
+If something opaque always covers the silhouette, hole-cut is sufficient and ~1000× cheaper than running an inpainter.
+
+### The two-layer composition pattern
+
+The two-layer pattern is functionally a drop-in for [text-behind-subject](#text-behind-subject-the-recommended-layout) without needing the original `presenter.mp4` in the project — the plate replaces it as the bottom layer:
+
+```html
+
+
+
+
+
+ MAKE IT IN HYPERFRAMES
+
+
+
+
+
+
+```
+
+Constraints: the flag requires a video input and `.webm` or `.mov` for both outputs. It's not valid for image inputs (no temporal pairing to do) and won't accept `.png` for the plate.
+
## Performance
Real-world numbers from the [matting eval](https://www.heygenverse.com/a/0dd5a431-1832-4858-862d-de7fb7d02654), running u²-net_human_seg on a 4-second 1080p clip:
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 57f8a0811..f9ae12f72 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -356,6 +356,10 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
# Single image → transparent PNG
npx hyperframes remove-background portrait.jpg -o cutout.png
+ # Layer separation: cutout AND inverse-alpha background plate in one pass
+ npx hyperframes remove-background avatar.mp4 \
+ -o subject.webm --background-output plate.webm
+
# Force CPU on a machine that has CoreML or CUDA
npx hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu
@@ -366,8 +370,9 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
| Flag | Description |
|------|-------------|
| `--output, -o` | Output path. Format inferred from extension: `.webm` (default), `.mov`, `.png` |
+ | `--background-output, -b` | Optional second output: inverse-alpha background plate (subject region transparent, surroundings opaque). Same source RGB, complementary mask. Must be `.webm` or `.mov`. Hole-cut, not inpainted — composite something underneath to fill the hole. |
| `--device` | Execution provider: `auto` (default), `cpu`, `coreml`, `cuda` |
- | `--quality` | WebM encoder preset: `fast` (crf 30, smallest), `balanced` (crf 18, default), `best` (crf 12, near-lossless). Higher quality keeps the cutout's RGB closer to the source mp4 — important when overlaying the cutout on its own source for text-behind-subject effects. Ignored for `.mov` / `.png`. |
+ | `--quality` | WebM encoder preset: `fast` (crf 30, smallest), `balanced` (crf 18, default), `best` (crf 12, near-lossless). Higher quality keeps the cutout's RGB closer to the source mp4 — important when overlaying the cutout on its own source for text-behind-subject effects. Applies to both `--output` and `--background-output`. Ignored for `.mov` / `.png`. |
| `--info` | Print detected execution providers and exit (no render) |
| `--json` | Output result as JSON |
diff --git a/packages/cli/src/background-removal/inference.test.ts b/packages/cli/src/background-removal/inference.test.ts
index ffc62cc0b..719bcab4d 100644
--- a/packages/cli/src/background-removal/inference.test.ts
+++ b/packages/cli/src/background-removal/inference.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { MEAN, STD } from "./inference.js";
+import { MEAN, STD, applyMask } from "./inference.js";
// Regression: the u2net_human_seg model was trained with ImageNet
// normalization. Drifting away from these exact values changes the input
@@ -16,3 +16,112 @@ describe("background-removal/inference — rembg u2net_human_seg parity", () =>
expect(STD).toEqual([0.229, 0.224, 0.225]);
});
});
+
+// These tests pin the contract that `--background-output` is built on:
+// fg.alpha + bg.alpha === 255 per pixel, and the RGB plane is byte-identical
+// between fg and bg. A future change to the postprocess loop (different mask
+// threshold, premultiplied alpha, gamma-corrected compositing) that breaks
+// either invariant should fail here loudly.
+describe("background-removal/inference — applyMask invariants", () => {
+ function makeRgb(pixels: number): Buffer {
+ // Deterministic but non-trivial RGB so byte equality is meaningful.
+ const buf = Buffer.allocUnsafe(pixels * 3);
+ for (let i = 0; i < pixels; i++) {
+ buf[i * 3] = (i * 7) & 0xff;
+ buf[i * 3 + 1] = (i * 13 + 31) & 0xff;
+ buf[i * 3 + 2] = (i * 19 + 61) & 0xff;
+ }
+ return buf;
+ }
+
+ function makeMask(pixels: number): Buffer {
+ // Hit the saturation endpoints (0, 255) and a few mid-tone values so the
+ // 255-m inversion is exercised across the full byte range.
+ const buf = Buffer.allocUnsafe(pixels);
+ for (let i = 0; i < pixels; i++) buf[i] = (i * 37) & 0xff;
+ return buf;
+ }
+
+ it("dual-output: fg.alpha + bg.alpha === 255 for every pixel", () => {
+ const pixels = 64;
+ const rgb = makeRgb(pixels);
+ const mask = makeMask(pixels);
+ const fg = Buffer.allocUnsafe(pixels * 4);
+ const bg = Buffer.allocUnsafe(pixels * 4);
+
+ const result = applyMask(rgb, mask, fg, bg, pixels);
+
+ expect(result.fg).toBe(fg);
+ expect(result.bg).toBe(bg);
+ for (let i = 0; i < pixels; i++) {
+ const sum = fg[i * 4 + 3]! + bg[i * 4 + 3]!;
+ expect(sum).toBe(255);
+ }
+ });
+
+ it("dual-output: RGB triples are byte-identical between fg and bg", () => {
+ const pixels = 64;
+ const rgb = makeRgb(pixels);
+ const mask = makeMask(pixels);
+ const fg = Buffer.allocUnsafe(pixels * 4);
+ const bg = Buffer.allocUnsafe(pixels * 4);
+
+ applyMask(rgb, mask, fg, bg, pixels);
+
+ for (let i = 0; i < pixels; i++) {
+ expect(fg[i * 4]).toBe(bg[i * 4]);
+ expect(fg[i * 4 + 1]).toBe(bg[i * 4 + 1]);
+ expect(fg[i * 4 + 2]).toBe(bg[i * 4 + 2]);
+ // And both match the source.
+ expect(fg[i * 4]).toBe(rgb[i * 3]);
+ expect(fg[i * 4 + 1]).toBe(rgb[i * 3 + 1]);
+ expect(fg[i * 4 + 2]).toBe(rgb[i * 3 + 2]);
+ }
+ });
+
+ it("dual-output: fg.alpha equals the input mask", () => {
+ const pixels = 32;
+ const rgb = makeRgb(pixels);
+ const mask = makeMask(pixels);
+ const fg = Buffer.allocUnsafe(pixels * 4);
+ const bg = Buffer.allocUnsafe(pixels * 4);
+
+ applyMask(rgb, mask, fg, bg, pixels);
+
+ for (let i = 0; i < pixels; i++) {
+ expect(fg[i * 4 + 3]).toBe(mask[i]);
+ }
+ });
+
+ it("single-output: bg=null returns bg=null and writes only fg", () => {
+ const pixels = 32;
+ const rgb = makeRgb(pixels);
+ const mask = makeMask(pixels);
+ const fg = Buffer.allocUnsafe(pixels * 4);
+
+ const result = applyMask(rgb, mask, fg, null, pixels);
+
+ expect(result.bg).toBeNull();
+ expect(result.fg).toBe(fg);
+ for (let i = 0; i < pixels; i++) {
+ expect(fg[i * 4]).toBe(rgb[i * 3]);
+ expect(fg[i * 4 + 3]).toBe(mask[i]);
+ }
+ });
+
+ it("saturates correctly at mask=0 and mask=255", () => {
+ // mask=0 → fg.alpha=0 (transparent subject), bg.alpha=255 (fully opaque plate)
+ // mask=255 → fg.alpha=255 (fully opaque subject), bg.alpha=0 (transparent plate)
+ const rgb = Buffer.from([10, 20, 30, 40, 50, 60]);
+ const mask = Buffer.from([0, 255]);
+ const fg = Buffer.allocUnsafe(8);
+ const bg = Buffer.allocUnsafe(8);
+
+ applyMask(rgb, mask, fg, bg, 2);
+
+ expect(fg[3]).toBe(0);
+ expect(bg[3]).toBe(255);
+ expect(fg[7]).toBe(255);
+ expect(bg[7]).toBe(0);
+ });
+});
diff --git a/packages/cli/src/background-removal/inference.ts b/packages/cli/src/background-removal/inference.ts
index d0b3d8adb..605257fc3 100644
--- a/packages/cli/src/background-removal/inference.ts
+++ b/packages/cli/src/background-removal/inference.ts
@@ -24,10 +24,24 @@ interface OrtModule {
Tensor: typeof Tensor;
}
+export interface SessionResult {
+ /** Subject opaque, background fully transparent. */
+ fg: Buffer;
+ /** Inverse-alpha plate: same RGB, alpha is `255 − mask`. Null unless `withBackground` was true. */
+ bg: Buffer | null;
+}
+
export interface Session {
- /** Run inference on one RGB frame, return RGBA bytes (H*W*4). */
- process(rgb: Buffer, width: number, height: number): Promise;
- /** ORT EP that was actually selected. */
+ /**
+ * Both `fg` and `bg` (when requested) are session-owned buffers reused on the
+ * next call — drain the encoder's stdin before invoking `process` again.
+ */
+ process(
+ rgb: Buffer,
+ width: number,
+ height: number,
+ withBackground?: boolean,
+ ): Promise;
provider: string;
close(): Promise;
}
@@ -73,16 +87,15 @@ export async function createSession(options: CreateSessionOptions = {}): Promise
throw new Error("ONNX session is missing input or output bindings");
}
- // Pre-allocated per-frame buffers reused across every process() call.
- // At 1080p this saves ~9 MB of allocations per frame. rgbaBuf is sized
- // lazily on the first call (we don't know W/H until then).
+ // Reused across calls; sized lazily on first frame. Saves ~9 MB/frame at 1080p.
const inputData = new Float32Array(3 * INPUT_PLANE);
const maskBuf = Buffer.allocUnsafe(INPUT_PLANE);
let rgbaBuf: Buffer | null = null;
+ let rgbaBgBuf: Buffer | null = null;
return {
provider: providerUsed,
- async process(rgb, width, height) {
+ async process(rgb, width, height, withBackground = false) {
const tensor = await preprocess(sharp, ort, rgb, width, height, inputData);
const outputs = await session.run({ [inputName]: tensor });
const output = outputs[outputName];
@@ -91,7 +104,21 @@ export async function createSession(options: CreateSessionOptions = {}): Promise
if (!rgbaBuf || rgbaBuf.length !== expectedBytes) {
rgbaBuf = Buffer.allocUnsafe(expectedBytes);
}
- return await postprocess(sharp, output, rgb, width, height, maskBuf, rgbaBuf);
+ if (withBackground) {
+ if (!rgbaBgBuf || rgbaBgBuf.length !== expectedBytes) {
+ rgbaBgBuf = Buffer.allocUnsafe(expectedBytes);
+ }
+ }
+ return await postprocess(
+ sharp,
+ output,
+ rgb,
+ width,
+ height,
+ maskBuf,
+ rgbaBuf,
+ withBackground ? rgbaBgBuf : null,
+ );
},
async close() {
await session.release();
@@ -141,7 +168,8 @@ async function postprocess(
height: number,
maskBuf: Buffer,
rgbaBuf: Buffer,
-): Promise {
+ rgbaBgBuf: Buffer | null,
+): Promise {
const raw = output.data as Float32Array;
let lo = Infinity;
@@ -172,11 +200,50 @@ async function postprocess(
.raw()
.toBuffer();
- for (let i = 0; i < width * height; i++) {
- rgbaBuf[i * 4] = rgb[i * 3]!;
- rgbaBuf[i * 4 + 1] = rgb[i * 3 + 1]!;
- rgbaBuf[i * 4 + 2] = rgb[i * 3 + 2]!;
- rgbaBuf[i * 4 + 3] = fullMask[i]!;
+ return applyMask(rgb, fullMask, rgbaBuf, rgbaBgBuf, width * height);
+}
+
+/**
+ * Composite the RGB source frame with the segmentation mask into one or two
+ * RGBA buffers. The contract this PR is built on:
+ * - `fg`'s alpha is the mask, `bg`'s alpha (when provided) is `255 − mask`,
+ * so `fg.alpha + bg.alpha === 255` for every pixel.
+ * - RGB triples are byte-identical between `fg` and `bg`.
+ * - When `bg` is null, only `fg` is touched.
+ *
+ * Exported for direct unit testing of the invariants above without spinning
+ * up an ONNX session.
+ */
+export function applyMask(
+ rgb: Buffer,
+ mask: Buffer,
+ fg: Buffer,
+ bg: Buffer | null,
+ pixels: number,
+): SessionResult {
+ if (bg) {
+ for (let i = 0; i < pixels; i++) {
+ const r = rgb[i * 3]!;
+ const g = rgb[i * 3 + 1]!;
+ const b = rgb[i * 3 + 2]!;
+ const m = mask[i]!;
+ const o = i * 4;
+ fg[o] = r;
+ fg[o + 1] = g;
+ fg[o + 2] = b;
+ fg[o + 3] = m;
+ bg[o] = r;
+ bg[o + 1] = g;
+ bg[o + 2] = b;
+ bg[o + 3] = 255 - m;
+ }
+ return { fg, bg };
}
- return rgbaBuf;
+ for (let i = 0; i < pixels; i++) {
+ fg[i * 4] = rgb[i * 3]!;
+ fg[i * 4 + 1] = rgb[i * 3 + 1]!;
+ fg[i * 4 + 2] = rgb[i * 3 + 2]!;
+ fg[i * 4 + 3] = mask[i]!;
+ }
+ return { fg, bg: null };
}
diff --git a/packages/cli/src/background-removal/pipeline.test.ts b/packages/cli/src/background-removal/pipeline.test.ts
index 7bc5488a9..5763efb06 100644
--- a/packages/cli/src/background-removal/pipeline.test.ts
+++ b/packages/cli/src/background-removal/pipeline.test.ts
@@ -1,7 +1,13 @@
import { describe, expect, it } from "vitest";
import { EventEmitter } from "node:events";
import type { spawn } from "node:child_process";
-import { inferOutputFormat, inferInputKind, buildEncoderArgs, waitForExit } from "./pipeline.js";
+import {
+ inferOutputFormat,
+ inferInputKind,
+ buildEncoderArgs,
+ resolveRenderTargets,
+ waitForExit,
+} from "./pipeline.js";
describe("background-removal/pipeline — inferOutputFormat", () => {
it("maps .webm → webm", () => {
@@ -97,6 +103,54 @@ describe("background-removal/pipeline — buildEncoderArgs", () => {
});
});
+describe("background-removal/pipeline — resolveRenderTargets", () => {
+ it("resolves a normal video → webm render", () => {
+ const t = resolveRenderTargets("/tmp/clip.mp4", "/tmp/cutout.webm");
+ expect(t.format).toBe("webm");
+ expect(t.inputKind).toBe("video");
+ expect(t.bgFormat).toBeUndefined();
+ });
+
+ it("resolves an image → png render", () => {
+ const t = resolveRenderTargets("/tmp/portrait.jpg", "/tmp/cutout.png");
+ expect(t.format).toBe("png");
+ expect(t.inputKind).toBe("image");
+ });
+
+ it("rejects image input with a video output extension", () => {
+ expect(() => resolveRenderTargets("/tmp/portrait.jpg", "/tmp/cutout.webm")).toThrow(
+ /Image input requires a \.png output/,
+ );
+ });
+
+ it("rejects video input with a .png output", () => {
+ expect(() => resolveRenderTargets("/tmp/clip.mp4", "/tmp/cutout.png")).toThrow(
+ /Video input requires a \.webm or \.mov output/,
+ );
+ });
+
+ it("threads background-output format through when valid", () => {
+ const t = resolveRenderTargets("/tmp/clip.mp4", "/tmp/fg.webm", "/tmp/bg.webm");
+ expect(t.bgFormat).toBe("webm");
+ const tMov = resolveRenderTargets("/tmp/clip.mp4", "/tmp/fg.webm", "/tmp/bg.mov");
+ expect(tMov.bgFormat).toBe("mov");
+ });
+
+ it("rejects --background-output for image inputs (no temporal pairing to do)", () => {
+ expect(() =>
+ resolveRenderTargets("/tmp/portrait.jpg", "/tmp/cutout.png", "/tmp/bg.png"),
+ ).toThrow(/--background-output is not supported for image inputs/);
+ });
+
+ it("rejects .png as the --background-output extension", () => {
+ // .png is only valid for single-image inputs, and image inputs themselves
+ // can't have a background-output anyway. So .png here is always a misuse.
+ expect(() => resolveRenderTargets("/tmp/clip.mp4", "/tmp/fg.webm", "/tmp/bg.png")).toThrow(
+ /--background-output must be \.webm or \.mov/,
+ );
+ });
+});
+
// Regression: a previous version of waitForExit treated `code === null` as
// success. Per Node's child_process docs, that's the signal-killed case —
// reporting it as success means a SIGTERM/SIGKILL'd ffmpeg encoder produces
diff --git a/packages/cli/src/background-removal/pipeline.ts b/packages/cli/src/background-removal/pipeline.ts
index 99b95386e..a0a0f3bfc 100644
--- a/packages/cli/src/background-removal/pipeline.ts
+++ b/packages/cli/src/background-removal/pipeline.ts
@@ -38,6 +38,16 @@ export const isQuality = (v: unknown): v is Quality =>
export interface RenderOptions {
inputPath: string;
outputPath: string;
+ /**
+ * Optional second output: an inverse-alpha background plate (same source
+ * RGB, transparent where the subject was). Only valid for video inputs and
+ * .webm/.mov outputs — not allowed alongside a .png output. The plate's
+ * format is inferred from this path independently of the foreground's.
+ *
+ * NOTE: this is a hole-cut plate, not an inpainted clean plate. Composite
+ * something opaque (graphics, blur, scene) under it to fill the hole.
+ */
+ backgroundOutputPath?: string;
device?: Device;
model?: ModelId;
/** Encoder CRF preset for `.webm`. See `QUALITY_CRF`. Ignored for `.mov`/`.png`. */
@@ -52,6 +62,8 @@ export type ProgressEvent =
export interface RenderResult {
outputPath: string;
+ /** Present only when `backgroundOutputPath` was set. */
+ backgroundOutputPath?: string;
framesProcessed: number;
durationSeconds: number;
avgMsPerFrame: number;
@@ -203,17 +215,27 @@ async function* readFrames(
}
}
-export async function render(options: RenderOptions): Promise {
- if (!hasFFmpeg() || !hasFFprobe()) {
- throw new Error("ffmpeg and ffprobe are required. Install: brew install ffmpeg");
- }
+export interface RenderTargets {
+ format: OutputFormat;
+ inputKind: "video" | "image";
+ bgFormat: OutputFormat | undefined;
+}
- const format = inferOutputFormat(options.outputPath);
- const inputKind = inferInputKind(options.inputPath);
+/**
+ * Resolve and validate the input/output combination before any I/O. Pure;
+ * exported so unit tests can pin the error messages without spawning ffmpeg.
+ */
+export function resolveRenderTargets(
+ inputPath: string,
+ outputPath: string,
+ backgroundOutputPath?: string,
+): RenderTargets {
+ const format = inferOutputFormat(outputPath);
+ const inputKind = inferInputKind(inputPath);
if (inputKind === "image" && format !== "png") {
throw new Error(
- `Image input requires a .png output (got ${extname(options.outputPath)}). Use a video input for .webm/.mov.`,
+ `Image input requires a .png output (got ${extname(outputPath)}). Use a video input for .webm/.mov.`,
);
}
if (inputKind === "video" && format === "png") {
@@ -222,6 +244,35 @@ export async function render(options: RenderOptions): Promise {
);
}
+ let bgFormat: OutputFormat | undefined;
+ if (backgroundOutputPath) {
+ if (inputKind === "image") {
+ throw new Error(
+ "--background-output is not supported for image inputs. Use a video input (mp4/mov/webm) to produce both a cutout and a background plate.",
+ );
+ }
+ bgFormat = inferOutputFormat(backgroundOutputPath);
+ if (bgFormat === "png") {
+ throw new Error(
+ "--background-output must be .webm or .mov; .png is only valid for single-image inputs.",
+ );
+ }
+ }
+
+ return { format, inputKind, bgFormat };
+}
+
+export async function render(options: RenderOptions): Promise {
+ if (!hasFFmpeg() || !hasFFprobe()) {
+ throw new Error("ffmpeg and ffprobe are required. Install: brew install ffmpeg");
+ }
+
+ const { format, bgFormat } = resolveRenderTargets(
+ options.inputPath,
+ options.outputPath,
+ options.backgroundOutputPath,
+ );
+
const media = await probeMedia(options.inputPath);
options.onProgress?.({
@@ -240,12 +291,13 @@ export async function render(options: RenderOptions): Promise {
try {
const start = Date.now();
- const framesProcessed = await runPipeline(options, session, media, format);
+ const framesProcessed = await runPipeline(options, session, media, format, bgFormat);
const durationSeconds = (Date.now() - start) / 1000;
const avgMsPerFrame = framesProcessed ? (durationSeconds * 1000) / framesProcessed : 0;
return {
outputPath: options.outputPath,
+ backgroundOutputPath: options.backgroundOutputPath,
framesProcessed,
durationSeconds,
avgMsPerFrame,
@@ -259,61 +311,77 @@ export async function render(options: RenderOptions): Promise {
const RECENT_WINDOW = 30;
+interface FfmpegProc {
+ proc: ReturnType;
+ exit: Promise;
+ /** Tail of stderr, captured for inclusion in error messages. */
+ getStderr: () => string;
+}
+
+type StdioFd = "ignore" | "pipe";
+type StdioTuple = [StdioFd, StdioFd, StdioFd];
+
+function spawnFfmpeg(args: string[], label: string, stdio: StdioTuple): FfmpegProc {
+ const proc = spawn("ffmpeg", args, { stdio });
+ let stderrBuf = "";
+ proc.stderr?.on("data", (d: Buffer) => {
+ stderrBuf += d.toString();
+ });
+ // If the encoder dies mid-render, the next .write() to its stdin emits an
+ // 'error' event on the writable. Without a listener, Node treats it as
+ // unhandled and crashes the CLI before waitForExit's reject path can
+ // surface the real cause (encoder stderr tail). Swallowing here is safe —
+ // the process exit is the source of truth.
+ proc.stdin?.on("error", () => {});
+ const exit = waitForExit(proc, label, () => stderrBuf);
+ return { proc, exit, getStderr: () => stderrBuf };
+}
+
async function runPipeline(
options: RenderOptions,
session: Session,
media: MediaInfo,
format: OutputFormat,
+ bgFormat: OutputFormat | undefined,
): Promise {
- const { inputPath, outputPath } = options;
+ const { inputPath, outputPath, backgroundOutputPath } = options;
const { width, height, fps, frameCount } = media;
const frameBytes = width * height * 3;
+ const quality = options.quality ?? DEFAULT_QUALITY;
- const decoder = spawn(
- "ffmpeg",
+ const decoder = spawnFfmpeg(
["-loglevel", "error", "-i", inputPath, "-f", "rawvideo", "-pix_fmt", "rgb24", "-an", "-"],
- { stdio: ["ignore", "pipe", "pipe"] },
+ "ffmpeg decoder",
+ ["ignore", "pipe", "pipe"],
);
- let decoderStderr = "";
- decoder.stderr?.on("data", (d: Buffer) => {
- decoderStderr += d.toString();
- });
- const decoderExit = waitForExit(decoder, "ffmpeg decoder", () => decoderStderr);
-
- const encoder = spawn(
- "ffmpeg",
- buildEncoderArgs(
- format,
- width,
- height,
- fps || 30,
- outputPath,
- options.quality ?? DEFAULT_QUALITY,
- ),
- {
- stdio: ["pipe", "ignore", "pipe"],
- },
+ const fg = spawnFfmpeg(
+ buildEncoderArgs(format, width, height, fps || 30, outputPath, quality),
+ "ffmpeg encoder",
+ ["pipe", "ignore", "pipe"],
);
- let encoderStderr = "";
- encoder.stderr?.on("data", (d: Buffer) => {
- encoderStderr += d.toString();
- });
- const encoderExit = waitForExit(encoder, "ffmpeg encoder", () => encoderStderr);
+
+ const bg =
+ backgroundOutputPath && bgFormat
+ ? spawnFfmpeg(
+ buildEncoderArgs(bgFormat, width, height, fps || 30, backgroundOutputPath, quality),
+ "ffmpeg background encoder",
+ ["pipe", "ignore", "pipe"],
+ )
+ : null;
let processed = 0;
const total = frameCount;
- // Running average over the last RECENT_WINDOW frames.
const recentMs = new Array(RECENT_WINDOW).fill(0);
let recentSum = 0;
let recentSlot = 0;
let recentCount = 0;
try {
- for await (const rgb of readFrames(decoder.stdout!, frameBytes)) {
+ for await (const rgb of readFrames(decoder.proc.stdout!, frameBytes)) {
const t0 = Date.now();
- const rgba = await session.process(rgb, width, height);
+ const result = await session.process(rgb, width, height, bg !== null);
const elapsed = Date.now() - t0;
recentSum += elapsed - recentMs[recentSlot]!;
@@ -321,8 +389,31 @@ async function runPipeline(
recentSlot = (recentSlot + 1) % RECENT_WINDOW;
if (recentCount < RECENT_WINDOW) recentCount++;
- if (!encoder.stdin!.write(rgba)) {
- await new Promise((resolve) => encoder.stdin!.once("drain", () => resolve()));
+ // Issue both writes before any await so a slow encoder doesn't block
+ // the other. Drain anything that returned false before the next
+ // session.process() — its output buffers are reused per frame.
+ //
+ // Subtlety: write() returning true means "highWaterMark not exceeded,"
+ // NOT "libuv has flushed the chunk." The buffer reference is held by
+ // libuv until the underlying syscall completes. Reusing the session's
+ // output buffer is safe because the next session.process() call takes
+ // ~10–50ms (ORT inference) — plenty of event-loop turns for libuv to
+ // drain. If that ever stops being true, we'd need to copy here.
+ const fgWroteFully = fg.proc.stdin!.write(result.fg);
+ const bgWroteFully = bg && result.bg ? bg.proc.stdin!.write(result.bg) : true;
+ if (!fgWroteFully || !bgWroteFully) {
+ const drains: Promise[] = [];
+ if (!fgWroteFully) {
+ drains.push(
+ new Promise((resolve) => fg.proc.stdin!.once("drain", () => resolve())),
+ );
+ }
+ if (!bgWroteFully && bg) {
+ drains.push(
+ new Promise((resolve) => bg.proc.stdin!.once("drain", () => resolve())),
+ );
+ }
+ await Promise.all(drains);
}
processed++;
@@ -334,17 +425,21 @@ async function runPipeline(
});
}
} catch (err) {
- decoder.kill("SIGKILL");
- encoder.kill("SIGKILL");
+ decoder.proc.kill("SIGKILL");
+ fg.proc.kill("SIGKILL");
+ bg?.proc.kill("SIGKILL");
throw err;
}
- encoder.stdin!.end();
- await Promise.all([decoderExit, encoderExit]);
+ fg.proc.stdin!.end();
+ bg?.proc.stdin!.end();
+ const exits: Promise[] = [decoder.exit, fg.exit];
+ if (bg) exits.push(bg.exit);
+ await Promise.all(exits);
if (processed === 0) {
throw new Error(
- `No frames produced from ${inputPath}. Decoder stderr:\n${decoderStderr.slice(-400)}`,
+ `No frames produced from ${inputPath}. Decoder stderr:\n${decoder.getStderr().slice(-400)}`,
);
}
diff --git a/packages/cli/src/commands/layout.ts b/packages/cli/src/commands/layout.ts
index a8a713963..fa27dd70b 100644
--- a/packages/cli/src/commands/layout.ts
+++ b/packages/cli/src/commands/layout.ts
@@ -1,6 +1,6 @@
import { defineCommand } from "citty";
import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import type { Example } from "./_examples.js";
import { c } from "../ui/colors.js";
@@ -107,27 +107,10 @@ async function seekTo(page: import("puppeteer-core").Page, time: number): Promis
}
async function bundleProjectHtml(projectDir: string): Promise {
+ // `bundleToSingleHtml` now inlines the runtime IIFE by default, so the
+ // previous post-bundle runtime substitution is no longer needed.
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
- let html = await bundleToSingleHtml(projectDir);
-
- const runtimePath = resolve(
- __dirname,
- "..",
- "..",
- "..",
- "core",
- "dist",
- "hyperframe.runtime.iife.js",
- );
- if (existsSync(runtimePath)) {
- const runtimeSource = readFileSync(runtimePath, "utf-8");
- html = html.replace(
- /]*data-hyperframes-preview-runtime[^>]*src="[^"]*"[^>]*><\/script>/,
- () => ``,
- );
- }
-
- return html;
+ return bundleToSingleHtml(projectDir);
}
async function alignViewportToComposition(
diff --git a/packages/cli/src/commands/remove-background.ts b/packages/cli/src/commands/remove-background.ts
index cc942f67e..1116bef74 100644
--- a/packages/cli/src/commands/remove-background.ts
+++ b/packages/cli/src/commands/remove-background.ts
@@ -20,6 +20,10 @@ export const examples: Example[] = [
"Remove background from a single image, output transparent PNG",
"hyperframes remove-background portrait.jpg -o cutout.png",
],
+ [
+ "Separate the layers — emit both the cutout and an inverse-alpha background plate (subject region transparent)",
+ "hyperframes remove-background avatar.mp4 -o subject.webm --background-output plate.webm",
+ ],
[
"Force CPU (skip CoreML/CUDA)",
"hyperframes remove-background avatar.mp4 -o transparent.webm --device cpu",
@@ -52,6 +56,12 @@ export default defineCommand({
description: "Output path. Format inferred from extension: .webm (default), .mov, .png",
alias: "o",
},
+ "background-output": {
+ type: "string",
+ description:
+ "Optional second output path for the inverse-alpha background plate (subject region transparent, original surroundings opaque). Hole-cut, not inpainted — composite something underneath to fill the hole. Must be .webm or .mov; not allowed for image inputs.",
+ alias: "b",
+ },
device: {
type: "string",
description: `Execution provider: ${DEVICES.join(", ")}`,
@@ -104,6 +114,8 @@ export default defineCommand({
const inputPath = resolve(args.input);
const outputPath = resolve(args.output);
+ const backgroundOutputArg = args["background-output"];
+ const backgroundOutputPath = backgroundOutputArg ? resolve(backgroundOutputArg) : undefined;
const { render } = await import("../background-removal/pipeline.js");
@@ -114,6 +126,7 @@ export default defineCommand({
const result = await render({
inputPath,
outputPath,
+ backgroundOutputPath,
device: args.device,
quality: args.quality,
onProgress: (event) => {
@@ -137,6 +150,9 @@ export default defineCommand({
JSON.stringify({
ok: true,
outputPath: result.outputPath,
+ ...(result.backgroundOutputPath
+ ? { backgroundOutputPath: result.backgroundOutputPath }
+ : {}),
framesProcessed: result.framesProcessed,
durationSeconds: Number(result.durationSeconds.toFixed(2)),
avgMsPerFrame: Number(result.avgMsPerFrame.toFixed(1)),
@@ -148,9 +164,12 @@ export default defineCommand({
const fpsThroughput = result.durationSeconds
? (result.framesProcessed / result.durationSeconds).toFixed(1)
: "n/a";
+ const outputs = result.backgroundOutputPath
+ ? `${c.accent(result.outputPath)} + ${c.accent(result.backgroundOutputPath)}`
+ : c.accent(result.outputPath);
spin?.stop(
c.success(
- `Removed background from ${c.accent(String(result.framesProcessed))} frames in ${result.durationSeconds.toFixed(1)}s (${fpsThroughput} fps, ${c.accent(result.provider)}) → ${c.accent(result.outputPath)}`,
+ `Removed background from ${c.accent(String(result.framesProcessed))} frames in ${result.durationSeconds.toFixed(1)}s (${fpsThroughput} fps, ${c.accent(result.provider)}) → ${outputs}`,
),
);
}
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index 2c1d26cce..0fd2a81da 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -97,20 +97,9 @@ async function captureSnapshots(
const numFrames = opts.frames ?? 5;
- // 1. Bundle
- let html = await bundleToSingleHtml(projectDir);
-
- // Inject local runtime if available.
- // Uses the same multi-strategy resolver as the studio preview server
- // (runtimeSource.ts) so snapshot works in dev (tsx), built CLI, and npx.
- const { loadRuntimeSource } = await import("../server/runtimeSource.js");
- const runtimeSource = await loadRuntimeSource();
- if (runtimeSource) {
- html = html.replace(
- /]*data-hyperframes-preview-runtime[^>]*src="[^"]*"[^>]*><\/script>/,
- () => ``,
- );
- }
+ // 1. Bundle. `bundleToSingleHtml` now inlines the runtime IIFE by default,
+ // so the previous post-bundle runtime substitution is no longer needed.
+ const html = await bundleToSingleHtml(projectDir);
const server = await serveStaticProjectHtml(projectDir, html);
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
index 90eb99cdc..996d84465 100644
--- a/packages/cli/src/commands/validate.ts
+++ b/packages/cli/src/commands/validate.ts
@@ -1,6 +1,6 @@
import { defineCommand } from "citty";
import { existsSync, readFileSync } from "node:fs";
-import { resolve, join, dirname } from "node:path";
+import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { resolveProject } from "../utils/project.js";
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
@@ -113,24 +113,10 @@ async function validateInBrowser(
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
const { ensureBrowser } = await import("../browser/manager.js");
- let html = await bundleToSingleHtml(projectDir);
-
- const runtimePath = resolve(
- __dirname,
- "..",
- "..",
- "..",
- "core",
- "dist",
- "hyperframe.runtime.iife.js",
- );
- if (existsSync(runtimePath)) {
- const runtimeSource = readFileSync(runtimePath, "utf-8");
- html = html.replace(
- /]*data-hyperframes-preview-runtime[^>]*src="[^"]*"[^>]*><\/script>/,
- () => ``,
- );
- }
+ // `bundleToSingleHtml` now inlines the runtime IIFE by default, so the
+ // previous post-bundle regex substitution (which matched `src="..."` on the
+ // runtime tag) is no longer needed — there's no `src` attribute to match.
+ const html = await bundleToSingleHtml(projectDir);
const { createServer } = await import("node:http");
const { getMimeType } = await import("@hyperframes/core/studio-api");
diff --git a/packages/cli/src/server/fileWatcher.test.ts b/packages/cli/src/server/fileWatcher.test.ts
new file mode 100644
index 000000000..62412fcb9
--- /dev/null
+++ b/packages/cli/src/server/fileWatcher.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+
+import { shouldWatchProjectFile } from "./fileWatcher.js";
+
+describe("shouldWatchProjectFile", () => {
+ it("watches files that can affect the project signature", () => {
+ expect(shouldWatchProjectFile("index.html")).toBe(true);
+ expect(shouldWatchProjectFile("src/scene.tsx")).toBe(true);
+ expect(shouldWatchProjectFile("assets/hero.png")).toBe(true);
+ expect(shouldWatchProjectFile("Dockerfile")).toBe(true);
+ });
+
+ it("skips generated and dependency directories excluded from signatures", () => {
+ expect(shouldWatchProjectFile("node_modules/pkg/index.js")).toBe(false);
+ expect(shouldWatchProjectFile("renders/output.mp4")).toBe(false);
+ expect(shouldWatchProjectFile("dist/index.html")).toBe(false);
+ expect(shouldWatchProjectFile(".hyperframes/cache.json")).toBe(false);
+ });
+});
diff --git a/packages/cli/src/server/fileWatcher.ts b/packages/cli/src/server/fileWatcher.ts
index ffe0620a9..050f009ea 100644
--- a/packages/cli/src/server/fileWatcher.ts
+++ b/packages/cli/src/server/fileWatcher.ts
@@ -8,9 +8,27 @@ export interface ProjectWatcher {
close(): void;
}
-const WATCHED_EXTENSIONS = new Set([".html", ".css", ".js", ".json"]);
+const WATCHER_EXCLUDED_DIRS = new Set([
+ ".cache",
+ ".git",
+ ".hyperframes",
+ ".next",
+ ".vite",
+ "build",
+ "coverage",
+ "dist",
+ "node_modules",
+ "outputs",
+ "renders",
+]);
const DEBOUNCE_MS = 300;
+export function shouldWatchProjectFile(filename: string): boolean {
+ if (!filename) return false;
+ const parts = filename.split(/[\\/]+/);
+ return !parts.some((part) => WATCHER_EXCLUDED_DIRS.has(part));
+}
+
export function createProjectWatcher(projectDir: string): ProjectWatcher {
const listeners = new Set();
let debounceTimer: ReturnType | null = null;
@@ -19,13 +37,13 @@ export function createProjectWatcher(projectDir: string): ProjectWatcher {
try {
watcher = watch(projectDir, { recursive: true }, (_event, filename) => {
if (!filename) return;
- const ext = "." + filename.split(".").pop()?.toLowerCase();
- if (!WATCHED_EXTENSIONS.has(ext)) return;
+ const relativePath = filename.toString();
+ if (!shouldWatchProjectFile(relativePath)) return;
if (debounceTimer) clearTimeout(debounceTimer);
debounceTimer = setTimeout(() => {
for (const fn of listeners) {
- fn(filename);
+ fn(relativePath);
}
}, DEBOUNCE_MS);
});
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index ccceccffb..f61f6a62a 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -14,6 +14,7 @@ import { loadRuntimeSource } from "./runtimeSource.js";
import { VERSION as version } from "../version.js";
import {
createStudioApi,
+ createProjectSignature,
getMimeType,
type StudioApiAdapter,
type ResolvedProject,
@@ -144,6 +145,10 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
// ── CLI adapter for the shared studio API ──────────────────────────────
const project: ResolvedProject = { id: projectId, dir: projectDir, title: projectId };
+ let cachedProjectSignature: string | null = null;
+ watcher.addListener(() => {
+ cachedProjectSignature = null;
+ });
const adapter: StudioApiAdapter = {
listProjects: () => [project],
@@ -153,8 +158,11 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
async bundle(dir: string): Promise {
try {
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
- let html = await bundleToSingleHtml(dir);
- // Fix empty runtime src from bundler — point to the local runtime endpoint
+ // Studio dev server: ask the bundler for an empty `src=""` placeholder so
+ // we can point it at our hot-reloadable local runtime endpoint. Inlining
+ // ~150 KB of runtime body on every preview render would defeat browser
+ // caching across composition edits.
+ let html = await bundleToSingleHtml(dir, { runtime: "placeholder" });
html = html.replace(
'data-hyperframes-preview-runtime="1" src=""',
'data-hyperframes-preview-runtime="1" src="/api/runtime.js"',
@@ -166,6 +174,12 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
}
},
+ getProjectSignature(dir: string): string {
+ if (resolve(dir) !== resolve(projectDir)) return createProjectSignature(dir);
+ cachedProjectSignature ??= createProjectSignature(projectDir);
+ return cachedProjectSignature;
+ },
+
async lint(html: string, opts?: { filePath?: string }) {
const { lintHyperframeHtml } = await import("@hyperframes/core/lint");
return lintHyperframeHtml(html, opts);
diff --git a/packages/cli/src/utils/publishProject.test.ts b/packages/cli/src/utils/publishProject.test.ts
index b5a3b8117..4764e0409 100644
--- a/packages/cli/src/utils/publishProject.test.ts
+++ b/packages/cli/src/utils/publishProject.test.ts
@@ -7,6 +7,7 @@ import {
createPublishArchive,
getPublishApiBaseUrl,
publishProjectArchive,
+ uploadTimeoutMs,
} from "./publishProject.js";
function makeProjectDir(): string {
@@ -35,6 +36,22 @@ describe("createPublishArchive", () => {
});
});
+describe("uploadTimeoutMs", () => {
+ it("returns the minimum timeout for small files", () => {
+ expect(uploadTimeoutMs(0)).toBe(120_000);
+ expect(uploadTimeoutMs(50 * 1024 * 1024)).toBe(120_000);
+ });
+
+ it("scales above the floor for large files", () => {
+ expect(uploadTimeoutMs(64 * 1024 * 1024)).toBeGreaterThan(120_000);
+ expect(uploadTimeoutMs(500 * 1024 * 1024)).toBeGreaterThan(900_000);
+ });
+
+ it("returns an integer", () => {
+ expect(Number.isInteger(uploadTimeoutMs(123_456))).toBe(true);
+ });
+});
+
describe("publishProjectArchive", () => {
beforeEach(() => {
vi.stubEnv("HYPERFRAMES_PUBLISHED_PROJECTS_API_URL", "");
diff --git a/packages/cli/src/utils/publishProject.ts b/packages/cli/src/utils/publishProject.ts
index 3b4d62855..9a317b619 100644
--- a/packages/cli/src/utils/publishProject.ts
+++ b/packages/cli/src/utils/publishProject.ts
@@ -5,7 +5,11 @@ import AdmZip from "adm-zip";
const IGNORED_DIRS = new Set([".git", "node_modules", "dist", ".next", "coverage"]);
const IGNORED_FILES = new Set([".DS_Store", "Thumbs.db"]);
const PUBLISH_CONTENT_TYPE = "application/zip";
-const PUBLISH_REQUEST_TIMEOUT_MS = 30_000;
+const PUBLISH_METADATA_TIMEOUT_MS = 30_000;
+const PUBLISH_UPLOAD_MIN_TIMEOUT_MS = 120_000;
+// Conservative floor — most connections are faster, but this prevents
+// premature aborts on slow/unstable networks (hotel wifi, tethering).
+const PUBLISH_UPLOAD_BYTES_PER_SECOND = 500_000;
export interface PublishArchiveResult {
buffer: Buffer;
@@ -25,6 +29,7 @@ interface StagedUploadResponse {
uploadKey: string;
contentType: string;
uploadHeaders: Record;
+ expiresInSeconds: number;
}
type JsonRecord = Record;
@@ -73,11 +78,14 @@ function parseStagedUploadResponse(
const uploadKey = stringField(data, "upload_key");
const contentType = stringField(data, "content_type") || PUBLISH_CONTENT_TYPE;
if (!uploadUrl || !uploadKey) return null;
+ const rawExpires = data["expires_in_seconds"];
+ const expiresInSeconds = typeof rawExpires === "number" && rawExpires > 0 ? rawExpires : 1800;
return {
uploadUrl,
uploadKey,
contentType,
uploadHeaders: getUploadHeaders(data, uploadUrl, contentType, archiveByteLength),
+ expiresInSeconds,
};
}
@@ -142,6 +150,13 @@ async function readErrorMessage(response: Response, fallback: string): Promise {
)?.[0];
expect(runtimeBlock).toBeDefined();
- expect(runtimeBlock).not.toContain("getElementById");
+ // The runtime block must contain the inlined HF runtime IIFE — bundled
+ // output is self-contained, so the bundle's runtime body is loaded inline,
+ // not referenced via src.
+ expect(runtimeBlock).toMatch(/data-hyperframes-preview-runtime="1">/);
+ expect(runtimeBlock).not.toMatch(/src=""/);
+ // The author's specific composition script must NOT be merged INTO the
+ // runtime tag — it stays as its own when no runtime URL was configured. An
+ // empty src resolves to the page URL itself, which Chrome flags as an
+ // infinite-fetch hazard. Verify that bundleToSingleHtml inlines the
+ // runtime body so the bundle is genuinely self-contained.
+ const dir = makeTempProject({
+ "index.html": `
+
+
+`,
+ });
+
+ const previousUrl = process.env.HYPERFRAME_RUNTIME_URL;
+ delete process.env.HYPERFRAME_RUNTIME_URL;
+ let bundled: string;
+ try {
+ bundled = await bundleToSingleHtml(dir);
+ } finally {
+ if (previousUrl !== undefined) process.env.HYPERFRAME_RUNTIME_URL = previousUrl;
+ }
+
+ const runtimeBlock = bundled.match(
+ /]*data-hyperframes-preview-runtime[^>]*>[\s\S]*?<\/script>/i,
+ )?.[0];
+ expect(runtimeBlock).toBeDefined();
+ // Must NOT have an empty src attribute (would self-fetch).
+ expect(runtimeBlock).not.toMatch(/src=""/);
+ // Must have a non-trivial inlined body (the runtime IIFE is ~150KB).
+ const innerLength = (runtimeBlock!.match(/>([\s\S]*?)<\/script>/)?.[1] ?? "").length;
+ expect(innerLength).toBeGreaterThan(1000);
+ });
+
+ it("preserves chunk integrity when a chunk ends with a line comment (ASI hazard guard)", async () => {
+ // Regression guard for the joinJsChunks helper. If a chunk ends with `// ...`
+ // and we naively appended `;` on the same line, the appended semicolon would
+ // be eaten by the comment, leaving the next chunk's first statement attached
+ // to the previous chunk's last expression. Verify the helper appends `\n;`
+ // instead so the comment terminates and the semicolon stands alone.
+ const dir = makeTempProject({
+ "index.html": `
+
+
+
+
+
+`,
+ // Chunk A ends with a // line comment — without the \n separator before
+ // the appended ;, that ; would be eaten by the comment.
+ "local-a.js": "window.__a = 1 // trailing line comment",
+ "local-b.js": "window.__b = 2",
+ });
+
+ const bundled = await bundleToSingleHtml(dir);
+ // Run every inline script body through esbuild; if the line comment ate
+ // the separator, parse would fail with an unexpected-token error somewhere
+ // around the chunk boundary. Use a real HTML parser (CodeQL flags regex-
+ // based script extraction as bad-tag-filter).
+ const { transformSync } = await import("esbuild");
+ const { document } = parseHTML(bundled);
+ for (const script of document.querySelectorAll("script")) {
+ const body = script.textContent;
+ if (!body || !body.trim()) continue;
+ expect(() => transformSync(body, { loader: "js", minify: false })).not.toThrow();
+ }
+ });
+
+ it("does not produce stray bare-semicolon lines between concatenated JS chunks", async () => {
+ // Regression guard: hf#XXX. Earlier the bundler joined script chunks with
+ // `\n;\n`, which produces a lone `;` on its own line between chunks. Valid
+ // JS but reads as a code smell. Each chunk should end in `;` and chunks
+ // should join with `\n`.
+ const dir = makeTempProject({
+ "index.html": `
+
+
+
+
+
+`,
+ "local-a.js": "window.__a = 1",
+ "local-b.js": "window.__b = 2",
+ "compositions/child.html": `
+
+
+
+`,
+ });
+
+ const bundled = await bundleToSingleHtml(dir);
+ // No line is JUST a bare semicolon (with optional surrounding whitespace).
+ expect(bundled).not.toMatch(/\n\s*;\s*\n/);
+ });
+
it("hoists external CDN scripts from sub-compositions into the bundle", async () => {
const dir = makeTempProject({
"index.html": `
@@ -84,8 +190,14 @@ describe("bundleToSingleHtml", () => {
// GSAP CDN from main doc should still be present
expect(bundled).toContain("cdn.jsdelivr.net/npm/gsap");
- // data-composition-src should be stripped (composition was inlined)
- expect(bundled).not.toContain("data-composition-src");
+ // data-composition-src should be stripped from the host element (composition
+ // was inlined). The literal string may still appear inside the inlined
+ // runtime IIFE that knows how to look up that attribute — so check the DOM,
+ // not the raw text.
+ const { document: doc } = parseHTML(bundled);
+ const hostEl = doc.getElementById("rockets-host");
+ expect(hostEl).toBeTruthy();
+ expect(hostEl?.hasAttribute("data-composition-src")).toBe(false);
});
it("does not duplicate CDN scripts already present in the main document", async () => {
diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.ts
index 3a80d58c9..def7c8463 100644
--- a/packages/core/src/compiler/htmlBundler.ts
+++ b/packages/core/src/compiler/htmlBundler.ts
@@ -10,6 +10,7 @@ import {
import { rewriteAssetPaths, rewriteCssAssetUrls } from "./rewriteSubCompPaths";
import { scopeCssToComposition, wrapScopedCompositionScript } from "./compositionScoping";
import { validateHyperframeHtmlContract } from "./staticGuard";
+import { getHyperframeRuntimeScript } from "../generated/runtime-inline";
/** Resolve a relative path within projectDir, rejecting traversal outside it. */
function safePath(projectDir: string, relativePath: string): string | null {
@@ -26,12 +27,28 @@ function getRuntimeScriptUrl(): string {
return configured || DEFAULT_RUNTIME_SCRIPT_URL;
}
-function injectInterceptor(html: string): string {
+function injectInterceptor(html: string, runtimeMode: "inline" | "placeholder" = "inline"): string {
const sanitized = stripEmbeddedRuntimeScripts(html);
if (sanitized.includes(RUNTIME_BOOTSTRAP_ATTR)) return sanitized;
- const runtimeScriptUrl = getRuntimeScriptUrl().replace(/"/g, """);
- const tag = ``;
+ // Three modes for the runtime `;
+ } else if (runtimeMode === "placeholder") {
+ tag = ``;
+ } else {
+ const inlinedRuntime = getHyperframeRuntimeScript();
+ tag = ``;
+ }
if (sanitized.includes("")) {
return sanitized.replace("", `${tag}\n`);
}
@@ -268,11 +285,7 @@ function coalesceHeadStylesAndBodyScripts(document: Document): void {
return !type || type === "text/javascript" || type === "application/javascript";
});
if (bodyInlineScripts.length > 0) {
- const mergedJs = bodyInlineScripts
- .map((el) => (el.textContent || "").trim())
- .filter(Boolean)
- .join("\n;\n")
- .trim();
+ const mergedJs = joinJsChunks(bodyInlineScripts.map((el) => el.textContent || ""));
for (const el of bodyInlineScripts) el.remove();
if (mergedJs) {
const stripped = stripJsCommentsParserSafe(mergedJs);
@@ -283,6 +296,31 @@ function coalesceHeadStylesAndBodyScripts(document: Document): void {
}
}
+/**
+ * Concatenate JS chunks safely. Goals:
+ * - Each chunk's last statement is terminated, so joining can't introduce ASI
+ * surprises (e.g. `a()` followed by `(b)()` — the second chunk would parse
+ * as a call on the first's return value).
+ * - In the common case (chunk already ends with `;` — typical of esbuild
+ * output and IIFE-wrapped composition scripts ending in `})();`), the join
+ * produces clean output: chunks separated by `\n` with no stray bare
+ * semicolon lines.
+ * - Defensive against trailing line comments. If a chunk ends with `// ...`
+ * and we appended `;` on the same line, the appended semicolon would be
+ * swallowed by the comment, leaving the next chunk's first statement
+ * attached to the previous chunk's last expression — exactly the ASI
+ * hazard this helper exists to prevent. So when a chunk doesn't already
+ * end in `;`, we append `\n;` instead — the newline closes any line
+ * comment, and the standalone `;` becomes the statement separator.
+ */
+function joinJsChunks(chunks: string[]): string {
+ return chunks
+ .map((chunk) => chunk.trim())
+ .filter((chunk) => chunk.length > 0)
+ .map((chunk) => (chunk.endsWith(";") ? chunk : chunk + "\n;"))
+ .join("\n");
+}
+
function stripJsCommentsParserSafe(source: string): string {
if (!source) return source;
try {
@@ -296,6 +334,22 @@ function stripJsCommentsParserSafe(source: string): string {
export interface BundleOptions {
/** Optional media duration prober (e.g., ffprobe). If omitted, media durations are not resolved. */
probeMediaDuration?: MediaDurationProber;
+ /**
+ * How to handle the HyperFrames runtime ` so the caller can
+ * substitute it with a real URL via string replace. Used by the dev studio
+ * server and vite preview to point at a local runtime endpoint, which keeps
+ * the runtime cacheable across hot-reloads instead of re-inlining ~150 KB
+ * on every change.
+ *
+ * The `HYPERFRAME_RUNTIME_URL` env var, when set, takes precedence over both
+ * modes and emits `