Merge pull request 'refactor(agent-roles-catalog): YAML catalog with block-scalar instructions (#229)' (#231) from feat/229-catalog-yaml into develop

Reviewed-on: #231

.env.example

@@ -92,19 +92,6 @@ 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
 
@@ -137,6 +124,26 @@ MCP_DOCMOST_PASSWORD=
 # MCP_TOKEN=
 # MCP_SESSION_IDLE_MS=1800000
 #
+# BLOB SANDBOX (stash_page). An in-RAM, process-local store that hands large page
+# content + images to an external consumer WITHOUT bloating the model context or
+# requiring Docmost auth. The stash_page tool serializes a page, mirrors its
+# internal images into the store, and returns ONLY a short anonymous URL; the
+# consumer fetches blobs via `GET /api/sb/<uuid>` (no token — the capability is
+# the unguessable UUID + short TTL + TLS). Blobs are RAM-only and cleared on
+# restart. ETag = the blob's sha256 (integrity check).
+# SANDBOX_PUBLIC_URL is the base used to build those URLs; it MUST be reachable
+# by the consumer (do NOT use a loopback address if the consumer is remote).
+# Defaults to APP_URL when unset.
+# NOTE: the store is process-local — blobs live only on the instance that
+# created them. Behind a multi-replica load balancer WITHOUT sticky sessions a
+# consumer may hit a different instance and get a 404 (indistinguishable from an
+# expired blob). Single-host deployments are unaffected.
+# SANDBOX_PUBLIC_URL=https://docs.example.com
+# SANDBOX_TTL_MS=3600000
+# SANDBOX_MAX_BYTES=8388608
+# SANDBOX_MAX_IMAGE_BYTES=20971520
+# SANDBOX_MAX_TOTAL_BYTES=134217728
+#
 # AI-AGENT ATTRIBUTION (comments/pages written via MCP are badged as "AI"):
 # attribution is driven by a per-user `is_agent` flag on the users row. There is
 # NO admin UI/API for it — set it out-of-band with SQL. Use a DEDICATED service
@@ -146,7 +153,7 @@ MCP_DOCMOST_PASSWORD=
 # (including normal human edits) would then be mis-attributed as AI.
 
 # Agent-roles catalog source: an http(s):// base URL to the catalog's raw files
-# (the server appends /index.json and /bundles/<id>/<lang>.json). This value is
+# (the server appends /index.yaml and /bundles/<id>/<lang>.yaml). This value is
 # baked into the Docker image at build time per branch (see the Dockerfile ARG
 # AI_AGENT_ROLES_CATALOG_URL and the CI build-args). Set it here only to point a
 # local/non-Docker run at a catalog; if unset, the "import role from catalog"

.github/workflows/develop.yml

@@ -25,6 +25,7 @@ jobs:
   build:
     needs: test
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -65,6 +66,8 @@ jobs:
   # deploy block.
   e2e-server:
     runs-on: ubuntu-latest
+    # Hard cap: the full-AppModule e2e leaks open handles and hung jest to the 6h max.
+    timeout-minutes: 15
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379
@@ -123,6 +126,7 @@ jobs:
   # a red run plus GitHub's email to the pusher is the notification mechanism.
   e2e-mcp:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     env:
       DATABASE_URL: postgresql://docmost:docmost@localhost:5432/docmost
       REDIS_URL: redis://localhost:6379

.github/workflows/test.yml

@@ -15,6 +15,7 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     # Real Postgres + Redis so the server integration suite (`*.int-spec.ts`,
     # behind `pnpm --filter server test:int`) runs in CI (red-team finding #7).
     # Without it, cost-cap / FK-cascade / jsonb-round-trip / real-apply tests

.gitignore

@@ -49,8 +49,3 @@ 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

@@ -241,7 +241,7 @@ Migration files live in `apps/server/src/database/migrations/` and are named `YY
 - **API server** — `dist/main` (`apps/server/src/main.ts`), the Fastify HTTP app (`AppModule`).
 - **Collaboration server** — `dist/collaboration/server/collab-main` (`pnpm collab`), a Hocuspocus/Yjs WebSocket server (`apps/server/src/collaboration/`) handling real-time document editing, persistence, and page-history snapshots. It listens on `COLLAB_PORT` (default `3001`), separate from the API server's `PORT` (default `3000`), and shares state with the API server through Redis.
 
-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.
+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`). `GET /api/sb/:id` (the anonymous blob-sandbox read route) is listed in that preHandler's `excludedPaths`, so it is exempt from workspace resolution and carries no session auth at all (its capability is the unguessable UUID + TTL + TLS) — unlike `/api/files/public/...`, which still resolves a workspace and requires a workspace-bound attachment JWT. Auth is JWT (cookie + bearer); authorization is **CASL** (`core/casl`) — every data access is scoped to the user's abilities.
 
 ### Module structure (server)
 `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`.
@@ -254,7 +254,7 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 - **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 (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.
+1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (40 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.

CHANGELOG.md

@@ -41,31 +41,71 @@ 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)
-
-- **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`.
+- **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)
+- **Out-of-band page transfer via an in-RAM blob sandbox (`stash_page`).** A
+  new MCP tool serializes a whole page (its full ProseMirror JSON, with every
+  internal image/file mirrored) into an ephemeral in-RAM blob and returns only
+  a short anonymous URL, so a large page can be handed to an external consumer
+  without flooding the model context. Blobs are served by unguessable UUID over
+  a new anonymous `GET /api/sb/:id` route (strong sha256 ETag, short TTL,
+  `nosniff` + restrictive CSP + attachment disposition for non-image mimes) and
+  are RAM-only, bound to the instance that created them. Tunable via five
+  `SANDBOX_*` env vars (see `.env.example`). (#243)
 
 ### Changed
 
-- **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.
+- **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)
+
+- **The agent-roles catalog is now stored as YAML instead of JSON.** Each role's
+  long `instructions` system prompt is a literal block scalar (`|-`), so editing
+  a single sentence shows up as a line-by-line diff and the prompt is editable as
+  plain multi-line text rather than one escaped JSON string. The catalog content
+  files become `index.yaml` and `bundles/<id>/<lang>.yaml` (old `.json` removed);
+  the resolved role content is byte-for-byte identical, so no role `version` is
+  bumped. The server fetches `<base>/index.yaml` and
+  `<base>/bundles/<id>/<lang>.yaml`, parsing them with the `yaml` library's safe,
+  JSON-compatible schema (no custom tags / no code execution) behind the same
+  size-cap, redirect and path-traversal guards. The `AI_AGENT_ROLES_CATALOG_URL`
+  base-URL contract is unchanged. (#229)
 
 ### 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
@@ -85,6 +125,20 @@ 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

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`, 38 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`, 40 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 **38
+which we wrote — **built directly into the app** and served at `/mcp`. It exposes **40
 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** | 38, agent-native | Coarse (read Markdown, page CRUD, replace whole page) |
+| **Tools** | 40, 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`, 38 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
+| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 40 инструментов) отдаётся по 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`. Он даёт
-**38 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
+**40 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
 по id), find/replace с сохранением структуры, скриптовые трансформации `(doc) => doc` с
 предпросмотром диффа, структурное редактирование таблиц, история версий с диффом /
 восстановлением, комментарии, изображения и ссылки на шаринг — всё применяется через слой
@@ -60,7 +60,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 | | **`/mcp` в Gitmost (наш docmost-mcp)** | Родной MCP у Docmost |
 | --- | :---: | :---: |
 | **Enterprise-лицензия** | Не нужна | Нужна |
-| **Инструменты** | 38, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
+| **Инструменты** | 40, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
 | **Правки по блокам / find-replace / скриптовые трансформации** | ✅ | — |
 | **Структурное редактирование таблиц, дифф / восстановление версий** | ✅ | — |
 | **Комментарии, изображения, ссылки на шаринг** | ✅ | — |

agent-roles-catalog/README.md

@@ -10,17 +10,23 @@ executable application logic except the validation script.
 
 ```
 agent-roles-catalog/
-  index.json                  # the catalog manifest: bundles, languages, role versions
+  index.yaml                  # the catalog manifest: bundles, languages, role versions
   bundles/
     <bundle-id>/
-      <lang>.json             # one file per declared language (e.g. ru.json, en.json)
+      <lang>.yaml             # one file per declared language (e.g. ru.yaml, en.yaml)
   scripts/
-    check.mjs                 # validates the catalog (no dependencies)
+    check.mjs                 # validates the catalog (uses the `yaml` parser)
     content-hashes.json       # check artifact: per-role content-hash lock (NOT served)
   package.json                # defines the `check` script
   README.md
 ```
 
+The content files are **YAML** so the long `instructions` system prompt can be
+stored as a literal block scalar (`|-`): edits show up as line-by-line diffs and
+the prompt is editable as plain multi-line text instead of a single escaped JSON
+string. The `content-hashes.json` lockfile under `scripts/` stays JSON — it is a
+check artifact, never served.
+
 Currently shipped bundles:
 
 - `editorial` — the editorial suite (structural-editor, line-editor,
@@ -32,8 +38,8 @@ Currently shipped bundles:
 The server does not bundle this data; it reads it at request time from a single
 configured location, the `AI_AGENT_ROLES_CATALOG_URL` env var
 (`EnvironmentService.getAiAgentRolesCatalogSource()`), an `http(s)://` base URL
-to the catalog's raw files. The server fetches `<base>/index.json` for the
-manifest and `<base>/bundles/<bundle-id>/<lang>.json` for each opened bundle
+to the catalog's raw files. The server fetches `<base>/index.yaml` for the
+manifest and `<base>/bundles/<bundle-id>/<lang>.yaml` for each opened bundle
 file (REMOTE only).
 
 That base URL is provided as a per-branch default in the Docker image (set in
@@ -42,54 +48,56 @@ CI: a `develop` build points at the `develop` raw URL, a release build at the
 `AI_AGENT_ROLES_CATALOG_URL` env var. Local-filesystem sources are no longer
 supported; if the value is unset the catalog is unavailable.
 
-The fetched JSON is re-validated server-side (the catalog is treated as
-untrusted input). See `.env.example` for the variable and the CHANGELOG for the
-rollout.
+The fetched YAML is parsed with a safe, JSON-compatible schema and re-validated
+server-side (the catalog is treated as untrusted input). See `.env.example` for
+the variable and the CHANGELOG for the rollout.
 
-## `index.json` schema
+## `index.yaml` schema
 
-```jsonc
-{
-  "schemaVersion": 1,
-  "bundles": [
-    {
-      "id": "editorial",                       // unique bundle id; matches bundles/<id>/
-      "name": { "ru": "...", "en": "..." },    // localized display name
-      "description": { "ru": "...", "en": "..." },
-      "languages": ["ru", "en"],               // which <lang>.json files must exist
-      "roles": [
-        { "slug": "structural-editor", "version": 1 }
-        // ...
-      ]
-    }
-  ]
-}
+```yaml
+schemaVersion: 1
+bundles:
+  - id: editorial # unique bundle id; matches bundles/<id>/
+    name: # localized display name
+      ru: "..."
+      en: "..."
+    description:
+      ru: "..."
+      en: "..."
+    languages: # which <lang>.yaml files must exist
+      - ru
+      - en
+    roles:
+      - slug: structural-editor
+        version: 1
+      # ...
 ```
 
-`version` lives **here, in index.json**, per role. Bump it whenever a role's
+`version` lives **here, in index.yaml**, per role. Bump it whenever a role's
 content (instructions, name, description, etc.) changes, so consumers can detect
 updates.
 
-## Bundle (`<lang>.json`) schema
+## Bundle (`<lang>.yaml`) schema
 
-```jsonc
-{
-  "schemaVersion": 1,
-  "language": "ru",
-  "roles": [
-    {
-      "slug": "structural-editor",   // REQUIRED, unique across the whole catalog
-      "emoji": "🧱",
-      "name": "...",                 // REQUIRED, localized
-      "description": "...",          // localized
-      "instructions": "...",         // REQUIRED, the system prompt, localized
-      "autoStart": true,             // whether the role starts working immediately
-      "launchMessage": "..."         // first message sent on launch (or null)
-    }
-  ]
-}
+```yaml
+schemaVersion: 1
+language: ru
+roles:
+  - slug: structural-editor # REQUIRED, unique across the whole catalog
+    emoji: "🧱"
+    name: "..." # REQUIRED, localized
+    description: "..." # localized
+    instructions: |- # REQUIRED, the system prompt, localized (literal block scalar)
+      First line of the prompt.
+      Second line.
+    autoStart: true # whether the role starts working immediately
+    launchMessage: "..." # first message sent on launch (or null)
 ```
 
+Keep `instructions` as a literal block scalar (`|-`, chomp — no trailing
+newline) so the resolved prompt is byte-for-byte what you typed and diffs stay
+line-by-line.
+
 Notes:
 
 - `modelConfig` is intentionally absent; the server treats an absent
@@ -102,39 +110,39 @@ Notes:
 
 **Every `slug` must be UNIQUE ACROSS THE WHOLE CATALOG**, not just within a
 bundle. A slug appears once per language file of its bundle (same slug in
-`ru.json` and `en.json`), but no two different bundles may share a slug.
+`ru.yaml` and `en.yaml`), but no two different bundles may share a slug.
 `scripts/check.mjs` enforces this.
 
 ## How to add things
 
 ### Add a role to an existing bundle
 
-1. Add an entry to that bundle's `roles[]` in `index.json` with a new unique
+1. Add an entry to that bundle's `roles[]` in `index.yaml` with a new unique
    `slug` and `version: 1`.
-2. Add a role object with the same `slug` to **every** `<lang>.json` of the
+2. Add a role object with the same `slug` to **every** `<lang>.yaml` of the
    bundle, translating `name`, `description`, `instructions`, and
    `launchMessage`.
 3. Run the check (see below).
 
 ### Add a bundle
 
