OSR OnPaint intermittently returns visually incomplete frame after JS-ready and Invalidate with external begin frame

[L0stInFades]

Describe the bug

In windowless/off-screen rendering (OSR), OnPaint can intermittently deliver a full-size image buffer that is visually incomplete after the page has reported that its JavaScript state is ready and the native host has invalidated the view.

The buffer dimensions and byte size are correct, and this does not appear to be a dirty-rect interpretation issue. The bad frame looks like an intermediate compositor result: the background is present, but some DOM/canvas/composited layers are missing or only partially updated, sometimes with a tiled/stair-step boundary. A later Invalidate / OnPaint for the same page state produces the complete image.

This is visible when using CEF OSR as a deterministic frame capture backend for video export, where each animation frame is driven by JavaScript and then captured from OnPaint.

To Reproduce

I have not reduced this to cefclient or cefsimple yet. The current reproduction is in a custom OSR application using CEF APIs through Rust bindings, but the flow maps directly to CEF windowless rendering APIs:

1. Create a windowless browser with:
   • external_begin_frame_enabled = true on CefWindowInfo
   • external_message_pump = true
   • windowless_rendering_enabled = true
   • windowless_frame_rate = 30
   • shared_texture_enabled = false / regular OnPaint buffer path
2. Use command-line switches including:
   • disable-gpu
   • disable-gpu-compositing
   • disable-dev-shm-usage
3. Load an HTML page with complex animated composited content:
   • gradient background
   • DOM overlays
   • canvas-drawn elements
   • CSS clip/reveal effects
   • filters and/or 3D transforms
4. Expose a JS method similar to setTime(ms) that updates the page to a deterministic animation time and reports a "frame ready" signal after the JS/React/canvas state update has completed.
5. Native frame loop:
   • call JS setTime(ms)
   • wait for the JS ready signal
   • drain previously queued paint callbacks
   • call CefBrowserHost::Invalidate(PET_VIEW)
   • pump the external message loop / external begin frames
   • capture the resulting OnPaint buffer
6. Repeat this for a sequence of frames.

Intermittently, the first OnPaint after the JS ready signal and invalidation contains an incomplete visual composite. Capturing another candidate for the same JS state usually produces the correct image.

Expected behavior

After the page has reached a stable JS state and the view is invalidated, there should be a reliable way for an OSR client to know when CEF has delivered a fully composited frame for that state.

Alternatively, if the first OnPaint after invalidation is allowed to represent an intermediate compositor state, the expected synchronization mechanism for deterministic frame capture should be documented.

Actual behavior

OnPaint sometimes returns a valid full-size BGRA buffer that is not visually complete for the current page state. Some composited layers appear missing or partially updated. A subsequent invalidation/capture for the same state produces the expected complete frame.

Workarounds tried

• Waiting for JavaScript / React / canvas completion before invalidating the view.
• Waiting for requestAnimationFrame on the page side before signaling readiness.
• Draining stale paint callbacks before each capture.
• Pumping external begin frames while waiting for OnPaint.

The reliable workaround so far is to capture multiple OnPaint candidates for the same JS state and choose the most complete candidate. This avoids the visual corruption, but it adds extra capture cost and suggests the first paint can be an intermediate compositor result.

Versions (please complete the following information):

• OS: macOS 15.7.4 (Darwin 24.6.0, x86_64)
• CEF Version: CEF 146.0.12 via cef-dll-sys 146.7.0+146.0.12 / Rust cef crate 146.7.0

Additional context

• The page renders correctly in an interactive browser context; the issue is specific to OSR frame capture timing.
• I have not yet reproduced this in cefclient or cefsimple.
• The observed OnPaint buffer is the full image buffer, not only the dirty rect data.
• The main question is whether this behavior is expected for OSR with external_begin_frame_enabled, and what synchronization point CEF recommends for deterministic capture of a fully composited frame.

[magreenblatt]

This is visible when using CEF OSR as a deterministic frame capture backend for video export, where each animation frame is driven by JavaScript and then captured from OnPaint.
The main question is whether this behavior is expected for OSR with external_begin_frame_enabled, and what synchronization point CEF recommends for deterministic capture of a fully composited frame.

