Fix home-page flicker AND close #725: interactive snapshot removed only after the routed DOM settles

[milanmajchrak]

Problem

Follow-up to #1318. On the real VSB instance (dev-6.pc), an incognito Ctrl+Shift+R still flickers — the home page visibly "preblikne". My earlier verification passed only because my local backend was too fast to reproduce the anonymous case; this time I reproduced and validated frame-by-frame against the live instance.

Root cause (different from #1318's assumption)

The home page renders piecewise — navbar, search box, community list and recent submissions each fetch their own data and appear at different times. #1318 dropped the SSR snapshot as soon as <ds-app> had #main-content + height ≥ 200px, which is already true while the page is still half-built. So on a hard reload the snapshot is removed mid-render, exposing an incomplete page that then pops into place.

Deployed code drops the snapshot at ~3771ms — half-built (no search box, no community list, navbar collapsed, content jumped to "Recent Submissions"):

~600ms later the same page is complete (what the SSR snapshot already showed):

That jump between the two is the flicker.

Fix — wait for the routed DOM to settle

After the auth/theme gate opens, keep the snapshot until the real <ds-app> subtree has had no element added/removed for 600ms (SETTLE_QUIET_MS) via a MutationObserver — i.e. the page finished rendering its sections — requiring a minimum amount of content first and capped at 10s (SETTLE_MAX_MS; the 15s fallback in index.html stays as the ultimate net).

Crucially this stays decoupled from ApplicationRef.isStable (DOM-settle ignores non-rendering background async), so it does not bring back the post-login non-interactive page (#725).

Review-driven update: issue #725 fully closed (interactive while masked)

Three Angular reviewers checked this for #725 regression risk. Key finding: DOM-settle alone only
shortened #725 — during the (now ~2-5s) masking window the page was still non-interactive,
because the opaque overlay sat over a visibility:hidden <ds-app> (clicks landed on nothing), and
the duplicate snapshot DOM still tripped strict-mode E2E locators. So two more changes were made:

• Interactive while masked. The overlay is already opaque + pointer-events:none; the only thing
  that killed interaction was a redundant visibility:hidden rule on <ds-app>. Dropping it (and
  giving the overlay min-height:100vh) means clicks pass through the opaque snapshot to the
  real, still-visible app underneath. The page is interactive the entire time it is masked, so
  import-TUL-dev5 #725 ("looks rendered but nothing is clickable") cannot recur — even if removal rides the 10s cap.
  The snapshot is aria-hidden so AT/locators target the live app.
• Bypass the overlay under WebDriver (navigator.webdriver), mirroring the existing Cypress
  guard, so Playwright/Selenium see no overlay and no duplicate DOM (the import-TUL-dev5 #725 strict-mode failure).
• Exclude the admin-sidebar subtree from the settle observer (its long animations would re-arm the
  quiet window and push admin toward the cap); add OnDestroy/takeUntil teardown.

Verified on the live build (Playwright, throttled):

check	result
WebDriver run (real Playwright)	overlay absent -> no duplicate DOM
webdriver spoofed false (real-user path): click navbar while snapshot still shown	click reaches the live <ds-app> -> interactive under mask
anon reveal	settled, CLS after reveal = 0
admin reveal	settled (reason "settled", not the cap), CLS after reveal = 0

So the flicker (CLS -> 0) and #725 (interactive throughout, no duplicate DOM for E2E) are both
resolved together, rather than traded against each other.

This is the original #1287 flicker, measured with #1287's own metric (CLS)

PR #1287 defined the problem as a layout shift — it reported CLS 0.89 — and its goal was to "reveal the CSR DOM in its final data-loaded state." Revealing early (deployed) is a visible layout shift; revealing once the DOM has settled is the final data-loaded state. Measured on dev-6.pc, the layout shift that occurs after the snapshot is removed (what the user actually sees):

scenario	overlay removed @	CLS after reveal
anon — deployed (early removal)	~2.0 s	0.32 - 0.36
anon — DOM-settle (this fix)	~3.6 - 4.0 s	0.00
admin — deployed (early removal)	~3.0 s	0.42
admin — DOM-settle (this fix)	~4.7 s	0.00

DOM-settle is exactly #1287's "final data-loaded state" detector — what #1288 approximated with isStable (too slow) and #1317 dropped (revealing early -> CLS back). The fix restores #1287's intent and drives the post-reveal CLS to 0.

Validation (against the live dev-6.pc instance)

I intercepted the overlay-removal call and drove it with the new DOM-settle condition, screencasting the result:

Scenario	deployed (#1318) drops @	DOM-settle drops @	page at that moment
anon reload	~3.2 s (half-built)	~4.8 s	complete
admin reload	~3.6 s	~5.0 s (reason: settled, not the cap)	complete; ~5 s, not the 15 s of #1288

DOM-settle drops the snapshot only once the page is complete:

Screencast videos: deployed (flicker) · DOM-settle (no flicker).

Robustness across instances (not tuned to one)

DOM-settle reacts to each load's actual DOM, so the reveal time is adaptive, not a fixed clock. Stress-tested on dev-6.pc from Fast-3G to a pathological 700ms-latency / 350kbps profile (anon):

network / CPU	reveal @	CLS after reveal
Fast-3G / 4x	3.8 - 4.8 s	0
Slow / 4x	5.4 - 5.6 s	0
Slow / 6x	6.7 - 7.1 s	0
700ms-lat 350kbps / 6x	9.4 - 10.8 s	0

The reveal time scales with how slow the instance is; CLS stays 0 throughout, so the fix is not tuned to one instance's speed. The only constants are the 600ms "DOM has stopped changing" debounce and the 10s cap (below index.html's 15s net). The 600ms held even at 700ms latency because DSpace issues the home-page section requests in parallel, so the gaps between section renders stay small. Theoretical edge: a single section rendering >600ms after everything else already settled could reveal a touch early - bounded by the cap.

"No flicker", measurably

At the instant the snapshot is removed, the real <ds-app> DOM has been quiet for ≥ 600ms (the page stopped changing) — so the revealed page matches what the snapshot showed; no element appears/disappears afterward.

Verify after deploy

The change is built and unit-tested locally, but the flicker only manifests on a real (slower) instance. Please redeploy this to dev-6.pc; I'll then re-run the live frame capture against the deployed build to confirm the snapshot now drops only on the complete page.

Refs: dspace-customers#725, PR #1288, PR #1317, PR #1318

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 622ccff5-164c-4f12-9b28-40f2985f7b24

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}