mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
Merge remote-tracking branch 'origin/main' into feat-studio-inline-rich-text
This commit is contained in:
@@ -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,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",
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,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",
|
||||
|
||||
@@ -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,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": {
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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
@@ -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(
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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,6 +1,6 @@
|
||||
{
|
||||
"name": "@hyperframes/core",
|
||||
"version": "0.7.99",
|
||||
"version": "0.7.101",
|
||||
"description": "",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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";');
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -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,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",
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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,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",
|
||||
|
||||
@@ -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,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,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,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,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,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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
Reference in New Issue
Block a user