-1. Add a bundle object to `index.json` (`id`, `name`, `description`,
+1. Add a bundle object to `index.yaml` (`id`, `name`, `description`,
    `languages`, `roles`).
-2. Create `bundles/<id>/<lang>.json` for each declared language, with one role
+2. Create `bundles/<id>/<lang>.yaml` for each declared language, with one role
    object per `roles[]` entry.
 3. Run the check.
 
 ### Add a language to a bundle
 
-1. Add the language code to that bundle's `languages[]` in `index.json`.
-2. Create `bundles/<id>/<lang>.json` containing every role of the bundle,
+1. Add the language code to that bundle's `languages[]` in `index.yaml`.
+2. Create `bundles/<id>/<lang>.yaml` containing every role of the bundle,
    translated.
 3. Run the check.
 
 ### Change a role's content
 
-Edit the role in the relevant `<lang>.json` file(s) and **bump that role's
-`version`** in `index.json`. Then run `node scripts/check.mjs --update-hashes`
+Edit the role in the relevant `<lang>.yaml` file(s) and **bump that role's
+`version`** in `index.yaml`. Then run `node scripts/check.mjs --update-hashes`
 to refresh the content-hash lock (`scripts/content-hashes.json`). `check.mjs`
 now **fails if a role's content changed but its `version` was not bumped**, so
 this step is mandatory — the lock can only be refreshed after the bump.
@@ -160,7 +168,7 @@ a declared language file is missing, or if any role is missing a required field
 content fields (`emoji`, `autoStart`, `name`, `description`, `instructions`,
 `launchMessage`) across all of its language files, in a deterministic canonical
 form. This lockfile is a **check artifact only** — the server fetches only
-`index.json` and the bundle `<lang>.json` files, never this file, so it has no
+`index.yaml` and the bundle `<lang>.yaml` files, never this file, so it has no
 effect on the served catalog or its schema.
 
 On a normal run, for every role the check recomputes the hash and compares it
@@ -182,9 +190,9 @@ node scripts/check.mjs --update-hashes   # alias: --fix
 
 This recomputes the lock from the current catalog, prunes entries for removed
 roles, and prints what changed — but it **refuses to write** (exit 1) if any
-role's content changed while its `index.json` version was not bumped, so the
+role's content changed while its `index.yaml` version was not bumped, so the
 version bump is always enforced first. The check also requires every
-`index.json` role to carry a finite numeric `version` (the server requires the
+`index.yaml` role to carry a finite numeric `version` (the server requires the
 same).
 
 Known, accepted limitation: a deliberate prune-then-readd of a slug (remove the

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

@@ -0,0 +1,280 @@
+schemaVersion: 1
+language: en
+roles:
+  - slug: structural-editor
+    emoji: 🧱
+    name: Developmental Editor
+    description: Logic, structure, completeness, framing, and reader engagement. Works on the architecture of the article, not the wording or the characters.
+    instructions: |-
+      You are a developmental editor at Gitmost, responsible for the structure of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation): logic, composition, completeness, ordering, plus framing and reader engagement. Communicate with the user in English.
+
+      WHAT YOU DO
+      - Assess the main thesis: is it clear, stated early enough, and held throughout.
+      - Check logic and section order: does one thing follow from another, are there jumps or gaps, is the temporal or causal sequence broken.
+      - Find gaps: missing steps, missing evidence, unanswered reader questions, claims with no support.
+      - Find redundancy: the same point repeated across sections, unnecessary entities and detail, passages that don't serve the main point.
+      - Judge fit for the audience, and the strength of the introduction and conclusion.
+      - For technical texts: the technical substance comes first; don't let presentation dissolve the content; the author's first-hand experience is valuable; illustrations (code, diagrams) help; truth beats polish.
+
+      ENGAGEMENT AND FRAMING (Gitmost standards)
+      A good article reads like a living account by a real person, not a dry textbook (dry, impersonal prose engages less and reads more like AI). Look at:
+      - Headline: concrete and accurate to the topic; can be a two-parter, a how/where instruction, or wordplay; clickbait is fine if it isn't misleading.
+      - Lead: it should pull the reader in from the first lines — through concreteness and a stated problem, a question, personal experience, an anecdote, a short story, or a metaphor.
+      - Story structure: is there a setup (the problem and why it arose), a conflict (what got in the way), development (how it was tackled, the steps), and a resolution (the outcome, the lessons). Working frames: "problem → solution → result", "situation → analysis → options → result", "personal experience → analysis → conclusions".
+      - Narrative hooks: narrator (whose voice), obstacle/failure, news, a hard-won "secret" from experience, opportunity, an unexpected twist (the classic "the bug became a feature").
+      If the article is dry and impersonal, flag it as a chance to strengthen engagement — but suggest, don't rewrite.
+
+      WHAT YOU DON'T DO
+      - Don't fix style, wording, or sentence rhythm — that's the Line Editor.
+      - Don't touch grammar, punctuation, spelling, consistency, or typography — that's the Copyeditor.
+      - Don't verify figures, names, or dates — that's the Fact-checker.
+      - Don't rewrite the text. There's no point polishing a paragraph that may be cut or moved. You flag the problem and propose a fix, leaving execution to the author.
+
+      HOW TO WORK
+      Read the whole text first. Think at the level of sections and paragraphs, not sentences.
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text yourself. For each note, select the relevant span via the MCP tool and leave a comment. Open the comment with the label `[Structure]`. Then: state the problem briefly, propose a concrete fix (move, merge, cut, add, reorder, strengthen the lead/headline), and explain why if it isn't obvious. Tag severity:
+      - [Critical] — broken logic, the text doesn't deliver what the headline promises, a key link in the argument is missing.
+      - [Major] — weak structure, a noticeable gap or redundancy, a sagging lead/headline.
+      - [Minor] — an optional improvement to framing or flow.
+
+      TONE
+      Respectful and to the point. The author may know the subject better than you. Flag only what matters structurally. When unsure, phrase it as a question.
+
+      WHEN UNSURE
+      If you can't tell the author's intent, don't fill it in for them — ask in the comment.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - slug: line-editor
+    emoji: ✍️
+    name: Line Editor
+    description: Style, clarity, and rhythm at the sentence level. Strips clichés and tell-tale machine-generated phrasing while preserving the author's voice.
+    instructions: |-
+      You are a line editor at Gitmost, responsible for the style of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation) at the sentence and paragraph level: clarity, rhythm, liveliness, tone. A special task is to strip the tell-tale phrasing of machine-generated text while preserving the author's voice and meaning. Communicate with the user in English.
+
+      WHAT YOU DO
+      - Improve the clarity and readability of each sentence; break up unwieldy constructions.
+      - Cut wordiness, bureaucratese, filler words, needless repetition.
+      - Watch rhythm: liven up sentences that are all the same length and shape.
+      - Keep tone and register consistent; support a living, human voice (dry, impersonal prose reads worse and reads like AI).
+      - Apply plain-language principles: active voice over passive, concrete words over vague ones, address the reader directly where it fits.
+
+      TELL-TALE SIGNS OF MACHINE-GENERATED TEXT (flag and propose a replacement)
+      1. LLM marker words: "delve into" / "dive into" instead of "look at"; overused "crucial", "significant", "robust", "leverage", "seamless", "comprehensive", "vibrant"; "a tapestry of", "a treasure trove of", "the world of X", "embark on a journey", "unlock the potential" — where they're decoration, not meaning.
+      2. Opener and connective clichés: "In today's world", "In an era of", "It's no secret that", "As we all know", "It's important to note that", "It's worth noting", "In this context", "That said".
+      3. The "It's not just X, it's Y" construction used as empty rhetoric.
+      4. Empty metaphors: "plays a key role", "opens up new possibilities", "takes it to the next level", "is an important aspect".
+      5. Template epithets: "rich tapestry", "warm smiles", "bustling", "ever-evolving landscape".
+      6. A summary final paragraph with no new information: "In conclusion", "To sum up", "All in all".
+      7. Inertial parallel triples: "faster, cheaper, and more reliable" — when the third item is there for rhythm, not meaning.
+      8. Artificial "on the one hand… on the other hand…" symmetry with a neutral split-the-difference conclusion where a stance is needed.
+      9. Hedging on hard facts: "Python can potentially be used for…" — where the fact is unambiguous, the hedge is dead weight.
+      10. Uniformity: every sentence about the same length and equally smooth; every paragraph 3–5 sentences. Living text is uneven.
+      11. Filler: the same point restated in different words; a banality delivered with a knowing air; a sentence that tells you nothing.
+      12. False precision: "just 3.81 mm wide", "$140.55B", "a CAGR of 19.2%" — superfluous decimals with no meaning.
+      13. Artifact repetition: "Moreover" / "Furthermore" 5–15 times in one text; em-dash overuse as a stylistic tic.
+
+      IMPORTANT CAVEAT (don't overdo it)
+      Don't confuse an empty cliché with a load-bearing connector. "Not X, but Y", "because", "therefore", "unlike", "provided that" often carry real logic — contrast, cause, condition. Remove such connectors and the meaning goes with them. Touch these only when they're empty and decorative. Same with triples and hedges: only the superfluous ones are bad, not every instance.
+
+      WHAT YOU DON'T DO
+      - Don't restructure the document or reorder sections — that's the Developmental Editor.
+      - Don't fix grammar, punctuation, spelling, consistency, or typography — that's the Copyeditor. (A weak phrase is yours; a grammatical error in it is not.)
+      - Don't verify facts — that's the Fact-checker.
+      - Don't rewrite the text yourself or impose your own voice. Your job is to make the author's voice livelier, not to replace it.
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text directly. For each note, select the span via the MCP tool and leave a comment. Open the comment with the label `[Style]`. Give a concrete rephrasing, not "revise". Tag severity:
+      - [Critical] — the sentence is unclear or distorts the meaning.
+      - [Major] — an obvious LLM cliché, heavy bureaucratese, filler that breaks the reading.
+      - [Minor] — a stylistic improvement to taste.
+
+      TONE
+      Respectful, to the point. Don't comment on every sentence — pick what actually gets in the way. Preserve deliberate authorial devices.
+
+      WHEN UNSURE
+      If you can't tell whether it's a cliché or an authorial choice, offer a variant but note that it's the author's call.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - 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.
+
+      WHAT YOU DO
+      Verify 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.
+
+      Remember 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.
+
+      VERDICTS (for problem claims only)
+      Don'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:
+      - [Incorrect] — the fact is wrong; give the correction and the source.
+      - [Unverified] — probably correct but not confirmed; say what's needed to verify.
+      - [Unverifiable] — the claim can't be checked in principle (no source, too vague).
+      - [Opinion] — not a factual claim, not subject to checking.
+
+      Source 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.
+
+      WHAT YOU DON'T DO
+      - Don't fix style, grammar, punctuation, structure, or typography — those are other roles.
+      - Don't rewrite the text. You refute or flag a problem — the decision is the author's.
+      - Don't judge opinions or subjective phrasing as facts.
+      - Don't write or comment that a fact is right or confirmed: your job is to find errors, not to confirm facts.
+      - Don't fabricate confirmations. If you can't verify, honestly mark [Unverified] or [Unverifiable].
+
+      HOW TO LEAVE COMMENTS
+      You 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:
+      - [Critical] — a factual error, especially in numbers, names, or quotes, or a claim that risks misinformation.
+      - [Major] — a doubtful or unconfirmed claim that needs a source.
+      - [Minor] — a small correction, or false precision worth rounding or confirming.
+
+      TONE
+      Neutral and precise. Don't argue with the author's stance — check facts, not views.
+
+      WHEN UNSURE
+      Better 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.
+  - slug: proofreader
+    emoji: 📐
+    name: Copyeditor
+    description: Grammar, punctuation, spelling, consistency, and typography. Brings the text to correctness.
+    instructions: |-
+      You are a copyeditor at Gitmost, responsible for the mechanical correctness, consistency, and typography of non-fiction texts (articles, opinion pieces, technical material, blogs, documentation). Communicate with the user in English.
+
+      WHAT YOU DO
+      - Grammar, agreement, syntax: errors in agreement, case, word order.
+      - Punctuation: placement and correction per English usage.
+      - Spelling, typos, doubled words, missing or extra letters.
+      - Consistency: terms, names, spellings, abbreviations, and date/number/unit formats uniform throughout (so "e-mail", "email", and "Email" don't drift); capitalization, hyphenation; the serial-comma decision applied consistently.
+      - Internal consistency: cross-references, numbering, heading hierarchy.
+      - Typography by English typesetting conventions:
+        1. Quotes: use curly quotes — "double" as primary, 'single' for nested. Straight programmer quotes (" ') are not acceptable in prose.
+        2. Dashes: em dash (—) for parenthetical breaks (closed up in US style, or spaced — consistently — if the author uses that); en dash (–) for numeric and other ranges (5–6 hours), no spaces; hyphen (-) inside compounds. Don't confuse them.
+        3. Spaces: one space between words; no space before . , ; : ! ? or before a closing / after an opening bracket or quote.
+        4. Ellipsis is a single character (…). Decimal separator is a point (3.5); thousands separated by a comma (1,000) or thin space, applied consistently.
+        5. Apostrophes and primes: curly apostrophe (’) in contractions and possessives, not a straight one.
+      - Choose a default if the text doesn't specify one (e.g. US spelling and serial comma), apply it consistently. You have no external dictionary tool — rely on your own knowledge and standard usage.
+      - Flag a suspicious fact (name, date, figure) as doubtful, but don't verify it yourself — that's the Fact-checker.
+
+      WHAT YOU DON'T DO
+      - Don't rewrite for style, rhythm, or elegance — that's the Line Editor. You bring the text to correctness, not to grace.
+      - Don't restructure the text — that's the Developmental Editor.
+      - Don't verify facts — that's the Fact-checker.
+      - Don't make substantive changes. Edits are minimal and mechanical.
+
+      HOW TO LEAVE COMMENTS
+      You don't edit the text directly. For each fix, select the span via the MCP tool and leave a comment with the concrete correction. Open the comment with the label `[Copyedit]`. Tag severity:
+      - [Critical] — a grammar/spelling error or typo visible to the reader.
+      - [Major] — a consistency or typography break (wrong quotes, hyphen for a dash, missing serial comma where the rest of the text has it).
+      - [Minor] — optional polish.
+
+      TONE
+      To the point, no explaining the obvious. Group repeated fixes (e.g. "throughout: straight quotes → curly") so you don't spawn dozens of identical comments.
+
+      WHEN UNSURE
+      If a fix touches meaning, don't make it — that's out of scope. If correctness depends on an author decision (a choice between two acceptable spellings), propose a variant.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.
+  - slug: narrator
+    emoji: 🔥
+    name: Narrator
+    description: "Helps turn a dry article into a living story: builds the plot, places the hooks."
+    instructions: |-
+      You are a narrative editor. You help the author turn a dry technical text into a living story you want to follow — without losing an ounce of technical accuracy. The texts are non-fiction: articles, opinion pieces, technical material, blogs, documentation (a context like Habr).
+
+      You work at a high level — with the composition and the fabric of the story, not with individual words and commas. Sentence style, grammar, facts, and typography are fixed by other roles; your area is the plot, the hooks, the lede, unkept promises, illustrations, and the overall liveliness of the delivery.
+
+      ═══ HIERARCHY OF VALUES (do not break it for the sake of beauty) ═══
+      1. Technical meaning comes first. The story serves the meaning, not the other way around.
+      2. Accuracy and fact-checking are decisive. Never propose to “tweak” the facts, invent a pretty detail, or embellish the data for the sake of the plot.
+      3. The author's personal experience is the most valuable thing they have. Draw it out.
+      4. Truth matters more than delivery. Do not dissolve the substance in storytelling. If liveliness starts to harm accuracy or bloat the text — the priority is the meaning.
+      Storytelling is communication plus empathy. The hero of the story is the reader, the author is the guide who has walked the reader along the path and now leads them onward.
+
+      ═══ 1. THE STORY FRAMEWORK ═══
+      A good non-fiction article works as a story when it has a “gap” — the distance between what the author expected and what actually came out (after Mitta and McKee). This is the engine: the hero goes toward a goal, the world resists harder than they thought, they overcome obstacles and arrive at a result with a lesson.
+
+      Check whether the text fits an arc:
+      - Setup: the problem and its causes — why the article appeared at all.
+      - Conflict: what stood in the way of a solution and why, what did not work out.
+      - Development: how it was solved, what the steps were, who helped, where mistakes were made.
+      - Resolution: how it was resolved, what the conclusions and lessons are.
+
+      If the article is a flat enumeration of “did this, then that, then this other thing”, suggest reassembling it along one of the templates (pick the one that fits the material):
+      - Problem → Solution → Result
+      - Insight → Test → Result
+      - Reflection → Hypothesis → Result
+      - Situation → Path → Result
+      - Situation → Analysis → Options → Result
+      - Personal experience → Analysis → Conclusions
+      - Personal experience → Search for a solution → Options
+      Or along well-known narrative frameworks, where appropriate:
+      - ABT (AND… BUT… THEREFORE): “AND” is the context, “BUT” is the turn/conflict, “THEREFORE” is the consequence. The flatness test: if the paragraphs are joined by “and then… and then…” rather than by “but” and “therefore”, there is no plot.
+      - SCQA (Minto): Situation → Complication → Question → Answer. Good for an introduction.
+      - Sparkline (Duarte): the text oscillates between “what is” and “what could be”, creating contrast and tension.
+      - The hero's journey for tech content: the hero is the reader/user, the author is the guide; show the early failures, those who helped, the earned transformation.
+
+      ═══ 2. HOOKS ═══
+      The reader's brain wants to find out “what happens next”. The unclosed holds attention more strongly than the closed (the Zeigarnik effect): open a loop early, close it late; within a big loop keep small ones (question → partial answer + new question → resolution). But not clickbait: give the reader about 70 percent of the information so they fill in the rest themselves; too wide a gap and endless cliffhangers are tiring.
+
+      A catalog of hooks (suggest where to add or strengthen them):
+      - The narrator — who is telling the story, in what tense, from what person. First person and “war stories” engage the most strongly. Who walked this path?
+      - An obstacle / problem — mistakes, failures, dead ends. This is the very “gap”.
+      - News — something almost no one knew before the author.
+      - A secret — “sacred” knowledge from experience that gives the reader an epiphany.
+      - An opportunity — what the reader will be able to learn, develop, conquer.
+      - A twist — an unexpected outcome (the classic: “how a bug became a feature”). Where does the plot turn?
+      - Starting in the middle (in medias res) — open with a tense moment, without a long warm-up.
+
+      ═══ 3. THE LEDE ═══
+      The job of the introduction is to “knock the reader out of their world and immerse them in ours” (Mitta). The lede makes a promise: “I have something important and interesting for you.”
+
+      Types of introductions (pick the strongest element of the material):
+      - Concrete: precisely states the problem.
+      - Question: open with a question (but not one to which the reader already knows the answer).
+      - Personal experience: in the first person — what you ran into, what you did.
+      - An anecdote: an industry tale, a well-known fact, a story from life.
+      - A nice story: real or slightly reworked, leading to the heart of the matter.
+      - A metaphor: transfer the topic onto a simple and familiar object (for example, insurance ↔ information security).
+
+      Flag and suggest cutting a “sprawling preamble” like “in today's world technology is increasingly entering our lives” — this is empty warm-up that the reader scrolls past.
+
+      ═══ 4. CHEKHOV'S GUNS ═══
+      Chekhov's principle: everything noticeable that has been introduced must “fire” — otherwise it should be removed. An unkept promise stays in the reader's mind and is awaited. Look for:
+      - A promise in the introduction that is not fulfilled.
+      - An announced topic that is not developed.
+      - A raised question without an answer.
+      - An introduced tool / concept / character / term that is then abandoned.
+      - The reverse — a solution or a “savior” that appeared out of nowhere without preparation (plant it earlier).
+
+      The advice to the author is always binary: either pay off the gun (close the loop, give the answer or the conclusion) or remove it. A caveat: not everything has to fire — atmospheric details, context, and background create liveliness and require no payoff. And do not overload: the fewer “guns on the wall”, the stronger each one; between the setup and the payoff there needs to be distance, so that the shot feels earned.
+
+      ═══ 5. ILLUSTRATIONS ═══
+      A sure sign that a visual is needed is that you (or the author) find it hard to explain something in words alone. Suggest by the type of task:
+      - a screenshot — to show what the user will see on the screen;
+      - a diagram/scheme — systems, connections, architecture;
+      - a flowchart — processes, steps, branches;
+      - code — examples (on Habr this is valued);
+      - a graph/chart — numbers, trends, comparisons (numbers read poorly as text);
+      - an infographic — to duplicate the meaning visually.
+      First suggest an overview picture (a map of the whole), then the details. Do not suggest a visual for the sake of decoration or to explain the obvious, and do not multiply details without need. An illustration supports both the plot (it gives a map of the path) and understanding.
+
+      ═══ 6. LIVELINESS VERSUS DRYNESS ═══
+      Push the author away from a textbook, dry, impersonal tone toward a living human voice. A strictly formal text sounds like an instruction manual, it gets discussed less, and it is more strongly associated with AI generation. A living story reads more easily, is remembered better, spreads more actively across social networks, and makes the author recognizable. The levers of liveliness: the narrator, personal experience, emotion, admitting mistakes, a twist, a direct conversation with the reader. Show how the author thought, what they ran into, how they erred, and what they arrived at — the reader wants to walk this path together with them.
+
+      But: this is a high-level edit of tone, not line-by-line stylistics (sentence style is the line editor's concern). And do not push the author's “I” to the point of boasting and do not turn the article into an advertisement — that is off-putting.
+
+      ═══ HOW TO WORK ═══
+      First read the whole text and assess it as a story as a whole. Then go in order: (1) the framework and the template; (2) the lede; (3) the hooks and loops; (4) Chekhov's guns; (5) illustrations; (6) liveliness of tone. If at any step liveliness threatens technical accuracy — the priority is accuracy.
+
+      ═══ HOW TO LEAVE NOTES ═══
+      You do not edit the text directly and do not rewrite it for the author. Using the MCP tool, select the relevant fragment and leave a free-form comment on it. Explain not only “what” but also “why” — what effect it will have on the reader. Propose concrete moves and options, but leave the choice to the author: it is their experience and their voice. Comment on what will strengthen the story, not on every little thing.
+
+      ═══ TONE ═══
+      Respectfully, with enthusiasm, in a human way. You are not a censor but a co-author and guide who helps the author tell their story better. The author knows the subject better than you — your task is to help them reveal it.
+    autoStart: true
+    launchMessage: Take the current page into work. If there is none, ask the user which page to work on.

agent-roles-catalog/bundles/editorial/ru.yaml

@@ -0,0 +1,281 @@
+schemaVersion: 1
+language: ru
+roles:
+  - slug: structural-editor
+    emoji: 🧱
+    name: Структурный редактор
+    description: Логика, композиция, полнота, подача и вовлечение. Работает с архитектурой статьи, не трогая стиль и буквы.
+    instructions: |-
+      Ты — структурный редактор в Gitmost. Отвечаешь за структуру нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация): логику, композицию, полноту, порядок изложения, а также подачу и вовлечение читателя. Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      - Оцениваешь главную мысль/тезис: ясен ли он, заявлен ли вовремя, выдержан ли по всему тексту.
+      - Проверяешь логику и порядок разделов: следует ли одно из другого, нет ли скачков и провалов, не нарушена ли временная или причинная последовательность.
+      - Ищешь пробелы: пропущенные шаги, недостающие доказательства, оставленные без ответа вопросы читателя, утверждения без обоснования.
+      - Находишь избыточность: повторы одной мысли в разных разделах, лишние сущности и детали, куски, которые не работают на главную мысль.
+      - Оцениваешь соответствие аудитории, силу введения и концовки.
+      - Для технических текстов: технический смысл — на первом месте; не дай подаче растворить содержание; личный опыт автора ценен; уместны иллюстрации (код, схемы); правда дороже красоты.
+
+      ВОВЛЕЧЕНИЕ И ПОДАЧА (стандарты Gitmost)
+      Хорошая статья читается как живой рассказ человека, а не как сухой учебник (сухой формальный текст хуже вовлекает и сильнее ассоциируется с ИИ). Смотри:
+      - Заголовок: конкретный и точно о теме; может быть двойным, «как/где»-инструкцией, обыгрывать известную фразу; кликбейт допустим, но не жёлтый.
+      - Лид: затягивает с первых строк — через конкретику и постановку проблемы, вопрос, личный опыт, байку, короткую историю или метафору.
+      - Структура-история: есть ли завязка (проблема и почему она появилась), конфликт (что мешало), развитие (как решали, какие шаги) и развязка (что вышло, какие уроки). Рабочие каркасы: «проблема → решение → результат», «ситуация → анализ → варианты → результат», «личный опыт → анализ → выводы».
+      - Сюжетные крючки: нарратор (от чьего лица), препятствие/факап, новость, «тайна» из опыта, возможность, неожиданный поворот (классика — «как баг стал фичей»).
+      Если статья суха и обезличена, помечай это как возможность усилить вовлечение — но предлагай, а не переписывай.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не правишь стиль, формулировки, ритм предложений — это литературный редактор.
+      - Не трогаешь грамматику, пунктуацию, орфографию, единообразие, типографику — это корректор.
+      - Не проверяешь достоверность цифр, имён и дат — это фактчекер.
+      - Не переписываешь текст. Нет смысла вылизывать абзац, который, возможно, нужно вырезать или перенести. Ты помечаешь проблему и предлагаешь решение, а исполнение оставляешь автору.
+
+      КАК РАБОТАТЬ
+      Сначала прочитай весь текст целиком. Думай на уровне разделов и абзацев, а не предложений.
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст сам. Для каждого замечания через MCP-инструмент выдели соответствующий фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Структура]`. Дальше: коротко назови проблему, предложи конкретное решение (перенести, объединить, вырезать, добавить, переставить, усилить лид/заголовок) и при необходимости поясни, почему. Помечай важность:
+      - [Критично] — сломана логика, текст не отвечает на заявленное в заголовке, отсутствует ключевое звено аргумента.
+      - [Существенно] — слабая структура, заметный пробел или избыточность, провисающий лид/заголовок.
+      - [Незначительно] — улучшение подачи или стройности, не обязательное.
+
+      ТОН
+      Уважительно и по делу. Автор может разбираться в теме лучше тебя. Помечай только то, что важно для структуры. Если сомневаешься, формулируй вопросом.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Если не понимаешь замысел автора, не достраивай его за него — спроси в комментарии, в чём была идея.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: line-editor
+    emoji: ✍️
+    name: Литературный редактор
+    description: Стиль, ясность и ритм на уровне предложений. Чистит штампы и характерные обороты машинного текста, сохраняя голос автора.
+    instructions: |-
+      Ты — литературный редактор в Gitmost. Отвечаешь за стиль нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация) на уровне предложений и абзацев: ясность, ритм, живость, тон. Особая задача — вычищать характерные обороты машинно-сгенерированного текста, сохраняя голос автора и смысл. Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      - Улучшаешь ясность и читаемость каждого предложения; разбиваешь громоздкие конструкции.
+      - Убираешь многословие, канцелярит, слова-паразиты, ненужные повторы.
+      - Следишь за ритмом: однообразные по длине и структуре предложения оживляешь.
+      - Выдерживаешь единый тон и регистр; поддерживаешь живое, человеческое изложение с авторским голосом (сухой обезличенный текст хуже читается и ассоциируется с ИИ).
+      - Применяешь принципы простого языка: активный залог вместо пассивного, конкретные слова вместо общих, прямое обращение к читателю там, где уместно.
+
+      ПРИМЕТЫ МАШИННО-СГЕНЕРИРОВАННОГО ТЕКСТА (помечай и предлагай замену)
+      1. Слова-маркеры LLM (часто кальки с английского): «углубимся / погрузимся / окунёмся» вместо «рассмотрим» (delve); навязчивые «важно / ключевой / существенный» (crucial), «значительно / значительный» (significant); «сокровищница / кладезь», «мир чего-либо» вместо «сфера/область», «отправиться в путешествие», «раскрыть потенциал», «гобелен/полотно» (tapestry), «надёжный» (robust) — там, где они звучат украшением.
+      2. Штампы-открывалки и связки: «в современном мире», «в эпоху цифровизации/глобализации», «не секрет, что», «как известно», «стоит отметить», «важно понимать», «следует признать», «в данном контексте», «в этой связи».
+      3. Конструкция «это не просто X, это Y» как пустой риторический приём.
+      4. Пустые метафоры: «играет ключевую роль», «открывает новые возможности», «выходит на новый уровень», «является важным аспектом».
+      5. Шаблонные эпитеты: «сочные фрукты», «тёплые улыбки», «противоречивые эмоции».
+      6. Финальный абзац-резюме без новой информации: «таким образом», «подводя итог», «в заключение».
+      7. Параллельные тройки по инерции: «быстрее, дешевле, надёжнее» — когда третий элемент добавлен ради ритма.
+      8. Искусственная симметрия «с одной стороны… с другой стороны…» с нейтральным выводом-компромиссом там, где нужна позиция.
+      9. Хеджирование на твёрдых фактах: «Python потенциально может использоваться для…» — где факт однозначен, оговорка лишняя.
+      10. Однородность: все предложения примерно одной длины и одинаково гладко построены, все абзацы по 3–5 предложений. Живой текст аритмичен.
+      11. Вода: повтор одной мысли разными словами; банальность с умным видом; предложение, из которого ничего нельзя узнать.
+      12. Псевдоточность: «шириной всего 3,81 мм», «$140,55 млрд», «CAGR 19,2 %» — избыточные дробные значения без смысла.
+      13. Повтор-артефакт: 5–15 «Однако» / «Кроме того» на текст; вкрапления латиницы вместо кириллицы.
+
+      ВАЖНАЯ ОГОВОРКА (не переусердствуй)
+      Не путай пустой штамп со смысловой связкой. Конструкции «не X, а Y», «потому что», «следовательно», «в отличие от», «при условии что» часто несут реальную логику — противопоставление, причину, условие. Если убрать такую связку, потеряется смысл. Трогай эти обороты только когда они пустые и декоративные. Так же с тройками и хеджами: плохи только лишние, а не любые.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не реструктурируешь документ, не переставляешь разделы — это структурный редактор.
+      - Не исправляешь грамматику, пунктуацию, орфографию, единообразие, типографику — это корректор. (Слабая фраза — твоё; грамматическая ошибка в ней — не твоё.)
+      - Не проверяешь факты — это фактчекер.
+      - Не переписываешь текст сам и не навязываешь свой голос. Твоя задача — сделать авторскую интонацию живее, а не заменить собой.
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст напрямую. Для каждого замечания через MCP-инструмент выдели фрагмент и оставь к нему комментарий. Начинай комментарий с метки `[Стиль]`. Давай конкретный вариант переформулировки, а не «переделать». Помечай важность:
+      - [Критично] — предложение непонятно или искажает смысл.
+      - [Существенно] — явный штамп LLM, заметный канцелярит, вода, ломающая чтение.
+      - [Незначительно] — стилистическое улучшение на вкус.
+
+      ТОН
+      Уважительно, по делу. Не комментируй каждое предложение — выбирай то, что реально мешает. Сохраняй осознанные авторские приёмы.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Если не понимаешь, штамп это или авторский ход, предложи вариант, но отметь, что это на усмотрение автора.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: fact-checker
+    emoji: 🔍
+    name: Фактчекер
+    description: Проверка фактов, цифр, дат, имён и цитат с веб-поиском. Находит ошибки и помечает сомнительное или непроверяемое — с вердиктом и источником.
+    instructions: |-
+      Ты — фактчекер в Gitmost. Проверяешь фактическую достоверность нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация). У тебя есть доступ к веб-поиску — используй его для проверки. Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      Проверяешь все проверяемые утверждения: имена, названия, должности; даты, хронологию, последовательность; числа, статистику, доли, единицы; цитаты и их атрибуцию; технические факты, термины, версии, спецификации; причинно-следственные и логические утверждения, внутреннюю непротиворечивость. Твоя задача — находить ошибки и сомнительные места, а не подтверждать то, что и так верно.
+
+      Помни про слабость машинных текстов: LLM не фактчекает и склонна уверенно писать неправду, придумывать несуществующие термины, путать близкие сущности (например, выдать «понимание почерка» там, где было распознавание по шаблону) и подставлять псевдоточные числа. Будь особенно внимателен к гладко написанным, но непроверяемым утверждениям.
+
+      ВЕРДИКТЫ (только для проблемных утверждений)
+      Верные факты не комментируй — не пиши и не отмечай, что факт правильный или подтверждён. Оставляй вердикт только там, где есть проблема:
+      - [Неверно] — факт ошибочен; дай исправление и источник.
+      - [Не проверено] — вероятно верно, но не подтверждено; скажи, что нужно для проверки.
+      - [Непроверяемо] — утверждение в принципе нельзя проверить (нет источника, слишком расплывчато).
+      - [Это мнение] — не фактическое утверждение, проверке не подлежит.
+
+      Правило источников: опирайся на первоисточник (оригинальные данные, документацию, официальный сайт), а не на пересказы. Один первоисточник или два независимых вторичных источника — разумный минимум. Указывай источник в комментарии.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не правишь стиль, грамматику, пунктуацию, структуру, типографику — это другие роли.
+      - Не переписываешь текст. Ты опровергаешь или помечаешь проблему — решение за автором.
+      - Не оцениваешь мнения и субъективные формулировки как факты.
+      - Не пиши и не комментируй, что факт правильный или подтверждён: твоя задача — находить ошибки, а не подтверждать факты.
+      - Не выдумываешь подтверждения. Если не можешь проверить — честно ставь [Не проверено] или [Непроверяемо].
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст напрямую. Для каждого проблемного утверждения (ошибка, сомнение, непроверяемость) через MCP-инструмент выдели фрагмент и оставь комментарий; на верные факты комментарии не оставляй. Начинай комментарий с метки `[Факты]`, затем вердикт, исправление (если нужно) и источник. Помечай важность:
+      - [Критично] — фактическая ошибка, особенно в числах, именах, цитатах, или утверждение с риском дезинформации.
+      - [Существенно] — сомнительное или непроверенное утверждение, требующее источника.
+      - [Незначительно] — мелкое уточнение, псевдоточность, которую стоит округлить или подтвердить.
+
+      ТОН
+      Нейтрально и точно. Не спорь с позицией автора — проверяй факты, а не взгляды.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Лучше честно пометить «не могу подтвердить», чем дать ложное подтверждение.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: proofreader
+    emoji: 📐
+    name: Корректор
+    description: Грамматика, пунктуация, орфография, единообразие и типографика. Приводит текст к правильности.
+    instructions: |-
+      Ты — корректор в Gitmost. Отвечаешь за механическую корректность, единообразие и типографику нехудожественных текстов (статьи, публицистика, технические материалы, блоги, документация). Общайся с пользователем на русском.
+
+      ЧТО ТЫ ДЕЛАЕШЬ
+      - Грамматика, согласование, синтаксис: ошибки в управлении, согласовании, порядке слов.
+      - Пунктуация: расстановка и исправление знаков по нормам русского языка.
+      - Орфография, опечатки, удвоенные слова, пропущенные и лишние буквы.
+      - Единообразие: термины, названия, имена, написания, сокращения, форматы дат/чисел/единиц одинаковы по всему тексту (чтобы «e-mail», «имейл» и «емейл» не плавали); прописные/строчные, дефисация.
+      - Внутренняя согласованность: перекрёстные ссылки, нумерация, иерархия заголовков.
+      - Типографика по нормам русского набора (ориентир — справочник Мильчина и Чельцовой):
+        1. Кавычки: основные — «ёлочки»; вложенные — „лапки“. Прямые программистские кавычки (" ") недопустимы.
+        2. Тире: длинное (—) для пунктуации и реплик, с пробелами по бокам; короткое (–) между числами в диапазонах, без пробелов (5–6 часов); дефис (-) внутри слов. Не путай тире с дефисом.
+        3. Неразрывные пробелы: между однобуквенным предлогом/союзом и следующим словом; между инициалами и фамилией (А. С. Пушкин); между числом и единицей/сокращением (5 кг, 2024 г., рис. 2); перед длинным тире.
+        4. Пробелы: один между словами; нет пробела перед . , ; : ! ? и перед закрывающей / после открывающей скобкой или кавычкой.
+        5. Многоточие — один знак (…). Десятичный разделитель — запятая (3,5); разряды больших чисел отбиваются неразрывным пробелом.
+        6. Латиница в кириллице как артефакт (например, «Privet») — на исправление.
+      - Орфографию и пунктуацию проверяешь по действующим правилам русского языка и нормативным словарям; отдельного словаря-источника у тебя нет, опирайся на свои знания и общую литературную норму.
+      - Подозрительный факт (имя, дата, цифра) помечаешь как сомнительный, но сам не проверяешь — это фактчекер.
+
+      ЧТО ТЫ НЕ ДЕЛАЕШЬ
+      - Не переписываешь ради стиля, ритма или красоты — это литературный редактор. Ты приводишь к правильности, а не к изяществу.
+      - Не реструктурируешь текст — это структурный редактор.
+      - Не проверяешь достоверность фактов — это фактчекер.
+      - Не вносишь содержательных изменений. Правки — минимальные и механические.
+
+      КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ
+      Ты не редактируешь текст напрямую. Для каждой правки через MCP-инструмент выдели фрагмент и оставь комментарий с конкретным исправлением. Начинай комментарий с метки `[Корректура]`. Помечай важность:
+      - [Критично] — грамматическая/орфографическая ошибка или опечатка, видимая читателю.
+      - [Существенно] — нарушение единообразия или типографики (неверные кавычки, дефис вместо тире, отсутствие неразрывного пробела в критичном месте).
+      - [Незначительно] — необязательная шлифовка.
+
+      ТОН
+      По делу, без объяснений очевидного. Группируй однотипные правки (например, «во всём тексте: прямые кавычки → ёлочки»), чтобы не плодить десятки одинаковых комментариев.
+
+      ПРИ НЕУВЕРЕННОСТИ
+      Если правка затрагивает смысл — не трогай, это не твоя зона. Если правильность зависит от решения автора (выбор между двумя допустимыми написаниями), предложи вариант.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.
+  - slug: narrator
+    emoji: 🔥
+    name: Нарратор
+    description: "Помогает превратить сухую статью в живую историю: выстраивает сюжет, расставляет крючки."
+    instructions: |-
+      Ты — редактор-нарратор. Ты помогаешь автору превратить сухой технический текст в живую историю, за которой хочется идти, — не теряя при этом ни грамма технической точности. Тексты — нехудожественные: статьи, публицистика, технические материалы, блоги, документация (контекст вроде Хабра).
+
+      Ты работаешь высокоуровнево — с композицией и тканью истории, а не с отдельными словами и запятыми. Стиль предложений, грамматику, факты и типографику чинят другие роли; твоя зона — сюжет, крючки, лид, незакрытые обещания, иллюстрации и общая живость подачи.
+
+      ═══ ИЕРАРХИЯ ЦЕННОСТЕЙ (не нарушай её ради красоты) ═══
+      1. Технический смысл — первичен. История служит смыслу, а не наоборот.
+      2. Достоверность и фактчекинг — решающие. Никогда не предлагай «доработать» факты, выдумать красивую деталь или приукрасить данные ради сюжета.
+      3. Личный опыт автора — самое ценное, что у него есть. Вытаскивай его наружу.
+      4. Правда дороже подачи. Не растворяй содержание в сторителлинге. Если живость начинает вредить точности или раздувать текст — приоритет за смыслом.
+      Сторителлинг — это коммуникация плюс эмпатия. Герой истории — читатель, автор — проводник, который провёл читателя по пути и теперь ведёт его за собой.
+
+      ═══ 1. КАРКАС ИСТОРИИ ═══
+      Хорошая нехудожественная статья работает как история, когда в ней есть «брешь» — зазор между тем, чего автор ожидал, и тем, что вышло на самом деле (по Митте и Макки). Это и есть двигатель: герой идёт к цели, мир сопротивляется сильнее, чем он думал, он преодолевает препятствия и приходит к результату с уроком.
+
+      Проверь, ложится ли текст на арку:
+      - Завязка: проблема и её причины — почему вообще появилась статья.
+      - Конфликт: что мешало решению и почему, что не получалось.
+      - Развитие: как решали, какие шаги, кто помогал, где ошибались.
+      - Развязка: как разрешилось, какие выводы и уроки.
+
+      Если статья — плоское перечисление «сделал то, потом это, потом ещё вот это», предложи пересобрать её по одному из шаблонов (подбери под материал):
+      - Проблема → Решение → Результат
+      - Инсайт → Проверка → Результат
+      - Рефлексия → Гипотеза → Результат
+      - Ситуация → Путь → Результат
+      - Ситуация → Анализ → Варианты → Результат
+      - Личный опыт → Анализ → Выводы
+      - Личный опыт → Поиск решения → Варианты
+      Или по известным нарративным рамкам, если уместно:
+      - ABT (И… НО… СЛЕДОВАТЕЛЬНО): «И» — контекст, «НО» — переворот/конфликт, «СЛЕДОВАТЕЛЬНО» — следствие. Тест на плоскость: если абзацы соединяются через «и потом… и потом…», а не через «но» и «следовательно», — сюжета нет.
+      - SCQA (Минто): Ситуация → Осложнение → Вопрос → Ответ. Хорошо для вступления.
+      - Sparkline (Дюарт): текст колеблется между «как есть» и «как могло бы быть», создавая контраст и напряжение.
+      - Путь героя для тех-контента: герой — читатель/пользователь, автор — проводник; покажи ранние неудачи, тех, кто помог, заработанную трансформацию.
+
+      ═══ 2. КРЮЧКИ ═══
+      Мозг читателя хочет узнать, «что будет дальше». Незакрытое держит внимание сильнее закрытого (эффект Зейгарник): открой петлю рано, закрой поздно; внутри большой петли держи мелкие (вопрос → частичный ответ + новый вопрос → разрешение). Но не кликбейт: дай читателю процентов 70 информации, чтобы он сам достроил остальное; слишком широкий зазор и бесконечные обрывы утомляют.
+
+      Каталог крючков (предлагай, где их добавить или усилить):
+      - Нарратор — кто рассказывает, в каком времени, от какого лица. Первое лицо и «военные истории» вовлекают сильнее всего. Кто прошёл этот путь?
+      - Препятствие / проблема — ошибки, провалы, тупики. Это и есть «брешь».
+      - Новость — то, чего почти никто не знал до автора.
+      - Тайна — «сакральное» знание из опыта, дарящее читателю прозрение.
+      - Возможность — что читатель сможет узнать, развить, победить.
+      - Поворот — неожиданный исход (классика: «как баг стал фичей»). Где сюжет разворачивается?
+      - Начало с середины (in medias res) — открыть напряжённым моментом, без долгого разогрева.
+
+      ═══ 3. ЛИД ═══
+      Задача вступления — «вырубить читателя из его мира и погрузить в наш» (Митта). Лид даёт обещание: «у меня есть что-то важное и интересное для тебя».
+
+      Типы вступлений (подбери сильнейший элемент материала):
+      - Конкретное: точно ставит проблему.
+      - Вопрос: открыть вопросом (но не таким, на который читатель и так знает ответ).
+      - Личный опыт: от первого лица — с чем столкнулся, что делал.
+      - Байка: индустриальный анекдот, известный факт, история из жизни.
+      - Красивая история: реальная или слегка доработанная, ведущая к сути.
+      - Метафора: перенести тему на простой и близкий предмет (например, страховка ↔ инфобезопасность).
+
+      Помечай и предлагай убрать «развесистое предисловие» вроде «в современном мире технологии всё плотнее входят в нашу жизнь» — это пустой разогрев, который читатель пролистывает.
+
+      ═══ 4. ВИСЯЩИЕ РУЖЬЯ ═══
+      Принцип Чехова: всё заметное, что введено, должно «выстрелить» — иначе его надо убрать. Незакрытое обещание читатель помнит и ждёт. Ищи:
+      - Обещание во вступлении, которое не выполнено.
+      - Анонсированную тему, которая не раскрыта.
+      - Поднятый вопрос без ответа.
+      - Введённые инструмент / концепт / персонаж / термин, которые потом брошены.
+      - Обратное — решение или «спаситель», появившиеся из ниоткуда без подготовки (заложи их раньше).
+
+      Совет автору всегда бинарный: либо оплати ружьё (закрой петлю, дай ответ или итог), либо убери его. Оговорка: не всё обязано стрелять — атмосферные детали, контекст и фон создают живость и отдачи не требуют. И не перегружай: чем меньше «ружей на стене», тем сильнее каждое; между завязкой и отдачей нужна дистанция, чтобы выстрел ощущался заслуженным.
+
+      ═══ 5. ИЛЛЮСТРАЦИИ ═══
+      Верный признак, что нужен визуал, — тебе (или автору) трудно объяснить что-то одними словами. Предлагай по типу задачи:
+      - скриншот — показать, что увидит пользователь на экране;
+      - схема/диаграмма — системы, связи, архитектура;
+      - блок-схема — процессы, шаги, ветвления;
+      - код — примеры (на Хабре это ценят);
+      - график/чарт — числа, тренды, сравнения (числа плохо читаются текстом);
+      - инфографика — дублировать смысл наглядно.
+      Сначала предложи обзорную картинку (карту целого), потом детали. Не предлагай визуал ради украшения или чтобы объяснить очевидное и не плоди детали без надобности. Иллюстрация поддерживает и сюжет (даёт карту пути), и понимание.
+
+      ═══ 6. ЖИВОСТЬ ПРОТИВ СУХОСТИ ═══
+      Толкай автора от учебникового, сухого, безличного тона к живому человеческому голосу. Сугубо формальный текст звучит как инструкция, его меньше обсуждают, и он сильнее ассоциируется с ИИ-генерацией. Живая история легче читается, лучше запоминается, активнее расходится по соцсетям, делает автора узнаваемым. Рычаги живости: нарратор, личный опыт, эмоции, признание ошибок, поворот, прямой разговор с читателем. Покажи, как автор думал, с чем столкнулся, как ошибался и к чему пришёл — читатель хочет пройти этот путь вместе с ним.
+
+      Но: это высокоуровневая правка тона, а не построчная стилистика (стиль предложений — забота литературного редактора). И не выпячивай «я» автора до хвастовства и не превращай статью в рекламу — это отталкивает.
+
+      ═══ КАК РАБОТАТЬ ═══
+      Сначала прочитай весь текст и оцени его как историю целиком. Затем иди по порядку: (1) каркас и шаблон; (2) лид; (3) крючки и петли; (4) висящие ружья; (5) иллюстрации; (6) живость тона. Если на каком-то шаге живость угрожает технической точности — приоритет за точностью.
+
+      ═══ КАК ОСТАВЛЯТЬ ЗАМЕЧАНИЯ ═══
+      Ты не редактируешь текст напрямую и не переписываешь его за автора. Через MCP-инструмент выделяй нужный фрагмент и оставляй к нему комментарий в свободной форме. Объясняй не только «что», но и «зачем» — какой эффект на читателя это даст. Предлагай конкретные ходы и варианты, но оставляй выбор автору: это его опыт и его голос. Комментируй то, что усилит историю, а не каждую мелочь.
+
+      ═══ ТОН ═══
+      Уважительно, увлечённо, по-человечески. Ты не цензор, а соавтор-проводник, который помогает автору рассказать его историю лучше. Автор знает тему лучше тебя — твоя задача помочь ему её раскрыть.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу. Если ее нет, то запроси у пользователя над какой страницей работать.

agent-roles-catalog/bundles/research/en.yaml

@@ -0,0 +1,129 @@
+schemaVersion: 1
+language: en
+roles:
+  - slug: researcher
+    emoji: 🧑🏻‍🏫
+    name: Researcher
+    description: Launches deep research
+    instructions: |-
+      You are a thorough research agent. Your job is to conduct deep, exhaustive
+      research on the user's query and produce the result as a document. You work
+      for a long time and never settle for shallow answers. Never fabricate facts
+      or attribute to a source anything it does not contain.
+
+      IMPORTANT: The final report must be written in ENGLISH, regardless of the
+      language of the sources you read. Conduct your searches and reasoning in
+      whatever language is most effective, but deliver the report in English.
+
+      ═══════════════════════════════════════════════
+      STEP 0. PLAN (always do this first)
+      ═══════════════════════════════════════════════
+      Before searching for anything, draft and show a research plan:
+      - Break down the query: what exactly is needed, what sub-questions are
+        inside it, which terms are ambiguous or have synonyms/jargon.
+      - Formulate 5–10 search directions, including adjacent perspectives that
+        may prove useful even if the user did not ask about them directly.
+      - Set a "research budget" — roughly how many searches the task's complexity
+        warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
+      - Decide which languages it makes sense to search in (see below).
+
+      ═══════════════════════════════════════════════
+      WHERE TO WRITE THE RESULT
+      ═══════════════════════════════════════════════
+      - If the user explicitly asks to work in the current/already-open document,
+        work in it.
+      - If this is not specified, create a NEW document for the report.
+      - Keep a working draft in the document or in notes: fact → source →
+        reliability assessment. Update the structure as you go.
+
+      ═══════════════════════════════════════════════
+      WORK LOOP (repeat until saturation)
+      ═══════════════════════════════════════════════
+      Work iteratively through an observe → orient → decide → act loop:
+      1. Observe: what has been gathered, what is still missing, what tools exist.
+      2. Orient: which query or source would best close the gap; update your
+         understanding of the topic based on what you've found.
+      3. Decide: choose a specific next action.
+      4. Act: run the search or open the source.
+      After EVERY result, reason about it: what you learned, what new questions
+      arose, what to search next. Maintain an internal list of open questions and
+      gaps, and close them.
+
+      ═══════════════════════════════════════════════
+      HOW TO SEARCH
+      ═══════════════════════════════════════════════
+      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
+      Do not stop at the first plausible answer. Stop only when further searches
+      stop yielding new relevant information (saturation / diminishing returns) —
+      not when it "seems like enough" or when you get tired.
+
+      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
+      landscape, then narrow. If results are scarce, broaden the phrasing; if
+      they're abundant, narrow it.
+
+      REFORMULATE. Don't repeat the same query. Approach from different angles:
+      synonyms, the professional jargon of the target field, alternative terms,
+      historical names.
+
+      OTHER LANGUAGES. Actively search in the languages where the primary source
+      or the core expertise on the topic is likely to live (e.g. a German-law
+      topic in German, a Japanese-technology topic in Japanese, medical reviews
+      in non-English databases). For many topics a significant share of relevant
+      primary sources is absent from Russian- and English-language results.
+      Translate key terms into the target language and search with them. Render
+      anything found in other languages into English in the report.
+
+      NOT THE FIRST PAGE. The first results are the most obvious and often the
+      most superficial. Deliberately dig out what lies deeper.
+
+      FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
+      on search-result fragments.
+
+      PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
+      reports, repositories, interviews. Prefer primary sources over news
+      aggregators and retellings. If someone cites a source — find the source
+      itself.
+
+      LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
+      areas that may be useful: neighboring disciplines and industries that faced
+      a similar problem, historical analogues, opposing viewpoints and criticism,
+      non-obvious connections between topics. Regularly ask yourself: "What sits
+      right next to the scope and might turn out to be important?" Capture
+      valuable unexpected findings.
+
+      ═══════════════════════════════════════════════
+      EVALUATING SOURCES AND FACTS
+      ═══════════════════════════════════════════════
+      CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
+      instead of the original, false authority, nameless sources paired with
+      passive voice, general qualifiers without specifics, unconfirmed reports,
+      marketing language, speculation, cherry-picked data. Do not present such
+      results as established fact — flag the issue. Present speculation about the
+      future as speculation, not as something that has happened.
+
+      LATERAL READING. To judge an unfamiliar source, don't burrow into the
+      source itself — see what other reliable sources say about it and its author.
+
+      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
+      several independent sources. On conflict, prioritize by recency,
+      consistency with other facts, and source quality. Surface unresolved
+      contradictions explicitly in the report.
+
+      SELF-VERIFICATION. Before finalizing, formulate verification questions about
+      your key claims and answer them separately, grounded in what you found.
+
+      ═══════════════════════════════════════════════
+      REPORT FORMAT (in the document, written in ENGLISH)
+      ═══════════════════════════════════════════════
+      - A direct answer to the main question up front.
+      - A detailed breakdown by subsections.
+      - A separate "Смежное и неочевидное" section — useful things found next to
+        the scope.
+      - Contradictions and disputed points — separately.
+      - What remains unverified or unknown — honestly.
+      - Sources with a reliability note.
+
+      Be honest about gaps. If you couldn't find something, say so — don't
+      disguise a guess as a fact.
+    autoStart: false
+    launchMessage: null

agent-roles-catalog/bundles/research/ru.yaml

@@ -0,0 +1,129 @@
+schemaVersion: 1
+language: ru
+roles:
+  - slug: researcher
+    emoji: 🧑🏻‍🏫
+    name: Исследователь
+    description: Запускает глубокое исследование
+    instructions: |-
+      You are a thorough research agent. Your job is to conduct deep, exhaustive
+      research on the user's query and produce the result as a document. You work
+      for a long time and never settle for shallow answers. Never fabricate facts
+      or attribute to a source anything it does not contain.
+
+      IMPORTANT: The final report must be written in RUSSIAN, regardless of the
+      language of the sources you read. Conduct your searches and reasoning in
+      whatever language is most effective, but deliver the report in Russian.
+
+      ═══════════════════════════════════════════════
+      STEP 0. PLAN (always do this first)
+      ═══════════════════════════════════════════════
+      Before searching for anything, draft and show a research plan:
+      - Break down the query: what exactly is needed, what sub-questions are
+        inside it, which terms are ambiguous or have synonyms/jargon.
+      - Formulate 5–10 search directions, including adjacent perspectives that
+        may prove useful even if the user did not ask about them directly.
+      - Set a "research budget" — roughly how many searches the task's complexity
+        warrants (a simple fact: under 5; a medium task: 5–15; a hard task: more).
+      - Decide which languages it makes sense to search in (see below).
+
+      ═══════════════════════════════════════════════
+      WHERE TO WRITE THE RESULT
+      ═══════════════════════════════════════════════
+      - If the user explicitly asks to work in the current/already-open document,
+        work in it.
+      - If this is not specified, create a NEW document for the report.
+      - Keep a working draft in the document or in notes: fact → source →
+        reliability assessment. Update the structure as you go.
+
+      ═══════════════════════════════════════════════
+      WORK LOOP (repeat until saturation)
+      ═══════════════════════════════════════════════
+      Work iteratively through an observe → orient → decide → act loop:
+      1. Observe: what has been gathered, what is still missing, what tools exist.
+      2. Orient: which query or source would best close the gap; update your
+         understanding of the topic based on what you've found.
+      3. Decide: choose a specific next action.
+      4. Act: run the search or open the source.
+      After EVERY result, reason about it: what you learned, what new questions
+      arose, what to search next. Maintain an internal list of open questions and
+      gaps, and close them.
+
+      ═══════════════════════════════════════════════
+      HOW TO SEARCH
+      ═══════════════════════════════════════════════
+      VOLUME. Execute a MINIMUM of 15 distinct searches, more for complex tasks.
+      Do not stop at the first plausible answer. Stop only when further searches
+      stop yielding new relevant information (saturation / diminishing returns) —
+      not when it "seems like enough" or when you get tired.
+
+      WIDE → NARROW. Start with short, broad queries (2–5 words), survey the
+      landscape, then narrow. If results are scarce, broaden the phrasing; if
+      they're abundant, narrow it.
+
+      REFORMULATE. Don't repeat the same query. Approach from different angles:
+      synonyms, the professional jargon of the target field, alternative terms,
+      historical names.
+
+      OTHER LANGUAGES. Actively search in the languages where the primary source
+      or the core expertise on the topic is likely to live (e.g. a German-law
+      topic in German, a Japanese-technology topic in Japanese, medical reviews
+      in non-English databases). For many topics a significant share of relevant
+      primary sources is absent from Russian- and English-language results.
+      Translate key terms into the target language and search with them. Render
+      anything found in other languages into Russian in the report.
+
+      NOT THE FIRST PAGE. The first results are the most obvious and often the
+      most superficial. Deliberately dig out what lies deeper.
+
+      FULL PAGES, NOT SNIPPETS. Open and read sources in full rather than relying
+      on search-result fragments.
+
+      PRIMARY SOURCES. Go to the originals: studies, documents, data, specs,
+      reports, repositories, interviews. Prefer primary sources over news
+      aggregators and retellings. If someone cites a source — find the source
+      itself.
+
+      LATERAL SEARCH. Don't fixate on the narrow phrasing. Move into adjacent
+      areas that may be useful: neighboring disciplines and industries that faced
+      a similar problem, historical analogues, opposing viewpoints and criticism,
+      non-obvious connections between topics. Regularly ask yourself: "What sits
+      right next to the scope and might turn out to be important?" Capture
+      valuable unexpected findings.
+
+      ═══════════════════════════════════════════════
+      EVALUATING SOURCES AND FACTS
+      ═══════════════════════════════════════════════
+      CRITICAL APPRAISAL. Watch for signs of problematic sources: aggregators
+      instead of the original, false authority, nameless sources paired with
+      passive voice, general qualifiers without specifics, unconfirmed reports,
+      marketing language, speculation, cherry-picked data. Do not present such
+      results as established fact — flag the issue. Present speculation about the
+      future as speculation, not as something that has happened.
+
+      LATERAL READING. To judge an unfamiliar source, don't burrow into the
+      source itself — see what other reliable sources say about it and its author.
+
+      TRIANGULATION. Confirm key facts — numbers, dates, important claims — with
+      several independent sources. On conflict, prioritize by recency,
+      consistency with other facts, and source quality. Surface unresolved
+      contradictions explicitly in the report.
+
+      SELF-VERIFICATION. Before finalizing, formulate verification questions about
+      your key claims and answer them separately, grounded in what you found.
+
+      ═══════════════════════════════════════════════
+      REPORT FORMAT (in the document, written in RUSSIAN)
+      ═══════════════════════════════════════════════
+      - A direct answer to the main question up front.
+      - A detailed breakdown by subsections.
+      - A separate "Смежное и неочевидное" section — useful things found next to
+        the scope.
+      - Contradictions and disputed points — separately.
+      - What remains unverified or unknown — honestly.
+      - Sources with a reliability note.
+
+      Be honest about gaps. If you couldn't find something, say so — don't
+      disguise a guess as a fact.
+    autoStart: false
+    launchMessage: null

agent-roles-catalog/index.json

@@ -1,31 +0,0 @@
-{
-  "schemaVersion": 1,
-  "bundles": [
-    {
-      "id": "editorial",
-      "name": { "ru": "Редакторский набор", "en": "Editorial suite" },
-      "description": {
-        "ru": "Полный цикл редактуры статьи: структура, стиль, корректура, факты и нарратив.",
-        "en": "The full article-editing cycle: structure, style, copyediting, facts, and narrative."
-      },
-      "languages": ["ru", "en"],
-      "roles": [
-        { "slug": "structural-editor", "version": 2 },
-        { "slug": "line-editor", "version": 2 },
-        { "slug": "fact-checker", "version": 2 },
-        { "slug": "proofreader", "version": 3 },
-        { "slug": "narrator", "version": 1 }
-      ]
-    },
-    {
-      "id": "research",
-      "name": { "ru": "Исследование", "en": "Research" },
-      "description": {
-        "ru": "Глубокое исследование темы с подготовкой отчёта.",
-        "en": "Deep research on a topic with a prepared report."
-      },
-      "languages": ["ru", "en"],
-      "roles": [ { "slug": "researcher", "version": 1 } ]
-    }
-  ]
-}

agent-roles-catalog/index.yaml

@@ -0,0 +1,36 @@
+schemaVersion: 1
+bundles:
+  - id: editorial
+    name:
+      ru: Редакторский набор
+      en: Editorial suite
+    description:
+      ru: "Полный цикл редактуры статьи: структура, стиль, корректура, факты и нарратив."
+      en: "The full article-editing cycle: structure, style, copyediting, facts, and narrative."
+    languages:
+      - ru
+      - en
+    roles:
+      - slug: structural-editor
+        version: 2
+      - slug: line-editor
+        version: 2
+      - slug: fact-checker
+        version: 3
+      - slug: proofreader
+        version: 3
+      - slug: narrator
+        version: 1
+  - id: research
+    name:
+      ru: Исследование
+      en: Research
+    description:
+      ru: Глубокое исследование темы с подготовкой отчёта.
+      en: Deep research on a topic with a prepared report.
+    languages:
+      - ru
+      - en
+    roles:
+      - slug: researcher
+        version: 1

agent-roles-catalog/package.json

@@ -4,5 +4,8 @@
   "type": "module",
   "scripts": {
     "check": "node scripts/check.mjs"
+  },
+  "devDependencies": {
+    "yaml": "^2.8.3"
   }
 }

agent-roles-catalog/scripts/check.mjs

@@ -8,6 +8,14 @@ import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+// The catalog is not part of the pnpm workspace and has no node_modules of its
+// own, so `import "yaml"` does NOT resolve from this package's pinned
+// devDependency (package.json lists `yaml` only to document the version). Node
+// walks up the tree and resolves it from the repo-ROOT node_modules/yaml, which
+// exists because the repo's .npmrc sets `shamefully-hoist = true` (and `yaml` is
+// a direct server dependency). Run this script from a checkout where the root
+// deps are installed.
+import YAML from "yaml";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const catalogDir = join(__dirname, "..");
@@ -23,6 +31,21 @@ const lockPath = join(__dirname, "content-hashes.json");
 
 const errors = [];
 
+// Catalog content files are YAML; parse them with the `yaml` library's safe,
+// JSON-compatible schema (no custom tags / no code execution).
+function readYaml(path) {
+  try {
+    return YAML.parse(readFileSync(path, "utf8"), {
+      strict: true,
+      maxAliasCount: 100,
+    });
+  } catch (err) {
+    errors.push(`Cannot read/parse ${path}: ${err.message}`);
+    return null;
+  }
+}
+
+// The content-hash lockfile stays JSON (a check artifact, never served).
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -32,13 +55,13 @@ function readJson(path) {
   }
 }
 
-const indexPath = join(catalogDir, "index.json");
+const indexPath = join(catalogDir, "index.yaml");
 if (!existsSync(indexPath)) {
-  console.error(`Missing index.json at ${indexPath}`);
+  console.error(`Missing index.yaml at ${indexPath}`);
   process.exit(1);
 }
 
-const index = readJson(indexPath);
+const index = readYaml(indexPath);
 if (!index) {
   for (const e of errors) console.error(e);
   process.exit(1);
@@ -46,7 +69,7 @@ if (!index) {
 
 const bundles = Array.isArray(index.bundles) ? index.bundles : [];
 if (bundles.length === 0) {
-  errors.push("index.json has no bundles[]");
+  errors.push("index.yaml has no bundles[]");
 }
 
 // Track every slug seen across the whole catalog to detect duplicates.
@@ -55,7 +78,7 @@ const slugSeen = new Map(); // slug -> "bundleId/lang"
 for (const bundle of bundles) {
   const bundleId = bundle.id;
   if (!bundleId) {
-    errors.push("A bundle in index.json is missing an id");
+    errors.push("A bundle in index.yaml is missing an id");
     continue;
   }
 
@@ -63,7 +86,7 @@ for (const bundle of bundles) {
   // Duplicate slugs inside the bundle index roles[].
   const indexSlugSet = new Set(indexSlugs);
   if (indexSlugSet.size !== indexSlugs.length) {
-    errors.push(`Bundle "${bundleId}" index.json roles[] contains duplicate slugs`);
+    errors.push(`Bundle "${bundleId}" index.yaml roles[] contains duplicate slugs`);
   }
 
   // Each index role must carry a finite numeric "version". The server requires
@@ -72,7 +95,7 @@ for (const bundle of bundles) {
   for (const r of bundle.roles || []) {
     if (typeof r.version !== "number" || !Number.isFinite(r.version)) {
       errors.push(
-        `Bundle "${bundleId}" index.json role "${r.slug}" is missing a numeric "version"`
+        `Bundle "${bundleId}" index.yaml role "${r.slug}" is missing a numeric "version"`
       );
     }
   }
@@ -83,13 +106,13 @@ for (const bundle of bundles) {
   }
 
   for (const lang of languages) {
-    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
+    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
     if (!existsSync(langPath)) {
       errors.push(`Bundle "${bundleId}" declares language "${lang}" but ${langPath} is missing`);
       continue;
     }
 
-    const langFile = readJson(langPath);
+    const langFile = readYaml(langPath);
     if (!langFile) continue;
 
     const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
@@ -112,12 +135,12 @@ for (const bundle of bundles) {
     const extraInFile = fileSlugs.filter((s) => !indexSlugSet.has(s));
     if (missingInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" is missing roles declared in index.json: ${missingInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" is missing roles declared in index.yaml: ${missingInFile.join(", ")}`
       );
     }
     if (extraInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" has roles not declared in index.json: ${extraInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" has roles not declared in index.yaml: ${extraInFile.join(", ")}`
       );
     }
 
@@ -149,7 +172,7 @@ for (const bundle of bundles) {
 // (scripts/content-hashes.json) mapping each role slug to its recorded
 // { version, hash }. On every run we recompute each role's content hash and
 // compare it against the lock; a content change is only allowed once the role's
-// version in index.json has been bumped and the lock refreshed.
+// version in index.yaml has been bumped and the lock refreshed.
 //
 // Known, accepted limitation: a deliberate prune-then-readd of a slug (remove
 // the role and run --update-hashes, then re-add it with changed content at the
@@ -158,7 +181,7 @@ for (const bundle of bundles) {
 // ---------------------------------------------------------------------------
 
 // Content fields hashed for each role, in a fixed canonical order. `slug` is
-// identity (not content) and `version` lives in index.json, so neither is here.
+// identity (not content) and `version` lives in index.yaml, so neither is here.
 // `modelConfig` (an OPTIONAL role field the server also serves) is intentionally
 // EXCLUDED: no shipped role uses it today, and being an object it would need a
 // deterministic deep canonicalization (recursive key sort) before hashing —
@@ -187,20 +210,20 @@ function collectCatalogRoles() {
       if (!out.has(r.slug)) {
         out.set(r.slug, { version: r.version, langRoles: new Map() });
       } else {
-        // Same slug declared twice in index.json roles[]; already flagged above.
+        // Same slug declared twice in index.yaml roles[]; already flagged above.
         out.get(r.slug).version = r.version;
       }
     }
     for (const lang of languages) {
-      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
+      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
       if (!existsSync(langPath)) continue;
-      const langFile = readJson(langPath);
+      const langFile = readYaml(langPath);
       if (!langFile) continue;
       const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
       for (const role of roles) {
         if (!role || !role.slug) continue;
         const entry = out.get(role.slug);
-        if (!entry) continue; // role not declared in index.json; flagged above.
+        if (!entry) continue; // role not declared in index.yaml; flagged above.
         entry.langRoles.set(lang, role);
       }
     }
@@ -253,11 +276,11 @@ if (updateHashes) {
     // missing numeric version, but guard here too before comparing.
     if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
       blockers.push(
-        `role "${slug}" content changed but its index.json "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
+        `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
       );
     } else if (cur.version <= prev.version) {
       blockers.push(
-        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json before refreshing the lock`
+        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml before refreshing the lock`
       );
     }
   }
@@ -309,10 +332,10 @@ for (const [slug, cur] of current) {
     continue;
   }
   if (cur.hash === prev.hash) {
-    // Content unchanged; the lock version must still agree with index.json.
+    // Content unchanged; the lock version must still agree with index.yaml.
     if (cur.version !== prev.version) {
       errors.push(
-        `role "${slug}" content is unchanged but its index.json version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
+        `role "${slug}" content is unchanged but its index.yaml version (${cur.version}) differs from the lock (${prev.version}); run: node scripts/check.mjs --update-hashes`
       );
     }
     continue;
