From 614ac2dbb836b63eb82d3fc56aaaca5b19a934fc Mon Sep 17 00:00:00 2001
From: Lycoon <hugo.bois@hotmail.fr>
Date: Tue, 11 Aug 2026 00:14:31 +0200
Subject: [PATCH] fixed revision mode stripes rendering on hide, prevent
 project navbar shift during scroll on mobile, fixed content shift when
 switching between paginated/endless scroll mode, improved closing behaviour
 on project page sidebars

---
 components/editor/EditorBottomBar.tsx         |   8 +-
 .../editor/MobileFormatToolbar.module.css     |  10 +
 components/navbar/HomeNavbar.tsx              |  16 +-
 components/navbar/ProjectNavbarMobile.tsx     |  14 +-
 src/app/projects/page.tsx                     |   2 +-
 src/context/ViewContext.tsx                   |   4 +-
 src/lib/editor/use-view-mode-scroll-anchor.ts | 243 ++++++++++++++----
 .../extensions/revisions-extension.ts         |  33 ++-
 src/lib/utils/hooks.ts                        | 107 ++++++++
 .../repro/revisions-overlay-clear.test.ts     | 113 ++++++++
 .../repro/view-mode-scroll-anchor.test.ts     | 213 +++++++++++++++
 11 files changed, 689 insertions(+), 74 deletions(-)
 create mode 100644 src/tests/repro/revisions-overlay-clear.test.ts
 create mode 100644 src/tests/repro/view-mode-scroll-anchor.test.ts

diff --git a/components/editor/EditorBottomBar.tsx b/components/editor/EditorBottomBar.tsx
index 9e2eaef0..9b089bdd 100644
--- a/components/editor/EditorBottomBar.tsx
+++ b/components/editor/EditorBottomBar.tsx
@@ -4,7 +4,7 @@ import { useEffect, useRef, useState } from "react";
 import { useTranslations } from "next-intl";
 import { ChevronDown, ChevronUp } from "lucide-react";
 
-import { useIsPhone, useIsTouch, useViewportBottomInset } from "@src/lib/utils/hooks";
+import { useIsPhone, useIsTouch, usePagePanLock, useViewportBottomInset } from "@src/lib/utils/hooks";
 import { KEYBOARD_MIN_HEIGHT } from "@src/lib/editor/visible-band";
 import { useActiveEditor } from "@src/lib/editor/use-active-editor";
 import { useEditorFocused } from "@src/lib/editor/use-editor-focused";
