@hyperframes/engine 0.4.6 → 0.4.8

package/dist/services/hdrCapture.js

@@ -0,0 +1,259 @@
+/// <reference types="@webgpu/types" />
+/**
+ * HDR Capture Service
+ *
+ * Captures HDR video frames via WebGPU float16 readback.
+ *
+ * The pipeline:
+ * 1. FFmpeg extracts raw HDR pixels (rgba64le) from video sources
+ * 2. Node converts HLG/PQ signal → linear light → float16
+ * 3. writeTexture uploads float16 data to WebGPU rgba16float texture
+ * 4. (Optional) WebGPU shader applies GSAP CSS transform
+ * 5. readback extracts float16 RGBA via base64 transfer
+ * 6. Node converts linear float16 → PQ signal → pipe to FFmpeg H.265
+ *
+ * Requirements:
+ * - Headed Chrome (not headless) — WebGPU unavailable in headless mode
+ * - GPU access (Metal on macOS, Vulkan+NVIDIA on Linux)
+ *
+ * Performance: ~6 fps at 1080x1920 via base64 transfer.
+ */
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+// ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
+const PQ_M1 = 0.1593017578125;
+const PQ_M2 = 78.84375;
+const PQ_C1 = 0.8359375;
+const PQ_C2 = 18.8515625;
+const PQ_C3 = 18.6875;
+const PQ_MAX_NITS = 10000.0;
+const SDR_NITS = 203.0;
+function linearToPQ(L) {
+    const Lp = Math.max(0, (L * SDR_NITS) / PQ_MAX_NITS);
+    const Lm1 = Math.pow(Lp, PQ_M1);
+    return Math.pow((PQ_C1 + PQ_C2 * Lm1) / (1.0 + PQ_C3 * Lm1), PQ_M2);
+}
+function float16Decode(h) {
+    const sign = (h >> 15) & 1;
+    const exp = (h >> 10) & 0x1f;
+    const frac = h & 0x3ff;
+    if (exp === 0)
+        return (sign ? -1 : 1) * Math.pow(2, -14) * (frac / 1024);
+    if (exp === 31)
+        return frac ? NaN : sign ? -Infinity : Infinity;
+    return (sign ? -1 : 1) * Math.pow(2, exp - 15) * (1 + frac / 1024);
+}
+// ── Initialization ────────────────────────────────────────────────────────────
+/**
+ * Inject the WebGPU HDR readback runtime into the page.
+ *
+ * Creates an rgba16float render texture that accepts writeTexture uploads
+ * and provides readback via base64 transfer.
+ */
+export async function initHdrReadback(page, width, height) {
+    return page.evaluate(async (w, h) => {
+        if (!navigator.gpu)
+            return false;
+        const adapter = await navigator.gpu.requestAdapter();
+        if (!adapter)
+            return false;
+        const device = await adapter.requestDevice();
+        const bytesPerPixel = 8; // rgba16float = 4 channels × 2 bytes
+        const bytesPerRow = Math.ceil((w * bytesPerPixel) / 256) * 256;
+        // Render texture — includes COPY_DST for writeTexture uploads
+        const renderTexture = device.createTexture({
+            size: [w, h],
+            format: "rgba16float",
+            usage: GPUTextureUsage.RENDER_ATTACHMENT |
+                GPUTextureUsage.COPY_SRC |
+                GPUTextureUsage.COPY_DST |
+                GPUTextureUsage.TEXTURE_BINDING,
+        });
+        const readBuffer = device.createBuffer({
+            size: bytesPerRow * h,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        });
+        const captureRuntime = {
+            device,
+            renderTexture,
+            readBuffer,
+            bytesPerRow,
+            width: w,
+            height: h,
+            /**
+             * Upload pre-converted float16 RGBA data and read it back.
+             * The float16 data must be row-aligned to bytesPerRow.
+             *
+             * Input: base64-encoded Uint16Array (float16 RGBA, row-padded)
+             * Output: base64-encoded readback of the same texture
+             */
+            async uploadAndReadback(float16Base64) {
+                // Decode base64 → Uint8Array
+                const binary = atob(float16Base64);
+                const bytes = new Uint8Array(binary.length);
+                for (let i = 0; i < binary.length; i++)
+                    bytes[i] = binary.charCodeAt(i);
+                // Upload to texture
+                device.queue.writeTexture({ texture: renderTexture }, bytes.buffer, { bytesPerRow, rowsPerImage: h }, [w, h]);
+                // Readback
+                const encoder = device.createCommandEncoder();
+                encoder.copyTextureToBuffer({ texture: renderTexture }, { buffer: readBuffer, bytesPerRow }, [w, h]);
+                device.queue.submit([encoder.finish()]);
+                await readBuffer.mapAsync(GPUMapMode.READ);
+                const readBytes = new Uint8Array(readBuffer.getMappedRange().slice(0));
+                readBuffer.unmap();
+                // Base64 encode in chunks
+                let b64 = "";
+                const chunkSize = 32768;
+                for (let i = 0; i < readBytes.length; i += chunkSize) {
+                    const slice = readBytes.subarray(i, Math.min(i + chunkSize, readBytes.length));
+                    b64 += String.fromCharCode(...slice);
+                }
+                return { base64: btoa(b64), bytesPerRow };
+            },
+        };
+        window.__hfHdrCapture = captureRuntime;
+        return true;
+    }, width, height);
+}
+// ── HDR frame conversion ──────────────────────────────────────────────────────
+/**
+ * Convert raw rgba64le pixels (from FFmpeg) to a base64 string for FFmpeg encoding.
+ *
+ * For HLG sources: the pixel values are already HLG-encoded. We pass them through
+ * as-is (normalized to 16-bit) and tag the output as HLG. No OETF conversion needed —
+ * the HLG signal values ARE the correct encoding. Converting to linear and back to
+ * PQ produces worse results because every viewer's PQ→display tone-mapping differs
+ * from its HLG→display tone-mapping.
+ *
+ * The WebGPU round-trip is skipped for pass-through — the pixels go directly from
+ * FFmpeg extraction to FFmpeg encoding. WebGPU is only needed when transforms
+ * (scale, rotate, opacity from GSAP) must be applied to the HDR pixels.
+ */
+export function convertHdrFrameToRgb48le(rawRgba64le, width, height) {
+    const input = new Uint16Array(rawRgba64le.buffer, rawRgba64le.byteOffset, rawRgba64le.byteLength / 2);
+    // Convert RGBA → RGB (drop alpha) for rgb48le output
+    const output = Buffer.alloc(width * height * 6);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const srcIdx = (y * width + x) * 4;
+            const dstIdx = (y * width + x) * 6;
+            output.writeUInt16LE(input[srcIdx] ?? 0, dstIdx);
+            output.writeUInt16LE(input[srcIdx + 1] ?? 0, dstIdx + 2);
+            output.writeUInt16LE(input[srcIdx + 2] ?? 0, dstIdx + 4);
+        }
+    }
+    return output;
+}
+// ── Frame upload + readback ───────────────────────────────────────────────────
+/**
+ * Upload a float16 frame to WebGPU and read it back.
+ * Call after converting with convertHdrFrameToFloat16Base64.
+ */
+export async function uploadAndReadbackHdrFrame(page, float16Base64) {
+    const result = await page.evaluate(async (b64) => {
+        const hdr = window.__hfHdrCapture;
+        if (!hdr)
+            throw new Error("HDR capture not initialized");
+        return hdr.uploadAndReadback(b64);
+    }, float16Base64);
+    return {
+        rawBuffer: Buffer.from(result.base64, "base64"),
+        bytesPerRow: result.bytesPerRow,
+    };
+}
+// ── PQ conversion ─────────────────────────────────────────────────────────────
+/**
+ * Convert float16 RGBA readback to PQ-encoded rgb48le for FFmpeg.
+ */
+export function float16ToPqRgb(rawBuffer, bytesPerRow, width, height) {
+    const data = new Uint16Array(rawBuffer.buffer, rawBuffer.byteOffset, rawBuffer.byteLength / 2);
+    const channelsPerRow = bytesPerRow / 2;
+    const output = Buffer.alloc(width * height * 6);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const srcIdx = y * channelsPerRow + x * 4;
+            const r = float16Decode(data[srcIdx] ?? 0);
+            const g = float16Decode(data[srcIdx + 1] ?? 0);
+            const b = float16Decode(data[srcIdx + 2] ?? 0);
+            const dstIdx = (y * width + x) * 6;
+            output.writeUInt16LE(Math.round(Math.min(1.0, linearToPQ(r)) * 65535), dstIdx);
+            output.writeUInt16LE(Math.round(Math.min(1.0, linearToPQ(g)) * 65535), dstIdx + 2);
+            output.writeUInt16LE(Math.round(Math.min(1.0, linearToPQ(b)) * 65535), dstIdx + 4);
+        }
+    }
+    return output;
+}
+// ── Chrome launch ─────────────────────────────────────────────────────────────
+function resolveHeadedChromePath() {
+    const baseDir = join(homedir(), ".cache", "puppeteer", "chrome");
+    if (!existsSync(baseDir))
+        return undefined;
+    const versions = readdirSync(baseDir).sort().reverse();
+    for (const version of versions) {
+        const candidates = [
+            join(baseDir, version, "chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+            join(baseDir, version, "chrome-mac-x64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+            join(baseDir, version, "chrome-linux64", "chrome"),
+            join(baseDir, version, "chrome-win64", "chrome.exe"),
+        ];
+        for (const binary of candidates) {
+            if (existsSync(binary))
+                return binary;
+        }
+    }
+    return undefined;
+}
+/**
+ * Launch a headed Chrome browser with WebGPU enabled.
+ */
+export async function launchHdrBrowser(width, height) {
+    let ppt;
+    try {
+        const mod = await import("puppeteer");
+        ppt = mod.default;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+            throw err;
+        }
+        const mod = await import("puppeteer-core");
+        ppt = mod.default;
+    }
+    if (!ppt)
+        throw new Error("Neither puppeteer nor puppeteer-core found");
+    const chromePath = resolveHeadedChromePath();
+    if (!chromePath) {
+        throw new Error("[HDR] No Chrome binary found. Install: npx @puppeteer/browsers install chrome@stable");
+    }
+    const browser = await ppt.launch({
+        headless: false,
+        executablePath: chromePath,
+        args: buildHdrChromeArgs(width, height),
+    });
+    const page = await browser.newPage();
+    await page.setViewport({ width, height });
+    return { browser, page };
+}
+export function buildHdrChromeArgs(width, height) {
+    return [
+        "--enable-unsafe-webgpu",
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--window-position=-10000,-10000",
+        `--window-size=${width},${height}`,
+        "--disable-background-timer-throttling",
+        "--disable-backgrounding-occluded-windows",
+        "--disable-renderer-backgrounding",
+        "--disable-background-media-suspend",
+        "--disable-extensions",
+        "--disable-component-update",
+        "--disable-default-apps",
+        "--disable-sync",
+        "--no-zygote",
+        "--force-gpu-mem-available-mb=4096",
+    ];
+}
+//# sourceMappingURL=hdrCapture.js.map