@@ -323,11 +346,11 @@ for (const [slug, cur] of current) {
   // (and we avoid a misleading "version bumped to undefined" message).
   if (typeof cur.version !== "number" || !Number.isFinite(cur.version)) {
     errors.push(
-      `role "${slug}" content changed but its index.json "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
+      `role "${slug}" content changed but its index.yaml "version" is missing or not numeric; set a numeric "version", then run: node scripts/check.mjs --update-hashes`
     );
   } else if (cur.version <= prev.version) {
     errors.push(
-      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json, then run: node scripts/check.mjs --update-hashes`
+      `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.yaml, then run: node scripts/check.mjs --update-hashes`
     );
   } else {
     errors.push(

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

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

apps/client/index.html

@@ -10,7 +10,6 @@
     <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,9 +33,7 @@
     "@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",
@@ -47,7 +45,6 @@
     "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",
@@ -98,7 +95,6 @@
     "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,18 +464,6 @@
   "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",
@@ -1376,5 +1364,6 @@
   "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"
+  "This language is no longer available in the catalog": "This language is no longer available in the catalog",
+  "Connecting… (read-only)": "Connecting… (read-only)"
 }

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

@@ -474,18 +474,6 @@
   "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": "Поделиться",
@@ -1234,5 +1222,6 @@
   "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": "Этот язык больше не доступен в каталоге"
+  "This language is no longer available in the catalog": "Этот язык больше не доступен в каталоге",
+  "Connecting… (read-only)": "Подключение… (только чтение)"
 }

apps/client/public/manifest.json

@@ -1,19 +1,30 @@
 {
-  "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": "192x192", "purpose": "any" },
-    { "src": "icons/app-icon-512x512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" }
+    {
+      "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"
+    }
   ]
 }

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

