Your Application Customizer's floating UI disappears when navigating the site

Symptom

Your extension renders a persistent floating element — a chat bubble, help launcher, feedback tab — by creating a node and appending it to document.body. On first load it shows up correctly.

Then the user clicks around the site (a link, a list item, the left nav) and the button vanishes. It does not come back on a normal refresh (F5); only a hard refresh (Ctrl+Shift+R) brings it back. No console errors.

Cause

Two things combine, and the second one sends you chasing the wrong fix.

1. Navigation is client-side, so onInit runs once. Modern SharePoint is a single-page app. Navigating between pages swaps page content in place; it does not reload the document. An Application Customizer's onInit fires on the first full load and then never again for the life of that document. During the in-place swap, SharePoint rebuilds large parts of the DOM and your body-appended node goes with it. Nothing re-adds it.

2. visibilitychange looks like the fix but is not. It is tempting to "re-validate on visibilitychange" — but that event fires only when the tab or window is hidden/shown (switching tabs, minimizing). It does not fire during in-page SPA navigation, because the tab stays visible the whole time. So a handler wired to visibilitychange never runs while the user is clicking around, which is exactly when the element disappears.

The F5-vs-hard-refresh detail is a red herring that points you at caching. After you deploy a new version, SharePoint may keep serving the previously cached component manifest/bundle until a hard refresh clears it — so a plain F5 can load stale code while Ctrl+Shift+R loads the new build. That difference is about deploy caching, not about a per-request config cache, and "add cache-busting to my config read" will not fix the disappearance.

Fix

Re-render on the navigation event, and keep a MutationObserver as a backstop:

public async onInit(): Promise<void> {
  await super.onInit();
  await this._tryRender();

  // Canonical fix: SharePoint fires navigatedEvent on every client-side navigation.
  // onInit will NOT run again on SPA nav; this will.
  this.context.application.navigatedEvent.add(this, this._onNavigated);

  // Safety net for non-navigation removals (some SP versions also prune unknown
  // body nodes on the same page). Watch only direct body children → cheap.
  if (typeof MutationObserver !== 'undefined') {
    this._observer = new MutationObserver(() => {
      if (this._rendering) return;
      if (this._skipUntilNavigation) return;                  // a definitive "no" (404/403, feature off) — see below
      if (this._shouldSkip()) return;                         // cheap sync hide-checks
      if (document.getElementById(CONTAINER_ID)) return;      // still there → nothing to do
      void this._tryRender();
    });
    this._observer.observe(document.body, { childList: true });
  }
}

private _onNavigated = (): void => {
  this._skipUntilNavigation = false;                          // a definitive "no" holds only until the next page
  if (this._observer) this._observer.observe(document.body, { childList: true });  // re-arm after a disconnect
  if (this._shouldSkip()) return;
  void this._tryRender();
};

protected onDispose(): void {
  this.context.application.navigatedEvent.remove(this, this._onNavigated);
  if (this._observer) { this._observer.disconnect(); this._observer = undefined; }
  // …unmount + remove container…
  super.onDispose();
}

Notes:

• _tryRender must be idempotent. Guard on getElementById(CONTAINER_ID) and hold a synchronous _rendering lock across the whole async path (config reads, etc.) so navigatedEvent and the observer can both call it without double-mounting. See Application Customizer runs again inside dialog iframes for the same-document race.
• Keep the observer cheap. Watch document.body with { childList: true } only (not subtree) — it fires when layers/dialogs are added or removed, which is rare enough. Bail out immediately when the container is still present; only run the expensive path (config read + render) when it is actually gone.
• Guard against thrash. If the extension has a page-state reason to not render (e.g. a full-page web part version of the same feature is present), re-check that cheaply (_shouldSkip) inside the observer, or you will re-add what your own hide logic just removed, and fight yourself on every mutation.
• This is not caught by the compiler, linter, or build. It only shows up when you click through a live site. Verify by navigating, not by unit tests.

Refinement: the observer misses deep-DOM removals

MutationObserver(document.body, { childList: true }) only fires on direct body children. If your re-render depends on some other element disappearing deep in the page — e.g. you hide the floating button while a full-app web part is present and wait for that web part's marker to be removed on navigation — the observer never wakes, because the marker lives deep in the canvas, not as a body child. The button then stays gone until an unrelated body-child mutation happens to fire.

Fix: after navigation, run a short bounded poll (e.g. every 500 ms for ~5 s) that re-checks the condition and renders once the deep node is gone. A poll beats subtree: true here, which would fire the callback — and any querySelector inside it — on every DOM mutation anywhere (expensive on busy pages). Async component loading (a bundle fetched from a CDN) slows teardown and widens this race, so the symptom can appear only after such a change.

The observer must stop asking — and must not wake itself up

Two more traps live in the same MutationObserver:

1. Remember a definitive "no". SharePoint adds and removes direct body children all the time — callouts, tooltips, layers — so the callback fires constantly. If a missing container sends it to _tryRender, and _tryRender reads configuration, then on every site where the extension is deployed but the app is not set up (settings list 404 or 403, feature switched off) each user re-reads that configuration every throttle window, for the whole session, on every site of the tenant. Treat 404/403 and "feature off" as final until the next navigation: set _skipUntilNavigation, disconnect() the observer, and re-arm it from navigatedEvent as in the code above. A network failure, a 429 or a 5xx is not final — keep observing. The full three-outcome version (shown / hidden-final / hidden-retry) is in Application Customizer runs again inside dialog iframes.
2. A synchronous "I'm writing" flag does not protect you from your own mutations. Mutation records are delivered after the synchronous code that caused them has finished, so by the time the callback runs, a try { writing = true; … } finally { writing = false; } flag is already back to false. The callback takes your own writes for somebody else's, schedules another render, which writes again — an endless loop at animation-frame speed that can take a tab to gigabytes of memory. When the callback's work writes into the node it observes, call observer.takeRecords() just before clearing the flag, or disconnect() before the write and observe() again after it.

In the code above, the early getElementById(CONTAINER_ID) return keeps the observer from reacting to its own re-append; the second trap appears as soon as the callback does more than check and re-add one node.

How to verify

1. Open a page of the site where the extension is deployed. The floating element shows.
2. Click to another page within the site (left nav, a list, a document library) without a full reload. The element should stay (or reappear within a frame).
3. In DevTools, add a breakpoint or log in the navigatedEvent handler and confirm it fires on each in-page navigation — and that visibilitychange does not fire for the same clicks.