fix(editor): smooth scroll-position restore, no yank on early scroll (#266)

The reading-position restore fired only after collab sync (`!showStatic`),
so the page painted at the top and then visibly jumped — and readers who had
already started scrolling were rudely yanked back to the saved position.

- Abort restore permanently on genuine user scroll intent: `wheel`/`touchstart`
  unconditionally, and `keydown` only for real scroll keys (Arrow/Page/Home/End/
  Space) so shortcuts and typing do not disable it. Our own `window.scrollTo`
  never emits these, so restore cannot self-abort.
- Restore earlier via `useLayoutEffect` (before paint) while the static/cached
  content is laid out, and re-assert once after the static->live editor swap.
- Make `restoreScrollPosition` idempotent with a redundancy guard so the two
  triggers never double-scroll; share one bounded timeout budget across them.
- Add tests for interaction-abort, scroll-key filtering, idempotence.

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

AGENTS.md

@@ -72,10 +72,7 @@ git log -1 --format='Author: %an <%ae>%nCommitter: %cn <%ce>'
 
 ### 4. Push and PR to develop
 
-PRs always target `develop`. Two different mechanisms are involved: **pushing
+PRs always target `develop`. The `claude_code` password lives in the macOS
-commits is git-native** (the Gitea MCP cannot push local git history, so the
-branch is still pushed with `git push`), while **the PR itself is opened through
-the Gitea MCP** (see below). The `claude_code` password lives in the macOS
 keychain as a **generic password** under service `gitea-claude-code` (do not
 duplicate it as an internet-password for `gitea.vvzvlad.xyz` — that creates a
 conflict with the owner's account in the git credential helper):
@@ -97,24 +94,18 @@ git remote set-url gitea "$ORIG_URL"
 unset AGENT_PASS SAFE_PASS
 ```
 
-The PR is opened through the **Gitea MCP** (server `gitea`), not `curl`/`tea` —
+The PR is created via the Gitea REST API (Basic Auth as `claude_code`):
-the MCP authenticates in-process, so no keychain lookup or Basic-Auth is needed.
-Call `pull_request_write` with:
 
-- `method: "create"`
+```bash
-- `owner: "vvzvlad"`, `repo: "gitmost"`
+curl -s -X POST \
-- `base: "develop"`, `head: "<branch>"`
+  -u "claude_code:$(security find-generic-password -s gitea-claude-code -w)" \
-- `title`, `body` — in the body: what was done, what is out of scope,
+  -H "Content-Type: application/json" \
-  verification results (tsc/lint/tests).
+  -d @pr_body.json \
+  "https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls"
+```
 
-Manage and read PRs through the same server: `list_pull_requests`,
+`base: develop`, `head: <branch>`. In the PR body: what was done, what is out
-`pull_request_read` (`get`, `get_diff`, `get_files`, `get_status`),
+of scope, verification results (tsc/lint/tests).
-`pull_request_review_write`.
-
-**Identity note:** the MCP acts under its **own** configured Gitea token (verify
-with `get_me`), a different account from the `claude_code` used for git
-commits/pushes in §3. Only the forge API calls (PR / issue / review) go through
-the MCP account; the commits themselves stay authored as `claude_code`.
 
 > If push fails with `User permission denied for writing`, then `claude_code`
 > lacks collaborator rights on the repo. Ask the owner to add them (once, via
@@ -161,25 +152,23 @@ below.
 | Agent user (Gitea/git) | `claude_code` |
 | Agent email | `claude_code@vvzvlad.xyz` |
 | Keychain password | `security find-generic-password -s gitea-claude-code -w` |
-| Forge API (PR / issue / review / reads) | **Gitea MCP** — server `gitea` (`pull_request_write`, `issue_write`, `list_pull_requests`, `pull_request_read`, `label_read`, …). Authenticated in-process; acts under its own token — check with `get_me`. Repo slug on the server is `gitmost`. |
+| PR API | `https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls` (here `gitmost` is the repo's real slug on the server) |
 | Base branch | `develop` |
 | `origin` | GitHub mirror `vvzvlad/gitmost` — **do not push**, updated by the owner's CI |
 | `upstream` | The original Docmost — **never push** |
 
-## Creating issues (Gitea MCP)
+## Creating issues (Gitea `tea` CLI)
 
-File issues through the **Gitea MCP** (server `gitea`), not a CLI — call
+Issues are filed with the official Gitea CLI `tea`, already logged in as
-`issue_write` with:
+`claude_code` (`tea logins list` shows the `gitea` login as default):
 
-- `method: "create"`
+```bash
-- `owner: "vvzvlad"`, `repo: "gitmost"`
+tea issues create --repo vvzvlad/gitmost --labels feature \
-- `title`, `body`
+  --title '<title>' --description "$(cat body.md)"
-- `labels` — an array of label **IDs** (numbers), *not* names. Resolve a name
+```
-  such as `feature` to its id first with `label_read` (`method: "list"`), then
-  pass e.g. `labels: [<id>]`.
 
-Read issues with `list_issues`, `issue_read`, or `search_issues`. The MCP is
+> Gotcha (tea 0.14.1): the issue body flag is `--description`/`-d`, **not**
-authenticated in-process, so no `tea`/`curl` and no keychain lookup are needed.
+> `--body` — passing `--body` fails with `flag provided but not defined: -body`.
 
 ---
 

CHANGELOG.md

@@ -14,10 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Place several images side by side in a row.** A new "Inline (side by
   side)" alignment mode in the image bubble menu renders consecutive inline
-  images as a row that wraps onto the next line on narrow screens. The row is
+  images as a row that wraps onto the next line on narrow screens. Unlike the
-  centered horizontally by default in modern browsers (CSS `:has()`), falling
+  float modes, text does not wrap around inline images. The mode round-trips
-  back to start-aligned rows in browsers without support. Unlike the float
-  modes, text does not wrap around inline images. The mode round-trips
   losslessly through markdown as `data-align`, like the other alignment
   values.
 
@@ -86,53 +84,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   with the `||text||` input rule; the rendered span blurs until clicked to reveal.
   The mark is preserved losslessly through Markdown export/import (as a raw
   `<span data-spoiler="true">…</span>`) and on public shares. (#259)
-- **Dock the AI chat window into the side menu.** The floating chat window can
-  be pinned to the sidebar — drag it onto the navbar (a drop-zone highlight
-  shows where it lands) or use the new "Dock to sidebar" header button; while
-  docked it fills the sidebar area and follows its live size. "Undock" (or
-  dragging it back out) restores the floating window, a collapsed/absent
-  sidebar falls back to floating, and the docked state survives a reload.
-  (#276, #282)
-- **Hovering commented text shows the comment thread in a tooltip.** Pointing
-  at a highlighted comment mark pops a small card with the author and plain
-  text of the root comment and its replies, so a thread can be skimmed without
-  opening the side panel. The card appears after a short delay (no flicker on a
-  passing glance), skips resolved and text-less threads, and dismisses on
-  scroll or click — clicking a mark still opens the comments panel. (#268,
-  #271)
-- **"Move to trash" button in the temporary-note banner.** Besides "Make
-  permanent", the banner on an open temporary note now also offers to trash the
-  note immediately instead of waiting out its lifetime. It reuses the regular
-  soft-delete path, so the "Page moved to trash" undo toast is the safety net —
-  no confirmation dialog. (#273, #277)
-- **Code-block controls float as an overlay instead of taking a row above the
-  code.** The language selector and copy button now sit in the block's top-right
-  corner, and the selector stays invisible until the block is hovered or the
-  selector is focused, so reading code is chrome-free. In read-only views only
-  the copy button renders. (#275, #278)
-- **The AI agent is told about your page edits between turns.** The server
-  snapshots the open page's Markdown at the end of every agent turn and, on the
-  next turn, injects a unified diff of what changed in between, so the agent
-  knows its earlier copy of the page is stale and builds on the user's edits
-  instead of reverting or overwriting them. The diff is whitespace-normalized
-  (pure formatting churn injects nothing) and size-capped, with a hint to
-  re-read the full page via `getPage` when truncated. (#274, #281)
-- **Stress-accent button (U+0301) in the bubble menu.** Select a vowel and
-  toggle a combining acute accent over it — a Russian-style stress mark. The
-  accent is stored as plain text (no custom mark), so it survives Markdown/HTML
-  export, full-text search and public shares unchanged; the toggle is a single
-  undo step and re-clicking removes the accent. (#270, #280)
-- **Reading position survives a reload.** The editor remembers how far you
-  scrolled in each page (per tab, in `sessionStorage`) and restores that
-  position after an F5 or reopening the document, waiting for the collaborative
-  content to finish laying out first. A URL `#hash` anchor still wins — restore
-  is a no-op then. (#266, #267)
-- **The slash menu finds commands typed in the wrong keyboard layout.** A query
-  typed with the wrong layout active (e.g. `/сщву` for `/code`, or `/cyjcrf`
-  for the Cyrillic «сноска» → Footnote) is additionally remapped ЙЦУКЕН↔QWERTY
-  by physical key position and matched against the commands; genuine Cyrillic
-  search terms keep priority over remapped candidates, and short wrong-layout
-  prefixes match by command title. (#283, #285, #287)
 
 ### Changed
 
@@ -198,25 +149,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   emits a single-use "intentional clear" signal that lets exactly that one empty
   write through the guard, so genuinely emptying a page is persisted while
   accidental empties are blocked. (#248, #251)
-- **Ctrl+Z works again right after using a table menu.** Closing a table
-  row/column menu (grip or chevron) left focus on the menu's portaled target
-  outside the editor, so undo keystrokes went nowhere until you clicked back
-  into a cell. The editor is now refocused after the menu closes — unless you
-  deliberately moved focus to another input or editable (e.g. the page title).
-  (#269, #279)
-- **The AI reindex progress counter no longer freezes at 0.** Right after
-  "Reindex now" the client could read the stale pre-reindex snapshot of an
-  already-indexed workspace (`reindexing=false`, all pages counted) as
-  "finished" and stop polling on the very first tick, leaving the counter
-  frozen until a manual reload. Polling now keeps going until it has actually
-  observed the active run. (#262, #264)
-- **An MCP edit can no longer be silently lost to a duplicate collab document.**
-  When the agent addressed a page by its short slugId, the MCP opened a
-  collaboration document named after that slugId while the web editor always
-  uses the page's canonical UUID — two independent live documents for one page,
-  whose debounced stores clobbered each other. The MCP now resolves every page
-  id to the canonical UUID before opening the collab doc (a UUID input
-  short-circuits locally; a slugId is resolved once and cached). (#260, #265)
 
 ### Security
 

README.md

@@ -104,7 +104,7 @@ community feature, with no enterprise license. Open it from the page header; the
 - ✅ **Page templates** — flag a page as a template and embed its whole content live into other pages; edits to the template propagate to every place it is inserted (whole-page transclusion on top of the existing synced blocks).
 - ✅ **Public-share AI assistant** — anonymous visitors of a shared page can ask the AI agent, scoped strictly to that share's page tree (read-only, share-scoped search), behind a workspace toggle.
 - ✅ **Footnotes** — academic-style footnotes: a numbered superscript reference inline (read it in place via a hover popover), with the note text living as a real, editable block at the bottom of the page; auto-numbered, collaboration-safe, and round-trips through Markdown export/import and the AI agent / MCP.
-- ✅ **Temporary notes** — create a note as temporary and it auto-moves to Trash after a configurable per-workspace lifetime (default 24h) unless made permanent first; create one in a click from the Home screen, any space overview.
+- ✅ **Temporary notes** — mark a note as temporary and it auto-moves to Trash after a configurable per-workspace lifetime (default 24h) unless made permanent first; create one in a click from the Home screen, any space overview, or the space sidebar, with a "Make permanent" rescue banner on the open note.
 
 ### In progress
 
@@ -187,17 +187,14 @@ start the new migrations apply on top of your existing schema (`CREATE EXTENSION
 - Spaces
 - Permissions management
 - Groups
-- Comments (with resolve / re-open and hover tooltips showing the comment text)
+- Comments (with resolve / re-open)
 - Page history
 - Search
 - File attachments
 - Embeds (Airtable, Loom, Miro and more)
 - Translations (10+ languages)
 - Embedded MCP server (`/mcp`)
-- AI agent chat over your wiki (read + write, RAG search, external MCP / web access); the chat window docks into the side menu, and the agent is told about your in-page edits between turns
+- AI agent chat over your wiki (read + write, RAG search, external MCP / web access)
-- Code-block buttons as an overlay, with the language selector revealed on hover
-- Stress-accent button (U+0301) in the bubble menu
-- Reading scroll position restored on reload
 
 ### Screenshots
 

README.ru.md

@@ -105,7 +105,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 - ✅ **Шаблоны страниц** — пометить страницу шаблоном и вставлять её содержимое живой ссылкой в другие страницы; правки шаблона распространяются на все места вставки (whole-page-транслюзия поверх существующих synced-блоков).
 - ✅ **AI-ассистент на публичных шарах** — анонимный зритель расшаренной страницы может спросить AI-агента, который ищет строго по дереву этой шары (read-only, share-scoped поиск), за тумблером воркспейса.
 - ✅ **Сноски** — сноски академического вида: нумерованная ссылка-надстрочник прямо в тексте (читается на месте во всплывающем окне по наведению), а текст сноски живёт реальным редактируемым блоком внизу страницы; авто-нумерация, безопасна для совместного редактирования, переживает экспорт/импорт Markdown и доступна AI-агенту / MCP.
-- ✅ **Временные заметки** — создайте временную заметку, и она автоматически уедет в корзину по истечении настраиваемого срока жизни (по умолчанию 24 ч); создать такую можно в один клик с домашнего экрана, с обзора любого пространства или из сайдбара пространства.
+- ✅ **Временные заметки** — пометьте заметку временной, и она автоматически уедет в корзину по истечении настраиваемого срока жизни воркспейса (по умолчанию 24 ч), если её предварительно не сделать постоянной; создать такую можно в один клик с домашнего экрана, с обзора любого пространства или из сайдбара пространства, а на открытой заметке есть баннер «Сделать постоянной».
 
 ### В процессе
 
@@ -174,18 +174,14 @@ dump/restore, существующий каталог данных переис
 - Пространства (Spaces)
 - Управление правами доступа
 - Группы
-- Комментарии (с резолвом / переоткрытием и всплывающими подсказками с текстом комментария при наведении)
+- Комментарии (с резолвом / переоткрытием)
 - История страниц
 - Поиск
 - Вложения файлов
 - Встраивания (Airtable, Loom, Miro и другие)
 - Переводы (10+ языков)
 - Встроенный MCP-сервер (`/mcp`)
-- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет); окно чата закрепляется в боковом меню, а агент узнаёт о ваших правках страницы между ходами
+- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет)
-- Кнопки код-блока оверлеем, селектор языка появляется при наведении
-- Кнопка «Ударение» (U+0301) в bubble-меню
-- Позиция чтения (прокрутка) восстанавливается после перезагрузки
-- Slash-меню терпимо к неправильной раскладке (ЙЦУКЕН↔QWERTY)
 
 ### Скриншоты
 

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

@@ -100,7 +100,7 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
   });
 
-  it("(a3) restores at most once per mount even if called again", () => {
+  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 to restore synchronously
@@ -111,8 +111,12 @@ describe("useScrollPosition", () => {
     });
     expect(window.scrollTo).toHaveBeenCalledTimes(1);
 
+    // Simulate the browser now being at the restored position.
+    setScrollY(500);
+
     // A second call (e.g. the wiring effect re-running on [showStatic, editor,
-    // restoreScrollPosition]) must NOT scroll again and yank the reader.
+    // restoreScrollPosition]) must NOT scroll again: the redundancy guard sees
+    // the window is already at the target and does nothing.
     act(() => {
       result.current.restoreScrollPosition();
     });
@@ -162,6 +166,84 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).not.toHaveBeenCalled();
   });
 
+  it("(g) does not restore if the reader scrolled (wheel) before restore fires", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}g1`, "500");
+    setScrollHeight(2000); // tall enough to restore synchronously
+
+    const { result } = renderHook(() => useScrollPosition("g1"));
+
+    // The reader shows scroll intent before restore is triggered.
+    act(() => {
+      window.dispatchEvent(new Event("wheel"));
+    });
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    expect(window.scrollTo).not.toHaveBeenCalled();
+  });
+
+  it("(h) aborts an in-flight restore poll when the reader scrolls", () => {
+    vi.useFakeTimers();
+    window.sessionStorage.setItem(`${KEY_PREFIX}h1`, "500");
+    setInnerHeight(800);
+    setScrollHeight(100); // maxScroll = -700: target not reachable yet, so it polls.
+
+    const { result } = renderHook(() => useScrollPosition("h1"));
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled(); // still polling
+
+    // The reader takes over mid-poll: this cancels the in-flight poll.
+    act(() => {
+      window.dispatchEvent(new Event("wheel"));
+    });
+
+    // Content of the page grows tall enough and time passes: the cancelled poll
+    // must NOT resurrect and yank the reader.
+    setScrollHeight(2000);
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled();
+  });
+
+  it("(i) a non-scroll keydown does NOT abort restore", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}i1`, "500");
+    setScrollHeight(2000); // tall enough to restore synchronously
+
+    const { result } = renderHook(() => useScrollPosition("i1"));
+
+    // A non-scroll key (e.g. typing, a shortcut) must NOT count as scroll intent.
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent("keydown", { key: "a" }));
+    });
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    // Restore still happens: the innocuous keypress did not disable it.
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
+  });
+
+  it("(j) a scroll keydown (Space) DOES abort restore", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}j1`, "500");
+    setScrollHeight(2000); // tall enough to restore synchronously
+
+    const { result } = renderHook(() => useScrollPosition("j1"));
+
+    // Space scrolls the page: this is real scroll intent and must abort restore.
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent("keydown", { key: " " }));
+    });
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    expect(window.scrollTo).not.toHaveBeenCalled();
+  });
+
   it("(c) does nothing when nothing is saved or the saved value is <= 0", () => {
     // Nothing saved.
     const a = renderHook(() => useScrollPosition("nope"));

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

@@ -13,6 +13,18 @@ const RESTORE_POLL_MS = 100;
 // "remember where I was reading" feature (self-limiting, no cross-tab leak).
 const STORAGE_PREFIX = "gitmost:scroll-position:";
 
+// Keys that scroll the window. Only these count as scroll intent for keydown;
+// other keys (shortcuts, modifiers, typing) must NOT disable scroll restore.
+const SCROLL_KEYS = new Set([
+  "ArrowUp",
+  "ArrowDown",
+  "PageUp",
+  "PageDown",
+  "Home",
+  "End",
+  " ", // Space (and Shift+Space) scroll the page
+]);
+
 function storageKey(pageId: string): string {
   return `${STORAGE_PREFIX}${pageId}`;
 }
@@ -48,32 +60,41 @@ function writeStorage(pageId: string, scrollY: number): void {
  * Persists and restores the window scroll position per page so a reader keeps
  * their place across a reload (F5) or reopening the document.
  *
- * Returns `restoreScrollPosition`, which the page editor calls once the live
+ * Returns `restoreScrollPosition`, which the page editor calls from two triggers
- * (non-static) content is laid out. The two scroll mechanisms are mutually
+ * (early, while the static/cached content is laid out, and again after the
- * exclusive: if the URL has a `#hash` anchor, the existing anchor-scroll logic
+ * static->live editor swap); it is idempotent, so re-asserting the same target is
- * wins and restore is a no-op.
+ * 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;
 } {
   // CONTRACT: this hook assumes PageEditor REMOUNTS per page — page.tsx renders
   // `<MemoizedFullEditor key={page.id} ...>`, so switching pages creates a fresh
-  // hook instance with fresh refs. These refs latch per-mount and are NOT reset
+  // hook instance with fresh refs. Restore is idempotent and interaction-gated
-  // when `pageId` changes in place (only the effect re-runs on [pageId]). If that
+  // (not single-shot): it may be called from several triggers and re-asserts the
-  // `key={page.id}` is ever removed, restore would silently break on the 2nd page
+  // SAME captured target, which is a no-op once the window is already positioned.
-  // (refs would hold the first page's target / already-restored flag) — in that
+  // The per-mount refs that latch are `initialTargetRef` (the captured target)
-  // case the refs must be reset on a pageId change.
+  // and `userInteractedRef` (the reader has taken over scrolling). They are NOT
+  // reset when `pageId` changes in place (only the effect re-runs on [pageId]).
+  // If that `key={page.id}` is ever removed, restore would silently break on the
+  // 2nd page (refs would hold the first page's target / interaction flag) — in
+  // that case the refs must be reset on a pageId change.
   //
   // The target Y captured synchronously at mount, BEFORE any scroll/visibility
   // handler can overwrite the stored value with a fresh 0 (the page starts
   // scrolled to top on load). `null` means "not yet captured".
   const initialTargetRef = useRef<number | null>(null);
-  // Guards so restore runs at most once per page mount.
+  // Set once the reader shows unambiguous scroll intent; restore must never yank
-  const hasRestoredRef = useRef(false);
+  // a reader who has already started scrolling.
+  const userInteractedRef = useRef(false);
   // Holds the in-flight restore poll timer so the cleanup can cancel it: without
   // 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.
@@ -114,14 +135,43 @@ export function useScrollPosition(pageId: string): {
       }
     };
 
+    // User scroll-intent signals. wheel and touch are unconditional scroll
+    // intent; keydown is filtered to actual scroll keys only (SCROLL_KEYS) so
+    // shortcuts, lone modifiers, and typing do not abort restore. Our own
+    // window.scrollTo does NOT emit these, so restore can never self-abort via
+    // them. Once the reader shows intent we mark it and cancel any in-flight
+    // restore poll so restore can never yank them back. (Scrollbar-drag via
+    // pointer is an accepted small gap — it is not covered here.)
+    const onUserIntent = (event: Event) => {
+      // wheel/touchstart are unambiguous scroll intent; for keydown, only real
+      // scroll keys count — a shortcut or typing must not abort restore.
+      if (
+        event.type === "keydown" &&
+        !SCROLL_KEYS.has((event as KeyboardEvent).key)
+      ) {
+        return;
+      }
+      userInteractedRef.current = true;
+      if (pollTimerRef.current !== null) {
+        window.clearTimeout(pollTimerRef.current);
+        pollTimerRef.current = null;
+      }
+    };
+
     window.addEventListener("scroll", onScroll, { passive: true });
     window.addEventListener("pagehide", onPageHide);
     document.addEventListener("visibilitychange", onVisibilityChange);
+    window.addEventListener("wheel", onUserIntent, { passive: true });
+    window.addEventListener("touchstart", onUserIntent, { passive: true });
+    window.addEventListener("keydown", onUserIntent);
 
     return () => {
       window.removeEventListener("scroll", onScroll);
       window.removeEventListener("pagehide", onPageHide);
       document.removeEventListener("visibilitychange", onVisibilityChange);
+      window.removeEventListener("wheel", onUserIntent);
+      window.removeEventListener("touchstart", onUserIntent);
+      window.removeEventListener("keydown", onUserIntent);
       if (throttleTimer !== null) {
         window.clearTimeout(throttleTimer);
         throttleTimer = null;
@@ -137,9 +187,8 @@ export function useScrollPosition(pageId: string): {
   }, [pageId]);
 
   const restoreScrollPosition = useCallback(() => {
-    // Run at most once per page mount.
+    // The reader took over — never yank them back.
-    if (hasRestoredRef.current) return;
+    if (userInteractedRef.current) return;
-    hasRestoredRef.current = true;
 
     // Anchor priority: a `#hash` in the URL is handled by useEditorScroll.
     if (window.location.hash) return;
@@ -148,9 +197,26 @@ export function useScrollPosition(pageId: string): {
     // Nothing meaningful to restore to.
     if (targetY <= 0) return;
 
-    const start = Date.now();
+    // 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;
+    }
+
+    // Share one timeout budget across re-triggers instead of restarting it.
+    if (restoreStartRef.current === null) {
+      restoreStartRef.current = Date.now();
+    }
+    const start = restoreStartRef.current;
 
     const tryRestore = () => {
+      // Bail mid-poll if the reader started scrolling while we were waiting.
+      if (userInteractedRef.current) {
+        pollTimerRef.current = null;
+        return;
+      }
+
       const maxScroll =
         document.documentElement.scrollHeight - window.innerHeight;
       const timedOut = Date.now() - start >= MAX_RESTORE_WAIT_MS;
@@ -158,10 +224,12 @@ export function useScrollPosition(pageId: string): {
       // 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) {
-        window.scrollTo({
+        const top = Math.min(targetY, Math.max(maxScroll, 0));
-          top: Math.min(targetY, Math.max(maxScroll, 0)),
+        // Redundancy guard: re-asserting the SAME target when already positioned
-          behavior: "auto",
+        // 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" });
+        }
         pollTimerRef.current = null;
         return;
       }

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

@@ -2,6 +2,7 @@ import "@/features/editor/styles/index.css";
 import React, {
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -482,8 +483,17 @@ export default function PageEditor({
     }
   }, [yjsConnectionStatus, isSynced]);
 
-  // Restore the saved reading position once the live content is laid out.
+  // Restore as early as the static (cached) content is laid out, before paint,
-  useEffect(() => {
+  // 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]);
+
+  // 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/styles/media.css

@@ -71,22 +71,3 @@
   }
 }
 
-/* Inline image rows (#284): center the anonymous line boxes formed by
-   consecutive [data-image-align="inline"] node-view containers. A row has no
-   DOM wrapper of its own, so its horizontal placement is controlled by the
-   text-align of the nearest block ancestor (the editor root or a nested
-   block container: blockquote, callout, list item, table cell, details).
-   Centering is enabled only in containers that actually hold an inline
-   image (:has), and every other child of such a container gets its default
-   alignment back so ordinary text is unaffected. Explicit per-block
-   alignment from the toolbar is an inline style and still wins. Browsers
-   without :has() degrade to left-pinned rows. */
-.ProseMirror:has(> [data-image-align="inline"]),
-.ProseMirror :has(> [data-image-align="inline"]) {
-  text-align: center;
-}
-
-.ProseMirror:has(> [data-image-align="inline"]) > :not([data-image-align="inline"]),
-.ProseMirror :has(> [data-image-align="inline"]) > :not([data-image-align="inline"]) {
-  text-align: start;
-}

apps/server/src/core/ai-chat/ai-chat.prompt.spec.ts

@@ -303,11 +303,6 @@ describe('buildSystemPrompt page-changed note (#274)', () => {
     expect(prompt).toContain(NOTE_MARKER);
     expect(prompt).toContain('-old line');
     expect(prompt).toContain('+new line');
-    // Strengthened note (#274): instructs a fresh re-read via getPage and steers
-    // the agent toward small, targeted edits instead of a full-page overwrite.
-    expect(prompt).toContain('getPage');
-    expect(prompt.toLowerCase()).toContain('targeted');
-    expect(prompt).toContain('editPageText');
     // Inside the safety sandwich: the trailing SAFETY block follows the note.
     expect(prompt.lastIndexOf(SAFETY_MARKER)).toBeGreaterThan(
       prompt.indexOf(NOTE_MARKER),

apps/server/src/core/ai-chat/ai-chat.prompt.ts

@@ -85,17 +85,11 @@ const INTERRUPT_NOTE =
 const PAGE_CHANGED_NOTE =
   'NOTE: The user edited the open page AFTER your last response in this ' +
   'conversation, so any copy of that page you produced or remember from earlier ' +
-  'is now STALE and must not be reused. Before you edit the page, you MUST first ' +
+  'is now STALE. The unified diff below shows exactly what changed since you last ' +
-  're-read its current content with the getPage tool and base your work on that ' +
+  'spoke (lines starting with "-" were removed, "+" were added) and is the source ' +
-  'live version — never on your earlier copy or on the transcript. The unified ' +
+  'of truth. Preserve the user\'s edits: build on the current page, do not revert ' +
-  'diff below shows exactly what the user changed since you last spoke (lines ' +
+  'or overwrite their changes. If you need the full up-to-date page, re-read it ' +
-  'starting with "-" were removed, "+" were added) and is the source of truth. ' +
+  'with the getPage tool before editing.';
-  'Preserve every one of the user\'s edits: make the smallest change that ' +
-  'satisfies the request using the targeted edit tools (editPageText, patchNode, ' +
-  'insertNode, deleteNode) rather than replacing the whole page, and do not ' +
-  'revert, drop, or overwrite anything the user changed. If a full rewrite is ' +
-  'truly unavoidable, start from the current getPage content and carry over all ' +
-  'of the user\'s edits.';
 
 /**
  * Sanitize a value interpolated into a prompt XML-ish attribute (e.g.

apps/server/src/core/ai-chat/ai-chat.service.spec.ts

@@ -356,32 +356,6 @@ describe('flushAssistant', () => {
     expect(flushed.toolCalls).not.toBeNull();
     expect(flushed.metadata.error).toBe('boom');
   });
-
-  // #274 observability: the page-change diff the agent saw this turn is persisted
-  // to metadata.pageChanged when a non-empty diff was injected, and omitted when
-  // the diff is empty/whitespace or the arg is not supplied.
-  it('persists metadata.pageChanged when a non-empty diff was injected', () => {
-    const f = flushAssistant([], '', 'completed', {
-      pageChanged: { title: 'Doc', diff: '@@ -1 +1 @@\n-old\n+new' },
-    });
-    expect(f.metadata.pageChanged).toEqual({
-      title: 'Doc',
-      diff: '@@ -1 +1 @@\n-old\n+new',
-    });
-  });
-
-  it('omits metadata.pageChanged for an empty/whitespace diff or a missing arg', () => {
-    const whitespace = flushAssistant([], '', 'completed', {
-      pageChanged: { title: 'Doc', diff: '   \n  ' },
-    });
-    expect('pageChanged' in whitespace.metadata).toBe(false);
-
-    const nullArg = flushAssistant([], '', 'completed', { pageChanged: null });
-    expect('pageChanged' in nullArg.metadata).toBe(false);
-
-    const omitted = flushAssistant([], '', 'streaming');
-    expect('pageChanged' in omitted.metadata).toBe(false);
-  });
 });
 
 /**

apps/server/src/core/ai-chat/ai-chat.service.ts

@@ -685,7 +685,7 @@ export class AiChatService implements OnModuleInit {
     // no-op (guarded below) so the turn still streams to the user.
     let assistantId: string | undefined;
     try {
-      const seed = flushAssistant([], '', 'streaming', { pageChanged });
+      const seed = flushAssistant([], '', 'streaming');
       const seeded = await this.aiChatMessageRepo.insert({
         chatId,
         workspaceId: workspace.id,
@@ -720,7 +720,7 @@ export class AiChatService implements OnModuleInit {
         await this.aiChatMessageRepo.update(
           assistantId,
           workspace.id,
-          flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
+          flushAssistant(capturedSteps, '', 'streaming'),
           { onlyIfStreaming: true },
         );
       } catch (err) {
@@ -860,7 +860,6 @@ export class AiChatService implements OnModuleInit {
               // resolved from the admin-configured provider settings (in
               // closure scope here). Omitted/0 = no limit.
               maxContextTokens: resolved?.chatContextWindow,
-              pageChanged,
             }),
           );
           // Lifecycle: release the external MCP clients leased for this turn.
@@ -912,7 +911,6 @@ export class AiChatService implements OnModuleInit {
           await finalizeAssistant(
             flushAssistant(capturedSteps, inProgressText, 'error', {
               error: errorText,
-              pageChanged,
             }),
           );
           await closeExternalClients();
@@ -942,9 +940,7 @@ export class AiChatService implements OnModuleInit {
               `steps=${steps.length}`,
           );
           await finalizeAssistant(
-            flushAssistant(capturedSteps, inProgressText, 'aborted', {
+            flushAssistant(capturedSteps, inProgressText, 'aborted'),
-              pageChanged,
-            }),
           );
           await closeExternalClients();
           // Advance the page snapshot even on abort (#274): an agent edit that
@@ -1510,7 +1506,6 @@ export function flushAssistant(
     contextTokens?: number;
     maxContextTokens?: number;
     error?: string;
-    pageChanged?: { title: string; diff: string } | null;
   },
 ): AssistantFlush {
   const finished = capturedSteps ?? [];
@@ -1543,15 +1538,6 @@ export function flushAssistant(
   if (extra?.maxContextTokens)
     metadata.maxContextTokens = extra.maxContextTokens;
   if (extra?.error) metadata.error = extra.error;
-  // Persist the page-change diff the agent saw this turn (#274 observability),
-  // so history / the Markdown export can show what the user changed. Only when
-  // a non-empty diff was actually injected into the prompt this turn.
-  if (extra?.pageChanged && extra.pageChanged.diff?.trim().length) {
-    metadata.pageChanged = {
-      title: extra.pageChanged.title,
-      diff: extra.pageChanged.diff,
-    };
-  }
 
   return {
     content: stepsText + trailing,

apps/server/src/core/ai-chat/chat-markdown.util.spec.ts

@@ -269,168 +269,6 @@ describe('buildChatMarkdown (server) — structure', () => {
     expect(md).toContain('**⚠️ Error:** 401: Unauthorized');
   });
 
-  // #274 observability: an assistant row whose turn started with a user edit to
-  // the open page carries metadata.pageChanged = { title, diff }; the export
-  // renders the diff the agent saw, before the message body.
-  it('renders the persisted page-change diff block for an assistant row', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: { title: 'Doc', diff: '@@ -1 +1 @@\n-old\n+new' },
-          } as never,
-        }),
-      ],
-    });
-    expect(md).toContain(
-      'The user edited this page before this turn; the diff the agent saw:',
-    );
-    expect(md).toContain('("Doc")');
-    expect(md).toContain('-old');
-    expect(md).toContain('+new');
-    // The diff sits before the message body (chronological: change, then reply).
-    expect(md.indexOf('-old')).toBeLessThan(md.indexOf('answer'));
-  });
-
-  it('does not render the page-change block when metadata.pageChanged is absent', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [row({ role: 'assistant', content: 'answer' })],
-    });
-    expect(md).not.toContain(
-      'The user edited this page before this turn; the diff the agent saw:',
-    );
-  });
-
-  // #288 F1/F2: an empty page title must render the BARE heading with no
-  // `("…")` suffix (the `pc.title ? … : …` false branch).
-  it('renders the page-change heading with no title suffix when title is empty', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: { title: '', diff: '@@ -1 +1 @@\n-old\n+new' },
-          } as never,
-        }),
-      ],
-    });
-    // Bare heading, single line, no parenthesized title.
-    expect(md).toContain(
-      '> **📝 The user edited this page before this turn; the diff the agent saw:**',
-    );
-    expect(md).not.toContain('("');
-    expect(md).toContain('-old');
-  });
-
-  // #288 F1: the page title is UNTRUSTED cross-user data, so a title carrying a
-  // newline / backtick / `"` / `<`/`>` must be neutralized by escapeAttr before
-  // it is interpolated into the `> **…**` blockquote heading — otherwise it
-  // could break the blockquote onto multiple lines or inject markup/HTML into
-  // the downloaded .md. escapeAttr strips `<>"` and collapses whitespace runs to
-  // a single space, so `Ev"il\n> `x` <b>` becomes ``Evil `x` b``.
-  it('escapes an untrusted page title in the page-change heading', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: {
-              title: 'Ev"il\n> `x` <b>',
-              diff: '@@ -1 +1 @@\n-old\n+new',
-            },
-          } as never,
-        }),
-      ],
-    });
-    // The heading stays a single blockquote line with the escaped title.
-    expect(md).toContain(
-      '> **📝 The user edited this page before this turn; the diff the agent saw: ("Evil `x` b")**',
-    );
-    // No raw attribute/markup breakers survived from the title.
-    expect(md).not.toContain('Ev"il');
-    expect(md).not.toContain('<b>');
-  });
-
-  // #288 review F1: escapeAttr ALONE is insufficient for this MARKDOWN sink —
-  // link/image syntax survives it. A cross-user title with `![x](url)` /
-  // `[phish](url)` must NOT become a working remote image or clickable link in
-  // the downloaded .md; markdownHeadingSafe backslash-escapes `[`/`]` so both are
-  // inert. (Non-vacuous: fails against the escapeAttr-only version, which left
-  // `](https://` intact.)
-  it('neutralizes markdown link/image syntax in an untrusted page title', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: {
-              title:
-                '![x](https://attacker.example/t.png) and [click](https://phish.example)',
-              diff: '@@ -1 +1 @@\n-old\n+new',
-            },
-          } as never,
-        }),
-      ],
-    });
-    // No WORKING image/link syntax survives — the `[…]` sits escaped as `\[…\]`,
-    // so the unescaped `![x](` image and `[click](` link markers are gone. (We
-    // deliberately do NOT assert `not.toContain('](https://')`: after escaping the
-    // literal `\](https://` still contains `](https://` as a raw substring — that
-    // check would false-fail even though the link is inert.)
-    expect(md).not.toContain('![x](');
-    expect(md).not.toContain('[click](');
-    // The brackets are backslash-escaped, so `[text](url)`/`![text](url)` are inert.
-    expect(md).toContain('\\[');
-    expect(md).toContain('\\]');
-    // The heading stays a SINGLE blockquote line (no newline injected).
-    const headingLine = md
-      .split('\n')
-      .find((l) => l.includes('the diff the agent saw:'));
-    expect(headingLine).toBeDefined();
-    expect(headingLine).toContain('\\[x\\]');
-    expect(headingLine).toContain('\\[click\\]');
-  });
-
-  // #288 internal review Finding 2: a NON-empty title made up entirely of
-  // escapeAttr breakers (`<>"`) escapes to '' — the ternary must then fall to the
-  // BARE heading with NO `("…")` suffix. Locks the ternary-on-escaped-value
-  // behavior (distinct from the empty-string input test above).
-  it('renders the bare heading for a title that escapes to empty', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: { title: '<>"', diff: '@@ -1 +1 @@\n-old\n+new' },
-          } as never,
-        }),
-      ],
-    });
-    expect(md).toContain(
-      '> **📝 The user edited this page before this turn; the diff the agent saw:**',
-    );
-    expect(md).not.toContain('("');
-    expect(md).toContain('-old');
-  });
-
   it('escapes embedded triple-backtick fences with a longer delimiter', () => {
     const md = buildChatMarkdown({
       title: 'T',

apps/server/src/core/ai-chat/chat-markdown.util.ts

@@ -15,7 +15,6 @@
  */
 
 import type { AiChatMessage } from '@docmost/db/types/entity.types';
-import { escapeAttr } from './ai-chat.prompt';
 
 /** Supported export label languages. Defaults to English. */
 export type ExportLang = 'en' | 'ru';
@@ -64,7 +63,6 @@ const LABELS: Record<
     tools: Record<string, string>;
     ranTool: (name: string) => string;
     stillGenerating: string;
-    pageEditedByUser: string;
   }
 > = {
   en: {
@@ -85,8 +83,6 @@ const LABELS: Record<
     ranTool: (name) => `Ran tool ${name}`,
     stillGenerating:
       'This message is still being generated — the export captured a partial, in-progress response.',
-    pageEditedByUser:
-      'The user edited this page before this turn; the diff the agent saw:',
   },
   ru: {
     untitled: 'Без названия',
@@ -106,29 +102,9 @@ const LABELS: Record<
     ranTool: (name) => `Выполнил инструмент ${name}`,
     stillGenerating:
       'Это сообщение всё ещё генерируется — экспорт захватил частичный, незавершённый ответ.',
-    pageEditedByUser:
-      'Пользователь изменил страницу перед этим ходом; дифф, который видел агент:',
   },
 };
 
-/**
- * Make an untrusted title safe to interpolate into a Markdown blockquote
- * HEADING. escapeAttr() neutralizes the XML/HTML breakers (`<` `>` `"`) and
- * collapses whitespace for the PROMPT sink (`page="…"`), but this export sink is
- * MARKDOWN — link/image syntax survives escapeAttr. So additionally backslash-
- * escape `[` and `]`: that disables both `[text](url)` links and `![text](url)`
- * images, so a cross-user title like `![x](http://evil)` or `[phish](http://evil)`
- * cannot inject a remote (auto-loading) image or a clickable link into the
- * downloaded .md disguised as a trusted system annotation. A bare `(url)` with no
- * preceding `[]` is inert Markdown, so brackets are the only security-critical
- * characters here. (We leave backticks to escapeAttr's whitespace pass — a title
- * shown as inline code cannot escape the blockquote line or load a resource, so
- * it is not a security concern for this sink.)
- */
-function markdownHeadingSafe(title: string): string {
-  return escapeAttr(title).replace(/[[\]]/g, (m) => `\\${m}`);
-}
-
 /** True for AI SDK tool parts (static `tool-*` or `dynamic-tool`). */
 function isToolPart(type: string): boolean {
   return type.startsWith('tool-') || type === 'dynamic-tool';
@@ -232,23 +208,6 @@ function rowParts(row: AiChatMessage): ExportPart[] {
     : [{ type: 'text', text: row.content ?? '' }];
 }
 
-/** The persisted page-change diff the agent saw this turn (#274), when any. */
-function pageChangedOf(
-  row: AiChatMessage,
-): { title: string; diff: string } | undefined {
-  const meta = (row.metadata ?? {}) as {
-    pageChanged?: { title?: string; diff?: string };
-  };
-  const pc = meta.pageChanged;
-  if (pc && typeof pc.diff === 'string' && pc.diff.trim().length > 0) {
-    return {
-      title: typeof pc.title === 'string' ? pc.title : '',
-      diff: pc.diff,
-    };
-  }
-  return undefined;
-}
-
 /**
  * Serialize a chat to a Markdown string from its persisted rows. Source = DB
  * ONLY (no live client state). A row whose `status` is still 'streaming' is an
@@ -307,26 +266,6 @@ export function buildChatMarkdown(args: {
       blocks.push(`<!-- ${iso} -->`);
     }
 
-    // Page-change observability (#274): show the diff the agent saw at the start
-    // of this turn, before its response, so the export reflects the stale-page
-    // warning the model received.
-    const pc = pageChangedOf(row);
-    if (pc) {
-      // The page title is UNTRUSTED cross-user data (a collaborative page's title
-      // controllable by another user). escapeAttr() alone (the prompt sink) is
-      // INSUFFICIENT here: this is a MARKDOWN sink, so we neutralize link/image
-      // syntax too (backslash-escaping `[`/`]`) before interpolating it into this
-      // `> **…**` blockquote heading — otherwise `![x](url)` / `[phish](url)` would
-      // inject a remote image or clickable link into the downloaded .md. An
-      // all-`<>"` title escapes to empty and correctly falls to the bare heading.
-      // The diff body is already safe via fence(). (#288 review F1.)
-      const safeTitle = markdownHeadingSafe(pc.title);
-      const heading = safeTitle
-        ? `${L.pageEditedByUser} ("${safeTitle}")`
-        : L.pageEditedByUser;
-      blocks.push(`> **📝 ${heading}**\n\n${fence(pc.diff, 'diff')}`);
-    }
-
     blocks.push(...renderMessageParts(rowParts(row), lang));
 
     // A still-'streaming' row is an interrupted/in-progress turn captured by the

packages/editor-ext/src/lib/image/image.ts

@@ -449,9 +449,7 @@ export function applyAlignment(container: HTMLElement, align: string) {
     // the next line when the viewport is narrow. The right/bottom padding
     // provides the gap between images in a row and between wrapped rows;
     // vertical-align: top keeps rows of different-height images aligned by
-    // their top edge. Horizontal centering of the whole row is handled by the
+    // their top edge.
-    // client stylesheet (media.css) via a :has() rule on the parent block
-    // container, since the row has no wrapper element of its own.
     container.style.display = "inline-block";
     container.style.verticalAlign = "top";
     container.style.padding = "0 10px 10px 0";