react-x11 2.1.0 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/nodes.js

@@ -254,6 +254,15 @@ const DAMAGE_SLOP = 1;
 // pass, and always restored through `finally`.
 let layoutDiffSink = null;
 
+// The uniform translation the subtree currently being walked is riding: set
+// while a scroll container whose blit is armed lays its children out, so the
+// diff can tell "moved" from "scrolled" (issue #398). Every child of such a
+// container lands at its old rect plus this shift, which is precisely what
+// the blit is about to do to those pixels — so it is not a change, and the
+// diff reports only the children that landed somewhere else. Null everywhere
+// else, and restored through `finally` like the sink beside it.
+let layoutDiffShift = null;
+
 // What an invalidate() may name as its reason — a small closed set, so the
 // frame log, the tracer and the full-repaint warning can print "why" next
 // to "where". A typo'd reason would silently vanish from every report, so
@@ -314,6 +323,13 @@ const NO_SCROLL_BLIT = process.env.REACT_X11_NO_SCROLL_BLIT === '1';
 // exposed strip is most of a repaint anyway.
 const SCROLL_BLIT_MIN_KEEP = 0.5;
 
+// …and how much of it the frame may end up repainting anyway. The strip and
+// the scrollbar repair sit under this by a wide margin; what can push past
+// it is a ledger repair (issue #398) that the damage cap had to merge with
+// the scrollbar column, whose box then reaches back across the viewport.
+// Past this the blit is buying a shift and paying for the viewport anyway.
+const SCROLL_BLIT_MAX_REPAINT = 0.75;
+
 // The server-side event mask every realized window ends up with. The
 // subscriptions are a constant — the EventManager's pointer/key/focus
 // listeners, the window's own resize/draw/expose pair, the backing store's
@@ -353,6 +369,14 @@ const BLIT_POISONED = Object.freeze({ poisoned: true });
 // net delta in `_pendingBlitContents` beside it.
 const BLIT_CONTENTS = Object.freeze({ contents: true });
 
+// How much of what changed inside a blitting viewport the ledger will carry
+// before the frame gives up and repaints the viewport instead (issue #398).
+// A virtualized list's scroll frame changes a handful of regions — the two
+// spacers and the entering rows — and past that the blit plus a scatter of
+// repaints stops being cheaper than the one pass it replaced.
+const BLIT_MAX_CLAIMS = 8;
+const BLIT_MAX_CLAIM_AREA = 0.25;
+
 const rectContains = (outer, inner) =>
   outer.x <= inner.x &&
   outer.y <= inner.y &&
@@ -1441,6 +1465,13 @@ function shallowEqual(a, b) {
   return ka.length === kb.length && ka.every((k) => a[k] === b[k]);
 }
 
