fix(#370): thread trx into addPageWatchers (F7 self-deadlock) + restore contributors on commit-failure (F8) + assert the lock (F9) (review round 2)

The round-1 F3 fix (wrapping the processor's find+save in a locked tx) itself
introduced two regressions:

F7 [CRITICAL] addPageWatchers ran WITHOUT trx inside the tx holding FOR UPDATE on
pages[pageId]. The watcher insert's FK check takes FOR KEY SHARE on the same row,
but on a DIFFERENT pool connection — a true self-deadlock (our tx connection sits
idle-in-transaction awaiting the JS await, the insert connection blocks on the
lock). Now passes trx (addPageWatchers already accepts it and routes it through
insertMany), so the FK lock is taken on the connection that already holds FOR
UPDATE — no self-conflict.

F8 [WARNING] popContributors is a destructive Redis SPOP; the inner catch only
restores on a throw INSIDE the callback. A COMMIT failure throws OUTSIDE it,
rolling the snapshot back while the pop is gone → a retry writes an unattributed
version. Now tracks the popped set and restores it in an outer catch (idempotent
SADD), leaving BullMQ to retry with attribution intact.

F9 [WARNING] The spec asserted saveHistory args with a loosened objectContaining
that stopped verifying trx, and never pinned withLock/trx on findById or the trx
on addPageWatchers — which is exactly why F7 slipped. Restored the exact
saveHistory(trx) assertion and added findById({withLock,trx}) + addPageWatchers
trx assertions (the latter would have caught F7), plus a commit-failure test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -12,6 +12,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Save intentional page versions.** Press `Cmd/Ctrl+S` (or use the page menu)
+  to save a named version of a page. The history panel now distinguishes
+  intentional versions (a "Saved" / "Agent version" badge) from automatic
+  snapshots, dims autosaves, and offers an "Only versions" filter. Automatic
+  snapshots switched from a fixed interval to a trailing idle-flush with a
+  max-wait ceiling, and a boundary snapshot is pinned whenever the editing source
+  changes (e.g. a person's edits followed by the AI agent). (#370)
+
 - **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

apps/client/public/locales/en-US/translation.json

@@ -1385,5 +1385,14 @@
   "The commented text changed since this suggestion was made; it was not applied.": "The commented text changed since this suggestion was made; it was not applied.",
   "Dismiss": "Dismiss",
   "Suggestion dismissed": "Suggestion dismissed",
-  "Failed to dismiss suggestion": "Failed to dismiss suggestion"
+  "Failed to dismiss suggestion": "Failed to dismiss suggestion",
+  "Save version": "Save version",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Version saved",
+  "Already saved as the latest version": "Already saved as the latest version",
+  "Agent version": "Agent version",
+  "Boundary": "Boundary",
+  "Autosave": "Autosave",
+  "Only versions": "Only versions",
+  "No saved versions yet.": "No saved versions yet."
 }

apps/client/public/locales/ru-RU/translation.json

@@ -1248,5 +1248,14 @@
   "The commented text changed since this suggestion was made; it was not applied.": "Прокомментированный текст изменился после создания предложения; оно не было применено.",
   "Dismiss": "Не применять",
   "Suggestion dismissed": "Предложение отклонено",
-  "Failed to dismiss suggestion": "Не удалось отклонить предложение"
+  "Failed to dismiss suggestion": "Не удалось отклонить предложение",
+  "Save version": "Сохранить версию",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Версия сохранена",
+  "Already saved as the latest version": "Уже сохранено как последняя версия",
+  "Agent version": "Версия агента",
+  "Boundary": "Граница",
+  "Autosave": "Автосейв",
+  "Only versions": "Только версии",
+  "No saved versions yet.": "Пока нет сохранённых версий."
 }

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -1,10 +1,19 @@
 import { atom } from "jotai";
 import { Editor } from "@tiptap/core";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 
 export const pageEditorAtom = atom<Editor | null>(null);
 
+// #370 — the active page's collab provider, published by the page editor so the
+// header menu can emit the "save-version" stateless signal (Cmd+S / button).
+// Null when the page is read-only / collab isn't connected. A typed initial
+// value (rather than an explicit generic) keeps jotai's overload resolution on
+// the writable PrimitiveAtom branch.
+const initialCollabProvider: HocuspocusProvider | null = null;
+export const collabProviderAtom = atom(initialCollabProvider);
+
 export const titleEditorAtom = atom<Editor | null>(null);
 
 export const readOnlyEditorAtom = atom<Editor | null>(null);

apps/client/src/features/editor/extensions/extensions.ts

@@ -45,7 +45,6 @@ import {
   TiptapPdf,
   PageBreak,
   SearchAndReplace,
-  MultiCursor,
   Mention,
   TableDndExtension,
   TableHandleCommandsExtension,
@@ -448,10 +447,6 @@ export const mainExtensions = [
       };
     },
   }).configure(),
