feat(fonts): bounded late-load reflow scheduler

When a required face loads after the gate's first-paint timeout the document
must re-measure, but on a slow network a font-heavy doc's faces arrive in many
waves (a probe saw ~38 over ~103s for 40 fonts) - reflowing per wave is a
re-measure storm. FontReadinessGate now batches late-loaded faces through a
small scheduler that flushes once per quiet window (no new face for ~250ms) or
at a max-wait ceiling (~2s) so a steady trickle still corrects within a bounded
time. Not a plain debounce: the ceiling bounds the worst case to ~total/maxWait
flushes instead of one-per-wave. First paint is untouched (still bounded by the
3s per-font gate timeout); notifyFontConfigChanged stays immediate; dispose
cancels pending work so a torn-down editor never reflows.

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontLateLoadReflowScheduler.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi } from 'vitest';
+import { FontLateLoadReflowScheduler, type FontReflowFlushDetails } from './FontLateLoadReflowScheduler';
+
+/** Virtual clock: fires injected timers in due order as the test advances time. */
+function makeClock() {
+  let nowMs = 0;
+  let seq = 0;
+  const timers = new Map<number, { due: number; cb: () => void }>();
+  return {
+    scheduleTimeout: (cb: () => void, ms: number) => {
+      const id = ++seq;
+      timers.set(id, { due: nowMs + ms, cb });
+      return id;
+    },
+    cancelTimeout: (handle: unknown) => {
+      timers.delete(handle as number);
+    },
+    advance: (ms: number) => {
+      const target = nowMs + ms;
+      for (;;) {
+        const dueEntries = [...timers.entries()].filter(([, t]) => t.due <= target).sort((a, b) => a[1].due - b[1].due);
+        if (dueEntries.length === 0) break;
+        const [id, t] = dueEntries[0];
+        timers.delete(id);
+        nowMs = t.due;
+        t.cb();
+      }
+      nowMs = target;
+    },
+  };
+}
+
+function makeScheduler(overrides: { quietMs?: number; maxWaitMs?: number } = {}) {
+  const clock = makeClock();
+  const flushes: FontReflowFlushDetails[] = [];
+  const scheduler = new FontLateLoadReflowScheduler({
+    quietMs: overrides.quietMs ?? 250,
+    maxWaitMs: overrides.maxWaitMs ?? 2000,
+    flush: (d) => flushes.push(d),
+    scheduleTimeout: clock.scheduleTimeout,
+    cancelTimeout: clock.cancelTimeout,
+  });
+  return { scheduler, clock, flushes };
+}
+
+describe('FontLateLoadReflowScheduler', () => {
+  it('batches bursty arrivals into a single quiet-window flush', () => {
+    const { scheduler, clock, flushes } = makeScheduler();
+    scheduler.schedule(['a']);
+    clock.advance(100);
+    scheduler.schedule(['b']);
+    scheduler.schedule(['c']);
+    expect(flushes).toHaveLength(0); // still within the quiet window
+    clock.advance(250);
+    expect(flushes).toHaveLength(1);
+    expect(flushes[0].reason).toBe('quiet');
+    expect(new Set(flushes[0].faceKeys)).toEqual(new Set(['a', 'b', 'c']));
+  });
+
+  it('restarts the quiet window on each new arrival', () => {
+    const { scheduler, clock, flushes } = makeScheduler();
+    scheduler.schedule(['a']);
+    clock.advance(200); // < quiet
+    scheduler.schedule(['b']); // resets quiet
+    clock.advance(200); // 400 total from 'a', but only 200 since 'b'
+    expect(flushes).toHaveLength(0);
+    clock.advance(50); // now 250 since 'b'
+    expect(flushes).toHaveLength(1);
+  });
+
+  it('flushes at the max-wait ceiling even under a steady trickle', () => {
+    const { scheduler, clock, flushes } = makeScheduler({ quietMs: 250, maxWaitMs: 2000 });
+    scheduler.schedule(['a']);
+    // A new face every 200ms keeps resetting the quiet window, but max-wait caps it.
+    for (let t = 0; t < 2000; t += 200) {
+      clock.advance(200);
+      scheduler.schedule([`f${t}`]);
+    }
+    expect(flushes).toHaveLength(1);
+    expect(flushes[0].reason).toBe('max-wait');
+  });
+
+  it('does not flush twice for a repeated same face key', () => {
+    const { scheduler, clock, flushes } = makeScheduler();
+    scheduler.schedule(['a']);
+    scheduler.schedule(['a']); // duplicate -> no new pending, no timer restart
+    clock.advance(250);
+    expect(flushes).toHaveLength(1);
+    expect(flushes[0].faceKeys).toEqual(['a']);
+  });
+
+  it('cancel() drops pending work without flushing', () => {
+    const { scheduler, clock, flushes } = makeScheduler();
+    scheduler.schedule(['a', 'b']);
+    scheduler.cancel();
+    clock.advance(5000);
+    expect(flushes).toHaveLength(0);
+  });
+
+  it('flushNow flushes immediately and arms nothing further', () => {
+    const { scheduler, clock, flushes } = makeScheduler();
+    scheduler.schedule(['a']);
+    scheduler.flushNow();
+    expect(flushes).toHaveLength(1);
+    expect(flushes[0].reason).toBe('manual');
+    clock.advance(5000);
+    expect(flushes).toHaveLength(1); // no second flush from the cleared timers
+  });
+
+  it('flushNow is a no-op when nothing is pending', () => {
+    const { scheduler, flushes } = makeScheduler();
+    scheduler.flushNow();
+    expect(flushes).toHaveLength(0);
+  });
+
+  it('starts a fresh batch after a flush', () => {
+    const { scheduler, clock, flushes } = makeScheduler();
+    scheduler.schedule(['a']);
+    clock.advance(250);
+    expect(flushes).toHaveLength(1);
+    scheduler.schedule(['b']);
+    clock.advance(250);
+    expect(flushes).toHaveLength(2);
+    expect(flushes[1].faceKeys).toEqual(['b']);
+  });
+});

packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontLateLoadReflowScheduler.ts

@@ -0,0 +1,122 @@
+/**
+ * Bounded late-load reflow scheduler.
+ *
+ * When a required font face loads after the readiness gate's first-paint timeout, the
+ * document must re-measure + reflow so it stops rendering against a fallback. On a slow
+ * network a font-heavy document's faces arrive in many waves over tens of seconds (a probe
+ * measured ~38 waves over ~103s for 40 fonts on Slow 3G). Reflowing on every wave is a
+ * full-document re-measure storm.
+ *
+ * This batches late-loaded faces and flushes (one reflow) when EITHER:
+ *  - a QUIET window passes with no new required face arriving (coalesces bursts), OR
+ *  - a MAX-WAIT ceiling passes since the batch started (so a steady trickle of arrivals
+ *    can never delay the correction forever).
+ *
+ * It is NOT a plain debounce: a debounce alone never fires while arrivals keep coming, so a
+ * trickle every few seconds would still reflow per wave. The max-wait ceiling bounds the
+ * worst case to ~totalTime/maxWait reflows instead of one-per-wave. It does not touch first
+ * paint - the gate's per-font timeout already bounds that; this only governs the
+ * after-the-fact corrections.
+ *
+ * Timer hooks are injectable so the policy is unit-testable without real time.
+ */
+
+export type FontReflowFlushReason = 'quiet' | 'max-wait' | 'manual';
+
+export interface FontReflowFlushDetails {
+  reason: FontReflowFlushReason;
+  /** The face keys batched into this flush (diagnostic; the gate reflows the whole doc). */
+  faceKeys: string[];
+}
+
+export interface FontLateLoadReflowSchedulerOptions {
+  /** Idle gap after the last new required face before flushing. */
+  quietMs?: number;
+  /** Hard ceiling from the first pending face to a flush, regardless of new arrivals. */
+  maxWaitMs?: number;
+  /** Perform the actual one-shot reflow (bump epoch + invalidate caches + request reflow). */
+  flush: (details: FontReflowFlushDetails) => void;
+  /** Timer hooks (injectable for tests); default to the globals. */
+  scheduleTimeout?: (cb: () => void, ms: number) => unknown;
+  cancelTimeout?: (handle: unknown) => void;
+}
+
+export const DEFAULT_REFLOW_QUIET_MS = 250;
+export const DEFAULT_REFLOW_MAX_WAIT_MS = 2000;
+
+export class FontLateLoadReflowScheduler {
+  readonly #quietMs: number;
+  readonly #maxWaitMs: number;
+  readonly #flush: (details: FontReflowFlushDetails) => void;
+  readonly #scheduleTimeout: (cb: () => void, ms: number) => unknown;
+  readonly #cancelTimeout: (handle: unknown) => void;
+
+  readonly #pending = new Set<string>();
+  #quietHandle: unknown = null;
+  #maxWaitHandle: unknown = null;
+
+  constructor(options: FontLateLoadReflowSchedulerOptions) {
+    this.#quietMs = options.quietMs ?? DEFAULT_REFLOW_QUIET_MS;
+    this.#maxWaitMs = options.maxWaitMs ?? DEFAULT_REFLOW_MAX_WAIT_MS;
+    this.#flush = options.flush;
+    this.#scheduleTimeout = options.scheduleTimeout ?? ((cb, ms) => globalThis.setTimeout(cb, ms));
+    this.#cancelTimeout =
+      options.cancelTimeout ?? ((handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>));
+  }
+
+  /**
+   * Record newly-available required face keys and (re)arm the flush timers. A call that
+   * adds no new key is a no-op (it does not restart the quiet window), so repeated
+   * `loadingdone` for the same face cannot keep the batch open or cause a second flush.
+   */
+  schedule(changedFaceKeys: Iterable<string>): void {
+    let added = false;
+    for (const key of changedFaceKeys) {
+      if (!this.#pending.has(key)) {
+        this.#pending.add(key);
+        added = true;
+      }
+    }
+    if (!added) return;
+
+    // Restart the quiet window on each new arrival.
+    if (this.#quietHandle !== null) this.#cancelTimeout(this.#quietHandle);
+    this.#quietHandle = this.#scheduleTimeout(() => this.#fire('quiet'), this.#quietMs);
+
+    // Anchor the max-wait ceiling at the FIRST pending face of this batch.
+    if (this.#maxWaitHandle === null) {
+      this.#maxWaitHandle = this.#scheduleTimeout(() => this.#fire('max-wait'), this.#maxWaitMs);
+    }
+  }
+
+  /** Flush any pending batch immediately (no-op if nothing is pending). */
+  flushNow(reason: FontReflowFlushReason = 'manual'): void {
+    if (this.#pending.size === 0) return;
+    this.#fire(reason);
+  }
+
+  /** Drop any pending batch and timers WITHOUT flushing (call on teardown). */
+  cancel(): void {
+    this.#clearTimers();
+    this.#pending.clear();
+  }
+
+  #fire(reason: FontReflowFlushReason): void {
+    this.#clearTimers();
+    if (this.#pending.size === 0) return;
+    const faceKeys = [...this.#pending];
+    this.#pending.clear();
+    this.#flush({ reason, faceKeys });
+  }
+
+  #clearTimers(): void {
+    if (this.#quietHandle !== null) {
+      this.#cancelTimeout(this.#quietHandle);
+      this.#quietHandle = null;
+    }
+    if (this.#maxWaitHandle !== null) {
+      this.#cancelTimeout(this.#maxWaitHandle);
+      this.#maxWaitHandle = null;
+    }
+  }
+}