Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
refactor(core): one owner for the distributed fps set (#5756)
Miguel Ángeld5162beb50a4
diff --git a/packages/aws-lambda/src/events.ts b/packages/aws-lambda/src/events.tsindex 233e938178..c15b52d679 100644--- a/packages/aws-lambda/src/events.ts+++ b/packages/aws-lambda/src/events.ts@@ -164,7 +164,7 @@ interface PlanLambdaResultBase {PlanHash: string;ChunkCount: number;TotalFrames: number;- Fps: 24 | 25 | 30 | 60;+ Fps: SerializableDistributedRenderConfig["fps"];Width: number;Height: number;Format: DistributedFormat;diff --git a/packages/aws-lambda/src/sdk/renderToLambda.test.ts b/packages/aws-lambda/src/sdk/renderToLambda.test.tsindex b858703235..9e36eeaf15 100644--- a/packages/aws-lambda/src/sdk/renderToLambda.test.ts+++ b/packages/aws-lambda/src/sdk/renderToLambda.test.ts@@ -173,7 +173,7 @@ describe("renderToLambda", () => {projectDir,bucketName: "test-bucket",stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",- config: { ...baseConfig, fps: 50 as 24 | 25 | 30 | 60 },+ config: { ...baseConfig, fps: 50 as never },sfn: asSFNClient(sfn),s3: asS3Client(s3),});diff --git a/packages/aws-lambda/src/sdk/validateConfig.test.ts b/packages/aws-lambda/src/sdk/validateConfig.test.tsindex a3560f5deb..495b5b22f3 100644--- a/packages/aws-lambda/src/sdk/validateConfig.test.ts+++ b/packages/aws-lambda/src/sdk/validateConfig.test.ts@@ -44,7 +44,7 @@ describe("validateDistributedRenderConfig", () => {["null config", null as unknown as SerializableDistributedRenderConfig, "config"],["wrong fps",- { ...VALID, fps: 50 as 24 | 25 | 30 | 60 } satisfies SerializableDistributedRenderConfig,+ { ...VALID, fps: 50 as never } satisfies SerializableDistributedRenderConfig,"config.fps",],[diff --git a/packages/cli/src/commands/cloudrun.ts b/packages/cli/src/commands/cloudrun.tsindex 405677596f..395277f5a2 100644--- a/packages/cli/src/commands/cloudrun.ts+++ b/packages/cli/src/commands/cloudrun.ts@@ -30,6 +30,7 @@ import {} from "../utils/variables.js";import { normalizeErrorMessage } from "../utils/errorMessage.js";import { readAllowedCompositionFpsFromDir } from "../utils/compositionFps.js";+import { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "@hyperframes/core";export const examples: Example[] = [["Deploy the Cloud Run render stack", "hyperframes cloudrun deploy --project my-gcp-project"],@@ -167,7 +168,7 @@ export default defineCommand({"site-id": { type: "string", description: "Explicit site id (overrides content hash)" },width: { type: "string", description: "Render width in pixels" },height: { type: "string", description: "Render height in pixels" },- fps: { type: "string", description: "Render fps (24 | 25 | 30 | 60)" },+ fps: { type: "string", description: `Render fps (${DISTRIBUTED_FPS.join(" | ")})` },format: { type: "string", description: "mp4 | mov | png-sequence | webm (default: mp4)" },codec: { type: "string", description: "h264 | h265 (mp4 only)" },quality: { type: "string", description: "draft | standard | high" },@@ -529,11 +530,12 @@ function resolveCloudRunFps(args: Record<string, unknown>,projectDir: string,command: "render" | "render-batch",-): 24 | 25 | 30 | 60 {- const fps =- parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir, [24, 25, 30, 60]) ?? 30;- if (fps === 24 || fps === 25 || fps === 30 || fps === 60) return fps;- console.error(`[cloudrun ${command}] --fps must be 24, 25, 30, or 60; got ${fps}.`);+): DistributedFps {+ const fps = parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir) ?? 30;+ if (isDistributedFps(fps)) return fps;+ console.error(+ `[cloudrun ${command}] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fps}.`,+ );failCommand();}diff --git a/packages/cli/src/commands/lambda.ts b/packages/cli/src/commands/lambda.tsindex e0226c84d4..6e9373de01 100644--- a/packages/cli/src/commands/lambda.ts+++ b/packages/cli/src/commands/lambda.ts@@ -11,7 +11,7 @@ import { failCommand } from "../utils/commandResult.js";import { defineCommand } from "citty";import type { DistributedFormat } from "@hyperframes/aws-lambda/sdk";-import { type CanvasResolution } from "@hyperframes/core";+import { type CanvasResolution, DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";import { parseOutputResolutionFlag } from "../utils/parseOutputResolution.js";import type { Example } from "./_examples.js";import { c } from "../ui/colors.js";@@ -126,7 +126,7 @@ export default defineCommand({description:"Output resolution preset that engages Chrome deviceScaleFactor supersampling. Accepts canonical names (landscape, landscape-4k, portrait, portrait-4k, square, square-4k) and aliases (1080p, 4k, uhd, hd). When set, the composition's authored data-width/data-height is supersampled to the target preset without changing the layout.",},- fps: { type: "string", description: "Render fps (24 | 25 | 30 | 60)" },+ fps: { type: "string", description: `Render fps (${DISTRIBUTED_FPS.join(" | ")})` },format: { type: "string", description: "mp4 | mov | png-sequence | webm (default: mp4)" },codec: { type: "string", description: "h264 | h265 (mp4 only)" },quality: { type: "string", description: "draft | standard | high" },@@ -296,12 +296,11 @@ export default defineCommand({console.error("[lambda render] --width and --height are required.");failCommand();}- const fpsRaw =- parseIntFlag(args.fps) ??- readAllowedCompositionFpsFromDir(projectDir, [24, 25, 30, 60]) ??- 30;- if (fpsRaw !== 24 && fpsRaw !== 25 && fpsRaw !== 30 && fpsRaw !== 60) {- console.error(`[lambda render] --fps must be 24, 25, 30, or 60; got ${fpsRaw}.`);+ const fpsRaw = parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir) ?? 30;+ if (!isDistributedFps(fpsRaw)) {+ console.error(+ `[lambda render] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fpsRaw}.`,+ );failCommand();}const { runRender } = await import("./lambda/render.js");@@ -353,12 +352,11 @@ export default defineCommand({console.error("[lambda render-batch] --width and --height are required.");failCommand();}- const fpsRaw =- parseIntFlag(args.fps) ??- readAllowedCompositionFpsFromDir(projectDir, [24, 25, 30, 60]) ??- 30;- if (fpsRaw !== 24 && fpsRaw !== 25 && fpsRaw !== 30 && fpsRaw !== 60) {- console.error(`[lambda render-batch] --fps must be 24, 25, 30, or 60; got ${fpsRaw}.`);+ const fpsRaw = parseIntFlag(args.fps) ?? readAllowedCompositionFpsFromDir(projectDir) ?? 30;+ if (!isDistributedFps(fpsRaw)) {+ console.error(+ `[lambda render-batch] --fps must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${fpsRaw}.`,+ );failCommand();}const { runRenderBatch } = await import("./lambda/render-batch.js");diff --git a/packages/cli/src/commands/lambda/render-batch.ts b/packages/cli/src/commands/lambda/render-batch.tsindex 9fd7c136b4..3a32b02af0 100644--- a/packages/cli/src/commands/lambda/render-batch.ts+++ b/packages/cli/src/commands/lambda/render-batch.ts@@ -29,7 +29,7 @@ import type {SerializableDistributedRenderConfig,SiteHandle,} from "@hyperframes/aws-lambda/sdk";-import type { CanvasResolution } from "@hyperframes/core";+import type { CanvasResolution, DistributedFps } from "@hyperframes/core";import { c } from "../../ui/colors.js";import { errorBox } from "../../ui/format.js";import {@@ -61,7 +61,7 @@ export interface RenderBatchArgs {*/siteId?: string;/** Composition config — fps/width/height/format required, rest optional. */- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;width: number;height: number;/** See {@link RenderArgs.outputResolution}. */diff --git a/packages/cli/src/commands/lambda/render.ts b/packages/cli/src/commands/lambda/render.tsindex 8274c23869..450aaac37e 100644--- a/packages/cli/src/commands/lambda/render.ts+++ b/packages/cli/src/commands/lambda/render.ts@@ -11,7 +11,7 @@ import type {DistributedFormat,SerializableDistributedRenderConfig,} from "@hyperframes/aws-lambda/sdk";-import type { CanvasResolution } from "@hyperframes/core";+import type { CanvasResolution, DistributedFps } from "@hyperframes/core";import { c } from "../../ui/colors.js";import {reportVariableIssues,@@ -32,7 +32,7 @@ export interface RenderArgs {stackName: string;siteId?: string;/** Composition config — fps/width/height/format required, rest optional. */- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;width: number;height: number;/**diff --git a/packages/cli/src/utils/compositionFps.test.ts b/packages/cli/src/utils/compositionFps.test.tsindex 84ce2c4f3e..0eb75a5d38 100644--- a/packages/cli/src/utils/compositionFps.test.ts+++ b/packages/cli/src/utils/compositionFps.test.ts@@ -43,7 +43,6 @@ describe("readCompositionFps", () => {describe("readAllowedCompositionFpsFromDir", () => {const projectDirs: string[] = [];- const allowedCloudFps = [24, 30, 60] as const;afterEach(() => {for (const dir of projectDirs.splice(0)) {@@ -63,7 +62,7 @@ describe("readAllowedCompositionFpsFromDir", () => {'<div data-composition-id="root" data-root="true" data-fps="60">x</div>',);- expect(readAllowedCompositionFpsFromDir(dir, allowedCloudFps)).toBe(60);+ expect(readAllowedCompositionFpsFromDir(dir)).toBe(60);});it("uses cloud-allowed data-fps=24 as the default", () => {@@ -71,7 +70,15 @@ describe("readAllowedCompositionFpsFromDir", () => {'<div data-composition-id="root" data-root="true" data-fps="24">x</div>',);- expect(readAllowedCompositionFpsFromDir(dir, allowedCloudFps)).toBe(24);+ expect(readAllowedCompositionFpsFromDir(dir)).toBe(24);+ });++ it("uses cloud-allowed data-fps=25 instead of falling back to 30", () => {+ const dir = makeProject(+ '<div data-composition-id="root" data-root="true" data-fps="25">x</div>',+ );++ expect(readAllowedCompositionFpsFromDir(dir)).toBe(25);});it("returns null for data-fps=48 so cloud callers keep their ?? 30 fallback", () => {@@ -79,7 +86,7 @@ describe("readAllowedCompositionFpsFromDir", () => {'<div data-composition-id="root" data-root="true" data-fps="48">x</div>',);- const declared = readAllowedCompositionFpsFromDir(dir, allowedCloudFps);+ const declared = readAllowedCompositionFpsFromDir(dir);expect(declared).toBeNull();expect(declared ?? 30).toBe(30);});@@ -89,19 +96,19 @@ describe("readAllowedCompositionFpsFromDir", () => {'<div data-composition-id="root" data-root="true" data-fps="30000/1001">x</div>',);- expect(readAllowedCompositionFpsFromDir(dir, allowedCloudFps)).toBeNull();+ expect(readAllowedCompositionFpsFromDir(dir)).toBeNull();});it("returns null when index.html has no data-fps", () => {const dir = makeProject('<div data-composition-id="root" data-root="true">x</div>');- expect(readAllowedCompositionFpsFromDir(dir, allowedCloudFps)).toBeNull();+ expect(readAllowedCompositionFpsFromDir(dir)).toBeNull();});it("returns null when index.html cannot be read", () => {const dir = mkdtempSync(join(tmpdir(), "hyperframes-composition-fps-missing-"));projectDirs.push(dir);- expect(readAllowedCompositionFpsFromDir(dir, allowedCloudFps)).toBeNull();+ expect(readAllowedCompositionFpsFromDir(dir)).toBeNull();});});diff --git a/packages/cli/src/utils/compositionFps.ts b/packages/cli/src/utils/compositionFps.tsindex bc2b13012e..952c004d35 100644--- a/packages/cli/src/utils/compositionFps.ts+++ b/packages/cli/src/utils/compositionFps.ts@@ -1,5 +1,6 @@import { readFileSync } from "node:fs";import { join } from "node:path";+import { type DistributedFps, isDistributedFps } from "@hyperframes/core";import { parseHTML } from "linkedom";/**@@ -35,17 +36,12 @@ export function readCompositionFps(html: string): string | null {}/**- * Cloud render backends (Lambda, Cloud Run) accept only an integer fps- * from a small fixed allowed set (currently {24, 25, 30, 60}) — unlike local- * `render`, they can't take an arbitrary/fractional data-fps. Reads- * `<projectDir>/index.html` and returns its declared data-fps as a number- * ONLY when it parses to an integer AND is a member of `allowed`;+ * Cloud render backends (Lambda, Cloud Run) accept only `DISTRIBUTED_FPS`;+ * unlike local `render`, they can't take an arbitrary/fractional data-fps.+ * Returns `<projectDir>/index.html`'s declared data-fps when it is a member,* otherwise `null` so the caller keeps its own existing default (30).*/-export function readAllowedCompositionFpsFromDir(- projectDir: string,- allowed: readonly number[],-): number | null {+export function readAllowedCompositionFpsFromDir(projectDir: string): DistributedFps | null {let html: string;try {html = readFileSync(join(projectDir, "index.html"), "utf8");@@ -55,5 +51,5 @@ export function readAllowedCompositionFpsFromDir(const raw = readCompositionFps(html);if (raw == null) return null;const n = Number(raw);- return Number.isInteger(n) && allowed.includes(n) ? n : null;+ return isDistributedFps(n) ? n : null;}diff --git a/packages/core/src/core.types.ts b/packages/core/src/core.types.tsindex 99d356b557..7abca72567 100644--- a/packages/core/src/core.types.ts+++ b/packages/core/src/core.types.ts@@ -136,6 +136,14 @@ export function parseFpsWithDefault(input: string | number | undefined): FpsParsreturn parseFps(input);}+/** Integer rates the distributed renderer (Lambda, Cloud Run) accepts; fractional fps renders in-process only. */+export const DISTRIBUTED_FPS = [24, 25, 30, 60] as const;+export type DistributedFps = (typeof DISTRIBUTED_FPS)[number];++export function isDistributedFps(value: unknown): value is DistributedFps {+ return (DISTRIBUTED_FPS as readonly unknown[]).includes(value);+}+/** Video orientation / aspect ratio. */export type Orientation = "16:9" | "9:16";diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 717d38f98c..ebb8f87042 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -14,6 +14,7 @@ export type {CanvasResolution,Fps,FpsInput,+ DistributedFps,FpsParseResult,MediaFile,CompositionAPI,@@ -72,6 +73,8 @@ export {toFps,fpsToNumber,fpsToFfmpegArg,+ DISTRIBUTED_FPS,+ isDistributedFps,TIMELINE_COLORS,DEFAULT_DURATIONS,COMPOSITION_VARIABLE_TYPES,diff --git a/packages/core/src/parseFps.test.ts b/packages/core/src/parseFps.test.tsindex 2a4f8705da..d2821b3210 100644--- a/packages/core/src/parseFps.test.ts+++ b/packages/core/src/parseFps.test.ts@@ -1,5 +1,11 @@import { describe, expect, it } from "vitest";-import { parseFps, fpsToNumber, fpsToFfmpegArg } from "./core.types";+import {+ DISTRIBUTED_FPS,+ fpsToFfmpegArg,+ fpsToNumber,+ isDistributedFps,+ parseFps,+} from "./core.types";describe("parseFps — integer forms", () => {it("parses integer string '30' as { num: 30, den: 1 }", () => {@@ -156,3 +162,16 @@ describe("fpsToNumber + fpsToFfmpegArg + frame interval math", () => {expect(fpsToFfmpegArg({ num: 60000, den: 1001 })).toBe("60000/1001");});});++describe("isDistributedFps", () => {+ it("accepts exactly the integer rates the distributed renderer supports", () => {+ expect(DISTRIBUTED_FPS).toEqual([24, 25, 30, 60]);+ for (const n of DISTRIBUTED_FPS) expect(isDistributedFps(n)).toBe(true);+ });++ it("rejects other rates, fractions and non-numbers", () => {+ for (const v of [0, 23.976, 29.97, 48, 50, 120, "30", null, undefined]) {+ expect(isDistributedFps(v)).toBe(false);+ }+ });+});diff --git a/packages/engine/src/config.test.ts b/packages/engine/src/config.test.tsindex 9f8c9b95c8..ea01c4d2bf 100644--- a/packages/engine/src/config.test.ts+++ b/packages/engine/src/config.test.ts@@ -13,6 +13,7 @@ import {resolveExtractCacheDir,defaultExtractCacheDir,EXTRACT_CACHE_DIR_DISABLED_ALIASES,+ validateEngineConfigSnapshot,} from "./config.js";import type { EngineConfig } from "./config.js";import { isLowMemorySystem } from "./services/systemMemory.js";@@ -996,3 +997,15 @@ describe("resolveExtractCacheDir", () => {expect(() => resolveExtractCacheDir()).not.toThrow();});});++describe("validateEngineConfigSnapshot fps", () => {+ it("accepts every distributed fps, including 25", () => {+ for (const fps of [24, 25, 30, 60] as const) {+ expect(() => validateEngineConfigSnapshot({ ...resolveConfig(), fps })).not.toThrow();+ }+ });++ it("rejects an fps outside the distributed set", () => {+ expect(() => validateEngineConfigSnapshot({ ...resolveConfig(), fps: 50 })).toThrow(/fps/);+ });+});diff --git a/packages/engine/src/config.ts b/packages/engine/src/config.tsindex 83ecc8e470..06f0ee0ab0 100644--- a/packages/engine/src/config.ts+++ b/packages/engine/src/config.ts@@ -7,6 +7,7 @@*/import { tmpdir } from "node:os";+import { DISTRIBUTED_FPS, type DistributedFps } from "@hyperframes/core";import { chromeMajorCeiling } from "./services/chromeHostCeiling.js";import { join } from "node:path";import {@@ -23,7 +24,7 @@ import { DEFAULT_VP9_CPU_USED, normalizeVp9CpuUsed } from "./services/vp9Options*/export interface EngineConfig {// ── Rendering ────────────────────────────────────────────────────────- fps: 24 | 30 | 60;+ fps: DistributedFps;quality: "draft" | "standard" | "high";format: "jpeg" | "png";jpegQuality: number;@@ -378,7 +379,7 @@ const POSITIVE_NUMBER_ENGINE_CONFIG_FIELDS = [] as const;const ENUM_ENGINE_CONFIG_FIELDS = {- fps: [24, 30, 60],+ fps: DISTRIBUTED_FPS,quality: ["draft", "standard", "high"],format: ["jpeg", "png"],browserGpuMode: ["software", "hardware", "auto"],diff --git a/packages/gcp-cloud-run/src/events.ts b/packages/gcp-cloud-run/src/events.tsindex f43fbc2449..f135e98b3d 100644--- a/packages/gcp-cloud-run/src/events.ts+++ b/packages/gcp-cloud-run/src/events.ts@@ -178,7 +178,7 @@ interface PlanResultBodyBase {PlanHash: string;ChunkCount: number;TotalFrames: number;- Fps: 24 | 25 | 30 | 60;+ Fps: SerializableDistributedRenderConfig["fps"];Width: number;Height: number;Format: DistributedFormat;diff --git a/packages/producer/src/plan-parity-contract.ts b/packages/producer/src/plan-parity-contract.tsindex 065abc11b9..400f536717 100644--- a/packages/producer/src/plan-parity-contract.ts+++ b/packages/producer/src/plan-parity-contract.ts@@ -6,10 +6,12 @@* expected to match even when they render identical output.*/+import type { DistributedFps } from "@hyperframes/core";+export type PlanParityProtocol = "v1" | "v2";export interface PlanParityRenderConfig {- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;width: number;height: number;format: "mp4";diff --git a/packages/producer/src/plan-parity-harness.test.ts b/packages/producer/src/plan-parity-harness.test.tsindex 9ddbee21d2..4032ada6a2 100644--- a/packages/producer/src/plan-parity-harness.test.ts+++ b/packages/producer/src/plan-parity-harness.test.ts@@ -98,7 +98,7 @@ describe("parsePlanParityArgs()", () => {parsePlanParityArgs(["node", "plan-parity", "--v1-plan-size-cap-bytes", "-1"]),).toThrow(/positive integer/);expect(() => parsePlanParityArgs(["node", "plan-parity", "--fps", "50"])).toThrow(- /24, 25, 30, or 60/,+ /must be one of 24, 25, 30, 60/,);expect(() =>parsePlanParityArgs(["node", "plan-parity", "--duration-tolerance-seconds", "not-a-number"]),diff --git a/packages/producer/src/plan-parity-harness.ts b/packages/producer/src/plan-parity-harness.tsindex 2b1e43d7aa..16f4c40fd5 100644--- a/packages/producer/src/plan-parity-harness.ts+++ b/packages/producer/src/plan-parity-harness.ts@@ -1,6 +1,7 @@import { existsSync, mkdirSync, writeFileSync } from "node:fs";import { resolve } from "node:path";import process from "node:process";+import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";import { analyzePlanParityDriverResult } from "./plan-parity-analysis.js";import {comparePlanParityMeasurements,@@ -155,8 +156,8 @@ export function parsePlanParityArgs(argv: string[]): PlanParityCliOptions {const fixtureDir = resolve(args.get("fixture") ?? "fixtures/plan-parity-visual-audio");const artifactsDir = resolve(args.get("artifacts-dir") ?? ".debug/plan-protocol-parity");const fps = parsePositiveInteger("fps", args.get("fps")) ?? 30;- if (fps !== 24 && fps !== 25 && fps !== 30 && fps !== 60) {- throw new Error("plan parity: --fps must be 24, 25, 30, or 60");+ if (!isDistributedFps(fps)) {+ throw new Error(`plan parity: --fps must be one of ${DISTRIBUTED_FPS.join(", ")}`);}return {diff --git a/packages/producer/src/regression-harness-distributed.ts b/packages/producer/src/regression-harness-distributed.tsindex 73aa59b192..a5774420af 100644--- a/packages/producer/src/regression-harness-distributed.ts+++ b/packages/producer/src/regression-harness-distributed.ts@@ -25,7 +25,7 @@* capture jitter, so the harness can't use it as a per-test gate.** Not every fixture can run in distributed-simulated mode. Distributed mode- * refuses HDR mp4, NTSC framerates, and non-{24,30,60} fps at plan time.+ * refuses HDR mp4, NTSC framerates, and fps outside DISTRIBUTED_FPS at plan time.* Fixtures that don't meet the constraints are skipped — the harness logs* the reason and the fixture is treated as "passed (skipped)" in* distributed-simulated mode.@@ -33,7 +33,12 @@import { existsSync, mkdirSync } from "node:fs";import { join } from "node:path";-import type { Fps } from "@hyperframes/core";+import {+ DISTRIBUTED_FPS,+ type DistributedFps,+ type Fps,+ isDistributedFps,+} from "@hyperframes/core";import { assemble, plan, renderChunk } from "./distributed.js";import { PLAN_AUDIO_RELATIVE_PATH, type DistributedFormat } from "./services/distributed/shared.js";@@ -70,8 +75,8 @@ export type DistributedSupportResult = { supported: true } | { supported: false;* Decide whether a fixture's `renderConfig` is one the distributed pipeline* can actually run. Two hard gates:*- * - fps must be `{ num: 24|30|60, den: 1 }`. `DistributedRenderConfig.fps`- * accepts only the three integer values, and rationals like+ * - fps must be `{ num: <DISTRIBUTED_FPS member>, den: 1 }`. `DistributedRenderConfig.fps`+ * accepts only those integer values, and rationals like* `{ num: 30000, den: 1001 }` (NTSC) trip the type system at the call* site. We surface this gate in code rather than only in TS so the* harness can skip the fixture cleanly instead of throwing.@@ -92,10 +97,10 @@ export function checkDistributedSupport(renderConfig: {};}const fpsNum = renderConfig.fps.num;- if (fpsNum !== 24 && fpsNum !== 25 && fpsNum !== 30 && fpsNum !== 60) {+ if (!isDistributedFps(fpsNum)) {return {supported: false,- reason: `fps ${fpsNum} not in {24, 25, 30, 60} (DistributedRenderConfig.fps is a closed set)`,+ reason: `fps ${fpsNum} not in {${DISTRIBUTED_FPS.join(", ")}} (DistributedRenderConfig.fps is a closed set)`,};}if (renderConfig.hdr === true) {@@ -120,7 +125,7 @@ export interface RunDistributedSimulatedInput {/** Where to write the assembled final mp4 / mov / png-sequence directory. */renderedOutputPath: string;/** From the fixture's renderConfig — must pass `checkDistributedSupport`. */- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;format: DistributedFormat;/*** Codec for `format: "mp4"`. Defaults to `"h264"`; pass `"h265"` todiff --git a/packages/producer/src/regression-harness-lambda-local-types.ts b/packages/producer/src/regression-harness-lambda-local-types.tsindex ab8dd0bb7f..ffb25a95b7 100644--- a/packages/producer/src/regression-harness-lambda-local-types.ts+++ b/packages/producer/src/regression-harness-lambda-local-types.ts@@ -9,6 +9,7 @@* type-check pass.*/+import type { DistributedFps } from "@hyperframes/core";import type { DistributedFormat } from "./services/distributed/shared.js";/** Inputs for {@link runLambdaLocalRender}. Same contract as `runDistributedSimulatedRender`. */@@ -18,7 +19,7 @@ export interface RunLambdaLocalInput {projectDir: string;tempRoot: string;renderedOutputPath: string;- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;/*** Width/height from the fixture's renderConfig. Forwarded directly to* the Lambda event so this mode catches drift if the handler everdiff --git a/packages/producer/src/regression-harness.ts b/packages/producer/src/regression-harness.tsindex 959b396f7b..9c6c84662e 100644--- a/packages/producer/src/regression-harness.ts+++ b/packages/producer/src/regression-harness.ts@@ -25,7 +25,7 @@ import {compareAudioEnvelopes,computeAudioResidualRmsDb,} from "./utils/audioRegression.js";-import { parseFps, fpsToNumber } from "@hyperframes/core";+import { type DistributedFps, parseFps, fpsToNumber } from "@hyperframes/core";import {checkDistributedSupport,type HarnessMode,@@ -179,7 +179,7 @@ type TestResult = {passed: boolean;/*** Set when `--mode=distributed-simulated` skips a fixture that the- * distributed pipeline can't run (HDR, NTSC fps, fps∉{24,30,60}).+ * distributed pipeline can't run (HDR, NTSC fps, fps outside DISTRIBUTED_FPS).* `passed` is `true` for skipped fixtures — skipping is a clean outcome,* not a failure — but the summary distinguishes them.*/@@ -1114,10 +1114,10 @@ async function runTestSuite(result.skipped = { reason: support.reason };return result;}- // `checkDistributedSupport` already narrowed fps to {24,30,60}; the+ // `checkDistributedSupport` already narrowed fps to DISTRIBUTED_FPS; the// cast surfaces that guarantee to TS. webm is now distributed-// supported via closed-GOP concat-copy, so the format passes through.- const fpsNum = suite.meta.renderConfig.fps.num as 24 | 25 | 30 | 60;+ const fpsNum = suite.meta.renderConfig.fps.num as DistributedFps;const distributedInput = {projectDir: tempSrcDir,tempRoot,diff --git a/packages/producer/src/regression-shard-plan.test.ts b/packages/producer/src/regression-shard-plan.test.tsindex 4a0e779acb..1138ec0b4d 100644--- a/packages/producer/src/regression-shard-plan.test.ts+++ b/packages/producer/src/regression-shard-plan.test.ts@@ -127,7 +127,7 @@ describe("shard planner fixture discovery", () => {it("only assigns distributed mode to fixtures the harness can actually run that way", () => {// The blocking gap: `checkDistributedSupport` refuses HDR, non-integer fps,- // and fps outside {24,30,60}, and the harness records a refusal as+ // and fps outside DISTRIBUTED_FPS, and the harness records a refusal as// `passed: true` with `skipped`. Skipping was safe while in-process also// ran the fixture. It is not safe now — these fixtures run in distributed// mode and nowhere else, so a later `hdr: true` or fps edit would turndiff --git a/packages/producer/src/renderRequest.ts b/packages/producer/src/renderRequest.tsindex abff40161a..63121520a1 100644--- a/packages/producer/src/renderRequest.ts+++ b/packages/producer/src/renderRequest.ts@@ -5,7 +5,13 @@ import {type EngineConfig,type VideoFrameFormat,} from "@hyperframes/engine";-import { VALID_CANVAS_RESOLUTIONS, type CanvasResolution, type Fps } from "@hyperframes/core";+import {+ VALID_CANVAS_RESOLUTIONS,+ type CanvasResolution,+ type DistributedFps,+ type Fps,+ isDistributedFps,+} from "@hyperframes/core";import type { ProducerLogger } from "./logger.js";import type { RenderConfig } from "./services/renderOrchestrator.js";import type { DistributedRenderConfig } from "./services/distributed/plan.js";@@ -262,9 +268,8 @@ export function renderConfigFromRequest(};}-function distributedFps(fps: Fps): 24 | 25 | 30 | 60 {- if (fps.den === 1 && (fps.num === 24 || fps.num === 25 || fps.num === 30 || fps.num === 60))- return fps.num;+function distributedFps(fps: Fps): DistributedFps {+ if (fps.den === 1 && isDistributedFps(fps.num)) return fps.num;throw new Error(`Distributed render does not support fps ${fps.num}/${fps.den}`);}diff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.tsindex ef9ea5c1e5..b6fabcefa4 100644--- a/packages/producer/src/services/distributed/plan.ts+++ b/packages/producer/src/services/distributed/plan.ts@@ -38,7 +38,7 @@ import {writeFileSync,} from "node:fs";import { extname, isAbsolute, join, relative, sep } from "node:path";-import { type CanvasResolution, fpsToNumber } from "@hyperframes/core";+import { type CanvasResolution, type DistributedFps, fpsToNumber } from "@hyperframes/core";import {type EngineConfig,type VideoFrameFormat,@@ -103,7 +103,7 @@ import {*/export interface DistributedRenderConfig {/** Integer frame rate. Distributed renders only accept integer fps; the in-process renderer's `Fps` rational handles NTSC. */- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;width: number;height: number;/**@@ -271,7 +271,7 @@ export interface LocalExecutionPlan {executionPlanHash: string;chunkCount: number;totalFrames: number;- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;width: number;height: number;format: DistributedFormat;@@ -307,7 +307,7 @@ export interface PlanResult {planHash: string;chunkCount: number;totalFrames: number;- fps: 24 | 25 | 30 | 60;+ fps: DistributedFps;width: number;height: number;format: DistributedFormat;diff --git a/packages/producer/src/services/distributed/planV2.test.ts b/packages/producer/src/services/distributed/planV2.test.tsindex 9c1be46b88..649554462d 100644--- a/packages/producer/src/services/distributed/planV2.test.ts+++ b/packages/producer/src/services/distributed/planV2.test.ts@@ -699,7 +699,7 @@ describe("Plan v2 manifest", () => {const root = tempPath("hf-plan-v2-fps-50-");const v1 = createV1Plan(root, { fpsNum: 50 });expect(() => createPlanV2FromV1(v1, join(root, "v2"))).toThrow(- "dimensions.fpsNum must be 24, 25, 30, or 60",+ "dimensions.fpsNum must be one of 24, 25, 30, 60",);});diff --git a/packages/producer/src/services/distributed/planV2.ts b/packages/producer/src/services/distributed/planV2.tsindex 02183f9bda..64df925a2a 100644--- a/packages/producer/src/services/distributed/planV2.ts+++ b/packages/producer/src/services/distributed/planV2.ts@@ -30,6 +30,7 @@ import {import { createHash } from "node:crypto";import { tmpdir } from "node:os";import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";+import { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "@hyperframes/core";import { createFrameLookupTable, type ExtractedFrames } from "@hyperframes/engine";import { recomputePlanHashFromPlanDir, type ChunkSliceJson } from "../render/stages/freezePlan.js";import { canonicalJsonStringify, sha256Hex } from "../render/stages/planHash.js";@@ -92,7 +93,7 @@ export interface PlanV2Manifest {readonly sourcePlanV1Hash: string;readonly chunkCount: number;readonly totalFrames: number;- readonly fps: 24 | 25 | 30 | 60;+ readonly fps: DistributedFps;readonly width: number;readonly height: number;readonly format: DistributedFormat;@@ -120,7 +121,7 @@ export interface PlanV2Result {readonly sourcePlanV1Hash: string;readonly chunkCount: number;readonly totalFrames: number;- readonly fps: 24 | 25 | 30 | 60;+ readonly fps: DistributedFps;readonly width: number;readonly height: number;readonly format: DistributedFormat;@@ -765,14 +766,16 @@ function readNonNegativeInteger(value: unknown, field: string): number {return value;}-function readSupportedFps(value: unknown): 24 | 25 | 30 | 60 {- if (value !== 24 && value !== 25 && value !== 30 && value !== 60) {- throw new PlanV2IntegrityError("dimensions.fpsNum must be 24, 25, 30, or 60");+function readSupportedFps(value: unknown): DistributedFps {+ if (!isDistributedFps(value)) {+ throw new PlanV2IntegrityError(+ `dimensions.fpsNum must be one of ${DISTRIBUTED_FPS.join(", ")}`,+ );}return value;}-function readExecutionPlanFps(dimensions: Record<string, unknown>): 24 | 25 | 30 | 60 {+function readExecutionPlanFps(dimensions: Record<string, unknown>): DistributedFps {const fpsDen = readPositiveInteger(dimensions.fpsDen, "dimensions.fpsDen");if (fpsDen !== 1) {throw new PlanV2IntegrityError("dimensions.fpsDen must be 1 for plan v2");diff --git a/packages/producer/src/services/distributed/renderConfigValidation.ts b/packages/producer/src/services/distributed/renderConfigValidation.tsindex 8b64f50656..fcbdc8bf92 100644--- a/packages/producer/src/services/distributed/renderConfigValidation.ts+++ b/packages/producer/src/services/distributed/renderConfigValidation.ts@@ -22,6 +22,7 @@ import {isVideoFrameFormat,validateEngineConfigSnapshot,} from "@hyperframes/engine";+import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";import { type DistributedFormat } from "./shared.js";import { type DistributedRenderConfig } from "./plan.js";@@ -48,7 +49,6 @@ export class InvalidConfigError extends Error {}}-const ALLOWED_FPS = [24, 25, 30, 60] as const;const ALLOWED_FORMATS = ["mp4","mov",@@ -80,10 +80,10 @@ export function validateDistributedRenderConfig(throw new InvalidConfigError("config", "must be an object");}- if (!ALLOWED_FPS.includes(config.fps as 24 | 25 | 30 | 60)) {+ if (!isDistributedFps(config.fps)) {throw new InvalidConfigError("config.fps",- `must be one of ${ALLOWED_FPS.join(", ")}; got ${String(config.fps)}`,+ `must be one of ${DISTRIBUTED_FPS.join(", ")}; got ${String(config.fps)}`,);}diff --git a/packages/producer/tests/README.md b/packages/producer/tests/README.mdindex 1bdeaa7b3f..57809e998d 100644--- a/packages/producer/tests/README.md+++ b/packages/producer/tests/README.md@@ -92,7 +92,7 @@ of these gates are **skipped** with a clear log line (and counted aspassing in the summary):- `fps.den !== 1` — distributed mode is integer-fps only (no NTSC).-- `fps.num ∉ {24, 25, 30, 60}` — closed set per `DistributedRenderConfig`.+- `fps.num` not in `DISTRIBUTED_FPS` (`@hyperframes/core`) — closed set per `DistributedRenderConfig`.- `format === "webm"` — `plan()` refuses webm.- `hdr === true` — distributed mode is SDR-only at v1.