@hyperframes/engine 0.6.118 → 0.6.120

package/src/utils/hdrCompositing.test.ts

@@ -1,130 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { groupIntoLayers } from "./layerCompositor.js";
-import type { ElementStackingInfo } from "../services/videoFrameInjector.js";
-
-function makeEl(
-  id: string,
-  zIndex: number,
-  isHdr: boolean,
-  overrides?: Partial<ElementStackingInfo>,
-): ElementStackingInfo {
-  return {
-    id,
-    zIndex,
-    x: 0,
-    y: 0,
-    width: 1920,
-    height: 1080,
-    layoutWidth: 1920,
-    layoutHeight: 1080,
-    opacity: 1,
-    visible: true,
-    isHdr,
-    transform: "none",
-    borderRadius: [0, 0, 0, 0],
-    objectFit: "cover",
-    objectPosition: "50% 50%",
-    clipRect: null,
-    ...overrides,
-  };
-}
-
-describe("HDR compositing — opacity filtering", () => {
-  it("zero-opacity elements remain in groupIntoLayers for hide-list correctness", () => {
-    const elements = [
-      makeEl("bg", 0, false),
-      makeEl("v-hdr", 1, true),
-      makeEl("overlay", 2, false, { opacity: 0 }),
-    ];
-    // Elements stay in layers for correct DOM screenshot hide-lists.
-    // The compositor skips zero-opacity HDR layers during blit.
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(3);
-    expect(layers[0]!.type).toBe("dom");
-    expect(layers[1]!.type).toBe("hdr");
-    expect(layers[2]!.type).toBe("dom");
-  });
-
-  it("zero-opacity HDR element should be skipped during blit", () => {
-    const el = makeEl("v-hdr", 1, true, { opacity: 0 });
-    // The compositor checks: if (layer.element.opacity <= 0) continue;
-    expect(el.opacity).toBe(0);
-    expect(el.opacity <= 0).toBe(true);
-  });
-
-  it("low but non-zero opacity HDR elements are NOT skipped", () => {
-    const el = makeEl("v-hdr", 1, true, { opacity: 0.1 });
-    expect(el.opacity > 0).toBe(true);
-  });
-
-  it("child data-start element with parent opacity 0 has effective opacity 0", () => {
-    const childOverlay = makeEl("s6-text-wrap", 10, false, { opacity: 0 });
-    expect(childOverlay.opacity).toBe(0);
-  });
-
-  it("DOM overlay above HDR video is in a separate layer when both visible", () => {
-    const elements = [makeEl("bg", 0, false), makeEl("v-hdr", 1, true), makeEl("badge", 10, false)];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(3);
-    expect(layers[0]!.type).toBe("dom");
-    expect(layers[1]!.type).toBe("hdr");
-    expect(layers[2]!.type).toBe("dom");
-    if (layers[2]!.type === "dom") {
-      expect(layers[2]!.elementIds).toEqual(["badge"]);
-    }
-  });
-});
-
-describe("HDR compositing — clip rect", () => {
-  it("clipRect is null when no overflow:hidden ancestor", () => {
-    const el = makeEl("video", 0, true);
-    expect(el.clipRect).toBeNull();
-  });
-
-  it("clipRect constrains element bounds for split-screen", () => {
-    const el = makeEl("video-left", 0, true, {
-      x: 0,
-      y: 0,
-      width: 1920,
-      height: 1080,
-      clipRect: { x: 0, y: 0, width: 960, height: 1080 },
-    });
-    const cr = el.clipRect!;
-    const cx1 = Math.max(el.x, cr.x);
-    const cy1 = Math.max(el.y, cr.y);
-    const cx2 = Math.min(el.x + el.width, cr.x + cr.width);
-    const cy2 = Math.min(el.y + el.height, cr.y + cr.height);
-    expect(cx2 - cx1).toBe(960);
-    expect(cy2 - cy1).toBe(1080);
-  });
-
-  it("fully clipped element produces zero-size intersection", () => {
-    const el = makeEl("offscreen", 0, true, {
-      x: 1000,
-      y: 0,
-      width: 920,
-      height: 1080,
-      clipRect: { x: 0, y: 0, width: 960, height: 1080 },
-    });
-    const cr = el.clipRect!;
-    const cx2 = Math.min(el.x + el.width, cr.x + cr.width);
-    const cx1 = Math.max(el.x, cr.x);
-    expect(Math.max(0, cx2 - cx1)).toBe(0);
-  });
-
-  it("right-half clip produces correct source crop offset", () => {
-    const el = makeEl("video-right", 0, true, {
-      x: 960,
-      y: 0,
-      width: 1920,
-      height: 1080,
-      clipRect: { x: 960, y: 0, width: 960, height: 1080 },
-    });
-    const cr = el.clipRect!;
-    const cx1 = Math.max(el.x, cr.x);
-    const blitSrcX = cx1 - el.x;
-    expect(blitSrcX).toBe(0);
-    const blitW = Math.min(el.x + el.width, cr.x + cr.width) - cx1;
-    expect(blitW).toBe(960);
-  });
-});