I'm not sure there is a reliable signal currently, as this involves multiple asynchronous pipelines in different processes. You mention a video pipeline, so I assume the usual answer of "wait a bit before capture" won't work for you (unless it's not intended to run in real-time, and you can "slow down" the JS frame generation to allow for complete capture of each).

[L0stInFades]

Follow-up after source-level investigation and another local run.

I pulled the matching CEF source for our binary (cef_binary_146.0.12+g6214c8e+chromium-146.0.7680.179, branch 7680) and found a more specific timing issue in the software OSR path:

• CefBrowserHost::SendExternalBeginFrame() maps to CefRenderWidgetHostViewOSR::SendExternalBeginFrame(), which calls compositor_->IssueExternalBeginFrame(..., OnFrameComplete). OnFrameComplete(const viz::BeginFrameAck&) only clears the private begin_frame_pending_; no completion/sequence signal is exposed to the client.
• With GPU compositing disabled, CefRenderWidgetHostViewOSR::Show() does not create CefVideoConsumerOSR.
• In that mode, CefRenderWidgetHostViewOSR::InvalidateInternal() falls back to host_display_client_ and calls OnPaint(bounds, host_display_client_->GetPixelSize(), host_display_client_->GetPixelMemory()) synchronously with the current shared-memory buffer.
• That seems different from the public Invalidate() documentation saying OnPaint is called asynchronously, and it also means a client can receive the current/cached software buffer immediately after Invalidate(), before a subsequent external begin frame has produced a fresh compositor result.

This explains the symptom we saw: after driving JS/rAF to a frame-ready state, the first OnPaint after Invalidate(PET_VIEW) can be a valid full-size buffer but visually stale/intermediate. In our video-export loop that buffer was occasionally encoded as a bad frame. The failure is not a dirty-rect issue; it is about which compositor result the full buffer corresponds to.

As a local experiment, I removed --disable-gpu and --disable-gpu-compositing so CEF uses the CefVideoConsumerOSR path (InvalidateInternal() -> RequestRefreshFrame() -> OnFrameCaptured() -> OnPaint()) instead of the software host_display_client_ synchronous replay path. On the same 1118-frame / 1920x1080 / 30fps project:

• Previous software path: 202s total, black-frame scan found spikes around the problem area (pblack up to 31 over the whole file).
• GPU-compositor/video-capturer path: 137s total, no visual corruption in the previously bad 27-29s region (pblack:0 for that region; max pblack=1 over the whole file).

So I think the actionable CEF-side questions are:

1. Is the synchronous OnPaint() from InvalidateInternal() in the software OSR fallback path expected behavior, despite the public async wording?
2. If it is expected, is there a recommended way for external-begin-frame OSR clients to distinguish “cached/current software buffer replayed by Invalidate()” from “fresh compositor result for a begin frame”?
3. Would CEF consider exposing a begin-frame completion / paint sequence signal for OSR, or documenting that deterministic capture should prefer the video-capturer path and avoid disabled GPU compositing?

I can try to reduce this to a cefclient/cefsimple repro next, now that the likely path difference is identified.

[magreenblatt]

Code documentation in this area tends to get stale quickly as Chromium architecture changes. Also difficult to verify given the lack of automated test coverage for complex interactions. Discoverable issues such as this one serve as living documentation.

Would CEF consider exposing a begin-frame completion / paint sequence signal for OSR

Possibly yes, if it helps. You’re welcome to perform an experiment and report your findings.

[L0stInFades]

Thanks for the guidance. We ran more application-level experiments and now have a more precise workaround that supports the idea that the missing piece is paint-level sequencing rather than page-side JS readiness.

Our previous stable workaround was to add two extra requestAnimationFrame waits after our page-side setTime()/ready signal. That made the bad frames disappear, but it imposed a fixed per-frame cost. We then replaced the fixed delay with a paint-marker validation scheme:

• For each export frame, after the page finishes applying the deterministic time/state update, it writes a deterministic per-frame marker color into a known 1px location.
• The native OSR loop rejects OnPaint buffers until that marker appears in the BGRA buffer for the current frame.
• Before encoding, we restore that marker pixel from a neighboring pixel so it does not appear in the final video.

With this approach we can run with zero extra worker-side rAF waits while still avoiding the stale/incomplete frames in our application-level tests. By contrast, removing the extra rAF waits without marker validation reproduces bad frames. Keeping the fixed two-rAF delay also works, but it pays the same delay on every frame even when the matching paint is already available.

This seems to confirm the problem shape we are seeing: our JS state/ready signal can be correct while the next native OnPaint candidate can still correspond to an older/intermediate compositor result. The robust signal for deterministic capture is therefore “this OnPaint contains the visual result for sequence N,” not “the page says sequence N is ready.”

So the CEF-side feature that would help us is an OSR paint/begin-frame sequence signal. For example, if an external begin frame or invalidation could be tagged with a client-visible sequence id, and OnPaint or an associated completion callback could report the corresponding sequence/compositor result id, we could replace the application-level marker pixel with an official paint-level synchronization mechanism.

These are still application-level results, not yet a minimal CEF repro. I will work on a small standalone experiment that demonstrates the same distinction outside our full application: page-side ready fires, the first paint candidate can be stale/intermediate, and a paint-level marker/sequence check is what makes capture deterministic.

[magreenblatt]

For each export frame, after the page finishes applying the deterministic time/state update, it writes a deterministic per-frame marker color into a known 1px location.

Just a note that I've seen this approach used in other projects as well.

[L0stInFades]

Thanks, that context is useful. I took your suggestion to run a concrete experiment and tried to keep it small enough that the synchronization behavior is visible without the rest of our application around it:

https://github.com/L0stInFades/cef-osr-sync-experiment

The experiment is meant to isolate the timing question from this issue: after the page reports that a target frame is ready, is the next inspected OSR OnPaint buffer a reliable capture boundary, or does the client still need some paint-level confirmation?

It uses public CEF APIs through the Rust bindings and does not require CEF source changes. The real CEF runner uses:

• external_message_pump and windowless_rendering_enabled
• WindowInfo::set_as_windowless with external_begin_frame_enabled
• regular RenderHandler::on_paint BGRA buffer capture
• a page-side console log as the JS-ready signal
• send_external_begin_frame() while pumping the external message loop

I compared three acceptance strategies:

• immediate: accept the first paint candidate after JS-ready/invalidate.
• fixed-delay: model the usual “wait a bit before capture” workaround with a fixed rAF-sized delay.
• marker-sync: inspect a deterministic marker pixel and reject paint candidates until the marker for the requested target frame is visible.

A local Linux/OrbStack/Xvfb real CEF run (cef = 146.7.0, Rust 1.95.0 in the container) produced this summary:

mode	rows	accepted marker mismatches	rejected marker mismatches	accepted marker matches	max accepted_elapsed_ms_since_ready
immediate	6	2	0	4	0.077ms
fixed-delay	12	0	3	6	42.720ms
marker-sync	7	0	1	6	9.912ms

The raw JSONL files are included in the repo under results/, including:

• results/linux-orbstack-cef-osr-immediate.jsonl
• results/linux-orbstack-cef-osr-fixed-delay.jsonl
• results/linux-orbstack-cef-osr-marker-sync.jsonl

The part that seems relevant for CEF is the distinction between the three rows above:

• immediate accepted marker-mismatched paint candidates after the page-side ready signal.
• fixed-delay avoided accepting mismatches in this run, but paid the configured delay even when a matching paint candidate was already available earlier.
• marker-sync rejected the mismatched candidate and accepted only matching candidates, without using a fixed per-frame delay.

So this does not prove that every pixel in a marker-matching frame is semantically complete, and it does not prove a universal CEF ordering rule. I am treating it as a small public-API sequence probe: it shows a case where page-side readiness plus the next inspected OnPaint is not enough for deterministic capture, while a paint-level sequence/content check changes the result.

Does this look like the right kind of experiment for evaluating whether a client-visible OSR paint/begin-frame sequence signal would help? If so, I would appreciate guidance on which CEF/Chromium-side event would be the best candidate to expose or approximate: external begin-frame ack/completion, compositor activation/presentation, or a monotonically increasing paint sequence associated with OnPaint.

[magreenblatt]

Thanks — that's the right shape of experiment, and the immediate row is a clean demonstration that page-ready + next OnPaint isn't a capture boundary.

For the "which event to expose" question: the most directly available signal is the viz::BeginFrameAck that CEF already receives. Compositor::IssueExternalBeginFrame's completion callback (mojo guarantees it fires when the frame is produced or declined) already lands in CefRenderWidgetHostViewOSR::OnFrameComplete — it just drops ack.frame_id.sequence_number and ack.has_damage on the floor today.

A minimal addition would be a new default-empty CefRenderHandler::OnFrameAcknowledged(browser, type, sequence_number, has_damage) plus a way to know which sequence SendExternalBeginFrame() just issued. has_damage is particularly relevant for your original --disable-gpu-compositing case: it distinguishes "this begin-frame produced a fresh compositor result" from "consumed but produced nothing new."

What source inspection can't answer is the ordering between OnFrameAcknowledged and the corresponding OnPaint — they arrive over different mojo pipes, so the robust client rule is probably "wait for ack-with-damage for sequence N, then accept the next OnPaint." If that's not strong enough in practice, Compositor::RequestSuccessfulPresentationTimeForNextFrame is a stricter "actually presented" hook that could back the same callback.

If you'd like to try a PR, that's the path I'd suggest — your existing harness is the right validator: re-run immediate with the new ack-based rule, and if it matches marker-sync without the marker pixel, the API addition justifies itself.