+/** The half of `Node._joinsYoga` that is about the child alone — a real X
+ * window (`<window>`, `<popup>`) or a node built without a box at all (a text
+ * chunk) sits outside whatever parent it lands in. This is what
+ * `_nonYogaKids` counts, so the count stays right for a parent that has no
+ * box of its own either. */
+const outsideYoga = (child) => !child.yoga || child.isWindow;
+
 export class Node {
   get ownerDocument() {
     return DEVTOOLS_FAKE_DOCUMENT;
@@ -1465,6 +1496,20 @@ export class Node {
     this.app = app;
     this.parent = null;
     this.children = [];
+    // Where this node sits in `parent.children`, and how many of *this*
+    // node's children sit outside its yoga tree. Both are bookkeeping that
+    // turns the scans `insertBefore` used to do over the whole child list
+    // into constant work, which is what stops a commit that mounts a
+    // virtualized list's window from costing O(rows x pane) (issue #397).
+    // The index is a hint — `_indexOfChild` proves it before using it — and
+    // the count is exact, maintained by the three places `children` is
+    // spliced.
+    this._childIndex = -1;
+    this._nonYogaKids = 0;
+    // The pre-mutation bounds this frame already claimed for this node, so
+    // that a second mutation reuses the rect instead of walking the subtree
+    // again. Lives exactly as long as membership in `root._reflowed`.
+    this._reflowBefore = null;
     this.root = null; // owning WindowNode once attached
     this.hidden = false;
     this.destroyed = false;
@@ -2199,8 +2244,19 @@ export class Node {
   }
 
   /** The theme above or on this node changed: drop the caches and restyle
-   * the subtree, since a token can appear at any depth. */
-  _themeChanged() {
+   * the subtree, since a token can appear at any depth.
+   *
+   * `mounting` is `insertBefore` attaching a subtree that has never been in
+   * the tree: the walk still resolves every token — the nodes can see their
+   * ancestors now — but it claims no damage (issue #402). A node that has
+   * never painted has no stale pixels to cover, and the rect it is about to
+   * occupy is claimed by the child-list/layout-diff protocol like any other
+   * inserted child's; the unbounded claims below would turn every commit
+   * that mounts a token-styled node into a full-window repaint — which is
+   * every re-slice of a virtualized list whose rows follow the palette. A
+   * live theme *swap* is the other caller and keeps them: it moves pixels
+   * that are already on screen, anywhere in the subtree. */
+  _themeChanged(mounting = false) {
     // This walk visits every node itself, so the per-node re-resolution below
     // is enough — a style swap it causes must not start a second walk of the
     // same subtree from halfway down.
@@ -2224,19 +2280,23 @@ export class Node {
         if (localTextStyleChanged(this.style, before)) {
           this._textContentChanged();
         }
-        this.root?.invalidate(true, null, 'theme');
+        if (!mounting) this.root?.invalidate(true, null, 'theme');
       }
       // The palette is the floor under the cascade, so a theme swap moves the
       // resolved style of every node that named none of its own — and none of
       // that is in a style object, so nothing above would have noticed. A
       // swap that only changes `fontFamily` is the case that made this worth
       // having: nothing else about the node changes, and a cached layout
-      // carries the face it was shaped with.
-      if (this._retext() !== 0) this.root?.invalidate(true, null, 'theme');
+      // carries the face it was shaped with. `_retext` runs on a mount too —
+      // its own claims are bounded — but cannot answer non-zero there: a
+      // node that was never attached has never resolved a text style.
+      if (this._retext() !== 0 && !mounting) {
+        this.root?.invalidate(true, null, 'theme');
+      }
       if (wasDirection !== undefined && this.direction !== wasDirection) {
         this._directionMoved();
       }
-      for (const child of this.children) child._themeChanged();
+      for (const child of this.children) child._themeChanged(mounting);
     } finally {
       inThemeWalk--;
     }
@@ -2256,6 +2316,12 @@ export class Node {
   /** Number of yoga-bearing children before `index` (window children and
    * text spans/chunks do not join the parent's yoga tree). */
   _yogaIndexAt(index) {
+    // A list of ordinary boxes — a scroll pane's rows, which is the list
+    // this is asked about a hundred times in one commit — has every child in
+    // the yoga tree, and then the yoga index *is* the child index. Counting
+    // the exceptions as they arrive turns that answer into a read instead of
+    // a walk of every sibling in front of the new row (issue #397).
+    if (this._nonYogaKids === 0) return index;
     let n = 0;
     for (let i = 0; i < index; i++) {
       if (this._joinsYoga(this.children[i])) n++;
@@ -2267,6 +2333,24 @@ export class Node {
     return Boolean(this.yoga && child.yoga && !child.isWindow);
   }
 
+  /**
+   * Where `child` sits in `this.children`.
+   *
+   * The cached slot is checked rather than trusted: a node appears in the
+   * list once, so `children[i] === child` *is* the proof that `i` is its
+   * index, and a cache that has gone stale costs a scan rather than a wrong
+   * answer. `_spliceChild` refreshes the two slots it knows — the child it
+   * placed and the sibling it pushed along — which is what keeps a run of
+   * inserts in front of the same trailing sibling (every virtualized list's
+   * commit) off the scan entirely.
+   */
+  _indexOfChild(child) {
+    if (this.children[child._childIndex] === child) return child._childIndex;
+    const i = this.children.indexOf(child);
+    child._childIndex = i;
+    return i;
+  }
+
   /**
    * Give this node's box a measure function, keeping a reference that can be
    * asked again later.
@@ -2354,12 +2438,22 @@ export class Node {
    * by calling insertBefore with a child that is *already* mounted here, and
    * without the removal it would appear twice. Returns the new index. */
   _spliceChild(child, beforeChild) {
-    const from = this.children.indexOf(child);
+    // `parent === this` is the cheap form of "already in this list" — the
+    // two are set and cleared together — so a child arriving for the first
+    // time, which is every node of a freshly mounted subtree, pays no scan
+    // at all for the question.
+    const from = child.parent === this ? this._indexOfChild(child) : -1;
     if (from !== -1) this.children.splice(from, 1);
-    const before =
-      beforeChild == null ? -1 : this.children.indexOf(beforeChild);
+    else if (outsideYoga(child)) this._nonYogaKids++;
+    const before = beforeChild == null ? -1 : this._indexOfChild(beforeChild);
     const index = before === -1 ? this.children.length : before;
     this.children.splice(index, 0, child);
+    // The two slots this splice knows. Every other cached index at or after
+    // `index` has shifted by one and will be caught by the check in
+    // `_indexOfChild`; these two are the ones a run of inserts in front of
+    // the same sibling asks about again on the very next call.
+    child._childIndex = index;
+    if (beforeChild != null) beforeChild._childIndex = index + 1;
     return index;
   }
 
@@ -2368,9 +2462,10 @@ export class Node {
       // popups live anywhere in the JSX tree but are independent
       // override-redirect windows: bookkeeping only, no yoga, no paint —
       // but they do inherit the theme of where they are written
+      const mounting = child.parent == null;
       this._spliceChild(child, beforeChild);
       child.parent = this;
-      if (this.theme || child.props.theme) child._themeChanged();
+      if (this.theme || child.props.theme) child._themeChanged(mounting);
       a11yHooks.attached?.(this, child);
       return;
     }
@@ -2407,13 +2502,19 @@ export class Node {
       );
     }
     // captured before the child joins, so it covers the arrangement that is
-    // about to be replaced (see _childListChanged)
-    const before = this.paintBounds();
+    // about to be replaced (see _childListChanged). A viewport mid-blit has
+    // nothing vacating — the child being added had no pixels — and the
+    // layout diff claims where it lands, so it names no region at all.
+    const before = this._blitLedgerOpen() ? null : this._childListBefore();
     // a move has to leave the yoga tree too — yoga aborts on insertChild of
     // a node that still has a parent
-    if (this.children.includes(child) && this._joinsYoga(child)) {
+    if (child.parent === this && this._joinsYoga(child)) {
       this.yoga.removeChild(child.yoga);
     }
+    // no parent means never attached: this insert is a mount, and the theme
+    // walk resolves without claiming — a keyed reorder arrives here too, with
+    // its parent still set, and that one keeps the claims (issue #402)
+    const mounting = child.parent == null;
     const index = this._spliceChild(child, beforeChild);
     child.parent = this;
     if (this._joinsYoga(child)) {
@@ -2423,12 +2524,98 @@ export class Node {
     child._registerSizeQueries();
     // it can see its ancestors now, so any token in its style can resolve.
     // With no theme anywhere there is nothing to resolve and nothing to walk
-    if (this.theme || child.props.theme) child._themeChanged();
+    if (this.theme || child.props.theme) child._themeChanged(mounting);
     this._textContentChanged();
     this._childListChanged(before);
     a11yHooks.attached?.(this, child);
   }
 
+  /**
+   * Is this node a scroll container that has a blit armed and still clean
+   * this frame (issue #398)?
+   *
+   * While it is, the window keeps a *ledger* of the regions that actually
+   * changed inside the viewport instead of cancelling the blit at the first
+   * sign of one. The coarse claims this node would otherwise make — its own
+   * box, which is all `paintBounds()` can say for a node that clips — would
+   * cover the whole band the blit is about to move and throw that ledger
+   * away, so the paths that make them take a finer route while this is true.
+   *
+   * `scrollContents` is out: an element blit already tests foreign claims
+   * against the rect it handed over (issue #309), and its region is not a
+   * viewport whose children *are* the scrolled content.
+   */
+  _blitLedgerOpen() {
+    const from = this._pendingBlitFrom;
+    return (
+      from != null &&
+      from !== BLIT_POISONED &&
+      !this._pendingBlitContents &&
+      this._blitLedger != null
+    );
+  }
+
+  /**
+   * Write one changed region into this viewport's ledger, in the coordinates
+   * it was named in. Returns false when the frame is better off repainting
+   * the viewport — too many regions to be worth the bookkeeping, or one big
+   * enough that there is nothing left for the blit to keep — which the
+   * caller turns into the poison the gate used to apply unconditionally.
+   *
+   * Which side of the frame's layout pass the rect came from decides
+   * whether it moves with the blit: a claim made during the commit names
+   * where the content sits *now*, and the blit is about to shift it, so
+   * `_applyScrollBlits` shifts the rect too. A claim raised once layout has
+   * run — the diff's, the reflow queue's — already names where it landed.
+   * Read off the window rather than passed in, so a claim from application
+   * code reached during the layout pass is filed on the right side of it.
+   */
+  _recordBlitClaim(rect) {
+    const ledger = this._blitLedger;
+    if (!ledger || ledger.length >= BLIT_MAX_CLAIMS) return false;
+    const inside = intersectRects(rect, this.abs);
+    // beside the band the blit moves: those pixels are painted the ordinary
+    // way, out of the frame's own damage
+    if (!inside) return true;
+    // …and a claim that covers the viewport leaves the blit nothing to keep
+    if (rectContains(inside, this.abs)) return false;
+    ledger.push({ ...inside, pre: !this.root?._laidOut });
+    return true;
+  }
+
+  /**
+   * This node's paint bounds from before a child-list mutation — the `before`
+   * half of `_childListChanged`'s protocol, captured while a departing child
+   * is still attached.
+   *
+   * Walked once per node per frame rather than once per mutation. A commit
+   * that mounts a virtualized list's window inserts a hundred rows into one
+   * pane, one `insertBefore` at a time, and a walk of the whole pane per row
+   * is what made that commit O(rows x pane) (issue #397).
+   *
+   * Reusing the first walk's answer is not an approximation. Nothing is laid
+   * out or painted between two mutations in the same frame, so every child
+   * still carries the rect it was last painted at, and a child that leaves
+   * later in the frame was in the list — and so inside the rect — when the
+   * first walk ran. `root._reflowed` is the marker for "this frame already
+   * has one", which is exactly its lifetime: joined at the first claim,
+   * cleared by `flush()`.
+   */
+  _childListBefore() {
+    const root = this.root;
+    // A subtree still being built off-tree claims nothing — this is the
+    // `appendInitialChild` path, which is most of a mount, and where the
+    // walk used to be thrown away by `_childListChanged`'s `!root` return.
+    if (!root) return null;
+    if (root._reflowed.has(this) && this._reflowBefore) {
+      return this._reflowBefore;
+    }
+    // NO_DAMAGE, not null, when a blitting viewport above clips this node
+    // away entirely (issue #398): null here would read as "somewhere" and
+    // repaint the window.
+    return (this._reflowBefore = this._claimBounds() ?? NO_DAMAGE);
+  }
+
   /**
    * A child was inserted or removed. `before` is this node's paint bounds from
    * *before* the mutation, which the caller has to capture while the departing
@@ -2448,20 +2635,35 @@ export class Node {
     this._clearHitBounds();
     const root = this.root;
     if (!root) return;
+    // A viewport keeping a ledger this frame (issue #398) says both halves
+    // of the protocol finer: `before` is the departing child's own rect
+    // rather than this node's box, and the "after" half comes from the
+    // shifted layout diff, which claims an entering child where it lands
+    // and says nothing about the ones that only rode the scroll. Joining
+    // `_reflowed` would undo both — its post-layout claim is this node's
+    // box, the whole band the blit is about to move.
+    if (this._blitLedgerOpen()) {
+      root.invalidate(true, before ?? NO_DAMAGE, 'child-list');
+      return;
+    }
     root.invalidate(true, before, 'child-list');
     root._reflowed.add(this);
   }
 
   removeChild(child) {
-    const index = this.children.indexOf(child);
+    const index = this._indexOfChild(child);
     if (index === -1) return;
     // told while the child is still wired, so the bridge can compute the
     // index the AT will see the removal at
     a11yHooks.detach?.(this, child);
     // captured while the child is still attached, so it covers the rect the
-    // child is about to stop occupying
-    const before = this.paintBounds();
+    // child is about to stop occupying — the child's own, for a viewport
+    // mid-blit, where this node's box is the whole scrolled band
+    const before = this._blitLedgerOpen()
+      ? (child._claimBounds() ?? NO_DAMAGE)
+      : this._childListBefore();
     this.children.splice(index, 1);
+    if (outsideYoga(child)) this._nonYogaKids--;
     if (this._joinsYoga(child)) {
       this.yoga.removeChild(child.yoga);
     }
@@ -3020,7 +3222,37 @@ export class Node {
     this._clearHitBounds();
     if (layoutDiffSink) {
       const grow = this._outlineExtent() + DAMAGE_SLOP;
-      if (old.width > 0 && old.height > 0) {
+      const shift = layoutDiffShift;
+      const had = old.width > 0 && old.height > 0;
+      if (shift) {
+        // Riding a blit (issue #398): the rect this node *would* have had if
+        // nothing but the scroll had happened. Landing there is the blit's
+        // own translation and claims nothing — claiming it would repaint the
+        // band the blit exists to keep. Landing anywhere else is a real move,
+        // and both ends of it are claimed in post-blit coordinates, which is
+        // where the frame will paint them.
+        const was = {
+          x: old.x + shift.x,
+          y: old.y + shift.y,
+          width: old.width,
+          height: old.height,
+        };
+        if (
+          had &&
+          was.x === x &&
+          was.y === y &&
+          old.width === width &&
+          old.height === height
+        ) {
+          return;
+        }
+        if (had) layoutDiffSink(insetRect(was, -grow));
+        if (width > 0 && height > 0) {
+          layoutDiffSink(insetRect(this.abs, -grow));
+        }
+        return;
+      }
+      if (had) {
         layoutDiffSink(insetRect(old, -grow));
       }
       if (width > 0 && height > 0) {
@@ -3199,10 +3431,48 @@ export class Node {
   _invalidateLayout(reason) {
     const root = this.root;
     if (!root) return;
-    root.invalidate(true, this.paintBounds(), reason);
+    // Same walk, same frame, same answer — see `_childListBefore`, whose
+    // record this shares so that a reflow and a child-list change on one
+    // node in one frame walk the subtree once between them.
+    root.invalidate(true, this._childListBefore(), reason);
     root._reflowed.add(this);
   }
 
+  /**
+   * `paintBounds()` with the one clip a damage claim must respect: a scroll
+   * container above this node that is waiting to blit (issue #398).
+   *
+   * A viewport clips its children, so the part of a claim outside its box is
+   * pixels that cannot appear — and leaving it in costs the blit the frame.
+   * A virtualized list is the shape that makes this concrete: its spacers
+   * are boxes thousands of pixels tall whose visible extent is a sliver or
+   * nothing at all, and their unclipped claims, coalesced into the scroll's
+   * own, leave `_blitKeptDamage` a damage rect many times the viewport to
+   * refuse. Null when the clip left nothing.
+   *
+   * Only while a blit is pending — outside that this is `paintBounds()` and
+   * one property read. Clipping every claim to every clipping ancestor
+   * would be correct too, and is a bigger change than the frame this is
+   * about.
+   */
+  _claimBounds() {
+    const bounds = this.paintBounds();
+    const sv = this._blitViewport();
+    return sv ? intersectRects(bounds, sv.paintBounds()) : bounds;
+  }
+
+  /** The scroll container above this node that is waiting to blit, if there
+   *  is one — the viewport whose ledger this node's claims belong in, and
+   *  whose box clips them (issue #398). One property read when no blit is
+   *  pending, which is every frame that is not a scroll. */
+  _blitViewport() {
+    if (!this.root?._pendingScrolls?.size) return null;
+    for (let n = this.parent; n; n = n.parent) {
+      if (n._blitLedgerOpen()) return n;
+    }
+    return null;
+  }
+
   /**
    * The region this node can put ink in: its own rect unioned with every
    * descendant's. Not the same as `abs` — a child of a node that does not
@@ -5100,13 +5370,31 @@ export const Scrollable = (Base) =>
       // real layout — claim it, but clipped to the viewport: ink below the
       // fold never reaches the surface, and an unclipped claim would repaint
       // whatever unrelated UI sits under this node's off-viewport extent.
-      const shifted =
-        this._childOrigin &&
-        (this._childOrigin.x !== ox || this._childOrigin.y !== oy);
+      const wasOrigin = this._childOrigin;
+      const shifted = wasOrigin && (wasOrigin.x !== ox || wasOrigin.y !== oy);
       this._childOrigin = { x: ox, y: oy };
       const outer = layoutDiffSink;
+      const outerShift = layoutDiffShift;
+      const ledger = shifted && this._blitLedgerOpen();
       if (outer) {
-        if (shifted) {
+        if (ledger) {
+          // The blit's own ledger takes this walk (issue #398). The shift
+          // below is what makes the diff worth running under a scroll at
+          // all: without it every child reports the move the blit is about
+          // to make for them, and the claims add up to the viewport. What
+          // is left is the virtualized list's real frame — the rows that
+          // entered, the ones that left, a spacer that resized — and it
+          // goes to the ledger rather than to `outer`, whose claims are
+          // what `layoutMoved` reads as "this frame is not a pure scroll".
+          const vp = insetRect(this.abs, -DAMAGE_SLOP);
+          layoutDiffSink = (rect) => {
+            const clipped = intersectRects(rect, vp);
+            if (clipped && !this._recordBlitClaim(clipped)) {
+              this._pendingBlitFrom = BLIT_POISONED;
+            }
+          };
+          layoutDiffShift = { x: ox - wasOrigin.x, y: oy - wasOrigin.y };
+        } else if (shifted) {
           layoutDiffSink = null;
         } else {
           const vp = insetRect(this.abs, -DAMAGE_SLOP);
@@ -5124,6 +5412,7 @@ export const Scrollable = (Base) =>
         }
       } finally {
         layoutDiffSink = outer;
+        layoutDiffShift = outerShift;
       }
     }
 
@@ -5274,10 +5563,19 @@ export const Scrollable = (Base) =>
         // has not claimed yet, so damage already overlapping this viewport
         // is foreign by construction: poison the frame instead of arming,
         // and the full-viewport repaint below stays in force.
-        if (this._pendingBlitFrom == null && Array.isArray(root._damage)) {
+        const arming = this._pendingBlitFrom == null;
+        // The ledger this frame's changes inside the viewport are written
+        // to (issue #398). Opened with the blit and read by
+        // _applyScrollBlits, which clears it beside the origin.
+        if (arming) this._blitLedger = [];
+        if (arming && Array.isArray(root._damage)) {
           const zone = insetRect(this.abs, -(DAMAGE_SLOP * 2 + 1));
           for (const rect of root._damage) {
-            if (rectsOverlap(rect, zone)) {
+            // Already coalesced, so these rects are as coarse as the frame
+            // has made them — which the ledger reads conservatively: a blob
+            // that swallowed the viewport says so and poisons, exactly as
+            // this gate used to for every claim it saw.
+            if (rectsOverlap(rect, zone) && !this._recordBlitClaim(rect)) {
               this._pendingBlitFrom = BLIT_POISONED;
               break;
             }
@@ -9465,6 +9763,7 @@ export class WindowNode extends Scrollable(Node) {
       return;
     }
     if (child.isWindow) {
+      const mounting = child.parent == null;
       this._spliceChild(child, beforeChild);
       child.parent = this;
       // Initial children are realized when this window realizes; a child
@@ -9476,7 +9775,7 @@ export class WindowNode extends Scrollable(Node) {
         child.realize(this.window);
         if (child.window) this._xStack.push(child.window.id);
       }
-      if (this.theme || child.props.theme) child._themeChanged();
+      if (this.theme || child.props.theme) child._themeChanged(mounting);
       // React reorders a keyed list with one insertBefore per moved child;
       // restacking once at the end of the commit skips the intermediate
       // orders, which nobody ever sees.
@@ -9488,8 +9787,11 @@ export class WindowNode extends Scrollable(Node) {
 
   removeChild(child) {
     if (child.isWindow) {
-      const index = this.children.indexOf(child);
-      if (index !== -1) this.children.splice(index, 1);
+      const index = this._indexOfChild(child);
+      if (index !== -1) {
+        this.children.splice(index, 1);
+        this._nonYogaKids--;
+      }
       const id = child.window?.id;
       child.parent = null;
       child.destroySubtree();
@@ -9951,14 +10253,21 @@ export class WindowNode extends Scrollable(Node) {
     // rects coalesce a change inside the viewport is indistinguishable from
     // the scroll's own claim. (Unbounded claims need no check: FULL_DAMAGE
     // fails the blit's damage gate by itself.)
+    // The region this claim actually covers — a node's paint reach, clipped
+    // to a blitting viewport above it (issue #398), or the bare rect a
+    // caller handed over. Null when the clip left nothing (the node draws
+    // where nothing can be seen, so it owes no pixels), and null on a frame
+    // that is already unbounded, which owes neither a rect nor the subtree
+    // walk that measures one — a blit cannot fire there either.
+    const bounds =
+      damage && damage !== NO_DAMAGE && this._damage !== FULL_DAMAGE
+        ? damage._claimBounds
+          ? damage._claimBounds()
+          : damage
+        : null;
     const pendingScrolls = this._pendingScrolls;
-    if (
-      pendingScrolls?.size &&
-      damage &&
-      damage !== NO_DAMAGE &&
-      this._scrollClaim !== damage
-    ) {
-      const rect = damage.paintBounds ? damage.paintBounds() : damage;
+    if (pendingScrolls?.size && bounds && this._scrollClaim !== damage) {
+      const rect = bounds;
       for (const sv of pendingScrolls) {
         // An element blitting a region of its own drawing (issue #303) is
         // waiting on that region, not on the whole node it lives in — and
@@ -9979,6 +10288,15 @@ export class WindowNode extends Scrollable(Node) {
           ? contents.rect
           : sv.abs && insetRect(sv.abs, -(DAMAGE_SLOP * 2 + 1));
         if (!waiting || rectsOverlap(rect, waiting)) {
+          // …unless this viewport is keeping a ledger of what changed
+          // inside it (issue #398): the region goes in the ledger and
+          // `_applyScrollBlits` repaints it after the blit, which is the
+          // same pixels on screen for a fraction of the drawing. The
+          // ledger says no when the frame stops paying, and then this
+          // falls through to the poison exactly as before.
+          if (sv._blitLedgerOpen() && sv._recordBlitClaim(rect)) {
+            continue;
+          }
           // Poison rather than disarm (react-x11#295): a null here would
           // let a second scrollTo in the same frame re-arm from a
           // mid-frame origin, and the blit would then move pixels that
@@ -9992,16 +10310,18 @@ export class WindowNode extends Scrollable(Node) {
     }
     if (layoutChanged && !damage) this._damage = FULL_DAMAGE;
     else if (!layoutChanged && !damage) this._damage = FULL_DAMAGE;
-    else if (this._damage !== FULL_DAMAGE) {
+    else if (!bounds) {
+      // A layout change that names no region: either NO_DAMAGE, from a
+      // caller with a finer claim already in flight, or a node whose reach
+      // a clipping ancestor left nothing of (issue #398). Unlike `!damage`
+      // neither is "something, somewhere", so neither costs a full repaint.
+    } else if (this._damage !== FULL_DAMAGE) {
       // a node, or a bare rect for a caller that has a region rather than a
       // node — a subtree that is about to be removed, say. Claims accumulate
       // as a list of rects rather than one box around them all, so two changes
       // at opposite corners of the window no longer repaint everything
       // between them.
-      this._damage = addDamageRect(
-        this._damage,
-        damage.paintBounds ? damage.paintBounds() : damage,
-      );
+      this._damage = addDamageRect(this._damage, bounds);
     }
     this.needsPaint = true;
     // Recorded before the `_scheduled` gate, not inside it: the debt is
@@ -10056,6 +10376,10 @@ export class WindowNode extends Scrollable(Node) {
     // not the flag's post-pass value
     const layoutRan = this.needsLayout;
     if (this.needsLayout) {
+      // From here on a claim names where its content *landed*, not where it
+      // sat before the scroll — which is what decides whether a blit
+      // ledger's rect moves with the shift (issue #398).
+      this._laidOut = true;
       this._resolveSizeQueries(width, height);
       this._applyContentFloors(width);
       this.yoga.setWidth(width);
@@ -10091,14 +10415,25 @@ export class WindowNode extends Scrollable(Node) {
       // replaced it. Claimed after layout because an inserted child has no
       // rect before it.
       for (const node of this._reflowed) {
-        if (!node.destroyed)
-          this._damage =
-            this._damage === FULL_DAMAGE
-              ? FULL_DAMAGE
-              : addDamageRect(this._damage, node.paintBounds());
+        // …and the pre-mutation walk this frame reused goes with it
+        node._reflowBefore = null;
+        if (node.destroyed || this._damage === FULL_DAMAGE) continue;
+        // clipped to a blitting viewport above it, like every other claim
+        // this frame, and written to that viewport's ledger too (issue
+        // #398): the claim would otherwise coalesce into the scroll's own
+        // and be dropped with it, leaving the band the blit kept holding
+        // this node's pixels from before the reflow.
+        const after = node._claimBounds();
+        if (!after) continue;
+        const sv = node._blitViewport();
+        if (sv && !sv._recordBlitClaim(after)) {
+          sv._pendingBlitFrom = BLIT_POISONED;
+        }
+        this._damage = addDamageRect(this._damage, after);
       }
       this._reflowed.clear();
     } else if (this._reflowed.size) {
+      for (const node of this._reflowed) node._reflowBefore = null;
       this._reflowed.clear();
     }
     // any node this pass laid out may be what an open popup is anchored to
@@ -10107,6 +10442,9 @@ export class WindowNode extends Scrollable(Node) {
     // a frame that turns out to be a pure scroll blits the surviving band
     // and narrows its claim to the exposed strip
     this._applyScrollBlits(width, height, layoutMoved);
+    // …and the next commit's claims name the arrangement this frame leaves
+    // behind again, from before whatever scroll comes with them
+    this._laidOut = false;
     if (!this.needsPaint) return;
     this.needsPaint = false;
     const damage = this._takeDamage(width, height);
@@ -10185,9 +10523,11 @@ export class WindowNode extends Scrollable(Node) {
     pending.clear();
     const from = nodes[0]._pendingBlitFrom;
     const contents = nodes[0]._pendingBlitContents;
+    const ledger = nodes[0]._blitLedger;
     for (const n of nodes) {
       n._pendingBlitFrom = null;
       n._pendingBlitContents = null;
+      n._blitLedger = null;
     }
     // two viewports scrolling in one frame is rare enough that sorting out
     // whether their regions interact is not worth it
@@ -10267,11 +10607,39 @@ export class WindowNode extends Scrollable(Node) {
     }
     const keep = this._blitKeptDamage(vp);
     if (!keep) return;
+    // What changed inside the viewport while the blit was armed, in the
+    // coordinates the frame is about to paint in (issue #398). A claim made
+    // during the commit named where the content sat before the shift, and
+    // the blit is about to move those pixels by the frame's delta, so it
+    // moves with them; a claim from the layout diff already landed there.
+    //
+    // Repainting the result is what makes the blit honest about them: the
+    // blit translates the previous frame's rendering, which is correct
+    // everywhere the content did not change, and these are the places it
+    // did. That is finer than the strip-only rule issue #398 asks for and
+    // no more complicated, so a mid-viewport change — a row upgrading from
+    // skeleton to content while the list scrolls — rides the fast path too
+    // instead of falling back to the whole viewport.
+    const repairs = [];
+    let repairArea = 0;
+    for (const claim of ledger ?? []) {
+      const moved = claim.pre
+        ? {
+            x: claim.x - dx,
+            y: claim.y - dy,
+            width: claim.width,
+            height: claim.height,
+          }
+        : claim;
+      const inside = intersectRects(moved, vp);
+      if (!inside) continue;
+      repairs.push(inside);
+      repairArea += inside.width * inside.height;
+    }
+    // past this the blit plus a scatter of repaints is no longer cheaper
+    // than the one full-viewport pass it replaced
+    if (repairArea > area * BLIT_MAX_CLAIM_AREA) return;
     if (!this._scrollBlitSafe(node, vp)) return;
-    // scroll offsets grow down/right; the pixels move the other way
-    // (0 - x rather than -x: negating +0 yields -0, which survives into
-    // request buffers and test comparisons)
-    if (!wnd.scrollRegion({ ...vp }, 0 - dx, 0 - dy)) return;
     let rects = keep;
     // the strip the shift exposed, full breadth — it also covers the corner
     // gutter beside the bars, whose old pixels the blit did not overwrite
@@ -10326,6 +10694,24 @@ export class WindowNode extends Scrollable(Node) {
     }
     const crossBar = node._scrollbar(axis === 'y' ? 'x' : 'y');
     if (crossBar) rects = addDamageRect(rects, scrollbarTrackRect(crossBar));
+    for (const repair of repairs) rects = addDamageRect(rects, repair);
+    // The last gate, and the only one that has to wait until the rects are
+    // assembled: the frame carries at most MAX_DAMAGE_RECTS of them, so a
+    // repair that does not sit beside the strip is merged with whatever is
+    // nearest — the scrollbar column, most often — and the box of that
+    // merge can reach back across the viewport. When it does, the blit is
+    // buying a shift and paying for the viewport anyway, so let the plain
+    // repaint scrollTo already claimed have the frame.
+    let painted = 0;
+    for (const rect of rects) {
+      const inside = intersectRects(rect, vp);
+      if (inside) painted += inside.width * inside.height;
+    }
+    if (painted > area * SCROLL_BLIT_MAX_REPAINT) return;
+    // scroll offsets grow down/right; the pixels move the other way
+    // (0 - x rather than -x: negating +0 yields -0, which survives into
+    // request buffers and test comparisons)
+    if (!wnd.scrollRegion({ ...vp }, 0 - dx, 0 - dy)) return;
     this._damage = rects;
   }