package/src/utils/htmlTemplate.test.ts

@@ -1,42 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { unwrapTemplate } from "./htmlTemplate.js";
-
-describe("unwrapTemplate", () => {
-  it("returns the input unchanged when there is no template wrapper", () => {
-    const html = `<div>hello</div>`;
-    expect(unwrapTemplate(html)).toBe(html);
-  });
-
-  it("unwraps a bare top-level template fragment", () => {
-    const inner = `<span>hi</span>`;
-    const html = `<template id="t" data-x="1">${inner}</template>`;
-    expect(unwrapTemplate(html)).toBe(inner);
-  });
-
-  it("unwraps a full document whose body only contains a template", () => {
-    const inner = `<div id="root"><audio id="a" src="a.mp3"></audio></div>`;
-    const html = `<!doctype html><html><body><template>${inner}</template></body></html>`;
-    expect(unwrapTemplate(html)).toBe(inner);
-  });
-
-  it("returns the input unchanged when the closing template tag is missing", () => {
-    const html = `<template><div>broken`;
-    expect(unwrapTemplate(html)).toBe(html);
-  });
-
-  it("returns an empty string for an empty template", () => {
-    const html = `<body><template></template></body>`;
-    expect(unwrapTemplate(html)).toBe("");
-  });
-
-  it("preserves nested templates inside the outer wrapper", () => {
-    const inner = `outer-before<template>inner-content</template>outer-after`;
-    const html = `<template>${inner}</template>`;
-    expect(unwrapTemplate(html)).toBe(inner);
-  });
-
-  it("leaves multiple sibling templates unchanged", () => {
-    const html = `<template>a</template>middle<template>b</template>`;
-    expect(unwrapTemplate(html)).toBe(html);
-  });
-});

package/src/utils/htmlTemplate.ts

@@ -1,42 +0,0 @@
-import { parseHTMLContent } from "@hyperframes/core/compiler";
-
-function getSingleMeaningfulChild(container: Element): Element | null {
-  let child: Element | null = null;
-  for (const node of Array.from(container.childNodes)) {
-    if (node.nodeType === 3 && !(node.textContent || "").trim()) continue;
-    if (node.nodeType === 8) continue;
-    if (node.nodeType !== 1) return null;
-    if (child) return null;
-    child = node as Element;
-  }
-  return child;
-}
-
-/**
- * Sub-compositions commonly use a single top-level <template> wrapper. Parse
- * the HTML and unwrap only that exact shape, rather than pattern-matching the
- * raw string. This avoids both regex backtracking risk and accidental rewrites
- * of inputs that contain multiple sibling templates or other top-level content.
- */
-export function unwrapTemplate(html: string): string {
-  const lowered = html.toLowerCase();
-  if (!lowered.includes("<template") || !lowered.includes("</template>")) {
-    return html;
-  }
-
-  const { body } = parseHTMLContent(html);
-  if (!body) return html;
-
-  let container: Element = body;
-  const bodyWrapper = getSingleMeaningfulChild(container);
-  if (bodyWrapper?.tagName === "BODY") {
-    container = bodyWrapper;
-  }
-
-  const template = getSingleMeaningfulChild(container);
-  if (template?.tagName !== "TEMPLATE") {
-    return html;
-  }
-
-  return template.innerHTML ?? html;
-}

package/src/utils/layerCompositor.test.ts

