fix(blink): synchronize first-paint styles before UICommand flush (#827)

andycall · web-flow · commit 002515b07453 · 2026-01-27T09:25:02.000-08:00
## Summary
Fixes a Blink-first-paint “unstyled/incorrect style” window by deferring
UICommand package flushing until a synchronous style update has run for
the newly-mounted visual subtree.

## Problem
When the Blink CSS engine is enabled, DOM mutations can enqueue/flush
UICommand packages before Blink has performed the first
`Document::UpdateStyleForThisDocument()`. This can lead to:
- an unstyled first frame (style commands arrive in a later batch)
- `getComputedStyle()` returning incorrect defaults during early mount
- RouterLink (hybrid router) subpage mounts being especially prone to
the issue

## Solution
- Add a “first-paint style sync” barrier on `ExecutingContext`:
  - `needs_first_paint_style_sync_` gates UICommand package emission
- `first_paint_committed_` prevents re-gating the initial document paint
- Arm the barrier on structural DOM insertions:
- `ContainerNode::{AppendChildCommon,InsertBeforeCommon}` call
`ExecutingContext::MaybeBeginFirstPaintStyleSync(...)`
  - Special-case RouterLink:
- do not block insertion of the RouterLink container into `&lt;body&gt;`
(avoids hybrid-router deadlock)
- re-arm when the RouterLink subtree (route contents) mounts its first
child
- Ensure the barrier clears deterministically:
- `SharedUICommand::AddCommand` calls `MaybeUpdateStyleForFirstPaint()`
on `kFinishRecordingCommand` to force a synchronous style update when
required
- `Document::UpdateStyleForThisDocument()` calls
`MaybeCommitFirstPaintStyleSync()` after updating styles to finalize the
barrier state
- Defer UICommand packages while the barrier is active:
- `UICommandPackageRingBuffer::PushPackage()` diverts packages into a
deferred queue when gated
- `FlushDeferredPackages()` pushes deferred packages once the barrier is
cleared
- `Reset/Clear` updated to account for deferred packages and lock
ordering

## Tests
- Bridge unit test:
`bridge/foundation/blink_first_paint_style_sync_test.cc`
- Verifies style commands (`kClearStyle`, `kSetStyleById`) appear in the
first flushed batch.
- Integration test:
`integration_tests/specs/cssom/first_paint_barrier_sync_flush.ts`
- Verifies `getComputedStyle()` is unblocked and returns expected values
during RouterLink subtree mount.
- Stabilize Blob constructor spec by waiting for a frame before
`toBlob()`.

## How to test
- `node scripts/run_bridge_unit_test.js`
- `cd integration_tests &amp;&amp; npm run integration`

## Notes / Risk
- Changes only take effect when the Blink engine is enabled.
- RouterLink handling is explicitly designed to avoid blocking
hybrid-router navigation while still gating the first painted subtree.
diff --git a/bridge/core/dom/container_node.cc b/bridge/core/dom/container_node.cc
@@ -723,6 +723,10 @@ void ContainerNode::InsertBeforeCommon(Node& next_child, Node& new_child) {
   assert(!new_child.nextSibling());
   assert(!new_child.previousSibling());
 
+  if (auto* context = GetExecutingContext()) {
+    context->MaybeBeginFirstPaintStyleSync(*this, new_child, !hasChildren());
+  }
+
   Node* prev = next_child.previousSibling();
   assert(last_child_ != prev);
   next_child.SetPreviousSibling(&new_child);
@@ -744,6 +748,11 @@ void ContainerNode::InsertBeforeCommon(Node& next_child, Node& new_child) {
 }
 
 void ContainerNode::AppendChildCommon(Node& child) {
+  const bool was_empty = !hasChildren();
+  if (auto* context = GetExecutingContext()) {
+    context->MaybeBeginFirstPaintStyleSync(*this, child, was_empty);
+  }
+
   child.SetParentOrShadowHostNode(this);
   if (last_child_) {
     child.SetPreviousSibling(last_child_);
diff --git a/bridge/core/dom/document.cc b/bridge/core/dom/document.cc
@@ -684,6 +684,7 @@ void Document::UpdateStyleForThisDocument() {
   style_engine.InvalidateEnvDependentStylesIfNeeded();
   UpdateStyleInvalidationIfNeeded();
   UpdateStyle();
+  context->MaybeCommitFirstPaintStyleSync();
 
   auto duration_ms =
       std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::steady_clock::now() - start_time).count();
diff --git a/bridge/core/executing_context.cc b/bridge/core/executing_context.cc
@@ -25,6 +25,7 @@
 #include "core/dom/mutation_observer.h"
 #include "core/css/style_engine.h"
 #include "core/events/error_event.h"
+#include "core/html/html_body_element.h"
 #include "core/html/html_script_element.h"
 #include "core/events/promise_rejection_event.h"
 #include "core/js_function_ref.h"
@@ -827,10 +828,64 @@ void ExecutingContext::SetWidgetElementShape(NativeWidgetElementShape* native_wi
 void ExecutingContext::EnableBlinkEngine() {
   WEBF_LOG(INFO) << "=== The Blink engine is enabled ===";
 
+  if (enable_blink_engine_) {
+    return;
+  }
+
   enable_blink_engine_ = true;
   document()->EnsureStyleEngine();
 }
 
+void ExecutingContext::MaybeBeginFirstPaintStyleSync(const ContainerNode& parent,
+                                                     const Node& child,
+                                                     bool parent_was_empty) {
+  if (!enable_blink_engine_ || needs_first_paint_style_sync_) {
+    return;
+  }
+
+  // Re-arm the barrier for the first mount of a RouterLink subtree (subpage).
+  if (parent.IsRouterLinkElement() && parent_was_empty) {
+    needs_first_paint_style_sync_ = true;
+    return;
+  }
+
+  // Only gate the very first document paint once.
+  if (first_paint_committed_) {
+    return;
+  }
+
+  // Avoid deadlocking hybrid-router navigation by *not* blocking the initial
+  // insertion of RouterLink containers into <body>. Route children are mounted
+  // later (into the RouterLink element), where we can safely gate.
+  if (IsA<HTMLBodyElement>(parent) && !child.IsRouterLinkElement()) {
+    needs_first_paint_style_sync_ = true;
+  }
+}
+
+void ExecutingContext::MaybeUpdateStyleForFirstPaint() {
+  if (!enable_blink_engine_ || !needs_first_paint_style_sync_) {
+    return;
+  }
+
+  if (!document_) {
+    return;
+  }
+
+  MemberMutationScope mutation_scope{this};
+  document_->UpdateStyleForThisDocument();
+  needs_first_paint_style_sync_ = false;
+  first_paint_committed_ = true;
+}
+
+void ExecutingContext::MaybeCommitFirstPaintStyleSync() {
+  if (!enable_blink_engine_ || !needs_first_paint_style_sync_) {
+    return;
+  }
+
+  needs_first_paint_style_sync_ = false;
+  first_paint_committed_ = true;
+}
+
 void ExecutingContext::FlushUICommand(const BindingObject* self, uint32_t reason) {
   std::vector<NativeBindingObject*> deps;
   FlushUICommand(self, reason, deps);
diff --git a/bridge/core/executing_context.h b/bridge/core/executing_context.h
@@ -66,6 +66,8 @@ class ScriptWrappable;
 class NativeByteDataFinalizerContext;
 class ScriptPromiseResolver;
 class HTMLScriptElement;
+class ContainerNode;
+class Node;
 struct NativeJSFunctionRef;
 
 using JSExceptionHandler = std::function<void(ExecutingContext* context, const char* message)>;
@@ -214,6 +216,10 @@ class ExecutingContext {
   FORCE_INLINE bool isIdle() const { return is_idle_; }
   FORCE_INLINE void SetIsIdle(bool is_idle) { is_idle_ = is_idle; }
   FORCE_INLINE void MarkNeedsStyleUpdateInMicrotask() { is_needs_update_styles_in_microtask_ = true; }
+  // If a "first-paint style sync" barrier is active, clear it after we've
+  // performed a synchronous style update so deferred UICommand packages can be
+  // flushed to Dart (e.g. for getComputedStyle()).
+  void MaybeCommitFirstPaintStyleSync();
 
   // Cached media/viewport values pushed from Dart (e.g., during resize). These
   // avoid synchronous GetBindingProperty calls (which may flush layout) during
@@ -272,6 +278,10 @@ class ExecutingContext {
   void InstallDocument();
   void InstallPerformance();
   void InstallNativeLoader();
+  void MaybeBeginFirstPaintStyleSync(const ContainerNode& parent,
+                                     const Node& child,
+                                     bool parent_was_empty);
+  void MaybeUpdateStyleForFirstPaint();
 
   void DrainPendingPromiseJobs();
 
@@ -323,6 +333,12 @@ class ExecutingContext {
   bool is_dedicated_;
   std::unique_ptr<RemoteObjectRegistry> remote_object_registry_;
   bool enable_blink_engine_ = false;
+  // When Blink CSS is enabled, defer UICommand packages until we've run at
+  // least one `Document::UpdateStyleForThisDocument()` for a newly-mounted
+  // visual subtree, so the first visible frame ships with both DOM + styles.
+  // This barrier can be re-armed (e.g., first mount of a RouterLink subtree).
+  bool needs_first_paint_style_sync_{false};
+  bool first_paint_committed_{false};
   bool is_idle_{true};
   bool is_needs_update_styles_in_microtask_ {false};
   std::optional<double> cached_viewport_width_;
@@ -335,6 +351,10 @@ class ExecutingContext {
 
   // Native library metadata
   std::vector<NativeLibraryMetaData*> native_library_meta_data_contaner_;
+
+  friend class ContainerNode;
+  friend class SharedUICommand;
+  friend class UICommandPackageRingBuffer;
 };
 
 class ObjectProperty {
diff --git a/bridge/foundation/blink_first_paint_style_sync_test.cc b/bridge/foundation/blink_first_paint_style_sync_test.cc
@@ -0,0 +1,50 @@
+#include "gtest/gtest.h"
+
+#include <cstring>
+
+#include "foundation/ui_command_buffer.h"
+#include "webf_test_env.h"
+
+using namespace webf;
+
+namespace {
+
+bool HasCommand(const UICommandItem* items, int64_t length, UICommand command) {
+  for (int64_t i = 0; i < length; ++i) {
+    if (items[i].type == static_cast<int32_t>(command)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+}  // namespace
+
+TEST(BlinkFirstPaintStyleSync, EmitsSheetStyleCommandsInFirstBatch) {
+  auto env = TEST_init(nullptr, nullptr, 0, /*enable_blink=*/1);
+  auto* context = env->page()->executingContext();
+
+  // Flush bootstrap microtasks and drop any initial commands.
+  TEST_runLoop(context);
+  context->uiCommandBuffer()->clear();
+
+  const char* setup = R"JS(
+    const style = document.createElement('style');
+    style.textContent = '.box { color: red; }';
+    document.body.appendChild(style);
+
+    const div = document.createElement('div');
+    div.className = 'box';
+    div.textContent = 'hi';
+    document.body.appendChild(div);
+  )JS";
+  env->page()->evaluateScript(setup, strlen(setup), "vm://", 0);
+
+  context->uiCommandBuffer()->SyncAllPackages();
+  auto* pack = static_cast<UICommandBufferPack*>(context->uiCommandBuffer()->data());
+  auto* items = static_cast<UICommandItem*>(pack->data);
+
+  EXPECT_TRUE(HasCommand(items, pack->length, UICommand::kClearStyle));
+  EXPECT_TRUE(HasCommand(items, pack->length, UICommand::kSetStyleById));
+}
+
diff --git a/bridge/foundation/shared_ui_command.cc b/bridge/foundation/shared_ui_command.cc
@@ -36,6 +36,10 @@ void SharedUICommand::AddCommand(UICommand type,
                                  void* native_binding_object,
                                  void* nativePtr2,
                                  bool request_ui_update) {
+  if (type == UICommand::kFinishRecordingCommand) {
+    context_->MaybeUpdateStyleForFirstPaint();
+  }
+
   // For non-dedicated contexts, add directly to read buffer
   if (!context_->isDedicated()) {
     std::lock_guard<std::mutex> lock(read_buffer_mutex_);
@@ -52,7 +56,12 @@ void SharedUICommand::AddCommand(UICommand type,
   if (type == UICommand::kFinishRecordingCommand) {
     // Calculate if we should request batch update based on waiting commands and ring buffer state
     bool should_request_batch_update =
-        ui_command_sync_strategy_->GetWaitingCommandsCount() > 0 || package_buffer_->HasUnflushedCommands();
+        ui_command_sync_strategy_->GetWaitingCommandsCount() > 0 || package_buffer_->HasUnflushedCommands() ||
+        package_buffer_->HasDeferredPackages() || package_buffer_->PackageCount() > 0;
+
+    if (!context_->needs_first_paint_style_sync_) {
+      package_buffer_->FlushDeferredPackages();
+    }
 
     // Flush all waiting ui commands to ring buffer
     ui_command_sync_strategy_->FlushWaitingCommands();
@@ -143,6 +152,9 @@ void SharedUICommand::SyncAllPackages() {
   // First flush waiting commands from UICommandStrategy to ring buffer
   ui_command_sync_strategy_->FlushWaitingCommands();
   package_buffer_->FlushCurrentPackage();
+  if (!context_->needs_first_paint_style_sync_) {
+    package_buffer_->FlushDeferredPackages();
+  }
 }
 
 void SharedUICommand::FillReadBuffer() {
diff --git a/bridge/foundation/ui_command_ring_buffer.cc b/bridge/foundation/ui_command_ring_buffer.cc
@@ -297,7 +297,32 @@ void UICommandPackageRingBuffer::FlushCurrentPackage() {
   PushPackage(std::move(package));
 }
 
+void UICommandPackageRingBuffer::FlushDeferredPackages() {
+  if (context_ && context_->needs_first_paint_style_sync_) {
+    return;
+  }
+
+  std::vector<std::unique_ptr<UICommandPackage>> deferred;
+  {
+    std::lock_guard<std::mutex> lock(deferred_mutex_);
+    if (deferred_packages_.empty()) {
+      return;
+    }
+    deferred.swap(deferred_packages_);
+  }
+
+  for (auto& package : deferred) {
+    PushPackage(std::move(package));
+  }
+}
+
 void UICommandPackageRingBuffer::PushPackage(std::unique_ptr<UICommandPackage> package) {
+  if (context_ && context_->needs_first_paint_style_sync_) {
+    std::lock_guard<std::mutex> lock(deferred_mutex_);
+    deferred_packages_.push_back(std::move(package));
+    return;
+  }
+
   size_t write_idx = write_index_.load(std::memory_order_relaxed);
   size_t next_write_idx = (write_idx + 1) & capacity_mask_;
 
@@ -357,6 +382,13 @@ size_t UICommandPackageRingBuffer::PackageCount() const {
 }
 
 bool UICommandPackageRingBuffer::Empty() const {
+  {
+    std::lock_guard<std::mutex> lock(const_cast<std::mutex&>(deferred_mutex_));
+    if (!deferred_packages_.empty()) {
+      return false;
+    }
+  }
+
   // Check if there are any packages in the ring buffer or overflow
   if (PackageCount() > 0) {
     return false;
@@ -372,6 +404,11 @@ bool UICommandPackageRingBuffer::HasUnflushedCommands() const {
   return !current_package_->commands.empty();
 }
 
+bool UICommandPackageRingBuffer::HasDeferredPackages() const {
+  std::lock_guard<std::mutex> lock(const_cast<std::mutex&>(deferred_mutex_));
+  return !deferred_packages_.empty();
+}
+
 void UICommandPackageRingBuffer::Clear() {
   write_index_.store(0, std::memory_order_relaxed);
   read_index_.store(0, std::memory_order_relaxed);
@@ -381,11 +418,20 @@ void UICommandPackageRingBuffer::Clear() {
     packages_[i].package.reset();
   }
 
-  std::lock_guard<std::mutex> lock(overflow_mutex_);
-  overflow_packages_.clear();
+  {
+    std::lock_guard<std::mutex> pkg_lock(current_package_mutex_);
+    current_package_->Clear();
+  }
 
-  std::lock_guard<std::mutex> pkg_lock(current_package_mutex_);
-  current_package_->Clear();
+  {
+    std::lock_guard<std::mutex> deferred_lock(deferred_mutex_);
+    deferred_packages_.clear();
+  }
+
+  {
+    std::lock_guard<std::mutex> overflow_lock(overflow_mutex_);
+    overflow_packages_.clear();
+  }
 }
 
 bool UICommandPackageRingBuffer::ShouldCreateNewPackage(UICommand command) const {
diff --git a/bridge/foundation/ui_command_ring_buffer.h b/bridge/foundation/ui_command_ring_buffer.h
@@ -108,6 +108,10 @@ class UICommandPackageRingBuffer {
                   bool request_ui_update = true);
   void AddCommandItem(const UICommandItem& item, UICommand type, bool request_ui_update = true);
   void FlushCurrentPackage();
+  // Push any deferred packages to the ring buffer (no-op while a first-paint
+  // barrier is active).
+  void FlushDeferredPackages();
+  bool HasDeferredPackages() const;
   
   // Consumer operations
   std::unique_ptr<UICommandPackage> PopPackage();
@@ -139,6 +143,10 @@ class UICommandPackageRingBuffer {
   std::atomic<size_t> write_index_{0};
   std::atomic<size_t> read_index_{0};
   
+  // Deferred packages (first-paint barrier) held on the producer thread.
+  std::mutex deferred_mutex_;
+  std::vector<std::unique_ptr<UICommandPackage>> deferred_packages_;
+
   // Overflow handling
   std::mutex overflow_mutex_;
   std::vector<std::unique_ptr<UICommandPackage>> overflow_packages_;
diff --git a/bridge/test/test.cmake b/bridge/test/test.cmake
@@ -36,6 +36,7 @@ list(APPEND WEBF_TEST_SOURCE
   ./core/html/html_link_element_rel_list_test.cc
   ./core/timing/performance_test.cc
   ./foundation/shared_ui_command_test.cc
+  ./foundation/blink_first_paint_style_sync_test.cc
   ./foundation/ui_command_ring_buffer_test.cc
   ./foundation/ui_command_strategy_test.cc
   ./foundation/string/string_impl_unittest.cc
diff --git a/integration_tests/specs/blob/constructor.ts b/integration_tests/specs/blob/constructor.ts
@@ -45,6 +45,8 @@ describe('Blob API', () => {
     div.style.border = '1px solid #000';
     document.body.appendChild(div);
 
+    await waitForFrame();
+
     const blob = await div.toBlob(1);
     // @ts-ignore
     const base64 = await blob.base64();
diff --git a/integration_tests/specs/cssom/first_paint_barrier_sync_flush.ts b/integration_tests/specs/cssom/first_paint_barrier_sync_flush.ts
@@ -0,0 +1,28 @@
+describe('First-paint barrier: synchronous flush', () => {
+  it('unblocks getComputedStyle() during RouterLink subtree mount', () => {
+    const style = document.createElement('style');
+    style.textContent = '.sync-flush-box { color: rgb(255, 0, 0); }';
+    document.head.appendChild(style);
+
+    const routerLink = document.createElement('webf-router-link');
+    document.body.appendChild(routerLink);
+
+    const target = document.createElement('div');
+    target.className = 'sync-flush-box';
+    target.textContent = 'sync flush';
+    routerLink.appendChild(target);
+
+    let color = '';
+    try {
+      color = getComputedStyle(target).color;
+    } catch (e) {
+      fail(`getComputedStyle threw: ${String(e)}`);
+      return;
+    }
+
+    expect(color.indexOf('255, 0, 0') >= 0 || color === 'red').toBeTrue();
+
+    style.remove();
+    routerLink.remove();
+  });
+});
diff --git a/webf/example/lib/main.dart b/webf/example/lib/main.dart