@@ -120,10 +120,16 @@ const EditorBottomBar = () => {
 
     const hasIslands = isTouch && !isPhone;
 
+    // A drag across the row must never pan the page: this bar is fixed chrome, so
+    // the pan would carry it off the screen (see usePagePanLock). The pill's own
+    // sideways scroll and its upward menus are exempted there.
+    const panLockRef = usePagePanLock<HTMLDivElement>();
+
     if (!isTouch || !isWriting) return null;
 
     return (
         <div
+            ref={panLockRef}
             className={styles.bar_row}
             // Handed to CSS as a length rather than set as `bottom` outright, so
             // the rule can floor it against the resting height — see .bar_row.
diff --git a/components/editor/MobileFormatToolbar.module.css b/components/editor/MobileFormatToolbar.module.css
index 9b137b7b..61d19551 100644
--- a/components/editor/MobileFormatToolbar.module.css
+++ b/components/editor/MobileFormatToolbar.module.css
@@ -153,6 +153,11 @@
     min-width: 0;
     overflow-x: auto;
     -webkit-overflow-scrolling: touch;
+    /* Stop at this row's own ends: without it, a drag that runs past the last
+     * control chains out to the document, and since the bar is fixed chrome that
+     * pans it clean off the screen. The vertical half of the same gesture is
+     * refused outright by the row's pan lock (see usePagePanLock). */
+    overscroll-behavior: contain;
     scrollbar-width: none;
 }
 
@@ -259,6 +264,9 @@
     min-width: 180px;
     max-height: 260px;
     overflow-y: auto;
+    /* Keep a flick through the list from chaining to the document once it hits
+     * either end — that pan takes the whole bar off screen (see .format_group). */
+    overscroll-behavior: contain;
     padding: 6px;
 
     background-color: var(--secondary);
@@ -312,6 +320,8 @@
     max-width: min(280px, 100%);
     max-height: 260px;
     overflow-y: auto;
+    /* As with .element_menu — the suggestions must not chain their scroll out. */
+    overscroll-behavior: contain;
     padding: 6px;
 
     background-color: var(--secondary);
diff --git a/components/navbar/HomeNavbar.tsx b/components/navbar/HomeNavbar.tsx
index dcf8e3eb..554a367e 100644
--- a/components/navbar/HomeNavbar.tsx
+++ b/components/navbar/HomeNavbar.tsx
@@ -13,12 +13,16 @@ import navbar from "./ProjectNavbar.module.css";
 import navBtn from "@components/utils/NavbarIconButton.module.css";
 
 interface HomeNavbarProps {
-    /** Phone only: opens the projects sidebar drawer (the burger lives here now). */
-    onOpenSidebar?: () => void;
+    /**
+     * Phone only: toggles the projects sidebar drawer (the burger lives here now).
+     * Both phone drawers sit below the navbar, so their opener stays tappable while
+     * they're open and has to close them again — see [ProjectPageContainer.module.css].
+     */
+    onToggleSidebar?: () => void;
 }
 
-const HomeNavbar = ({ onOpenSidebar }: HomeNavbarProps) => {
-    const { openDashboard } = useContext(DashboardContext);
+const HomeNavbar = ({ onToggleSidebar }: HomeNavbarProps) => {
+    const { isOpen, openDashboard, closeDashboard } = useContext(DashboardContext);
     const { user, isLoading } = useCookieUser();
     const isPhone = useIsPhone();
     const tNav = useTranslations("navbar");
@@ -29,6 +33,8 @@ const HomeNavbar = ({ onOpenSidebar }: HomeNavbarProps) => {
     // While the auth state is still loading, omit the tab arg so the modal
     // opens on its current activeTab instead of guessing wrong.
     const onOpen = () => {
+        // Second tap on the Settings icon closes the drawer it opened.
+        if (isOpen) return closeDashboard();
         if (isLoading) openDashboard();
         else openDashboard(user ? "Profile" : "Auth");
     };
@@ -44,7 +50,7 @@ const HomeNavbar = ({ onOpenSidebar }: HomeNavbarProps) => {
                     <div className={navbar.mobile_left}>
                         <button
                             className={join(navBtn.button, navbar.mobile_icon, navbar.home_burger)}
-                            onClick={onOpenSidebar}
+                            onClick={onToggleSidebar}
                             aria-label={tNav("menu")}
                         >
                             <Menu size={18} />
diff --git a/components/navbar/ProjectNavbarMobile.tsx b/components/navbar/ProjectNavbarMobile.tsx
index 06995c6b..db9e5027 100644
--- a/components/navbar/ProjectNavbarMobile.tsx
+++ b/components/navbar/ProjectNavbarMobile.tsx
@@ -23,6 +23,7 @@ import { useViewContext } from "@src/context/ViewContext";
 import { useActiveEditor } from "@src/lib/editor/use-active-editor";
 import { getDictationLanguage, useDictation } from "@src/lib/editor/use-dictation";
 import { uploadToCloudPopup } from "@src/lib/screenplay/popup";
+import { usePagePanLock } from "@src/lib/utils/hooks";
 import { join } from "@src/lib/utils/misc";
 
 import { useProjectNavbar } from "./useProjectNavbar";
@@ -160,8 +161,19 @@ const ProjectNavbarMobile = () => {
         setMobileEditMode(false);
     };
 
+    // The bar is a fixed overlay on phone, so a drag that lands on it and pans the
+    // page takes the bar off the top of the screen with it — most visibly while
+    // editing, when the keyboard gives WKWebView's scroll view the room to move.
+    // Refuse those pans here (see usePagePanLock). Everything that scrolls — the
+    // burger drawer, the search panel, the tool sheets — is portaled to <body> and
+    // so sits outside this subtree entirely.
+    const panLockRef = usePagePanLock<HTMLElement>();
+
     return (
-        <nav className={join(navbar.container, chromeHidden ? navbar.container_hidden : "")}>
+        <nav
+            ref={panLockRef}
+            className={join(navbar.container, chromeHidden ? navbar.container_hidden : "")}
+        >
             <nav className={navbar.mobile_bar}>
                 {/* Left cluster: edit-mode controls (leave edit mode + undo/redo)
                     while editing; otherwise the back-to-projects arrow. */}
diff --git a/src/app/projects/page.tsx b/src/app/projects/page.tsx
index 0944587a..a6dcbadc 100644
--- a/src/app/projects/page.tsx
+++ b/src/app/projects/page.tsx
@@ -36,7 +36,7 @@ function ProjectsPageContent() {
     if (!projectId) {
         return (
             <>
-                <HomeNavbar onOpenSidebar={() => setSidebarOpen(true)} />
+                <HomeNavbar onToggleSidebar={() => setSidebarOpen((open) => !open)} />
                 <ProjectPageContainer sidebarOpen={sidebarOpen} setSidebarOpen={setSidebarOpen} />
                 <DashboardModal />
             </>
diff --git a/src/context/ViewContext.tsx b/src/context/ViewContext.tsx
index d532e51b..37e9a420 100644
--- a/src/context/ViewContext.tsx
+++ b/src/context/ViewContext.tsx
@@ -95,8 +95,8 @@ interface ViewContextType {
     /**
      * Subscribe to be called synchronously *just before* `isEndlessScroll`
      * flips — i.e. while the outgoing layout is still on screen and measurable.
-     * Editor panels use it to record which block sits at the top of their
-     * viewport, because the two modes render the same document at very
+     * Editor panels use it to record which block the reader is looking at (and
+     * how far into it), because the two modes render the same document at very
      * different heights and a raw scrollTop would land somewhere else entirely
      * (see DocumentEditorPanel's scroll anchoring). Returns an unsubscribe.
      */
diff --git a/src/lib/editor/use-view-mode-scroll-anchor.ts b/src/lib/editor/use-view-mode-scroll-anchor.ts
index dfee3681..2f4e7c19 100644
--- a/src/lib/editor/use-view-mode-scroll-anchor.ts
+++ b/src/lib/editor/use-view-mode-scroll-anchor.ts
@@ -3,6 +3,8 @@
 import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
 import type { Editor } from "@tiptap/react";
 
+import { coveredBottomBand } from "./visible-band";
+
 // useLayoutEffect warns on the server; fall back to useEffect there. The
 // correction must run before paint, so it needs the layout variant in the browser.
 const useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
@@ -26,6 +28,184 @@ const SETTLED_EPSILON = 0.5;
 /** Class of the page-break widgets, which endless-scroll mode hides entirely. */
 const PAGE_BREAK_CLASS = "pagination-page-break";
 
+/**
+ * Pagination's widget decorations. They are direct children of the editor DOM,
+ * interleaved with the real blocks, and none of them is a usable anchor: the
+ * page breaks are display:none in endless, and the first/last-page widgets are
+ * pure spacers whose height is itself mode-dependent (endless collapses the last
+ * page's freespace down to the bottom margin). Their collapsed rects would also
+ * break the monotonic ordering the search below relies on.
+ *
+ * The page-start *classes* pagination puts on real paragraphs
+ * (pagination-doc-start / pagination-break-start) are deliberately not listed —
+ * those are content, and among the best anchors on a page.
+ */
+const WIDGET_CLASSES = [PAGE_BREAK_CLASS, "pagination-first-page", "pagination-last-page", "page-lock-marker"];
+
+const isWidget = (el: HTMLElement) => WIDGET_CLASSES.some((cls) => el.classList.contains(cls));
+
+/**
+ * A block split across a page boundary (a dialogue running over with
+ * MORE/CONT'D) hosts its break widget *inside* itself, so its own height changes
+ * with the mode and a position partway into it wouldn't map across.
+ */
+const hostsSplitBreak = (el: HTMLElement) => el.querySelector(`.${PAGE_BREAK_CLASS}`) !== null;
+
+/**
+ * Where the reader is looking, as a viewport y coordinate: the middle of the
+ * band of the scroll viewport they can actually see.
+ *
+ * Pinning the *top edge* instead — what this hook did at first — is what still
+ * let the content slide. The top edge is not where the eye is, and every layout
+ * difference between the two modes accumulates between the pinned point and
+ * whatever is actually being read: paged mode reinstates a whole page-break
+ * widget (bottom margin + gap + top margin + freespace) wherever a boundary
+ * falls, so a block halfway down the screen came back a screen-third lower even
+ * though the correction was, strictly speaking, exact. Anchoring on the middle
+ * puts the residual error at the edges, where the eye isn't.
+ *
+ * The band is the scroll viewport minus whatever covers its bottom — an
+ * on-screen keyboard and the format bar riding on it (coveredBottomBand, the
+ * same measure the caret follow and that bar itself position against). On a
+ * tablet the view-mode toggle lives in exactly that bar, so this switch is
+ * routinely made with a keyboard up and half the viewport not being looked at.
+ * The scroller's navbar-height top padding on phone is *not* discounted: the bar
+ * is a narrow overlay and the content genuinely scrolls, visibly, under it.
+ */
+const focalPoint = (container: HTMLElement) => {
+    const top = container.getBoundingClientRect().top;
+    const covered = coveredBottomBand();
+    const viewportBottom = top + container.clientHeight;
+    // Never above `top`: a keyboard covering the whole scroller leaves no band to
+    // take a middle of, and the top edge is the sane degenerate answer.
+    const bottom = Math.max(top, covered > 0 ? Math.min(viewportBottom, window.innerHeight - covered) : viewportBottom);
+    return (top + bottom) / 2;
+};
+
+/**
+ * A reading position expressed as content rather than as a pixel offset: which
+ * block the reader is looking at, and how far into it.
+ */
+export interface ViewModeAnchor {
+    el: HTMLElement;
+    /** data-id of the block, to re-resolve `el` if its DOM gets recreated. */
+    id: string | null;
+    /**
+     * How far into the block the focal point falls, as a fraction of its height.
+     * A fraction rather than a pixel depth because the block itself is not the
+     * same height in both modes — on phone, endless reflows it to a narrow
+     * measure at full font size while paged renders the canonical page scaled
+     * down — and a paragraph that goes from five lines to two still comes back
+     * showing the part of itself that was being read.
+     */
+    ratio: number;
+    /**
+     * Leftover distance from that point to the focal point, non-zero only when
+     * the focal point isn't inside the block at all (the split-block skip below
+     * can push the anchor a block away). Pins the block's near edge, as the
+     * first version of this did.
+     */
+    offset: number;
+}
+
+/**
+ * Nearest block to the focal point that isn't split across a page boundary,
+ * searching outwards from `from` in both directions. -1 if every block is split.
+ */
+const nearestUnsplit = (blocks: HTMLElement[], from: number, focus: number): number => {
+    if (!hostsSplitBreak(blocks[from])) return from;
+
+    let before = from - 1;
+    while (before >= 0 && hostsSplitBreak(blocks[before])) before--;
+    let after = from + 1;
+    while (after < blocks.length && hostsSplitBreak(blocks[after])) after++;
+
+    if (before < 0) return after < blocks.length ? after : -1;
+    if (after >= blocks.length) return before;
+
+    // Whichever is closer: the residual error is whatever the two modes disagree
+    // about over the gap between the anchor and the focal point, so the shorter
+    // gap wins.
+    const gapBefore = focus - blocks[before].getBoundingClientRect().bottom;
+    const gapAfter = blocks[after].getBoundingClientRect().top - focus;
+    return gapAfter < gapBefore ? after : before;
+};
+
+/**
+ * Record what the reader is looking at. Must run while the outgoing layout is
+ * still on screen, i.e. synchronously before the mode flips.
+ */
+export const captureViewModeAnchor = (container: HTMLElement, dom: HTMLElement): ViewModeAnchor | null => {
+    const blocks = (Array.from(dom.children) as HTMLElement[]).filter((child) => !isWidget(child));
+    if (blocks.length === 0) return null;
+
+    const focus = focalPoint(container);
+
+    // First block whose bottom edge is past the focal point, i.e. the block the
+    // reader's eye is on. Binary search rather than a scan: rects are monotonic
+    // in document order, and a feature-length script has thousands of blocks.
+    // The first read flushes layout, so the ~12 that follow are cheap.
+    let lo = 0;
+    let hi = blocks.length - 1;
+    let found = blocks.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (blocks[mid].getBoundingClientRect().bottom > focus) {
+            found = mid;
+            hi = mid - 1;
+        } else {
+            lo = mid + 1;
+        }
+    }
+
+    const index = nearestUnsplit(blocks, found, focus);
+    if (index < 0) return null;
+
+    const el = blocks[index];
+    const rect = el.getBoundingClientRect();
+    // Clamped: when the skip above moved the anchor off the focal point, the
+    // leftover distance goes to `offset` instead of distorting the fraction.
+    const ratio = rect.height > 0 ? Math.min(1, Math.max(0, (focus - rect.top) / rect.height)) : 0;
+    return {
+        el,
+        id: el.getAttribute("data-id"),
+        ratio,
+        offset: focus - (rect.top + ratio * rect.height),
+    };
+};
+
+/**
+ * Put the anchored reading position back under the focal point, by scrolling the
+ * container by however far the new layout moved it. Returns whether it was
+ * already in place, i.e. there was nothing to correct.
+ */
+export const applyViewModeAnchor = (container: HTMLElement, anchor: ViewModeAnchor): boolean => {
+    // Re-resolve when the block's DOM was recreated under us: pagination redraws
+    // by replacing widget and node decorations, so the captured element can be
+    // detached by the time the new mode is laid out. Treating that as "nothing to
+    // correct" is what would silently drop the whole correction.
+    if (!anchor.el.isConnected) {
+        const replacement = anchor.id
+            ? (container.querySelector(`[data-id="${CSS.escape(anchor.id)}"]`) as HTMLElement | null)
+            : null;
+        if (!replacement) return true;
+        anchor.el = replacement;
+    }
+
+    const rect = anchor.el.getBoundingClientRect();
+    const delta = rect.top + anchor.ratio * rect.height + anchor.offset - focalPoint(container);
+    if (Math.abs(delta) < SETTLED_EPSILON) return true;
+
+    const maxScroll = container.scrollHeight - container.clientHeight;
+    const next = Math.max(0, Math.min(maxScroll, container.scrollTop + delta));
+    // Clamped at either end — the document simply isn't long enough to put the
+    // anchor back. Report it settled so the loop stops instead of burning its
+    // whole budget re-measuring a correction it can't apply.
+    if (next === container.scrollTop) return true;
+    container.scrollTop = next;
+    return false;
+};
+
 interface ViewModeScrollAnchorOptions {
     /** The scroll container whose reading position must be preserved. */
     container: HTMLElement | null;
@@ -52,9 +232,9 @@ interface ViewModeScrollAnchorOptions {
  * you are — a switch near the end can be pages off.
  *
  * The fix is to preserve the *content* rather than a pixel offset: just before
- * the switch, record which block sits at the top of the viewport and how far into
- * it we are; afterwards, scroll by however far the new layout moved that block.
- * Everything here runs on a toggle only — never during scrolling or typing.
+ * the switch, record which block the reader is looking at and how far into it;
+ * afterwards, scroll by however far the new layout moved that point. Everything
+ * here runs on a toggle only — never during scrolling or typing.
  *
  * Both phases are layout-phase, so the correction lands before the browser paints
  * and is never seen as a jump. Callers whose own effects change the mode's layout
@@ -67,7 +247,7 @@ export const useViewModeScrollAnchor = ({
     viewMode,
     onBeforeChange,
 }: ViewModeScrollAnchorOptions) => {
-    const anchorRef = useRef<{ el: HTMLElement; offset: number } | null>(null);
+    const anchorRef = useRef<ViewModeAnchor | null>(null);
 
     // Runs synchronously before the mode flips, so the outgoing layout is still
     // on screen and measurable.
@@ -75,46 +255,7 @@ export const useViewModeScrollAnchor = ({
         anchorRef.current = null;
         const dom = editor && !editor.isDestroyed ? (editor.view?.dom as HTMLElement | undefined) : undefined;
         if (!container || !dom) return;
-
-        // Only blocks that exist in BOTH modes make usable anchors: the page-break
-        // widgets are display:none in endless, so one picked here would have no
-        // position to come back to — and its collapsed rect would also break the
-        // monotonic ordering the search below relies on.
-        const blocks = (Array.from(dom.children) as HTMLElement[]).filter(
-            (child) => !child.classList.contains(PAGE_BREAK_CLASS),
-        );
-        if (blocks.length === 0) return;
-
-        // First block whose bottom edge is still below the top of the visible
-        // area. Binary search rather than a scan: rects are monotonic in document
-        // order, and a feature-length script has thousands of blocks. The first
-        // read flushes layout, so the ~12 that follow are cheap.
-        const containerTop = container.getBoundingClientRect().top;
-        let lo = 0;
-        let hi = blocks.length - 1;
-        let found = blocks.length - 1;
-        while (lo <= hi) {
-            const mid = (lo + hi) >> 1;
-            if (blocks[mid].getBoundingClientRect().bottom > containerTop) {
-                found = mid;
-                hi = mid - 1;
-            } else {
-                lo = mid + 1;
-            }
-        }
-
-        // A block split across a page boundary (a dialogue running over with
-        // MORE/CONT'D) hosts its break widget *inside* itself, so its own height
-        // changes with the mode and a position partway into it wouldn't map
-        // across. Step past those to the next unsplit block — the offset below is
-        // signed and relative to the viewport top, so anchoring to a block under
-        // the fold restores just as exactly as one at the fold.
-        while (found < blocks.length - 1 && blocks[found].querySelector(`.${PAGE_BREAK_CLASS}`)) found++;
-
-        const el = blocks[found];
-        // Signed: negative when the block starts above the fold (we're partway
-        // through it), so the same line — not merely the same block — comes back.
-        anchorRef.current = { el, offset: el.getBoundingClientRect().top - containerTop };
+        anchorRef.current = captureViewModeAnchor(container, dom);
     }, [container, editor]);
 
     // Subscribe through a ref so a new container/editor identity doesn't churn the
@@ -126,20 +267,10 @@ export const useViewModeScrollAnchor = ({
 
     useEffect(() => onBeforeChange(() => captureRef.current()), [onBeforeChange]);
 
-    /**
-     * Put the anchored block back where it was, by scrolling the container by
-     * however far the new layout moved it. Returns whether it was already in
-     * place, i.e. there was nothing to correct.
-     */
     const restore = useCallback((): boolean => {
         const anchor = anchorRef.current;
-        if (!container || !anchor || !anchor.el.isConnected) return true;
-
-        const delta = anchor.el.getBoundingClientRect().top - container.getBoundingClientRect().top - anchor.offset;
-        if (Math.abs(delta) < SETTLED_EPSILON) return true;
-        const maxScroll = container.scrollHeight - container.clientHeight;
-        container.scrollTop = Math.max(0, Math.min(maxScroll, container.scrollTop + delta));
-        return false;
+        if (!container || !anchor) return true;
+        return applyViewModeAnchor(container, anchor);
     }, [container]);
 
     const prevModeRef = useRef(viewMode);
diff --git a/src/lib/screenplay/extensions/revisions-extension.ts b/src/lib/screenplay/extensions/revisions-extension.ts
index 28ff7358..35c068d1 100644
--- a/src/lib/screenplay/extensions/revisions-extension.ts
+++ b/src/lib/screenplay/extensions/revisions-extension.ts
@@ -697,11 +697,11 @@ export const createRevisionsExtension = (config: RevisionsConfig) => {
         name: "revisions",
 
         addProseMirrorPlugins() {
-            // One stable container, mounted via a single widget decoration — but
-            // ONLY while revisions are enabled. When disabled the plugin adds no
-            // decoration, schedules no frames, and stamps nothing, so it costs a
-            // single boolean check per transaction (the editor hot path stays
-            // exactly as it was before the feature).
+            // One stable container, mounted via a single widget decoration. It is
+            // always mounted (see `decorations` below) but stays EMPTY while
+            // revisions are hidden: no children are built, no frames scheduled and
+            // nothing is stamped, so the feature costs a single boolean check per
+            // transaction (the editor hot path stays exactly as it was before it).
             const overlay = document.createElement("div");
             overlay.className = "revision-overlay";
             overlay.setAttribute("contenteditable", "false");
@@ -770,10 +770,27 @@ export const createRevisionsExtension = (config: RevisionsConfig) => {
                     },
 
                     props: {
-                        // No decoration at all when display is hidden → ProseMirror
-                        // does no extra reconciliation for this plugin on the hot path.
+                        // The overlay widget stays mounted in EVERY mode, including
+                        // "hidden" — there it is simply emptied (see the view's
+                        // update below), which costs nothing beyond the single stable
+                        // widget every other mode already carries.
+                        //
+                        // Dropping the decoration instead (returning null) detaches
+                        // the overlay with its stripes still inside, and WebKit does
+                        // not repaint the area an absolutely-positioned child covered
+                        // when the zero-sized parent that holds it is removed — the
+                        // stripes sit in the parent's visual overflow, which its own
+                        // repaint rect doesn't span. On Safari that left the stripes
+                        // painted over every page the viewport had already drawn when
+                        // "No revision" was picked, while pages that had never been
+                        // painted (the renderer is viewport-culled) correctly showed
+                        // none. Removing the stripe elements themselves while the
+                        // overlay is still in the document repaints each one normally
+                        // — the path scroll culling and the "current" filter already
+                        // take on every frame.
                         decorations(state) {
-                            if (getDisplayMode() === "hidden") return null;
+                            // Hidden: overlay only — no live colouring of pending text.
+                            if (getDisplayMode() === "hidden") return DecorationSet.create(state.doc, [overlayDeco]);
 
                             // Colour the still-pending (not-yet-flushed) inserted
                             // text live, via cheap inline decorations rebuilt from
diff --git a/src/lib/utils/hooks.ts b/src/lib/utils/hooks.ts
index 9fc09ec3..47b5ee77 100644
--- a/src/lib/utils/hooks.ts
+++ b/src/lib/utils/hooks.ts
@@ -209,6 +209,112 @@ const useKeyboardInset = (enabled: boolean): number => useViewportInset(enabled,
 const useViewportBottomInset = (enabled: boolean): number =>
     useViewportInset(enabled, viewportBottomInset);
 
+/** Movement (px) before a drag is committed to an axis — below this it's a tap. */
+const PAN_AXIS_THRESHOLD = 3;
+
+/**
+ * Nearest ancestor of `target`, up to and including `root`, that can actually
+ * scroll along `axis` — i.e. is a scroll container on that axis *and* has content
+ * overflowing it. Null when the drag has nothing inside the chrome to scroll, in
+ * which case the browser would hand it to the page.
+ */
+const scrollerForAxis = (target: EventTarget | null, root: HTMLElement, axis: "x" | "y"): HTMLElement | null => {
+    let el = target instanceof Element ? target : null;
+    while (el) {
+        if (el instanceof HTMLElement) {
+            const style = getComputedStyle(el);
+            const overflow = axis === "y" ? style.overflowY : style.overflowX;
+            const scrolls =
+                axis === "y" ? el.scrollHeight > el.clientHeight : el.scrollWidth > el.clientWidth;
+            if ((overflow === "auto" || overflow === "scroll") && scrolls) return el;
+        }
+        if (el === root) return null;
+        el = el.parentElement;
+    }
+    return null;
+};
+
+/**
+ * Keep a drag that lands on a piece of fixed chrome from panning the page behind
+ * it, and return the ref to hang on that chrome.
+ *
+ * The app shell is pinned to the viewport (html/body `overflow: clip`), but with
+ * the on-screen keyboard up WKWebView still gives its scroll view room to move —
+ * the keyboard is added as a bottom content inset — so a drag the page has no
+ * inner scroller for pans the whole document instead. Fixed chrome is positioned
+ * against the layout viewport, so that pan carries the navbar and the format bar
+ * clean off the screen, and they only come back when [ProjectWorkspace]'s anchor
+ * guard snaps the document back at the end of the gesture. Both must stay put for
+ * the whole gesture, so the pan has to be refused where it starts.
+ *
+ * Only pans with nowhere to go are refused. The axis is decided from the first
+ * few px of the drag and matched against the scrollers inside the chrome, so the
+ * format bar's sideways scroll and its upward menus keep working while a vertical
+ * drag across those same controls — the gesture that used to take the bar with it
+ * — is swallowed. Their own `overscroll-behavior: contain` covers the rest: once a
+ * scroller is at its end, the leftover must not chain out to the document.
+ *
+ * A native non-passive listener rather than React's `onTouchMove`, which is
+ * registered passively and so cannot preventDefault. Handed back as a *callback*
+ * ref so the listeners follow the node itself: both consumers come and go with the
+ * mode they belong to, and an effect keyed on mount would have run against a null
+ * ref and never re-run when the chrome finally appeared.
+ */
+const usePagePanLock = <T extends HTMLElement>(): ((node: T | null) => void) => {
+    const detachRef = useRef<(() => void) | null>(null);
+
+    return useCallback((node: T | null) => {
+        detachRef.current?.();
+        detachRef.current = null;
+        if (!node) return;
+
+        let start: { x: number; y: number } | null = null;
+        // null while the drag is still too small to have an axis; true once it has
+        // been resolved to one nothing here can absorb, and is refused for the rest
+        // of the gesture (the axis must not flip mid-drag).
+        let block: boolean | null = null;
+
+        const onTouchStart = (e: TouchEvent) => {
+            const touch = e.touches[0];
+            start = e.touches.length === 1 && touch ? { x: touch.clientX, y: touch.clientY } : null;
+            block = null;
+        };
+
+        const onTouchMove = (e: TouchEvent) => {
+            // A second finger means pinch-zoom, which is the browser's to handle.
+            if (!start || e.touches.length > 1) return;
+            const touch = e.touches[0];
+            if (!touch) return;
+
+            if (block === null) {
+                const dx = touch.clientX - start.x;
+                const dy = touch.clientY - start.y;
+                if (Math.abs(dx) < PAN_AXIS_THRESHOLD && Math.abs(dy) < PAN_AXIS_THRESHOLD) return;
+                const axis = Math.abs(dy) >= Math.abs(dx) ? "y" : "x";
+                block = !scrollerForAxis(e.target, node, axis);
+            }
+
+            if (block) e.preventDefault();
+        };
+
+        const onTouchEnd = () => {
+            start = null;
+            block = null;
+        };
+
+        node.addEventListener("touchstart", onTouchStart, { passive: true });
+        node.addEventListener("touchmove", onTouchMove, { passive: false });
+        node.addEventListener("touchend", onTouchEnd, { passive: true });
+        node.addEventListener("touchcancel", onTouchEnd, { passive: true });
+        detachRef.current = () => {
+            node.removeEventListener("touchstart", onTouchStart);
+            node.removeEventListener("touchmove", onTouchMove);
+            node.removeEventListener("touchend", onTouchEnd);
+            node.removeEventListener("touchcancel", onTouchEnd);
+        };
+    }, []);
+};
+
 const useProjectIdFromUrl = () => {
     const searchParams = useSearchParams();
     return searchParams.get("projectId") ?? "";
@@ -695,6 +801,7 @@ export {
     useIsTouch,
     useKeyboardInset,
     useViewportBottomInset,
+    usePagePanLock,
     useCachedProjects,
     useCachedProjectInfo,
     useProjectIdFromUrl,
diff --git a/src/tests/repro/revisions-overlay-clear.test.ts b/src/tests/repro/revisions-overlay-clear.test.ts
new file mode 100644
index 00000000..f7c57da5
--- /dev/null
+++ b/src/tests/repro/revisions-overlay-clear.test.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { Editor } from "@tiptap/core";
+
+import { BASE_EXTENSIONS } from "@src/lib/screenplay/editor";
+import { createRevisionsExtension, refreshRevisions } from "@src/lib/screenplay/extensions/revisions-extension";
+
+/**
+ * Regression guard for hiding the revision overlay ("No revision" in the
+ * production panel).
+ *
+ * The overlay's stripes/asterisks are absolutely-positioned children of a
+ * zero-sized container, most of them outside its box. Clearing the overlay by
+ * dropping its widget decoration therefore removed a 0×0 element whose repaint
+ * rect doesn't span its children: WebKit never invalidated the area they
+ * covered, so on Safari every stripe the viewport had already painted stayed on
+ * screen (pages that were never painted — the renderer is viewport-culled —
+ * correctly showed none). The overlay must stay mounted and be emptied in
+ * place, so each stripe's own removal repaints it.
+ */
+
+type RevState = { enabled: boolean; current: number; display: "all" | "hidden" | "current" };
+
+function makeEditor(n: number) {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const rev: RevState = { enabled: false, current: 0, display: "all" };
+
+    const content: object[] = [];
+    for (let i = 0; i < n; i++) {
+        content.push({
+            type: "action",
+            attrs: { "data-id": `n${i}`, class: "action" },
+            content: [{ type: "text", text: `L${i}` }],
+        });
+    }
+
+    const editor = new Editor({
+        element: el,
+        injectCSS: false,
+        autofocus: false,
+        content: { type: "doc", content },
+        extensions: [
+            ...BASE_EXTENSIONS,
+            createRevisionsExtension({
+                getRevisionsEnabled: () => rev.enabled,
+                getCurrentRevision: () => rev.current,
+                getDisplayMode: () => rev.display,
+            }),
+        ],
+    });
+
+    // The overlay renderer reads its page geometry from these (normally set by
+    // the pagination extension); without them it bails out and paints nothing.
+    const dom = editor.view.dom as HTMLElement;
+    dom.style.setProperty("--page-height", "1000px");
+    dom.style.setProperty("--page-gap", "20px");
+    dom.style.setProperty("--page-width", "800px");
+    dom.style.setProperty("--page-margin-right", "100px");
+    dom.style.setProperty("--page-margin-top", "0px");
+    dom.style.setProperty("--page-margin-bottom", "0px");
+    dom.style.setProperty("--line-height", "16px");
+    return { editor, rev, el };
+}
+
+/** Revision stamping is debounced (FLUSH_DELAY = 220ms). */
+const settle = () => new Promise((r) => setTimeout(r, 320));
+/** The overlay repaints on a coalesced rAF; two frames is past it. */
+const frames = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r(null))));
+
+function insidePos(editor: Editor, index: number): number {
+    let pos = -1;
+    editor.state.doc.forEach((node, p, i) => {
+        if (i === index) pos = p + 1;
+    });
+    return pos;
+}
+
+const overlayOf = (el: HTMLElement) => el.querySelector(".revision-overlay") as HTMLElement | null;
+
+describe("revisions overlay: hiding the display", () => {
+    it("empties the overlay in place instead of detaching it", async () => {
+        const { editor, rev, el } = makeEditor(6);
+        rev.enabled = true;
+        rev.current = 1;
+        editor.chain().focus().insertContentAt(insidePos(editor, 2), "hello").run();
+        await settle();
+        refreshRevisions(editor);
+        await frames();
+
+        const overlay = overlayOf(el);
+        expect(overlay).not.toBeNull();
+        expect(overlay!.querySelectorAll(".revision-stripe").length).toBeGreaterThan(0);
+        expect(overlay!.querySelectorAll(".revision-asterisk").length).toBeGreaterThan(0);
+
+        rev.display = "hidden";
+        refreshRevisions(editor);
+        await frames();
+
+        // Emptied…
+        expect(overlay!.childElementCount).toBe(0);
+        // …while still in the document: the stripes are removed one by one from
+        // an attached parent, which is what makes WebKit repaint their area.
+        expect(overlay!.isConnected).toBe(true);
+
+        // And it comes back on re-show.
+        rev.display = "all";
+        refreshRevisions(editor);
+        await frames();
+        expect(overlay!.querySelectorAll(".revision-stripe").length).toBeGreaterThan(0);
+
+        editor.destroy();
+    });
+});
diff --git a/src/tests/repro/view-mode-scroll-anchor.test.ts b/src/tests/repro/view-mode-scroll-anchor.test.ts
new file mode 100644
index 00000000..f2f5a12a
--- /dev/null
+++ b/src/tests/repro/view-mode-scroll-anchor.test.ts
@@ -0,0 +1,213 @@
+import { describe, it, expect, afterEach } from "vitest";
+
+import { applyViewModeAnchor, captureViewModeAnchor } from "@src/lib/editor/use-view-mode-scroll-anchor";
+
+/**
+ * Regression guard for the reading position across the endless ⇄ paged switch.
+ *
+ * Real layout, so this runs in the browser instances (chromium + webkit) and
+ * exercises the two shapes the switch actually takes:
+ *
+ *  - tablet/desktop: both modes lay the text out identically and the only
+ *    difference is that paged reinstates the page-break widgets. Pinning the
+ *    *top* of the viewport was therefore exact and still slid the reader: every
+ *    boundary that falls on screen pushes everything below it down by a whole
+ *    spacer, so a block in the middle came back near the bottom.
+ *  - phone: endless additionally reflows to a compact measure at full font size
+ *    while paged renders the canonical page under a transform: scale(), so the
+ *    same block is a very different height in each.
+ *
+ * Both are checked against the same invariant: whatever was under the middle of
+ * the viewport is still under it afterwards.
+ */
+
+const VIEWPORT_H = 700;
+const NAVBAR_PAD = 56;
+/** Bottom margin + inter-page gap + top margin of a page-break widget. */
+const BREAK_H = 212;
+const BLOCKS_PER_PAGE = 12;
+const PAGES = 10;
+/** A block's height in paged (canonical) layout. */
+const BLOCK_H = 32;
+/** …and in phone endless, where the narrow measure wraps it onto more lines. */
+const BLOCK_H_REFLOWED = 96;
+const PHONE_ZOOM = 0.47;
+
+type Kind = "tablet" | "phone";
+
+interface Harness {
+    container: HTMLElement;
+    blocks: HTMLElement[];
+    /** Viewport y of the point the reader is looking at. */
+    focus: () => number;
+    /** Viewport y of a block's middle. */
+    middleOf: (block: HTMLElement) => number;
+    setPaged: () => void;
+    cleanup: () => void;
+}
+
+const style = document.createElement("style");
+style.textContent = `
+    .vma_container { position: absolute; top: 0; left: 0; overflow-y: auto; overflow-x: hidden; }
+    .vma_container.phone { width: 390px; padding-top: ${NAVBAR_PAD}px; }
+    .vma_container.tablet { width: 900px; }
+    .vma_pm { width: 816px; margin: 0 auto; }
+    .vma_pm > p { height: ${BLOCK_H}px; margin: 0; }
+
+    /* Endless hides every inter-page break. */
+    .vma_wrapper.endless .pagination-page-break { display: none; }
+
+    /* Phone endless: fill the width and reflow onto more lines. */
+    .vma_wrapper.phone.endless .vma_pm { width: 100%; }
+    .vma_wrapper.phone.endless .vma_pm > p { height: ${BLOCK_H_REFLOWED}px; }
+
+    /* Phone paged: the canonical page scaled down to fit, with the (1 − zoom)
+       tail of the layout height collapsed away — as in EditorPanel.module.css. */
+    .vma_wrapper.phone:not(.endless) .vma_pm {
+        transform: scale(${PHONE_ZOOM});
+        transform-origin: top center;
+        margin-bottom: calc((${PHONE_ZOOM} - 1) * var(--layout-height, 0px));
+    }
+`;
+document.head.appendChild(style);
+
+const widget = (cls: string, height: number) => {
+    const el = document.createElement("div");
+    el.className = cls;
+    el.contentEditable = "false";
+    el.style.height = `${height}px`;
+    return el;
+};
+
+/**
+ * A document of PAGES pages: a first-page spacer, then blocks with a page-break
+ * widget at every page boundary, then the last-page spacer.
+ */
+function build(kind: Kind): Harness {
+    const container = document.createElement("div");
+    container.className = `vma_container ${kind}`;
+    container.style.height = `${VIEWPORT_H}px`;
+
+    const wrapper = document.createElement("div");
+    wrapper.className = `vma_wrapper ${kind} endless`;
+
+    const pm = document.createElement("div");
+    pm.className = "vma_pm";
+
+    pm.appendChild(widget("pagination-first-page", 96));
+    const blocks: HTMLElement[] = [];
+    for (let i = 0; i < PAGES * BLOCKS_PER_PAGE; i++) {
+        if (i > 0 && i % BLOCKS_PER_PAGE === 0) pm.appendChild(widget("pagination-page-break", BREAK_H));
+        const p = document.createElement("p");
+        p.setAttribute("data-id", `b${i}`);
+        p.textContent = `block ${i}`;
+        pm.appendChild(p);
+        blocks.push(p);
+    }
+    pm.appendChild(widget("pagination-last-page", 96));
+
+    wrapper.appendChild(pm);
+    container.appendChild(wrapper);
+    document.body.appendChild(container);
+
+    return {
+        container,
+        blocks,
+        focus: () => container.getBoundingClientRect().top + container.clientHeight / 2,
+        middleOf: (block) => {
+            const rect = block.getBoundingClientRect();
+            return rect.top + rect.height / 2;
+        },
+        setPaged: () => {
+            wrapper.classList.remove("endless");
+            // Mirrors DocumentEditorPanel's layout effect, which publishes the
+            // untransformed height before the anchor is re-applied.
+            if (kind === "phone") container.style.setProperty("--layout-height", `${pm.offsetHeight}px`);
+        },
+        cleanup: () => container.remove(),
+    };
+}
+
+/** The hook's rAF settle loop, run synchronously — layout is flushed per read. */
+const settle = (harness: Harness, anchor: ReturnType<typeof captureViewModeAnchor>) => {
+    for (let i = 0; i < 5; i++) {
+        if (applyViewModeAnchor(harness.container, anchor!)) break;
+    }
+};
+
+/** Scroll so a block's middle sits exactly under the focal point. */
+const stareAt = (harness: Harness, block: HTMLElement) => {
+    harness.container.scrollTop += harness.middleOf(block) - harness.focus();
+};
+
+let active: Harness | null = null;
+afterEach(() => {
+    active?.cleanup();
+    active = null;
+});
+
+describe("view-mode scroll anchor", () => {
+    for (const kind of ["tablet", "phone"] as Kind[]) {
+        it(`keeps the block under the reader's eye in place (${kind})`, () => {
+            const harness = (active = build(kind));
+            // Deep enough into the script that several page boundaries — and on
+            // phone the whole reflow difference — have accumulated above.
+            const target = harness.blocks[BLOCKS_PER_PAGE * 5 + 6];
+            stareAt(harness, target);
+
+            const anchor = captureViewModeAnchor(harness.container, harness.container.querySelector(".vma_pm")!);
+            expect(anchor).not.toBeNull();
+
+            harness.setPaged();
+
+            // The scenario has to be a real one: carrying the scroll position
+            // across untouched moves the block far off the focal point.
+            expect(Math.abs(harness.middleOf(target) - harness.focus())).toBeGreaterThan(100);
+
+            settle(harness, anchor);
+            expect(harness.middleOf(target) - harness.focus()).toBeLessThan(2);
+            expect(harness.middleOf(target) - harness.focus()).toBeGreaterThan(-2);
+        });
+    }
+
+    it("anchors to a neighbour when the reader's block straddles a page boundary", () => {
+        const harness = (active = build("tablet"));
+        const target = harness.blocks[BLOCKS_PER_PAGE * 4 + 3];
+        // A block split mid-way across a boundary hosts the break widget inside
+        // itself, so its own height is mode-dependent and it can't be anchored to.
+        const split = widget("pagination-page-break", BREAK_H);
+        target.appendChild(split);
+        stareAt(harness, target);
+
+        const anchor = captureViewModeAnchor(harness.container, harness.container.querySelector(".vma_pm")!);
+        expect(anchor).not.toBeNull();
+        expect(anchor!.el).not.toBe(target);
+        // …and to one right next to it, not to some far-away fallback.
+        expect(Math.abs(harness.blocks.indexOf(anchor!.el) - harness.blocks.indexOf(target))).toBe(1);
+
+        harness.setPaged();
+        settle(harness, anchor);
+
+        // The neighbour is pinned exactly; the reader's own block is off by at
+        // most what the two modes disagree about over one block.
+        expect(Math.abs(harness.middleOf(target) - harness.focus())).toBeLessThan(BLOCK_H + BREAK_H);
+    });
+
+    it("re-resolves the anchored block when its DOM is recreated by the switch", () => {
+        const harness = (active = build("tablet"));
+        const target = harness.blocks[BLOCKS_PER_PAGE * 3 + 4];
+        stareAt(harness, target);
+
+        const pm = harness.container.querySelector(".vma_pm") as HTMLElement;
+        const anchor = captureViewModeAnchor(harness.container, pm);
+        harness.setPaged();
+
+        // Pagination redraws by replacing decorations, which can swap the whole
+        // element out from under the captured reference.
+        const replacement = anchor!.el.cloneNode(true) as HTMLElement;
+        anchor!.el.replaceWith(replacement);
+
+        settle(harness, anchor);
+        expect(Math.abs(harness.middleOf(replacement) - harness.focus())).toBeLessThan(2);
+    });
+});