package/dist/services/hdrCapture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hdrCapture.js","sourceRoot":"","sources":["../../src/services/hdrCapture.ts"],"names":[],"mappings":"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"}

package/dist/services/screenshotService.d.ts

@@ -20,6 +20,121 @@ export declare function beginFrameCapture(page: Page, options: CaptureOptions, f
  * Fallback for environments where BeginFrame is unavailable (macOS, Windows).
  */
 export declare function pageScreenshotCapture(page: Page, options: CaptureOptions): Promise<Buffer>;
+/**
+ * Capture a screenshot with transparent background (PNG + alpha channel).
+ *
+ * Used in the two-pass HDR compositing pipeline — captures DOM content
+ * (text, graphics, SDR overlays) with transparency where the background shows,
+ * so it can be overlaid on top of native HDR video frames in FFmpeg.
+ *
+ * Sets and restores the background color override on every call. For sessions
+ * that capture many frames, prefer calling initTransparentBackground() once
+ * at session init, then captureAlphaPng() per frame to avoid the 2× CDP
+ * round-trip overhead.
+ */
+export declare function captureScreenshotWithAlpha(page: Page, width: number, height: number): Promise<Buffer>;
+/**
+ * Set the page background to transparent once for a dedicated HDR DOM session.
+ *
+ * Call this once after session initialization. Then use captureAlphaPng() per
+ * frame instead of captureScreenshotWithAlpha() to skip the per-frame CDP
+ * background override round-trips.
+ *
+ * Only use on sessions that are exclusively dedicated to transparent capture
+ * (e.g., the HDR two-pass DOM layer session) — the background will stay
+ * transparent for the lifetime of the session.
+ *
+ * NOTE on the injected stylesheet: `Emulation.setDefaultBackgroundColorOverride`
+ * only replaces the *default* page background. Compositions almost always set
+ * `body { background: ... }` and `#root { background: ... }`, which paint over
+ * the override and ruin alpha capture for layered HDR compositing — the
+ * composition root's full-frame background paints across the entire viewport
+ * and wipes out HDR content captured beneath it.
+ *
+ * We force `html`, `body`, and any element marked as a composition root
+ * (`[data-composition-id]`) to transparent. In HDR layered compositing the HDR
+ * video itself is the backdrop, so DOM layers must only contribute their
+ * foreground UI pixels — never a page-spanning solid backdrop.
+ */
+export declare const TRANSPARENT_BG_STYLE_ID = "__hf_transparent_bg__";
+export declare function initTransparentBackground(page: Page): Promise<void>;
+/**
+ * Capture a transparent-background PNG screenshot without setting the
+ * background color override. Requires initTransparentBackground() to have
+ * been called once on this session.
+ *
+ * Faster than captureScreenshotWithAlpha() for per-frame use in the HDR
+ * two-pass compositing loop.
+ */
+export declare function captureAlphaPng(page: Page, width: number, height: number): Promise<Buffer>;
+/**
+ * Stylesheet ID used by applyDomLayerMask / removeDomLayerMask. Exposed so
+ * tests can assert presence/absence of the mask between captures.
+ */
+export declare const DOM_LAYER_MASK_STYLE_ID = "__hf_dom_layer_mask__";
+/**
+ * Mask the DOM so a single layer screenshot captures ONLY the layer's pixels.
+ *
+ * The HDR layered compositor walks z-ordered layers and blits each one over a
+ * shared canvas. DOM layers are full-page screenshots — a naive screenshot
+ * captures every painted pixel on the page, which means root background +
+ * static overlays + sibling-scene content all overwrite previously composited
+ * HDR content beneath. The mask narrows each screenshot to the elements that
+ * actually belong to this layer.
+ *
+ * Strategy:
+ *
+ * 1. Inject a stylesheet that hides every body descendant
+ *    (`body * { visibility: hidden !important }`) and re-shows the layer's
+ *    elements (and their descendants and their injected `__render_frame_*`
+ *    siblings) via `visibility: visible !important`. CSS `visibility: visible`
+ *    on a descendant overrides an ancestor's `visibility: hidden`, so deep
+ *    layer elements remain visible even though intermediate parents are
+ *    hidden by the mass-hide rule.
+ * 2. Inline-hide each `extraHideId` (and its `__render_frame_*` sibling) with
+ *    `visibility: hidden !important`. Inline `!important` beats stylesheet
+ *    `!important`, so this overrides the show rule for elements that fall
+ *    under a show selector but should NOT paint — typically other-layer
+ *    elements that are descendants of a container layer (for example HDR
+ *    videos and other-layer SDR videos are descendants of `#root` when we
+ *    capture the root DOM layer).
+ *
+ * Only `visibility` is set on extraHideIds — never `opacity`. CSS opacity is
+ * multiplicative through the descendant chain and a descendant cannot escape
+ * an ancestor's `opacity: 0`. If `#root` is in `extraHideIds` and we set
+ * `opacity: 0` on it, every descendant — including `#vid-5-b` and its
+ * `__render_frame_vid-5-b__` IMG — becomes invisible even with
+ * `visibility: visible !important`. `visibility` does NOT have this problem:
+ * a descendant with `visibility: visible` overrides an ancestor's
+ * `visibility: hidden`.
+ *
+ * Layout is preserved (visibility doesn't trigger reflow), so border-radius
+ * clipping, overflow:hidden, and absolute positioning continue to apply to
+ * the visible layer elements. Opacity is also preserved — an ancestor at
+ * `opacity: 0` (e.g. an inactive scene during a transition) still
+ * propagates to its descendants, which is the desired behavior during
+ * cross-scene blends.
+ *
+ * Idempotent across calls: an existing mask stylesheet is removed before a
+ * new one is installed, so consecutive `applyDomLayerMask` invocations leave
+ * exactly one stylesheet attached.
+ */
+export declare function applyDomLayerMask(page: Page, showIds: string[], extraHideIds: string[]): Promise<void>;
+/**
+ * Tear down the mask installed by applyDomLayerMask.
+ *
+ * Removes the mask stylesheet and clears the inline `visibility` properties
+ * set on `extraHideIds` (and their `__render_frame_*` siblings).
+ *
+ * IMPORTANT: We do NOT strip inline `opacity` here. applyDomLayerMask only
+ * ever sets `visibility` (never `opacity`), so any inline opacity present on
+ * a wrapper was put there by user animation code (typically GSAP) and must
+ * survive across per-layer captures. GSAP's seek with suppress-events does
+ * not re-apply tweens when the timeline is already at the target time, so if
+ * we strip opacity here and then seek to the same time for the next layer,
+ * GSAP won't put it back and the wrapper will render fully opaque.
+ */
+export declare function removeDomLayerMask(page: Page, extraHideIds: string[]): Promise<void>;
 export declare function injectVideoFramesBatch(page: Page, updates: Array<{
     videoId: string;
     dataUri: string;

package/dist/services/screenshotService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshotService.d.ts","sourceRoot":"","sources":["../../src/services/screenshotService.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,eAAO,MAAM,eAAe,oDAA2D,CAAC;AAExF,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,gBAAgB,EAAE,UAAU,CAAC,CAO5F;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AA6CD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CAuC3B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAWhG;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CAyFf;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CAgBf"}
+{"version":3,"file":"screenshotService.d.ts","sourceRoot":"","sources":["../../src/services/screenshotService.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,eAAO,MAAM,eAAe,oDAA2D,CAAC;AAExF,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,gBAAgB,EAAE,UAAU,CAAC,CAO5F;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AA6CD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CAuC3B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAWhG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAoBjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAazE;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUhG;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EAAE,EACjB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,IAAI,CAAC,CAsCf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB1F;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CAsGf;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CA8Bf"}