fix(nav): a navigation closes every overlay before it pushes
The overlay history stack let a navigation land ABOVE open overlays and "buried" their entries with a counter. Measured in Chrome: Shift+W over About navigated under the still-open dialog, the next Back both undid the navigation and closed About, and the Back after that did nothing; Shift+W on Home with the player open did nothing at all. The counter could also be spent by a different overlay closing first, and callers that could not report whether they pushed were assumed to have. setPage and openChannel now close every open overlay and push only once the history is back in sync (one entry per live overlay, no programmatic back() in flight, no reconcile queued), so nothing is ever buried and the whole mechanism goes: navigateOverOverlays, closeThenNavigate, buryUnder, setPage's boolean, and the three test files that pinned them. The palette closes only itself before running a row, so a theme picked over the player keeps the player. Shift+W on Home with the player open now closes it (owner decision 2026-09-09). The wait is on state, not on "a popstate": the old 250 ms fallback could run with back()s still in flight. An overlay that refuses to close within 1.5 s drops the command instead of being navigated out from under.
This commit is contained in:
@@ -1,32 +1,55 @@
|
||||
// @vitest-environment jsdom
|
||||
//
|
||||
// Component-test lane pilot: the useBackToExit "back-ladder". This is the first jsdom/renderHook
|
||||
// test in the repo (the pure-node lane can't touch window.history / popstate). It exercises the
|
||||
// module-level overlay stack in history.ts through its only observable effect — which onExit fires.
|
||||
// The overlay history stack in history.ts, driven through its observable effects: which close/exit
|
||||
// callback fires, how many programmatic back()s go out, and when a command finally runs.
|
||||
//
|
||||
// A GENUINE user Back is simulated by dispatching `popstate` directly: the real-Back branch in
|
||||
// history.ts does NOT call history.back() (it only decrements its own historyDepth to match the
|
||||
// entry the browser already dropped), so a raw popstate reproduces it deterministically without
|
||||
// depending on jsdom's async back() semantics. The invariant that keeps the module-global
|
||||
// bookkeeping clean between tests here is NOT "only genuine Backs" — two closeThenNavigate cases
|
||||
// deliberately drive a reconcile into history.back() — it is that no REAL back() is ever left in
|
||||
// flight: a layer is closed by a genuine Back, by a STUBBED back() that lands its own popstate, or
|
||||
// by an unmount whose burial mark is consumed. A test that needs an unstubbed one belongs in its own
|
||||
// file (see history.burial.dom.test.ts).
|
||||
// A GENUINE user Back is simulated by dispatching `popstate` directly: the real-Back branch does NOT
|
||||
// call history.back() (it only decrements its own historyDepth to match the entry the browser already
|
||||
// dropped), so a raw popstate reproduces it deterministically. A PROGRAMMATIC back() — a reconcile
|
||||
// reclaiming a closed overlay's entry — is stubbed to land its own popstate, so no real jsdom back()
|
||||
// is ever left in flight. The bookkeeping is module-global: every test must leave the stack, the
|
||||
// depth and the in-flight count at zero for the next one.
|
||||
import { describe, it, expect, vi, afterEach } from "vitest";
|
||||
import { renderHook, act } from "@testing-library/react";
|
||||
import { closeThenNavigate, navigateOverOverlays, useBackToClose, useBackToExit } from "./history";
|
||||
import {
|
||||
closeOverlaysThenNavigate,
|
||||
closeTopOverlayThenRun,
|
||||
useBackToClose,
|
||||
useBackToExit,
|
||||
} from "./history";
|
||||
|
||||
// Let the mount effect's coalesced reconcile microtask settle.
|
||||
const settle = () =>
|
||||
act(async () => {
|
||||
await Promise.resolve();
|
||||
});
|
||||
// Past `afterClosing`'s hop onto a fresh task (a setTimeout 0).
|
||||
const tick = () =>
|
||||
act(async () => {
|
||||
await new Promise((r) => setTimeout(r, 0));
|
||||
});
|
||||
// A genuine user Back (browser already dropped the entry; popstate arrives with no pending back()).
|
||||
const userBack = () =>
|
||||
act(() => {
|
||||
window.dispatchEvent(new PopStateEvent("popstate", { state: window.history.state }));
|
||||
});
|
||||
// A programmatic back() that lands its popstate at once — the browser does it 1–13 ms later.
|
||||
const stubBack = () =>
|
||||
vi.spyOn(window.history, "back").mockImplementation(() => {
|
||||
window.dispatchEvent(new PopStateEvent("popstate", { state: window.history.state }));
|
||||
});
|
||||
/** A Back-closable layer whose close really unmounts it, as a closing dialog does. */
|
||||
function mountLayer(onClose: () => void) {
|
||||
const holder: { unmount?: () => void } = {};
|
||||
const r = renderHook(() =>
|
||||
useBackToClose(() => {
|
||||
onClose();
|
||||
holder.unmount?.();
|
||||
}),
|
||||
);
|
||||
holder.unmount = r.unmount;
|
||||
return r;
|
||||
}
|
||||
|
||||
afterEach(() => {
|
||||
vi.clearAllMocks();
|
||||
@@ -92,137 +115,179 @@ describe("useBackToExit back-ladder", () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe("closeThenNavigate", () => {
|
||||
// The bug it exists for: an overlay's unmount reclaims its Back-to-close entry with a programmatic
|
||||
// history.back(). A pushState made before that lands is undone by it, so a dialog command that
|
||||
// navigates does nothing but close. PlayerModal hit it once; the command palette hit it again.
|
||||
it("closes first and navigates only after the reclaim lands", () => {
|
||||
const order: string[] = [];
|
||||
closeThenNavigate(
|
||||
() => order.push("close"),
|
||||
// Braced: `navigate` reports whether it PUSHED (see `buryUnder`), so a bare `push` returning
|
||||
// an array length is a type error rather than an accidental "yes".
|
||||
() => {
|
||||
order.push("navigate");
|
||||
},
|
||||
);
|
||||
expect(order).toEqual(["close"]);
|
||||
|
||||
window.dispatchEvent(new PopStateEvent("popstate"));
|
||||
expect(order).toEqual(["close", "navigate"]);
|
||||
});
|
||||
|
||||
it("navigates exactly once, however many pops follow", () => {
|
||||
describe("closeOverlaysThenNavigate", () => {
|
||||
// Every in-app navigation goes through it (setPage, openChannel). The trap: closing an overlay
|
||||
// reclaims its Back-to-close entry with a programmatic back(), and a pushState made before that
|
||||
// lands is undone by it — so the command would do nothing but close.
|
||||
it("navigates synchronously when no overlay is open", () => {
|
||||
const navigate = vi.fn();
|
||||
closeThenNavigate(() => {}, navigate);
|
||||
window.dispatchEvent(new PopStateEvent("popstate"));
|
||||
window.dispatchEvent(new PopStateEvent("popstate"));
|
||||
closeOverlaysThenNavigate(navigate);
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
// E10 review round 1. Waiting for ONE reclaim is not enough when a SECOND Back-closable layer is
|
||||
// still mounted and the navigation is what unmounts it: that layer's own reconcile fired another
|
||||
// history.back(), which popped the entry the navigation had just pushed and bounced the user back
|
||||
// where they started (palette opened over the player → "go to Channels" landed on the feed).
|
||||
//
|
||||
// NOTE this one may NOT use the raw-popstate shortcut the rest of the file uses: a synthetic
|
||||
// popstate is read as a GENUINE Back, which pops the lower layer off the stack and decrements
|
||||
// historyDepth by itself — so the test would pass with or without the fix. The bug only appears
|
||||
// on the programmatic path, so back() is stubbed to land its own popstate instead.
|
||||
it("adopts the entries of layers the navigation itself unmounts", async () => {
|
||||
const back = vi.spyOn(window.history, "back").mockImplementation(() => {
|
||||
window.dispatchEvent(new PopStateEvent("popstate", { state: window.history.state }));
|
||||
});
|
||||
it("closes every open overlay, topmost first, and navigates only once all their entries are back", async () => {
|
||||
const back = stubBack();
|
||||
try {
|
||||
const player = renderHook(() => useBackToClose(() => {}));
|
||||
const closed: string[] = [];
|
||||
mountLayer(() => closed.push("player"));
|
||||
await settle();
|
||||
const palette = renderHook(() => useBackToClose(() => {}));
|
||||
mountLayer(() => closed.push("palette"));
|
||||
await settle();
|
||||
expect(back).not.toHaveBeenCalled(); // both layers hold an entry; nothing reclaimed yet
|
||||
|
||||
const navigate = vi.fn(() => window.history.pushState({ sfPage: "channels" }, ""));
|
||||
await act(async () => {
|
||||
closeThenNavigate(() => palette.unmount(), navigate);
|
||||
await Promise.resolve(); // let the palette's own reclaim reconcile run
|
||||
});
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
expect(back).toHaveBeenCalledTimes(1); // the palette's entry, and only that
|
||||
act(() => closeOverlaysThenNavigate(navigate));
|
||||
expect(closed).toEqual(["palette", "player"]);
|
||||
expect(navigate).not.toHaveBeenCalled();
|
||||
|
||||
player.unmount(); // …which is what the navigation does to the layer below
|
||||
await settle();
|
||||
expect(back).toHaveBeenCalledTimes(1); // must NOT back over the entry navigate just pushed
|
||||
await settle(); // the reconcile reclaims both entries in one go
|
||||
expect(back).toHaveBeenCalledTimes(2);
|
||||
// Not inside the popstate dispatch that settled it — a later listener would still apply the
|
||||
// OLD entry's page over the push.
|
||||
expect(navigate).not.toHaveBeenCalled();
|
||||
|
||||
await tick();
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
await tick();
|
||||
expect(back).toHaveBeenCalledTimes(2); // nothing reclaims over the entry navigate pushed
|
||||
expect(window.history.state).toMatchObject({ sfPage: "channels" });
|
||||
} finally {
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
// The mirror of the case above, and the OTHER door into `buryUnder` — round 3 found that only
|
||||
// `navigateOverOverlays` was pinned, so this call site could be reverted to the old unconditional
|
||||
// burial with the whole suite green. Reachable through the palette: `run: () => setPage(page)` is
|
||||
// a bare arrow, so `setPage`'s `false` really does arrive here when the chosen module is the one
|
||||
// already on screen. Nothing was pushed, so the layer underneath is still ours to reclaim.
|
||||
it("leaves the layer below reclaimable when the command navigated nowhere", async () => {
|
||||
// The old helper ran after "a popstate" OR a 250 ms fallback, whichever came first — so a reclaim
|
||||
// slower than the fallback undid the navigation. It must wait for the history, not the clock.
|
||||
it("waits for a back() still in flight instead of pushing under it", async () => {
|
||||
let land: (() => void) | undefined;
|
||||
const back = vi.spyOn(window.history, "back").mockImplementation(() => {
|
||||
window.dispatchEvent(new PopStateEvent("popstate", { state: window.history.state }));
|
||||
land = () =>
|
||||
window.dispatchEvent(new PopStateEvent("popstate", { state: window.history.state }));
|
||||
});
|
||||
try {
|
||||
const player = renderHook(() => useBackToClose(() => {}));
|
||||
mountLayer(() => {});
|
||||
await settle();
|
||||
const palette = renderHook(() => useBackToClose(() => {}));
|
||||
const navigate = vi.fn();
|
||||
act(() => closeOverlaysThenNavigate(navigate));
|
||||
await settle();
|
||||
expect(back).toHaveBeenCalledTimes(1);
|
||||
|
||||
const navigate = vi.fn(() => false); // setPage's early return: already on that page
|
||||
await act(async () => {
|
||||
closeThenNavigate(() => palette.unmount(), navigate);
|
||||
await Promise.resolve();
|
||||
await new Promise((r) => setTimeout(r, 300)); // past where the old fallback fired
|
||||
});
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
expect(back).toHaveBeenCalledTimes(1); // the palette's own entry
|
||||
expect(navigate).not.toHaveBeenCalled();
|
||||
|
||||
player.unmount();
|
||||
await settle();
|
||||
expect(back).toHaveBeenCalledTimes(2); // and the player's, because nothing was pushed over it
|
||||
act(() => land?.());
|
||||
await tick();
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
} finally {
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
// Without this the command is not late, it never happens: an overlay closed in the same tick it
|
||||
// opened never pushed an entry, so no reclaim popstate is ever coming.
|
||||
it("navigates anyway when no reclaim popstate ever arrives", () => {
|
||||
// No such overlay exists today, but a future "discard your changes?" guard must not have the page
|
||||
// switched out from under it: dropping the command is the honest outcome.
|
||||
it("drops the command when an overlay does not actually close", async () => {
|
||||
const back = stubBack();
|
||||
const stubborn = renderHook(() => useBackToClose(() => {}));
|
||||
await settle();
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
const navigate = vi.fn();
|
||||
closeThenNavigate(() => {}, navigate);
|
||||
act(() => closeOverlaysThenNavigate(navigate));
|
||||
act(() => {
|
||||
vi.advanceTimersByTime(2000);
|
||||
});
|
||||
expect(navigate).not.toHaveBeenCalled();
|
||||
vi.advanceTimersByTime(300);
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
stubborn.unmount();
|
||||
await settle();
|
||||
expect(back).toHaveBeenCalledTimes(1); // its entry is still reclaimed on the way out
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("navigateOverOverlays", () => {
|
||||
// The global-shortcut half of the same trap `closeThenNavigate` solves. Shift+W does not know an
|
||||
// overlay is open and cannot close it — it just navigates, and the page change unmounts the player
|
||||
// (which lives inside the module column). That unmount's reconcile then reclaimed the entry the
|
||||
// navigation had only just pushed, so the player closed and the page snapped straight back.
|
||||
it("a navigation made from outside an open overlay survives that overlay's unmount", async () => {
|
||||
const overlay = renderHook(() => useBackToClose(() => {}));
|
||||
await settle();
|
||||
const back = vi.spyOn(window.history, "back");
|
||||
// Shift+W pressed on Home with the player open: setPage finds nothing to push. The player must
|
||||
// still close (owner decision 2026-09-09), and its entry must be reclaimed rather than orphaned —
|
||||
// an orphan is a later browser Back that changes nothing on screen.
|
||||
it("closes the overlay and reclaims its entry when the navigation turns out to go nowhere", async () => {
|
||||
const back = stubBack();
|
||||
try {
|
||||
const navigate = vi.fn(() => window.history.pushState({ sfPage: "home" }, ""));
|
||||
act(() => navigateOverOverlays(navigate));
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
|
||||
overlay.unmount(); // what the page change does to the player
|
||||
const closed = vi.fn();
|
||||
mountLayer(closed);
|
||||
await settle();
|
||||
// The mark is consumed instead: no back(), so the entry `navigate` pushed is still current.
|
||||
const navigate = vi.fn(); // setPage's early return: already on that page
|
||||
act(() => closeOverlaysThenNavigate(navigate));
|
||||
await settle();
|
||||
await tick();
|
||||
expect(closed).toHaveBeenCalledTimes(1);
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
expect(back).toHaveBeenCalledTimes(1);
|
||||
} finally {
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
// An overlay closed in the tick it opened never pushed an entry, so no popstate is coming at all.
|
||||
it("navigates when the overlay closes before its entry was ever pushed", async () => {
|
||||
const back = stubBack();
|
||||
try {
|
||||
mountLayer(() => {}); // no settle: its reconcile is still queued
|
||||
const navigate = vi.fn();
|
||||
act(() => closeOverlaysThenNavigate(navigate));
|
||||
await settle();
|
||||
await tick();
|
||||
expect(navigate).toHaveBeenCalledTimes(1);
|
||||
expect(back).not.toHaveBeenCalled();
|
||||
} finally {
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("closeTopOverlayThenRun", () => {
|
||||
// The palette's rows. Only the palette closes: a theme picked over the player must leave it open.
|
||||
it("closes only the top overlay and runs once its entry is back, leaving the one below", async () => {
|
||||
const back = stubBack();
|
||||
try {
|
||||
const playerClosed = vi.fn();
|
||||
mountLayer(playerClosed);
|
||||
await settle();
|
||||
const palette = renderHook(() => useBackToClose(() => {}));
|
||||
await settle();
|
||||
|
||||
const run = vi.fn();
|
||||
act(() => closeTopOverlayThenRun(() => palette.unmount(), run));
|
||||
expect(run).not.toHaveBeenCalled();
|
||||
await settle();
|
||||
await tick();
|
||||
expect(run).toHaveBeenCalledTimes(1);
|
||||
expect(back).toHaveBeenCalledTimes(1); // the palette's entry, and only that
|
||||
expect(playerClosed).not.toHaveBeenCalled();
|
||||
|
||||
await userBack(); // teardown: the player closes by a genuine Back
|
||||
expect(playerClosed).toHaveBeenCalledTimes(1);
|
||||
await settle();
|
||||
} finally {
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
it("runs exactly once, however many popstates follow", async () => {
|
||||
const back = stubBack();
|
||||
try {
|
||||
const palette = renderHook(() => useBackToClose(() => {}));
|
||||
await settle();
|
||||
const run = vi.fn();
|
||||
act(() => closeTopOverlayThenRun(() => palette.unmount(), run));
|
||||
await settle();
|
||||
await tick();
|
||||
await userBack();
|
||||
await userBack();
|
||||
await tick();
|
||||
expect(run).toHaveBeenCalledTimes(1);
|
||||
} finally {
|
||||
back.mockRestore();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user