diff --git a/packages/core/src/runtime/entry.ts b/packages/core/src/runtime/entry.ts
index b5e2b387f7..3e08a28736 100644
--- a/packages/core/src/runtime/entry.ts
+++ b/packages/core/src/runtime/entry.ts
@@ -11,7 +11,7 @@ import { hideTimedClipsUntilFirstPass, keepInlineHideRulesForOlderShaders } from
import { fitTextFontSize } from "../text/fitTextFontSize";
import { pretext } from "../text/pretext";
import { assetUrl } from "./assetUrl";
-import { getVariables } from "./getVariables";
+import { getDeclaredVariableSources, getVariables } from "./getVariables";
import { clearRuntimeData, registerRuntimeDataHandler, setRuntimeData } from "./runtimeData";
import { runScriptsAfterFonts } from "./afterFonts";
import { AFTER_FONTS_SCRIPTS } from "../compiler/scriptRuns";
@@ -27,6 +27,7 @@ type HyperframeWindow = Window & {
assetUrl: typeof assetUrl;
fitTextFontSize: typeof fitTextFontSize;
getVariables: typeof getVariables;
+ getDeclaredVariableSources: typeof getDeclaredVariableSources;
pretext: typeof pretext;
registerRuntimeDataHandler: typeof registerRuntimeDataHandler;
setRuntimeData: typeof setRuntimeData;
@@ -60,6 +61,7 @@ deferMediaUntilDue();
assetUrl,
fitTextFontSize,
getVariables,
+ getDeclaredVariableSources,
pretext,
registerRuntimeDataHandler,
setRuntimeData,
diff --git a/packages/core/src/runtime/getVariables.test.ts b/packages/core/src/runtime/getVariables.test.ts
index 371ea2e6af..c7205bb60e 100644
--- a/packages/core/src/runtime/getVariables.test.ts
+++ b/packages/core/src/runtime/getVariables.test.ts
@@ -2,7 +2,12 @@
* @vitest-environment jsdom
*/
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { getVariables, readDeclaredDefaults, resetUnknownEnumWarnings } from "./getVariables";
+import {
+ getDeclaredVariableSources,
+ getVariables,
+ readDeclaredDefaults,
+ resetUnknownEnumWarnings,
+} from "./getVariables";
const VARIABLES_ATTR = "data-composition-variables";
@@ -451,3 +456,35 @@ describe("css variable injection (figma brand-token chain)", () => {
expect(getVariables()["figma:brand"]).toBe("#445566");
});
});
+
+describe("getDeclaredVariableSources", () => {
+ afterEach(() => {
+ setDeclared(null);
+ document.body.innerHTML = "";
+ (window as Window & { __hfVariablesByComp?: unknown }).__hfVariablesByComp = undefined;
+ });
+
+ it("lists first, then every other declarer in document order", () => {
+ setDeclared("[1]");
+ document.body.innerHTML = `
`;
+ expect(getDeclaredVariableSources()).toEqual(["[1]", "[2]", "[3]"]);
+ });
+
+ it("is empty when nothing declares variables", () => {
+ expect(getDeclaredVariableSources()).toEqual([]);
+ });
+
+ it("leaves out a sub-composition's declaration, which has its own scope", () => {
+ setDeclared("[1]");
+ document.body.innerHTML = `
`;
+ (window as Window & { __hfVariablesByComp?: unknown }).__hfVariablesByComp = { sub: {} };
+ expect(getDeclaredVariableSources()).toEqual(["[1]"]);
+ });
+
+ it("is the scope getVariables merges, so a later declarer's default wins", () => {
+ setDeclared(JSON.stringify([{ id: "a", type: "string", label: "A", default: "html" }]));
+ document.body.innerHTML = ``;
+ expect(getVariables()).toEqual({ a: "div" });
+ expect(getDeclaredVariableSources()).toHaveLength(2);
+ });
+});
diff --git a/packages/core/src/runtime/getVariables.ts b/packages/core/src/runtime/getVariables.ts
index 1fe60ab6cc..d0bdd4b966 100644
--- a/packages/core/src/runtime/getVariables.ts
+++ b/packages/core/src/runtime/getVariables.ts
@@ -27,15 +27,7 @@ export function getVariables<
>(): Partial {
if (typeof document === "undefined") return {} as Partial;
- // first, then any element carrying the attribute (later declarers win), then render-time
- // overrides. A sub-composition's declaration is its own scope's, read from its scoped table.
- const declarers = new Set();
- if (document.documentElement?.hasAttribute("data-composition-variables")) {
- declarers.add(document.documentElement);
- }
- for (const el of Array.from(document.querySelectorAll("[data-composition-variables]"))) {
- if (!scopedVariablesFor(el)) declarers.add(el);
- }
+ const declarers = topLevelDeclarers();
const declaredDefaults: Record = {};
for (const el of declarers) {
Object.assign(declaredDefaults, readDeclaredDefaults(el));
@@ -47,6 +39,30 @@ export function getVariables<
return merged as Partial;
}
+/**
+ * Top-level declarers: `` first, then others outside a sub-composition's scope; a later one wins.
+ * `getVariables` merges these, and `getDeclaredVariableSources` hands the same elements to a strict render.
+ */
+function topLevelDeclarers(): Set {
+ const declarers = new Set();
+ if (document.documentElement?.hasAttribute("data-composition-variables")) {
+ declarers.add(document.documentElement);
+ }
+ for (const el of Array.from(document.querySelectorAll("[data-composition-variables]"))) {
+ if (!scopedVariablesFor(el)) declarers.add(el);
+ }
+ return declarers;
+}
+
+/** The raw `data-composition-variables` text of each top-level declarer, in precedence order (later wins). */
+export function getDeclaredVariableSources(): string[] {
+ if (typeof document === "undefined") return [];
+ return Array.from(
+ topLevelDeclarers(),
+ (el) => el.getAttribute("data-composition-variables") ?? "",
+ );
+}
+
/**
* An enum variable given a value outside its declared `options` is coerced to
* the composition's default by the composition's own guard. That fallback is
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 349e119697..3d7f73ba6a 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -557,3 +557,8 @@ export {
pipeLaunchClosedOnMac,
sandboxDeniedRemediation,
} from "./services/sandboxLaunch.js";
+export {
+ VariablesInvalidError,
+ type VariablesIssue,
+ type VariablesInvalidMetadata,
+} from "./services/variablesCheck.js";
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index f1539cf1e9..9029cd3f14 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -130,6 +130,7 @@ import {
} from "./chromeMemorySampler.js";
import { sampleProcessRss } from "../utils/processRss.js";
import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
+import { assertVariablesMatchPage } from "./variablesCheck.js";
export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
@@ -234,6 +235,8 @@ export interface CaptureSession {
scriptLoadCauses?: ScriptLoadCause[];
/** Uncaught page errors; a timed-out timeline wait with any of these becomes a script failure. */
pageErrors: string[];
+ /** True once this session honoured `options.strictVariables`: the check ran and passed. */
+ strictVariablesChecked?: boolean;
/** The first VFX chain error; its frames would lack the effect, so it stops the render. */
vfxFailure?: string;
/** Outcome of the sub-composition timeline wait: ready | timeout | script_failure. */
@@ -3078,6 +3081,13 @@ export async function describeThrowSite(
return ` [thrown at: ${where}]`;
}
+/** When the session asks for strict variables, refuse a render whose variables the page does not declare. */
+async function checkStrictVariables(session: CaptureSession): Promise {
+ if (!session.options.strictVariables) return;
+ await assertVariablesMatchPage(session.page, session.options.variables);
+ session.strictVariablesChecked = true;
+}
+
export async function initializeSession(session: CaptureSession): Promise {
const { page, serverUrl } = session;
@@ -3220,6 +3230,7 @@ export async function initializeSession(session: CaptureSession): Promise
session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
await pollHfReady(page, pageReadyTimeout);
logInitPhase("pollHfReady complete");
+ await checkStrictVariables(session);
await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
@@ -3362,6 +3373,7 @@ export async function initializeSession(session: CaptureSession): Promise
session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
await pollHfReady(page, pageReadyTimeout);
logInitPhase("pollHfReady complete");
+ await checkStrictVariables(session);
await waitForSubCompositionTimelines(session, page, pageReadyTimeout);
logInitPhase(`pollSubCompositionTimelines complete (${session.subTimelineWaitOutcome})`);
diff --git a/packages/engine/src/services/variablesCheck.test.ts b/packages/engine/src/services/variablesCheck.test.ts
new file mode 100644
index 0000000000..f42a8b6c73
--- /dev/null
+++ b/packages/engine/src/services/variablesCheck.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import type { Page } from "puppeteer-core";
+import {
+ assertVariablesMatchPage,
+ VariablesInvalidError,
+ variablesIssues,
+ type VariablesIssue,
+} from "./variablesCheck.js";
+
+const declare = (...decls: object[]): string => JSON.stringify(decls);
+const title = { id: "title", type: "string", label: "Title", default: "x" };
+const speed = { id: "speed", type: "number", label: "Speed", default: 1 };
+const theme = {
+ id: "theme",
+ type: "enum",
+ label: "Theme",
+ default: "dark",
+ options: [
+ { value: "dark", label: "Dark" },
+ { value: "light", label: "Light" },
+ ],
+};
+
+describe("variablesIssues", () => {
+ it("has nothing to check when the render passes no variables", () => {
+ expect(variablesIssues({}, null)).toEqual([]);
+ });
+
+ it("accepts variables the page declares with matching types", () => {
+ expect(variablesIssues({ title: "Hi", speed: 2 }, [declare(title, speed)])).toEqual([]);
+ });
+
+ it("names a variable the page does not declare", () => {
+ expect(variablesIssues({ titel: "Hi" }, [declare(title)])).toEqual([
+ { kind: "undeclared", variableId: "titel" },
+ ]);
+ });
+
+ it("names the declared and the given type of a mismatch, never the value", () => {
+ const issues = variablesIssues({ speed: "fast and secret" }, [declare(speed)]);
+ expect(issues).toEqual([
+ { kind: "type-mismatch", variableId: "speed", expected: "number", actual: "string" },
+ ]);
+ expect(JSON.stringify(issues)).not.toContain("secret");
+ });
+
+ it("names an enum value outside its options without echoing the value", () => {
+ const issues = variablesIssues({ theme: "purple-secret" }, [declare(theme)]);
+ expect(issues).toEqual([{ kind: "enum-out-of-range", variableId: "theme" }]);
+ });
+
+ it("lets a later declarer win a duplicate id, as the runtime merges them", () => {
+ const first = declare({ ...speed, type: "string", default: "slow" });
+ expect(variablesIssues({ speed: 2 }, [first, declare(speed)])).toEqual([]);
+ expect(variablesIssues({ speed: 2 }, [declare(speed), first])).toHaveLength(1);
+ });
+
+ it("fails closed when the runtime offers no declarations to read", () => {
+ expect(variablesIssues({ title: "Hi" }, null)).toEqual([{ kind: "declarations-unreadable" }]);
+ });
+
+ it.each([["not json"], ['{"id":"title"}']])(
+ "does not call a variable undeclared when a declaration cannot be read (%s)",
+ (broken) => {
+ expect(variablesIssues({ title: "Hi" }, [broken])).toEqual([
+ { kind: "declarations-unreadable" },
+ ]);
+ },
+ );
+
+ it("does not call a variable undeclared when one entry of the list is malformed", () => {
+ const source = declare(speed, { id: "title" });
+ expect(variablesIssues({ title: "Hi" }, [source])).toEqual([
+ { kind: "declarations-unreadable" },
+ ]);
+ expect(variablesIssues({ speed: 2 }, [source])).toEqual([]);
+ });
+});
+
+describe("VariablesInvalidError", () => {
+ it("is a user-owned, non-retryable VARIABLES_INVALID the producer can transport", () => {
+ const error = new VariablesInvalidError([{ kind: "undeclared", variableId: "titel" }]);
+ expect(error.code).toBe("VARIABLES_INVALID");
+ expect(error.owner).toBe("user");
+ expect(error.retryable).toBe(false);
+ expect(error.message).toBe('Variable "titel" is not declared in data-composition-variables.');
+ });
+
+ it("keeps ten issues and says how many there were", () => {
+ const undeclared = (n: number): VariablesIssue => ({ kind: "undeclared", variableId: `v${n}` });
+ const error = new VariablesInvalidError([
+ undeclared(0),
+ ...Array.from({ length: 24 }, (_, i) => undeclared(i + 1)),
+ ]);
+ expect(error.publicMetadata.issues).toHaveLength(10);
+ expect(error.publicMetadata.total).toBe(25);
+ });
+
+ it("cuts a long name and strips control characters before it is carried anywhere", () => {
+ const nameOf = (overrides: Record): string | undefined => {
+ const [issue] = variablesIssues(overrides, [declare(title)]);
+ return issue && "variableId" in issue ? issue.variableId : undefined;
+ };
+ const long = nameOf({ [`${"a".repeat(200)}\n\u0000b`]: 1 });
+ expect(long).toHaveLength(64);
+ expect([...(long ?? "")].some((ch) => ch.charCodeAt(0) < 32)).toBe(false);
+ expect(nameOf({ "a\nb": 1 })).toBe("a?b");
+ });
+});
+
+function pageReturning(value: unknown): Page {
+ return { evaluate: async () => value } as unknown as Page;
+}
+
+describe("assertVariablesMatchPage", () => {
+ it("passes without reading the page when there are no variables", async () => {
+ const page = {
+ evaluate: async () => {
+ throw new Error("must not be read");
+ },
+ } as unknown as Page;
+ await expect(assertVariablesMatchPage(page, undefined)).resolves.toBeUndefined();
+ await expect(assertVariablesMatchPage(page, {})).resolves.toBeUndefined();
+ });
+
+ it("passes when the page declares the variables", async () => {
+ await expect(
+ assertVariablesMatchPage(pageReturning([declare(title)]), { title: "Hi" }),
+ ).resolves.toBeUndefined();
+ });
+
+ it("refuses with VARIABLES_INVALID naming the variable", async () => {
+ await expect(
+ assertVariablesMatchPage(pageReturning([declare(title)]), { titel: "Hi" }),
+ ).rejects.toMatchObject({
+ code: "VARIABLES_INVALID",
+ message: expect.stringContaining("titel"),
+ });
+ });
+
+ it("refuses when the page's runtime cannot list its declarations", async () => {
+ await expect(
+ assertVariablesMatchPage(pageReturning(null), { title: "Hi" }),
+ ).rejects.toMatchObject({
+ code: "VARIABLES_INVALID",
+ publicMetadata: { issues: [{ kind: "declarations-unreadable" }] },
+ });
+ });
+});
diff --git a/packages/engine/src/services/variablesCheck.ts b/packages/engine/src/services/variablesCheck.ts
new file mode 100644
index 0000000000..2d2adff9cf
--- /dev/null
+++ b/packages/engine/src/services/variablesCheck.ts
@@ -0,0 +1,108 @@
+import type { Page } from "puppeteer-core";
+import { readCompositionVariables } from "@hyperframes/parsers/composition";
+import { validateVariables, type VariableValidationIssue } from "@hyperframes/core";
+
+const MAX_ISSUES = 10;
+const MAX_ID_CHARS = 64;
+
+/** One reason a render's variables were refused. Never carries a value the caller supplied. */
+export type VariablesIssue =
+ | { kind: "undeclared"; variableId: string }
+ | { kind: "type-mismatch"; variableId: string; expected: string; actual: string }
+ | { kind: "enum-out-of-range"; variableId: string }
+ | { kind: "declarations-unreadable" };
+
+export interface VariablesInvalidMetadata {
+ issues: VariablesIssue[];
+ /** How many issues there were before the list was cut to its bound. */
+ total: number;
+}
+
+/** The render's variables do not match what the page declares, or the declarations could not be read. */
+export class VariablesInvalidError extends Error {
+ readonly code = "VARIABLES_INVALID" as const;
+ // The producer server reads these off the error for the wire envelope.
+ readonly owner = "user" as const;
+ readonly retryable = false as const;
+ readonly publicMetadata: VariablesInvalidMetadata;
+
+ constructor(issues: readonly [VariablesIssue, ...VariablesIssue[]]) {
+ const shown = issues.slice(0, MAX_ISSUES);
+ super(describeIssue(issues[0]));
+ this.name = "VariablesInvalidError";
+ this.publicMetadata = { issues: shown, total: issues.length };
+ }
+}
+
+function describeIssue(issue: VariablesIssue): string {
+ switch (issue.kind) {
+ case "undeclared":
+ return `Variable "${issue.variableId}" is not declared in data-composition-variables.`;
+ case "type-mismatch":
+ return `Variable "${issue.variableId}" expected ${issue.expected}, got ${issue.actual}.`;
+ case "enum-out-of-range":
+ return `Variable "${issue.variableId}" is not one of its declared options.`;
+ case "declarations-unreadable":
+ return "The page's data-composition-variables could not be read, so the variables cannot be checked.";
+ default:
+ return issue satisfies never;
+ }
+}
+
+/** A name the caller chose, cut and stripped of control characters before it is echoed anywhere. */
+function boundedId(id: string): string {
+ return Array.from(id.slice(0, MAX_ID_CHARS), (ch) => {
+ const code = ch.charCodeAt(0);
+ return code < 32 || code === 127 ? "?" : ch;
+ }).join("");
+}
+
+function toIssue(issue: VariableValidationIssue): VariablesIssue {
+ const variableId = boundedId(issue.variableId);
+ switch (issue.kind) {
+ case "undeclared":
+ return { kind: "undeclared", variableId };
+ case "type-mismatch":
+ return { kind: "type-mismatch", variableId, expected: issue.expected, actual: issue.actual };
+ case "enum-out-of-range":
+ return { kind: "enum-out-of-range", variableId };
+ }
+}
+
+/**
+ * Issues between `overrides` and the page's declarations (`getDeclaredVariableSources`). Declarations that cannot
+ * all be read never yield "undeclared". Empty overrides need no check.
+ */
+export function variablesIssues(
+ overrides: Record,
+ sources: readonly string[] | null,
+): VariablesIssue[] {
+ if (Object.keys(overrides).length === 0) return [];
+ if (sources === null) return [{ kind: "declarations-unreadable" }];
+ const read = sources.map(readCompositionVariables);
+ const byId = new Map(read.flatMap((r) => r.declarations).map((decl) => [decl.id, decl]));
+ const issues = validateVariables(overrides, [...byId.values()]).map(toIssue);
+ if (read.every((r) => r.complete)) return issues;
+ return issues.map((issue) =>
+ issue.kind === "undeclared" ? { kind: "declarations-unreadable" } : issue,
+ );
+}
+
+/** Read the page's declaration sources through its runtime; null when the runtime does not offer them. */
+async function readDeclaredVariableSources(page: Page): Promise {
+ const sources: unknown = await page.evaluate(
+ `window.__hyperframes?.getDeclaredVariableSources?.() ?? null`,
+ );
+ return Array.isArray(sources) && sources.every((s) => typeof s === "string") ? sources : null;
+}
+
+/** Throws `VariablesInvalidError` when the render's variables do not match the page; run once the page is ready. */
+export async function assertVariablesMatchPage(
+ page: Page,
+ overrides: Record | undefined,
+): Promise {
+ const values = overrides ?? {};
+ if (Object.keys(values).length === 0) return;
+ const [first, ...rest] = variablesIssues(values, await readDeclaredVariableSources(page));
+ if (first) throw new VariablesInvalidError([first, ...rest]);
+}
diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts
index b7a95e2148..ceb578df3f 100644
--- a/packages/engine/src/types.ts
+++ b/packages/engine/src/types.ts
@@ -253,6 +253,11 @@ export interface CaptureOptions {
* `--variables-file `. Must be a JSON-serializable plain object.
*/
variables?: Record;
+ /**
+ * Check `variables` against the page's `data-composition-variables` once it is ready, before any frame;
+ * a mismatch or unreadable declarations end the session with `VariablesInvalidError`. Off by default.
+ */
+ strictVariables?: boolean;
/**
* When `true`, the BeginFrame warmup loop driven during page navigation
* runs exactly `LOCKED_WARMUP_TICKS` (60) iterations regardless of how
diff --git a/packages/parsers/src/composition.ts b/packages/parsers/src/composition.ts
index 5d18b5b8fc..edd69f6a80 100644
--- a/packages/parsers/src/composition.ts
+++ b/packages/parsers/src/composition.ts
@@ -13,6 +13,8 @@ export { fontShorthandFamilies, parseFontShorthand } from "./fontShorthand.js";
export { decodeUrlPathVariants } from "./utils/urlPath.js";
export {
parseCompositionVariables,
+ readCompositionVariables,
+ type ReadCompositionVariables,
isCompositionVariable,
isFontValue,
isImageValue,
diff --git a/packages/parsers/src/compositionVariables.test.ts b/packages/parsers/src/compositionVariables.test.ts
index c347a44207..649c8cbfc3 100644
--- a/packages/parsers/src/compositionVariables.test.ts
+++ b/packages/parsers/src/compositionVariables.test.ts
@@ -1,5 +1,9 @@
import { describe, it, expect } from "vitest";
-import { isCompositionVariable, parseCompositionVariables } from "./compositionVariables.js";
+import {
+ isCompositionVariable,
+ parseCompositionVariables,
+ readCompositionVariables,
+} from "./compositionVariables.js";
import type { CompositionVariable } from "./types.js";
describe("font/image declaration defaults", () => {
@@ -51,3 +55,34 @@ describe("font/image declaration defaults", () => {
expect(parseCompositionVariables(element)).toEqual([]);
});
});
+
+describe("readCompositionVariables", () => {
+ const title = { id: "title", type: "string", label: "Title", default: "x" };
+
+ it("reads every declaration of a well-formed attribute as complete", () => {
+ expect(readCompositionVariables(JSON.stringify([title]))).toEqual({
+ declarations: [title],
+ complete: true,
+ });
+ });
+
+ it("treats an absent attribute as complete and empty", () => {
+ expect(readCompositionVariables(null)).toEqual({ declarations: [], complete: true });
+ expect(readCompositionVariables("")).toEqual({ declarations: [], complete: true });
+ });
+
+ it("keeps the valid entries and reports incomplete when one is malformed", () => {
+ expect(readCompositionVariables(JSON.stringify([title, { id: "broken" }]))).toEqual({
+ declarations: [title],
+ complete: false,
+ });
+ });
+
+ it("reports incomplete for invalid JSON and for a payload that is not an array", () => {
+ expect(readCompositionVariables("{")).toEqual({ declarations: [], complete: false });
+ expect(readCompositionVariables('{"id":"title"}')).toEqual({
+ declarations: [],
+ complete: false,
+ });
+ });
+});
diff --git a/packages/parsers/src/compositionVariables.ts b/packages/parsers/src/compositionVariables.ts
index fc863becf6..a314cabcaf 100644
--- a/packages/parsers/src/compositionVariables.ts
+++ b/packages/parsers/src/compositionVariables.ts
@@ -76,6 +76,24 @@ export function isCompositionVariable(v: unknown): v is CompositionVariable {
return true;
}
+export interface ReadCompositionVariables {
+ declarations: CompositionVariable[];
+ complete: boolean;
+}
+
+/** Valid declarations in the raw attribute text; `complete` is false when anything in it was dropped or unreadable. */
+export function readCompositionVariables(raw: string | null | undefined): ReadCompositionVariables {
+ if (!raw) return { declarations: [], complete: true };
+ try {
+ const parsed: unknown = JSON.parse(raw);
+ if (!Array.isArray(parsed)) return { declarations: [], complete: false };
+ const declarations = parsed.filter(isCompositionVariable);
+ return { declarations, complete: declarations.length === parsed.length };
+ } catch {
+ return { declarations: [], complete: false };
+ }
+}
+
/**
* Parse the typed variable declarations from an element's
* `data-composition-variables` attribute. Malformed entries (wrong shape,
@@ -83,20 +101,7 @@ export function isCompositionVariable(v: unknown): v is CompositionVariable {
* absent attribute, invalid JSON, or a non-array payload yields `[]`.
*/
export function parseCompositionVariables(htmlEl: Element): CompositionVariable[] {
- const variablesAttr = htmlEl.getAttribute("data-composition-variables");
- if (!variablesAttr) {
- return [];
- }
-
- try {
- const parsed = JSON.parse(variablesAttr);
- if (!Array.isArray(parsed)) {
- return [];
- }
- return parsed.filter(isCompositionVariable);
- } catch {
- return [];
- }
+ return readCompositionVariables(htmlEl.getAttribute("data-composition-variables")).declarations;
}
/**
diff --git a/packages/producer/scripts/integration-tests.json b/packages/producer/scripts/integration-tests.json
index 0585d0b1b3..b0d0c01722 100644
--- a/packages/producer/scripts/integration-tests.json
+++ b/packages/producer/scripts/integration-tests.json
@@ -29,6 +29,7 @@
"src/services/fileServer.listenError.test.ts",
"src/services/healthWorker.test.ts",
"src/services/scriptFailureAttribution.test.ts",
+ "src/services/strictVariablesSession.test.ts",
"src/services/hyperframeLint.file-race.test.ts",
"src/services/assetMediaType.test.ts",
"src/services/htmlCompiler.mediaType.test.ts",
diff --git a/packages/producer/src/renderRequest.test.ts b/packages/producer/src/renderRequest.test.ts
index 1bd799d385..d821b0ebbf 100644
--- a/packages/producer/src/renderRequest.test.ts
+++ b/packages/producer/src/renderRequest.test.ts
@@ -66,6 +66,24 @@ describe("RenderRequest", () => {
).toBe("off");
});
+ it("carries strictVariables through the in-process and distributed adapters, and refuses a non-boolean", () => {
+ const value = request();
+ value.options.strictVariables = true;
+ expect(renderConfigFromRequest(value).strictVariables).toBe(true);
+ const config = distributedConfigFromRequest(value);
+ expect(config.strictVariables).toBe(true);
+ expect(
+ renderRequestFromDistributedConfig({
+ projectDir: value.projectDir,
+ outputPath: value.outputPath,
+ config,
+ }).options.strictVariables,
+ ).toBe(true);
+ expect(() =>
+ parseRenderRequest({ ...value, options: { ...value.options, strictVariables: "yes" } }),
+ ).toThrow(/strictVariables must be a boolean/);
+ });
+
it("carries the delivery encoder options through every adapter", () => {
const value = request();
Object.assign(value.options, {
diff --git a/packages/producer/src/renderRequest.ts b/packages/producer/src/renderRequest.ts
index 6d64a4631b..870ad35bee 100644
--- a/packages/producer/src/renderRequest.ts
+++ b/packages/producer/src/renderRequest.ts
@@ -68,6 +68,7 @@ export interface RenderRequestOptions {
chromaSubsampling?: RenderConfig["chromaSubsampling"];
pageMotionBlur?: RenderConfig["pageMotionBlur"];
variables?: Record;
+ strictVariables?: boolean;
outputResolution?: CanvasResolution;
outputResolutionAspectAgnostic?: boolean;
engineConfig: EngineConfig;
@@ -216,6 +217,9 @@ function assertRequestOptionObjects(options: Record): void {
if (options.variables !== undefined && !isPlainObject(options.variables)) {
throw new Error("Render request variables must be a JSON object");
}
+ if (options.strictVariables !== undefined && typeof options.strictVariables !== "boolean") {
+ throw new Error("Render request strictVariables must be a boolean");
+ }
if (options.distributed !== undefined) assertDistributedOptions(options.distributed);
}
@@ -350,6 +354,7 @@ export function distributedConfigFromRequest(
abortSignal: runtime.abortSignal,
planDirSizeLimitBytes: distributed.planDirSizeLimitBytes,
variables: options.variables,
+ strictVariables: options.strictVariables,
};
}
@@ -400,6 +405,7 @@ export function renderRequestFromDistributedConfig(input: {
...optionalProperty("strictness", config.strictness),
...optionalProperty("entryFile", config.entryFile),
...optionalProperty("variables", config.variables),
+ ...optionalProperty("strictVariables", config.strictVariables),
} satisfies CreateRenderRequestInput["options"];
return createRenderRequest({
projectDir: input.projectDir,
diff --git a/packages/producer/src/server.errorCode.test.ts b/packages/producer/src/server.errorCode.test.ts
index 457a0d516a..ec8a2d31dd 100644
--- a/packages/producer/src/server.errorCode.test.ts
+++ b/packages/producer/src/server.errorCode.test.ts
@@ -4,7 +4,7 @@ import {
assertVideoExtractionSucceeded,
VideoExtractionStageError,
} from "./services/render/stages/extractVideosStage.js";
-import type { ExtractionResult } from "@hyperframes/engine";
+import { VariablesInvalidError, type ExtractionResult } from "@hyperframes/engine";
import { AssetMediaTypeMismatchError } from "./services/assetMediaType.js";
import { EncoderInterruptedError } from "./services/render/encoderInterruption.js";
import { RenderStageStalledError } from "./services/render/observability.js";
@@ -139,3 +139,16 @@ describe("extractSafeRenderErrorCode", () => {
).toBeUndefined();
});
});
+
+describe("VARIABLES_INVALID", () => {
+ it("is transported with its owner, no retry and bounded issue metadata", () => {
+ const error = new VariablesInvalidError([{ kind: "undeclared", variableId: "titel" }]);
+ expect(extractSafeRenderErrorCode(error)).toBe("VARIABLES_INVALID");
+ expect(extractSafeRenderErrorMetadata(error)).toEqual({
+ errorCode: "VARIABLES_INVALID",
+ errorOwner: "user",
+ retryable: false,
+ errorMetadata: { issues: [{ kind: "undeclared", variableId: "titel" }], total: 1 },
+ });
+ });
+});
diff --git a/packages/producer/src/server.ts b/packages/producer/src/server.ts
index 5bf586a80c..62e4854ea7 100644
--- a/packages/producer/src/server.ts
+++ b/packages/producer/src/server.ts
@@ -114,6 +114,8 @@ interface RenderInput {
* composition's declared defaults, ignoring per-request overrides.
*/
variables?: Record;
+ /** Fails with `VARIABLES_INVALID` before any frame if `variables` mismatch the page's declarations. Default off. */
+ strictVariables?: boolean;
/**
* Output resolution preset (e.g. `landscape-4k`). Drives the same
* `resolveDeviceScaleFactor` supersampling path the local CLI uses — Chrome
@@ -166,6 +168,12 @@ export function extractSafeRenderErrorMetadata(
};
}
+function strictVariablesResult(job: RenderJob): { strictVariablesChecked?: boolean } {
+ return job.strictVariablesChecked === undefined
+ ? {}
+ : { strictVariablesChecked: job.strictVariablesChecked };
+}
+
function parseServerFps(value: unknown): RenderInput["fps"] {
if (typeof value !== "number" && typeof value !== "string") return DEFAULT_SERVER_FPS;
const parsed = parseFps(value);
@@ -246,7 +254,7 @@ export function parseRenderOptions(body: Record): Omit): Omit {
*/
function parseRenderOverrides(body: Record): {
variables?: Record;
+ strictVariables?: boolean;
outputResolution?: CanvasResolution;
outputResolutionAspectAgnostic?: boolean;
} {
// Only forward a plain JSON object. Arrays / primitives / null → undefined.
const variables = isPlainObject(body.variables) ? body.variables : undefined;
+ const strictVariables = body.strictVariables === true ? true : undefined;
// Accept canonical presets and aliases ("4k", "landscape-4k", …).
const rawOutputResolution =
typeof body.outputResolution === "string" ? body.outputResolution : undefined;
@@ -304,7 +315,7 @@ function parseRenderOverrides(body: Record): {
const outputResolutionAspectAgnostic = outputResolution
? isAspectAgnosticResolutionAlias(rawOutputResolution)
: undefined;
- return { variables, outputResolution, outputResolutionAspectAgnostic };
+ return { variables, strictVariables, outputResolution, outputResolutionAspectAgnostic };
}
/**
@@ -334,6 +345,7 @@ function buildRenderJobConfig(input: RenderInput, outputPath: string, log: Produ
strictness: input.strictness,
entryFile: input.entryFile,
variables: input.variables,
+ strictVariables: input.strictVariables,
outputResolution: input.outputResolution,
outputResolutionAspectAgnostic: input.outputResolutionAspectAgnostic,
videoFrameFormat: input.videoFrameFormat,
@@ -413,6 +425,9 @@ function validateRenderOverrides(body: Record): string | undefi
if (body.variables !== undefined && !isPlainObject(body.variables)) {
return 'variables must be a JSON object keyed by variable id (e.g. {"title":"Hello"})';
}
+ if (body.strictVariables !== undefined && typeof body.strictVariables !== "boolean") {
+ return "strictVariables must be a boolean";
+ }
if (
body.outputDynamicRange !== undefined &&
parseServerOutputDynamicRange(body.outputDynamicRange) === undefined
@@ -843,6 +858,7 @@ export function createRenderHandlers(options: HandlerOptions = {}): RenderHandle
outcome: job.outcome ?? "completed",
warnings: job.warnings,
perf: job.perfSummary ?? null,
+ ...strictVariablesResult(job),
});
} catch (error) {
const durationMs = Date.now() - t0;
@@ -946,6 +962,7 @@ export function createRenderHandlers(options: HandlerOptions = {}): RenderHandle
warnings: job.warnings,
perf: job.perfSummary ?? null,
producerVersion: readProducerVersion(),
+ ...strictVariablesResult(job),
}),
});
} catch (error) {
diff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.ts
index d3fbf2320b..fb2cb1c6ca 100644
--- a/packages/producer/src/services/distributed/plan.ts
+++ b/packages/producer/src/services/distributed/plan.ts
@@ -308,6 +308,8 @@ export interface DistributedRenderConfig extends Pick;
+ /** Fails with `VARIABLES_INVALID` before any frame if `variables` mismatch the page's declarations. Default off. */
+ strictVariables?: boolean;
}
/** Shared local representation consumed by both distributed plan transports. */
@@ -322,6 +324,8 @@ export interface LocalExecutionPlan extends Partial {
format: DistributedFormat;
ffmpegVersion: string;
producerVersion: string;
+ /** Present when `strictVariables` was asked; true only if this producer honoured it. */
+ strictVariablesChecked?: boolean;
}
export interface BuildLocalExecutionPlanOptions {
@@ -384,6 +388,8 @@ export interface PlanResult extends Partial {
format: DistributedFormat;
ffmpegVersion: string;
producerVersion: string;
+ /** Present when `strictVariables` was asked; true only if this producer honoured it. */
+ strictVariablesChecked?: boolean;
}
/** Applies the same audio correctness policy used by the in-process renderer. */
@@ -1228,6 +1234,7 @@ async function compilePlanComposition(
logger: config.logger,
producerConfig: cfg,
variables: config.variables,
+ strictVariables: config.strictVariables,
pageMotionBlur: config.pageMotionBlur,
});
const entryFile = config.entryFile ?? "index.html";
@@ -1392,6 +1399,7 @@ async function compilePlanComposition(
logPlanStage(log, "reference_background", stageStarted);
}
compiled = probeResult.compiled;
+ job.strictVariablesChecked = probeResult.strictVariablesChecked;
job.duration = probeResult.duration;
job.totalFrames = probeResult.totalFrames;
const totalFrames = probeResult.totalFrames;
@@ -1832,6 +1840,9 @@ export async function buildLocalExecutionPlan(
format: config.format,
ffmpegVersion,
producerVersion,
+ ...(job.strictVariablesChecked === undefined
+ ? {}
+ : { strictVariablesChecked: job.strictVariablesChecked }),
};
}
@@ -1894,5 +1905,8 @@ export async function plan(
format: executionPlan.format,
ffmpegVersion: executionPlan.ffmpegVersion,
producerVersion: executionPlan.producerVersion,
+ ...(executionPlan.strictVariablesChecked === undefined
+ ? {}
+ : { strictVariablesChecked: executionPlan.strictVariablesChecked }),
};
}
diff --git a/packages/producer/src/services/distributed/planV2.ts b/packages/producer/src/services/distributed/planV2.ts
index ba225b1c1d..10c407f31f 100644
--- a/packages/producer/src/services/distributed/planV2.ts
+++ b/packages/producer/src/services/distributed/planV2.ts
@@ -160,6 +160,7 @@ export interface PlanV2WithPublisherOptions {
readonly remoteFiles?: BuildLocalExecutionPlanOptions["remoteFiles"];
readonly chunksCarryAudio?: boolean;
readonly deferAudio?: boolean;
+ readonly onPlanned?: (summary: { readonly strictVariablesChecked?: boolean }) => void;
}
export interface PlanV2MaterializationResult {
@@ -772,7 +773,7 @@ export async function planV2WithPublisher(
const stagingRoot = createStagingDir(options.stagingParentDir ?? tmpdir(), ".execution-plan-");
const digests: PlanFileDigests = new Map();
try {
- await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
+ const planned = await buildLocalExecutionPlan(projectDir, config, stagingRoot, {
executionPlanSizeLimitBytes: Number.MAX_SAFE_INTEGER,
deferVideoExtraction: true,
remoteFiles: options.remoteFiles,
@@ -789,6 +790,7 @@ export async function planV2WithPublisher(
sliceChunkAudio: true,
deferAudio: options.deferAudio,
});
+ options.onPlanned?.({ strictVariablesChecked: planned.strictVariablesChecked });
return await publishExecutionPlan(stagingRoot, publisher, { digests, log: config.logger });
} catch (error) {
try {
diff --git a/packages/producer/src/services/distributed/renderConfigValidation.ts b/packages/producer/src/services/distributed/renderConfigValidation.ts
index 5fbcc37587..6d7c2d2a2e 100644
--- a/packages/producer/src/services/distributed/renderConfigValidation.ts
+++ b/packages/producer/src/services/distributed/renderConfigValidation.ts
@@ -272,6 +272,9 @@ export function validateDistributedRenderConfig(
if (config.variables !== undefined) {
validateVariablesPayload(config.variables);
}
+ if (config.strictVariables !== undefined && typeof config.strictVariables !== "boolean") {
+ throw new InvalidConfigError("config.strictVariables", "must be a boolean");
+ }
if (config.engineConfig !== undefined) {
try {
validateEngineConfigSnapshot(config.engineConfig);
diff --git a/packages/producer/src/services/distributed/shared.ts b/packages/producer/src/services/distributed/shared.ts
index 2ad0ce9acf..cc3dd3f867 100644
--- a/packages/producer/src/services/distributed/shared.ts
+++ b/packages/producer/src/services/distributed/shared.ts
@@ -444,6 +444,7 @@ export interface SyntheticRenderJobInput {
producerConfig?: RenderConfig["producerConfig"];
/** Render-time overrides consumed by the plan browser probe. */
variables?: RenderConfig["variables"];
+ strictVariables?: RenderConfig["strictVariables"];
pageMotionBlur?: RenderConfig["pageMotionBlur"];
}
@@ -472,6 +473,7 @@ export function buildSyntheticRenderJob(input: SyntheticRenderJobInput): RenderJ
strictness: input.strictness,
producerConfig: input.producerConfig,
variables: input.variables,
+ strictVariables: input.strictVariables,
pageMotionBlur: input.pageMotionBlur,
};
return createRenderJob(renderConfig);
diff --git a/packages/producer/src/services/render/stages/probeStage.ts b/packages/producer/src/services/render/stages/probeStage.ts
index 607a352e13..0507c8b995 100644
--- a/packages/producer/src/services/render/stages/probeStage.ts
+++ b/packages/producer/src/services/render/stages/probeStage.ts
@@ -82,7 +82,7 @@ import {
writeCompiledArtifacts,
type CompositionMetadata,
} from "../shared.js";
-import type { RenderJob } from "../../renderOrchestrator.js";
+import type { RenderConfig, RenderJob } from "../../renderOrchestrator.js";
import { isActionableProbeFailure } from "./probeFailures.js";
import { preflightCompositionAssetMediaTypes } from "../../assetMediaType.js";
import { resolveCaptureSurface } from "../captureImageFormat.js";
@@ -126,6 +126,7 @@ function durationToFrameCount(duration: number, fps: number): number {
}
export interface ProbeStageResult {
+ strictVariablesChecked: boolean | undefined;
/** May be reassigned from `recompileWithResolutions`. */
compiled: CompiledComposition;
/** Created when `needsBrowser` was true; `null` otherwise. */
@@ -325,6 +326,20 @@ function hasRuntimeMediaChanges(html: string): boolean {
* that shape is measured statically and must never reach the band's `applied`
* cohort (review finding, R4).
*/
+/** A strict render with variables to check needs the loaded page; with none there is nothing to read. */
+function checksVariablesInBrowser(config: RenderConfig): boolean {
+ return config.strictVariables === true && Object.keys(config.variables ?? {}).length > 0;
+}
+
+/** Reported `strictVariables`: undefined if not asked; true if checked or nothing needed checking; else false. */
+export function strictVariablesAttestation(
+ config: RenderConfig,
+ probeSession: CaptureSession | null,
+): boolean | undefined {
+ if (config.strictVariables !== true) return undefined;
+ return !checksVariablesInBrowser(config) || probeSession?.strictVariablesChecked === true;
+}
+
export function probeRequiresBrowser(args: {
durationSeconds: number;
unresolvedCompositionCount: number;
@@ -332,8 +347,10 @@ export function probeRequiresBrowser(args: {
hasScriptedAudio: boolean;
hasVariableMedia: boolean;
hasInsertedMedia: boolean;
+ requiresVariablesCheck?: boolean;
}): boolean {
return (
+ args.requiresVariablesCheck === true ||
args.durationSeconds <= 0 ||
args.unresolvedCompositionCount > 0 ||
args.hasAutoStart ||
@@ -405,6 +422,7 @@ export async function runProbeStage(input: ProbeStageInput): Promise): RenderConfig => extra as RenderConfig;
+const session = (checked: boolean | undefined): CaptureSession =>
+ ({ strictVariablesChecked: checked }) as CaptureSession;
+
+describe("probeRequiresBrowser", () => {
+ it("needs a browser to check variables against the loaded page", () => {
+ expect(probeRequiresBrowser(noBrowserNeeded)).toBe(false);
+ expect(probeRequiresBrowser({ ...noBrowserNeeded, requiresVariablesCheck: true })).toBe(true);
+ });
+});
+
+describe("strictVariablesAttestation", () => {
+ it("says nothing when strict variables were not asked", () => {
+ expect(strictVariablesAttestation(config({ variables: { a: 1 } }), null)).toBeUndefined();
+ expect(strictVariablesAttestation(config({ strictVariables: false }), null)).toBeUndefined();
+ });
+
+ it("attests a pass when the probe session checked the page", () => {
+ const asked = config({ strictVariables: true, variables: { a: 1 } });
+ expect(strictVariablesAttestation(asked, session(true))).toBe(true);
+ });
+
+ it("does not attest when variables needed checking and no session checked them", () => {
+ const asked = config({ strictVariables: true, variables: { a: 1 } });
+ expect(strictVariablesAttestation(asked, null)).toBe(false);
+ expect(strictVariablesAttestation(asked, session(undefined))).toBe(false);
+ });
+
+ it("attests when there are no variables, which have nothing to check", () => {
+ expect(strictVariablesAttestation(config({ strictVariables: true }), null)).toBe(true);
+ expect(strictVariablesAttestation(config({ strictVariables: true, variables: {} }), null)).toBe(
+ true,
+ );
+ });
+});
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 2105beaf35..1a306b505a 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -481,6 +481,7 @@ export interface RenderConfig {
* `--variables-file `. Must be a JSON-serializable plain object.
*/
variables?: Record;
+ strictVariables?: boolean;
/**
* Override the output resolution via Chrome `deviceScaleFactor` (DPR).
* The composition's authored dimensions are unchanged. See
@@ -791,6 +792,7 @@ export interface RenderStageProgress {
export interface RenderJob extends Partial {
id: string;
+ strictVariablesChecked?: boolean;
config: RenderConfig;
status: RenderStatus;
progress: number;
@@ -3464,6 +3466,7 @@ async function executeRenderPipeline(input: {
compositionHash = computeCompositionObservabilityHash(compiled.html);
fileServer = probeResult.fileServer;
probeSession = probeResult.probeSession;
+ job.strictVariablesChecked = probeResult.strictVariablesChecked;
lastBrowserConsole = probeResult.lastBrowserConsole;
let resolvedCaptureBeyondViewport = probeSession?.options.captureBeyondViewport;
if (resolvedCaptureBeyondViewport !== undefined) {
diff --git a/packages/producer/src/services/safeRenderErrorCode.ts b/packages/producer/src/services/safeRenderErrorCode.ts
index dc9ac4e982..e35be21be9 100644
--- a/packages/producer/src/services/safeRenderErrorCode.ts
+++ b/packages/producer/src/services/safeRenderErrorCode.ts
@@ -10,6 +10,7 @@ const SAFE_RENDER_ERROR_CODES = new Set([
"RENDER_TOO_SLOW",
"RENDER_STAGE_STALLED",
"PAGE_NEVER_READY",
+ "VARIABLES_INVALID",
]);
/**
diff --git a/packages/producer/src/services/strictVariablesSession.test.ts b/packages/producer/src/services/strictVariablesSession.test.ts
new file mode 100644
index 0000000000..58d1bb4569
--- /dev/null
+++ b/packages/producer/src/services/strictVariablesSession.test.ts
@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { closeCaptureSession, createCaptureSession, initializeSession } from "@hyperframes/engine";
+import type { CaptureOptions } from "@hyperframes/engine";
+import { createFileServer } from "./fileServer.js";
+import { compileForRender } from "./htmlCompiler.js";
+import { writeCompiledArtifacts } from "./render/shared.js";
+
+// Real Chromium on the render path: the compiled page carries the runtime, and the session's own
+// readiness poll runs before the variables are checked against what the page declares.
+const DECLARED = JSON.stringify([
+ { id: "title", type: "string", label: "Title", default: "Hi" },
+ { id: "speed", type: "number", label: "Speed", default: 1 },
+]);
+const page = (htmlAttributes: string) => `
+
+
+`;
+
+let root: string;
+beforeAll(() => {
+ root = mkdtempSync(join(tmpdir(), "hf-strict-variables-"));
+});
+afterAll(() => {
+ rmSync(root, { recursive: true, force: true });
+});
+
+async function openSession(html: string, options: Partial) {
+ const projectDir = mkdtempSync(join(root, "case-"));
+ const workDir = mkdtempSync(join(root, "work-"));
+ writeFileSync(join(projectDir, "index.html"), html);
+ const compiled = await compileForRender(
+ projectDir,
+ join(projectDir, "index.html"),
+ join(workDir, "downloads"),
+ );
+ writeCompiledArtifacts(compiled, workDir, false);
+ const server = await createFileServer({
+ projectDir,
+ compiledDir: join(workDir, "compiled"),
+ port: 0,
+ });
+ const session = await createCaptureSession(
+ server.url,
+ join(workDir, "frames"),
+ {
+ width: 160,
+ height: 120,
+ fps: { num: 30, den: 1 },
+ format: "jpeg",
+ quality: 80,
+ ...options,
+ },
+ null,
+ { browserGpuMode: "software", playerReadyTimeout: 10_000 },
+ );
+ return {
+ session,
+ close: async () => {
+ await closeCaptureSession(session).catch(() => {});
+ server.close();
+ },
+ };
+}
+
+async function initialize(options: Partial) {
+ const { session, close } = await openSession(
+ page(`data-composition-variables='${DECLARED}'`),
+ options,
+ );
+ try {
+ await initializeSession(session);
+ return session.strictVariablesChecked;
+ } finally {
+ await close();
+ }
+}
+
+describe("strictVariables on a capture session", () => {
+ it("lets a session start when the page declares the variables, and says it checked", async () => {
+ expect(
+ await initialize({ variables: { title: "Hello", speed: 2 }, strictVariables: true }),
+ ).toBe(true);
+ }, 60_000);
+
+ it("refuses a variable the page does not declare, naming it, before any frame", async () => {
+ await expect(
+ initialize({ variables: { titel: "Hello" }, strictVariables: true }),
+ ).rejects.toMatchObject({
+ code: "VARIABLES_INVALID",
+ owner: "user",
+ retryable: false,
+ message: 'Variable "titel" is not declared in data-composition-variables.',
+ });
+ }, 60_000);
+
+ it("refuses a value of the wrong type without echoing it", async () => {
+ const result = initialize({ variables: { speed: "fast-secret" }, strictVariables: true });
+ await expect(result).rejects.toMatchObject({
+ code: "VARIABLES_INVALID",
+ publicMetadata: {
+ issues: [
+ { kind: "type-mismatch", variableId: "speed", expected: "number", actual: "string" },
+ ],
+ },
+ });
+ await expect(result).rejects.not.toThrow(/fast-secret/);
+ }, 60_000);
+
+ it("refuses when the page's declarations cannot be read, not as undeclared", async () => {
+ const { session, close } = await openSession(page(`data-composition-variables='{broken'`), {
+ variables: { title: "Hello" },
+ strictVariables: true,
+ });
+ try {
+ await expect(initializeSession(session)).rejects.toMatchObject({
+ code: "VARIABLES_INVALID",
+ publicMetadata: { issues: [{ kind: "declarations-unreadable" }] },
+ });
+ } finally {
+ await close();
+ }
+ }, 60_000);
+
+ it("checks nothing and still says it checked when there are no variables", async () => {
+ expect(await initialize({ strictVariables: true })).toBe(true);
+ }, 60_000);
+
+ it("does not check, and does not say it did, when strict variables were not asked", async () => {
+ expect(await initialize({ variables: { titel: "Hello" } })).toBeUndefined();
+ }, 60_000);
+});