Skip to content

Commit 0749cd9

Browse files
vanceingallsclaude
andcommitted
feat(producer): open the DE single-worker inversion to short comps under an element ceiling
31% of fleet renders (24h, v0.7.78+) are DE-eligible comps clamped to parallel screenshot purely because they sit under the 900-frame inversion floor — the median fleet render is ~250-600 frames, below every DE entry threshold. This opens a 250-899 frame band, gated on composition size. Measured, not assumed. A controlled sweep (fixed synthetic content, {250,400,600,900}f, single-DE vs parallel-screenshot-W4, 3 reps, capture mode verified per row, AC power, load-gated) showed single-DE winning 1.16-1.24x at every size — but only for content in constant motion. A follow-up 2x2 found motion and DOM size pull in OPPOSITE directions, so neither alone predicts the winner (ratio = ss4/de1, >1 means DE wins): 24 movers / 0 nodes -> 1.05 320 movers / 0 nodes -> 1.24 320 movers / 7000 nodes -> 1.09 24 movers / 7000 nodes -> 0.96 24 movers / 20000 nodes -> 0.71 24 movers / 40000 nodes -> 0.55 DE's wall-clock scales ~0.50ms/element against parallel screenshot's ~0.22ms — drawElement repaints the whole tree per frame while fan-out amortizes it — so the downside is NOT bounded and a bare floor drop would have handed a 1.8x regression to large comps. Since motion only ever helps DE, an element ceiling calibrated at the lowest-motion case is safe at every motion level; crossover there is ~3.9k, and the default sits at 2500. The predicate is untouched; the call site picks the floor. Above the ceiling, or at 900+ frames, behaviour is bit-identical to today — the change can only add inversions in the new band, never remove one. Instrumentation, since this ships at full exposure rather than cohorted: `composition_element_count` on EVERY render (the fleet distribution of the gate variable is unknown — without it we cannot tell whether 2500 opens the band for most short comps or almost none, nor re-derive the threshold from real content), and `de_short_band` = applied | skipped_elements, unset when the frame count made the band irrelevant, so a fleet perf shift is attributable to this change rather than to content mix. Safety is unchanged and already proven on this path: per-frame PSNR self-verify with screenshot fallback, exactly as the 900+ band has shipped default-on. Knobs: HF_DE_SHORT_MIN_FRAMES, HF_DE_SHORT_MAX_ELEMENTS (0 disables the band). Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 0d42d65 commit 0749cd9

7 files changed

Lines changed: 225 additions & 1 deletion

File tree

