Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(core): settle slow documents against their own frame cadence (#5168)
Miguel Ángelda6259896b5d
diff --git a/docs/contracts/2026-10-07-document-idle-readiness.html b/docs/contracts/2026-10-07-document-idle-readiness.htmlnew file mode 100644index 0000000000..3d6b3a46ef--- /dev/null+++ b/docs/contracts/2026-10-07-document-idle-readiness.html@@ -0,0 +1,67 @@+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Document-relative readiness contract</title><style>+:root{color-scheme:light dark;+ --bg:#fbfbfa;--card:#ffffff;--line:#e6e4df;--ink:#1c1c1a;--dim:#6b6b66;--faint:#9a9a94;+ --go:#178a5a;--go-bg:#e8f6ee;--warn:#a6690a;--warn-bg:#fbf1dc;--bad:#c0392b;--bad-bg:#fbe7e4;--info:#2a5db0;--info-bg:#e8eefb;+ --mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}+@media (prefers-color-scheme:dark){:root{--bg:#111213;--card:#191b1d;--line:#2a2d31;--ink:#ecebe8;--dim:#a2a29c;--faint:#6f6f6a;+ --go:#5fd39a;--go-bg:#12291f;--warn:#e6b35a;--warn-bg:#2b2311;--bad:#ff7b6b;--bad-bg:#2d1714;--info:#7fa9ff;--info-bg:#15203a}}+*{box-sizing:border-box}+body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.55 var(--sans)}+.wrap{max-width:900px;margin:0 auto;padding:56px 24px 96px}+header h1{font-size:30px;line-height:1.15;letter-spacing:-.4px;margin:0 0 10px}+header .what{font-size:18px;color:var(--dim);margin:0 0 18px;max-width:70ch}+.strip{display:flex;gap:10px;flex-wrap:wrap;align-items:center;font:13px var(--mono);color:var(--faint)}+.strip .sep{opacity:.5}+.pill{display:inline-flex;align-items:center;gap:6px;font:600 12px/1 var(--mono);padding:6px 10px;border-radius:999px;white-space:nowrap}+.pill.go{color:var(--go);background:var(--go-bg)}.pill.warn{color:var(--warn);background:var(--warn-bg)}+.pill.bad{color:var(--bad);background:var(--bad-bg)}.pill.info{color:var(--info);background:var(--info-bg)}+.pill b{font-size:13px}+section{margin-top:56px}+h2{font-size:22px;letter-spacing:-.3px;margin:0 0 6px}+.sub{color:var(--dim);margin:0 0 18px;font-size:15px}+.card{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:20px 22px;margin:14px 0}+.breath{border-left:4px solid var(--go);font-size:18px;line-height:1.5}+.breath b{color:var(--go)}+.plain{color:var(--dim);font-size:15px;margin:0 0 10px}+.plain::before{content:"In plain words ";font:600 11px var(--mono);letter-spacing:1px;color:var(--faint);text-transform:uppercase}+pre{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font:13px/1.55 var(--mono);margin:10px 0}+code{font:13px var(--mono);background:var(--bg);border:1px solid var(--line);border-radius:5px;padding:1px 6px}+.cite{font:12px var(--mono);color:var(--faint);margin-top:8px;display:block}+.states{display:flex;gap:8px;margin:12px 0 4px;flex-wrap:wrap}+table{width:100%;border-collapse:collapse;margin:10px 0;font-size:14.5px}+th{text-align:left;font:600 11px/1.4 var(--mono);text-transform:uppercase;letter-spacing:.7px;color:var(--faint);border-bottom:1px solid var(--line);padding:8px 10px}+td{padding:10px;border-bottom:1px solid var(--line);vertical-align:top}+tr:last-child td{border-bottom:0}+td.k{font:13px var(--mono);white-space:nowrap}+.decision{border-left:4px solid var(--info)}+.decision h3{margin:0 0 8px;font-size:17px}+.decision .ask{color:var(--info);font-weight:600}+blockquote{margin:12px 0;padding:8px 0 8px 16px;border-left:2px solid var(--line);color:var(--dim);font-style:italic;font-size:14.5px}+blockquote .src{display:block;font-style:normal;font:12px var(--mono);color:var(--faint);margin-top:6px}+ul,ol{padding-left:22px}li{margin:6px 0}+.mermaid{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:18px;margin:14px 0;overflow:auto}+.mermaid svg{max-width:100%}+footer{margin-top:72px;padding-top:16px;border-top:1px solid var(--line);font:12px/1.7 var(--mono);color:var(--faint)}+</style></head><body><main class="wrap">+<header><h1>Idle against the document's own frame gaps</h1><p class="what">Keep the timeline in step with the picture while removing the slow-document readiness hold.</p><div class="strip">hyperframes · implementation audited at 23b8c9c8 · 2026-10-07 · audited 8 · trusting 0 · not exercised 2 · decisions 0</div></header>+<section class="card breath"><b>In one breath.</b> Core owns the paint-and-idle decision; the player reports painted only after loader clearance, and Studio commits the shadow timeline when that picture becomes live.</section>+<section><h2>Where the value travels</h2><div class="card">Document frame timestamps → core settlement → player assetsready → loader hidden → painted → Studio readyToShow → shadow promotion and timeline commit</div></section>+<section><h2>The contract, per boundary</h2>+<div class="card"><h3>Core paint-and-idle input</h3><p class="plain">The established under-50 ms path remains exact. Slower gaps qualify up to 1.5x the shortest gap observed in this wait. Two consecutive qualifying gaps settle early; continuing stalls retain the existing 1.5-second cap.</p><pre>export function paintAndIdleReadinessInput(+ doc: Document,+ signal: AbortSignal,+): Promise<void> | null</pre><span class="cite">Producer packages/core/src/compositionReadiness.ts:271; consumer :316 and :323. First-frame wrapper :357 supplies scope.</span><div class="states"><span class="pill go">exists</span><span class="pill go">reachable</span><span class="pill go">read and written</span></div></div>+<div class="card"><h3>Player settlement</h3><p class="plain">The player calls core for an accessible document. A generation check rejects stale loads before readiness is emitted.</p><pre>settleFirstFrameCompositionReadiness(doc, ({ timedOut }) => {+ if (generation !== this._assetsGeneration) return;+ if (timedOut) this._warnStuckAssets(doc);+ this._settleAssetsReady(generation);+}, { timeoutMs: ASSETS_READY_TIMEOUT_MS });</pre><span class="cite">Producer/consumer packages/player/src/hyperframes-player.ts:1343; settlement :1396; painted write :1405. Loader consumer packages/player/src/shader-loader-state.ts:55.</span><div class="states"><span class="pill go">exists</span><span class="pill go">reachable</span><span class="pill go">read and written</span></div></div>+<div class="card"><h3>Studio and timeline promotion</h3><p class="plain">An empty or slow timeline must not be committed ahead of its picture.</p><pre>const readyToShow = firstFrameShown && !assetsLoading;+iframeRef.current = shadow;+pending.commit();</pre><span class="cite">Readiness producer packages/studio/src/player/components/Player.tsx:435-456. Consumer packages/studio/src/player/hooks/useShadowPreviewReload.ts:243; gate :162; live iframe and timeline writes :182-183.</span><div class="states"><span class="pill go">exists</span><span class="pill go">reachable</span><span class="pill go">read and written</span></div></div><div class="card"><h3>Runtime and Studio Play callers</h3><p class="plain">The same core gate serves runtime-reported first-frame readiness and Studio's full-timeline Play gate.</p><pre>postRuntimeMessage({ source: "hf-preview", type: "assets-ready", timedOut });+if (generation === timelineReadyGeneration) set({ timelineReady: true });</pre><span class="cite">Runtime producer packages/core/src/runtime/init.ts:3282-3285; message consumer packages/player/src/runtime-message-handler.ts:103 and generation-gated callback packages/player/src/hyperframes-player.ts:1250-1252. Studio producer/consumer packages/studio/src/player/store/readinessSlice.ts:45-46.</span><div class="states"><span class="pill go">exists</span><span class="pill go">reachable</span><span class="pill go">read and written</span></div></div></section>+<section><h2>How it says no</h2><table><tr><th>Signal</th><th>Meaning and action</th></tr><tr><td>null</td><td>No document window, no paint input is pending.</td></tr><tr><td>AbortSignal</td><td>Shared timeout or completion cancels remaining frame requests.</td></tr><tr><td>timedOut: true</td><td>Shared 8-second wait elapsed. Player warns and continues; this is not proof of idle.</td></tr><tr><td>Generation mismatch</td><td>Old load cannot mark the current picture ready.</td></tr></table></section>+<section><h2>Chosen rule after measurement</h2><div class="card"><h3>1.5x the shortest gap in the current readiness attempt</h3><p>Fast gaps retain the strict < 50 ms comparison, including zero timestamps. Above that path, two consecutive relative gaps must qualify. A slower gap resets the streak. The existing paint cap, shared timeout and abort semantics remain.</p><table><tr><th>Tolerance</th><th>Unsettled ordinary windows after nine gaps</th><th>Worst observed settlement</th></tr><tr><td>1.1x</td><td>2 / 183</td><td>500 ms among those that settled</td></tr><tr><td>1.25x</td><td>2 / 183</td><td>500 ms among those that settled</td></tr><tr><td>1.5x</td><td>0 / 183</td><td>350 ms</td></tr><tr><td>1.75x</td><td>0 / 183</td><td>233 ms</td></tr></table><p>1.5x is the smallest tested tolerance that covers every ordinary window. The baseline belongs to one bounded readiness attempt and never rises during that attempt. These are overlapping nine-gap windows from nine controlled browser traces, excluding windows containing the deliberately injected burst. They are not independent trials. The injected 250 ms gap exceeds the selected threshold.</p><p>Sixfold CPU throttling, inline content and 60 ms frame work: main settles steady-slow in 1682 to 1701 ms, jittered in 1652 to 1703 ms, and burst/recovery in 1637 to 1686 ms. Final candidate at 23b8c9c8: 352 to 429 ms, 368 to 376 ms and 603 to 622 ms respectively, three runs each. Timer begins before the first workload; these wall times include that work and scheduling. Concurrent machine activity limits absolute timing claims.</p><p>Stable cadence is not proof of completed computation. The separate compute, media, loader and generation gates retain their authority.</p></div></section>+<section><h2>Coverage, honestly</h2><table><tr><th>Audited</th><td>Eight modules at implementation 23b8c9c8: core input/orchestrator, player caller and generation checks, loader callback, Studio Player, shadow promotion, runtime message producer, runtime message consumer, and Studio Play caller. Core ran in a throttled browser; existing consumer tests passed.</td></tr><tr><th>Trusting</th><td>No mapped boundary relies solely on a type or comment.</td></tr><tr><th>Not exercised</th><td>Full Studio reload and opaque-origin message delivery in a real browser. DOM-harness consumer tests cover their corresponding guards.</td></tr></table></section>+<section><h2>What would prove this page wrong</h2><ul><li>A steady slow document already settles before the cap on current main.</li><li>A trace shows timeline commit preceding shadow picture promotion.</li><li>A deliberately broken stabilization rule passes steady-slow and burst/recovery witnesses.</li></ul></section>+</main></body></html>\ No newline at end of filediff --git a/packages/core/src/compositionReadiness.test.ts b/packages/core/src/compositionReadiness.test.tsindex 5172460bca..3dc7c4cb13 100644--- a/packages/core/src/compositionReadiness.test.ts+++ b/packages/core/src/compositionReadiness.test.ts@@ -309,7 +309,7 @@ describe("paintAndIdleReadinessInput", () => {await flushMicrotasks();expect(isResolved()).toBe(false);- // First quiet gap (10ms < 50ms threshold) — one is not enough.+ // First quiet gap (10ms < 50ms threshold): one is not enough.fireFrame(26);await flushMicrotasks();expect(isResolved()).toBe(false);@@ -358,29 +358,80 @@ describe("paintAndIdleReadinessInput", () => {expect(pendingFrameCount()).toBe(0); // the in-flight rAF was cancelled, not left pending});- it("gives up and resolves after MAX_PAINT_WAIT_MS of steady sub-20fps painting, never reaching a quiet gap", async () => {- // A composition rendering a real, steady 15fps (~66ms/frame) never- // produces a sub-50ms gap — this is the exact shape that used to hang- // paintAndIdleReadinessInput until settleCompositionReadiness's 8s- // shared timeout won the race on every single Play.+ it("settles a steady slow document after two of its own quiet gaps", async () => {const { fireFrame, isResolved } = startPaintAndIdleTracking();- const FRAME_GAP_MS = 66;+ for (const ts of [0, 66, 132]) {+ fireFrame(ts);+ await flushMicrotasks();+ expect(isResolved()).toBe(false);+ }+ fireFrame(198);+ await flushMicrotasks();+ expect(isResolved()).toBe(true);+ });- let ts = 0;- fireFrame(ts); // first paint scheduled+ it("accepts ordinary jitter up to one and a half of the shortest gap", async () => {+ const { fireFrame, isResolved } = startPaintAndIdleTracking();+ for (const ts of [0, 50, 125]) {+ fireFrame(ts);+ await flushMicrotasks();+ expect(isResolved()).toBe(false);+ }+ fireFrame(200);await flushMicrotasks();- ts += FRAME_GAP_MS;- fireFrame(ts); // first paint presented, lastTs = 66+ expect(isResolved()).toBe(true);+ });++ it.each([+ { label: "variable-refresh", frames: [0, 8, 24, 40] },+ { label: "alternating", frames: [0, 16, 49, 65] },+ ])("preserves fast $label gaps", async ({ frames }) => {+ const { fireFrame, isResolved } = startPaintAndIdleTracking();+ for (const ts of frames) {+ expect(isResolved()).toBe(false);+ fireFrame(ts);+ await flushMicrotasks();+ }+ expect(isResolved()).toBe(true);+ });++ it("preserves fast-page settlement after zero timestamps", async () => {+ const { fireFrame, isResolved } = startPaintAndIdleTracking();+ for (const ts of [0, 0, 16]) {+ fireFrame(ts);+ await flushMicrotasks();+ expect(isResolved()).toBe(false);+ }+ fireFrame(32);await flushMicrotasks();+ expect(isResolved()).toBe(true);+ });+ it("does not raise the shortest-gap baseline during later stalls", async () => {+ const { fireFrame, isResolved } = startPaintAndIdleTracking();+ for (const ts of [0, 100, 140, 230, 320, 410]) {+ fireFrame(ts);+ await flushMicrotasks();+ expect(isResolved()).toBe(false);+ }+ });++ it("keeps the paint cap when stalls prevent two consecutive quiet gaps", async () => {+ const { fireFrame, isResolved } = startPaintAndIdleTracking();+ let ts = 0;+ fireFrame(ts);+ await flushMicrotasks();+ ts = 66;+ fireFrame(ts);+ await flushMicrotasks();+ let slow = true;while (ts < 1_500) {expect(isResolved()).toBe(false);- ts += FRAME_GAP_MS;+ ts += slow ? 200 : 66;+ slow = !slow;fireFrame(ts);await flushMicrotasks();}- // The frame that crosses MAX_PAINT_WAIT_MS resolves on its own — no- // quiet gap was ever produced, only elapsed steady-paint time.expect(isResolved()).toBe(true);});});diff --git a/packages/core/src/compositionReadiness.ts b/packages/core/src/compositionReadiness.tsindex 49c69f1b17..f1b959deb2 100644--- a/packages/core/src/compositionReadiness.ts+++ b/packages/core/src/compositionReadiness.ts@@ -227,18 +227,17 @@ export function computeReadinessInput(doc: Document, signal: AbortSignal): Promi});}-// Frame-to-frame gap under which the main thread counts as free. Generous-// relative to a 16.7ms (60fps) frame budget — this detects a busy stretch-// (a mesh build, a shader compile), not ordinary frame-time variance.+// Gaps under this bound count as quiet on any document.const IDLE_FRAME_GAP_MS = 50;+// Ordinary frame jitter can span 1.5x the document's shortest observed gap.+const IDLE_FRAME_GAP_RATIO = 1.5;// Two consecutive quiet frames, not one: a single fast gap can follow// directly after the busy work finishes mid-frame and says nothing about// whether the next frame is also free.const IDLE_FRAMES_REQUIRED = 2;-// Gives up on a doc that keeps producing frames below 20fps. Does NOT bound-// a doc that stops painting entirely (backgrounded tab, or fewer than 3-// frames total) — that still rides the full shared 8s timeout, same as-// before this input existed. ponytail: 1500ms is unmeasured, retune later.+// Bounds continuing stalls. A backgrounded document with no frames still+// rides the shared timeout; this budget only bounds frames that arrive.+// ponytail: 1500ms is unmeasured; retune with frame traces.const MAX_PAINT_WAIT_MS = 1_500;// Resolves with -1 on abort instead of rejecting: every caller already@@ -267,8 +266,8 @@ function nextAnimationFrame(win: Window, signal: AbortSignal): Promise<number> {/** Composition-agnostic readiness input: waits for a frame to paint, then* two consecutive quiet frame gaps — an early-out once the main thread is- * free, not a hold on steady sub-20fps painting. See MAX_PAINT_WAIT_MS for- * what this bound does and does not cover. */+ * free relative to its own frame cadence. See MAX_PAINT_WAIT_MS for+ * what this bound does and does not cover. Compute and media inputs own completion. */export function paintAndIdleReadinessInput(doc: Document,signal: AbortSignal,@@ -279,12 +278,16 @@ export function paintAndIdleReadinessInput(const firstTs = await nextAnimationFrame(win, signal);if (signal.aborted) return;let lastTs = await nextAnimationFrame(win, signal);+ let shortestGap = lastTs - firstTs;let quietStreak = 0;while (!signal.aborted && quietStreak < IDLE_FRAMES_REQUIRED) {if (lastTs - firstTs >= MAX_PAINT_WAIT_MS) return;const ts = await nextAnimationFrame(win, signal);if (signal.aborted) return;- quietStreak = ts - lastTs < IDLE_FRAME_GAP_MS ? quietStreak + 1 : 0;+ const gap = ts - lastTs;+ shortestGap = Math.min(shortestGap, gap);+ const quiet = gap < IDLE_FRAME_GAP_MS || gap <= shortestGap * IDLE_FRAME_GAP_RATIO;+ quietStreak = quiet ? quietStreak + 1 : 0;lastTs = ts;}})();