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); +});