@@ -1,150 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { groupIntoLayers } from "./layerCompositor.js";
-import type { ElementStackingInfo } from "../services/videoFrameInjector.js";
-
-function makeEl(
-  id: string,
-  zIndex: number,
-  isHdr: boolean,
-  overrides?: Partial<ElementStackingInfo>,
-): ElementStackingInfo {
-  return {
-    id,
-    zIndex,
-    x: 0,
-    y: 0,
-    width: 1920,
-    height: 1080,
-    layoutWidth: 1920,
-    layoutHeight: 1080,
-    opacity: 1,
-    visible: true,
-    isHdr,
-    transform: "none",
-    borderRadius: [0, 0, 0, 0],
-    objectFit: "cover",
-    objectPosition: "50% 50%",
-    clipRect: null,
-    ...overrides,
-  };
-}
-
-describe("groupIntoLayers", () => {
-  it("single DOM element → 1 DOM layer", () => {
-    const layers = groupIntoLayers([makeEl("text", 0, false)]);
-    expect(layers).toHaveLength(1);
-    expect(layers[0]!.type).toBe("dom");
-  });
-
-  it("single HDR element → 1 HDR layer", () => {
-    const layers = groupIntoLayers([makeEl("v-hdr", 0, true)]);
-    expect(layers).toHaveLength(1);
-    expect(layers[0]!.type).toBe("hdr");
-  });
-
-  it("merges adjacent DOM elements into one layer", () => {
-    const elements = [makeEl("bg", 0, false), makeEl("text", 1, false), makeEl("logo", 2, false)];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(1);
-    expect(layers[0]!.type).toBe("dom");
-    if (layers[0]!.type === "dom") {
-      expect(layers[0]!.elementIds).toEqual(["bg", "text", "logo"]);
-    }
-  });
-
-  it("splits on HDR/DOM boundary: DOM → HDR → DOM = 3 layers", () => {
-    const elements = [makeEl("bg", 0, false), makeEl("v-hdr", 1, true), makeEl("title", 2, false)];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(3);
-    expect(layers[0]!.type).toBe("dom");
-    expect(layers[1]!.type).toBe("hdr");
-    expect(layers[2]!.type).toBe("dom");
-  });
-
-  it("merges adjacent DOM around multiple HDR: DOM → HDR → HDR → DOM = 4 layers", () => {
-    const elements = [
-      makeEl("bg", 0, false),
-      makeEl("v-hdr1", 1, true),
-      makeEl("v-hdr2", 2, true),
-      makeEl("title", 3, false),
-    ];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(4);
-    expect(layers[0]!.type).toBe("dom");
-    expect(layers[1]!.type).toBe("hdr");
-    expect(layers[2]!.type).toBe("hdr");
-    expect(layers[3]!.type).toBe("dom");
-  });
-
-  it("complex case: DOM DOM HDR DOM HDR DOM = 5 layers (2 DOM merges)", () => {
-    const elements = [
-      makeEl("bg", 0, false),
-      makeEl("caption", 1, false),
-      makeEl("v-hdr1", 2, true),
-      makeEl("text", 3, false),
-      makeEl("v-hdr2", 4, true),
-      makeEl("logo", 5, false),
-    ];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(5);
-    expect(layers.map((l) => l.type)).toEqual(["dom", "hdr", "dom", "hdr", "dom"]);
-    if (layers[0]!.type === "dom") {
-      expect(layers[0]!.elementIds).toEqual(["bg", "caption"]);
-    }
-  });
-
-  it("sorts by zIndex before grouping", () => {
-    const elements = [makeEl("title", 5, false), makeEl("v-hdr", 2, true), makeEl("bg", 0, false)];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(3);
-    expect(layers[0]!.type).toBe("dom"); // bg (z=0)
-    expect(layers[1]!.type).toBe("hdr"); // v-hdr (z=2)
-    expect(layers[2]!.type).toBe("dom"); // title (z=5)
-  });
-
-  it("includes invisible elements in correct z-position", () => {
-    const elements = [
-      makeEl("bg", 0, false),
-      { ...makeEl("hidden-sdr", 1, false), visible: false },
-      { ...makeEl("hidden-hdr", 2, true), visible: false },
-      makeEl("title", 3, false),
-    ];
-    const layers = groupIntoLayers(elements);
-    // All elements included — invisible SDR videos need their injected
-    // <img> replacements hidden from other layers' screenshots
-    expect(layers).toHaveLength(3);
-    expect(layers[0]!.type).toBe("dom"); // bg + hidden-sdr (merged)
-    expect(layers[1]!.type).toBe("hdr"); // hidden-hdr
-    expect(layers[2]!.type).toBe("dom"); // title
-    if (layers[0]!.type === "dom") {
-      expect(layers[0]!.elementIds).toEqual(["bg", "hidden-sdr"]);
-    }
-  });
-
-  it("returns an empty array for empty input", () => {
-    expect(groupIntoLayers([])).toEqual([]);
-  });
-
-  it("handles negative z-index (valid CSS back layers)", () => {
-    const elements = [makeEl("fg", 1, false), makeEl("bg", -5, false)];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(1);
-    expect(layers[0]!.type).toBe("dom");
-    if (layers[0]!.type === "dom") {
-      expect(layers[0]!.elementIds).toEqual(["bg", "fg"]);
-    }
-  });
-
-  it("preserves input order for equal z-index (stable tie-break)", () => {
-    const elements = [
-      makeEl("first", 0, false),
-      makeEl("second", 0, false),
-      makeEl("third", 0, false),
-    ];
-    const layers = groupIntoLayers(elements);
-    expect(layers).toHaveLength(1);
-    if (layers[0]!.type === "dom") {
-      expect(layers[0]!.elementIds).toEqual(["first", "second", "third"]);
-    }
-  });
-});

