fix(offline): wait for page control before warming editor assets

Author: chaxus

CHANGELOG.md

@@ -9,6 +9,8 @@ notes. Entries describe what users experience, not internal refactors.
 
 ### Fixed
 
+- First-visit editor preparation waits for the service worker to control the
+  page, so warmed font resources remain available in its offline cache.
 - A failed recovery snapshot no longer removes an older document when storage
   remains full after a retry.
 - Recovery files that exceed the storage budget are rejected before their

docs/explorations/2026-10-17-pr279-ci-followup.md

@@ -0,0 +1,48 @@
+# PR 279: first-visit editor cache race
+
+The Docker E2E run at commit `5ae9dfdf` failed its landing-page cache assertion
+in shard 2. The other 109 cases in that shard passed. The retained trace from
+GitHub Actions run `39027953673` showed that the sole missing entry was
+`/sdkjs/common/libfont/engine/fonts.js`.
+
+The font request succeeded, but occurred after `serviceWorker.ready` resolved
+and before `clients.claim()` controlled the first-visit page. It populated only
+the browser HTTP cache. The prefetcher's request deduplication then prevented a
+controlled retry that would populate the worker's offline cache.
+
+`public/landing-prefetch.js` now waits for actual page control before issuing
+warm-up requests. It installs the control listener before rechecking the
+controller, removes listeners when settled, and cancels the wait on departure
+or worker upgrade. Resuming keeps the URL eligible for a new request. Existing
+controlled pages continue immediately, and the upgrade gate still applies.
+
+Two deterministic regressions first failed against the previous implementation:
+one verifies that a resolved readiness promise cannot start an uncontrolled
+fetch; the other checks cancellation, late control changes and retry after
+returning. Both pass with the fix, along with all 15 landing-prefetch unit tests.
+Independent read-only review also checked upgrade and BFCache interactions and
+reported no actionable findings.
+
+The browser assertion now reports the actual list of missing URLs rather than
+only their count. Its existing 120-second deadline is unchanged.
+
+## Verification
+
+- Full unit coverage: 6,290 tests in 238 files pass; 89.56% lines and 83.08%
+  branches. All repository coverage gates pass.
+- A fresh production Docker image passes all four landing-prefetch Chromium
+  cases, including all editor engines cached, background core caching, actual
+  font-catalog requests and an editor open served from the warmed worker cache.
+- Archive integrity, repository-wide formatting, oxlint, refreshed workspace
+  declarations and application TypeScript checks pass.
+
+```sh
+pnpm run test:coverage --maxWorkers=2
+pnpm run format:check
+pnpm run lint:ts
+docker build -t document:pr279-ci .
+docker run -d --rm --name document-pr279-ci -p 127.0.0.1:4199:80 document:pr279-ci
+E2E_BASE_URL=http://127.0.0.1:4199 E2E_PORT=4199 pnpm exec playwright test \
+  test/e2e/landing-prefetch.spec.ts --workers=1 --reporter=line
+docker stop document-pr279-ci
+```

public/landing-prefetch.js

@@ -201,10 +201,41 @@
    * serves the vendored tree cache-first -- a miss there re-requests the file
    * even when the browser still holds a copy.
    */