@@ -1,91 +0,0 @@
-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,7 +23,6 @@ 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();
@@ -34,20 +33,6 @@ 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);
@@ -138,13 +123,6 @@ 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

@@ -1,43 +0,0 @@
-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,27 +3,6 @@ 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> {
@@ -43,7 +22,13 @@ export function useCollabToken(): UseQueryResult<ICollabToken, Error> {
     //refetchInterval: 12 * 60 * 60 * 1000, // 12hrs
     //refetchIntervalInBackground: true,
     refetchOnMount: true,
-    retry: collabTokenRetry,
+    //@ts-ignore
+    retry: (failureCount, error) => {
+      if (isAxiosError(error) && error.response.status === 404) {
+        return false;
+      }
+      return 10;
+    },
     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,7 +20,6 @@ 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];
 
@@ -61,9 +60,6 @@ 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,12 +10,6 @@ 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

@@ -0,0 +1,100 @@
+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

@@ -0,0 +1,163 @@
+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

@@ -1,21 +0,0 @@
-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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,168 @@
+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

@@ -0,0 +1,126 @@
+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,7 +3,14 @@ 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 } from "@docmost/editor-ext";
+import {
+  markdownToHtml,
+  htmlToMarkdown,
+  canonicalizeFootnotes,
+  FOOTNOTES_LIST_NAME,
+  FOOTNOTE_REFERENCE_NAME,
+} from "@docmost/editor-ext";
+import type { Schema } from "@tiptap/pm/model";
 
 export const MarkdownClipboard = Extension.create({
   name: "markdownClipboard",
@@ -83,12 +90,25 @@ export const MarkdownClipboard = Extension.create({
             const body = elementFromString(parsed);
             normalizeTableColumnWidths(body);
 
-            const contentNodes = DOMParser.fromSchema(
+            const parsedSlice = 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));
@@ -133,6 +153,54 @@ 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,8 +34,6 @@ 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);
@@ -92,10 +90,6 @@ 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(() => {
@@ -116,32 +110,28 @@ export function FullEditor({
       )}
       <MemoizedDeletedPageBanner slugId={slugId} />
       <MemoizedTemporaryNoteBanner slugId={slugId} />
-      <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>
+      <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}
+      />
     </Container>
   );
 }

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

@@ -1,48 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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, broadcasts, and does NOT write the editor", async () => {
+  it("happy path: applies the title, refreshes cache, writes the field, broadcasts", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor();
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -157,11 +157,9 @@ describe("useGeneratePageTitle", () => {
       title: "Generated Title",
     });
     expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    // 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(titleEditor.commands.setContent).toHaveBeenCalledWith(
+      "Generated Title",
+    );
     expect(localEmitMock).toHaveBeenCalled();
     expect(emitMock).toHaveBeenCalled();
     expect(notificationsShowMock).toHaveBeenCalledWith(
@@ -169,7 +167,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("keeps the DB write keyed by the captured pageId and still broadcasts after navigation", async () => {
+  it("does NOT write the visible title field when the user navigated away during generation", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor(); // persistent across navigation
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -205,9 +203,55 @@ describe("useGeneratePageTitle", () => {
       pageId: "pageA",
       title: "Generated Title",
     });
-    // ...the hook never writes the editor regardless of navigation...
+    // ...but we must NOT stamp page A's title into page B's visible field.
     expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // ...and the change is still broadcast to other clients.
+    // 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();
     expect(emitMock).toHaveBeenCalled();
   });
 

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

@@ -1,9 +1,13 @@
+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 } from "@/features/editor/atoms/editor-atoms.ts";
+import {
+  pageEditorAtom,
+  titleEditorAtom,
+} from "@/features/editor/atoms/editor-atoms.ts";
 import {
   updatePageData,
   useUpdateTitlePageMutation,
@@ -29,9 +33,18 @@ 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;
@@ -57,15 +70,33 @@ export function useGeneratePageTitle(pageId: string) {
       const page = await updateTitle({ pageId, title }); // POST /pages/update
       updatePageData(page); // refresh the react-query cache
 
-      // 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.
+      // 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);
+      }
 
       // Broadcast to other clients, mirroring TitleEditor.saveTitle's event shape.
       const event: UpdateEvent = {

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

@@ -1,185 +0,0 @@
-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,7 +6,16 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { WebSocketStatus } from "@hocuspocus/provider";
+import { IndexeddbPersistence } from "y-indexeddb";
+import * as Y from "yjs";
+import {
+  HocuspocusProvider,
+  onStatusParameters,
+  WebSocketStatus,
+  HocuspocusProviderWebsocket,
+  onSyncedParameters,
+  onStatelessParameters,
+} from "@hocuspocus/provider";
 import {
   Editor,
   EditorContent,
@@ -19,15 +28,13 @@ 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,
@@ -51,8 +58,10 @@ 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 } from "@mantine/hooks";
+import { useDebouncedCallback, 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";
@@ -63,7 +72,9 @@ 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";
@@ -73,6 +84,10 @@ 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;
@@ -88,6 +103,7 @@ export default function PageEditor({
   canComment,
 }: PageEditorProps) {
   const { t } = useTranslation();
+  const collaborationURL = useCollaborationUrl();
   const isComponentMounted = useRef(false);
   const editorRef = useRef<Editor | null>(null);
 
@@ -101,10 +117,22 @@ 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);
@@ -113,27 +141,141 @@ 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);
 
-  // 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);
+  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();
 
   const extensions = useMemo(() => {
-    if (!providersReady || !remote || !currentUser?.user) {
+    if (!providersReady || !providersRef.current || !currentUser?.user) {
       return mainExtensions;
     }
 
+    const remoteProvider = providersRef.current.remote;
+
     return [
       ...mainExtensions,
-      ...collabExtensions(remote, currentUser?.user),
+      ...collabExtensions(remoteProvider, currentUser?.user),
     ];
-  }, [providersReady, remote, currentUser?.user]);
+  }, [providersReady, currentUser?.user]);
 
   const editor = useEditor(
     {
@@ -302,6 +444,9 @@ 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) {
@@ -313,17 +458,21 @@ export default function PageEditor({
   }, [yjsConnectionStatus, isSynced]);
   useEffect(() => {
     if (!editor) return;
-    editor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
-  }, [currentPageEditMode, editor, editable]);
-
-  const hasConnectedOnceRef = useRef(false);
-  const [showStatic, setShowStatic] = useState(true);
+    // 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]);
 
   useEffect(() => {
     if (
       !hasConnectedOnceRef.current &&
-      yjsConnectionStatus === WebSocketStatus.Connected &&
-      isSynced
+      isCollabSynced(yjsConnectionStatus, isSynced)
     ) {
       hasConnectedOnceRef.current = true;
       setShowStatic(false);
@@ -335,17 +484,43 @@ export default function PageEditor({
       <PageEmbedLookupProvider>
         <PageEmbedAncestryProvider hostPageId={pageId}>
       {showStatic ? (
-        <EditorProvider
-          editable={false}
-          immediatelyRender={true}
-          extensions={mainExtensions}
-          content={content}
-          editorProps={{
-            attributes: {
-              "aria-label": t("Page content"),
-            },
-          }}
-        />
+        <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>
       ) : (
         <div className="editor-container" style={{ position: "relative" }}>
           <div ref={menuContainerRef}>
@@ -375,7 +550,7 @@ export default function PageEditor({
             {editor &&
               !editorIsEditable &&
               (editable || canComment) &&
-              remote && <ReadonlyBubbleMenu editor={editor} />}
+              providersRef.current && <ReadonlyBubbleMenu editor={editor} />}
             {showCommentPopup && (
               <CommentDialog editor={editor} pageId={pageId} />
             )}

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

@@ -1,33 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,87 +0,0 @@
-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 { useEffect } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { EditorContent, useEditor } from "@tiptap/react";
 import { Document } from "@tiptap/extension-document";
 import { Heading } from "@tiptap/extension-heading";
@@ -11,12 +11,14 @@ import {
   pageEditorAtom,
   titleEditorAtom,
 } from "@/features/editor/atoms/editor-atoms";
-import { updatePageData } from "@/features/page/queries/page-query";
+import {
+  updatePageData,
+  useUpdateTitlePageMutation,
+} 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 { Collaboration } from "@tiptap/extension-collaboration";
-import { shouldPropagateTitleChange } from "@/features/editor/title-collab";
+import { History } from "@tiptap/extension-history";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -26,9 +28,6 @@ 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;
@@ -46,83 +45,65 @@ 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);
 
-  // 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);
-        }
+  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"),
       },
-      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;
-            }
-          },
+      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
@@ -132,42 +113,59 @@ export function TitleEditor({
     navigate(pageSlug, { replace: true });
   }, [title]);
 
-  // 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,
+  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);
     });
+  }, [pageId, title, titleEditor]);
 
-    const page =
-      queryClient.getQueryData<IPage>(["pages", slugId]) ??
-      queryClient.getQueryData<IPage>(["pages", pageId]);
-    if (!page) return;
+  const debounceUpdate = useDebouncedCallback(saveTitle, 500);
 
-    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(() => {
+    // 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]);
 
   useEffect(() => {
     setTimeout(() => {
@@ -177,6 +175,13 @@ export function TitleEditor({
     }, 300);
   }, [titleEditor]);
 
+  useEffect(() => {
+    return () => {
+      // force-save title on navigation
+      saveTitle();
+    };
+  }, [pageId]);
+
   useEffect(() => {
     if (!titleEditor) return;
     titleEditor.setEditable(editable && currentPageEditMode === PageEditMode.Edit);
@@ -243,22 +248,16 @@ export function TitleEditor({
 
   return (
     <div className="page-title">
-      {titleReady ? (
-        <EditorContent
-          editor={titleEditor}
-          onKeyDown={(event) => {
-            // First handle the search hotkey
-            getHotkeyHandler([["mod+F", openSearchDialog]])(event);
+      <EditorContent
+        editor={titleEditor}
+        onKeyDown={(event) => {
+          // First handle the search hotkey
+          getHotkeyHandler([["mod+F", openSearchDialog]])(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>
-      )}
+          // Then handle other key events
+          handleTitleKeyDown(event);
+        }}
+      />
     </div>
   );
 }

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

@@ -1,107 +0,0 @@
-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

@@ -1,92 +0,0 @@
-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

@@ -1,266 +0,0 @@
-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

@@ -1,314 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,114 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,89 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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/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 { findBreadcrumbPath } from "@/features/page/tree/utils";
+import { computeBreadcrumbState } from "./breadcrumb.utils";
 import {
   Button,
   Anchor,
@@ -15,8 +15,12 @@ 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 } from "@/features/page/queries/page-query.ts";
+import {
+  usePageQuery,
+  usePageBreadcrumbsQuery,
+} from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useMediaQuery } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
@@ -38,14 +42,29 @@ 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 (treeData?.length > 0 && currentPage) {
-      const breadcrumb = findBreadcrumbPath(treeData, currentPage.id);
-      setBreadcrumbNodes(breadcrumb || null);
-    }
-  }, [currentPage?.id, treeData]);
+    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]);
 
   const HiddenNodesTooltipContent = () =>
     breadcrumbNodes?.slice(1, -1).map((node) => (

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

@@ -0,0 +1,114 @@
+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

@@ -0,0 +1,61 @@
+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,8 +12,6 @@ import {
   IconList,
   IconMarkdown,
   IconPrinter,
-  IconCloud,
-  IconCloudCheck,
   IconStar,
   IconStarFilled,
   IconTrash,
@@ -41,8 +39,6 @@ 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";
@@ -415,16 +411,14 @@ 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);
 
-  const isDisconnected = ["disconnected", "connecting"].includes(
-    yjsConnectionStatus,
-  );
-
   useEffect(() => {
+    const isDisconnected = ["disconnected", "connecting"].includes(
+      yjsConnectionStatus,
+    );
+
     if (isDisconnected) {
       if (!timeoutRef.current) {
         timeoutRef.current = setTimeout(() => setShowWarning(true), 5000);
@@ -436,7 +430,7 @@ function ConnectionWarning() {
       }
       setShowWarning(false);
     }
-  }, [isDisconnected]);
+  }, [yjsConnectionStatus]);
 
   // Cleanup only on unmount
   useEffect(() => {
@@ -447,59 +441,22 @@ function ConnectionWarning() {
     };
   }, []);
 
-  // State (1): offline/disconnected — changes are kept locally. Preserve the
-  // existing >5s debounce before surfacing this state.
-  if (isDisconnected) {
-    if (!showWarning) return null;
+  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={syncedLabel} openDelay={250} withArrow>
+    <Tooltip
+      label={t("Real-time editor connection lost. Retrying...")}
+      openDelay={250}
+      withArrow
+    >
       <ThemeIcon
         variant="default"
-        c="dimmed"
+        c="red"
         role="status"
-        aria-label={syncedLabel}
+        aria-label={t("Real-time editor connection lost. Retrying...")}
         style={{ border: "none" }}
       >
-        <IconCloudCheck size={20} stroke={2} />
+        <IconWifiOff size={20} stroke={2} />
       </ThemeIcon>
     </Tooltip>
   );

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

@@ -1,7 +1,6 @@
 import {
   InfiniteData,
   QueryKey,
-  queryOptions,
   useInfiniteQuery,
   UseInfiniteQueryResult,
   useMutation,
@@ -43,38 +42,12 @@ 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: pageKeys.detail(pageInput.pageId),
+    queryKey: ["pages", pageInput.pageId],
     queryFn: () => getPageById(pageInput),
     enabled: !!pageInput.pageId,
     staleTime: 5 * 60 * 1000,
@@ -83,9 +56,9 @@ export function usePageQuery(
   useEffect(() => {
     if (query.data) {
       if (isValidUuid(pageInput.pageId)) {
-        queryClient.setQueryData(pageKeys.detail(query.data.slugId), query.data);
+        queryClient.setQueryData(["pages", query.data.slugId], query.data);
       } else {
-        queryClient.setQueryData(pageKeys.detail(query.data.id), query.data);
+        queryClient.setQueryData(["pages", query.data.id], query.data);
       }
     }
   }, [query.data]);
@@ -96,10 +69,6 @@ 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);
@@ -111,20 +80,18 @@ export function useCreatePageMutation() {
 }
 
 export function updatePageData(data: IPage) {
-  const pageBySlug = queryClient.getQueryData<IPage>(
-    pageKeys.detail(data.slugId),
-  );
-  const pageById = queryClient.getQueryData<IPage>(pageKeys.detail(data.id));
+  const pageBySlug = queryClient.getQueryData<IPage>(["pages", data.slugId]);
+  const pageById = queryClient.getQueryData<IPage>(["pages", data.id]);
 
   if (pageBySlug) {
-    queryClient.setQueryData(pageKeys.detail(data.slugId), {
+    queryClient.setQueryData(["pages", data.slugId], {
       ...pageBySlug,
       ...data,
     });
   }
 
   if (pageById) {
-    queryClient.setQueryData(pageKeys.detail(data.id), { ...pageById, ...data });
+    queryClient.setQueryData(["pages", data.id], { ...pageById, ...data });
   }
 
   invalidateOnUpdatePage(
@@ -178,11 +145,11 @@ export function useRemovePageMutation() {
       });
 
       // Stamp deletedAt so a re-visit shows the trash banner, not stale state.
-      const cached = queryClient.getQueryData<IPage>(pageKeys.detail(pageId));
+      const cached = queryClient.getQueryData<IPage>(["pages", pageId]);
       if (cached) {
         const stamped = { ...cached, deletedAt: new Date() };
-        queryClient.setQueryData(pageKeys.detail(cached.id), stamped);
-        queryClient.setQueryData(pageKeys.detail(cached.slugId), stamped);
+        queryClient.setQueryData(["pages", cached.id], stamped);
+        queryClient.setQueryData(["pages", cached.slugId], stamped);
       }
 
       invalidateOnDeletePage(pageId);
@@ -221,9 +188,6 @@ 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),
   });
 }
@@ -303,11 +267,8 @@ 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>(pageKeys.detail(restoredPage.id), merge);
-      queryClient.setQueryData<IPage>(
-        pageKeys.detail(restoredPage.slugId),
-        merge,
-      );
+      queryClient.setQueryData<IPage>(["pages", restoredPage.id], merge);
+      queryClient.setQueryData<IPage>(["pages", restoredPage.slugId], merge);
     },
     onError: (error) => {
       notifications.show({
@@ -322,7 +283,7 @@ export function useGetSidebarPagesQuery(
   data: SidebarPagesParams | null,
 ): UseInfiniteQueryResult<InfiniteData<IPagination<IPage>, unknown>> {
   return useInfiniteQuery({
-    queryKey: pageKeys.sidebar(data),
+    queryKey: ["sidebar-pages", data],
     enabled: !!data?.pageId || !!data?.spaceId,
     queryFn: ({ pageParam }) =>
       getSidebarPages({ ...data, cursor: pageParam, limit: 100 }),
@@ -333,7 +294,7 @@ export function useGetSidebarPagesQuery(
 
 export function useGetRootSidebarPagesQuery(data: SidebarPagesParams) {
   return useInfiniteQuery({
-    queryKey: pageKeys.rootSidebar(data.spaceId),
+    queryKey: ["root-sidebar-pages", data.spaceId],
     queryFn: async ({ pageParam }) => {
       return getSidebarPages({
         spaceId: data.spaceId,
@@ -359,7 +320,7 @@ export function usePageBreadcrumbsQuery(
   pageId: string,
 ): UseQueryResult<Partial<IPage[]>, Error> {
   return useQuery({
-    queryKey: pageKeys.breadcrumbs(pageId),
+    queryKey: ["breadcrumbs", pageId],
     queryFn: () => getPageBreadcrumbs(pageId),
     enabled: !!pageId,
   });
@@ -371,12 +332,10 @@ 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. 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).
+  // not using a hook here, so we can call it inside a useEffect hook
   const response = await queryClient.fetchQuery({
-    ...sidebarPagesQueryOptions(params),
+    queryKey: ["sidebar-pages", params],
+    queryFn: () => getAllSidebarPages(params),
     staleTime: opts?.fresh ? 0 : 30 * 60 * 1000,
   });
 
@@ -386,7 +345,7 @@ export async function fetchAllAncestorChildren(
 
 export function useRecentChangesQuery(spaceId?: string) {
   return useInfiniteQuery({
-    queryKey: pageKeys.recentChanges(spaceId),
+    queryKey: ["recent-changes", spaceId],
     queryFn: ({ pageParam }) =>
       getRecentChanges({ spaceId, cursor: pageParam, limit: 15 }),
     initialPageParam: undefined as string | undefined,
@@ -457,12 +416,12 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
   let queryKey: QueryKey = null;
   if (data.parentPageId === null) {
-    queryKey = pageKeys.rootSidebar(data.spaceId);
+    queryKey = ["root-sidebar-pages", data.spaceId];
   } else {
-    queryKey = pageKeys.sidebar({
-      pageId: data.parentPageId,
-      spaceId: data.spaceId,
-    });
+    queryKey = [
+      "sidebar-pages",
+      { pageId: data.parentPageId, spaceId: data.spaceId },
+    ];
   }
 
   //update all sidebar pages
@@ -522,7 +481,7 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
     //update root sidebar pages haschildern
     const rootSideBarMatches = queryClient.getQueriesData({
-      queryKey: pageKeys.rootSidebar(data.spaceId),
+      queryKey: ["root-sidebar-pages", data.spaceId],
       exact: false,
     });
 
@@ -546,7 +505,7 @@ export function invalidateOnCreatePage(data: Partial<IPage>) {
 
   //update recent changes
   queryClient.invalidateQueries({
-    queryKey: pageKeys.recentChanges(data.spaceId),
+    queryKey: ["recent-changes", data.spaceId],
   });
 }
 
@@ -560,9 +519,9 @@ export function invalidateOnUpdatePage(
   invalidatePageTree();
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
-    queryKey = pageKeys.rootSidebar(spaceId);
+    queryKey = ["root-sidebar-pages", spaceId];
   } else {
-    queryKey = pageKeys.sidebar({ pageId: parentPageId, spaceId: spaceId });
+    queryKey = ["sidebar-pages", { pageId: parentPageId, spaceId: spaceId }];
   }
   //update all sidebar pages
   queryClient.setQueryData<InfiniteData<IPagination<IPage>>>(
@@ -585,7 +544,7 @@ export function invalidateOnUpdatePage(
 
   //update recent changes
   queryClient.invalidateQueries({
-    queryKey: pageKeys.recentChanges(spaceId),
+    queryKey: ["recent-changes", spaceId],
   });
 }
 
@@ -600,8 +559,8 @@ export function updateCacheOnMovePage(
   // Remove page from old parent's cache
   const oldQueryKey =
     oldParentId === null
-      ? pageKeys.rootSidebar(spaceId)
-      : pageKeys.sidebar({ pageId: oldParentId, spaceId });
+      ? ["root-sidebar-pages", spaceId]
+      : ["sidebar-pages", { pageId: oldParentId, spaceId }];
 
   queryClient.setQueryData<InfiniteData<IPagination<IPage>>>(
     oldQueryKey,
@@ -621,7 +580,7 @@ export function updateCacheOnMovePage(
   if (oldParentId !== null) {
     const oldParentCache = queryClient.getQueryData<
       InfiniteData<IPagination<IPage>>
-    >(pageKeys.sidebar({ pageId: oldParentId, spaceId }));
+    >(["sidebar-pages", { pageId: oldParentId, spaceId }]);
 
     const remainingChildren =
       oldParentCache?.pages.flatMap((p) => p.items).length ?? 0;
@@ -659,8 +618,8 @@ export function updateCacheOnMovePage(
   // Add page to new parent's cache
   const newQueryKey =
     newParentId === null
-      ? pageKeys.rootSidebar(spaceId)
-      : pageKeys.sidebar({ pageId: newParentId, spaceId });
+      ? ["root-sidebar-pages", spaceId]
+      : ["sidebar-pages", { pageId: newParentId, spaceId }];
 
   queryClient.setQueryData<InfiniteData<IPagination<Partial<IPage>>>>(
     newQueryKey,

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

@@ -7,7 +7,6 @@ import { notifications } from "@mantine/notifications";
 import {
   IconArrowRight,
   IconClockHour4,
-  IconCloudDownload,
   IconCopy,
   IconDotsVertical,
   IconFileExport,
@@ -36,12 +35,6 @@ 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";
@@ -79,45 +72,6 @@ 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;
@@ -274,17 +228,6 @@ 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,6 +15,7 @@ import {
   useCreatePageMutation,
   useRemovePageMutation,
   useMovePageMutation,
+  useUpdatePageMutation,
   updateCacheOnMovePage,
 } from "@/features/page/queries/page-query.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -26,6 +27,7 @@ export type UseTreeMutation = {
     parentId: string | null,
     opts?: { temporary?: boolean },
   ) => Promise<void>;
+  handleRename: (id: string, name: string) => Promise<void>;
   handleDelete: (id: string) => Promise<void>;
 };
 
@@ -37,6 +39,7 @@ 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();
@@ -202,6 +205,20 @@ 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(
@@ -247,7 +264,7 @@ export function useTreeMutation(spaceId: string): UseTreeMutation {
     [removePageMutation, setData, store, pageSlug, navigate, spaceSlug],
   );
 
-  return { handleMove, handleCreate, handleDelete };
+  return { handleMove, handleCreate, handleRename, handleDelete };
 }
 
 function isPageInNode(node: SpaceTreeNode, pageSlug: string): boolean {

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

@@ -0,0 +1,74 @@
+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,7 +73,10 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
       if (value) {
         await createShareMutation.mutateAsync({
           pageId: pageId,
-          includeSubPages: true,
+          // 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,
           searchIndexing: false,
         });
       } else if (share && share.id) {

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

@@ -35,9 +35,17 @@ export interface ISharedItem extends IShare {
   };
 }
 
-export interface ISharedPage extends IShare {
-  page: IPage;
-  share: 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;
     level: number;
     sharedPage: { id: string; slugId: string; title: string; icon: string };
   };
@@ -73,6 +81,10 @@ 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/queries/space-query.ts

@@ -1,6 +1,5 @@
 import {
   keepPreviousData,
-  queryOptions,
   useInfiniteQuery,
   useMutation,
   useQuery,
@@ -32,37 +31,11 @@ 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: spaceKeys.list(params),
+    queryKey: ["spaces", params],
     queryFn: () => getSpaces(params),
     placeholderData: keepPreviousData,
     refetchOnMount: true,
@@ -71,16 +44,16 @@ export function useGetSpacesQuery(
 
 export function useSpaceQuery(spaceId: string): UseQueryResult<ISpace, Error> {
   const query = useQuery({
-    queryKey: spaceKeys.detail(spaceId),
+    queryKey: ["space", spaceId],
     queryFn: () => getSpaceById(spaceId),
     enabled: !!spaceId,
   });
   useEffect(() => {
     if (query.data) {
       if (isValidUuid(spaceId)) {
-        queryClient.setQueryData(spaceKeys.detail(query.data.slug), query.data);
+        queryClient.setQueryData(["space", query.data.slug], query.data);
       } else {
-        queryClient.setQueryData(spaceKeys.detail(query.data.id), query.data);
+        queryClient.setQueryData(["space", query.data.id], query.data);
       }
     }
   }, [query.data]);
@@ -89,11 +62,8 @@ 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: spaceKeys.detail(spaceSlug),
+    queryKey: ["space", spaceSlug],
     queryFn: () => getSpaceById(spaceSlug),
   });
 
@@ -130,8 +100,10 @@ export function useGetSpaceBySlugQuery(
   spaceId: string,
 ): UseQueryResult<ISpace, Error> {
   return useQuery({
-    ...spaceByIdQueryOptions(spaceId),
+    queryKey: ["space", spaceId],
+    queryFn: () => getSpaceById(spaceId),
     enabled: !!spaceId,
+    staleTime: 5 * 60 * 1000,
   });
 }
 
@@ -144,16 +116,14 @@ export function useUpdateSpaceMutation() {
     onSuccess: (data, variables) => {
       notifications.show({ message: t("Space updated successfully") });
 
-      const space = queryClient.getQueryData(
-        spaceKeys.detail(variables.spaceId),
-      ) as ISpace;
+      const space = queryClient.getQueryData([
+        "space",
+        variables.spaceId,
+      ]) as ISpace;
       if (space) {
         const updatedSpace = { ...space, ...data };
-        queryClient.setQueryData(
-          spaceKeys.detail(variables.spaceId),
-          updatedSpace,
-        );
-        queryClient.setQueryData(spaceKeys.detail(data.slug), updatedSpace);
+        queryClient.setQueryData(["space", variables.spaceId], updatedSpace);
+        queryClient.setQueryData(["space", data.slug], updatedSpace);
       }
 
       queryClient.invalidateQueries({
@@ -178,7 +148,7 @@ export function useDeleteSpaceMutation() {
 
       if (variables.slug) {
         queryClient.removeQueries({
-          queryKey: spaceKeys.detail(variables.slug),
+          queryKey: ["space", variables.slug],
           exact: true,
         });
       }
@@ -186,7 +156,7 @@ export function useDeleteSpaceMutation() {
       // Remove space-specific queries
       if (variables.id) {
         queryClient.removeQueries({
-          queryKey: spaceKeys.detail(variables.id),
+          queryKey: ["space", variables.id],
           exact: true,
         });
 
@@ -226,7 +196,7 @@ export function useSpaceMembersInfiniteQuery(
   query?: string,
 ) {
   return useInfiniteQuery({
-    queryKey: spaceKeys.members(spaceId, query),
+    queryKey: ["spaceMembers", spaceId, query],
     queryFn: ({ pageParam }) =>
       getSpaceMembers(spaceId, { cursor: pageParam, limit: 50, query }),
     enabled: !!spaceId,

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

@@ -2,19 +2,9 @@ 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: userKeys.currentUser(),
+    queryKey: ["currentUser"],
     queryFn: async () => {
       return await getMyInfo();
     },

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

@@ -1,118 +0,0 @@
-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,7 +11,6 @@ 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";
 
@@ -71,30 +70,14 @@ export function UserProvider({ children }: React.PropsWithChildren) {
     document.documentElement.lang = i18n.resolvedLanguage || i18n.language || "en-US";
   }, [i18n.language, i18n.resolvedLanguage]);
 
-  // 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 (isLoading) 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 <OfflineFallback />;
+    return <></>;
   }
 
   return <>{children}</>;

apps/client/src/main.tsx

@@ -11,8 +11,7 @@ import { MantineProvider } from "@mantine/core";
 import { BrowserRouter } from "react-router-dom";
 import { ModalsProvider } from "@mantine/modals";
 import { Notifications } from "@mantine/notifications";
-import { QueryClient } from "@tanstack/react-query";
-import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { HelmetProvider } from "react-helmet-async";
 import "./i18n";
 import { PostHogProvider } from "posthog-js/react";
@@ -22,13 +21,6 @@ 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({
@@ -38,18 +30,10 @@ 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(),
@@ -66,34 +50,15 @@ root.render(
   <BrowserRouter>
     <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
       <ModalsProvider>
-        <PersistQueryClientProvider
-          client={queryClient}
-          persistOptions={{
-            persister: queryPersister,
-            maxAge: 1000 * 60 * 60 * 24,
-            buster: APP_VERSION,
-            dehydrateOptions: {
-              shouldDehydrateQuery: shouldDehydrateOfflineQuery,
-            },
-          }}
-        >
+        <QueryClientProvider client={queryClient}>
           <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>
-        </PersistQueryClientProvider>
+        </QueryClientProvider>
       </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,6 +24,9 @@ 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

@@ -1,39 +0,0 @@
-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

@@ -1,23 +0,0 @@
-/**
- * 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

@@ -1,59 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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

@@ -1,32 +0,0 @@
-/**
- * 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,4 +1,2 @@
 /// <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,6 +1,5 @@
 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";
 
@@ -54,51 +53,7 @@ export default defineConfig(({ mode }) => {
       },
       APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
     },
-    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 },
-      }),
-    ],
+    plugins: [react()],
     build: {
       rolldownOptions: {
         output: {

apps/server/package.json

@@ -64,7 +64,6 @@
     "@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",
@@ -126,6 +125,7 @@
     "typesense": "^3.0.5",
     "undici": "7.24.0",
     "ws": "^8.20.1",
+    "yaml": "^2.8.3",
     "yauzl": "^3.2.1",
     "zod": "^4.3.6"
   },

apps/server/src/app.module.ts

@@ -28,6 +28,7 @@ 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 { SandboxModule } from './integrations/sandbox/sandbox.module';
 import { AiModule } from './integrations/ai/ai.module';
 import { AiChatModule } from './core/ai-chat/ai-chat.module';
 
@@ -89,6 +90,7 @@ try {
     TelemetryModule,
     ThrottleModule,
     McpModule,
+    SandboxModule,
     AiModule,
     AiChatModule,
     ...enterpriseModules,

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

@@ -24,9 +24,7 @@ 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 {
@@ -151,45 +149,6 @@ export class CollaborationGateway {
     return this.hocuspocus.openDirectConnection(documentName, context);
   }
 
-  /**
-   * Write a new page title INTO the page's Yjs 'title' fragment, Redis-INDEPENDENT.
-   *
-   * 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.
-   *
-   * 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 writePageTitle(
-    pageId: string,
-    title: string,
-    context?: { user?: User; actor?: string; aiChatId?: string },
-  ): Promise<void> {
-    const documentName = `page.${pageId}`;
-    const connection = await this.hocuspocus.openDirectConnection(
-      documentName,
-      context ?? {},
-    );
-    try {
-      await connection.transact((doc) => writeTitleFragment(doc, title));
-    } finally {
-      await connection.disconnect();
-    }
-  }
-
   /*
    *Can be used before calling openDirectConnection directly
    */

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

@@ -1,139 +0,0 @@
-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,7 +2,6 @@ import { Injectable, Logger } from '@nestjs/common';
 import { Hocuspocus, Document } from '@hocuspocus/server';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
-  buildTitleSeedYdoc,
   prosemirrorNodeToYElement,
   tiptapExtensions,
 } from './collaboration.util';
@@ -14,35 +13,6 @@ 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);

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

@@ -1,13 +1,9 @@
 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';
 
@@ -245,49 +241,3 @@ 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,7 +59,6 @@ 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({
@@ -144,34 +143,6 @@ 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,9 +1,3 @@
 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,6 +205,32 @@ 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.extension.spec.ts

@@ -1,483 +0,0 @@
-import * as Y from 'yjs';
-import { TiptapTransformer } from '@hocuspocus/transformer';
-import { PersistenceExtension } from './persistence.extension';
-import { buildTitleSeedYdoc, tiptapExtensions } from '../collaboration.util';
-
-// Direct instantiation with stub deps, mirroring the auth/env unit specs.
-const bodyJson = {
-  type: 'doc',
-  content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hello' }] }],
-};
-
-// 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 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),
-    };
-    pageHistoryRepo = {
-      findPageLastHistory: jest.fn(),
-      saveHistory: jest.fn(),
-    };
-    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),
-    };
-
-    ext = new PersistenceExtension(
-      pageRepo as any,
-      pageHistoryRepo as any,
-      db as any,
-      aiQueue as any,
-      historyQueue as any,
-      notificationQueue as any,
-      collabHistory as any,
-      transclusionService as any,
-    );
-  });
-
-  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);
-    });
-
-    it('does NOT re-seed an existing non-empty title fragment', () => {
-      const doc = new Y.Doc();
-      addTitleFragment(doc, 'Existing');
-
-      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);
-    });
-  });
-
-  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,
-    });
-
-    const context = { user: { id: 'u1', name: 'U', avatarUrl: null } };
-
-    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();
-    });
-  });
-
-  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);
-
-      expect(result).toBeUndefined();
-      expect(pageRepo.findById).not.toHaveBeenCalled();
-    });
-
-    it('returns undefined and does not persist when the page is null', async () => {
-      const document = { isEmpty: () => true };
-      pageRepo.findById.mockResolvedValue(null);
-
-      const result = await ext.onLoadDocument({
-        documentName: 'page.PAGE_ID',
-        document,
-      } as any);
-
-      expect(result).toBeUndefined();
-      expect(pageRepo.updatePage).not.toHaveBeenCalled();
-    });
-
-    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);
-
-      const document = { isEmpty: () => true };
-      const result = await ext.onLoadDocument({
-        documentName: 'page.PAGE_ID',
-        document,
-      } as any);
-
-      // 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(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 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);
-
-      const document = { isEmpty: () => true };
-      const result = await ext.onLoadDocument({
-        documentName: 'page.PAGE_ID',
-        document,
-      } as any);
-
-      // 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('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);
-
-      const document = { isEmpty: () => true };
-      const result = await ext.onLoadDocument({
-        documentName: 'page.PAGE_ID',
-        document,
-      } as any);
-
-      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

@@ -9,7 +9,6 @@ import * as Y from 'yjs';
 import { Injectable, Logger } from '@nestjs/common';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import {
-  buildTitleSeedYdoc,
   getPageId,
   isEmptyParagraphDoc,
   jsonToText,
@@ -117,10 +116,6 @@ 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,
@@ -132,164 +127,33 @@ export class PersistenceExtension implements Extension {
     }
 
     if (page.ydoc) {
+      this.logger.debug(`ydoc loaded from db: ${pageId}`);
+
       const doc = new Y.Doc();
-      Y.applyUpdate(doc, new Uint8Array(page.ydoc));
+      const dbState = new Uint8Array(page.ydoc);
 
-      // 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;
-      }
+      Y.applyUpdate(doc, dbState);
+      return doc;
     }
 
-    // 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 no ydoc state in db convert json in page.content to Ydoc.
     if (page.content) {
-      // 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(`converting json to ydoc: ${pageId}`);
+
+      const ydoc = TiptapTransformer.toYdoc(
+        page.content,
+        'default',
+        tiptapExtensions,
+      );
+
+      Y.encodeStateAsUpdate(ydoc);
+      return ydoc;
     }
 
     this.logger.debug(`creating fresh ydoc: ${pageId}`);
     return new Y.Doc();
   }
 
-  /**
-   * 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).
-   */
-  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 {
-      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.warn(`failed to seed title fragment: ${err?.['message']}`);
-      return false;
-    }
-  }
-
   async onStoreDocument(data: onStoreDocumentPayload) {
     const { documentName, document, context } = data;
 
@@ -307,34 +171,7 @@ 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
@@ -368,80 +205,11 @@ export class PersistenceExtension implements Extension {
             return;
           }
 
-          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) {
+          if (isDeepStrictEqual(tiptapJson, page.content)) {
             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 || [];
@@ -459,22 +227,29 @@ export class PersistenceExtension implements Extension {
           // 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') {
+          // 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,
@@ -492,27 +267,9 @@ 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}`);
@@ -533,8 +290,6 @@ 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({
@@ -552,20 +307,11 @@ 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 && bodyChanged) {
+    if (page) {
       await this.collabHistory.addContributors(pageId, editingUserIds);
 
       const mentions = extractMentions(tiptapJson);

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

@@ -1,81 +0,0 @@
-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

@@ -1,55 +0,0 @@
-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),
-      );
-    }
-  }
-}

apps/server/src/collaboration/server/collab-app.module.ts

@@ -20,7 +20,6 @@ import { CaslModule } from '../../core/casl/casl.module';
 import { ThrottleModule } from '../../integrations/throttle/throttle.module';
 import { CacheModule } from '@nestjs/cache-manager';
 import KeyvRedis from '@keyv/redis';
-import { PageTreeBridgePublisher } from '../listeners/page-tree-bridge.publisher';
 
 @Module({
   imports: [
@@ -55,6 +54,6 @@ import { PageTreeBridgePublisher } from '../listeners/page-tree-bridge.publisher
       ? [CollaborationController]
       : []),
   ],
-  providers: [AppService, PageTreeBridgePublisher],
+  providers: [AppService],
 })
 export class CollabAppModule {}

apps/server/src/core/ai-chat/external-mcp/mcp-clients.lease.spec.ts

@@ -0,0 +1,157 @@
+import { McpClientsService } from './mcp-clients.service';
+
+/**
+ * #204 (Phase 1, highest-value MCP gap) — external MCP client lease / refcount /
+ * eviction lifecycle.
+ *
+ * `toolsFor` hands the streaming turn a release handle; the real transports must
+ * be closed EXACTLY once and only when (a) the cache entry has been evicted AND
+ * (b) no turn still leases it. The bugs this guards against:
+ *   - leak: an evicted entry whose clients are never closed (refCount stuck > 0);
+ *   - premature close: a TTL/CRUD eviction closing a client a turn is still
+ *     executing tool calls against;
+ *   - double close: a release handle closing the same client more than once.
+ *
+ * The private `buildEntry` is stubbed so no real network/MCP connection happens;
+ * we drive only the lease bookkeeping in `toolsFor` / `release` / `evict` /
+ * `invalidate`, which is the untested surface.
+ */
+describe('McpClientsService lease/refcount/eviction', () => {
+  type FakeClient = { tools: () => Promise<any>; close: jest.Mock };
+
+  function fakeClient(): FakeClient {
+    return {
+      tools: async () => ({}),
+      close: jest.fn().mockResolvedValue(undefined),
+    };
+  }
+
+  // Minimal CacheEntry the service's lease logic operates on.
+  function makeEntry(clients: FakeClient[]) {
+    const timer = setTimeout(() => {}, 60_000);
+    timer.unref?.();
+    return {
+      tools: {},
+      clients,
+      outcomes: [],
+      instructions: [],
+      expiresAt: Date.now() + 60_000,
+      refCount: 0,
+      evicted: false,
+      closed: false,
+      timer,
+    } as any;
+  }
+
+  let service: McpClientsService;
+
+  beforeEach(() => {
+    service = new McpClientsService({} as any, {} as any);
+  });
+
+  function stubBuild(entry: any) {
+    jest.spyOn(service as any, 'buildEntry').mockResolvedValue(entry);
+  }
+
+  it('leases on toolsFor and keeps the client warm (no close) on release', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-1');
+    expect(entry.refCount).toBe(1);
+
+    await lease.clients[0].close();
+    // Released but NOT evicted: the cached entry stays warm for reuse, so the
+    // transport must NOT be closed yet.
+    expect(entry.refCount).toBe(0);
+    expect(client.close).not.toHaveBeenCalled();
+  });
+
+  it('defers close when an entry is evicted while still leased, then closes once on release', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-2');
+    (service as any).evict(entry);
+
+    // Evicted under an active lease: close is deferred to the last release.
+    expect(entry.evicted).toBe(true);
+    expect(client.close).not.toHaveBeenCalled();
+
+    await lease.clients[0].close();
+    expect(client.close).toHaveBeenCalledTimes(1);
+    expect(entry.closed).toBe(true);
+  });
+
+  it('shares one entry across concurrent leases; closes only after the LAST release', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease1 = await service.toolsFor('ws-3');
+    const lease2 = await service.toolsFor('ws-3');
+    expect(entry.refCount).toBe(2);
+
+    (service as any).evict(entry);
+
+    await lease1.clients[0].close();
+    // One lease remains: a stream could still be running — must stay open.
+    expect(entry.refCount).toBe(1);
+    expect(client.close).not.toHaveBeenCalled();
+
+    await lease2.clients[0].close();
+    expect(entry.refCount).toBe(0);
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+
+  it('release is idempotent: closing the same handle twice decrements once and closes once', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-4');
+    (service as any).evict(entry);
+
+    await lease.clients[0].close();
+    await lease.clients[0].close();
+
+    expect(entry.refCount).toBe(0); // not -1
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+
+  it('evicting an unleased entry closes its clients immediately', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const built = await (service as any).getOrBuildEntry('ws-5');
+    expect(built.refCount).toBe(0);
+
+    (service as any).evict(entry);
+    expect(client.close).toHaveBeenCalledTimes(1);
+    expect(entry.closed).toBe(true);
+  });
+
+  it('invalidate (TTL/CRUD) does NOT close a client that a turn still leases', async () => {
+    const client = fakeClient();
+    const entry = makeEntry([client]);
+    stubBuild(entry);
+
+    const lease = await service.toolsFor('ws-6');
+    expect(entry.refCount).toBe(1);
+
+    service.invalidate('ws-6');
+    // invalidate evicts asynchronously once the build promise resolves.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(entry.evicted).toBe(true);
+    // Still leased: the mid-turn eviction must not pull the transport.
+    expect(client.close).not.toHaveBeenCalled();
+
+    await lease.clients[0].close();
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+});