-  // Multi-cursor editing (MVP / Variant A): select-all-occurrences + type into
-  // all at once. Does not depend on collaboration, so it lives in mainExtensions
-  // (available in both the plain and collaborative editors).
-  MultiCursor,
   Columns,
   Column,
   AutoJoiner.configure({

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

@@ -31,11 +31,18 @@ import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
+  collabProviderAtom,
   currentPageEditModeAtom,
   dictationAvailabilityAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { notifications } from "@mantine/notifications";
+import {
+  VERSION_SAVED_MESSAGE_TYPE,
+  type VersionSavedMessage,
+  saveVersionPending,
+} from "@/features/page-history/version-messages";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
   activeCommentIdAtom,
@@ -123,6 +130,7 @@ export default function PageEditor({
 
   const [currentUser] = useAtom(currentUserAtom);
   const [, setEditor] = useAtom(pageEditorAtom);
+  const setCollabProvider = useSetAtom(collabProviderAtom);
   const [, setAsideState] = useAtom(asideStateAtom);
   const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
@@ -180,6 +188,24 @@ export default function PageEditor({
       const onStatelessHandler = ({ payload }: onStatelessParameters) => {
         try {
           const message = JSON.parse(payload);
+          // #370 — a version was saved somewhere; live-refresh the history panel
+          // on every client. Only the client that pressed Save (tracked by the
+          // module-level flag) shows the confirmation toast.
+          if (message?.type === VERSION_SAVED_MESSAGE_TYPE) {
+            const versionMsg = message as VersionSavedMessage;
+            queryClient.invalidateQueries({
+              queryKey: ["page-history-list"],
+            });
+            if (saveVersionPending.current) {
+              saveVersionPending.current = false;
+              notifications.show({
+                message: versionMsg.alreadySaved
+                  ? t("Already saved as the latest version")
+                  : t("Version saved"),
+              });
+            }
+            return;
+          }
           if (message?.type !== "page.updated" || !message.updatedAt) return;
           const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
           if (pageData) {
@@ -237,12 +263,16 @@ export default function PageEditor({
 
       local.on("synced", onLocalSyncedHandler);
       providersRef.current = { socket, local, remote };
+      // #370 — publish the provider so the header menu can emit save-version.
+      setCollabProvider(remote);
       setProvidersReady(true);
     } else {
+      setCollabProvider(providersRef.current.remote);
       setProvidersReady(true);
     }
     // Only destroy on final unmount
     return () => {
+      setCollabProvider(null);
       providersRef.current?.socket.destroy();
       providersRef.current?.remote.destroy();
       providersRef.current?.local.destroy();

apps/client/src/features/editor/styles/index.css

@@ -1,6 +1,5 @@
 @import "./core.css";
 @import "./collaboration.css";
-@import "./multi-cursor.css";
 @import "./task-list.css";
 @import "./placeholder.css";
 @import "./drag-handle.css";

apps/client/src/features/editor/styles/multi-cursor.css

@@ -1,60 +0,0 @@
-/*
- * Multi-cursor (issue #196). Deliberately DISTINCT from the collaboration
- * carets (collaboration.css) so a user never confuses their own multi-cursors
- * with a co-author's caret: solid accent-blue carets + a translucent blue
- * range highlight, versus the thin dark collaboration caret with a name label.
- */
-
-/* A secondary caret rendered as a Decoration.widget at each cursor position. */
-.multi-cursor__caret {
-    position: relative;
-    display: inline-block;
-    width: 0;
-    height: 1em;
-    vertical-align: text-bottom;
-    pointer-events: none;
-}
-
-.multi-cursor__caret::after {
-    content: "";
-    position: absolute;
-    left: -1px;
-    top: 0;
-    bottom: 0;
-    width: 2px;
-    background: #2b6cb0;
-    animation: multi-cursor-blink 1s steps(1) infinite;
-}
-
-/* Optional label class reserved for future per-cursor annotations. */
-.multi-cursor__label {
-    position: absolute;
-    top: -1.4em;
-    left: -1px;
-    font-size: 0.7rem;
-    line-height: normal;
-    padding: 0.05rem 0.25rem;
-    border-radius: 3px 3px 3px 0;
-    background: #2b6cb0;
-    color: #fff;
-    white-space: nowrap;
-    user-select: none;
-    pointer-events: none;
-}
-
-/* Inline highlight for a multi-cursor RANGE (from < to). */
-.multi-cursor__selection {
-    background: rgba(43, 108, 176, 0.28);
-    border-radius: 2px;
-}
-
-@keyframes multi-cursor-blink {
-    0%,
-    50% {
-        opacity: 1;
-    }
-    51%,
-    100% {
-        opacity: 0;
-    }
-}

apps/client/src/features/page-history/components/history-item.tsx

@@ -1,4 +1,11 @@
-import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
+import {
+  Text,
+  Group,
+  UnstyledButton,
+  Avatar,
+  Tooltip,
+  Badge,
+} from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import { formattedDate } from "@/lib/time";
@@ -7,36 +14,59 @@ import clsx from "clsx";
 import { IPageHistory } from "@/features/page-history/types/page.types";
 import { memo, useCallback } from "react";
 import { useSetAtom } from "jotai";
+import { useTranslation } from "react-i18next";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
 
 const MAX_VISIBLE_AVATARS = 5;
 
+/**
+ * #370 — map a snapshot's intentionality tier to its badge. `version: true`
+ * marks the intentional points (manual / agent); autosaves (boundary / idle /
+ * legacy null) are non-versions and get dimmed in the list.
+ */
+type HistoryKindMeta = { labelKey: string; color: string; version: boolean };
+export function historyKindMeta(kind?: string | null): HistoryKindMeta {
+  switch (kind) {
+    case "manual":
+      return { labelKey: "Saved", color: "blue", version: true };
+    case "agent":
+      return { labelKey: "Agent version", color: "violet", version: true };
+    case "boundary":
+      return { labelKey: "Boundary", color: "gray", version: false };
+    default: // "idle" | null | undefined (legacy autosave)
+      return { labelKey: "Autosave", color: "gray", version: false };
+  }
+}
+
 interface HistoryItemProps {
   historyItem: IPageHistory;
-  index: number;
-  onSelect: (id: string, index: number) => void;
-  onHover?: (id: string, index: number) => void;
+  // The previous snapshot for diff/restore is resolved by id from the FULL list
+  // in the parent (resolvePrevSnapshotId), so the item only needs to report its
+  // own id — never a list index (which would be the filtered-view index).
+  onSelect: (id: string) => void;
+  onHover?: (id: string) => void;
   onHoverEnd?: () => void;
   isActive: boolean;
 }
 
 const HistoryItem = memo(function HistoryItem({
   historyItem,
-  index,
   onSelect,
   onHover,
   onHoverEnd,
   isActive,
 }: HistoryItemProps) {
   const setHistoryModalOpen = useSetAtom(historyAtoms);
+  const { t } = useTranslation();
+  const kindMeta = historyKindMeta(historyItem.kind);
 
   const handleClick = useCallback(() => {
-    onSelect(historyItem.id, index);
-  }, [onSelect, historyItem.id, index]);
+    onSelect(historyItem.id);
+  }, [onSelect, historyItem.id]);
 
   const handleMouseEnter = useCallback(() => {
-    onHover?.(historyItem.id, index);
-  }, [onHover, historyItem.id, index]);
+    onHover?.(historyItem.id);
+  }, [onHover, historyItem.id]);
 
   const contributors = historyItem.contributors;
   const hasContributors = contributors && contributors.length > 0;
@@ -49,8 +79,20 @@ const HistoryItem = memo(function HistoryItem({
       onMouseEnter={handleMouseEnter}
       onMouseLeave={onHoverEnd}
       className={clsx(classes.history, { [classes.active]: isActive })}
+      // #370 — dim autosnapshots so intentional versions stand out.
+      style={{ opacity: kindMeta.version ? 1 : 0.55 }}
     >
-      <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+      <Group gap={6} wrap="nowrap" justify="space-between">
+        <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+        <Badge
+          size="xs"
+          radius="sm"
+          variant={kindMeta.version ? "filled" : "light"}
+          color={kindMeta.color}
+        >
+          {t(kindMeta.labelKey)}
+        </Badge>
+      </Group>
 
       <Group gap={6} wrap="nowrap" mt={4}>
         {hasContributors ? (

apps/client/src/features/page-history/components/history-list.tsx

@@ -9,7 +9,7 @@ import {
   historyAtoms,
 } from "@/features/page-history/atoms/history-atoms";
 import { useAtom, useSetAtom } from "jotai";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   Button,
   ScrollArea,
@@ -17,9 +17,12 @@ import {
   Divider,
   Loader,
   Center,
+  Switch,
+  Text,
 } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import { useHistoryRestore } from "@/features/page-history/hooks";
+import { resolvePrevSnapshotId } from "@/features/page-history/utils/resolve-prev-snapshot";
 
 const PREFETCH_DELAY_MS = 150;
 
@@ -47,6 +50,23 @@ function HistoryList({ pageId }: Props) {
     [pageHistoryData],
   );
 
+  // #370 — "only versions" filter: hide autosnapshots (idle/boundary/legacy
+  // null), keep only intentional points (manual/agent). Filtering is over the
+  // already-loaded pages; the diff/restore still targets the true previous
+  // snapshot, so items carry their index within the FULL list.
+  const [onlyVersions, setOnlyVersions] = useState(false);
+  const isVersion = useCallback(
+    (kind?: string | null) => kind === "manual" || kind === "agent",
+    [],
+  );
+  const visibleItems = useMemo(
+    () =>
+      onlyVersions
+        ? historyItems.filter((item) => isVersion(item.kind))
+        : historyItems,
+    [historyItems, onlyVersions, isVersion],
+  );
+
   const loadMoreRef = useRef<HTMLDivElement>(null);
   const prefetchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -60,11 +80,13 @@ function HistoryList({ pageId }: Props) {
   }, []);
 
   const handleHover = useCallback(
-    (historyId: string, index: number) => {
+    (historyId: string) => {
       clearPrefetchTimeout();
       prefetchTimeoutRef.current = setTimeout(() => {
         prefetchPageHistory(historyId);
-        const prevId = historyItems[index + 1]?.id;
+        // The true previous snapshot in the FULL list (not the previous visible
+        // one under the "only versions" filter).
+        const prevId = resolvePrevSnapshotId(historyItems, historyId);
         if (prevId) {
           prefetchPageHistory(prevId);
         }
@@ -78,9 +100,11 @@ function HistoryList({ pageId }: Props) {
   }, [clearPrefetchTimeout]);
 
   const handleSelect = useCallback(
-    (id: string, index: number) => {
+    (id: string) => {
       setActiveHistoryId(id);
-      setActiveHistoryPrevId(historyItems[index + 1]?.id ?? "");
+      // Baseline = true previous snapshot in the FULL list, so the "only
+      // versions" filter never diffs/restores against the wrong item.
+      setActiveHistoryPrevId(resolvePrevSnapshotId(historyItems, id));
     },
     [historyItems, setActiveHistoryId, setActiveHistoryPrevId],
   );
@@ -128,12 +152,27 @@ function HistoryList({ pageId }: Props) {
 
   return (
     <div>
+      <Group px="xs" py={6} justify="flex-end">
+        <Switch
+          size="xs"
+          checked={onlyVersions}
+          onChange={(e) => setOnlyVersions(e.currentTarget.checked)}
+          label={t("Only versions")}
+        />
+      </Group>
+
       <ScrollArea h={620} w="100%" type="scroll" scrollbarSize={5}>
-        {historyItems.map((historyItem, index) => (
+        {onlyVersions && visibleItems.length === 0 && (
+          <Center py="md">
+            <Text size="sm" c="dimmed">
+              {t("No saved versions yet.")}
+            </Text>
+          </Center>
+        )}
+        {visibleItems.map((historyItem) => (
           <HistoryItem
             key={historyItem.id}
             historyItem={historyItem}
-            index={index}
             onSelect={handleSelect}
             onHover={handleHover}
             onHoverEnd={clearPrefetchTimeout}

apps/client/src/features/page-history/types/page.types.ts

@@ -24,6 +24,10 @@ export interface IPageHistory {
   updatedAt: string;
   lastUpdatedBy: IPageHistoryUser;
   contributors?: IPageHistoryUser[];
+  // #370 — intentionality tier: 'manual'/'agent' are versions (intentional
+  // points), 'idle'/'boundary' are autosnapshots; null/undefined = legacy
+  // autosave. Derived server-side, drives the history badge + "versions" filter.
+  kind?: "manual" | "agent" | "idle" | "boundary" | null;
   // Provenance markers copied off the page row when the snapshot was saved.
   // `'agent'` marks a version written by the AI agent; `lastUpdatedAiChatId`
   // (when present) deep-links to the chat that produced the edit.

apps/client/src/features/page-history/utils/resolve-prev-snapshot.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { resolvePrevSnapshotId } from "./resolve-prev-snapshot";
+
+// #370 F4 — the risky client path: with the "only versions" filter active, diff
+// and restore must still baseline against the TRUE previous snapshot in the FULL
+// list, never the previous VISIBLE version (which would skip the autosnapshots
+// between two versions). These pin that the resolution is by FULL-list order.
+describe("resolvePrevSnapshotId", () => {
+  // Newest-first, as the history list stores it: a version, then two autosaves,
+  // then an older version.
+  const full = [
+    { id: "v2", kind: "manual" },
+    { id: "a2", kind: "idle" },
+    { id: "a1", kind: "boundary" },
+    { id: "v1", kind: "manual" },
+    { id: "a0", kind: null },
+  ];
+
+  it("returns the immediate FULL-list successor, not the previous visible version", () => {
+    // Selecting v2 while filtered to versions-only must baseline against a2 (the
+    // real chronological predecessor), NOT v1 (the previous visible version).
+    expect(resolvePrevSnapshotId(full, "v2")).toBe("a2");
+  });
+
+  it("resolves an autosnapshot's predecessor by full-list order", () => {
+    expect(resolvePrevSnapshotId(full, "a1")).toBe("v1");
+  });
+
+  it("returns '' for the oldest item (no predecessor)", () => {
+    expect(resolvePrevSnapshotId(full, "a0")).toBe("");
+  });
+
+  it("returns '' for an id not in the list", () => {
+    expect(resolvePrevSnapshotId(full, "missing")).toBe("");
+  });
+
+  it("does not depend on a filtered subset — same result whatever is visible", () => {
+    // The helper only ever sees the full list; a filtered view cannot change the
+    // baseline it computes.
+    expect(resolvePrevSnapshotId(full, "v1")).toBe("a0");
+  });
+});

apps/client/src/features/page-history/utils/resolve-prev-snapshot.ts

@@ -0,0 +1,22 @@
+/**
+ * #370 — resolve the TRUE previous snapshot for a history item.
+ *
+ * The history panel can be filtered to "only versions" (manual/agent), but diff
+ * and restore must always compare against the immediately-preceding snapshot in
+ * the FULL, unfiltered list — NOT the previous VISIBLE item. Comparing against
+ * the previous visible version would silently skip the autosnapshots between two
+ * versions and diff/restore the wrong baseline.
+ *
+ * Given the full (newest-first) list and an item id, this returns the id of the
+ * item right after it in the full list (its chronological predecessor), or "" if
+ * it is the oldest / not found. Pure and list-order-preserving so it can be unit
+ * tested without mounting the component.
+ */
+export function resolvePrevSnapshotId(
+  fullItems: ReadonlyArray<{ id: string }>,
+  id: string,
+): string {
+  const index = fullItems.findIndex((item) => item.id === id);
+  if (index === -1) return "";
+  return fullItems[index + 1]?.id ?? "";
+}

apps/client/src/features/page-history/version-messages.ts

@@ -0,0 +1,28 @@
+/**
+ * #370 — page-version stateless wire formats. Kept in one place so the client
+ * emitter (Save hotkey / button) and the client listener (page-editor) agree
+ * with the server (PersistenceExtension) on the message shapes.
+ */
+
+/** Client → server: "save a version now". The server derives the tier
+ * (manual/agent) from the signed connection actor, never from this payload. */
+export const SAVE_VERSION_MESSAGE_TYPE = "save-version";
+
+/** Server → all clients: a version was saved (or promoted / already existed). */
+export const VERSION_SAVED_MESSAGE_TYPE = "version.saved";
+
+export interface VersionSavedMessage {
+  type: typeof VERSION_SAVED_MESSAGE_TYPE;
+  historyId: string;
+  kind: "manual" | "agent";
+  /** True when the latest snapshot was already a manual version (a no-op save). */
+  alreadySaved: boolean;
+}
+
+/**
+ * Cross-component coordination flag so only the client that pressed Save shows
+ * the confirmation toast, while every other client silently refreshes its
+ * history panel on the broadcast. A module-level ref avoids stale-closure
+ * pitfalls in the editor's long-lived stateless handler.
+ */
+export const saveVersionPending = { current: false };

apps/client/src/features/page/components/header/page-header-menu.tsx

@@ -3,6 +3,7 @@ import {
   IconArrowRight,
   IconArrowsHorizontal,
   IconClockHour4,
+  IconDeviceFloppy,
   IconDots,
   IconEye,
   IconEyeOff,
@@ -17,7 +18,7 @@ import {
   IconTrash,
   IconWifiOff,
 } from "@tabler/icons-react";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { useAsideTriggerProps } from "@/hooks/use-toggle-aside.tsx";
 import { useAtom, useAtomValue } from "jotai";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
@@ -39,9 +40,14 @@ import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
 import { htmlToMarkdown } from "@docmost/editor-ext";
 import {
+  collabProviderAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms.ts";
+import {
+  SAVE_VERSION_MESSAGE_TYPE,
+  saveVersionPending,
+} from "@/features/page-history/version-messages.ts";
 import { formattedDate } from "@/lib/time.ts";
 import { PageEditModeToggle } from "@/features/user/components/page-state-pref.tsx";
 import MovePageModal from "@/features/page/components/move-page-modal.tsx";
@@ -72,9 +78,34 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
   });
   const isDeleted = !!page?.deletedAt;
   const [workspace] = useAtom(workspaceAtom);
+  const collabProvider = useAtomValue(collabProviderAtom);
   // Community public-sharing entry point (replaces the removed EE PageShareModal)
   const workspaceSharingDisabled = workspace?.settings?.sharing?.disabled === true;
 
+  // #370 — explicit "save a version" (Cmd+S / Save button). One path for the
+  // human; the server derives the tier from the signed actor. Readers can't save
+  // (the button is hidden and the collab connection is read-only server-side).
+  const handleSaveVersion = useCallback(() => {
+    if (readOnly || !collabProvider) return;
+    // Flag this client as the initiator so only it shows the confirmation toast;
+    // a safety timeout clears it if no broadcast comes back (e.g. offline).
+    saveVersionPending.current = true;
+    window.setTimeout(() => {
+      saveVersionPending.current = false;
+    }, 5000);
+    collabProvider.sendStateless(
+      JSON.stringify({ type: SAVE_VERSION_MESSAGE_TYPE }),
+    );
+  }, [readOnly, collabProvider]);
+
+  // mod+S must also block the browser's "Save page" dialog. `triggerOnContent-
+  // Editable` + empty ignore-list so it fires while typing in the editor/title.
+  useHotkeys(
+    [["mod+S", handleSaveVersion, { preventDefault: true }]],
+    [],
+    true,
+  );
+
   useHotkeys(
     [
       [
@@ -133,15 +164,16 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
         </ActionIcon>
       </Tooltip>
 
-      <PageActionMenu readOnly={readOnly} />
+      <PageActionMenu readOnly={readOnly} onSaveVersion={handleSaveVersion} />
     </>
   );
 }
 
 interface PageActionMenuProps {
   readOnly?: boolean;
+  onSaveVersion?: () => void;
 }
-function PageActionMenu({ readOnly }: PageActionMenuProps) {
+function PageActionMenu({ readOnly, onSaveVersion }: PageActionMenuProps) {
   const { t } = useTranslation();
   const [, setHistoryModalOpen] = useAtom(historyAtoms);
   const clipboard = useClipboard({ timeout: 500 });
@@ -302,6 +334,20 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
             </Group>
           </Menu.Item>
 
+          {!readOnly && (
+            <Menu.Item
+              leftSection={<IconDeviceFloppy size={16} />}
+              onClick={onSaveVersion}
+              rightSection={
+                <Text size="xs" c="dimmed">
+                  {t("Ctrl+S")}
+                </Text>
+              }
+            >
+              {t("Save version")}
+            </Menu.Item>
+          )}
+
           <Menu.Item
             leftSection={<IconHistory size={16} />}
             onClick={openHistoryModal}

apps/server/src/collaboration/constants.ts

@@ -1,3 +1,29 @@
-export const HISTORY_INTERVAL = 5 * 60 * 1000;
-export const HISTORY_FAST_INTERVAL = 60 * 1000;
-export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
+/**
+ * #370 — page-history intentionality tiers. Domain of `page_history.kind`.
+ *   - 'manual' / 'agent'  → Tier 1 versions (intentional points)
+ *   - 'idle' / 'boundary' → Tier 0 autosnapshots (safety net)
+ * A legacy `null` kind is treated as an autosave.
+ */
+export type PageHistoryKind = 'manual' | 'agent' | 'idle' | 'boundary';
+
+/**
+ * #370 — trailing idle-flush windows. A page's pending idle snapshot is
+ * re-armed on every store and fires this long after edits go quiet, so a burst
+ * of edits collapses into a single autosnapshot instead of one-per-store. Human
+ * sessions are noisier and less risky, so they flush less often than the agent.
+ */
+export const IDLE_INTERVAL_USER = 60 * 60 * 1000; // 60m
+export const IDLE_INTERVAL_AGENT = 15 * 60 * 1000; // 15m
+
+/**
+ * #370 — max-wait ceiling for the idle flush. Pure trailing debounce starves the
+ * safety net: hocuspocus stores at least every ~45s, so a CONTINUOUS editing
+ * session would re-arm the trailing timer forever and never take an idle
+ * snapshot until edits finally go quiet (up to IDLE_INTERVAL_USER = 60m). This
+ * ceiling bounds the actual wait from the FIRST edit of a burst, so an idle
+ * snapshot fires at least this often during a long unbroken session — restoring
+ * a recovery point cadence closer to the old heuristic without one-per-store
+ * noise. Mirrors hocuspocus's own maxDebounce idea.
+ */
+export const IDLE_MAX_WAIT_USER = 10 * 60 * 1000; // 10m
+export const IDLE_MAX_WAIT_AGENT = 5 * 60 * 1000; // 5m

apps/server/src/collaboration/extensions/compute-history-job.spec.ts

@@ -1,84 +1,93 @@
+import { computeHistoryJob, resolveSource } from './persistence.extension';
 import {
-  computeHistoryJob,
-  resolveSource,
-} from './persistence.extension';
-import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
 } from '../constants';
 
-// A fixed clock + fixed createdAt make pageAge deterministic.
-const NOW = 1_700_000_000_000;
 const PAGE_ID = '550e8400-e29b-41d4-a716-446655440000';
 
-// Build a minimal page whose age (NOW - createdAt) is exactly `ageMs`.
-const pageAged = (ageMs: number) => ({
-  id: PAGE_ID,
-  createdAt: new Date(NOW - ageMs),
-});
+const page = { id: PAGE_ID };
 
-describe('computeHistoryJob', () => {
-  it('agent edit → delay MUST be 0 and job id is source-keyed', () => {
-    // INVARIANT (§15 H2 / persistence.extension): the agent delay MUST stay 0.
-    // The worker re-reads the page row at run time, so any non-zero delay risks
-    // snapshotting content a later human edit has already overwritten. This is
-    // the load-bearing assertion of this spec — do not relax it.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'agent', NOW);
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('agent edit on an OLD page is still delay 0 (age never applies to agents)', () => {
-    // Even when the page is far older than the fast threshold, the agent path
-    // must short-circuit to 0 — age-based debounce is a human-only concern.
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 60_000),
-      'agent',
-      NOW,
-    );
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('human edit on a YOUNG page (age < threshold) → fast interval, bare job id', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD - 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+describe('computeHistoryJob (#370 — shared trailing idle pipeline)', () => {
+  it('human edit → user idle window, bare page.id job', () => {
+    // Humans and the agent now share ONE idle job per page (jobId = page.id).
+    // The agent's old delay=0 fast path is GONE — intentional agent points now
+    // arrive via the explicit save-version signal, not a zero-delay snapshot.
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
     expect(jobId).toBe(PAGE_ID);
   });
 
-  it('human edit on an OLD page (age > threshold) → standard interval', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent edit → agent idle window (shorter), still the bare page.id job', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'agent');
+    expect(delay).toBe(IDLE_INTERVAL_AGENT);
+    // No `-agent` suffix anymore: the agent joins the common idle pipeline.
     expect(jobId).toBe(PAGE_ID);
   });
 
-  it('boundary: pageAge EXACTLY === threshold takes the slow branch (the `<` is strict)', () => {
-    // Off-by-one guard: the condition is `pageAge < HISTORY_FAST_THRESHOLD`, so
-    // an age of exactly the threshold is NOT "fast" — it must use HISTORY_INTERVAL.
-    const { delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent flushes sooner than a human', () => {
+    expect(IDLE_INTERVAL_AGENT).toBeLessThan(IDLE_INTERVAL_USER);
   });
 
-  it('treats any non-"agent" source string as human', () => {
-    // resolveSource only ever yields 'agent' | 'user', but guard the contract:
-    // the agent branch keys strictly on === 'agent'.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'user', NOW);
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+  it('treats any non-"agent" source string as human (keys strictly on === agent)', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
     expect(jobId).toBe(PAGE_ID);
   });
+
+  // #370 review round-1 WARNING: the max-wait ceiling prevents autosnapshot
+  // starvation during a continuous editing session (the trailing timer would
+  // otherwise re-arm forever and never fire).
+  describe('max-wait ceiling', () => {
+    const T0 = 1_000_000; // arbitrary fixed epoch for deterministic tests
+
+    it('once a burst is armed, delay clamps to the remaining max-wait budget', () => {
+      // 1 minute into the burst the USER interval (60m) far exceeds the remaining
+      // max-wait budget (10m - 1m = 9m), so the delay is clamped DOWN to that
+      // remaining budget — the full interval is NOT used once a ceiling applies.
+      const { delay } = computeHistoryJob(page, 'user', T0, T0 + 60_000);
+      expect(delay).toBe(IDLE_MAX_WAIT_USER - 60_000);
+    });
+
+    it('never waits longer than the max-wait budget from the burst start', () => {
+      // A store arriving right at the ceiling → delay 0 (fire promptly).
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('past the ceiling never returns a negative delay', () => {
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER + 5 * 60_000,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('the agent ceiling is shorter than the user ceiling', () => {
+      expect(IDLE_MAX_WAIT_AGENT).toBeLessThan(IDLE_MAX_WAIT_USER);
+      const { delay } = computeHistoryJob(
+        page,
+        'agent',
+        T0,
+        T0 + IDLE_MAX_WAIT_AGENT,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('without a burstStart there is no ceiling (backward-compatible)', () => {
+      expect(computeHistoryJob(page, 'user').delay).toBe(IDLE_INTERVAL_USER);
+      expect(computeHistoryJob(page, 'agent').delay).toBe(IDLE_INTERVAL_AGENT);
+    });
+  });
 });
 
 describe('resolveSource (truth table)', () => {

apps/server/src/collaboration/extensions/persistence-store.spec.ts

@@ -40,11 +40,12 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
   let pageHistoryRepo: {
     saveHistory: jest.Mock;
     findPageLastHistory: jest.Mock;
+    updateHistoryKind: jest.Mock;
   };
   let aiQueue: { add: jest.Mock };
-  let historyQueue: { add: jest.Mock };
+  let historyQueue: { add: jest.Mock; remove: jest.Mock };
   let notificationQueue: { add: jest.Mock };
-  let collabHistory: { addContributors: jest.Mock };
+  let collabHistory: { addContributors: jest.Mock; popContributors: jest.Mock };
   let transclusionService: {
     syncPageTransclusions: jest.Mock;
     syncPageReferences: jest.Mock;
@@ -93,13 +94,22 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     pageHistoryRepo = {
       saveHistory: jest.fn().mockImplementation(async () => {
         callOrder.push('saveHistory');
+        return { id: 'history-1' };
       }),
       findPageLastHistory: jest.fn().mockResolvedValue(null),
+      updateHistoryKind: jest.fn().mockResolvedValue(undefined),
     };
     aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = {
+      add: jest.fn().mockResolvedValue(undefined),
+      // #370 — enqueuePageHistory now removes any pending idle job before re-adding.
+      remove: jest.fn().mockResolvedValue(undefined),
+    };
     notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = {
+      addContributors: jest.fn().mockResolvedValue(undefined),
+      popContributors: jest.fn().mockResolvedValue([]),
+    };
     transclusionService = {
       syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
       syncPageReferences: jest.fn().mockResolvedValue(undefined),
@@ -165,6 +175,50 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
   });
 
+  // #370 review round-1 SUGGESTION: the boundary was GENERALIZED from a
+  // user→agent special-case to ANY lastUpdatedSource transition. These pin the
+  // generalized behaviour it was rebuilt for.
+  describe('generalized boundary — any source transition', () => {
+    // Same persisted page but with an explicit prior source.
+    const pageWithPriorSource = (prior: string | null) => ({
+      ...persistedHumanPage('NEW CONTENT'),
+      lastUpdatedSource: prior,
+    });
+
+    it('agent→user transition fires the boundary (pins the prior agent revision)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('agent'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+      expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
+    });
+
+    it('git→user transition fires the boundary (git-sync overwrite is a source change)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('git'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+    });
+
+    it('a null prior source (first-ever edit) does NOT fire the boundary', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource(null));
+
+      await ext.onStoreDocument(buildData(document, 'agent') as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+    });
+  });
+
   it('idempotency: unchanged content → no updatePage, no history, no queues', async () => {
     // The Y.Doc content equals the persisted content deeply → early skip.
     // A Y.Doc round-trip normalizes attrs (e.g. paragraph indent), so derive
@@ -469,4 +523,125 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     // Contributors keyed by the UUID so they match the PAGE_HISTORY job (page.id).
     expect(collabHistory.addContributors.mock.calls[0][0]).toBe(PAGE_ID);
   });
+
+  // #370 — explicit save-version (Cmd+S / agent save tool) over the stateless
+  // seam. The tier is derived from the SIGNED connection actor, the store path
+  // is reused, and promote-not-dup avoids duplicating heavy content rows.
+  describe('save-version (#370)', () => {
+    const emitSave = (document: any, actor: 'user' | 'agent') =>
+      ext.onStateless({
+        connection: {
+          readOnly: false,
+          context: { user: { id: USER_ID, name: 'Alice' }, actor },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+    // findById returns a page whose content already equals the live doc, so the
+    // store path is a no-op and we isolate the versioning decision.
+    const pageMatchingDoc = (document: any) => ({
+      ...persistedHumanPage('IGNORED'),
+      content: TiptapTransformer.fromYdoc(document, 'default'),
+    });
+
+    it('human save with no prior snapshot → writes a manual version + broadcasts', async () => {
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(pageHistoryRepo.saveHistory.mock.calls[0][1]).toEqual(
+        expect.objectContaining({ kind: 'manual' }),
+      );
+      // The pending idle autosnapshot is cancelled by the explicit version.
+      expect(historyQueue.remove).toHaveBeenCalledWith(PAGE_ID);
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({
+        type: 'version.saved',
+        kind: 'manual',
+        alreadySaved: false,
+      });
+    });
+
+    it('agent save derives kind=agent from the signed actor', async () => {
+      const document = ydocFor(doc('AGENT VERSION'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'agent');
+
+      expect(pageHistoryRepo.saveHistory.mock.calls[pageHistoryRepo.saveHistory.mock.calls.length - 1][1]).toEqual(
+        expect.objectContaining({ kind: 'agent' }),
+      );
+    });
+
+    it('promote-not-dup: latest snapshot is an autosave with identical content → upgrades in place', async () => {
+      const document = ydocFor(doc('SAME'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'auto-1',
+        content: page.content,
+        kind: 'idle',
+      });
+
+      await emitSave(document, 'user');
+
+      // No heavy new content row — the existing autosave is promoted to manual.
+      expect(pageHistoryRepo.updateHistoryKind).toHaveBeenCalledWith(
+        'auto-1',
+        'manual',
+        expect.anything(),
+      );
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ historyId: 'auto-1', alreadySaved: false });
+    });
+
+    it('no-op when the latest snapshot is already a manual version of this content', async () => {
+      const document = ydocFor(doc('ALREADY SAVED'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'ver-1',
+        content: page.content,
+        kind: 'manual',
+      });
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ alreadySaved: true, kind: 'manual' });
+    });
+
+    it('a read-only connection cannot save a version', async () => {
+      const document = ydocFor(doc('READER'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+
+      await ext.onStateless({
+        connection: {
+          readOnly: true,
+          context: { user: { id: USER_ID }, actor: 'user' },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+    });
+  });
 });

apps/server/src/collaboration/extensions/persistence.extension.ts

@@ -36,9 +36,11 @@ import {
 import { Page } from '@docmost/db/types/entity.types';
 import { CollabHistoryService } from '../services/collab-history.service';
 import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
+  PageHistoryKind,
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
 import { observeCollabStore } from '../../integrations/metrics/metrics.registry';
@@ -51,6 +53,16 @@ import { observeCollabStore } from '../../integrations/metrics/metrics.registry'
  */
 export const INTENTIONAL_CLEAR_MESSAGE_TYPE = 'intentional-clear';
 
+/**
+ * #370 — wire format of the client→server "save a version" signal. Sent by the
+ * human (Cmd+S / Save button) and by the agent's explicit save tool over the
+ * SAME stateless channel. The intentionality tier ('manual' vs 'agent') is
+ * derived SERVER-SIDE from the signed connection actor, never from this
+ * payload, so a version's type is unforgeable. The document is taken from the
+ * connection (not the payload), so the signal cannot be aimed at another page.
+ */
+export const SAVE_VERSION_MESSAGE_TYPE = 'save-version';
+
 /**
  * #251 — how long an intentional-clear signal stays "pending" before it is
  * ignored. The signal is set on the clearing keystroke but consumed by the
@@ -87,35 +99,39 @@ export function resolveSource(
 }
 
 /**
- * Compute the BullMQ job id + delay for a page-history snapshot job. Pure so
- * the data-loss-sensitive timing arithmetic is unit-testable; `now` is injected
- * (caller passes `Date.now()`) for determinism.
+ * #370 — compute the BullMQ job id + delay for a page's trailing idle-flush
+ * autosnapshot. Pure so the timing is unit-testable.
  *
- * - Agent edits: delay 0 and a source-keyed job id `${page.id}-agent`. The
- *   delay MUST stay 0 — the worker re-reads the page row at run time, so any
- *   delay risks reading content a later human edit has already overwritten
- *   (mis-tagged snapshot). 0 minimizes that window. The `-agent` suffix keeps
- *   the job from coalescing with the bare-page.id human job.
- * - Human edits: age-based debounce so rapid human edits coalesce into one
- *   snapshot; job id is the bare `page.id`.
- *
- * BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is used;
- * page.id is a UUID, so `${page.id}-agent` cannot collide with a human job.
+ * Both humans and the agent now share ONE idle pipeline (the agent's old
+ * `delay=0` fast path is gone — intentional agent points arrive via the
+ * explicit save-version signal instead). The job id is the bare `page.id`, so a
+ * page has at most one pending idle job; the caller removes-and-re-adds it on
+ * every store to keep it debounced to the trailing edge of an edit burst. The
+ * window differs by source only: the agent flushes sooner than a human.
  */
 export function computeHistoryJob(
-  page: Pick<Page, 'id' | 'createdAt'>,
+  page: Pick<Page, 'id'>,
   source: string,
-  now: number,
+  // Epoch ms of the FIRST edit in the current burst (when the pending idle job
+  // was first armed). Used to enforce the max-wait ceiling so a continuous
+  // editing session cannot re-arm the trailing timer forever. `now` is injectable
+  // for tests; both default to a live clock / no ceiling when omitted.
+  burstStart?: number,
+  now: number = Date.now(),
 ): { jobId: string; delay: number } {
   const isAgent = source === 'agent';
-  const pageAge = now - new Date(page.createdAt).getTime();
-  const delay = isAgent
-    ? 0
-    : pageAge < HISTORY_FAST_THRESHOLD
-      ? HISTORY_FAST_INTERVAL
-      : HISTORY_INTERVAL;
-  const jobId = isAgent ? `${page.id}-agent` : page.id;
-  return { jobId, delay };
+  const interval = isAgent ? IDLE_INTERVAL_AGENT : IDLE_INTERVAL_USER;
+  const maxWait = isAgent ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+
+  let delay = interval;
+  if (burstStart !== undefined) {
+    // Time already elapsed since the burst's first edit; the snapshot must fire
+    // no later than `maxWait` after that, so shrink the trailing delay to the
+    // remaining budget (never negative, so BullMQ fires it promptly).
+    const remaining = burstStart + maxWait - now;
+    delay = Math.max(0, Math.min(interval, remaining));
+  }
+  return { jobId: page.id, delay };
 }
 
 @Injectable()
@@ -127,6 +143,11 @@ export class PersistenceExtension implements Extension {
   // coalescing window" per document and OR it across all edits in the window,
   // so the snapshot is marked 'agent' regardless of who wrote last.
   private agentTouched: Map<string, boolean> = new Map();
+  // #370 — epoch ms of the FIRST edit in the current idle-flush burst, per page.
+  // Set when the pending idle job is first armed (empty entry), read to enforce
+  // the max-wait ceiling in computeHistoryJob, and cleared when the idle job is
+  // consumed/cancelled so the next burst starts a fresh window.
+  private idleBurstStart: Map<string, number> = new Map();
   // #251 — per-document "intentional clear pending" flags. Keyed by
   // documentName, value = expiry timestamp (ms). Set by onStateless when the
   // client reports a deliberate clear; consumed once by the next
@@ -326,20 +347,19 @@ export class PersistenceExtension implements Extension {
             //this.logger.debug('Contributors error:' + err?.['message']);
           }
 
-          // Approach A — boundary snapshot before the agent's first edit.
-          // When this store is the agent's and the page's currently persisted
-          // state was authored by a human, pin that human state as its own
-          // history version BEFORE the agent overwrites it. `page` still holds
-          // the OLD content/provenance here, so saveHistory(page) captures the
-          // pre-agent state tagged 'user'. The agent's new content is
-          // snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
-          // if the prior state is already agent-authored (boundary already
-          // pinned on the user->agent transition), if the page is effectively
-          // empty, or if the latest existing snapshot already equals this human
-          // state (avoid duplicates).
+          // #370 — boundary snapshot on ANY source transition. When the store
+          // flips the page's provenance (user↔agent↔git), pin the OUTGOING
+          // state as its own history version BEFORE the incoming source
+          // overwrites it. `page` still holds the OLD content/provenance here,
+          // so saveHistory(page) captures the pre-transition state tagged with
+          // its own source, kind='boundary'. The incoming content is snapshotted
+          // later by the debounced idle job. Skip if the page is effectively
+          // empty or if the latest existing snapshot already equals this state
+          // (the shared isDeepStrictEqual gate — avoids duplicates). Generalizing
+          // beyond the old user→agent special-case also covers git-sync for free.
           if (
-            lastUpdatedSource === 'agent' &&
-            page.lastUpdatedSource !== 'agent'
+            page.lastUpdatedSource &&
+            page.lastUpdatedSource !== lastUpdatedSource
           ) {
             // pageHistory.pageId is uuid-typed; use page.id (never the doc-name
             // slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
@@ -347,15 +367,13 @@ export class PersistenceExtension implements Extension {
               page.id,
               { includeContent: true, trx },
             );
-            const humanBaselineMissing =
+            const baselineMissing =
               !lastHistory ||
               !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+            if (!isEmptyParagraphDoc(page.content as any) && baselineMissing) {
               await this.pageHistoryRepo.saveHistory(page, {
                 contributorIds: page.contributorIds ?? undefined,
+                kind: 'boundary',
                 trx,
               });
             }
@@ -480,6 +498,14 @@ export class PersistenceExtension implements Extension {
       return; // unrelated / malformed stateless message
     }
 
+    // #370 — explicit "save a version" (human Cmd+S / agent save tool). Edit
+    // rights are already enforced by the readOnly reject above (a reader can't
+    // create a version), exactly as intentional-clear requires.
+    if (message?.type === SAVE_VERSION_MESSAGE_TYPE) {
+      await this.handleSaveVersion(data);
+      return;
+    }
+
     if (message?.type !== INTENTIONAL_CLEAR_MESSAGE_TYPE) return;
 
     this.intentionalClear.set(
@@ -488,6 +514,117 @@ export class PersistenceExtension implements Extension {
     );
   }
 
+  /**
+   * #370 — persist an intentional version from the live in-memory ydoc.
+   *
+   * One stateless path serves BOTH the human and the agent; the tier is derived
+   * SERVER-SIDE from the signed connection actor ('agent' → 'agent', anything
+   * else → 'manual'), so the version type cannot be spoofed by the client. We
+   * take the fresh ydoc from the collab process memory and run it through the
+   * EXISTING store path first (so pages.content/ydoc reflect the exact content
+   * being versioned — a REST endpoint would race the up-to-10s-stale page row),
+   * then snapshot it into page_history with the intentional kind.
+   *
+   * Promote-not-dup: if the latest history row already holds this exact content
+   * and it is an autosave (idle/boundary/legacy-null), upgrade its kind in place
+   * instead of duplicating a heavy content row; if it is already 'manual', it is
+   * a no-op (the client shows an "already saved" toast). Otherwise a fresh
+   * version row is written, popping the aggregated contributors from Redis.
+   */
+  private async handleSaveVersion(data: onStatelessPayload): Promise<void> {
+    const { connection, document, documentName } = data;
+    const context = connection?.context;
+    const pageId = getPageId(documentName);
+    // Unforgeable: 'agent' only for a signed agent connection, else 'manual'.
+    const kind: PageHistoryKind =
+      context?.actor === 'agent' ? 'agent' : 'manual';
+
+    // Flush the live ydoc through the normal store path so the page row + ydoc
+    // hold exactly what we are about to version (also fires the idle enqueue we
+    // supersede below, plus any source-transition boundary). onStoreDocument
+    // only needs document/documentName/context.
+    await this.onStoreDocument({
+      document,
+      documentName,
+      context,
+    } as onStoreDocumentPayload);
+
+    let result:
+      | { historyId: string; kind: PageHistoryKind; alreadySaved: boolean }
+      | undefined;
+
+    await executeTx(this.db, async (trx) => {
+      const page = await this.pageRepo.findById(pageId, {
+        withLock: true,
+        includeContent: true,
+        trx,
+      });
+      if (!page) return;
+      // Never version an effectively-empty page (mirrors the processor's
+      // first-history guard); there is nothing intentional to pin.
+      if (isEmptyParagraphDoc(page.content as any)) return;
+
+      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+        page.id,
+        { includeContent: true, trx },
+      );
+
+      if (
+        lastHistory &&
+        isDeepStrictEqual(lastHistory.content, page.content)
+      ) {
+        // Content is already snapshotted. Promote-not-dup.
+        if (lastHistory.kind === 'manual') {
+          result = {
+            historyId: lastHistory.id,
+            kind: 'manual',
+            alreadySaved: true,
+          };
+          return;
+        }
+        await this.pageHistoryRepo.updateHistoryKind(
+          lastHistory.id,
+          kind,
+          trx,
+        );
+        result = { historyId: lastHistory.id, kind, alreadySaved: false };
+        return;
+      }
+
+      // Fresh version row. Pop the contributors aggregated since the last
+      // snapshot (SPOP); restore them if the write fails so they aren't lost.
+      const contributorIds = await this.collabHistory.popContributors(page.id);
+      try {
+        const saved = await this.pageHistoryRepo.saveHistory(page, {
+          contributorIds,
+          kind,
+          trx,
+        });
+        result = { historyId: saved.id, kind, alreadySaved: false };
+      } catch (err) {
+        await this.collabHistory.addContributors(page.id, contributorIds);
+        throw err;
+      }
+    });
+
+    // Housekeeping: this explicit version supersedes the page's pending idle
+    // autosnapshot, so cancel it (delayed job → remove() just deletes it) and
+    // end the current idle burst so the next edit starts a fresh max-wait window.
+    await this.historyQueue.remove(pageId).catch(() => undefined);
+    this.idleBurstStart.delete(pageId);
+
+    if (result) {
+      document.broadcastStateless(
+        JSON.stringify({
+          type: 'version.saved',
+          historyId: result.historyId,
+          kind: result.kind,
+          alreadySaved: result.alreadySaved,
+        }),
+      );
+    }
+  }
+
   async onChange(data: onChangePayload) {
     const documentName = data.documentName;
     const userId = data.context?.user?.id;
@@ -545,17 +682,45 @@ export class PersistenceExtension implements Extension {
     page: Page,
     lastUpdatedSource: string,
   ): Promise<void> {
-    // Job id + delay arithmetic lives in the pure `computeHistoryJob` (see its
-    // doc comment for the agent-delay-0 / age-based-debounce invariants).
+    // #370 — trailing idle debounce with a max-wait ceiling. One pending idle
+    // job per page (jobId = page.id); on every store we remove the pending
+    // delayed job and re-add it, so the snapshot lands `delay` after edits go
+    // quiet rather than once per store (precedent: workspace.service.ts).
+    // remove() on a delayed job simply deletes it (0 if absent, no throw); if the
+    // job is already ACTIVE and the remove is a no-op, the add still de-dups and
+    // the processor's isDeepStrictEqual gate collapses the duplicate content.
+    //
+    // The FIRST arm of a burst records `burstStart`; computeHistoryJob shrinks
+    // the delay to the remaining max-wait budget from that point, so a continuous
+    // session cannot re-arm the trailing timer forever and starve the snapshot.
+    // A burst marker older than THIS TIER's max-wait means the previous idle job
+    // has already fired — start a fresh window instead of firing immediately on
+    // the next edit. Must use the SAME source-specific max-wait computeHistoryJob
+    // uses (agent 5m / user 10m): a hardcoded USER ceiling would leave an agent
+    // burst's marker stale for 5..10m, forcing delay=0 on every store in that
+    // window and writing one idle row per store — exactly the per-store bloat the
+    // debounce exists to prevent, on the continuous-agent path.
+    const maxWait =
+      lastUpdatedSource === 'agent' ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+    const now = Date.now();
+    let burstStart = this.idleBurstStart.get(page.id);
+    if (burstStart === undefined || now - burstStart >= maxWait) {
+      burstStart = now;
+      this.idleBurstStart.set(page.id, burstStart);
+    }
+
     const { jobId, delay } = computeHistoryJob(
       page,
       lastUpdatedSource,
-      Date.now(),
+      burstStart,
+      now,
     );
 
+    await this.historyQueue.remove(jobId).catch(() => undefined);
+
     await this.historyQueue.add(
       QueueJob.PAGE_HISTORY,
-      { pageId: page.id } as IPageHistoryJob,
+      { pageId: page.id, kind: 'idle' } as IPageHistoryJob,
       { jobId, delay },
     );
   }

apps/server/src/collaboration/processors/history.processor.spec.ts

@@ -66,6 +66,15 @@ describe('HistoryProcessor.process', () => {
     notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
     generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
 
+    // #370 F3 — the processor now serializes its find+save under a page-row lock
+    // via executeTx. A db whose transaction().execute(fn) runs fn with a trx stub
+    // drives the real executeTx() helper without a database.
+    const db = {
+      transaction: () => ({
+        execute: (fn: (trx: any) => Promise<any>) => fn({ __trx: true }),
+      }),
+    };
+
     // WorkerHost's constructor reads `this.worker`; passing repos positionally
     // matches the constructor and avoids the Nest DI container.
     proc = new HistoryProcessor(
@@ -73,6 +82,7 @@ describe('HistoryProcessor.process', () => {
       pageRepo as any,
       collabHistory as any,
       watcherService as any,
+      db as any,
       notificationQueue as any,
       generalQueue as any,
     );
@@ -126,15 +136,26 @@ describe('HistoryProcessor.process', () => {
     await proc.process(buildJob());
 
     expect(collabHistory.popContributors).toHaveBeenCalledWith(PAGE_ID);
+    // #370 F3/F9 — the snapshot decision runs under a page-row lock. Pin the lock
+    // structurally so a refactor that drops withLock/trx (silently reintroducing
+    // the TOCTOU double-insert) turns this red. The tx stub is { __trx: true }.
+    expect(pageRepo.findById).toHaveBeenCalledWith(
+      PAGE_ID,
+      expect.objectContaining({ withLock: true, trx: { __trx: true } }),
+    );
+    // #370 F7 — addPageWatchers MUST receive the trx, or its FK-check runs on a
+    // separate connection and self-deadlocks against our FOR UPDATE. Asserting
+    // the trx arg here is exactly what would have caught that regression.
     expect(watcherService.addPageWatchers).toHaveBeenCalledWith(
       ['u1', 'u2'],
       PAGE_ID,
       SPACE_ID,
       WORKSPACE_ID,
+      { __trx: true },
     );
     expect(pageHistoryRepo.saveHistory).toHaveBeenCalledWith(
       expect.objectContaining({ id: PAGE_ID }),
-      { contributorIds: ['u1', 'u2'] },
+      { contributorIds: ['u1', 'u2'], kind: 'idle', trx: { __trx: true } },
     );
     expect(generalQueue.add).toHaveBeenCalledWith(
       QueueJob.PAGE_BACKLINKS,
@@ -186,6 +207,48 @@ describe('HistoryProcessor.process', () => {
     ]);
   });
 
+  it('COMMIT failure (throw outside the tx callback) → contributors RESTORED', async () => {
+    // #370 F8 — a commit-time failure throws OUTSIDE the callback, so the inner
+    // try/catch does not run; the outer catch must restore the popped set (else a
+    // BullMQ retry writes an unattributed version). Use a db whose execute() runs
+    // the callback THEN throws, simulating a commit abort.
+    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+      content: { type: 'doc', content: [] },
+    });
+    const commitFail = {
+      transaction: () => ({
+        execute: async (fn: (trx: any) => Promise<any>) => {
+          await fn({ __trx: true }); // callback succeeds (saveHistory ok)
+          throw new Error('commit aborted'); // ...but the COMMIT fails
+        },
+      }),
+    };
+    const procCommitFail = new HistoryProcessor(
+      pageHistoryRepo as any,
+      pageRepo as any,
+      collabHistory as any,
+      watcherService as any,
+      commitFail as any,
+      notificationQueue as any,
+      generalQueue as any,
+    );
+    jest
+      .spyOn(procCommitFail['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    await expect(procCommitFail.process(buildJob())).rejects.toThrow(
+      'commit aborted',
+    );
+    // The inner catch did NOT run (save succeeded), so only the outer catch can
+    // restore — assert it did.
+    expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+      'u1',
+      'u2',
+    ]);
+    // And the post-snapshot queue work must NOT have run (we rethrew).
+    expect(generalQueue.add).not.toHaveBeenCalled();
+  });
+
   it('backlinks + notification queue failures are swallowed (history still committed)', async () => {
     pageHistoryRepo.findPageLastHistory.mockResolvedValue({
       content: { type: 'doc', content: [] },

apps/server/src/collaboration/processors/history.processor.ts

@@ -19,6 +19,9 @@ import { isDeepStrictEqual } from 'node:util';
 import { CollabHistoryService } from '../services/collab-history.service';
 import { WatcherService } from '../../core/watcher/watcher.service';
 import { isEmptyParagraphDoc } from '../collaboration.util';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';
 
 @Processor(QueueName.HISTORY_QUEUE)
 export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
@@ -29,6 +32,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
     private readonly pageRepo: PageRepo,
     private readonly collabHistory: CollabHistoryService,
     private readonly watcherService: WatcherService,
+    @InjectKysely() private readonly db: KyselyDB,
     @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
     @InjectQueue(QueueName.GENERAL_QUEUE) private generalQueue: Queue,
   ) {
@@ -41,6 +45,9 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
     try {
       const { pageId } = job.data;
 
+      // Read the page WITHOUT a lock first, only to bail early on the two cheap
+      // no-write cases (page gone / empty first snapshot) without opening a
+      // transaction. The authoritative check-then-write happens locked below.
       const page = await this.pageRepo.findById(pageId, {
         includeContent: true,
       });
@@ -51,40 +58,109 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
         return;
       }
 
-      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
-        pageId,
-        { includeContent: true },
-      );
+      // #370 F3 — the snapshot decision (findPageLastHistory → saveHistory) must
+      // be serialized against manual-save/boundary writers, which run under a
+      // page-row lock in onStoreDocument. Without it, this processor and a
+      // concurrent manual-save each read the same lastHistory (MVCC), both see
+      // content != lastHistory, and both insert — producing two page_history rows
+      // with IDENTICAL content (one 'idle', one 'manual'), defeating
+      // promote-not-dup and the version-vs-autosave split. Taking the same
+      // page-row lock makes the second writer observe the first's committed row so
+      // the isDeepStrictEqual gate collapses the duplicate. Only the read+write
+      // is transacted; the post-snapshot queue work stays outside.
+      let contributorIds: string[] = [];
+      let snapshotWritten = false;
+      let lastHistoryContent: unknown;
+      // #370 F8 — the contributor set popped from Redis (destructive SPOP) must be
+      // restored if the snapshot does not durably land. The inner try/catch only
+      // covers a throw INSIDE the callback; a COMMIT failure (connection drop,
+      // serialization/deadlock abort on commit — the transient class the epic
+      // already retries) throws OUTSIDE it, rolling the snapshot back while the
+      // pop is already gone. We track the popped set here and restore it in the
+      // outer catch so a BullMQ retry re-attributes the version. addContributors
+      // is an idempotent Redis SADD, so a double-restore is harmless.
+      let poppedForRestore: string[] = [];
 
-      if (!lastHistory && isEmptyParagraphDoc(page.content as any)) {
-        this.logger.debug(
-          `Skipping first history for page ${pageId}: empty content`,
-        );
-        await this.collabHistory.clearContributors(pageId);
+      try {
+        await executeTx(this.db, async (trx) => {
+          const lockedPage = await this.pageRepo.findById(pageId, {
+            includeContent: true,
+            withLock: true,
+            trx,
+          });
+          if (!lockedPage) return;
+
+          const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+            pageId,
+            { includeContent: true, trx },
+          );
+          lastHistoryContent = lastHistory?.content;
+
+          if (!lastHistory && isEmptyParagraphDoc(lockedPage.content as any)) {
+            this.logger.debug(
+              `Skipping first history for page ${pageId}: empty content`,
+            );
+            return;
+          }
+
+          if (
+            lastHistory &&
+            isDeepStrictEqual(lastHistory.content, lockedPage.content)
+          ) {
+            return; // already snapshotted at this content — nothing to write
+          }
+
+          contributorIds = await this.collabHistory.popContributors(pageId);
+          poppedForRestore = contributorIds;
+          try {
+            // Pass `trx` so the watcher insert's FK check (FOR KEY SHARE on
+            // pages[pageId]) runs on the SAME connection that already holds the
+            // FOR UPDATE lock from findById — otherwise it takes the FK lock on a
+            // separate pool connection and self-deadlocks against our own tx.
+            await this.watcherService.addPageWatchers(
+              contributorIds,
+              pageId,
+              lockedPage.spaceId,
+              lockedPage.workspaceId,
+              trx,
+            );
+
+            // #370 — every job on this queue is a trailing idle-flush autosnapshot.
+            await this.pageHistoryRepo.saveHistory(lockedPage, {
+              contributorIds,
+              kind: job.data.kind ?? 'idle',
+              trx,
+            });
+            snapshotWritten = true;
+            this.logger.debug(`History created for page: ${pageId}`);
+          } catch (err) {
+            await this.collabHistory.addContributors(pageId, contributorIds);
+            poppedForRestore = [];
+            throw err;
+          }
+        });
+      } catch (err) {
+        // A throw here means the tx did NOT commit (callback threw, or the commit
+        // itself failed and rolled back). If we popped contributors and the inner
+        // catch did not already restore them, restore now so the retry keeps
+        // attribution. snapshotWritten is irrelevant: it is set before commit, so
+        // it can be true even when the commit rolled the snapshot back.
+        if (poppedForRestore.length) {
+          await this.collabHistory.addContributors(pageId, poppedForRestore);
+        }
+        throw err;
+      }
+
+      // No snapshot written (page vanished / empty-first / unchanged content) →
+      // clear the contributor set for the skip cases and stop.
+      if (!snapshotWritten) {
+        if (!lastHistoryContent && isEmptyParagraphDoc(page.content as any)) {
+          await this.collabHistory.clearContributors(pageId);
+        }
         return;
       }
 
-      if (
-        !lastHistory ||
-        !isDeepStrictEqual(lastHistory.content, page.content)
-      ) {
-        const contributorIds = await this.collabHistory.popContributors(pageId);
-
-        try {
-          await this.watcherService.addPageWatchers(
-            contributorIds,
-            pageId,
-            page.spaceId,
-            page.workspaceId,
-          );
-
-          await this.pageHistoryRepo.saveHistory(page, { contributorIds });
-          this.logger.debug(`History created for page: ${pageId}`);
-        } catch (err) {
-          await this.collabHistory.addContributors(pageId, contributorIds);
-          throw err;
-        }
-
+      {
         const mentions = extractMentions(page.content);
         const pageMentions = extractPageMentions(mentions);
         const internalLinkSlugIds = extractInternalLinkSlugIds(page.content);
@@ -102,7 +178,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
             );
           });
 
-        if (contributorIds.length > 0 && lastHistory?.content) {
+        if (contributorIds.length > 0 && lastHistoryContent) {
           await this.notificationQueue
             .add(QueueJob.PAGE_UPDATED, {
               pageId,

apps/server/src/database/migrations/20260705T120000-page-history-kind.ts

@@ -0,0 +1,27 @@
+import { type Kysely } from 'kysely';
+
+/**
+ * #370 — page-versioning intentionality tier on a history snapshot.
+ *
+ * Adds `page_history.kind`, the three-tier "how intentional was this snapshot"
+ * marker that lets versions (intentional points) be told apart from autosaves:
+ *   - 'manual'   — a human explicitly saved a version (Cmd+S / Save button)
+ *   - 'agent'    — the AI agent explicitly saved a version
+ *   - 'idle'     — trailing idle-flush autosnapshot (safety net)
+ *   - 'boundary' — autosnapshot pinned on a source transition (user↔agent↔git)
+ *
+ * Nullable with NO default (mirrors last_updated_source in the agent-provenance
+ * migration): legacy rows predate the marker and read back as `null`, which the
+ * client renders as a plain autosave. Stored as a short varchar to stay
+ * forward-compatible without an enum migration.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('page_history')
+    .addColumn('kind', 'varchar(20)', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.alterTable('page_history').dropColumn('kind').execute();
+}

apps/server/src/database/repos/page/page-history.repo.ts

@@ -13,6 +13,7 @@ import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB } from '@docmost/db/types/db';
 import { resolveAgentProvenance } from '../agent-provenance';
+import { PageHistoryKind } from '../../../collaboration/constants';
 
 /**
  * Role-resolution subquery for a page-history row's bound AI chat (#300). Joins
@@ -46,6 +47,9 @@ export class PageHistoryRepo {
     'lastUpdatedById',
     'lastUpdatedSource',
     'lastUpdatedAiChatId',
+    // #370 — intentionality tier ('manual' | 'agent' | 'idle' | 'boundary');
+    // null on legacy rows (= autosave). Selected so callers can read/promote it.
+    'kind',
     'contributorIds',
     'spaceId',
     'workspaceId',
@@ -85,9 +89,15 @@ export class PageHistoryRepo {
 
   async saveHistory(
     page: Page,
-    opts?: { contributorIds?: string[]; trx?: KyselyTransaction },
-  ): Promise<void> {
-    await this.insertPageHistory(
+    opts?: {
+      contributorIds?: string[];
+      // #370 — intentionality tier for this snapshot. Omitted → null (legacy
+      // autosave semantics). Callers derive it server-side, never from a client.
+      kind?: PageHistoryKind;
+      trx?: KyselyTransaction;
+    },
+  ): Promise<PageHistory> {
+    return await this.insertPageHistory(
       {
         pageId: page.id,
         slugId: page.slugId,
@@ -99,6 +109,7 @@ export class PageHistoryRepo {
         // Copy the provenance marker off the page row, as for lastUpdatedById.
         lastUpdatedSource: page.lastUpdatedSource,
         lastUpdatedAiChatId: page.lastUpdatedAiChatId,
+        kind: opts?.kind ?? null,
         contributorIds: opts?.contributorIds,
         spaceId: page.spaceId,
         workspaceId: page.workspaceId,
@@ -107,6 +118,25 @@ export class PageHistoryRepo {
     );
   }
 
+  /**
+   * #370 — promote an existing snapshot's intentionality tier in place. Used by
+   * the manual-save "promote-not-dup" path: when the latest history row already
+   * holds the exact content being versioned, we upgrade its `kind` instead of
+   * duplicating a heavy content row.
+   */
+  async updateHistoryKind(
+    pageHistoryId: string,
+    kind: PageHistoryKind,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .updateTable('pageHistory')
+      .set({ kind })
+      .where('id', '=', pageHistoryId)
+      .execute();
+  }
+
   async findPageHistoryByPageId(pageId: string, pagination: PaginationOptions) {
     const query = this.db
       .selectFrom('pageHistory')

apps/server/src/database/types/db.d.ts

@@ -280,6 +280,7 @@ export interface PageHistory {
   createdAt: Generated<Timestamp>;
   icon: string | null;
   id: Generated<string>;
+  kind: string | null;
   lastUpdatedAiChatId: string | null;
   lastUpdatedById: string | null;
   lastUpdatedSource: string | null;

apps/server/src/integrations/queue/constants/queue.interface.ts

@@ -20,6 +20,10 @@ export interface IStripeSeatsSyncJob {
 
 export interface IPageHistoryJob {
   pageId: string;
+  // #370 — intentionality tier the worker stamps on the snapshot. All jobs on
+  // this queue are trailing idle-flush autosnapshots, so this is 'idle' (absent
+  // → treated as 'idle' by the processor).
+  kind?: 'idle';
 }
 
 /**

packages/editor-ext/src/index.ts

@@ -20,7 +20,6 @@ export * from "./lib/html-embed/html-embed";
 export * from "./lib/mention";
 export * from "./lib/markdown";
 export * from "./lib/search-and-replace";
-export * from "./lib/multi-cursor";
 export * from "./lib/embed-provider";
 export * from "./lib/subpages";
 export * from "./lib/transclusion";

packages/editor-ext/src/lib/multi-cursor/index.ts

@@ -1,3 +0,0 @@
-import { MultiCursor } from "./multi-cursor";
-export * from "./multi-cursor";
-export default MultiCursor;

packages/editor-ext/src/lib/multi-cursor/multi-cursor.test.ts

@@ -1,453 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { Editor } from "@tiptap/core";
-import { Document } from "@tiptap/extension-document";
-import { Paragraph } from "@tiptap/extension-paragraph";
-import { Text } from "@tiptap/extension-text";
-import { Bold } from "@tiptap/extension-bold";
-import { Node as PMNode } from "@tiptap/pm/model";
-import { MultiCursor, multiCursorPluginKey, MAX_CURSORS } from "./multi-cursor";
-import { findOccurrences } from "../search-and-replace/find-occurrences";
-
-const extensions = [Document, Paragraph, Text, Bold, MultiCursor];
-
-function makeEditor(content?: any) {
-  return new Editor({
-    extensions,
-    content: content ?? { type: "doc", content: [{ type: "paragraph" }] },
-  });
-}
-
-function doc(...paragraphs: string[]) {
-  return {
-    type: "doc",
-    content: paragraphs.map((text) => ({
-      type: "paragraph",
-      content: text ? [{ type: "text", text }] : [],
-    })),
-  };
-}
-
-function paraTexts(d: PMNode): string[] {
-  const out: string[] = [];
-  d.forEach((node) => {
-    if (node.type.name === "paragraph") out.push(node.textContent);
-  });
-  return out;
-}
-
-function cursors(editor: Editor) {
-  return multiCursorPluginKey.getState(editor.state)!.cursors;
-}
-
-// Simulate typing a character through the real handleTextInput routing (the
-// browser path). someMethod-equivalent: dispatch a DOM-ish text input by calling
-// the view's input handler directly.
-function typeText(editor: Editor, text: string) {
-  const { from, to } = editor.state.selection;
-  // props.handleTextInput is what ProseMirror calls on beforeinput/keypress.
-  const handled = editor.view.someProp(
-    "handleTextInput",
-    (fn) => fn(editor.view, from, to, text) || false,
-  );
-  if (!handled) {
-    // Fall back to a normal insertion (no active multi-cursor set).
-    editor.view.dispatch(editor.state.tr.insertText(text, from, to));
-  }
-}
-
-function pressKey(editor: Editor, key: string) {
-  editor.view.someProp("handleKeyDown", (fn) =>
-    fn(editor.view, new KeyboardEvent("keydown", { key })),
-  );
-}
-
-describe("multi-cursor: selectAllOccurrences", () => {
-  it("finds EVERY occurrence of a repeated word under the cursor", () => {
-    const editor = makeEditor(doc("foo bar foo baz foo"));
-    // Cursor inside the first "foo".
-    editor.commands.setTextSelection(2);
-    expect(editor.commands.selectAllOccurrences()).toBe(true);
-
-    const cs = cursors(editor);
-    expect(cs.length).toBe(3);
-    // Every cursor spans a "foo".
-    for (const c of cs) {
-      expect(editor.state.doc.textBetween(c.from, c.to)).toBe("foo");
-    }
-    editor.destroy();
-  });
-
-  it("uses the current non-empty selection as the term", () => {
-    const editor = makeEditor(doc("ab abc ab abcd ab"));
-    // Select the first "ab".
-    editor.commands.setTextSelection({ from: 1, to: 3 });
-    expect(editor.state.doc.textBetween(1, 3)).toBe("ab");
-    editor.commands.selectAllOccurrences();
-    // Literal substring match (selection is not whole-word), so every "ab"
-    // including those inside "abc"/"abcd" is matched: 5 total.
-    const cs = cursors(editor);
-    expect(cs.length).toBe(5);
-    editor.destroy();
-  });
-
-  it("whole-word matching from a word cursor does not match substrings", () => {
-    const editor = makeEditor(doc("cat category cat scatter cat"));
-    editor.commands.setTextSelection(2); // inside first "cat"
-    editor.commands.selectAllOccurrences();
-    // Only the three standalone "cat" words, not "category"/"scatter".
-    expect(cursors(editor).length).toBe(3);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: mass typing (single transaction)", () => {
-  it("types text into N carets at once", () => {
-    const editor = makeEditor(doc("foo foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(3);
-
-    // Typing replaces each selected "foo" with "X".
-    typeText(editor, "X");
-    expect(paraTexts(editor.state.doc)).toEqual(["X X X"]);
-
-    // The cursors are now carets right after each inserted "X".
-    const cs = cursors(editor);
-    expect(cs.length).toBe(3);
-    for (const c of cs) expect(c.from).toBe(c.to);
-    editor.destroy();
-  });
-
-  it("continues typing at the resulting carets (append semantics)", () => {
-    const editor = makeEditor(doc("a a a"));
-    editor.commands.setTextSelection(1);
-    editor.commands.selectAllOccurrences();
-    typeText(editor, "b"); // each "a" -> "b"
-    typeText(editor, "c"); // append at each caret -> "bc"
-    expect(paraTexts(editor.state.doc)).toEqual(["bc bc bc"]);
-    editor.destroy();
-  });
-
-  it("applies the whole multi-edit in a SINGLE transaction (one undo step)", () => {
-    // "One Cmd/Ctrl+Z undoes the whole multi-edit" holds iff the N edits land in
-    // ONE transaction (history groups by transaction). @tiptap/extension-history
-    // is not a dependency here, so rather than exercise undo we assert the
-    // property that guarantees it: typing into N cursors is exactly ONE dispatch.
-    const editor = makeEditor(doc("foo foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(3);
-
-    const orig = editor.view.dispatch.bind(editor.view);
-    let dispatches = 0;
-    editor.view.dispatch = (tr) => {
-      dispatches += 1;
-      return orig(tr);
-    };
-    typeText(editor, "Z");
-    editor.view.dispatch = orig;
-
-    expect(dispatches).toBe(1); // all three edits share one transaction
-    expect(paraTexts(editor.state.doc)).toEqual(["Z Z Z"]);
-    editor.destroy();
-  });
-
-  it("off-by-one guard: reverse-order iteration keeps every position valid", () => {
-    // If the mass edit iterated FORWARD, inserting at an earlier cursor would
-    // shift every later cursor and corrupt the result. Different-length
-    // replacement makes such a bug visible.
-    const editor = makeEditor(doc("x x x x"));
-    editor.commands.setTextSelection(1);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(4);
-    typeText(editor, "LONG");
-    expect(paraTexts(editor.state.doc)).toEqual(["LONG LONG LONG LONG"]);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: mass Backspace / Delete", () => {
-  it("Backspace removes one char before each caret", () => {
-    const editor = makeEditor(doc("foo foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    // Collapse selections to carets at the END of each "foo" by typing then
-    // removing is complex; instead type to convert ranges into carets first.
-    typeText(editor, "ab"); // each "foo" -> "ab", carets after "ab"
-    expect(paraTexts(editor.state.doc)).toEqual(["ab ab ab"]);
-    pressKey(editor, "Backspace"); // remove the trailing "b" at each caret
-    expect(paraTexts(editor.state.doc)).toEqual(["a a a"]);
-    editor.destroy();
-  });
-
-  it("Delete removes one char after each caret", () => {
-    const editor = makeEditor(doc("fooX fooX"));
-    // Literal (selection) match of "foo" -> both occurrences inside "fooX".
-    editor.commands.setTextSelection({ from: 1, to: 4 }); // first "foo"
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(2);
-    typeText(editor, "foo"); // rewrite "foo", carets now sit before each "X"
-    expect(paraTexts(editor.state.doc)).toEqual(["fooX fooX"]);
-    pressKey(editor, "Delete"); // remove the "X" after each caret
-    expect(paraTexts(editor.state.doc)).toEqual(["foo foo"]);
-    editor.destroy();
-  });
-
-  it("Backspace at a block-start caret is a no-op for that cursor", () => {
-    const editor = makeEditor(doc("ab", "ab"));
-    // Select both "ab" then convert to carets at start by replacing with "".
-    editor.commands.setTextSelection({ from: 1, to: 3 }); // first "ab"
-    editor.commands.selectAllOccurrences();
-    // Move carets to block start: type "" is not possible; instead delete range.
-    pressKey(editor, "Backspace"); // deletes each selected "ab"
-    expect(paraTexts(editor.state.doc)).toEqual(["", ""]);
-    // Carets are now at each block start; another Backspace must not throw and
-    // must not merge blocks (still two empty paragraphs).
-    pressKey(editor, "Backspace");
-    expect(paraTexts(editor.state.doc)).toEqual(["", ""]);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: addNextOccurrence (Cmd/Ctrl+D)", () => {
-  it("first press selects the current word, next press adds the next", () => {
-    const editor = makeEditor(doc("go go go"));
-    editor.commands.setTextSelection(2); // inside first "go"
-    editor.commands.addNextOccurrence();
-    expect(cursors(editor).length).toBe(1);
-    editor.commands.addNextOccurrence();
-    expect(cursors(editor).length).toBe(2);
-    editor.commands.addNextOccurrence();
-    expect(cursors(editor).length).toBe(3);
-    // Nothing left to add — stays at 3.
-    editor.commands.addNextOccurrence();
-    expect(cursors(editor).length).toBe(3);
-    for (const c of cursors(editor)) {
-      expect(editor.state.doc.textBetween(c.from, c.to)).toBe("go");
-    }
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: position remapping", () => {
-  it("remaps cursors after a LOCAL edit before them", () => {
-    const editor = makeEditor(doc("foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    const before = cursors(editor).map((c) => ({ ...c }));
-
-    // Insert unrelated text at the very start (pos 1), shifting everything +5.
-    editor.view.dispatch(editor.state.tr.insertText("HELLO", 1));
-
-    const after = cursors(editor);
-    expect(after.length).toBe(before.length);
-    for (let i = 0; i < after.length; i += 1) {
-      expect(after[i].from).toBe(before[i].from + 5);
-      expect(after[i].to).toBe(before[i].to + 5);
-      // And they still point at "foo".
-      expect(editor.state.doc.textBetween(after[i].from, after[i].to)).toBe(
-        "foo",
-      );
-    }
-    editor.destroy();
-  });
-
-  it("remaps cursors after a simulated REMOTE edit (ordinary transaction)", () => {
-    const editor = makeEditor(doc("foo bar foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    const before = cursors(editor).map((c) => ({ ...c }));
-    expect(before.length).toBe(2);
-
-    // y-prosemirror applies remote changes as ordinary transactions. Emulate a
-    // remote insertion between the two "foo"s (inside "bar", pos 6) with a tr
-    // that carries NO multi-cursor meta — exactly like a collaborator's edit.
-    const tr = editor.state.tr.insertText("ZZ", 6);
-    editor.view.dispatch(tr);
-
-    const after = cursors(editor);
-    // The first "foo" (before the insertion) is unchanged; the second shifts +2.
-    expect(after[0].from).toBe(before[0].from);
-    expect(after[1].from).toBe(before[1].from + 2);
-    for (const c of after) {
-      expect(editor.state.doc.textBetween(c.from, c.to)).toBe("foo");
-    }
-    editor.destroy();
-  });
-
-  it("a REMOTE delete UNDER a cursor collapses it to a caret (not drop), leaving others intact", () => {
-    // The riskiest remap path: a collaborator deletes the very text one cursor
-    // spans. Both edges map with assoc +1 and there is no drop logic, so the
-    // deleted-over cursor CONTRACT is: it collapses to a zero-width caret at the
-    // deletion point (from === to) and STAYS in the set — it is not removed.
-    // Untouched cursors keep spanning their occurrence. Pinning this makes the
-    // collapse-not-drop choice explicit (review #372 F2).
-    const editor = makeEditor(doc("foo bar foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    const before = cursors(editor).map((c) => ({ ...c }));
-    expect(before.length).toBe(2);
-
-    // Remote (no multi-cursor meta) delete of the FIRST "foo" range.
-    const tr = editor.state.tr.delete(before[0].from, before[0].to);
-    editor.view.dispatch(tr);
-
-    const after = cursors(editor);
-    // Still two cursors — the deleted-over one is NOT dropped.
-    expect(after.length).toBe(2);
-    // The first collapsed to a caret at the deletion point.
-    expect(after[0].from).toBe(after[0].to);
-    expect(after[0].from).toBe(before[0].from);
-    // The second still spans "foo" (shifted left by the 3 removed chars).
-    expect(after[1].from).toBe(before[1].from - 3);
-    expect(editor.state.doc.textBetween(after[1].from, after[1].to)).toBe("foo");
-    // Sanity: the document now reads " bar foo".
-    expect(paraTexts(editor.state.doc)).toEqual([" bar foo"]);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: collapse / exit", () => {
-  it("exitMultiCursor clears the set", () => {
-    const editor = makeEditor(doc("foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(2);
-    editor.commands.exitMultiCursor();
-    expect(cursors(editor).length).toBe(0);
-    editor.destroy();
-  });
-
-  it("an arrow key collapses the set", () => {
-    const editor = makeEditor(doc("foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(2);
-    pressKey(editor, "ArrowRight");
-    expect(cursors(editor).length).toBe(0);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: collapse on composition / mousedown", () => {
-  // Invoke a plugin handleDOMEvents handler through the real prop plumbing.
-  function fireDOM(editor: Editor, name: string): void {
-    editor.view.someProp("handleDOMEvents", (handlers: any) => {
-      const h = handlers && handlers[name];
-      if (h) h(editor.view, new Event(name));
-      return false;
-    });
-  }
-
-  it("collapses the set on compositionstart (IME) — MVP does not multi-IME", () => {
-    const editor = makeEditor(doc("foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(2);
-    fireDOM(editor, "compositionstart");
-    expect(cursors(editor).length).toBe(0);
-    editor.destroy();
-  });
-
-  it("collapses the set on a plain mousedown (VS Code behaviour)", () => {
-    const editor = makeEditor(doc("foo foo"));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(2);
-    fireDOM(editor, "mousedown");
-    expect(cursors(editor).length).toBe(0);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: hard cap", () => {
-  it("never activates more than MAX_CURSORS cursors", () => {
-    const many = new Array(MAX_CURSORS + 20).fill("w").join(" ");
-    const editor = makeEditor(doc(many));
-    editor.commands.setTextSelection(2);
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(MAX_CURSORS);
-    editor.destroy();
-  });
-});
-
-describe("multi-cursor: marks are carried across a mass edit", () => {
-  it("preserves marks spanning each replaced range", () => {
-    const editor = makeEditor({
-      type: "doc",
-      content: [
-        {
-          type: "paragraph",
-          content: [
-            { type: "text", text: "a " },
-            { type: "text", marks: [{ type: "bold" }], text: "key" },
-            { type: "text", text: " b " },
-            { type: "text", marks: [{ type: "bold" }], text: "key" },
-          ],
-        },
-      ],
-    });
-    editor.commands.setTextSelection(3); // inside first bold "key"
-    editor.commands.selectAllOccurrences();
-    expect(cursors(editor).length).toBe(2);
-    typeText(editor, "NEW");
-
-    // Both replacements keep the bold mark.
-    let boldRuns = 0;
-    editor.state.doc.descendants((node) => {
-      if (
-        node.isText &&
-        node.text === "NEW" &&
-        node.marks.some((m) => m.type.name === "bold")
-      ) {
-        boldRuns += 1;
-      }
-    });
-    expect(boldRuns).toBe(2);
-    editor.destroy();
-  });
-});
-
-// The extracted find-occurrences util must return the SAME occurrences that the
-// old inline walk produced (and that search-and-replace still relies on).
-describe("find-occurrences util", () => {
-  it("finds all matches of a literal regex across text nodes", () => {
-    const editor = makeEditor(doc("foo foofoo foo"));
-    const results = findOccurrences(editor.state.doc, /foo/gu);
-    // 4 occurrences: two standalone + two inside "foofoo".
-    expect(results.length).toBe(4);
-    for (const r of results) {
-      expect(editor.state.doc.textBetween(r.from, r.to)).toBe("foo");
-    }
-    editor.destroy();
-  });
-
-  it("ignores whitespace-only matches and empty regex", () => {
-    const editor = makeEditor(doc("a b c"));
-    expect(findOccurrences(editor.state.doc, null as any).length).toBe(0);
-    // A whitespace regex yields no results (matches are trimmed away).
-    expect(findOccurrences(editor.state.doc, /\s/gu).length).toBe(0);
-    editor.destroy();
-  });
-
-  it("finds a match spanning two differently-marked contiguous text nodes", () => {
-    const editor = makeEditor({
-      type: "doc",
-      content: [
-        {
-          type: "paragraph",
-          content: [
-            { type: "text", text: "wo" },
-            { type: "text", marks: [{ type: "bold" }], text: "rd" },
-          ],
-        },
-      ],
-    });
-    const results = findOccurrences(editor.state.doc, /word/gu);
-    expect(results.length).toBe(1);
-    expect(editor.state.doc.textBetween(results[0].from, results[0].to)).toBe(
-      "word",
-    );
-    editor.destroy();
-  });
-});

packages/editor-ext/src/lib/multi-cursor/multi-cursor.ts

@@ -1,545 +0,0 @@
-import { Extension, Range } from "@tiptap/core";
-import { Decoration, DecorationSet, EditorView } from "@tiptap/pm/view";
-import {
-  Plugin,
-  PluginKey,
-  TextSelection,
-  type EditorState,
-} from "@tiptap/pm/state";
-import { Mark } from "@tiptap/pm/model";
-import { findOccurrences } from "../search-and-replace/find-occurrences";
-
-/**
- * Multi-cursor editing — MVP (issue #196, "Variant A").
- *
- * VS Code-style multi-cursor limited to "select all occurrences of a word (or
- * the current selection) and type into all of them at once", built ON TOP OF
- * the search-and-replace mass-transaction machinery:
- *
- *   - Cmd/Ctrl+Shift+L (selectAllOccurrences): the word under the cursor (or the
- *     current non-empty selection) -> ALL its occurrences become active cursors.
- *   - Cmd/Ctrl+D (addNextOccurrence): add the NEXT occurrence of the term.
- *   - Typing / Backspace / Delete apply to EVERY active cursor in ONE
- *     transaction (so a single Cmd/Ctrl+Z undoes the whole multi-edit).
- *   - Esc (exitMultiCursor): collapse back to a single cursor.
- *
- * The single-transaction, reverse-order edit mechanic mirrors `replaceAll` in
- * search-and-replace.ts: we iterate cursors from the END of the document to the
- * START so an earlier edit never invalidates a later position, carrying the
- * marks that span each range.
- *
- * CONSCIOUS v1 OUT-OF-SCOPE BOUNDARIES (these are "Variant B", deliberately NOT
- * built here):
- *   - Alt+Click arbitrary carets and Alt+drag column selection.
- *   - Cmd/Ctrl+Alt+Up/Down "add cursor on the adjacent line".
- *   - Simultaneous IME / composition input into multiple positions — on
- *     `compositionstart` we collapse back to a single cursor.
- *   - Cursors spanning different schema nodes in one edit.
- *
- * NOT out of scope, but worth stating precisely: there is NO schema-aware or
- * structural cursor. Occurrences are found by a plain text-node walk
- * (`findOccurrences`), so a term that appears inside a table cell, code block or
- * callout DOES get a cursor there and IS edited — as plain text, exactly like
- * `replaceAll`. There is no special table/code handling; the per-cursor try/catch
- * only SKIPS a cursor whose edit would violate the schema (never applied
- * half-way), it does not exclude those node types from matching.
- */
-
-interface MultiCursorState {
-  // Each active cursor: a caret when from === to, a range when from < to.
-  cursors: Range[];
-}
-
-export const multiCursorPluginKey = new PluginKey<MultiCursorState>(
-  "multiCursor",
-);
-
-// Hard safety cap on simultaneously-active cursors — stop adding past it.
-export const MAX_CURSORS = 100;
-
-export interface MultiCursorStorage {
-  // Whether the active term matches whole words only. Set to true when the set
-  // was seeded from a bare cursor (word under caret), false when seeded from an
-  // explicit selection (literal substring match, like VS Code). Remembered so
-  // addNextOccurrence keeps matching the same way as selectAllOccurrences.
-  wholeWord: boolean;
-}
-
-declare module "@tiptap/core" {
-  interface Storage {
-    multiCursor: MultiCursorStorage;
-  }
-  interface Commands<ReturnType> {
-    multiCursor: {
-      /** Select all occurrences of the word/selection as active cursors. */
-      selectAllOccurrences: () => ReturnType;
-      /** Add the next occurrence of the current term to the cursor set. */
-      addNextOccurrence: () => ReturnType;
-      /** Collapse the multi-cursor set back to a single cursor. */
-      exitMultiCursor: () => ReturnType;
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Term helpers
-// ---------------------------------------------------------------------------
-
-function escapeRegExp(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-// A "word" is a run of letters/numbers/underscore; those get whole-word
-// matching (\b…\b) so a term never matches inside a larger word. Anything else
-// (punctuation, phrases) is matched literally. Case-sensitive, like VS Code.
-function isWordTerm(s: string): boolean {
-  return /^[\p{L}\p{N}_]+$/u.test(s);
-}
-
-// wholeWord uses \b…\b so the term never matches inside a larger word; it only
-// applies to word-like terms (a term containing punctuation cannot be
-// whole-word-bounded meaningfully). Otherwise the term is matched literally.
-function buildTermRegex(term: string, wholeWord: boolean): RegExp {
-  const esc = escapeRegExp(term);
-  return wholeWord && isWordTerm(term)
-    ? new RegExp(`\\b${esc}\\b`, "gu")
-    : new RegExp(esc, "gu");
-}
-
-// Word under a position: returns the exact { from, to } range and its text, or
-// null if the position is not inside a word in a textblock.
-function getWordAt(
-  state: EditorState,
-  pos: number,
-): { from: number; to: number; text: string } | null {
-  const $pos = state.doc.resolve(pos);
-  const parent = $pos.parent;
-  if (!parent.isTextblock) return null;
-
-  const text = parent.textContent;
-  const offset = $pos.parentOffset;
-  const start = $pos.start();
-  const wordRe = /[\p{L}\p{N}_]+/gu;
-
-  let m: RegExpExecArray | null;
-  while ((m = wordRe.exec(text)) !== null) {
-    const s = m.index;
-    const e = m.index + m[0].length;
-    if (offset >= s && offset <= e) {
-      return { from: start + s, to: start + e, text: m[0] };
-    }
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Plugin-state access
-// ---------------------------------------------------------------------------
-
-function getCursors(state: EditorState): Range[] {
-  const st = multiCursorPluginKey.getState(state);
-  return st ? st.cursors : [];
-}
-
-function setCursors(view: EditorView, cursors: Range[]): void {
-  view.dispatch(view.state.tr.setMeta(multiCursorPluginKey, cursors));
-}
-
-function collapse(view: EditorView): void {
-  setCursors(view, []);
-}
-
-// ---------------------------------------------------------------------------
-// The single-transaction, reverse-order mass edit (mirrors replaceAll)
-// ---------------------------------------------------------------------------
-
-interface EditOp {
-  from: number;
-  to: number;
-  // Text to insert at `from` after deleting [from, to); "" for a pure delete.
-  text: string;
-}
-
-/**
- * Apply one edit per cursor in ONE transaction. Ops are processed from the END
- * of the document to the START so an earlier edit never shifts a later position
- * (mirrors `replaceAll`). Each cursor is wrapped independently: a schema
- * violation SKIPS that one cursor instead of throwing away the whole
- * transaction, so the document is never left half-applied.
- *
- * After building the transaction the new cursor positions are recomputed by
- * mapping each op's original anchor through `tr.mapping` (which also remaps any
- * concurrent changes), so carets land right after their inserted text.
- */
-function dispatchMassEdit(view: EditorView, ops: EditOp[]): boolean {
-  if (!ops.length) return false;
-
-  const { state } = view;
-  const tr = state.tr;
-  const schema = state.schema;
-
-  // Ascending by `from`; iterate reverse so earlier positions stay valid.
-  const sorted = [...ops].sort((a, b) => a.from - b.from);
-  const appliedLen: number[] = new Array(sorted.length).fill(0);
-
-  for (let i = sorted.length - 1; i >= 0; i -= 1) {
-    const { from, to, text } = sorted[i];
-    try {
-      let marks: readonly Mark[] = [];
-      if (text) {
-        if (to > from) {
-          // Carry all marks spanning the replaced range.
-          const set = new Set<Mark>();
-          tr.doc.nodesBetween(from, to, (node) => {
-            if (node.isText && node.marks) {
-              node.marks.forEach((mk) => set.add(mk));
-            }
-          });
-          marks = Array.from(set);
-        } else {
-          // Caret: continue the marks active at the insertion point.
-          marks = state.storedMarks || state.doc.resolve(from).marks();
-        }
-      }
-
-      // ONE atomic step per cursor: replaceWith covers both insert (from === to)
-      // and replace (to > from); a pure delete (empty text) uses delete. This
-      // can never leave a cursor half-applied (deleted but not re-inserted) the
-      // way a separate delete-then-insert pair could if the insert step threw.
-      if (text) {
-        tr.replaceWith(from, to, schema.text(text, marks as Mark[]));
-      } else if (to > from) {
-        tr.delete(from, to);
-      }
-
-      appliedLen[i] = text.length;
-    } catch {
-      // Per-cursor backstop (text-only MVP): drop this cursor's edit, keep the
-      // rest of the transaction intact.
-      appliedLen[i] = 0;
-    }
-  }
-
-  if (!tr.docChanged) return false;
-
-  // Recompute cursor carets from the ORIGINAL op anchors through the full map.
-  const newCursors: Range[] = sorted.map((op, i) => {
-    const start = tr.mapping.map(op.from, -1);
-    const caret = start + appliedLen[i];
-    return { from: caret, to: caret };
-  });
-
-  tr.setMeta(multiCursorPluginKey, newCursors);
-
-  // Park the native selection on the last caret so the browser draws exactly
-  // one real caret; the rest are our decoration widgets.
-  const last = newCursors[newCursors.length - 1];
-  tr.setSelection(TextSelection.create(tr.doc, last.from));
-
-  view.dispatch(tr);
-  return true;
-}
-
-function buildDeleteOps(
-  state: EditorState,
-  cursors: Range[],
-  forward: boolean,
-): EditOp[] {
-  return cursors.map((c) => {
-    // A selected range: Backspace/Delete removes the whole range.
-    if (c.to > c.from) return { from: c.from, to: c.to, text: "" };
-
-    const $pos = state.doc.resolve(c.from);
-    if (forward) {
-      // Delete: at the end of a textblock there is nothing to remove (a no-op;
-      // MVP does not merge blocks across a multi-cursor set).
-      if ($pos.parentOffset >= $pos.parent.content.size) {
-        return { from: c.from, to: c.from, text: "" };
-      }
-      return { from: c.from, to: c.from + 1, text: "" };
-    }
-    // Backspace: at the start of a textblock there is nothing to remove.
-    if ($pos.parentOffset <= 0) {
-      return { from: c.from, to: c.from, text: "" };
-    }
-    return { from: c.from - 1, to: c.from, text: "" };
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Extension
-// ---------------------------------------------------------------------------
-
-export const MultiCursor = Extension.create<unknown, MultiCursorStorage>({
-  name: "multiCursor",
-
-  addStorage() {
-    return { wholeWord: true };
-  },
-
-  addCommands() {
-    return {
-      selectAllOccurrences:
-        () =>
-        ({ editor, state, tr, dispatch }) => {
-          let term: string;
-          // A bare cursor expands to the whole word; an explicit selection is
-          // matched literally (VS Code semantics).
-          const wholeWord = state.selection.empty;
-          if (wholeWord) {
-            const word = getWordAt(state, state.selection.from);
-            if (!word) return false;
-            term = word.text;
-          } else {
-            term = state.doc.textBetween(
-              state.selection.from,
-              state.selection.to,
-            );
-          }
-          if (!term.trim()) return false;
-          editor.storage.multiCursor.wholeWord = wholeWord;
-
-          const results = findOccurrences(
-            state.doc,
-            buildTermRegex(term, wholeWord),
-          ).slice(0, MAX_CURSORS);
-          if (!results.length) return false;
-
-          if (dispatch) {
-            tr.setMeta(multiCursorPluginKey, results);
-            const last = results[results.length - 1];
-            tr.setSelection(TextSelection.create(tr.doc, last.from, last.to));
-            dispatch(tr);
-          }
-          return true;
-        },
-
-      addNextOccurrence:
-        () =>
-        ({ editor, state, tr, dispatch }) => {
-          const existing = getCursors(state);
-          let cursors: Range[];
-
-          if (!existing.length) {
-            // First press: turn the current word/selection into the one cursor.
-            let range: Range;
-            const wholeWord = state.selection.empty;
-            if (wholeWord) {
-              const word = getWordAt(state, state.selection.from);
-              if (!word) return false;
-              range = { from: word.from, to: word.to };
-            } else {
-              range = { from: state.selection.from, to: state.selection.to };
-            }
-            editor.storage.multiCursor.wholeWord = wholeWord;
-            cursors = [range];
-          } else {
-            // Subsequent press: add the next unselected occurrence of the term,
-            // matched the SAME way (whole-word vs literal) the set was seeded.
-            if (existing.length >= MAX_CURSORS) return true;
-
-            const first = existing[0];
-            const term = state.doc.textBetween(first.from, first.to);
-            if (!term.trim()) return false;
-
-            const results = findOccurrences(
-              state.doc,
-              buildTermRegex(term, editor.storage.multiCursor.wholeWord),
-            );
-            const keys = new Set(existing.map((c) => `${c.from}:${c.to}`));
-            const notSelected = results.filter(
-              (r) => !keys.has(`${r.from}:${r.to}`),
-            );
-            if (!notSelected.length) return true; // all occurrences selected
-
-            const maxTo = Math.max(...existing.map((c) => c.to));
-            const next =
-              notSelected.find((r) => r.from >= maxTo) || notSelected[0];
-            cursors = [...existing, next];
-          }
-
-          if (dispatch) {
-            tr.setMeta(multiCursorPluginKey, cursors);
-            const last = cursors[cursors.length - 1];
-            tr.setSelection(TextSelection.create(tr.doc, last.from, last.to));
-            dispatch(tr);
-          }
-          return true;
-        },
-
-      exitMultiCursor:
-        () =>
-        ({ tr, dispatch }) => {
-          if (dispatch) {
-            tr.setMeta(multiCursorPluginKey, []);
-            dispatch(tr);
-          }
-          return true;
-        },
-    };
-  },
-
-  addKeyboardShortcuts() {
-    return {
-      "Mod-Shift-l": () => {
-        this.editor.commands.selectAllOccurrences();
-        // Always consume so the browser's default is prevented.
-        return true;
-      },
-      "Mod-d": () => {
-        this.editor.commands.addNextOccurrence();
-        // Consume unconditionally to prevent the browser's Cmd/Ctrl+D bookmark.
-        return true;
-      },
-      Escape: () => {
-        // Only swallow Escape while a multi-cursor set is active; otherwise let
-        // Escape keep its other behaviours (e.g. closing dialogs).
-        if (!getCursors(this.editor.state).length) return false;
-        return this.editor.commands.exitMultiCursor();
-      },
-    };
-  },
-
-  addProseMirrorPlugins() {
-    return [
-      new Plugin<MultiCursorState>({
-        key: multiCursorPluginKey,
-
-        state: {
-          init: () => ({ cursors: [] }),
-          apply(tr, value): MultiCursorState {
-            // A command (or a mass edit) can set/clear the cursor set directly.
-            // Its cursors are already in the post-transaction coordinate space,
-            // so they take priority over remapping.
-            const meta = tr.getMeta(multiCursorPluginKey) as
-              | Range[]
-              | undefined;
-            if (meta !== undefined) {
-              return { cursors: meta.slice(0, MAX_CURSORS) };
-            }
-
-            if (!value.cursors.length) return value;
-
-            // Remap surviving cursors across ANY doc change — this covers both
-            // local edits and REMOTE Yjs edits (y-prosemirror applies remote
-            // changes as ordinary transactions, so mapping them here keeps every
-            // multi-cursor correctly positioned without special-casing collab).
-            if (tr.docChanged) {
-              // Map both edges with the SAME association (+1) so content
-              // inserted at a boundary shifts the whole cursor right and a caret
-              // (from === to) can never invert into a range.
-              const cursors = value.cursors.map((c) => ({
-                from: tr.mapping.map(c.from, 1),
-                to: tr.mapping.map(c.to, 1),
-              }));
-              return { cursors };
-            }
-
-            return value;
-          },
-        },
-
-        props: {
-          decorations(state) {
-            const st = multiCursorPluginKey.getState(state);
-            if (!st || !st.cursors.length) return DecorationSet.empty;
-
-            const decorations: Decoration[] = [];
-            st.cursors.forEach((c, i) => {
-              if (c.from === c.to) {
-                decorations.push(
-                  Decoration.widget(
-                    c.from,
-                    () => {
-                      const el = document.createElement("span");
-                      el.className = "multi-cursor__caret";
-                      return el;
-                    },
-                    { side: 0, key: `mc-caret-${i}` },
-                  ),
-                );
-              } else {
-                decorations.push(
-                  Decoration.inline(c.from, c.to, {
-                    class: "multi-cursor__selection",
-                  }),
-                );
-              }
-            });
-
-            return DecorationSet.create(state.doc, decorations);
-          },
-
-          handleTextInput(view, _from, _to, text) {
-            const cursors = getCursors(view.state);
-            if (!cursors.length) return false;
-
-            // Insert `text` at EVERY cursor in one transaction. Returning true
-            // prevents ProseMirror's own single-position insert at the native
-            // selection, so there is no double-insert there.
-            const ops = cursors.map((c) => ({
-              from: c.from,
-              to: c.to,
-              text,
-            }));
-            return dispatchMassEdit(view, ops);
-          },
-
-          handleKeyDown(view, event) {
-            const cursors = getCursors(view.state);
-            if (!cursors.length) return false;
-
-            if (event.key === "Backspace") {
-              dispatchMassEdit(view, buildDeleteOps(view.state, cursors, false));
-              return true;
-            }
-            if (event.key === "Delete") {
-              dispatchMassEdit(view, buildDeleteOps(view.state, cursors, true));
-              return true;
-            }
-
-            // Let modifier combinations (our own shortcuts, copy, etc.) through
-            // WITHOUT collapsing the set.
-            if (event.metaKey || event.ctrlKey || event.altKey) return false;
-
-            // Navigation / block keys collapse back to a single cursor, then let
-            // ProseMirror handle the movement on the native selection.
-            const COLLAPSE_KEYS = [
-              "ArrowLeft",
-              "ArrowRight",
-              "ArrowUp",
-              "ArrowDown",
-              "Home",
-              "End",
-              "PageUp",
-              "PageDown",
-              "Enter",
-              "Tab",
-            ];
-            if (COLLAPSE_KEYS.includes(event.key)) {
-              collapse(view);
-              return false;
-            }
-
-            return false;
-          },
-
-          handleDOMEvents: {
-            // A plain click exits multi-cursor (VS Code behaviour).
-            mousedown: (view) => {
-              if (getCursors(view.state).length) collapse(view);
-              return false;
-            },
-            // MVP does not drive multi-position IME — collapse on composition.
-            compositionstart: (view) => {
-              if (getCursors(view.state).length) collapse(view);
-              return false;
-            },
-          },
-        },
-      }),
-    ];
-  },
-});
-
-export default MultiCursor;

packages/editor-ext/src/lib/search-and-replace/find-occurrences.ts

@@ -1,69 +0,0 @@
-import { Range } from "@tiptap/core";
-import { Node as PMNode } from "@tiptap/pm/model";
-
-interface TextNodesWithPosition {
-  text: string;
-  pos: number;
-}
-
-/**
- * Shared "find all occurrences of a term in the doc" primitive.
- *
- * Walks every text node of the document and returns each regex match as a
- * `{ from, to }` range. Contiguous text nodes (which may differ only by marks)
- * are concatenated into a single run, so a match that spans e.g. "wo" + bold
- * "rd" is still found; runs are split by any non-text node, so a match never
- * crosses a node boundary. Whitespace-only matches are ignored.
- *
- * This is used by BOTH search-and-replace (highlight/replace) and multi-cursor
- * (turn occurrences into active cursors) so the two stay behaviourally in sync.
- * Extracted verbatim from the original `processSearches` walk.
- */
-export function findOccurrences(doc: PMNode, searchTerm: RegExp): Range[] {
-  const results: Range[] = [];
-
-  if (!searchTerm) return results;
-
-  let textNodesWithPosition: TextNodesWithPosition[] = [];
-  let index = 0;
-
-  doc?.descendants((node, pos) => {
-    if (node.isText) {
-      if (textNodesWithPosition[index]) {
-        textNodesWithPosition[index] = {
-          text: textNodesWithPosition[index].text + node.text,
-          pos: textNodesWithPosition[index].pos,
-        };
-      } else {
-        textNodesWithPosition[index] = {
-          text: `${node.text}`,
-          pos,
-        };
-      }
-    } else {
-      index += 1;
-    }
-  });
-
-  textNodesWithPosition = textNodesWithPosition.filter(Boolean);
-
-  for (const element of textNodesWithPosition) {
-    const { text, pos } = element;
-    const matches = Array.from(text.matchAll(searchTerm)).filter(
-      ([matchText]) => matchText.trim(),
-    );
-
-    for (const m of matches) {
-      if (m[0] === "") break;
-
-      if (m.index !== undefined) {
-        results.push({
-          from: pos + m.index,
-          to: pos + m.index + m[0].length,
-        });
-      }
-    }
-  }
-
-  return results;
-}

packages/editor-ext/src/lib/search-and-replace/index.ts

@@ -1,4 +1,3 @@
 import { SearchAndReplace } from './search-and-replace'
 export * from './search-and-replace'
-export * from './find-occurrences'
 export default SearchAndReplace

packages/editor-ext/src/lib/search-and-replace/search-and-replace.ts

@@ -29,7 +29,6 @@ import {
   type Transaction,
 } from "@tiptap/pm/state";
 import { Node as PMNode, Mark } from "@tiptap/pm/model";
-import { findOccurrences } from "./find-occurrences";
 
 declare module "@tiptap/core" {
   interface Storage {
@@ -77,6 +76,11 @@ declare module "@tiptap/core" {
   }
 }
 
+interface TextNodesWithPosition {
+  text: string;
+  pos: number;
+}
+
 const getRegex = (
   s: string,
   disableRegex: boolean,
@@ -100,6 +104,10 @@ function processSearches(
   resultIndex: number,
 ): ProcessedSearches {
   const decorations: Decoration[] = [];
+  const results: Range[] = [];
+
+  let textNodesWithPosition: TextNodesWithPosition[] = [];
+  let index = 0;
 
   if (!searchTerm) {
     return {
@@ -108,8 +116,43 @@ function processSearches(
     };
   }
 
-  // Shared find-all-occurrences primitive (also used by multi-cursor).
-  const results: Range[] = findOccurrences(doc, searchTerm);
+  doc?.descendants((node, pos) => {
+    if (node.isText) {
+      if (textNodesWithPosition[index]) {
+        textNodesWithPosition[index] = {
+          text: textNodesWithPosition[index].text + node.text,
+          pos: textNodesWithPosition[index].pos,
+        };
+      } else {
+        textNodesWithPosition[index] = {
+          text: `${node.text}`,
+          pos,
+        };
+      }
+    } else {
+      index += 1;
+    }
+  });
+
+  textNodesWithPosition = textNodesWithPosition.filter(Boolean);
+
+  for (const element of textNodesWithPosition) {
+    const { text, pos } = element;
+    const matches = Array.from(text.matchAll(searchTerm)).filter(
+      ([matchText]) => matchText.trim(),
+    );
+
+    for (const m of matches) {
+      if (m[0] === "") break;
+
+      if (m.index !== undefined) {
+        results.push({
+          from: pos + m.index,
+          to: pos + m.index + m[0].length,
+        });
+      }
+    }
+  }
 
   for (let i = 0; i < results.length; i += 1) {
     const r = results[i];