fix(offline): address PR #120 review (cross-user leak, Yjs title dup, i18n, docs, guards)

Security:
- Clear the offline IndexedDB cache on sign-in (not only logout) so a previous
  user's persisted query cache and Yjs page bodies cannot leak to the next user
  on a shared device when the prior session ended without an explicit logout.

Regressions:
- Remove the double Yjs title write from the AI title-generation path: the title
  editor is bound to the Yjs `title` fragment and the server REST update reseeds
  it, so the local setContent raced that reseed and doubled/garbled the title.

Conventions / i18n / docs:
- Remove the unused showAiMenuAtom.
- Register the 3 offline-fallback strings in en-US and ru-RU.
- Fix the 5 broken links to the nonexistent docs/offline-sync-plan.md.

Stability / simplification:
- warmInfiniteAll now reports truncation (returns false) when it hits maxPages
  with a cursor still pending instead of silently succeeding.
- space-tree make-offline catch logs the raw error and surfaces the real cause.
- Move the Offline/Mobile/CORS CHANGELOG entries from the released 0.93.0 section
  into [Unreleased] (CORS is a documented breaking change).
- Drop the pass-through sync-flag forwarders in use-page-collab-providers; set the
  atoms directly.
- Collapse the three isSwaggerEnabled true-cases into it.each.

Tests / architecture:
- Extract collabTokenNeedsRefresh (pure) and cover all four token states.
- Extract shouldPropagateTitleChange and cover the collab-origin skip; add a
  TitleEditor render test for the static-h1 vs collaborative-editor switch.
- Add a use-auth test asserting the sign-in cache purge runs before login.
- Add an OFFLINE_PERSIST_ROOTS guard test asserting every persisted root maps to
  an exported query-key factory; route make-offline's currentUser warm through a
  new userKeys factory.

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

.env.example

@@ -92,6 +92,19 @@ IFRAME_EMBED_ALLOWED=false
 # Example: https://intranet.example.com,https://portal.example.com
 IFRAME_ALLOWED_ORIGINS=
 
+# Comma-separated list of additional origins allowed to call the API via CORS.
+# The APP_URL origin and native mobile (Capacitor) origins are always allowed.
+# Leave empty for a same-origin (web-only) deployment.
+CORS_ALLOWED_ORIGINS=
+
+# Expose OpenAPI/Swagger docs at /api/docs (development/debugging aid only).
+SWAGGER_ENABLED=false
+
+# Capacitor (mobile shell): hosted client URL loaded by the iOS shell so the
+# AGPL web client is NOT bundled into the .ipa (see docs/mobile-app-plan.md §9).
+# Leave empty for Android bundled mode / local development.
+CAP_SERVER_URL=
+
 # Enable debug logging in production (default: false)
 DEBUG_MODE=false
 
@@ -203,42 +216,3 @@ MCP_DOCMOST_PASSWORD=
 # FAILS CLOSED if Redis is unavailable (default: 1,000,000 tokens per workspace
 # per rolling day).
 # SHARE_AI_WORKSPACE_TOKEN_BUDGET_PER_DAY=1000000
-
-# --- GIT-SYNC (native two-way Docmost <-> git Markdown sync) ---
-# Master switch. Off by default. When 'true', GIT_SYNC_SERVICE_USER_ID below is
-# REQUIRED (the service account that git-originated create/move/rename/delete are
-# attributed to) — the server refuses to boot with sync enabled and no user id.
-# GIT_SYNC_ENABLED=false
-#
-# Serve the per-space vaults over smart-HTTP (the /git host). Defaults to
-# GIT_SYNC_ENABLED when unset.
-# GIT_SYNC_HTTP_ENABLED=false
-#
-# REQUIRED when GIT_SYNC_ENABLED=true: id of the user that git-originated page
-# operations (create / move / rename / delete) are attributed to.
-# GIT_SYNC_SERVICE_USER_ID=
-#
-# Where the per-space working vaults live (non-bare repos; the engine needs a
-# working tree).
-# Defaults to "<DATA_DIR or ./data>/git-sync".
-# GIT_SYNC_DATA_DIR=
-#
-# Optional remote URL template to mirror each space's vault to (e.g. a git host).
-# The literal "{spaceId}" is substituted per-space, so each space mirrors to its
-# OWN remote — e.g. git@host:vault-{spaceId}.git. Without the placeholder every
-# space would point at one remote. Leave unset to keep vaults local-only.
-# GIT_SYNC_REMOTE_TEMPLATE=
-#
-# Poll-safety interval in ms — the cadence of the background reconcile cycle
-# (default: 15000).
-# GIT_SYNC_POLL_INTERVAL_MS=15000
-#
-# Debounce window in ms for collapsing bursts of page edits into one sync cycle
-# (default: 2000).
-# GIT_SYNC_DEBOUNCE_MS=2000
-#
-# Watchdog timeout in ms for the spawned `git http-backend` process serving a
-# git smart-HTTP push (default: 120000). A stalled/hung receive-pack is killed
-# after this deadline so it cannot hold the per-space lock forever.
-# GIT_SYNC_BACKEND_TIMEOUT_MS=120000
-#

.github/workflows/test.yml

@@ -68,13 +68,6 @@ jobs:
       - name: Build editor-ext
         run: pnpm --filter @docmost/editor-ext build
 
-      # git-sync and mcp are no longer committed in built form (build/ is
-      # gitignored), so CI must compile them: the server resolves both via their
-      # built build/index.js. The server pretest also builds them, but building
-      # here keeps it explicit and independent of pnpm lifecycle ordering.
-      - name: Build git-sync and mcp
-        run: pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build
-
       - name: Run unit tests
         run: pnpm -r test
 

.gitignore

@@ -5,12 +5,6 @@ data
 # compiled output
 /dist
 /node_modules
-# workspace package node_modules (pnpm symlinks — never commit; they bake
-# machine-local store paths) and the git-sync compiled output (built in CI/Docker
-# via `pnpm build`, never committed, so src/ and prod can never silently diverge).
-packages/*/node_modules/
-packages/git-sync/build/
-packages/mcp/build/
 
 # Logs
 logs
@@ -55,3 +49,8 @@ lerna-debug.log*
 
 # Self-hosted VAD / onnxruntime-web assets (copied from node_modules at dev/build time)
 apps/client/public/vad/
+
+# Capacitor native platform projects (generated locally via 'npx cap add ios|android')
+/ios
+/android
+.capacitor

AGENTS.md

@@ -182,7 +182,7 @@ tea issues create --repo vvzvlad/gitmost --labels feature \
 
 ## Monorepo layout
 
-pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Five workspace packages:
+pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 
 | Path | Name | Stack | Role |
 | --- | --- | --- | --- |
@@ -190,7 +190,6 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Five workspace packages:
 | `apps/client` | `client` | React 18 + Vite + Mantine 8 + TanStack Query + Jotai | SPA frontend |
 | `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
 | `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Does **not** import `editor-ext` — it keeps its own vendored mirror of the schema in `packages/mcp/src/lib/` |
-| `packages/git-sync` | `@docmost/git-sync` | Tiptap/ProseMirror, Yjs, git | Pure ProseMirror↔Markdown converter plus the two-way Docmost↔git Markdown sync engine. Bundled into the server (loaded over the ESM bridge), built in CI and the Dockerfile. Does **not** import `editor-ext` — it keeps its own vendored mirror of the document schema (kept in sync with `editor-ext`). |
 
 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
 
@@ -244,10 +243,8 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 
 The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes `robots.txt`, public share pages, and `mcp` from the prefix). A `preHandler` hook enforces that a resolved `workspaceId` exists for most `/api` routes (multi-tenant by hostname/subdomain via `DomainMiddleware`). Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
 
-Two routes are mounted **outside** the `/api` prefix at the root, as raw Fastify routes that bypass the Nest pipeline (so neither `DomainMiddleware` nor `ThrottlerGuard` runs for them — each resolves the workspace and throttles itself): `/mcp` (the embedded MCP server, see below) and `/git/<spaceId>.git/...` (the git-sync smart-HTTP host, see below). Both share `mcp-auth.helpers.ts` (HTTP-Basic parsing, `FailedLoginLimiter`, `clientIp`) and the common `resolveRequestWorkspace` helper.
-
 ### Module structure (server)
-`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`, `git-sync`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
+`AppModule` wires integration modules (`integrations/*`: storage [local/S3/Azure], mail, queue [BullMQ on Redis], security, telemetry, throttle, `mcp`, `ai`) plus `CoreModule`, `DatabaseModule`, and `CollaborationModule`. `CoreModule` (`core/*`) holds the domain modules: `page`, `space`, `comment`, `workspace`, `user`, `auth`, `group`, `attachment`, `search`, `share`, `ai-chat`, etc. Each domain module follows NestJS controller → service → repo layering; DB repos live under `database/repos` and are injected app-wide from the global `DatabaseModule`.
 
 **EE removal artifact:** `app.module.ts` still contains a `try/require('./ee/ee.module')` stub. That path no longer exists, so the require fails and is swallowed (it only hard-exits when `CLOUD === 'true'`). Treat EE as gone — do not add code that depends on it.
 
@@ -257,22 +254,16 @@ Two routes are mounted **outside** the `/api` prefix at the root, as raw Fastify
 - **Redis** backs caching, the BullMQ queues, the WebSocket Socket.IO adapter, and collaboration sync.
 
 ### The two AI subsystems (the main fork additions)
-1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (39 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
+1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (38 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
 2. **AI agent chat** (`core/ai-chat/` server + `apps/client/src/features/ai-chat/` client). A built-in agent over the wiki using the Vercel **AI SDK** (`ai`, `@ai-sdk/*`) against any OpenAI-compatible provider configured per workspace (`integrations/ai/` — credentials encrypted at rest via `integrations/crypto`, stored in `ai_provider_credentials`). Key pieces:
    - `core/ai-chat/tools/` — the agent's ~40 read+write tools. Every tool runs under the **calling user's** CASL permissions via a per-user loopback access token (`docmost-client.loader.ts`), so the agent can never exceed what the user could do. Only **reversible** operations are exposed (page history + trash; no permanent delete). Agent edits get an "AI agent" provenance badge in page history (`20260616T130000-agent-provenance` migration).
    - `core/ai-chat/embedding/` — RAG indexer + a BullMQ consumer on `AI_QUEUE` that embeds pages into `page_embeddings` (vector search), complementing Postgres full-text search. Pages are (re)indexed on edit; `AI_EMBEDDING_TIMEOUT_MS` bounds a hung embeddings endpoint.
    - `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
 
-### Git-sync (native two-way Docmost ↔ git Markdown sync)
-`integrations/git-sync/` (`GitSyncModule`) + the vendored pure engine in `packages/git-sync`. Off by default; gated by the `GIT_SYNC_ENABLED` master switch (and `GIT_SYNC_SERVICE_USER_ID`, the account git-originated writes are attributed to). Per-space opt-in via `space.settings.gitSync.enabled`, with a second per-space toggle `space.settings.gitSync.autoMergeConflicts` that changes PUSH behavior for a still-conflicted page (one carrying `<<<<<<<`/`>>>>>>>` markers): **off (the safe default)** records a per-page failure and holds the refs so the user resolves the git conflict first (markers never reach Docmost); **on** strips the marker lines and pushes both sides' content. Each enabled space gets an on-disk working "vault" repo; the `GitSyncOrchestrator` runs a debounced + poll-backstop reconcile cycle (PULL Docmost→vault, PUSH vault→Docmost) under a per-space Redis leader lock + in-process mutex (`SpaceLockService`). Writes go through the collaboration layer (so concurrent human edits aren't clobbered) and are stamped `lastUpdatedSource = 'git-sync'` for the listener loop-guard. The in-process `setInterval` orchestration + best-effort lock (no fencing tokens) is a known multi-replica limitation — BullMQ + fencing is the documented future direction.
-
-- **`/git` smart-HTTP host** (`integrations/git-sync/http/`, gated additionally by `GIT_SYNC_HTTP_ENABLED`, which defaults to `GIT_SYNC_ENABLED`): a raw root-mounted Fastify route `/git/<spaceId>.git/...` (registered in `main.ts`, NOT under `/api`) that bridges `git clone`/`fetch`/`push` to `git http-backend`. It authenticates HTTP Basic against `AuthService` (throttled by a `FailedLoginLimiter` mirroring the `/mcp` path), authorizes via `SpaceAbilityFactory` (read = fetch, Manage = push), and gates existence so a non-member gets the SAME 404 as a missing/sync-disabled space (never 403 — that would leak space existence). A push runs the receive-pack under the space lock, then a reconcile cycle.
-- **Schema mirror:** `packages/git-sync/src/lib/docmost-schema.ts` is one of the **three** hand-synced copies of the Tiptap document schema (see Client structure) — keep it in lockstep with `editor-ext` (canonical) and `packages/mcp`.
-
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
 - **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
-- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, import/export) — editor schema changes often need to be made in `editor-ext`, not just the client. Note neither `packages/mcp` nor `packages/git-sync` depends on `editor-ext`; each carries its own mirrored copy of the schema. There are now **three** independent copies (`editor-ext` is canonical, plus `packages/mcp` and `packages/git-sync`), so keep all three in sync manually when the document schema changes.
+- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, import/export) — editor schema changes often need to be made in `editor-ext`, not just the client. Note `packages/mcp` does *not* depend on `editor-ext`; it carries its own mirrored copy of the schema, so keep the two in sync manually when the document schema changes.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
 

CHANGELOG.md

@@ -12,20 +12,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Native two-way Docmost ↔ git Markdown sync.** Opt-in per space (Space
-  settings → a git-sync toggle, plus an `autoMergeConflicts` toggle that controls
-  whether a still-conflicted page is held back or pushed with its conflict
-  markers stripped): each enabled space is mirrored to an on-disk git "vault" of
-  Markdown files and reconciled in both directions (Docmost → vault and vault →
-  Docmost) on a debounced + poll-backstop cycle, under a per-space lock, writing
-  through the collaboration layer so concurrent human edits aren't clobbered.
-  Git-originated changes are attributed to a configurable service account and
-  carry a "git-sync" provenance badge in page history. Optionally exposes a `/git`
-  smart-HTTP host so you can `git clone`/`fetch`/`push` a space directly (HTTP
-  Basic auth, space-permission authorized). Off by default and configured via the
-  `GIT_SYNC_*` environment variables, including `GIT_SYNC_ENABLED`,
-  `GIT_SYNC_SERVICE_USER_ID`, and `GIT_SYNC_HTTP_ENABLED` (see `.env.example`).
-  (#119)
 - **Quick-create regular and temporary notes from the Home and Space screens.**
   The Home screen now shows a second action next to "New note" that creates a
   *temporary* note (one that auto-moves to Trash after the workspace lifetime),
@@ -55,50 +41,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `AI_AGENT_ROLES_CATALOG_URL` env var — an `http(s)://` base URL to the
   catalog's raw files; the image ships a per-branch default baked in CI, and it
   can be overridden at runtime via the env var (see `.env.example`). (#222)
-- **Author footnotes inline from an agent, and deterministic server-side footnote
-  canonicalization on every non-editor write path.** A new MCP `insert_footnote`
-  tool places a footnote at a body anchor by content only — the agent supplies
-  WHERE (anchor text) and WHAT (markdown); the number and the bottom
-  `footnotesList` are derived server-side, so an agent can never assign a number,
-  edit the list, or desync, and a same-content note reuses one definition. Under
-  the hood, the editor's footnote-integrity invariant (one trailing list,
-  numbering by first reference, no orphans/duplicates, no raw `[^id]`) is now
-  enforced as a pure `canonicalizeFootnotes(doc)` on the FULL-document write paths
-  that bypass the editor's plugins: server markdown/HTML import, `PageService`
-  create and full-document (`replace`) updates, the client markdown paste, and the
-  MCP markdown page-import / `update_page` (markdown) / `update_page_json` /
-  `docmost_transform` / `insert_footnote` / `copy_page_content` paths. It is
-  idempotent (a no-op once canonical) and is deliberately NOT applied to
-  append/prepend fragments, nor to COMMENT bodies — a comment may legitimately
-  contain a standalone footnote definition, which canonicalization would drop.
-  (#228)
+
+- **Offline reading support**: opened pages, their sidebar tree, breadcrumb
+  children, and comments are cached in IndexedDB (TanStack Query persister plus
+  `y-indexeddb` for the page's Yjs document), and a PWA service worker
+  (vite-plugin-pwa) serves an app shell so previously opened pages stay readable
+  offline. The offline cache (persisted query cache, Yjs page documents, and the
+  service-worker API cache) is cleared on logout AND on sign-in so a previous
+  user's private data does not remain in the browser.
+- **Mobile bootstrap**: a `returnToken` opt-in on login so native/mobile clients
+  can request the access JWT in the response body (`data.authToken`) in addition
+  to the httpOnly cookie (the web client stays cookie-only); an optional
+  OpenAPI/Swagger UI at `/api/docs` gated by `SWAGGER_ENABLED` (off by default);
+  and new env vars `CORS_ALLOWED_ORIGINS`, `SWAGGER_ENABLED`, `CAP_SERVER_URL`.
 
 ### Changed
 
-- **Enabling a public share no longer auto-shares the whole sub-tree.** Turning
-  a page "Shared to web" now defaults to the page alone; descendant pages become
-  public only when you explicitly turn on the dedicated "Include sub-pages"
-  toggle. Previously the create call defaulted to including sub-pages, silently
-  exposing every child of a freshly shared page. (#216)
+- **CORS is now an explicit allowlist** (replaces the previous unconfigured
+  `app.enableCors()`). The same-origin web client is unaffected, but any
+  separately-hosted cross-domain client must now be listed in
+  `CORS_ALLOWED_ORIGINS` (native Capacitor/Ionic/localhost WebView origins are
+  allowed automatically). Requests with no `Origin` header (server-to-server)
+  are still allowed.
 
 ### Fixed
 
-- **Internal links in exported Markdown no longer lose their visible text.** A
-  link whose target page name had no file extension (e.g. a bare title) was
-  collapsed to empty text during export, producing an unclickable, label-less
-  link; the page name is now preserved. (#204)
-- **Deep pages no longer render a blank breadcrumb while the sidebar tree loads.**
-  The breadcrumb now falls back to the page's own ancestor chain (fetched
-  independently of the lazily-built sidebar tree) so a deep page resolves its
-  trail immediately; navigating away no longer leaves the previously-viewed
-  page's breadcrumb showing until the new one resolves. (#206, #218)
-- **Pasted GitHub-style callouts (`> [!NOTE]` …) now convert to real callouts.**
-  GitHub admonition blocks pasted as Markdown are recognized and rendered as
-  callout blocks instead of plain block-quotes. (#192)
-- **The editor stays read-only until collaboration has synced.** While a page is
-  connecting, the body is shown as a non-editable static view with a
-  "Connecting… (read-only)" banner, so edits typed before the document finishes
-  syncing can no longer be silently dropped. (#218)
 - **A shared page now keeps EXACTLY ONE custom address (`/l/:alias`).** Editing a
   page's vanity slug previously inserted a second `share_aliases` row instead of
   renaming the existing one, leaving the old `/l/<old>` link live forever and
@@ -118,20 +85,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   enabled, so the existing reassign-confirm flow (`409 ALIAS_REASSIGN_REQUIRED` →
   "Move custom address?") is discoverable instead of reading as terminal. (#227)
 
-### Security
-
-- **The anonymous public-share page payload is trimmed to an explicit allowlist.**
-  The `/shares/page-info` route (the only unauthenticated path serializing a
-  page + its share) now returns only the fields the public renderer needs;
-  internal metadata — creator/last-updater/contributor ids, space/workspace ids,
-  AI/source bookkeeping, lock/template flags, parent/position and raw timestamps
-  — is no longer exposed to anonymous viewers. (#218)
-- **A forged or mismatched share id can no longer render a page off its slug
-  alone.** When the public URL carries a share id/key, the page must be reachable
-  through that exact share (its own share or an ancestor `includeSubPages`
-  share); any other value now returns the generic "not found" instead of
-  serving the page. (#218)
-
 ## [0.94.0] - 2026-06-26
 
 This release makes AI chat durable and fast: assistant turns are persisted to

Dockerfile

@@ -17,9 +17,8 @@ RUN pnpm build
 
 FROM base AS installer
 
-# git: required by the git-sync VaultGit (shells out to git)
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends curl bash git \
+  && apt-get install -y --no-install-recommends curl bash \
   && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -39,14 +38,6 @@ COPY --from=builder /app/packages/editor-ext/dist /app/packages/editor-ext/dist
 COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
 COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
 COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
-# git-sync: the server loads @docmost/git-sync at runtime via the loader
-# (git-sync.loader.ts), which deliberately does NOT `require()` it — the package is
-# ESM-only, so the loader uses `require.resolve` + a dynamic `import()`. Without
-# these copied build artifacts that resolve/import fails and the server crashes on
-# first use. Built fresh by the builder's `pnpm build` (nx builds the package's tsc
-# `build` target).
-COPY --from=builder /app/packages/git-sync/build /app/packages/git-sync/build
-COPY --from=builder /app/packages/git-sync/package.json /app/packages/git-sync/package.json
 
 # Copy root package files
 COPY --from=builder /app/package.json /app/package.json

README.md

@@ -34,7 +34,7 @@ The goal of the fork is a **100% open, AGPL-only build with no Enterprise-Editio
 | --- | --- |
 | **EE code removed** | Stripped all client and server Enterprise-Edition code; ships as a clean community/AGPL build with no license checks. |
 | **Comment resolution** | Re-implemented from scratch as a community feature (resolve / re-open with Open/Resolved tabs). No EE code reused, available to anyone who can comment. |
-| **Embedded MCP server** | A community MCP server (`@docmost/mcp`, 39 tools) is served over HTTP at `/mcp` — no enterprise license required. Replaces the removed license-gated EE MCP. |
+| **Embedded MCP server** | A community MCP server (`@docmost/mcp`, 38 tools) is served over HTTP at `/mcp` — no enterprise license required. Replaces the removed license-gated EE MCP. |
 | **AI agent chat** | Built-in AI agent chat over your wiki, written from scratch as a community feature — no enterprise license. The agent reads and edits pages on your behalf (scoped to your permissions), with full-text + vector (RAG) search and optional web access via external MCP servers. |
 | **Rebranding** | App logo / name changed from *Docmost* to *Gitmost*. |
 | **Compact page tree** | Default page-tree indentation reduced from 16px to 8px per nesting level. |
@@ -44,7 +44,7 @@ The goal of the fork is a **100% open, AGPL-only build with no Enterprise-Editio
 ### Embedded MCP server
 
 Gitmost has **our own MCP server** — [docmost-mcp](https://github.com/vvzvlad/docmost-mcp),
-which we wrote — **built directly into the app** and served at `/mcp`. It exposes **39
+which we wrote — **built directly into the app** and served at `/mcp`. It exposes **38
 agent-native tools**: surgical per-block edits (patch / insert / delete by id),
 structure-preserving find/replace, scripted `(doc) => doc` transforms with a dry-run diff,
 structured table editing, version history with diff / restore, comments, images and share
@@ -60,7 +60,7 @@ every little fix. And it needs no enterprise license.
 | | **Gitmost `/mcp` (our docmost-mcp)** | Docmost's built-in MCP |
 | --- | :---: | :---: |
 | **Enterprise license** | Not required | Required |
-| **Tools** | 39, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
+| **Tools** | 38, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
 | **Per-block edits / find-replace / scripted transforms** | ✅ | — |
 | **Structured table editing, version diff / restore** | ✅ | — |
 | **Comments, images, share links** | ✅ | — |

README.ru.md

@@ -33,7 +33,7 @@
 | --- | --- |
 | **Удалён EE-код** | Вырезан весь код Enterprise-редакции на клиенте и сервере; это чистая community/AGPL-сборка без лицензионных проверок. |
 | **Резолв комментариев** | Переписан с нуля как community-функция (резолв / переоткрытие с вкладками «Открытые» / «Решённые»). EE-код не используется, доступно любому, кто может комментировать. |
-| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 39 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
+| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 38 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
 | **Чат с AI-агентом** | Встроенный чат с AI-агентом по содержимому вики, написанный с нуля как community-функция — без enterprise-лицензии. Агент читает и редактирует страницы от вашего имени (в рамках ваших прав), с полнотекстовым + векторным (RAG) поиском и опциональным доступом в интернет через внешние MCP-серверы. |
 | **Ребрендинг** | Логотип / название приложения изменены с *Docmost* на *Gitmost*. |
 | **Компактное дерево страниц** | Отступ дерева страниц по умолчанию уменьшен с 16px до 8px на уровень вложенности. |
@@ -44,7 +44,7 @@
 
 В Gitmost есть **наш собственный MCP-сервер** — [docmost-mcp](https://github.com/vvzvlad/docmost-mcp),
 который мы написали сами, — **встроенный прямо в приложение** и доступный на `/mcp`. Он даёт
-**39 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
+**38 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
 по id), find/replace с сохранением структуры, скриптовые трансформации `(doc) => doc` с
 предпросмотром диффа, структурное редактирование таблиц, история версий с диффом /
 восстановлением, комментарии, изображения и ссылки на шаринг — всё применяется через слой
@@ -60,7 +60,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 | | **`/mcp` в Gitmost (наш docmost-mcp)** | Родной MCP у Docmost |
 | --- | :---: | :---: |
 | **Enterprise-лицензия** | Не нужна | Нужна |
-| **Инструменты** | 39, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
+| **Инструменты** | 38, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
 | **Правки по блокам / find-replace / скриптовые трансформации** | ✅ | — |
 | **Структурное редактирование таблиц, дифф / восстановление версий** | ✅ | — |
 | **Комментарии, изображения, ссылки на шаринг** | ✅ | — |

agent-roles-catalog/bundles/editorial/en.json

@@ -24,8 +24,8 @@
       "slug": "fact-checker",
       "emoji": "🔍",
       "name": "Fact-checker",
-      "description": "Verifies facts, figures, dates, names, and quotes with web search. Finds errors and flags the doubtful or unverifiable — with a verdict and a source.",
-      "instructions": "You are a fact-checker at Gitmost, verifying the factual accuracy of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). You have access to web search — use it to verify. Communicate with the user in English.\n\nWHAT YOU DO\nVerify every checkable claim: names, titles, positions; dates, chronology, sequence; numbers, statistics, proportions, units; quotations and their attribution; technical facts, terms, versions, specifications; causal and logical claims, and internal consistency. Your job is to find errors and doubtful spots, not to confirm what is already correct.\n\nRemember the weakness of machine text: an LLM does not fact-check and will confidently state falsehoods, invent non-existent terms, conflate near-neighbor entities (e.g. claim \"handwriting understanding\" where it was template-based recognition), and insert pseudo-precise numbers. Be especially wary of smoothly written but unverifiable claims.\n\nVERDICTS (for problem claims only)\nDon't comment on correct facts — don't write or mark that a fact is right or confirmed. Leave a verdict only where there is a problem:\n- [Incorrect] — the fact is wrong; give the correction and the source.\n- [Unverified] — probably correct but not confirmed; say what's needed to verify.\n- [Unverifiable] — the claim can't be checked in principle (no source, too vague).\n- [Opinion] — not a factual claim, not subject to checking.\n\nSource rule: rely on primary sources (original data, documentation, official site), not retellings. One primary source or two independent secondary sources is a reasonable minimum. Cite the source in the comment.\n\nWHAT YOU DON'T DO\n- Don't fix style, grammar, punctuation, structure, or typography — those are other roles.\n- Don't rewrite the text. You refute or flag a problem — the decision is the author's.\n- Don't judge opinions or subjective phrasing as facts.\n- Don't write or comment that a fact is right or confirmed: your job is to find errors, not to confirm facts.\n- Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable].\n\nHOW TO LEAVE COMMENTS\nYou don't edit the text directly. For each problem claim (an error, a doubt, an unverifiable statement), select the span via the MCP tool and leave a comment; leave no comment on correct facts. Open the comment with the label `[Facts]`, then the verdict, the correction (if any), and the source. Tag severity:\n- [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.\n- [Major] — a doubtful or unconfirmed claim that needs a source.\n- [Minor] — a small correction, or false precision worth rounding or confirming.\n\nTONE\nNeutral and precise. Don't argue with the author's stance — check facts, not views.\n\nWHEN UNSURE\nBetter to honestly flag \"can't confirm\" than to give a false confirmation.",
+      "description": "Verifies facts, figures, dates, names, and quotes with web search. Confirms, corrects, or flags the unverifiable — with a verdict and a source.",
+      "instructions": "You are a fact-checker at Gitmost, verifying the factual accuracy of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). You have access to web search — use it to verify. Communicate with the user in English.\n\nWHAT YOU DO\nVerify every checkable claim: names, titles, positions; dates, chronology, sequence; numbers, statistics, proportions, units; quotations and their attribution; technical facts, terms, versions, specifications; causal and logical claims, and internal consistency.\n\nRemember the weakness of machine text: an LLM does not fact-check and will confidently state falsehoods, invent non-existent terms, conflate near-neighbor entities (e.g. claim \"handwriting understanding\" where it was template-based recognition), and insert pseudo-precise numbers. Be especially wary of smoothly written but unverifiable claims.\n\nA VERDICT FOR EACH CLAIM\n- [Verified] — the fact is correct; cite the source.\n- [Incorrect] — the fact is wrong; give the correction and the source.\n- [Unverified] — probably correct but not confirmed; say what's needed to verify.\n- [Unverifiable] — the claim can't be checked in principle (no source, too vague).\n- [Opinion] — not a factual claim, not subject to checking.\n\nSource rule: rely on primary sources (original data, documentation, official site), not retellings. One primary source or two independent secondary sources is a reasonable minimum. Cite the source in the comment.\n\nWHAT YOU DON'T DO\n- Don't fix style, grammar, punctuation, structure, or typography — those are other roles.\n- Don't rewrite the text. You confirm, correct, or flag — the decision is the author's.\n- Don't judge opinions or subjective phrasing as facts.\n- Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable]. Never confirm a fact you don't know.\n\nHOW TO LEAVE COMMENTS\nYou don't edit the text directly. For each checked claim, select the span via the MCP tool and leave a comment. Open the comment with the label `[Facts]`, then the verdict, the correction (if any), and the source. Tag severity:\n- [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.\n- [Major] — a doubtful or unconfirmed claim that needs a source.\n- [Minor] — a small correction, or false precision worth rounding or confirming.\n\nTONE\nNeutral and precise. Don't argue with the author's stance — check facts, not views.\n\nWHEN UNSURE\nBetter to honestly flag \"can't confirm\" than to give a false confirmation.",
       "autoStart": true,
       "launchMessage": "Take the current page into work. If there is none, ask the user which page to work on."
     },

agent-roles-catalog/index.json

@@ -12,7 +12,7 @@
       "roles": [
         { "slug": "structural-editor", "version": 2 },
         { "slug": "line-editor", "version": 2 },
-        { "slug": "fact-checker", "version": 3 },
+        { "slug": "fact-checker", "version": 2 },
         { "slug": "proofreader", "version": 3 },
         { "slug": "narrator", "version": 1 }
       ]

agent-roles-catalog/scripts/content-hashes.json

@@ -1,7 +1,7 @@
 {
   "fact-checker": {
-    "version": 3,
-    "hash": "a94931fbd20272570a588c72159ac9e48a89c99bd8f718449cda5e7ca4280fdf"
+    "version": 2,
+    "hash": "d7ad1dae07d6f4321e7d40c5b36259dbf930264d748834809c4fb77294bf72e3"
   },
   "line-editor": {
     "version": 2,

apps/client/index.html

@@ -10,6 +10,7 @@
     <meta name="theme-color" content="#0E1117" media="(prefers-color-scheme: dark)" />
     <meta name="theme-color" content="#f6f7f9" media="(prefers-color-scheme: light)" />
     <link rel="manifest" href="/manifest.json" />
+    <link rel="apple-touch-icon" href="/icons/app-icon-192x192.png" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="apple-touch-fullscreen" content="yes" />
     <meta name="apple-mobile-web-app-title" content="Gitmost" />

apps/client/package.json

@@ -33,7 +33,9 @@
     "@slidoapp/emoji-mart-data": "1.2.4",
     "@slidoapp/emoji-mart-react": "1.1.5",
     "@tabler/icons-react": "3.40.0",
+    "@tanstack/query-async-storage-persister": "5.90.17",
     "@tanstack/react-query": "5.90.17",
+    "@tanstack/react-query-persist-client": "5.90.17",
     "@tanstack/react-virtual": "3.13.24",
     "ai": "6.0.207",
     "alfaaz": "1.1.0",
@@ -45,6 +47,7 @@
     "highlightjs-sap-abap": "0.3.0",
     "i18next": "25.10.1",
     "i18next-http-backend": "3.0.6",
+    "idb-keyval": "6.2.5",
     "jotai": "2.18.1",
     "jotai-optics": "0.4.0",
     "js-cookie": "3.0.7",
@@ -95,6 +98,7 @@
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.1",
     "vite": "8.0.5",
+    "vite-plugin-pwa": "1.3.0",
     "vitest": "4.1.6"
   }
 }

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

@@ -464,6 +464,18 @@
   "Move page": "Move page",
   "Move page to a different space.": "Move page to a different space.",
   "Real-time editor connection lost. Retrying...": "Real-time editor connection lost. Retrying...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Offline — changes are saved locally and will sync when you reconnect",
+  "Syncing changes…": "Syncing changes…",
+  "All changes synced": "All changes synced",
+  "Update available": "Update available",
+  "Reload": "Reload",
+  "Make available offline": "Make available offline",
+  "Saving page for offline use...": "Saving page for offline use...",
+  "Page is now available offline": "Page is now available offline",
+  "Failed to make page available offline": "Failed to make page available offline",
+  "You're offline": "You're offline",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+  "Retry": "Retry",
   "Table of contents": "Table of contents",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Add headings (H1, H2, H3) to generate a table of contents.",
   "Share": "Share",
@@ -1217,8 +1229,6 @@
   "Ran tool {{name}}": "Ran tool {{name}}",
   "AI-agent": "AI-agent",
   "Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{name}}",
-  "Git sync": "Git sync",
-  "Synced from Git on behalf of {{name}}": "Synced from Git on behalf of {{name}}",
   "Endpoints": "Endpoints",
   "where we fetch models": "where we fetch models",
   "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
@@ -1243,10 +1253,6 @@
   "MCP server": "MCP server",
   "expose the workspace": "expose the workspace",
   "Enable MCP server": "Enable MCP server",
-  "Enable Git sync": "Enable Git sync",
-  "Sync this space's pages to a Git repository.": "Sync this space's pages to a Git repository.",
-  "Auto-merge conflicts on push": "Auto-merge conflicts on push",
-  "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.": "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
   "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.",
   "Resolves to {{url}}": "Resolves to {{url}}",
   "Model": "Model",
@@ -1370,6 +1376,5 @@
   "Already up to date": "Already up to date",
   "Updated to the latest version": "Updated to the latest version",
   "This role is no longer in the catalog": "This role is no longer in the catalog",
-  "This language is no longer available in the catalog": "This language is no longer available in the catalog",
-  "Connecting… (read-only)": "Connecting… (read-only)"
+  "This language is no longer available in the catalog": "This language is no longer available in the catalog"
 }

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

@@ -474,6 +474,18 @@
   "Move page": "Переместить страницу",
   "Move page to a different space.": "Переместите страницу в другое пространство.",
   "Real-time editor connection lost. Retrying...": "Соединение с редактором в реальном времени потеряно. Повторная попытка...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Нет сети — изменения сохраняются локально и синхронизируются при восстановлении соединения",
+  "Syncing changes…": "Синхронизация изменений…",
+  "All changes synced": "Все изменения синхронизированы",
+  "Update available": "Доступно обновление",
+  "Reload": "Перезагрузить",
+  "Make available offline": "Сделать доступным офлайн",
+  "Saving page for offline use...": "Сохраняем страницу для офлайн-доступа…",
+  "Page is now available offline": "Страница доступна офлайн",
+  "Failed to make page available offline": "Не удалось сделать страницу доступной офлайн",
+  "You're offline": "Вы офлайн",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "Эта страница не была сохранена для офлайн-доступа, поэтому её нельзя загрузить сейчас. Подключитесь к интернету и попробуйте снова.",
+  "Retry": "Повторить",
   "Table of contents": "Оглавление",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Добавьте заголовки (H1, H2, H3), чтобы создать оглавление.",
   "Share": "Поделиться",
@@ -1222,6 +1234,5 @@
   "Already up to date": "Уже актуальна",
   "Updated to the latest version": "Обновлено до последней версии",
   "This role is no longer in the catalog": "Эта роль больше не представлена в каталоге",
-  "This language is no longer available in the catalog": "Этот язык больше не доступен в каталоге",
-  "Connecting… (read-only)": "Подключение… (только чтение)"
+  "This language is no longer available in the catalog": "Этот язык больше не доступен в каталоге"
 }

apps/client/public/manifest.json

@@ -1,30 +1,19 @@
 {
+  "id": "/",
   "name": "Gitmost",
   "short_name": "Gitmost",
+  "description": "Gitmost - open-source collaborative documentation and knowledge base.",
+  "lang": "en",
   "start_url": "/",
+  "scope": "/",
   "display": "standalone",
+  "orientation": "any",
   "background_color": "#0E1117",
   "theme_color": "#0E1117",
   "icons": [
-    {
-      "src": "icons/favicon-16x16.png",
-      "type": "image/png",
-      "sizes": "16x16"
-    },
-    {
-      "src": "icons/favicon-32x32.png",
-      "type": "image/png",
-      "sizes": "32x32"
-    },
-    {
-      "src": "icons/app-icon-192x192.png",
-      "type": "image/png",
-      "sizes": "180x180 192x192"
-    },
-    {
-      "src": "icons/app-icon-512x512.png",
-      "type": "image/png",
-      "sizes": "512x512"
-    }
+    { "src": "icons/favicon-16x16.png", "type": "image/png", "sizes": "16x16" },
+    { "src": "icons/favicon-32x32.png", "type": "image/png", "sizes": "32x32" },
+    { "src": "icons/app-icon-192x192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
+    { "src": "icons/app-icon-512x512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" }
   ]
 }

apps/client/src/components/ui/git-sync-badge.tsx

@@ -1,37 +0,0 @@
-import { Badge, Tooltip } from "@mantine/core";
-import { IconGitMerge } from "@tabler/icons-react";
-import { useTranslation } from "react-i18next";
-
-interface GitSyncBadgeProps {
-  authorName?: string;
-}
-
-/**
- * Badge marking a version produced by git-sync (provenance §8.1). The history
- * version is created on the PUSH path — when an incoming git body is written back
- * into the Docmost doc — not by the pull itself. Like {@link AiAgentBadge} it is
- * ADDITIVE — shown next to the human author, never replacing them — but a git-sync
- * edit is NOT an agent edit and has no chat to deep-link into, so it is a small,
- * neutral, non-clickable label.
- */
-export function GitSyncBadge({ authorName }: GitSyncBadgeProps) {
-  const { t } = useTranslation();
-
-  const tooltip = t("Synced from Git on behalf of {{name}}", {
-    name: authorName ?? "",
-  });
-
-  return (
-    <Tooltip label={tooltip} withArrow>
-      <Badge
-        size="sm"
-        variant="light"
-        color="gray"
-        radius="sm"
-        leftSection={<IconGitMerge size={12} stroke={2} />}
-      >
-        {t("Git sync")}
-      </Badge>
-    </Tooltip>
-  );
-}

apps/client/src/features/auth/hooks/use-auth.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// react-i18next: identity t() so the hook renders without an i18n provider.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+// react-router-dom: only useNavigate is used by the hook.
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+// The auth service is the network boundary; stub login per test.
+const loginMock = vi.fn();
+vi.mock("@/features/auth/services/auth-service", () => ({
+  login: (...args: unknown[]) => loginMock(...args),
+  logout: vi.fn(),
+  forgotPassword: vi.fn(),
+  passwordReset: vi.fn(),
+  setupWorkspace: vi.fn(),
+  verifyUserToken: vi.fn(),
+}));
+
+vi.mock("@/features/workspace/services/workspace-service.ts", () => ({
+  acceptInvitation: vi.fn(),
+}));
+
+// The offline cache purge is the unit under test — assert it is invoked.
+const clearOfflineCacheMock = vi.fn();
+vi.mock("@/features/offline/clear-offline-cache", () => ({
+  clearOfflineCache: () => clearOfflineCacheMock(),
+}));
+
+// app-route helpers are pure config; provide deterministic values.
+vi.mock("@/lib/app-route.ts", () => ({
+  default: { AUTH: { LOGIN: "/login" }, HOME: "/home" },
+  getPostLoginRedirect: () => "/home",
+}));
+
+// Mantine notifications: avoid touching the DOM-bound notification system.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+
+import useAuth from "./use-auth";
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  loginMock.mockReset();
+  loginMock.mockResolvedValue(undefined);
+  clearOfflineCacheMock.mockReset();
+  clearOfflineCacheMock.mockResolvedValue(undefined);
+});
+
+describe("useAuth.handleSignIn", () => {
+  it("clears the offline cache BEFORE logging in (cross-user leak guard)", async () => {
+    const order: string[] = [];
+    clearOfflineCacheMock.mockImplementation(async () => {
+      order.push("clear");
+    });
+    loginMock.mockImplementation(async () => {
+      order.push("login");
+    });
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.signIn({ email: "b@x", password: "pw" } as any);
+    });
+
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    expect(loginMock).toHaveBeenCalledTimes(1);
+    // The purge must run before the new session's login resolves.
+    expect(order).toEqual(["clear", "login"]);
+    expect(navigateMock).toHaveBeenCalledWith("/home");
+  });
+
+  it("does not block sign-in when the cache purge throws (best-effort)", async () => {
+    clearOfflineCacheMock.mockRejectedValue(new Error("idb unavailable"));
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.signIn({ email: "b@x", password: "pw" } as any);
+    });
+
+    // Login still proceeds despite the cleanup failure.
+    expect(loginMock).toHaveBeenCalledTimes(1);
+    expect(navigateMock).toHaveBeenCalledWith("/home");
+  });
+});

apps/client/src/features/auth/hooks/use-auth.ts

@@ -23,6 +23,7 @@ import { acceptInvitation } from "@/features/workspace/services/workspace-servic
 import APP_ROUTE, { getPostLoginRedirect } from "@/lib/app-route.ts";
 import { RESET } from "jotai/utils";
 import { useTranslation } from "react-i18next";
+import { clearOfflineCache } from "@/features/offline/clear-offline-cache";
 
 export default function useAuth() {
   const { t } = useTranslation();
@@ -33,6 +34,20 @@ export default function useAuth() {
   const handleSignIn = async (data: ILogin) => {
     setIsLoading(true);
 
+    // Purge any previous user's offline data BEFORE signing in (mirrors logout).
+    // On a shared/kiosk device the prior session may have ended WITHOUT an
+    // explicit logout (cookie/JWT expiry, tab close, force-quit), leaving user
+    // A's persisted query cache (gitmost-rq-cache) and Yjs page bodies
+    // (page.<id>) in IndexedDB. Without this purge user B would briefly read A's
+    // cached currentUser/pages/comments on first render (UserProvider serves the
+    // cached user) and A's page bodies would stay readable offline. Best-effort:
+    // never block sign-in on cache cleanup.
+    try {
+      await clearOfflineCache();
+    } catch {
+      // best-effort: never block sign-in on cache cleanup
+    }
+
     try {
       await login(data);
       setIsLoading(false);
@@ -123,6 +138,13 @@ export default function useAuth() {
   const handleLogout = async () => {
     setCurrentUser(RESET);
     await logout();
+    // Purge the previous user's offline data while the page is still alive —
+    // window.location.replace below would otherwise interrupt async cleanup.
+    try {
+      await clearOfflineCache();
+    } catch {
+      // best-effort: never block logout on cache cleanup
+    }
     window.location.replace(`${APP_ROUTE.AUTH.LOGIN}?logout=1`);
   };
 

apps/client/src/features/auth/queries/auth-query.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { AxiosError } from "axios";
+import { collabTokenRetry } from "./auth-query";
+
+// Regression for the offline white-screen (#237/#238): offline the collab-token
+// POST rejects as an axios NETWORK error (isAxiosError === true but
+// error.response === undefined). The old predicate read `error.response.status`
+// without a guard and threw an uncaught TypeError inside the React Query retryer
+// BEFORE React mounted, blanking the whole app. The predicate must stay total.
+describe("collabTokenRetry", () => {
+  it("does NOT throw and returns a retryable value for a network error with no response (offline)", () => {
+    // An axios error with no `response` is exactly the offline/network-failure shape.
+    const networkError = new AxiosError("Network Error");
+    expect(networkError.response).toBeUndefined();
+
+    let result: boolean | number = false;
+    expect(() => {
+      result = collabTokenRetry(0, networkError);
+    }).not.toThrow();
+    // Network failures stay retryable (truthy), matching the original intent.
+    expect(result).toBe(true);
+  });
+
+  it("returns false (no retry) for a real 404 response", () => {
+    const notFound = new AxiosError("Not Found");
+    notFound.response = { status: 404 } as AxiosError["response"];
+    expect(collabTokenRetry(0, notFound)).toBe(false);
+  });
+
+  it("retries for a non-404 response (e.g. 500)", () => {
+    const serverError = new AxiosError("Server Error");
+    serverError.response = { status: 500 } as AxiosError["response"];
+    expect(collabTokenRetry(0, serverError)).toBe(true);
+  });
+
+  it("does not throw and retries for a non-axios error", () => {
+    let result: boolean | number = false;
+    expect(() => {
+      result = collabTokenRetry(0, new Error("boom"));
+    }).not.toThrow();
+    expect(result).toBe(true);
+  });
+});

apps/client/src/features/auth/queries/auth-query.tsx

@@ -3,6 +3,27 @@ import { getCollabToken, verifyUserToken } from "../services/auth-service";
 import { ICollabToken, IVerifyUserToken } from "../types/auth.types";
 import { isAxiosError } from "axios";
 
+/**
+ * Retry predicate for the collab-token query.
+ *
+ * Offline (or any network failure) the POST rejects as an axios NETWORK error:
+ * `isAxiosError(error) === true` but `error.response === undefined`. Reading
+ * `error.response.status` without a guard threw an uncaught TypeError inside the
+ * React Query retryer BEFORE React mounted, white-screening the whole app on an
+ * offline cold boot (#237/#238). Optional-chaining `error.response?.status`
+ * keeps the predicate total: a network error (no response) is retryable, a real
+ * 404 is not. Extracted (and exported) so it can be unit-tested in isolation.
+ */
+export function collabTokenRetry(
+  _failureCount: number,
+  error: Error,
+): boolean {
+  if (isAxiosError(error) && error.response?.status === 404) {
+    return false;
+  }
+  return true;
+}
+
 export function useVerifyUserTokenQuery(
   verify: IVerifyUserToken,
 ): UseQueryResult<any, Error> {
@@ -22,13 +43,7 @@ export function useCollabToken(): UseQueryResult<ICollabToken, Error> {
     //refetchInterval: 12 * 60 * 60 * 1000, // 12hrs
     //refetchIntervalInBackground: true,
     refetchOnMount: true,
-    //@ts-ignore
-    retry: (failureCount, error) => {
-      if (isAxiosError(error) && error.response.status === 404) {
-        return false;
-      }
-      return 10;
-    },
+    retry: collabTokenRetry,
     retryDelay: (retryAttempt) => {
       // Exponential backoff: 5s, 10s, 20s, etc.
       return 5000 * Math.pow(2, retryAttempt - 1);

apps/client/src/features/comment/queries/comment-query.ts

@@ -20,6 +20,7 @@ import { notifications } from "@mantine/notifications";
 import { IPagination } from "@/lib/types.ts";
 import { useTranslation } from "react-i18next";
 import { useEffect, useMemo } from "react";
+import { offlineMutationKeys } from "@/features/offline/offline-mutations";
 
 export const RQ_KEY = (pageId: string) => ["comments", pageId];
 
@@ -60,6 +61,9 @@ export function useCreateCommentMutation() {
   const { t } = useTranslation();
 
   return useMutation<IComment, Error, Partial<IComment>>({
+    // Stable key so a paused comment-create restored from IndexedDB after an
+    // offline reload finds its default mutationFn and is replayed on reconnect.
+    mutationKey: offlineMutationKeys.createComment,
     mutationFn: (data) => createComment(data),
     onSuccess: (newComment) => {
       const cache = queryClient.getQueryData(

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

@@ -10,6 +10,12 @@ export const readOnlyEditorAtom = atom<Editor | null>(null);
 
 export const yjsConnectionStatusAtom = atom<string>("");
 
+// Local (IndexedDB) persistence sync state for the current page's Y.Doc.
+export const isLocalSyncedAtom = atom<boolean>(false);
+
+// Remote (Hocuspocus) sync state for the current page's Y.Doc.
+export const isRemoteSyncedAtom = atom<boolean>(false);
+
 export const showLinkMenuAtom = atom(false);
 
 // Current page's edit mode — initialized from the user's saved preference on

apps/client/src/features/editor/components/emoji-menu/utils.test.ts

@@ -1,100 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import {
-  sortFrequentlyUsedEmoji,
-  getFrequentlyUsedEmoji,
-  LOCAL_STORAGE_FREQUENT_KEY,
-} from "./utils";
-
-describe("sortFrequentlyUsedEmoji", () => {
-  it("orders known emoji by descending usage count", async () => {
-    const result = await sortFrequentlyUsedEmoji({
-      rocket: 1,
-      joy: 9,
-      heart_eyes: 5,
-    });
-    expect(result.map((e) => e.id)).toEqual(["joy", "heart_eyes", "rocket"]);
-  });
-
-  it("caps the result at the top 5 most frequent", async () => {
-    const result = await sortFrequentlyUsedEmoji({
-      rocket: 1,
-      joy: 2,
-      heart_eyes: 3,
-      grinning: 4,
-      laughing: 5,
-      scream: 6,
-      sweat_smile: 7,
-    });
-    expect(result).toHaveLength(5);
-    // Highest counts retained, lowest (rocket:1, joy:2) dropped.
-    expect(result.map((e) => e.id)).toEqual([
-      "sweat_smile",
-      "scream",
-      "laughing",
-      "grinning",
-      "heart_eyes",
-    ]);
-  });
-
-  it("drops ids that have no matching emoji in the index", async () => {
-    const result = await sortFrequentlyUsedEmoji({
-      __definitely_not_a_real_emoji_id__: 100,
-      rocket: 1,
-    });
-    expect(result.map((e) => e.id)).toEqual(["rocket"]);
-  });
-
-  it("maps each entry to its native glyph and a command", async () => {
-    const [entry] = await sortFrequentlyUsedEmoji({ rocket: 5 });
-    expect(entry.id).toBe("rocket");
-    expect(typeof entry.emoji).toBe("string");
-    expect(entry.emoji.length).toBeGreaterThan(0);
-    expect(typeof entry.command).toBe("function");
-  });
-
-  it("returns an empty list for empty input", async () => {
-    expect(await sortFrequentlyUsedEmoji({})).toEqual([]);
-  });
-});
-
-describe("getFrequentlyUsedEmoji", () => {
-  beforeEach(() => {
-    localStorage.clear();
-  });
-
-  it("falls back to the default map when nothing is stored", () => {
-    const result = getFrequentlyUsedEmoji();
-    expect(result["+1"]).toBe(10);
-    expect(result["rocket"]).toBe(1);
-  });
-
-  it("parses a valid stored JSON map", () => {
-    localStorage.setItem(
-      LOCAL_STORAGE_FREQUENT_KEY,
-      JSON.stringify({ rocket: 42 }),
-    );
-    expect(getFrequentlyUsedEmoji()).toEqual({ rocket: 42 });
-  });
-
-  // BUG (issue #204, Phase 2): getFrequentlyUsedEmoji() does an unprotected
-  // JSON.parse() of the raw localStorage value. A corrupt value (e.g. truncated
-  // by a crash, or written by another tab/extension) makes the emoji menu throw
-  // on open instead of degrading gracefully to the default set.
-  //
-  // Documented with it.fails: this asserts the DESIRED behavior (return a sane
-  // default, never throw). It currently FAILS because the function throws —
-  // flip to `it()` once utils.ts guards the JSON.parse.
-  it.fails(
-    "should degrade to a sane default on corrupt localStorage (currently throws)",
-    () => {
-      localStorage.setItem(LOCAL_STORAGE_FREQUENT_KEY, "{not valid json");
-      let result: Record<string, number> | undefined;
-      expect(() => {
-        result = getFrequentlyUsedEmoji();
-      }).not.toThrow();
-      // Should hand back a usable, non-empty map rather than nothing.
-      expect(result).toBeTruthy();
-      expect(Object.keys(result ?? {}).length).toBeGreaterThan(0);
-    },
-  );
-});

apps/client/src/features/editor/components/table/handle/lib/sort-cells.test.ts

@@ -1,163 +0,0 @@
-import { describe, it, expect } from "vitest";
-import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
-import {
-  isHeaderCell,
-  sortItems,
-  weaveItems,
-  type SortableItem,
-} from "./sort-cells";
-
-// isHeaderCell only reads node.type.name and node.attrs?.header, so a minimal
-// duck-typed node is sufficient (no real ProseMirror schema needed).
-function fakeNode(typeName: string, attrs: Record<string, unknown> = {}) {
-  return { type: { name: typeName }, attrs } as unknown as ProseMirrorNode;
-}
-
-function item<T>(
-  payload: T,
-  text: string,
-  originalOrder: number,
-  opts: { isHeader?: boolean; isEmpty?: boolean } = {},
-): SortableItem<T> {
-  return {
-    payload,
-    text,
-    originalOrder,
-    isHeader: opts.isHeader ?? false,
-    isEmpty: opts.isEmpty ?? text.trim() === "",
-  };
-}
-
-describe("isHeaderCell", () => {
-  it("recognizes the tableHeader node type", () => {
-    expect(isHeaderCell(fakeNode("tableHeader"))).toBe(true);
-  });
-
-  it("recognizes the snake_case table_header node type", () => {
-    expect(isHeaderCell(fakeNode("table_header"))).toBe(true);
-  });
-
-  it("treats a plain cell with header:true attr as a header", () => {
-    expect(isHeaderCell(fakeNode("tableCell", { header: true }))).toBe(true);
-  });
-
-  it("returns false for a regular body cell", () => {
-    expect(isHeaderCell(fakeNode("tableCell", { header: false }))).toBe(false);
-    expect(isHeaderCell(fakeNode("tableCell"))).toBe(false);
-  });
-});
-
-describe("sortItems", () => {
-  it("sorts non-empty rows ascending using a base/numeric collator", () => {
-    const data = [
-      item("c", "cherry", 0),
-      item("a", "Apple", 1),
-      item("b", "banana", 2),
-    ];
-    expect(sortItems(data, "asc").map((i) => i.payload)).toEqual([
-      "a",
-      "b",
-      "c",
-    ]);
-  });
-
-  it("sorts descending when direction is desc", () => {
-    const data = [
-      item("a", "apple", 0),
-      item("b", "banana", 1),
-      item("c", "cherry", 2),
-    ];
-    expect(sortItems(data, "desc").map((i) => i.payload)).toEqual([
-      "c",
-      "b",
-      "a",
-    ]);
-  });
-
-  it("orders numerically, not lexically (numeric collator)", () => {
-    const data = [
-      item("ten", "10", 0),
-      item("two", "2", 1),
-      item("one", "1", 2),
-    ];
-    expect(sortItems(data, "asc").map((i) => i.payload)).toEqual([
-      "one",
-      "two",
-      "ten",
-    ]);
-  });
-
-  it("always pushes empty cells to the bottom regardless of direction", () => {
-    const data = [
-      item("empty", "", 0, { isEmpty: true }),
-      item("b", "banana", 1),
-      item("a", "apple", 2),
-    ];
-    const asc = sortItems(data, "asc");
-    expect(asc.map((i) => i.payload)).toEqual(["a", "b", "empty"]);
-    const desc = sortItems(data, "desc");
-    // Empty stays last even when the rest is reversed.
-    expect(desc[desc.length - 1].payload).toBe("empty");
-  });
-
-  it("keeps empty cells in their original relative order (stable)", () => {
-    const data = [
-      item("e1", "", 5, { isEmpty: true }),
-      item("e2", "", 2, { isEmpty: true }),
-      item("a", "apple", 9),
-    ];
-    const sorted = sortItems(data, "asc");
-    // e2 (originalOrder 2) before e1 (originalOrder 5).
-    expect(sorted.map((i) => i.payload)).toEqual(["a", "e2", "e1"]);
-  });
-
-  it("does not mutate the input array", () => {
-    const data = [item("b", "banana", 0), item("a", "apple", 1)];
-    const snapshot = data.map((i) => i.payload);
-    sortItems(data, "asc");
-    expect(data.map((i) => i.payload)).toEqual(snapshot);
-  });
-});
-
-describe("weaveItems", () => {
-  it("keeps header rows pinned in place and fills body slots from sorted data", () => {
-    const header = item("H", "Name", 0, { isHeader: true });
-    const all = [
-      header,
-      item("orig-b", "b", 1),
-      item("orig-a", "a", 2),
-    ];
-    const sortedBody = [item("orig-a", "a", 2), item("orig-b", "b", 1)];
-
-    const woven = weaveItems(all, sortedBody);
-    // Header never moves out of row 0...
-    expect(woven[0]).toBe(header);
-    // ...and the body positions are filled in sorted order.
-    expect(woven.slice(1).map((i) => i.payload)).toEqual(["orig-a", "orig-b"]);
-  });
-
-  it("does not consume body data for header positions (header stays at top)", () => {
-    const header = item("H", "head", 0, { isHeader: true });
-    const all = [header, item("x", "x", 1), item("y", "y", 2)];
-    const sortedBody = [item("y", "y", 2), item("x", "x", 1)];
-    const woven = weaveItems(all, sortedBody);
-    expect(woven[0].isHeader).toBe(true);
-    expect(woven.filter((i) => !i.isHeader).map((i) => i.payload)).toEqual([
-      "y",
-      "x",
-    ]);
-  });
-
-  it("interleaves correctly when a header sits between body rows", () => {
-    const header = item("H", "head", 1, { isHeader: true });
-    const all = [
-      item("b1", "b1", 0),
-      header,
-      item("b2", "b2", 2),
-    ];
-    const sortedBody = [item("b2", "b2", 2), item("b1", "b1", 0)];
-    const woven = weaveItems(all, sortedBody);
-    expect(woven.map((i) => i.payload)).toEqual(["b2", "H", "b1"]);
-    expect(woven[1]).toBe(header);
-  });
-});

apps/client/src/features/editor/contexts/editor-providers-context.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import type * as Y from "yjs";
+
+// Shared collaboration providers lifted above the title/body editors so that
+// both siblings bind to the SAME Y.Doc and HocuspocusProvider. The title lives
+// in a dedicated 'title' fragment of the same doc as the body.
+export interface EditorProvidersContextValue {
+  ydoc: Y.Doc;
+  remote: HocuspocusProvider;
+  providersReady: boolean;
+}
+
+export const EditorProvidersContext =
+  createContext<EditorProvidersContextValue | null>(null);
+
+// Returns the shared providers, or null when rendered outside of a provider.
+// Consumers must be null-safe (the body editor falls back to a non-collab mode).
+export function useEditorProviders(): EditorProvidersContextValue | null {
+  return useContext(EditorProvidersContext);
+}

apps/client/src/features/editor/editor-sync-state.test.ts

@@ -1,32 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { WebSocketStatus } from "@hocuspocus/provider";
-import { isCollabSynced, isBodyEditable } from "./editor-sync-state";
-
-describe("isCollabSynced", () => {
-  it("is true only when Connected and synced", () => {
-    expect(isCollabSynced(WebSocketStatus.Connected, true)).toBe(true);
-  });
-
-  it("is false while connecting or not yet synced", () => {
-    expect(isCollabSynced(WebSocketStatus.Connecting, true)).toBe(false);
-    expect(isCollabSynced(WebSocketStatus.Connected, false)).toBe(false);
-    expect(isCollabSynced(WebSocketStatus.Disconnected, true)).toBe(false);
-  });
-});
-
-describe("isBodyEditable (pre-sync data-loss gate, #218)", () => {
-  const base = { editable: true, inEditMode: true, showStatic: false };
-
-  it("allows editing only after the static (pre-sync) phase ends", () => {
-    expect(isBodyEditable(base)).toBe(true);
-  });
-
-  it("never editable while the static read-only editor is shown", () => {
-    expect(isBodyEditable({ ...base, showStatic: true })).toBe(false);
-  });
-
-  it("honors read-only and view mode", () => {
-    expect(isBodyEditable({ ...base, editable: false })).toBe(false);
-    expect(isBodyEditable({ ...base, inEditMode: false })).toBe(false);
-  });
-});

apps/client/src/features/editor/editor-sync-state.ts

@@ -1,32 +0,0 @@
-import { WebSocketStatus } from "@hocuspocus/provider";
-
-/**
- * The collab document is usable only once the provider is Connected AND has
- * synced (both the local IndexedDB replica and the remote room). Until then the
- * in-browser Y.Doc is empty/stale, so edits would either be dropped or clobber
- * the server's authoritative doc when it finally arrives.
- */
-export function isCollabSynced(
-  status: WebSocketStatus | string,
-  isSynced: boolean,
-): boolean {
-  return status === WebSocketStatus.Connected && isSynced;
-}
-
-/**
- * Whether the page BODY editor may accept edits.
- *
- * `showStatic` is true during the pre-sync window (a read-only static editor is
- * shown). Gating editability on `!showStatic` guarantees the body never becomes
- * editable before the collab doc is synced, so early keystrokes on a freshly
- * created page can't land only in local ProseMirror and then be lost when the
- * server's initial empty doc syncs in (#218). Read-only and view modes are
- * still honored via `editable`/`inEditMode`.
- */
-export function isBodyEditable(opts: {
-  editable: boolean;
-  inEditMode: boolean;
-  showStatic: boolean;
-}): boolean {
-  return opts.editable && opts.inEditMode && !opts.showStatic;
-}

apps/client/src/features/editor/extensions/markdown-clipboard.canonicalize.test.ts

@@ -1,168 +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 { Node as PMNode, Fragment, Slice } from "@tiptap/pm/model";
-import {
-  FootnoteReference,
-  FootnotesList,
-  FootnoteDefinition,
-  FOOTNOTE_REFERENCE_NAME,
-  FOOTNOTE_DEFINITION_NAME,
-  FOOTNOTES_LIST_NAME,
-} from "@docmost/editor-ext";
-import { canonicalizePastedFootnotes } from "./markdown-clipboard";
-
-/**
- * A markdown paste builds its ProseMirror fragment via DOM -> parseSlice and is
- * applied with a manual transaction (handlePaste returns true), so it bypasses
- * the editor's footnoteSyncPlugin — which never reorders an existing list. These
- * tests pin canonicalizePastedFootnotes, the focused hook that makes a pasted
- * out-of-order markdown footnote block come out canonical (issue #228).
- */
-
-const extensions = [
-  Document,
-  Paragraph,
-  Text,
-  FootnoteReference,
-  FootnotesList,
-  FootnoteDefinition,
-];
-
-function makeSchema() {
-  const editor = new Editor({ extensions, content: { type: "doc", content: [] } });
-  const { schema } = editor;
-  return { editor, schema };
-}
-
-/** List footnote def ids of the (single) footnotesList in a slice, in order. */
-function listIds(slice: Slice): string[] {
-  const out: string[] = [];
-  slice.content.forEach((node: PMNode) => {
-    if (node.type.name === FOOTNOTES_LIST_NAME) {
-      node.content.forEach((def: PMNode) => {
-        if (def.type.name === FOOTNOTE_DEFINITION_NAME) out.push(def.attrs.id);
-      });
-    }
-  });
-  return out;
-}
-
-function hasList(slice: Slice): boolean {
-  let found = false;
-  slice.content.forEach((n: PMNode) => {
-    if (n.type.name === FOOTNOTES_LIST_NAME) found = true;
-  });
-  return found;
-}
-
-describe("canonicalizePastedFootnotes", () => {
-  it("reorders a pasted block to reference order, dedups reuse, drops orphans", () => {
-    const { editor, schema } = makeSchema();
-    // Body references c, a, b (and again a => reuse); definitions a, b, c, z
-    // (z is an orphan) — the exact shape a markdown paste produces.
-    const slice = new Slice(
-      Fragment.fromArray([
-        schema.nodes.paragraph.create(null, [
-          schema.text("body "),
-          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "c" }),
-          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
-          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "b" }),
-          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
-        ]),
-        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
-            schema.nodes.paragraph.create(null, [schema.text("note A")]),
-          ]),
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
-            schema.nodes.paragraph.create(null, [schema.text("note B")]),
-          ]),
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "c" }, [
-            schema.nodes.paragraph.create(null, [schema.text("note C")]),
-          ]),
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "z" }, [
-            schema.nodes.paragraph.create(null, [schema.text("orphan")]),
-          ]),
-        ]),
-      ]),
-      0,
-      0,
-    );
-
-    const out = canonicalizePastedFootnotes(slice, schema);
-    // Reference order, orphan z dropped, reused a appears once.
-    expect(listIds(out)).toEqual(["c", "a", "b"]);
-    editor.destroy();
-  });
-
-  it("leaves a reference-ONLY paste untouched (no synthesized definitions)", () => {
-    // A paste that reuses an id defined in the TARGET doc must NOT gain a
-    // synthesized empty definition here — it carries no footnotesList of its own.
-    const { editor, schema } = makeSchema();
-    const slice = new Slice(
-      Fragment.from(
-        schema.nodes.paragraph.create(null, [
-          schema.text("see "),
-          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
-        ]),
-      ),
-      0,
-      0,
-    );
-    const out = canonicalizePastedFootnotes(slice, schema);
-    expect(hasList(out)).toBe(false);
-    expect(out).toBe(slice); // returned unchanged (same reference)
-    editor.destroy();
-  });
-
-  it("leaves a definitions-ONLY paste untouched (no references -> no empty paste)", () => {
-    // A whole-block paste of ONLY definitions (a footnotesList with no matching
-    // footnoteReference anywhere in the selection). Canonicalizing it would strip
-    // the reference-less list -> an EMPTY paste, losing the pasted text. The hook
-    // must leave such a block untouched.
-    const { editor, schema } = makeSchema();
-    const slice = new Slice(
-      Fragment.fromArray([
-        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
-            schema.nodes.paragraph.create(null, [schema.text("note A")]),
-          ]),
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "b" }, [
-            schema.nodes.paragraph.create(null, [schema.text("note B")]),
-          ]),
-        ]),
-      ]),
-      0,
-      0,
-    );
-    const out = canonicalizePastedFootnotes(slice, schema);
-    expect(out).toBe(slice); // returned unchanged (same reference, content kept)
-    expect(listIds(out)).toEqual(["a", "b"]);
-    editor.destroy();
-  });
-
-  it("leaves an open (partial) slice untouched even if it carries a list", () => {
-    // An open slice (openStart/openEnd > 0) is a partial selection, not a
-    // standalone block, so it is returned as-is BEFORE any footnote handling.
-    const { editor, schema } = makeSchema();
-    const slice = new Slice(
-      Fragment.fromArray([
-        schema.nodes.paragraph.create(null, [
-          schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: "a" }),
-        ]),
-        schema.nodes[FOOTNOTES_LIST_NAME].create(null, [
-          schema.nodes[FOOTNOTE_DEFINITION_NAME].create({ id: "a" }, [
-            schema.nodes.paragraph.create(null, [schema.text("A")]),
-          ]),
-        ]),
-      ]),
-      1,
-      1,
-    );
-    const out = canonicalizePastedFootnotes(slice, schema);
-    expect(out).toBe(slice);
-    editor.destroy();
-  });
-});

apps/client/src/features/editor/extensions/markdown-clipboard.test.ts

@@ -1,126 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { normalizeTableColumnWidths } from "./markdown-clipboard";
-
-// normalizeTableColumnWidths mutates a DOM subtree (jsdom provides document).
-function root(html: string): HTMLElement {
-  const div = document.createElement("div");
-  div.innerHTML = html;
-  return div;
-}
-
-function firstRowColWidths(container: HTMLElement): (string | null)[] {
-  const row = container.querySelector("tr");
-  return Array.from(row?.children ?? []).map((c) =>
-    c.getAttribute("colwidth"),
-  );
-}
-
-describe("normalizeTableColumnWidths", () => {
-  // The core "squash столбцов вставленной таблицы" concern: markdown has no
-  // widths, so every pasted table would otherwise render at table-layout:fixed
-  // / 100% and squash columns. This stamps an explicit per-column px width.
-  it("stamps the default px width on every column when no widths are present", () => {
-    const container = root(
-      "<table><tbody><tr><td>a</td><td>b</td><td>c</td></tr></tbody></table>",
-    );
-    normalizeTableColumnWidths(container);
-    expect(firstRowColWidths(container)).toEqual(["150", "150", "150"]);
-  });
-
-  it("derives column widths from a colgroup", () => {
-    const container = root(
-      "<table>" +
-        '<colgroup><col style="width:200px"><col style="width:80px"></colgroup>' +
-        "<tbody><tr><td>a</td><td>b</td></tr></tbody>" +
-        "</table>",
-    );
-    normalizeTableColumnWidths(container);
-    expect(firstRowColWidths(container)).toEqual(["200", "80"]);
-  });
-
-  it("derives column widths from per-cell width attributes", () => {
-    const container = root(
-      '<table><tbody><tr><td width="120">a</td><td width="90">b</td></tr></tbody></table>',
-    );
-    normalizeTableColumnWidths(container);
-    expect(firstRowColWidths(container)).toEqual(["120", "90"]);
-  });
-
-  it("derives column widths from a cell style:width:px", () => {
-    const container = root(
-      '<table><tbody><tr><td style="width:140px">a</td><td>b</td></tr></tbody></table>',
-    );
-    normalizeTableColumnWidths(container);
-    // First cell width parsed; a fully-unmeasured column is left untouched
-    // (the 100 fallback only fills in NULL gaps inside an otherwise-measured
-    // multi-column slice, e.g. a colspan).
-    expect(firstRowColWidths(container)).toEqual(["140", null]);
-  });
-
-  it("fills a null gap inside a measured colspanned slice with 100", () => {
-    // colgroup gives [200, null]; the single colspan=2 cell spans both, so its
-    // slice is [200, null] -> the null is backfilled to 100 => "200,100".
-    const container = root(
-      "<table>" +
-        '<colgroup><col style="width:200px"><col></colgroup>' +
-        '<tbody><tr><td colspan="2">merged</td></tr></tbody>' +
-        "</table>",
-    );
-    normalizeTableColumnWidths(container);
-    expect(firstRowColWidths(container)).toEqual(["200,100"]);
-  });
-
-  it("splits a measured width across a colspanned cell", () => {
-    const container = root(
-      '<table><tbody><tr><td colspan="2" width="300">merged</td><td width="100">x</td></tr></tbody></table>',
-    );
-    normalizeTableColumnWidths(container);
-    // 300 / colspan(2) = 150 per underlying column => "150,150" on the merged cell.
-    expect(firstRowColWidths(container)).toEqual(["150,150", "100"]);
-  });
-
-  it("falls back to the default width per spanned column when nothing is measurable", () => {
-    const container = root(
-      '<table><tbody><tr><td colspan="2">merged</td><td>x</td></tr></tbody></table>',
-    );
-    normalizeTableColumnWidths(container);
-    expect(firstRowColWidths(container)).toEqual(["150,150", "150"]);
-  });
-
-  it("leaves cells that already have a colwidth untouched", () => {
-    const container = root(
-      '<table><tbody><tr><td colwidth="42">a</td><td>b</td></tr></tbody></table>',
-    );
-    normalizeTableColumnWidths(container);
-    expect(firstRowColWidths(container)).toEqual(["42", "150"]);
-  });
-
-  it("normalizes every table in the subtree", () => {
-    const container = root(
-      "<table><tbody><tr><td>a</td></tr></tbody></table>" +
-        "<table><tbody><tr><td>b</td><td>c</td></tr></tbody></table>",
-    );
-    normalizeTableColumnWidths(container);
-    const tables = container.querySelectorAll("table");
-    const widths = Array.from(tables).map((t) =>
-      Array.from(t.querySelector("tr")!.children).map((c) =>
-        c.getAttribute("colwidth"),
-      ),
-    );
-    expect(widths).toEqual([["150"], ["150", "150"]]);
-  });
-
-  it("only annotates the first row (column widths are defined once)", () => {
-    const container = root(
-      "<table><tbody>" +
-        "<tr><td>a</td><td>b</td></tr>" +
-        "<tr><td>c</td><td>d</td></tr>" +
-        "</tbody></table>",
-    );
-    normalizeTableColumnWidths(container);
-    const rows = container.querySelectorAll("tr");
-    expect(
-      Array.from(rows[1].children).map((c) => c.getAttribute("colwidth")),
-    ).toEqual([null, null]);
-  });
-});

apps/client/src/features/editor/extensions/markdown-clipboard.ts

@@ -3,14 +3,7 @@ import { Extension } from "@tiptap/core";
 import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
 import { DOMParser, DOMSerializer, Fragment, Slice } from "@tiptap/pm/model";
 import { find } from "linkifyjs";
-import {
-  markdownToHtml,
-  htmlToMarkdown,
-  canonicalizeFootnotes,
-  FOOTNOTES_LIST_NAME,
-  FOOTNOTE_REFERENCE_NAME,
-} from "@docmost/editor-ext";
-import type { Schema } from "@tiptap/pm/model";
+import { markdownToHtml, htmlToMarkdown } from "@docmost/editor-ext";
 
 export const MarkdownClipboard = Extension.create({
   name: "markdownClipboard",
@@ -90,25 +83,12 @@ export const MarkdownClipboard = Extension.create({
             const body = elementFromString(parsed);
             normalizeTableColumnWidths(body);
 
-            const parsedSlice = DOMParser.fromSchema(
+            const contentNodes = DOMParser.fromSchema(
               this.editor.schema,
             ).parseSlice(body, {
               preserveWhitespace: true,
             });
 
-            // A markdown paste builds its ProseMirror fragment directly (DOM ->
-            // parseSlice), bypassing the editor's footnoteSyncPlugin, which never
-            // reorders an existing list. So a pasted markdown block whose footnote
-            // definitions are out of order (or contains orphan defs) would be
-            // stored out of order. Canonicalize the self-contained pasted block so
-            // its footnotes come out reference-ordered, deduped and orphan-free
-            // (issue #228). See canonicalizePastedFootnotes for why this is scoped
-            // to whole-block pastes that carry their own footnotesList.
-            const contentNodes = canonicalizePastedFootnotes(
-              parsedSlice,
-              this.editor.schema,
-            );
-
             tr.replaceRange(from, to, contentNodes);
             const insertEnd = tr.mapping.map(from, 1);
             tr.setSelection(TextSelection.near(tr.doc.resolve(Math.max(from, insertEnd - 2)), -1));
@@ -153,54 +133,6 @@ export const MarkdownClipboard = Extension.create({
   },
 });
 
-/**
- * Reorder/dedup the footnotes of a SELF-CONTAINED pasted markdown block to the
- * canonical invariant (the live footnoteSyncPlugin never reorders an existing
- * list, so an out-of-order pasted block would otherwise persist out of order).
- *
- * Scoped deliberately to whole-block pastes (openStart/openEnd === 0) that carry
- * their OWN footnotesList: canonicalizeFootnotes would synthesize empty
- * definitions for any reference lacking a definition, which is correct for a
- * standalone block but would be wrong for a reference-only paste that REUSES a
- * footnote already defined in the target document — so those are left untouched
- * for the paste/sync plugins to merge. Residual: when the pasted block is merged
- * into a doc that already has footnotes, ordering RELATIVE to the pre-existing
- * footnotes is still governed by the sync plugin (which does not reorder).
- *
- * Also requires at least one footnoteReference in the selection: a definitions-ONLY
- * paste (`[^a]: …` with no `[^a]` reference in the same block) has no references,
- * so canonicalizeFootnotes would drop the whole list and the paste would come out
- * EMPTY — losing the pasted text. Such a block is left as-is for the sync plugin.
- */
-export function canonicalizePastedFootnotes(slice: Slice, schema: Schema): Slice {
-  if (slice.openStart !== 0 || slice.openEnd !== 0) return slice;
-
-  let hasFootnotesList = false;
-  let hasReference = false;
-  slice.content.forEach((node) => {
-    if (node.type.name === FOOTNOTES_LIST_NAME) hasFootnotesList = true;
-    // footnoteReference is an inline atom, never a top-level slice child here
-    // (this function early-returns for open slices, so children are whole
-    // blocks), so it is only reachable by descending.
-    node.descendants((child) => {
-      if (child.type.name === FOOTNOTE_REFERENCE_NAME) hasReference = true;
-    });
-  });
-  if (!hasFootnotesList) return slice;
-  // No reference anywhere -> a definitions-only paste; canonicalizing would strip
-  // the reference-less list (empty paste). Leave it untouched.
-  if (!hasReference) return slice;
-
-  const content = slice.content.toJSON();
-  if (!Array.isArray(content)) return slice;
-
-  const canonical = canonicalizeFootnotes({ type: "doc", content }) as {
-    content?: unknown[];
-  };
-  const fragment = Fragment.fromJSON(schema, canonical.content ?? []);
-  return new Slice(fragment, 0, 0);
-}
-
 function elementFromString(value) {
   // add a wrapper to preserve leading and trailing whitespace
   const wrappedValue = `<body>${value}</body>`;

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

@@ -34,6 +34,8 @@ import {
 } from "@/features/editor/atoms/editor-atoms.ts";
 import { DictationGroup } from "@/features/editor/components/fixed-toolbar/groups/dictation-group";
 import { GenerateTitleGroup } from "@/features/editor/components/fixed-toolbar/groups/generate-title-group";
+import { usePageCollabProviders } from "@/features/editor/hooks/use-page-collab-providers";
+import { EditorProvidersContext } from "@/features/editor/contexts/editor-providers-context";
 
 const MemoizedTitleEditor = React.memo(TitleEditor);
 const MemoizedPageEditor = React.memo(PageEditor);
@@ -90,6 +92,10 @@ export function FullEditor({
     user.settings?.preferences?.pageEditMode ?? PageEditMode.Edit;
   const isEditMode = currentPageEditMode === PageEditMode.Edit;
 
+  // Single shared Y.Doc + HocuspocusProvider for both the title and body
+  // editors (title lives in the 'title' fragment of the same doc).
+  const { ydoc, remote, providersReady } = usePageCollabProviders(pageId);
+
   // Apply the user's saved preference only once on initial load, not on every
   // page navigation — so the mode sticks across navigations within a session.
   useEffect(() => {
@@ -110,28 +116,32 @@ export function FullEditor({
       )}
       <MemoizedDeletedPageBanner slugId={slugId} />
       <MemoizedTemporaryNoteBanner slugId={slugId} />
-      <MemoizedTitleEditor
-        pageId={pageId}
-        slugId={slugId}
-        title={title}
-        spaceSlug={spaceSlug}
-        editable={editable}
-      />
-      <PageByline
-        pageId={pageId}
-        creator={creator}
-        contributors={contributors}
-        editable={editable}
-        isEditMode={isEditMode}
-        isDictationEnabled={isDictationEnabled}
-        isTitleGenEnabled={isTitleGenEnabled}
-      />
-      <MemoizedPageEditor
-        pageId={pageId}
-        editable={editable}
-        content={content}
-        canComment={canComment}
-      />
+      <EditorProvidersContext.Provider
+        value={ydoc && remote ? { ydoc, remote, providersReady } : null}
+      >
+        <MemoizedTitleEditor
+          pageId={pageId}
+          slugId={slugId}
+          title={title}
+          spaceSlug={spaceSlug}
+          editable={editable}
+        />
+        <PageByline
+          pageId={pageId}
+          creator={creator}
+          contributors={contributors}
+          editable={editable}
+          isEditMode={isEditMode}
+          isDictationEnabled={isDictationEnabled}
+          isTitleGenEnabled={isTitleGenEnabled}
+        />
+        <MemoizedPageEditor
+          pageId={pageId}
+          editable={editable}
+          content={content}
+          canComment={canComment}
+        />
+      </EditorProvidersContext.Provider>
     </Container>
   );
 }

apps/client/src/features/editor/hooks/collab-token.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// jwt-decode is mocked so we can drive the four token states deterministically
+// (decode success with a chosen exp, or a thrown decode error).
+const decodeMock = vi.hoisted(() => vi.fn());
+vi.mock("jwt-decode", () => ({
+  jwtDecode: decodeMock,
+}));
+
+import { collabTokenNeedsRefresh } from "./collab-token";
+
+const NOW_MS = 1_000_000_000; // fixed "now" in ms (so NOW_MS/1000 seconds)
+
+beforeEach(() => {
+  decodeMock.mockReset();
+});
+
+describe("collabTokenNeedsRefresh", () => {
+  it("returns true when there is no token (fetch a fresh one)", () => {
+    expect(collabTokenNeedsRefresh(undefined, NOW_MS)).toBe(true);
+    // jwtDecode must not even be called for a missing token.
+    expect(decodeMock).not.toHaveBeenCalled();
+  });
+
+  it("returns true when the token is malformed (jwtDecode throws)", () => {
+    decodeMock.mockImplementation(() => {
+      throw new Error("invalid token");
+    });
+    expect(collabTokenNeedsRefresh("garbage", NOW_MS)).toBe(true);
+  });
+
+  it("returns false for a valid, not-yet-expired token (no reconnect)", () => {
+    // exp is in the future relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 + 60 });
+    expect(collabTokenNeedsRefresh("good", NOW_MS)).toBe(false);
+  });
+
+  it("returns true for a valid but expired token (refresh + reconnect)", () => {
+    // exp is in the past relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 - 60 });
+    expect(collabTokenNeedsRefresh("expired", NOW_MS)).toBe(true);
+  });
+
+  it("treats exp exactly equal to now as expired (>= boundary)", () => {
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 });
+    expect(collabTokenNeedsRefresh("boundary", NOW_MS)).toBe(true);
+  });
+});

apps/client/src/features/editor/hooks/collab-token.ts

@@ -0,0 +1,26 @@
+import { jwtDecode } from "jwt-decode";
+
+/**
+ * Decide whether a collab token must be refreshed before reconnecting after an
+ * onAuthenticationFailed event. Pure and side-effect free so the four token
+ * states can be unit-tested directly:
+ *   - no token              -> true  (fetch a fresh one and reconnect)
+ *   - undecodable/malformed -> true  (jwtDecode throws -> refresh)
+ *   - valid, not expired    -> false (token is still good; do NOT reconnect)
+ *   - valid, expired        -> true  (refresh + reconnect)
+ *
+ * `nowMs` is injectable for deterministic tests; it defaults to `Date.now()`.
+ */
+export function collabTokenNeedsRefresh(
+  token: string | undefined,
+  nowMs: number = Date.now(),
+): boolean {
+  if (!token) return true;
+  try {
+    const payload = jwtDecode<{ exp: number }>(token);
+    return nowMs / 1000 >= payload.exp;
+  } catch {
+    // malformed/undecodable token -> refresh
+    return true;
+  }
+}

apps/client/src/features/editor/hooks/use-generate-page-title.test.tsx

@@ -139,7 +139,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("happy path: applies the title, refreshes cache, writes the field, broadcasts", async () => {
+  it("happy path: applies the title, refreshes cache, broadcasts, and does NOT write the editor", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor();
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -157,9 +157,11 @@ describe("useGeneratePageTitle", () => {
       title: "Generated Title",
     });
     expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    expect(titleEditor.commands.setContent).toHaveBeenCalledWith(
-      "Generated Title",
-    );
+    // The title editor is bound to the Yjs `title` fragment; the server REST
+    // update reseeds that fragment and the reseed reaches the bound editor on
+    // its own. Writing here too would double/garble the title, so the hook must
+    // NOT touch the editor (regression guard for the Yjs duplication trap).
+    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
     expect(localEmitMock).toHaveBeenCalled();
     expect(emitMock).toHaveBeenCalled();
     expect(notificationsShowMock).toHaveBeenCalledWith(
@@ -167,7 +169,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("does NOT write the visible title field when the user navigated away during generation", async () => {
+  it("keeps the DB write keyed by the captured pageId and still broadcasts after navigation", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor(); // persistent across navigation
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -203,55 +205,9 @@ describe("useGeneratePageTitle", () => {
       pageId: "pageA",
       title: "Generated Title",
     });
-    // ...but we must NOT stamp page A's title into page B's visible field.
+    // ...the hook never writes the editor regardless of navigation...
     expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(emitMock).toHaveBeenCalled();
-  });
-
-  it("does NOT write the visible title field when the title editor is focused", async () => {
-    const store = createStore();
-    const titleEditor = makeTitleEditor();
-    store.set(pageEditorAtom as never, makePageEditor("pageA"));
-    store.set(titleEditorAtom as never, titleEditor);
-
-    // Resolve generation under our control so we can mark the live title editor
-    // as focused before the post-generation write runs.
-    let resolveTitle!: (t: string) => void;
-    generatePageTitleMock.mockReturnValue(
-      new Promise<string>((res) => {
-        resolveTitle = res;
-      }),
-    );
-    updateTitleMock.mockResolvedValue(PAGE_A);
-    const { result } = setup("pageA", store);
-
-    let pending!: Promise<void>;
-    act(() => {
-      pending = result.current.mutateAsync();
-    });
-
-    // The user clicked into the title field while the model ran — overwriting it
-    // now would clobber what they are actively typing.
-    act(() => {
-      (titleEditor as { isFocused: boolean }).isFocused = true;
-    });
-
-    await act(async () => {
-      resolveTitle("Generated Title");
-      await pending;
-    });
-
-    // The DB write still persists the value...
-    expect(updateTitleMock).toHaveBeenCalledWith({
-      pageId: "pageA",
-      title: "Generated Title",
-    });
-    expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    // ...but the visible field is left alone while it is focused.
-    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(localEmitMock).toHaveBeenCalled();
+    // ...and the change is still broadcast to other clients.
     expect(emitMock).toHaveBeenCalled();
   });
 

apps/client/src/features/editor/hooks/use-generate-page-title.ts

@@ -1,13 +1,9 @@
-import { useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { htmlToMarkdown } from "@docmost/editor-ext";
-import {
-  pageEditorAtom,
-  titleEditorAtom,
-} from "@/features/editor/atoms/editor-atoms.ts";
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import {
   updatePageData,
   useUpdateTitlePageMutation,
@@ -33,18 +29,9 @@ const MAX_CONTENT_CHARS = 20000;
 export function useGeneratePageTitle(pageId: string) {
   const { t } = useTranslation();
   const pageEditor = useAtomValue(pageEditorAtom);
-  const titleEditor = useAtomValue(titleEditorAtom);
   const { mutateAsync: updateTitle } = useUpdateTitlePageMutation();
   const emit = useQueryEmit();
 
-  // The page/title editors come from GLOBAL atoms that re-point when the user
-  // navigates to another page. The mutation below awaits the model for 1-3s, and
-  // its closure captures the editors from the render that started it. Keep a live
-  // reference so the post-generation write targets whatever page is on screen
-  // *now*, not the page the generation was started from.
-  const editorsRef = useRef({ pageEditor, titleEditor });
-  editorsRef.current = { pageEditor, titleEditor };
-
   return useMutation<void, Error, void>({
     mutationFn: async () => {
       if (!pageEditor || pageEditor.isDestroyed) return;
@@ -70,33 +57,15 @@ export function useGeneratePageTitle(pageId: string) {
       const page = await updateTitle({ pageId, title }); // POST /pages/update
       updatePageData(page); // refresh the react-query cache
 
-      // Reflect the new title in the field immediately. The button lives in the
-      // byline, so the title editor is not focused — setContent is safe and stays
-      // undoable through its History extension (Ctrl/Cmd+Z reverts the change).
-      //
-      // Guard against navigation during generation: if the user switched pages
-      // while the model ran, the (persistent) title editor now shows ANOTHER
-      // page, so writing here would drop page A's title into page B's visible
-      // field. page-editor.tsx stamps the live page editor with its pageId
-      // (`editor.storage.pageId`), mirroring TitleEditor's `activePageId !==
-      // pageId` guard — bail the visible write unless that live editor still
-      // belongs to the page this title was generated for. The DB write above is
-      // already correct (keyed by the captured `pageId`), and the broadcast below
-      // still propagates page A's change to other clients.
-      const livePageEditor = editorsRef.current.pageEditor;
-      const liveTitleEditor = editorsRef.current.titleEditor;
-      // `storage.pageId` is stamped untyped in page-editor.tsx's onCreate.
-      const livePageId = (livePageEditor?.storage as { pageId?: string })
-        ?.pageId;
-      const stillOnPage = livePageId === pageId;
-      if (
-        stillOnPage &&
-        liveTitleEditor &&
-        !liveTitleEditor.isDestroyed &&
-        !liveTitleEditor.isFocused
-      ) {
-        liveTitleEditor.commands.setContent(page.title);
-      }
+      // Do NOT write the title into the editor here. The title editor is bound to
+      // the Yjs `title` fragment and Yjs is the source of truth. The server REST
+      // /pages/update reseeds that fragment (writePageTitle → writeTitleFragment,
+      // a full clear+replace) and the reseed reaches the bound title editor on
+      // its own as a remote provider update. The old REST-era setContent here
+      // would race that reseed and double/garble the title (the "Yjs duplication
+      // trap"), so it is intentionally omitted. The DB write above is keyed by
+      // the captured `pageId`, so it stays correct even if the user navigated
+      // away during generation.
 
       // Broadcast to other clients, mirroring TitleEditor.saveTitle's event shape.
       const event: UpdateEvent = {

apps/client/src/features/editor/hooks/use-page-collab-providers.ts

@@ -0,0 +1,185 @@
+import { useEffect, useRef, useState } from "react";
+import { IndexeddbPersistence } from "y-indexeddb";
+import * as Y from "yjs";
+import {
+  HocuspocusProvider,
+  onStatusParameters,
+  WebSocketStatus,
+  HocuspocusProviderWebsocket,
+  onSyncedParameters,
+  onStatelessParameters,
+} from "@hocuspocus/provider";
+import { useAtom, useSetAtom } from "jotai";
+import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
+import {
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
+  yjsConnectionStatusAtom,
+} from "@/features/editor/atoms/editor-atoms";
+import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
+import { useDocumentVisibility } from "@mantine/hooks";
+import { useIdle } from "@/hooks/use-idle.ts";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
+import { useParams } from "react-router-dom";
+import { extractPageSlugId } from "@/lib";
+import { FIVE_MINUTES } from "@/lib/constants.ts";
+import { collabTokenNeedsRefresh } from "@/features/editor/hooks/collab-token";
+
+export interface PageCollabProviders {
+  ydoc: Y.Doc | null;
+  remote: HocuspocusProvider | null;
+  socket: HocuspocusProviderWebsocket | null;
+  providersReady: boolean;
+}
+
+/**
+ * Owns the full collaboration provider lifecycle for a page so that the title
+ * and body editors can share a single Y.Doc + HocuspocusProvider. The behavior
+ * is relocated verbatim from page-editor.tsx: it creates the providers once per
+ * pageId, connects/disconnects on idle/visibility, attaches each render,
+ * destroys on unmount, refreshes the collab token on auth failure, and applies
+ * the onStateless 'page.updated' cache update.
+ */
+export function usePageCollabProviders(pageId: string): PageCollabProviders {
+  const collaborationURL = useCollaborationUrl();
+  const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
+    yjsConnectionStatusAtom,
+  );
+  const setIsLocalSyncedAtom = useSetAtom(isLocalSyncedAtom);
+  const setIsRemoteSyncedAtom = useSetAtom(isRemoteSyncedAtom);
+  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
+  // The provider-creating effect runs only once per pageId, so any token read
+  // inside its handlers would be captured STALE (the old token at first render).
+  // Mirror the latest token into a ref the auth-failure handler can read live.
+  const collabTokenRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    collabTokenRef.current = collabQuery?.token;
+  }, [collabQuery?.token]);
+  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
+  const documentState = useDocumentVisibility();
+  const { pageSlug } = useParams();
+  const slugId = extractPageSlugId(pageSlug);
+
+  // Providers only created once per pageId
+  const providersRef = useRef<{
+    ydoc: Y.Doc;
+    local: IndexeddbPersistence;
+    remote: HocuspocusProvider;
+    socket: HocuspocusProviderWebsocket;
+  } | null>(null);
+  const [providersReady, setProvidersReady] = useState(false);
+
+  useEffect(() => {
+    if (!providersRef.current) {
+      const documentName = `page.${pageId}`;
+      const ydoc = new Y.Doc();
+      const local = new IndexeddbPersistence(documentName, ydoc);
+      const socket = new HocuspocusProviderWebsocket({
+        url: collaborationURL,
+      });
+      const onLocalSyncedHandler = () => {
+        setIsLocalSyncedAtom(true);
+      };
+      const onStatusHandler = (event: onStatusParameters) => {
+        setYjsConnectionStatus(event.status);
+      };
+      const onSyncedHandler = (event: onSyncedParameters) => {
+        setIsRemoteSyncedAtom(event.state);
+      };
+      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
+        try {
+          const message = JSON.parse(payload);
+          if (message?.type !== "page.updated" || !message.updatedAt) return;
+          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
+          if (pageData) {
+            queryClient.setQueryData(["pages", slugId], {
+              ...pageData,
+              updatedAt: message.updatedAt,
+              ...(message.lastUpdatedBy && {
+                lastUpdatedBy: message.lastUpdatedBy,
+              }),
+            });
+          }
+        } catch {
+          // ignore unrelated stateless messages
+        }
+      };
+      const onAuthenticationFailedHandler = () => {
+        // Read the token from the ref, not the closed-over `collabQuery`: this
+        // handler is created once and would otherwise decode a stale token after
+        // a refetch. A missing/malformed token must NOT crash the handler —
+        // jwtDecode(undefined) throws — so treat any decode failure as "needs
+        // refresh" and proceed to refetch + reconnect instead of getting stuck.
+        if (!collabTokenNeedsRefresh(collabTokenRef.current)) return;
+        refetchCollabToken().then((result) => {
+          if (result.data?.token) {
+            socket.disconnect();
+            setTimeout(() => {
+              remote.configuration.token = result.data.token;
+              socket.connect();
+            }, 100);
+          }
+        });
+      };
+      const remote = new HocuspocusProvider({
+        websocketProvider: socket,
+        name: documentName,
+        document: ydoc,
+        token: collabQuery?.token,
+        onAuthenticationFailed: onAuthenticationFailedHandler,
+        onStatus: onStatusHandler,
+        onSynced: onSyncedHandler,
+        onStateless: onStatelessHandler,
+      });
+
+      local.on("synced", onLocalSyncedHandler);
+      providersRef.current = { ydoc, socket, local, remote };
+      setProvidersReady(true);
+    } else {
+      setProvidersReady(true);
+    }
+    // Only destroy on final unmount
+    return () => {
+      providersRef.current?.socket.destroy();
+      providersRef.current?.remote.destroy();
+      providersRef.current?.local.destroy();
+      providersRef.current = null;
+      // Reset shared sync state on page change/unmount.
+      setIsLocalSyncedAtom(false);
+      setIsRemoteSyncedAtom(false);
+    };
+  }, [pageId]);
+
+  // Only connect/disconnect on tab/idle, not destroy
+  useEffect(() => {
+    if (!providersReady || !providersRef.current) return;
+    const socket = providersRef.current.socket;
+
+    if (
+      isIdle &&
+      documentState === "hidden" &&
+      yjsConnectionStatus === WebSocketStatus.Connected
+    ) {
+      socket.disconnect();
+      return;
+    }
+    if (
+      documentState === "visible" &&
+      yjsConnectionStatus === WebSocketStatus.Disconnected
+    ) {
+      resetIdle();
+      socket.connect();
+    }
+  }, [isIdle, documentState, providersReady, resetIdle]);
+
+  // Attach here, to make sure the connection gets properly established
+  providersRef.current?.remote.attach();
+
+  return {
+    ydoc: providersRef.current?.ydoc ?? null,
+    remote: providersRef.current?.remote ?? null,
+    socket: providersRef.current?.socket ?? null,
+    providersReady,
+  };
+}

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

@@ -6,16 +6,7 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { IndexeddbPersistence } from "y-indexeddb";
-import * as Y from "yjs";
-import {
-  HocuspocusProvider,
-  onStatusParameters,
-  WebSocketStatus,
-  HocuspocusProviderWebsocket,
-  onSyncedParameters,
-  onStatelessParameters,
-} from "@hocuspocus/provider";
+import { WebSocketStatus } from "@hocuspocus/provider";
 import {
   Editor,
   EditorContent,
@@ -28,13 +19,15 @@ import {
   mainExtensions,
 } from "@/features/editor/extensions/extensions";
 import { useAtom, useAtomValue } from "jotai";
-import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
   currentPageEditModeAtom,
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
   activeCommentIdAtom,
@@ -58,10 +51,8 @@ import {
 } from "@/features/editor/components/common/editor-paste-handler.tsx";
 import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
 import DrawioMenu from "./components/drawio/drawio-menu";
-import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
-import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";
-import { useIdle } from "@/hooks/use-idle.ts";
+import { useDebouncedCallback } from "@mantine/hooks";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
@@ -72,9 +63,7 @@ import {
   GitmostInsertRecordingResult,
   gitmostInsertRecordingIntoEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
-import { FIVE_MINUTES } from "@/lib/constants.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
-import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
@@ -84,10 +73,6 @@ import { PageEmbedLookupProvider } from "@/features/editor/components/page-embed
 import { PageEmbedAncestryProvider } from "@/features/editor/components/page-embed/page-embed-ancestry-context";
 import PageEmbedPicker from "@/features/editor/components/page-embed/page-embed-picker";
 import { useTranslation } from "react-i18next";
-import {
-  isBodyEditable,
-  isCollabSynced,
-} from "@/features/editor/editor-sync-state";
 
 interface PageEditorProps {
   pageId: string;
@@ -103,7 +88,6 @@ export default function PageEditor({
   canComment,
 }: PageEditorProps) {
   const { t } = useTranslation();
-  const collaborationURL = useCollaborationUrl();
   const isComponentMounted = useRef(false);
   const editorRef = useRef<Editor | null>(null);
 
@@ -117,22 +101,10 @@ export default function PageEditor({
   const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
   const [showReadOnlyCommentPopup] = useAtom(showReadOnlyCommentPopupAtom);
-  const [isLocalSynced, setIsLocalSynced] = useState(false);
-  const [isRemoteSynced, setIsRemoteSynced] = useState(false);
   const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
     yjsConnectionStatusAtom,
   );
   const menuContainerRef = useRef(null);
-  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
-  // Always holds the latest collab token. The provider effect below runs once
-  // per pageId, so a handler created inside it would otherwise close over a
-  // stale `collabQuery`. Reading the ref gives the current token instead.
-  const collabTokenRef = useRef<string | undefined>(undefined);
-  useEffect(() => {
-    collabTokenRef.current = collabQuery?.token;
-  }, [collabQuery?.token]);
-  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
-  const documentState = useDocumentVisibility();
   const { pageSlug } = useParams();
   const slugId = extractPageSlugId(pageSlug);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
@@ -141,141 +113,27 @@ export default function PageEditor({
     [isComponentMounted],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
-  // Providers only created once per pageId
-  const providersRef = useRef<{
-    local: IndexeddbPersistence;
-    remote: HocuspocusProvider;
-    socket: HocuspocusProviderWebsocket;
-  } | null>(null);
-  const [providersReady, setProvidersReady] = useState(false);
 
-  useEffect(() => {
-    if (!providersRef.current) {
-      const documentName = `page.${pageId}`;
-      const ydoc = new Y.Doc();
-      const local = new IndexeddbPersistence(documentName, ydoc);
-      const socket = new HocuspocusProviderWebsocket({
-        url: collaborationURL,
-      });
-      const onLocalSyncedHandler = () => {
-        setIsLocalSynced(true);
-      };
-      const onStatusHandler = (event: onStatusParameters) => {
-        setYjsConnectionStatus(event.status);
-      };
-      const onSyncedHandler = (event: onSyncedParameters) => {
-        setIsRemoteSynced(event.state);
-      };
-      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
-        try {
-          const message = JSON.parse(payload);
-          if (message?.type !== "page.updated" || !message.updatedAt) return;
-          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-          if (pageData) {
-            queryClient.setQueryData(["pages", slugId], {
-              ...pageData,
-              updatedAt: message.updatedAt,
-              ...(message.lastUpdatedBy && {
-                lastUpdatedBy: message.lastUpdatedBy,
-              }),
-            });
-          }
-        } catch {
-          // ignore unrelated stateless messages
-        }
-      };
-      const onAuthenticationFailedHandler = () => {
-        // Read the latest token via the ref (the closure-captured `collabQuery`
-        // may be stale). Guard the decode: a missing or unparseable token must
-        // not throw "Invalid token specified" and should trigger a refresh so
-        // the editor reconnects even when the initial token fetch failed.
-        const token = collabTokenRef.current;
-        let needsRefresh = true; // no/unparseable token -> fetch a fresh one and reconnect
-        if (token) {
-          try {
-            // A token that decodes but lacks a numeric `exp` must be treated as
-            // expired (`Date.now()/1000 >= undefined` is `false`, which would
-            // otherwise skip the reconnect), so refresh on any missing/non-number exp.
-            const exp = jwtDecode<{ exp?: number }>(token).exp;
-            needsRefresh = typeof exp !== "number" || Date.now() / 1000 >= exp;
-          } catch {
-            needsRefresh = true;
-          }
-        }
-        if (!needsRefresh) return;
-        refetchCollabToken().then((result) => {
-          if (result.data?.token) {
-            socket.disconnect();
-            setTimeout(() => {
-              remote.configuration.token = result.data.token;
-              socket.connect();
-            }, 100);
-          }
-        });
-      };
-      const remote = new HocuspocusProvider({
-        websocketProvider: socket,
-        name: documentName,
-        document: ydoc,
-        token: collabQuery?.token,
-        onAuthenticationFailed: onAuthenticationFailedHandler,
-        onStatus: onStatusHandler,
-        onSynced: onSyncedHandler,
-        onStateless: onStatelessHandler,
-      });
-
-      local.on("synced", onLocalSyncedHandler);
-      providersRef.current = { socket, local, remote };
-      setProvidersReady(true);
-    } else {
-      setProvidersReady(true);
-    }
-    // Only destroy on final unmount
-    return () => {
-      providersRef.current?.socket.destroy();
-      providersRef.current?.remote.destroy();
-      providersRef.current?.local.destroy();
-      providersRef.current = null;
-    };
-  }, [pageId]);
-
-  // Only connect/disconnect on tab/idle, not destroy
-  useEffect(() => {
-    if (!providersReady || !providersRef.current) return;
-    const socket = providersRef.current.socket;
-
-    if (
-      isIdle &&
-      documentState === "hidden" &&
-      yjsConnectionStatus === WebSocketStatus.Connected
-    ) {
-      socket.disconnect();
-      return;
-    }
-    if (
-      documentState === "visible" &&
-      yjsConnectionStatus === WebSocketStatus.Disconnected
-    ) {
-      resetIdle();
-      socket.connect();
-    }
-  }, [isIdle, documentState, providersReady, resetIdle]);
-
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  // Shared providers + Y.Doc lifted into full-editor via context. The provider
+  // lifecycle (creation, idle/visibility connect, attach, destroy, token
+  // refresh) lives in usePageCollabProviders. Null-safe when rendered without
+  // the context (defensive) — in practice full-editor always provides it.
+  const editorProviders = useEditorProviders();
+  const remote = editorProviders?.remote ?? null;
+  const providersReady = editorProviders?.providersReady ?? false;
+  const isLocalSynced = useAtomValue(isLocalSyncedAtom);
+  const isRemoteSynced = useAtomValue(isRemoteSyncedAtom);
 
   const extensions = useMemo(() => {
-    if (!providersReady || !providersRef.current || !currentUser?.user) {
+    if (!providersReady || !remote || !currentUser?.user) {
       return mainExtensions;
     }
 
-    const remoteProvider = providersRef.current.remote;
-
     return [
       ...mainExtensions,
-      ...collabExtensions(remoteProvider, currentUser?.user),
+      ...collabExtensions(remote, currentUser?.user),
     ];
-  }, [providersReady, currentUser?.user]);
+  }, [providersReady, remote, currentUser?.user]);
 
   const editor = useEditor(
     {
@@ -444,9 +302,6 @@ export default function PageEditor({
 
   const isSynced = isLocalSynced && isRemoteSynced;
 
-  const hasConnectedOnceRef = useRef(false);
-  const [showStatic, setShowStatic] = useState(true);
-
   useEffect(() => {
     const timeout = setTimeout(() => {
       if (yjsConnectionStatus === WebSocketStatus.Connecting || !isSynced) {
@@ -458,21 +313,17 @@ export default function PageEditor({
   }, [yjsConnectionStatus, isSynced]);
   useEffect(() => {
     if (!editor) return;
-    // Keep the body read-only until the collab doc has synced (showStatic), so
-    // early keystrokes on a freshly created page can't be lost (#218).
-    editor.setEditable(
-      isBodyEditable({
-        editable,
-        inEditMode: currentPageEditMode === PageEditMode.Edit,
-        showStatic,
-      }),
-    );
-  }, [currentPageEditMode, editor, editable, showStatic]);
+    editor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
+  }, [currentPageEditMode, editor, editable]);
+
+  const hasConnectedOnceRef = useRef(false);
+  const [showStatic, setShowStatic] = useState(true);
 
   useEffect(() => {
     if (
       !hasConnectedOnceRef.current &&
-      isCollabSynced(yjsConnectionStatus, isSynced)
+      yjsConnectionStatus === WebSocketStatus.Connected &&
+      isSynced
     ) {
       hasConnectedOnceRef.current = true;
       setShowStatic(false);
@@ -484,43 +335,17 @@ export default function PageEditor({
       <PageEmbedLookupProvider>
         <PageEmbedAncestryProvider hostPageId={pageId}>
       {showStatic ? (
-        <div style={{ position: "relative" }}>
-          {/* Surface the pre-sync read-only window so edits typed before the
-              collab provider connects aren't silently swallowed (#218). Shown
-              only when the user is otherwise allowed to edit. */}
-          {editable && currentPageEditMode === PageEditMode.Edit && (
-            <div
-              role="status"
-              aria-live="polite"
-              className="print-hide"
-              style={{
-                position: "absolute",
-                top: 0,
-                right: 0,
-                zIndex: 2,
-                padding: "2px 8px",
-                fontSize: "12px",
-                borderRadius: "4px",
-                background: "var(--mantine-color-gray-light)",
-                color: "var(--mantine-color-dimmed)",
-                pointerEvents: "none",
-              }}
-            >
-              {t("Connecting… (read-only)")}
-            </div>
-          )}
-          <EditorProvider
-            editable={false}
-            immediatelyRender={true}
-            extensions={mainExtensions}
-            content={content}
-            editorProps={{
-              attributes: {
-                "aria-label": t("Page content"),
-              },
-            }}
-          />
-        </div>
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={mainExtensions}
+          content={content}
+          editorProps={{
+            attributes: {
+              "aria-label": t("Page content"),
+            },
+          }}
+        />
       ) : (
         <div className="editor-container" style={{ position: "relative" }}>
           <div ref={menuContainerRef}>
@@ -550,7 +375,7 @@ export default function PageEditor({
             {editor &&
               !editorIsEditable &&
               (editable || canComment) &&
-              providersRef.current && <ReadonlyBubbleMenu editor={editor} />}
+              remote && <ReadonlyBubbleMenu editor={editor} />}
             {showCommentPopup && (
               <CommentDialog editor={editor} pageId={pageId} />
             )}

apps/client/src/features/editor/title-collab.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// isChangeOrigin is mocked so we can simulate local vs remote/collab-origin
+// transactions without constructing a real ProseMirror/Yjs transaction.
+const isChangeOriginMock = vi.hoisted(() => vi.fn());
+vi.mock("@tiptap/extension-collaboration", () => ({
+  isChangeOrigin: isChangeOriginMock,
+}));
+
+import { shouldPropagateTitleChange } from "./title-collab";
+
+beforeEach(() => {
+  isChangeOriginMock.mockReset();
+});
+
+describe("shouldPropagateTitleChange", () => {
+  it("propagates a genuine local edit (isChangeOrigin false)", () => {
+    isChangeOriginMock.mockReturnValue(false);
+    expect(shouldPropagateTitleChange({ local: true })).toBe(true);
+    expect(isChangeOriginMock).toHaveBeenCalledWith({ local: true });
+  });
+
+  it("skips a remote/collab-origin update (isChangeOrigin true)", () => {
+    isChangeOriginMock.mockReturnValue(true);
+    expect(shouldPropagateTitleChange({ remote: true })).toBe(false);
+  });
+
+  it("propagates when there is no transaction (treated as local)", () => {
+    expect(shouldPropagateTitleChange(undefined)).toBe(true);
+    // isChangeOrigin must not be called for a missing transaction.
+    expect(isChangeOriginMock).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/title-collab.ts

@@ -0,0 +1,19 @@
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+
+/**
+ * Whether a TitleEditor `onUpdate` should drive URL + tree propagation.
+ *
+ * Only genuine LOCAL edits propagate. Remote/collab-origin Yjs updates
+ * (detected via `isChangeOrigin`) are skipped so a remote title change is not
+ * re-broadcast back, which would create a feedback loop. A missing transaction
+ * is treated as a local edit (propagate).
+ *
+ * Extracted as a pure helper so the skip decision is unit-testable without
+ * mounting the full collaborative editor.
+ */
+export function shouldPropagateTitleChange(transaction: unknown): boolean {
+  return !(
+    transaction &&
+    isChangeOrigin(transaction as Parameters<typeof isChangeOrigin>[0])
+  );
+}

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

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+// Drive the fallback-vs-collaborative switch (titleReady = providersReady &&
+// !!ydoc) by controlling what the editor-providers context returns.
+const editorProvidersValue: { ydoc: unknown; providersReady: boolean } = {
+  ydoc: null,
+  providersReady: false,
+};
+vi.mock("@/features/editor/contexts/editor-providers-context", () => ({
+  useEditorProviders: () => editorProvidersValue,
+}));
+
+// Mock the tiptap React bindings so the test does not mount a real editor:
+// useEditor returns a minimal stub and EditorContent renders a marker.
+vi.mock("@tiptap/react", () => ({
+  useEditor: () => ({
+    isInitialized: true,
+    commands: { focus: vi.fn() },
+    setEditable: vi.fn(),
+    getText: () => "",
+  }),
+  EditorContent: () => <div data-testid="collab-editor" />,
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+vi.mock("@/features/websocket/use-query-emit.ts", () => ({
+  useQueryEmit: () => vi.fn(),
+}));
+
+// page-query transitively imports @/main.tsx; mock it to a pure stub.
+vi.mock("@/features/page/queries/page-query", () => ({
+  updatePageData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData: vi.fn(), setQueryData: vi.fn() },
+}));
+
+import { TitleEditor } from "./title-editor";
+
+const baseProps = {
+  pageId: "p1",
+  slugId: "slug-1",
+  title: "My Page Title",
+  spaceSlug: "space",
+  editable: true,
+};
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  editorProvidersValue.ydoc = null;
+  editorProvidersValue.providersReady = false;
+});
+
+describe("TitleEditor fallback vs collaborative switch", () => {
+  it("renders a static <h1> with the title before the shared doc is ready", () => {
+    editorProvidersValue.ydoc = null;
+    editorProvidersValue.providersReady = false;
+
+    render(<TitleEditor {...baseProps} />);
+
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent).toBe("My Page Title");
+    // The collaborative editor must NOT mount until the doc is ready.
+    expect(screen.queryByTestId("collab-editor")).toBeNull();
+  });
+
+  it("renders the collaborative editor once the shared doc is ready", () => {
+    editorProvidersValue.ydoc = {}; // truthy shared doc
+    editorProvidersValue.providersReady = true;
+
+    render(<TitleEditor {...baseProps} />);
+
+    expect(screen.getByTestId("collab-editor")).toBeDefined();
+    // The static fallback <h1> is gone — Yjs is the single source of truth and
+    // the prop is never seeded into the collaborative editor.
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+});

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

@@ -1,5 +1,5 @@
 import "@/features/editor/styles/index.css";
-import React, { useCallback, useEffect, useState } from "react";
+import { useEffect } from "react";
 import { EditorContent, useEditor } from "@tiptap/react";
 import { Document } from "@tiptap/extension-document";
 import { Heading } from "@tiptap/extension-heading";
@@ -11,14 +11,12 @@ import {
   pageEditorAtom,
   titleEditorAtom,
 } from "@/features/editor/atoms/editor-atoms";
-import {
-  updatePageData,
-  useUpdateTitlePageMutation,
-} from "@/features/page/queries/page-query";
+import { updatePageData } from "@/features/page/queries/page-query";
 import { useDebouncedCallback, getHotkeyHandler } from "@mantine/hooks";
 import { useAtom } from "jotai";
 import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
-import { History } from "@tiptap/extension-history";
+import { Collaboration } from "@tiptap/extension-collaboration";
+import { shouldPropagateTitleChange } from "@/features/editor/title-collab";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -28,6 +26,9 @@ import localEmitter from "@/lib/local-emitter.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { platformModifierKey } from "@/lib";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
 
 export interface TitleEditorProps {
   pageId: string;
@@ -45,65 +46,83 @@ export function TitleEditor({
   editable,
 }: TitleEditorProps) {
   const { t } = useTranslation();
-  const { mutateAsync: updateTitlePageMutationAsync } =
-    useUpdateTitlePageMutation();
   const pageEditor = useAtomValue(pageEditorAtom);
   const [, setTitleEditor] = useAtom(titleEditorAtom);
   const emit = useQueryEmit();
   const navigate = useNavigate();
-  const [activePageId, setActivePageId] = useState(pageId);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
 
-  const titleEditor = useEditor({
-    extensions: [
-      Document.extend({
-        content: "heading",
-      }),
-      Heading.configure({
-        levels: [1],
-      }),
-      Text,
-      Placeholder.configure({
-        placeholder: t("Untitled"),
-        showOnlyWhenEditable: false,
-      }),
-      History.configure({
-        depth: 20,
-      }),
-      EmojiCommand,
-    ],
-    onCreate({ editor }) {
-      if (editor) {
-        // @ts-ignore
-        setTitleEditor(editor);
-        setActivePageId(pageId);
-      }
-    },
-    onUpdate({ editor }) {
-      debounceUpdate();
-    },
-    editable: editable,
-    content: title,
-    immediatelyRender: true,
-    shouldRerenderOnTransaction: false,
-    editorProps: {
-      attributes: {
-        "aria-label": t("Page title"),
+  // Shared Y.Doc (title lives in its own 'title' fragment of the same doc as
+  // the body). Yjs is the source of truth for the title content.
+  const editorProviders = useEditorProviders();
+  const ydoc = editorProviders?.ydoc ?? null;
+  const providersReady = editorProviders?.providersReady ?? false;
+
+  // Until the shared doc is ready, the collaborative editor binds nothing and
+  // would render an empty heading until the Yjs 'title' fragment hydrates. Show
+  // a non-editable static <h1> with the `title` prop in the meantime. The prop
+  // is NEVER fed into the collaborative editor (Yjs stays the single source of
+  // truth — seeding it would duplicate the title).
+  const titleReady = providersReady && !!ydoc;
+
+  const titleEditor = useEditor(
+    {
+      extensions: [
+        Document.extend({
+          content: "heading",
+        }),
+        Heading.configure({
+          levels: [1],
+        }),
+        Text,
+        Placeholder.configure({
+          placeholder: t("Untitled"),
+          showOnlyWhenEditable: false,
+        }),
+        // Bind the title to the dedicated 'title' fragment of the shared doc.
+        // Collaboration also manages undo/redo, so the History extension is
+        // intentionally omitted (it would conflict with Yjs). When the doc is
+        // not ready yet the editor renders empty until the doc arrives.
+        ...(ydoc
+          ? [Collaboration.configure({ document: ydoc, field: "title" })]
+          : []),
+        EmojiCommand,
+      ],
+      onCreate({ editor }) {
+        if (editor) {
+          // @ts-ignore
+          setTitleEditor(editor);
+        }
       },
-      handleDOMEvents: {
-        keydown: (_view, event) => {
-          if (platformModifierKey(event) && event.code === "KeyS") {
-            event.preventDefault();
-            return true;
-          }
-          if (platformModifierKey(event) && event.code === "KeyK") {
-            searchSpotlight.open();
-            return true;
-          }
+      onUpdate({ editor, transaction }) {
+        // Drive URL + tree propagation only on genuine local edits; skip
+        // remote/collab-origin Yjs updates to avoid feedback loops.
+        if (!shouldPropagateTitleChange(transaction)) return;
+        debouncedPropagateTitle(editor.getText());
+      },
+      editable: editable,
+      immediatelyRender: true,
+      shouldRerenderOnTransaction: false,
+      editorProps: {
+        attributes: {
+          "aria-label": t("Page title"),
+        },
+        handleDOMEvents: {
+          keydown: (_view, event) => {
+            if (platformModifierKey(event) && event.code === "KeyS") {
+              event.preventDefault();
+              return true;
+            }
+            if (platformModifierKey(event) && event.code === "KeyK") {
+              searchSpotlight.open();
+              return true;
+            }
+          },
         },
       },
     },
-  });
+    [pageId, ydoc],
+  );
 
   useEffect(() => {
     const anchorId = window.location.hash
@@ -113,59 +132,42 @@ export function TitleEditor({
     navigate(pageSlug, { replace: true });
   }, [title]);
 
-  const saveTitle = useCallback(() => {
-    if (!titleEditor || activePageId !== pageId) return;
-
-    if (
-      titleEditor.getText() === title ||
-      (titleEditor.getText() === "" && title === null)
-    ) {
-      return;
-    }
-
-    updateTitlePageMutationAsync({
-      pageId: pageId,
-      title: titleEditor.getText(),
-    }).then((page) => {
-      const event: UpdateEvent = {
-        operation: "updateOne",
-        spaceId: page.spaceId,
-        entity: ["pages"],
-        id: page.id,
-        payload: {
-          title: page.title,
-          slugId: page.slugId,
-          parentPageId: page.parentPageId,
-          icon: page.icon,
-        },
-      };
-
-      if (page.title !== titleEditor.getText()) return;
-
-      updatePageData(page);
-
-      localEmitter.emit("message", event);
-      emit(event);
+  // On a local title change: update the URL slug and propagate the change to
+  // the live tree/breadcrumbs for online users. No REST round-trip — the title
+  // itself is persisted through Yjs. Offline this simply no-ops the socket
+  // emit and the title syncs on reconnect.
+  const debouncedPropagateTitle = useDebouncedCallback((titleText: string) => {
+    const anchorId = window.location.hash
+      ? window.location.hash.substring(1)
+      : undefined;
+    navigate(buildPageUrl(spaceSlug, slugId, titleText, anchorId), {
+      replace: true,
     });
-  }, [pageId, title, titleEditor]);
 
-  const debounceUpdate = useDebouncedCallback(saveTitle, 500);
+    const page =
+      queryClient.getQueryData<IPage>(["pages", slugId]) ??
+      queryClient.getQueryData<IPage>(["pages", pageId]);
+    if (!page) return;
 
-  useEffect(() => {
-    // Do not overwrite the title while the user is actively editing it. The
-    // server rebroadcasts PAGE_UPDATED to the author too, and that echo can
-    // carry a title that lags behind what the user has just typed; resetting
-    // content from it here would drop in-progress characters and jump the
-    // cursor. Apply external title changes only when the field is not focused.
-    if (
-      titleEditor &&
-      !titleEditor.isDestroyed &&
-      !titleEditor.isFocused &&
-      title !== titleEditor.getText()
-    ) {
-      titleEditor.commands.setContent(title);
-    }
-  }, [pageId, title, titleEditor]);
+    const updatedPage: IPage = { ...page, title: titleText };
+
+    const event: UpdateEvent = {
+      operation: "updateOne",
+      spaceId: page.spaceId,
+      entity: ["pages"],
+      id: page.id,
+      payload: {
+        title: titleText,
+        slugId: page.slugId,
+        parentPageId: page.parentPageId,
+        icon: page.icon,
+      },
+    };
+
+    updatePageData(updatedPage);
+    localEmitter.emit("message", event);
+    emit(event);
+  }, 500);
 
   useEffect(() => {
     setTimeout(() => {
@@ -175,13 +177,6 @@ export function TitleEditor({
     }, 300);
   }, [titleEditor]);
 
-  useEffect(() => {
-    return () => {
-      // force-save title on navigation
-      saveTitle();
-    };
-  }, [pageId]);
-
   useEffect(() => {
     if (!titleEditor) return;
     titleEditor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
@@ -248,16 +243,22 @@ export function TitleEditor({
 
   return (
     <div className="page-title">
-      <EditorContent
-        editor={titleEditor}
-        onKeyDown={(event) => {
-          // First handle the search hotkey
-          getHotkeyHandler([["mod+F", openSearchDialog]])(event);
+      {titleReady ? (
+        <EditorContent
+          editor={titleEditor}
+          onKeyDown={(event) => {
+            // First handle the search hotkey
+            getHotkeyHandler([["mod+F", openSearchDialog]])(event);
 
-          // Then handle other key events
-          handleTitleKeyDown(event);
-        }}
-      />
+            // Then handle other key events
+            handleTitleKeyDown(event);
+          }}
+        />
+      ) : (
+        // Static, non-editable fallback so the title is visible before Yjs
+        // hydrates the 'title' fragment. Not wired into the collaborative editor.
+        <h1>{title}</h1>
+      )}
     </div>
   );
 }

apps/client/src/features/offline/clear-offline-cache.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// vi.mock factories are hoisted above imports, so the spies they reference must
+// be declared via vi.hoisted (also hoisted). These are inspected by assertions.
+const h = vi.hoisted(() => ({
+  clear: vi.fn(),
+  del: vi.fn(),
+}));
+
+// The module under test imports the app entry at load time — it must be mocked.
+vi.mock("@/main.tsx", () => ({
+  queryClient: { clear: h.clear },
+}));
+vi.mock("idb-keyval", () => ({
+  del: h.del,
+}));
+
+import { clearOfflineCache } from "./clear-offline-cache";
+import { OFFLINE_CACHE_KEY } from "./query-persister";
+
+// jsdom does not provide indexedDB.databases() or Cache Storage, so the browser
+// globals are stubbed per-test. We restore them afterwards.
+const originalIndexedDB = (globalThis as any).indexedDB;
+const originalCaches = (globalThis as any).caches;
+
+beforeEach(() => {
+  h.clear.mockClear();
+  h.del.mockClear();
+});
+
+afterEach(() => {
+  (globalThis as any).indexedDB = originalIndexedDB;
+  (globalThis as any).caches = originalCaches;
+  vi.restoreAllMocks();
+});
+
+describe("clearOfflineCache", () => {
+  it("resolves without throwing when the browser globals are absent", async () => {
+    (globalThis as any).indexedDB = undefined;
+    delete (globalThis as any).caches;
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+
+    // The two store-agnostic steps still run.
+    expect(h.clear).toHaveBeenCalledTimes(1);
+    expect(h.del).toHaveBeenCalledWith(OFFLINE_CACHE_KEY);
+  });
+
+  it("deletes only `page.*` IndexedDB databases and only `api-get-cache` caches", async () => {
+    const deleteDatabase = vi.fn((_name: string) => {
+      const request: any = {};
+      // Resolve the deletion on the next microtask, like a real IDBRequest.
+      queueMicrotask(() => request.onsuccess && request.onsuccess());
+      return request;
+    });
+    (globalThis as any).indexedDB = {
+      databases: vi
+        .fn()
+        .mockResolvedValue([
+          { name: "page.aaa" },
+          { name: "page.bbb" },
+          { name: "keyval-store" },
+          { name: undefined },
+        ]),
+      deleteDatabase,
+    };
+
+    const cacheDelete = vi.fn().mockResolvedValue(true);
+    (globalThis as any).caches = {
+      keys: vi
+        .fn()
+        .mockResolvedValue([
+          "workbox-runtime-https://app/api-get-cache",
+          "other-cache",
+        ]),
+      delete: cacheDelete,
+    };
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+
+    // Only the two page.* databases are deleted.
+    expect(deleteDatabase).toHaveBeenCalledTimes(2);
+    expect(deleteDatabase).toHaveBeenCalledWith("page.aaa");
+    expect(deleteDatabase).toHaveBeenCalledWith("page.bbb");
+
+    // Only the api-get-cache entry is deleted.
+    expect(cacheDelete).toHaveBeenCalledTimes(1);
+    expect(cacheDelete).toHaveBeenCalledWith(
+      "workbox-runtime-https://app/api-get-cache",
+    );
+  });
+
+  it("never throws even if a step rejects (best-effort)", async () => {
+    h.del.mockRejectedValueOnce(new Error("idb boom"));
+    (globalThis as any).indexedDB = {
+      databases: vi.fn().mockRejectedValue(new Error("databases boom")),
+      deleteDatabase: vi.fn(),
+    };
+    (globalThis as any).caches = {
+      keys: vi.fn().mockRejectedValue(new Error("caches boom")),
+      delete: vi.fn(),
+    };
+
+    await expect(clearOfflineCache()).resolves.toBeUndefined();
+    expect(h.clear).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/offline/clear-offline-cache.ts

@@ -0,0 +1,92 @@
+import { del } from "idb-keyval";
+
+import { queryClient } from "@/main.tsx";
+import { OFFLINE_CACHE_KEY } from "./query-persister";
+
+/**
+ * Best-effort purge of all of the current user's offline data from the browser.
+ *
+ * On logout the previous user's private data would otherwise linger locally and
+ * be readable by the next person on the device. This clears the three offline
+ * stores the app writes:
+ *   1. the in-memory + IndexedDB-persisted TanStack Query cache (idb-keyval key
+ *      `OFFLINE_CACHE_KEY`),
+ *   2. the Yjs page documents (IndexedDB databases named `page.<id>` created by
+ *      y-indexeddb in make-offline.ts), and
+ *   3. any legacy service worker `api-get-cache` Cache Storage entry. The
+ *      Workbox runtime no longer creates this cache (the GET /api NetworkFirst
+ *      rule was removed — offline reads come from the persisted RQ cache), so
+ *      this is now a defensive cleanup for caches left by older app versions.
+ *
+ * Fully best-effort: every step is isolated so a single failure neither blocks
+ * the remaining steps nor throws to the caller (logout must never be blocked on
+ * cache cleanup). Callers may ignore the resolved value.
+ *
+ * Limitations:
+ *   - Deleting the Yjs page databases relies on `indexedDB.databases()`, which
+ *     is unavailable in some browsers (notably Firefox). There we skip silently;
+ *     those `page.<id>` databases are then left in place.
+ *   - Cache Storage clearing only runs where `caches` exists (secure contexts /
+ *     service-worker-capable browsers).
+ */
+export async function clearOfflineCache(): Promise<void> {
+  // 1a. Drop the in-memory query cache immediately.
+  try {
+    queryClient.clear();
+  } catch {
+    // best-effort: ignore in-memory cache reset failures
+  }
+
+  // 1b. Delete the persisted RQ cache from IndexedDB.
+  try {
+    await del(OFFLINE_CACHE_KEY);
+  } catch {
+    // best-effort: ignore persisted-cache deletion failures
+  }
+
+  // 2. Delete the Yjs page IndexedDB databases (`page.<id>`).
+  // `indexedDB.databases()` is not implemented everywhere (e.g. Firefox); when
+  // it is missing we cannot enumerate the page databases, so we skip silently.
+  try {
+    if (
+      typeof indexedDB !== "undefined" &&
+      typeof indexedDB.databases === "function"
+    ) {
+      const dbs = await indexedDB.databases();
+      for (const db of dbs) {
+        const name = db?.name;
+        if (typeof name !== "string" || !name.startsWith("page.")) continue;
+        try {
+          // Fire-and-forget delete; await a thin wrapper so a slow delete does
+          // not race the page teardown, but never reject on it.
+          await new Promise<void>((resolve) => {
+            const request = indexedDB.deleteDatabase(name);
+            request.onsuccess = () => resolve();
+            request.onerror = () => resolve();
+            request.onblocked = () => resolve();
+          });
+        } catch {
+          // best-effort per database
+        }
+      }
+    }
+  } catch {
+    // best-effort: ignore enumeration/deletion failures
+  }
+
+  // 3. Clear any legacy service worker API cache. Current builds no longer
+  // create it, but an older client may have left an "api-get-cache" entry
+  // (Workbox may prefix the name), so match by substring rather than exact name.
+  try {
+    if ("caches" in window) {
+      const keys = await caches.keys();
+      await Promise.all(
+        keys
+          .filter((key) => key.includes("api-get-cache"))
+          .map((key) => caches.delete(key)),
+      );
+    }
+  } catch {
+    // best-effort: ignore Cache Storage failures
+  }
+}

apps/client/src/features/offline/make-offline.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// vi.mock factories are hoisted above imports, so any spy they reference must be
+// declared with vi.hoisted (which is hoisted as well). These shared spies are
+// inspected by the assertions below.
+const h = vi.hoisted(() => ({
+  ydocDestroy: vi.fn(),
+  idbDestroy: vi.fn(),
+  providerOn: vi.fn(),
+  providerOff: vi.fn(),
+  providerDestroy: vi.fn(),
+}));
+
+// The module under test imports the app entry at load time — it must be mocked.
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData: vi.fn(), prefetchQuery: vi.fn() },
+}));
+vi.mock("@/features/page/services/page-service", () => ({
+  getPageById: vi.fn(),
+  getPageBreadcrumbs: vi.fn(),
+  getSidebarPages: vi.fn(),
+  getAllSidebarPages: vi.fn(),
+}));
+vi.mock("@/features/space/services/space-service.ts", () => ({
+  getSpaceById: vi.fn(),
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  getPageComments: vi.fn(),
+}));
+
+// Use the `function` form (not an arrow) so Vitest binds the constructor return
+// value when the module under test calls `new Y.Doc()` etc.
+vi.mock("yjs", () => ({
+  Doc: vi.fn(function () {
+    return { destroy: h.ydocDestroy };
+  }),
+}));
+vi.mock("y-indexeddb", () => ({
+  IndexeddbPersistence: vi.fn(function () {
+    return { destroy: h.idbDestroy };
+  }),
+}));
+vi.mock("@hocuspocus/provider", () => ({
+  HocuspocusProvider: vi.fn(function () {
+    return { on: h.providerOn, off: h.providerOff, destroy: h.providerDestroy };
+  }),
+}));
+
+import {
+  warmInfiniteAll,
+  warmPageYdoc,
+  makePageAvailableOffline,
+} from "./make-offline";
+import { queryClient } from "@/main.tsx";
+import {
+  getPageById,
+  getPageBreadcrumbs,
+  getSidebarPages,
+} from "@/features/page/services/page-service";
+import { getPageComments } from "@/features/comment/services/comment-service";
+
+const setQueryData = (queryClient as any).setQueryData as ReturnType<
+  typeof vi.fn
+>;
+const prefetchQuery = (queryClient as any).prefetchQuery as ReturnType<
+  typeof vi.fn
+>;
+
+beforeEach(() => {
+  // Clear call history WITHOUT wiping the mock implementations the vi.mock
+  // factories installed (vi.clearAllMocks would drop the constructor return
+  // objects and break the provider/idb/yjs spies).
+  setQueryData.mockClear();
+  prefetchQuery.mockReset();
+  prefetchQuery.mockResolvedValue(undefined);
+  (getPageById as ReturnType<typeof vi.fn>).mockReset();
+  (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockReset();
+  (getSidebarPages as ReturnType<typeof vi.fn>).mockReset();
+  (getPageComments as ReturnType<typeof vi.fn>).mockReset();
+  h.ydocDestroy.mockClear();
+  h.idbDestroy.mockClear();
+  h.providerOn.mockClear();
+  h.providerOff.mockClear();
+  h.providerDestroy.mockClear();
+});
+
+describe("warmInfiniteAll", () => {
+  it("warms a single page and writes the InfiniteData cache shape", async () => {
+    const res = { items: [{ id: 1 }], meta: { nextCursor: null } };
+    const fetchPage = vi.fn().mockResolvedValue(res);
+
+    await warmInfiniteAll(["comments", "p1"], fetchPage);
+
+    expect(fetchPage).toHaveBeenCalledTimes(1);
+    expect(fetchPage).toHaveBeenCalledWith(undefined);
+    expect(setQueryData).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledWith(["comments", "p1"], {
+      pages: [res],
+      pageParams: [undefined],
+    });
+  });
+
+  it("walks the cursor chain across multiple pages", async () => {
+    const r0 = { items: [], meta: { nextCursor: "c1" } };
+    const r1 = { items: [], meta: { nextCursor: "c2" } };
+    const r2 = { items: [], meta: { nextCursor: null } };
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValueOnce(r0)
+      .mockResolvedValueOnce(r1)
+      .mockResolvedValueOnce(r2);
+
+    await warmInfiniteAll(["comments", "p1"], fetchPage);
+
+    expect(fetchPage).toHaveBeenCalledTimes(3);
+    expect(fetchPage.mock.calls.map((c) => c[0])).toEqual([
+      undefined,
+      "c1",
+      "c2",
+    ]);
+    const payload = setQueryData.mock.calls[0][1];
+    expect(payload.pages).toEqual([r0, r1, r2]);
+    expect(payload.pageParams).toEqual([undefined, "c1", "c2"]);
+  });
+
+  it("caps pagination at maxPages and reports the truncation (returns false)", async () => {
+    // Always returns a non-null cursor — the cap is the only thing that stops it.
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValue({ items: [], meta: { nextCursor: "more" } });
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Hitting maxPages with a cursor still pending is a truncated warm: the
+    // (partial) cache is still written, but the result is reported as false.
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage, 2),
+    ).resolves.toBe(false);
+
+    expect(fetchPage).toHaveBeenCalledTimes(2);
+    const payload = setQueryData.mock.calls[0][1];
+    expect(payload.pages).toHaveLength(2);
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+
+  it("returns true on success", async () => {
+    const fetchPage = vi
+      .fn()
+      .mockResolvedValue({ items: [], meta: { nextCursor: null } });
+
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage),
+    ).resolves.toBe(true);
+  });
+
+  it("reports errors (returns false) and never writes the cache on failure", async () => {
+    const fetchPage = vi.fn().mockRejectedValue(new Error("network"));
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(
+      warmInfiniteAll(["comments", "p1"], fetchPage),
+    ).resolves.toBe(false);
+    expect(setQueryData).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});
+
+describe("makePageAvailableOffline", () => {
+  const okPage = {
+    id: "uuid-1",
+    slugId: "slug-1",
+    space: { slug: "space-slug" },
+  };
+
+  it("returns ok:true with no failures when every step succeeds", async () => {
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    (getPageComments as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    expect(result).toEqual({ ok: true, failed: [] });
+  });
+
+  it("returns ok:false with the failed step label when a warm step fails", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    (getPageById as ReturnType<typeof vi.fn>).mockResolvedValue(okPage);
+    (getPageBreadcrumbs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    (getSidebarPages as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [],
+      meta: { nextCursor: null },
+    });
+    // Comments warm fails -> labeled "comments".
+    (getPageComments as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error("network"),
+    );
+
+    const result = await makePageAvailableOffline({
+      pageId: "uuid-1",
+      spaceId: "space-uuid",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.failed).toContain("comments");
+    expect(errorSpy).toHaveBeenCalled();
+
+    errorSpy.mockRestore();
+  });
+});
+
+describe("warmPageYdoc", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("resolves on synced, detaches the listener once, and tears everything down (settle-once)", async () => {
+    const promise = warmPageYdoc("p1", "ws://x");
+
+    // Grab the synced handler the provider registered.
+    expect(h.providerOn).toHaveBeenCalledWith("synced", expect.any(Function));
+    const handler = h.providerOn.mock.calls.find(
+      (c) => c[0] === "synced",
+    )![1] as () => void;
+
+    handler();
+    await expect(promise).resolves.toBeUndefined();
+
+    // Listener detached and everything cleaned up.
+    expect(h.providerOff).toHaveBeenCalledWith("synced", expect.any(Function));
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+
+    // Firing the handler again must NOT re-run cleanup (settled guard).
+    handler();
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves and cleans up after the timeout when synced never fires", async () => {
+    vi.useFakeTimers();
+    const promise = warmPageYdoc("p1", "ws://x");
+
+    // Do not fire "synced"; let the 8s safety timeout settle it.
+    await vi.advanceTimersByTimeAsync(8000);
+    await expect(promise).resolves.toBeUndefined();
+
+    expect(h.providerDestroy).toHaveBeenCalledTimes(1);
+    expect(h.idbDestroy).toHaveBeenCalledTimes(1);
+    expect(h.ydocDestroy).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/offline/make-offline.ts

@@ -0,0 +1,314 @@
+import * as Y from "yjs";
+import { IndexeddbPersistence } from "y-indexeddb";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+
+import { queryClient } from "@/main.tsx";
+import {
+  getPageById,
+  getPageBreadcrumbs,
+  getSidebarPages,
+} from "@/features/page/services/page-service";
+import {
+  pageKeys,
+  sidebarPagesQueryOptions,
+} from "@/features/page/queries/page-query";
+import { spaceByIdQueryOptions } from "@/features/space/queries/space-query";
+import { RQ_KEY } from "@/features/comment/queries/comment-query";
+import { getPageComments } from "@/features/comment/services/comment-service";
+import { getMyInfo } from "@/features/user/services/user-service";
+import { userKeys } from "@/features/user/hooks/use-current-user";
+import { IPage } from "@/features/page/types/page.types";
+import { IPagination } from "@/lib/types.ts";
+
+/**
+ * Fully paginate an infinite query and write the @tanstack InfiniteData cache
+ * shape ({ pages, pageParams }) that the matching useInfiniteQuery hook reads.
+ *
+ * The default prefetchInfiniteQuery only warms the FIRST page, which leaves
+ * hooks that treat hasNextPage as still-loading (e.g. the comments panel)
+ * spinning forever offline, and silently truncates large lists. This walks the
+ * cursor chain until it runs out (or hits maxPages) so the whole list is cached.
+ *
+ * Best-effort: a failure does not throw (a partial/failed warm is still useful),
+ * but it is reported — the error is logged with context and `false` is returned
+ * so the caller can record the failed step instead of silently succeeding.
+ *
+ * Returns true ONLY if the cursor chain was fully exhausted and written. If the
+ * walk stops because it hit `maxPages` while a `nextCursor` is still pending,
+ * the cached list is truncated AND its last page keeps a nextCursor that cannot
+ * be re-fetched offline (hooks that gate on hasNextPage would spin forever), so
+ * that case is logged and returns false too — the caller records it as a failed
+ * warm instead of a silent truncated success. The (partial) cache is still
+ * written so what we did fetch is usable.
+ *
+ * Exported for unit testing of the cursor-walk / cache-write behavior.
+ */
+export async function warmInfiniteAll<T>(
+  queryKey: readonly unknown[],
+  fetchPage: (cursor: string | undefined) => Promise<IPagination<T>>,
+  maxPages = 50,
+): Promise<boolean> {
+  try {
+    const pages: IPagination<T>[] = [];
+    const pageParams: (string | undefined)[] = [];
+    let cursor: string | undefined = undefined;
+    let exhausted = false;
+
+    for (let i = 0; i < maxPages; i++) {
+      const res = await fetchPage(cursor);
+      pages.push(res);
+      pageParams.push(cursor);
+      cursor = res?.meta?.nextCursor ?? undefined;
+      if (!cursor) {
+        exhausted = true;
+        break;
+      }
+    }
+
+    queryClient.setQueryData(queryKey, { pages, pageParams });
+
+    if (!exhausted) {
+      // Stopped at maxPages with a cursor still pending: the list is truncated
+      // and the last cached page's nextCursor is un-fetchable offline. Report it
+      // as a failed warm rather than a silent truncated success.
+      console.error("warmInfiniteAll truncated at maxPages", {
+        queryKey,
+        maxPages,
+      });
+      return false;
+    }
+    return true;
+  } catch (error) {
+    console.error("warmInfiniteAll failed", { queryKey, error });
+    return false;
+  }
+}
+
+export interface MakePageAvailableOfflineParams {
+  pageId: string;
+  spaceId?: string;
+}
+
+/**
+ * Outcome of {@link makePageAvailableOffline}. `ok` is true only when every warm
+ * step succeeded; `failed` lists the labels of the steps that failed (a subset
+ * of: "currentUser", "page", "space", "tree", "breadcrumbs", "comments").
+ */
+export interface MakePageAvailableOfflineResult {
+  ok: boolean;
+  failed: string[];
+}
+
+/**
+ * Best-effort prefetch of a page's read queries so they get persisted to
+ * IndexedDB and become readable offline.
+ *
+ * Each step is isolated and this function does NOT throw — a partial warm is
+ * still useful. Instead of silently succeeding, every failed step is logged
+ * with a label and recorded in the returned result: `{ ok, failed }` where
+ * `ok` is true only if no step failed and `failed` lists the failed step
+ * labels. Only meaningful while online (the underlying requests must succeed).
+ */
+export async function makePageAvailableOffline({
+  pageId,
+  spaceId,
+}: MakePageAvailableOfflineParams): Promise<MakePageAvailableOfflineResult> {
+  const failed: string[] = [];
+
+  // Warm the current user (['currentUser']) so the auth-gated <Layout> can
+  // hydrate offline. UserProvider blanks the whole app while useCurrentUser has
+  // no data, and the offline POST /api/users/me fails as a network error, so
+  // without a persisted user a pinned page still white-screens after relaunch
+  // (#238). Persisted via OFFLINE_PERSIST_ROOTS; warmed here so the persisted
+  // cache actually has an entry to restore.
+  try {
+    await queryClient.prefetchQuery({
+      queryKey: userKeys.currentUser(),
+      queryFn: () => getMyInfo(),
+    });
+  } catch (error) {
+    console.error("makePageAvailableOffline: currentUser step failed", {
+      pageId,
+      error,
+    });
+    failed.push("currentUser");
+  }
+
+  // Fetch the page document ONCE and write it under BOTH cache keys, exactly
+  // like usePageQuery's onData effect. Every page consumer reads
+  // pageKeys.detail(slugId) (usePageQuery keys on the slugId for routed reads),
+  // so warming only the uuid key would leave the offline page blank.
+  let page: IPage | undefined;
+  try {
+    page = await getPageById({ pageId });
+    queryClient.setQueryData(pageKeys.detail(page.slugId), page);
+    queryClient.setQueryData(pageKeys.detail(page.id), page);
+  } catch (error) {
+    console.error("makePageAvailableOffline: page step failed", {
+      pageId,
+      error,
+    });
+    failed.push("page");
+  }
+
+  // Warm the space — page.tsx renders nothing until the space query resolves
+  // (useGetSpaceBySlugQuery). Awaited (not the fire-and-forget prefetchSpace) so
+  // the space is actually persisted before the caller fires its toast. Shares
+  // spaceByIdQueryOptions so the key/fn cannot drift from the hook.
+  try {
+    const spaceSlug = page?.space?.slug;
+    if (spaceSlug) {
+      await queryClient.prefetchQuery(spaceByIdQueryOptions(spaceSlug));
+    }
+  } catch (error) {
+    console.error("makePageAvailableOffline: space step failed", {
+      pageId,
+      error,
+    });
+    failed.push("space");
+  }
+
+  // Warm the sidebar tree root so the WHOLE root level renders offline (matches
+  // useGetRootSidebarPagesQuery's pageKeys.rootSidebar(spaceId) infinite cache).
+  // Fully paginated so large root levels are not truncated at 100.
+  if (spaceId) {
+    const ok = await warmInfiniteAll(pageKeys.rootSidebar(spaceId), (cursor) =>
+      getSidebarPages({ spaceId, cursor, limit: 100 }),
+    );
+    if (!ok) failed.push("tree");
+  }
+
+  // Warm the children of the page and of every ancestor so the path to this
+  // page is expandable offline. We MIRROR fetchAllAncestorChildren exactly via
+  // sidebarPagesQueryOptions — same pageKeys.sidebar({ pageId, spaceId }) key,
+  // same getAllSidebarPages fn (which aggregates ALL children pages, so nothing
+  // is truncated at 100), same 30min staleTime — otherwise the warmed cache
+  // would never be read by the offline tree.
+  const warmSidebarChildren = async (id: string): Promise<boolean> => {
+    try {
+      // Keep EXACTLY { pageId, spaceId } so the key hashes identically to
+      // fetchAllAncestorChildren's (no parentPageId, no extra fields).
+      const params = { pageId: id, spaceId };
+      await queryClient.prefetchQuery(sidebarPagesQueryOptions(params));
+      return true;
+    } catch (error) {
+      console.error("makePageAvailableOffline: tree node step failed", {
+        pageId: id,
+        error,
+      });
+      return false;
+    }
+  };
+
+  // The page's own children.
+  if (!(await warmSidebarChildren(pageId))) failed.push("tree");
+
+  // Each ancestor's children. Use the breadcrumbs endpoint ONLY to discover the
+  // ancestor ids — we intentionally do NOT cache the breadcrumbs themselves
+  // (the UI derives the path from the tree).
+  try {
+    const ancestors = (await getPageBreadcrumbs(pageId)) as
+      | Array<{ id?: string }>
+      | undefined;
+    for (const ancestor of ancestors ?? []) {
+      const ancestorId = ancestor?.id;
+      if (!ancestorId || ancestorId === pageId) continue;
+      if (!(await warmSidebarChildren(ancestorId))) failed.push("tree");
+    }
+  } catch (error) {
+    console.error("makePageAvailableOffline: breadcrumbs step failed", {
+      pageId,
+      error,
+    });
+    failed.push("breadcrumbs");
+  }
+
+  // Comments (matches useCommentsQuery's RQ_KEY(pageId) infinite cache).
+  // useCommentsQuery reports isLoading while hasNextPage is true, so warming
+  // only the first page leaves the offline comments panel spinning forever on
+  // pages with >100 comments. Fully paginate so the last cached page has no
+  // nextCursor and the panel settles offline.
+  const commentsOk = await warmInfiniteAll(RQ_KEY(pageId), (cursor) =>
+    getPageComments({ pageId, cursor, limit: 100 }),
+  );
+  if (!commentsOk) failed.push("comments");
+
+  // Dedupe — the tree label can be recorded once per failed node/ancestor.
+  const uniqueFailed = [...new Set(failed)];
+  return { ok: uniqueFailed.length === 0, failed: uniqueFailed };
+}
+
+/**
+ * Best-effort warm-up of the page's Yjs document into IndexedDB so the editor
+ * can open offline.
+ *
+ * Opens a local IndexeddbPersistence plus a transient HocuspocusProvider to
+ * pull the server state into IndexedDB, then tears both down once synced (or
+ * after a timeout). Entirely wrapped in try/catch — NEVER throws.
+ *
+ * Only meaningful when online at warm time; offline it is a no-op that resolves.
+ */
+export async function warmPageYdoc(
+  pageId: string,
+  collabUrl: string,
+  token?: string,
+): Promise<void> {
+  let ydoc: Y.Doc | null = null;
+  let local: IndexeddbPersistence | null = null;
+  let remote: HocuspocusProvider | null = null;
+
+  try {
+    const documentName = `page.${pageId}`;
+    ydoc = new Y.Doc();
+    local = new IndexeddbPersistence(documentName, ydoc);
+    remote = new HocuspocusProvider({
+      url: collabUrl,
+      name: documentName,
+      document: ydoc,
+      token,
+    });
+
+    const provider = remote;
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        // Clear the pending timeout and detach the listener so neither leaks
+        // after we resolve.
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+        try {
+          provider.off("synced", finish);
+        } catch {
+          // best-effort
+        }
+        resolve();
+      };
+
+      // Resolve once the server state has synced into the local doc...
+      provider.on("synced", finish);
+      // ...or give up after a short timeout so we never hang.
+      timeoutId = setTimeout(finish, 8000);
+    });
+  } catch {
+    // best-effort
+  } finally {
+    try {
+      remote?.destroy();
+    } catch {
+      // best-effort
+    }
+    try {
+      local?.destroy();
+    } catch {
+      // best-effort
+    }
+    try {
+      ydoc?.destroy();
+    } catch {
+      // best-effort
+    }
+  }
+}

apps/client/src/features/offline/offline-fallback.tsx

@@ -0,0 +1,45 @@
+import { Button, Container, Group, Stack, Text, Title } from "@mantine/core";
+import { Helmet } from "react-helmet-async";
+import { useTranslation } from "react-i18next";
+import { getAppName } from "@/lib/config";
+
+/**
+ * Shown when the authenticated app shell cannot hydrate because the current
+ * user is unavailable AND there is no cached user to fall back on (e.g. an
+ * offline cold boot of a page that was never warmed for offline).
+ *
+ * Previously UserProvider returned a bare `<></>` in this situation, which
+ * white-screened the whole app on any offline reload (#237/#238). Rendering an
+ * explicit "you're offline" state with a retry instead gives the user a clear,
+ * non-blank fallback and a way to recover once the network returns.
+ */
+export function OfflineFallback() {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <Helmet>
+        <title>
+          {t("You're offline")} - {getAppName()}
+        </title>
+      </Helmet>
+      <Container size="sm" py={80}>
+        <Stack align="center" gap="md">
+          <Title order={2} ta="center">
+            {t("You're offline")}
+          </Title>
+          <Text c="dimmed" size="lg" ta="center">
+            {t(
+              "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+            )}
+          </Text>
+          <Group justify="center">
+            <Button onClick={() => window.location.reload()} variant="subtle">
+              {t("Retry")}
+            </Button>
+          </Group>
+        </Stack>
+      </Container>
+    </>
+  );
+}

apps/client/src/features/offline/offline-mutations.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { QueryClient, hydrate, dehydrate } from "@tanstack/react-query";
+
+// Stub the network services so a replayed mutation hits a spy, not the network.
+const h = vi.hoisted(() => ({
+  createPage: vi.fn(),
+  movePage: vi.fn(),
+  createComment: vi.fn(),
+}));
+
+vi.mock("@/features/page/services/page-service", () => ({
+  createPage: h.createPage,
+  movePage: h.movePage,
+}));
+vi.mock("@/features/comment/services/comment-service", () => ({
+  createComment: h.createComment,
+}));
+// page-query pulls in the app entry (queryClient) and a lot of UI deps via its
+// cache helpers; we only need invalidateOnCreatePage to be a no-op here.
+vi.mock("@/features/page/queries/page-query", () => ({
+  invalidateOnCreatePage: vi.fn(),
+}));
+
+import {
+  offlineMutationKeys,
+  registerOfflineMutationDefaults,
+} from "./offline-mutations";
+
+beforeEach(() => {
+  h.createPage.mockReset().mockResolvedValue({ id: "new-page" });
+  h.movePage.mockReset().mockResolvedValue(undefined);
+  h.createComment.mockReset().mockResolvedValue({ id: "new-comment" });
+});
+
+describe("registerOfflineMutationDefaults", () => {
+  it("registers a default mutationFn for every offline mutation key", () => {
+    const qc = new QueryClient();
+    registerOfflineMutationDefaults(qc);
+
+    for (const key of Object.values(offlineMutationKeys)) {
+      const defaults = qc.getMutationDefaults(key);
+      expect(typeof defaults?.mutationFn).toBe("function");
+    }
+  });
+
+  // The headline durability guarantee: a paused mutation dehydrated into
+  // IndexedDB while offline must, after a reload, have a mutationFn so
+  // resumePausedMutations() actually replays the write on reconnect.
+  it("makes a rehydrated paused create replayable by resumePausedMutations", async () => {
+    // 1) Simulate the offline tab: a paused create mutation gets dehydrated.
+    const offlineClient = new QueryClient();
+    const observer = offlineClient.getMutationCache().build(offlineClient, {
+      mutationKey: offlineMutationKeys.createPage,
+    });
+    // Force the dehydrate-worthy paused state (offline = isPaused) with the
+    // payload the user submitted before losing connectivity.
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { spaceId: "s1", title: "Offline page" };
+
+    const dehydrated = dehydrate(offlineClient, {
+      shouldDehydrateMutation: () => true,
+    });
+    expect(dehydrated.mutations).toHaveLength(1);
+    // The dehydrated mutation carries NO mutationFn (functions aren't
+    // serializable) — only its key + variables survive the reload.
+    expect((dehydrated.mutations[0] as any).mutationFn).toBeUndefined();
+
+    // 2) Simulate the fresh page after reload: register defaults, then hydrate
+    //    the persisted paused mutation back in.
+    const freshClient = new QueryClient();
+    registerOfflineMutationDefaults(freshClient);
+    hydrate(freshClient, dehydrated);
+
+    expect(freshClient.getMutationCache().getAll()).toHaveLength(1);
+
+    // 3) Reconnect: replay the paused mutations.
+    await freshClient.resumePausedMutations();
+
+    // The default mutationFn ran with the persisted variables — the write is
+    // NOT silently dropped.
+    expect(h.createPage).toHaveBeenCalledTimes(1);
+    expect(h.createPage).toHaveBeenCalledWith({
+      spaceId: "s1",
+      title: "Offline page",
+    });
+  });
+
+  it("makes a rehydrated paused move replayable by resumePausedMutations", async () => {
+    const offlineClient = new QueryClient();
+    const observer = offlineClient.getMutationCache().build(offlineClient, {
+      mutationKey: offlineMutationKeys.movePage,
+    });
+    observer.state.isPaused = true;
+    observer.state.status = "pending";
+    observer.state.variables = { pageId: "p1", parentPageId: null, position: "a" };
+
+    const dehydrated = dehydrate(offlineClient, {
+      shouldDehydrateMutation: () => true,
+    });
+
+    const freshClient = new QueryClient();
+    registerOfflineMutationDefaults(freshClient);
+    hydrate(freshClient, dehydrated);
+    await freshClient.resumePausedMutations();
+
+    expect(h.movePage).toHaveBeenCalledTimes(1);
+    expect(h.movePage).toHaveBeenCalledWith({
+      pageId: "p1",
+      parentPageId: null,
+      position: "a",
+    });
+  });
+});

apps/client/src/features/offline/offline-mutations.ts

@@ -0,0 +1,64 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { createPage, movePage } from "@/features/page/services/page-service";
+import { createComment } from "@/features/comment/services/comment-service";
+import { invalidateOnCreatePage } from "@/features/page/queries/page-query";
+import type {
+  IMovePage,
+  IPage,
+  IPageInput,
+} from "@/features/page/types/page.types";
+import type { IComment } from "@/features/comment/types/comment.types";
+
+/**
+ * Stable mutation keys for the offline-relevant structural mutations.
+ *
+ * When the browser goes offline, React Query PAUSES these mutations and the
+ * PersistQueryClientProvider dehydrates the paused mutation into IndexedDB. On a
+ * reload-while-offline the mutation is restored, but a restored mutation has NO
+ * observer (no component is mounted) — so its replay relies entirely on the
+ * `mutationFn` registered via `setMutationDefaults` for its `mutationKey`.
+ * Without that, `resumePausedMutations()` finds a paused mutation with no
+ * `mutationFn` and silently no-ops, dropping the offline create/move/comment
+ * (#237/#238). Each offline mutation hook tags itself with the matching key so
+ * the rehydrated paused mutation can find its default `mutationFn` and replay.
+ */
+export const offlineMutationKeys = {
+  createPage: ["create-page"] as const,
+  movePage: ["move-page"] as const,
+  createComment: ["create-comment"] as const,
+};
+
+/**
+ * Register default `mutationFn`s (and the minimal success side effects safe to
+ * run without a mounted component) for the offline-relevant mutation keys, so a
+ * paused mutation restored from IndexedDB after an offline reload is replayable
+ * by `resumePausedMutations()` on reconnect.
+ *
+ * Called once when the QueryClient is created (see main.tsx). The hooks still
+ * carry their own inline `mutationFn`/`onSuccess` for the live in-session path;
+ * these defaults only take over for a rehydrated paused mutation that lost its
+ * observer across the reload.
+ */
+export function registerOfflineMutationDefaults(queryClient: QueryClient): void {
+  queryClient.setMutationDefaults(offlineMutationKeys.createPage, {
+    mutationFn: (data: Partial<IPageInput>) => createPage(data),
+    // Re-converge the sidebar tree / recent-changes from the authoritative
+    // create response. Pure cache writes — safe with no component mounted.
+    onSuccess: (data: IPage) => {
+      invalidateOnCreatePage(data);
+    },
+  });
+
+  queryClient.setMutationDefaults(offlineMutationKeys.movePage, {
+    // Replay the server-side move. The tree re-converges from the next online
+    // sidebar fetch / websocket `moveTreeNode` echo, so no cache write is
+    // needed here (the optimistic tree state was local-only anyway).
+    mutationFn: (data: IMovePage) => movePage(data),
+  });
+
+  queryClient.setMutationDefaults(offlineMutationKeys.createComment, {
+    // Replay the server-side comment create. The comments list refetches on the
+    // online reload, so the replay only needs to persist the write.
+    mutationFn: (data: Partial<IComment>) => createComment(data),
+  });
+}

apps/client/src/features/offline/persist-roots.guard.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+
+// The query modules transitively import the app entry (@/main.tsx) for the
+// shared queryClient; mock it so importing the key factories has no side effects.
+import { vi } from "vitest";
+vi.mock("@/main.tsx", () => ({
+  queryClient: { setQueryData: vi.fn(), getQueryData: vi.fn() },
+}));
+
+import { OFFLINE_PERSIST_ROOTS } from "./query-persister";
+import { pageKeys } from "@/features/page/queries/page-query";
+import { spaceKeys } from "@/features/space/queries/space-query";
+import { RQ_KEY } from "@/features/comment/queries/comment-query";
+import { userKeys } from "@/features/user/hooks/use-current-user";
+
+/**
+ * Architecture guard (#13): every string persisted via OFFLINE_PERSIST_ROOTS
+ * must be the ROOT (queryKey[0]) of some exported query-key factory. If a
+ * factory's root is renamed without updating the persist registry — or vice
+ * versa — offline persist/warm silently breaks (persisted keys never match the
+ * live queries). This turns that silent regression into a red build.
+ *
+ * Each factory is invoked with throwaway args; only queryKey[0] is inspected.
+ */
+function rootOf(key: readonly unknown[]): string {
+  return String(key[0]);
+}
+
+const FACTORY_ROOTS = new Set<string>([
+  rootOf(pageKeys.detail("x")),
+  rootOf(pageKeys.sidebar({})),
+  rootOf(pageKeys.rootSidebar("x")),
+  rootOf(pageKeys.breadcrumbs("x")),
+  rootOf(pageKeys.recentChanges("x")),
+  rootOf(spaceKeys.detail("x")),
+  rootOf(spaceKeys.list()),
+  rootOf(RQ_KEY("x")),
+  rootOf(userKeys.currentUser()),
+]);
+
+describe("OFFLINE_PERSIST_ROOTS is backed by real query-key factories", () => {
+  it("maps every persisted root to an exported factory root", () => {
+    const unbacked = [...OFFLINE_PERSIST_ROOTS].filter(
+      (root) => !FACTORY_ROOTS.has(root),
+    );
+    expect(unbacked).toEqual([]);
+  });
+});

apps/client/src/features/offline/query-persister.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import {
+  shouldDehydrateOfflineQuery,
+  OFFLINE_PERSIST_ROOTS,
+} from "./query-persister";
+
+// Small helper to build the structural query shape the predicate reads.
+const makeQuery = (status: string, queryKey: readonly unknown[]) =>
+  ({ state: { status }, queryKey }) as any;
+
+describe("shouldDehydrateOfflineQuery", () => {
+  it("returns true for a successful query whose root is in the allowlist", () => {
+    expect(shouldDehydrateOfflineQuery(makeQuery("success", ["pages", "abc"]))).toBe(
+      true,
+    );
+    expect(
+      shouldDehydrateOfflineQuery(
+        makeQuery("success", ["sidebar-pages", { pageId: "p", spaceId: "s" }]),
+      ),
+    ).toBe(true);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["comments", "p1"])),
+    ).toBe(true);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["space", "s"])),
+    ).toBe(true);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["recent-changes"])),
+    ).toBe(true);
+    // currentUser is persisted so the auth-gated Layout can hydrate offline.
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["currentUser"])),
+    ).toBe(true);
+  });
+
+  it("returns false when the status is not success (status gate)", () => {
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("pending", ["pages", "abc"])),
+    ).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("error", ["pages", "abc"])),
+    ).toBe(false);
+  });
+
+  it("returns false for a successful query whose root is NOT in the allowlist (privacy gate)", () => {
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["collab-token", "ws"])),
+    ).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["trash", "s"])),
+    ).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", ["unknown"])),
+    ).toBe(false);
+  });
+
+  it("returns false for an empty/undefined queryKey", () => {
+    // String(undefined) is not a member of the allowlist.
+    expect(shouldDehydrateOfflineQuery(makeQuery("success", []))).toBe(false);
+    expect(
+      shouldDehydrateOfflineQuery(makeQuery("success", undefined as any)),
+    ).toBe(false);
+  });
+});
+
+describe("OFFLINE_PERSIST_ROOTS", () => {
+  it("contains exactly the expected 9 navigation/read roots", () => {
+    const expected = [
+      "pages",
+      "sidebar-pages",
+      "root-sidebar-pages",
+      "breadcrumbs",
+      "comments",
+      "space",
+      "spaces",
+      "recent-changes",
+      "currentUser",
+    ];
+    expect(OFFLINE_PERSIST_ROOTS.size).toBe(9);
+    for (const root of expected) {
+      expect(OFFLINE_PERSIST_ROOTS.has(root)).toBe(true);
+    }
+  });
+
+  it("does NOT contain volatile/auth keys", () => {
+    expect(OFFLINE_PERSIST_ROOTS.has("collab-token")).toBe(false);
+    expect(OFFLINE_PERSIST_ROOTS.has("trash")).toBe(false);
+  });
+});

apps/client/src/features/offline/query-persister.ts

@@ -0,0 +1,58 @@
+import { get, set, del } from "idb-keyval";
+import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
+
+// Structural subset of a TanStack Query we read when deciding what to persist.
+// We avoid importing the branded `Query` class because the persist-client and
+// react-query may resolve to different `@tanstack/query-core` copies, whose
+// `Query` types are nominally incompatible (private brand). This structural
+// shape stays assignable to whichever copy the persister expects.
+type DehydratableQuery = {
+  state: { status: string };
+  queryKey: readonly unknown[];
+};
+
+// idb-keyval key under which TanStack Query persists its dehydrated cache.
+// Exported so the logout cache-clear logic deletes the exact same key (no
+// magic-string drift between persist and purge).
+export const OFFLINE_CACHE_KEY = "gitmost-rq-cache";
+
+// IndexedDB-backed storage adapter for TanStack Query's async persister.
+const idbStorage = {
+  getItem: (key: string) => get<string>(key).then((v) => v ?? null),
+  setItem: (key: string, value: string) => set(key, value),
+  removeItem: (key: string) => del(key),
+};
+
+export const queryPersister = createAsyncStoragePersister({
+  storage: idbStorage,
+  key: OFFLINE_CACHE_KEY,
+  throttleTime: 1000,
+});
+
+// Only navigation/read query roots are persisted for offline reading.
+// Volatile/auth queries (collab tokens, trash lists) are intentionally excluded.
+//
+// `currentUser` IS persisted: UserProvider gates the entire <Layout> subtree on
+// useCurrentUser(), and offline the POST /api/users/me fails as a no-response
+// network error. Without the persisted/hydrated user the gate blanked every
+// authenticated route on an offline cold boot (#237/#238). It is the logged-in
+// user's own profile (already mirrored to localStorage["currentUser"]), so
+// persisting it to IndexedDB leaks nothing new while unlocking offline reads.
+export const OFFLINE_PERSIST_ROOTS = new Set<string>([
+  "pages",
+  "sidebar-pages",
+  "root-sidebar-pages",
+  "breadcrumbs",
+  "comments",
+  "space",
+  "spaces",
+  "recent-changes",
+  "currentUser",
+]);
+
+export function shouldDehydrateOfflineQuery(query: DehydratableQuery): boolean {
+  return (
+    query.state.status === "success" &&
+    OFFLINE_PERSIST_ROOTS.has(String(query.queryKey?.[0]))
+  );
+}

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

@@ -1,227 +0,0 @@
-import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
-import { render, screen, cleanup, within } from "@testing-library/react";
-import { MantineProvider } from "@mantine/core";
-
-// Mantine Tooltip mounts its label lazily on hover via Floating UI, which is
-// flaky under jsdom. Replace ONLY the Tooltip with a thin wrapper that renders
-// the label inline (keeping Badge/Switch/etc. real), so the provenance label —
-// the contract we care about — is deterministically queryable.
-vi.mock("@mantine/core", async () => {
-  const actual =
-    await vi.importActual<typeof import("@mantine/core")>("@mantine/core");
-  const Tooltip = ({
-    label,
-    children,
-  }: {
-    label?: React.ReactNode;
-    children?: React.ReactNode;
-  }) => (
-    <>
-      {children}
-      <span data-testid="tooltip-label">{label}</span>
-    </>
-  );
-  Tooltip.Group = ({ children }: { children?: React.ReactNode }) => (
-    <>{children}</>
-  );
-  return { ...actual, Tooltip };
-});
-
-// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
-beforeAll(() => {
-  if (!window.matchMedia) {
-    window.matchMedia = (query: string) =>
-      ({
-        matches: false,
-        media: query,
-        onchange: null,
-        addListener: () => {},
-        removeListener: () => {},
-        addEventListener: () => {},
-        removeEventListener: () => {},
-        dispatchEvent: () => false,
-      }) as unknown as MediaQueryList;
-  }
-});
-
-// --- Mocks for the heavy / networked module graph ---------------------------
-// HistoryItem pulls in i18n, jotai atoms (ai-chat / history), a config-backed
-// avatar and a time formatter. The provenance-badge contract is the unit under
-// test, so we stub everything else down to inert, deterministic renders and
-// keep the real Mantine Badge/Tooltip so role/label queries are meaningful.
-
-// i18n: interpolate {{name}} so the git-sync tooltip carries the author name,
-// letting us assert provenance attribution without a real i18n backend.
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({
-    t: (key: string, vars?: Record<string, unknown>) =>
-      vars && typeof vars.name !== "undefined"
-        ? key.replace("{{name}}", String(vars.name))
-        : key,
-  }),
-}));
-
-// jotai setters: the badges call useSetAtom; return inert setters so a click on
-// the (deep-linkable) AiAgentBadge would fire these — proving the git-sync badge
-// does NOT wire any of them.
-const setAiChatWindowOpen = vi.fn();
-const setActiveChatId = vi.fn();
-const setDraft = vi.fn();
-const setHistoryModalOpen = vi.fn();
-vi.mock("jotai", async () => {
-  const actual = await vi.importActual<typeof import("jotai")>("jotai");
-  return {
-    ...actual,
-    useSetAtom: (atom: unknown) => {
-      switch (atom) {
-        case aiChatWindowOpenAtom:
-          return setAiChatWindowOpen;
-        case activeAiChatIdAtom:
-          return setActiveChatId;
-        case aiChatDraftAtom:
-          return setDraft;
-        case historyAtoms:
-          return setHistoryModalOpen;
-        default:
-          return vi.fn();
-      }
-    },
-  };
-});
-
-// Atoms are imported only as identity tokens for the useSetAtom switch above.
-vi.mock("@/features/ai-chat/atoms/ai-chat-atom.ts", () => ({
-  activeAiChatIdAtom: { __tag: "activeAiChatIdAtom" },
-  aiChatWindowOpenAtom: { __tag: "aiChatWindowOpenAtom" },
-  aiChatDraftAtom: { __tag: "aiChatDraftAtom" },
-}));
-vi.mock("@/features/page-history/atoms/history-atoms.ts", () => ({
-  historyAtoms: { __tag: "historyAtoms" },
-}));
-
-// Avatar reaches into config (getAvatarUrl) — stub to a plain element.
-vi.mock("@/components/ui/custom-avatar.tsx", () => ({
-  CustomAvatar: ({ name }: { name?: string }) => (
-    <span data-testid="avatar">{name}</span>
-  ),
-}));
-
-// Deterministic, locale-free date string.
-vi.mock("@/lib/time", () => ({
-  formattedDate: () => "2026-06-21",
-}));
-
-import HistoryItem from "./history-item";
-import {
-  activeAiChatIdAtom,
-  aiChatWindowOpenAtom,
-  aiChatDraftAtom,
-} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
-import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
-import type { IPageHistory } from "@/features/page-history/types/page.types";
-
-function makeItem(overrides: Partial<IPageHistory> = {}): IPageHistory {
-  return {
-    id: "h1",
-    pageId: "p1",
-    title: "Title",
-    slug: "slug",
-    icon: "",
-    coverPhoto: "",
-    version: 1,
-    lastUpdatedById: "u1",
-    workspaceId: "w1",
-    createdAt: "2026-06-21T00:00:00.000Z",
-    updatedAt: "2026-06-21T00:00:00.000Z",
-    lastUpdatedBy: { id: "u1", name: "Alice", avatarUrl: "" },
-    ...overrides,
-  };
-}
-
-function renderItem(item: IPageHistory) {
-  return render(
-    <MantineProvider>
-      <HistoryItem
-        historyItem={item}
-        index={0}
-        onSelect={vi.fn()}
-        isActive={false}
-      />
-    </MantineProvider>,
-  );
-}
-
-afterEach(() => {
-  cleanup();
-  vi.clearAllMocks();
-});
-
-describe("HistoryItem git-sync provenance badge", () => {
-  // Test 1: the git-sync badge renders ONLY for lastUpdatedSource === 'git-sync'.
-  it("renders the Git sync badge only when lastUpdatedSource is 'git-sync'", () => {
-    renderItem(makeItem({ lastUpdatedSource: "git-sync" }));
-    expect(screen.getByText("Git sync")).toBeTruthy();
-  });
-
-  it.each([
-    ["agent", "agent"],
-    ["user", "user"],
-    ["undefined", undefined],
-  ])(
-    "does NOT render the Git sync badge when lastUpdatedSource is %s",
-    (_label, source) => {
-      renderItem(makeItem({ lastUpdatedSource: source }));
-      expect(screen.queryByText("Git sync")).toBeNull();
-    },
-  );
-
-  // Test 2: provenance attribution + the git-sync badge is NOT interactive.
-  it("attributes the git-sync provenance to the correct author and is not clickable", () => {
-    renderItem(
-      makeItem({
-        lastUpdatedSource: "git-sync",
-        lastUpdatedBy: { id: "u2", name: "Bob", avatarUrl: "" },
-      }),
-    );
-
-    const badge = screen.getByText("Git sync");
-
-    // Provenance attribution: the tooltip label carries the author name (the
-    // git-sync badge passes authorName -> "Synced from Git on behalf of {{name}}").
-    expect(screen.getByText("Synced from Git on behalf of Bob")).toBeTruthy();
-
-    // The git-sync badge must NOT behave like AiAgentBadge: the badge element
-    // itself is not a button, carries no role=button and no tabIndex, and
-    // clicking it must not trigger any ai-chat deep-link. (The surrounding
-    // history-row IS an UnstyledButton — that is the row's own select affordance,
-    // not the badge — so we scope these checks to the badge element.)
-    const badgeRoot = (badge.closest("[class*='mantine-Badge-root']") ??
-      badge) as HTMLElement;
-    expect(badgeRoot.getAttribute("role")).not.toBe("button");
-    expect(badgeRoot.getAttribute("tabindex")).toBeNull();
-    expect(badgeRoot.tagName.toLowerCase()).not.toBe("button");
-    // No interactive descendant button lives inside the badge itself.
-    expect(within(badgeRoot).queryByRole("button")).toBeNull();
-
-    badgeRoot.dispatchEvent(new MouseEvent("click", { bubbles: true }));
-    expect(setActiveChatId).not.toHaveBeenCalled();
-    expect(setAiChatWindowOpen).not.toHaveBeenCalled();
-    expect(setDraft).not.toHaveBeenCalled();
-    expect(setHistoryModalOpen).not.toHaveBeenCalled();
-  });
-
-  // Sanity contrast: the agent badge (the copy-paste source) IS interactive when
-  // it carries an aiChatId — proving the not-clickable assertion above is real.
-  it("contrast: the AI-agent badge is a deep-link button when it has an aiChatId", () => {
-    renderItem(
-      makeItem({
-        lastUpdatedSource: "agent",
-        lastUpdatedAiChatId: "chat-1",
-      }),
-    );
-    const agentBadge = screen.getByText("AI-agent");
-    const root = agentBadge.closest("[role='button']");
-    expect(root).not.toBeNull();
-    within(root as HTMLElement).getByText("AI-agent");
-  });
-});

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

@@ -1,7 +1,6 @@
 import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
-import { GitSyncBadge } from "@/components/ui/git-sync-badge.tsx";
 import { formattedDate } from "@/lib/time";
 import classes from "./css/history.module.css";
 import clsx from "clsx";
@@ -42,7 +41,6 @@ const HistoryItem = memo(function HistoryItem({
   const contributors = historyItem.contributors;
   const hasContributors = contributors && contributors.length > 0;
   const isAgentEdit = historyItem.lastUpdatedSource === "agent";
-  const isGitSyncEdit = historyItem.lastUpdatedSource === "git-sync";
 
   return (
     <UnstyledButton
@@ -110,10 +108,6 @@ const HistoryItem = memo(function HistoryItem({
             onActivate={() => setHistoryModalOpen(false)}
           />
         )}
-
-        {isGitSyncEdit && (
-          <GitSyncBadge authorName={historyItem.lastUpdatedBy?.name} />
-        )}
       </Group>
     </UnstyledButton>
   );

apps/client/src/features/page/components/breadcrumbs/breadcrumb.tsx

@@ -1,7 +1,7 @@
 import { useAtomValue } from "jotai";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import React, { useCallback, useEffect, useState } from "react";
-import { computeBreadcrumbState } from "./breadcrumb.utils";
+import { findBreadcrumbPath } from "@/features/page/tree/utils";
 import {
   Button,
   Anchor,
@@ -15,12 +15,8 @@ import { IconCornerDownRightDouble, IconDots } from "@tabler/icons-react";
 import { Link, useParams } from "react-router-dom";
 import classes from "./breadcrumb.module.css";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
-import { IPage } from "@/features/page/types/page.types.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
-import {
-  usePageQuery,
-  usePageBreadcrumbsQuery,
-} from "@/features/page/queries/page-query.ts";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useMediaQuery } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
@@ -42,29 +38,14 @@ export default function Breadcrumb() {
   const { data: currentPage } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });
-  // The page's own ancestor chain, fetched independently of the lazily-built
-  // sidebar tree so a deep page doesn't render a blank breadcrumb for seconds
-  // while the tree backfills (#218).
-  const { data: ancestors } = usePageBreadcrumbsQuery(currentPage?.id);
   const isMobile = useMediaQuery("(max-width: 48em)");
 
   useEffect(() => {
-    if (!currentPage) return;
-
-    // Selection/mapping + stale-clearing live in a pure, unit-tested helper
-    // (#218). It resolves the correct chain when possible and, on a transient
-    // miss, clears a chain left over from a previously-viewed page instead of
-    // showing the wrong trail — while keeping a chain already resolved for THIS
-    // page to avoid a blank flash.
-    setBreadcrumbNodes((previous) =>
-      computeBreadcrumbState(
-        treeData,
-        ancestors as IPage[] | undefined,
-        currentPage.id,
-        previous,
-      ),
-    );
-  }, [currentPage?.id, treeData, ancestors]);
+    if (treeData?.length > 0 && currentPage) {
+      const breadcrumb = findBreadcrumbPath(treeData, currentPage.id);
+      setBreadcrumbNodes(breadcrumb || null);
+    }
+  }, [currentPage?.id, treeData]);
 
   const HiddenNodesTooltipContent = () =>
     breadcrumbNodes?.slice(1, -1).map((node) => (

apps/client/src/features/page/components/breadcrumbs/breadcrumb.utils.test.ts

@@ -1,114 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  computeBreadcrumbState,
-  resolveBreadcrumbNodes,
-} from "./breadcrumb.utils";
-import { SpaceTreeNode } from "@/features/page/tree/types.ts";
-import { IPage } from "@/features/page/types/page.types.ts";
-
-// Pure selection/mapping behind the breadcrumb (#218): tree-hit prefers the live
-// sidebar tree, tree-miss maps the page's own ancestors, and "no data" returns
-// null so the component keeps its prior state.
-
-function treeNode(id: string, over?: Partial<SpaceTreeNode>): SpaceTreeNode {
-  return {
-    id,
-    slugId: `slug-${id}`,
-    name: `node-${id}`,
-    icon: null,
-    position: "a",
-    hasChildren: false,
-    spaceId: "space-1",
-    parentPageId: null,
-    children: [],
-    ...over,
-  } as SpaceTreeNode;
-}
-
-function ancestorPage(id: string, over?: Partial<IPage>): IPage {
-  return {
-    id,
-    slugId: `slug-${id}`,
-    title: `title-${id}`,
-    icon: "📄",
-    position: "m",
-    spaceId: "space-1",
-    parentPageId: null,
-    hasChildren: true,
-    ...over,
-  } as IPage;
-}
-
-describe("resolveBreadcrumbNodes", () => {
-  it("tree-hit: returns the path found in the live sidebar tree", () => {
-    const child = treeNode("child");
-    const root = treeNode("root", { hasChildren: true, children: [child] });
-    // findBreadcrumbPath walks the tree; the chain ends at the target page.
-    const result = resolveBreadcrumbNodes([root], [ancestorPage("child")], "child");
-
-    expect(result).not.toBeNull();
-    expect(result!.map((n) => n.id)).toEqual(["root", "child"]);
-    // Came from the tree, NOT the ancestor mapping (icon stays the tree's null).
-    expect(result![result!.length - 1].icon).toBeNull();
-  });
-
-  it("tree-miss: maps the page's own ancestors (title->name, hasChildren default)", () => {
-    // Tree has no node for the target page -> findBreadcrumbPath misses.
-    const unrelated = treeNode("unrelated");
-    const ancestors = [
-      ancestorPage("a", { hasChildren: true }),
-      ancestorPage("b", { hasChildren: undefined as any }),
-    ];
-
-    const result = resolveBreadcrumbNodes([unrelated], ancestors, "missing-page");
-
-    expect(result).not.toBeNull();
-    expect(result!.map((n) => n.id)).toEqual(["a", "b"]);
-    // Non-trivial field transform: title -> name.
-    expect(result![0].name).toBe("title-a");
-    // hasChildren defaults to false when the ancestor row omits it.
-    expect(result![1].hasChildren).toBe(false);
-    expect(result![0].hasChildren).toBe(true);
-  });
-
-  it("falls back to ancestors when the tree is empty", () => {
-    const result = resolveBreadcrumbNodes([], [ancestorPage("a")], "a");
-    expect(result!.map((n) => n.id)).toEqual(["a"]);
-  });
-
-  it("returns null when there is no tree hit and no ancestor data", () => {
-    expect(resolveBreadcrumbNodes([], [], "x")).toBeNull();
-    expect(resolveBreadcrumbNodes(undefined, undefined, "x")).toBeNull();
-    expect(resolveBreadcrumbNodes(null, null, "x")).toBeNull();
-  });
-});
-
-describe("computeBreadcrumbState (stale-chain clearing on navigation)", () => {
-  it("uses a freshly resolved chain when available", () => {
-    const child = treeNode("B");
-    const root = treeNode("root", { hasChildren: true, children: [child] });
-    const next = computeBreadcrumbState([root], null, "B", null);
-    expect(next!.map((n) => n.id)).toEqual(["root", "B"]);
-  });
-
-  it("navigating A->B to a page absent from treeData clears the previous A chain (no stale trail)", () => {
-    // Previous chain ends at page A; we are now on page B, which is not yet in
-    // the lazily-built tree and whose ancestors have not loaded.
-    const previous = [treeNode("rootA"), treeNode("A")];
-    const next = computeBreadcrumbState([treeNode("unrelated")], undefined, "B", previous);
-    // Must NOT keep showing A's (clickable) chain.
-    expect(next).toBeNull();
-  });
-
-  it("keeps a chain that already ends at the current page through a transient miss", () => {
-    // We already resolved B once (chain ends at B); a transient miss must not
-    // blank it.
-    const previous = [treeNode("rootB"), treeNode("B")];
-    const next = computeBreadcrumbState([], undefined, "B", previous);
-    expect(next).toBe(previous);
-  });
-
-  it("returns null when nothing resolves and there is no previous chain", () => {
-    expect(computeBreadcrumbState([], undefined, "B", null)).toBeNull();
-  });
-});

apps/client/src/features/page/components/breadcrumbs/breadcrumb.utils.ts

@@ -1,61 +0,0 @@
-import { IPage } from "@/features/page/types/page.types.ts";
-import { SpaceTreeNode } from "@/features/page/tree/types.ts";
-import { findBreadcrumbPath, pageToTreeNode } from "@/features/page/tree/utils";
-
-/**
- * Pure selection/mapping for the breadcrumb nodes (#218). Three branches:
- *   1. tree-hit  — the lazily-built sidebar tree already contains this page's
- *      ancestor chain, so prefer it (stays live with sidebar renames/moves).
- *   2. tree-miss — fall back to the page's own ancestor data so a deep page
- *      resolves immediately instead of rendering a blank breadcrumb for seconds
- *      while the tree backfills. Mapped through the canonical `pageToTreeNode`
- *      (title -> name, hasChildren defaulted to false).
- *   3. neither   — no data yet, return null (the caller decides whether to keep
- *      a prior chain via computeBreadcrumbState).
- */
-export function resolveBreadcrumbNodes(
-  treeData: SpaceTreeNode[] | null | undefined,
-  ancestors: IPage[] | null | undefined,
-  pageId: string,
-): SpaceTreeNode[] | null {
-  if (treeData && treeData.length > 0) {
-    const breadcrumb = findBreadcrumbPath(treeData, pageId);
-    if (breadcrumb) {
-      return breadcrumb;
-    }
-  }
-
-  if (ancestors && ancestors.length > 0) {
-    return ancestors.map((page) =>
-      pageToTreeNode(page, { hasChildren: page.hasChildren ?? false }),
-    );
-  }
-
-  return null;
-}
-
-/**
- * Decide the next breadcrumb state, given the previous one. When a chain
- * resolves (#218) it always wins. When nothing resolves yet, a stale chain from
- * a previously-viewed page must be CLEARED rather than left showing the wrong,
- * clickable trail (the reverse regression of the original blank-breadcrumb fix
- * when navigating A -> B to a deep page not yet in the lazily-built tree). The
- * one chain we keep through a transient miss is one that already ends at the
- * current page — that means we already resolved THIS page, so keeping it avoids
- * a needless blank flash without ever showing the previous page's chain.
- */
-export function computeBreadcrumbState(
-  treeData: SpaceTreeNode[] | null | undefined,
-  ancestors: IPage[] | null | undefined,
-  pageId: string,
-  previous: SpaceTreeNode[] | null,
-): SpaceTreeNode[] | null {
-  const resolved = resolveBreadcrumbNodes(treeData, ancestors, pageId);
-  if (resolved) {
-    return resolved;
-  }
-
-  const previousEndsAtCurrentPage =
-    previous != null && previous[previous.length - 1]?.id === pageId;
-  return previousEndsAtCurrentPage ? previous : null;
-}

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

@@ -12,6 +12,8 @@ import {
   IconList,
   IconMarkdown,
   IconPrinter,
+  IconCloud,
+  IconCloudCheck,
   IconStar,
   IconStarFilled,
   IconTrash,
@@ -39,6 +41,8 @@ import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
 import { htmlToMarkdown } from "@docmost/editor-ext";
 import {
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms.ts";
@@ -411,14 +415,16 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
 function ConnectionWarning() {
   const { t } = useTranslation();
   const yjsConnectionStatus = useAtomValue(yjsConnectionStatusAtom);
+  const isLocalSynced = useAtomValue(isLocalSyncedAtom);
+  const isRemoteSynced = useAtomValue(isRemoteSyncedAtom);
   const [showWarning, setShowWarning] = useState(false);
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  useEffect(() => {
-    const isDisconnected = ["disconnected", "connecting"].includes(
-      yjsConnectionStatus,
-    );
+  const isDisconnected = ["disconnected", "connecting"].includes(
+    yjsConnectionStatus,
+  );
 
+  useEffect(() => {
     if (isDisconnected) {
       if (!timeoutRef.current) {
         timeoutRef.current = setTimeout(() => setShowWarning(true), 5000);
@@ -430,7 +436,7 @@ function ConnectionWarning() {
       }
       setShowWarning(false);
     }
-  }, [yjsConnectionStatus]);
+  }, [isDisconnected]);
 
   // Cleanup only on unmount
   useEffect(() => {
@@ -441,22 +447,59 @@ function ConnectionWarning() {
     };
   }, []);
 
-  if (!showWarning) return null;
+  // State (1): offline/disconnected — changes are kept locally. Preserve the
+  // existing >5s debounce before surfacing this state.
+  if (isDisconnected) {
+    if (!showWarning) return null;
 
+    const offlineLabel = t(
+      "Offline — changes are saved locally and will sync when you reconnect",
+    );
+    return (
+      <Tooltip label={offlineLabel} openDelay={250} withArrow>
+        <ThemeIcon
+          variant="default"
+          c="red"
+          role="status"
+          aria-label={offlineLabel}
+          style={{ border: "none" }}
+        >
+          <IconWifiOff size={20} stroke={2} />
+        </ThemeIcon>
+      </Tooltip>
+    );
+  }
+
+  // State (2): connected but the remote replica is not fully caught up yet.
+  if (!isRemoteSynced || !isLocalSynced) {
+    const syncingLabel = t("Syncing changes…");
+    return (
+      <Tooltip label={syncingLabel} openDelay={250} withArrow>
+        <ThemeIcon
+          variant="default"
+          c="dimmed"
+          role="status"
+          aria-label={syncingLabel}
+          style={{ border: "none" }}
+        >
+          <IconCloud size={20} stroke={2} />
+        </ThemeIcon>
+      </Tooltip>
+    );
+  }
+
+  // State (3): fully synced — subtle confirmation indicator.
+  const syncedLabel = t("All changes synced");
   return (
-    <Tooltip
-      label={t("Real-time editor connection lost. Retrying...")}
-      openDelay={250}
-      withArrow
-    >
+    <Tooltip label={syncedLabel} openDelay={250} withArrow>
       <ThemeIcon
         variant="default"
-        c="red"
+        c="dimmed"
         role="status"
-        aria-label={t("Real-time editor connection lost. Retrying...")}
+        aria-label={syncedLabel}
         style={{ border: "none" }}
       >
-        <IconWifiOff size={20} stroke={2} />
+        <IconCloudCheck size={20} stroke={2} />
       </ThemeIcon>
     </Tooltip>
   );

apps/client/src/features/page/queries/page-query.ts

@@ -1,6 +1,7 @@
 import {
   InfiniteData,
   QueryKey,
+  queryOptions,
   useInfiniteQuery,
   UseInfiniteQueryResult,
   useMutation,
@@ -42,12 +43,38 @@ import { treeModel } from "@/features/page/tree/model/tree-model";
 import { SpaceTreeNode } from "@/features/page/tree/types";
 import { useQueryEmit } from "@/features/websocket/use-query-emit";
 import { moveToTrashNotificationMessage } from "@/features/page/components/move-to-trash-notification";
+import { offlineMutationKeys } from "@/features/offline/offline-mutations";
+
+/**
+ * Centralized React Query key factories for page queries. The hooks below and
+ * the offline warm path (features/offline/make-offline.ts) share these so the
+ * runtime keys can never silently drift apart.
+ */
+export const pageKeys = {
+  detail: (idOrSlug: string) => ["pages", idOrSlug] as const,
+  sidebar: (data: unknown) => ["sidebar-pages", data] as const,
+  rootSidebar: (spaceId: string) => ["root-sidebar-pages", spaceId] as const,
+  breadcrumbs: (pageId: string) => ["breadcrumbs", pageId] as const,
+  recentChanges: (spaceId?: string) => ["recent-changes", spaceId] as const,
+};
+
+/**
+ * Shared queryOptions for the sidebar-pages (ancestor children) query. Both
+ * fetchAllAncestorChildren and the offline warm path consume this so the key,
+ * queryFn and staleTime stay identical.
+ */
+export const sidebarPagesQueryOptions = (params: SidebarPagesParams) =>
+  queryOptions({
+    queryKey: pageKeys.sidebar(params),
+    queryFn: () => getAllSidebarPages(params),
+    staleTime: 30 * 60 * 1000,
+  });
 
 export function usePageQuery(
   pageInput: Partial<IPageInput>,
 ): UseQueryResult<IPage, Error> {
   const query = useQuery({
-    queryKey: ["pages", pageInput.pageId],
+    queryKey: pageKeys.detail(pageInput.pageId),
     queryFn: () => getPageById(pageInput),
     enabled: !!pageInput.pageId,
     staleTime: 5 * 60 * 1000,
@@ -56,9 +83,9 @@ export function usePageQuery(
   useEffect(() => {
     if (query.data) {
       if (isValidUuid(pageInput.pageId)) {
-        queryClient.setQueryData(["pages", query.data.slugId], query.data);
+        queryClient.setQueryData(pageKeys.detail(query.data.slugId), query.data);
       } else {
-        queryClient.setQueryData(["pages", query.data.id], query.data);
+        queryClient.setQueryData(pageKeys.detail(query.data.id), query.data);
       }
     }
   }, [query.data]);
@@ -69,6 +96,10 @@ export function usePageQuery(
 export function useCreatePageMutation() {
   const { t } = useTranslation();
   return useMutation<IPage, Error, Partial<IPageInput>>({
+    // Stable key so a paused create restored from IndexedDB after an offline
+    // reload finds its default mutationFn (registerOfflineMutationDefaults) and
+    // is replayed by resumePausedMutations() on reconnect instead of being lost.
+    mutationKey: offlineMutationKeys.createPage,
     mutationFn: (data) => createPage(data),
     onSuccess: (data) => {
       invalidateOnCreatePage(data);
@@ -80,18 +111,20 @@ export function useCreatePageMutation() {
 }
 
 export function updatePageData(data: IPage) {
-  const pageBySlug = queryClient.getQueryData<IPage>(["pages", data.slugId]);
-  const pageById = queryClient.getQueryData<IPage>(["pages", data.id]);
+  const pageBySlug = queryClient.getQueryData<IPage>(
+    pageKeys.detail(data.slugId),
+  );
+  const pageById = queryClient.getQueryData<IPage>(pageKeys.detail(data.id));
 
   if (pageBySlug) {
-    queryClient.setQueryData(["pages", data.slugId], {
+    queryClient.setQueryData(pageKeys.detail(data.slugId), {
       ...pageBySlug,
       ...data,
     });
   }
 
   if (pageById) {
-    queryClient.setQueryData(["pages", data.id], { ...pageById, ...data });
+    queryClient.setQueryData(pageKeys.detail(data.id), { ...pageById, ...data });
   }
 
   invalidateOnUpdatePage(
@@ -145,11 +178,11 @@ export function useRemovePageMutation() {
       });
 
       // Stamp deletedAt so a re-visit shows the trash banner, not stale state.
-      const cached = queryClient.getQueryData<IPage>(["pages", pageId]);
+      const cached = queryClient.getQueryData<IPage>(pageKeys.detail(pageId));
       if (cached) {
         const stamped = { ...cached, deletedAt: new Date() };
-        queryClient.setQueryData(["pages", cached.id], stamped);
-        queryClient.setQueryData(["pages", cached.slugId], stamped);
+        queryClient.setQueryData(pageKeys.detail(cached.id), stamped);
+        queryClient.setQueryData(pageKeys.detail(cached.slugId), stamped);
       }
 
       invalidateOnDeletePage(pageId);
@@ -188,6 +221,9 @@ export function useDeletePageMutation() {
 
 export function useMovePageMutation() {
   return useMutation<void, Error, IMovePage>({
+    // Stable key so a paused move restored from IndexedDB after an offline
+    // reload finds its default mutationFn and is replayed on reconnect.
+    mutationKey: offlineMutationKeys.movePage,
     mutationFn: (data) => movePage(data),
   });
 }
@@ -267,8 +303,11 @@ export function useRestorePageMutation() {
       // Replace would strip space/permissions/content and break the editor.
       const merge = (cached: IPage | undefined) =>
         cached ? { ...cached, ...restoredPage } : cached;
-      queryClient.setQueryData<IPage>(["pages", restoredPage.id], merge);
-      queryClient.setQueryData<IPage>(["pages", restoredPage.slugId], merge);
+      queryClient.setQueryData<IPage>(pageKeys.detail(restoredPage.id), merge);
+      queryClient.setQueryData<IPage>(
+        pageKeys.detail(restoredPage.slugId),
+        merge,
+      );
     },
     onError: (error) => {
       notifications.show({
@@ -283,7 +322,7 @@ export function useGetSidebarPagesQuery(
   data: SidebarPagesParams | null,
 ): UseInfiniteQueryResult<InfiniteData<IPagination<IPage>, unknown>> {
   return useInfiniteQuery({
-    queryKey: ["sidebar-pages", data],
+    queryKey: pageKeys.sidebar(data),
     enabled: !!data?.pageId || !!data?.spaceId,
     queryFn: ({ pageParam }) =>
       getSidebarPages({ ...data, cursor: pageParam, limit: 100 }),
@@ -294,7 +333,7 @@ export function useGetSidebarPagesQuery(
 
 export function useGetRootSidebarPagesQuery(data: SidebarPagesParams) {
   return useInfiniteQuery({
-    queryKey: ["root-sidebar-pages", data.spaceId],
+    queryKey: pageKeys.rootSidebar(data.spaceId),
     queryFn: async ({ pageParam }) => {
       return getSidebarPages({
         spaceId: data.spaceId,
@@ -320,7 +359,7 @@ export function usePageBreadcrumbsQuery(
   pageId: string,
 ): UseQueryResult<Partial<IPage[]>, Error> {
   return useQuery({
-    queryKey: ["breadcrumbs", pageId],
+    queryKey: pageKeys.breadcrumbs(pageId),
     queryFn: () => getPageBreadcrumbs(pageId),
     enabled: !!pageId,
   });
@@ -332,10 +371,12 @@ export async function fetchAllAncestorChildren(
   // refresh (#159 #8), which must NOT receive the 30-min-cached children.
   opts?: { fresh?: boolean },
 ) {
-  // not using a hook here, so we can call it inside a useEffect hook
+  // not using a hook here, so we can call it inside a useEffect hook. Reuse the
+  // shared sidebarPagesQueryOptions (key + queryFn) so the offline warm path and
+  // this fetch never drift, but override staleTime for the `fresh` reconnect
+  // refresh (#159 #8), which must force a server refetch (staleTime 0).
   const response = await queryClient.fetchQuery({
-    queryKey: ["sidebar-pages", params],
-    queryFn: () => getAllSidebarPages(params),
+    ...sidebarPagesQueryOptions(params),
     staleTime: opts?.fresh ? 0 : 30 * 60 * 1000,
   });
 
@@ -345,7 +386,7 @@ export async function fetchAllAncestorChildren(
 
 export function useRecentChangesQuery(spaceId?: string) {
   return useInfiniteQuery({
-    queryKey: ["recent-changes", spaceId],
+    queryKey: pageKeys.recentChanges(spaceId),
     queryFn: ({ pageParam }) =>
       getRecentChanges({ spaceId, cursor: pageParam, limit: 15 }),
     initialPageParam: undefined as string | undefined,
@@ -416,12 +457,12 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
   let queryKey: QueryKey = null;
   if (data.parentPageId === null) {
-    queryKey = ["root-sidebar-pages", data.spaceId];
+    queryKey = pageKeys.rootSidebar(data.spaceId);
   } else {
-    queryKey = [
-      "sidebar-pages",
-      { pageId: data.parentPageId, spaceId: data.spaceId },
-    ];
+    queryKey = pageKeys.sidebar({
+      pageId: data.parentPageId,
+      spaceId: data.spaceId,
+    });
   }
 
   //update all sidebar pages
@@ -481,7 +522,7 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
     //update root sidebar pages haschildern
     const rootSideBarMatches = queryClient.getQueriesData({
-      queryKey: ["root-sidebar-pages", data.spaceId],
+      queryKey: pageKeys.rootSidebar(data.spaceId),
       exact: false,
     });
 
@@ -505,7 +546,7 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
   //update recent changes
   queryClient.invalidateQueries({
-    queryKey: ["recent-changes", data.spaceId],
+    queryKey: pageKeys.recentChanges(data.spaceId),
   });
 }
 
@@ -519,9 +560,9 @@ export function invalidateOnUpdatePage(
   invalidatePageTree();
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
-    queryKey = ["root-sidebar-pages", spaceId];
+    queryKey = pageKeys.rootSidebar(spaceId);
   } else {
-    queryKey = ["sidebar-pages", { pageId: parentPageId, spaceId: spaceId }];
+    queryKey = pageKeys.sidebar({ pageId: parentPageId, spaceId: spaceId });
   }
   //update all sidebar pages
   queryClient.setQueryData<InfiniteData<IPagination<IPage>>>(
@@ -544,7 +585,7 @@ export function invalidateOnUpdatePage(
 
   //update recent changes
   queryClient.invalidateQueries({
-    queryKey: ["recent-changes", spaceId],
+    queryKey: pageKeys.recentChanges(spaceId),
   });
 }
 
@@ -559,8 +600,8 @@ export function updateCacheOnMovePage(
   // Remove page from old parent's cache
   const oldQueryKey =
     oldParentId === null
-      ? ["root-sidebar-pages", spaceId]
-      : ["sidebar-pages", { pageId: oldParentId, spaceId }];
+      ? pageKeys.rootSidebar(spaceId)
+      : pageKeys.sidebar({ pageId: oldParentId, spaceId });
 
   queryClient.setQueryData<InfiniteData<IPagination<IPage>>>(
     oldQueryKey,
@@ -580,7 +621,7 @@ export function updateCacheOnMovePage(
   if (oldParentId !== null) {
     const oldParentCache = queryClient.getQueryData<
       InfiniteData<IPagination<IPage>>
-    >(["sidebar-pages", { pageId: oldParentId, spaceId }]);
+    >(pageKeys.sidebar({ pageId: oldParentId, spaceId }));
 
     const remainingChildren =
       oldParentCache?.pages.flatMap((p) => p.items).length ?? 0;
@@ -618,8 +659,8 @@ export function updateCacheOnMovePage(
   // Add page to new parent's cache
   const newQueryKey =
     newParentId === null
-      ? ["root-sidebar-pages", spaceId]
-      : ["sidebar-pages", { pageId: newParentId, spaceId }];
+      ? pageKeys.rootSidebar(spaceId)
+      : pageKeys.sidebar({ pageId: newParentId, spaceId });
 
   queryClient.setQueryData<InfiniteData<IPagination<Partial<IPage>>>>(
     newQueryKey,

apps/client/src/features/page/tree/components/space-tree-node-menu.tsx

@@ -7,6 +7,7 @@ import { notifications } from "@mantine/notifications";
 import {
   IconArrowRight,
   IconClockHour4,
+  IconCloudDownload,
   IconCopy,
   IconDotsVertical,
   IconFileExport,
@@ -35,6 +36,12 @@ import {
   useToggleTemplateMutation,
   useToggleTemporaryMutation,
 } from "@/features/page-embed/queries/page-embed-query";
+import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
+import { getCollaborationUrl } from "@/lib/config.ts";
+import {
+  makePageAvailableOffline,
+  warmPageYdoc,
+} from "@/features/offline/make-offline";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { treeModel } from "@/features/page/tree/model/tree-model";
 import { pageToTreeNode } from "@/features/page/tree/utils";
@@ -72,6 +79,45 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
   const isTemplate = !!node.isTemplate;
   const toggleTemporary = useToggleTemporaryMutation();
   const isTemporary = !!node.temporaryExpiresAt;
+  const { data: collabQuery } = useCollabToken();
+
+  const handleMakeAvailableOffline = async () => {
+    notifications.show({ message: t("Saving page for offline use...") });
+    try {
+      // Prefetch read queries so they get persisted to IndexedDB. The result
+      // reports whether every warm step succeeded.
+      const result = await makePageAvailableOffline({
+        pageId: node.id,
+        spaceId: node.spaceId,
+      });
+      // Best-effort: warm the page's Yjs document into IndexedDB.
+      await warmPageYdoc(node.id, getCollaborationUrl(), collabQuery?.token);
+
+      if (result.ok) {
+        notifications.show({ message: t("Page is now available offline") });
+      } else {
+        // Partial warm — the page may still be partly usable offline, but some
+        // queries failed to cache, so surface it as an error rather than a
+        // silent success.
+        notifications.show({
+          message: t("Failed to make page available offline"),
+          color: "red",
+        });
+      }
+    } catch (err) {
+      // makePageAvailableOffline no longer throws, but warmPageYdoc and other
+      // unexpected failures stay guarded here. Log the raw error and surface the
+      // real cause to the user instead of a bare generic string (AGENTS.md).
+      console.error("handleMakeAvailableOffline failed", err);
+      const reason =
+        (err as { response?: { data?: { message?: string } } })?.response?.data
+          ?.message ?? (err instanceof Error ? err.message : String(err));
+      notifications.show({
+        message: `${t("Failed to make page available offline")}: ${reason}`,
+        color: "red",
+      });
+    }
+  };
 
   const handleToggleTemplate = async () => {
     const next = !isTemplate;
@@ -228,6 +274,17 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
             {t("Export")}
           </Menu.Item>
 
+          <Menu.Item
+            leftSection={<IconCloudDownload size={16} />}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              handleMakeAvailableOffline();
+            }}
+          >
+            {t("Make available offline")}
+          </Menu.Item>
+
           {canEdit && (
             <>
               <Menu.Item

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -15,7 +15,6 @@ import {
   useCreatePageMutation,
   useRemovePageMutation,
   useMovePageMutation,
-  useUpdatePageMutation,
   updateCacheOnMovePage,
 } from "@/features/page/queries/page-query.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -27,7 +26,6 @@ export type UseTreeMutation = {
     parentId: string | null,
     opts?: { temporary?: boolean },
   ) => Promise<void>;
-  handleRename: (id: string, name: string) => Promise<void>;
   handleDelete: (id: string) => Promise<void>;
 };
 
@@ -39,7 +37,6 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
   // children) and then immediately invokes a handler.
   const store = useStore();
   const createPageMutation = useCreatePageMutation();
-  const updatePageMutation = useUpdatePageMutation();
   const removePageMutation = useRemovePageMutation();
   const movePageMutation = useMovePageMutation();
   const navigate = useNavigate();
@@ -205,20 +202,6 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
     [spaceId, createPageMutation, setData, store, navigate, spaceSlug],
   );
 
-  const handleRename = useCallback(
-    async (id: string, name: string) => {
-      setData((prev) =>
-        treeModel.update(prev, id, { name } as Partial<SpaceTreeNode>),
-      );
-      try {
-        await updatePageMutation.mutateAsync({ pageId: id, title: name });
-      } catch (error) {
-        console.error("Error updating page title:", error);
-      }
-    },
-    [updatePageMutation, setData],
-  );
-
   const handleDelete = useCallback(
     async (id: string) => {
       const node = treeModel.find(
@@ -264,7 +247,7 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
     [removePageMutation, setData, store, pageSlug, navigate, spaceSlug],
   );
 
-  return { handleMove, handleCreate, handleRename, handleDelete };
+  return { handleMove, handleCreate, handleDelete };
 }
 
 function isPageInNode(node: SpaceTreeNode, pageSlug: string): boolean {

apps/client/src/features/share/components/share-modal.test.tsx

@@ -1,74 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, fireEvent, waitFor } from "@testing-library/react";
-import { MantineProvider } from "@mantine/core";
-import { MemoryRouter } from "react-router-dom";
-
-// matchMedia / storage are stubbed globally in vitest.setup.ts.
-
-// Enabling a public share must NOT silently expose the whole sub-tree (#216):
-// the create call defaults includeSubPages to false. This was a one-literal,
-// security-relevant default with no test — lock it.
-
-const createMutateAsync = vi.fn(async () => ({}));
-const deleteMutateAsync = vi.fn(async () => ({}));
-
-// No existing share for this page (toggle starts OFF).
-let shareData: any = undefined;
-
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
-}));
-
-vi.mock("@/features/share/queries/share-query.ts", () => ({
-  useCreateShareMutation: () => ({ mutateAsync: createMutateAsync }),
-  useDeleteShareMutation: () => ({ mutateAsync: deleteMutateAsync }),
-  useUpdateShareMutation: () => ({ mutateAsync: vi.fn() }),
-  useShareForPageQuery: () => ({ data: shareData }),
-}));
-
-vi.mock("@/features/page/queries/page-query.ts", () => ({
-  usePageQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
-}));
-
-vi.mock("@/features/space/queries/space-query.ts", () => ({
-  useSpaceQuery: () => ({ data: { settings: {} } }),
-}));
-
-import ShareModal from "./share-modal";
-
-function renderModal() {
-  return render(
-    <MemoryRouter>
-      <MantineProvider>
-        <ShareModal readOnly={false} />
-      </MantineProvider>
-    </MemoryRouter>,
-  );
-}
-
-describe("ShareModal — enabling a share defaults includeSubPages to false (#216)", () => {
-  beforeEach(() => {
-    createMutateAsync.mockClear();
-    deleteMutateAsync.mockClear();
-    shareData = undefined;
-  });
-
-  it("creates the share with includeSubPages: false when the user turns it on", async () => {
-    renderModal();
-
-    // Open the share popover.
-    fireEvent.click(screen.getByRole("button", { name: "Share" }));
-
-    // The "Share to web" toggle is the only switch in the not-yet-shared state.
-    const toggle = await screen.findByRole("switch");
-    fireEvent.click(toggle);
-
-    await waitFor(() => expect(createMutateAsync).toHaveBeenCalledTimes(1));
-    expect(createMutateAsync).toHaveBeenCalledWith(
-      expect.objectContaining({
-        pageId: "page-1",
-        includeSubPages: false,
-      }),
-    );
-  });
-});

apps/client/src/features/share/components/share-modal.tsx

@@ -73,10 +73,7 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
       if (value) {
         await createShareMutation.mutateAsync({
           pageId: pageId,
-          // Opt-in: enabling a share must NOT silently expose the whole
-          // sub-tree (#216). Sub-pages are shared only when the user turns on
-          // the dedicated "Include sub-pages" toggle.
-          includeSubPages: false,
+          includeSubPages: true,
           searchIndexing: false,
         });
       } else if (share && share.id) {

apps/client/src/features/share/types/share.types.ts

@@ -35,17 +35,9 @@ export interface ISharedItem extends IShare {
   };
 }
 
-// The `/shares/page-info` (anonymous) response. Mirrors the server-side
-// PublicSharePayload allowlist (#218): the server trims `page`/`share` to these
-// fields exactly, so the client type must not over-declare internal metadata it
-// will never receive. Keep this in sync with share-public-payload.ts.
-export interface ISharedPage {
-  page: Pick<IPage, "id" | "slugId" | "title" | "icon" | "content">;
-  share: {
-    id: string;
-    key: string;
-    includeSubPages: boolean;
-    searchIndexing: boolean;
+export interface ISharedPage extends IShare {
+  page: IPage;
+  share: IShare & {
     level: number;
     sharedPage: { id: string; slugId: string; title: string; icon: string };
   };
@@ -81,10 +73,6 @@ export type IUpdateShare = ICreateShare & { shareId: string; pageId?: string };
 
 export interface IShareInfoInput {
   pageId: string;
-  // The share id/key from the `/share/:shareId/p/:slug` URL. When present the
-  // server binds content access to this exact share (#218): a forged/mismatched
-  // shareId 404s instead of rendering the page off its slug alone.
-  shareId?: string;
 }
 
 // Vanity /l/:alias pointer.

apps/client/src/features/space/components/edit-space-form.test.tsx

@@ -1,240 +0,0 @@
-import {
-  describe,
-  it,
-  expect,
-  vi,
-  beforeAll,
-  afterEach,
-} from "vitest";
-import {
-  render,
-  screen,
-  cleanup,
-  fireEvent,
-  waitFor,
-} from "@testing-library/react";
-import { MantineProvider } from "@mantine/core";
-
-// --- Mocks for the heavy / networked module graph ---------------------------
-// EditSpaceForm wires the "Enable Git sync" Switch to a TanStack-Query mutation
-// (useUpdateSpaceMutation). We mock ONLY that hook so the test fully controls
-// mutateAsync (resolve / reject) and isPending, and stub i18n. The real Mantine
-// Switch is rendered so the checkbox role / disabled state is meaningful.
-
-// i18n: identity translator — labels stay as their English keys for queries.
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
-}));
-
-// Mutation hook: a controllable mutateAsync plus a togglable isPending.
-const mutateAsync = vi.fn();
-let isPending = false;
-vi.mock("@/features/space/queries/space-query.ts", () => ({
-  useUpdateSpaceMutation: () => ({
-    mutateAsync,
-    get isPending() {
-      return isPending;
-    },
-  }),
-}));
-
-// jsdom lacks matchMedia, which MantineProvider's color-scheme hook needs.
-beforeAll(() => {
-  if (!window.matchMedia) {
-    window.matchMedia = (query: string) =>
-      ({
-        matches: false,
-        media: query,
-        onchange: null,
-        addListener: () => {},
-        removeListener: () => {},
-        addEventListener: () => {},
-        removeEventListener: () => {},
-        dispatchEvent: () => false,
-      }) as unknown as MediaQueryList;
-  }
-});
-
-import { EditSpaceForm } from "./edit-space-form";
-import type { ISpace } from "@/features/space/types/space.types.ts";
-
-function makeSpace(overrides: Partial<ISpace> = {}): ISpace {
-  return {
-    id: "space-1",
-    name: "Engineering",
-    description: "",
-    slug: "eng",
-    hostname: "host",
-    creatorId: "u1",
-    createdAt: new Date("2026-01-01"),
-    updatedAt: new Date("2026-01-01"),
-    ...overrides,
-  } as ISpace;
-}
-
-function renderForm(props: { space: ISpace; readOnly?: boolean }) {
-  return render(
-    <MantineProvider>
-      <EditSpaceForm space={props.space} readOnly={props.readOnly} />
-    </MantineProvider>,
-  );
-}
-
-// The form now renders TWO switches (git-sync enable + auto-merge-conflicts) in
-// that DOM order. Mantine renders each as an <input type="checkbox"
-// role="switch"> but does NOT expose its label as the accessible name, so we
-// disambiguate by DOM order (index 0 = enable, 1 = auto-merge) and assert the
-// human-readable label text is present alongside.
-function getToggle(): HTMLInputElement {
-  screen.getByText("Enable Git sync");
-  return screen.getAllByRole("switch")[0] as HTMLInputElement;
-}
-
-function getAutoMergeToggle(): HTMLInputElement {
-  screen.getByText("Auto-merge conflicts on push");
-  return screen.getAllByRole("switch")[1] as HTMLInputElement;
-}
-
-afterEach(() => {
-  cleanup();
-  mutateAsync.mockReset();
-  isPending = false;
-});
-
-describe("EditSpaceForm git-sync toggle", () => {
-  // Test 3: initial checked state derives from settings.gitSync.enabled ?? false.
-  it("derives initial checked state from space.settings.gitSync.enabled (true -> checked)", () => {
-    renderForm({
-      space: makeSpace({ settings: { gitSync: { enabled: true } } }),
-    });
-    expect(getToggle().checked).toBe(true);
-  });
-
-  it("defaults to unchecked when gitSync settings are missing", () => {
-    renderForm({ space: makeSpace() });
-    expect(getToggle().checked).toBe(false);
-  });
-
-  // Test 4: toggling fires the mutation with { spaceId, gitSyncEnabled } and
-  // optimistically flips the switch.
-  it("fires the mutation with the correct payload and optimistically flips on", async () => {
-    mutateAsync.mockResolvedValue(undefined);
-    renderForm({ space: makeSpace() });
-
-    const toggle = getToggle();
-    expect(toggle.checked).toBe(false);
-
-    fireEvent.click(toggle);
-
-    // Optimistic update: the switch reflects the new state immediately.
-    expect(toggle.checked).toBe(true);
-
-    expect(mutateAsync).toHaveBeenCalledTimes(1);
-    expect(mutateAsync).toHaveBeenCalledWith({
-      spaceId: "space-1",
-      gitSyncEnabled: true,
-    });
-
-    // Resolution leaves the toggle on.
-    await waitFor(() => expect(toggle.checked).toBe(true));
-  });
-
-  // Test 5: rollback on mutation error — the most valuable test.
-  it("rolls back the toggle to its prior state when the mutation rejects", async () => {
-    mutateAsync.mockRejectedValue(new Error("network"));
-    renderForm({
-      space: makeSpace({ settings: { gitSync: { enabled: false } } }),
-    });
-
-    const toggle = getToggle();
-    expect(toggle.checked).toBe(false);
-
-    fireEvent.click(toggle);
-
-    // Optimistically flips on before the rejection lands.
-    expect(toggle.checked).toBe(true);
-    expect(mutateAsync).toHaveBeenCalledWith({
-      spaceId: "space-1",
-      gitSyncEnabled: true,
-    });
-
-    // After the rejected promise settles, the component reverts to OFF so the
-    // user is not misled into believing sync is enabled.
-    await waitFor(() => expect(toggle.checked).toBe(false));
-  });
-
-  // Test 6: disabled when readOnly and when the mutation is pending.
-  it("disables the toggle when readOnly", () => {
-    renderForm({ space: makeSpace(), readOnly: true });
-    expect(getToggle().disabled).toBe(true);
-  });
-
-  it("disables the toggle while the mutation is pending", () => {
-    isPending = true;
-    renderForm({ space: makeSpace() });
-    expect(getToggle().disabled).toBe(true);
-  });
-});
-
-describe("EditSpaceForm auto-merge-conflicts toggle", () => {
-  it("derives initial checked state from space.settings.gitSync.autoMergeConflicts (true -> checked)", () => {
-    renderForm({
-      space: makeSpace({
-        settings: { gitSync: { autoMergeConflicts: true } },
-      }),
-    });
-    expect(getAutoMergeToggle().checked).toBe(true);
-  });
-
-  it("defaults to unchecked when autoMergeConflicts is missing (SAFE default)", () => {
-    renderForm({ space: makeSpace() });
-    expect(getAutoMergeToggle().checked).toBe(false);
-  });
-
-  it("fires the mutation with { spaceId, autoMergeConflicts } and optimistically flips on", async () => {
-    mutateAsync.mockResolvedValue(undefined);
-    renderForm({ space: makeSpace() });
-
-    const toggle = getAutoMergeToggle();
-    expect(toggle.checked).toBe(false);
-
-    fireEvent.click(toggle);
-
-    // Optimistic update.
-    expect(toggle.checked).toBe(true);
-    expect(mutateAsync).toHaveBeenCalledTimes(1);
-    expect(mutateAsync).toHaveBeenCalledWith({
-      spaceId: "space-1",
-      autoMergeConflicts: true,
-    });
-
-    await waitFor(() => expect(toggle.checked).toBe(true));
-  });
-
-  it("rolls back to its prior state when the mutation rejects", async () => {
-    mutateAsync.mockRejectedValue(new Error("network"));
-    renderForm({
-      space: makeSpace({
-        settings: { gitSync: { autoMergeConflicts: false } },
-      }),
-    });
-
-    const toggle = getAutoMergeToggle();
-    expect(toggle.checked).toBe(false);
-
-    fireEvent.click(toggle);
-
-    expect(toggle.checked).toBe(true);
-    expect(mutateAsync).toHaveBeenCalledWith({
-      spaceId: "space-1",
-      autoMergeConflicts: true,
-    });
-
-    await waitFor(() => expect(toggle.checked).toBe(false));
-  });
-
-  it("disables the toggle when readOnly", () => {
-    renderForm({ space: makeSpace(), readOnly: true });
-    expect(getAutoMergeToggle().disabled).toBe(true);
-  });
-});

apps/client/src/features/space/components/edit-space-form.tsx

@@ -1,14 +1,5 @@
-import {
-  Group,
-  Box,
-  Button,
-  TextInput,
-  Stack,
-  Textarea,
-  Divider,
-  Switch,
-} from "@mantine/core";
-import React, { useState } from "react";
+import { Group, Box, Button, TextInput, Stack, Textarea } from "@mantine/core";
+import React from "react";
 import { useForm } from "@mantine/form";
 import { zod4Resolver } from "mantine-form-zod-resolver";
 import { z } from "zod/v4";
@@ -38,37 +29,6 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
   const { t } = useTranslation();
   const updateSpaceMutation = useUpdateSpaceMutation();
 
-  const [gitSyncEnabled, setGitSyncEnabled] = useState<boolean>(
-    space?.settings?.gitSync?.enabled ?? false,
-  );
-
-  const [autoMergeConflicts, setAutoMergeConflicts] = useState<boolean>(
-    space?.settings?.gitSync?.autoMergeConflicts ?? false,
-  );
-
-  // One parameterized handler for both git-sync space toggles: they differ only by
-  // the local state setter, the mutation payload field, and the error label. The
-  // update is optimistic and reverts the local state on failure (the mutation
-  // surfaces a toast via onError; the raw error is still logged per AGENTS.md).
-  const handleToggle = async (
-    field: "gitSyncEnabled" | "autoMergeConflicts",
-    value: boolean,
-    previous: boolean,
-    setLocal: (next: boolean) => void,
-    errorLabel: string,
-  ) => {
-    setLocal(value); // optimistic update
-    try {
-      await updateSpaceMutation.mutateAsync({
-        spaceId: space.id,
-        [field]: value,
-      });
-    } catch (err) {
-      setLocal(previous); // revert on failure
-      console.error(errorLabel, err);
-    }
-  };
-
   const form = useForm<FormValues>({
     validate: zod4Resolver(formSchema),
     initialValues: {
@@ -144,43 +104,6 @@ export function EditSpaceForm({ space, readOnly }: EditSpaceFormProps) {
             </Group>
           )}
         </form>
-
-        <Divider my="lg" />
-
-        <Switch
-          label={t("Enable Git sync")}
-          description={t("Sync this space's pages to a Git repository.")}
-          checked={gitSyncEnabled}
-          disabled={readOnly || updateSpaceMutation.isPending}
-          onChange={(event) =>
-            handleToggle(
-              "gitSyncEnabled",
-              event.currentTarget.checked,
-              gitSyncEnabled,
-              setGitSyncEnabled,
-              "Failed to toggle git-sync for space",
-            )
-          }
-        />
-
-        <Switch
-          mt="md"
-          label={t("Auto-merge conflicts on push")}
-          description={t(
-            "When off (recommended), a page whose content still has unresolved Git conflict markers is skipped on push until you resolve the conflict in Git. When on, the markers are stripped and both sides' content is pushed.",
-          )}
-          checked={autoMergeConflicts}
-          disabled={readOnly || updateSpaceMutation.isPending}
-          onChange={(event) =>
-            handleToggle(
-              "autoMergeConflicts",
-              event.currentTarget.checked,
-              autoMergeConflicts,
-              setAutoMergeConflicts,
-              "Failed to toggle git-sync auto-merge-conflicts",
-            )
-          }
-        />
       </Box>
     </>
   );

apps/client/src/features/space/queries/space-query.ts

@@ -1,5 +1,6 @@
 import {
   keepPreviousData,
+  queryOptions,
   useInfiniteQuery,
   useMutation,
   useQuery,
@@ -31,11 +32,37 @@ import { getRecentChanges } from "@/features/page/services/page-service.ts";
 import { useEffect } from "react";
 import { validate as isValidUuid } from "uuid";
 
+/**
+ * Centralized React Query key factories for space queries. The hooks below and
+ * the offline warm path (features/offline/make-offline.ts) share these so the
+ * runtime keys can never silently drift apart.
+ */
+export const spaceKeys = {
+  detail: (idOrSlug: string) => ["space", idOrSlug] as const,
+  list: (params?: QueryParams) => ["spaces", params] as const,
+  members: (spaceId: string, query?: string) =>
+    ["spaceMembers", spaceId, query] as const,
+};
+
+/**
+ * Shared queryOptions for fetching a space by id/slug. Both
+ * useGetSpaceBySlugQuery and the offline warm path consume this so the key,
+ * queryFn and staleTime stay identical. (`enabled` is intentionally omitted —
+ * prefetchQuery ignores it anyway and the warm path always passes a real id;
+ * the hook reapplies `enabled` itself.)
+ */
+export const spaceByIdQueryOptions = (spaceId: string) =>
+  queryOptions({
+    queryKey: spaceKeys.detail(spaceId),
+    queryFn: () => getSpaceById(spaceId),
+    staleTime: 5 * 60 * 1000,
+  });
+
 export function useGetSpacesQuery(
   params?: QueryParams,
 ): UseQueryResult<IPagination<ISpace>, Error> {
   return useQuery({
-    queryKey: ["spaces", params],
+    queryKey: spaceKeys.list(params),
     queryFn: () => getSpaces(params),
     placeholderData: keepPreviousData,
     refetchOnMount: true,
@@ -44,16 +71,16 @@ export function useGetSpacesQuery(
 
 export function useSpaceQuery(spaceId: string): UseQueryResult<ISpace, Error> {
   const query = useQuery({
-    queryKey: ["space", spaceId],
+    queryKey: spaceKeys.detail(spaceId),
     queryFn: () => getSpaceById(spaceId),
     enabled: !!spaceId,
   });
   useEffect(() => {
     if (query.data) {
       if (isValidUuid(spaceId)) {
-        queryClient.setQueryData(["space", query.data.slug], query.data);
+        queryClient.setQueryData(spaceKeys.detail(query.data.slug), query.data);
       } else {
-        queryClient.setQueryData(["space", query.data.id], query.data);
+        queryClient.setQueryData(spaceKeys.detail(query.data.id), query.data);
       }
     }
   }, [query.data]);
@@ -62,8 +89,11 @@ export function useSpaceQuery(spaceId: string): UseQueryResult<ISpace, Error> {
 }
 
 export const prefetchSpace = (spaceSlug: string, spaceId?: string) => {
+  // Note: intentionally NOT using spaceByIdQueryOptions here — that factory sets
+  // a 5min staleTime which would let this prefetch skip fetching fresh data;
+  // prefetchSpace must always refetch (default staleTime: 0).
   queryClient.prefetchQuery({
-    queryKey: ["space", spaceSlug],
+    queryKey: spaceKeys.detail(spaceSlug),
     queryFn: () => getSpaceById(spaceSlug),
   });
 
@@ -100,10 +130,8 @@ export function useGetSpaceBySlugQuery(
   spaceId: string,
 ): UseQueryResult<ISpace, Error> {
   return useQuery({
-    queryKey: ["space", spaceId],
-    queryFn: () => getSpaceById(spaceId),
+    ...spaceByIdQueryOptions(spaceId),
     enabled: !!spaceId,
-    staleTime: 5 * 60 * 1000,
   });
 }
 
@@ -116,14 +144,16 @@ export function useUpdateSpaceMutation() {
     onSuccess: (data, variables) => {
       notifications.show({ message: t("Space updated successfully") });
 
-      const space = queryClient.getQueryData([
-        "space",
-        variables.spaceId,
-      ]) as ISpace;
+      const space = queryClient.getQueryData(
+        spaceKeys.detail(variables.spaceId),
+      ) as ISpace;
       if (space) {
         const updatedSpace = { ...space, ...data };
-        queryClient.setQueryData(["space", variables.spaceId], updatedSpace);
-        queryClient.setQueryData(["space", data.slug], updatedSpace);
+        queryClient.setQueryData(
+          spaceKeys.detail(variables.spaceId),
+          updatedSpace,
+        );
+        queryClient.setQueryData(spaceKeys.detail(data.slug), updatedSpace);
       }
 
       queryClient.invalidateQueries({
@@ -148,7 +178,7 @@ export function useDeleteSpaceMutation() {
 
       if (variables.slug) {
         queryClient.removeQueries({
-          queryKey: ["space", variables.slug],
+          queryKey: spaceKeys.detail(variables.slug),
           exact: true,
         });
       }
@@ -156,7 +186,7 @@ export function useDeleteSpaceMutation() {
       // Remove space-specific queries
       if (variables.id) {
         queryClient.removeQueries({
-          queryKey: ["space", variables.id],
+          queryKey: spaceKeys.detail(variables.id),
           exact: true,
         });
 
@@ -196,7 +226,7 @@ export function useSpaceMembersInfiniteQuery(
   query?: string,
 ) {
   return useInfiniteQuery({
-    queryKey: ["spaceMembers", spaceId, query],
+    queryKey: spaceKeys.members(spaceId, query),
     queryFn: ({ pageParam }) =>
       getSpaceMembers(spaceId, { cursor: pageParam, limit: 50, query }),
     enabled: !!spaceId,

apps/client/src/features/space/types/space.types.ts

@@ -13,15 +13,9 @@ export interface ISpaceCommentsSettings {
   allowViewerComments?: boolean;
 }
 
-export interface ISpaceGitSyncSettings {
-  enabled?: boolean;
-  autoMergeConflicts?: boolean;
-}
-
 export interface ISpaceSettings {
   sharing?: ISpaceSharingSettings;
   comments?: ISpaceCommentsSettings;
-  gitSync?: ISpaceGitSyncSettings;
 }
 
 export interface ISpace {
@@ -41,8 +35,6 @@ export interface ISpace {
   // for updates
   disablePublicSharing?: boolean;
   allowViewerComments?: boolean;
-  gitSyncEnabled?: boolean;
-  autoMergeConflicts?: boolean;
 }
 
 interface IMembership {

apps/client/src/features/user/hooks/use-current-user.ts

@@ -2,9 +2,19 @@ import { useQuery, UseQueryResult } from "@tanstack/react-query";
 import { getMyInfo } from "@/features/user/services/user-service";
 import { ICurrentUser } from "@/features/user/types/user.types";
 
+/**
+ * Centralized React Query key factory for current-user queries. This hook and
+ * the offline warm path (features/offline/make-offline.ts) share it so the
+ * runtime key can never silently drift, and the OFFLINE_PERSIST_ROOTS guard
+ * test can assert the persisted "currentUser" root maps to a real factory.
+ */
+export const userKeys = {
+  currentUser: () => ["currentUser"] as const,
+};
+
 export default function useCurrentUser(): UseQueryResult<ICurrentUser> {
   return useQuery({
-    queryKey: ["currentUser"],
+    queryKey: userKeys.currentUser(),
     queryFn: async () => {
       return await getMyInfo();
     },

apps/client/src/features/user/user-provider.test.tsx

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { MemoryRouter } from "react-router-dom";
+import { HelmetProvider } from "react-helmet-async";
+
+// Control useCurrentUser per test; stub the rest of UserProvider's network/
+// socket dependencies so we only exercise its render-gating logic.
+const h = vi.hoisted(() => ({ useCurrentUser: vi.fn() }));
+
+vi.mock("@/features/user/hooks/use-current-user", () => ({
+  default: h.useCurrentUser,
+}));
+vi.mock("@/features/auth/queries/auth-query.tsx", () => ({
+  useCollabToken: () => ({ data: undefined }),
+}));
+vi.mock("@/features/websocket/use-query-subscription.ts", () => ({
+  useQuerySubscription: () => {},
+}));
+vi.mock("@/features/websocket/use-tree-socket.ts", () => ({
+  useTreeSocket: () => {},
+}));
+vi.mock("@/features/notification/hooks/use-notification-socket.ts", () => ({
+  useNotificationSocket: () => {},
+}));
+vi.mock("@/main.tsx", () => ({ queryClient: {} }));
+vi.mock("@/features/user/connect-resync.ts", () => ({
+  makeConnectHandler: () => () => {},
+}));
+vi.mock("socket.io-client", () => ({
+  io: () => ({ on: vi.fn(), disconnect: vi.fn() }),
+}));
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (k: string) => k,
+    i18n: {
+      changeLanguage: vi.fn(),
+      language: "en-US",
+      resolvedLanguage: "en-US",
+    },
+  }),
+}));
+
+import { UserProvider } from "./user-provider";
+
+const networkError = { message: "Network Error" }; // axios network error: no `response`
+
+function renderProvider() {
+  return render(
+    <HelmetProvider>
+      <MemoryRouter>
+        <MantineProvider>
+          <UserProvider>
+            <div data-testid="app-child">app content</div>
+          </UserProvider>
+        </MantineProvider>
+      </MemoryRouter>
+    </HelmetProvider>,
+  );
+}
+
+beforeEach(() => {
+  h.useCurrentUser.mockReset();
+});
+
+describe("UserProvider offline render-gating", () => {
+  it("renders the app (cached children) when useCurrentUser errors offline but a cached user exists", () => {
+    // Offline reload: the persisted ['currentUser'] cache hydrates `data`, but
+    // the background POST /api/users/me refetch fails as a network error.
+    h.useCurrentUser.mockReturnValue({
+      data: {
+        user: { id: "u1", locale: "en" },
+        workspace: { id: "w1" },
+      },
+      isLoading: false,
+      error: networkError,
+      isError: true,
+    });
+
+    renderProvider();
+
+    // The cached app must render — NOT a blank fragment (#237/#238).
+    expect(screen.getByTestId("app-child")).toBeDefined();
+    expect(screen.queryByText("You're offline")).toBeNull();
+  });
+
+  it("renders the offline fallback (not a blank fragment) when erroring with no cached user", () => {
+    h.useCurrentUser.mockReturnValue({
+      data: undefined,
+      isLoading: false,
+      error: networkError,
+      isError: true,
+    });
+
+    const { container } = renderProvider();
+
+    // Previously this returned `<></>` — a blank white screen. Now it must show
+    // an explicit offline fallback.
+    expect(screen.getByText("You're offline")).toBeDefined();
+    expect(screen.queryByTestId("app-child")).toBeNull();
+    expect(container.textContent?.length).toBeGreaterThan(0);
+  });
+
+  it("renders the app normally on a successful currentUser load", () => {
+    h.useCurrentUser.mockReturnValue({
+      data: {
+        user: { id: "u1", locale: "en" },
+        workspace: { id: "w1" },
+      },
+      isLoading: false,
+      error: null,
+      isError: false,
+    });
+
+    renderProvider();
+    expect(screen.getByTestId("app-child")).toBeDefined();
+  });
+});

apps/client/src/features/user/user-provider.tsx

@@ -11,6 +11,7 @@ import { useTreeSocket } from "@/features/websocket/use-tree-socket.ts";
 import { useNotificationSocket } from "@/features/notification/hooks/use-notification-socket.ts";
 import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import { Error404 } from "@/components/ui/error-404.tsx";
+import { OfflineFallback } from "@/features/offline/offline-fallback.tsx";
 import { queryClient } from "@/main.tsx";
 import { makeConnectHandler } from "@/features/user/connect-resync.ts";
 
@@ -70,14 +71,30 @@ export function UserProvider({ children }: React.PropsWithChildren) {
     document.documentElement.lang = i18n.resolvedLanguage || i18n.language || "en-US";
   }, [i18n.language, i18n.resolvedLanguage]);
 
-  if (isLoading) return <></>;
+  // First load with no cached user yet: render nothing briefly while the
+  // persisted ['currentUser'] cache hydrates (avoids flashing the offline
+  // fallback before restore). Once we have a user we render the app even if a
+  // refetch is still in flight.
+  if (isLoading && !data) return <></>;
 
   if (isError && error?.["response"]?.status === 404) {
     return <Error404 />;
   }
 
+  // We have a (possibly cached/stale) user — render the app. Offline, the
+  // POST /api/users/me refetch fails as a network error, but the persisted/
+  // hydrated user is enough to render the cached UI. Previously `if (error)
+  // return <></>` blanked every authenticated route on an offline reload even
+  // though the cached data was present (#237/#238).
+  if (data) {
+    return <>{children}</>;
+  }
+
+  // No user AND an error (offline cold boot of a page never warmed for offline,
+  // or no persisted cache to restore): show an explicit offline fallback rather
+  // than a blank white screen.
   if (error) {
-    return <></>;
+    return <OfflineFallback />;
   }
 
   return <>{children}</>;

apps/client/src/main.tsx

@@ -11,7 +11,8 @@ import { MantineProvider } from "@mantine/core";
 import { BrowserRouter } from "react-router-dom";
 import { ModalsProvider } from "@mantine/modals";
 import { Notifications } from "@mantine/notifications";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { QueryClient } from "@tanstack/react-query";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
 import { HelmetProvider } from "react-helmet-async";
 import "./i18n";
 import { PostHogProvider } from "posthog-js/react";
@@ -21,6 +22,13 @@ import {
   isCloud,
   isPostHogEnabled,
 } from "@/lib/config.ts";
+import {
+  queryPersister,
+  shouldDehydrateOfflineQuery,
+} from "@/features/offline/query-persister";
+import { registerOfflineMutationDefaults } from "@/features/offline/offline-mutations";
+import { PwaUpdatePrompt } from "@/pwa/pwa-update-prompt";
+import { isCapacitorNativePlatform } from "@/pwa/is-capacitor";
 import posthog from "posthog-js";
 
 export const queryClient = new QueryClient({
@@ -30,10 +38,18 @@ export const queryClient = new QueryClient({
       refetchOnWindowFocus: false,
       retry: false,
       staleTime: 5 * 60 * 1000,
+      // Keep cached read data around long enough to be persisted/restored for offline use.
+      gcTime: 1000 * 60 * 60 * 24,
     },
   },
 });
 
+// Register default mutationFns for the offline-relevant structural mutations so
+// a paused mutation restored from IndexedDB after an offline reload still has a
+// mutationFn and is replayed by resumePausedMutations() on reconnect (instead
+// of silently no-op'ing and dropping the offline create/move/comment).
+registerOfflineMutationDefaults(queryClient);
+
 if (isCloud() && isPostHogEnabled) {
   posthog.init(getPostHogKey(), {
     api_host: getPostHogHost(),
@@ -50,15 +66,34 @@ root.render(
   <BrowserRouter>
     <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
       <ModalsProvider>
-        <QueryClientProvider client={queryClient}>
+        <PersistQueryClientProvider
+          client={queryClient}
+          persistOptions={{
+            persister: queryPersister,
+            maxAge: 1000 * 60 * 60 * 24,
+            buster: APP_VERSION,
+            dehydrateOptions: {
+              shouldDehydrateQuery: shouldDehydrateOfflineQuery,
+            },
+          }}
+        >
           <Notifications position="bottom-center" limit={3} zIndex={10000} />
+          {/* Skip SW registration inside the Capacitor native WebView — the
+              native shell serves assets itself; a browser SW would conflict. */}
+          {!isCapacitorNativePlatform() && <PwaUpdatePrompt />}
           <HelmetProvider>
             <PostHogProvider client={posthog}>
               <App />
             </PostHogProvider>
           </HelmetProvider>
-        </QueryClientProvider>
+        </PersistQueryClientProvider>
       </ModalsProvider>
     </MantineProvider>
   </BrowserRouter>,
 );
+
+// Service worker registration is owned by <PwaUpdatePrompt /> above (via
+// vite-plugin-pwa's useRegisterSW: Workbox precache + prompt-based updates,
+// and skipped inside the Capacitor native WebView). The earlier hand-written
+// /sw.js registration from the mobile bootstrap was removed here to avoid a
+// double registration / competing service worker.

apps/client/src/pages/share/shared-page.tsx

@@ -24,9 +24,6 @@ export default function SharedPage() {
 
   const { data, isLoading, isError, error } = useSharePageQuery({
     pageId: extractPageSlugId(pageSlug),
-    // Forward the URL's shareId so the server binds content to this share
-    // (#218): a forged shareId 404s instead of rendering the page off its slug.
-    shareId,
   });
 
   const sharedTreeData = useAtomValue(sharedTreeDataAtom);

apps/client/src/pwa/is-capacitor.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { isCapacitorNativePlatform } from "./is-capacitor";
+
+describe("isCapacitorNativePlatform", () => {
+  afterEach(() => {
+    // Keep tests isolated from each other and from the rest of the suite.
+    delete (globalThis as any).Capacitor;
+  });
+
+  it("returns false when Capacitor is undefined", () => {
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+
+  it("uses isNativePlatform() when it is a function", () => {
+    (globalThis as any).Capacitor = { isNativePlatform: () => true };
+    expect(isCapacitorNativePlatform()).toBe(true);
+
+    (globalThis as any).Capacitor = { isNativePlatform: () => false };
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+
+  it("falls back to the boolean property when isNativePlatform is not a function", () => {
+    (globalThis as any).Capacitor = { isNativePlatform: true };
+    expect(isCapacitorNativePlatform()).toBe(true);
+
+    (globalThis as any).Capacitor = { isNativePlatform: false };
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+
+  it("returns false when reading Capacitor throws (try/catch)", () => {
+    Object.defineProperty(globalThis, "Capacitor", {
+      configurable: true,
+      get() {
+        throw new Error("boom");
+      },
+    });
+    expect(isCapacitorNativePlatform()).toBe(false);
+  });
+});

apps/client/src/pwa/is-capacitor.ts

@@ -0,0 +1,23 @@
+/**
+ * Detects whether the client is running inside a Capacitor native WebView
+ * (native iOS/Android shell from the feature/mobile-app-bootstrap branch).
+ *
+ * This is a pure runtime check against the global `Capacitor` object that the
+ * native bridge injects — no `@capacitor/*` dependency is added. On the plain
+ * browser / installed-PWA path `window.Capacitor` is undefined, so this returns
+ * false and the Workbox service worker registers normally.
+ *
+ * Inside the native WebView the SW must NOT register: it would layer a redundant
+ * (and conflicting) cache over Capacitor's own asset serving and interfere with
+ * the native auth/CORS flow.
+ */
+export function isCapacitorNativePlatform(): boolean {
+  try {
+    const cap = (globalThis as any)?.Capacitor;
+    return !!(cap && typeof cap.isNativePlatform === "function"
+      ? cap.isNativePlatform()
+      : cap?.isNativePlatform);
+  } catch {
+    return false;
+  }
+}

apps/client/src/pwa/pwa-update-prompt.tsx

@@ -0,0 +1,59 @@
+import { useEffect } from "react";
+import { Button } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+import { useRegisterSW } from "virtual:pwa-register/react";
+
+// Stable notification id so we can show/hide a single update prompt.
+const UPDATE_NOTIFICATION_ID = "pwa-update-available";
+
+/**
+ * Listens for a waiting service worker and surfaces a Mantine notification
+ * prompting the user to reload into the new version.
+ *
+ * Must be mounted inside the Mantine provider subtree (Notifications must be
+ * available). Renders nothing itself.
+ */
+export function PwaUpdatePrompt() {
+  const { t } = useTranslation();
+
+  const {
+    needRefresh: [needRefresh],
+    updateServiceWorker,
+  } = useRegisterSW({
+    onRegisterError(error) {
+      // Best-effort: a failed registration must not break the app.
+      console.error("Service worker registration error:", error);
+    },
+  });
+
+  useEffect(() => {
+    if (!needRefresh) return;
+
+    notifications.show({
+      id: UPDATE_NOTIFICATION_ID,
+      title: t("Update available"),
+      message: (
+        <Button
+          size="xs"
+          variant="light"
+          mt="xs"
+          onClick={() => updateServiceWorker(true)}
+        >
+          {t("Reload")}
+        </Button>
+      ),
+      autoClose: false,
+      withCloseButton: true,
+    });
+
+    // Hide the notification when the prompt is no longer needed / on cleanup.
+    return () => {
+      notifications.hide(UPDATE_NOTIFICATION_ID);
+    };
+  }, [needRefresh, t, updateServiceWorker]);
+
+  return null;
+}
+
+export default PwaUpdatePrompt;

apps/client/src/pwa/sw-strategy.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { isApiPath, isCollabOrSocketPath } from "./sw-strategy";
+
+describe("isApiPath", () => {
+  it("matches the /api segment and its subtree", () => {
+    expect(isApiPath("/api")).toBe(true);
+    expect(isApiPath("/api/")).toBe(true);
+    expect(isApiPath("/api/pages")).toBe(true);
+  });
+
+  it("does not over-match sibling paths", () => {
+    expect(isApiPath("/apidocs")).toBe(false);
+    expect(isApiPath("/apixyz")).toBe(false);
+    expect(isApiPath("/")).toBe(false);
+    expect(isApiPath("/pages")).toBe(false);
+  });
+});
+
+describe("isCollabOrSocketPath", () => {
+  it("matches the /collab and /socket.io segments and their subtrees", () => {
+    expect(isCollabOrSocketPath("/collab")).toBe(true);
+    expect(isCollabOrSocketPath("/collab/x")).toBe(true);
+    expect(isCollabOrSocketPath("/socket.io")).toBe(true);
+    expect(isCollabOrSocketPath("/socket.io/abc")).toBe(true);
+  });
+
+  it("does not over-match sibling paths", () => {
+    expect(isCollabOrSocketPath("/collaborators")).toBe(false);
+    expect(isCollabOrSocketPath("/collabx")).toBe(false);
+    expect(isCollabOrSocketPath("/socket.iox")).toBe(false);
+  });
+});

apps/client/src/pwa/sw-strategy.ts

@@ -0,0 +1,32 @@
+/**
+ * Canonical service-worker routing predicates.
+ *
+ * IMPORTANT: With vite-plugin-pwa using Workbox `generateSW`, the
+ * `runtimeCaching[].urlPattern` functions are serialized standalone into the
+ * generated service worker and CANNOT reference imported symbols. The matching
+ * logic is therefore duplicated as inline regex literals in
+ * apps/client/vite.config.ts. This module is the testable source of truth, and
+ * the two MUST be kept in sync. This duplication is intentional and is the
+ * documented Workbox limitation.
+ *
+ * Matching is anchored to a path SEGMENT boundary (`^/<seg>(/|$)`) so that
+ * sibling paths like `/apidocs`, `/collaborators`, `/socket.iox` are NOT
+ * wrongly treated as API/realtime traffic.
+ */
+
+/**
+ * True when `pathname` is the `/api` segment or anything beneath it.
+ * `/api` and `/api/...` -> true; `/apidocs`, `/apixyz` -> false.
+ */
+export function isApiPath(pathname: string): boolean {
+  return /^\/api(\/|$)/.test(pathname);
+}
+
+/**
+ * True when `pathname` is the `/collab` or `/socket.io` segment (or beneath it).
+ * `/collab`, `/collab/x`, `/socket.io`, `/socket.io/abc` -> true;
+ * `/collaborators`, `/collabx`, `/socket.iox` -> false.
+ */
+export function isCollabOrSocketPath(pathname: string): boolean {
+  return /^\/(collab|socket\.io)(\/|$)/.test(pathname);
+}

apps/client/src/vite-env.d.ts

@@ -1,2 +1,4 @@
 /// <reference types="vite/client" />
+/// <reference types="vite-plugin-pwa/react" />
+/// <reference types="vite-plugin-pwa/info" />
 declare const APP_VERSION: string

apps/client/vite.config.ts

@@ -1,5 +1,6 @@
 import { defineConfig, loadEnv } from "vite";
 import react from "@vitejs/plugin-react";
+import { VitePWA } from "vite-plugin-pwa";
 import * as path from "path";
 import { execSync } from "node:child_process";
 
@@ -53,7 +54,51 @@ export default defineConfig(({ mode }) => {
       },
       APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
     },
-    plugins: [react()],
+    plugins: [
+      react(),
+      VitePWA({
+        registerType: "prompt",
+        injectRegister: null,
+        strategies: "generateSW",
+        manifest: false,
+        workbox: {
+          globPatterns: ["**/*.{js,css,html,svg,png,ico,woff2,json}"],
+          navigateFallback: "index.html",
+          // Segment-anchored (`^/<seg>(/|$)`) so navigation requests to these
+          // segments are consistently excluded from the SPA fallback, mirroring
+          // the runtimeCaching urlPattern regexes below.
+          //
+          // `/share`, `/mcp`, and `/robots.txt` mirror the server static-serve
+          // exclude list (apps/server/src/main.ts setGlobalPrefix `exclude`):
+          // robots.txt, the SEO/OG/analytics-injected public share HTML, and the
+          // embedded MCP endpoint are served by server controllers, so the SW must
+          // never shadow them with the precached index.html app shell (doing so
+          // would break SEO and MCP).
+          navigateFallbackDenylist: [
+            /^\/api(\/|$)/,
+            /^\/collab(\/|$)/,
+            /^\/socket\.io(\/|$)/,
+            /^\/share(\/|$)/,
+            /^\/mcp(\/|$)/,
+            /^\/robots\.txt$/,
+          ],
+          cleanupOutdatedCaches: true,
+          clientsClaim: true,
+          // The urlPattern regexes below mirror apps/client/src/pwa/sw-strategy.ts
+          // and MUST be kept in sync with it. Workbox `generateSW` serializes these
+          // functions standalone into the generated service worker, so they cannot
+          // import the module — the matching logic is intentionally duplicated as
+          // self-contained inline regex literals anchored to a path segment boundary.
+          runtimeCaching: [
+            { urlPattern: ({ url }) => /^\/(collab|socket\.io)(\/|$)/.test(url.pathname), handler: "NetworkOnly" },
+            // All /api stays network-only; offline reads come from the persisted
+            // React Query cache (IndexedDB) + y-indexeddb, not the SW HTTP cache.
+            { urlPattern: ({ url }) => /^\/api(\/|$)/.test(url.pathname), handler: "NetworkOnly" },
+          ],
+        },
+        devOptions: { enabled: false },
+      }),
+    ],
     build: {
       rolldownOptions: {
         output: {

apps/server/package.json

@@ -23,7 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/git-sync build && pnpm --filter @docmost/mcp build",
+    "pretest": "pnpm --filter @docmost/editor-ext build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -41,7 +41,6 @@
     "@aws-sdk/s3-request-presigner": "3.1050.0",
     "@azure/storage-blob": "12.31.0",
     "@clickhouse/client": "^1.18.2",
-    "@docmost/git-sync": "workspace:*",
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
     "@fastify/cookie": "^11.0.2",
@@ -65,6 +64,7 @@
     "@nestjs/platform-fastify": "^11.1.19",
     "@nestjs/platform-socket.io": "^11.1.19",
     "@nestjs/schedule": "^6.1.3",
+    "@nestjs/swagger": "^11.2.0",
     "@nestjs/terminus": "^11.1.1",
     "@nestjs/throttler": "^6.5.0",
     "@nestjs/websockets": "^11.1.19",
@@ -189,12 +189,7 @@
           ]
         }
       ],
-      "^.+\\.(t|j)sx?$": [
-        "ts-jest",
-        {
-          "isolatedModules": true
-        }
-      ]
+      "^.+\\.(t|j)sx?$": "ts-jest"
     },
     "transformIgnorePatterns": [
       "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
@@ -204,17 +199,11 @@
     ],
     "coverageDirectory": "../coverage",
     "testEnvironment": "node",
-    "setupFiles": [
-      "<rootDir>/../test/jest.setup.ts"
-    ],
     "moduleNameMapper": {
       "^@docmost/db/(.*)$": "<rootDir>/database/$1",
       "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
       "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
-      "^src/(.*)$": "<rootDir>/$1",
-      "^@docmost/git-sync$": "<rootDir>/../../../packages/git-sync/src/index.ts",
-      "^@docmost/git-sync/(.*)$": "<rootDir>/../../../packages/git-sync/src/$1",
-      "^(\\.{1,2}/.*)\\.js$": "$1"
+      "^src/(.*)$": "<rootDir>/$1"
     }
   }
 }

apps/server/src/app.module.ts

@@ -28,7 +28,6 @@ import { ClsModule } from 'nestjs-cls';
 import { NoopAuditModule } from './integrations/audit/audit.module';
 import { ThrottleModule } from './integrations/throttle/throttle.module';
 import { McpModule } from './integrations/mcp/mcp.module';
-import { GitSyncModule } from './integrations/git-sync/git-sync.module';
 import { AiModule } from './integrations/ai/ai.module';
 import { AiChatModule } from './core/ai-chat/ai-chat.module';
 
@@ -90,7 +89,6 @@ try {
     TelemetryModule,
     ThrottleModule,
     McpModule,
-    GitSyncModule,
     AiModule,
     AiChatModule,
     ...enterpriseModules,

apps/server/src/collaboration/collaboration.gateway.ts

@@ -24,7 +24,9 @@ import { CollabWsAdapter } from './adapter/collab-ws.adapter';
 import {
   CollaborationHandler,
   CollabEventHandlers,
+  writeTitleFragment,
 } from './collaboration.handler';
+import { User } from '@docmost/db/types/entity.types';
 
 @Injectable()
 export class CollaborationGateway {
@@ -150,42 +152,42 @@ export class CollaborationGateway {
   }
 
   /**
-   * Write a git-originated body into a page, applying the merge on the instance
-   * that OWNS the live Y.Doc so a connected editor CONVERGES on the change.
+   * Write a new page title INTO the page's Yjs 'title' fragment, Redis-INDEPENDENT.
    *
-   * git-sync must NOT use openDirectConnection directly for this: that opens the
-   * document on whichever instance/process runs git-sync (the API/worker). When
-   * an editor is connected to a DIFFERENT collab instance/process, that is a
-   * SEPARATE, detached Y.Doc — the merge lands in the detached doc and the DB,
-   * but the live editor never receives the Yjs update; its next debounced
-   * autosave then overwrites the DB with its stale state and SILENTLY REVERTS
-   * the git change (the data-loss bug). Routing through the custom-event channel
-   * runs the merge on the owning instance's shared Document, whose update is
-   * broadcast to every connection (handleUpdate), so the editor's CRDT converges
-   * on the merged result.
+   * Unlike the Redis-routed `handleYjsEvent` path — which routes through
+   * `redisSync?.handleEvent` and SILENTLY no-ops when Redis is disabled
+   * (COLLAB_DISABLE_REDIS=true → redisSync === null) — this goes straight
+   * through the local Hocuspocus `openDirectConnection`. The title sync
+   * therefore works in BOTH single-process (no Redis) and Redis-clustered
+   * deployments.
    *
-   * Without redis there is a single instance, so the write runs locally — which
-   * is already the owning (and only) instance the editor is connected to.
+   * openDirectConnection loads the doc from persistence when no editor is
+   * connected, so this works whether or not an editor is currently open: the
+   * clear+reseed lands on the loaded doc and is persisted by onStoreDocument.
+   *
+   * Provenance: when the caller is the agent, the actor/aiChatId are threaded
+   * into the connection `context` so onStoreDocument sees `context.actor ===
+   * 'agent'` for the resulting title store (mirrors the body/REST path). The
+   * resulting title store is usually a no-op anyway — PageService already wrote
+   * the same title to the page.title column, so onStoreDocument's
+   * `titleText !== page.title` guard skips the column write — but we wire the
+   * context for correctness regardless.
    */
-  async writePageBody(
-    documentName: string,
-    payload: {
-      prosemirrorJson: unknown;
-      baseProsemirrorJson?: unknown;
-      userId: string;
-    },
+  async writePageTitle(
+    pageId: string,
+    title: string,
+    context?: { user?: User; actor?: string; aiChatId?: string },
   ): Promise<void> {
-    if (this.redisSync) {
-      await this.handleYjsEvent(
-        'gitSyncWriteBody',
-        documentName,
-        payload as any,
-      );
-      return;
+    const documentName = `page.${pageId}`;
+    const connection = await this.hocuspocus.openDirectConnection(
+      documentName,
+      context ?? {},
+    );
+    try {
+      await connection.transact((doc) => writeTitleFragment(doc, title));
+    } finally {
+      await connection.disconnect();
     }
-    await this.collabEventsService
-      .getHandlers(this.hocuspocus)
-      .gitSyncWriteBody(documentName, payload as any);
   }
 
   /*

apps/server/src/collaboration/collaboration.handler.git-sync.spec.ts

@@ -1,262 +0,0 @@
-// Exercises the REAL `gitSyncWriteBody` collab handler (the owner-routed body
-// write the data-loss fix introduces). The handler imports the editor graph via
-// collaboration.util / yjs.util (tiptapExtensions -> editor-ext -> react-dom,
-// unloadable under jest's node env, same coupling noted in
-// gitmost-datasource.service.spec.ts), so we stub those + the transformer. The
-// stubbed toYdoc builds paragraph blocks straight from the ProseMirror JSON so
-// we can assert convergence on real text.
-jest.mock('./collaboration.util', () => ({
-  tiptapExtensions: [],
-  getPageId: (name: string) => name.replace(/^page\./, ''),
-  prosemirrorNodeToYElement: jest.fn(),
-}));
-jest.mock('./yjs.util', () => ({
-  setYjsMark: jest.fn(),
-  updateYjsMarkAttribute: jest.fn(),
-}));
-jest.mock('@hocuspocus/transformer', () => {
-  const Yjs = require('yjs');
-  return {
-    TiptapTransformer: {
-      toYdoc: (json: any) => {
-        if (json?.__throw) throw new Error('boom: malformed doc');
-        const d = new Yjs.Doc();
-        const frag = d.getXmlFragment('default');
-        const blocks = (json?.content ?? []).map((node: any) => {
-          const el = new Yjs.XmlElement(node.type || 'paragraph');
-          const text = (node.content ?? [])
-            .map((t: any) => t.text ?? '')
-            .join('');
-          const t = new Yjs.XmlText();
-          if (text) t.insert(0, text);
-          el.insert(0, [t]);
-          return el;
-        });
-        if (blocks.length) frag.insert(0, blocks);
-        return d;
-      },
-    },
-  };
-});
-
-import * as Y from 'yjs';
-import { CollaborationHandler } from './collaboration.handler';
-
-const pmDoc = (...paras: string[]) => ({
-  type: 'doc',
-  content: paras.map((text) => ({
-    type: 'paragraph',
-    content: text ? [{ type: 'text', text }] : [],
-  })),
-});
-
-const texts = (frag: Y.XmlFragment): string[] =>
-  frag.toArray().map((el) =>
-    (el as Y.XmlElement)
-      .toArray()
-      .map((c) => (c as Y.XmlText).toString())
-      .join(''),
-  );
-
-// Build a fake Hocuspocus whose openDirectConnection yields a DirectConnection
-// over a REAL shared Document, with a connected "editor" doc that receives the
-// shared doc's updates (modelling Document.handleUpdate's broadcast on the
-// OWNING instance). Initial content carries live block ids; the editor starts
-// fully synced with the shared doc.
-function fakeHocuspocus(initial: { text: string; id: string }[]) {
-  const shared = new Y.Doc();
-  const frag = shared.getXmlFragment('default');
-  shared.transact(() => {
-    frag.insert(
-      0,
-      initial.map((s) => {
-        const el = new Y.XmlElement('paragraph');
-        el.setAttribute('id', s.id);
-        const t = new Y.XmlText();
-        if (s.text) t.insert(0, s.text);
-        el.insert(0, [t]);
-        return el;
-      }),
-    );
-  });
-  const editor = new Y.Doc();
-  Y.applyUpdate(editor, Y.encodeStateAsUpdate(shared));
-  // Broadcast relay: server-originated updates flow to the connected editor.
-  shared.on('update', (u: Uint8Array, origin: any) => {
-    if (origin !== 'editor') Y.applyUpdate(editor, u, 'server');
-  });
-
-  const openDirectConnection = jest.fn(async () => ({
-    // DirectConnection.transact runs the fn directly against the Document (no
-    // wrapping Y transaction), exactly like @hocuspocus/server.
-    transact: async (fn: (doc: Y.Doc) => void) => fn(shared),
-    disconnect: jest.fn(async () => undefined),
-  }));
-
-  return { hocuspocus: { openDirectConnection } as any, shared, editor };
-}
-
-describe('CollaborationHandler.gitSyncWriteBody (owner-routed body write)', () => {
-  it('converges a connected editor on the git change (no silent revert)', async () => {
-    const { hocuspocus, shared, editor } = fakeHocuspocus([
-      { text: 'alpha', id: 'p1' },
-      { text: 'beta', id: 'p2' },
-    ]);
-    const handler = new CollaborationHandler();
-    const handlers = handler.getHandlers(hocuspocus);
-
-    // git changed block 1 beta -> beta2; base is the pre-change content.
-    await handlers.gitSyncWriteBody('page.x', {
-      prosemirrorJson: pmDoc('alpha', 'beta2'),
-      baseProsemirrorJson: pmDoc('alpha', 'beta'),
-      userId: 'svc-user',
-    });
-
-    // The shared (owning-instance) doc holds the merge...
-    expect(texts(shared.getXmlFragment('default'))).toEqual(['alpha', 'beta2']);
-    // ...and the connected editor CONVERGED via the broadcast (the bug would
-    // leave it on 'beta' and revert the page on its next autosave).
-    expect(texts(editor.getXmlFragment('default'))).toEqual(['alpha', 'beta2']);
-  });
-
-  it('preserves a concurrent edit to a DIFFERENT block (3-way, finding #2)', async () => {
-    const { hocuspocus, shared, editor } = fakeHocuspocus([
-      { text: 'alpha', id: 'p1' },
-      { text: 'beta', id: 'p2' },
-    ]);
-    // The editor is actively editing block 0 while the push arrives.
-    const eFrag = editor.getXmlFragment('default');
-    editor.transact(
-      () => (eFrag.get(0) as Y.XmlElement).get(0) instanceof Y.XmlText &&
-        ((eFrag.get(0) as Y.XmlElement).get(0) as Y.XmlText).insert(5, ' EDIT'),
-      'editor',
-    );
-    Y.applyUpdate(shared, Y.encodeStateAsUpdate(editor), 'editor');
-
-    const handler = new CollaborationHandler();
-    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
-      prosemirrorJson: pmDoc('alpha', 'beta2'),
-      baseProsemirrorJson: pmDoc('alpha', 'beta'),
-      userId: 'svc-user',
-    });
-
-    // Human's block-0 edit AND git's block-1 change both survive on the editor.
-    expect(texts(editor.getXmlFragment('default'))).toEqual([
-      'alpha EDIT',
-      'beta2',
-    ]);
-  });
-
-  it('FLUSHES the pending debounced store BEFORE merging so an in-flight edit survives (finding #2)', async () => {
-    // QA #119 finding #2: the 3-way merge must run against the latest live-doc
-    // state. A concurrent UI edit that is still in-flight (the store is debounced)
-    // must be drained into the live doc BEFORE git merges, or git clean-applies and
-    // the edit is silently dropped — even on a DIFFERENT block. Model the drain via
-    // the pending-store flush: when it runs, the in-flight block-0 edit lands.
-    const shared = new Y.Doc();
-    const frag = shared.getXmlFragment('default');
-    shared.transact(() => {
-      frag.insert(
-        0,
-        [
-          { text: 'alpha', id: 'p1' },
-          { text: 'beta', id: 'p2' },
-        ].map((s) => {
-          const el = new Y.XmlElement('paragraph');
-          el.setAttribute('id', s.id);
-          const t = new Y.XmlText();
-          t.insert(0, s.text);
-          el.insert(0, [t]);
-          return el;
-        }),
-      );
-    });
-
-    const order: string[] = [];
-    const debouncer = {
-      isDebounced: jest.fn(() => true),
-      executeNow: jest.fn(async () => {
-        order.push('flush');
-        // The in-flight client edit to block 0 only lands once the pending store
-        // is flushed (i.e. the event loop is drained) — BEFORE the merge.
-        shared.transact(() =>
-          ((frag.get(0) as Y.XmlElement).get(0) as Y.XmlText).insert(5, ' EDIT'),
-        );
-      }),
-    };
-    const openDirectConnection = jest.fn(async () => ({
-      transact: async (fn: (doc: Y.Doc) => void) => {
-        order.push('merge');
-        fn(shared);
-      },
-      disconnect: jest.fn(async () => undefined),
-    }));
-    const hocuspocus = { openDirectConnection, debouncer } as any;
-
-    const handler = new CollaborationHandler();
-    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
-      prosemirrorJson: pmDoc('alpha', 'beta2'), // git changes block 1
-      baseProsemirrorJson: pmDoc('alpha', 'beta'),
-      userId: 'svc-user',
-    });
-
-    // The flush ran, and it ran BEFORE the merge transaction.
-    expect(debouncer.executeNow).toHaveBeenCalledTimes(1);
-    expect(order).toEqual(['flush', 'merge']);
-    // Both the in-flight block-0 edit and git's block-1 change survive — the
-    // pre-flush bug would have produced ['alpha', 'beta2'] (UI edit dropped).
-    expect(texts(shared.getXmlFragment('default'))).toEqual([
-      'alpha EDIT',
-      'beta2',
-    ]);
-  });
-
-  it('does not flush when no store is pending (isDebounced false)', async () => {
-    const { hocuspocus, shared } = fakeHocuspocus([{ text: 'a', id: 'p1' }]);
-    const executeNow = jest.fn();
-    (hocuspocus as any).debouncer = {
-      isDebounced: jest.fn(() => false),
-      executeNow,
-    };
-    const handler = new CollaborationHandler();
-    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
-      prosemirrorJson: pmDoc('a', 'b'),
-      userId: 'svc-user',
-    });
-    expect(executeNow).not.toHaveBeenCalled();
-    expect(texts(shared.getXmlFragment('default'))).toEqual(['a', 'b']);
-  });
-
-  it('crash-safe: a transform failure never opens the connection or mutates the live doc', async () => {
-    const { hocuspocus, shared } = fakeHocuspocus([{ text: 'alpha', id: 'p1' }]);
-    const before = texts(shared.getXmlFragment('default'));
-    const handler = new CollaborationHandler();
-
-    await expect(
-      handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
-        prosemirrorJson: { __throw: true } as any,
-        userId: 'svc-user',
-      }),
-    ).rejects.toThrow('boom');
-
-    // The incoming doc is built BEFORE opening the connection, so the throw
-    // happens first: the live doc is untouched and no connection was opened.
-    expect(hocuspocus.openDirectConnection).not.toHaveBeenCalled();
-    expect(texts(shared.getXmlFragment('default'))).toEqual(before);
-  });
-
-  it('falls back to a 2-way merge when no base is supplied', async () => {
-    const { hocuspocus, shared, editor } = fakeHocuspocus([
-      { text: 'alpha', id: 'p1' },
-    ]);
-    const handler = new CollaborationHandler();
-
-    await handler.getHandlers(hocuspocus).gitSyncWriteBody('page.x', {
-      prosemirrorJson: pmDoc('alpha', 'gamma'),
-      userId: 'svc-user',
-    });
-
-    expect(texts(shared.getXmlFragment('default'))).toEqual(['alpha', 'gamma']);
-    expect(texts(editor.getXmlFragment('default'))).toEqual(['alpha', 'gamma']);
-  });
-});

apps/server/src/collaboration/collaboration.handler.spec.ts

@@ -0,0 +1,139 @@
+import * as Y from 'yjs';
+import { TiptapTransformer } from '@hocuspocus/transformer';
+import { writeTitleFragment } from './collaboration.handler';
+import { CollaborationGateway } from './collaboration.gateway';
+import {
+  buildTitleSeedYdoc,
+  jsonToText,
+  tiptapExtensions,
+} from './collaboration.util';
+
+// Read the plain text held in the doc's 'title' XmlFragment, the same way
+// PersistenceExtension.onStoreDocument extracts it before writing page.title.
+const readTitleText = (doc: Y.Doc): string => {
+  const titleJson = TiptapTransformer.fromYdoc(doc, 'title');
+  return titleJson ? jsonToText(titleJson).trim() : '';
+};
+
+describe('writeTitleFragment — the clear+seed title write (Bug 1)', () => {
+  it('replaces an OLD title fragment with EXACTLY the new title (no duplication)', () => {
+    // Seed the doc's 'title' fragment with an OLD title, like a real page.
+    const doc = new Y.Doc();
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Old Title')));
+    expect(readTitleText(doc)).toBe('Old Title');
+
+    writeTitleFragment(doc, 'New Title');
+
+    // The fragment must contain EXACTLY the new title — not "Old TitleNew Title"
+    // (append) or "New TitleNew Title" (duplication). A single heading node.
+    expect(readTitleText(doc)).toBe('New Title');
+
+    const titleJson = TiptapTransformer.fromYdoc(doc, 'title') as any;
+    expect(titleJson.content).toHaveLength(1);
+    expect(titleJson.content[0].type).toBe('heading');
+  });
+
+  it('seeds the title fragment when it started empty', () => {
+    const doc = new Y.Doc();
+    // Force the 'title' fragment to exist but be empty.
+    doc.getXmlFragment('title');
+    expect(readTitleText(doc)).toBe('');
+
+    writeTitleFragment(doc, 'First Title');
+
+    expect(readTitleText(doc)).toBe('First Title');
+  });
+
+  it('does not corrupt the body when rewriting the title', () => {
+    // A doc with both a body and an old title; the body must survive untouched.
+    const doc = new Y.Doc();
+    const bodyDoc = TiptapTransformer.toYdoc(
+      {
+        type: 'doc',
+        content: [
+          { type: 'paragraph', content: [{ type: 'text', text: 'body text' }] },
+        ],
+      },
+      'default',
+      tiptapExtensions,
+    );
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(bodyDoc));
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Old')));
+
+    writeTitleFragment(doc, 'New');
+
+    expect(readTitleText(doc)).toBe('New');
+    const bodyJson = TiptapTransformer.fromYdoc(doc, 'default');
+    expect(jsonToText(bodyJson)).toContain('body text');
+  });
+});
+
+describe('CollaborationGateway.writePageTitle — Redis-independent path', () => {
+  // Build a gateway with only its hocuspocus.openDirectConnection stubbed; the
+  // method must drive the clear+seed through that direct connection (NOT through
+  // redisSync), so the title write survives COLLAB_DISABLE_REDIS.
+  const makeGateway = (doc: Y.Doc) => {
+    const disconnect = jest.fn().mockResolvedValue(undefined);
+    const transact = jest.fn(async (fn: (d: Y.Doc) => void) => {
+      fn(doc);
+    });
+    const openDirectConnection = jest
+      .fn()
+      .mockResolvedValue({ transact, disconnect });
+
+    const gateway = Object.create(CollaborationGateway.prototype);
+    // redisSync is intentionally null — this is the no-Redis scenario.
+    gateway.redisSync = null;
+    gateway.hocuspocus = { openDirectConnection } as any;
+
+    return { gateway, openDirectConnection, transact, disconnect };
+  };
+
+  it('writes the new title via openDirectConnection and disconnects', async () => {
+    const doc = new Y.Doc();
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Old Title')));
+
+    const { gateway, openDirectConnection, disconnect } = makeGateway(doc);
+
+    await gateway.writePageTitle('page-1', 'New Title', { user: { id: 'u1' } });
+
+    expect(openDirectConnection).toHaveBeenCalledWith(
+      'page.page-1',
+      expect.objectContaining({ user: { id: 'u1' } }),
+    );
+    expect(readTitleText(doc)).toBe('New Title');
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it('threads agent provenance into the connection context', async () => {
+    const doc = new Y.Doc();
+    const { gateway, openDirectConnection } = makeGateway(doc);
+
+    await gateway.writePageTitle('page-1', 'Agent Title', {
+      user: { id: 'u1' },
+      actor: 'agent',
+      aiChatId: 'chat-1',
+    });
+
+    expect(openDirectConnection).toHaveBeenCalledWith(
+      'page.page-1',
+      expect.objectContaining({ actor: 'agent', aiChatId: 'chat-1' }),
+    );
+  });
+
+  it('disconnects even when the transaction throws', async () => {
+    const disconnect = jest.fn().mockResolvedValue(undefined);
+    const openDirectConnection = jest.fn().mockResolvedValue({
+      transact: jest.fn().mockRejectedValue(new Error('boom')),
+      disconnect,
+    });
+    const gateway = Object.create(CollaborationGateway.prototype);
+    gateway.redisSync = null;
+    gateway.hocuspocus = { openDirectConnection } as any;
+
+    await expect(
+      gateway.writePageTitle('page-1', 'X', {}),
+    ).rejects.toThrow('boom');
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+});

apps/server/src/collaboration/collaboration.handler.ts

@@ -2,21 +2,47 @@ import { Injectable, Logger } from '@nestjs/common';
 import { Hocuspocus, Document } from '@hocuspocus/server';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
+  buildTitleSeedYdoc,
   prosemirrorNodeToYElement,
   tiptapExtensions,
 } from './collaboration.util';
 import { setYjsMark, updateYjsMarkAttribute, YjsSelection } from './yjs.util';
 import * as Y from 'yjs';
 import { User } from '@docmost/db/types/entity.types';
-import {
-  mergeXmlFragments,
-  mergeXmlFragments3WayWithStats,
-} from './merge/yjs-body-merge';
 
 export type CollabEventHandlers = ReturnType<
   CollaborationHandler['getHandlers']
 >;
 
+/**
+ * Clear+reseed the 'title' XmlFragment of `doc` so it holds EXACTLY `title`.
+ *
+ * Used by the gateway's direct `writePageTitle` method to write a new page
+ * title INTO the page's Yjs 'title' fragment. The title lives in the same
+ * Y.Doc as the body; onStoreDocument extracts it on every save, so a REST/MCP
+ * rename that only updated the page.title DB column would be reverted on the
+ * next collaborative save unless the Yjs 'title' fragment is kept in sync.
+ * The whole fragment is replaced (no merge/append),
+ * mirroring the 'replace' body path: the new title fully supersedes the old.
+ *
+ * DELIBERATE TRADE-OFF: because this does a FULL clear+replace of the 'title'
+ * fragment, a REST/MCP rename arriving while a user is actively editing the
+ * title in an open editor WILL overwrite that in-progress edit. This is
+ * acceptable — the title is a short, rarely-concurrently-edited field — and is
+ * preferable to leaving a stale Yjs title that onStoreDocument would revert the
+ * DB column to on the next save.
+ */
+export function writeTitleFragment(doc: Y.Doc, title: string): void {
+  const titleFragment = doc.getXmlFragment('title');
+
+  if (titleFragment.length > 0) {
+    titleFragment.delete(0, titleFragment.length);
+  }
+
+  const newTitleDoc = buildTitleSeedYdoc(title);
+  Y.applyUpdate(doc, Y.encodeStateAsUpdate(newTitleDoc));
+}
+
 @Injectable()
 export class CollaborationHandler {
   private readonly logger = new Logger(CollaborationHandler.name);
@@ -116,130 +142,9 @@ export class CollaborationHandler {
           },
         );
       },
-      /**
-       * Git-sync body write, applied as a block-level MERGE into the LIVE doc on
-       * the instance that OWNS it (routed here via the custom-event channel —
-       * see CollaborationGateway.writePageBody). Running on the owning instance
-       * is what makes a connected editor CONVERGE: the merge mutates the shared
-       * Document, whose update is broadcast to every connection, so the editor's
-       * CRDT applies the git change instead of silently reverting it on its next
-       * autosave (the data-loss bug this fixes).
-       *
-       * With a `baseProsemirrorJson` (the last-synced common ancestor) it does a
-       * THREE-WAY merge — a block only the human changed is kept, a block only
-       * git changed is taken (conflicts -> git). Without a base it falls back to
-       * the 2-way merge.
-       */
-      gitSyncWriteBody: async (
-        documentName: string,
-        payload: {
-          prosemirrorJson: any;
-          baseProsemirrorJson?: any;
-          userId: string;
-        },
-      ) => {
-        const { prosemirrorJson, baseProsemirrorJson, userId } = payload;
-
-        // Build the incoming (and base) Yjs docs BEFORE opening the connection /
-        // touching the live doc. If a transform throws (a malformed/unsupported
-        // doc) we must NOT have mutated the live body — otherwise a conversion
-        // failure could leave the page empty (crash-safe conversion).
-        const targetDoc = TiptapTransformer.toYdoc(
-          prosemirrorJson,
-          'default',
-          tiptapExtensions,
-        );
-        const baseDoc =
-          baseProsemirrorJson != null
-            ? TiptapTransformer.toYdoc(
-                baseProsemirrorJson,
-                'default',
-                tiptapExtensions,
-              )
-            : null;
-
-        // CONCURRENT-EDIT FLUSH (QA #119, finding #2). The 3-way merge below runs
-        // against the LIVE Y.Doc, so a concurrent UI edit is only preserved if it
-        // is already part of that doc. A user's edit is debounced before it lands
-        // (the editor batches; the collab store is debounced up to 10s), so the
-        // merge could otherwise run against a PRE-EDIT doc: git would then
-        // clean-apply (no same-block conflict detected) and the in-flight UI edit
-        // — even on a DIFFERENT block — would be silently dropped.
-        //
-        // Flushing the pending debounced store here (a) drains the event loop so a
-        // just-arrived client Yjs update is applied to the live doc BEFORE we
-        // merge, and (b) persists the live doc so the merge baseline is current
-        // even on the doc-reload-from-DB path. After the flush the merge sees the
-        // latest state, so an edit on a different block is MERGED (not overwritten)
-        // and a genuine same-block edit is detected as a conflict -> the
-        // boundary-snapshot in PersistenceExtension pins it to page history
-        // (recoverable) instead of vanishing silently.
-        await this.flushPendingStore(hocuspocus, documentName);
-
-        // actor:'git-sync' + the service user flow into PersistenceExtension
-        // (lastUpdatedSource='git-sync', lastUpdatedById=userId).
-        await this.withYdocConnection(
-          hocuspocus,
-          documentName,
-          { actor: 'git-sync', user: { id: userId } },
-          (doc) => {
-            const liveFrag = doc.getXmlFragment('default');
-            const targetFrag = targetDoc.getXmlFragment('default');
-            if (baseDoc) {
-              const { conflicts } = mergeXmlFragments3WayWithStats(
-                liveFrag,
-                targetFrag,
-                baseDoc.getXmlFragment('default'),
-              );
-              // SAME-BLOCK conflict contract (SPEC §9): a block both the human
-              // and git changed resolves to GIT (deterministic). Make that
-              // OBSERVABLE rather than silent — log it. The losing human content
-              // is NOT destroyed: the persistence extension's boundary snapshot
-              // pins the pre-merge page state to history on this user->git-sync
-              // transition, so it stays recoverable.
-              if (conflicts > 0) {
-                this.logger.warn(
-                  `git-sync merge for ${documentName}: ${conflicts} same-block ` +
-                    `conflict(s) resolved to the git version; the prior page ` +
-                    `state is preserved in page history (recoverable).`,
-                );
-              }
-            } else {
-              mergeXmlFragments(liveFrag, targetFrag);
-            }
-          },
-        );
-      },
     };
   }
 
-  /**
-   * Flush any pending DEBOUNCED store for `documentName` so the live Y.Doc and the
-   * DB are current BEFORE a git-sync merge reads them (QA #119, finding #2 —
-   * concurrent UI edit silently lost). Mirrors the PersistenceExtension.onDisconnect
-   * flush: only acts when a store is actually pending (`isDebounced`), runs the
-   * SAME scheduled payload (`executeNow`, preserving the edit's context/actor), and
-   * never throws — a flush failure must not abort the git-sync write. Awaiting it
-   * also drains the event loop, so a client Yjs update sitting in the socket buffer
-   * is applied to the live doc before the merge transaction runs.
-   */
-  private async flushPendingStore(
-    hocuspocus: Hocuspocus,
-    documentName: string,
-  ): Promise<void> {
-    const debounceId = `onStoreDocument-${documentName}`;
-    try {
-      const debouncer = (hocuspocus as any)?.debouncer;
-      if (!debouncer?.isDebounced?.(debounceId)) return;
-      await debouncer.executeNow(debounceId);
-    } catch (err) {
-      this.logger.warn(
-        `git-sync pre-merge flush failed for ${documentName}: ` +
-          (err instanceof Error ? err.message : String(err)),
-      );
-    }
-  }
-
   async withYdocConnection(
     hocuspocus: Hocuspocus,
     documentName: string,

apps/server/src/collaboration/collaboration.util.spec.ts

@@ -1,9 +1,13 @@
 import * as Y from 'yjs';
+import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
   getPageId,
   isEmptyParagraphDoc,
   jsonToNode,
   prosemirrorNodeToYElement,
+  buildTitleSeedYdoc,
+  jsonToText,
+  tiptapExtensions,
 } from './collaboration.util';
 import { Node } from '@tiptap/pm/model';
 
@@ -241,3 +245,49 @@ describe('prosemirrorNodeToYElement', () => {
     expect(element.get(1).get(0).toString()).toBe('two');
   });
 });
+
+describe('buildTitleSeedYdoc', () => {
+  it('builds a level-1 heading carrying the title text', () => {
+    const doc = buildTitleSeedYdoc('Hello World');
+    const json: any = TiptapTransformer.fromYdoc(doc, 'title');
+
+    const first = json.content?.[0];
+    expect(first.type).toBe('heading');
+    expect(first.attrs.level).toBe(1);
+    expect(jsonToText(json).trim()).toBe('Hello World');
+  });
+
+  it('produces a non-empty title fragment for a non-empty title', () => {
+    const doc = buildTitleSeedYdoc('Some Title');
+    expect(doc.get('title', Y.XmlFragment).length).toBeGreaterThan(0);
+  });
+
+  it('produces a heading with no text child for an empty title', () => {
+    const doc = buildTitleSeedYdoc('');
+    const json: any = TiptapTransformer.fromYdoc(doc, 'title');
+
+    const first = json.content?.[0];
+    expect(first.type).toBe('heading');
+    // No text content for an empty title.
+    expect(first.content ?? []).toHaveLength(0);
+    expect(jsonToText(json).trim()).toBe('');
+  });
+
+  it('round-trips a title through build -> extract -> build -> extract', () => {
+    const title = 'Round Trip Title';
+    const doc1 = buildTitleSeedYdoc(title);
+    const text1 = jsonToText(TiptapTransformer.fromYdoc(doc1, 'title')).trim();
+
+    const doc2 = buildTitleSeedYdoc(text1);
+    const text2 = jsonToText(TiptapTransformer.fromYdoc(doc2, 'title')).trim();
+
+    expect(text1).toBe(title);
+    expect(text2).toBe(text1);
+  });
+
+  // Touch tiptapExtensions so the import is exercised (mirrors the brief's import
+  // list and guards against accidental tree-shaking of the schema dependency).
+  it('uses the shared tiptap extensions schema', () => {
+    expect(Array.isArray(tiptapExtensions)).toBe(true);
+  });
+});

apps/server/src/collaboration/collaboration.util.ts

@@ -59,6 +59,7 @@ import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
 import { Node, Schema } from '@tiptap/pm/model';
 import * as Y from 'yjs';
 import { Logger } from '@nestjs/common';
+import { TiptapTransformer } from '@hocuspocus/transformer';
 
 export const tiptapExtensions = [
   StarterKit.configure({
@@ -143,6 +144,34 @@ export function jsonToText(tiptapJson: JSONContent) {
   return generateText(tiptapJson, tiptapExtensions);
 }
 
+/**
+ * Build a standalone Y.Doc that holds ONLY the page title, in a dedicated Yjs
+ * fragment named exactly 'title' (the collaborative title-editor contract with
+ * the client). The ProseMirror shape is a doc with a single level-1 heading
+ * whose text is the title (empty title => heading with no text child).
+ *
+ * The encoded state of the returned doc can be merged into a body doc via
+ * `Y.applyUpdate(doc, Y.encodeStateAsUpdate(titleSeed))` to seed the title
+ * fragment for legacy pages. Seeding MUST be guarded by an emptiness check on
+ * the existing 'title' fragment to avoid the Yjs duplication trap.
+ */
+export function buildTitleSeedYdoc(title: string): Y.Doc {
+  return TiptapTransformer.toYdoc(
+    {
+      type: 'doc',
+      content: [
+        {
+          type: 'heading',
+          attrs: { level: 1 },
+          content: title ? [{ type: 'text', text: title }] : [],
+        },
+      ],
+    },
+    'title',
+    tiptapExtensions,
+  );
+}
+
 export function jsonToNode(tiptapJson: JSONContent) {
   const schema = getSchema(tiptapExtensions);
   try {

apps/server/src/collaboration/constants.ts

@@ -1,3 +1,9 @@
 export const HISTORY_INTERVAL = 5 * 60 * 1000;
 export const HISTORY_FAST_INTERVAL = 60 * 1000;
 export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
+
+// Redis pub/sub channel that bridges a PAGE_UPDATED tree snapshot (a title/icon
+// rename) from the standalone collab process to the API process, which is the
+// single broadcast authority. Imported by both halves of the bridge:
+// PageTreeBridgePublisher (collab process) and PageTreeBridgeSubscriber (API process).
+export const COLLAB_TREE_UPDATE_CHANNEL = 'collab:tree-update';

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

@@ -205,32 +205,6 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(historyQueue.add).toHaveBeenCalledTimes(1);
   });
 
-  // #206 persist-6 — RED (it.failing): a momentarily-empty live Y.Doc must not
-  // overwrite non-empty persisted content. `onStoreDocument` empty-guards the
-  // LOAD path but not the STORE path, so today an empty doc (a client/agent
-  // glitch, a bad merge, an emptying transclusion) is written straight over the
-  // page and the content is wiped silently. A store-side empty-guard is a real
-  // behaviour change (a deliberate "select-all + delete" is also empty), so it
-  // is left UNFIXED pending a product decision; this documents the data-loss
-  // path and flips to a normal passing test the moment the guard lands.
-  it.failing(
-    'does NOT overwrite non-empty content with a momentarily-empty live doc (persist-6)',
-    async () => {
-      const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
-      const document = ydocFor(emptyDoc);
-      pageRepo.findById.mockResolvedValue({
-        ...persistedHumanPage('IGNORED'),
-        content: doc('IMPORTANT RICH CONTENT'),
-      });
-
-      await ext.onStoreDocument(buildData(document, 'user') as any);
-
-      // Desired contract: the empty incoming doc is rejected and the rich page
-      // survives. Today updatePage is called with the empty content (data loss).
-      expect(pageRepo.updatePage).not.toHaveBeenCalled();
-    },
-  );
-
   // persist-1 — when every attempt fails the hook must NOT report a phantom
   // success: no "page.updated" badge broadcast and no history snapshot for
   // content that was never written.

apps/server/src/collaboration/extensions/persistence.disconnect-flush.spec.ts

@@ -1,89 +0,0 @@
-import { PersistenceExtension } from './persistence.extension';
-
-/**
- * Regression for the QA #119 "loss-on-fast-close" data loss: editing a page then
- * closing the tab within the collab debounce window (~3-18s) lost the edit
- * because, with `unloadImmediately: false`, Hocuspocus does NOT flush the
- * debounced onStoreDocument on a last-client disconnect. PersistenceExtension
- * now flushes the pending store on the LAST disconnect (and only then).
- */
-describe('PersistenceExtension.onDisconnect flush (loss-on-fast-close)', () => {
-  function makeExt(): PersistenceExtension {
-    // onDisconnect touches none of the injected deps; pass casts.
-    return new PersistenceExtension(
-      null as any,
-      null as any,
-      null as any,
-      null as any,
-      null as any,
-      null as any,
-      null as any,
-      null as any,
-    );
-  }
-
-  function makeData(opts: {
-    clientsCount: number;
-    isDebounced: boolean;
-    isLoading?: boolean;
-  }) {
-    const executeNow = jest.fn(async () => undefined);
-    const isDebounced = jest.fn(() => opts.isDebounced);
-    return {
-      executeNow,
-      isDebounced,
-      payload: {
-        clientsCount: opts.clientsCount,
-        context: {},
-        document: { isLoading: opts.isLoading ?? false } as any,
-        documentName: 'page.abc',
-        instance: { debouncer: { isDebounced, executeNow } } as any,
-        requestHeaders: {},
-        requestParameters: new URLSearchParams(),
-        socketId: 's',
-      } as any,
-    };
-  }
-
-  it('flushes the pending store when the LAST client disconnects', async () => {
-    const ext = makeExt();
-    const { executeNow, payload } = makeData({
-      clientsCount: 0,
-      isDebounced: true,
-    });
-    await ext.onDisconnect(payload);
-    expect(executeNow).toHaveBeenCalledTimes(1);
-    expect(executeNow).toHaveBeenCalledWith('onStoreDocument-page.abc');
-  });
-
-  it('does NOT flush while other editors remain connected', async () => {
-    const ext = makeExt();
-    const { executeNow, payload } = makeData({
-      clientsCount: 2,
-      isDebounced: true,
-    });
-    await ext.onDisconnect(payload);
-    expect(executeNow).not.toHaveBeenCalled();
-  });
-
-  it('does NOT write when nothing is pending (already persisted)', async () => {
-    const ext = makeExt();
-    const { executeNow, payload } = makeData({
-      clientsCount: 0,
-      isDebounced: false,
-    });
-    await ext.onDisconnect(payload);
-    expect(executeNow).not.toHaveBeenCalled();
-  });
-
-  it('does NOT flush a doc that is still loading (load error guard)', async () => {
-    const ext = makeExt();
-    const { executeNow, payload } = makeData({
-      clientsCount: 0,
-      isDebounced: true,
-      isLoading: true,
-    });
-    await ext.onDisconnect(payload);
-    expect(executeNow).not.toHaveBeenCalled();
-  });
-});

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

@@ -1,223 +1,483 @@
-// Stub collaboration.util so importing the extension does not drag in the
-// editor-ext -> @tiptap/react -> react-dom graph (unloadable under jest's node
-// env, same coupling the gitmost-datasource / mcp specs document). The
-// extension only calls getPageId, jsonToText and isEmptyParagraphDoc from it on
-// the store path; tiptapExtensions is unused by onStoreDocument.
-jest.mock('../collaboration.util', () => ({
-  tiptapExtensions: [],
-  getPageId: (name: string) => name.replace(/^page\./, ''),
-  jsonToText: () => 'text',
-  isEmptyParagraphDoc: () => false,
-  // The post-write mention extraction walks the doc via jsonToNode().descendants;
-  // return a node-like stub with no descendants so no mentions are produced
-  // (mention handling is out of scope here — we only assert provenance).
-  jsonToNode: () => ({ descendants: () => undefined }),
-}));
-
-// Control the Yjs<->JSON bridge: fromYdoc returns the "incoming" doc the writer
-// is storing. We keep it distinct from the page's persisted content so the
-// no-op guard (isDeepStrictEqual) never short-circuits the write.
-const INCOMING_JSON = { type: 'doc', content: [{ type: 'paragraph' }, { t: 1 }] };
-jest.mock('@hocuspocus/transformer', () => ({
-  TiptapTransformer: {
-    fromYdoc: jest.fn(() => INCOMING_JSON),
-    toYdoc: jest.fn(),
-  },
-}));
-
-// Run the executeTx callback inline with a passthrough trx.
-jest.mock('@docmost/db/utils', () => ({
-  executeTx: jest.fn(async (_db: any, cb: any) => cb({} as any)),
-}));
-
 import * as Y from 'yjs';
+import { TiptapTransformer } from '@hocuspocus/transformer';
 import { PersistenceExtension } from './persistence.extension';
-import {
-  onChangePayload,
-  onStoreDocumentPayload,
-} from '@hocuspocus/server';
+import { buildTitleSeedYdoc, tiptapExtensions } from '../collaboration.util';
 
-/**
- * Provenance-precedence coverage for PersistenceExtension.onStoreDocument
- * (test-strategy Module 4 / item #2): the contract `agent > git-sync > user`,
- * plus the negative that a git-sync store does NOT pin a boundary history
- * snapshot. We drive the precedence through the real public method (onChange to
- * arm the sticky agent marker, then onStoreDocument), mocking the repos / db /
- * Yjs bridge so no real database or collab server is needed. The store's
- * persisted `lastUpdatedSource` and the saveHistory call are the observable
- * outputs.
- */
-describe('PersistenceExtension.onStoreDocument — provenance precedence (#2)', () => {
-  const DOCUMENT_NAME = 'page.page-1';
-  const PAGE_ID = 'page-1';
+// Direct instantiation with stub deps, mirroring the auth/env unit specs.
+const bodyJson = {
+  type: 'doc',
+  content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hello' }] }],
+};
 
-  // `page.content` differs from INCOMING_JSON so the write is never skipped.
-  const persistedPage = (overrides?: { lastUpdatedSource?: string }) => ({
-    id: PAGE_ID,
-    slugId: 'slug-1',
-    spaceId: 'space-1',
-    workspaceId: 'ws-1',
-    creatorId: 'creator-1',
-    contributorIds: ['creator-1'],
-    content: { type: 'doc', content: [{ type: 'paragraph', content: [] }] },
-    lastUpdatedSource: overrides?.lastUpdatedSource ?? 'user',
-    createdAt: new Date(),
-  });
+// Build a body Y.Doc with a known JSON, plus a monkey-patched broadcastStateless
+// (the real Hocuspocus Document supplies it; a bare Y.Doc does not).
+const buildDoc = () => {
+  const d: any = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+  d.broadcastStateless = jest.fn();
+  return d;
+};
 
-  const build = (pageOverrides?: { lastUpdatedSource?: string }) => {
-    const pageRepo = {
-      findById: jest.fn().mockResolvedValue(persistedPage(pageOverrides)),
-      updatePage: jest.fn().mockResolvedValue({ numUpdatedRows: 1n }),
+const cloneOut = (doc: any) =>
+  JSON.parse(JSON.stringify(TiptapTransformer.fromYdoc(doc, 'default')));
+
+const addTitleFragment = (doc: any, title: string) =>
+  Y.applyUpdate(doc, Y.encodeStateAsUpdate(buildTitleSeedYdoc(title)));
+
+describe('PersistenceExtension', () => {
+  let pageRepo: any;
+  let pageHistoryRepo: any;
+  let trx: any;
+  let db: any;
+  let aiQueue: any;
+  let historyQueue: any;
+  let notificationQueue: any;
+  let collabHistory: any;
+  let transclusionService: any;
+  let ext: PersistenceExtension;
+
+  beforeEach(() => {
+    pageRepo = {
+      findById: jest.fn(),
+      updatePage: jest.fn().mockResolvedValue(undefined),
     };
-    const pageHistoryRepo = {
-      // No prior snapshot -> humanBaselineMissing is true, so the ONLY thing
-      // gating the boundary snapshot in these tests is the source precedence.
-      findPageLastHistory: jest.fn().mockResolvedValue(null),
-      saveHistory: jest.fn().mockResolvedValue(undefined),
+    pageHistoryRepo = {
+      findPageLastHistory: jest.fn(),
+      saveHistory: jest.fn(),
     };
-    const aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    const historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    const notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    const collabHistory = {
-      addContributors: jest.fn().mockResolvedValue(undefined),
-    };
-    const transclusionService = {
+    trx = {};
+    db = { transaction: () => ({ execute: (fn: any) => fn(trx) }) };
+    aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    transclusionService = {
       syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
       syncPageReferences: jest.fn().mockResolvedValue(undefined),
       syncPageTemplateReferences: jest.fn().mockResolvedValue(undefined),
     };
 
-    const ext = new PersistenceExtension(
+    ext = new PersistenceExtension(
       pageRepo as any,
       pageHistoryRepo as any,
-      {} as any, // db
+      db as any,
       aiQueue as any,
       historyQueue as any,
       notificationQueue as any,
       collabHistory as any,
       transclusionService as any,
     );
-
-    return { ext, pageRepo, pageHistoryRepo, historyQueue };
-  };
-
-  // A real Y.Doc is required for Y.encodeStateAsUpdate(document); broadcastStateless
-  // is a no-op spy. The fromYdoc bridge is mocked, so the doc's contents are
-  // irrelevant to the JSON path.
-  const makeStorePayload = (context: any): onStoreDocumentPayload =>
-    ({
-      documentName: DOCUMENT_NAME,
-      document: Object.assign(new Y.Doc(), {
-        broadcastStateless: jest.fn(),
-      }),
-      context,
-    }) as any;
-
-  const makeChangePayload = (actor: string): onChangePayload =>
-    ({
-      documentName: DOCUMENT_NAME,
-      context: { user: { id: 'user-1' }, actor },
-    }) as any;
-
-  const sourceOf = (pageRepo: { updatePage: jest.Mock }) =>
-    pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource;
-
-  it("tags 'user' for a plain write (no agent touch, no git-sync actor)", async () => {
-    const { ext, pageRepo } = build();
-
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
-    );
-
-    expect(sourceOf(pageRepo)).toBe('user');
   });
 
-  it("tags 'git-sync' when the writer's actor is 'git-sync' and no agent touched the window", async () => {
-    const { ext, pageRepo } = build();
+  describe('seedTitleFragment', () => {
+    it('returns false for empty/whitespace/null titles', () => {
+      const doc = new Y.Doc();
+      expect((ext as any).seedTitleFragment(doc, '')).toBe(false);
+      expect((ext as any).seedTitleFragment(doc, '   ')).toBe(false);
+      expect((ext as any).seedTitleFragment(doc, null)).toBe(false);
+    });
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+    it('does NOT re-seed an existing non-empty title fragment', () => {
+      const doc = new Y.Doc();
+      addTitleFragment(doc, 'Existing');
 
-    expect(sourceOf(pageRepo)).toBe('git-sync');
+      expect((ext as any).seedTitleFragment(doc, 'Other')).toBe(false);
+
+      const text = TiptapTransformer.fromYdoc(doc, 'title');
+      expect(JSON.stringify(text)).toContain('Existing');
+      expect(JSON.stringify(text)).not.toContain('Other');
+    });
+
+    it('seeds an empty fragment from a non-empty title and returns true', () => {
+      const doc = new Y.Doc();
+      expect((ext as any).seedTitleFragment(doc, 'Hello')).toBe(true);
+
+      const json: any = TiptapTransformer.fromYdoc(doc, 'title');
+      expect(JSON.stringify(json)).toContain('Hello');
+    });
+
+    it('returns false (defensive) when reading the fragment throws', () => {
+      const fakeDoc = {
+        get: () => {
+          throw new Error('boom');
+        },
+      };
+      expect((ext as any).seedTitleFragment(fakeDoc as any, 'X')).toBe(false);
+    });
   });
 
-  it("keeps 'git-sync' for an explicit git-sync store even with a sticky agent marker (#14 loop-guard)", async () => {
-    const { ext, pageRepo } = build();
+  describe('onStoreDocument', () => {
+    const basePage = (overrides: any) => ({
+      id: 'PAGE_ID',
+      slugId: 'slug',
+      spaceId: 'space',
+      parentPageId: null,
+      creatorId: 'creator',
+      contributorIds: ['creator'],
+      workspaceId: 'ws',
+      title: 'whatever',
+      content: null,
+      lastUpdatedSource: 'user',
+      createdAt: new Date().toISOString(),
+      ...overrides,
+    });
 
-    // An agent edit landed earlier in the coalescing window (sticky marker),
-    // then a git-sync writer performs the store. Red-team finding #14: an
-    // EXPLICIT current-write actor is authoritative for THIS write, so the
-    // store must stay 'git-sync' — otherwise the PageChangeListener loop-guard
-    // (keyed on lastUpdatedSource === 'git-sync') fails to recognize git-sync's
-    // own write and re-exports it. Explicit 'agent' still wins (see below); the
-    // sticky marker only promotes a plain human writer to 'agent'.
-    await ext.onChange(makeChangePayload('agent'));
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+    const context = { user: { id: 'u1', name: 'U', avatarUrl: null } };
 
-    expect(sourceOf(pageRepo)).toBe('git-sync');
+    it('no-op when neither body nor title changed', async () => {
+      const document = buildDoc();
+      const page = basePage({
+        content: cloneOut(document),
+        title: 'hello title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      expect(document.broadcastStateless).not.toHaveBeenCalled();
+      expect(collabHistory.addContributors).not.toHaveBeenCalled();
+      expect(transclusionService.syncPageTransclusions).not.toHaveBeenCalled();
+      expect(aiQueue.add).not.toHaveBeenCalled();
+      expect(historyQueue.add).not.toHaveBeenCalled();
+    });
+
+    it('title-only change persists the title without body side-effects', async () => {
+      const document = buildDoc();
+      addTitleFragment(document, 'New Title');
+      const page = basePage({
+        content: cloneOut(document),
+        title: 'Old Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(call[0].title).toBe('New Title');
+      expect(call[0].ydoc).toBeDefined();
+      expect(call[0].contributorIds).toBeDefined();
+      expect('content' in call[0]).toBe(false);
+      // Title-only must not touch the body-authorship provenance.
+      expect('lastUpdatedSource' in call[0]).toBe(false);
+      expect(call[1]).toBe('PAGE_ID');
+      expect(call[3].treeUpdate.title).toBe('New Title');
+
+      expect(collabHistory.addContributors).toHaveBeenCalledTimes(1);
+      expect(collabHistory.addContributors).toHaveBeenCalledWith(
+        'PAGE_ID',
+        expect.any(Array),
+      );
+      expect(document.broadcastStateless).toHaveBeenCalledTimes(1);
+      expect(transclusionService.syncPageTransclusions).not.toHaveBeenCalled();
+      expect(aiQueue.add).not.toHaveBeenCalled();
+      expect(historyQueue.add).not.toHaveBeenCalled();
+    });
+
+    it('an EMPTY title fragment does NOT overwrite a non-empty page.title (anti-corruption guard, Bug 2)', async () => {
+      // The client can momentarily seed the 'title' fragment as an EMPTY heading
+      // (hasTitleFragment true, extracted text '') before the real title syncs.
+      // Body is unchanged here, so the only candidate write is the title -> the
+      // guard must turn this into a full no-op (no updatePage, no broadcast).
+      const document = buildDoc();
+      addTitleFragment(document, ''); // empty heading: length > 0 but text ''
+      const page = basePage({
+        content: cloneOut(document),
+        title: 'Real Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      // No write at all: the empty title is not authoritative and the body is
+      // unchanged, so onStoreDocument must take the no-op fast path.
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      expect(document.broadcastStateless).not.toHaveBeenCalled();
+    });
+
+    it('an EMPTY title fragment alongside a body change persists the body but NOT an empty title (anti-corruption guard, Bug 2)', async () => {
+      const document = buildDoc();
+      addTitleFragment(document, ''); // empty title fragment
+      const page = basePage({
+        content: { type: 'doc', content: [] }, // different body -> bodyChanged
+        title: 'Real Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      // Body is persisted, but the title is NOT included (empty == not
+      // authoritative) and no tree update is broadcast for the title.
+      expect(call[0].content).toBeTruthy();
+      expect('title' in call[0]).toBe(false);
+      expect(call[3]).toBeUndefined();
+    });
+
+    it('body + title change persists both with full body side-effects', async () => {
+      const document = buildDoc();
+      addTitleFragment(document, 'New Title');
+      const page = basePage({
+        content: { type: 'doc', content: [] },
+        title: 'Old Title',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(call[0].content).toBeTruthy();
+      expect(call[0].title).toBe('New Title');
+      expect(call[0].ydoc).toBeDefined();
+      expect(call[0].lastUpdatedSource).toBe('user');
+      expect(call[3].treeUpdate).toBeDefined();
+
+      expect(transclusionService.syncPageTransclusions).toHaveBeenCalled();
+      expect(aiQueue.add).toHaveBeenCalled();
+      expect(historyQueue.add).toHaveBeenCalled();
+      expect(collabHistory.addContributors).toHaveBeenCalled();
+      expect(document.broadcastStateless).toHaveBeenCalled();
+    });
+
+    it('body-only change persists the body without a tree update', async () => {
+      const document = buildDoc();
+      const page = basePage({
+        content: { type: 'doc', content: [] },
+        title: 'whatever',
+      });
+      pageRepo.findById.mockResolvedValue(page);
+
+      await ext.onStoreDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+        context,
+      } as any);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(call[0].content).toBeTruthy();
+      expect('title' in call[0]).toBe(false);
+      // No treeUpdate for a body-only save.
+      expect(call[3]).toBeUndefined();
+
+      expect(transclusionService.syncPageTransclusions).toHaveBeenCalled();
+      expect(aiQueue.add).toHaveBeenCalled();
+      expect(historyQueue.add).toHaveBeenCalled();
+      expect(document.broadcastStateless).toHaveBeenCalled();
+    });
   });
 
-  it("tags 'agent' when the storing writer itself is the agent (no prior onChange)", async () => {
-    const { ext, pageRepo } = build();
+  describe('onLoadDocument', () => {
+    it('returns early (no DB read) when the document is not empty', async () => {
+      const document = { isEmpty: () => false };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
-    );
+      expect(result).toBeUndefined();
+      expect(pageRepo.findById).not.toHaveBeenCalled();
+    });
 
-    expect(sourceOf(pageRepo)).toBe('agent');
-  });
+    it('returns undefined and does not persist when the page is null', async () => {
+      const document = { isEmpty: () => true };
+      pageRepo.findById.mockResolvedValue(null);
 
-  // --- boundary snapshot for a git-sync store over a HUMAN baseline -----------
-  // SPEC §9 observable-loss guard (bug #2): a git-sync body write is a block-level
-  // 3-way merge whose same-block rule is "git wins". To keep a concurrent human
-  // edit RECOVERABLE rather than silently overwritten, a git-sync store over a
-  // prior NON-git-sync baseline pins that prior state to page history first —
-  // exactly like the agent path. So saveHistory MUST be called here.
-  it('DOES pin a boundary snapshot for a git-sync store over a prior human state', async () => {
-    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+      expect(result).toBeUndefined();
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+    });
 
-    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
-  });
+    it('seeds + persists under a lock when the persisted ydoc lacks a title fragment', async () => {
+      const src = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+      const page = {
+        id: 'PAGE_ID',
+        title: 'Legacy Title',
+        ydoc: Buffer.from(Y.encodeStateAsUpdate(src)),
+        content: null,
+      };
+      // Both the cheap pre-check and the locked re-read return the same row.
+      pageRepo.findById.mockResolvedValue(page);
 
-  // --- negative: a git-sync store over a git-sync baseline does NOT re-pin -----
-  // The boundary is pinned once on the transition INTO git-sync; a subsequent
-  // git-sync store over an already-git-sync baseline must not churn history.
-  it('does NOT re-pin a boundary snapshot for a git-sync store over a git-sync baseline', async () => {
-    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'git-sync' });
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'svc-user' }, actor: 'git-sync' }),
-    );
+      // The locked re-read must take the row lock inside the tx.
+      const lockedReadCall = pageRepo.findById.mock.calls.find(
+        (c: any[]) => c[1]?.withLock,
+      );
+      expect(lockedReadCall).toBeDefined();
+      expect(lockedReadCall[1].trx).toBe(trx);
 
-    expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
-  });
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(Buffer.isBuffer(call[0].ydoc)).toBe(true);
+      expect(call[1]).toBe('PAGE_ID');
+      // Persist must run inside the transaction.
+      expect(call[2]).toBe(trx);
+      expect(result).toBeTruthy();
+    });
 
-  it('DOES pin a boundary snapshot for an agent store over a prior human state (control)', async () => {
-    // Confirms the negative above is meaningful: under the SAME mocks, an agent
-    // store over a 'user' baseline DOES trigger the boundary snapshot.
-    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+    it('does NOT lock or persist when the ydoc already has a title fragment', async () => {
+      const src = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+      Y.applyUpdate(src, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Has Title')));
+      const page = {
+        id: 'PAGE_ID',
+        title: 'Has Title',
+        ydoc: Buffer.from(Y.encodeStateAsUpdate(src)),
+        content: null,
+      };
+      pageRepo.findById.mockResolvedValue(page);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'agent-user' }, actor: 'agent' }),
-    );
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
-  });
+      // Hot path: only the cheap lock-free read, no locked re-read, no write.
+      expect(pageRepo.findById).toHaveBeenCalledTimes(1);
+      expect(pageRepo.findById.mock.calls[0][1]?.withLock).toBeFalsy();
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      expect(result).toBeTruthy();
+    });
 
-  it('does NOT pin a boundary snapshot for a plain user store', async () => {
-    const { ext, pageHistoryRepo } = build({ lastUpdatedSource: 'user' });
+    it('converts legacy content -> ydoc inside a tx and persists a {ydoc} Buffer', async () => {
+      const page = {
+        id: 'PAGE_ID',
+        title: 'T',
+        ydoc: null,
+        content: bodyJson,
+      };
+      pageRepo.findById.mockResolvedValue(page);
 
-    await ext.onStoreDocument(
-      makeStorePayload({ user: { id: 'user-1' }, actor: 'user' }),
-    );
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
 
-    expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const lockedReadCall = pageRepo.findById.mock.calls.find(
+        (c: any[]) => c[1]?.withLock,
+      );
+      expect(lockedReadCall).toBeDefined();
+      expect(lockedReadCall[1].trx).toBe(trx);
+
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+      const call = pageRepo.updatePage.mock.calls[0];
+      expect(Buffer.isBuffer(call[0].ydoc)).toBe(true);
+      expect(call[2]).toBe(trx);
+      // The rebuilt doc carries the body.
+      expect(JSON.stringify(cloneOut(result))).toContain('hello');
+    });
+
+    it('SKIPS rebuild when the locked re-read shows the ydoc was already healed', async () => {
+      // Simulate a concurrent process: the cheap pre-check sees ydoc=null (legacy
+      // rebuild path), but by the time we hold the lock another process has
+      // already persisted a healthy ydoc. We must adopt it, not rebuild/clobber.
+      const healed = TiptapTransformer.toYdoc(
+        { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'healed' }] }] },
+        'default',
+        tiptapExtensions,
+      );
+      Y.applyUpdate(healed, Y.encodeStateAsUpdate(buildTitleSeedYdoc('Healed Title')));
+      const healedYdoc = Buffer.from(Y.encodeStateAsUpdate(healed));
+
+      const preCheck = { id: 'PAGE_ID', title: 'T', ydoc: null, content: bodyJson };
+      const lockedRow = {
+        id: 'PAGE_ID',
+        title: 'Healed Title',
+        ydoc: healedYdoc,
+        content: bodyJson,
+      };
+      pageRepo.findById
+        .mockResolvedValueOnce(preCheck) // cheap pre-check
+        .mockResolvedValueOnce(lockedRow); // locked re-read
+
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
+
+      // The healthy ydoc had a title fragment already, so nothing was rebuilt or
+      // seeded -> no clobbering write.
+      expect(pageRepo.updatePage).not.toHaveBeenCalled();
+      // The returned doc is the healed body, NOT a fresh rebuild of bodyJson.
+      expect(JSON.stringify(cloneOut(result))).toContain('healed');
+    });
+
+    it('REJECTS the load when the rebuild persist fails (does not return an unpersisted doc)', async () => {
+      const page = { id: 'PAGE_ID', title: 'T', ydoc: null, content: bodyJson };
+      pageRepo.findById.mockResolvedValue(page);
+      pageRepo.updatePage.mockRejectedValue(new Error('db down'));
+      const errSpy = jest
+        .spyOn((ext as any).logger, 'error')
+        .mockImplementation(() => undefined);
+
+      const document = { isEmpty: () => true };
+      await expect(
+        ext.onLoadDocument({
+          documentName: 'page.PAGE_ID',
+          document,
+        } as any),
+      ).rejects.toThrow('db down');
+      expect(errSpy).toHaveBeenCalled();
+    });
+
+    it('seed-only persist FAILURE returns the doc from the existing ydoc (no throw)', async () => {
+      const src = TiptapTransformer.toYdoc(bodyJson, 'default', tiptapExtensions);
+      const page = {
+        id: 'PAGE_ID',
+        title: 'Legacy Title',
+        ydoc: Buffer.from(Y.encodeStateAsUpdate(src)),
+        content: null,
+      };
+      pageRepo.findById.mockResolvedValue(page);
+      pageRepo.updatePage.mockRejectedValue(new Error('db down'));
+      const errSpy = jest
+        .spyOn((ext as any).logger, 'error')
+        .mockImplementation(() => undefined);
+
+      const document = { isEmpty: () => true };
+      const result = await ext.onLoadDocument({
+        documentName: 'page.PAGE_ID',
+        document,
+      } as any);
+
+      // Non-fatal: we fall back to the doc loaded from the existing page.ydoc.
+      expect(result).toBeTruthy();
+      expect(JSON.stringify(cloneOut(result))).toContain('hello');
+      expect(errSpy).toHaveBeenCalled();
+    });
   });
 });

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

@@ -2,7 +2,6 @@ import {
   afterUnloadDocumentPayload,
   Extension,
   onChangePayload,
-  onDisconnectPayload,
   onLoadDocumentPayload,
   onStoreDocumentPayload,
 } from '@hocuspocus/server';
@@ -10,6 +9,7 @@ import * as Y from 'yjs';
 import { Injectable, Logger } from '@nestjs/common';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
+  buildTitleSeedYdoc,
   getPageId,
   isEmptyParagraphDoc,
   jsonToText,
@@ -53,17 +53,7 @@ export function resolveSource(
   stickyTouched: boolean,
   contextActor?: string,
 ): ProvenanceSource {
-  // An EXPLICIT current-write actor is authoritative for THIS write and wins
-  // over the sticky-agent fallback. Order: explicit 'agent' > explicit
-  // 'git-sync' > sticky agent marker > plain human 'user'. The git-sync case
-  // must NOT be masked by the sticky marker, or the PageChangeListener
-  // loop-guard (which keys on lastUpdatedSource === 'git-sync') would re-export
-  // git-sync's own writes (#14). Explicit agent still wins so a window that
-  // mixed an agent edit stays tagged 'agent'.
-  if (contextActor === 'agent') return 'agent';
-  if (contextActor === 'git-sync') return 'git-sync';
-  if (stickyTouched) return 'agent';
-  return 'user';
+  return stickyTouched || contextActor === 'agent' ? 'agent' : 'user';
 }
 
 /**
@@ -127,6 +117,10 @@ export class PersistenceExtension implements Extension {
       return;
     }
 
+    // Cheap, lock-free pre-check (hot path stays lock-free). It tells us whether
+    // any heal (legacy rebuild and/or title seed) is needed; the heal itself
+    // re-reads the row FOR UPDATE and re-validates inside a transaction so it
+    // runs exactly once (see healUnderLock).
     const page = await this.pageRepo.findById(pageId, {
       includeContent: true,
       includeYdoc: true,
@@ -138,27 +132,70 @@ export class PersistenceExtension implements Extension {
     }
 
     if (page.ydoc) {
-      this.logger.debug(`ydoc loaded from db: ${pageId}`);
-
       const doc = new Y.Doc();
-      const dbState = new Uint8Array(page.ydoc);
+      Y.applyUpdate(doc, new Uint8Array(page.ydoc));
 
-      Y.applyUpdate(doc, dbState);
-      return doc;
+      // Legacy pages persisted their title only in the `page.title` column; the
+      // ydoc has no 'title' fragment. Decide cheaply (no lock) whether a seed is
+      // needed by inspecting the loaded doc's 'title' fragment. A seed is needed
+      // only when that fragment is empty AND there is a non-empty column title.
+      let titleSeedNeeded = false;
+      try {
+        const titleFrag = doc.get('title', Y.XmlFragment);
+        titleSeedNeeded = titleFrag.length === 0 && !!page.title?.trim();
+      } catch (err) {
+        // A malformed title fragment must not break loading; skip the seed.
+        this.logger.warn(`failed to inspect title fragment: ${err?.['message']}`);
+        titleSeedNeeded = false;
+      }
+
+      if (!titleSeedNeeded) {
+        // Fully healthy: a ydoc with a title fragment (or nothing to seed).
+        this.logger.debug(`ydoc loaded from db: ${pageId}`);
+        return doc;
+      }
+
+      // SEED-ONLY heal: a valid page.ydoc already exists; we only need to add the
+      // title fragment. If the persist fails we must NOT hand out an unpersisted
+      // fresh-client-id seed (it could later duplicate the title), so we fall
+      // back to the healthy doc loaded from the EXISTING page.ydoc, without the
+      // seed. The title just won't render until a later successful heal —
+      // non-fatal, non-corrupting.
+      try {
+        return await this.healUnderLock(pageId);
+      } catch (err) {
+        this.logger.error(
+          `Failed to persist seeded ydoc for page ${pageId}; serving existing ydoc without title seed`,
+          err,
+        );
+        return doc;
+      }
     }
 
-    // if no ydoc state in db convert json in page.content to Ydoc.
+    // NOTE (offline-sync M1, Goal 2): this per-load self-heal converts +
+    // title-seeds + persists every legacy page (content set, ydoc null) on its
+    // first open, which neutralizes the duplication trap incrementally. A
+    // proactive one-shot BATCH migration over all such pages could be added
+    // later, but it requires the tiptap schema + TiptapTransformer (Node/Yjs),
+    // which a Kysely SQL migration cannot run; no runnable-task/CLI convention
+    // exists in this repo yet, so we deliberately avoid a fragile migration.
+    //
+    // If no ydoc state in db, REBUILD a Y.Doc from the JSON in page.content under
+    // a row lock (see healUnderLock).
     if (page.content) {
-      this.logger.debug(`converting json to ydoc: ${pageId}`);
-
-      const ydoc = TiptapTransformer.toYdoc(
-        page.content,
-        'default',
-        tiptapExtensions,
-      );
-
-      Y.encodeStateAsUpdate(ydoc);
-      return ydoc;
+      // REBUILD heal: surface failures. If the persist fails we REFUSE the load
+      // (re-throw) rather than hand out an unpersisted fresh-client-id rebuild —
+      // returning it would re-arm the duplication trap. A transient DB failure
+      // means the client reconnects and retries: correctness over availability.
+      try {
+        return await this.healUnderLock(pageId);
+      } catch (err) {
+        this.logger.error(
+          `Failed to persist rebuilt ydoc for page ${pageId}; refusing load`,
+          err,
+        );
+        throw err;
+      }
     }
 
     this.logger.debug(`creating fresh ydoc: ${pageId}`);
@@ -166,36 +203,90 @@ export class PersistenceExtension implements Extension {
   }
 
   /**
-   * LOSS-ON-FAST-CLOSE FIX (QA #119). When the LAST editor disconnects, FLUSH any
-   * pending (debounced) store to the DB IMMEDIATELY instead of waiting out the
-   * up-to-10s `debounce` window.
-   *
-   * The collab server runs with `unloadImmediately: false` (collaboration.gateway),
-   * so on a last-client disconnect Hocuspocus does NOT flush the debounced
-   * onStoreDocument — it relies on the timer firing later. A quick edit-then-close
-   * (closing the tab within the debounce window, ~3-18s) therefore left the edit
-   * only in the soon-to-be-unloaded in-memory Y.Doc; meanwhile git-sync mirrored
-   * the STALE/empty DB body to the vault (the reported "59-byte frontmatter-only"
-   * data loss). Running the already-scheduled store now closes that window.
-   *
-   * Gated tightly so it never adds a redundant write: only on the LAST disconnect
-   * (`clientsCount === 0`), only for a fully-loaded doc, and only when a store is
-   * actually pending (`isDebounced`). `executeNow` runs the SAME payload Hocuspocus
-   * scheduled (preserving the edit's context/actor) and clears the timer.
+   * Serialize the legacy self-heal (rebuild from page.content and/or seed the
+   * title fragment, then persist) so it runs exactly ONCE per page, closing the
+   * Yjs duplication trap. Both TiptapTransformer.toYdoc and buildTitleSeedYdoc
+   * mint FRESH Yjs client-ids every call, so two concurrent rebuilds (the API
+   * process via openDirectConnection AND the standalone collab process both
+   * seeing `ydoc IS NULL`) could each persist a different-client-id state and let
+   * a long-offline client merge-and-duplicate. We prevent that by re-reading the
+   * row FOR UPDATE inside a transaction and re-validating state under the lock:
+   * whoever wins the lock heals; the loser observes the healthy `ydoc` and adopts
+   * it instead of rebuilding. The persist happens IN THE SAME TX, so a failed
+   * write rolls back and propagates out (the caller then decides refuse vs.
+   * fall-back).
    */
-  async onDisconnect(data: onDisconnectPayload) {
-    const { instance, document, documentName, clientsCount } = data;
-    if (clientsCount > 0) return;
-    if (!document || document.isLoading) return;
-    const debounceId = `onStoreDocument-${documentName}`;
-    if (!instance?.debouncer?.isDebounced(debounceId)) return;
+  private async healUnderLock(pageId: string): Promise<Y.Doc> {
+    return executeTx(this.db, async (trx) => {
+      const locked = await this.pageRepo.findById(pageId, {
+        withLock: true,
+        includeContent: true,
+        includeYdoc: true,
+        trx,
+      });
+
+      const doc = new Y.Doc();
+      let rebuilt = false;
+
+      if (locked?.ydoc) {
+        // Another process already healed (or the page always had a ydoc): adopt
+        // the healthy persisted state, do NOT rebuild.
+        Y.applyUpdate(doc, new Uint8Array(locked.ydoc));
+      } else if (locked?.content) {
+        this.logger.debug(`converting json to ydoc: ${pageId}`);
+        const built = TiptapTransformer.toYdoc(
+          locked.content,
+          'default',
+          tiptapExtensions,
+        );
+        Y.applyUpdate(doc, Y.encodeStateAsUpdate(built));
+        rebuilt = true;
+      }
+      // else: no ydoc and no content -> a fresh empty doc.
+
+      // Idempotent, emptiness-guarded title seed (safe to call always).
+      const seeded = this.seedTitleFragment(doc, locked?.title ?? null);
+
+      if (rebuilt || seeded) {
+        // Persist IN THE SAME TX. If this throws, the tx rolls back and the
+        // error propagates out of executeTx to the caller.
+        await this.pageRepo.updatePage(
+          { ydoc: Buffer.from(Y.encodeStateAsUpdate(doc)) },
+          pageId,
+          trx,
+        );
+        this.logger.debug(`persisted rebuilt/seeded ydoc: ${pageId}`);
+      }
+
+      return doc;
+    });
+  }
+
+  /**
+   * Seed the 'title' fragment of `doc` from the `page.title` column for legacy
+   * pages whose persisted ydoc has no title fragment yet.
+   *
+   * Guarded STRICTLY by emptiness: we only seed when the existing 'title'
+   * fragment is empty AND there is a non-empty column title. Seeding a non-empty
+   * fragment would re-introduce the Yjs duplication trap, so we never do it.
+   * Returns true when a seed was applied (so the caller can persist).
+   * Defensive: a malformed title must not break document loading.
+   */
+  private seedTitleFragment(doc: Y.Doc, title: string | null): boolean {
+    const trimmed = (title ?? '').trim();
+    if (!trimmed) return false;
+
     try {
-      await instance.debouncer.executeNow(debounceId);
+      const titleFrag = doc.get('title', Y.XmlFragment);
+      if (titleFrag.length !== 0) return false;
+
+      const titleSeed = buildTitleSeedYdoc(title);
+      Y.applyUpdate(doc, Y.encodeStateAsUpdate(titleSeed));
+      this.logger.debug('seeded title fragment from page.title column');
+      return true;
     } catch (err) {
-      this.logger.error(
-        `onDisconnect flush failed for ${documentName}: ` +
-          (err instanceof Error ? err.message : String(err)),
-      );
+      this.logger.warn(`failed to seed title fragment: ${err?.['message']}`);
+      return false;
     }
   }
 
@@ -216,16 +307,38 @@ export class PersistenceExtension implements Extension {
       this.logger.warn('jsonToText' + err?.['message']);
     }
 
+    // Title lives in the SAME Y.Doc as the body, in a dedicated 'title' fragment
+    // (the collaborative title-editor contract with the client). Extract it
+    // defensively: a malformed title fragment must NOT crash the document store.
+    // `hasTitleFragment` distinguishes "the doc actually carries a title
+    // fragment" from "legacy doc with no title fragment" — only the former may
+    // write page.title, so a legacy doc never clobbers the column with ''.
+    let titleText = '';
+    let hasTitleFragment = false;
+    try {
+      const titleFrag = document.get('title', Y.XmlFragment);
+      hasTitleFragment = !!titleFrag && titleFrag.length > 0;
+      if (hasTitleFragment) {
+        const titleJson = TiptapTransformer.fromYdoc(document, 'title');
+        titleText = titleJson ? jsonToText(titleJson).trim() : '';
+      }
+    } catch (err) {
+      this.logger.warn('title extraction: ' + err?.['message']);
+      hasTitleFragment = false;
+    }
+
     let page: Page = null;
+    // Tracks whether the BODY ('default') changed in this store. The heavy
+    // body-only side-effects (transclusion sync, mentions, RAG, history) stay
+    // gated on this so a title-only change does not trigger them.
+    let bodyChanged = false;
+    // Tracks a successful title-only persist so the post-tx contributor folding
+    // (collabHistory.addContributors) runs for the title-only case too.
+    let titleOnlyPersisted = false;
     const editingUserIds = this.consumeContributors(documentName);
     // Sticky agent marker: 'agent' if any agent edit landed in this window, OR
     // if the current writer is the agent (covers a store with no prior onChange
     // agent event in the same window). §15 H2.
-    // Provenance precedence: agent > git-sync > user (see resolveSource). A
-    // 'git-sync' store is NOT given an immediate history snapshot — it is
-    // debounced like a human edit (a git-sync write is a block-level merge into
-    // the live doc, so it reads like an incremental human edit, not a bulk
-    // import that would warrant its own immediate snapshot).
     const lastUpdatedSource = resolveSource(
       this.consumeAgentTouched(documentName),
       context?.actor,
@@ -255,11 +368,80 @@ export class PersistenceExtension implements Extension {
             return;
           }
 
-          if (isDeepStrictEqual(tiptapJson, page.content)) {
+          bodyChanged = !isDeepStrictEqual(tiptapJson, page.content);
+          // Only a populated 'title' fragment may update page.title; compare
+          // against the current column value (treat null as '').
+          //
+          // ANTI-CORRUPTION GUARD (Bug 2): the client's collaborative title-editor
+          // can momentarily initialize the 'title' fragment as an EMPTY heading
+          // (so `hasTitleFragment` is true, but the extracted `titleText` is '')
+          // BEFORE the server's real-title seed has synced. Writing that '' would
+          // silently wipe a non-empty page.title to "untitled". A wiki page is
+          // never legitimately retitled to empty via this path, so we treat an
+          // empty extracted title as "not authoritative" and never persist it.
+          // The `titleText.length > 0` clause makes this guard apply to BOTH the
+          // title-only branch and the body+title branch below.
+          //
+          // DELIBERATE: this intentionally makes it impossible to retitle a page
+          // to EMPTY via the collab path — a wiki page is never legitimately
+          // empty-titled. If a non-empty-title rule ever needs relaxing or
+          // enforcing differently, the REST UpdatePageDto is the place to validate
+          // the title, not this collab guard.
+          const titleChanged =
+            hasTitleFragment &&
+            titleText.length > 0 &&
+            titleText !== (page.title ?? '');
+
+          // No-op fast path: neither body nor title changed.
+          if (!bodyChanged && !titleChanged) {
             page = null;
             return;
           }
 
+          // Title-only change: the body is unchanged, so skip the heavy body
+          // history/contributor logic and persist just the new title and the
+          // ydoc (the title fragment edit lives in the same ydoc). The early-skip
+          // used to drop this case entirely, losing the title change.
+          if (!bodyChanged) {
+            // Fold the window's editing users into contributors the same way the
+            // body branch does, so a user who edited ONLY the title is not dropped
+            // from page.contributorIds.
+            const contributorIds = Array.from(
+              new Set([
+                ...(page.contributorIds || []),
+                ...editingUserIds,
+                page.creatorId,
+              ]),
+            );
+            await this.pageRepo.updatePage(
+              {
+                title: titleText,
+                ydoc: ydocState,
+                lastUpdatedById: context.user.id,
+                contributorIds,
+                // A title-only change is not a body-authorship transition; leave
+                // lastUpdatedSource/aiChatId untouched so the user->agent history
+                // boundary in the body branch is not bypassed.
+              },
+              pageId,
+              trx,
+              // Mirror PageService.update's tree snapshot so a collaborative rename
+              // propagates to other users' sidebar/breadcrumbs like the REST rename.
+              {
+                treeUpdate: {
+                  id: pageId,
+                  slugId: page.slugId,
+                  spaceId: page.spaceId,
+                  parentPageId: page.parentPageId ?? null,
+                  title: titleText,
+                },
+              },
+            );
+            this.logger.debug(`Page title updated: ${pageId} - SlugId: ${page.slugId}`);
+            titleOnlyPersisted = true;
+            return;
+          }
+
           let contributorIds = undefined;
           try {
             const existingContributors = page.contributorIds || [];
@@ -274,41 +456,25 @@ export class PersistenceExtension implements Extension {
             //this.logger.debug('Contributors error:' + err?.['message']);
           }
 
-          // Approach A — boundary snapshot before a MACHINE write overwrites a
-          // human (or other-source) baseline. When this store is from a machine
-          // source — the AGENT or GIT-SYNC — and the page's currently persisted
-          // state was authored by a DIFFERENT source, pin that prior state as its
-          // own history version BEFORE the machine write overwrites it. `page`
-          // still holds the OLD content/provenance here, so saveHistory(page)
-          // captures the pre-write state. The machine's new content is snapshotted
-          // later by the debounced PAGE_HISTORY job.
-          //
-          // For GIT-SYNC this is the OBSERVABLE-LOSS guard (SPEC §9 conflict
-          // contract): a git-sync body write is a block-level 3-way merge whose
-          // same-block rule is "git wins". Without this pin, a concurrent human
-          // edit to a block git also changed would be overwritten with NO trace.
-          // Pinning the pre-merge state here means the human's content is always
-          // RECOVERABLE via page history rather than silently lost — git still
-          // wins the live doc deterministically, but nothing is destroyed.
-          //
-          // Skip if the prior state was already authored by THIS machine source
-          // (boundary already pinned on the transition into it), if the page is
-          // effectively empty, or if the latest existing snapshot already equals
-          // the prior state (avoid duplicates).
-          const isMachineWrite =
-            lastUpdatedSource === 'agent' || lastUpdatedSource === 'git-sync';
-          if (isMachineWrite && page.lastUpdatedSource !== lastUpdatedSource) {
+          // 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).
+          if (lastUpdatedSource === 'agent' && page.lastUpdatedSource !== 'agent') {
             const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
               pageId,
               { includeContent: true, trx },
             );
             const humanBaselineMissing =
-              !lastHistory ||
-              !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+              !lastHistory || !isDeepStrictEqual(lastHistory.content, page.content);
+            if (!isEmptyParagraphDoc(page.content as any) && humanBaselineMissing) {
               await this.pageHistoryRepo.saveHistory(page, {
                 contributorIds: page.contributorIds ?? undefined,
                 trx,
@@ -326,9 +492,27 @@ export class PersistenceExtension implements Extension {
               lastUpdatedSource,
               lastUpdatedAiChatId: context?.aiChatId ?? null,
               contributorIds: contributorIds,
+              // Persist the title in the SAME transaction when the title fragment
+              // changed alongside the body.
+              ...(titleChanged ? { title: titleText } : {}),
             },
             pageId,
             trx,
+            // Mirror PageService.update's tree snapshot so a collaborative rename
+            // propagates to other users' sidebar/breadcrumbs like the REST rename.
+            // Only attach when the title actually changed; a body-only save must
+            // not trigger a tree broadcast.
+            titleChanged
+              ? {
+                  treeUpdate: {
+                    id: pageId,
+                    slugId: page.slugId,
+                    spaceId: page.spaceId,
+                    parentPageId: page.parentPageId ?? null,
+                    title: titleText,
+                  },
+                }
+              : undefined,
           );
 
           this.logger.debug(`Page updated: ${pageId} - SlugId: ${page.slugId}`);
@@ -349,6 +533,8 @@ export class PersistenceExtension implements Extension {
       }
     }
 
+    // `page` is truthy whenever anything was persisted (body OR title-only), so
+    // the page.updated broadcast fires for a title-only change too.
     if (page) {
       document.broadcastStateless(
         JSON.stringify({
@@ -366,11 +552,20 @@ export class PersistenceExtension implements Extension {
             : undefined,
         }),
       );
+    }
 
+    // Record the window's editing users in collab history for a title-only
+    // change too (the body branch does this below, gated on bodyChanged).
+    if (page && titleOnlyPersisted) {
+      await this.collabHistory.addContributors(pageId, editingUserIds);
+    }
+
+    // Body-only side-effects: skip them for a title-only change (body unchanged).
+    if (page && bodyChanged) {
       await this.syncTransclusion(pageId, page.workspaceId, tiptapJson);
     }
 
-    if (page) {
+    if (page && bodyChanged) {
       await this.collabHistory.addContributors(pageId, editingUserIds);
 
       const mentions = extractMentions(tiptapJson);

apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.spec.ts

@@ -1,208 +0,0 @@
-// Regression coverage for the custom-event request/reply protocol in the
-// RedisSyncExtension. git-sync routes its body write through a custom event
-// (`gitSyncWriteBody`) which, when the target doc is owned by a DIFFERENT collab
-// instance, runs REMOTELY inside `handleRedisMessage` on the owning instance. The
-// remote handler can THROW (markdown->ProseMirror transform on a malformed body).
-//
-// Before the fix the throw was uncaught: (1) no `customEventComplete` reply was
-// published, so the origin's awaiting promise only rejected after `customEventTTL`
-// (~30s) as a generic 'TIMEOUT', and (2) an unhandledRejection escaped the async
-// `messageBuffer` listener on the owning instance. These tests assert the throw is
-// turned into an error-carrying reply that rejects the origin PROMPTLY with the
-// real message, with the no-throw and local paths unchanged.
-
-import { RedisSyncExtension } from './redis-sync.extension';
-
-type Listener = (channel: Buffer, message: Buffer) => unknown;
-
-// Minimal in-memory pub/sub + lock store shared across FakeRedis duplicates,
-// modelling the two-instance topology (origin + owner) over one Redis.
-class FakeRedisBus {
-  instances: FakeRedis[] = [];
-  locks = new Map<string, string>();
-  published: { channel: string; message: Buffer }[] = [];
-
-  register(inst: FakeRedis) {
-    this.instances.push(inst);
-  }
-
-  publish(channel: string, message: Buffer) {
-    this.published.push({ channel, message });
-    for (const inst of this.instances) {
-      if (!inst.subscribed.has(channel)) continue;
-      for (const listener of inst.messageListeners) {
-        // ioredis delivers async; `void` mirrors the production listener
-        // registration (`sub.on('messageBuffer', ...)`), whose rejection would
-        // surface as an unhandledRejection if the handler did not catch.
-        void listener(Buffer.from(channel), message);
-      }
-    }
-  }
-}
-
-class FakeRedis {
-  subscribed = new Set<string>();
-  messageListeners: Listener[] = [];
-
-  constructor(private bus: FakeRedisBus) {
-    bus.register(this);
-  }
-
-  duplicate() {
-    return new FakeRedis(this.bus);
-  }
-
-  subscribe(...channels: string[]) {
-    for (const c of channels) this.subscribed.add(c);
-    return Promise.resolve();
-  }
-
-  on(event: string, cb: any) {
-    if (event === 'messageBuffer') this.messageListeners.push(cb as Listener);
-    return this;
-  }
-
-  publish(channel: string, message: Buffer) {
-    this.bus.publish(channel, message);
-    return Promise.resolve(1);
-  }
-
-  // Models `SET key val PX ttl NX GET`: only writes when absent (NX); returns the
-  // previous value (GET) so the origin observes the owner already holding the lock.
-  set(key: string, val: string, ...args: any[]) {
-    const hasNX = args.includes('NX');
-    const hasGET = args.includes('GET');
-    const old = this.bus.locks.get(key) ?? null;
-    if (!hasNX || old === null) this.bus.locks.set(key, val);
-    return Promise.resolve(hasGET ? old : 'OK');
-  }
-
-  del(key: string) {
-    this.bus.locks.delete(key);
-    return Promise.resolve(1);
-  }
-
-  disconnect() {}
-}
-
-const pack = (m: any) => Buffer.from(JSON.stringify(m));
-const unpack = (b: Buffer) => JSON.parse(b.toString());
-
-function makeExtension(
-  bus: FakeRedisBus,
-  serverId: string,
-  customEvents: Record<string, (doc: string, payload: any) => Promise<any>>,
-) {
-  const ext = new RedisSyncExtension({
-    redis: new FakeRedis(bus) as any,
-    pack: pack as any,
-    unpack: unpack as any,
-    serverId,
-    customEvents: customEvents as any,
-    customEventTTL: 30_000,
-  });
-  // Doc is NOT loaded on this instance -> handleEvent takes the remote/proxy path.
-  (ext as any).instance = { documents: new Map() };
-  return ext;
-}
-
-describe('RedisSyncExtension custom-event error propagation', () => {
-  let unhandled: unknown[];
-  let onUnhandled: (e: unknown) => void;
-
-  beforeEach(() => {
-    // Fake timers so the 30s TTL fallback timer never fires (and never dangles).
-    jest.useFakeTimers();
-    unhandled = [];
-    onUnhandled = (e) => unhandled.push(e);
-    process.on('unhandledRejection', onUnhandled);
-  });
-
-  afterEach(() => {
-    process.off('unhandledRejection', onUnhandled);
-    jest.useRealTimers();
-  });
-
-  const flush = async () => {
-    for (let i = 0; i < 10; i++) await Promise.resolve();
-  };
-
-  it('owner publishes an error-carrying reply (no unhandledRejection) when the remote handler throws', async () => {
-    const bus = new FakeRedisBus();
-    const owner = makeExtension(bus, 'owner', {
-      boom: async () => {
-        throw new Error('kaboom');
-      },
-    });
-
-    // Drive the remote branch directly, as if the origin's customEventStart arrived.
-    await (owner as any).handleRedisMessage(
-      Buffer.from('collabMsg:owner'),
-      pack({
-        type: 'customEventStart',
-        documentName: 'page.x',
-        eventName: 'boom',
-        payload: {},
-        replyTo: 'collabMsg:origin',
-        replyId: 7,
-      }),
-    );
-    await flush();
-
-    const replies = bus.published
-      .filter((p) => p.channel === 'collabMsg:origin')
-      .map((p) => unpack(p.message));
-    expect(replies).toHaveLength(1);
-    expect(replies[0]).toMatchObject({
-      type: 'customEventComplete',
-      replyId: 7,
-      error: 'kaboom',
-    });
-    expect(unhandled).toHaveLength(0);
-  });
-
-  it('origin rejects PROMPTLY with the real error (not a TTL TIMEOUT) when the remote handler throws', async () => {
-    const bus = new FakeRedisBus();
-    // Owner already holds the document lock.
-    bus.locks.set('collabLock:page.x', 'owner');
-    makeExtension(bus, 'owner', {
-      boom: async () => {
-        throw new Error('kaboom');
-      },
-    });
-    const origin = makeExtension(bus, 'origin', {
-      boom: async () => undefined,
-    });
-
-    const promise = (origin as any).handleEvent('boom', 'page.x', { foo: 1 });
-    // Attach a catch immediately so a rejection is never momentarily unhandled.
-    const settled = promise.then(
-      () => ({ ok: true as const }),
-      (e: unknown) => ({ ok: false as const, error: e }),
-    );
-
-    await flush();
-    // Resolves WITHOUT advancing any timer -> the 30s TIMEOUT fallback did not fire.
-    const result = await settled;
-    expect(result.ok).toBe(false);
-    expect((result as any).error).toBeInstanceOf(Error);
-    expect(((result as any).error as Error).message).toBe('kaboom');
-    expect(unhandled).toHaveLength(0);
-  });
-
-  it('origin resolves with the payload when the remote handler succeeds (unchanged behavior)', async () => {
-    const bus = new FakeRedisBus();
-    bus.locks.set('collabLock:page.x', 'owner');
-    makeExtension(bus, 'owner', {
-      ok: async (_doc: string, payload: any) => ({ echoed: payload }),
-    });
-    const origin = makeExtension(bus, 'origin', {
-      ok: async () => undefined,
-    });
-
-    const promise = (origin as any).handleEvent('ok', 'page.x', { foo: 1 });
-    await flush();
-    await expect(promise).resolves.toEqual({ echoed: { foo: 1 } });
-    expect(unhandled).toHaveLength(0);
-  });
-});

apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.ts

@@ -51,15 +51,9 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
   private instance!: Hocuspocus;
   private readonly customEvents: TCE;
   private replyIdCounter: number = 0;
-  private pendingReplies: Record<
-    number,
-    {
-      // @ts-ignore
-      resolve: PromiseWithResolvers<any>['resolve'];
-      // @ts-ignore
-      reject: PromiseWithResolvers<any>['reject'];
-    }
-  > = {};
+  // @ts-ignore
+  private pendingReplies: Record<number, PromiseWithResolvers<any>['resolve']> =
+    {};
 
   constructor(configuration: Configuration<TCE>) {
     const {
@@ -182,45 +176,25 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
     }
     if (type === 'customEventStart') {
       const { documentName, eventName, payload, replyTo, replyId } = msg;
-      let reply: RSAMessageCustomEventComplete;
-      try {
-        const res = await this.handleEventLocally(
-          eventName as Extract<keyof TCE, string>,
-          documentName,
-          payload,
-        );
-        reply = {
-          type: 'customEventComplete',
-          replyId,
-          payload: res,
-        };
-      } catch (err) {
-        // The remote handler threw (e.g. the markdown->ProseMirror transform in
-        // gitSyncWriteBody can throw on a malformed body). Reply with the error on
-        // the SAME correlation channel so the origin rejects promptly with the real
-        // message instead of waiting out customEventTTL as a generic 'TIMEOUT'.
-        // Catching here also keeps the throw from escaping this async messageBuffer
-        // listener as an unhandledRejection on the owning instance.
-        reply = {
-          type: 'customEventComplete',
-          replyId,
-          payload: undefined,
-          error: err instanceof Error ? err.message : String(err),
-        };
-      }
+      const res = await this.handleEventLocally(
+        eventName as Extract<keyof TCE, string>,
+        documentName,
+        payload,
+      );
+      const reply: RSAMessageCustomEventComplete = {
+        type: 'customEventComplete',
+        replyId,
+        payload: res,
+      };
       this.pub.publish(`${replyTo}`, this.pack(reply));
       return;
     }
     if (type === 'customEventComplete') {
-      const { replyId, payload, error } = msg;
-      const pending = this.pendingReplies[replyId];
-      if (!pending) return;
+      const { replyId, payload } = msg;
+      const resolveFn = this.pendingReplies[replyId];
+      if (!resolveFn) return;
       delete this.pendingReplies[replyId];
-      if (error !== undefined) {
-        pending.reject(new Error(error));
-      } else {
-        pending.resolve(payload);
-      }
+      resolveFn(payload);
       return;
     }
     const { socketId } = msg;
@@ -299,22 +273,11 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
       };
       const msg = this.pack(proxyMessage);
       this.pub.publish(`${this.msgChannel}:${proxyTo}`, msg);
-      // Manual deferred (no Promise.withResolvers) so this runs on Node < 22 too.
-      let resolve!: (v: unknown) => void;
-      let reject!: (e: unknown) => void;
-      const promise = new Promise((res, rej) => {
-        resolve = res;
-        reject = rej;
-      });
-      this.pendingReplies[replyId] = { resolve, reject };
+      // @ts-ignore
+      const { promise, resolve, reject } = Promise.withResolvers();
+      this.pendingReplies[replyId] = resolve;
       setTimeout(() => {
-        // Fallback for a genuinely lost reply. A handler that threw now rejects
-        // promptly via the error-carrying customEventComplete above; this TIMEOUT
-        // only fires when no reply ever comes back.
-        if (this.pendingReplies[replyId]) {
-          delete this.pendingReplies[replyId];
-          reject('TIMEOUT');
-        }
+        reject('TIMEOUT');
       }, this.customEventTTL);
       return promise as Promise<ReturnType<TCE[TName]>>;
     }

apps/server/src/collaboration/extensions/redis-sync/redis-sync.types.ts

@@ -72,10 +72,6 @@ export type RSAMessageCustomEventComplete = {
   type: 'customEventComplete';
   replyId: number;
   payload: unknown;
-  // When the remote handler THREW, the owner sends back the error message here
-  // instead of a payload, so the origin can reject its awaiting promise promptly
-  // (with the real error) rather than waiting out the customEventTTL timeout.
-  error?: string;
 };
 
 export type RSAMessage =

apps/server/src/collaboration/git-sync-converter-gate.spec.ts

@@ -1,535 +0,0 @@
-/**
- * JEST CONFIG NOTE (#119 ESM refactor): this is the one spec that needs the REAL
- * `@docmost/git-sync` converter (not a mock). The package is now ESM, which jest
- * cannot `require()` nor `import()` without --experimental-vm-modules, so the
- * server jest config `moduleNameMapper`s `@docmost/git-sync` to its TS SOURCE and
- * strips the ESM `.js` import suffixes. ts-jest then type-checks that source under
- * the server's (looser) tsconfig and trips a benign narrowing; the global
- * `isolatedModules: true` on the ts-jest transform (apps/server/package.json)
- * makes it transpile-only so this spec loads. Full type-checking of the package
- * is still enforced by its own `tsc`/vitest gates and the server `tsc --noEmit`.
- *
- * §13.1 IDEMPOTENCY GATE — the blocking gate for git-sync Phase B.
- *
- * Proves the `@docmost/git-sync` pure converter is schema-compatible
- * with the server's REAL editor-ext document schema: a representative corpus of
- * editor-ext ProseMirror documents must survive a full round trip through the
- * actual server write path without losing any node / mark / attribute.
- *
- * Pipeline per document (issue #194 §13.1):
- *   1. md   = convertProseMirrorToMarkdown(content)          // git-sync export
- *   2. doc  = await markdownToProseMirror(md)                // git-sync import
- *   3. push `doc` through the REAL editor-ext Yjs write path the server uses:
- *        ydoc       = TiptapTransformer.toYdoc(doc, 'default', tiptapExtensions)
- *        normalized = TiptapTransformer.fromYdoc(ydoc, 'default')
- *      This is exactly what PersistenceExtension does on store
- *      (apps/server/src/collaboration/extensions/persistence.extension.ts:96/115)
- *      with the same `tiptapExtensions` (collaboration.util.ts) and the same
- *      `@hocuspocus/transformer`, so the gate exercises the real schema
- *      validation that runs on a git-sync write (issue #194 §3.3).
- *   4. assert docsCanonicallyEqual(canon(original), canon(normalized)) === true
- *
- * Any node / mark / attr that editor-ext drops (because the git-sync
- * docmost-schema named it differently, or declares a different default) makes
- * the gate FAIL for that document — exactly the schema-divergence issue #194 §3.3 /
- * §13.1 warn about. Genuine, irreducible divergences are isolated into the
- * clearly-named `KNOWN DIVERGENCE` block at the bottom (never silently hidden).
- *
- * Requires the workspace packages built first:
- *   pnpm --filter @docmost/editor-ext build
- *   pnpm --filter @docmost/git-sync  build
- */
-import { TiptapTransformer } from '@hocuspocus/transformer';
-// Import the server's real schema FIRST so `@docmost/editor-ext` resolves to its
-// built CJS `dist` (its `main`). The ESM-only `@docmost/git-sync` package is
-// mapped to its TS SOURCE by the jest `moduleNameMapper` (the built ESM cannot
-// be `require()`d nor dynamically `import()`ed under jest's node VM), so ts-jest
-// transpiles the real converter to CJS here — exercising the actual converter
-// the server ships, not a stub.
-import { tiptapExtensions } from './collaboration.util';
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-  canonicalizeContent,
-  docsCanonicallyEqual,
-} from '@docmost/git-sync';
-
-/**
- * Run a single editor-ext document through the full gate pipeline and return
- * the canonical original vs the canonical doc as it lands after the real Yjs
- * write path, plus the intermediate markdown for diagnostics.
- */
-async function runGate(original: any): Promise<{
-  md: string;
-  imported: any;
-  normalized: any;
-  canonOriginal: any;
-  canonNormalized: any;
-}> {
-  // 1) editor-ext JSON -> markdown (git-sync export).
-  const md = convertProseMirrorToMarkdown(original);
-
-  // 2) markdown -> ProseMirror JSON (git-sync import, docmost-schema).
-  const imported = await markdownToProseMirror(md);
-
-  // 3) push through the REAL editor-ext schema via the server's Yjs write path.
-  //    toYdoc validates `imported` against tiptapExtensions (throws on an
-  //    unknown node, drops unknown attrs); fromYdoc reads it back as the
-  //    normalized editor-ext JSON the server would persist.
-  const ydoc = TiptapTransformer.toYdoc(imported, 'default', tiptapExtensions);
-  const normalized = TiptapTransformer.fromYdoc(ydoc, 'default');
-
-  return {
-    md,
-    imported,
-    normalized,
-    canonOriginal: canonicalizeContent(original),
-    canonNormalized: canonicalizeContent(normalized),
-  };
-}
-
-const doc = (...content: any[]) => ({ type: 'doc', content });
-const text = (t: string, marks?: any[]) =>
-  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
-const para = (...content: any[]) => ({ type: 'paragraph', content });
-
-// ---------------------------------------------------------------------------
-// Corpus: editor-ext ProseMirror documents covering the common node/mark types.
-// Node / mark / attr names and DEFAULTS are taken from the real schema —
-// editor-ext (packages/editor-ext/src) + the server's tiptapExtensions
-// (collaboration.util.ts) — NOT guessed. Where editor-ext materializes a
-// non-null default on import (e.g. image.align="center", callout.type, list
-// start) the fixture pre-authors that materialized value so the round trip is
-// already at its fixpoint (matches how the engine normalizes-on-write, SPEC §11).
-// ---------------------------------------------------------------------------
-const CORPUS: Record<string, any> = {
-  'paragraphs + headings (h1-h3)': doc(
-    { type: 'heading', attrs: { level: 1 }, content: [text('Heading one')] },
-    { type: 'heading', attrs: { level: 2 }, content: [text('Heading two')] },
-    { type: 'heading', attrs: { level: 3 }, content: [text('Heading three')] },
-    para(text('A plain paragraph of text.')),
-    para(text('Second paragraph.')),
-  ),
-
-  'inline marks (bold/italic/strike/code)': doc(
-    para(
-      text('normal '),
-      text('bold', [{ type: 'bold' }]),
-      text(' '),
-      text('italic', [{ type: 'italic' }]),
-      text(' '),
-      text('struck', [{ type: 'strike' }]),
-      text(' '),
-      text('code', [{ type: 'code' }]),
-    ),
-  ),
-
-  'links': doc(
-    para(
-      text('see '),
-      text('the site', [
-        { type: 'link', attrs: { href: 'https://example.com' } },
-      ]),
-      text(' for more'),
-    ),
-  ),
-
-  'bullet list': doc({
-    type: 'bulletList',
-    content: [
-      { type: 'listItem', content: [para(text('first'))] },
-      { type: 'listItem', content: [para(text('second'))] },
-      { type: 'listItem', content: [para(text('third'))] },
-    ],
-  }),
-
-  'ordered list': doc({
-    type: 'orderedList',
-    attrs: { start: 1 },
-    content: [
-      { type: 'listItem', content: [para(text('one'))] },
-      { type: 'listItem', content: [para(text('two'))] },
-    ],
-  }),
-
-  'task list (checkbox)': doc({
-    type: 'taskList',
-    content: [
-      {
-        type: 'taskItem',
-        attrs: { checked: true },
-        content: [para(text('done item'))],
-      },
-      {
-        type: 'taskItem',
-        attrs: { checked: false },
-        content: [para(text('todo item'))],
-      },
-    ],
-  }),
-
-  'blockquote': doc({
-    type: 'blockquote',
-    content: [para(text('a quoted line')), para(text('second quoted line'))],
-  }),
-
-  'callout (info)': doc({
-    type: 'callout',
-    attrs: { type: 'info' },
-    content: [para(text('an informational callout'))],
-  }),
-
-  'callout (warning)': doc({
-    type: 'callout',
-    attrs: { type: 'warning' },
-    content: [para(text('a warning callout'))],
-  }),
-
-  'code block (with language)': doc({
-    type: 'codeBlock',
-    attrs: { language: 'typescript' },
-    // A fenced code block's body is stored with a trailing newline (the form a
-    // markdown ``` fence round-trips to: marked normalizes the code text to end
-    // in "\n"). Authoring the fixture at that fixpoint mirrors how the engine
-    // normalizes-on-write (SPEC §11): codeBlock + `language` round-trip exactly.
-    content: [text('const a: number = 1;\nconsole.log(a);\n')],
-  }),
-
-  'horizontal rule': doc(
-    para(text('before')),
-    { type: 'horizontalRule' },
-    para(text('after')),
-  ),
-
-  'table (header row + cells)': doc({
-    type: 'table',
-    content: [
-      {
-        type: 'tableRow',
-        content: [
-          {
-            type: 'tableHeader',
-            attrs: { colspan: 1, rowspan: 1, colwidth: null },
-            content: [para(text('Name'))],
-          },
-          {
-            type: 'tableHeader',
-            attrs: { colspan: 1, rowspan: 1, colwidth: null },
-            content: [para(text('Value'))],
-          },
-        ],
-      },
-      {
-        type: 'tableRow',
-        content: [
-          {
-            type: 'tableCell',
-            attrs: { colspan: 1, rowspan: 1, colwidth: null },
-            content: [para(text('alpha'))],
-          },
-          {
-            type: 'tableCell',
-            attrs: { colspan: 1, rowspan: 1, colwidth: null },
-            content: [para(text('1'))],
-          },
-        ],
-      },
-    ],
-  }),
-
-  // --- editor-ext nodes/marks beyond the original corpus (item #7) ----------
-  // Each of these was verified to round-trip CLEANLY through the real gate
-  // (export -> markdown -> import -> editor-ext Yjs write path). Fixtures are
-  // pre-authored at the engine's normalize-on-write fixpoint (SPEC §11), e.g.
-  // details carries the materialized `open:false`, and color marks use the
-  // `rgb(...)` form the HTML re-parser normalizes to.
-
-  'mention (user)': doc(
-    para(
-      text('hi '),
-      {
-        type: 'mention',
-        attrs: {
-          id: 'user-123',
-          label: 'Alice',
-          entityType: 'user',
-          entityId: 'user-123',
-          creatorId: 'creator-1',
-        },
-      },
-      text(' there'),
-    ),
-  ),
-
-  'inline math': doc(
-    para(
-      text('inline '),
-      { type: 'mathInline', attrs: { text: 'x^2' } },
-      text(' math'),
-    ),
-  ),
-
-  'block math': doc({ type: 'mathBlock', attrs: { text: 'x^2 + y^2 = z^2' } }),
-
-  'details (collapsible)': doc({
-    type: 'details',
-    // `open:false` is the value editor-ext materializes on import; pre-authoring
-    // it puts the fixture at its round-trip fixpoint.
-    attrs: { open: false },
-    content: [
-      { type: 'detailsSummary', content: [text('Summary line')] },
-      { type: 'detailsContent', content: [para(text('hidden body'))] },
-    ],
-  }),
-
-  'highlight (mark, no color)': doc(
-    para(
-      text('a '),
-      text('highlighted', [{ type: 'highlight' }]),
-      text(' word'),
-    ),
-  ),
-
-  'highlight (mark, with color)': doc(
-    para(
-      text('a '),
-      text('red', [{ type: 'highlight', attrs: { color: 'rgb(255, 0, 0)' } }]),
-      text(' word'),
-    ),
-  ),
-
-  'subscript': doc(
-    para(text('H'), text('2', [{ type: 'subscript' }]), text('O')),
-  ),
-
-  'superscript': doc(
-    para(text('E=mc'), text('2', [{ type: 'superscript' }])),
-  ),
-
-  'text color (textStyle)': doc(
-    // The HTML re-parser normalizes CSS colors to the `rgb(...)` form, so the
-    // fixture pre-authors that form; a `#hex` color would round-trip to the
-    // equivalent rgb() and is therefore a value-normalization divergence (see
-    // the KNOWN DIVERGENCE block below).
-    para(text('green', [{ type: 'textStyle', attrs: { color: 'rgb(0, 255, 0)' } }])),
-  ),
-
-  'nested / mixed document': doc(
-    { type: 'heading', attrs: { level: 1 }, content: [text('Mixed')] },
-    para(
-      text('intro with '),
-      text('bold', [{ type: 'bold' }]),
-      text(' and a '),
-      text('link', [{ type: 'link', attrs: { href: 'https://example.com' } }]),
-      text('.'),
-    ),
-    {
-      type: 'bulletList',
-      content: [
-        {
-          type: 'listItem',
-          content: [
-            para(text('item with '), text('code', [{ type: 'code' }])),
-          ],
-        },
-        {
-          type: 'listItem',
-          content: [
-            para(text('item with sublist')),
-            {
-              type: 'bulletList',
-              content: [
-                { type: 'listItem', content: [para(text('nested a'))] },
-                { type: 'listItem', content: [para(text('nested b'))] },
-              ],
-            },
-          ],
-        },
-      ],
-    },
-    {
-      type: 'callout',
-      attrs: { type: 'success' },
-      content: [
-        para(text('callout body')),
-        { type: 'codeBlock', attrs: { language: 'bash' }, content: [text('echo hi\n')] },
-      ],
-    },
-    {
-      type: 'blockquote',
-      content: [para(text('quote at the end'))],
-    },
-  ),
-
-  // Atom embeds that carry no inline text: they must round-trip via their
-  // schema-matching HTML (data-type div), NOT a literal that re-imports as plain
-  // text. `subpages` used to export as the literal "{{SUBPAGES}}" and came back
-  // as visible text on the page (red-team round-trip data loss) — this locks it.
-  // editor-ext materializes the `recursive: false` default on import, so the
-  // fixture pre-authors it to sit at the round-trip fixpoint (matches the other
-  // default-materializing fixtures above).
-  'subpages embed': doc({ type: 'subpages', attrs: { recursive: false } }),
-};
-
-describe('git-sync converter §13.1 idempotency gate (editor-ext schema)', () => {
-  for (const [name, original] of Object.entries(CORPUS)) {
-    it(`round-trips losslessly: ${name}`, async () => {
-      const { md, canonOriginal, canonNormalized } = await runGate(original);
-
-      const equal = docsCanonicallyEqual(original, canonNormalized);
-      if (!equal) {
-        // Surface a readable diff so a real divergence is actionable.
-        // eslint-disable-next-line no-console
-        console.error(
-          `\n[GATE FAIL] ${name}\n--- markdown ---\n${md}\n` +
-            `--- canonical original ---\n${JSON.stringify(canonOriginal, null, 2)}\n` +
-            `--- canonical round-tripped ---\n${JSON.stringify(canonNormalized, null, 2)}\n`,
-        );
-      }
-      expect(equal).toBe(true);
-    });
-  }
-});
-
-// ---------------------------------------------------------------------------
-// KNOWN DIVERGENCE — images (isolated so it does NOT silently weaken the gate).
-//
-// This is NOT a schema-name divergence: the `image` NODE itself round-trips
-// through editor-ext fine (it survives toYdoc under the real tiptapExtensions).
-// The loss is intrinsic to MARKDOWN, the on-disk transport format git-sync uses:
-//
-//   1. `convertProseMirrorToMarkdown` emits a standard `![alt](src)` image
-//      (markdown-converter.ts case "image"). Standard markdown image syntax has
-//      no way to express `width` / `height` / `align`, so those attrs are
-//      DROPPED on export and cannot be recovered on import.
-//   2. A block-level image is hoisted out of its line by the HTML re-parser,
-//      leaving a leading EMPTY paragraph (the same block-image-hoist limitation
-//      documented in packages/git-sync/test/fixtures/known-limitations).
-//
-// The gate documents the EXACT lossy shape below. If the converter is ever
-// taught to preserve image dimensions (e.g. by emitting an HTML <img> with
-// data-* attrs, as it already does for video/diagrams), these assertions flip
-// and the image fixture should be promoted into the green CORPUS above.
-// ---------------------------------------------------------------------------
-describe('git-sync converter §13.1 image dimensions preserved (was KNOWN DIVERGENCE)', () => {
-  const imageDoc = doc({
-    type: 'image',
-    attrs: {
-      src: 'https://example.com/pic.png',
-      width: 640,
-      height: 480,
-      align: 'center',
-    },
-  });
-
-  it('preserves width/height/align by exporting an HTML <img> (PR #119 round-trip fix)', async () => {
-    const { md, canonNormalized } = await runGate(imageDoc);
-
-    // A top-level image carrying layout attrs is now exported as a schema-
-    // matching HTML <img> (the same path video/diagrams already use), so the
-    // dimensions and alignment survive the round trip instead of collapsing to
-    // bare `![](src)`.
-    expect(md.trim()).toBe(
-      '<img src="https://example.com/pic.png" width="640" height="480" align="center">',
-    );
-
-    // The round-tripped image keeps src + the layout attrs. width/height are
-    // re-imported as strings (matching the video/audio/pdf string convention),
-    // so assert the values rather than the JS type.
-    const imgAttrs = (canonNormalized as any).content[0].attrs;
-    expect((canonNormalized as any).content[0].type).toBe('image');
-    expect(imgAttrs.src).toBe('https://example.com/pic.png');
-    expect(imgAttrs.align).toBe('center');
-    expect(String(imgAttrs.width)).toBe('640');
-    expect(String(imgAttrs.height)).toBe('480');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// KNOWN DIVERGENCE — text alignment (item #7; isolated, not silently dropped).
-//
-// editor-ext registers TextAlign for heading+paragraph, and the SERVER schema
-// fully supports it — the loss is intrinsic to the MARKDOWN transport:
-//
-//   • A paragraph's `textAlign` is EXPORTED as `<div align="...">text</div>`
-//     (markdown-converter case "paragraph"), but on import the converter's
-//     docmost-schema declares `textAlign` WITHOUT a parseHTML mapping, so the
-//     `align` attribute is never recovered -> it imports as `textAlign:null`
-//     and canonicalizes away. A heading's alignment is not even exported.
-//   • Therefore any non-default alignment is dropped on a full round trip.
-//
-// If the converter is ever taught to parse `align`/`text-align` back onto the
-// block, this assertion flips and an aligned-paragraph fixture should be
-// promoted into the green CORPUS above.
-// ---------------------------------------------------------------------------
-describe('git-sync converter §13.1 KNOWN DIVERGENCE (text alignment dropped)', () => {
-  it('drops a paragraph textAlign on the markdown round trip', async () => {
-    const alignedDoc = doc({
-      type: 'paragraph',
-      attrs: { textAlign: 'center' },
-      content: [text('centered')],
-    });
-
-    const { canonNormalized } = await runGate(alignedDoc);
-
-    // The round-tripped paragraph carries no alignment.
-    expect(canonNormalized).toEqual({
-      type: 'doc',
-      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'centered' }] }],
-    });
-    expect(docsCanonicallyEqual(alignedDoc, canonNormalized)).toBe(false);
-  });
-
-  it('drops a heading textAlign (headings do not export alignment at all)', async () => {
-    const alignedHeading = doc({
-      type: 'heading',
-      attrs: { level: 2, textAlign: 'center' },
-      content: [text('centered heading')],
-    });
-
-    const { md, canonNormalized } = await runGate(alignedHeading);
-
-    // Export is a plain markdown heading — no alignment syntax.
-    expect(md.trim()).toBe('## centered heading');
-    expect(docsCanonicallyEqual(alignedHeading, canonNormalized)).toBe(false);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// KNOWN DIVERGENCE — textStyle color is VALUE-NORMALIZED, not lost (item #7).
-//
-// The textStyle/color mark itself round-trips (the green CORPUS has the rgb()
-// form). But a `#hex` color is normalized to the equivalent `rgb(...)` string
-// by the HTML re-parser on import, and canonicalize.ts does NOT normalize color
-// formats — so a `#hex` original is not STRING-identical to its round trip even
-// though the color is semantically preserved. Locked here so the boundary is
-// explicit: author color fixtures in rgb() form to stay in the green corpus.
-// ---------------------------------------------------------------------------
-describe('git-sync converter §13.1 KNOWN DIVERGENCE (textStyle color #hex -> rgb)', () => {
-  it('normalizes a #hex text color to rgb() (semantically preserved, string-divergent)', async () => {
-    const hexDoc = doc(
-      para(text('green', [{ type: 'textStyle', attrs: { color: '#00ff00' } }])),
-    );
-
-    const { canonNormalized } = await runGate(hexDoc);
-
-    // Color survives, but as the normalized rgb() string.
-    expect(canonNormalized).toEqual({
-      type: 'doc',
-      content: [
-        {
-          type: 'paragraph',
-          content: [
-            {
-              type: 'text',
-              text: 'green',
-              marks: [{ type: 'textStyle', attrs: { color: 'rgb(0, 255, 0)' } }],
-            },
-          ],
-        },
-      ],
-    });
-    // Not string-identical to the #hex original.
-    expect(docsCanonicallyEqual(hexDoc, canonNormalized)).toBe(false);
-  });
-});

apps/server/src/collaboration/listeners/page-tree-bridge.publisher.spec.ts

@@ -0,0 +1,81 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import { PageTreeBridgePublisher } from './page-tree-bridge.publisher';
+import { COLLAB_TREE_UPDATE_CHANNEL } from '../constants';
+import {
+  PageEvent,
+  TreeUpdateSnapshot,
+} from '../../database/listeners/page.listener';
+
+const treeUpdate: TreeUpdateSnapshot = {
+  id: 'page-1',
+  slugId: 'slug-1',
+  spaceId: 'space-1',
+  parentPageId: null,
+  title: 'Renamed',
+  icon: '🚀',
+};
+
+describe('PageTreeBridgePublisher', () => {
+  let publisher: PageTreeBridgePublisher;
+  let redis: { publish: jest.Mock };
+
+  beforeEach(async () => {
+    redis = { publish: jest.fn().mockResolvedValue(1) };
+    const redisService = { getOrThrow: () => redis } as unknown as RedisService;
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        PageTreeBridgePublisher,
+        { provide: RedisService, useValue: redisService },
+      ],
+    }).compile();
+
+    publisher = module.get<PageTreeBridgePublisher>(PageTreeBridgePublisher);
+  });
+
+  it('WITH a `treeUpdate`: publishes the JSON snapshot on the channel', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+      treeUpdate,
+    };
+
+    await publisher.onPageUpdated(event);
+
+    expect(redis.publish).toHaveBeenCalledTimes(1);
+    expect(redis.publish).toHaveBeenCalledWith(
+      COLLAB_TREE_UPDATE_CHANNEL,
+      JSON.stringify(treeUpdate),
+    );
+  });
+
+  it('content-only save (NO `treeUpdate`): does NOT publish', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+    };
+
+    await publisher.onPageUpdated(event);
+
+    expect(redis.publish).not.toHaveBeenCalled();
+  });
+
+  it('a publish rejection is caught (no throw)', async () => {
+    redis.publish.mockRejectedValueOnce(new Error('redis down'));
+    const errorSpy = jest
+      .spyOn(publisher['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+      treeUpdate,
+    };
+
+    await expect(publisher.onPageUpdated(event)).resolves.toBeUndefined();
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+
+    errorSpy.mockRestore();
+  });
+});

apps/server/src/collaboration/listeners/page-tree-bridge.publisher.ts

@@ -0,0 +1,55 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import type { Redis } from 'ioredis';
+import { EventName } from '../../common/events/event.contants';
+import { PageEvent } from '../../database/listeners/page.listener';
+import { COLLAB_TREE_UPDATE_CHANNEL } from '../constants';
+
+/**
+ * Collab-process half of the cross-process tree-update bridge.
+ *
+ * The standalone collab process bootstraps `CollabAppModule`, which does NOT
+ * import `WsModule`/`PageWsListener`. So when a collaborative title/icon rename
+ * persists and emits `EventName.PAGE_UPDATED` with a `treeUpdate` snapshot, there
+ * is no listener in this process to broadcast it — the live tree update would be
+ * lost for 2-process (COLLAB_URL set) deployments.
+ *
+ * This publisher fills that gap: it forwards the `treeUpdate` snapshot over a
+ * Redis pub/sub channel to the API process, which re-broadcasts it via
+ * `WsTreeService` (the single broadcast authority).
+ *
+ * It is registered ONLY in `CollabAppModule.providers`, so it never runs in the
+ * API process (where `PageWsListener` already broadcasts the same event locally).
+ * That module placement is what prevents a double broadcast. In single-process
+ * mode `CollabAppModule` is not loaded at all, so this publisher never runs.
+ */
+@Injectable()
+export class PageTreeBridgePublisher {
+  private readonly logger = new Logger(PageTreeBridgePublisher.name);
+  private readonly redis: Redis;
+
+  constructor(private readonly redisService: RedisService) {
+    this.redis = this.redisService.getOrThrow();
+  }
+
+  @OnEvent(EventName.PAGE_UPDATED)
+  async onPageUpdated(event: PageEvent): Promise<void> {
+    // Mirror PageWsListener's gating: only title/icon changes carry a snapshot.
+    // Content-only saves leave `treeUpdate` undefined and are ignored.
+    if (!event.treeUpdate) return;
+
+    try {
+      await this.redis.publish(
+        COLLAB_TREE_UPDATE_CHANNEL,
+        JSON.stringify(event.treeUpdate),
+      );
+    } catch (err) {
+      // A Redis publish failure must not break the store path.
+      this.logger.error(
+        `Failed to publish tree update to ${COLLAB_TREE_UPDATE_CHANNEL}`,
+        err instanceof Error ? err.stack : String(err),
+      );
+    }
+  }
+}