+  // ready can resolve before clients.claim() controls this first-visit page.
+  // Fetching in that gap warms only the HTTP cache, then requested[url] would
+  // prevent the controlled retry that actually populates the worker cache.
+  function waitForControl(registration) {
+    var workers = navigator.serviceWorker;
+    if (workers.controller) return Promise.resolve(!leaving && watchRegistration(registration));
+    return new Promise(function (resolve) {
+      var signal = aborter && aborter.signal;
+      var finished = false;
+      function done(allowed) {
+        if (finished) return;
+        finished = true;
+        workers.removeEventListener('controllerchange', changed);
+        if (signal) signal.removeEventListener('abort', cancelled);
+        resolve(allowed);
+      }
+      function cancelled() {
+        done(false);
+      }
+      function changed() {
+        if (leaving || upgrading || (signal && signal.aborted)) done(false);
+        else if (workers.controller) done(watchRegistration(registration));
+      }
+      workers.addEventListener('controllerchange', changed);
+      if (signal) signal.addEventListener('abort', cancelled, { once: true });
+      changed();
+    });
+  }
+
   function warm(url) {
     if (!navigator.serviceWorker) return warmRequest(url);
     return navigator.serviceWorker.ready
-      .then(watchRegistration)
+      .then(function (registration) {
+        return watchRegistration(registration) ? waitForControl(registration) : false;
+      })
       .then(function (allowed) {
         if (allowed) return warmRequest(url);
       })

test/e2e/landing-prefetch.spec.ts

@@ -68,7 +68,7 @@ test.describe('landing page warm-up', () => {
         return wanted.filter((u) => !held.has(u));
       });
 
-    await expect.poll(async () => (await missing()).length, { timeout: 120_000 }).toBe(0);
+    await expect.poll(missing, { timeout: 120_000, intervals: [1000] }).toEqual([]);
 
     const shape = await page.evaluate(() => {
       const lp = (window as any).__landingPrefetch;

test/unit/landing-prefetch.test.ts

@@ -116,7 +116,7 @@ describe('landing page warm-up', () => {
 });
 
 describe('landing warm-up during a worker upgrade', () => {
-  function setup(effectiveType?: string) {
+  function setup(effectiveType?: string, controlled = true) {
     const src = readFileSync(resolve(__dirname, '../../public/landing-prefetch.js'), 'utf8');
     const win = Object.assign(new EventTarget(), {
       requestIdleCallback: (callback: () => void) => callback(),
@@ -128,7 +128,10 @@ describe('landing warm-up during a worker upgrade', () => {
       waiting: null as (EventTarget & { state: string; scriptURL?: string }) | null,
       installing: null as (EventTarget & { state: string }) | null,
     });
-    const workers = Object.assign(new EventTarget(), { ready: Promise.resolve(registration) });
+    const workers = Object.assign(new EventTarget(), {
+      ready: Promise.resolve(registration),
+      controller: controlled ? ({} as object | null) : null,
+    });
     const fetchMock = vi.fn((_url: string, _init?: RequestInit) => Promise.resolve(okResponse()));
     new Function('window', 'document', 'navigator', 'fetch', 'AbortController', src)(
       win,
@@ -140,6 +143,39 @@ describe('landing warm-up during a worker upgrade', () => {
     return { win, doc, cta, registration, workers, fetchMock, hook: win.__landingPrefetch! };
   }
 
+  it('waits for actual page control after ready before fetching a cacheable resource', async () => {
+    const { workers, hook, fetchMock } = setup(undefined, false);
+    const cached = new Set<string>();
+    fetchMock.mockImplementation((url) => {
+      if (workers.controller) cached.add(url);
+      return Promise.resolve(okResponse());
+    });
+    const pending = hook.warm('/sdkjs/common/libfont/engine/fonts.js');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(cached.size).toBe(0);
+
+    workers.controller = {};
+    workers.dispatchEvent(new Event('controllerchange'));
+    await pending;
+    expect(cached.has('/sdkjs/common/libfont/engine/fonts.js')).toBe(true);
+  });
+
+  it('settles a control wait on departure and leaves the URL retryable after returning', async () => {
+    const { workers, win, hook, fetchMock } = setup(undefined, false);
+    const pending = hook.warm('/awaiting-control.js');
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    win.dispatchEvent(new Event('beforeunload'));
+    await pending;
+    workers.controller = {};
+    workers.dispatchEvent(new Event('controllerchange'));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    win.dispatchEvent(new Event('pointerdown'));
+    await hook.warm('/awaiting-control.js');
+    expect(fetchMock.mock.calls.filter(([url]) => url === '/awaiting-control.js')).toHaveLength(1);
+  });
+
   it('holds a waiting upgrade without poisoning URLs, then warms after controllerchange', async () => {
     const { registration, workers, win, hook, fetchMock } = setup();
     registration.waiting = Object.assign(new EventTarget(), { state: 'installed' });