‎packages/cli/src/commands/render.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1433,6 +1433,8 @@ function trackRenderMetrics(
14331433
deClampReason: perf?.drawElement?.clampReason,
14341434
deWorkerInversion: perf?.drawElement?.workerInversion,
14351435
dePreInversionWorkers: perf?.drawElement?.preInversionWorkers,
1436+
compositionElementCount: perf?.drawElement?.compositionElementCount,
1437+
deShortBand: perf?.drawElement?.shortBand,
14361438
deParallelRouter: perf?.drawElement?.parallelRouter,
14371439
dePreRouterWorkers: perf?.drawElement?.preRouterWorkers,
14381440
deGateReason: perf?.drawElement?.gateReason,

‎packages/cli/src/telemetry/events.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ export interface RenderObservabilityTelemetryPayload {
7272
// the more authoritative perfSummary value wins when both are present.
7373
captureDeWorkerInversion?: string;
7474
captureDePreInversionWorkers?: number;
75+
captureCompositionElementCount?: number;
76+
captureDeShortBand?: string;
7577
captureDeParallelRouter?: string;
7678
captureDeGpuRenderer?: string;
7779
captureDePreRouterWorkers?: number;
@@ -130,6 +132,8 @@ function renderObservabilityEventProperties(props: RenderObservabilityTelemetryP
130132
capture_memory_exhaustion_detected: props.captureMemoryExhaustionDetected,
131133
de_worker_inversion: props.captureDeWorkerInversion,
132134
de_pre_inversion_workers: props.captureDePreInversionWorkers,
135+
composition_element_count: props.captureCompositionElementCount,
136+
de_short_band: props.captureDeShortBand,
133137
de_parallel_router: props.captureDeParallelRouter,
134138
gpu_renderer: props.captureDeGpuRenderer,
135139
de_pre_router_workers: props.captureDePreRouterWorkers,
@@ -204,6 +208,8 @@ export function trackRenderComplete(
204208
deClampReason?: string;
205209
deWorkerInversion?: string;
206210
dePreInversionWorkers?: number;
211+
compositionElementCount?: number;
212+
deShortBand?: string;
207213
deParallelRouter?: string;
208214
dePreRouterWorkers?: number;
209215
deGateReason?: string;
@@ -303,6 +309,8 @@ export function trackRenderComplete(
303309
de_clamp_reason: props.deClampReason,
304310
de_worker_inversion: props.deWorkerInversion,
305311
de_pre_inversion_workers: props.dePreInversionWorkers,
312+
composition_element_count: props.compositionElementCount,
313+
de_short_band: props.deShortBand,
306314
de_parallel_router: props.deParallelRouter,
307315
de_pre_router_workers: props.dePreRouterWorkers,
308316
de_gate_reason: props.deGateReason,

‎packages/cli/src/telemetry/renderObservability.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ export function renderObservabilityTelemetryPayload(
4242
captureMemoryExhaustionDetected: capture.memoryExhaustionDetected,
4343
captureDeWorkerInversion: capture.deWorkerInversion,
4444
captureDePreInversionWorkers: capture.dePreInversionWorkers,
45+
captureCompositionElementCount: capture.compositionElementCount,
46+
captureDeShortBand: capture.deShortBand,
4547
captureDeParallelRouter: capture.deParallelRouter,
4648
captureDeGpuRenderer: capture.deGpuRenderer,
4749
captureDePreRouterWorkers: capture.dePreRouterWorkers,

‎packages/producer/src/services/render/observability.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,26 @@ export interface RenderCaptureObservability {
7070
deWorkerInversion?: "inverted" | "reverted";
7171
/** Worker count the resolver would have used absent the inversion; undefined if it never fired. */
7272
dePreInversionWorkers?: number;
73+
/**
74+
* Rough element count of the compiled composition (`countElementTags`).
75+
*
76+
* Emitted on every render, not just inverted ones — this is the variable the
77+
* short-comp inversion band is gated on, and the fleet distribution of it is
78+
* unknown. Without it there is no way to tell whether the 2500 ceiling opens
79+
* the band for most short comps or almost none, and no way to re-derive the
80+
* threshold from real content instead of synthetic sweeps.
81+
*/
82+
compositionElementCount?: number;
83+
/**
84+
* Why the short-comp band did or did not apply to this render:
85+
* "applied" (frames landed in 250-899 and the element count cleared the
86+
* ceiling), "skipped_elements" (band was open by frame count but the comp
87+
* was too large), or undefined when the frame count made the band
88+
* irrelevant either way. Distinguishes "the new routing chose this" from
89+
* "the pre-existing 900 floor chose this" — otherwise a fleet perf shift is
90+
* unattributable.
91+
*/
92+
deShortBand?: "applied" | "skipped_elements";
7393
/** DE parallel-router outcome: "routed" (fired, held) | "reverted" (fired, self-verify retry rolled back). */
7494
deParallelRouter?: "routed" | "reverted";
7595
/**

‎packages/producer/src/services/render/perfSummary.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,10 @@ export interface DrawElementPerfInput {
8080
workerInversion?: "inverted" | "reverted";
8181
/** Auto-resolved worker count before the inversion pinned it to 1 (set only when the inversion fired). */
8282
preInversionWorkers?: number;
83+
/** Rough compiled-composition element count — gate variable for the short-comp inversion band. */
84+
compositionElementCount?: number;
85+
/** Short-comp band attribution: "applied" | "skipped_elements"; unset when the band was irrelevant. */
86+
shortBand?: string;
8387
parallelRouter?: "routed" | "reverted";
8488
/** Auto-resolved worker count before the router pinned it to 3 (set only when the router fired). */
8589
preRouterWorkers?: number;
@@ -121,6 +125,8 @@ function aggregateDrawElement(
121125
clampReason: de.clampReason,
122126
workerInversion: de.workerInversion ?? "none",
123127
preInversionWorkers: de.preInversionWorkers,
128+
compositionElementCount: de.compositionElementCount,
129+
shortBand: de.shortBand,
124130
parallelRouter: de.parallelRouter ?? "none",
125131
preRouterWorkers: de.preRouterWorkers,
126132
gateReason: gateReasons.length > 0 ? gateReasons.join("|") : undefined,

‎packages/producer/src/services/renderOrchestrator.test.ts‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ import {
3434
resolveParallelRouterRetryPlan,
3535
resetCaptureAttemptProgress,
3636
shouldRetryViaPinnedFallback,
37+
countElementTags,
38+
envInt,
3739
shouldPreferParallelDrawElement,
3840
shouldPreferSingleWorkerDrawElement,
3941
shouldStreamParallelCapture,
@@ -1693,6 +1695,108 @@ describe("shouldPreferSingleWorkerDrawElement (DE priority inversion)", () => {
16931695
expect(shouldPreferSingleWorkerDrawElement(eligible)).toBe(true);
16941696
});
16951697

1698+
// ── Short-comp band ────────────────────────────────────────────────────
1699+
// The band lowers the effective floor from 900 to 250 for SMALL comps only.
1700+
// The predicate itself is unchanged — the call site picks the floor — so
1701+
// these pin the arithmetic the call site performs.
1702+
//
1703+
// Measured basis (400f, single-DE vs parallel-screenshot-W4, 2 reps, ratio
1704+
// = ss4/de1 so >1 means DE wins):
1705+
// 24 movers / 0 nodes -> 1.05 DE wins
1706+
// 320 movers / 0 nodes -> 1.24 DE wins
1707+
// 320 movers / 7000 nodes -> 1.09 DE wins
1708+
// 24 movers / 7000 nodes -> 0.96 DE LOSES
1709+
// 24 movers / 20000 nodes -> 0.71 DE loses badly
1710+
// 24 movers / 40000 nodes -> 0.55 DE loses very badly
1711+
// Motion helps DE, DOM size punishes it; the ceiling is calibrated at the
1712+
// lowest-motion case so every higher-motion comp is covered too.
1713+
describe("short-comp band floor arithmetic", () => {
1714+
const shortBandFloor = (elementCount: number, maxElements = 2500): number =>
1715+
elementCount <= maxElements ? Math.min(900, 250) : 900;
1716+
1717+
it("opens the 250-frame floor for a small comp", () => {
1718+
expect(shortBandFloor(800)).toBe(250);
1719+
expect(
1720+
shouldPreferSingleWorkerDrawElement({
1721+
...eligible,
1722+
totalFrames: 400,
1723+
minFrames: shortBandFloor(800),
1724+
}),
1725+
).toBe(true);
1726+
});
1727+
1728+
it("keeps the 900-frame floor for a large comp — the measured 1.8x regression case", () => {
1729+
expect(shortBandFloor(40000)).toBe(900);
1730+
expect(
1731+
shouldPreferSingleWorkerDrawElement({
1732+
...eligible,
1733+
totalFrames: 400,
1734+
minFrames: shortBandFloor(40000),
1735+
}),
1736+
).toBe(false);
1737+
});
1738+
1739+
it("never RAISES the floor: a large comp at 900+ frames still inverts as it did before", () => {
1740+
expect(
1741+
shouldPreferSingleWorkerDrawElement({
1742+
...eligible,
1743+
totalFrames: 2380,
1744+
minFrames: shortBandFloor(40000),
1745+
}),
1746+
).toBe(true);
1747+
});
1748+
1749+
it("leaves comps below the band floor alone", () => {
1750+
expect(
1751+
shouldPreferSingleWorkerDrawElement({
1752+
...eligible,
1753+
totalFrames: 200,
1754+
minFrames: shortBandFloor(800),
1755+
}),
1756+
).toBe(false);
1757+
});
1758+
});
1759+
1760+
describe("countElementTags", () => {
1761+
it("counts closing tags", () => {
1762+
expect(countElementTags("<div><span>a</span></div>")).toBe(2);
1763+
});
1764+
1765+
it("undercounts void elements — biases the count DOWN, so the ceiling must stay conservative", () => {
1766+
expect(countElementTags("<img><br><hr>")).toBe(0);
1767+
});
1768+
1769+
it("is stable on empty and malformed input rather than throwing", () => {
1770+
expect(countElementTags("")).toBe(0);
1771+
expect(countElementTags("<<<>>>")).toBe(0);
1772+
});
1773+
1774+
it("scales to a large document without a full parse", () => {
1775+
expect(countElementTags("<p>x</p>".repeat(40000))).toBe(40000);
1776+
});
1777+
});
1778+
1779+
describe("envInt", () => {
1780+
afterEach(() => {
1781+
delete process.env.HF_TEST_ENV_INT;
1782+
});
1783+
1784+
it("falls back when unset, empty, or non-numeric — a typo must not disable a guard", () => {
1785+
expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(2500);
1786+
process.env.HF_TEST_ENV_INT = "";
1787+
expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(2500);
1788+
process.env.HF_TEST_ENV_INT = "lots";
1789+
expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(2500);
1790+
});
1791+
1792+
it("reads an explicit value, including 0 as a real disable", () => {
1793+
process.env.HF_TEST_ENV_INT = "700";
1794+
expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(700);
1795+
process.env.HF_TEST_ENV_INT = "0";
1796+
expect(envInt("HF_TEST_ENV_INT", 2500)).toBe(0);
1797+
});
1798+
});
1799+
16961800
it("honors explicitly requested workers", () => {
16971801
expect(shouldPreferSingleWorkerDrawElement({ ...eligible, requestedWorkers: 3 })).toBe(false);
16981802
});

‎packages/producer/src/services/renderOrchestrator.ts‎

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -492,6 +492,10 @@ export interface RenderPerfSummary {
492492
workerInversion?: string;
493493
/** Worker count the auto-resolution chose BEFORE the inversion pinned it to 1 — the parallel counterfactual for speedup math. Only set when the inversion fired. */
494494
preInversionWorkers?: number;
495+
/** Rough compiled-composition element count — the variable the short-comp inversion band is gated on. Always set. */
496+
compositionElementCount?: number;
497+
/** Short-comp band attribution: "applied" | "skipped_elements"; unset when the frame count made the band irrelevant. */
498+
shortBand?: string;
495499
/** DE parallel-router outcome: "routed" (fired, held), "reverted" (fired, self-verify retry rolled back), "none". Mutually exclusive with workerInversion. */
496500
parallelRouter?: string;
497501
/** Worker count the auto-resolution chose BEFORE the router pinned it to 3 — the single-worker-inversion counterfactual. Only set when the router fired. */
@@ -1222,6 +1226,37 @@ export function shouldUseStreamingEncode(
12221226
return workerCount === 1;
12231227
}
12241228

1229+
/**
1230+
* Integer tuning knob from the environment. Matches the convention the
1231+
* surrounding DE thresholds already use: unset OR set-but-empty falls back to
1232+
* the default (a blank var is not a kill switch), and so does anything
1233+
* non-numeric — a typo must never silently disable a routing guard.
1234+
*/
1235+
export function envInt(name: string, fallback: number): number {
1236+
const raw = process.env[name];
1237+
if (raw === undefined || raw.trim() === "") return fallback;
1238+
const parsed = Number(raw);
1239+
return Number.isFinite(parsed) ? parsed : fallback;
1240+
}
1241+
1242+
/**
1243+
* Rough element count for compiled composition HTML.
1244+
*
1245+
* Deliberately a string scan and not a `parseHTML` + `querySelectorAll` (the
1246+
* `countAuthoredTimedClips` approach): this runs on EVERY render before the
1247+
* routing decision, and a full linkedom parse of the exact documents that
1248+
* matter here — the 20k-40k node ones — is the most expensive case. Precision
1249+
* is not needed. It feeds a threshold whose measured crossover is ~3.9k and
1250+
* whose default sits at 2500, so counting closing tags is comfortably inside
1251+
* the margin. Undercounts void elements (`<img>`, `<br>`) and self-closing
1252+
* SVG nodes, which biases the count DOWN — the direction that opens the band
1253+
* — so the ceiling is the thing to keep conservative.
1254+
*/
1255+
export function countElementTags(html: string): number {
1256+
const matches = html.match(/<\/[a-zA-Z]/g);
1257+
return matches === null ? 0 : matches.length;
1258+
}
1259+
12251260
/**
12261261
* DE priority inversion predicate: should an AUTO-resolved multi-worker render
12271262
* drop to single-worker verified drawElement streaming?
@@ -2405,6 +2440,38 @@ async function executeRenderPipeline(input: {
24052440
? 900
24062441
: Number(deSingleMinFramesRaw);
24072442
const deSingleMinFrames = Number.isFinite(deSingleMinFramesNum) ? deSingleMinFramesNum : 900;
2443+
// Short-comp band: 31% of fleet renders (24h, 0.7.78+) are DE-eligible
2444+
// comps clamped to parallel screenshot purely because they sit under this
2445+
// floor. A controlled sweep (fixed synthetic content, {250,400,600,900}f,
2446+
// single-DE vs parallel-screenshot-W4, 3 reps, capture modes verified per
2447+
// run) showed single-DE winning 1.16-1.24x at EVERY size — but only for
2448+
// content in constant motion. A follow-up 2x2 (movers x static DOM nodes)
2449+
// found the two variables pull in opposite directions: motion favours DE,
2450+
// DOM size punishes it, and DE's wall-clock scales ~0.50ms/node against
2451+
// parallel screenshot's ~0.22ms (drawElement repaints the whole tree per
2452+
// frame; fan-out amortizes it). At 24 movers / 400f the measured curve is
2453+
// +5% for DE at 0 nodes, -4% at 7k, -41% at 20k, -80% at 40k — crossover
2454+
// near ~3.9k. Since motion only ever helps DE, a node ceiling calibrated
2455+
// at the LOWEST-motion case is safe for every motion level, so the short
2456+
// band opens only below `deShortBandMaxElements`. Above it the original
2457+
// 900 floor stands, unchanged.
2458+
const deShortBandMinFrames = envInt("HF_DE_SHORT_MIN_FRAMES", 250);
2459+
const deShortBandMaxElements = envInt("HF_DE_SHORT_MAX_ELEMENTS", 2500);
2460+
const compositionElementCount = countElementTags(compiled.html);
2461+
const deShortBandOpen =
2462+
deShortBandMinFrames > 0 &&
2463+
deShortBandMaxElements > 0 &&
2464+
compositionElementCount <= deShortBandMaxElements;
2465+
const deEffectiveMinFrames = deShortBandOpen
2466+
? Math.min(deSingleMinFrames, deShortBandMinFrames)
2467+
: deSingleMinFrames;
2468+
// Does the band even matter for this render? Only when the frame count
2469+
// falls in the newly-opened window — at or above the original floor the
2470+
// inversion fires regardless, and below `deShortBandMinFrames` nothing
2471+
// fires either way. Keeps the telemetry reason from claiming credit (or
2472+
// blame) on renders the change could not have affected.
2473+
const deShortBandApplies =
2474+
totalFrames >= deShortBandMinFrames && totalFrames < deSingleMinFrames;
24082475
// "Would ANY multi-worker resolution be inverted?" — if workers resolve
24092476
// to 1 naturally the outcome is identical either way.
24102477
const WOULD_RESOLVE_MULTI_WORKER = 2;
@@ -2416,7 +2483,7 @@ async function executeRenderPipeline(input: {
24162483
forceScreenshot: captureForceScreenshot,
24172484
outputFormat,
24182485
totalFrames,
2419-
minFrames: deSingleMinFrames,
2486+
minFrames: deEffectiveMinFrames,
24202487
singleWorkerStreamingOk: shouldUseStreamingEncode(cfg, outputFormat, 1, job.duration),
24212488
layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
24222489
supersampling: deviceScaleFactor > 1,
@@ -2678,6 +2745,15 @@ async function executeRenderPipeline(input: {
26782745
// any resource-pressure failure unique to this cohort.
26792746
dePreInversionWorkers: deWorkerInversion ? preRoutingWorkerCount : undefined,
26802747
dePreRouterWorkers: deParallelRouter ? preRoutingWorkerCount : undefined,
2748+
// Short-comp band attribution — see the field docs. Emitted on every
2749+
// render so the fleet element-count distribution is readable, and so a
2750+
// perf shift can be split into "the new band did it" vs "unchanged".
2751+
compositionElementCount,
2752+
deShortBand: deShortBandApplies
2753+
? deShortBandOpen
2754+
? "applied"
2755+
: "skipped_elements"
2756+
: undefined,
26812757
// Same rationale as the counters above: carried on live capture
26822758
// observability, not only the success-path perfSummary, so a crash /
26832759
// OOM / timeout still reports which GPU backend it happened on. That
@@ -3524,6 +3600,12 @@ async function executeRenderPipeline(input: {
35243600
clampReason: deClampReason,
35253601
workerInversion: deWorkerInversion,
35263602
preInversionWorkers: deWorkerInversion ? preRoutingWorkerCount : undefined,
3603+
compositionElementCount,
3604+
shortBand: deShortBandApplies
3605+
? deShortBandOpen
3606+
? "applied"
3607+
: "skipped_elements"
3608+
: undefined,
35273609
parallelRouter: deParallelRouter,
35283610
preRouterWorkers: deParallelRouter ? preRoutingWorkerCount : undefined,
35293611
selfVerifyFallback: deSelfVerifyFallback,

0 commit comments

Comments
 (0)