package/src/utils/layerCompositor.ts

@@ -1,58 +0,0 @@
-/**
- * Layer Compositor — z-order analysis for multi-layer HDR compositing.
- *
- * Groups timed elements into z-ordered layers (DOM or HDR) for the
- * per-frame compositing loop. Adjacent DOM elements merge into a single
- * layer to minimize Chrome screenshots.
- */
-
-import type { ElementStackingInfo } from "../services/videoFrameInjector.js";
-
-export type { ElementStackingInfo };
-
-export type CompositeLayer =
-  | { type: "dom"; elementIds: string[] }
-  | { type: "hdr"; element: ElementStackingInfo };
-
-/**
- * Group z-sorted elements into composite layers. Adjacent DOM elements merge
- * into a single layer; each HDR video/image is its own layer.
- *
- * Elements are sorted by \`zIndex\` ascending (back to front). Ties fall
- * through to V8's stable sort, which preserves \`querySelectorAll\` DOM order —
- * this is the same order Chrome uses for equal-z elements in a stacking
- * context, so the blit order matches what the user sees in-browser.
- *
- * The DOM merge doesn't lose information: DOM layers are rendered via a
- * full-page screenshot with non-layer elements hidden, so within-layer
- * z-order is handled by Chrome itself.
- *
- * Invisible elements ARE included (video elements are hidden by the frame
- * injector, but their injected \`<img>\` replacements are visible — they must
- * stay in the correct z-ordered layer so sibling layers' DOM screenshots
- * hide them).
- */
-export function groupIntoLayers(elements: ElementStackingInfo[]): CompositeLayer[] {
-  // Include ALL elements regardless of visibility. Video elements are hidden by
-  // the frame injector (HEVC can't decode in headless Chrome) but their injected
-  // <img> replacements ARE visible. We need them in the correct z-ordered layer
-  // so they get hidden from other layers' DOM screenshots.
-  const sorted = [...elements].sort((a, b) => a.zIndex - b.zIndex);
-
-  const layers: CompositeLayer[] = [];
-
-  for (const el of sorted) {
-    if (el.isHdr) {
-      layers.push({ type: "hdr", element: el });
-    } else {
-      const last = layers[layers.length - 1];
-      if (last && last.type === "dom") {
-        last.elementIds.push(el.id);
-      } else {
-        layers.push({ type: "dom", elementIds: [el.id] });
-      }
-    }
-  }
-
-  return layers;
-}

package/src/utils/parityContract.ts

@@ -1 +0,0 @@
-export { MEDIA_VISUAL_STYLE_PROPERTIES, quantizeTimeToFrame } from "@hyperframes/core";

package/src/utils/processTracker.test.ts

@@ -1,74 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { spawn } from "node:child_process";
-import { trackChildProcess, killTrackedProcesses } from "./processTracker.js";
-
-// Reset tracked set between tests by killing everything
-beforeEach(() => {
-  killTrackedProcesses();
-});
-
-describe("trackChildProcess", () => {
-  it("tracks a spawned process and removes it after exit", async () => {
-    const proc = spawn("echo", ["hello"], { stdio: "ignore" });
-    trackChildProcess(proc);
-
-    await new Promise<void>((resolve) => proc.on("close", resolve));
-
-    // After exit, killTrackedProcesses should be a no-op (nothing to kill)
-    killTrackedProcesses();
-  });
-
-  it("removes the process on spawn error", async () => {
-    const proc = spawn("/nonexistent-binary-that-does-not-exist", { stdio: "ignore" });
-    trackChildProcess(proc);
-
-    await new Promise<void>((resolve) => proc.on("error", () => resolve()));
-
-    killTrackedProcesses();
-  });
-});
-
-describe("killTrackedProcesses", () => {
-  it("kills a running process", async () => {
-    const proc = spawn("sleep", ["60"], { stdio: "ignore" });
-    trackChildProcess(proc);
-
-    const exitPromise = new Promise<number | null>((resolve) => proc.on("close", resolve));
-    killTrackedProcesses();
-
-    const code = await exitPromise;
-    // SIGTERM exit: code is null (killed by signal)
-    expect(code).toBeNull();
-  });
-
-  it("handles already-exited processes gracefully", async () => {
-    const proc = spawn("true", { stdio: "ignore" });
-    trackChildProcess(proc);
-
-    await new Promise<void>((resolve) => proc.on("close", resolve));
-
-    // Should not throw even though process already exited
-    killTrackedProcesses();
-  });
-
-  it("escalates to SIGKILL for processes that ignore SIGTERM", async () => {
-    // Spawn a process that traps SIGTERM (bash ignoring it)
-    const proc = spawn("bash", ["-c", "trap '' TERM; sleep 60"], { stdio: "ignore" });
-    trackChildProcess(proc);
-
-    const exitPromise = new Promise<void>((resolve) => proc.on("close", resolve));
-    killTrackedProcesses();
-
-    // The 500ms SIGKILL escalation should kill it
-    await exitPromise;
-    expect(proc.killed).toBe(true);
-  }, 5000);
-
-  it("is idempotent — second call is a no-op", () => {
-    const proc = spawn("sleep", ["60"], { stdio: "ignore" });
-    trackChildProcess(proc);
-
-    killTrackedProcesses();
-    killTrackedProcesses();
-  });
-});

