Merge remote-tracking branch 'origin/main' into feat-studio-inline-rich-text

This commit is contained in:
Miguel Angel Simon Sierra
2026-08-07 21:29:39 -07:00
154 changed files with 4701 additions and 782 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "hyperframes",
"description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
"version": "0.7.99",
"version": "0.7.101",
"author": {
"name": "HeyGen",
"email": "hyperframes@heygen.com",
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "hyperframes",
"description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
"version": "0.7.99",
"version": "0.7.101",
"author": {
"name": "HeyGen",
"email": "hyperframes@heygen.com",
+1 -1
View File
@@ -3,7 +3,7 @@
"name": "hyperframes",
"displayName": "HyperFrames by HeyGen",
"description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website capture for HyperFrames.",
"version": "0.7.99",
"version": "0.7.101",
"author": {
"name": "HeyGen",
"email": "hyperframes@heygen.com"
+21
View File
@@ -58,6 +58,14 @@ jobs:
with:
chrome-version: stable
# The renderer shells out to ffmpeg for both halves of a preview: the
# poster transcode and the web encode of the mp4. Neither ran here before
# (`--skip-video` skipped the encode, and the poster copy was a plain
# file copy), so the job never needed it and ubuntu-latest does not ship
# it.
- name: Install ffmpeg
run: sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends ffmpeg
- name: Render changed block/component previews
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
@@ -68,6 +76,19 @@ jobs:
| sed 's|^registry/[^/]*/\([^/]*\)/.*|\1|' \
| sort -u)
# A renderer change reaches every item, so it cannot be trusted to a
# PR that happens to also touch a block. Two canaries cover the two
# shapes the renderer has to tell apart: a block whose scene lives in
# a <template> (mounted through a wrapper) and one that registers its
# timeline at body level (rendered directly). Getting that wrong is
# silent — the wrong-shaped block renders blank, not red.
RENDERER_CHANGED=$(git diff --name-only --diff-filter=ACMR "$BASE_SHA"...HEAD \
-- scripts/generate-catalog-previews.ts scripts/registry-target-paths.mjs)
if [ -n "$RENDERER_CHANGED" ]; then
CHANGED_ITEMS=$(printf '%s\n' $CHANGED_ITEMS \
code-snippet-visual-studio-dark code-snippet-apple-terminal-pro | sort -u)
fi
if [ -z "$CHANGED_ITEMS" ]; then
echo "No block/component changes detected."
exit 0
+7
View File
@@ -755,6 +755,13 @@ jobs:
test -s /tmp/hf-cli-inside/renders/inside.mp4
# Belongs in this job because it needs the BUILT CLI: `shouldTrack()`
# short-circuits whenever `isDevMode()` is true, which it is for any `.ts`
# entry, so under vitest a real event and no event look identical. Sends
# nothing to PostHog — the script wraps fetch and captures the batch.
- name: Smoke-test `add` telemetry end to end
run: node scripts/ci/cli-telemetry-e2e.mjs
- name: Assert page.goto completes under 5s budget
run: |
set -euo pipefail
+63
View File
@@ -8,6 +8,69 @@ Recent HyperFrames releases, including user-facing features, fixes, and migratio
{/* New release entries are prepended by `bun run changelog:draft <version> --write`. */}
<Update
label="HyperFrames v0.7.101"
description="Released - 2026-08-08"
tags={["Release", "Studio", "CLI", "Cli,core"]}
>
Faster drawElement capture starts rolling out to a small slice of installs. Five in
a hundred now use the parallel capture path for long renders. If a render ever has
to fall back, that install turns it off and keeps it off.
Set HF_DE_PARALLEL_ROUTER=false to opt out, or =true to opt in early. Studio also
stops three editor crashes.
## Features
- **Cli,core:** Ramp the default-on router through the canary ([4a2514232](https://github.com/heygen-com/hyperframes/commit/4a2514232b9f20ea4baa94510e79a42bae85e92f)).
- **Producer:** Enable the parallel-DE router by default, behind a per-install circuit breaker ([c6df112ac](https://github.com/heygen-com/hyperframes/commit/c6df112ac1843e228a9d40bbcb6bad1752f53de5)).
## Fixes
- **Studio:** Stop three crash-boundary trips in the editor ([d8a91fc34](https://github.com/heygen-com/hyperframes/commit/d8a91fc347df4def4a957609d1847ca3306eb867), [#3102](https://github.com/heygen-com/hyperframes/pull/3102)).
- **CLI:** Keep a set-but-empty router env var breaker-managed (review) ([af535080a](https://github.com/heygen-com/hyperframes/commit/af535080a250bb150c0a6448517a075cd8076818)).
## Docs & Examples
- **CLI:** Stop calling the router trial an opt-in in risk prose ([1033d0327](https://github.com/heygen-com/hyperframes/commit/1033d03271fb381be51fbc1103063cd8147a626b)).
[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.7.100...v0.7.101).
</Update>
<Update
label="HyperFrames v0.7.100"
description="Released - 2026-08-07"
tags={["Release", "Core", "Engine", "Scripts"]}
>
Components that another composition mounts now keep their own styles in the live preview. Some of them rendered unstyled before, even though the video they produced was correct.
Screenshot captures on software rendering no longer accumulate earlier frames, and Studio keeps the preview alive in a tight window.
## Features
- **Producer:** Sniff HTML payload before ffprobe in resolveMediaDuration ([8a11e9776](https://github.com/heygen-com/hyperframes/commit/8a11e9776d3c65c2512c595bbde3dfc5bb194f39)).
## Fixes
- **Engine:** Stop SwiftShader ghosting in software screenshot captures ([b57dc13cb](https://github.com/heygen-com/hyperframes/commit/b57dc13cb6c8752c4f8f9426cfda2faf529136c2), [#3096](https://github.com/heygen-com/hyperframes/pull/3096)).
- **Studio:** Resize an element whose scale is an instant hold ([a850e97f3](https://github.com/heygen-com/hyperframes/commit/a850e97f3d5a2cfcf183aec2cc2620020e8e1bf4), [#3092](https://github.com/heygen-com/hyperframes/pull/3092)).
- **Core:** Stop dropping a mounted composition styles, and gate the divergence ([8d9db3df7](https://github.com/heygen-com/hyperframes/commit/8d9db3df731409d5aaed4ba0af70ea1c81ab40e4), [#3094](https://github.com/heygen-com/hyperframes/pull/3094)).
- **Compiler:** Split font-family only on top-level commas ([172311e95](https://github.com/heygen-com/hyperframes/commit/172311e95e99b04cd2d76d43de9bbadd69c630ab), [#3067](https://github.com/heygen-com/hyperframes/pull/3067)).
- **Studio:** Keep the preview alive when the window is tight ([d5cc1c9c6](https://github.com/heygen-com/hyperframes/commit/d5cc1c9c6249c27a63269288d8b7771656eb50db), [#3091](https://github.com/heygen-com/hyperframes/pull/3091)).
- **CLI:** Refresh identity persistence classification ([7640adc5f](https://github.com/heygen-com/hyperframes/commit/7640adc5f2c39bd5d330aca3d0180ea2f67a793d)).
- **Producer:** Classify JSON error bodies as non-media sources too ([349c066a8](https://github.com/heygen-com/hyperframes/commit/349c066a83c21046f888073776212348c2c5057b)).
- **Producer:** Scope and harden the markup-payload sniff ([f3689c148](https://github.com/heygen-com/hyperframes/commit/f3689c148190b0c72d1b5296b2a5b740d8dd97d8)).
## Catalog
- **Scripts:** Render template-only blocks in catalog previews ([218eff7d3](https://github.com/heygen-com/hyperframes/commit/218eff7d361487becf7e1d6fc0d85453ac199b5e), [#3098](https://github.com/heygen-com/hyperframes/pull/3098)).
## Internal
- **Core:** Settle the four remaining preview-vs-render divergences ([57ec008cb](https://github.com/heygen-com/hyperframes/commit/57ec008cb295efb0a817840a1eadac53fbbf355e), [#3097](https://github.com/heygen-com/hyperframes/pull/3097)).
[View the full commit range](https://github.com/heygen-com/hyperframes/compare/v0.7.99...v0.7.100).
</Update>
<Update
label="HyperFrames v0.7.99"
description="Released - 2026-08-07"
+2 -1
View File
@@ -1063,7 +1063,8 @@ npx hyperframes telemetry status
Telemetry collects command names, render performance, render checkpoint and
error names, aggregate browser diagnostic counts, browser initialization
duration and tween count, aggregate video-extraction workload counts (extracted
frames, VFR preflights), example choices, and system info — including a coarse
frames, VFR preflights), example choices, the names of registry items `add`
installs, and system info — including a coarse
environment fingerprint: OS, kernel string, CPU and memory shape, sandbox
runtime such as gVisor or Docker, and the _name_ of a coding agent driving the
CLI when one is detected (`claude_code`, `codex`, `cursor`). That name is
+4
View File
@@ -265,6 +265,8 @@ Resources:
- PlanProtocolUnsupportedError
- VIDEO_SOURCE_UNRENDERABLE
- INVALID_VIDEO_METADATA
- NOT_MEDIA_PAYLOAD
- NotMediaPayloadError
- PLAN_ARTIFACT_DIGEST_MISMATCH
- FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
MaxAttempts: 0
@@ -309,6 +311,8 @@ Resources:
- PLAN_V2_INTEGRITY_UNRECOVERABLE
- VIDEO_SOURCE_UNRENDERABLE
- INVALID_VIDEO_METADATA
- NOT_MEDIA_PAYLOAD
- NotMediaPayloadError
- PlanV2IntegrityError
- PLAN_ARTIFACT_DIGEST_MISMATCH
- FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/aws-lambda",
"version": "0.7.99",
"version": "0.7.101",
"description": "AWS Lambda adapter for HyperFrames distributed rendering — handler, client-side SDK, and CDK construct.",
"repository": {
"type": "git",
@@ -78,6 +78,8 @@ const EXPECTED_NON_RETRYABLE_ERRORS = new Set([
"PLAN_V2_INTEGRITY_UNRECOVERABLE",
"VIDEO_SOURCE_UNRENDERABLE",
"INVALID_VIDEO_METADATA",
"NOT_MEDIA_PAYLOAD",
"NotMediaPayloadError",
"PlanV2IntegrityError",
"PLAN_ARTIFACT_DIGEST_MISMATCH",
"FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED",
@@ -206,6 +206,8 @@ export class HyperframesRenderStack extends Construct {
"PLAN_V2_INTEGRITY_UNRECOVERABLE",
"VIDEO_SOURCE_UNRENDERABLE",
"INVALID_VIDEO_METADATA",
"NOT_MEDIA_PAYLOAD",
"NotMediaPayloadError",
"PlanV2IntegrityError",
"PLAN_ARTIFACT_DIGEST_MISMATCH",
"FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED",
+1
View File
@@ -152,6 +152,7 @@ function normalizeTerminalErrorName(error: unknown): void {
candidate.code === "PLAN_V2_INTEGRITY_UNRECOVERABLE" ||
candidate.code === "FONT_FETCH_FAILED" ||
candidate.code === "FONT_FETCH_UNAVAILABLE" ||
candidate.code === "NOT_MEDIA_PAYLOAD" ||
candidate.code === "VIDEO_SOURCE_UNRENDERABLE" ||
candidate.code === "VIDEO_EXTRACTION_FAILED" ||
candidate.code === "INVALID_VIDEO_METADATA"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/cli",
"version": "0.7.99",
"version": "0.7.101",
"description": "HyperFrames CLI — create, preview, and render HTML video compositions",
"license": "Apache-2.0",
"repository": {
+38 -1
View File
@@ -4,6 +4,12 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import type { RegistryItem, RegistryManifest } from "@hyperframes/core";
import { AddError, buildSnippet, remapTarget, runAdd } from "./add.js";
import { trackRegistryItemAdded } from "../telemetry/events.js";
// Assert the emitted payload rather than the transport: `shouldTrack()` is
// already false under test (dev mode / no PostHog key), so a real call would
// be indistinguishable from no call at all.
vi.mock("../telemetry/events.js", () => ({ trackRegistryItemAdded: vi.fn() }));
// ── Fixtures ────────────────────────────────────────────────────────────────
@@ -250,7 +256,10 @@ describe("add command pure helpers", () => {
});
describe("runAdd (integration, mocked registry)", () => {
beforeEach(() => mockFetch());
beforeEach(() => {
vi.mocked(trackRegistryItemAdded).mockClear();
mockFetch();
});
afterEach(() => {
vi.unstubAllGlobals();
});
@@ -313,6 +322,9 @@ describe("runAdd (integration, mocked registry)", () => {
code: "incompatible-cli",
});
expect(existsSync(join(dir, "compositions/future-block.html"))).toBe(false);
// Nothing was written, so nothing may be counted: an install count that
// also counts refused installs is not a download count.
expect(trackRegistryItemAdded).not.toHaveBeenCalled();
} finally {
rmSync(dir, { recursive: true, force: true });
}
@@ -359,6 +371,31 @@ describe("runAdd (integration, mocked registry)", () => {
}
});
it("reports every installed item, marking only the requested one", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
await runAdd({ name: "dep-block", projectDir: dir, skipClipboard: true });
// A dependency dragged in behind the request must not read as a vote for
// itself, or a popular dependency outranks everything that depends on it.
expect(trackRegistryItemAdded).toHaveBeenCalledTimes(2);
expect(trackRegistryItemAdded).toHaveBeenCalledWith({
item: "base-component",
itemType: "hyperframes:component",
requested: false,
});
expect(trackRegistryItemAdded).toHaveBeenCalledWith({
item: "dep-block",
itemType: "hyperframes:block",
requested: true,
});
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("throws AddError with code 'example-type' when asked to add an example", async () => {
const dir = tmp();
try {
+17
View File
@@ -28,6 +28,7 @@ import {
writeProjectConfig,
} from "../utils/projectConfig.js";
import { copyToClipboard } from "../utils/clipboard.js";
import { trackRegistryItemAdded } from "../telemetry/events.js";
// ── Target-path resolution ──────────────────────────────────────────────────
// `registry-item.json` files specify `target` paths relative to the project
@@ -197,6 +198,17 @@ export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {
// 5. Install — dependencies first, requested item last.
const written = await installAll(installPlan, projectDir, config.registry);
// Report what landed, not what was asked for: a failed install throws above,
// and the bulk `add <tag>` path re-enters here per item, so this one place
// covers every way an item reaches a project.
for (const planItem of installPlan) {
trackRegistryItemAdded({
item: planItem.name,
itemType: planItem.type,
requested: planItem.name === item.name,
});
}
// 6. Build include snippet + clipboard copy for the requested item.
const itemForInstall = installPlan[installPlan.length - 1]!;
const primaryFile =
@@ -254,6 +266,11 @@ export default defineCommand({
description: "Print a machine-readable summary (written files + snippet) to stdout",
},
},
// `run` is 28 cyclomatic and predates this change, which touches only
// `runAdd`. Fallow scores it as new because the file changed. Splitting the
// tag-fallback branch out would fix it honestly and is worth doing, but not
// inside a telemetry change.
// fallow-ignore-next-line complexity
async run({ args }) {
const projectDir = resolve(args.dir ?? process.cwd());
const json = args.json === true;
+140 -70
View File
@@ -42,6 +42,10 @@ const configState = vi.hoisted(
);
const trackingState = vi.hoisted(() => ({
// The rollout slice. Default-ON is gated on canary enrolment, so these
// tests control it directly rather than depending on where the test
// machine's bucketSeed happens to land.
canaryEnabled: true,
// maybeEnableDeParallelRouterTrial gates on the real shouldTrack(), which
// (via isDevMode()) always returns false when this file itself runs as
// `.ts` source under vitest — mocked here so the CLI-trial tests can
@@ -172,6 +176,10 @@ vi.mock("../telemetry/client.js", () => ({
shouldTrack: vi.fn(() => trackingState.shouldTrack),
}));
vi.mock("../telemetry/canary.js", () => ({
isCanaryEnabled: vi.fn(() => trackingState.canaryEnabled),
}));
vi.mock("../telemetry/events.js", () => ({
trackRenderComplete: vi.fn(),
trackRenderError: vi.fn(),
@@ -238,6 +246,7 @@ describe("renderLocal browser GPU config", () => {
configState.failMirrors = 0;
configState.writeConfigCalls = [];
trackingState.shouldTrack = true;
trackingState.canaryEnabled = true;
trackingState.renderObservations = [];
ffmpegEncoderState.mode = "software";
ffmpegEncoderState.error = null;
@@ -725,7 +734,11 @@ describe("renderLocal browser GPU config", () => {
});
});
describe("renderLocal — DE parallel-router CLI trial", () => {
// Suite renamed with the breaker work: this is no longer an opt-in trial. The
// bindings come from main's shared top-level `renderModule` import rather than
// this suite's own beforeAll — same module instance every other suite uses, so
// module-scope arm/consume state resets through the one `resetTrialState()`.
describe("renderLocal — DE parallel-router circuit breaker", () => {
const { renderLocal, __resetDeParallelRouterTrialStateForTests: resetTrialState } = renderModule;
const savedEnv = new Map<string, string | undefined>();
@@ -736,6 +749,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
configState.failWrites = 0;
configState.writeConfigCalls = [];
trackingState.shouldTrack = true;
trackingState.canaryEnabled = true;
// The "managed by us" flag lives at module scope in render.ts (real CLI
// processes only ever run one --batch sequence, so it never needs
// resetting there) — reset explicitly here so tests don't leak arm/
@@ -768,21 +782,73 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
browserGpuMode: "software" as const,
hdrMode: "auto" as const,
quiet: true,
// The trial is OPT-IN (review): only the CLI's own sequential call sites
// set this. These tests simulate those call sites.
enableDeParallelRouterTrial: true,
// Breaker management is OPT-IN (review): only the CLI's own sequential
// call sites set it. These tests simulate those call sites.
manageDeParallelRouterBreaker: true,
};
it("enables the trial (sets the env var) on a fresh install with telemetry on", async () => {
// The rollout slice. Default-ON means every eligible render routes the
// moment this ships — a ~17x exposure jump. The canary is what makes that
// fraction chosen and revertible instead of emergent.
it("disarms for an install the canary did not enrol", async () => {
trackingState.canaryEnabled = false;
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
// Explicit "false", not delete: with default-ON polarity, deleting the
// var means ON — the same trap the breaker fix exists for.
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
// Setting the registry percentage to 0 must switch the router off fleet-wide
// without a release. That is the revert path, so it has to be pinned.
it("registry percentage is a full kill switch", async () => {
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
trackingState.canaryEnabled = false;
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
delete process.env.HF_DE_PARALLEL_ROUTER;
trackingState.canaryEnabled = true;
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});
// An explicit user choice outranks enrolment in both directions — the
// documented escalation path for anyone who wants the router regardless.
it("never overrides an explicit user value, enrolled or not", async () => {
trackingState.canaryEnabled = false;
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
process.env.HF_DE_PARALLEL_ROUTER = "true";
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
});
it("leaves the env var untouched on a fresh install — the router is default-ON", async () => {
// Under the old opt-in trial this armed HF_DE_PARALLEL_ROUTER="true".
// The router now ships on, so the breaker's job is to stay out of the
// way until something actually fails.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});
it("does not override an env var the user already set themselves", async () => {
configState.disk = {
telemetryEnabled: true,
@@ -794,49 +860,75 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
it("does not enable the trial once it has already fired for this install", async () => {
it("writes an explicit false once the breaker has tripped for this install", async () => {
// THE regression this rework exists for: the old code disabled the
// router by DELETING the var. With a default-ON router, absent means ON,
// so deleting would silently re-enable it on the very host that just
// failed. Only an explicit "false" is a real off-switch.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: true,
telemetryNoticeShown: true,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
it("does not enable the trial when shouldTrack() is false (dev mode / DO_NOT_TRACK)", async () => {
for (const emptyish of ["", " "]) {
it(`treats a set-but-empty env var (${JSON.stringify(emptyish)}) as default, not a user choice`, async () => {
// Both parsers read empty/whitespace as "unset → default ON", so the
// producer routes. If ownership instead treated any defined value as a
// user choice, the breaker would no-op and this install would keep
// retrying a failing router forever — losing the first-fallback
// protection that is the point of the breaker.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
process.env.HF_DE_PARALLEL_ROUTER = emptyish;
producerState.executeImpl = async (job) => {
job.perfSummary = {
resolution: { width: 100, height: 100 },
drawElement: { parallelRouter: "reverted" },
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
expect(configState.writeConfigCalls).toContainEqual(
expect.objectContaining({ deParallelRouterTrialFired: true }),
);
});
}
it("does not override an explicit user opt-in even after a fallback", async () => {
// "Explicit user choice wins in both directions" — the opt-in half.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
trackingState.shouldTrack = false;
process.env.HF_DE_PARALLEL_ROUTER = "true";
producerState.executeImpl = async (job) => {
job.perfSummary = {
resolution: { width: 100, height: 100 },
drawElement: { parallelRouter: "reverted" },
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
});
it("does not enable the trial when config.telemetryEnabled is false, even if shouldTrack() is stale-true (e.g. `hyperframes telemetry off` mid-batch)", async () => {
it("keeps the router on for a telemetry opt-out — analytics choice must not cost performance", async () => {
// The old trial refused to arm without recordable telemetry (no point
// running an experiment you can't measure). Now that the router is a
// shipped default, gating it on telemetry would punish a privacy choice
// with a slower renderer.
configState.disk = {
telemetryEnabled: false,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
trackingState.shouldTrack = true;
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});
it("does not enable the trial before the first-run telemetry disclosure has been shown at least once", async () => {
// cli.ts shows this notice via a fire-and-forget, unawaited dynamic
// import — there's no guarantee it printed before renderLocal runs on a
// brand-new install's very first invocation. Requiring
// telemetryNoticeShown means the trial never races an opt-in message
// against the disclosure it depends on.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: false,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});
@@ -946,11 +1038,9 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
});
it("persists a later --batch row's revert even though this process already armed the trial on an earlier row", async () => {
// Regression test for the exact scenario a --batch run hits: multiple
// renderLocal calls in one process. Before the fix, row 2's
// maybeEnableDeParallelRouterTrial saw process.env.HF_DE_PARALLEL_ROUTER
// already "true" (set by row 1) and mistook that for "the user set it",
// returning trialArmed=false — silently dropping row 2's revert.
// The --batch scenario: multiple renderLocal calls in one process. Row 1
// succeeds (breaker stays out of the way, env untouched); row 2 reverts
// and must still be recorded and trip the breaker.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
@@ -964,7 +1054,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(configState.disk.deParallelRouterTrialFired).toBe(false);
producerState.executeImpl = async (job) => {
@@ -978,12 +1068,14 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
expect(configState.writeConfigCalls).toContainEqual(
expect.objectContaining({ deParallelRouterTrialFired: true }),
);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
// Explicit "false", not deleted: with a default-ON router, unsetting the
// var would re-enable it on the host that just reverted.
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
it("does not arm the trial for programmatic callers that never opted in (opt-in polarity — also covers --batch-concurrency N>=2, which leaves it unset)", async () => {
// The trial's process-wide env var and module-level flags are only safe
// under sequential invocation, so enableDeParallelRouterTrial is OPT-IN
// under sequential invocation, so manageDeParallelRouterBreaker is OPT-IN
// (review): a programmatic renderLocal consumer that doesn't know about
// the trial must get no trial. The CLI's concurrent-batch path relies on
// the same default by leaving the option unset.
@@ -992,7 +1084,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
const { enableDeParallelRouterTrial: _omitted, ...programmaticOptions } = baseOptions;
const { manageDeParallelRouterBreaker: _omitted, ...programmaticOptions } = baseOptions;
await renderLocal("/tmp/project", "/tmp/out.mp4", programmaticOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(configState.writeConfigCalls).toHaveLength(0);
@@ -1011,7 +1103,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
// A real interactive user can't do this mid-batch, but a wrapper script
// invoking the CLI programmatically in the same process could — the
@@ -1021,7 +1113,10 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
it("caps exposure at DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS even when the router never reverts", async () => {
it("never trips on healthy renders, however many — the old 25-render cap is gone", async () => {
// The cap was sampling logic for an opt-in experiment. Under a shipped
// default it would switch the feature off behind the user's back after
// 25 good renders.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
@@ -1034,40 +1129,14 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
};
};
for (let i = 0; i < 25; i++) {
for (let i = 0; i < 30; i++) {
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
}
expect(configState.writeConfigCalls).toContainEqual(
expect.objectContaining({
deParallelRouterTrialFired: true,
deParallelRouterTrialRenderCount: 25,
}),
);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
// The 26th eligible render must not re-arm it.
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});
it("observes a telemetry opt-out written by another process mid-batch (arm site reads fresh, not cached)", async () => {
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
// Row 1 arms and primes the config cache.
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
// Another process runs `hyperframes telemetry off`, writing straight to
// "disk" — this process's cache still says telemetryEnabled: true, so a
// cached read at the arm site would keep arming (review finding).
configState.disk = { ...configState.disk, telemetryEnabled: false };
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(
configState.writeConfigCalls.some((call) => call.deParallelRouterTrialFired === true),
).toBe(false);
});
// The config write landing is NOT enough: config.json is the copy a stale
@@ -1136,10 +1205,11 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
// Nothing could persist...
expect(configState.disk.deParallelRouterTrialFired).toBe(false);
// ...but the in-process latch still blocks the next render from
// re-running the experiment that just failed (review finding).
// re-running the path that just failed (review finding) — and now does
// it by writing an explicit "false", since absent means ON.
producerState.executeImpl = async () => undefined;
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
});
+205 -151
View File
@@ -1,4 +1,5 @@
import { failCommand, requestCliExit } from "../utils/commandResult.js";
import { isCanaryEnabled } from "../telemetry/canary.js";
import { defineCommand } from "citty";
import type { Example } from "./_examples.js";
import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
@@ -69,7 +70,6 @@ import {
writeConfigWithResult,
type HyperframesConfig,
} from "../telemetry/config.js";
import { shouldTrack } from "../telemetry/client.js";
import { renderJobObservabilityTelemetryPayload } from "../telemetry/renderObservability.js";
import { bytesToMb } from "../telemetry/system.js";
import { VERSION } from "../version.js";
@@ -424,21 +424,26 @@ export interface RenderOptions {
/** Skip the interactive feedback prompt after a successful render. */
skipFeedback?: boolean;
/**
* OPT IN to the DE parallel-router CLI trial
* (`maybeEnableDeParallelRouterTrial`) for this render. Default OFF —
* OPT IN to managing the DE parallel-router circuit breaker
* (`applyDeParallelRouterCircuitBreaker`) for this render. Default OFF —
* only the top-level CLI render command's own call sites should ever set
* this (review): the trial mechanism shares one process-wide env var and
* two module-level flags across every `renderLocal` call in the process,
* this (review): the mechanism shares one process-wide env var and two
* module-level flags across every `renderLocal` call in the process,
* which is safe for SEQUENTIAL calls (single render, single-concurrency
* batch rows) but not for genuinely concurrent ones — racing invocations
* could tear down or misattribute each other's outcome. Programmatic
* consumers importing `renderLocal` (a future studio-server path, test
* harnesses, distributed runners) therefore get NO trial unless they
* explicitly opt in AND guarantee sequential invocation. The CLI sets
* this for single renders and for `--batch` at concurrency 1; it leaves
* it unset for `--batch-concurrency N>=2`.
* harnesses, distributed runners) therefore do not manage the breaker
* unless they explicitly opt in AND guarantee sequential invocation. The
* CLI sets this for single renders and for `--batch` at concurrency 1; it
* leaves it unset for `--batch-concurrency N>=2`.
*
* NOTE the asymmetry: the ROUTER itself is default-on for every consumer
* (the producer decides that). This flag only governs whether we
* additionally enforce the per-install breaker, because that is the part
* with process-wide state.
*/
enableDeParallelRouterTrial?: boolean;
manageDeParallelRouterBreaker?: boolean;
}
/**
@@ -841,10 +846,12 @@ export async function renderLocal(
}
const producer = await loadProducer();
const deParallelRouterTrialArmed = maybeEnableDeParallelRouterTrial(
options.quiet,
options.enableDeParallelRouterTrial === true,
);
const deParallelRouterActive =
options.manageDeParallelRouterBreaker === true
? applyDeParallelRouterCircuitBreaker(options.quiet)
: // Not managing the breaker: the router still runs (producer default),
// we just don't enforce or record the per-install trip.
false;
const startTime = Date.now();
const logger = createRenderTelemetryLogger(
@@ -894,7 +901,7 @@ export async function renderLocal(
try {
await producer.executeRenderJob(job, projectDir, outputPath, onProgress);
} catch (error: unknown) {
maybeConsumeDeParallelRouterTrial(deParallelRouterTrialArmed, job, options.quiet);
maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);
handleRenderError(
error,
options,
@@ -913,7 +920,7 @@ export async function renderLocal(
// (win32/x64, CLI 0.7.58): valid MP4 on disk, exited 1 with no error print.
markRenderSucceeded();
maybeConsumeDeParallelRouterTrial(deParallelRouterTrialArmed, job, options.quiet);
maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);
const elapsed = Date.now() - startTime;
if (job.outcome === "completed_with_warnings") {
for (const warning of job.warnings) {
@@ -1072,37 +1079,40 @@ function createNoopProducerLogger(): ProducerLogger {
};
}
/** Backstop cap: even absent an actual router failure, stop offering the
* trial after this many engaged (routed or reverted) renders for an
* install. Without this, a healthy router that never reverts would stay
* force-enabled on every eligible render forever (review finding). */
const DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS = 25;
/**
* True across every `renderLocal` call in THIS process once the trial has
* armed `HF_DE_PARALLEL_ROUTER` here — distinct from the env var's own
* value, which stays "true" across an entire `--batch` run. Without this,
* a second batch row's `process.env.HF_DE_PARALLEL_ROUTER !== undefined`
* check can't tell "we set this ourselves on row 1" from "the user set
* this" and would wrongly treat itself as un-armed, silently dropping that
* row's outcome from ever reaching `maybeConsumeDeParallelRouterTrial`
* (review finding).
* The 25-render exposure cap that bounded the old opt-in TRIAL is gone: the
* router is default-ON as of 2026-07-27, so "stop offering it after N
* renders" would mean switching a shipped default off behind the user's
* back. What survives is the half that was always safety rather than
* sampling — the per-install circuit breaker below, which latches the router
* off for good the first time a render has to fall back.
*/
let deParallelRouterTrialManagedByUs = false;
/**
* In-process latch mirroring `deParallelRouterTrialFired`: set the moment we
* DECIDE the trial is over, independent of whether persisting that decision
* to `~/.hyperframes/config.json` succeeds. `writeConfig` swallows all fs
* The user set `HF_DE_PARALLEL_ROUTER` themselves (either polarity), latched
* once at first observation. Their choice wins over the circuit breaker in
* BOTH directions: we never overwrite an explicit opt-in with `"false"` on a
* fallback, and never overwrite an explicit opt-out either. Latched rather
* than re-read because the breaker itself writes the var — after the first
* write a live `process.env` read could no longer tell "the user set this"
* from "we set this" (the same distinction the old trial needed for
* `--batch` rows sharing one process).
*/
let deParallelRouterUserManaged = false;
let deParallelRouterUserManagedResolved = false;
/**
* In-process latch mirroring the persisted `deParallelRouterTrialFired`: set
* the moment the breaker trips, independent of whether persisting that to
* `~/.hyperframes/config.json` succeeds. `writeConfig` swallows all fs
* errors (by design — telemetry must never break the CLI), so on an
* unwritable config (root-owned file, disk full) the fired flag can never
* stick on disk; without this latch the trial would silently re-arm and
* re-fail on every subsequent render in this process forever (review
* finding). Later processes still re-arm — disk is the only cross-process
* channel — but each process now stops after at most one failure it
* couldn't record.
* unwritable config (root-owned file, disk full) the flag can never stick on
* disk; without this latch the router would re-enable and re-fail on every
* subsequent render in this process. Later processes re-arm — disk is the
* only cross-process channel — but each process now stops after at most one
* failure it couldn't record.
*/
let deParallelRouterTrialFiredThisProcess = false;
let deParallelRouterBreakerTrippedThisProcess = false;
/**
* Test-only reset for the module-level trial state — a real CLI process
@@ -1111,111 +1121,133 @@ let deParallelRouterTrialFiredThisProcess = false;
* one imported module instance.
*/
export function __resetDeParallelRouterTrialStateForTests(): void {
deParallelRouterTrialManagedByUs = false;
deParallelRouterTrialFiredThisProcess = false;
deParallelRouterBreakerTrippedThisProcess = false;
deParallelRouterUserManaged = false;
deParallelRouterUserManagedResolved = false;
}
/**
* True once the trial should stop offering itself: already failed (on disk
* or via this process's in-memory latch), hit the render-count backstop, or
* telemetry isn't actually recordable right now.
* Has this install's router circuit breaker already tripped — on disk, or via
* this process's in-memory latch?
*
* Checks BOTH `shouldTrack()` and `config.telemetryEnabled` directly, not
* `shouldTrack()` alone: `shouldTrack()` (`../telemetry/client.js`) memoizes
* its verdict once per process and never invalidates, so during a long
* `--batch` run (all rows share one process) a `hyperframes telemetry off`
* issued from another terminal mid-batch would never be observed. The
* caller must pass a `readConfigFresh()` snapshot for the same reason —
* `readConfig()` serves a process-lifetime cache that is exactly as stale
* as the `shouldTrack()` memoization this check exists to bypass (review
* finding).
* Deliberately does NOT consider telemetry state. The old opt-in trial did:
* there was no point running an experimental path if the resulting signal
* couldn't be recorded. Now that the router is a shipped default, gating it
* on telemetry would mean users who opted out of analytics silently get a
* slower renderer — punishing a privacy choice with a performance penalty
* (review finding). Telemetry state governs REPORTING, never behavior.
*/
function isDeParallelRouterTrialBlocked(config: HyperframesConfig): boolean {
const overRenderCap =
(config.deParallelRouterTrialRenderCount ?? 0) >= DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS;
return (
deParallelRouterTrialFiredThisProcess ||
Boolean(config.deParallelRouterTrialFired) ||
overRenderCap ||
!config.telemetryEnabled ||
!shouldTrack() ||
// cli.ts shows the first-run telemetry disclosure via a fire-and-forget,
// unawaited dynamic import — there's no guarantee it has printed before
// this render command reaches this point. Requiring telemetryNoticeShown
// means the trial simply never offers itself on a fresh install's very
// first invocation (before the disclosure is guaranteed to have run at
// least once), rather than racing an experimental opt-in message against
// the disclosure it depends on (review finding).
!config.telemetryNoticeShown
);
}
/** Shared cleanup for both `maybeEnableDeParallelRouterTrial` (this process
* should stop offering the trial) and `maybeConsumeDeParallelRouterTrial`
* (the trial just failed/hit its cap) — a no-op unless WE were the ones
* managing the env var. */
function stopManagingDeParallelRouterTrial(): void {
if (!deParallelRouterTrialManagedByUs) return;
delete process.env.HF_DE_PARALLEL_ROUTER;
deParallelRouterTrialManagedByUs = false;
function hasDeParallelRouterBreakerTripped(config: HyperframesConfig): boolean {
return deParallelRouterBreakerTrippedThisProcess || Boolean(config.deParallelRouterTrialFired);
}
/**
* Enable the DE parallel-router experiment (`HF_DE_PARALLEL_ROUTER`, default
* off) for this render, on every eligible render for this install (up to
* `DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS`), so we get real-traffic router
* telemetry (revert rate, verify-db distribution) without requiring anyone
* to manually set the env var — see `HyperframesConfig.deParallelRouterTrialFired`.
* See `maybeConsumeDeParallelRouterTrial` for what turns it off. Returns
* whether this call armed it (so the caller knows to check for consumption
* afterward) — false unless the caller explicitly opted in (`enabled` —
* OPT-IN polarity, review: only the top-level CLI render command's own
* sequential call sites set it; programmatic `renderLocal` consumers get no
* trial by default because the mechanism's process-wide state is unsafe
* under concurrent invocation — see
* `RenderOptions.enableDeParallelRouterTrial`), if it's already failed (or
* hit the render cap) for this install, if the user already set the env var
* themselves (never override an explicit choice — see
* `deParallelRouterTrialManagedByUs` for how a later `--batch` row
* distinguishes that from our own earlier arm), or if telemetry isn't
* actually recordable right now (see `isDeParallelRouterTrialBlocked`; no
* point risking the experimental path if we can't even record the
* resulting signal).
* Latch the router OFF for the rest of this process by writing an explicit
* `"false"`.
*
* Under the old default-OFF flag this deleted the var, because absent meant
* off. With the router default-ON, deleting means ON — the same call would
* silently RE-ENABLE the router on exactly the host that just failed
* (review finding). Writing the explicit value is what makes the breaker a
* breaker. No-op when the user set the var themselves: their choice wins in
* both directions.
*/
function maybeEnableDeParallelRouterTrial(quiet: boolean, enabled: boolean): boolean {
if (!enabled) return false;
// The in-process latch alone decides once it's set — short-circuit before
// the disk read so post-fired batch rows don't pay a config read + parse +
// shared-cache invalidation per row for an answer module state already
// knows (review finding).
if (deParallelRouterTrialFiredThisProcess) {
stopManagingDeParallelRouterTrial();
/**
* Mirror of the producer's `isDeParallelRouterEnabled`. Deliberately
* duplicated rather than imported: `@hyperframes/producer` is lazily loaded
* (`loadProducer()`) to keep CLI startup fast, and this runs on the startup
* path. Keep the two in sync — the producer copy is the source of truth.
*/
function userValueEnablesDeParallelRouter(): boolean {
const raw = process.env.HF_DE_PARALLEL_ROUTER?.trim().toLowerCase();
if (raw === undefined || raw === "") return true;
return !(raw === "false" || raw === "0" || raw === "off" || raw === "no");
}
function applyDeParallelRouterBreaker(): void {
if (deParallelRouterUserManaged) return;
process.env.HF_DE_PARALLEL_ROUTER = "false";
}
/**
* Apply this install's router circuit breaker before a render.
*
* The router is default-ON, so the normal path does NOTHING here — the
* producer's own default takes over. This exists for the one case that must
* survive a shipped default: an install that already had a render fall back
* stays off, permanently, across processes (the verdict is persisted to
* `~/.hyperframes/config.json`). See `maybeConsumeDeParallelRouterTrial` for
* what trips it.
*
* Returns whether the router is active for this render, so the caller knows
* to inspect the outcome afterward.
*/
function applyDeParallelRouterCircuitBreaker(quiet: boolean): boolean {
// Latch the user's own choice on first observation, BEFORE the breaker can
// write the var itself and make the two indistinguishable.
//
// Ownership uses the SAME normalization as the two parsers: a set-but-empty
// (or whitespace) value means "unset / default ON", so it is NOT a user
// choice and must stay breaker-managed. Treating any defined value as
// user-managed would let `HF_DE_PARALLEL_ROUTER=` route the render (empty
// parses as ON) while exempting that install from the breaker — it would
// keep retrying a failing router forever, losing exactly the first-fallback
// protection this PR exists to provide (review finding).
if (!deParallelRouterUserManagedResolved) {
deParallelRouterUserManaged = (process.env.HF_DE_PARALLEL_ROUTER ?? "").trim() !== "";
deParallelRouterUserManagedResolved = true;
}
if (deParallelRouterUserManaged) {
// Explicit choice, either polarity — report whether it enables the
// router so outcomes are still consumed, but never override it.
return userValueEnablesDeParallelRouter();
}
// The in-process latch decides once set — short-circuit before the disk
// read so post-trip batch rows don't pay a config read + parse per row for
// an answer module state already knows.
if (deParallelRouterBreakerTrippedThisProcess) {
applyDeParallelRouterBreaker();
return false;
}
const userSetIt =
process.env.HF_DE_PARALLEL_ROUTER !== undefined && !deParallelRouterTrialManagedByUs;
if (userSetIt) return false;
// readConfigFresh, NOT readConfig: the cached read is exactly as stale as
// the shouldTrack() memoization the blocked-check exists to bypass — a
// mid-batch `hyperframes telemetry off` (or another process persisting
// fired=true) would never be observed through the cache (review finding).
if (isDeParallelRouterTrialBlocked(readConfigFresh())) {
stopManagingDeParallelRouterTrial();
// readConfigFresh, NOT readConfig: the cached read is process-lifetime, so
// another process persisting a trip mid-`--batch` would never be observed.
if (hasDeParallelRouterBreakerTripped(readConfigFresh())) {
deParallelRouterBreakerTrippedThisProcess = true;
applyDeParallelRouterBreaker();
if (!quiet) {
console.log(
c.dim(
" Parallel drawElement capture stays off for this install (a previous render " +
"had to fall back). Re-enable with HF_DE_PARALLEL_ROUTER=true.",
),
);
}
return false;
}
if (deParallelRouterTrialManagedByUs) return true;
deParallelRouterTrialManagedByUs = true;
process.env.HF_DE_PARALLEL_ROUTER = "true";
if (!quiet) {
console.log(
c.dim(
" Trying the experimental parallel drawElement capture path for this install " +
"(disabled automatically if it ever needs to fall back; opt out anytime: " +
"HF_DE_PARALLEL_ROUTER=false)",
),
);
// The rollout slice. Default-ON means every eligible render routes the
// moment this ships — a ~17x jump in exposure, onto profiles today's trial
// population never covered (<=4 CPUs, Docker: ~12% of eligible renders
// between them). Note "trial" is not a user opt-in: it arms automatically on
// the CLI render path, so ~11% of installs already route without anyone
// choosing it. The opt-in is at the CALL SITE — the flag excludes
// programmatic renderLocal consumers, not users.
//
// 0.7.60-0.7.64 is why that matters: every unclamped render reverted for
// five consecutive releases and nobody saw it.
//
// Ramping through the registry makes the exposed fraction a number someone
// chose. Today's ~11% is emergent — the product of eligibility rules and a
// capped trial — so it drifts with fleet composition and cannot be reverted
// without a release. Setting the percentage to 0 turns the router off for
// everyone, immediately, with no code change.
//
// Disarm uses the same explicit "false" the breaker writes, for the same
// reason: with default-ON polarity, deleting the var means ON.
if (!isCanaryEnabled("de-parallel-router")) {
applyDeParallelRouterBreaker();
return false;
}
return true;
}
@@ -1302,40 +1334,62 @@ function persistDeParallelRouterTrialFired(): boolean {
* `persistDeParallelRouterTrialFired`.
*/
function maybeConsumeDeParallelRouterTrial(
trialArmed: boolean,
routerActive: boolean,
job: RenderJob,
quiet: boolean,
): void {
if (!trialArmed) return;
if (!routerActive) return;
const outcome = resolveDeParallelRouterOutcome(job);
if (outcome === undefined) return;
const config = readConfigFresh();
const renderCount = (config.deParallelRouterTrialRenderCount ?? 0) + 1;
config.deParallelRouterTrialRenderCount = renderCount;
const fired = outcome === "reverted" || renderCount >= DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS;
// Trip ONLY on an actual fallback. The old trial also tripped at a
// 25-render exposure cap, which was sampling logic: bound how long an
// experiment force-enables itself. Under a shipped default that would
// switch the feature off behind the user's back after 25 good renders.
const fired = outcome === "reverted";
if (fired) {
config.deParallelRouterTrialFired = true;
// Latch BEFORE attempting persistence — the decision holds for this
// process even if the disk write never sticks (unwritable config).
deParallelRouterTrialFiredThisProcess = true;
stopManagingDeParallelRouterTrial();
deParallelRouterBreakerTrippedThisProcess = true;
applyDeParallelRouterBreaker();
}
writeConfig(config);
// `!quiet`-gated like every other trial message: quiet/batch-json renders
// must produce no unexpected terminal output — CI wrappers asserting
// empty stderr would misread the warning as a render failure (review
// finding). The in-process latch above already guarantees the safety
// behavior the warning describes, whether or not it prints.
if (fired && !persistDeParallelRouterTrialFired() && !quiet) {
console.warn(
c.warn(
" Could not persist the parallel drawElement trial's off-switch to " +
"~/.hyperframes/config.json (unwritable?). The experiment stays off for this " +
"process; future runs may retry it. Set HF_DE_PARALLEL_ROUTER=false to opt out.",
),
);
}
// Only announce a trip the breaker could actually act on. With an explicit
// user opt-in the breaker is a no-op, so "now off for this install" would
// be false — and would reprint on every subsequent revert, since the user's
// value keeps the router active (review finding).
if (fired && !deParallelRouterUserManaged) reportDeParallelRouterBreakerTrip(quiet);
}
/**
* Tell the user the breaker tripped, and warn if the verdict couldn't be
* persisted. All output is `!quiet`-gated: quiet/batch-json renders must
* produce no unexpected terminal output — CI wrappers asserting empty stderr
* would misread a warning as a render failure (review finding). The
* in-process latch guarantees the safety behavior either way.
*/
function reportDeParallelRouterBreakerTrip(quiet: boolean): void {
const persisted = persistDeParallelRouterTrialFired();
if (quiet) return;
console.log(
c.dim(
" A frame failed verification, so parallel drawElement capture fell back to the " +
"screenshot path and is now off for this install. Re-enable: " +
"HF_DE_PARALLEL_ROUTER=true",
),
);
if (persisted) return;
console.warn(
c.warn(
" Could not persist the parallel drawElement circuit breaker to " +
"~/.hyperframes/config.json (unwritable?). It stays off for this process; " +
"future runs may retry it. Set HF_DE_PARALLEL_ROUTER=false to opt out for good.",
),
);
}
function handleRenderError(
+2 -3
View File
@@ -34,7 +34,6 @@ export interface RenderExecutionDependencies {
}
// Exported only through render.ts so command tests can lock the user-facing guidance.
// fallow-ignore-next-line unused-export
export function renderLintContinuationHint(strictErrors: boolean): string {
return strictErrors
? " Continuing render despite lint warnings. Use --strict-all to block warnings."
@@ -109,7 +108,7 @@ export async function executeRenderPlan(
protocolTimeout: plan.protocolTimeout,
playerReadyTimeout: plan.playerReadyTimeout,
exitAfterComplete: true,
enableDeParallelRouterTrial: true,
manageDeParallelRouterBreaker: true,
};
if (plan.useDocker) {
options.pageSideCompositing = plan.pageSideCompositing;
@@ -259,7 +258,7 @@ async function executeBatchRender(
exitAfterComplete: false,
throwOnError: true,
skipFeedback: true,
enableDeParallelRouterTrial: plan.batchConcurrency <= 1,
manageDeParallelRouterBreaker: plan.batchConcurrency <= 1,
};
const manifest = await batchModule.runBatchRender({
prepared: preparedBatch,
+31
View File
@@ -498,6 +498,37 @@ export function trackInitTemplate(templateId: string, props?: { tailwind?: boole
trackEvent("init_template", { template: templateId, tailwind: props?.tailwind });
}
/**
* One event per registry item written into a project.
*
* `cli_command` records that `add` ran, never what it installed, so the
* catalog cannot be ranked by what people actually pull — and the registry is
* served from raw.githubusercontent.com, which gives us no per-item counter
* either. `add` is the only place an item lands in a project, so this is the
* one signal that answers "which block is worth building more of".
*
* `requested` separates the item the user named from the transitive
* `registryDependencies` dragged in behind it. A dependency installed
* alongside something else is not a vote for itself, and collapsing the two
* would rank a popular dependency above everything that depends on it.
*
* Item names are public registry identifiers, never user content or project
* data. This routes through `trackEvent`, so an install that opted out
* (`hyperframes telemetry disable`, `HYPERFRAMES_NO_TELEMETRY`, `DO_NOT_TRACK`)
* emits nothing.
*/
export function trackRegistryItemAdded(props: {
item: string;
itemType: string;
requested: boolean;
}): void {
trackEvent("registry_item_added", {
item: props.item,
item_type: props.itemType,
requested: props.requested,
});
}
export function trackBrowserInstall(): void {
trackEvent("browser_install", {});
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/core",
"version": "0.7.99",
"version": "0.7.101",
"description": "",
"repository": {
"type": "git",
+20 -2
View File
@@ -1,4 +1,6 @@
import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { canaryBucket, evaluateCanary, parseCanaryOverride, type CanaryInput } from "./canary.js";
import { CANARIES, canaryEnvVar, findCanary, overdueCanaries } from "./canaryRegistry.js";
import {
@@ -295,8 +297,24 @@ describe("registry", () => {
// surface. This canary's own description says "ramp only alongside the
// per-install circuit breaker" — without an assertion, bumping it to 5
// before that wiring lands would go green.
it("keeps de-parallel-router at 0% until the circuit breaker is wired", () => {
expect(findCanary("de-parallel-router")?.percentage).toBe(0);
// The registry is data, so a ramp is a one-line edit with no code review
// surface. The previous version enforced "ramp only alongside the circuit
// breaker" by pinning the percentage to 0 — which blocks the ramp forever
// and never checks the wiring it names.
//
// Assert the wiring instead: a non-zero percentage is allowed only while
// the CLI render path really gates on this canary AND still consults the
// per-install breaker. Ramping without the gate would enrol everybody at
// once, which is the whole thing the ramp exists to prevent.
it("only ramps de-parallel-router while the CLI render path gates on it", () => {
const pct = findCanary("de-parallel-router")?.percentage ?? 0;
if (pct === 0) return;
const renderSrc = readFileSync(
join(import.meta.dirname, "..", "..", "cli", "src", "commands", "render.ts"),
"utf8",
);
expect(renderSrc).toContain('isCanaryEnabled("de-parallel-router")');
expect(renderSrc).toContain("deParallelRouterTrialFired");
});
it("has in-range percentages and a parseable sunset date", () => {
+13 -1
View File
@@ -83,7 +83,19 @@ export const CANARIES: readonly CanaryDefinition[] = [
// ── Real rollouts ────────────────────────────────────────────────────────
{
name: "de-parallel-router",
percentage: 0,
// Ramp 5 -> 25 -> 100. This gates the DEFAULT-ON behaviour (uncapped, no
// telemetry precondition), not the old capped trial — so 0 means the
// router is off for everyone and is a full revert without a release.
//
// Calibration validated the bucketer first: 9.62%/49.76% against 10%/50%
// targets at n=13,547, overrides and CI both attributable, sustained
// cohort flips at 0.10% — an order of magnitude under this feature's own
// ~2.79% revert rate.
//
// At each step split revert rate by cpu_count and is_docker. Hold at 5
// until PRINFRA-372 is resolved: `--workers auto` crashes every worker on
// macOS arm64 while `--workers 1` is clean, and the router forces 3.
percentage: 5,
description:
"Route auto multi-worker renders to verified parallel drawElement streaming (HF_DE_PARALLEL_ROUTER). Ramp only alongside the per-install circuit breaker.",
owner: "vance",
@@ -0,0 +1,268 @@
import { readFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import {
enumerateNestedCompositionHosts,
MAX_SUB_COMPOSITION_DEPTH,
planCompositionAssembly,
type CompositionAssemblyPlan,
} from "./compositionAssembly";
function parseComposition(html: string): Document {
return new DOMParser().parseFromString(html, "text/html");
}
/**
* Drive the module the way both real paths do: find the `<template>`, fall back
* to `<body>`, and hand it the document's head and root element. The explicit
* `<Element>` type argument is the whole point of the structural inputs — a
* `DocumentFragment` and an `HTMLElement` both satisfy them without a cast.
*/
function planFor(html: string, compositionId: string | null): CompositionAssemblyPlan<Element> {
const doc = parseComposition(html);
const template = doc.querySelector("template");
return planCompositionAssembly<Element>({
contentNode: template ? template.content : doc.body,
head: doc.head,
documentElement: doc.documentElement,
hasTemplate: Boolean(template),
compositionId,
});
}
const SIBLING_ASSETS = `
<html data-composition-variables='{"tone":"dark"}'>
<head></head>
<body>
<template id="scene-template">
<style id="sibling-style">#root { container-type: size; }</style>
<div data-composition-id="scene" id="root" data-width="1920" data-height="1080"></div>
<script id="sibling-script">window.__a = 1;</script>
</template>
</body>
</html>`;
const ROOT_INTERNAL_ASSETS = `
<html>
<head></head>
<body>
<template id="scene-template">
<div data-composition-id="scene" id="root">
<style id="inner-style">#root { color: red; }</style>
<script id="inner-script">window.__b = 1;</script>
</div>
</template>
</body>
</html>`;
const BOTH_SHAPES = `
<html>
<head></head>
<body>
<template id="scene-template">
<style id="sibling-style">#root { container-type: size; }</style>
<div data-composition-id="scene" id="root">
<style id="inner-style">#root { color: red; }</style>
</div>
</template>
</body>
</html>`;
const FULL_DOCUMENT = `
<html data-composition-variables='{"tone":"dark"}'>
<head>
<link rel="preconnect" href="https://fonts.example">
<link rel="stylesheet" href="fonts.css">
<link rel="icon" href="favicon.ico">
<style id="head-style">body { background: black; }</style>
<script id="head-script" src="https://cdn.example/gsap.js"></script>
</head>
<body>
<div data-composition-id="scene" id="root" data-composition-variables='{"tone":"light"}'>
<style id="body-style">#root { color: red; }</style>
</div>
<script id="body-script">window.__c = 1;</script>
</body>
</html>`;
const ids = (elements: Element[]): string[] => elements.map((el) => el.getAttribute("id") || "");
describe("planCompositionAssembly", () => {
it("reports assets authored as siblings of the composition root inside <template>", () => {
// This is the original defect: collecting from the composition root alone
// dropped the whole stylesheet on mount while the render stayed correct.
const plan = planFor(SIBLING_ASSETS, "scene");
expect(ids(plan.styleSources)).toEqual(["sibling-style"]);
expect(ids(plan.scriptSources)).toEqual(["sibling-script"]);
expect(plan.styleSources[0]?.textContent).toContain("container-type: size");
});
it("reports assets authored inside the composition root", () => {
const plan = planFor(ROOT_INTERNAL_ASSETS, "scene");
expect(ids(plan.styleSources)).toEqual(["inner-style"]);
expect(ids(plan.scriptSources)).toEqual(["inner-script"]);
});
it("reports both shapes once each, in document order", () => {
const plan = planFor(BOTH_SHAPES, "scene");
expect(ids(plan.styleSources)).toEqual(["sibling-style", "inner-style"]);
});
it("reports body assets for a composition with no <template>", () => {
const plan = planFor(FULL_DOCUMENT, "scene");
expect(ids(plan.styleSources)).toContain("body-style");
expect(ids(plan.scriptSources)).toContain("body-script");
});
it("orders head-sourced assets before content-sourced ones", () => {
const plan = planFor(FULL_DOCUMENT, "scene");
expect(ids(plan.styleSources)).toEqual(["head-style", "body-style"]);
expect(ids(plan.scriptSources)).toEqual(["head-script", "body-script"]);
});
it("does not treat a templated composition's page head as an asset source", () => {
// The head belongs to the host page, not to the composition; only the
// non-templated (full-document) shape carries composition assets in <head>.
const plan = planFor(
SIBLING_ASSETS.replace("<head></head>", '<head><style id="page-style">a{}</style></head>'),
"scene",
);
expect(ids(plan.styleSources)).toEqual(["sibling-style"]);
});
it("hoists stylesheet and preconnect links from <head> and nothing else", () => {
const plan = planFor(FULL_DOCUMENT, "scene");
expect(plan.linkSources.map((link) => link.getAttribute("href"))).toEqual([
"https://fonts.example",
"fonts.css",
]);
});
it("identifies the composition from the host id, matching the root exactly", () => {
const plan = planFor(SIBLING_ASSETS, "scene");
expect(plan.innerRoot?.getAttribute("data-composition-id")).toBe("scene");
expect(plan.authoredCompositionId).toBe("scene");
expect(plan.scriptCompositionId).toBe("scene");
expect(plan.authoredRootId).toBe("root");
});
it("keeps CSS on the host id and scripts on the declared id when they disagree", () => {
// A `captions-comp` host mounting a `captions` template: there is no exact
// root match, so nothing is flattened, but the script's self-referencing
// querySelector still has to resolve against the id the content declares.
const plan = planFor(SIBLING_ASSETS, "scene-comp");
expect(plan.innerRoot).toBeNull();
expect(plan.authoredCompositionId).toBe("scene-comp");
expect(plan.scriptCompositionId).toBe("scene");
expect(plan.authoredRootId).toBeNull();
});
it("falls back to the first declared root for an anonymous host", () => {
const plan = planFor(SIBLING_ASSETS, null);
expect(plan.innerRoot?.getAttribute("id")).toBe("root");
expect(plan.authoredCompositionId).toBe("scene");
});
it("reports both the document element and the inner root as variable carriers", () => {
const plan = planFor(FULL_DOCUMENT, "scene");
expect(plan.variableDefaultCarriers).toHaveLength(2);
expect(plan.variableDefaultCarriers[0]?.tagName.toLowerCase()).toBe("html");
expect(plan.variableDefaultCarriers[1]?.getAttribute("id")).toBe("root");
// Precedence order, lowest first: the inner root's declaration wins.
expect(plan.variableDefaultCarriers[1]?.getAttribute("data-composition-variables")).toContain(
"light",
);
});
it("reports only the document element when the content declares no root", () => {
const plan = planFor(
`<html><head></head><body><template id="scene-template"><p>no root</p></template></body></html>`,
"scene",
);
expect(plan.innerRoot).toBeNull();
expect(plan.variableDefaultCarriers).toHaveLength(1);
expect(plan.authoredCompositionId).toBe("scene");
});
});
describe("enumerateNestedCompositionHosts", () => {
const assembled = (html: string): Element => {
const doc = parseComposition(`<html><body><div id="host">${html}</div></body></html>`);
const host = doc.getElementById("host");
if (!host) throw new Error("fixture host missing");
return host;
};
it("enumerates every nested host in document order", () => {
const host = assembled(
`<div data-composition-src="child-a.html"></div><div data-composition-src="child-b.html"></div>`,
);
const { hosts, skipped } = enumerateNestedCompositionHosts(host, ["outer.html"]);
expect(hosts.map((entry) => entry.src)).toEqual(["child-a.html", "child-b.html"]);
expect(hosts[0]?.host.getAttribute("data-composition-src")).toBe("child-a.html");
expect(skipped).toEqual([]);
});
it("skips a src already in its own ancestry instead of recursing forever", () => {
const host = assembled(`<div data-composition-src="outer.html"></div>`);
const { hosts, skipped } = enumerateNestedCompositionHosts(host, ["outer.html"]);
expect(hosts).toEqual([]);
expect(skipped).toEqual([{ src: "outer.html", reason: "circular composition reference" }]);
});
it("stops at the depth cap", () => {
const host = assembled(`<div data-composition-src="deep.html"></div>`);
const atCap = Array.from({ length: MAX_SUB_COMPOSITION_DEPTH }, (_, i) => `level-${i}.html`);
const { hosts, skipped } = enumerateNestedCompositionHosts(host, atCap);
expect(hosts).toEqual([]);
expect(skipped).toEqual([{ src: "deep.html", reason: "nesting depth exceeded" }]);
});
it("ignores a host whose src attribute is empty", () => {
const host = assembled(`<div data-composition-src=""></div>`);
expect(enumerateNestedCompositionHosts(host, ["outer.html"])).toEqual({
hosts: [],
skipped: [],
});
});
});
describe("import surface", () => {
it("imports nothing that the CDN runtime bundle must not carry", () => {
// The runtime ships as an esbuild IIFE. A DOM, filesystem, or cross-package
// import here would ride along, so assert the module's own source rather
// than trusting a comment.
const here = dirname(fileURLToPath(import.meta.url));
const source = readFileSync(resolve(here, "compositionAssembly.ts"), "utf8");
const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
const specifiers = Array.from(code.matchAll(/\bfrom\s+["']([^"']+)["']/g)).map(
(match) => match[1] ?? "",
);
expect(specifiers).toEqual([]);
expect(code).not.toMatch(/\brequire\s*\(/);
// No ambient DOM or Node globals either — the structural inputs exist so
// this module never needs them.
expect(code).not.toMatch(/\b(document|window|globalThis|process|fetch)\s*[.[]/);
});
});
@@ -0,0 +1,244 @@
/**
* Composition assembly decisions — the questions both assembly paths answer.
*
* A composition is assembled twice in this repo: `compiler/inlineSubCompositions.ts`
* assembles it for rendering (Node, linkedom, synchronous, emits strings) and
* `runtime/compositionLoader.ts` assembles it for mounting (browser, fetch, live
* DOM, executes scripts). Their I/O is genuinely different; their *decisions* are
* not. This module owns the decisions:
*
* - which nodes are a composition's asset sources, and in what order
* - which `<head>` elements hoist into the host document
* - the composition's scope identity (CSS scope, script scope, authored root id)
* - which nodes carry the composition's declared variable defaults
* - how nested `data-composition-src` hosts are enumerated
*
* It is deliberately DOM-free, filesystem-free and network-free: the runtime is
* bundled by esbuild into the IIFE published to a CDN, so anything reachable
* from `runtime/entry.ts` ships to every viewer. It takes narrow structural
* types instead of `Document`/`Element` for the same reason `compositionScoping.ts`
* takes strings — so both a linkedom document and a live browser document
* satisfy it without an `as T` cast at either call site.
*/
const COMPOSITION_ID_ATTR = "data-composition-id";
const COMPOSITION_SRC_ATTR = "data-composition-src";
const COMPOSITION_ROOT_SELECTOR = `[${COMPOSITION_ID_ATTR}]`;
const COMPOSITION_HOST_SELECTOR = `[${COMPOSITION_SRC_ATTR}]`;
const STYLE_SELECTOR = "style";
const SCRIPT_SELECTOR = "script";
/**
* `<head>` links both paths hoist into the host document. Stylesheets carry
* webfonts a composition's CSS depends on; preconnects are their latency hint.
*/
const HOISTED_LINK_SELECTOR = 'link[rel="stylesheet"], link[rel="preconnect"]';
/**
* The compiler's nesting cap, enforced against the ancestry chain rather than a
* counter so a wide tree is not penalised for a deep sibling.
*/
export const MAX_SUB_COMPOSITION_DEPTH = 20;
// ---------------------------------------------------------------------------
// Structural inputs
// ---------------------------------------------------------------------------
/** An element this module only ever reads attributes from. */
export interface AssemblyAttributed {
getAttribute(name: string): string | null;
}
/** A node this module only ever searches with a CSS selector. */
export interface AssemblyQueryable<TElement> {
querySelectorAll(selectors: string): Iterable<TElement>;
}
export interface CompositionAssemblyInput<TElement extends AssemblyAttributed> {
/**
* The composition's content: a `<template>`'s content when the composition is
* templated, the parsed document's `<body>` otherwise.
*
* Asset sources are collected from the WHOLE content node, never from the
* composition root alone. The canonical authored shape puts `<style>`/`<script>`
* as SIBLINGS of the root inside `<template>`; scanning only the root dropped a
* composition's entire stylesheet on mount while its render stayed correct.
*/
contentNode: AssemblyQueryable<TElement>;
/**
* The parsed document's `<head>`, when the composition was loaded as a full
* HTML document. Omit it for an inline `<template>`, which has no head of its
* own.
*/
head?: AssemblyQueryable<TElement> | null;
/**
* The parsed document's `<html>` element, when there is one. It is the first
* variable-default carrier; see `variableDefaultCarriers`.
*/
documentElement?: TElement | null;
/**
* True when `contentNode` came from a `<template>`. A templated composition's
* `<head>` styles and scripts are not part of the composition — the template
* already carries everything it needs — so they are not collected.
*/
hasTemplate: boolean;
/**
* The composition id the host asks this composition to mount as, or `null` for
* an anonymous host.
*/
compositionId: string | null;
}
export interface CompositionAssemblyPlan<TElement extends AssemblyAttributed> {
/**
* The composition root inside `contentNode`. Matched on an EXACT id when the
* host names one — a template may intentionally use a different local id (a
* `captions-comp` host mounting a `captions` template), and flattening that
* fallback root changes the assembled DOM. Anonymous hosts fall back to the
* first root in the content.
*/
innerRoot: TElement | null;
/**
* The id CSS is scoped to: the host's id when it names one, otherwise the id
* declared inside the content.
*/
authoredCompositionId: string | null;
/**
* The id composition scripts are scoped to. It differs from
* `authoredCompositionId` only when a host names an id that no root inside the
* content declares: CSS stays on the host's id while scripts follow the id the
* content actually declares, so a script's self-referencing
* `querySelector('[data-composition-id="X"]')` still resolves.
*/
scriptCompositionId: string | null;
/** The `id` attribute authored on the composition root, if any. */
authoredRootId: string | null;
/** `<style>` sources in injection order: head-sourced first, then content. */
styleSources: TElement[];
/**
* `<script>` sources in execution order: head-sourced first, then content. A
* head script (a GSAP CDN tag in a non-templated composition) has to run
* before the content scripts that call into it.
*/
scriptSources: TElement[];
/** `<head>` links to hoist into the host document. */
linkSources: TElement[];
/**
* Nodes that may declare the composition's variable defaults, in precedence
* order — later wins. Full-document compositions declare on `<html>`;
* template/fragment compositions declare on the `[data-composition-id]` root
* div, because they have no `<html>` of their own. Callers read the declared
* defaults off each carrier and merge left to right.
*/
variableDefaultCarriers: TElement[];
}
// ---------------------------------------------------------------------------
// Decisions
// ---------------------------------------------------------------------------
function toArray<TElement>(items: Iterable<TElement> | null | undefined): TElement[] {
return items ? Array.from(items) : [];
}
/**
* Answer, for one composition, where its assets come from, in what order, and
* how it is identified. Pure: it reads attributes and runs selectors, and does
* not mutate, fetch, or touch a filesystem.
*/
export function planCompositionAssembly<TElement extends AssemblyAttributed>(
input: CompositionAssemblyInput<TElement>,
): CompositionAssemblyPlan<TElement> {
const { contentNode, head, documentElement, hasTemplate, compositionId } = input;
const compositionRoots = toArray(contentNode.querySelectorAll(COMPOSITION_ROOT_SELECTOR));
const innerRoot = compositionId
? (compositionRoots.find((root) => root.getAttribute(COMPOSITION_ID_ATTR) === compositionId) ??
null)
: (compositionRoots[0] ?? null);
// The id declared inside the content, even when the host asked for a
// different one. `innerRoot` is preferred so an exact match always wins.
const declaredCompositionId =
(innerRoot ?? compositionRoots[0])?.getAttribute(COMPOSITION_ID_ATTR)?.trim() || "";
// A templated composition's <head> belongs to its host page, not to it.
const assetHead = hasTemplate ? null : (head ?? null);
return {
innerRoot,
authoredCompositionId: compositionId || declaredCompositionId || null,
scriptCompositionId: declaredCompositionId || compositionId || null,
authoredRootId: innerRoot?.getAttribute("id")?.trim() || null,
styleSources: [
...toArray(assetHead?.querySelectorAll(STYLE_SELECTOR)),
...toArray(contentNode.querySelectorAll(STYLE_SELECTOR)),
],
scriptSources: [
...toArray(assetHead?.querySelectorAll(SCRIPT_SELECTOR)),
...toArray(contentNode.querySelectorAll(SCRIPT_SELECTOR)),
],
linkSources: toArray(head?.querySelectorAll(HOISTED_LINK_SELECTOR)),
variableDefaultCarriers: [documentElement, innerRoot].filter(
(carrier): carrier is TElement => carrier != null,
),
};
}
// ---------------------------------------------------------------------------
// Nested hosts
// ---------------------------------------------------------------------------
export type NestedHostSkipReason = "circular composition reference" | "nesting depth exceeded";
export interface NestedCompositionHost<TElement> {
host: TElement;
src: string;
}
export interface NestedCompositionHosts<TElement> {
hosts: NestedCompositionHost<TElement>[];
skipped: { src: string; reason: NestedHostSkipReason }[];
}
/**
* Enumerate the sub-composition hosts nested inside a composition that has just
* been assembled, refusing the two shapes that do not terminate.
*
* `ancestry` is the chain down to and including the assembled composition's own
* `src`, so a top-level host is enumerated with `[itsOwnSrc]`.
*/
export function enumerateNestedCompositionHosts<TElement extends AssemblyAttributed>(
assembledHost: AssemblyQueryable<TElement>,
ancestry: readonly string[],
): NestedCompositionHosts<TElement> {
const hosts: NestedCompositionHost<TElement>[] = [];
const skipped: { src: string; reason: NestedHostSkipReason }[] = [];
for (const nestedHost of assembledHost.querySelectorAll(COMPOSITION_HOST_SELECTOR)) {
const src = nestedHost.getAttribute(COMPOSITION_SRC_ATTR);
if (!src) continue;
if (ancestry.includes(src)) {
skipped.push({ src, reason: "circular composition reference" });
continue;
}
if (ancestry.length >= MAX_SUB_COMPOSITION_DEPTH) {
skipped.push({ src, reason: "nesting depth exceeded" });
continue;
}
hosts.push({ host: nestedHost, src });
}
return { hosts, skipped };
}
@@ -286,6 +286,61 @@ describe("inlineSubCompositions – #ID selector scoping divergence", () => {
});
});
it("collects an inline <head> script instead of discarding it", () => {
// The <head> loop had a `src` branch and no else, so an inline <head>
// script was silently dropped on render while the mount path executed it.
const subCompWithHeadScript = `<!doctype html>
<html><head>
<script>window.__headScriptRan = true;</script>
</head><body>
<div data-composition-id="intro" data-width="1920" data-height="1080"><span>Hi</span></div>
</body></html>`;
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => subCompWithHeadScript,
parseHtml: (html) => parseHTML(html).document,
});
expect(result.scripts.join("\n")).toContain("window.__headScriptRan = true;");
expect(result.scriptItems).toContainEqual({
kind: "inline",
content: expect.stringContaining("window.__headScriptRan = true;"),
});
});
it("hoists a <link> from a TEMPLATED sub-composition's head", () => {
// Hoisting used to be gated on the composition being non-templated, so a
// templated composition's webfont link was kept in preview (the mount path
// hoists unconditionally) and dropped from the render.
const templatedSubCompWithLink = `<!doctype html>
<html><head>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Montserrat">
</head><body>
<template id="intro-template">
<div data-composition-id="intro" data-width="1920" data-height="1080"><span>Hi</span></div>
</template>
</body></html>`;
const document = makeHostDocument("intro");
const host = document.querySelector('[data-composition-src="intro.html"]')!;
const result = inlineSubCompositions(document, [host], {
resolveHtml: () => templatedSubCompWithLink,
parseHtml: (html) => parseHTML(html).document,
});
expect(result.externalLinks).toEqual([
{
href: "https://fonts.googleapis.com/css2?family=Montserrat",
rel: "stylesheet",
crossorigin: undefined,
},
]);
});
it("deduplicates link hrefs across multiple sub-compositions", () => {
const subComp = `<!doctype html>
<html><head>
@@ -15,13 +15,13 @@ import {
rewriteInlineStyleAssetUrls,
type AssetExists,
} from "./rewriteSubCompPaths";
import { queryByAttr } from "../utils/cssSelector";
import {
scopeCssToComposition,
wrapInlineScriptWithErrorBoundary,
wrapScopedCompositionScript,
} from "./compositionScoping";
import { checkSubCompositionUsability } from "@hyperframes/parsers/sub-composition-validity";
import { enumerateNestedCompositionHosts, planCompositionAssembly } from "./compositionAssembly";
// ---------------------------------------------------------------------------
// Public interface
@@ -141,8 +141,6 @@ function defaultBuildScopeSelector(compId: string): string {
return `[data-composition-id="${escaped}"]`;
}
const MAX_SUB_COMPOSITION_DEPTH = 20;
// ---------------------------------------------------------------------------
// Core implementation
// ---------------------------------------------------------------------------
@@ -244,21 +242,21 @@ export function inlineSubCompositions(
continue;
}
// Keep structural flattening tied to an exact mount-id match. A template
// may intentionally use a different local id (for example, a
// `captions-comp` host mounting a `captions` template); flattening that
// fallback root changes the compiled DOM and can invalidate selectors and
// regression goldens. Discover it separately so script timeline
// registration can still map the authored id onto the runtime mount id.
const innerRoot = compId
? queryByAttr(contentDoc, "data-composition-id", compId)
: contentDoc.querySelector("[data-composition-id]");
const authoredCompositionRoot = innerRoot ?? contentDoc.querySelector("[data-composition-id]");
const inferredCompId =
authoredCompositionRoot?.getAttribute("data-composition-id")?.trim() || "";
const authoredRootId = innerRoot?.getAttribute("id")?.trim() || null;
const scopeCompId = compId || inferredCompId;
const scriptCompositionId = inferredCompId || scopeCompId;
// Which node is the composition root, which id its CSS scopes to, which
// id its scripts scope to, where its assets come from and in what order —
// every one of those is decided by the shared assembly module, so the mount
// path in runtime/compositionLoader.ts decides them the same way.
const plan = planCompositionAssembly<Element>({
contentNode: contentDoc,
head: compDoc.head,
documentElement: compDoc.documentElement,
hasTemplate: Boolean(contentRoot),
compositionId: compId,
});
const innerRoot = plan.innerRoot;
const authoredRootId = plan.authoredRootId;
const scopeCompId = plan.authoredCompositionId || "";
const scriptCompositionId = plan.scriptCompositionId || "";
const runtimeScope = runtimeCompId ? buildScopeSelector(runtimeCompId) : "";
// Variable merging (bundler feature). Read declared defaults from the
@@ -266,11 +264,11 @@ export function inlineSubCompositions(
// (template/fragment sub-comps store their schema on the root div, not a
// synthetic <html>), then let per-instance host values override.
if (readVariableDefaults && parseHostVariables && runtimeCompId) {
const mergedVariables = {
...readVariableDefaults(compDoc.documentElement),
...(innerRoot ? readVariableDefaults(innerRoot) : {}),
...parseHostVariables(hostEl),
};
const mergedVariables: Record<string, unknown> = {};
for (const carrier of plan.variableDefaultCarriers) {
Object.assign(mergedVariables, readVariableDefaults(carrier));
}
Object.assign(mergedVariables, parseHostVariables(hostEl));
if (Object.keys(mergedVariables).length > 0) {
variablesByComp[runtimeCompId] = mergedVariables;
}
@@ -295,47 +293,35 @@ export function inlineSubCompositions(
: css;
};
// When a sub-composition is a full HTML document (no <template>), styles
// and scripts in <head> are not part of contentDoc (which only has body
// content). Extract them so backgrounds, positioning, fonts, and library
// scripts (e.g. GSAP CDN) are not silently dropped.
if (!contentRoot && compDoc.head) {
for (const s of [...compDoc.head.querySelectorAll("style")]) {
styles.push(scopeSubStyle(s.textContent || ""));
}
for (const s of [...compDoc.head.querySelectorAll("script")]) {
const externalSrc = resolveSubAssetPath(s.getAttribute("src"));
if (externalSrc) {
if (!externalScriptSrcs.includes(externalSrc)) {
externalScriptSrcs.push(externalSrc);
}
scriptItems.push({ kind: "external", src: externalSrc });
}
}
for (const link of [
...compDoc.head.querySelectorAll('link[rel="stylesheet"], link[rel="preconnect"]'),
]) {
const href = resolveSubAssetPath(link.getAttribute("href"));
if (href && !seenLinkHrefs.has(href)) {
seenLinkHrefs.add(href);
const rel = (link.getAttribute("rel") || "").trim();
const crossorigin = link.hasAttribute("crossorigin")
? link.getAttribute("crossorigin") || ""
: undefined;
externalLinks.push({ href, rel, crossorigin });
}
// <link> hoisting is unconditional. A templated sub-composition's webfont
// link is as load-bearing as a non-templated one's, and the mount path has
// always hoisted both; gating this on `!contentRoot` dropped a templated
// composition's font from the render while preview kept it.
for (const link of plan.linkSources) {
const href = resolveSubAssetPath(link.getAttribute("href"));
if (href && !seenLinkHrefs.has(href)) {
seenLinkHrefs.add(href);
const rel = (link.getAttribute("rel") || "").trim();
const crossorigin = link.hasAttribute("crossorigin")
? link.getAttribute("crossorigin") || ""
: undefined;
externalLinks.push({ href, rel, crossorigin });
}
}
// Extract styles from content
for (const s of [...contentDoc.querySelectorAll("style")]) {
styles.push(scopeSubStyle(s.textContent || ""));
s.remove();
// Head-sourced assets come first: a non-templated sub-composition's <head>
// carries its backgrounds, positioning and fonts, and a <head> library tag
// (GSAP from a CDN) has to run before the content scripts calling into it.
for (const styleEl of plan.styleSources) {
styles.push(scopeSubStyle(styleEl.textContent || ""));
styleEl.remove();
}
// Extract scripts from content
for (const s of [...contentDoc.querySelectorAll("script")]) {
const externalSrc = resolveSubAssetPath(s.getAttribute("src"));
// Head- and content-sourced scripts take the same branch. The head loop
// used to handle only `src`, so an inline <head> script was silently
// discarded on render while the mount path executed it.
for (const scriptEl of plan.scriptSources) {
const externalSrc = resolveSubAssetPath(scriptEl.getAttribute("src"));
if (externalSrc) {
if (!externalScriptSrcs.includes(externalSrc)) {
externalScriptSrcs.push(externalSrc);
@@ -344,18 +330,18 @@ export function inlineSubCompositions(
} else {
const wrappedScript = scriptCompositionId
? wrapScopedCompositionScript(
s.textContent || "",
scriptEl.textContent || "",
scriptCompositionId,
scriptErrorLabel,
runtimeScope || undefined,
runtimeCompId || scopeCompId || scriptCompositionId,
authoredRootId,
)
: wrapInlineScriptWithErrorBoundary(s.textContent || "", scriptErrorLabel);
: wrapInlineScriptWithErrorBoundary(scriptEl.textContent || "", scriptErrorLabel);
scripts.push(wrappedScript);
scriptItems.push({ kind: "inline", content: wrappedScript });
}
s.remove();
scriptEl.remove();
}
// Rewrite relative asset paths before inlining so ../foo.svg from
@@ -408,7 +394,7 @@ export function inlineSubCompositions(
for (const child of [...innerRoot.querySelectorAll("style, script")]) child.remove();
if (flattenInnerRoot) {
const prepared = flattenInnerRoot(innerRoot);
if (!compId && inferredCompId) {
if (!compId && scopeCompId) {
// Anonymous host: flattenInnerRoot strips data-composition-id,
// assuming the host already carries the composition's identity.
// When the host has none, nothing in the render DOM matches the
@@ -416,7 +402,7 @@ export function inlineSubCompositions(
// (e.g. document.querySelector('[data-composition-id="X"]')).
// Restore it on the wrapper so both keep resolving, same as
// before flattening preserved it via outerHTML.
prepared.setAttribute("data-composition-id", inferredCompId);
prepared.setAttribute("data-composition-id", scopeCompId);
}
hostEl.innerHTML = prepared.outerHTML || "";
} else {
@@ -441,18 +427,12 @@ export function inlineSubCompositions(
hostEl.removeAttribute("data-composition-src");
const nestedAncestry = [...ancestry, src];
for (const nestedHost of [...hostEl.querySelectorAll("[data-composition-src]")]) {
const nestedSrc = nestedHost.getAttribute("data-composition-src");
if (!nestedSrc) continue;
if (nestedAncestry.includes(nestedSrc)) {
onMissingComposition?.(nestedSrc, "circular composition reference");
continue;
}
if (nestedAncestry.length >= MAX_SUB_COMPOSITION_DEPTH) {
onMissingComposition?.(nestedSrc, "nesting depth exceeded");
continue;
}
queue.push({ element: nestedHost, ancestry: nestedAncestry });
const nested = enumerateNestedCompositionHosts(hostEl, nestedAncestry);
for (const skipped of nested.skipped) {
onMissingComposition?.(skipped.src, skipped.reason);
}
for (const nestedHost of nested.hosts) {
queue.push({ element: nestedHost.host, ancestry: nestedAncestry });
}
}
@@ -34,6 +34,19 @@ function installGsapMock() {
return { setCalls };
}
/** A gsap mock whose `getTweensOf` returns the supplied colour tweens, so classification is testable. */
function installGsapMockWithTweens(tweens: Array<Record<string, unknown>>) {
const gsap = {
set() {},
killTweensOf() {},
getTweensOf() {
return tweens.map((vars, i) => ({ vars, startTime: () => i }));
},
};
Object.defineProperty(window, "gsap", { configurable: true, value: gsap });
return tweens;
}
async function flushCaptionOverrides() {
for (let i = 0; i < 4; i++) {
await Promise.resolve();
@@ -122,3 +135,103 @@ describe("applyCaptionOverrides", () => {
expect(setCalls[0]?.vars).toEqual({ x: 16 });
});
});
describe("caption state declaration", () => {
it("honours a declared state when dim and active colours are IDENTICAL", async () => {
// The failure the declaration exists for. Classification by colour equality takes the first
// tween's colour as the dim baseline, so a composition whose two states share a colour has
// every tween classified dim — and `activeColor` is silently dropped.
const tweens = installGsapMockWithTweens([
{ color: "#888", data: { captionState: "dim" } },
{ color: "#888", data: { captionState: "active" } },
]);
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
applyCaptionOverrides();
await flushCaptionOverrides();
expect(tweens[0].color).toBe("#111");
expect(tweens[1].color).toBe("#eee");
});
it("falls back to colour classification when nothing is declared", async () => {
// Undeclared compositions must keep working exactly as before — the declaration is additive.
const tweens = installGsapMockWithTweens([{ color: "#222" }, { color: "#fff" }]);
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
applyCaptionOverrides();
await flushCaptionOverrides();
expect(tweens[0].color).toBe("#111");
expect(tweens[1].color).toBe("#eee");
});
it("prefers the declaration over the colour heuristic when they disagree", async () => {
// Declared order is deliberately the reverse of what colour-equality would infer.
const tweens = installGsapMockWithTweens([
{ color: "#222", data: { captionState: "active" } },
{ color: "#fff", data: { captionState: "dim" } },
]);
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#111", activeColor: "#eee" }]);
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
applyCaptionOverrides();
await flushCaptionOverrides();
expect(tweens[0].color).toBe("#eee");
expect(tweens[1].color).toBe("#111");
});
it("does not let a declared tween poison the baseline for undeclared ones", async () => {
// The baseline exists to guess about tweens the declaration has NOT spoken to. Deriving it from
// a tween declared "active" makes every undeclared same-state tween compare against a colour
// that has explicitly said it is not the dim reference — so the one genuinely dim tween here
// gets classified active and receives the wrong override.
const tweens = installGsapMockWithTweens([
{ color: "#eee", data: { captionState: "active" } },
{ color: "#111" },
]);
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#dim", activeColor: "#active" }]);
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
applyCaptionOverrides();
await flushCaptionOverrides();
expect(tweens[0].color).toBe("#active");
expect(tweens[1].color).toBe("#dim");
});
it("prefers a declared dim tween as the baseline over an undeclared one", async () => {
const tweens = installGsapMockWithTweens([
{ color: "#aaa" },
{ color: "#bbb", data: { captionState: "dim" } },
]);
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#dim", activeColor: "#active" }]);
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
applyCaptionOverrides();
await flushCaptionOverrides();
// #bbb is the declared dim reference, so the undeclared #aaa is not dim.
expect(tweens[0].color).toBe("#active");
expect(tweens[1].color).toBe("#dim");
});
it("falls through to the heuristic for a malformed declaration", async () => {
// A typo, a primitive, or a null must never ship a broken composition — an unrecognised value
// is not a state, so classification continues as if nothing was declared.
for (const data of [{ captionState: "typo" }, { captionState: 42 }, null, "notAnObject"]) {
const tweens = installGsapMockWithTweens([{ color: "#222", data }, { color: "#fff" }]);
installCaptionOverrideFetch([{ wordIndex: 0, dimColor: "#dim", activeColor: "#active" }]);
document.body.innerHTML = `<div class="caption-group"><span id="w0">Hi</span></div>`;
applyCaptionOverrides();
await flushCaptionOverrides();
expect(tweens[0].color).toBe("#dim");
expect(tweens[1].color).toBe("#active");
}
});
});
+39 -15
View File
@@ -38,6 +38,23 @@ interface GsapStatic {
getTweensOf: (target: Element) => GsapTween[];
}
/**
* The caption state a composition DECLARES for a colour tween, if any.
*
* Authored as `data: { captionState: "dim" | "active" }` in the tween's vars. GSAP passes unknown
* vars through untouched, so this costs a declaring composition nothing at runtime.
*
* It exists because the fallback below has to GUESS. Classifying by colour equality breaks outright
* when a composition's two states share a colour: every tween matches the dim baseline, and the
* active override is silently dropped. A declaration is the composition telling us what it built,
* rather than us inferring it from what it happens to look like.
*/
function declaredCaptionState(tween: GsapTween): "dim" | "active" | undefined {
const data = tween.vars.data as { captionState?: unknown } | undefined;
const state = data?.captionState;
return state === "dim" || state === "active" ? state : undefined;
}
function resolveCaptionWordElement(el: Element | null): HTMLElement | null {
if (!(el instanceof HTMLElement)) return null;
if (el.dataset.captionWrapper !== "true") return el;
@@ -121,30 +138,37 @@ export function applyCaptionOverrides(): void {
if (override.fontWeight !== undefined) styleProps.fontWeight = override.fontWeight;
if (override.fontFamily !== undefined) styleProps.fontFamily = override.fontFamily;
// Replace color values in existing GSAP tweens.
// Instead of relying on timeline position order (fragile if custom
// color tweens exist), we classify each tween by comparing its
// target color to the current computed color of the element.
// Tweens that match the current color are "dim" tweens; tweens
// with a different color are "active" tweens.
// Replace color values in existing GSAP tweens, classified in two layers.
//
// A tween that DECLARES its state is taken at its word. Anything undeclared falls back to
// colour equality against a dim reference — a guess, and the reason the declaration exists:
// two states sharing a colour make every tween look dim.
//
// The reference is drawn only from tweens the guess still applies to (a declared "dim" one
// if present, else the first undeclared one). Deriving it from a tween declared "active"
// would compare undeclared siblings against a colour that has explicitly said it is not the
// dim reference.
if (override.activeColor || override.dimColor) {
const allTweens = gsap.getTweensOf(el);
const colorTweens = allTweens
.filter((tw) => tw.vars.color !== undefined)
.sort((a, b) => a.startTime() - b.startTime());
// Use the first tween's color as the dim baseline — if no tweens,
// fall back to computed style.
const dimBaseline = colorTweens[0] ? String(colorTweens[0].vars.color) : "";
const dimReference =
colorTweens.find((tw) => declaredCaptionState(tw) === "dim") ??
colorTweens.find((tw) => declaredCaptionState(tw) === undefined);
const dimBaseline = dimReference ? String(dimReference.vars.color) : "";
for (const tw of colorTweens) {
const tweenColor = String(tw.vars.color);
if (tweenColor === dimBaseline) {
// This tween targets the dim/inactive color
// A declaration wins over the colour guess, per tween, so a composition can declare
// some tweens and leave others to the fallback.
const state =
declaredCaptionState(tw) ??
(String(tw.vars.color) === dimBaseline ? "dim" : "active");
if (state === "dim") {
if (override.dimColor) tw.vars.color = override.dimColor;
} else {
// This tween targets the active/spoken color
if (override.activeColor) tw.vars.color = override.activeColor;
} else if (override.activeColor) {
tw.vars.color = override.activeColor;
}
}
@@ -90,6 +90,43 @@ describe("loadExternalCompositions", () => {
expect(injectedStyles.length).toBeGreaterThan(0);
});
it("mounts <style>/<script> authored as siblings of the composition root", async () => {
// The canonical sub-composition shape puts <style> and <script> directly
// inside <template>, NEXT TO the root div rather than inside it. Collecting
// only from the root dropped the composition's whole stylesheet, so rules
// keyed on the root (`#root { container-type: size }`) never landed and every
// container-query unit in the composition resolved against the wrong basis.
const host = document.createElement("div");
host.setAttribute("data-composition-src", "https://example.com/scene.html");
host.setAttribute("data-composition-id", "scene");
document.body.appendChild(host);
const compositionHtml =
`
<html><body>
<template>
<style>#root { container-type: size; }</style>
<div id="root" data-composition-id="scene"><p>Scene</p></div>
<script>window.__sceneRan = true;</scr` +
`ipt>
</template>
</body></html>
`;
vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(compositionHtml, { status: 200 }));
const injectedStyles: HTMLStyleElement[] = [];
const injectedScripts: HTMLScriptElement[] = [];
await loadExternalCompositions({ ...defaultParams, injectedStyles, injectedScripts });
expect(injectedStyles.map((style) => style.textContent).join("")).toContain(
"container-type: size",
);
expect(injectedScripts.map((script) => script.textContent).join("")).toContain("__sceneRan");
// The extracted nodes are stripped from the mounted copy, not duplicated.
expect(host.querySelectorAll("style, script")).toHaveLength(0);
expect(host.querySelector("p")?.textContent).toBe("Scene");
});
it("preserves head stylesheets when an external composition uses a template", async () => {
const host = document.createElement("div");
host.setAttribute("data-composition-src", "https://example.com/compositions/scene.html");
@@ -1182,22 +1219,19 @@ describe("loadExternalCompositions", () => {
});
});
it("preserves data-composition-id unflattened for a host with no id of its own (anonymous host)", async () => {
// Regression test documenting why this file's own prepareFlattenedInnerRoot
// (line ~527) does NOT need the same anonymous-host id-restoration that
// producer/bundler compilation needed: an anonymous host's authoredCompositionId
// is null, so mountCompositionContent's innerRoot lookup never runs, and it
// falls through to a raw document.importNode() of the whole template content
// instead of prepareFlattenedInnerRoot. The composition's own
// data-composition-id is never stripped in the first place, so its root-styling
// CSS and self-referencing querySelector('[data-composition-id="X"]') calls
// already resolve. See PR review discussion on #1886 for the audit trail.
it("scopes an anonymous host's composition to the id its own content declares", async () => {
// A host naming no composition id used to mount the fetched content WHOLE:
// unflattened, and with its CSS injected unscoped, so the composition's
// rules landed on the host document at large. The compiler has always
// fallen back to the first root declared in the content, scoped to it, and
// restored the id that flattening strips. The mount path does the same now.
const host = document.createElement("div");
host.setAttribute("data-composition-src", "https://example.com/scoped-text.html");
document.body.appendChild(host);
const compositionHtml = `
<template id="scoped-text-template">
<style>.label { color: rgb(1, 2, 3); }</style>
<div data-composition-id="scoped-text" data-width="1080" data-height="1920">
<div class="label">Scoped Text Should Stay Styled</div>
</div>
@@ -1206,17 +1240,76 @@ describe("loadExternalCompositions", () => {
vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(compositionHtml, { status: 200 }));
await loadExternalCompositions({ ...defaultParams });
const injectedStyles: HTMLStyleElement[] = [];
await loadExternalCompositions({ ...defaultParams, injectedStyles });
// Not flattened: no data-hf-inner-root wrapper was created.
expect(host.querySelector("[data-hf-inner-root]")).toBeNull();
// The composition's own root element, with its own id intact, is a
// direct descendant of the (still anonymous) host.
// Flattened like every other mount, with the declared id restored so the
// composition's scoped CSS and self-referencing queries still resolve.
const mountedRoot = host.querySelector('[data-composition-id="scoped-text"]');
expect(mountedRoot).not.toBeNull();
expect(mountedRoot?.getAttribute("data-hf-inner-root")).toBe("true");
expect(mountedRoot?.querySelector(".label")?.textContent).toBe(
"Scoped Text Should Stay Styled",
);
// The stylesheet is scoped to the composition rather than leaking whole.
const injectedCss = injectedStyles.map((style) => style.textContent).join("\n");
expect(injectedCss).toContain('[data-composition-id="scoped-text"]');
expect(injectedCss).not.toMatch(/^\s*\.label\s*\{/);
});
// --- D1/D4 regressions: what the compiler and the mount path now agree on ---
it("executes an inline <head> script of a non-templated composition", async () => {
// The compiler used to drop this one on the floor (its <head> loop had a
// `src` branch and no else); the mount path always executed it.
const host = document.createElement("div");
host.setAttribute("data-composition-src", "https://example.com/head-script.html");
host.setAttribute("data-composition-id", "head-script");
document.body.appendChild(host);
vi.spyOn(globalThis, "fetch").mockResolvedValue(
new Response(
`<html><head><script>window.__headScriptRan = true;</script></head><body>
<div data-composition-id="head-script"><p>Body</p></div>
</body></html>`,
{ status: 200 },
),
);
const injectedScripts: HTMLScriptElement[] = [];
await loadExternalCompositions({ ...defaultParams, injectedScripts });
expect(injectedScripts.map((script) => script.textContent).join("\n")).toContain(
"window.__headScriptRan = true;",
);
});
it("scopes scripts to the id the content declares when the host names another", async () => {
// Two scope ids, not one: CSS stays on the id the host asked for, scripts
// follow the id the content actually declares, so a script's own
// querySelector('[data-composition-id="..."]') resolves. Collapsing them
// pointed every self-query at an id that is nowhere in the content.
const host = document.createElement("div");
host.setAttribute("data-composition-src", "https://example.com/captions.html");
host.setAttribute("data-composition-id", "captions-comp");
document.body.appendChild(host);
vi.spyOn(globalThis, "fetch").mockResolvedValue(
new Response(
`<template id="captions-comp-template">
<div data-composition-id="captions"><p>Caption</p></div>
<script>void 0;</script>
</template>`,
{ status: 200 },
),
);
const injectedScripts: HTMLScriptElement[] = [];
const injectedStyles: HTMLStyleElement[] = [];
await loadExternalCompositions({ ...defaultParams, injectedScripts, injectedStyles });
const scriptSource = injectedScripts.map((script) => script.textContent).join("\n");
expect(scriptSource).toContain('var __hfCompId = "captions";');
expect(scriptSource).not.toContain('var __hfCompId = "captions-comp";');
});
});
+100 -120
View File
@@ -1,3 +1,4 @@
import { planCompositionAssembly } from "../compiler/compositionAssembly";
import { scopeCssToComposition, wrapScopedCompositionScript } from "../compiler/compositionScoping";
import { markFlattenedInnerRoot } from "./flattenedRoot";
import {
@@ -181,6 +182,20 @@ function resetCompositionHost(host: Element) {
host.textContent = "";
}
/**
* A composition's `<style>`/`<script>` are extracted and re-injected into the
* host document (scoped), so strip them from the copy that gets mounted —
* otherwise the mount re-declares the same CSS unscoped and re-runs the script.
*
* Strips the CLONE, never the source: `sourceNode` is a live `<template>` on the
* inline-template path, and mutating it would leave a remount with no styles.
*/
function stripExtractedCompositionAssets(node: ParentNode): void {
for (const el of Array.from(node.querySelectorAll("style, script"))) {
el.remove();
}
}
function prepareFlattenedInnerRoot(innerRoot: HTMLElement): HTMLElement {
const prepared = document.importNode(innerRoot, true) as HTMLElement;
markFlattenedInnerRoot(prepared);
@@ -369,12 +384,12 @@ async function mountCompositionContent(params: {
injectedScripts: HTMLScriptElement[];
injectedLinks: HTMLLinkElement[];
parseDimensionPx: (value: string | null) => string | null;
/** Extra <style> elements from the parsed document <head> (non-template sub-compositions). */
headStyles?: HTMLStyleElement[];
/** Extra <script> elements from the parsed document <head> (non-template sub-compositions). */
headScripts?: HTMLScriptElement[];
/** Extra <link> elements from the parsed document <head> (font stylesheets, preconnects). */
headLinks?: HTMLLinkElement[];
/**
* The parsed document's `<head>`, when the composition was loaded as a full
* HTML document. What comes out of it is the shared assembly module's call:
* styles and scripts only for a non-templated composition, links always.
*/
head?: ParentNode | null;
/**
* Defaults extracted from the sub-composition's own
* `<html data-composition-variables="...">` attribute. Layered under the
@@ -389,43 +404,51 @@ async function mountCompositionContent(params: {
details: Record<string, string | number | boolean | null | string[]>;
}) => void;
}): Promise<void> {
let innerRoot: HTMLElement | null = null;
if (params.authoredCompositionId) {
const candidateRoots = Array.from(
params.sourceNode.querySelectorAll<HTMLElement>("[data-composition-id]"),
);
innerRoot =
candidateRoots.find(
(candidate) =>
candidate instanceof HTMLElement &&
candidate.getAttribute("data-composition-id") === params.authoredCompositionId,
) ?? null;
}
// Which node is the composition root, which id its CSS scopes to, which id
// its scripts scope to, where its assets come from and in what order: the
// shared assembly module answers all of it, so this path and the compiler's
// inlineSubCompositions agree by construction. Notably, an ANONYMOUS host
// (one naming no composition id) now falls back to the first root declared
// in the content and mounts scoped to it — mounting the content whole left
// its CSS unscoped and leaking into the host document.
const plan = planCompositionAssembly<Element>({
contentNode: params.sourceNode,
head: params.head,
hasTemplate: params.hasTemplate,
compositionId: params.authoredCompositionId,
});
// The mount sizes and flattens the root, which needs an HTMLElement; a root
// that is not one mounts as plain content, exactly as before.
const innerRoot = plan.innerRoot instanceof HTMLElement ? plan.innerRoot : null;
const contentNode = innerRoot ?? params.sourceNode;
const authoredScopeCompositionId =
innerRoot?.getAttribute("data-composition-id")?.trim() || params.authoredCompositionId || null;
const runtimeScopeCompositionId =
params.runtimeCompositionId || authoredScopeCompositionId || null;
const authoredRootId = innerRoot?.getAttribute("id")?.trim() || null;
const authoredScopeCompositionId = plan.authoredCompositionId;
// Scripts follow the id the CONTENT declares, CSS the id the HOST asked for.
// They differ only when a host names an id no root in the content declares,
// where collapsing them breaks a script's own
// `querySelector('[data-composition-id="..."]')`.
const scriptScopeCompositionId = plan.scriptCompositionId;
// No fallback to the authored id: an anonymous host has no runtime id, and
// the compiler emits no runtime scope selector and no variable table for one.
const runtimeScopeCompositionId = params.runtimeCompositionId || null;
const authoredRootId = plan.authoredRootId;
const runtimeScopeSelector = runtimeScopeCompositionId
? `[data-composition-id="${CSS.escape(runtimeScopeCompositionId)}"]`
: undefined;
if (params.headLinks) {
for (const link of params.headLinks) {
const rawHref = (link.getAttribute("href") || "").trim();
if (!rawHref) continue;
const href = params.compositionUrl ? new URL(rawHref, params.compositionUrl).href : rawHref;
if (params.compositionUrl && isSameDocumentUrl(href, params.compositionUrl)) continue;
if (document.head.querySelector(`link[href="${CSS.escape(href)}"]`)) continue;
const clonedLink = link.cloneNode(true) as HTMLLinkElement;
clonedLink.href = href;
document.head.appendChild(clonedLink);
params.injectedLinks.push(clonedLink);
}
for (const link of plan.linkSources) {
const rawHref = (link.getAttribute("href") || "").trim();
if (!rawHref) continue;
const href = params.compositionUrl ? new URL(rawHref, params.compositionUrl).href : rawHref;
if (params.compositionUrl && isSameDocumentUrl(href, params.compositionUrl)) continue;
if (document.head.querySelector(`link[href="${CSS.escape(href)}"]`)) continue;
const clonedLink = link.cloneNode(true);
if (!(clonedLink instanceof HTMLLinkElement)) continue;
clonedLink.href = href;
document.head.appendChild(clonedLink);
params.injectedLinks.push(clonedLink);
}
const injectScopedStyles = (styleEls: Iterable<HTMLStyleElement>): void => {
const injectScopedStyles = (styleEls: Iterable<Element>): void => {
for (const style of styleEls) {
const clonedStyle = style.cloneNode(true);
if (!(clonedStyle instanceof HTMLStyleElement)) continue;
@@ -446,72 +469,33 @@ async function mountCompositionContent(params: {
params.injectedStyles.push(clonedStyle);
}
};
// Inject <head> styles from non-template sub-compositions first (they define
// element styles like backgrounds and positioning that the composition needs),
// then the content styles.
if (params.headStyles) injectScopedStyles(params.headStyles);
injectScopedStyles(Array.from(contentNode.querySelectorAll<HTMLStyleElement>("style")));
// Already in injection order: <head> styles from a non-template composition
// first (they define backgrounds and positioning the composition needs), then
// the content's — including the ones authored as SIBLINGS of the composition
// root, the shape whose omission dropped a mounted composition's stylesheet.
injectScopedStyles(plan.styleSources);
// Collect head scripts first (e.g. GSAP CDN loaded in <head> of non-template sub-comps),
// then content scripts. Head scripts must execute before content scripts.
const headScriptPayloads: PendingScript[] = [];
if (params.headScripts) {
for (const script of params.headScripts) {
const scriptType = script.getAttribute("type")?.trim() ?? "";
const scriptSrc = script.getAttribute("src")?.trim() ?? "";
if (scriptSrc) {
const resolvedSrc = resolveScriptSourceUrl(scriptSrc, params.compositionUrl);
if (params.compositionUrl && isSameDocumentUrl(resolvedSrc, params.compositionUrl)) {
continue;
}
headScriptPayloads.push({ kind: "external", src: resolvedSrc, type: scriptType });
} else {
const scriptText = script.textContent?.trim() ?? "";
if (scriptText) {
headScriptPayloads.push({
kind: "inline",
content: scriptText,
type: scriptType,
scopeCompositionId: authoredScopeCompositionId,
});
}
}
}
}
const scripts = Array.from(contentNode.querySelectorAll<HTMLScriptElement>("script"));
const scriptPayloads: PendingScript[] = [...headScriptPayloads];
for (const script of scripts) {
const scriptType = script.getAttribute("type")?.trim() ?? "";
const scriptSrc = script.getAttribute("src")?.trim() ?? "";
if (scriptSrc) {
const resolvedSrc = resolveScriptSourceUrl(scriptSrc, params.compositionUrl);
const toPendingScript = (script: Element): PendingScript | null => {
const type = script.getAttribute("type")?.trim() ?? "";
const src = script.getAttribute("src")?.trim() ?? "";
if (src) {
const resolvedSrc = resolveScriptSourceUrl(src, params.compositionUrl);
// A sub-comp that <script src>s itself would re-enter the mount; skip it.
if (params.compositionUrl && isSameDocumentUrl(resolvedSrc, params.compositionUrl)) {
script.parentNode?.removeChild(script);
continue;
}
scriptPayloads.push({
kind: "external",
src: resolvedSrc,
type: scriptType,
});
} else {
const scriptText = script.textContent?.trim() ?? "";
if (scriptText) {
scriptPayloads.push({
kind: "inline",
content: scriptText,
type: scriptType,
scopeCompositionId: authoredScopeCompositionId,
});
return null;
}
return { kind: "external", src: resolvedSrc, type };
}
script.parentNode?.removeChild(script);
}
const remainingStyles = Array.from(contentNode.querySelectorAll<HTMLStyleElement>("style"));
for (const style of remainingStyles) {
style.parentNode?.removeChild(style);
}
const content = script.textContent?.trim() ?? "";
if (!content) return null;
return { kind: "inline", content, type, scopeCompositionId: scriptScopeCompositionId };
};
// Already in execution order: <head> scripts first (a GSAP CDN tag in a
// non-template sub-comp) so they run before the content scripts calling in.
const scriptPayloads = plan.scriptSources
.map(toPendingScript)
.filter((payload): payload is PendingScript => payload !== null);
if (innerRoot) {
const widthRaw = innerRoot.getAttribute("data-width");
@@ -525,9 +509,20 @@ async function mountCompositionContent(params: {
if (innerRoot.hasAttribute("data-timeline-locked")) {
params.host.setAttribute("data-timeline-locked", "");
}
params.host.appendChild(prepareFlattenedInnerRoot(innerRoot));
const flattenedRoot = prepareFlattenedInnerRoot(innerRoot);
if (!params.authoredCompositionId && authoredScopeCompositionId) {
// Flattening strips data-composition-id on the assumption the host
// carries the composition's identity. An anonymous host does not, so
// restore it or nothing in the mounted DOM matches the composition's own
// scoped CSS. Mirrors the identical restore in inlineSubCompositions.
flattenedRoot.setAttribute("data-composition-id", authoredScopeCompositionId);
}
stripExtractedCompositionAssets(flattenedRoot);
params.host.appendChild(flattenedRoot);
} else if (params.hasTemplate) {
params.host.appendChild(document.importNode(contentNode, true));
const mountedContent = document.importNode(contentNode, true);
stripExtractedCompositionAssets(mountedContent);
params.host.appendChild(mountedContent);
} else {
params.host.innerHTML = params.fallbackBodyInnerHtml;
}
@@ -702,23 +697,6 @@ export async function loadExternalCompositions(
)
: null) ?? doc.querySelector<HTMLTemplateElement>("template");
const sourceNode = template ? template.content : doc.body;
// When loading a non-template sub-composition (full HTML document),
// extract <style> and <script> elements from the parsed document's
// <head>. These contain critical CSS (backgrounds, positioning, fonts)
// and library scripts (e.g. GSAP CDN) that would otherwise be lost
// because mountCompositionContent only looks inside the composition
// root element.
const headStyles = !template
? Array.from(doc.head.querySelectorAll<HTMLStyleElement>("style"))
: undefined;
const headScripts = !template
? Array.from(doc.head.querySelectorAll<HTMLScriptElement>("script"))
: undefined;
const headLinks = Array.from(
doc.head.querySelectorAll<HTMLLinkElement>(
'link[rel="stylesheet"], link[rel="preconnect"]',
),
);
await mountCompositionContent({
host,
authoredCompositionId,
@@ -732,9 +710,11 @@ export async function loadExternalCompositions(
injectedScripts: params.injectedScripts,
injectedLinks: params.injectedLinks,
parseDimensionPx: params.parseDimensionPx,
headStyles,
headScripts,
headLinks,
// A non-templated composition's <head> carries critical CSS
// (backgrounds, positioning, fonts) and library scripts; every
// composition's <head> can carry a webfont <link>. The shared
// assembly module decides which of those apply.
head: doc.head,
// TODO(template-var-carriers): reads `<html>` only. A template/fragment
// sub-comp that declares on its `[data-composition-id]` root div (the
// dual-carrier contract from #2081) loses its defaults on this lazy
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/engine",
"version": "0.7.99",
"version": "0.7.101",
"description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
"repository": {
"type": "git",
+8
View File
@@ -274,6 +274,14 @@ export {
type KeyframeAnalysis,
} from "./utils/ffprobe.js";
export {
NOT_MEDIA_PAYLOAD,
NotMediaPayloadError,
assertMediaPayload,
fingerprintElementId,
isNotMediaPayload,
} from "./utils/notMediaPayload.js";
export {
assertPublicHttpsUrl,
downloadToTemp,
@@ -154,6 +154,50 @@ describe("processCompositionAudio", () => {
]);
});
// STUDIO-5433: an audio src that resolved to an HTML/XML page (an unresolved
// nested-composition preview URL, or a 403/404 body served as a 200) skips the
// probe entirely when the element carries an authored duration, and used to
// surface as `prepare/ffmpeg_failed` with owner "system" — an authoring bug
// paged as a platform fault, after every frame had already been captured.
it("classifies a document audio source as a user-owned invalid media source", async () => {
const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));
const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));
tempDirs.push(baseDir, workDir);
writeFileSync(join(baseDir, "bgm.mp3"), "<!DOCTYPE html><html><body>not audio</body></html>");
const result = await processCompositionAudio(
[
{
id: "bgm",
src: "bgm.mp3",
// Authored duration + loop is the shape that bypasses every probe.
start: 0,
end: 30,
mediaStart: 0,
layer: 0,
volume: 1,
type: "audio",
},
],
baseDir,
workDir,
join(baseDir, "out.m4a"),
30,
);
expect(result.failures).toEqual([
expect.objectContaining({
stage: "source",
reason: "invalid_media",
owner: "user",
retryable: false,
elementId: "bgm",
}),
]);
// Never reached ffmpeg: the whole point is failing before the work.
expect(runFfmpegMock).not.toHaveBeenCalled();
});
it("preserves muted tracks and uses unity master gain by default", async () => {
const baseDir = mkdtempSync(join(tmpdir(), "hf-audio-base-"));
const workDir = mkdtempSync(join(tmpdir(), "hf-audio-work-"));
@@ -9,6 +9,7 @@ import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeF
import { join, dirname } from "path";
import { parseHTML } from "linkedom";
import { extractAudioMetadata } from "../utils/ffprobe.js";
import { isNotMediaPayload } from "../utils/notMediaPayload.js";
import {
downloadToTemp,
isHttpUrl,
@@ -745,6 +746,26 @@ export async function processCompositionAudio(
return;
}
// STUDIO-5433: an audio src that resolved to a text document (an
// unresolved nested-composition preview URL, or a 403/404 body served
// with a 200) never reaches the probe below when the element carries an
// authored duration or `loop`. It then fails inside ffmpeg as
// `prepare/ffmpeg_failed` with owner "system" — an authoring bug paged
// as a platform fault, after every frame has already been captured.
if (await isNotMediaPayload(srcPath)) {
failures.push({
stage: "source",
reason: "invalid_media",
owner: "user",
retryable: false,
elementId: element.id,
detail: boundedDetail(
`Audio element ${element.id} source is a text document (HTML/XML/JSON), not media`,
),
});
return;
}
// Fallback: if no duration was specified, probe the actual file
if (element.end - element.start <= 0) {
let metadata;
@@ -7,6 +7,8 @@ import { join } from "node:path";
import type { Browser, PuppeteerNode } from "puppeteer-core";
import type { CaptureMode } from "./browserLeasePool.js";
import {
_resetAutoBrowserGpuModeCacheForTests,
_resetBrowserPoolForTests,
@@ -132,23 +134,22 @@ describe("buildChromeArgs browser GPU mode", () => {
expect(args).not.toContain("--enable-gpu-rasterization");
});
it("disables GPU compositing only for software BeginFrame capture", () => {
const softwareBeginFrame = buildChromeArgs(
{ ...base, captureMode: "beginframe" },
{ browserGpuMode: "software" },
);
const softwareScreenshot = buildChromeArgs(
{ ...base, captureMode: "screenshot" },
{ browserGpuMode: "software" },
);
const hardwareBeginFrame = buildChromeArgs(
{ ...base, captureMode: "beginframe", platform: "linux" },
{ browserGpuMode: "hardware" },
);
// HF#3049: the stale-raster accumulation lives in SwiftShader's compositor,
// which every capture mode reads from — so the gate is the GPU mode alone.
// Swept over the whole CaptureMode union so a future mode can't quietly opt
// out of the workaround the way `screenshot` did.
const captureModes: CaptureMode[] = ["beginframe", "screenshot", "drawelement"];
expect(softwareBeginFrame).toContain("--disable-gpu-compositing");
expect(softwareScreenshot).not.toContain("--disable-gpu-compositing");
expect(hardwareBeginFrame).not.toContain("--disable-gpu-compositing");
it.each(captureModes)("disables GPU compositing for software %s capture", (captureMode) => {
expect(
buildChromeArgs({ ...base, captureMode, platform: "linux" }, { browserGpuMode: "software" }),
).toContain("--disable-gpu-compositing");
});
it.each(captureModes)("leaves hardware %s capture on the GPU compositor", (captureMode) => {
expect(
buildChromeArgs({ ...base, captureMode, platform: "linux" }, { browserGpuMode: "hardware" }),
).not.toContain("--disable-gpu-compositing");
});
it("uses Metal-backed ANGLE for hardware browser GPU mode on macOS", () => {
+25 -12
View File
@@ -910,20 +910,33 @@ export function buildChromeArgs(
chromeArgs.push(WEBGPU_FLAG);
}
// SwiftShader's GPU compositor can retain a transformed layer for several
// sequential frames after a GSAP yoyo/reversal, and it re-presents stale
// raster for a partially invalidated layer: content already drawn in an
// earlier seek is never cleared, so successive captures accumulate copies of
// it (HF#3049 — a moving SVG group smears wider on every frame, and static
// siblings appear duplicated one band lower). The DOM and timeline are
// already at the requested time; the defect is in the compositor surface both
// BeginFrame and Page.captureScreenshot read, so it is not specific to a
// capture mode — it is specific to compositing on SwiftShader.
//
// Routing compositing through Chrome's software path is the only mitigation
// that holds: capture-side changes (fromSurface, captureBeyondViewport, a
// second capture, extra rAF ticks, a 250ms settle) and every raster/tiling
// flag (--disable-partial-raster, --disable-checker-imaging, --disable-zero-copy,
// forced tile sizes) leave the accumulation untouched. The cost is that
// SwiftShader rasterizes thin strokes and glyph edges slightly differently
// (antialiased edges only — measured on HF#3049's frame 0: 96 opaque pixels
// differ, by 1/255). Duplicated content in 68% of frames is the worse defect.
//
// Remove this workaround once the pinned chrome-headless-shell includes
// https://issues.chromium.org/issues/535256667.
if (browserGpuMode === "software") {
chromeArgs.push("--disable-gpu-compositing");
}
// BeginFrame flags — only when using chrome-headless-shell on Linux
if (options.captureMode !== "screenshot") {
// SwiftShader's GPU compositor can retain a transformed layer for several
// sequential frames after a GSAP yoyo/reversal. The DOM and timeline are
// already at the requested time, but both BeginFrame and
// Page.captureScreenshot read the stale surface (the duplicate is present
// in the raw JPEG before encoding). Keep deterministic BeginFrame capture,
// but route compositing through Chrome's software path when the browser is
// already in software-GPU mode. Hardware-GPU and screenshot captures keep
// their existing compositor paths. Remove this workaround once the pinned
// chrome-headless-shell includes https://issues.chromium.org/issues/535256667.
if (browserGpuMode === "software") {
chromeArgs.push("--disable-gpu-compositing");
}
chromeArgs.push(
"--deterministic-mode",
"--enable-begin-frame-control",
@@ -0,0 +1,177 @@
import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import {
assertMediaPayload,
fingerprintElementId,
isNotMediaPayload,
NotMediaPayloadError,
} from "./notMediaPayload.js";
function writeFixture(name: string, contents: string | Buffer): string {
const dir = mkdtempSync(join(tmpdir(), "hf-markup-sniff-"));
const filePath = join(dir, name);
writeFileSync(filePath, contents);
return filePath;
}
describe("isNotMediaPayload", () => {
it.each([
["doctype", "<!DOCTYPE html>\n<html><body></body></html>"],
["bare html tag, uppercase", "<HTML><body>hi</body></HTML>"],
[
"xml prolog",
'<?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg"/>',
],
// The prolog-less form is the common minified SVG shape, and the one a
// `<!doctype|<html|<?xml` prefix allowlist misses.
["prolog-less svg", '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 1"/>'],
// How a media URL most often downloads as XML in production: an expired
// signed URL or an ACL change, served as a 200 with an S3 error body.
["s3 error document", '<?xml version="1.0"?><Error><Code>AccessDenied</Code></Error>'],
["comment first", "<!-- generated -->\n<!DOCTYPE html>"],
// Replicate answers a dead asset this way, and a gateway in front of it can
// relay the body with a 200 — the shape a `<` -only check misses.
["json object error body", '{"detail": "requested file not found"}'],
["json array body", '[{"error": "gone"}]'],
])("detects %s", async (_label, contents) => {
expect(await isNotMediaPayload(writeFixture("payload", contents))).toBe(true);
});
it("detects a document behind a UTF-8 BOM and leading whitespace", async () => {
const filePath = writeFixture(
"bom.html",
Buffer.concat([
Buffer.from([0xef, 0xbb, 0xbf]),
Buffer.from("\n \t<!doctype html><html></html>"),
]),
);
expect(await isNotMediaPayload(filePath)).toBe(true);
});
it("detects a document behind a leading NUL run", async () => {
const filePath = writeFixture(
"nul.html",
Buffer.concat([Buffer.from([0x00, 0x00, 0x00]), Buffer.from("<html>x</html>")]),
);
expect(await isNotMediaPayload(filePath)).toBe(true);
});
it.each([
["little-endian", [0xff, 0xfe]],
["big-endian", [0xfe, 0xff]],
])("detects UTF-16 %s markup", async (_label, bom) => {
// UTF-16 interleaves NULs between ASCII bytes, so a utf8-decoded prefix
// comparison sees replacement characters and misses it entirely.
const body = Buffer.from("<html>", "utf16le");
const bytes = _label === "little-endian" ? body : body.swap16();
const filePath = writeFixture("utf16.html", Buffer.concat([Buffer.from(bom), bytes]));
expect(await isNotMediaPayload(filePath)).toBe(true);
});
it("detects nothing when padding overruns the sniff window", async () => {
const filePath = writeFixture("padded.html", `${" ".repeat(600)}<!doctype html>`);
// 600 bytes of padding overruns the 512-byte sniff window, so the verdict
// has to be "unknown" (false) rather than a misread — asserted here so the
// window size is a deliberate, visible bound rather than an accident.
expect(await isNotMediaPayload(filePath)).toBe(false);
});
it.each([
["mp4 / ftypmp42", [0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70, 0x6d, 0x70, 0x34, 0x32]],
["matroska / webm EBML", [0x1a, 0x45, 0xdf, 0xa3, 0x9f, 0x42, 0x86, 0x81, 0x01]],
["ogg", [0x4f, 0x67, 0x67, 0x53, 0x00, 0x02]],
["riff / wav", [0x52, 0x49, 0x46, 0x46, 0x24, 0x08]],
["mpeg-ts", [0x47, 0x40, 0x00, 0x10]],
["flac", [0x66, 0x4c, 0x61, 0x43, 0x00]],
["mp3 / ID3", [0x49, 0x44, 0x33, 0x03, 0x00]],
["adts aac", [0xff, 0xf1, 0x50, 0x80]],
["mpeg-ps", [0x00, 0x00, 0x01, 0xba]],
])("does not flag a %s container", async (_label, bytes) => {
expect(await isNotMediaPayload(writeFixture("clip.bin", Buffer.from(bytes)))).toBe(false);
});
it("does not flag a container that merely contains a document byte further in", async () => {
const filePath = writeFixture(
"not-html.bin",
Buffer.concat([Buffer.from([0x00, 0x00, 0x01, 0xba]), Buffer.from("<html later on")]),
);
expect(await isNotMediaPayload(filePath)).toBe(false);
});
it("does not flag an empty file", async () => {
expect(await isNotMediaPayload(writeFixture("empty.bin", ""))).toBe(false);
});
it("reports not-a-document instead of throwing when the path is a directory", async () => {
// `existsSync` passes for a directory, so callers reach the sniff with one.
// The read fails EISDIR; classifying rather than propagating keeps the real
// probe's own error as the one the caller sees.
const dir = mkdtempSync(join(tmpdir(), "hf-markup-sniff-dir-"));
mkdirSync(join(dir, "assets"));
expect(await isNotMediaPayload(join(dir, "assets"))).toBe(false);
});
it("reports not-a-document instead of throwing when the file is missing", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-markup-sniff-gone-"));
expect(await isNotMediaPayload(join(dir, "evicted.mp4"))).toBe(false);
});
});
describe("assertMediaPayload", () => {
it("throws NotMediaPayloadError carrying routing metadata and a hashed element key", async () => {
const filePath = writeFixture("nested.html", "<!DOCTYPE html><html></html>");
let caught: unknown;
try {
await assertMediaPayload(filePath, "aroll-scene-3");
} catch (error) {
caught = error;
}
expect(caught).toBeInstanceOf(NotMediaPayloadError);
const error = caught as NotMediaPayloadError;
expect(error.code).toBe("NOT_MEDIA_PAYLOAD");
expect(error.owner).toBe("user");
expect(error.retryable).toBe(false);
expect(error.elementFingerprints).toEqual([fingerprintElementId("aroll-scene-3")]);
expect(error.message).toContain(fingerprintElementId("aroll-scene-3"));
});
it("names both possible causes and leaks neither the src nor the payload bytes", async () => {
// `error.message` is forwarded to API clients over SSE/JSON, so a
// per-tenant CDN path or a token in the payload's first bytes must not
// reach it — and an on-call engineer must not be pointed at the authoring
// bug when a 403 error page is the actual cause.
const filePath = writeFixture(
"interstitial.html",
'<!DOCTYPE html><html data-request-token="tok_9fA3xQ7pLz">',
);
const error = await assertMediaPayload(
filePath,
"https://cdn.example.com/tenants/acme-corp/projects/secret-q4/streamed-preview.html",
).catch((caught: unknown) => caught as NotMediaPayloadError);
expect(error.message).not.toContain("acme-corp");
expect(error.message).not.toContain("secret-q4");
expect(error.message).not.toContain("cdn.example.com");
expect(error.message).not.toContain("tok_9fA3xQ7pLz");
expect(error.message).toContain("unresolved");
expect(error.message).toContain("success status");
});
it("resolves for a real container", async () => {
const filePath = writeFixture("clip.mp4", Buffer.from([0x00, 0x00, 0x00, 0x18, 0x66, 0x74]));
await expect(assertMediaPayload(filePath, "v1")).resolves.toBeUndefined();
});
it("caps the fingerprint list so the message stays bounded", async () => {
const error = new NotMediaPayloadError(
Array.from({ length: 12 }, (_unused, index) => fingerprintElementId(`el-${index}`)),
);
expect(error.message).toContain("+4");
expect(error.message.length).toBeLessThan(500);
});
});
@@ -0,0 +1,152 @@
import { createHash } from "node:crypto";
import { open as openFile } from "node:fs/promises";
export const NOT_MEDIA_PAYLOAD = "NOT_MEDIA_PAYLOAD" as const;
/** Cap the joined fingerprint list so the message stays bounded. */
const MAX_LISTED_FINGERPRINTS = 8;
/**
* Thrown when a file behind a `<video>`/`<audio>` src is a text document
* (HTML, XML, SVG, JSON) rather than a media container.
*
* Motivating incident: STUDIO-5433 — an authoring bug produced an a-roll
* element whose src pointed at a `streamed-preview.html` URL that downloaded
* to a legitimate 6.5 KB `<!DOCTYPE html>` page instead of the expected MP4.
* ffprobe's `[mov,mp4,m4a,3gp,3g2,mj2 @ ...] moov atom not found` masked the
* cause (the `mov,mp4,…` prefix is ffprobe's demuxer probe order, not the
* file's true format), so the alert routed as an ffmpeg/codec bug.
*
* Only a 2xx response reaches this classifier. `downloadToTemp` rejects a
* 404/410 as `http_not_found` before writing a byte (urlDownloader.ts
* `classifyHttpFailure`), and every ffprobe input is local — an http src is
* downloaded first. So the shapes that land here are a soft-404 or
* interstitial HTML body, an S3/CloudFront error document, or a JSON API error
* body, each served with a success status.
*
* Deliberately says nothing about *why* the payload is a document: an
* unresolved nested-composition URL and a CDN error page served with a 200
* both land here, and naming only the first sends on-call after the wrong
* cause.
*
* Message discipline mirrors `AssetMediaTypeMismatchError`: bounded text with
* hashed element correlation keys, never the authored src or the payload's own
* bytes — producer forwards `error.message` to API clients.
*/
export class NotMediaPayloadError extends Error {
readonly code = NOT_MEDIA_PAYLOAD;
readonly owner = "user" as const;
readonly retryable = false as const;
readonly elementFingerprints: readonly string[];
constructor(elementFingerprints: readonly string[]) {
const listed = elementFingerprints.slice(0, MAX_LISTED_FINGERPRINTS).join(",");
const elided = elementFingerprints.length - MAX_LISTED_FINGERPRINTS;
super(
`${elementFingerprints.length} media source(s) are text documents ` +
`(HTML/XML/JSON), not media containers ` +
`[elements=${listed}${elided > 0 ? `,+${elided}` : ""}]. Either an unresolved ` +
"nested-composition preview URL was authored as a media src, or the source answered with " +
"an error page or API error body carrying a success status.",
);
this.name = "NotMediaPayloadError";
this.elementFingerprints = elementFingerprints;
}
}
/** Stable, bounded correlation key. Never the raw element id or source. */
export function fingerprintElementId(elementId: string): string {
return createHash("sha256").update(elementId).digest("hex").slice(0, 16);
}
const SNIFF_BYTES = 512;
// `<` opens HTML/XML/SVG and an S3 `<Error>` body; `{` and `[` open a JSON API
// error body, which some gateways return with a 200.
const DOCUMENT_OPENING_BYTES = new Set([0x3c, 0x7b, 0x5b]);
// NUL is skippable so UTF-16-encoded text (`3C 00 68 00 …`) is caught, and so
// is a payload padded with NULs. No supported container is defeated by this:
// mp4/mov open with a box size whose first non-NUL byte is the size itself, and
// MPEG-PS `00 00 01 BA` stops at 0x01.
const SKIPPABLE_LEADING_BYTES = new Set([0x00, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x20]);
const BYTE_ORDER_MARKS = [
Buffer.from([0xef, 0xbb, 0xbf]), // UTF-8
Buffer.from([0xff, 0xfe]), // UTF-16 LE
Buffer.from([0xfe, 0xff]), // UTF-16 BE
];
function byteOrderMarkLength(head: Buffer): number {
for (const mark of BYTE_ORDER_MARKS) {
if (head.length >= mark.length && head.subarray(0, mark.length).equals(mark)) {
return mark.length;
}
}
return 0;
}
/** Read up to {@link SNIFF_BYTES} from the front of the file. */
async function readHead(filePath: string): Promise<Buffer> {
const fh = await openFile(filePath, "r");
try {
const buf = Buffer.alloc(SNIFF_BYTES);
let filled = 0;
// Looped because a single read can come back short on NFS/FUSE and on
// FIFOs, which would truncate the window mid-prefix.
while (filled < buf.length) {
const { bytesRead } = await fh.read(buf, filled, buf.length - filled, filled);
if (bytesRead === 0) break;
filled += bytesRead;
}
return buf.subarray(0, filled);
} finally {
await fh.close().catch(() => {});
}
}
function startsWithDocumentByte(head: Buffer): boolean {
for (let index = byteOrderMarkLength(head); index < head.length; index++) {
const byte = head[index];
if (byte === undefined) break;
if (SKIPPABLE_LEADING_BYTES.has(byte)) continue;
return DOCUMENT_OPENING_BYTES.has(byte);
}
// Empty or all-whitespace: not this classifier's call.
return false;
}
/**
* True when the file's first meaningful byte opens a text document (`<`, `{`,
* `[`) rather than a media container. BOM- and whitespace-tolerant.
*
* Three bytes replace an allowlist of document shapes: `<!doctype`, `<html`,
* `<?xml`, a prolog-less `<svg`, an S3 `<Error>` body, and a JSON
* `{"detail": "requested file not found"}` all start with one of them, and no
* container this pipeline supports does — mp4/mov start with a box size,
* Matroska/WebM `1A 45 DF A3`, Ogg `OggS`, RIFF `RIFF`, MPEG-TS `0x47`, FLAC
* `fLaC`, ADTS `FF Fx`, MP3 `ID3`. An allowlist would need a new entry every
* time a new payload shape shows up in production.
*
* Never throws: this is a classifier, not a gate. An unreadable file (EACCES,
* EISDIR, a temp file evicted between `existsSync` and here) reports "not a
* document" so the real probe still produces the real error, exactly as it did
* before the sniff existed.
*/
export async function isNotMediaPayload(filePath: string): Promise<boolean> {
try {
return startsWithDocumentByte(await readHead(filePath));
} catch {
return false;
}
}
/**
* Throw {@link NotMediaPayloadError} if `filePath` is a text document.
*
* Only for sources whose element type can never legitimately be one —
* `<video>` and `<audio>`. An `<img>` src may be an SVG, which ffprobe reads
* through its `svg_pipe` demuxer, so image sources must not be sniffed.
*/
export async function assertMediaPayload(filePath: string, elementId: string): Promise<void> {
if (await isNotMediaPayload(filePath)) {
throw new NotMediaPayloadError([fingerprintElementId(elementId)]);
}
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/gcp-cloud-run",
"version": "0.7.99",
"version": "0.7.101",
"description": "Google Cloud Run + Workflows adapter for HyperFrames distributed rendering — request handler, client-side SDK, and Terraform module.",
"repository": {
"type": "git",
+2
View File
@@ -906,11 +906,13 @@ const NON_RETRYABLE_ERROR_NAMES = new Set([
"PLAN_V2_INTEGRITY_UNRECOVERABLE",
"VIDEO_SOURCE_UNRENDERABLE",
"INVALID_VIDEO_METADATA",
"NOT_MEDIA_PAYLOAD",
// Producer error class names (`.name`) + their string code aliases — the
// class sets `.name` to the class name but wraps a `code`; cover both so a
// raw-code throw is caught too. Mirrors the AWS state machine's
// non-retryable list.
"FormatNotSupportedInDistributedError",
"NotMediaPayloadError",
"PlanTooLargeError",
"PlanProtocolUnsupportedError",
"PlanV2IntegrityError",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/lint",
"version": "0.7.99",
"version": "0.7.101",
"repository": {
"type": "git",
"url": "https://github.com/heygen-com/hyperframes",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/parsers",
"version": "0.7.99",
"version": "0.7.101",
"repository": {
"type": "git",
"url": "https://github.com/heygen-com/hyperframes",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/player",
"version": "0.7.99",
"version": "0.7.101",
"description": "Embeddable web component for HyperFrames compositions",
"repository": {
"type": "git",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@hyperframes/producer",
"version": "0.7.99",
"version": "0.7.101",
"description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
"repository": {
"type": "git",
@@ -0,0 +1,19 @@
import { describe, expect, it } from "vitest";
import { NotMediaPayloadError } from "@hyperframes/engine";
import { extractSafeRenderErrorMetadata } from "./server.js";
// Kept out of server.errorCode.test.ts so that suite keeps exactly one typed
// error class in scope: two same-shaped classes there defeat the dead-code
// analyzer's member resolution and it reports the sibling's fields as unused.
describe("extractSafeRenderErrorMetadata — non-media payloads", () => {
it("transports the code, owner, and retry policy", () => {
// Without the SAFE_RENDER_ERROR_CODES entry the API emits
// `errorCode: undefined` and the failure is indistinguishable from an
// untyped crash — as unroutable as the `moov atom not found` it replaces.
expect(extractSafeRenderErrorMetadata(new NotMediaPayloadError(["0123456789abcdef"]))).toEqual({
errorCode: "NOT_MEDIA_PAYLOAD",
errorOwner: "user",
retryable: false,
});
});
});
+1
View File
@@ -121,6 +121,7 @@ interface PreparedRenderInput {
const DEFAULT_SERVER_FPS = { num: 30, den: 1 } as const;
const SAFE_RENDER_ERROR_CODES = new Set<string>([
"ASSET_MEDIA_TYPE_MISMATCH",
"NOT_MEDIA_PAYLOAD",
"INVALID_VIDEO_METADATA",
"VIDEO_SOURCE_UNRENDERABLE",
"VIDEO_EXTRACTION_FAILED",
@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { NOT_MEDIA_PAYLOAD, NotMediaPayloadError } from "@hyperframes/engine";
import {
ASSET_MEDIA_TYPE_MISMATCH,
AssetMediaTypeMismatchError,
@@ -191,6 +192,64 @@ describe("preflightCompositionAssetMediaTypes", () => {
await expect(run({ imageSrc: "corrupt-media" })).resolves.toBeUndefined();
});
// STUDIO-5433. This preflight sees every local media src regardless of its
// authored timing, so it is the only place a document payload behind a
// `data-end` video or a `loop`ing audio is caught before frames are captured
// — for those elements the compiler never resolves a duration, so its own
// sniff never runs.
describe("non-media payloads", () => {
beforeAll(() => {
writeFileSync(
join(projectDir, "streamed-preview.html"),
"<!DOCTYPE html><html><body>not media</body></html>",
);
writeFileSync(
join(projectDir, "brand-mark.svg"),
'<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"><rect width="8" height="8"/></svg>',
);
});
it("rejects an HTML payload under a video element", async () => {
let caught: unknown;
try {
await run({ videoSrc: "streamed-preview.html" });
} catch (error) {
caught = error;
}
expect(caught).toBeInstanceOf(NotMediaPayloadError);
expect(caught).toMatchObject({
code: NOT_MEDIA_PAYLOAD,
owner: "user",
retryable: false,
});
const message = (caught as Error).message;
expect(message).not.toContain("streamed-preview.html");
expect(message).not.toContain(fixtureDir);
});
it("reports the document verdict ahead of the type mismatch the same file also produces", async () => {
// An HTML page under a <video> is both "not media" and "not video". The
// document verdict is the actionable one; the mismatch is a symptom of it.
await expect(run({ videoSrc: "streamed-preview.html" })).rejects.toBeInstanceOf(
NotMediaPayloadError,
);
});
it("leaves an audio source to the mixer's per-element classification", async () => {
// A bad audio source is non-fatal by existing policy: the render ships
// without the track and reports `audioError`. Aborting the whole compile
// here would turn renders that used to succeed into hard failures, so
// audioMixer classifies it as source/invalid_media/owner:user instead.
await expect(run({ audioSrc: "streamed-preview.html" })).resolves.toBeUndefined();
});
it("leaves an SVG image source alone", async () => {
// ffprobe reads SVG through its svg_pipe demuxer, so an XML body is a
// legitimate <img> payload and must not be swept up by the sniff.
await expect(run({ imageSrc: "brand-mark.svg" })).resolves.toBeUndefined();
});
});
it("re-probes a path after its media contents are replaced", async () => {
const mutablePath = join(projectDir, "mutable-media");
const signal = new AbortController().signal;
@@ -1,6 +1,8 @@
import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
import {
fingerprintElementId,
isNotMediaPayload,
NotMediaPayloadError,
probeMediaProfile,
resolveProjectRelativeSrc,
type AudioElement,
@@ -39,10 +41,6 @@ export class AssetMediaTypeMismatchError extends Error {
}
}
function fingerprintElementId(elementId: string): string {
return createHash("sha256").update(elementId).digest("hex").slice(0, 16);
}
function detectedAssetMediaType(profile: MediaProbeProfile): DetectedAssetMediaType {
if (profile.visualKind === "moving") return "video";
if (profile.visualKind === "still") return "image";
@@ -133,10 +131,29 @@ export async function preflightCompositionAssetMediaTypes(input: {
}
const mismatches: AssetMediaTypeMismatch[] = [];
const notMediaFingerprints: string[] = [];
const entries = [...byPath];
await Promise.all(
entries.map(([resolvedPath, pathReferences]) =>
withMediaProbeSlot(async () => {
// STUDIO-5433. This preflight is the only place every local media src is
// seen regardless of its authored timing, so it is where a document
// payload behind a `data-end` video gets caught — the compiler's own
// sniff only runs for elements whose duration it has to resolve.
//
// Video only, deliberately. An `<img>` may legitimately be an SVG,
// which ffprobe reads through its `svg_pipe` demuxer. And a bad audio
// source is non-fatal by existing policy (audioStage ships the render
// without the track and reports `audioError`), so it is classified
// per-element in audioMixer instead of aborted here.
const sniffableReferences = pathReferences.filter((ref) => ref.expected === "video");
if (sniffableReferences.length > 0 && (await isNotMediaPayload(resolvedPath))) {
notMediaFingerprints.push(
...sniffableReferences.map((ref) => fingerprintElementId(ref.id)),
);
return;
}
let profile: MediaProbeProfile;
try {
profile = await probeMediaProfile(resolvedPath, { signal: input.signal });
@@ -156,5 +173,8 @@ export async function preflightCompositionAssetMediaTypes(input: {
),
);
// Thrown ahead of the mismatch aggregate: "this file is an HTML page" is the
// actionable diagnosis, while the type mismatch it also produces is a symptom.
if (notMediaFingerprints.length > 0) throw new NotMediaPayloadError(notMediaFingerprints);
if (mismatches.length > 0) throw new AssetMediaTypeMismatchError(mismatches);
}
@@ -253,6 +253,17 @@ describe("injectDeterministicFontFaces — failClosedFontFetch: true", () => {
expect(result).toBe(html);
});
it("does NOT throw when font-family uses a CSS var() reference with a fallback", async () => {
const html = `<!doctype html><html><head><style>
.title { font-family: var(--brand-font, inherit); }
</style></head><body><h1 class="title">hello</h1></body></html>`;
const result = await injectDeterministicFontFaces(html, {
failClosedFontFetch: true,
fetchImpl: makeFailingFetch(),
});
expect(result).toBe(html);
});
it("resolves simple CSS var() font aliases when injecting deterministic fonts", async () => {
const html = `<!doctype html><html><head><style>
:root { --ui-font: "Inter"; --vowel-font: "Montserrat"; }
@@ -54,10 +54,44 @@ export const GENERIC_FAMILIES: ReadonlySet<string> = new Set([
* Whitespace and surrounding `"…"` / `'…'` quotes are stripped; case is
* preserved. Pass each name through `normalizeFamilyName` for case-
* insensitive comparisons.
*
* Only top-level commas split: a `var(--x, fallback)` expression stays one
* token, as does a comma inside a quoted family name.
*/
export function parseFontFamilyValue(value: string): string[] {
return value
.split(",")
const pieces: string[] = [];
let start = 0;
let depth = 0;
let quote: "'" | '"' | null = null;
for (let index = 0; index < value.length; index += 1) {
const char = value[index];
if (char === "\\") {
index += 1;
continue;
}
if (quote) {
if (char === quote) quote = null;
continue;
}
if (char === "'" || char === '"') {
quote = char;
continue;
}
if (char === "(") {
depth += 1;
continue;
}
if (char === ")") {
depth = Math.max(0, depth - 1);
continue;
}
if (char !== "," || depth !== 0) continue;
pieces.push(value.slice(start, index));
start = index + 1;
}
pieces.push(value.slice(start));
return pieces
.map((piece) => piece.trim().replace(/^['"]/, "").replace(/['"]$/, "").trim())
.filter((piece) => piece.length > 0);
}
@@ -1,19 +1,39 @@
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
// @vitest-environment happy-dom
import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
import {
bundleToSingleHtml,
extractCompiledHtmlParityContract,
injectScriptsIntoHtml,
} from "@hyperframes/core/compiler";
// Deep import: the mount path is not part of core's published export map (it is
// bundled into the runtime IIFE, not imported by consumers). Same shape as
// engine/src/services/videoFrameExtractor.test.ts reaching into core's runtime.
import { loadExternalCompositions } from "../../../core/src/runtime/compositionLoader.js";
import { compileForRender } from "./htmlCompiler.js";
import { getVerifiedHyperframeRuntimeSource } from "./hyperframeRuntimeLoader.js";
const tempDirs: string[] = [];
beforeAll(() => {
// The mount path scopes CSS with CSS.escape, which the DOM stub omits.
if (typeof globalThis.CSS === "undefined") {
Object.defineProperty(globalThis, "CSS", { value: {}, configurable: true, writable: true });
}
if (typeof CSS.escape !== "function") {
CSS.escape = (value: string) => value.replace(/([^\w-])/g, "\\$1");
}
});
afterEach(() => {
for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
document.head.innerHTML = "";
document.body.innerHTML = "";
delete (window as Window & { __hfVariablesByComp?: unknown }).__hfVariablesByComp;
delete (window as Window & { __timelines?: unknown }).__timelines;
vi.restoreAllMocks();
});
function project(files: Record<string, string>): string {
@@ -27,6 +47,39 @@ function project(files: Record<string, string>): string {
return dir;
}
type ParityContract = ReturnType<typeof extractCompiledHtmlParityContract>;
/**
* Mount the project the way the player does — parse `index.html` into the live
* document, serve its sub-compositions over a stubbed `fetch`, and let the
* runtime assemble them — then read the same contract off the resulting DOM.
*
* This is the third assembly path. Both compiler arms below run the same code
* up to `bundleToSingleHtml`, which is why a runtime-only regression (a mounted
* composition losing every `<style>` authored beside its root) stayed invisible
* to a green suite.
*/
async function mountContract(dir: string, indexHtml: string): Promise<ParityContract> {
const parsed = new DOMParser().parseFromString(indexHtml, "text/html");
document.head.innerHTML = parsed.head.innerHTML;
document.body.innerHTML = parsed.body.innerHTML;
vi.spyOn(globalThis, "fetch").mockImplementation(async (input) =>
Promise.resolve(new Response(readFileSync(join(dir, String(input)), "utf8"), { status: 200 })),
);
await loadExternalCompositions({
injectedStyles: [],
injectedScripts: [],
injectedLinks: [],
parseDimensionPx: (value: string | null) => (value ? `${value}px` : null),
// A mount that fails is not a parity result. Surface it instead of
// comparing the contract of an empty host against a compiled one.
onDiagnostic: ({ code, details }) => {
throw new Error(`mount diagnostic ${code}: ${JSON.stringify(details)}`);
},
});
return extractCompiledHtmlParityContract(`<!doctype html>${document.documentElement.outerHTML}`);
}
async function contracts(files: Record<string, string>) {
const dir = project(files);
const preview = await bundleToSingleHtml(dir);
@@ -42,6 +95,7 @@ async function contracts(files: Record<string, string>) {
return {
preview: extractCompiledHtmlParityContract(preview),
render: extractCompiledHtmlParityContract(servedRender),
mount: await mountContract(dir, files["index.html"]!),
};
}
@@ -94,3 +148,151 @@ describe("preview/render semantic compilation parity", () => {
expect(result.render).toEqual(result.preview);
});
});
const FONT_FACE = `@font-face { font-family: ParityBody; src: url(data:font/woff2;base64,d09GMgAB) format("woff2"); }`;
const anonymousCardHost = (body: string) => ({
"index.html":
shell(`<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
<section id="card-host" data-composition-src="compositions/card.html"
data-start="1" data-duration="3"></section>
</main>`),
"compositions/card.html": body,
});
const cardHost = (body: string) => ({
"index.html":
shell(`<main data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="6">
<section id="card-host" data-composition-id="card" data-composition-src="compositions/card.html"
data-start="1" data-duration="3"></section>
</main>`),
"compositions/card.html": body,
});
/**
* Every fixture here mounts a sub-composition, because the mount path only runs
* for one. The set has to keep covering the shape that broke — see the
* assertion below, which fails if a refactor quietly drops it.
*/
const MOUNT_PARITY_FIXTURES: { name: string; files: Record<string, string> }[] = [
{
name: "assets authored as siblings of the composition root",
files: cardHost(`<template id="card-template">
<style>${FONT_FACE}
.parity-card { --parity-contract: 3; font-family: ParityBody, sans-serif; }</style>
<article id="card-root" data-composition-id="card" data-width="800" data-height="600">
<h2 class="parity-card">Card</h2>
</article>
</template>`),
},
{
name: "assets authored inside the composition root",
files: cardHost(`<template id="card-template">
<article id="card-root" data-composition-id="card" data-width="800" data-height="600">
<style>${FONT_FACE}
.parity-card { --parity-contract: 4; font-family: ParityBody, sans-serif; }</style>
<h2 class="parity-card">Card</h2>
</article>
</template>`),
},
{
name: "a TEMPLATED composition hoisting a head stylesheet link",
// The compiler used to hoist a <link> only for a non-templated
// composition, so a templated one's webfont survived preview (the mount
// path always hoisted) and vanished from the render.
files: cardHost(`<!doctype html><html><head>
<link rel="preconnect" href="https://fonts.example.com" />
</head><body>
<template id="card-template">
<style>${FONT_FACE}
.parity-card { --parity-contract: 6; font-family: ParityBody, sans-serif; }</style>
<article id="card-root" data-composition-id="card" data-width="800" data-height="600">
<h2 class="parity-card">Card</h2>
</article>
</template>
</body></html>`),
},
{
name: "an anonymous host scoping to the id its content declares",
// A host naming no composition id. The mount path used to drop the
// content in whole and unscoped, so this composition's CSS landed on the
// host document at large; the compiler has always fallen back to the
// first declared root and scoped to it.
files: anonymousCardHost(`<template id="card-template">
<style>${FONT_FACE}
.parity-card { --parity-contract: 7; font-family: ParityBody, sans-serif; }</style>
<article id="card-root" data-composition-id="card" data-width="800" data-height="600">
<h2 class="parity-card">Card</h2>
</article>
</template>`),
},
{
name: "a full-document composition hoisting a head stylesheet link",
files: cardHost(`<!doctype html><html><head>
<link rel="preconnect" href="https://fonts.example.com" />
<style>${FONT_FACE}
.parity-card { --parity-contract: 5; font-family: ParityBody, sans-serif; }</style>
</head><body>
<article id="card-root" data-composition-id="card" data-width="800" data-height="600">
<h2 class="parity-card">Card</h2>
</article>
</body></html>`),
},
];
/** True when a sub-composition authors a `<style>`/`<script>` outside its root. */
function hasRootSiblingAssets(subCompositionHtml: string): boolean {
const doc = new DOMParser().parseFromString(subCompositionHtml, "text/html");
const template = doc.querySelector("template");
const scope: ParentNode = template ? template.content : doc.body;
const root = scope.querySelector("[data-composition-id]");
const assets = Array.from(scope.querySelectorAll("style, script"));
return assets.length > 0 && assets.some((asset) => !root?.contains(asset));
}
const subCompositions = (files: Record<string, string>) =>
Object.entries(files)
.filter(([path]) => path !== "index.html")
.map(([, content]) => content);
/**
* The runtime's assembly is not a compiler, so two contract fields are outside
* what this arm gates, and are asserted rather than compared:
*
* - `runtimeBootstrap` / `variableBootstrap` — the runtime IIFE and the variable
* bootstrap script are injected by the player and the producer AROUND a mount,
* never by `loadExternalCompositions`. Comparing them would compare harnesses.
*
* Nothing else is excluded. The templated-head-`<link>` divergence this file
* used to carve out is closed and gated by a fixture above; so is the
* anonymous-host one. Two divergences remain ungated HERE rather than
* unfixed — an inline `<head>` script and the split between the CSS scope id
* and the script scope id both live in script bodies, and this contract
* carries no script-body field. Their gates are the unit suites in
* `packages/core/src/{compiler,runtime}`.
*/
function assembledContract(contract: ParityContract) {
const { runtimeBootstrap: _runtime, variableBootstrap: _variables, ...assembled } = contract;
return assembled;
}
describe("mount/compile assembly parity", () => {
it("keeps a fixture set that still covers the shape the mount path used to drop", () => {
expect(MOUNT_PARITY_FIXTURES.length).toBeGreaterThan(0);
const siblingShaped = MOUNT_PARITY_FIXTURES.filter((fixture) =>
subCompositions(fixture.files).some(hasRootSiblingAssets),
);
expect(siblingShaped.map((fixture) => fixture.name)).not.toHaveLength(0);
});
it.each(MOUNT_PARITY_FIXTURES)(
"assembles $name identically on all three paths",
async ({ files }) => {
const result = await contracts(files);
expect(result.render).toEqual(result.preview);
expect(assembledContract(result.mount)).toEqual(assembledContract(result.preview));
expect(result.mount.runtimeBootstrap).toBe(false);
expect(result.mount.variableBootstrap).toBe(false);
},
);
});
@@ -6,6 +6,7 @@ import { join } from "node:path";
import { parseHTML } from "linkedom";
import { interpolateVolumeGain } from "@hyperframes/core/media-volume-envelope";
import { defaultLogger } from "../logger.js";
import { NotMediaPayloadError } from "@hyperframes/engine";
import {
collectExternalAssets,
compileForRender,
@@ -2364,3 +2365,94 @@ describe("sub-composition variable injection (render path, #2064)", () => {
expect(compiled.html).not.toMatch(/window\.__hfVariablesByComp\s*=\s*Object\.assign/);
});
});
// ── Markup payload sniff (STUDIO-5433) ─────────────────────────────────────
//
// Producer's `resolveMediaDuration` is a two-step pipeline (download → probe)
// that runs on every media element without an authored duration. Before this
// defense, an authoring bug that handed a `.html` payload through as a video
// src produced an opaque `[mov,mp4,m4a,3gp,3g2,mj2 @ ...] moov atom not found`
// from ffprobe — the `mov,mp4,…` prefix is ffprobe's demuxer probe order, NOT
// the file's true format, so every alert routed as a codec/ffmpeg bug. The
// byte-level sniff itself is unit-tested in
// `engine/src/utils/notMediaPayload.test.ts`; what is pinned here is the
// compiler's handling of the verdict, which differs by element type.
describe("compileForRender non-media payload sniff (STUDIO-5433)", () => {
function writeProject(mediaTag: string): string {
const projectDir = mkdtempSync(join(tmpdir(), "hf-payload-sniff-e2e-"));
mkdirSync(join(projectDir, "assets"));
writeFileSync(
join(projectDir, "assets", "nested.html"),
"<!DOCTYPE html>\n<html><head><title>streamed-preview</title></head><body></body></html>",
);
writeFileSync(
join(projectDir, "index.html"),
`<!DOCTYPE html>
<html>
<body>
<div data-composition-id="root" data-width="640" data-height="360" data-start="0" data-duration="4">
${mediaTag}
</div>
<script>
window.__timelines = window.__timelines || {};
window.__timelines["root"] = { duration: () => 4 };
</script>
</body>
</html>`,
);
return projectDir;
}
it("aborts with NotMediaPayloadError before ffprobe when a <video> src is an HTML payload", async () => {
// Mimics STUDIO-5433: an a-roll element whose src points at a legitimate
// 6.5 KB `<!DOCTYPE html>` preview page instead of the rendered MP4.
const projectDir = writeProject(
'<video id="v1" src="assets/nested.html" data-start="0" muted></video>',
);
let caught: unknown;
try {
await compileForRender(projectDir, join(projectDir, "index.html"), projectDir);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(NotMediaPayloadError);
const err = caught as NotMediaPayloadError;
// Routing metadata, not just a readable string: these are what the server's
// SAFE_RENDER_ERROR_CODES allowlist and the distributed retry sets key off.
expect(err.code).toBe("NOT_MEDIA_PAYLOAD");
expect(err.owner).toBe("user");
expect(err.retryable).toBe(false);
// Correlation is the hashed element id — the authored src never reaches a
// message that producer forwards to API clients.
expect(err.elementFingerprints).toHaveLength(1);
expect(err.message).not.toContain("assets/nested.html");
// Also the ordering pin: this fixture is an input ffprobe rejects, so if
// the sniff ran after the probe the rejection would be ffprobe's untyped
// error and this assertion would fail.
});
it("drops an <audio> document payload to duration 0 and warns instead of failing the render", async () => {
// The audio/video split is the compiler's contract: an unprobeable audio
// src is excluded from the render, and only video surfaces its probe
// failure. A hard abort here would take down renders that used to succeed
// without the offending audio.
const projectDir = writeProject(
'<audio id="a1" src="assets/nested.html" data-start="0"></audio>',
);
const warnings: string[] = [];
const log = { ...defaultLogger, warn: (message: string) => warnings.push(message) };
const compiled = await compileForRender(
projectDir,
join(projectDir, "index.html"),
projectDir,
{ log },
);
expect(compiled.html).not.toContain('id="a1" src="assets/nested.html" data-end');
expect(warnings.join("\n")).toContain("text document");
expect(warnings.join("\n")).toContain("a1");
});
});
+32 -4
View File
@@ -51,6 +51,8 @@ import {
type AudioVolumeKeyframe,
type MediaProbeProfile,
analyzeKeyframeIntervals,
assertMediaPayload,
NotMediaPayloadError,
probeMediaProfile,
} from "@hyperframes/engine";
import {
@@ -423,6 +425,7 @@ async function resolveMediaDuration(
downloadDir: string,
tagName: string,
elementIdentity: string,
log?: ProducerLogger,
): Promise<{ duration: number; resolvedPath: string }> {
let filePath = src;
@@ -448,12 +451,30 @@ async function resolveMediaDuration(
return withMediaProbeSlot(async () => {
let profile: MediaProbeProfile;
try {
// Payload sniff (STUDIO-5433): if an authoring bug hands us a text
// payload (e.g. an unresolved nested-composition preview URL), fail with
// a typed NotMediaPayloadError instead of letting ffprobe emit an opaque
// `[mov,mp4,...] moov atom not found` that routes as a codec bug.
// Deliberately inside this try: the audio/video split below is the
// contract, so a bad audio src must still degrade to duration 0 rather
// than take down the whole render.
await assertMediaPayload(filePath, elementIdentity);
profile = await probeMediaProfile(filePath);
} catch (error) {
// Preserve the historical split: invalid video sources surface their
// probe failure, while invalid/unreadable audio sources resolve to zero
// duration and are excluded by the compiler.
if (tagName !== "video") return { duration: 0, resolvedPath: filePath };
if (tagName !== "video") {
if (error instanceof NotMediaPayloadError) {
// Dropping it silently is what let STUDIO-5433 resurface downstream
// as `prepare/ffmpeg_failed` with owner "system".
log?.warn(
`[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media ` +
"file — the element is dropped from the render. Point it at a rendered media file.",
);
}
return { duration: 0, resolvedPath: filePath };
}
throw error;
}
assertAssetMediaTypeProfile(tagName === "video" ? "video" : "audio", profile, elementIdentity);
@@ -501,9 +522,15 @@ async function compileHtmlFile(
// Phase 1: Resolve missing durations (parallel ffprobe)
const resolvedResults = await Promise.all(
mediaUnresolved.map((el) =>
resolveMediaDuration(el.src!, el.mediaStart, baseDir, downloadDir, el.tagName, el.id).then(
({ duration }) => ({ id: el.id, duration }),
),
resolveMediaDuration(
el.src!,
el.mediaStart,
baseDir,
downloadDir,
el.tagName,
el.id,
log,
).then(({ duration }) => ({ id: el.id, duration })),
),
);
const resolutions: ResolvedDuration[] = resolvedResults.filter((r) => r.duration > 0);
@@ -525,6 +552,7 @@ async function compileHtmlFile(
downloadDir,
el.tagName,
el.id,
log,
);
return { id: el.id, tagName: el.tagName, duration: el.duration, maxDuration, src: el.src! };
}),
@@ -169,6 +169,26 @@ describe("parseFontFamilyValue", () => {
expect(parseFontFamilyValue(`'My Custom Font', serif`)).toEqual(["My Custom Font", "serif"]);
});
it("keeps a comma inside a quoted family name", () => {
expect(parseFontFamilyValue(`"Display, Condensed", serif`)).toEqual([
"Display, Condensed",
"serif",
]);
});
it("keeps a var() fallback in a single token", () => {
expect(parseFontFamilyValue(`var(--brand-font, inherit), sans-serif`)).toEqual([
"var(--brand-font, inherit)",
"sans-serif",
]);
});
it("keeps a nested var() fallback in a single token", () => {
expect(
parseFontFamilyValue(`var(--brand-font, var(--fallback-font, "Inter")), sans-serif`),
).toEqual([`var(--brand-font, var(--fallback-font, "Inter"))`, "sans-serif"]);
});
it("ignores empty entries (trailing commas)", () => {
expect(parseFontFamilyValue(`Inter,,sans-serif`)).toEqual(["Inter", "sans-serif"]);
});
@@ -36,6 +36,7 @@ import {
shouldRetryViaPinnedFallback,
countElementTags,
envInt,
isDeParallelRouterEnabled,
mergeWorkerInitObservability,
resolveCompositionElementCount,
resolveDeShortBand,
@@ -2266,6 +2267,27 @@ describe("resolveInversionRetryPlan (self-verify retry rollback)", () => {
});
});
describe("isDeParallelRouterEnabled (kill switch parsing)", () => {
it("defaults ON when unset or set-but-empty", () => {
expect(isDeParallelRouterEnabled({})).toBe(true);
expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "" })).toBe(true);
expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: " " })).toBe(true);
});
it("honours every conventional spelling of off — an opt-out must never fail OPEN", () => {
// A naive `!== "false"` would enable the router for all of these, handing
// 3-worker parallel DE to a user who explicitly asked for none.
for (const v of ["false", "FALSE", "False", "0", "off", "OFF", "no", "No", " false "]) {
expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: v })).toBe(false);
}
});
it("treats any other value as enabled", () => {
expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "true" })).toBe(true);
expect(isDeParallelRouterEnabled({ HF_DE_PARALLEL_ROUTER: "1" })).toBe(true);
});
});
describe("shouldPreferParallelDrawElement (DE parallel router)", () => {
const eligible = {
workerCount: 5,
@@ -1564,11 +1564,12 @@ export function resolveInversionRetryPlan(args: {
* clear 1.25x (3,600f, 39% static/dedup-heavy) still didn't LOSE to single-
* worker (1.16x) — dedup already skips the capture work parallelism would
* split, so there's mechanically less headroom, not a regression. No comp
* anywhere showed par3 < single. Default-off (HF_DE_PARALLEL_ROUTER): this
* promotes the opt-in mechanism from #2056 into the auto-routing decision,
* but the decision itself stays gated behind its own flag pending the
* telemetry soak (revert rate, de_verify_min_db distribution) on real wild
* traffic — there is currently none, since nothing routes here by default.
* anywhere showed par3 < single. Default ON since 2026-07-27
* (HF_DE_PARALLEL_ROUTER=false is the kill switch): the default-off soak
* proved the safety half (zero shipped damage, 100% revert recovery), so the
* flip trades an accepted ~2.3% revert rate for parallelizing the ≥700f
* band. This promotes the opt-in mechanism from #2056 into the auto-routing
* decision.
* Takes priority over the single-worker inversion when both would fire.
* Re-calibrated 2026-07-27: a controlled crossover sweep (three content
* profiles including a genuinely init-expensive 24-sub-composition comp;
@@ -1578,6 +1579,29 @@ export function resolveInversionRetryPlan(args: {
* dropped below the inversion's threshold (700 vs 900): where both fire,
* parallel wins over the inversion's single-worker pick (+17–21% at 700f).
*/
/**
* Is the DE parallel router enabled for this process?
*
* Default ON since 2026-07-27; `HF_DE_PARALLEL_ROUTER` is the kill switch.
* Every conventional spelling of "off" disables it — a naive
* `!== "false"` would silently ignore `0`, `off`, `no`, `FALSE`, and an
* exported-but-empty var, i.e. an opt-out that FAILS OPEN and hands the user
* 3-worker parallel DE anyway (review finding). A set-but-empty value means
* "unset" here, matching how the sibling HF_DE_* numeric knobs treat it.
*
* The CLI's circuit breaker relies on this accepting an explicit "false":
* once an install trips the breaker it writes that value rather than
* unsetting the var, because under a default-ON flag unsetting means ON.
* Pure; exported for tests.
*/
export function isDeParallelRouterEnabled(
env: Readonly<Record<string, string | undefined>>,
): boolean {
const raw = env.HF_DE_PARALLEL_ROUTER?.trim().toLowerCase();
if (raw === undefined || raw === "") return true;
return !(raw === "false" || raw === "0" || raw === "off" || raw === "no");
}
export function shouldPreferParallelDrawElement(args: {
workerCount: number;
/** job.config.workers — a number means the user explicitly chose. */
@@ -1593,7 +1617,7 @@ export function shouldPreferParallelDrawElement(args: {
supersampling: boolean;
probeDeGated: boolean;
experimentalParallelDeOptIn: boolean;
/** HF_DE_PARALLEL_ROUTER === "true" — the router's own kill switch, default off. */
/** HF_DE_PARALLEL_ROUTER !== "false" — default ON since 2026-07-27; env var is the kill switch. */
routerEnabled: boolean;
/**
* Whether verified parallel DE STREAMING can actually run for this render
@@ -2732,7 +2756,17 @@ async function executeRenderPipeline(input: {
? Math.min(deSingleMinFrames, deShortBandMinFrames)
: deSingleMinFrames;
// DE parallel-router eligibility — see shouldPreferParallelDrawElement.
// Default-off (HF_DE_PARALLEL_ROUTER); HF_DE_PARALLEL_MIN_FRAMES default
// Default ON since 2026-07-27 (kill switch: HF_DE_PARALLEL_ROUTER=false).
// The soak that gated this flip answered the safety question: zero
// damaged frames shipped across the entire default-off window — every
// revert was the self-verify net catching a bad frame and recovering via
// screenshot. The residual metric (revert rate ~2.3% vs the 2% goal) is
// an efficiency cost (a revert forfeits the speedup, never correctness),
// accepted in exchange for parallelizing the ≥700-frame band (~80% of
// all DE capture wall-clock). Post-flip tripwire on dashboard 1807532:
// sustained revert >10% or any verify-missed damage rolls this back —
// one env default, decoupled from the floor change one release earlier.
// HF_DE_PARALLEL_MIN_FRAMES default
// 700, re-calibrated 2026-07-27 from the original safe-high 2000. A
// controlled frame-count sweep (fixed content-per-frame, three synthetic
// profiles × {350..3000f} × {single,par2,par3} × 3 reps, worker counts +
@@ -2744,7 +2778,7 @@ async function executeRenderPipeline(input: {
// duplicated init costs CPU, not wall-clock. Below ~700f the win thins
// toward ~+10% while still paying 3 hardware-GPU browsers, so the floor
// stays. Harness: plans/drawelement-fast-capture/de-crossover-bench.sh.
const deParallelRouterEnabled = process.env.HF_DE_PARALLEL_ROUTER === "true";
const deParallelRouterEnabled = isDeParallelRouterEnabled(process.env);
const deParallelMinFramesRaw = process.env.HF_DE_PARALLEL_MIN_FRAMES;
const deParallelMinFramesNum =
deParallelMinFramesRaw === undefined || deParallelMinFramesRaw.trim() === ""
@@ -35,7 +35,7 @@
top: 30%;
left: 50%;
transform: translateX(-50%);
font-family: var(--display-font), sans-serif;
font-family: var(--display-font, "Montserrat"), sans-serif;
font-size: 48px;
font-weight: 900;
color: #e94560;
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:4933d5dd2abc677fa661d5e94b673f26fed05b7921b252d0a65da0e17f51824f
size 7997
oid sha256:2c8fe979b1f7614e3d06a8621676000d490385e24e4e1621220d7fa6d7e7c40c
size 8405
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:9195c93140f142bfbded3a1f5758141f87bcb11eaa8ec8350a37eef7c0902fe4
size 9205
oid sha256:a72f7e1e9704355583d1ea1a0ff978b9a29c7de23ab5c81492aa05ae1034b419
size 9477
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:e8a5d321bcbf9edff83068102f14ff4ea599034d1a97a33b684c5c33f384fa73
size 9261
oid sha256:fbf2e34f4afaeca9d8892f6bf5b0253cbf57b0ce237a91b02cfdc4cfde3b9c7a
size 9493
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:3daa0e36f959ce465b04db4180733ed9c309bdc13851a3caedd0261d004401f9
size 9272
oid sha256:e2691b00b80a3568ca18c4326bb100601289ad318fea41f91f903db1032e7194
size 9546
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:bef89116d6825d572d9c655e8a01cb0e391087e1175d70ececc90ee6941b148f
size 9249
oid sha256:66930f2960c859b3fb076d063001be3d0f6a657accf4af03b594c2ca66302be1
size 9456
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:1100827ceda13433b600ea226331eb3f8a1e9f73517d73381e626302d5e3b675
size 9322
oid sha256:147b6397bdfe142493ecff31ec08182e28a83d5cdb928ef7608baaf78b0eed4e
size 9502
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:bcd7d85837277d51b52804bb0761c93ac49d2a5d0d1e11d1c411e1f4386d4f7b
size 9302
oid sha256:aefbcc88ecd307c30646088bb66b20812d3dba85a1c60cd8b6944f31c4f5b016
size 9535
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:fc9826a6adbbf40cca08779aa9c6e8564e1d39902eb4c052c517d0574324d699
size 9371
oid sha256:cc6e8972198cccc0dcaf6737b27bcae9cd867e560b37361fa200e0e9e54ac135
size 9575
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:6fa8146dcc47b6a78a5b55db9289693772aaa2c366ff7ee124b7053155af058c
size 9385
oid sha256:c9e071232d0b596f9e16c6267320cc55e7f7fff22afb3b7f9c7a7f7cd8046e38
size 9538
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:d0c8bf011435e3e229f615e081d2933fca5c8937505465a8481582ac46de94cb
size 9285
oid sha256:fda9cfa100daf93d10d9c3290802342fabceeaa1ab79c963dc447b0caa5e63aa
size 9512
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:3baf13eab4045857adc8aa75bf1cc4fe4fa829c50ef6c857eab0bd3c28a45293
size 9303
oid sha256:37af0b17c0767715c76edcfa5ee4f8e63bd3fc609fc86b70e7f6bc2bbecba144
size 9501
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:b71dfee4cd91267f4d6ea65a2d6c846dd5ac5689cfe8781a90ded5c10ca50afa
size 9236
oid sha256:c0088245a34bf610169f51cda6df2eb4da40638294083c1822283fda23d81bee
size 9446
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:737a38a778b722d280ec11986650c57e72466245687db964222bbe47a085aea5
size 9265
oid sha256:9ee9ab760d6b200b0df7e4a2a2a485a5fbd3cf0dff28970c1f3893cbc9036431
size 9515
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:b3bc25a8bcf17103040f6bec9642e09f155d3115397c6ba2b59dd5d60314bf92
size 9286
oid sha256:dbfcc3db6712ca8aea566b91db7646767f40fb745d010ea43e39d7b14ea245f5
size 9530
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:bf033c619debdcaa970ef0a32e67001ee3d2caee6df54d671f23003008ca7ef7
size 9204
oid sha256:fde35f1ffa2e8753597d44c215a1f4c969ddcb77a6dd34241a5d3dfd8a6a51fc
size 9494
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:4933d5dd2abc677fa661d5e94b673f26fed05b7921b252d0a65da0e17f51824f
size 7997
oid sha256:4ea5c9bc5b5d07f36eeeba5d7cc79224dd13f65950708cf49b6ac81864d9bf59
size 8434
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:9195c93140f142bfbded3a1f5758141f87bcb11eaa8ec8350a37eef7c0902fe4
size 9205
oid sha256:7ea22f1adabdbc1ad71992bd4801a767208593393815712468d81afc30e20b37
size 9460
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:e8a5d321bcbf9edff83068102f14ff4ea599034d1a97a33b684c5c33f384fa73
size 9261
oid sha256:b12908fa220330116f9335ec4c9a934630841914ccf98e8d86f6df218dda9f1e
size 9507
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:3daa0e36f959ce465b04db4180733ed9c309bdc13851a3caedd0261d004401f9
size 9272
oid sha256:daf29a1d905c07e29c5c8bcefc00dfa2493e9e2f4bd835745ee6f36008677546
size 9542
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:bef89116d6825d572d9c655e8a01cb0e391087e1175d70ececc90ee6941b148f
size 9249
oid sha256:a8fdc3d1d6075eda922ae6ce0d27616e166267bc7c87afa28cc95f7657153c2c
size 9450
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:1100827ceda13433b600ea226331eb3f8a1e9f73517d73381e626302d5e3b675
size 9322
oid sha256:77fa7bf9335ed8cc4612de77bd3453a094a945251f937b556f87e505eb5ee1fa
size 9485
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:3de351c6f5e536ea58347cddb373b7521eb146558ed058a2609cd3e59e46bd62
size 9301
oid sha256:dcc4fe096faa4845d8c813c700446c59a4bacda1fe5b4870b54b2b92b677fa9b
size 9554
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:fc9826a6adbbf40cca08779aa9c6e8564e1d39902eb4c052c517d0574324d699
size 9371
oid sha256:cb4ed6eac97fb10db7fc0e1ed061474b3a0628e456eaab094e6baa957cbeb635
size 9552
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:90b58af819c992b79c43b9681028f5f9f2467253c36a16dbb927e77fbad27bc1
size 9389
oid sha256:0f2ce347d9c4a177d4063a92f5c815337c89d78b1967d0036f05b82ffc8189dd
size 9548
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:49e4a510bfe9c2a983cdc93a9760ade16e8da6818ac75b21eff3eea17218f3f8
size 9285
oid sha256:5b0c2b3bc7e2259c06a8af025ee0263f7026758ecdc8882eafeb5c53931728eb
size 9522
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:3baf13eab4045857adc8aa75bf1cc4fe4fa829c50ef6c857eab0bd3c28a45293
size 9303
oid sha256:e3518e127b1ec1f47f31fa37a5dd4235abcfde5d576d70d451a37d00ef4df7fb
size 9492
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:b71dfee4cd91267f4d6ea65a2d6c846dd5ac5689cfe8781a90ded5c10ca50afa
size 9236
oid sha256:e6e698f65937196a0fa50d736f4bcf6f398fbd627e378963675caf6abaae0a8f
size 9455
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:737a38a778b722d280ec11986650c57e72466245687db964222bbe47a085aea5
size 9265
oid sha256:03cce5b1878abad51e320804bab43dadc981e8c2cc3ceec8e8019d7e1ccef46d
size 9509
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:40e724c558e8e1597943ec672224cd2e18ca8a5100fad3f153bca8bca0df4969
size 11311
oid sha256:339a6a01940bfec95ddb120777c6942fdbd4a71103b064e57a7e7ef1c5236ab1
size 11488
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:94e3e8ce6cbffa74557fcc76ecc561471d3d49ecdb3591a0fe01b8e14013fe5a
size 11391
oid sha256:c38baf7191241ee9b8e7dfa3a50ab4b3467161218b02da0fae88b8c4a3d32dce
size 11619
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:48602bb09bff3d79210729565bdb524488149574cae55eeda53671eae88e01dc
size 10344
oid sha256:360b92cfd177bfb3020cd56f8eadbc590f10cbe22932730fb0432240d4e60d30
size 10627
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:389ae5df4c313fbe65043e3edc8e1d1a64d58a195c006c60c089164700cb12de
size 11471
oid sha256:a013c2c0f7e73c37fc81f56b4a0f1b9c8bb6713e72130139522f17155ae0a253
size 11723
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:d9552049a6b5c263b350d98d86a3f1e9ba474a0cba8af2d8899903c3a2b401d0
size 11467
oid sha256:4e0bc4a96760ce265b1a2bb3bd999b53eb2f4948fb793f249c3fa5ddbcbf1c7c
size 11737
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:7b00cd02037d594c4576f0413d61d6a88de62cca131de314d002dbf33c6292aa
size 10046
oid sha256:197a78d36de126e3a400c59ee1ddd577b8d3c6ebcc4a98ea3a17406666507bdf
size 10381
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:46d60ddd91ec1d7185aaeb6686d6add1aed7d81aae53612ac2edbf6a7d93c345
size 10031
oid sha256:65c7999d6d9450d3065e00588d24871fd1d51db6deac8f18ab361192a9c50600
size 10290
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:c5e13cd286a3233563cdbeb4ba5b1b2bab04b4cb29bac5c93e5702744d11c088
size 10110
oid sha256:51eb31ff58a2ffdf17f0def28262858af83ed54436a9a805f0f219c03f52f414
size 10324
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:633d22d5463e34c3fb2c6335b249467cb9807a04980d05eb0bbca6d82f203b76
size 10093
oid sha256:649bf8c28bb205d9793cdac00253e864078ea20874e40a08e97f4c6c9a9109c7
size 10357
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:f0f2982c19feb426c3d813a1e552d8d89f10b244744cb2664c31404d918e5471
size 10156
oid sha256:4c2c84a261b9ae3960a557afdeaf304784797bc673d6a13d6500f11293cecb4e
size 10383
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:6019e56d9876d24e67ee8f3458f9d2073e8af0be9852876ea3e377c79b24fae6
size 10164
oid sha256:38df8ee3d7cc5ad72d6fa459371020ac7805aead0ead3cc58a7bbf78f14a3083
size 10341
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:69839d2376bb82be36e1ebb4b3250c2b8d8e554285008c1ae30b6bc1d52f1752
size 10070
oid sha256:f84949c05a27072c7be007fc42efdb27578b2f8b6b1f8184f67beb962bd4c2c3
size 10376
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:9f1d1e98f9d5a24ce456a3a13c4b47d83f602a3c3e1a61c72726335d62e14657
size 10093
oid sha256:a79d6f344e31dd880c330873b162a9728d863f676b32e1d3a55e4b72baec3776
size 10309
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:bc31fc2b24e5a97e8ffbf87e8428354adb35eec131693ddd171f8485017477c4
size 10020
oid sha256:26b2d85f0596c1c25f92e5b472a3174897478c13971c83fa40ddbc464451b76a
size 10259
@@ -1,3 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:48a14b5afb08bd5770f8b462df9ee5077837ca0c0235b74c94bc158e97e0519c
size 10040
oid sha256:802f826ab596ddbc6577a065e72cb13b3893161cde9b0442fc920de9011d8f40
size 10343

Some files were not shown because too many files have changed in this diff Show More