From 651de1d948b0f619001e3705cba98fa415baf0dd Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Mon, 9 Nov 2026 23:42:50 +0000 Subject: [PATCH] feat(cli): carry the motion blur summary on the @hf-result line (#7468) Co-authored-by: Claude Sonnet 5.5 --- packages/cli/README.md | 7 +- packages/cli/src/commands/render.ts | 3 + .../cli/src/commands/render/execute.test.ts | 21 ++++ .../cli/src/telemetry/renderMotionBlur.ts | 29 ++++++ packages/cli/src/ui/renderResult.test.ts | 97 +++++++++++++++++++ packages/cli/src/ui/renderResult.ts | 19 ++-- 6 files changed, 167 insertions(+), 9 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index 6ea539e359..0e52cddbf0 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -104,8 +104,11 @@ Piped, non-quiet renders also emit a single `@hf-result ` JSON line after a loca render succeeds, never after a failure. Version 1 has `operation: "render"` and `reference_background`, the background the render measured from the composition's root and body: `{"kind":"solid","rgb":[r,g,b]}`, `{"kind":"none"}`, -`{"kind":"unsupported_non_solid"}` or `{"kind":"unknown"}`. Consumers must ignore -unknown versions and fields. A `--docker` render prints no result line from the +`{"kind":"unsupported_non_solid"}` or `{"kind":"unknown"}`. A render that applied +motion blur also carries `motion_blur`: `tier` (`"capture"` or `"filter"`, absent +when none ran), `movers`, `failed_frames` and a `fingerprint` of 14 snake_case +counts (absent when the page produced none); it is absent when the render has no +blur summary. Consumers must ignore unknown versions and fields. A `--docker` render prints no result line from the launcher. In batch mode each manifest row carries the same `reference_background` value (`null` until the row completes, and for a row that failed). diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 3f8d7fa44b..dc384d75e0 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -150,6 +150,7 @@ import type { ProducerLogger, RenderJob, RenderPerfSummary } from "@hyperframes/ import { EXTRACT_CACHE_DIR_DISABLED_ALIASES, sandboxDeniedRemediation, + type PageMotionBlurSummary, type ProresProfile, type VideoFrameFormat, } from "@hyperframes/engine"; @@ -509,6 +510,7 @@ export default defineCommand({ }); export interface SingleRenderResult extends Partial { + motionBlur?: PageMotionBlurSummary; durationMs?: number; renderTimeMs: number; outcome?: "completed" | "completed_with_warnings"; @@ -1304,6 +1306,7 @@ async function executeLocalRender( job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed"; return { ...producer.referenceBackgroundResult(job[producer.REFERENCE_BACKGROUND_FIELD]), + motionBlur: job.perfSummary?.motionBlur, renderTimeMs: elapsed, durationMs, outcome, diff --git a/packages/cli/src/commands/render/execute.test.ts b/packages/cli/src/commands/render/execute.test.ts index 9b63a17c2c..2dc5133eaf 100644 --- a/packages/cli/src/commands/render/execute.test.ts +++ b/packages/cli/src/commands/render/execute.test.ts @@ -175,6 +175,27 @@ describe("the machine result line after a single render", () => { }); }); + it("prints the motion blur summary beside the background", async () => { + const lines = await resultLines({ + renderTimeMs: 5, + reference_background: { kind: "none" }, + motionBlur: { + tier: "capture", + reasonCode: null, + movers: 2, + failedFrames: 1, + readEvents: true, + fingerprint: null, + }, + }); + expect(JSON.parse((lines[0] ?? "").slice("@hf-result ".length))).toEqual({ + version: 1, + operation: "render", + reference_background: { kind: "none" }, + motion_blur: { tier: "capture", movers: 2, failed_frames: 1 }, + }); + }); + it("prints nothing when the render fails", async () => { expect(await resultLines(new Error("capture failed"))).toEqual([]); }); diff --git a/packages/cli/src/telemetry/renderMotionBlur.ts b/packages/cli/src/telemetry/renderMotionBlur.ts index 6efbf4e2d2..d867a42bc3 100644 --- a/packages/cli/src/telemetry/renderMotionBlur.ts +++ b/packages/cli/src/telemetry/renderMotionBlur.ts @@ -36,3 +36,32 @@ export function renderMotionBlurEventProperties( ...Object.fromEntries(counts), }; } + +export interface RenderMotionBlurResult { + tier?: "capture" | "filter"; + movers: number; + failed_frames: number; + fingerprint?: Record; +} + +const count = (value: unknown): number => + typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0; + +export function renderMotionBlurResult(motionBlur: PageMotionBlurSummary): RenderMotionBlurResult { + const { tier, fingerprint } = motionBlur; + return { + ...(tier === "capture" || tier === "filter" ? { tier } : {}), + movers: count(motionBlur.movers), + failed_frames: count(motionBlur.failedFrames), + ...(fingerprint + ? { + fingerprint: Object.fromEntries( + MOTION_BLUR_FINGERPRINT_FIELDS.map((field) => [ + snake(field), + count(fingerprint[field]), + ]), + ), + } + : {}), + }; +} diff --git a/packages/cli/src/ui/renderResult.test.ts b/packages/cli/src/ui/renderResult.test.ts index ce3dbc16a5..b74ee460c1 100644 --- a/packages/cli/src/ui/renderResult.test.ts +++ b/packages/cli/src/ui/renderResult.test.ts @@ -1,5 +1,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import type { ReferenceBackground } from "@hyperframes/producer"; +import type { PageMotionBlurSummary } from "@hyperframes/engine"; +import { MOTION_BLUR_FINGERPRINT_FIELDS } from "@hyperframes/core"; import { renderMachineResult } from "./renderResult.js"; const originalIsTTY = process.stdout.isTTY; @@ -68,4 +70,99 @@ describe("renderMachineResult", () => { vi.stubEnv("HYPERFRAMES_STDOUT_IS_TTY", "1"); expect(capture(() => renderMachineResult(result, false))).toBe(""); }); + + describe("motion blur summary", () => { + const summary = (over: Partial = {}): PageMotionBlurSummary => ({ + tier: "filter", + reasonCode: "accelerated-canvas", + movers: 4, + failedFrames: 2, + readEvents: true, + fingerprint: { + ...Object.fromEntries(MOTION_BLUR_FINGERPRINT_FIELDS.map((field) => [field, 0])), + canvas2d: 3, + threeD: 1, + } as NonNullable, + ...over, + }); + + it("carries tier, movers, failed frames and all fingerprint counts next to the background", () => { + const line = capture(() => + renderMachineResult( + { reference_background: { kind: "none" }, motionBlur: summary() }, + false, + ), + ); + const parsed = parse(line) as { motion_blur: { fingerprint: Record } }; + expect(parsed).toEqual({ + version: 1, + operation: "render", + reference_background: { kind: "none" }, + motion_blur: { + tier: "filter", + movers: 4, + failed_frames: 2, + fingerprint: expect.objectContaining({ canvas2d: 3, three_d: 1, svg_clip: 0 }), + }, + }); + expect(Object.keys(parsed.motion_blur.fingerprint)).toHaveLength(14); + }); + + it("omits motion_blur when the render has no summary", () => { + const line = capture(() => + renderMachineResult({ reference_background: { kind: "none" } }, false), + ); + expect(parse(line)).toEqual({ + version: 1, + operation: "render", + reference_background: { kind: "none" }, + }); + }); + + it("prints a line for a summary alone, without inventing a background", () => { + const line = capture(() => renderMachineResult({ motionBlur: summary() }, false)); + const parsed = parse(line) as Record; + expect(parsed).not.toHaveProperty("reference_background"); + expect(parsed).toHaveProperty("motion_blur"); + }); + + it("omits tier and fingerprint when the summary has none", () => { + const line = capture(() => + renderMachineResult( + { motionBlur: summary({ tier: null, fingerprint: null, movers: 0, failedFrames: 0 }) }, + false, + ), + ); + expect(parse(line)).toEqual({ + version: 1, + operation: "render", + motion_blur: { movers: 0, failed_frames: 0 }, + }); + }); + + it("never prints free text, whatever the summary carries", () => { + const line = capture(() => + renderMachineResult( + { + motionBlur: summary({ + reasonCode: "/private/clip.mp4 #secret-selector", + tier: "/private/tier" as never, + movers: "/private/movers" as never, + }), + }, + false, + ), + ); + expect(line).not.toContain("/private"); + expect(line).not.toContain("secret"); + expect(line).not.toContain("reason"); + expect(line).not.toContain("accelerated-canvas"); + expect(parse(line)).toMatchObject({ motion_blur: { movers: 0 } }); + }); + + it("stays silent for quiet mode and a terminal even with a summary", () => { + expect(capture(() => renderMachineResult({ motionBlur: summary() }, true))).toBe(""); + expect(capture(() => renderMachineResult({ motionBlur: summary() }, false), true)).toBe(""); + }); + }); }); diff --git a/packages/cli/src/ui/renderResult.ts b/packages/cli/src/ui/renderResult.ts index 468344d934..02c69a4227 100644 --- a/packages/cli/src/ui/renderResult.ts +++ b/packages/cli/src/ui/renderResult.ts @@ -3,18 +3,23 @@ import { referenceBackgroundResult, type ReferenceBackgroundResult, } from "@hyperframes/producer"; +import type { PageMotionBlurSummary } from "@hyperframes/engine"; +import { renderMotionBlurResult } from "../telemetry/renderMotionBlur.js"; -/** Versioned, content-free success line for a piped CLI: the background the render measured, never a path or a word of the composition. */ -export function renderMachineResult( - result: Partial, - quiet: boolean, -): void { +export interface RenderMachineResultInput extends Partial { + motionBlur?: PageMotionBlurSummary; +} + +/** Versioned, content-free success line for a piped CLI: the background and motion blur counts the render measured, never a path or a word of the composition. */ +export function renderMachineResult(result: RenderMachineResultInput, quiet: boolean): void { if (quiet || process.stdout.isTTY || process.env.HYPERFRAMES_STDOUT_IS_TTY === "1") return; - if (!(REFERENCE_BACKGROUND_FIELD in result)) return; + const hasBackground = REFERENCE_BACKGROUND_FIELD in result; + if (!hasBackground && !result.motionBlur) return; const line = { version: 1, operation: "render", - ...referenceBackgroundResult(result[REFERENCE_BACKGROUND_FIELD]), + ...(hasBackground ? referenceBackgroundResult(result[REFERENCE_BACKGROUND_FIELD]) : {}), + ...(result.motionBlur ? { motion_blur: renderMotionBlurResult(result.motionBlur) } : {}), }; process.stdout.write(`@hf-result ${JSON.stringify(line)}\n`); }