package/src/utils/processTracker.ts

@@ -1,41 +0,0 @@
-import type { ChildProcess } from "node:child_process";
-
-const tracked = new Set<ChildProcess>();
-
-export function trackChildProcess(proc: ChildProcess): void {
-  tracked.add(proc);
-  const remove = () => tracked.delete(proc);
-  proc.once("exit", remove);
-  proc.once("error", remove);
-}
-
-/**
- * SIGTERM all tracked child processes, then SIGKILL any that survive
- * after a short grace period.
- */
-export function killTrackedProcesses(): void {
-  const alive: ChildProcess[] = [];
-  for (const proc of tracked) {
-    if (!proc.killed) {
-      try {
-        proc.kill("SIGTERM");
-        alive.push(proc);
-      } catch {
-        // Already exited between the check and the kill.
-      }
-    }
-  }
-  tracked.clear();
-
-  if (alive.length === 0) return;
-
-  setTimeout(() => {
-    for (const proc of alive) {
-      try {
-        proc.kill("SIGKILL");
-      } catch {
-        // Already exited.
-      }
-    }
-  }, 500).unref();
-}

package/src/utils/readWebGlVendorInfoFromCanvas.ts

@@ -1,52 +0,0 @@
-/**
- * Read SwiftShader vendor/renderer via a 1×1 WebGL canvas + the
- * `WEBGL_debug_renderer_info` extension. Used as the `readInfo` override
- * for {@link assertSwiftShader} when the worker is running on
- * `chrome-headless-shell` — that build serves `chrome://gpu` as an empty
- * document so the default `chrome://gpu`-based info reader trips
- * `net::ERR_FAILED` even when the GL backend is in fact SwiftShader.
- *
- * The canvas-based probe runs against whatever page the caller hands in
- * (we use a fresh `about:blank` so it doesn't depend on the composition
- * URL being navigated yet). The renderer string returned matches the
- * format `assertSwiftShader` expects (substring match against
- * `"swiftshader"`).
- */
-
-import type { Page } from "puppeteer-core";
-
-export async function readWebGlVendorInfoFromCanvas(
-  page: Page,
-): Promise<{ vendor: string; renderer: string }> {
-  await page.goto("about:blank", { waitUntil: "domcontentloaded", timeout: 30_000 });
-  return page.evaluate((): { vendor: string; renderer: string } => {
-    try {
-      const canvas = document.createElement("canvas");
-      const gl =
-        (canvas.getContext("webgl") as WebGLRenderingContext | null) ??
-        (canvas.getContext("experimental-webgl") as WebGLRenderingContext | null);
-      if (!gl) {
-        return { vendor: "", renderer: "" };
-      }
-      const ext = gl.getExtension("WEBGL_debug_renderer_info") as {
-        UNMASKED_VENDOR_WEBGL: number;
-        UNMASKED_RENDERER_WEBGL: number;
-      } | null;
-      if (!ext) {
-        return {
-          vendor: String(gl.getParameter(gl.VENDOR) ?? ""),
-          renderer: String(gl.getParameter(gl.RENDERER) ?? ""),
-        };
-      }
-      // Older Chrome builds expose the unmasked strings under the literal
-      // numeric constants 0x9245 / 0x9246. The extension surface above is
-      // identical across builds — read through it.
-      return {
-        vendor: String(gl.getParameter(ext.UNMASKED_VENDOR_WEBGL) ?? ""),
-        renderer: String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) ?? ""),
-      };
-    } catch {
-      return { vendor: "", renderer: "" };
-    }
-  });
-}