feat(#300 ui): move launcher to top-right, per-agent dark glyph color

- Launcher (human) avatar moves from the bottom-right to the TOP-RIGHT
  corner of the agent glyph.
- The emoji/sparkles glyph circle is no longer a fixed violet: its
  background is derived from a hash of the agent name (hue) and pinned to a
  fixed dark shade (hsl(h, 45%, 24%)) so distinct agents get distinct colors
  while the emoji / white sparkles icon stays readable. Agents with an
  uploaded avatar image are unaffected.

Add a unit test for agentGlyphBackground (deterministic, name-varying, dark).
client tsc clean, 11 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/client/src/components/ui/agent-avatar-stack.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 import { Provider, createStore } from "jotai";
-import { AgentAvatarStack } from "./agent-avatar-stack";
+import { AgentAvatarStack, agentGlyphBackground } from "./agent-avatar-stack";
 import {
   activeAiChatIdAtom,
   aiChatWindowOpenAtom,
@@ -26,6 +26,23 @@ function renderStack(props: Props) {
   return { store, ...utils };
 }
 
+describe("agentGlyphBackground", () => {
+  it("is deterministic for a given agent name", () => {
+    expect(agentGlyphBackground("Researcher")).toBe(
+      agentGlyphBackground("Researcher"),
+    );
+  });
+
+  it("differs by name and stays a fixed dark shade (readable emoji)", () => {
+    expect(agentGlyphBackground("Researcher")).not.toBe(
+      agentGlyphBackground("Нарратор"),
+    );
+    // Only the hue varies; saturation/lightness are pinned low so the glyph is
+    // always a dark circle.
+    expect(agentGlyphBackground("Нарратор")).toMatch(/^hsl\(\d+, 45%, 24%\)$/);
+  });
+});
+
 describe("AgentAvatarStack", () => {
   it("internal chat WITH role: emoji glyph in front + human launcher behind", () => {
     const { container } = renderStack({

apps/client/src/components/ui/agent-avatar-stack.tsx

@@ -23,14 +23,34 @@ export interface LauncherInfo {
   avatarUrl?: string | null;
 }
 
-// Same violet token as the former AiAgentBadge (which used color="violet").
-const AGENT_COLOR = "violet";
 const GLYPH_SIZE = 38;
 const LAUNCHER_SIZE = 22;
-// How far the launcher avatar sticks out past the agent's bottom-right corner, so
+// How far the launcher avatar sticks out past the agent's top-right corner, so
 // the "human behind" reads as behind (lower z-index) yet stays clearly visible.
 const LAUNCHER_OVERHANG = 8;
 
+// Small deterministic string hash (same algorithm as custom-avatar's initials
+// hash) used to pick a stable per-agent glyph color.
+function hashName(input: string): number {
+  let hash = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    hash = (hash << 5) - hash + input.charCodeAt(i);
+    hash |= 0;
+  }
+  return Math.abs(hash);
+}
+
+/**
+ * Deterministic DARK background for an emoji/sparkles agent glyph. The hue is
+ * derived from the agent-name hash so distinct agents get distinct circles;
+ * saturation and lightness are pinned low ("shifted into darkness") so a bright
+ * emoji or the white sparkles icon stays legible on top (#300).
+ */
+export function agentGlyphBackground(name: string): string {
+  const hue = hashName(name) % 360;
+  return `hsl(${hue}, 45%, 24%)`;
+}
+
 /**
  * The front avatar. Image-source priority (#300):
  *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
@@ -48,9 +68,18 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
     );
   }
 
+  // Emoji/sparkles glyphs sit on a per-agent dark circle (hashed from the agent
+  // name) so different agents are visually distinct, while the dark background
+  // keeps the emoji / white sparkles icon readable.
+  const bg = agentGlyphBackground(agent.name);
+  const glyphStyles = {
+    root: { background: bg },
+    placeholder: { background: bg, color: "var(--mantine-color-white)" },
+  };
+
   if (agent.emoji) {
     return (
-      <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
+      <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
         <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
           {agent.emoji}
         </span>
@@ -59,7 +88,7 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
   }
 
   return (
-    <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
+    <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
       <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
     </Avatar>
   );
@@ -156,7 +185,7 @@ export function AgentAvatarStack({
         : {})}
     >
       {launcher && (
-        <Box pos="absolute" bottom={0} right={0} style={{ zIndex: 0 }}>
+        <Box pos="absolute" top={0} right={0} style={{ zIndex: 0 }}>
           <CustomAvatar
             size={LAUNCHER_SIZE}
             avatarUrl={launcher.avatarUrl}
@@ -165,8 +194,8 @@ export function AgentAvatarStack({
           />
         </Box>
       )}
-      {/* Pin the agent glyph to the top-left at its own size; the launcher then
-          overhangs it by LAUNCHER_OVERHANG at the bottom-right and stays visible. */}
+      {/* The agent glyph keeps its own size (flex-centered in the container); the
+          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
       <Box
         style={{
           position: "relative",

apps/client/src/features/editor/hooks/use-scroll-position.test.ts

@@ -93,10 +93,9 @@ describe("useScrollPosition", () => {
     // Restore still scrolls to 500 (the captured target), NOT the clobbered 0.
     // If the capture were moved into an effect (after handlers register), it
     // would read the clobbered 0 and this assertion would fail.
-    setScrollHeight(2000); // maxScroll = 1200 >= 500, held steady -> settles
+    setScrollHeight(2000); // maxScroll = 1200 >= 500
     act(() => {
       result.current.restoreScrollPosition();
-      vi.advanceTimersByTime(500);
     });
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
   });
@@ -104,12 +103,11 @@ describe("useScrollPosition", () => {
   it("(a3) is idempotent: re-asserting the same target does not scroll again", () => {
     vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}once`, "500");
-    setScrollHeight(2000); // tall enough + steady -> settles
+    setScrollHeight(2000); // tall enough to restore synchronously
 
     const { result } = renderHook(() => useScrollPosition("once"));
     act(() => {
       result.current.restoreScrollPosition();
-      vi.advanceTimersByTime(500);
     });
     expect(window.scrollTo).toHaveBeenCalledTimes(1);
 
@@ -121,7 +119,6 @@ describe("useScrollPosition", () => {
     // the window is already at the target and does nothing.
     act(() => {
       result.current.restoreScrollPosition();
-      vi.advanceTimersByTime(500);
     });
     expect(window.scrollTo).toHaveBeenCalledTimes(1);
   });
@@ -129,10 +126,10 @@ describe("useScrollPosition", () => {
   it("(b) does not restore when the URL has a #hash anchor", () => {
     vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}p2`, "500");
-    // Content is ALREADY tall enough (maxScroll = 2000 - 800 = 1200 >= 500) and
-    // steady, so without the hash guard the wait would settle and scroll to the
-    // target. The assertion below therefore genuinely proves the hash guard
-    // short-circuits before any scroll (not just that the wait has not fired).
+    // Content is ALREADY tall enough (maxScroll = 2000 - 800 = 1200 >= 500), so
+    // without the hash guard tryRestore would call scrollTo synchronously on the
+    // first tick. The assertion below therefore genuinely proves the hash guard
+    // short-circuits before any scroll (not just that the poll has not fired).
     setScrollHeight(2000);
     window.location.hash = "#some-heading";
 
@@ -171,7 +168,7 @@ describe("useScrollPosition", () => {
 
   it("(g) does not restore if the reader scrolled (wheel) before restore fires", () => {
     window.sessionStorage.setItem(`${KEY_PREFIX}g1`, "500");
-    setScrollHeight(2000); // tall enough (would settle and restore, absent the wheel)
+    setScrollHeight(2000); // tall enough to restore synchronously
 
     const { result } = renderHook(() => useScrollPosition("g1"));
 
@@ -213,9 +210,8 @@ describe("useScrollPosition", () => {
   });
 
   it("(i) a non-scroll keydown does NOT abort restore", () => {
-    vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}i1`, "500");
-    setScrollHeight(2000); // tall enough + steady -> settles
+    setScrollHeight(2000); // tall enough to restore synchronously
 
     const { result } = renderHook(() => useScrollPosition("i1"));
 
@@ -225,7 +221,6 @@ describe("useScrollPosition", () => {
     });
     act(() => {
       result.current.restoreScrollPosition();
-      vi.advanceTimersByTime(500);
     });
 
     // Restore still happens: the innocuous keypress did not disable it.
@@ -234,7 +229,7 @@ describe("useScrollPosition", () => {
 
   it("(j) a scroll keydown (Space) DOES abort restore", () => {
     window.sessionStorage.setItem(`${KEY_PREFIX}j1`, "500");
-    setScrollHeight(2000); // tall enough (would settle and restore, absent the scroll key)
+    setScrollHeight(2000); // tall enough to restore synchronously
 
     const { result } = renderHook(() => useScrollPosition("j1"));
 
@@ -266,7 +261,7 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).not.toHaveBeenCalled();
   });
 
-  it("(d) scrolls to the saved Y once the height settles tall enough", () => {
+  it("(d) scrolls to the saved Y once the content is tall enough", () => {
     vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}p4`, "500");
     setInnerHeight(800);
@@ -275,50 +270,17 @@ describe("useScrollPosition", () => {
     const { result } = renderHook(() => useScrollPosition("p4"));
     act(() => {
       result.current.restoreScrollPosition();
-      vi.advanceTimersByTime(300);
     });
 
-    // Still waiting: content not laid out tall enough yet.
+    // Still polling: content not laid out yet.
     expect(window.scrollTo).not.toHaveBeenCalled();
 
-    // Content becomes tall enough and then holds steady past the stable window:
-    // maxScroll = 2000 - 800 = 1200 >= 500.
+    // Content becomes tall enough: maxScroll = 2000 - 800 = 1200 >= 500.
     setScrollHeight(2000);
     act(() => {
-      vi.advanceTimersByTime(500);
-    });
-
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
-  });
-
-  it("(d3) waits for the height to STOP changing before restoring", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}p4b`, "500");
-    setInnerHeight(800);
-    setScrollHeight(2000); // reachable from the start (maxScroll 1200 >= 500)...
-
-    const { result } = renderHook(() => useScrollPosition("p4b"));
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    // ...but the height keeps changing every tick, so it never settles.
-    act(() => {
-      vi.advanceTimersByTime(100);
-      setScrollHeight(2500);
-      vi.advanceTimersByTime(100);
-      setScrollHeight(3000);
-      vi.advanceTimersByTime(100);
-      setScrollHeight(3500);
       vi.advanceTimersByTime(100);
     });
-    expect(window.scrollTo).not.toHaveBeenCalled(); // reachable, but not settled
 
-    // Height now holds steady past HEIGHT_STABLE_MS -> restore fires (to the
-    // fixed target, unaffected by the taller document).
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
   });
 
@@ -341,39 +303,53 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 200, behavior: "auto" });
   });
 
-  it("(k) a re-trigger while the wait is running does not start a second concurrent poll", () => {
-    // Both triggers (early on-mount + post-swap) call restore. The
-    // `if (pollTimerRef.current !== null) return` guard makes a re-trigger during
-    // an in-flight wait a no-op, so exactly ONE poll runs and scrolls exactly once.
-    // A mutant dropping that guard would start a second parallel poll; since the
-    // stubbed scrollTo never moves window.scrollY, the second poll would scroll
-    // again (redundancy guard sees scrollY still 0 != target) -> two calls, and
-    // this assertion would fail.
+  it("(k) shares ONE timeout budget across re-triggers (does not restart the clock)", () => {
+    // The static->live editor swap re-invokes restore. The shared budget
+    // (restoreStartRef) must measure the MAX_RESTORE_WAIT_MS (5000) deadline
+    // from the FIRST trigger, not restart it on every re-trigger. This pins
+    // the `if (restoreStartRef.current === null)` guard: a mutant that resets
+    // `restoreStartRef.current = Date.now()` on every trigger would push the
+    // deadline out to t=8000 (3000 + 5000) and fail the t=5000 assertion below.
     vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}k1`, "500");
+    vi.setSystemTime(0);
+    window.sessionStorage.setItem(`${KEY_PREFIX}k1`, "5000");
     setInnerHeight(800);
-    setScrollHeight(100); // too short -> the first wait keeps polling (no scroll yet)
+    setScrollHeight(1000); // maxScroll = 200, never reaches 5000 -> it polls.
 
     const { result } = renderHook(() => useScrollPosition("k1"));
 
-    // First trigger: starts the wait.
+    // First trigger at t=0: starts the shared budget and begins polling.
     act(() => {
       result.current.restoreScrollPosition();
     });
-    // Second trigger while the first wait is still running: the guard suppresses it.
+    expect(window.scrollTo).not.toHaveBeenCalled();
+
+    // Advance to t=3000 (still polling: content short, not yet timed out).
+    act(() => {
+      vi.advanceTimersByTime(3000);
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled();
+
+    // Second trigger at t=3000 (the swap re-assert). Under the real code the
+    // budget is shared, so `start` stays 0; under the reset-mutant it becomes 3000.
     act(() => {
       result.current.restoreScrollPosition();
     });
 
-    // Content becomes reachable and holds steady past the stable window.
-    setScrollHeight(2000);
+    // At t=4900 the FIRST budget has not yet elapsed (4900 - 0 < 5000): no clamp.
     act(() => {
-      vi.advanceTimersByTime(500);
+      vi.advanceTimersByTime(1900);
     });
+    expect(window.scrollTo).not.toHaveBeenCalled();
 
-    // Exactly one scroll — the guard prevented a second concurrent poll.
-    expect(window.scrollTo).toHaveBeenCalledTimes(1);
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
+    // At t=5000 the shared budget (measured from t=0) times out and clamps to the
+    // furthest reachable position (maxScroll = 200). The reset-mutant, measuring
+    // from t=3000, would still be waiting (5000 - 3000 = 2000 < 5000) and would
+    // NOT have scrolled here -> this assertion fails against that mutant.
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 200, behavior: "auto" });
   });
 
   it("(e) never throws when storage access throws", () => {

apps/client/src/features/editor/hooks/use-scroll-position.ts

@@ -8,11 +8,6 @@ const SAVE_THROTTLE_MS = 250;
 const MAX_RESTORE_WAIT_MS = 5000;
 // How often to re-check the document height while waiting for content to load.
 const RESTORE_POLL_MS = 100;
-// The document height must stay unchanged this long before we treat the layout
-// as settled and safe to restore against — restoring while content is still
-// rendering in lets scroll-anchoring drift the saved offset (and re-fire, which
-// is the residual reload "jitter" this replaces).
-const HEIGHT_STABLE_MS = 400;
 
 // sessionStorage key prefix. sessionStorage survives an F5 in the same tab and
 // is cleared on tab close, which is exactly the lifetime we want for an MVP
@@ -78,13 +73,10 @@ export function hasSavedReadingPosition(pageId: string): boolean {
  * their place across a reload (F5) or reopening the document.
  *
  * Returns `restoreScrollPosition`, which the page editor calls from two triggers
- * (early on mount + after the static->live editor swap). It WAITS for the
- * document height to stop changing (the layout to settle) and then scrolls once
- * to the saved offset — so it never fires mid-render, where scroll-anchoring
- * would drift the position. It is idempotent: a running wait suppresses a second
- * trigger, and once positioned re-asserting is a no-op. The two scroll mechanisms
- * are mutually exclusive: if the URL has a `#hash` anchor, the existing
- * anchor-scroll logic wins and restore is a no-op.
+ * (early, while the static/cached content is laid out, and again after the
+ * static->live editor swap); it is idempotent, so re-asserting the same target is
+ * a no-op. The two scroll mechanisms are mutually exclusive: if the URL has a
+ * `#hash` anchor, the existing anchor-scroll logic wins and restore is a no-op.
  */
 export function useScrollPosition(pageId: string): {
   restoreScrollPosition: () => void;
@@ -112,6 +104,9 @@ export function useScrollPosition(pageId: string): {
   // this, a fast SPA navigation away mid-poll would let the old page's poll fire
   // window.scrollTo against the NEW page's document (visible wrong-page scroll).
   const pollTimerRef = useRef<number | null>(null);
+  // Timestamp of the FIRST restore attempt so re-triggers (e.g. the static→live
+  // editor swap) share ONE bounded timeout budget instead of restarting it.
+  const restoreStartRef = useRef<number | null>(null);
 
   // Capture the previously-saved value synchronously during render, before the
   // effect below registers handlers that would persist the current (0) scrollY.
@@ -214,43 +209,36 @@ export function useScrollPosition(pageId: string): {
     // Nothing meaningful to restore to.
     if (targetY <= 0) return;
 
-    // Idempotent: if a restore poll is already running, do not start a second.
-    // Both triggers (early + post-swap) share it; a running poll suppresses the
-    // second, and once positioned the redundancy guard makes it a no-op.
-    if (pollTimerRef.current !== null) return;
+    // Cancel any in-flight poll before (re)starting, so overlapping triggers can
+    // never run two concurrent polls against the same target.
+    if (pollTimerRef.current !== null) {
+      window.clearTimeout(pollTimerRef.current);
+      pollTimerRef.current = null;
+    }
 
-    const start = Date.now();
-    let lastHeight = -1;
-    let stableSince = start;
+    // Share one timeout budget across re-triggers instead of restarting it.
+    if (restoreStartRef.current === null) {
+      restoreStartRef.current = Date.now();
+    }
+    const start = restoreStartRef.current;
 
-    // Restore ONCE the document height has been stable for HEIGHT_STABLE_MS AND
-    // the target is reachable, so the saved pixel offset lands on the same content
-    // the reader left. Restoring earlier — while the doc is still rendering in
-    // (progressive content / static->live swap) — lets scroll-anchoring drift the
-    // position and makes the restore re-fire (the reload jitter). The timeout is
-    // the only fallback that clamps to the furthest reachable position.
-    const tick = () => {
-      // Bail mid-wait if the reader started scrolling.
+    const tryRestore = () => {
+      // Bail mid-poll if the reader started scrolling while we were waiting.
       if (userInteractedRef.current) {
         pollTimerRef.current = null;
         return;
       }
 
-      const now = Date.now();
-      const height = document.documentElement.scrollHeight;
-      if (height !== lastHeight) {
-        lastHeight = height;
-        stableSince = now;
-      }
-      const maxScroll = height - window.innerHeight;
-      const settled = now - stableSince >= HEIGHT_STABLE_MS;
-      const reachable = maxScroll >= targetY;
-      const timedOut = now - start >= MAX_RESTORE_WAIT_MS;
+      const maxScroll =
+        document.documentElement.scrollHeight - window.innerHeight;
+      const timedOut = Date.now() - start >= MAX_RESTORE_WAIT_MS;
 
-      if ((settled && reachable) || timedOut) {
+      // Restore once the content is tall enough to reach the target, or bail out
+      // after the timeout and scroll as far as currently possible.
+      if (maxScroll >= targetY || timedOut) {
         const top = Math.min(targetY, Math.max(maxScroll, 0));
-        // No-op when already there — avoids a redundant scroll and keeps the two
-        // triggers from double-scrolling.
+        // Redundancy guard: re-asserting the SAME target when already positioned
+        // is a no-op, so this hook can be called from multiple triggers safely.
         if (Math.abs(window.scrollY - top) > 1) {
           window.scrollTo({ top, behavior: "auto" });
         }
@@ -259,10 +247,10 @@ export function useScrollPosition(pageId: string): {
       }
 
       // Stored in a ref so the effect cleanup can cancel it on unmount.
-      pollTimerRef.current = window.setTimeout(tick, RESTORE_POLL_MS);
+      pollTimerRef.current = window.setTimeout(tryRestore, RESTORE_POLL_MS);
     };
 
-    tick();
+    tryRestore();
   }, []);
 
   return { restoreScrollPosition };
@@ -273,9 +261,8 @@ export function useScrollPosition(pageId: string): {
  *
  * Extracted from PageEditor so the exact restore triggers (their deps and the
  * post-swap `&& editor` guard) are directly unit-testable rather than mirrored.
- * `restoreScrollPosition` waits for the layout to settle and is idempotent, so
- * both triggers together produce a single restore (a running wait suppresses the
- * second; once positioned re-asserting is a no-op).
+ * Behaviour is unchanged: `restoreScrollPosition` is idempotent, so re-asserting
+ * the same target from either trigger is a no-op.
  *
  * @param pageId      the page whose scroll position is persisted/restored.
  * @param editor      the tiptap editor instance, or `null` until it is ready.
@@ -288,18 +275,16 @@ export function useScrollRestoreOnSwap(
 ): void {
   const { restoreScrollPosition } = useScrollPosition(pageId);
 
-  // Early trigger: start the restore wait on mount, so a reload that never
-  // reaches the live editor (offline / collab never syncs — the static cache
-  // stays shown) still restores once the static layout settles. The wait itself
-  // holds off scrolling until the height is stable, and aborts if the reader
-  // starts scrolling (handled inside the hook).
+  // Restore as early as the static (cached) content is laid out, before paint,
+  // so the reader's position is applied without a visible jump. Aborts itself if
+  // the reader has already started scrolling (handled inside the hook).
   useLayoutEffect(() => {
     restoreScrollPosition();
   }, [restoreScrollPosition]);
 
-  // Post-swap trigger: after the static -> live swap, (re)start the wait so it
-  // measures the final live layout. Idempotent: a no-op while the early wait is
-  // still running, and a no-op once already positioned or the reader interacted.
+  // Re-assert once after the static -> live editor swap in case the swap reset
+  // the window scroll. Idempotent: a no-op when the position is already correct,
+  // and a no-op after the reader has interacted.
   useLayoutEffect(() => {
     if (!showStatic && editor) restoreScrollPosition();
   }, [showStatic, editor, restoreScrollPosition]);

apps/client/src/features/editor/page-editor.test.tsx

@@ -28,11 +28,9 @@ const KEY_PREFIX = "gitmost:scroll-position:";
 // guard the production code directly (verified: removing `&& editor` reddens the
 // first test).
 //
-// Both tests observe the real effect via `window.scrollTo`. Restore is NOT
-// synchronous: it waits for the document height to settle (HEIGHT_STABLE_MS)
-// before scrolling, so the tests use fake timers and advance them with a steady,
-// reachable height to let the wait fire. The stubbed `window.scrollTo` never
-// mutates `window.scrollY`, so every restore that settles yields exactly one
+// Both tests observe the real effect via `window.scrollTo`. The stubbed
+// `window.scrollTo` never mutates `window.scrollY`, and the target is left
+// unreached, so every restore invocation that passes the guard yields exactly one
 // `scrollTo` call — making the call count a faithful proxy for restore invocations.
 
 function setScrollY(value: number): void {
@@ -82,69 +80,61 @@ describe("PageEditor scroll-restore wiring (useScrollRestoreOnSwap)", () => {
     window.location.hash = "";
   });
 
-  it("early trigger restores once the layout settles; post-swap re-assert gated by && editor", () => {
-    // Restore WAITS for the document height to settle (HEIGHT_STABLE_MS), so tests
-    // advance fake timers. `window.scrollY` stays 0 (stubbed scrollTo never updates
-    // it), so scrollTo's call count proxies the number of effective restores.
-    vi.useFakeTimers();
+  it("re-invokes restore after the swap, with the [showStatic, editor] deps/guard", () => {
+    // Target is immediately reachable, so each restore that passes the guard
+    // scrolls synchronously. `window.scrollY` stays 0 (stubbed scrollTo never
+    // updates it), so scrollTo is called once per effective restore — a proxy for
+    // the restore invocation count.
     window.sessionStorage.setItem(`${KEY_PREFIX}guard`, "500");
     setInnerHeight(800);
-    setScrollHeight(2000); // reachable + held steady -> the wait settles
+    setScrollHeight(2000); // maxScroll = 1200 >= 500: reachable, no polling.
 
-    // Pre-swap: the early on-mount trigger's wait settles and restores once — this
-    // is the offline / collab-never-syncs path (no swap needed).
+    // Pre-swap: static content shown, live editor not ready. Only the early
+    // pre-paint restore fires; the post-swap effect's guard (!showStatic) blocks it.
     const { rerender } = render(
       <Host pageId="guard" showStatic={true} editor={null} />,
     );
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
     expect(window.scrollTo).toHaveBeenCalledTimes(1);
 
-    // showStatic flips false but the editor is still null: the post-swap effect
-    // re-runs (deps [showStatic, editor] changed) but its `&& editor` guard must
-    // keep it a no-op. (Dropping `&& editor` would start a fresh wait against a
-    // null editor and produce a 2nd scrollTo, failing this expectation.)
+    // Collab reports synced (showStatic flips false) but the editor is not ready
+    // yet: the swap effect re-runs (deps [showStatic, editor] changed) but the
+    // `&& editor` guard must keep it a no-op. The early effect does NOT re-fire
+    // (its dep [restoreScrollPosition] is a stable useCallback([])).
+    // (Pins the guard: dropping `&& editor` would restore against a null editor,
+    // producing a 2nd scrollTo and failing this expectation.)
     rerender(<Host pageId="guard" showStatic={false} editor={null} />);
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
     expect(window.scrollTo).toHaveBeenCalledTimes(1);
 
     // The static -> live swap completes (showStatic false AND editor present): the
-    // post-swap effect re-invokes restore, whose fresh wait settles and re-asserts.
+    // post-swap effect re-asserts the restore exactly once more, driven solely by
+    // the [showStatic, editor] deps changing.
     rerender(<Host pageId="guard" showStatic={false} editor={fakeEditor} />);
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
     expect(window.scrollTo).toHaveBeenCalledTimes(2);
   });
 
-  it("restore waits for the height to settle before scrolling (end-to-end via the hook)", () => {
+  it("the post-swap re-assert drives a REAL restore (window.scrollTo) via the hook", () => {
+    // End-to-end through the real useScrollPosition (inside the hook): the swap
+    // re-invocation is the CAUSE of the scroll (nothing scrolls before it).
     vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}peg`, "500");
     setInnerHeight(800);
-    setScrollHeight(100); // maxScroll = -700: target not reachable yet.
+    setScrollHeight(100); // maxScroll = -700: target not reachable yet -> polls.
 
-    // Mount + swap while the content is still too short: nothing scrolls, even as
-    // time passes — restore never fires against an unsettled/unreachable layout.
+    // Pre-swap: the early restore runs but content is too short, so it starts
+    // polling (a pending timer) without scrolling. We never advance timers, so the
+    // early poll cannot fire on its own — isolating the swap as the sole cause.
     const { rerender } = render(
       <Host pageId="peg" showStatic={true} editor={null} />,
     );
-    act(() => {
-      vi.advanceTimersByTime(500);
-    });
-    act(() => {
-      rerender(<Host pageId="peg" showStatic={false} editor={fakeEditor} />);
-      vi.advanceTimersByTime(500);
-    });
     expect(window.scrollTo).not.toHaveBeenCalled();
 
-    // The live content finally lays out tall enough and holds steady past the
-    // stable window -> restore fires exactly to the saved target.
-    setScrollHeight(2000);
+    // The live content is now laid out tall enough to reach the target.
+    setScrollHeight(2000); // maxScroll = 1200 >= 500
+
+    // The static -> live swap: the post-swap useLayoutEffect re-invokes the real
+    // hook, whose synchronous tryRestore now reaches the target and scrolls.
     act(() => {
-      vi.advanceTimersByTime(500);
+      rerender(<Host pageId="peg" showStatic={false} editor={fakeEditor} />);
     });
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
   });