fix(offline): address PR #120 review (comment 2513)

CHANGELOG: stop presenting the service-worker API cache as an active offline
store (/api is NetworkOnly) — describe it as a defensive purge of the legacy
api-get-cache from older clients; add an explicit upgrade note that the new CORS
allowlist rejects previously-allowed cross-domain REST clients until their origin
is added to CORS_ALLOWED_ORIGINS.

test(offline): cover make-offline ancestor-walk + dedup — a real-ancestor case
exercising the ancestorId===pageId guard (page warmed once), the dedup of
repeated tree failures into a single "tree" label, and the "breadcrumbs" label
when the breadcrumbs lookup rejects.

test(auth): cover clearOfflineCache in handleLogout — purged exactly once before
window.location.replace, and a thrown purge error does not block the redirect.

conventions: use pageKeys.detail() instead of raw ["pages", …] literals in
title-editor and use-page-collab-providers.

cleanup: remove the dead emit() in title-editor (the gateway ignores it; the
cross-user tree refresh is server-side via the Yjs title fragment); drop the
trivial Array.isArray(tiptapExtensions) test (schema is exercised transitively).

refactor: extract the shared page.<id> Yjs doc-name convention into
pageYdocName()/PAGE_YDOC_NAME_PREFIX so the editor providers, offline warm, and
offline purge can no longer drift apart.

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

.env.example

@@ -92,6 +92,19 @@ IFRAME_EMBED_ALLOWED=false
 # Example: https://intranet.example.com,https://portal.example.com
 IFRAME_ALLOWED_ORIGINS=
 
+# Comma-separated list of additional origins allowed to call the API via CORS.
+# The APP_URL origin and native mobile (Capacitor) origins are always allowed.
+# Leave empty for a same-origin (web-only) deployment.
+CORS_ALLOWED_ORIGINS=
+
+# Expose OpenAPI/Swagger docs at /api/docs (development/debugging aid only).
+SWAGGER_ENABLED=false
+
+# Capacitor (mobile shell): hosted client URL loaded by the iOS shell so the
+# AGPL web client is NOT bundled into the .ipa (see docs/mobile-app-plan.md §9).
+# Leave empty for Android bundled mode / local development.
+CAP_SERVER_URL=
+
 # Enable debug logging in production (default: false)
 DEBUG_MODE=false
 
@@ -124,26 +137,6 @@ 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
@@ -153,7 +146,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.yaml and /bundles/<id>/<lang>.yaml). This value is
+# (the server appends /index.json and /bundles/<id>/<lang>.json). 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,7 +25,6 @@ jobs:
   build:
     needs: test
     runs-on: ubuntu-latest
-    timeout-minutes: 30
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -66,8 +65,6 @@ 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
@@ -75,9 +72,7 @@ jobs:
       APP_URL: http://localhost:3000
     services:
       postgres:
-        # via mirror.gcr.io (Docker Hub pull-through cache; avoids Hub anonymous
-        # pull rate-limit that randomly fails on shared GitHub runner IPs).
-        image: mirror.gcr.io/pgvector/pgvector:pg18
+        image: pgvector/pgvector:pg18
         env:
           POSTGRES_DB: docmost
           POSTGRES_USER: docmost
@@ -90,8 +85,7 @@ jobs:
           --health-timeout 5s
           --health-retries 20
       redis:
-        # via mirror.gcr.io (see postgres note above).
-        image: mirror.gcr.io/library/redis:7
+        image: redis:7
         ports:
           - 6379:6379
         options: >-
@@ -129,7 +123,6 @@ 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
@@ -138,9 +131,7 @@ jobs:
       NODE_ENV: production
     services:
       postgres:
-        # via mirror.gcr.io (Docker Hub pull-through cache; avoids Hub anonymous
-        # pull rate-limit that randomly fails on shared GitHub runner IPs).
-        image: mirror.gcr.io/pgvector/pgvector:pg18
+        image: pgvector/pgvector:pg18
         env:
           POSTGRES_DB: docmost
           POSTGRES_USER: docmost
@@ -153,8 +144,7 @@ jobs:
           --health-timeout 5s
           --health-retries 20
       redis:
-        # via mirror.gcr.io (see postgres note above).
-        image: mirror.gcr.io/library/redis:7
+        image: redis:7
         ports:
           - 6379:6379
         options: >-

.github/workflows/test.yml

@@ -15,7 +15,6 @@ 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
@@ -27,9 +26,7 @@ jobs:
     # TEST_*_URL overrides are needed.
     services:
       postgres:
-        # via mirror.gcr.io (Docker Hub pull-through cache; avoids Hub anonymous
-        # pull rate-limit that randomly fails on shared GitHub runner IPs).
-        image: mirror.gcr.io/pgvector/pgvector:pg18
+        image: pgvector/pgvector:pg18
         env:
           POSTGRES_USER: docmost
           POSTGRES_PASSWORD: docmost_dev_pw
@@ -42,8 +39,7 @@ jobs:
           --health-timeout 5s
           --health-retries 5
       redis:
-        # via mirror.gcr.io (see postgres note above).
-        image: mirror.gcr.io/library/redis:7
+        image: redis:7
         ports:
           - 6379:6379
         options: >-

.gitignore

@@ -49,3 +49,8 @@ lerna-debug.log*
 
 # Self-hosted VAD / onnxruntime-web assets (copied from node_modules at dev/build time)
 apps/client/public/vad/
+
+# Capacitor native platform projects (generated locally via 'npx cap add ios|android')
+/ios
+/android
+.capacitor

AGENTS.md

@@ -72,10 +72,7 @@ git log -1 --format='Author: %an <%ae>%nCommitter: %cn <%ce>'
 
 ### 4. Push and PR to develop
 
-PRs always target `develop`. Two different mechanisms are involved: **pushing
-commits is git-native** (the Gitea MCP cannot push local git history, so the
-branch is still pushed with `git push`), while **the PR itself is opened through
-the Gitea MCP** (see below). The `claude_code` password lives in the macOS
+PRs always target `develop`. The `claude_code` password lives in the macOS
 keychain as a **generic password** under service `gitea-claude-code` (do not
 duplicate it as an internet-password for `gitea.vvzvlad.xyz` — that creates a
 conflict with the owner's account in the git credential helper):
@@ -97,24 +94,18 @@ git remote set-url gitea "$ORIG_URL"
 unset AGENT_PASS SAFE_PASS
 ```
 
-The PR is opened through the **Gitea MCP** (server `gitea`), not `curl`/`tea` —
-the MCP authenticates in-process, so no keychain lookup or Basic-Auth is needed.
-Call `pull_request_write` with:
+The PR is created via the Gitea REST API (Basic Auth as `claude_code`):
 
-- `method: "create"`
-- `owner: "vvzvlad"`, `repo: "gitmost"`
-- `base: "develop"`, `head: "<branch>"`
-- `title`, `body` — in the body: what was done, what is out of scope,
-  verification results (tsc/lint/tests).
+```bash
+curl -s -X POST \
+  -u "claude_code:$(security find-generic-password -s gitea-claude-code -w)" \
+  -H "Content-Type: application/json" \
+  -d @pr_body.json \
+  "https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls"
+```
 
-Manage and read PRs through the same server: `list_pull_requests`,
-`pull_request_read` (`get`, `get_diff`, `get_files`, `get_status`),
-`pull_request_review_write`.
-
-**Identity note:** the MCP acts under its **own** configured Gitea token (verify
-with `get_me`), a different account from the `claude_code` used for git
-commits/pushes in §3. Only the forge API calls (PR / issue / review) go through
-the MCP account; the commits themselves stay authored as `claude_code`.
+`base: develop`, `head: <branch>`. In the PR body: what was done, what is out
+of scope, verification results (tsc/lint/tests).
 
 > If push fails with `User permission denied for writing`, then `claude_code`
 > lacks collaborator rights on the repo. Ask the owner to add them (once, via
@@ -161,25 +152,23 @@ below.
 | Agent user (Gitea/git) | `claude_code` |
 | Agent email | `claude_code@vvzvlad.xyz` |
 | Keychain password | `security find-generic-password -s gitea-claude-code -w` |
-| Forge API (PR / issue / review / reads) | **Gitea MCP** — server `gitea` (`pull_request_write`, `issue_write`, `list_pull_requests`, `pull_request_read`, `label_read`, …). Authenticated in-process; acts under its own token — check with `get_me`. Repo slug on the server is `gitmost`. |
+| PR API | `https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls` (here `gitmost` is the repo's real slug on the server) |
 | Base branch | `develop` |
 | `origin` | GitHub mirror `vvzvlad/gitmost` — **do not push**, updated by the owner's CI |
 | `upstream` | The original Docmost — **never push** |
 
-## Creating issues (Gitea MCP)
+## Creating issues (Gitea `tea` CLI)
 
-File issues through the **Gitea MCP** (server `gitea`), not a CLI — call
-`issue_write` with:
+Issues are filed with the official Gitea CLI `tea`, already logged in as
+`claude_code` (`tea logins list` shows the `gitea` login as default):
 
-- `method: "create"`
-- `owner: "vvzvlad"`, `repo: "gitmost"`
-- `title`, `body`
-- `labels` — an array of label **IDs** (numbers), *not* names. Resolve a name
-  such as `feature` to its id first with `label_read` (`method: "list"`), then
-  pass e.g. `labels: [<id>]`.
+```bash
+tea issues create --repo vvzvlad/gitmost --labels feature \
+  --title '<title>' --description "$(cat body.md)"
+```
 
-Read issues with `list_issues`, `issue_read`, or `search_issues`. The MCP is
-authenticated in-process, so no `tea`/`curl` and no keychain lookup are needed.
+> Gotcha (tea 0.14.1): the issue body flag is `--description`/`-d`, **not**
+> `--body` — passing `--body` fails with `flag provided but not defined: -body`.
 
 ---
 
@@ -208,12 +197,6 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 
 Run from the repo root unless noted. The dev workflow needs **Postgres (with the `pgvector` extension) and Redis** reachable per `.env` (copy `.env.example` → `.env`).
 
-> **Bringing up a full local stand** (API + client + the separate realtime
-> collaboration process) has several non-obvious gotchas — a missing collab
-> server, `APP_SECRET` mismatch between processes, a stale `editor-ext` white-
-> screening the client, LAN exposure. See **[docs/dev-stand.md](docs/dev-stand.md)**
-> for the step-by-step and the traps.
-
 ```bash
 pnpm install                 # install all workspaces (uses pnpm patches; see package.json `pnpm.patchedDependencies`)
 pnpm dev                     # client (Vite) + server (Nest watch) concurrently — primary dev loop
@@ -258,9 +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.
 
-`pnpm dev` starts **only** the API server + client — the collaboration process is separate and must be started too, or the editor never connects. See **[docs/dev-stand.md](docs/dev-stand.md)** for running both locally (and why `APP_SECRET` must match between them).
-
-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.
+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.
 
 ### 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`.
@@ -273,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 (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.
+1. **Embedded MCP server** (`integrations/mcp/` + `packages/mcp`). The standalone `@docmost/mcp` server (39 agent-native tools: per-block patch/insert/delete by id, scripted `(doc)=>doc` transforms with dry-run diff, table editing, version diff/restore, comments, images, shares) is bundled and served over HTTP at `/mcp`. It writes through Docmost's real-time-collaboration layer so concurrent human edits aren't clobbered. Each request authenticates **per-user** via the `Authorization` header — either HTTP Basic (`base64(email:password)`, the user's own Docmost login, validated through `AuthService`) or a Bearer access JWT (the user's `authToken`) — and the session acts under that user's permissions. `MCP_DOCMOST_EMAIL` / `MCP_DOCMOST_PASSWORD` are an **optional service-account fallback**, used only when a request carries neither Basic nor Bearer credentials (back-compat for CI/scripts). An admin enables MCP with a workspace toggle (Workspace settings → AI). Optionally protected by a shared `MCP_TOKEN`: when set, every `/mcp` request must carry a matching `X-MCP-Token` header (its own header, separate from `Authorization`, which now carries the per-user Basic/Bearer credentials). Note: this changed from the older `Authorization: Bearer <MCP_TOKEN>` scheme — see `.env.example` and the CHANGELOG Breaking Changes entry.
 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

@@ -12,20 +12,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Place several images side by side in a row.** A new "Inline (side by
-  side)" alignment mode in the image bubble menu renders consecutive inline
-  images as a row that wraps onto the next line on narrow screens. The row is
-  centered horizontally by default in modern browsers (CSS `:has()`), falling
-  back to start-aligned rows in browsers without support. Unlike the float
-  modes, text does not wrap around inline images. The mode round-trips
-  losslessly through markdown as `data-align`, like the other alignment
-  values.
-
-- **Editable captions for images.** Images gain an optional caption shown
-  below them, edited inline from the image bubble menu and stored as a `caption` attribute. Captions round-trip
-  losslessly through markdown as a `data-caption` attribute on the image, so
-  they survive export/import unchanged. (#221)
-
 - **Quick-create regular and temporary notes from the Home and Space screens.**
   The Home screen now shows a second action next to "New note" that creates a
   *temporary* note (one that auto-moves to Trash after the workspace lifetime),
@@ -72,67 +58,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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)
-- **Inline spoiler mark — hide text behind click-to-reveal blur.** Selected text
-  can be marked as a spoiler from a new bubble-menu toggle, or typed Discord-style
-  with the `||text||` input rule; the rendered span blurs until clicked to reveal.
-  The mark is preserved losslessly through Markdown export/import (as a raw
-  `<span data-spoiler="true">…</span>`) and on public shares. (#259)
-- **Dock the AI chat window into the side menu.** The floating chat window can
-  be pinned to the sidebar — drag it onto the navbar (a drop-zone highlight
-  shows where it lands) or use the new "Dock to sidebar" header button; while
-  docked it fills the sidebar area and follows its live size. "Undock" (or
-  dragging it back out) restores the floating window, a collapsed/absent
-  sidebar falls back to floating, and the docked state survives a reload.
-  (#276, #282)
-- **Hovering commented text shows the comment thread in a tooltip.** Pointing
-  at a highlighted comment mark pops a small card with the author and plain
-  text of the root comment and its replies, so a thread can be skimmed without
-  opening the side panel. The card appears after a short delay (no flicker on a
-  passing glance), skips resolved and text-less threads, and dismisses on
-  scroll or click — clicking a mark still opens the comments panel. (#268,
-  #271)
-- **"Move to trash" button in the temporary-note banner.** Besides "Make
-  permanent", the banner on an open temporary note now also offers to trash the
-  note immediately instead of waiting out its lifetime. It reuses the regular
-  soft-delete path, so the "Page moved to trash" undo toast is the safety net —
-  no confirmation dialog. (#273, #277)
-- **Code-block controls float as an overlay instead of taking a row above the
-  code.** The language selector and copy button now sit in the block's top-right
-  corner, and the selector stays invisible until the block is hovered or the
-  selector is focused, so reading code is chrome-free. In read-only views only
-  the copy button renders. (#275, #278)
-- **The AI agent is told about your page edits between turns.** The server
-  snapshots the open page's Markdown at the end of every agent turn and, on the
-  next turn, injects a unified diff of what changed in between, so the agent
-  knows its earlier copy of the page is stale and builds on the user's edits
-  instead of reverting or overwriting them. The diff is whitespace-normalized
-  (pure formatting churn injects nothing) and size-capped, with a hint to
-  re-read the full page via `getPage` when truncated. (#274, #281)
-- **Stress-accent button (U+0301) in the bubble menu.** Select a vowel and
-  toggle a combining acute accent over it — a Russian-style stress mark. The
-  accent is stored as plain text (no custom mark), so it survives Markdown/HTML
-  export, full-text search and public shares unchanged; the toggle is a single
-  undo step and re-clicking removes the accent. (#270, #280)
-- **Reading position survives a reload.** The editor remembers how far you
-  scrolled in each page (per tab, in `sessionStorage`) and restores that
-  position after an F5 or reopening the document, waiting for the collaborative
-  content to finish laying out first. A URL `#hash` anchor still wins — restore
-  is a no-op then. (#266, #267)
-- **The slash menu finds commands typed in the wrong keyboard layout.** A query
-  typed with the wrong layout active (e.g. `/сщву` for `/code`, or `/cyjcrf`
-  for the Cyrillic «сноска» → Footnote) is additionally remapped ЙЦУКЕН↔QWERTY
-  by physical key position and matched against the commands; genuine Cyrillic
-  search terms keep priority over remapped candidates, and short wrong-layout
-  prefixes match by command title. (#283, #285, #287)
 
 ### Changed
 
@@ -142,17 +67,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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)
+- **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 two offline stores (the persisted query cache and the Yjs page
+  documents) are cleared on logout AND on sign-in so a previous user's private
+  data does not remain in the browser; the same purge also defensively drops any
+  legacy service-worker `api-get-cache` left by older clients (current builds
+  serve `/api` as NetworkOnly, so there is no active service-worker API cache).
+- **Mobile bootstrap**: a `returnToken` opt-in on login so native/mobile clients
+  can request the access JWT in the response body (`data.authToken`) in addition
+  to the httpOnly cookie (the web client stays cookie-only); an optional
+  OpenAPI/Swagger UI at `/api/docs` gated by `SWAGGER_ENABLED` (off by default);
+  and new env vars `CORS_ALLOWED_ORIGINS`, `SWAGGER_ENABLED`, `CAP_SERVER_URL`.
+
+### Changed
+
+- **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. **Upgrade note:** the old bare `app.enableCors()` reflected
+  *any* origin (with `credentials:false`), so any previously-working cross-domain
+  REST/browser client is now rejected until its origin is added to
+  `CORS_ALLOWED_ORIGINS` (see `.env.example`).
 
 ### Fixed
 
@@ -190,33 +130,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   "This address is in use. Saving will move it to this page." — and keeps Save
   enabled, so the existing reassign-confirm flow (`409 ALIAS_REASSIGN_REQUIRED` →
   "Move custom address?") is discoverable instead of reading as terminal. (#227)
-- **A non-empty page can no longer be silently lost to a momentarily-empty live
-  document.** The server's persistence guard now refuses to overwrite non-empty
-  persisted content with an empty live Y.Doc — a transient emptiness from a
-  glitch, a bad merge, or an emptying transclusion no longer wipes the saved
-  page. A *deliberate* clear still works: a select-all + Delete in the editor
-  emits a single-use "intentional clear" signal that lets exactly that one empty
-  write through the guard, so genuinely emptying a page is persisted while
-  accidental empties are blocked. (#248, #251)
-- **Ctrl+Z works again right after using a table menu.** Closing a table
-  row/column menu (grip or chevron) left focus on the menu's portaled target
-  outside the editor, so undo keystrokes went nowhere until you clicked back
-  into a cell. The editor is now refocused after the menu closes — unless you
-  deliberately moved focus to another input or editable (e.g. the page title).
-  (#269, #279)
-- **The AI reindex progress counter no longer freezes at 0.** Right after
-  "Reindex now" the client could read the stale pre-reindex snapshot of an
-  already-indexed workspace (`reindexing=false`, all pages counted) as
-  "finished" and stop polling on the very first tick, leaving the counter
-  frozen until a manual reload. Polling now keeps going until it has actually
-  observed the active run. (#262, #264)
-- **An MCP edit can no longer be silently lost to a duplicate collab document.**
-  When the agent addressed a page by its short slugId, the MCP opened a
-  collaboration document named after that slugId while the web editor always
-  uses the page's canonical UUID — two independent live documents for one page,
-  whose debounced stores clobbered each other. The MCP now resolves every page
-  id to the canonical UUID before opening the collab doc (a UUID input
-  short-circuits locally; a slugId is resolved once and cached). (#260, #265)
 
 ### Security
 
@@ -589,7 +502,6 @@ knowledge layer, an embedded MCP server, and the Gitmost rebrand.
 - Build: drop the private EE submodule, retarget CI to GHCR, and update the
   Docker image to the GHCR registry.
 
-[Unreleased]: https://github.com/vvzvlad/gitmost/compare/v0.94.0...HEAD
-[0.94.0]: https://github.com/vvzvlad/gitmost/compare/v0.93.0...v0.94.0
+[Unreleased]: https://github.com/vvzvlad/gitmost/compare/v0.93.0...HEAD
 [0.93.0]: https://github.com/vvzvlad/gitmost/compare/v0.91.0...v0.93.0
 [0.91.0]: https://github.com/vvzvlad/gitmost/compare/v0.90.1...v0.91.0

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

README.ru.md

@@ -33,7 +33,7 @@
 | --- | --- |
 | **Удалён EE-код** | Вырезан весь код Enterprise-редакции на клиенте и сервере; это чистая community/AGPL-сборка без лицензионных проверок. |
 | **Резолв комментариев** | Переписан с нуля как community-функция (резолв / переоткрытие с вкладками «Открытые» / «Решённые»). EE-код не используется, доступно любому, кто может комментировать. |
-| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 40 инструментов) отдаётся по HTTP на `/mcp` — без enterprise-лицензии. Заменяет удалённый лицензируемый EE MCP. |
+| **Встроенный MCP-сервер** | Community MCP-сервер (`@docmost/mcp`, 39 инструментов) отдаётся по 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`. Он даёт
-**40 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
+**39 agent-native инструментов**: точечное редактирование по блокам (patch / insert / delete
 по id), find/replace с сохранением структуры, скриптовые трансформации `(doc) => doc` с
 предпросмотром диффа, структурное редактирование таблиц, история версий с диффом /
 восстановлением, комментарии, изображения и ссылки на шаринг — всё применяется через слой
@@ -60,7 +60,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 | | **`/mcp` в Gitmost (наш docmost-mcp)** | Родной MCP у Docmost |
 | --- | :---: | :---: |
 | **Enterprise-лицензия** | Не нужна | Нужна |
-| **Инструменты** | 40, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
+| **Инструменты** | 39, agent-native | Примитивные (Markdown, CRUD страниц, замена целиком) |
 | **Правки по блокам / find-replace / скриптовые трансформации** | ✅ | — |
 | **Структурное редактирование таблиц, дифф / восстановление версий** | ✅ | — |
 | **Комментарии, изображения, ссылки на шаринг** | ✅ | — |
@@ -105,7 +105,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 - ✅ **Шаблоны страниц** — пометить страницу шаблоном и вставлять её содержимое живой ссылкой в другие страницы; правки шаблона распространяются на все места вставки (whole-page-транслюзия поверх существующих synced-блоков).
 - ✅ **AI-ассистент на публичных шарах** — анонимный зритель расшаренной страницы может спросить AI-агента, который ищет строго по дереву этой шары (read-only, share-scoped поиск), за тумблером воркспейса.
 - ✅ **Сноски** — сноски академического вида: нумерованная ссылка-надстрочник прямо в тексте (читается на месте во всплывающем окне по наведению), а текст сноски живёт реальным редактируемым блоком внизу страницы; авто-нумерация, безопасна для совместного редактирования, переживает экспорт/импорт Markdown и доступна AI-агенту / MCP.
-- ✅ **Временные заметки** — создайте временную заметку, и она автоматически уедет в корзину по истечении настраиваемого срока жизни (по умолчанию 24 ч); создать такую можно в один клик с домашнего экрана, с обзора любого пространства или из сайдбара пространства.
+- ✅ **Временные заметки** — пометьте заметку временной, и она автоматически уедет в корзину по истечении настраиваемого срока жизни воркспейса (по умолчанию 24 ч), если её предварительно не сделать постоянной; создать такую можно в один клик с домашнего экрана, с обзора любого пространства или из сайдбара пространства, а на открытой заметке есть баннер «Сделать постоянной».
 
 ### В процессе
 
@@ -174,18 +174,14 @@ dump/restore, существующий каталог данных переис
 - Пространства (Spaces)
 - Управление правами доступа
 - Группы
-- Комментарии (с резолвом / переоткрытием и всплывающими подсказками с текстом комментария при наведении)
+- Комментарии (с резолвом / переоткрытием)
 - История страниц
 - Поиск
 - Вложения файлов
 - Встраивания (Airtable, Loom, Miro и другие)
 - Переводы (10+ языков)
 - Встроенный MCP-сервер (`/mcp`)
-- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет); окно чата закрепляется в боковом меню, а агент узнаёт о ваших правках страницы между ходами
-- Кнопки код-блока оверлеем, селектор языка появляется при наведении
-- Кнопка «Ударение» (U+0301) в bubble-меню
-- Позиция чтения (прокрутка) восстанавливается после перезагрузки
-- Slash-меню терпимо к неправильной раскладке (ЙЦУКЕН↔QWERTY)
+- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет)
 
 ### Скриншоты
 

agent-roles-catalog/README.md

@@ -10,23 +10,17 @@ executable application logic except the validation script.
 
 ```
 agent-roles-catalog/
-  index.yaml                  # the catalog manifest: bundles, languages, role versions
+  index.json                  # the catalog manifest: bundles, languages, role versions
   bundles/
     <bundle-id>/
-      <lang>.yaml             # one file per declared language (e.g. ru.yaml, en.yaml)
+      <lang>.json             # one file per declared language (e.g. ru.json, en.json)
   scripts/
-    check.mjs                 # validates the catalog (uses the `yaml` parser)
+    check.mjs                 # validates the catalog (no dependencies)
     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,
@@ -38,8 +32,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.yaml` for the
-manifest and `<base>/bundles/<bundle-id>/<lang>.yaml` for each opened bundle
+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
 file (REMOTE only).
 
 That base URL is provided as a per-branch default in the Docker image (set in
@@ -48,56 +42,54 @@ 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 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.
+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.
 
-## `index.yaml` schema
+## `index.json` schema
 
-```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
-      # ...
+```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 }
+        // ...
+      ]
+    }
+  ]
+}
 ```
 
-`version` lives **here, in index.yaml**, per role. Bump it whenever a role's
+`version` lives **here, in index.json**, per role. Bump it whenever a role's
 content (instructions, name, description, etc.) changes, so consumers can detect
 updates.
 
-## Bundle (`<lang>.yaml`) schema
+## Bundle (`<lang>.json`) schema
 
-```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)
+```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)
+    }
+  ]
+}
 ```
 
-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
@@ -110,39 +102,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.yaml` and `en.yaml`), but no two different bundles may share a slug.
+`ru.json` and `en.json`), 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.yaml` with a new unique
+1. Add an entry to that bundle's `roles[]` in `index.json` with a new unique
    `slug` and `version: 1`.
-2. Add a role object with the same `slug` to **every** `<lang>.yaml` of the
+2. Add a role object with the same `slug` to **every** `<lang>.json` 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.yaml` (`id`, `name`, `description`,
+1. Add a bundle object to `index.json` (`id`, `name`, `description`,
    `languages`, `roles`).
-2. Create `bundles/<id>/<lang>.yaml` for each declared language, with one role
+2. Create `bundles/<id>/<lang>.json` 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.yaml`.
-2. Create `bundles/<id>/<lang>.yaml` containing every role of the 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,
    translated.
 3. Run the check.
 
 ### Change a role's content
 
-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`
+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`
 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.
@@ -168,7 +160,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.yaml` and the bundle `<lang>.yaml` files, never this file, so it has no
+`index.json` and the bundle `<lang>.json` 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
@@ -190,9 +182,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.yaml` version was not bumped, so the
+role's content changed while its `index.json` version was not bumped, so the
 version bump is always enforced first. The check also requires every
-`index.yaml` role to carry a finite numeric `version` (the server requires the
+`index.json` 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

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

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

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

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

@@ -0,0 +1,31 @@
+{
+  "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/index.yaml

@@ -1,36 +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: 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,8 +4,5 @@
   "type": "module",
   "scripts": {
     "check": "node scripts/check.mjs"
-  },
-  "devDependencies": {
-    "yaml": "^2.8.3"
   }
 }

agent-roles-catalog/scripts/check.mjs

@@ -8,14 +8,6 @@ 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, "..");
@@ -31,21 +23,6 @@ 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"));
@@ -55,13 +32,13 @@ function readJson(path) {
   }
 }
 
-const indexPath = join(catalogDir, "index.yaml");
+const indexPath = join(catalogDir, "index.json");
 if (!existsSync(indexPath)) {
-  console.error(`Missing index.yaml at ${indexPath}`);
+  console.error(`Missing index.json at ${indexPath}`);
   process.exit(1);
 }
 
-const index = readYaml(indexPath);
+const index = readJson(indexPath);
 if (!index) {
   for (const e of errors) console.error(e);
   process.exit(1);
@@ -69,7 +46,7 @@ if (!index) {
 
 const bundles = Array.isArray(index.bundles) ? index.bundles : [];
 if (bundles.length === 0) {
-  errors.push("index.yaml has no bundles[]");
+  errors.push("index.json has no bundles[]");
 }
 
 // Track every slug seen across the whole catalog to detect duplicates.
@@ -78,7 +55,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.yaml is missing an id");
+    errors.push("A bundle in index.json is missing an id");
     continue;
   }
 
@@ -86,7 +63,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.yaml roles[] contains duplicate slugs`);
+    errors.push(`Bundle "${bundleId}" index.json roles[] contains duplicate slugs`);
   }
 
   // Each index role must carry a finite numeric "version". The server requires
@@ -95,7 +72,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.yaml role "${r.slug}" is missing a numeric "version"`
+        `Bundle "${bundleId}" index.json role "${r.slug}" is missing a numeric "version"`
       );
     }
   }
@@ -106,13 +83,13 @@ for (const bundle of bundles) {
   }
 
   for (const lang of languages) {
-    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+    const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
     if (!existsSync(langPath)) {
       errors.push(`Bundle "${bundleId}" declares language "${lang}" but ${langPath} is missing`);
       continue;
     }
 
-    const langFile = readYaml(langPath);
+    const langFile = readJson(langPath);
     if (!langFile) continue;
 
     const roles = Array.isArray(langFile.roles) ? langFile.roles : [];
@@ -135,12 +112,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.yaml: ${missingInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" is missing roles declared in index.json: ${missingInFile.join(", ")}`
       );
     }
     if (extraInFile.length > 0) {
       errors.push(
-        `Bundle "${bundleId}/${lang}" has roles not declared in index.yaml: ${extraInFile.join(", ")}`
+        `Bundle "${bundleId}/${lang}" has roles not declared in index.json: ${extraInFile.join(", ")}`
       );
     }
 
@@ -172,7 +149,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.yaml has been bumped and the lock refreshed.
+// version in index.json 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
@@ -181,7 +158,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.yaml, so neither is here.
+// identity (not content) and `version` lives in index.json, 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 —
@@ -210,20 +187,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.yaml roles[]; already flagged above.
+        // Same slug declared twice in index.json roles[]; already flagged above.
         out.get(r.slug).version = r.version;
       }
     }
     for (const lang of languages) {
-      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.yaml`);
+      const langPath = join(catalogDir, "bundles", bundleId, `${lang}.json`);
       if (!existsSync(langPath)) continue;
-      const langFile = readYaml(langPath);
+      const langFile = readJson(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.yaml; flagged above.
+        if (!entry) continue; // role not declared in index.json; flagged above.
         entry.langRoles.set(lang, role);
       }
     }
@@ -276,11 +253,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.yaml "version" is missing or not numeric; set a numeric "version" before refreshing the lock`
+        `role "${slug}" content changed but its index.json "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.yaml before refreshing the lock`
+        `role "${slug}" content changed but its version was not bumped (still ${prev.version}); bump "version" in index.json before refreshing the lock`
       );
     }
   }
@@ -332,10 +309,10 @@ for (const [slug, cur] of current) {
     continue;
   }
   if (cur.hash === prev.hash) {
-    // Content unchanged; the lock version must still agree with index.yaml.
+    // Content unchanged; the lock version must still agree with index.json.
     if (cur.version !== prev.version) {
       errors.push(
-        `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`
+        `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`
       );
     }
     continue;
@@ -346,11 +323,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.yaml "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.json "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.yaml, 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.json, then run: node scripts/check.mjs --update-hashes`
     );
   } else {
     errors.push(

apps/client/index.html

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

apps/client/package.json

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

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

@@ -257,8 +257,6 @@
   "Copy": "Copy",
   "Copy to space": "Copy to space",
   "Copy chat": "Copy chat",
-  "Dock to sidebar": "Dock to sidebar",
-  "Undock": "Undock",
   "Copied": "Copied",
   "Failed to export chat": "Failed to export chat",
   "Duplicate": "Duplicate",
@@ -288,9 +286,6 @@
   "Alt text": "Alt text",
   "Describe this for accessibility.": "Describe this for accessibility.",
   "Add a description": "Add a description",
-  "Caption": "Caption",
-  "Add a caption": "Add a caption",
-  "Shown below the image.": "Shown below the image.",
   "Justify": "Justify",
   "Merge cells": "Merge cells",
   "Split cell": "Split cell",
@@ -357,8 +352,6 @@
   "Underline": "Underline",
   "Strike": "Strike",
   "Code": "Code",
-  "Spoiler": "Spoiler",
-  "Stress": "Stress",
   "Comment": "Comment",
   "Text": "Text",
   "Heading 1": "Heading 1",
@@ -471,6 +464,18 @@
   "Move page": "Move page",
   "Move page to a different space.": "Move page to a different space.",
   "Real-time editor connection lost. Retrying...": "Real-time editor connection lost. Retrying...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Offline — changes are saved locally and will sync when you reconnect",
+  "Syncing changes…": "Syncing changes…",
+  "All changes synced": "All changes synced",
+  "Update available": "Update available",
+  "Reload": "Reload",
+  "Make available offline": "Make available offline",
+  "Saving page for offline use...": "Saving page for offline use...",
+  "Page is now available offline": "Page is now available offline",
+  "Failed to make page available offline": "Failed to make page available offline",
+  "You're offline": "You're offline",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.",
+  "Retry": "Retry",
   "Table of contents": "Table of contents",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Add headings (H1, H2, H3) to generate a table of contents.",
   "Share": "Share",
@@ -1222,8 +1227,8 @@
   "Commented": "Commented",
   "Resolved comment": "Resolved comment",
   "Ran tool {{name}}": "Ran tool {{name}}",
-  "AI agent «{{role}}» on behalf of {{person}}": "AI agent «{{role}}» on behalf of {{person}}",
-  "AI agent {{name}}": "AI agent {{name}}",
+  "AI-agent": "AI-agent",
+  "Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{name}}",
   "Endpoints": "Endpoints",
   "where we fetch models": "where we fetch models",
   "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.",
@@ -1325,7 +1330,6 @@
   "Move to space": "Move to space",
   "Float left (wrap text)": "Float left (wrap text)",
   "Float right (wrap text)": "Float right (wrap text)",
-  "Inline (side by side)": "Inline (side by side)",
   "Switch to tree": "Switch to tree",
   "Switch to flat list": "Switch to flat list",
   "Toggle subpages display mode": "Toggle subpages display mode",

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

@@ -351,8 +351,6 @@
   "Underline": "Подчёркнутый",
   "Strike": "Перечёркнутый",
   "Code": "Код",
-  "Spoiler": "Спойлер",
-  "Stress": "Ударение",
   "Comment": "Комментарий",
   "Text": "Текст",
   "Heading 1": "Заголовок 1",
@@ -476,6 +474,18 @@
   "Move page": "Переместить страницу",
   "Move page to a different space.": "Переместите страницу в другое пространство.",
   "Real-time editor connection lost. Retrying...": "Соединение с редактором в реальном времени потеряно. Повторная попытка...",
+  "Offline — changes are saved locally and will sync when you reconnect": "Нет сети — изменения сохраняются локально и синхронизируются при восстановлении соединения",
+  "Syncing changes…": "Синхронизация изменений…",
+  "All changes synced": "Все изменения синхронизированы",
+  "Update available": "Доступно обновление",
+  "Reload": "Перезагрузить",
+  "Make available offline": "Сделать доступным офлайн",
+  "Saving page for offline use...": "Сохраняем страницу для офлайн-доступа…",
+  "Page is now available offline": "Страница доступна офлайн",
+  "Failed to make page available offline": "Не удалось сделать страницу доступной офлайн",
+  "You're offline": "Вы офлайн",
+  "This page hasn't been saved for offline use, so it can't be loaded right now. Reconnect to the internet and try again.": "Эта страница не была сохранена для офлайн-доступа, поэтому её нельзя загрузить сейчас. Подключитесь к интернету и попробуйте снова.",
+  "Retry": "Повторить",
   "Table of contents": "Оглавление",
   "Add headings (H1, H2, H3) to generate a table of contents.": "Добавьте заголовки (H1, H2, H3), чтобы создать оглавление.",
   "Share": "Поделиться",
@@ -716,16 +726,13 @@
   "Ask the AI agent anything about your workspace.": "Спросите AI-агента о чём угодно по вашему рабочему пространству.",
   "Ask the AI agent…": "Спросите AI-агента…",
   "Copy chat": "Копировать чат",
-  "Dock to sidebar": "Закрепить в боковой панели",
-  "Undock": "Открепить",
   "Created successfully": "Успешно создано",
   "Context size / model limit": "Размер контекста / лимит модели",
   "Context window (tokens)": "Окно контекста (токены)",
   "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
   "Delete this chat?": "Удалить этот чат?",
   "Deleted successfully": "Успешно удалено",
-  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
-  "AI agent {{name}}": "AI-агент {{name}}",
+  "Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
   "Failed to delete chat": "Не удалось удалить чат",
   "Failed to rename chat": "Не удалось переименовать чат",
   "Failed": "Ошибка",
@@ -1179,7 +1186,6 @@
   "Spoken language hint sent to the transcription model. Auto-detect lets the model decide.": "Подсказка языка речи для модели транскрипции. «Автоопределение» оставляет выбор за моделью.",
   "Float left (wrap text)": "Обтекание слева",
   "Float right (wrap text)": "Обтекание справа",
-  "Inline (side by side)": "В ряд",
   "Switch to tree": "Переключить на дерево",
   "Switch to flat list": "Переключить на плоский список",
   "Toggle subpages display mode": "Переключить режим отображения подстраниц",

apps/client/public/manifest.json

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

apps/client/src/components/common/export-modal.tsx

@@ -14,22 +14,6 @@ import { notifications } from "@mantine/notifications";
 import { exportSpace } from "@/features/space/services/space-service";
 import { useTranslation } from "react-i18next";
 
-// The export request uses `responseType: "blob"`, so a server error body arrives
-// as a Blob rather than parsed JSON — `err.response?.data.message` is therefore
-// always undefined. Read and parse the blob to surface the real error message.
-async function extractExportError(err: any): Promise<string> {
-  const data = err?.response?.data;
-  if (data instanceof Blob) {
-    try {
-      const json = JSON.parse(await data.text());
-      return json?.message ?? "";
-    } catch {
-      return "";
-    }
-  }
-  return data?.message ?? err?.message ?? "";
-}
-
 interface ExportModalProps {
   id: string;
   type: "space" | "page";
@@ -68,9 +52,8 @@ export default function ExportModal({
       });
       onClose();
     } catch (err) {
-      const message = await extractExportError(err);
       notifications.show({
-        message: t("Export failed") + (message ? `: ${message}` : ""),
+        message: "Export failed:" + err.response?.data.message,
         color: "red",
       });
       console.error("export error", err);

apps/client/src/components/layouts/global/app-header.tsx

@@ -12,7 +12,6 @@ import TopMenu from "@/components/layouts/global/top-menu.tsx";
 import { Link } from "react-router-dom";
 import { useAtom } from "jotai";
 import {
-  NAVBAR_COLLAPSE_BREAKPOINT,
   desktopSidebarAtom,
   mobileSidebarAtom,
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
@@ -54,13 +53,7 @@ export function AppHeader() {
               aria-label={t("Sidebar toggle")}
               opened={mobileOpened}
               onClick={toggleMobile}
-              // Must match the AppShell navbar breakpoint (md). The navbar
-              // collapses to the MOBILE drawer below md, so the mobile toggle
-              // (which flips mobileOpened) must be the one visible across the
-              // whole <md band — otherwise at 768-991 the desktop toggle showed
-              // but flipped the wrong atom, leaving the drawer unopenable (the
-              // regression from the initial sm->md navbar change).
-              hiddenFrom={NAVBAR_COLLAPSE_BREAKPOINT}
+              hiddenFrom="sm"
               size="sm"
             />
           </Tooltip>
@@ -70,7 +63,7 @@ export function AppHeader() {
               aria-label={t("Sidebar toggle")}
               opened={desktopOpened}
               onClick={toggleDesktop}
-              visibleFrom={NAVBAR_COLLAPSE_BREAKPOINT}
+              visibleFrom="sm"
               size="sm"
             />
           </Tooltip>

apps/client/src/components/layouts/global/global-app-shell.tsx

@@ -5,8 +5,6 @@ import { useTranslation } from "react-i18next";
 import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
 import { useAtom } from "jotai";
 import {
-  APP_NAVBAR_ID,
-  NAVBAR_COLLAPSE_BREAKPOINT,
   asideStateAtom,
   desktopSidebarAtom,
   mobileSidebarAtom,
@@ -89,13 +87,7 @@ export default function GlobalAppShell({
       header={{ height: 45 }}
       navbar={{
         width: isSpaceRoute ? sidebarWidth : 300,
-        // `md` (not `sm`): below 992px the fixed ~300px sidebar leaves too little
-        // room for content — the settings tables (Members/…) overflow the offset
-        // content area on tablet (~768px) and clip the Role/actions columns
-        // off-screen with no horizontal scroll. Collapsing the navbar to a toggle
-        // drawer across the whole tablet band frees the full width for content
-        // (the mobile drawer is closed by default, so nothing overlaps on load).
-        breakpoint: NAVBAR_COLLAPSE_BREAKPOINT,
+        breakpoint: "sm",
         collapsed: {
           mobile: !mobileOpened,
           desktop: !desktopOpened,
@@ -104,7 +96,7 @@ export default function GlobalAppShell({
       aside={
         isPageRoute && {
           width: 420,
-          breakpoint: "md",
+          breakpoint: "sm",
           collapsed: { mobile: !isAsideOpen, desktop: !isAsideOpen },
         }
       }
@@ -114,7 +106,6 @@ export default function GlobalAppShell({
         <AppHeader />
       </AppShell.Header>
       <AppShell.Navbar
-        id={APP_NAVBAR_ID}
         className={classes.navbar}
         withBorder={false}
         ref={sidebarRef}

apps/client/src/components/layouts/global/hooks/atoms/sidebar-atom.ts

@@ -1,19 +1,6 @@
 import { atomWithWebStorage } from "@/lib/jotai-helper.ts";
 import { atom } from "jotai";
 
-// Stable DOM id set on the app-shell navbar (<AppShell.Navbar>). Declared here —
-// alongside the sidebar atoms — rather than in the chat window so the AI chat
-// window can reference the navbar by id without importing the app shell (which
-// would create a shell -> chat-window -> shell import cycle).
-export const APP_NAVBAR_ID = "app-shell-navbar";
-
-// Single source of truth for the navbar collapse breakpoint. The AppShell navbar
-// `breakpoint` and BOTH burger toggles' `hiddenFrom`/`visibleFrom` MUST use this
-// exact value: if they drift, the sidebar becomes unreachable on tablet widths
-// (the round-1 regression of #292). Kept here so the shell and the header share
-// one constant the compiler enforces, instead of three hand-synced string literals.
-export const NAVBAR_COLLAPSE_BREAKPOINT = "md";
-
 export const mobileSidebarAtom = atom<boolean>(false);
 
 export const desktopSidebarAtom = atomWithWebStorage<boolean>(

apps/client/src/components/ui/agent-avatar-stack.test.tsx

@@ -1,136 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent } from "@testing-library/react";
-import { MantineProvider } from "@mantine/core";
-import { Provider, createStore } from "jotai";
-import { AgentAvatarStack, agentGlyphBackground } from "./agent-avatar-stack";
-import {
-  activeAiChatIdAtom,
-  aiChatWindowOpenAtom,
-  aiChatDraftAtom,
-} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
-
-// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
-
-type Props = React.ComponentProps<typeof AgentAvatarStack>;
-
-function renderStack(props: Props) {
-  const store = createStore();
-  store.set(aiChatDraftAtom, "leftover draft from another chat");
-  const utils = render(
-    <Provider store={store}>
-      <MantineProvider>
-        <AgentAvatarStack {...props} />
-      </MantineProvider>
-    </Provider>,
-  );
-  return { store, ...utils };
-}
-
-describe("agentGlyphBackground", () => {
-  it("is deterministic for a given agent name", () => {
-    expect(agentGlyphBackground("Researcher")).toBe(
-      agentGlyphBackground("Researcher"),
-    );
-  });
-
-  it("differs by name and stays a fixed dark shade (readable emoji)", () => {
-    expect(agentGlyphBackground("Researcher")).not.toBe(
-      agentGlyphBackground("Нарратор"),
-    );
-    // Only the hue varies; saturation/lightness are pinned low so the glyph is
-    // always a dark circle.
-    expect(agentGlyphBackground("Нарратор")).toMatch(/^hsl\(\d+, 45%, 24%\)$/);
-  });
-});
-
-describe("AgentAvatarStack", () => {
-  it("internal chat WITH role: emoji glyph in front + human launcher behind", () => {
-    const { container } = renderStack({
-      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
-      launcher: { name: "Alice", avatarUrl: null },
-      aiChatId: "chat-1",
-    });
-
-    // Emoji is used as the glyph (priority 2), NOT the sparkles fallback.
-    expect(screen.getByText("🔬")).toBeDefined();
-    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
-    // Label: bold role name + dimmed "· launcher".
-    expect(screen.getByText("Researcher")).toBeDefined();
-    expect(screen.getByText(/·/)).toBeDefined();
-    expect(screen.getByText("Alice")).toBeDefined();
-  });
-
-  it("showName=false: renders only the avatars, no inline name label", () => {
-    renderStack({
-      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
-      launcher: { name: "Alice", avatarUrl: null },
-      aiChatId: "chat-1",
-      showName: false,
-    });
-
-    // The agent glyph is still rendered...
-    expect(screen.getByText("🔬")).toBeDefined();
-    // ...but neither the agent NOR the launcher inline name label is rendered
-    // (they live only in the hover tooltip, which is not mounted in the initial
-    // DOM) — guards against suppressing only the agent name and leaking the
-    // launcher name.
-    expect(screen.queryByText("Researcher")).toBeNull();
-    expect(screen.queryByText("Alice")).toBeNull();
-  });
-
-  it("internal chat WITHOUT role: sparkles fallback + 'AI agent' + launcher", () => {
-    const { container } = renderStack({
-      agent: { name: "AI agent", avatarUrl: null },
-      launcher: { name: "Bob", avatarUrl: null },
-      aiChatId: "chat-2",
-    });
-
-    // No avatarUrl and no emoji => sparkles glyph (priority 3).
-    expect(container.querySelector(".tabler-icon-sparkles")).not.toBeNull();
-    expect(screen.getByText("AI agent")).toBeDefined();
-    expect(screen.getByText("Bob")).toBeDefined();
-  });
-
-  it("external MCP: agent avatar in front, NO launcher behind", () => {
-    const { container } = renderStack({
-      agent: { name: "MCP Bot", avatarUrl: "http://example.test/a.png" },
-      launcher: null,
-      aiChatId: null,
-    });
-
-    // avatarUrl provided (priority 1) => not the sparkles fallback.
-    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
-    expect(screen.getByText("MCP Bot")).toBeDefined();
-    // No human behind => no "·" separator is rendered.
-    expect(screen.queryByText(/·/)).toBeNull();
-    // No internal chat => the stack is not an interactive deep-link button.
-    expect(screen.queryByRole("button")).toBeNull();
-  });
-
-  it("click deep-links into the chat when aiChatId is present", () => {
-    const { store } = renderStack({
-      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
-      launcher: { name: "Alice", avatarUrl: null },
-      aiChatId: "chat-1",
-    });
-
-    const button = screen.getByRole("button");
-    fireEvent.click(button);
-
-    expect(store.get(activeAiChatIdAtom)).toBe("chat-1");
-    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
-    expect(store.get(aiChatDraftAtom)).toBe(""); // draft cleared on switch
-  });
-
-  it("click is a no-op / not interactive without a chat target", () => {
-    const onActivate = vi.fn();
-    renderStack({
-      agent: { name: "MCP Bot", avatarUrl: "http://example.test/a.png" },
-      launcher: null,
-      aiChatId: null,
-      onActivate,
-    });
-    expect(screen.queryByRole("button")).toBeNull();
-    expect(onActivate).not.toHaveBeenCalled();
-  });
-});

apps/client/src/components/ui/agent-avatar-stack.tsx

@@ -1,238 +0,0 @@
-import { Avatar, Box, Group, Text, Tooltip } from "@mantine/core";
-import { IconSparkles } from "@tabler/icons-react";
-import { useCallback } from "react";
-import { useTranslation } from "react-i18next";
-import { useSetAtom } from "jotai";
-import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
-import {
-  activeAiChatIdAtom,
-  aiChatWindowOpenAtom,
-  aiChatDraftAtom,
-} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
-
-// The FRONT identity (the acting agent) and the BEHIND identity (the human who
-// launched it). Both are computed server-side (#300) so the client never branches
-// on the internal-vs-MCP provenance — it just renders whatever it is handed.
-export interface AgentInfo {
-  name: string;
-  emoji?: string | null;
-  avatarUrl?: string | null;
-}
-export interface LauncherInfo {
-  name: string;
-  avatarUrl?: string | null;
-}
-
-const GLYPH_SIZE = 38;
-const LAUNCHER_SIZE = 22;
-// How far the launcher avatar sticks out past the agent's top-right corner, so
-// the "human behind" reads as behind (lower z-index) yet stays clearly visible.
-const LAUNCHER_OVERHANG = 8;
-
-// Small deterministic string hash (same algorithm as custom-avatar's initials
-// hash) used to pick a stable per-agent glyph color.
-function hashName(input: string): number {
-  let hash = 0;
-  for (let i = 0; i < input.length; i += 1) {
-    hash = (hash << 5) - hash + input.charCodeAt(i);
-    hash |= 0;
-  }
-  return Math.abs(hash);
-}
-
-/**
- * Deterministic DARK background for an emoji/sparkles agent glyph. The hue is
- * derived from the agent-name hash so distinct agents get distinct circles;
- * saturation and lightness are pinned low ("shifted into darkness") so a bright
- * emoji or the white sparkles icon stays legible on top (#300).
- */
-export function agentGlyphBackground(name: string): string {
-  const hue = hashName(name) % 360;
-  return `hsl(${hue}, 45%, 24%)`;
-}
-
-/**
- * The front avatar. Image-source priority (#300):
- *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
- *   2. agent.emoji     -> the role emoji on a violet circle.
- *   3. otherwise       -> the IconSparkles glyph on a violet circle (fallback).
- */
-function AgentGlyph({ agent }: { agent: AgentInfo }) {
-  if (agent.avatarUrl) {
-    return (
-      <CustomAvatar
-        size={GLYPH_SIZE}
-        avatarUrl={agent.avatarUrl}
-        name={agent.name}
-      />
-    );
-  }
-
-  // Emoji/sparkles glyphs sit on a per-agent dark circle (hashed from the agent
-  // name) so different agents are visually distinct, while the dark background
-  // keeps the emoji / white sparkles icon readable.
-  const bg = agentGlyphBackground(agent.name);
-  const glyphStyles = {
-    root: { background: bg },
-    placeholder: { background: bg, color: "var(--mantine-color-white)" },
-  };
-
-  if (agent.emoji) {
-    return (
-      <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
-        <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
-          {agent.emoji}
-        </span>
-      </Avatar>
-    );
-  }
-
-  return (
-    <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
-      <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
-    </Avatar>
-  );
-}
-
-export interface AgentAvatarStackProps {
-  agent: AgentInfo;
-  // null/absent => external MCP (front agent avatar only, no human behind).
-  launcher?: LauncherInfo | null;
-  // Deep-links into the internal AI chat when present (null for external MCP).
-  aiChatId?: string | null;
-  // Fired after the stack deep-links into its chat, so the caller can react
-  // (e.g. the page-history row closes the history modal). Keeps this ui/ primitive
-  // free of cross-feature coupling (inherited from the old AiAgentBadge, #143).
-  onActivate?: () => void;
-  // Whether to render the inline name label next to the avatars (default true).
-  // Set false when the caller renders the name itself (e.g. the comment row).
-  showName?: boolean;
-}
-
-/**
- * The "agent avatar stack" (#300): the AGENT glyph in front, and — for an
- * internal AI chat — the HUMAN who launched it as a smaller avatar offset behind.
- * Replaces the old text `AI-agent` badge. When the item carries an `aiChatId` the
- * whole stack is a deep-link into that chat (the click the old badge owned moved
- * here); the click is contained (stopPropagation) so it does not also trigger an
- * enclosing row handler.
- */
-export function AgentAvatarStack({
-  agent,
-  launcher,
-  aiChatId,
-  onActivate,
-  showName = true,
-}: AgentAvatarStackProps) {
-  const { t } = useTranslation();
-  const setAiChatWindowOpen = useSetAtom(aiChatWindowOpenAtom);
-  const setActiveChatId = useSetAtom(activeAiChatIdAtom);
-  const setDraft = useSetAtom(aiChatDraftAtom);
-
-  const clickable = !!aiChatId;
-
-  const openChat = useCallback(
-    (event: React.SyntheticEvent) => {
-      event.stopPropagation();
-      if (!aiChatId) return;
-      setActiveChatId(aiChatId);
-      // Switching chats must start with a clean composer — clear any unsent draft
-      // so it does not leak from the previously open chat.
-      setDraft("");
-      setAiChatWindowOpen(true);
-      onActivate?.();
-    },
-    [aiChatId, setActiveChatId, setDraft, setAiChatWindowOpen, onActivate],
-  );
-
-  // Internal chat => "role on behalf of person"; external MCP => just the agent.
-  const tooltip = launcher
-    ? t("AI agent «{{role}}» on behalf of {{person}}", {
-        role: agent.name,
-        person: launcher.name,
-      })
-    : t("AI agent {{name}}", { name: agent.name });
-
-  // The container is only enlarged when there is a launcher to overhang; with no
-  // human behind it stays tight at the agent glyph size.
-  const stackSize = launcher ? GLYPH_SIZE + LAUNCHER_OVERHANG : GLYPH_SIZE;
-
-  const stack = (
-    <Box
-      pos="relative"
-      style={{
-        width: stackSize,
-        height: stackSize,
-        flexShrink: 0,
-        // Center the (in-flow) agent glyph vertically so it lines up with its
-        // name label; the absolutely-positioned launcher is unaffected by flex.
-        display: "flex",
-        alignItems: "center",
-        cursor: clickable ? "pointer" : undefined,
-      }}
-      {...(clickable
-        ? {
-            role: "button",
-            tabIndex: 0,
-            onClick: openChat,
-            onKeyDown: (event: React.KeyboardEvent) => {
-              if (event.key === "Enter" || event.key === " ") {
-                event.preventDefault();
-                openChat(event);
-              }
-            },
-          }
-        : {})}
-    >
-      {launcher && (
-        <Box pos="absolute" top={0} right={0} style={{ zIndex: 0 }}>
-          <CustomAvatar
-            size={LAUNCHER_SIZE}
-            avatarUrl={launcher.avatarUrl}
-            name={launcher.name}
-            style={{ border: "2px solid var(--mantine-color-body)" }}
-          />
-        </Box>
-      )}
-      {/* The agent glyph keeps its own size (flex-centered in the container); the
-          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
-      <Box
-        style={{
-          position: "relative",
-          zIndex: 1,
-          width: GLYPH_SIZE,
-          height: GLYPH_SIZE,
-        }}
-      >
-        <AgentGlyph agent={agent} />
-      </Box>
-    </Box>
-  );
-
-  return (
-    <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
-      <Tooltip label={tooltip} withArrow>
-        {stack}
-      </Tooltip>
-      {showName && (
-        <Group gap={4} wrap="nowrap" style={{ minWidth: 0 }}>
-          <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
-            {agent.name}
-          </Text>
-          {launcher && (
-            <>
-              <Text size="xs" c="dimmed" fw={400} aria-hidden>
-                ·
-              </Text>
-              <Text size="xs" c="dimmed" fw={400} lineClamp={1} lh={1.2}>
-                {launcher.name}
-              </Text>
-            </>
-          )}
-        </Group>
-      )}
-    </Group>
-  );
-}
-
-export default AgentAvatarStack;

apps/client/src/components/ui/ai-agent-badge.test.tsx

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { Provider, createStore } from "jotai";
+import { AiAgentBadge } from "./ai-agent-badge";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+function renderBadge(props: { authorName?: string; aiChatId?: string | null }) {
+  return render(
+    <MantineProvider>
+      <AiAgentBadge {...props} />
+    </MantineProvider>,
+  );
+}
+
+// Render a clickable badge inside an explicit jotai store, with a leftover draft
+// and an onActivate + parent-click spy, so the deep-link side effects are
+// assertable. Returns the store and spies.
+function setupClickable() {
+  const store = createStore();
+  store.set(aiChatDraftAtom, "leftover draft from another chat");
+  const onActivate = vi.fn();
+  const onParentClick = vi.fn();
+  render(
+    <Provider store={store}>
+      <MantineProvider>
+        <div onClick={onParentClick}>
+          <AiAgentBadge authorName="Bot" aiChatId="chat-1" onActivate={onActivate} />
+        </div>
+      </MantineProvider>
+    </Provider>,
+  );
+  return { store, onActivate, onParentClick, badge: screen.getByRole("button") };
+}
+
+function expectDeepLinked(store: ReturnType<typeof createStore>, onActivate: ReturnType<typeof vi.fn>) {
+  expect(store.get(activeAiChatIdAtom)).toBe("chat-1");
+  expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+  expect(store.get(aiChatDraftAtom)).toBe(""); // draft cleared
+  expect(onActivate).toHaveBeenCalledTimes(1); // caller closes its own modal etc.
+}
+
+describe("AiAgentBadge", () => {
+  it("renders the AI-agent label", () => {
+    renderBadge({ authorName: "Bot" });
+    expect(screen.getByText("AI-agent")).toBeDefined();
+  });
+
+  it("is clickable (accessible button) when aiChatId is present", () => {
+    renderBadge({ authorName: "Bot", aiChatId: "chat-1" });
+    const badge = screen.getByRole("button");
+    expect(badge).toBeDefined();
+    expect(badge.textContent).toContain("AI-agent");
+  });
+
+  it("click deep-links: sets active chat, clears draft, opens window, fires onActivate, stops propagation", () => {
+    const { store, onActivate, onParentClick, badge } = setupClickable();
+    fireEvent.click(badge);
+    expectDeepLinked(store, onActivate);
+    expect(onParentClick).not.toHaveBeenCalled(); // stopPropagation contained the click
+  });
+
+  it.each(["Enter", " "])(
+    "keyboard %j activates the deep-link (same side effects as click)",
+    (key) => {
+      const { store, onActivate, badge } = setupClickable();
+      fireEvent.keyDown(badge, { key });
+      expectDeepLinked(store, onActivate);
+    },
+  );
+
+  it("an unrelated key does NOT activate the badge", () => {
+    const { store, onActivate, badge } = setupClickable();
+    fireEvent.keyDown(badge, { key: "Tab" });
+    expect(store.get(activeAiChatIdAtom)).toBeNull();
+    expect(store.get(aiChatWindowOpenAtom)).toBe(false);
+    expect(store.get(aiChatDraftAtom)).toBe("leftover draft from another chat");
+    expect(onActivate).not.toHaveBeenCalled();
+  });
+
+  it.each([{ aiChatId: null }, {}])(
+    "is a plain non-clickable label without a chat target (%o)",
+    (props) => {
+      renderBadge({ authorName: "Bot", ...props });
+      expect(screen.getByText("AI-agent")).toBeDefined();
+      // No interactive role is exposed when there is no chat to deep-link into.
+      expect(screen.queryByRole("button")).toBeNull();
+    },
+  );
+});

apps/client/src/components/ui/ai-agent-badge.tsx

@@ -0,0 +1,99 @@
+import { Badge, Tooltip } from "@mantine/core";
+import { IconSparkles } from "@tabler/icons-react";
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { useSetAtom } from "jotai";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+interface AiAgentBadgeProps {
+  authorName?: string;
+  aiChatId?: string | null;
+  // Fired after the badge deep-links into its chat. The caller handles its own
+  // context (e.g. the page-history row closes the history modal) so this generic
+  // ui/ primitive stays free of cross-feature coupling (#143 review Arch B).
+  onActivate?: () => void;
+}
+
+/**
+ * Badge marking content written by the AI agent (provenance C3 / §7.4). It is
+ * ADDITIVE — shown next to the human author, never replacing them. Reused by the
+ * page-history list and the comments sidebar.
+ *
+ * When the item carries an `aiChatId` (an internal AI-chat edit), clicking the
+ * badge deep-links into that chat: it sets the active-chat atom and opens the
+ * floating AI-chat window, then invokes `onActivate` so the caller can react
+ * (e.g. the history modal closes itself). When `aiChatId` is null/absent (an
+ * external MCP write with no internal ai_chats row), the badge is a plain
+ * non-clickable label. The click is contained (stopPropagation) so it does not
+ * also trigger an enclosing row's click handler.
+ */
+export function AiAgentBadge({
+  authorName,
+  aiChatId,
+  onActivate,
+}: AiAgentBadgeProps) {
+  const { t } = useTranslation();
+  const setAiChatWindowOpen = useSetAtom(aiChatWindowOpenAtom);
+  const setActiveChatId = useSetAtom(activeAiChatIdAtom);
+  const setDraft = useSetAtom(aiChatDraftAtom);
+
+  const tooltip = t("Edited by AI agent on behalf of {{name}}", {
+    name: authorName ?? "",
+  });
+
+  const openChat = useCallback(
+    (event: React.SyntheticEvent) => {
+      event.stopPropagation();
+      if (!aiChatId) return;
+      setActiveChatId(aiChatId);
+      // Switching to another chat must start with a clean composer — clear any
+      // unsent draft so it does not leak from the previously open chat.
+      setDraft("");
+      setAiChatWindowOpen(true);
+      onActivate?.();
+    },
+    [aiChatId, setActiveChatId, setDraft, setAiChatWindowOpen, onActivate],
+  );
+
+  const badge = (
+    <Badge
+      size="sm"
+      variant="light"
+      color="violet"
+      radius="sm"
+      leftSection={<IconSparkles size={12} stroke={2} />}
+      style={aiChatId ? { cursor: "pointer" } : undefined}
+      {...(aiChatId
+        ? {
+            // Keep the default Badge root element (not a <button>) to avoid an
+            // invalid <button>-in-<button> nesting inside a row's
+            // UnstyledButton; expose it as an accessible button via
+            // role/keyboard.
+            role: "button",
+            tabIndex: 0,
+            onClick: openChat,
+            onKeyDown: (event: React.KeyboardEvent) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                openChat(event);
+              }
+            },
+          }
+        : {})}
+    >
+      {t("AI-agent")}
+    </Badge>
+  );
+
+  return (
+    <Tooltip label={tooltip} withArrow>
+      {badge}
+    </Tooltip>
+  );
+}
+
+export default AiAgentBadge;

apps/client/src/features/ai-chat/atoms/ai-chat-atom.ts

@@ -18,18 +18,6 @@ export const aiChatWindowGeomAtom = atomWithStorage<AiChatWindowGeom | null>(
   null,
 );
 
-/**
- * Whether the AI chat window is docked into the sidebar (page-tree navbar).
- * Persisted to localStorage so the docked/floating mode survives a full page
- * reload and close/reopen. `false` = the default floating window. When docked,
- * the SAME window instance pins itself to the live bounding rect of the app
- * navbar (see AiChatWindow), overlaying the page tree.
- */
-export const aiChatWindowDockedAtom = atomWithStorage<boolean>(
-  "ai-chat-window-docked",
-  false,
-);
-
 /**
  * The currently selected chat id. `null` means a fresh (not-yet-created) chat:
  * the server creates the chat row on the first streamed message and echoes its

apps/client/src/features/ai-chat/components/ai-chat-window.module.css

@@ -35,35 +35,6 @@
     background: transparent;
 }
 
-/* Docked into the sidebar: the window pins itself to the live navbar rect
-   (position/size supplied inline). It sits flush inside the navbar area, so we
-   drop the floating chrome — no border-radius, drop shadow or user resize — and
-   remove the floating min/max clamps so the size is driven ENTIRELY by the
-   inline navbar rect (which may be narrower than the floating min-width of
-   300px, e.g. the 220px navbar minimum). z-index 105 keeps it above the page
-   tree (navbar 101) but below the header and Mantine overlays. */
-.docked {
-    border-radius: 0;
-    box-shadow: none;
-    resize: none;
-    min-width: 0;
-    min-height: 0;
-    max-width: none;
-    max-height: none;
-}
-
-/* Drop-zone highlight shown over the navbar bounds while a floating window is
-   dragged onto the sidebar. Sits just above the docked window (106) so the cue
-   is visible; purely decorative, so it never intercepts pointer events. */
-.dockHighlight {
-    position: fixed;
-    z-index: 106;
-    border: 2px dashed light-dark(var(--mantine-color-blue-5), var(--mantine-color-blue-4));
-    background: light-dark(rgba(34, 139, 230, 0.08), rgba(34, 139, 230, 0.14));
-    border-radius: var(--mantine-radius-sm);
-    pointer-events: none;
-}
-
 /* When minimized the window collapses to the header only: auto height, no
    resize. Width/height inline values are overridden. */
 .minimized {

apps/client/src/features/ai-chat/components/ai-chat-window.tsx

@@ -13,29 +13,21 @@ import {
   IconChevronDown,
   IconCopy,
   IconGripVertical,
-  IconLayoutSidebarLeftCollapse,
-  IconLayoutSidebarLeftExpand,
   IconMinus,
   IconPlus,
   IconX,
 } from "@tabler/icons-react";
 import { useAtom, useSetAtom } from "jotai";
-import { useLocation, useMatch } from "react-router-dom";
+import { useMatch } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { useQueryClient } from "@tanstack/react-query";
 import {
   activeAiChatIdAtom,
   aiChatWindowOpenAtom,
   aiChatWindowGeomAtom,
-  aiChatWindowDockedAtom,
   aiChatDraftAtom,
   selectedAiRoleIdAtom,
 } from "@/features/ai-chat/atoms/ai-chat-atom.ts";
-import {
-  APP_NAVBAR_ID,
-  desktopSidebarAtom,
-  mobileSidebarAtom,
-} from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
 import { usePageQuery } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import {
@@ -54,11 +46,6 @@ import {
   isHeaderClick,
 } from "@/features/ai-chat/utils/collapse-helpers.ts";
 import { selectContextBadge } from "@/features/ai-chat/utils/context-badge.ts";
-import {
-  isPointWithinRect,
-  isNavbarRectVisible,
-  type NavbarRect,
-} from "@/features/ai-chat/utils/dock-helpers.ts";
 import { useClipboard } from "@/hooks/use-clipboard";
 import { notifications } from "@mantine/notifications";
 import classes from "@/features/ai-chat/components/ai-chat-window.module.css";
@@ -125,28 +112,6 @@ function clampGeom(g: {
   };
 }
 
-// Live bounding rect of the app-shell navbar (the page-tree sidebar), by its
-// stable id. Returns null when the navbar is absent OR collapsed: Mantine
-// collapses the navbar by translating it off-screen (its right edge lands at or
-// left of the viewport), so a zero-size or off-screen rect is treated as "no
-// navbar" — the docked window then falls back to floating instead of pinning to
-// an off-screen box. Reads the DOM, so call it inside effects / handlers only.
-function getNavbarRect(): NavbarRect | null {
-  const el = document.getElementById(APP_NAVBAR_ID);
-  if (!el) return null;
-  const r = el.getBoundingClientRect();
-  // Off-screen/collapsed navbar (visibility predicate extracted + unit-tested).
-  if (!isNavbarRectVisible(r)) return null;
-  return { left: r.left, top: r.top, width: r.width, height: r.height };
-}
-
-// Whether a viewport point falls within the (visible) navbar bounds. Used to
-// decide dock-on-drop and undock-on-drag-out. The point-in-rect math is the pure
-// isPointWithinRect helper (unit-tested); this only supplies the live rect.
-function isPointerOverNavbar(x: number, y: number): boolean {
-  return isPointWithinRect(x, y, getNavbarRect());
-}
-
 /**
  * Floating, draggable, resizable, minimizable AI chat window. Replaces the
  * former right-aside `AiChatPanel`: it owns ALL chat orchestration (active
@@ -173,43 +138,6 @@ export default function AiChatWindow() {
   const minimizedRef = useRef(minimized);
   minimizedRef.current = minimized;
 
-  // Docked-into-sidebar mode (#276). Persisted so it survives reload + reopen.
-  // When docked the SAME window instance pins itself to the navbar rect below.
-  const [docked, setDocked] = useAtom(aiChatWindowDockedAtom);
-  // Mirror for the useCallback([]) drag handlers (same reason as minimizedRef).
-  const dockedRef = useRef(docked);
-  dockedRef.current = docked;
-  // Live navbar rect the docked window is pinned to; synced before paint by the
-  // layout effect below. null = navbar absent/collapsed -> floating fallback.
-  const [dockRect, setDockRect] = useState<NavbarRect | null>(null);
-  // While dragging a FLOATING window over the navbar: show the drop-zone hint.
-  const [dockHint, setDockHint] = useState(false);
-  // Live window position during a drag. Normally the drag is fully imperative
-  // (el.style updated per mousemove, no re-render — matching the pre-#276
-  // behavior), so this stays null. It is set ONLY at a navbar-boundary crossing:
-  // that crossing already forces a re-render (dockHint flips), which would
-  // otherwise re-apply the committed geom and snap the box back for a frame — so
-  // we hand the render the live position at that instant instead. Cleared on drop.
-  const [dragPos, setDragPos] = useState<{ left: number; top: number } | null>(
-    null,
-  );
-
-  // Subscribed (read-only) so this component re-renders — and the dockRect-sync
-  // effect below re-runs — when the sidebar is collapsed/expanded via the header
-  // toggle. Mantine collapses the navbar with a transform (width/border-box
-  // unchanged), so the navbar's ResizeObserver never fires; these deps + the
-  // navbar `transitionend` listener are what re-measure the rect on toggle.
-  const [desktopSidebarOpen] = useAtom(desktopSidebarAtom);
-  const [mobileSidebarOpen] = useAtom(mobileSidebarAtom);
-
-  // Dock mode is only EFFECTIVE when a navbar rect is available. When docked but
-  // the navbar is absent/collapsed (dockRect === null) the window falls back to
-  // the floating look, so effects gated on "is docked" must use this — not the
-  // raw `docked` flag — or a fallback-floating window would behave half-docked.
-  const useDock = docked && dockRect !== null;
-
-  const location = useLocation();
-
   const winRef = useRef<HTMLDivElement>(null);
   // Live window geometry (position + size); persisted to localStorage so a
   // drag/resize survives a full page reload (and close/reopen). `null` means
@@ -397,47 +325,6 @@ export default function AiChatWindow() {
     setMinimized(false);
   }, [windowOpen]);
 
-  // While docked, keep the window pinned to the navbar's LIVE rect. useLayoutEffect
-  // (not useEffect) so dockRect is measured/committed before the browser paints,
-  // avoiding a first-frame jump. Re-measures on: navbar size changes (manual
-  // sidebar resize -> ResizeObserver), viewport resize (window `resize`), and
-  // route changes that swap the navbar width (space <-> shared/global sidebar are
-  // 300px vs sidebarWidth -> re-run on location.pathname). If the navbar is
-  // absent/collapsed, getNavbarRect() returns null and the render falls back to
-  // the floating look (the window does NOT vanish).
-  useLayoutEffect(() => {
-    if (!windowOpen || !docked) return;
-    const sync = () => setDockRect(getNavbarRect());
-    sync();
-    const navbar = document.getElementById(APP_NAVBAR_ID);
-    let ro: ResizeObserver | null = null;
-    if (navbar) {
-      ro = new ResizeObserver(sync);
-      ro.observe(navbar);
-      // Collapsing/expanding the sidebar translates the navbar off-screen WITHOUT
-      // changing its width/border-box, so the ResizeObserver never fires and the
-      // effect's initial sync() may measure mid-transition (stale). Re-measure at
-      // transitionend so getNavbarRect() sees the final position: null once the
-      // navbar is translated off (right <= 0) -> fall back to floating; the real
-      // rect once it slides back -> re-dock. The sidebar-state deps below force
-      // this effect (and the immediate sync) to re-run on each toggle, covering
-      // the reduced-motion case where no transition -> no transitionend.
-      navbar.addEventListener("transitionend", sync);
-    }
-    window.addEventListener("resize", sync);
-    return () => {
-      ro?.disconnect();
-      navbar?.removeEventListener("transitionend", sync);
-      window.removeEventListener("resize", sync);
-    };
-  }, [
-    windowOpen,
-    docked,
-    location.pathname,
-    desktopSidebarOpen,
-    mobileSidebarOpen,
-  ]);
-
   // Auto-collapse the window into its header as soon as the user interacts with
   // anything outside it (clicks the page/editor). Armed ONLY while the window is
   // open and expanded, so it never fires repeatedly and never collapses on the
@@ -446,12 +333,7 @@ export default function AiChatWindow() {
   // (shouldCollapseOnOutsidePointer) prevent false collapses from clicks inside
   // the window or inside Mantine portals (kebab menu, delete-confirm modal).
   useEffect(() => {
-    // Disabled while EFFECTIVELY docked: a docked window intentionally overlays
-    // the page tree, so a click on the surrounding page must NOT auto-collapse
-    // it. Gated on useDock (not raw `docked`) so a fallback-floating window
-    // (docked but navbar absent/collapsed) still auto-collapses like a normal
-    // floating window.
-    if (!windowOpen || minimized || useDock) return;
+    if (!windowOpen || minimized) return;
     const onPointerDown = (e: MouseEvent): void => {
       if (shouldCollapseOnOutsidePointer(e.target, winRef.current)) {
         setMinimized(true);
@@ -459,18 +341,13 @@ export default function AiChatWindow() {
     };
     document.addEventListener("mousedown", onPointerDown, true);
     return () => document.removeEventListener("mousedown", onPointerDown, true);
-  }, [windowOpen, minimized, useDock]);
+  }, [windowOpen, minimized]);
 
   // Persist the user's resize into state so it survives close/reopen. Skipped
   // while minimized so the collapsed (auto) height is never captured. The
   // equality guard avoids an update loop.
   useEffect(() => {
-    // Disabled while EFFECTIVELY docked: in dock mode the size is driven by the
-    // navbar rect, not a user resize, so we must not capture the navbar-sized box
-    // into the persisted floating geom (it would clobber the remembered floating
-    // size). Gated on useDock so a fallback-floating window (docked but navbar
-    // absent) still persists user resizes like a normal floating window.
-    if (!windowOpen || minimized || useDock) return;
+    if (!windowOpen || minimized) return;
     const el = winRef.current;
     // `geom` is in the deps so this re-runs once geometry is settled and the
     // window is actually rendered (on the first open `geom` is still null on the
@@ -488,30 +365,18 @@ export default function AiChatWindow() {
     });
     ro.observe(el);
     return () => ro.disconnect();
-  }, [windowOpen, minimized, useDock, geom !== null]);
+  }, [windowOpen, minimized, geom !== null]);
 
   const startDrag = useCallback((e: React.MouseEvent): void => {
-    // Ignore drags that originate on a button (dock/minimize/close/new chat).
+    // Ignore drags that originate on a button (minimize/close/new chat).
     if ((e.target as HTMLElement).closest("button")) return;
     const el = winRef.current;
     if (!el) return;
 
     const sx = e.clientX;
     const sy = e.clientY;
-    // Starting position: the element's current inline left/top, whether it was
-    // placed by the floating geom or pinned to the navbar rect (both render as
-    // "<n>px"). getBoundingClientRect would work too, but the inline values keep
-    // the drag math identical to the pre-#276 floating behavior.
     const ol = parseFloat(el.style.left) || 0;
     const ot = parseFloat(el.style.top) || 0;
-    // Freeze the box size for the drag: a docked window keeps its navbar size
-    // while being pulled out, a floating window keeps its own size.
-    const dragW = el.offsetWidth;
-    const dragH = el.offsetHeight;
-
-    // Latch for the drop-zone hint so setState fires only when the pointer
-    // actually crosses the navbar boundary, not on every mousemove.
-    let overNavbar = false;
 
     const move = (ev: MouseEvent): void => {
       let nl = ol + (ev.clientX - sx);
@@ -520,58 +385,20 @@ export default function AiChatWindow() {
       // with position: fixed) with an 8px margin.
       nl = Math.max(
         EDGE_MARGIN,
-        Math.min(nl, window.innerWidth - dragW - EDGE_MARGIN),
+        Math.min(nl, window.innerWidth - el.offsetWidth - EDGE_MARGIN),
       );
       nt = Math.max(
         EDGE_MARGIN,
-        Math.min(nt, window.innerHeight - dragH - EDGE_MARGIN),
+        Math.min(nt, window.innerHeight - el.offsetHeight - EDGE_MARGIN),
       );
       el.style.left = `${nl}px`;
       el.style.top = `${nt}px`;
-      // Drop-zone highlight: only meaningful when dragging a FLOATING window in
-      // to dock it (a docked window is already over the navbar).
-      if (!dockedRef.current) {
-        const nowOver = isPointerOverNavbar(ev.clientX, ev.clientY);
-        if (nowOver !== overNavbar) {
-          overNavbar = nowOver;
-          // This re-render would re-apply the committed geom; hand it the live
-          // position so the box does not snap back for a frame.
-          setDragPos({ left: nl, top: nt });
-          setDockHint(nowOver);
-        }
-      }
     };
 
     const up = (ev: MouseEvent): void => {
       document.removeEventListener("mousemove", move);
       document.removeEventListener("mouseup", up);
       document.body.style.userSelect = "";
-      setDragPos(null);
-      setDockHint(false);
-      const overNavbarNow = isPointerOverNavbar(ev.clientX, ev.clientY);
-
-      if (dockedRef.current) {
-        // Docked window: releasing OUTSIDE the navbar pops it out as a floating
-        // window at the drop point (clamped to the viewport). Released over the
-        // navbar -> stays docked (a header click is a no-op here). The response
-        // stream is untouched — only the mode flag / geom change.
-        if (!overNavbarNow) {
-          const el2 = winRef.current;
-          const dropLeft = el2 ? parseFloat(el2.style.left) || 0 : 0;
-          const dropTop = el2 ? parseFloat(el2.style.top) || 0 : 0;
-          setGeom((prev) =>
-            clampGeom({
-              ...(prev ?? computeInitialGeom()),
-              left: dropLeft,
-              top: dropTop,
-            }),
-          );
-          setDocked(false);
-        }
-        return;
-      }
-
-      // Floating window.
       // Treat a near-zero-movement press as a click (not a drag). When the
       // window is minimized, a header click expands it; nothing to persist
       // because the position did not change. minimizedRef avoids the stale
@@ -583,13 +410,6 @@ export default function AiChatWindow() {
         setMinimized(false);
         return;
       }
-      // Released over the navbar -> dock. The layout effect then pins the window
-      // to the navbar rect; the last floating geom is left untouched so a later
-      // undock/close restores the remembered floating placement.
-      if (overNavbarNow) {
-        setDocked(true);
-        return;
-      }
       const el2 = winRef.current;
       // Persist the final position back into state (preserving the size) so
       // re-renders keep it.
@@ -612,20 +432,6 @@ export default function AiChatWindow() {
     e.preventDefault();
   }, []);
 
-  // Dock/undock via the header button. Docking pins the window to the navbar;
-  // undocking restores the floating window at its last remembered geom. On
-  // undock we re-clamp that geom to the current viewport (matching drag-undock's
-  // clampGeom) so a viewport shrink while docked can't leave the popped-out
-  // window partly off-screen. The chat thread stays mounted across the toggle,
-  // so a live stream is intact. dockedRef gives the live value inside this
-  // useCallback([]) handler.
-  const toggleDock = useCallback((): void => {
-    if (dockedRef.current) {
-      setGeom((prev) => (prev ? clampGeom(prev) : prev));
-    }
-    setDocked((d) => !d);
-  }, [setDocked, setGeom]);
-
   // Just toggle the flag. The `.minimized` CSS handles the collapsed height and
   // disables resize, and `.minimized .content` hides the body while keeping
   // ChatThread mounted (so an in-flight stream is not aborted).
@@ -635,45 +441,17 @@ export default function AiChatWindow() {
 
   if (!windowOpen || !geom) return null;
 
-  // `useDock` (computed above) is the EFFECTIVE dock state: docked AND a navbar
-  // rect is available. If the navbar is absent/collapsed we keep the persisted
-  // `docked` flag but render the floating look so the window never vanishes (it
-  // re-docks once the navbar reappears — see the layout effect above). Minimize
-  // is suppressed while actually docked.
-  const showMinimized = minimized && !useDock;
-
-  // Position/size of the window this frame. `dragPos` (set only at a mid-drag
-  // navbar-boundary crossing) overrides the committed position so the box does
-  // not snap back for a frame when that crossing forces a re-render.
-  const boxStyle = dockRect && useDock
-    ? {
-        left: dockRect.left,
-        top: dockRect.top,
-        width: dockRect.width,
-        height: dockRect.height,
-      }
-    : {
+  return (
+    <div
+      ref={winRef}
+      className={`${classes.window}${minimized ? ` ${classes.minimized}` : ""}`}
+      style={{
         left: geom.left,
         top: geom.top,
         width: geom.width,
         // Height omitted when minimized so the `.minimized` CSS auto-height wins.
-        height: showMinimized ? undefined : geom.height,
-      };
-  const style = dragPos
-    ? { ...boxStyle, left: dragPos.left, top: dragPos.top }
-    : boxStyle;
-
-  // Drop-zone highlight over the navbar bounds while dragging a floating window
-  // onto the sidebar. Rendered as a viewport-fixed sibling overlay (not inside
-  // the moving window), so its position is independent of the drag.
-  const hintRect = dockHint ? getNavbarRect() : null;
-
-  return (
-    <>
-    <div
-      ref={winRef}
-      className={`${classes.window}${showMinimized ? ` ${classes.minimized}` : ""}${useDock ? ` ${classes.docked}` : ""}`}
-      style={style}
+        height: minimized ? undefined : geom.height,
+      }}
     >
       {/* drag bar / header. Mouse users expand a minimized window by clicking
           anywhere on the bar (the click-vs-drag logic in startDrag, which
@@ -693,11 +471,11 @@ export default function AiChatWindow() {
             is a plain, non-focusable label. */}
         <span
           className={classes.title}
-          role={showMinimized ? "button" : undefined}
-          tabIndex={showMinimized ? 0 : undefined}
-          aria-label={showMinimized ? t("Expand") : undefined}
+          role={minimized ? "button" : undefined}
+          tabIndex={minimized ? 0 : undefined}
+          aria-label={minimized ? t("Expand") : undefined}
           onKeyDown={
-            showMinimized
+            minimized
               ? (event) => {
                   if (event.key === "Enter" || event.key === " ") {
                     event.preventDefault();
@@ -753,39 +531,15 @@ export default function AiChatWindow() {
               )}
             </button>
           )}
-          {/* Dock/undock toggle. Effectively docked -> "Undock" (expand icon) pops
-              the window back out to floating; floating -> "Dock to sidebar"
-              (collapse icon) pins it into the navbar. The LABEL/icon reflect the
-              EFFECTIVE state (useDock), consistent with the Minimize gate: when
-              docked but the navbar is absent/collapsed the window renders floating,
-              so an "Undock" label there would misdescribe a floating window. The
-              action still toggles the raw `docked` atom. */}
           <button
             type="button"
             className={classes.headerBtn}
-            title={useDock ? t("Undock") : t("Dock to sidebar")}
-            aria-label={useDock ? t("Undock") : t("Dock to sidebar")}
-            onClick={toggleDock}
+            title={t("Minimize")}
+            aria-label={t("Minimize")}
+            onClick={toggleMinimize}
           >
-            {useDock ? (
-              <IconLayoutSidebarLeftExpand size={14} />
-            ) : (
-              <IconLayoutSidebarLeftCollapse size={14} />
-            )}
+            <IconMinus size={14} />
           </button>
-          {/* Minimize (collapse to header) makes no sense while docked — the
-              window fills the navbar — so it is hidden in dock mode. */}
-          {!useDock && (
-            <button
-              type="button"
-              className={classes.headerBtn}
-              title={t("Minimize")}
-              aria-label={t("Minimize")}
-              onClick={toggleMinimize}
-            >
-              <IconMinus size={14} />
-            </button>
-          )}
           <button
             type="button"
             className={classes.headerBtn}
@@ -887,29 +641,12 @@ export default function AiChatWindow() {
         </div>
       </div>
 
-      {/* resize affordance icon (drawn manually; native resizer is hidden).
-          Hidden while docked — the docked size follows the navbar, not a manual
-          resize. */}
-      {!showMinimized && !useDock && (
+      {/* resize affordance icon (drawn manually; native resizer is hidden) */}
+      {!minimized && (
         <span className={classes.resizeHandle}>
           <IconArrowsDiagonal size={12} />
         </span>
       )}
     </div>
-      {/* Drop-zone highlight over the navbar while dragging a floating window in
-          to dock it. Sibling of the window (position: fixed) so it tracks the
-          navbar bounds, not the moving window. */}
-      {hintRect && (
-        <div
-          className={classes.dockHighlight}
-          style={{
-            left: hintRect.left,
-            top: hintRect.top,
-            width: hintRect.width,
-            height: hintRect.height,
-          }}
-        />
-      )}
-    </>
   );
 }

apps/client/src/features/ai-chat/utils/dock-helpers.test.ts

@@ -1,58 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  isPointWithinRect,
-  isNavbarRectVisible,
-  type NavbarRect,
-} from "./dock-helpers.ts";
-
-const NAVBAR: NavbarRect = { left: 0, top: 45, width: 300, height: 800 };
-
-describe("isPointWithinRect", () => {
-  it("returns true for a point inside the navbar", () => {
-    expect(isPointWithinRect(150, 400, NAVBAR)).toBe(true);
-  });
-
-  it("treats the boundary edges as inside (drop exactly on the edge docks)", () => {
-    // Top-left corner and bottom-right corner are both inclusive.
-    expect(isPointWithinRect(0, 45, NAVBAR)).toBe(true);
-    expect(isPointWithinRect(300, 845, NAVBAR)).toBe(true);
-  });
-
-  it("returns false for a point in the content area (to the right)", () => {
-    expect(isPointWithinRect(500, 400, NAVBAR)).toBe(false);
-  });
-
-  it("returns false above the navbar (in the header band)", () => {
-    expect(isPointWithinRect(150, 10, NAVBAR)).toBe(false);
-  });
-
-  it("returns false when the navbar rect is null (absent/collapsed)", () => {
-    expect(isPointWithinRect(150, 400, null)).toBe(false);
-  });
-});
-
-describe("isNavbarRectVisible", () => {
-  it("returns true for a normal on-screen navbar rect", () => {
-    expect(isNavbarRectVisible({ width: 300, height: 800, right: 300 })).toBe(
-      true,
-    );
-  });
-
-  it("returns false for a zero-size rect (width or height 0)", () => {
-    expect(isNavbarRectVisible({ width: 0, height: 800, right: 300 })).toBe(
-      false,
-    );
-    expect(isNavbarRectVisible({ width: 300, height: 0, right: 300 })).toBe(
-      false,
-    );
-  });
-
-  it("returns false when the navbar is translated off-screen (right <= 0)", () => {
-    expect(isNavbarRectVisible({ width: 300, height: 800, right: 0 })).toBe(
-      false,
-    );
-    expect(isNavbarRectVisible({ width: 300, height: 800, right: -50 })).toBe(
-      false,
-    );
-  });
-});

apps/client/src/features/ai-chat/utils/dock-helpers.ts

@@ -1,48 +0,0 @@
-// Pure geometry helper for the AI chat window dock/undock decision (#276). Kept
-// free of React and the DOM so it can be unit-tested in isolation (see
-// dock-helpers.test.ts). The DOM-reading getNavbarRect() lives in the window
-// component; this is only the point-in-rect math that decides dock-on-drop and
-// undock-on-drag-out from the measured navbar rect.
-
-export type NavbarRect = {
-  left: number;
-  top: number;
-  width: number;
-  height: number;
-};
-
-/**
- * Whether a viewport point (x, y) falls within `rect`. Edges are inclusive so a
- * drop exactly on the navbar boundary counts as "over the navbar". Returns false
- * when the rect is null (navbar absent/collapsed) so the caller falls back to the
- * floating behavior.
- */
-export function isPointWithinRect(
-  x: number,
-  y: number,
-  rect: NavbarRect | null,
-): boolean {
-  if (!rect) return false;
-  return (
-    x >= rect.left &&
-    x <= rect.left + rect.width &&
-    y >= rect.top &&
-    y <= rect.top + rect.height
-  );
-}
-
-/**
- * Whether a measured navbar rect represents a VISIBLE navbar. Mantine collapses
- * the navbar by translating it off-screen (its right edge lands at or left of the
- * viewport) without changing its width/border-box, so a zero-size or off-screen
- * rect means "no navbar" — the docked window then falls back to floating instead
- * of pinning to an invisible box. Pure (no DOM) so it can be unit-tested; the
- * DOM-reading getNavbarRect() in the window component supplies the rect.
- */
-export function isNavbarRectVisible(r: {
-  width: number;
-  height: number;
-  right: number;
-}): boolean {
-  return !(r.width === 0 || r.height === 0 || r.right <= 0);
-}

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

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach, afterEach } 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/logout per test.
+const loginMock = vi.fn();
+const logoutMock = vi.fn();
+vi.mock("@/features/auth/services/auth-service", () => ({
+  login: (...args: unknown[]) => loginMock(...args),
+  logout: (...args: unknown[]) => logoutMock(...args),
+  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);
+  logoutMock.mockReset();
+  logoutMock.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");
+  });
+});
+
+describe("useAuth.handleLogout", () => {
+  const replaceMock = vi.fn();
+  let originalLocation: Location;
+
+  beforeEach(() => {
+    replaceMock.mockReset();
+    // window.location.replace is the post-logout redirect. jsdom's real `replace`
+    // is a non-configurable method that warns "not implemented", so swap the
+    // whole location object for one whose `replace` we can capture.
+    originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { replace: replaceMock },
+    });
+  });
+
+  afterEach(() => {
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: originalLocation,
+    });
+  });
+
+  it("purges the offline cache exactly once BEFORE redirecting (cross-user leak guard)", async () => {
+    const order: string[] = [];
+    clearOfflineCacheMock.mockImplementation(async () => {
+      order.push("clear");
+    });
+    replaceMock.mockImplementation((url: string) => {
+      order.push(`replace:${url}`);
+    });
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.logout();
+    });
+
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    // Purge must complete before the redirect (which would otherwise interrupt
+    // the async cleanup).
+    expect(order).toEqual(["clear", "replace:/login?logout=1"]);
+  });
+
+  it("still redirects when the cache purge throws (best-effort, never blocks logout)", async () => {
+    clearOfflineCacheMock.mockRejectedValue(new Error("idb unavailable"));
+
+    const { result } = renderHook(() => useAuth());
+    await act(async () => {
+      await result.current.logout();
+    });
+
+    // The thrown purge error is swallowed and the redirect still fires.
+    expect(clearOfflineCacheMock).toHaveBeenCalledTimes(1);
+    expect(replaceMock).toHaveBeenCalledTimes(1);
+    expect(replaceMock).toHaveBeenCalledWith("/login?logout=1");
+  });
+});

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

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

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

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

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

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

apps/client/src/features/comment/components/comment-hover-preview.test.tsx

@@ -1,434 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { render, screen, act } from "@testing-library/react";
-import { useRef } from "react";
-import { MantineProvider } from "@mantine/core";
-import { IComment } from "@/features/comment/types/comment.types";
-
-// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
-
-// Stub the comments query so the component renders without react-query/network.
-const mockUseCommentsQuery = vi.fn();
-vi.mock("@/features/comment/queries/comment-query", () => ({
-  useCommentsQuery: (params: { pageId: string }) =>
-    mockUseCommentsQuery(params),
-}));
-
-import CommentHoverPreview from "./comment-hover-preview";
-import { commentContentToText } from "@/features/comment/utils/comment-content-to-text";
-
-const doc = (text: string) =>
-  JSON.stringify({
-    type: "doc",
-    content: [{ type: "paragraph", content: [{ type: "text", text }] }],
-  });
-
-const comment = (over?: Partial<IComment>): IComment =>
-  ({
-    id: "c-1",
-    content: doc("Hello world"),
-    creatorId: "u-1",
-    pageId: "page-1",
-    workspaceId: "ws-1",
-    createdAt: new Date(),
-    creator: { id: "u-1", name: "User", avatarUrl: null } as any,
-    ...over,
-  }) as IComment;
-
-function setComments(items: IComment[]) {
-  mockUseCommentsQuery.mockReturnValue({
-    data: { items, meta: {} },
-    isLoading: false,
-    isError: false,
-  });
-}
-
-// Test harness: owns the container ref, hosts a comment-mark span and the
-// preview component, mirroring how page-editor mounts it next to EditorContent.
-function Harness({
-  spanAttrs = { "data-comment-id": "c-1" },
-  pageId = "page-1",
-}: {
-  spanAttrs?: Record<string, string>;
-  pageId?: string;
-}) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  return (
-    <MantineProvider>
-      <div ref={containerRef}>
-        <span data-testid="mark" className="comment-mark" {...spanAttrs}>
-          marked text
-        </span>
-        <CommentHoverPreview pageId={pageId} containerRef={containerRef} />
-      </div>
-    </MantineProvider>
-  );
-}
-
-function hoverMark() {
-  const span = screen.getByTestId("mark");
-  act(() => {
-    span.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
-  });
-}
-
-function leaveMark() {
-  const span = screen.getByTestId("mark");
-  act(() => {
-    span.dispatchEvent(new MouseEvent("mouseout", { bubbles: true }));
-  });
-}
-
-describe("commentContentToText", () => {
-  it("flattens a multi-node ProseMirror doc to plain text", () => {
-    const content = JSON.stringify({
-      type: "doc",
-      content: [
-        {
-          type: "paragraph",
-          content: [
-            { type: "text", text: "Hello " },
-            { type: "text", text: "world" },
-          ],
-        },
-        { type: "paragraph", content: [{ type: "text", text: "Second line" }] },
-      ],
-    });
-    expect(commentContentToText(content)).toBe("Hello world\nSecond line");
-  });
-
-  it("joins nested block structures (lists) on block boundaries", () => {
-    const content = {
-      type: "doc",
-      content: [
-        {
-          type: "bulletList",
-          content: [
-            {
-              type: "listItem",
-              content: [
-                { type: "paragraph", content: [{ type: "text", text: "one" }] },
-              ],
-            },
-            {
-              type: "listItem",
-              content: [
-                { type: "paragraph", content: [{ type: "text", text: "two" }] },
-              ],
-            },
-          ],
-        },
-      ],
-    };
-    expect(commentContentToText(content)).toBe("one\ntwo");
-  });
-
-  it("accepts an already-parsed object", () => {
-    expect(commentContentToText({ type: "doc", content: [] })).toBe("");
-  });
-
-  it("returns '' for empty / missing / malformed content", () => {
-    expect(commentContentToText("")).toBe("");
-    expect(commentContentToText("   ")).toBe("");
-    expect(commentContentToText(undefined)).toBe("");
-    expect(commentContentToText(null)).toBe("");
-    expect(commentContentToText(JSON.stringify({ type: "doc", content: [] }))).toBe(
-      "",
-    );
-  });
-
-  it("falls back to the raw string when content is not JSON", () => {
-    expect(commentContentToText("plain text")).toBe("plain text");
-  });
-
-  it("preserves a hardBreak inside a paragraph as a newline", () => {
-    const content = JSON.stringify({
-      type: "doc",
-      content: [
-        {
-          type: "paragraph",
-          content: [
-            { type: "text", text: "line1" },
-            { type: "hardBreak" },
-            { type: "text", text: "line2" },
-          ],
-        },
-      ],
-    });
-    expect(commentContentToText(content)).toBe("line1\nline2");
-  });
-});
-
-describe("CommentHoverPreview — hover behaviour", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    mockUseCommentsQuery.mockReset();
-  });
-
-  afterEach(() => {
-    vi.runOnlyPendingTimers();
-    vi.useRealTimers();
-  });
-
-  it("shows the parent comment text and author after the open delay", () => {
-    setComments([
-      comment({
-        content: doc("Hello world"),
-        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
-      }),
-    ]);
-    render(<Harness />);
-
-    hoverMark();
-    // Before the delay elapses there is no card.
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    const card = screen.getByTestId("comment-hover-preview");
-    // The line shows "Author: text" — both the author name and the comment text.
-    expect(card.textContent).toContain("Alice:");
-    expect(card.textContent).toContain("Hello world");
-    // The card MUST NOT intercept the mark's click (which opens the side panel):
-    // pointer-events:none is the single property guaranteeing that — lock it so
-    // a regression dropping it from the style object fails here.
-    expect(card.style.pointerEvents).toBe("none");
-  });
-
-  it("renders the whole thread: parent plus replies, each with its author", () => {
-    setComments([
-      comment({
-        id: "c-1",
-        content: doc("Parent comment"),
-        createdAt: new Date("2026-01-01T10:00:00Z"),
-        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
-      }),
-      comment({
-        id: "c-3",
-        content: doc("Second reply"),
-        parentCommentId: "c-1",
-        createdAt: new Date("2026-01-01T12:00:00Z"),
-        creator: { id: "u-3", name: "Carol", avatarUrl: null } as any,
-      }),
-      comment({
-        id: "c-2",
-        content: doc("First reply"),
-        parentCommentId: "c-1",
-        createdAt: new Date("2026-01-01T11:00:00Z"),
-        creator: { id: "u-2", name: "Bob", avatarUrl: null } as any,
-      }),
-    ]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    const card = screen.getByTestId("comment-hover-preview");
-
-    // Parent and both replies are present, each as "Author: text".
-    const body = card.textContent ?? "";
-    expect(body).toContain("Alice: Parent comment");
-    expect(body).toContain("Bob: First reply");
-    expect(body).toContain("Carol: Second reply");
-
-    // Replies are ordered by createdAt ascending after the parent
-    // (Parent -> First reply -> Second reply), even though the input was
-    // out of order (Second reply's comment came before First reply's).
-    expect(body.indexOf("Parent comment")).toBeLessThan(
-      body.indexOf("First reply"),
-    );
-    expect(body.indexOf("First reply")).toBeLessThan(
-      body.indexOf("Second reply"),
-    );
-  });
-
-  it("shows the thread even when the parent text is empty but it has replies", () => {
-    setComments([
-      comment({
-        id: "c-1",
-        content: JSON.stringify({ type: "doc", content: [] }),
-        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
-      }),
-      comment({
-        id: "c-2",
-        content: doc("A reply"),
-        parentCommentId: "c-1",
-        createdAt: new Date(),
-        creator: { id: "u-2", name: "Bob", avatarUrl: null } as any,
-      }),
-    ]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    const card = screen.getByTestId("comment-hover-preview");
-    expect(card.textContent).toContain("Bob: A reply");
-  });
-
-  it("shows nothing when neither the parent nor its reply has any text", () => {
-    // The card is gated on rows-with-text (not thread length), so a text-less
-    // root whose only reply is also text-less must NOT open an empty card.
-    const emptyDoc = JSON.stringify({ type: "doc", content: [] });
-    setComments([
-      comment({
-        id: "c-1",
-        content: emptyDoc,
-        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
-      }),
-      comment({
-        id: "c-2",
-        content: emptyDoc,
-        parentCommentId: "c-1",
-        createdAt: new Date(),
-        creator: { id: "u-2", name: "Bob", avatarUrl: null } as any,
-      }),
-    ]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("hides on mouseout", () => {
-    setComments([comment()]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    expect(
-      screen.getByTestId("comment-hover-preview").textContent,
-    ).toContain("Hello world");
-
-    leaveMark();
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("does not show a card for a resolved comment (data-resolved)", () => {
-    setComments([comment()]);
-    render(
-      <Harness
-        spanAttrs={{ "data-comment-id": "c-1", "data-resolved": "true" }}
-      />,
-    );
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(200);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("does not show a card for a resolved comment (resolvedAt set)", () => {
-    setComments([comment({ resolvedAt: new Date() })]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(200);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("does not show a card for an unknown comment id", () => {
-    setComments([comment()]);
-    render(<Harness spanAttrs={{ "data-comment-id": "missing" }} />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(200);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("does not show a card when the comment text is empty", () => {
-    setComments([comment({ content: JSON.stringify({ type: "doc", content: [] }) })]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(200);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("hides on scroll", () => {
-    setComments([comment()]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    expect(
-      screen.getByTestId("comment-hover-preview").textContent,
-    ).toContain("Hello world");
-
-    act(() => {
-      window.dispatchEvent(new Event("scroll"));
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("hides on mousedown (clicking the mark to open the panel dismisses the card)", () => {
-    setComments([comment()]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    expect(
-      screen.getByTestId("comment-hover-preview").textContent,
-    ).toContain("Hello world");
-
-    const span = screen.getByTestId("mark");
-    act(() => {
-      span.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-
-  it("does not hide when the pointer moves WITHIN the same span (anti-flicker)", () => {
-    setComments([comment()]);
-    render(<Harness />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).not.toBeNull();
-
-    // mouseout whose relatedTarget is still inside the span must NOT hide.
-    const span = screen.getByTestId("mark");
-    act(() => {
-      span.dispatchEvent(
-        new MouseEvent("mouseout", { bubbles: true, relatedTarget: span }),
-      );
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).not.toBeNull();
-  });
-
-  it("hides when the page changes", () => {
-    setComments([comment()]);
-    const { rerender } = render(<Harness pageId="page-1" />);
-
-    hoverMark();
-    act(() => {
-      vi.advanceTimersByTime(350);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).not.toBeNull();
-
-    act(() => {
-      rerender(<Harness pageId="page-2" />);
-    });
-    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
-  });
-});

apps/client/src/features/comment/components/comment-hover-preview.tsx

@@ -1,267 +0,0 @@
-import React, { useEffect, useMemo, useRef, useState } from "react";
-import { createPortal } from "react-dom";
-import { Paper, Text } from "@mantine/core";
-import { useCommentsQuery } from "@/features/comment/queries/comment-query";
-import { IComment } from "@/features/comment/types/comment.types";
-import { commentContentToText } from "@/features/comment/utils/comment-content-to-text";
-
-interface CommentHoverPreviewProps {
-  pageId: string;
-  containerRef: React.RefObject<HTMLElement>;
-}
-
-// Delay before the card appears, to avoid flicker when the pointer quickly
-// passes over comment marks (kept generous so it does not pop up on a passing
-// glance).
-const OPEN_DELAY_MS = 350;
-const CARD_MAX_WIDTH = 360;
-const CARD_MAX_HEIGHT = 300;
-const GAP = 6;
-// Reserve roughly this much room below the span; flip above when it doesn't fit.
-// Match CARD_MAX_HEIGHT so the flip-above decision reserves the real worst-case
-// height — otherwise a tall thread placed below near the viewport bottom passes
-// the "fits below" check and then overflows off-screen (clipped, no scroll).
-const ESTIMATED_CARD_HEIGHT = 300;
-
-// One rendered line of the thread: the author and the comment's plain text,
-// pre-computed at hover time so render stays cheap. Shown as "Author: text".
-interface ThreadRow {
-  id: string;
-  name: string;
-  text: string;
-}
-
-interface HoverState {
-  thread: ThreadRow[];
-  rect: { top: number; bottom: number; left: number };
-}
-
-function isResolved(comment: IComment): boolean {
-  return comment.resolvedAt != null || comment.resolvedById != null;
-}
-
-// Build the thread for a root (parent) comment: the root first, followed by its
-// replies sorted by createdAt ascending. Reads every comment from the map.
-function buildThread(
-  commentMap: Map<string, IComment>,
-  root: IComment,
-): ThreadRow[] {
-  const replies: IComment[] = [];
-  commentMap.forEach((comment) => {
-    if (comment.parentCommentId === root.id) replies.push(comment);
-  });
-  replies.sort(
-    (a, b) =>
-      new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
-  );
-
-  return [root, ...replies].map((comment) => ({
-    id: comment.id,
-    name: comment.creator?.name ?? "",
-    text: commentContentToText(comment.content),
-  }));
-}
-
-/**
- * Shows a small floating card when the user hovers a `.comment-mark` span in the
- * main editor: the parent comment plus all its replies, one per line as
- * "Author: text" (plain — no avatars or timestamps). Read-only:
- * `pointer-events: none` so it never intercepts the mark's click (which opens
- * the side panel via ACTIVE_COMMENT_EVENT). Resolved/unknown marks show nothing.
- */
-export default function CommentHoverPreview({
-  pageId,
-  containerRef,
-}: CommentHoverPreviewProps) {
-  const { data } = useCommentsQuery({ pageId });
-
-  // Map of commentId -> comment. The map indexes every comment (parents and
-  // replies) so a thread can be assembled from a single source.
-  const commentMap = useMemo(() => {
-    const map = new Map<string, IComment>();
-    data?.items?.forEach((comment) => map.set(comment.id, comment));
-    return map;
-  }, [data]);
-
-  // Read the latest map from the delegated listeners without re-attaching them
-  // every time the comments query refreshes.
-  const commentMapRef = useRef(commentMap);
-  useEffect(() => {
-    commentMapRef.current = commentMap;
-  }, [commentMap]);
-
-  const [hover, setHover] = useState<HoverState | null>(null);
-  const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const activeSpanRef = useRef<HTMLElement | null>(null);
-
-  const clearOpenTimer = () => {
-    if (openTimerRef.current !== null) {
-      clearTimeout(openTimerRef.current);
-      openTimerRef.current = null;
-    }
-  };
-
-  const hide = () => {
-    clearOpenTimer();
-    activeSpanRef.current = null;
-    setHover(null);
-  };
-
-  // Hide and reset when the page changes (the comment set belongs to a page):
-  // the cleanup runs on every pageId change before the effect re-runs.
-  useEffect(() => {
-    return () => hide();
-  }, [pageId]);
-
-  useEffect(() => {
-    const container = containerRef.current;
-    if (!container) return;
-
-    const handleMouseOver = (event: MouseEvent) => {
-      const target = event.target as HTMLElement | null;
-      const span = target?.closest<HTMLElement>(
-        ".comment-mark[data-comment-id]",
-      );
-      if (!span) return;
-
-      const commentId = span.getAttribute("data-comment-id");
-      if (!commentId) return;
-
-      const comment = commentMapRef.current.get(commentId);
-      // Unknown (not loaded yet) or resolved -> no tooltip. Resolved marks also
-      // carry data-resolved="true"; check both the data attribute and the model.
-      if (
-        !comment ||
-        span.hasAttribute("data-resolved") ||
-        isResolved(comment)
-      ) {
-        return;
-      }
-
-      // Already tracking this span: nothing to do (avoids re-building the thread
-      // on every intra-span mousemove).
-      if (span === activeSpanRef.current) return;
-
-      const thread = buildThread(commentMapRef.current, comment);
-      // Show the card only when SOME comment has text. Gating on thread length
-      // could open an empty card (a text-less root whose only reply is also
-      // text-less), since the render filters out empty-text rows.
-      const hasContent = thread.some((row) => row.text.length > 0);
-      if (!hasContent) return;
-
-      activeSpanRef.current = span;
-
-      clearOpenTimer();
-      openTimerRef.current = setTimeout(() => {
-        openTimerRef.current = null;
-        if (activeSpanRef.current !== span || !span.isConnected) return;
-        const rect = span.getBoundingClientRect();
-        setHover({
-          thread,
-          rect: { top: rect.top, bottom: rect.bottom, left: rect.left },
-        });
-      }, OPEN_DELAY_MS);
-    };
-
-    const handleMouseOut = (event: MouseEvent) => {
-      const target = event.target as HTMLElement | null;
-      const span = target?.closest<HTMLElement>(
-        ".comment-mark[data-comment-id]",
-      );
-      if (!span) return;
-
-      // Ignore moves that stay within the same comment-mark span.
-      const related = event.relatedTarget as HTMLElement | null;
-      if (related && span.contains(related)) return;
-
-      if (span === activeSpanRef.current) hide();
-    };
-
-    // Scroll uses capture so it also catches scrolling inside nested containers.
-    const handleScroll = () => hide();
-    const handleResize = () => hide();
-    // Dismiss on press: clicking a mark opens the side panel, and the card
-    // would otherwise linger (no mouseout fires while the pointer stays put).
-    const handleMouseDown = () => hide();
-
-    container.addEventListener("mouseover", handleMouseOver);
-    container.addEventListener("mouseout", handleMouseOut);
-    container.addEventListener("mousedown", handleMouseDown);
-    window.addEventListener("scroll", handleScroll, true);
-    window.addEventListener("resize", handleResize);
-
-    return () => {
-      container.removeEventListener("mouseover", handleMouseOver);
-      container.removeEventListener("mouseout", handleMouseOut);
-      container.removeEventListener("mousedown", handleMouseDown);
-      window.removeEventListener("scroll", handleScroll, true);
-      window.removeEventListener("resize", handleResize);
-      clearOpenTimer();
-    };
-  }, [containerRef]);
-
-  if (!hover) return null;
-
-  const viewportWidth = window.innerWidth;
-  const viewportHeight = window.innerHeight;
-  // Flip above when there isn't enough room below the span.
-  const placeAbove =
-    hover.rect.bottom + ESTIMATED_CARD_HEIGHT > viewportHeight &&
-    hover.rect.top > ESTIMATED_CARD_HEIGHT;
-
-  const left = Math.max(
-    8,
-    Math.min(hover.rect.left, viewportWidth - CARD_MAX_WIDTH - 8),
-  );
-
-  const positionStyle: React.CSSProperties = placeAbove
-    ? { bottom: viewportHeight - hover.rect.top + GAP }
-    : { top: hover.rect.bottom + GAP };
-
-  return createPortal(
-    <Paper
-      withBorder
-      shadow="md"
-      radius="sm"
-      role="tooltip"
-      data-testid="comment-hover-preview"
-      style={{
-        position: "fixed",
-        left,
-        ...positionStyle,
-        zIndex: 1000,
-        maxWidth: CARD_MAX_WIDTH,
-        // The card is pointer-events:none, so it can't scroll; clamp long
-        // threads instead (most threads are short).
-        maxHeight: CARD_MAX_HEIGHT,
-        overflow: "hidden",
-        padding: "8px 10px",
-        fontSize: "13px",
-        lineHeight: 1.4,
-        // Never intercept clicks targeting the comment-mark span beneath.
-        pointerEvents: "none",
-        wordBreak: "break-word",
-      }}
-    >
-      {hover.thread
-        // A comment with no plain text (e.g. an image-only reply) adds nothing
-        // to a text preview — skip its line.
-        .filter((row) => row.text.length > 0)
-        .map((row) => (
-          <Text
-            key={row.id}
-            size="xs"
-            mt={4}
-            style={{ whiteSpace: "pre-wrap", wordBreak: "break-word" }}
-          >
-            {/* "Author: text" — one line per comment, parent then replies. */}
-            <Text span fw={600}>
-              {row.name}:
-            </Text>{" "}
-            {row.text}
-          </Text>
-        ))}
-    </Paper>,
-    document.body,
-  );
-}

apps/client/src/features/comment/components/comment-list-item.test.tsx

@@ -40,50 +40,20 @@ function renderItem(comment: IComment) {
   );
 }
 
-describe("CommentListItem — agent avatar stack", () => {
-  it('flips the hierarchy for an agent comment: agent primary, launcher shown once', () => {
-    // Internal-chat shape with DISTINCT names so absence-of-duplication is
-    // assertable: creator is the human "Alice", the acting agent is "Researcher".
-    renderItem(
-      baseComment({
-        creator: { id: "user-1", name: "Alice", avatarUrl: null } as any,
-        createdSource: "agent",
-        aiChatId: "chat-1",
-        agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
-        launcher: { name: "Alice", avatarUrl: null },
-      }),
-    );
-    // The AGENT is the primary label (the flipped hierarchy).
-    expect(screen.getByText("Researcher")).toBeDefined();
-    // The human launcher name shows exactly once — it is no longer duplicated as
-    // a separate creator name (that duplication is the bug this fixes).
-    expect(screen.getAllByText("Alice").length).toBe(1);
-  });
-
-  it('external MCP agent comment (no launcher): shows the agent name, no separator', () => {
-    // aiChatId null => external MCP: the agent IS the account, no human behind.
-    renderItem(
-      baseComment({
-        creator: { id: "bot-1", name: "MCP Bot", avatarUrl: null } as any,
-        createdSource: "agent",
-        aiChatId: null,
-        agent: { name: "MCP Bot", avatarUrl: null },
-        launcher: null,
-      }),
-    );
-    expect(screen.getByText("MCP Bot")).toBeDefined();
-    // No launcher => no dimmed "·" separator in the header.
-    expect(screen.queryByText("·")).toBeNull();
-  });
-
-  it('does NOT render the stack for a normal user comment (createdSource "user")', () => {
-    const { container } = renderItem(baseComment({ createdSource: "user" }));
-    // No agent glyph (sparkles) is present for a plain human comment.
-    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
+describe("CommentListItem — AI badge", () => {
+  it('renders the AI-agent badge when createdSource === "agent"', () => {
+    renderItem(baseComment({ createdSource: "agent", aiChatId: null }));
+    expect(screen.getByText("AI-agent")).toBeDefined();
     expect(screen.getByText("Service Bot")).toBeDefined();
   });
 
-  // The stack's own behaviors (glyph priority, launcher-behind, deep-link click)
-  // are covered directly in agent-avatar-stack.test.tsx; this integration suite
-  // only guards the insertion gate (agent → stack, user → no stack).
+  it('does NOT render the badge for a normal user comment (createdSource "user")', () => {
+    renderItem(baseComment({ createdSource: "user" }));
+    expect(screen.queryByText("AI-agent")).toBeNull();
+    expect(screen.getByText("Service Bot")).toBeDefined();
+  });
+
+  // The non-clickable (null aiChatId) branch is a property of AiAgentBadge itself
+  // and is covered in ai-agent-badge.test.tsx; this integration suite only needs
+  // the insertion gate (agent → badge, user → no badge) above (#143 review).
 });

apps/client/src/features/comment/components/comment-list-item.tsx

@@ -1,5 +1,5 @@
 import { Group, Text, Box } from "@mantine/core";
-import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
+import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
 import React, { useEffect, useRef, useState } from "react";
 import classes from "./comment.module.css";
 import { useAtom, useAtomValue } from "jotai";
@@ -119,44 +119,24 @@ function CommentListItem({
   return (
     <Box ref={ref} pb={6}>
       <Group gap="xs">
-        {comment.createdSource === "agent" && comment.agent ? (
-          <AgentAvatarStack
-            agent={comment.agent}
-            launcher={comment.launcher}
-            aiChatId={comment.aiChatId}
-            showName={false}
-          />
-        ) : (
-          <CustomAvatar
-            size="sm"
-            avatarUrl={comment.creator.avatarUrl}
-            name={comment.creator.name}
-          />
-        )}
+        <CustomAvatar
+          size="sm"
+          avatarUrl={comment.creator.avatarUrl}
+          name={comment.creator.name}
+        />
 
         <div style={{ flex: 1 }}>
           <Group justify="space-between" wrap="nowrap">
             <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
-              {comment.createdSource === "agent" && comment.agent ? (
-                <>
-                  <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
-                    {comment.agent.name}
-                  </Text>
-                  {comment.launcher && (
-                    <>
-                      <Text size="xs" c="dimmed" fw={400} aria-hidden>
-                        ·
-                      </Text>
-                      <Text size="xs" c="dimmed" fw={400} lineClamp={1} lh={1.2}>
-                        {comment.launcher.name}
-                      </Text>
-                    </>
-                  )}
-                </>
-              ) : (
-                <Text size="xs" fw={500} lineClamp={1} lh={1.2}>
-                  {comment.creator.name}
-                </Text>
+              <Text size="xs" fw={500} lineClamp={1} lh={1.2}>
+                {comment.creator.name}
+              </Text>
+
+              {comment.createdSource === "agent" && (
+                <AiAgentBadge
+                  authorName={comment.creator?.name}
+                  aiChatId={comment.aiChatId}
+                />
               )}
             </Group>
 

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

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

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

@@ -1,9 +1,5 @@
 import { IUser } from "@/features/user/types/user.types";
 import { QueryParams } from "@/lib/types.ts";
-import type {
-  AgentInfo,
-  LauncherInfo,
-} from "@/components/ui/agent-avatar-stack.tsx";
 
 export interface IComment {
   id: string;
@@ -28,11 +24,6 @@ export interface IComment {
   createdSource?: string;
   aiChatId?: string | null;
   resolvedSource?: string | null;
-  // Server-normalized "agent avatar stack" provenance (#300), present only when
-  // createdSource === "agent": `agent` is the front identity, `launcher` the
-  // human behind it (null for an external MCP agent).
-  agent?: AgentInfo | null;
-  launcher?: LauncherInfo | null;
   yjsSelection?: {
     anchor: any;
     head: any;

apps/client/src/features/comment/utils/comment-content-to-text.ts

@@ -1,71 +0,0 @@
-/**
- * Flatten a comment's ProseMirror JSON document to plain text.
- *
- * `IComment.content` is stored as a stringified ProseMirror doc, but this also
- * accepts an already-parsed object. Walks the node tree, concatenating `text`
- * leaves and joining text-bearing blocks with newlines. Missing, empty or
- * malformed content yields an empty string (never throws).
- */
-export function commentContentToText(content: unknown): string {
-  let doc: any = content;
-
-  if (typeof content === "string") {
-    const trimmed = content.trim();
-    if (!trimmed) return "";
-    try {
-      doc = JSON.parse(trimmed);
-    } catch {
-      // Not JSON — fall back to treating the raw string as plain text.
-      return trimmed;
-    }
-  }
-
-  if (!doc || typeof doc !== "object") return "";
-
-  const blocks: string[] = [];
-
-  const walk = (node: any): void => {
-    if (!node || typeof node !== "object") return;
-
-    if (typeof node.text === "string") {
-      // Inline text leaf: append to the current block line.
-      if (blocks.length === 0) blocks.push("");
-      blocks[blocks.length - 1] += node.text;
-      return;
-    }
-
-    if (node.type === "hardBreak") {
-      // A soft line break inside a block: keep the newline so the two halves
-      // do not run together.
-      if (blocks.length === 0) blocks.push("");
-      blocks[blocks.length - 1] += "\n";
-      return;
-    }
-
-    const children = Array.isArray(node.content) ? node.content : [];
-    const containsText = children.some(
-      (child: any) =>
-        child && typeof child === "object" && typeof child.text === "string",
-    );
-
-    if (containsText) {
-      // Text-bearing block (paragraph, heading, ...): start a fresh line, then
-      // collect its inline text.
-      blocks.push("");
-      children.forEach(walk);
-      return;
-    }
-
-    // Structural container (doc, list, blockquote, ...): recurse so each nested
-    // text block becomes its own line.
-    children.forEach(walk);
-  };
-
-  walk(doc);
-
-  return blocks
-    .map((block) => block.trim())
-    .filter((block) => block.length > 0)
-    .join("\n")
-    .trim();
-}

apps/client/src/features/dictation/hooks/use-streaming-dictation.test.tsx

@@ -1,206 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
-
-// Shared, hoisted test state the module mocks write into. `onSpeechEnd` is the
-// VAD callback the hook registers on MicVAD.new — capturing it lets us drive
-// "a speech segment ended" deterministically. `pending` collects the deferred
-// transcription promises so the test controls their resolution order, which is
-// the whole point: out-of-order HTTP responses must NOT scramble the emitted
-// text (the in-order emitter under test).
-const h = vi.hoisted(() => {
-  return {
-    onSpeechEnd: null as null | ((audio: Float32Array) => void),
-    pending: [] as { resolve: (s: string) => void; reject: (e: unknown) => void }[],
-    notify: null as null | ReturnType<typeof Object>,
-  };
-});
-
-// Lazy-imported VAD: capture the onSpeechEnd handler and hand back a no-op
-// instance (start/pause/destroy all resolve).
-vi.mock("@ricky0123/vad-web", () => ({
-  MicVAD: {
-    new: vi.fn(async (opts: { onSpeechEnd: (a: Float32Array) => void }) => {
-      h.onSpeechEnd = opts.onSpeechEnd;
-      return {
-        start: vi.fn(async () => {}),
-        pause: vi.fn(async () => {}),
-        destroy: vi.fn(async () => {}),
-      };
-    }),
-  },
-}));
-
-// Each transcribeAudio call returns a promise we resolve/reject by index.
-vi.mock("@/features/dictation/services/dictation-service", () => ({
-  transcribeAudio: vi.fn(
-    () =>
-      new Promise<string>((resolve, reject) => {
-        h.pending.push({ resolve, reject });
-      }),
-  ),
-}));
-
-// Avoid real WAV encoding; the segment payload is irrelevant to ordering.
-vi.mock("@/features/dictation/utils/encode-wav", () => ({
-  encodeWavPcm16: vi.fn(() => new Blob()),
-}));
-
-const notifyShow = vi.fn();
-vi.mock("@mantine/notifications", () => ({
-  notifications: { show: (...args: unknown[]) => notifyShow(...args) },
-}));
-
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({ t: (s: string) => s }),
-}));
-
-import { useStreamingDictation } from "./use-streaming-dictation";
-
-// jsdom has no AudioContext; the hook constructs one and calls resume(). A
-// trivial stub is enough — the real audio path is irrelevant to ordering.
-class FakeAudioContext {
-  state = "running";
-  resume() {
-    return Promise.resolve();
-  }
-  close() {
-    this.state = "closed";
-    return Promise.resolve();
-  }
-}
-
-async function startRecording(onText: (t: string) => void) {
-  const hook = renderHook(() => useStreamingDictation({ onText }));
-  await act(async () => {
-    await hook.result.current.start();
-  });
-  // The VAD registered its onSpeechEnd and start() resolved into "recording".
-  expect(h.onSpeechEnd).toBeTypeOf("function");
-  expect(hook.result.current.status).toBe("recording");
-  return hook;
-}
-
-// Fire N ended speech segments (seq 0..N-1), each kicking off one transcription.
-async function emitSegments(n: number) {
-  await act(async () => {
-    for (let i = 0; i < n; i++) h.onSpeechEnd!(new Float32Array(8));
-  });
-}
-
-describe("useStreamingDictation — in-order segment emitter", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    h.onSpeechEnd = null;
-    h.pending = [];
-    notifyShow.mockClear();
-    (window as unknown as { AudioContext: unknown }).AudioContext =
-      FakeAudioContext;
-  });
-
-  it("emits transcriptions in segment order even when responses resolve out of order", async () => {
-    const emitted: string[] = [];
-    await startRecording((t) => emitted.push(t));
-    await emitSegments(3);
-    expect(h.pending).toHaveLength(3);
-
-    // Resolve seq 1 FIRST: it must be buffered, not emitted, because seq 0 is
-    // still outstanding (nextEmit == 0).
-    await act(async () => {
-      h.pending[1].resolve("second");
-    });
-    expect(emitted).toEqual([]);
-
-    // Resolve seq 0: this unblocks the buffer and flushes 0 then 1 in order.
-    await act(async () => {
-      h.pending[0].resolve("first");
-    });
-    expect(emitted).toEqual(["first", "second"]);
-
-    // seq 2 resolves last and flushes immediately (it is now next).
-    await act(async () => {
-      h.pending[2].resolve("third");
-    });
-    expect(emitted).toEqual(["first", "second", "third"]);
-  });
-
-  it("trims whitespace and drops empty/whitespace-only transcriptions while still advancing", async () => {
-    const emitted: string[] = [];
-    await startRecording((t) => emitted.push(t));
-    await emitSegments(3);
-
-    await act(async () => {
-      h.pending[0].resolve("  hello  "); // leading/trailing space trimmed
-      h.pending[1].resolve("   "); // whitespace-only -> not emitted, but seq advances
-      h.pending[2].resolve("world");
-    });
-
-    expect(emitted).toEqual(["hello", "world"]);
-  });
-
-  it("a failed segment shows one notification and is skipped so later segments still flush in order", async () => {
-    const emitted: string[] = [];
-    await startRecording((t) => emitted.push(t));
-    await emitSegments(2);
-
-    // seq 0 fails: the user sees a notification and the emitter advances past it.
-    await act(async () => {
-      h.pending[0].reject({ message: "boom" });
-    });
-    expect(notifyShow).toHaveBeenCalledTimes(1);
-    expect(emitted).toEqual([]);
-
-    // seq 1 still flushes (it is now next), proving one failure did not stall.
-    await act(async () => {
-      h.pending[1].resolve("survivor");
-    });
-    expect(emitted).toEqual(["survivor"]);
-  });
-
-  it("an OUT-OF-ORDER failed segment is buffered as empty and skipped without stalling later text", async () => {
-    const emitted: string[] = [];
-    await startRecording((t) => emitted.push(t));
-    await emitSegments(3);
-
-    // seq 1 (NOT next-to-emit) fails first: it takes the else branch — an empty
-    // placeholder is buffered (resultsRef.set(seq, "")) so the emitter can later
-    // skip it. One notification, nothing emitted yet (seq 0 still gates).
-    await act(async () => {
-      h.pending[1].reject({ message: "boom" });
-    });
-    expect(notifyShow).toHaveBeenCalledTimes(1);
-    expect(emitted).toEqual([]);
-
-    // seq 0 flushes; the drain then reaches the buffered empty seq 1 and SKIPS
-    // past it to seq 2.
-    await act(async () => {
-      h.pending[0].resolve("alpha");
-    });
-    expect(emitted).toEqual(["alpha"]);
-
-    // seq 2 emits — proving the empty placeholder let the emitter advance past
-    // the failed seq 1. Without the else branch's placeholder the drain would
-    // stall at the missing seq 1 and "gamma" would never flush.
-    await act(async () => {
-      h.pending[2].resolve("gamma");
-    });
-    expect(emitted).toEqual(["alpha", "gamma"]);
-  });
-
-  it("ignores a transcription that resolves AFTER cancel() (stale epoch — no emit)", async () => {
-    const emitted: string[] = [];
-    const hook = await startRecording((t) => emitted.push(t));
-    await emitSegments(1);
-
-    // Hard discard the session: the in-flight request is now stale.
-    act(() => {
-      hook.result.current.cancel();
-    });
-    expect(hook.result.current.status).toBe("idle");
-
-    // Its late resolution must be dropped (no emit into the new/empty session).
-    await act(async () => {
-      h.pending[0].resolve("late");
-    });
-    expect(emitted).toEqual([]);
-  });
-});

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

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

apps/client/src/features/editor/components/bubble-menu/bubble-menu.tsx

@@ -1,14 +1,7 @@
 import { BubbleMenu, BubbleMenuProps } from "@tiptap/react/menus";
 import { isNodeSelection, useEditorState } from "@tiptap/react";
 import type { Editor } from "@tiptap/react";
-import {
-  ComponentType,
-  CSSProperties,
-  FC,
-  useEffect,
-  useRef,
-  useState,
-} from "react";
+import { FC, useEffect, useRef, useState } from "react";
 import {
   IconBold,
   IconCode,
@@ -16,8 +9,6 @@ import {
   IconStrikethrough,
   IconUnderline,
   IconMessage,
-  IconEyeOff,
-  IconClearFormatting,
 } from "@tabler/icons-react";
 import clsx from "clsx";
 import classes from "./bubble-menu.module.css";
@@ -36,46 +27,12 @@ import { LinkSelector } from "@/features/editor/components/bubble-menu/link-sele
 import { useTranslation } from "react-i18next";
 import { showLinkMenuAtom } from "@/features/editor/atoms/editor-atoms";
 import { userAtom } from "@/features/user/atoms/current-user-atom";
-import {
-  hasStressAfterSelection,
-  toggleStressAccent,
-} from "./stress-accent";
-
-// Tabler has no acute-accent glyph (IconGrave is a tombstone), so we ship a
-// tiny local icon that mirrors the Tabler icon API ({ style, stroke }).
-function IconStress({
-  style,
-  stroke = 2,
-}: {
-  style?: React.CSSProperties;
-  stroke?: string | number;
-}) {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={stroke}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      style={style}
-    >
-      <path d="M5 19l5 -12l5 12" />
-      <path d="M7.5 14h5" />
-      <path d="M13 5l4 -3" />
-    </svg>
-  );
-}
 
 export interface BubbleMenuItem {
   name: string;
   isActive: () => boolean;
   command: () => void;
-  // Rendered as <item.icon style={...} stroke={2} />, so the real contract is
-  // just { style?, stroke? }. stroke is string|number to match Tabler's own prop
-  // type; Tabler icons and the local IconStress both satisfy it (no cast needed).
-  icon: ComponentType<{ style?: CSSProperties; stroke?: string | number }>;
+  icon: typeof IconBold;
 }
 
 type EditorBubbleMenuProps = Omit<BubbleMenuProps, "children" | "editor"> & {
@@ -117,9 +74,6 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
         isStrike: ctx.editor.isActive("strike"),
         isCode: ctx.editor.isActive("code"),
         isComment: ctx.editor.isActive("comment"),
-        isSpoiler: ctx.editor.isActive("spoiler"),
-        // A stress accent already sits right after the selection end.
-        isStress: hasStressAfterSelection(ctx.editor.state),
       };
     },
   });
@@ -155,32 +109,6 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
       command: () => props.editor.chain().focus().toggleCode().run(),
       icon: IconCode,
     },
-    {
-      name: "Spoiler",
-      isActive: () => editorState?.isSpoiler,
-      command: () => props.editor.chain().focus().toggleSpoiler().run(),
-      icon: IconEyeOff,
-    },
-    {
-      name: "Stress",
-      isActive: () => editorState?.isStress,
-      // Toggle the U+0301 combining accent right after the selected letter.
-      // The whole toggle is a single transaction, so one Ctrl+Z reverts it.
-      command: () => {
-        const editor = props.editor;
-        editor.view.dispatch(toggleStressAccent(editor.state));
-        editor.view.focus();
-      },
-      icon: IconStress,
-    },
-    {
-      name: "Clear formatting",
-      // Action, not a toggle — never show an active/highlighted state.
-      isActive: () => false,
-      // Mirror the fixed-toolbar behavior: strip all inline marks from the selection.
-      command: () => props.editor.chain().focus().unsetAllMarks().run(),
-      icon: IconClearFormatting,
-    },
   ];
 
   const commentItem: BubbleMenuItem = {

apps/client/src/features/editor/components/bubble-menu/stress-accent.test.ts

@@ -1,94 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { Schema } from "@tiptap/pm/model";
-import { EditorState, TextSelection } from "@tiptap/pm/state";
-import {
-  STRESS_ACCENT,
-  hasStressAfterSelection,
-  toggleStressAccent,
-} from "./stress-accent";
-
-// Minimal ProseMirror schema: paragraph of text with a single `bold` mark.
-const schema = new Schema({
-  nodes: {
-    doc: { content: "block+" },
-    paragraph: {
-      group: "block",
-      content: "text*",
-      toDOM: () => ["p", 0],
-    },
-    text: { group: "inline" },
-  },
-  marks: {
-    bold: { toDOM: () => ["strong", 0] },
-  },
-});
-
-function makeState(
-  text: string,
-  from: number,
-  to: number,
-  marked = false,
-): EditorState {
-  const marks = marked ? [schema.marks.bold.create()] : [];
-  const textNode = schema.text(text, marks);
-  const doc = schema.node("doc", null, [
-    schema.node("paragraph", null, [textNode]),
-  ]);
-  const state = EditorState.create({ schema, doc });
-  return state.apply(
-    state.tr.setSelection(TextSelection.create(state.doc, from, to)),
-  );
-}
-
-describe("stress-accent", () => {
-  it("uses U+0301 as the combining accent", () => {
-    expect(STRESS_ACCENT).toHaveLength(1);
-    expect(STRESS_ACCENT.codePointAt(0)).toBe(0x0301);
-  });
-
-  it("inserts the accent right after the selected vowel", () => {
-    // "кот", select "о" (positions 2..3).
-    const state = makeState("кот", 2, 3);
-    expect(hasStressAfterSelection(state)).toBe(false);
-
-    const next = state.apply(toggleStressAccent(state));
-    expect(next.doc.textContent).toBe(`ко${STRESS_ACCENT}т`);
-    // Selection is preserved on the letter, so the button reads active.
-    expect(next.selection.from).toBe(2);
-    expect(next.selection.to).toBe(3);
-    expect(hasStressAfterSelection(next)).toBe(true);
-  });
-
-  it("removes the accent on a second toggle (round-trips to original)", () => {
-    const state = makeState("кот", 2, 3);
-    const inserted = state.apply(toggleStressAccent(state));
-    const removed = inserted.apply(toggleStressAccent(inserted));
-
-    expect(removed.doc.textContent).toBe("кот");
-    expect(hasStressAfterSelection(removed)).toBe(false);
-    expect(removed.selection.from).toBe(2);
-    expect(removed.selection.to).toBe(3);
-  });
-
-  it("inherits the letter's marks so the accent stays bold", () => {
-    // Whole word is bold; select "о".
-    const state = makeState("кот", 2, 3, true);
-    const next = state.apply(toggleStressAccent(state));
-
-    // The accent lands at positions 3..4 (right after "о")...
-    expect(next.doc.textBetween(3, 4)).toBe(STRESS_ACCENT);
-    // ...inside a bold text node, so it inherits the letter's bold mark.
-    const accentNode = next.doc.nodeAt(3);
-    expect(accentNode?.marks.some((m) => m.type.name === "bold")).toBe(true);
-  });
-
-  it("handles a selection at the end of the doc without throwing", () => {
-    // "а" is the whole paragraph; select it (1..2), end of content.
-    const state = makeState("а", 1, 2);
-    expect(hasStressAfterSelection(state)).toBe(false);
-
-    const next = state.apply(toggleStressAccent(state));
-    expect(next.doc.textContent).toBe(`а${STRESS_ACCENT}`);
-    expect(hasStressAfterSelection(next)).toBe(true);
-  });
-});

apps/client/src/features/editor/components/bubble-menu/stress-accent.ts

@@ -1,41 +0,0 @@
-import { EditorState, TextSelection, Transaction } from "@tiptap/pm/state";
-
-// U+0301 COMBINING ACUTE ACCENT — a plain Unicode combining char inserted
-// right after a vowel to render a Russian-style stress accent over it.
-// It is stored as literal text (not a TipTap mark), so it survives HTML/
-// Markdown export, full-text search and public share with zero server or
-// converter changes.
-export const STRESS_ACCENT = "́";
-
-// True when a stress accent already sits immediately after the selection end
-// (the single char following the selection). Used both for the toolbar
-// active state and to decide the toggle direction.
-export function hasStressAfterSelection(state: EditorState): boolean {
-  const { to } = state.selection;
-  const docSize = state.doc.content.size;
-  // Clamp to the doc size so a selection at the very end never reads past it.
-  const afterChar = state.doc.textBetween(to, Math.min(to + 1, docSize));
-  return afterChar === STRESS_ACCENT;
-}
-
-// Build a single transaction that toggles the stress accent after the
-// selection. One transaction => one undo step (Ctrl+Z reverts the toggle).
-export function toggleStressAccent(state: EditorState): Transaction {
-  const { from, to } = state.selection;
-  const tr = state.tr;
-
-  if (hasStressAfterSelection(state)) {
-    // Toggle off: drop the accent that immediately follows the letter.
-    tr.delete(to, to + 1);
-  } else {
-    // Toggle on: insertText inherits the marks at `to`, so the accent lands
-    // in the same text node as the letter and renders over it even when the
-    // letter is bold / italic / colored.
-    tr.insertText(STRESS_ACCENT, to);
-  }
-
-  // Restore the original selection so the accented letter stays highlighted
-  // and a re-click toggles the accent back off.
-  tr.setSelection(TextSelection.create(tr.doc, from, to));
-  return tr;
-}

apps/client/src/features/editor/components/code-block/code-block-view.test.tsx

@@ -1,68 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { render } from "@testing-library/react";
-
-// Covers the read-only render branch (PR #278): the language <Select> renders
-// only when `editor.isEditable`; in read-only the copy button still shows.
-// Mocks mirror the #146 structural harness (footnote-views.structure.test.tsx),
-// except Select becomes a detectable node so we can assert its presence/absence.
-vi.mock("@tiptap/react", () => ({
-  NodeViewWrapper: ({ children }: any) => <div>{children}</div>,
-  NodeViewContent: (props: any) => <div data-node-view-content="" {...props} />,
-}));
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
-}));
-vi.mock("@mantine/core", () => ({
-  Group: ({ children }: any) => <div>{children}</div>,
-  Select: () => <div data-testid="language-select" />,
-  Tooltip: ({ children }: any) => <>{children}</>,
-  ActionIcon: ({ children, onClick }: any) => (
-    <button data-testid="copy-button" onClick={onClick}>
-      {children}
-    </button>
-  ),
-}));
-vi.mock("@/components/common/copy-button", () => ({
-  CopyButton: ({ children }: any) => children({ copied: false, copy: () => {} }),
-}));
-vi.mock("@tabler/icons-react", () => ({
-  IconCheck: () => null,
-  IconCopy: () => null,
-}));
-vi.mock("@/features/editor/components/code-block/mermaid-view.tsx", () => ({
-  default: () => null,
-}));
-
-import CodeBlockView from "./code-block-view";
-
-const makeProps = (isEditable: boolean) =>
-  ({
-    node: { attrs: { language: "javascript" }, textContent: "", nodeSize: 1 },
-    editor: {
-      state: { selection: { from: 0, to: 0 } },
-      isEditable,
-      commands: {},
-      on: vi.fn(),
-      off: vi.fn(),
-    },
-    extension: {
-      options: { lowlight: { listLanguages: () => ["javascript", "python"] } },
-    },
-    getPos: () => 0,
-    updateAttributes: () => {},
-    deleteNode: () => {},
-  }) as any;
-
-describe("CodeBlockView language selector visibility (#278)", () => {
-  it("renders the language selector when the editor is editable", () => {
-    const { queryByTestId } = render(<CodeBlockView {...makeProps(true)} />);
-    expect(queryByTestId("language-select")).not.toBeNull();
-    expect(queryByTestId("copy-button")).not.toBeNull();
-  });
-
-  it("hides the language selector in read-only but keeps the copy button", () => {
-    const { queryByTestId } = render(<CodeBlockView {...makeProps(false)} />);
-    expect(queryByTestId("language-select")).toBeNull();
-    expect(queryByTestId("copy-button")).not.toBeNull();
-  });
-});

apps/client/src/features/editor/components/code-block/code-block-view.tsx

@@ -50,10 +50,10 @@ export default function CodeBlockView(props: NodeViewProps) {
       {/* #146: the editable <pre><code> (contentDOM) MUST come first in the DOM.
           With the non-editable menu rendered before it, the browser's click
           hit-testing snapped the caret up one line. Render content first; the
-          menu is rendered after it and floated into the top-right corner as an
-          absolute overlay (see `.menuGroup` in code-block.module.css, anchored
-          to the `position: relative` `.codeBlock` wrapper in code.css). It no
-          longer takes a full-width row above the code. The second #146
+          menu is rendered after it and lifted back above visually via flex
+          `order: -1` (the `.codeBlock` wrapper is a flex column — see
+          code-block.module.css). It stays fully in flow as a full-width row
+          above the code: no overlay/absolute positioning. The second #146
           mitigation lives in editor-paste-handler.tsx (reflowAfterPaste). */}
       <pre
         spellCheck="false"
@@ -67,23 +67,22 @@ export default function CodeBlockView(props: NodeViewProps) {
         <NodeViewContent as="code" className={`language-${language}`} />
       </pre>
 
-      <Group contentEditable={false} className={classes.menuGroup}>
-        {/* In read-only (published) there is no language selector at all —
-            only the copy button. When editable the selector is hidden until
-            the block is hovered/focused (or its dropdown is open) via the
-            `.languageSelect` class (see code-block.module.css). */}
-        {editor.isEditable && (
-          <Select
-            placeholder="auto"
-            checkIconPosition="right"
-            data={extension.options.lowlight.listLanguages().sort()}
-            value={languageValue}
-            onChange={changeLanguage}
-            searchable
-            style={{ maxWidth: "130px" }}
-            classNames={{ root: classes.languageSelect, input: classes.selectInput }}
-          />
-        )}
+      <Group
+        justify="flex-end"
+        contentEditable={false}
+        className={classes.menuGroup}
+      >
+        <Select
+          placeholder="auto"
+          checkIconPosition="right"
+          data={extension.options.lowlight.listLanguages().sort()}
+          value={languageValue}
+          onChange={changeLanguage}
+          searchable
+          style={{ maxWidth: "130px" }}
+          classNames={{ input: classes.selectInput }}
+          disabled={!editor.isEditable}
+        />
 
         <CopyButton value={node?.textContent} timeout={2000}>
           {({ copied, copy }) => (

apps/client/src/features/editor/components/code-block/code-block.module.css

@@ -17,37 +17,15 @@
     justify-content: center;
 }
 
-/* #146: the menu follows the <pre> in the DOM (so the editable contentDOM is
-   FIRST and click hit-testing is correct). Instead of sitting in-flow, it is
-   floated into the top-right corner as an absolute overlay anchored to the
-   `position: relative` .codeBlock wrapper (see code.css), so it no longer
-   takes a full-width row above the code. The Mantine dropdown is portaled, so
-   it is never clipped by the overlay. */
+/* #146: the menu now follows the <pre> in the DOM (so the editable contentDOM is
+   FIRST and click hit-testing is correct). Lift it back ABOVE the code visually
+   with flex `order` — the .codeBlock wrapper is a flex column (see code.css) —
+   so the menu still reads as a row above the code, exactly as before, without
+   sitting in-flow before the contentDOM. */
 .menuGroup {
-    position: absolute;
-    top: 8px;
-    right: 8px;
-    z-index: 1;
-    gap: 4px;
+    order: -1;
 
     @media print {
         display: none;
     }
 }
-
-/* The language selector is hidden until the block is hovered, or the selector
-   itself is focused / its dropdown is open. It keeps its width in the flex
-   Group (only opacity toggles) so the copy button never jumps, and
-   `pointer-events: none` while hidden lets clicks fall through to the code.
-   `.codeBlock` is the global NodeViewWrapper class → use :global(). */
-.languageSelect {
-    opacity: 0;
-    pointer-events: none;
-    transition: opacity 150ms ease;
-}
-
-:global(.codeBlock):hover .languageSelect,
-.languageSelect:focus-within {
-    opacity: 1;
-    pointer-events: auto;
-}

apps/client/src/features/editor/components/common/use-alt-text-control.tsx

@@ -1,7 +1,16 @@
+import React, { useCallback, useEffect, useState } from "react";
 import { Editor } from "@tiptap/react";
+import {
+  ActionIcon,
+  Button,
+  Group,
+  Paper,
+  Text,
+  Textarea,
+  Tooltip,
+} from "@mantine/core";
 import { IconAlt } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
-import { useImageTextFieldControl } from "@/features/editor/components/common/use-image-text-field-control.tsx";
 
 const ALT_MAX_LENGTH = 300;
 
@@ -18,25 +27,113 @@ type UseAltTextControlArgs = {
   currentAlt: string;
 };
 
-// Thin wrapper over the shared image text-field popover; see
-// useImageTextFieldControl. The t("...") literals stay here so they remain
-// statically extractable for i18n.
 export function useAltTextControl({
   editor,
   nodeName,
   currentAlt,
 }: UseAltTextControlArgs) {
   const { t } = useTranslation();
-  return useImageTextFieldControl({
-    editor,
-    nodeName,
-    currentValue: currentAlt,
-    attrName: "alt",
-    sanitize: sanitizeAlt,
-    maxLength: ALT_MAX_LENGTH,
-    icon: <IconAlt size={18} />,
-    label: t("Alt text"),
-    description: t("Describe this for accessibility."),
-    placeholder: t("Add a description"),
-  });
+  const [showInput, setShowInput] = useState(false);
+  const [draft, setDraft] = useState("");
+
+  const open = useCallback(() => {
+    setDraft(currentAlt || "");
+    setShowInput(true);
+  }, [currentAlt]);
+
+  useEffect(() => {
+    const handler = () => {
+      if (!editor.isActive(nodeName)) {
+        setShowInput(false);
+      }
+    };
+    editor.on("selectionUpdate", handler);
+    return () => {
+      editor.off("selectionUpdate", handler);
+    };
+  }, [editor, nodeName]);
+
+  const cancel = useCallback(() => {
+    setShowInput(false);
+  }, []);
+
+  const save = useCallback(() => {
+    editor
+      .chain()
+      .focus(undefined, { scrollIntoView: false })
+      .updateAttributes(nodeName, { alt: sanitizeAlt(draft) || undefined })
+      .run();
+    setShowInput(false);
+  }, [editor, nodeName, draft]);
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        save();
+      } else if (e.key === "Escape") {
+        e.preventDefault();
+        cancel();
+      }
+    },
+    [save, cancel],
+  );
+
+  const button = (
+    <Tooltip position="top" label={t("Alt text")} withinPortal={false}>
+      <ActionIcon
+        onClick={open}
+        size="lg"
+        aria-label={t("Alt text")}
+        variant="subtle"
+      >
+        <IconAlt size={18} />
+      </ActionIcon>
+    </Tooltip>
+  );
+
+  const panel = showInput ? (
+    <Paper
+      withBorder
+      shadow="md"
+      radius={6}
+      p="sm"
+      w={320}
+      style={{ position: "relative", zIndex: 100 }}
+    >
+      <Text size="sm" fw={600} mb={2}>
+        {t("Alt text")}
+      </Text>
+      <Text size="xs" c="dimmed" mb="xs">
+        {t("Describe this for accessibility.")}
+      </Text>
+      <Textarea
+        size="xs"
+        placeholder={t("Add a description")}
+        value={draft}
+        onChange={(e) => setDraft(e.currentTarget.value)}
+        onKeyDown={onKeyDown}
+        autoFocus
+        autosize
+        minRows={2}
+        maxRows={5}
+        maxLength={ALT_MAX_LENGTH}
+      />
+      <Group justify="space-between" align="center" mt="xs" wrap="nowrap">
+        <Text size="xs" c="dimmed">
+          {draft.length}/{ALT_MAX_LENGTH}
+        </Text>
+        <Group gap="xs">
+          <Button size="compact-xs" variant="default" onClick={cancel}>
+            {t("Cancel")}
+          </Button>
+          <Button size="compact-xs" onClick={save}>
+            {t("Save")}
+          </Button>
+        </Group>
+      </Group>
+    </Paper>
+  ) : null;
+
+  return { button, panel, isEditing: showInput };
 }

apps/client/src/features/editor/components/common/use-caption-control.test.ts

@@ -1,59 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { sanitizeCaption } from "@/features/editor/components/common/use-caption-control.tsx";
-
-/**
- * `sanitizeCaption` = collapse every whitespace run to a single space + trim +
- * cap at 500 chars. Captions are plain visible text, so this is a softer
- * normalization than alt-text sanitization.
- */
-describe("sanitizeCaption", () => {
-  it("trims leading and trailing whitespace", () => {
-    expect(sanitizeCaption("  hello  ")).toBe("hello");
-  });
-
-  it("collapses internal whitespace runs to a single space", () => {
-    expect(sanitizeCaption("a   b    c")).toBe("a b c");
-  });
-
-  it("treats tab, newline and CRLF as whitespace", () => {
-    expect(sanitizeCaption("a\tb")).toBe("a b");
-    expect(sanitizeCaption("a\nb")).toBe("a b");
-    expect(sanitizeCaption("a\r\nb")).toBe("a b");
-    expect(sanitizeCaption("line1\n\n\nline2")).toBe("line1 line2");
-  });
-
-  it("treats unicode whitespace (no-break space) as a separator", () => {
-    // U+00A0 NO-BREAK SPACE is matched by the \s class.
-    expect(sanitizeCaption("a b")).toBe("a b");
-  });
-
-  it("returns empty string for whitespace-only input", () => {
-    expect(sanitizeCaption("   ")).toBe("");
-    expect(sanitizeCaption("")).toBe("");
-  });
-
-  it("keeps a caption at the 500-char limit unchanged", () => {
-    const exact = "x".repeat(500);
-    expect(sanitizeCaption(exact)).toHaveLength(500);
-    expect(sanitizeCaption(exact)).toBe(exact);
-  });
-
-  it("slices a caption longer than 500 chars down to 500", () => {
-    const tooLong = "y".repeat(600);
-    const result = sanitizeCaption(tooLong);
-    expect(result).toHaveLength(500);
-    expect(result).toBe("y".repeat(500));
-  });
-
-  it("collapses whitespace before applying the 500-char cap", () => {
-    // 120 "a  b " groups (600 raw chars) collapse to "a b a b ..." = 479 chars
-    // after trimming the trailing space, which stays under the 500 cap — so only
-    // the collapse is exercised here, no slice. (See the dedicated >500 test
-    // above for the slice boundary.)
-    const input = "a  b ".repeat(120); // lots of double spaces
-    const result = sanitizeCaption(input);
-    expect(result).toHaveLength(479);
-    expect(result.length).toBeLessThanOrEqual(500);
-    expect(result).not.toMatch(/\s{2,}/);
-  });
-});

apps/client/src/features/editor/components/common/use-caption-control.tsx

@@ -1,42 +0,0 @@
-import { Editor } from "@tiptap/react";
-import { IconTextCaption } from "@tabler/icons-react";
-import { useTranslation } from "react-i18next";
-import { useImageTextFieldControl } from "@/features/editor/components/common/use-image-text-field-control.tsx";
-
-const CAPTION_MAX_LENGTH = 500;
-
-// Caption is plain visible text (not a markdown link target like alt), so it is
-// sanitized more softly than alt: collapse runs of whitespace/newlines into a
-// single space and trim, keeping the limit generous.
-export function sanitizeCaption(value: string): string {
-  return value.replace(/\s+/g, " ").trim().slice(0, CAPTION_MAX_LENGTH);
-}
-
-type UseCaptionControlArgs = {
-  editor: Editor;
-  nodeName: string;
-  currentCaption: string;
-};
-
-// Thin wrapper over the shared image text-field popover; see
-// useImageTextFieldControl. The t("...") literals stay here so they remain
-// statically extractable for i18n.
-export function useCaptionControl({
-  editor,
-  nodeName,
-  currentCaption,
-}: UseCaptionControlArgs) {
-  const { t } = useTranslation();
-  return useImageTextFieldControl({
-    editor,
-    nodeName,
-    currentValue: currentCaption,
-    attrName: "caption",
-    sanitize: sanitizeCaption,
-    maxLength: CAPTION_MAX_LENGTH,
-    icon: <IconTextCaption size={18} />,
-    label: t("Caption"),
-    description: t("Shown below the image."),
-    placeholder: t("Add a caption"),
-  });
-}

apps/client/src/features/editor/components/common/use-image-text-field-control.tsx

@@ -1,145 +0,0 @@
-import React, { useCallback, useEffect, useState } from "react";
-import { Editor } from "@tiptap/react";
-import {
-  ActionIcon,
-  Button,
-  Group,
-  Paper,
-  Text,
-  Textarea,
-  Tooltip,
-} from "@mantine/core";
-import { useTranslation } from "react-i18next";
-
-// Shared logic+UI for the image bubble-menu text-field popovers (alt text,
-// caption, ...). Each field is the same popover — an ActionIcon that opens a
-// titled Paper with a counted Textarea and Cancel/Save — differing only in the
-// node attribute it writes, its sanitizer, length cap, icon and labels. The
-// label/description/placeholder are passed already translated so the literal
-// t("...") calls stay in the thin wrappers and remain extractable; the shared
-// Cancel/Save strings are translated here.
-type UseImageTextFieldControlArgs = {
-  editor: Editor;
-  nodeName: string;
-  currentValue: string;
-  attrName: string;
-  sanitize: (value: string) => string;
-  maxLength: number;
-  icon: React.ReactNode;
-  label: string;
-  description: string;
-  placeholder: string;
-};
-
-export function useImageTextFieldControl({
-  editor,
-  nodeName,
-  currentValue,
-  attrName,
-  sanitize,
-  maxLength,
-  icon,
-  label,
-  description,
-  placeholder,
-}: UseImageTextFieldControlArgs) {
-  const { t } = useTranslation();
-  const [showInput, setShowInput] = useState(false);
-  const [draft, setDraft] = useState("");
-
-  const open = useCallback(() => {
-    setDraft(currentValue || "");
-    setShowInput(true);
-  }, [currentValue]);
-
-  useEffect(() => {
-    const handler = () => {
-      if (!editor.isActive(nodeName)) {
-        setShowInput(false);
-      }
-    };
-    editor.on("selectionUpdate", handler);
-    return () => {
-      editor.off("selectionUpdate", handler);
-    };
-  }, [editor, nodeName]);
-
-  const cancel = useCallback(() => {
-    setShowInput(false);
-  }, []);
-
-  const save = useCallback(() => {
-    editor
-      .chain()
-      .focus(undefined, { scrollIntoView: false })
-      .updateAttributes(nodeName, { [attrName]: sanitize(draft) || undefined })
-      .run();
-    setShowInput(false);
-  }, [editor, nodeName, attrName, sanitize, draft]);
-
-  const onKeyDown = useCallback(
-    (e: React.KeyboardEvent) => {
-      if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault();
-        save();
-      } else if (e.key === "Escape") {
-        e.preventDefault();
-        cancel();
-      }
-    },
-    [save, cancel],
-  );
-
-  const button = (
-    <Tooltip position="top" label={label} withinPortal={false}>
-      <ActionIcon onClick={open} size="lg" aria-label={label} variant="subtle">
-        {icon}
-      </ActionIcon>
-    </Tooltip>
-  );
-
-  const panel = showInput ? (
-    <Paper
-      withBorder
-      shadow="md"
-      radius={6}
-      p="sm"
-      w={320}
-      style={{ position: "relative", zIndex: 100 }}
-    >
-      <Text size="sm" fw={600} mb={2}>
-        {label}
-      </Text>
-      <Text size="xs" c="dimmed" mb="xs">
-        {description}
-      </Text>
-      <Textarea
-        size="xs"
-        placeholder={placeholder}
-        value={draft}
-        onChange={(e) => setDraft(e.currentTarget.value)}
-        onKeyDown={onKeyDown}
-        autoFocus
-        autosize
-        minRows={2}
-        maxRows={5}
-        maxLength={maxLength}
-      />
-      <Group justify="space-between" align="center" mt="xs" wrap="nowrap">
-        <Text size="xs" c="dimmed">
-          {draft.length}/{maxLength}
-        </Text>
-        <Group gap="xs">
-          <Button size="compact-xs" variant="default" onClick={cancel}>
-            {t("Cancel")}
-          </Button>
-          <Button size="compact-xs" onClick={save}>
-            {t("Save")}
-          </Button>
-        </Group>
-      </Group>
-    </Paper>
-  ) : null;
-
-  return { button, panel, isEditing: showInput };
-}

apps/client/src/features/editor/components/image/image-menu.tsx

@@ -15,7 +15,6 @@ import {
   IconLayoutAlignRight,
   IconFloatLeft,
   IconFloatRight,
-  IconLayoutColumns,
   IconDownload,
   IconRefresh,
   IconTrash,
@@ -24,7 +23,6 @@ import { useTranslation } from "react-i18next";
 import { getFileUrl } from "@/lib/config.ts";
 import { uploadImageAction } from "@/features/editor/components/image/upload-image-action.tsx";
 import { useAltTextControl } from "@/features/editor/components/common/use-alt-text-control.tsx";
-import { useCaptionControl } from "@/features/editor/components/common/use-caption-control.tsx";
 import classes from "../common/toolbar-menu.module.css";
 
 export function ImageMenu({ editor }: EditorMenuProps) {
@@ -47,10 +45,8 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         isAlignRight: ctx.editor.isActive("image", { align: "right" }),
         isFloatLeft: ctx.editor.isActive("image", { align: "floatLeft" }),
         isFloatRight: ctx.editor.isActive("image", { align: "floatRight" }),
-        isInline: ctx.editor.isActive("image", { align: "inline" }),
         src: imageAttrs?.src || null,
         alt: imageAttrs?.alt || "",
-        caption: imageAttrs?.caption || "",
       };
     },
   });
@@ -128,14 +124,6 @@ export function ImageMenu({ editor }: EditorMenuProps) {
       .run();
   }, [editor]);
 
-  const alignImageInline = useCallback(() => {
-    editor
-      .chain()
-      .focus(undefined, { scrollIntoView: false })
-      .setImageAlign("inline")
-      .run();
-  }, [editor]);
-
   const handleDownload = useCallback(() => {
     if (!editorState?.src) return;
     const url = getFileUrl(editorState.src);
@@ -180,16 +168,6 @@ export function ImageMenu({ editor }: EditorMenuProps) {
     currentAlt: editorState?.alt || "",
   });
 
-  const {
-    button: captionButton,
-    panel: captionPanel,
-    isEditing: isEditingCaption,
-  } = useCaptionControl({
-    editor,
-    nodeName: "image",
-    currentCaption: editorState?.caption || "",
-  });
-
   return (
     <BaseBubbleMenu
       editor={editor}
@@ -205,8 +183,6 @@ export function ImageMenu({ editor }: EditorMenuProps) {
     >
       {isEditingAlt ? (
         altTextPanel
-      ) : isEditingCaption ? (
-        captionPanel
       ) : (
         <div className={classes.toolbar}>
         <Tooltip position="top" label={t("Align left")} withinPortal={false}>
@@ -269,24 +245,10 @@ export function ImageMenu({ editor }: EditorMenuProps) {
           </ActionIcon>
         </Tooltip>
 
-        <Tooltip position="top" label={t("Inline (side by side)")} withinPortal={false}>
-          <ActionIcon
-            onClick={alignImageInline}
-            size="lg"
-            aria-label={t("Inline (side by side)")}
-            variant="subtle"
-            className={clsx({ [classes.active]: editorState?.isInline })}
-          >
-            <IconLayoutColumns size={18} />
-          </ActionIcon>
-        </Tooltip>
-
         <div className={classes.divider} />
 
         {altTextButton}
 
-        {captionButton}
-
         <div className={classes.divider} />
 
         <Tooltip position="top" label={t("Download")} withinPortal={false}>

apps/client/src/features/editor/components/image/image-view.tsx

@@ -9,9 +9,7 @@ import { useTranslation } from "react-i18next";
 export default function ImageView(props: NodeViewProps) {
   const { t } = useTranslation();
   const { editor, node, selected } = props;
-  const { src, width, align, alt, caption, aspectRatio, placeholder } =
-    node.attrs;
-  const captionText = (caption || "").trim();
+  const { src, width, align, alt, aspectRatio, placeholder } = node.attrs;
   const alignClass = useMemo(() => {
     if (align === "left") return "alignLeft";
     if (align === "right") return "alignRight";
@@ -31,7 +29,6 @@ export default function ImageView(props: NodeViewProps) {
 
   return (
     <NodeViewWrapper data-drag-handle>
-      <figure style={{ margin: 0 }}>
       <div
         className={clsx(
           selected && "ProseMirror-selectednode",
@@ -69,15 +66,6 @@ export default function ImageView(props: NodeViewProps) {
           </Group>
         )}
       </div>
-      {captionText && (
-        <Text
-          component="figcaption"
-          className="image-caption"
-        >
-          {captionText}
-        </Text>
-      )}
-      </figure>
     </NodeViewWrapper>
   );
 }

apps/client/src/features/editor/components/link/internal-link-paste.test.ts

@@ -1,194 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-// Mock the page-service so importing the module under test does not pull in the
-// axios/api-client chain. `createMentionAction` is wired to `getPageById`; the
-// spy lets us assert that wiring without any network. `vi.hoisted` keeps the spy
-// available inside the hoisted vi.mock factory.
-const { getPageById } = vi.hoisted(() => ({ getPageById: vi.fn() }));
-vi.mock("@/features/page/services/page-service.ts", () => ({
-  getPageById,
-}));
-
-// `uuid` v7 is used for the mention node id; pin only v7 so assertions are
-// stable, keeping the rest (e.g. `validate`, used by extractPageSlugId) real.
-vi.mock("uuid", async (importOriginal) => ({
-  ...(await importOriginal<typeof import("uuid")>()),
-  v7: () => "fixed-mention-uuid",
-}));
-
-import {
-  handleInternalLink,
-  createMentionAction,
-} from "./internal-link-paste";
-
-// Minimal ProseMirror-ish EditorView fake. We record what handleInternalLink
-// builds and dispatches without standing up a real schema/state.
-function makeView() {
-  const tr = {
-    replaceWith: vi.fn(function (this: unknown) {
-      return tr;
-    }),
-    insertText: vi.fn(function (this: unknown) {
-      return tr;
-    }),
-    addMark: vi.fn(function (this: unknown) {
-      return tr;
-    }),
-  };
-  const schema = {
-    nodes: {
-      mention: {
-        // Echo the attrs back so we can assert exactly what was created.
-        create: vi.fn((attrs: Record<string, unknown>) => ({
-          type: "mention",
-          attrs,
-        })),
-      },
-    },
-    marks: {
-      link: {
-        create: vi.fn((attrs: Record<string, unknown>) => ({
-          type: "link",
-          attrs,
-        })),
-      },
-    },
-  };
-  const view = {
-    state: { schema, tr },
-    dispatch: vi.fn(),
-  };
-  return { view, tr, schema };
-}
-
-describe("handleInternalLink", () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  it("does nothing when validateFn rejects the url (no resolve, no dispatch)", async () => {
-    const onResolveLink = vi.fn();
-    const validateFn = vi.fn(() => false);
-    const { view } = makeView();
-
-    await handleInternalLink({ validateFn, onResolveLink })(
-      "any-url",
-      view as never,
-      3,
-      "creator-1",
-    );
-
-    expect(validateFn).toHaveBeenCalledWith("any-url", view);
-    expect(onResolveLink).not.toHaveBeenCalled();
-    expect(view.dispatch).not.toHaveBeenCalled();
-  });
-
-  it("on resolve: inserts a mention node carrying the resolved page + anchor and dispatches replaceWith at pos", async () => {
-    const page = {
-      id: "page-id-99",
-      title: "My Page",
-      slugId: "slugABC",
-    };
-    const onResolveLink = vi.fn().mockResolvedValue(page);
-    const { view, tr, schema } = makeView();
-
-    // extractPageSlugId("doc-slug-xyz789") -> "xyz789" (last hyphen segment).
-    await handleInternalLink({ validateFn: () => true, onResolveLink })(
-      "doc-slug-xyz789",
-      view as never,
-      5,
-      "creator-7",
-      "anchor-42",
-    );
-
-    // The linked page id is the extracted slug-id, not the whole url.
-    expect(onResolveLink).toHaveBeenCalledWith("xyz789", "creator-7");
-    expect(schema.nodes.mention.create).toHaveBeenCalledWith({
-      id: "fixed-mention-uuid",
-      label: "My Page",
-      entityType: "page",
-      entityId: "page-id-99",
-      slugId: "slugABC",
-      creatorId: "creator-7",
-      anchorId: "anchor-42",
-    });
-    expect(tr.replaceWith).toHaveBeenCalledWith(5, 5, {
-      type: "mention",
-      attrs: expect.objectContaining({ entityId: "page-id-99" }),
-    });
-    expect(tr.insertText).not.toHaveBeenCalled();
-    expect(view.dispatch).toHaveBeenCalledTimes(1);
-    expect(view.dispatch).toHaveBeenCalledWith(tr);
-  });
-
-  it("falls back to 'Untitled' label when the resolved page has no title", async () => {
-    const onResolveLink = vi
-      .fn()
-      .mockResolvedValue({ id: "p", title: "", slugId: "s" });
-    const { view, schema } = makeView();
-
-    await handleInternalLink({ validateFn: () => true, onResolveLink })(
-      "abc-id1",
-      view as never,
-      0,
-      "c",
-    );
-
-    expect(schema.nodes.mention.create).toHaveBeenCalledWith(
-      expect.objectContaining({ label: "Untitled" }),
-    );
-  });
-
-  it("on reject: inserts the raw url as plain text with a link mark and dispatches", async () => {
-    const onResolveLink = vi.fn().mockRejectedValue(new Error("not found"));
-    const { view, tr, schema } = makeView();
-
-    await handleInternalLink({ validateFn: () => true, onResolveLink })(
-      "http://x/page-id2",
-      view as never,
-      4,
-      "creator-1",
-    );
-
-    // No mention node on the failure path.
-    expect(schema.nodes.mention.create).not.toHaveBeenCalled();
-    expect(tr.insertText).toHaveBeenCalledWith("http://x/page-id2", 4);
-    expect(schema.marks.link.create).toHaveBeenCalledWith({
-      href: "http://x/page-id2",
-    });
-    // Mark spans exactly the inserted url text: [pos, pos + url.length].
-    expect(tr.addMark).toHaveBeenCalledWith(4, 4 + "http://x/page-id2".length, {
-      type: "link",
-      attrs: { href: "http://x/page-id2" },
-    });
-    expect(view.dispatch).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("createMentionAction", () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  it("resolves the link via getPageById and inserts the mention", async () => {
-    getPageById.mockResolvedValue({
-      id: "real-page",
-      title: "Real",
-      slugId: "rslug",
-    });
-    const { view, schema } = makeView();
-
-    await createMentionAction("ref-pageABC", view as never, 2, "creator-9");
-
-    expect(getPageById).toHaveBeenCalledWith({ pageId: "pageABC" });
-    expect(schema.nodes.mention.create).toHaveBeenCalledWith(
-      expect.objectContaining({ entityId: "real-page", label: "Real" }),
-    );
-  });
-
-  it("propagates a getPageById failure to the plain-link fallback", async () => {
-    getPageById.mockRejectedValue(new Error("404"));
-    const { view, tr } = makeView();
-
-    await createMentionAction("ref-pageABC", view as never, 1, "creator-9");
-
-    // Failure path: the url is inserted as text, not as a mention node.
-    expect(tr.insertText).toHaveBeenCalledWith("ref-pageABC", 1);
-  });
-});

apps/client/src/features/editor/components/slash-menu/menu-items.layout.test.ts

@@ -1,86 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  buildLayoutCandidates,
-  getSuggestionItems,
-} from "./menu-items";
-
-/**
- * `buildLayoutCandidates` maps a slash query across physical keyboard layouts
- * (RU ЙЦУКЕН <-> US QWERTY) so the menu matches Latin item titles/terms even
- * when typed with the wrong layout active, while keeping the original query so
- * genuine Cyrillic search terms still match. See bug #283.
- */
-describe("buildLayoutCandidates", () => {
-  it("remaps a RU-layout query to its US-QWERTY equivalent (сщву -> code)", () => {
-    expect(buildLayoutCandidates("сщву")).toContain("code");
-  });
-
-  it("remaps a US-layout query to its RU-ЙЦУКЕН equivalent (cyjcrf -> сноска)", () => {
-    expect(buildLayoutCandidates("cyjcrf")).toContain("сноска");
-  });
-
-  it("always includes the original query", () => {
-    expect(buildLayoutCandidates("сщву")).toContain("сщву");
-    expect(buildLayoutCandidates("cyjcrf")).toContain("cyjcrf");
-    expect(buildLayoutCandidates("сноска")).toContain("сноска");
-  });
-
-  it("leaves a query with no mappable keys as a single-element set", () => {
-    // Digits are on neither layout map, so both remaps are no-ops and de-dup
-    // back to one entry.
-    expect(buildLayoutCandidates("123")).toEqual(["123"]);
-  });
-});
-
-/** Helper: flatten grouped suggestion items to a flat list of titles. */
-const titles = (groups: ReturnType<typeof getSuggestionItems>): string[] =>
-  Object.values(groups).flatMap((items) => items.map((i) => i.title));
-
-describe("getSuggestionItems layout-aware matching", () => {
-  it("finds Code when 'code' is typed in RU layout (/сщву)", () => {
-    expect(titles(getSuggestionItems({ query: "сщву" }))).toContain("Code");
-  });
-
-  it("still finds Code for the plain /code query", () => {
-    expect(titles(getSuggestionItems({ query: "code" }))).toContain("Code");
-  });
-
-  it("finds Code for a short wrong-layout prefix (/сщ -> co)", () => {
-    // "сщ" RU->EN remaps to "co", which fuzzy-matches the "Code" title. Short
-    // remaps are title-only, but a title match must still get through. See #283.
-    expect(titles(getSuggestionItems({ query: "сщ" }))).toContain("Code");
-  });
-
-  it("still finds Code for the plain short query (/co)", () => {
-    // Sanity: the original (non-remapped) short query keeps full matching.
-    expect(titles(getSuggestionItems({ query: "co" }))).toContain("Code");
-  });
-
-  it("still matches genuine Cyrillic search terms (/сноска -> Footnote)", () => {
-    expect(titles(getSuggestionItems({ query: "сноска" }))).toContain(
-      "Footnote",
-    );
-  });
-
-  it("finds Footnote when 'сноска' is typed in EN layout (/cyjcrf)", () => {
-    expect(titles(getSuggestionItems({ query: "cyjcrf" }))).toContain(
-      "Footnote",
-    );
-  });
-
-  it("does not surface Footnote for a short wrong-layout query (/cy)", () => {
-    // "cy" EN->RU remaps to "сн", a substring of the "сноска" searchTerm, but
-    // the gate blocks it because the remapped candidate is < 3 chars.
-    expect(titles(getSuggestionItems({ query: "cy" }))).not.toContain(
-      "Footnote",
-    );
-  });
-
-  it("does not surface Footnote for a single-char wrong-layout query (/b)", () => {
-    // "b" EN->RU remaps to "и", a substring of the "примечание" searchTerm, but
-    // the gate blocks it because the remapped candidate is < 3 chars.
-    expect(titles(getSuggestionItems({ query: "b" }))).not.toContain(
-      "Footnote",
-    );
-  });
-});

apps/client/src/features/editor/components/slash-menu/menu-items.ts

@@ -35,7 +35,6 @@ import { PAGE_EMBED_PICKER_EVENT } from "@/features/editor/components/page-embed
 import {
   CommandProps,
   SlashMenuGroupedItemsType,
-  SlashMenuItemType,
 } from "@/features/editor/components/slash-menu/types";
 import { uploadImageAction } from "@/features/editor/components/image/upload-image-action.tsx";
 import { uploadVideoAction } from "@/features/editor/components/video/upload-video-action.tsx";
@@ -836,49 +835,6 @@ export function isHtmlEmbedFeatureEnabled(): boolean {
   }
 }
 
-// Russian ЙЦУКЕН -> US QWERTY by physical key position (lowercase; callers
-// lowercase first). Lets the slash menu match Latin item titles/terms even when
-// a command is typed with the wrong keyboard layout active (e.g. "/сщву" while
-// ЙЦУКЕН is on physically types the same keys as "/code").
-const RU_TO_EN_LAYOUT: Record<string, string> = {
-  й: "q", ц: "w", у: "e", к: "r", е: "t", н: "y", г: "u", ш: "i", щ: "o",
-  з: "p", х: "[", ъ: "]",
-  ф: "a", ы: "s", в: "d", а: "f", п: "g", р: "h", о: "j", л: "k", д: "l",
-  ж: ";", э: "'",
-  я: "z", ч: "x", с: "c", м: "v", и: "b", т: "n", ь: "m", б: ",", ю: ".",
-  ё: "`",
-};
-// Inverse map: US QWERTY -> Russian ЙЦУКЕН by physical key position. Handles the
-// mirror case (e.g. "cyjcrf" typed with EN layout on == "сноска" == Footnote).
-const EN_TO_RU_LAYOUT: Record<string, string> = Object.fromEntries(
-  Object.entries(RU_TO_EN_LAYOUT).map(([ru, en]) => [en, ru]),
-);
-
-function translitByLayout(text: string, map: Record<string, string>): string {
-  let out = "";
-  for (const ch of text) out += map[ch] ?? ch;
-  return out;
-}
-
-/**
- * Build the list of search strings to try for a given query: the original
- * query first, followed by its RU->EN and EN->RU physical-layout remappings.
- * Keeping the original first preserves genuine Cyrillic search terms (e.g.
- * "сноска"/"примечание" for Footnote) and lets callers treat the original
- * differently from the remapped candidates. De-duplication only collapses the
- * list to one element when nothing is remappable (e.g. digits/spaces), so a
- * typical ASCII query still yields multiple candidates.
- */
-export function buildLayoutCandidates(search: string): string[] {
-  return [
-    ...new Set([
-      search,
-      translitByLayout(search, RU_TO_EN_LAYOUT),
-      translitByLayout(search, EN_TO_RU_LAYOUT),
-    ]),
-  ];
-}
-
 export const getSuggestionItems = ({
   query,
   excludeItems,
@@ -887,18 +843,6 @@ export const getSuggestionItems = ({
   excludeItems?: Set<string>;
 }): SlashMenuGroupedItemsType => {
   const search = query.toLowerCase();
-  const candidates = buildLayoutCandidates(search);
-  // buildLayoutCandidates dedupes the remaps against the original, so
-  // candidates[0] is the original query and the rest are wrong-layout remaps.
-  // The original query matches on everything (title, description, searchTerms).
-  // A remapped candidate matches fully only when it is long enough to be
-  // unambiguous; a short (1-2 char) remap is restricted to a TITLE match so it
-  // does not spuriously substring-match unrelated Cyrillic search terms
-  // (e.g. "/cy" -> "сн" hitting the "сноска" searchTerm, "/b" -> "и" hitting
-  // "примечание"), while still letting a real short wrong-layout prefix through
-  // (e.g. "/сщ" -> "co" fuzzy-matching the "Code" title).
-  const REMAP_FULL_MATCH_MIN_LEN = 3;
-  const [originalCandidate, ...remapped] = candidates;
   const filteredGroups: SlashMenuGroupedItemsType = {};
   const htmlEmbedFeatureEnabled = isHtmlEmbedFeatureEnabled();
 
@@ -912,52 +856,24 @@ export const getSuggestionItems = ({
     return false;
   };
 
-  const candidateMatchesItem = (
-    candidate: string,
-    item: SlashMenuItemType,
-    description: string,
-    titleOnly: boolean,
-  ) => {
-    if (fuzzyMatch(candidate, item.title)) return true;
-    if (titleOnly) return false;
-    return (
-      description.includes(candidate) ||
-      (item.searchTerms != null &&
-        item.searchTerms.some((term: string) => term.includes(candidate)))
-    );
-  };
-
   for (const [group, items] of Object.entries(CommandGroups)) {
     const filteredItems = items.filter((item) => {
       if (excludeItems?.has(item.title)) return false;
       // Hide the HTML embed item unless the workspace master toggle is ON.
       if (item.requiresHtmlEmbedFeature && !htmlEmbedFeatureEnabled)
         return false;
-      const description = item.description.toLowerCase();
       return (
-        candidateMatchesItem(originalCandidate, item, description, false) ||
-        remapped.some((candidate) =>
-          candidateMatchesItem(
-            candidate,
-            item,
-            description,
-            candidate.length < REMAP_FULL_MATCH_MIN_LEN,
-          ),
-        )
+        fuzzyMatch(search, item.title) ||
+        item.description.toLowerCase().includes(search) ||
+        (item.searchTerms &&
+          item.searchTerms.some((term: string) => term.includes(search)))
       );
     });
 
     if (filteredItems.length) {
-      const titleMatchesAnyCandidate = (title: string) => {
-        const lower = title.toLowerCase();
-        return (
-          lower.includes(originalCandidate) ||
-          remapped.some((candidate) => lower.includes(candidate))
-        );
-      };
       filteredGroups[group] = filteredItems.sort((a, b) => {
-        const aTitle = titleMatchesAnyCandidate(a.title) ? 0 : 1;
-        const bTitle = titleMatchesAnyCandidate(b.title) ? 0 : 1;
+        const aTitle = a.title.toLowerCase().includes(search) ? 0 : 1;
+        const bTitle = b.title.toLowerCase().includes(search) ? 0 : 1;
         return aTitle - bTitle;
       });
     }

apps/client/src/features/editor/components/spoiler/spoiler-view.tsx

@@ -1,20 +0,0 @@
-import { MarkViewContent, MarkViewProps } from "@tiptap/react";
-import { useState } from "react";
-
-// Click-to-reveal spoiler. The revealed state is UI-only and is never written to
-// the document: toggling only adds/removes the `is-revealed` class (CSS removes
-// the blur). renderHTML never emits `is-revealed`, so it can't leak into the
-// doc/clipboard. Works the same in editor, read-only and public-share views.
-export default function SpoilerView(_props: MarkViewProps) {
-  const [revealed, setRevealed] = useState(false);
-
-  return (
-    <span
-      className={revealed ? "spoiler is-revealed" : "spoiler"}
-      data-spoiler="true"
-      onClick={() => setRevealed((v) => !v)}
-    >
-      <MarkViewContent />
-    </span>
-  );
-}

apps/client/src/features/editor/components/table/handle/cell-chevron.tsx

@@ -11,7 +11,6 @@ import clsx from "clsx";
 import { useTranslation } from "react-i18next";
 import { isCellSelection } from "@docmost/editor-ext";
 import { CellChevronMenu } from "./menus/cell-chevron-menu";
-import { refocusEditorAfterMenuClose } from "./hooks/use-column-row-menu-lifecycle";
 import classes from "./handle.module.css";
 
 interface CellChevronProps {
@@ -88,7 +87,6 @@ export const CellChevron = React.memo(function CellChevron({
 
   const onClose = useCallback(() => {
     editor.commands.unfreezeHandles();
-    refocusEditorAfterMenuClose(editor);
   }, [editor]);
 
   if (!cellDom) return null;

apps/client/src/features/editor/components/table/handle/hooks/use-column-row-menu-lifecycle.test.ts

@@ -1,56 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import type { Editor } from "@tiptap/react";
-import { refocusEditorAfterMenuClose } from "./use-column-row-menu-lifecycle";
-
-// A minimal fake editor. `view.dom` is a real element so `.contains()` works,
-// and `view.focus` is a spy so we assert on it without relying on real DOM
-// focus (unreliable in jsdom). rAF is stubbed to a `setTimeout(0)` so fake
-// timers can flush the deferred callback deterministically.
-function makeEditor() {
-  const dom = document.createElement("div");
-  document.body.appendChild(dom);
-  const focus = vi.fn();
-  const editor = { isDestroyed: false, view: { dom, focus } };
-  return { editor: editor as unknown as Editor, focus, dom };
-}
-
-describe("refocusEditorAfterMenuClose", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) =>
-      setTimeout(() => cb(0), 0),
-    );
-  });
-
-  afterEach(() => {
-    vi.runOnlyPendingTimers();
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-    document.body.innerHTML = "";
-  });
-
-  it("(a) does not refocus the editor when an external <input> is active", () => {
-    const { editor, focus } = makeEditor();
-    const input = document.createElement("input");
-    document.body.appendChild(input);
-    input.focus();
-    expect(document.activeElement).toBe(input);
-
-    refocusEditorAfterMenuClose(editor);
-    vi.runAllTimers();
-
-    expect(focus).not.toHaveBeenCalled();
-  });
-
-  it("(b) refocuses the editor when a non-focusable element (body) is active", () => {
-    const { editor, focus } = makeEditor();
-    // Ensure focus rests on body: nothing is focused / an <input> was blurred.
-    (document.activeElement as HTMLElement | null)?.blur();
-    expect(document.activeElement).toBe(document.body);
-
-    refocusEditorAfterMenuClose(editor);
-    vi.runAllTimers();
-
-    expect(focus).toHaveBeenCalledTimes(1);
-  });
-});

apps/client/src/features/editor/components/table/handle/hooks/use-column-row-menu-lifecycle.ts

@@ -11,39 +11,6 @@ interface Args {
   tablePos: number;
 }
 
-/**
- * Restore focus to the editor after a table handle/cell menu closes.
- *
- * The grip/chevron menus are Mantine `<Menu>`s with `returnFocus: true`, and
- * their targets live in a floating/portaled layer OUTSIDE the editor's
- * contenteditable. After an action (delete row/column, insert, etc.) the menu
- * closes and Mantine returns focus to that outside target, so ProseMirror's
- * undo keymap never sees Ctrl+Z until the user clicks back into a cell.
- *
- * We defer with `requestAnimationFrame` so this runs AFTER Mantine's
- * returnFocus, and guard against stealing focus if the user intentionally
- * moved to another input/editable (e.g. the page title).
- */
-export function refocusEditorAfterMenuClose(editor: Editor) {
-  requestAnimationFrame(() => {
-    if (editor.isDestroyed) return;
-    const active = document.activeElement as HTMLElement | null;
-    // Already inside the editor — nothing to do.
-    if (active && editor.view.dom.contains(active)) return;
-    // Respect a deliberate move to another field/editable.
-    const tag = active?.tagName;
-    if (
-      tag === "INPUT" ||
-      tag === "TEXTAREA" ||
-      tag === "SELECT" ||
-      active?.isContentEditable
-    ) {
-      return;
-    }
-    editor.view.focus(); // pure DOM focus, no extra transaction
-  });
-}
-
 export function useColumnRowMenuLifecycle({
   editor,
   orientation,
@@ -67,7 +34,6 @@ export function useColumnRowMenuLifecycle({
 
   const onClose = useCallback(() => {
     editor.commands.unfreezeHandles();
-    refocusEditorAfterMenuClose(editor);
   }, [editor]);
 
   return { onOpen, onClose };

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

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

apps/client/src/features/editor/extensions/custom-typography.test.ts

@@ -1,231 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { Editor } from "@tiptap/core";
-import { Document } from "@tiptap/extension-document";
-import { Paragraph } from "@tiptap/extension-paragraph";
-import { Text } from "@tiptap/extension-text";
-import { ySyncPluginKey } from "@tiptap/y-tiptap";
-import {
-  CustomTypography,
-  undoGuardKey,
-  findChangedRange,
-  mapRangeThroughChange,
-} from "./custom-typography";
-
-/**
- * PR #296 — the collab-safe typography undo-guard is exercised through the REAL
- * editor path: a fresh Editor with the CustomTypography extension, transactions
- * tagged exactly the way prosemirror-history / y-tiptap tag undo & remote
- * changes (`setMeta("history$", …)` and `setMeta(ySyncPluginKey, …)`), plus
- * direct unit tests of the two pure diff helpers. No hand-poke of plugin state.
- *
- * ARMING MECHANISM (verified against custom-typography.ts source):
- *   - A transaction arms the guard only when it is BOTH history/remote
- *     (`getMeta("history$")` truthy, or `isChangeOrigin` via the ySync meta)
- *     AND an undo/redo (`getMeta("history$")` truthy, or ySync
- *     `isUndoRedoOperation`), AND its whole-doc diff is a REPLACE
- *     (change.oldTo > change.from && change.newTo > change.from).
- *   - `history$` is the stringified PluginKey of the single prosemirror-history
- *     plugin; ProseMirror stores meta under `key.key`, so setMeta("history$")
- *     in a test is read identically by the extension's getMeta("history$").
- */
-
-const singlePara = (text: string) => ({
-  type: "doc",
-  content: [{ type: "paragraph", content: [{ type: "text", text }] }],
-});
-
-const makeEditor = (text: string) =>
-  new Editor({
-    extensions: [Document, Paragraph, Text, CustomTypography],
-    content: singlePara(text),
-  });
-
-// Build a before/after EditorState pair by applying one plain transaction.
-const mutate = (text: string, apply: (tr: any, schema: any) => void) => {
-  const editor = new Editor({
-    extensions: [Document, Paragraph, Text],
-    content: singlePara(text),
-  });
-  const before = editor.state;
-  const tr = before.tr;
-  apply(tr, before.schema);
-  editor.view.dispatch(tr);
-  const after = editor.state;
-  return { before, after, editor };
-};
-
-describe("findChangedRange", () => {
-  it("returns null for identical docs", () => {
-    const editor = new Editor({
-      extensions: [Document, Paragraph, Text],
-      content: singlePara("hello"),
-    });
-    expect(findChangedRange(editor.state, editor.state)).toBeNull();
-    editor.destroy();
-  });
-
-  it("returns the minimal range for a normal middle insertion", () => {
-    // "hello world" (text at 1..12); insert "there " at pos 6.
-    const { before, after, editor } = mutate("hello world", (tr) =>
-      tr.insertText("there ", 6),
-    );
-    expect(findChangedRange(before, after)).toEqual({
-      from: 6,
-      oldTo: 6,
-      newTo: 12,
-    });
-    editor.destroy();
-  });
-
-  it("normalizes the INSERTION overlapping-bounds branch (repeated content)", () => {
-    // Insert one more 'a' into "aaaaa" at pos 3. findDiffStart lands at the end
-    // (6) while findDiffEnd reports an end BEFORE it ({a:1,b:2}); both ends must
-    // be pushed forward by the same delta -> a non-degenerate range.
-    const { before, after, editor } = mutate("aaaaa", (tr) =>
-      tr.insertText("a", 3),
-    );
-    const change = findChangedRange(before, after)!;
-    expect(change).toEqual({ from: 6, oldTo: 6, newTo: 7 });
-    // Invariant the guard logic relies on: never degenerate.
-    expect(change.from).toBeLessThanOrEqual(change.oldTo);
-    expect(change.from).toBeLessThanOrEqual(change.newTo);
-    editor.destroy();
-  });
-
-  it("normalizes the DELETION overlapping-bounds branch (F2 fix)", () => {
-    // Delete one repeated 'a' from the middle of "aaaaa" ([3,4)). Here
-    // findDiffEnd reports newTo < start, the symmetric case the old one-sided
-    // normalization missed -> it used to yield a degenerate range (newTo < from).
-    const { before, after, editor } = mutate("aaaaa", (tr) => tr.delete(3, 4));
-    const change = findChangedRange(before, after)!;
-    expect(change).toEqual({ from: 5, oldTo: 6, newTo: 5 });
-    // The whole point of F2: from <= newTo (and from <= oldTo) still holds.
-    expect(change.from).toBeLessThanOrEqual(change.newTo);
-    expect(change.from).toBeLessThanOrEqual(change.oldTo);
-    editor.destroy();
-  });
-
-  it("normalizes a multi-char repeated deletion (F2 fix)", () => {
-    const { before, after, editor } = mutate("aaaaa", (tr) => tr.delete(2, 4));
-    const change = findChangedRange(before, after)!;
-    expect(change).toEqual({ from: 4, oldTo: 6, newTo: 4 });
-    expect(change.from).toBeLessThanOrEqual(change.newTo);
-    editor.destroy();
-  });
-});
-
-describe("mapRangeThroughChange", () => {
-  const range = { from: 5, to: 10 };
-
-  it("RELEASES on a strict intersection (edit inside the guarded range)", () => {
-    // change straddles the interior of the guard.
-    expect(
-      mapRangeThroughChange(range, { from: 6, oldTo: 8, newTo: 7 }),
-    ).toBeNull();
-  });
-
-  it("does NOT release on a boundary touch at the guard END", () => {
-    // Edit begins exactly at range.to (10): from < to is false -> no intersect.
-    expect(
-      mapRangeThroughChange(range, { from: 10, oldTo: 10, newTo: 12 }),
-    ).toEqual(range);
-  });
-
-  it("does NOT release on a boundary touch at the guard START", () => {
-    // Edit ends exactly at range.from (5): oldTo > from is false -> no intersect;
-    // it is treated as a change fully before, shifting the guard.
-    expect(
-      mapRangeThroughChange(range, { from: 3, oldTo: 5, newTo: 8 }),
-    ).toEqual({ from: 8, to: 13 });
-  });
-
-  it("SHIFTS the guard for a change fully before it", () => {
-    // Insert 2 chars entirely before the range (oldTo 3 <= from 5): +2 delta.
-    expect(
-      mapRangeThroughChange(range, { from: 2, oldTo: 3, newTo: 5 }),
-    ).toEqual({ from: 7, to: 12 });
-  });
-
-  it("leaves the guard untouched for a change fully after it", () => {
-    expect(
-      mapRangeThroughChange(range, { from: 12, oldTo: 14, newTo: 16 }),
-    ).toBe(range);
-  });
-});
-
-describe("undo-guard arming (integration)", () => {
-  it("arms {from, to:newTo} on a LOCAL undo-replace (history meta)", () => {
-    // Undo of an em-dash substitution: "a—b" restored to "a--b" — the em-dash
-    // (pos 2..3) is REPLACED by "--", tagged with the history plugin's meta.
-    const editor = makeEditor("a—b");
-    const { state } = editor;
-    const tr = state.tr
-      .replaceWith(2, 3, state.schema.text("--"))
-      .setMeta("history$", { redo: false });
-    editor.view.dispatch(tr);
-
-    expect(editor.state.doc.textContent).toBe("a--b");
-    // from = diff start (2), to = newTo = end of the inserted "--" (4).
-    expect(undoGuardKey.getState(editor.state)).toEqual({ from: 2, to: 4 });
-    editor.destroy();
-  });
-
-  it("does NOT arm on a REMOTE change-origin replace (no undo meta)", () => {
-    // Same replace, but tagged only as a y-sync remote change: history/remote
-    // yes, undo/redo NO -> must not arm.
-    const editor = makeEditor("a—b");
-    const { state } = editor;
-    const tr = state.tr
-      .replaceWith(2, 3, state.schema.text("--"))
-      .setMeta(ySyncPluginKey, { isChangeOrigin: true });
-    editor.view.dispatch(tr);
-
-    expect(editor.state.doc.textContent).toBe("a--b");
-    expect(undoGuardKey.getState(editor.state)).toBeNull();
-    editor.destroy();
-  });
-
-  it("does NOT arm on an ordinary local edit", () => {
-    const editor = makeEditor("a—b");
-    editor.view.dispatch(
-      editor.state.tr.replaceWith(2, 3, editor.state.schema.text("--")),
-    );
-    expect(undoGuardKey.getState(editor.state)).toBeNull();
-    editor.destroy();
-  });
-});
-
-describe("undo-guard release / shift (integration)", () => {
-  it("RELEASES when a later edit lands inside the guarded region", () => {
-    const editor = makeEditor("a—b");
-    editor.view.dispatch(
-      editor.state.tr
-        .replaceWith(2, 3, editor.state.schema.text("--"))
-        .setMeta("history$", { redo: false }),
-    );
-    const guard = undoGuardKey.getState(editor.state)!;
-    expect(guard).toEqual({ from: 2, to: 4 });
-
-    // Type a character inside the restored region -> guard is dropped.
-    editor.view.dispatch(editor.state.tr.insertText("x", guard.from + 1));
-    expect(undoGuardKey.getState(editor.state)).toBeNull();
-    editor.destroy();
-  });
-
-  it("keeps and SHIFTS the guard when a later edit lands before it", () => {
-    const editor = makeEditor("zz a—b");
-    // "zz a—b": em-dash at pos 5; replace the 'a' at 4..5 with "--" to arm.
-    editor.view.dispatch(
-      editor.state.tr
-        .replaceWith(4, 5, editor.state.schema.text("--"))
-        .setMeta("history$", { redo: false }),
-    );
-    const guard = undoGuardKey.getState(editor.state)!;
-    expect(guard).toEqual({ from: 4, to: 6 });
-
-    // Insert one char at the very start (before the guard) -> guard shifts +1.
-    editor.view.dispatch(editor.state.tr.insertText("Q", 1));
-    expect(undoGuardKey.getState(editor.state)).toEqual({ from: 5, to: 7 });
-    editor.destroy();
-  });
-});

apps/client/src/features/editor/extensions/custom-typography.ts

@@ -1,193 +0,0 @@
-import { InputRule } from "@tiptap/core";
-import {
-  Plugin,
-  PluginKey,
-  type EditorState,
-  type Transaction,
-} from "@tiptap/pm/state";
-import { Typography } from "@tiptap/extension-typography";
-import { isChangeOrigin } from "@tiptap/extension-collaboration";
-import { ySyncPluginKey } from "@tiptap/y-tiptap";
-
-// Region restored by the latest undo — while it is intact, typography
-// input rules overlapping it must not fire again.
-interface UndoGuardRange {
-  from: number;
-  to: number;
-}
-
-// Exported for tests: the plugin key lets a test read the armed guard state,
-// and the two pure helpers below are unit-tested directly.
-export const undoGuardKey = new PluginKey<UndoGuardRange | null>(
-  "typographyUndoGuard",
-);
-
-// prosemirror-history does not export its plugin key, so template-editor
-// undo/redo is detected via the stable stringified key. Only one
-// PluginKey("history") exists in the dependency tree, so "history$" is stable.
-const HISTORY_META = "history$";
-
-const isUndoRedoTransaction = (tr: Transaction): boolean => {
-  if (tr.getMeta(HISTORY_META)) {
-    return true;
-  }
-  // Read yjs undo/redo meta via the real ySyncPluginKey object (imported, not
-  // a fragile stringified key), which y-tiptap sets on Y.UndoManager changes.
-  const ySyncMeta = tr.getMeta(ySyncPluginKey) as
-    | { isUndoRedoOperation?: boolean }
-    | undefined;
-  return !!ySyncMeta?.isUndoRedoOperation;
-};
-
-interface DocChange {
-  from: number;
-  oldTo: number;
-  newTo: number;
-}
-
-// Compute the minimal changed region between two docs. yjs undo/redo (and any
-// remote change) arrives as a whole-document replace step, so the transaction
-// step maps are useless — diff the docs to recover the real minimal change.
-// Returns null when the docs are identical.
-export const findChangedRange = (
-  oldState: EditorState,
-  newState: EditorState,
-): DocChange | null => {
-  const start = oldState.doc.content.findDiffStart(newState.doc.content);
-  const end = oldState.doc.content.findDiffEnd(newState.doc.content);
-  if (start == null || end == null) {
-    return null;
-  }
-  let { a: oldTo, b: newTo } = end;
-  // findDiffEnd can report an end BEFORE the diff start when the changed text
-  // abuts repeated content (insertion -> oldTo<start, deletion -> newTo<start).
-  // Push both ends forward by the same delta so the range stays non-degenerate
-  // (from <= oldTo and from <= newTo), matching ProseMirror's own diff bounds.
-  const minTo = Math.min(oldTo, newTo);
-  if (minTo < start) {
-    const delta = start - minTo;
-    oldTo += delta;
-    newTo += delta;
-  }
-  return { from: start, oldTo, newTo };
-};
-
-// Map an armed guard range across a single document change described by a diff.
-// Returns null when the change touches the guarded text itself (the restored
-// substitution was edited, so the guard must be released).
-export const mapRangeThroughChange = (
-  range: UndoGuardRange,
-  change: DocChange,
-): UndoGuardRange | null => {
-  // Strict intersection: an edit exactly at a guard boundary (e.g. the user
-  // typing the suppressed space right after the restored text, or deleting it)
-  // must NOT drop the guard.
-  if (change.from < range.to && change.oldTo > range.from) {
-    return null;
-  }
-  // Change fully before the guard: shift the guard by the length delta.
-  if (change.oldTo <= range.from) {
-    const delta = change.newTo - change.oldTo;
-    return { from: range.from + delta, to: range.to + delta };
-  }
-  // Change fully after the guard: positions are unaffected.
-  return range;
-};
-
-// Detect history/remote transactions that may arrive as a whole-document
-// replace step: prosemirror-history undo/redo, or any yjs remote-origin change
-// (isChangeOrigin is the canonical predicate already used across the app).
-const isHistoryOrRemoteTransaction = (tr: Transaction): boolean =>
-  !!tr.getMeta(HISTORY_META) || isChangeOrigin(tr);
-
-export const CustomTypography = Typography.extend({
-  addProseMirrorPlugins() {
-    return [
-      ...(this.parent?.() ?? []),
-      new Plugin({
-        key: undoGuardKey,
-        state: {
-          init: () => null,
-          apply(tr, prev, oldState, newState): UndoGuardRange | null {
-            if (tr.docChanged && isHistoryOrRemoteTransaction(tr)) {
-              const change = findChangedRange(oldState, newState);
-              if (change == null) {
-                // Attribute-only or otherwise content-neutral change: keep the
-                // guard.
-                return prev;
-              }
-              // Arm the guard only when the LOCAL user's undo/redo REPLACED text
-              // (deleted + inserted) — the signature of reverting an input-rule
-              // substitution. Pure insertions/deletions and remote peer edits
-              // must not arm it.
-              if (
-                isUndoRedoTransaction(tr) &&
-                change.oldTo > change.from &&
-                change.newTo > change.from
-              ) {
-                return { from: change.from, to: change.newTo };
-              }
-              // Non-arming history/remote change: map the existing guard through
-              // the real diff instead of the (whole-document) step map.
-              if (!prev) {
-                return null;
-              }
-              return mapRangeThroughChange(prev, change);
-            }
-            if (!prev) {
-              return null;
-            }
-            if (!tr.docChanged) {
-              return prev;
-            }
-            // Ordinary local edit: minimal step maps are accurate and cheap.
-            let range: UndoGuardRange | null = prev;
-            for (const stepMap of tr.mapping.maps) {
-              const { from: rangeFrom, to: rangeTo } = range;
-              let touched = false;
-              stepMap.forEach((fromA, toA) => {
-                if (fromA < rangeTo && toA > rangeFrom) {
-                  touched = true;
-                }
-              });
-              if (touched) {
-                range = null;
-                break;
-              }
-              range = {
-                from: stepMap.map(rangeFrom, 1),
-                to: stepMap.map(rangeTo, -1),
-              };
-            }
-            return range && range.to > range.from ? range : null;
-          },
-        },
-      }),
-    ];
-  },
-
-  addInputRules() {
-    // Wrap every typography rule: skip it when its match overlaps the text
-    // just restored by undo, so an undone substitution is not re-applied.
-    return (this.parent?.() ?? []).map(
-      (rule) =>
-        new InputRule({
-          find: rule.find,
-          undoable: rule.undoable,
-          handler: (props) => {
-            const guard = undoGuardKey.getState(props.state);
-            if (
-              guard &&
-              props.range.from < guard.to &&
-              props.range.to > guard.from
-            ) {
-              // Returning null skips this rule and lets the typed character
-              // be inserted as plain text.
-              return null;
-            }
-            return rule.handler(props);
-          },
-        }),
-    );
-  },
-});

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

@@ -6,7 +6,7 @@ import { TaskList, TaskItem } from "@tiptap/extension-list";
 import { Placeholder, CharacterCount, UndoRedo } from "@tiptap/extensions";
 import { Superscript } from "@tiptap/extension-superscript";
 import SubScript from "@tiptap/extension-subscript";
-import { CustomTypography } from "./custom-typography";
+import { Typography } from "@tiptap/extension-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
 import { Youtube } from "@tiptap/extension-youtube";
@@ -53,7 +53,6 @@ import {
   Subpages,
   Heading,
   Highlight,
-  Spoiler,
   Indent,
   UniqueID,
   SharedStorage,
@@ -117,7 +116,6 @@ import mentionRenderItems from "@/features/editor/components/mention/mention-sug
 import { ReactNodeViewRenderer, ReactMarkViewRenderer } from "@tiptap/react";
 import MentionView from "@/features/editor/components/mention/mention-view.tsx";
 import LinkView from "@/features/editor/components/link/link-view.tsx";
-import SpoilerView from "@/features/editor/components/spoiler/spoiler-view.tsx";
 import i18n from "@/i18n.ts";
 import { MarkdownClipboard } from "@/features/editor/extensions/markdown-clipboard.ts";
 import EmojiCommand from "./emoji-command";
@@ -125,7 +123,6 @@ import { countWords } from "alfaaz";
 import AutoJoiner from "@/features/editor/extensions/autojoiner.ts";
 import GlobalDragHandle from "@/features/editor/extensions/drag-handle.ts";
 import { CleanStyles } from "@/features/editor/extensions/clean-styles.ts";
-import { IntentionalClear } from "@/features/editor/extensions/intentional-clear.ts";
 
 const lowlight = createLowlight(common);
 lowlight.register("mermaid", plaintext);
@@ -240,14 +237,7 @@ export const mainExtensions = [
   Highlight.configure({
     multicolor: true,
   }),
-  Spoiler.configure({}).extend({
-    addMarkView() {
-      return ReactMarkViewRenderer(SpoilerView);
-    },
-  }),
-  // Typography with an undo guard: does not re-apply a substitution the user
-  // just undid (e.g. Ctrl+Z on "1/2" -> "½" followed by another space).
-  CustomTypography,
+  Typography,
   TrailingNode,
   GlobalDragHandle.configure({
     customNodes: ["transclusionSource", "transclusionReference", "pageEmbed"],
@@ -496,10 +486,4 @@ export const collabExtensions: CollabExtensions = (provider, user) => [
       color: randomElement(userColors),
     },
   }),
-  // #251 — emit an intentional-clear signal to the server when the user
-  // deliberately empties the page, so the #248 store-side empty-guard lets that
-  // one clear through while still blocking accidental empties.
-  IntentionalClear.configure({
-    provider,
-  }),
 ];

apps/client/src/features/editor/extensions/intentional-clear.test.ts

@@ -1,120 +0,0 @@
-import { describe, it, expect, vi, beforeEach } 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 { ySyncPluginKey } from "@tiptap/y-tiptap";
-import {
-  IntentionalClear,
-  INTENTIONAL_CLEAR_MESSAGE_TYPE,
-} from "./intentional-clear";
-
-/**
- * #251 — the intentional-clear signal is driven through the REAL editor path:
- * a fresh Editor with the IntentionalClear extension, a fake provider that
- * records sendStateless, and the actual select-all + delete command the user's
- * keystroke runs. No hand-poke of any flag.
- */
-describe("IntentionalClear extension", () => {
-  let sendStateless: ReturnType<typeof vi.fn>;
-
-  const makeEditor = (content: unknown) =>
-    new Editor({
-      extensions: [
-        Document,
-        Paragraph,
-        Text,
-        IntentionalClear.configure({
-          // Minimal provider stand-in: only sendStateless is exercised.
-          provider: { sendStateless } as any,
-        }),
-      ],
-      content: content as any,
-    });
-
-  beforeEach(() => {
-    sendStateless = vi.fn();
-  });
-
-  it("emits the clear signal when a user empties a non-empty doc (select-all + delete)", () => {
-    const editor = makeEditor({
-      type: "doc",
-      content: [
-        { type: "paragraph", content: [{ type: "text", text: "hello world" }] },
-      ],
-    });
-
-    // The exact command path a select-all + Delete keystroke dispatches.
-    editor.chain().selectAll().deleteSelection().run();
-
-    expect(sendStateless).toHaveBeenCalledTimes(1);
-    const payload = JSON.parse(sendStateless.mock.calls[0][0]);
-    expect(payload).toEqual({ type: INTENTIONAL_CLEAR_MESSAGE_TYPE });
-
-    editor.destroy();
-  });
-
-  it("does NOT emit when typing into an empty doc (no non-empty → empty transition)", () => {
-    const editor = makeEditor({ type: "doc", content: [{ type: "paragraph" }] });
-
-    editor.chain().insertContent("typed text").run();
-
-    expect(sendStateless).not.toHaveBeenCalled();
-    editor.destroy();
-  });
-
-  it("does NOT emit on an edit that leaves the doc non-empty", () => {
-    const editor = makeEditor({
-      type: "doc",
-      content: [
-        { type: "paragraph", content: [{ type: "text", text: "keep me" }] },
-      ],
-    });
-
-    editor.chain().insertContent(" more").run();
-
-    expect(sendStateless).not.toHaveBeenCalled();
-    editor.destroy();
-  });
-
-  it("does NOT emit when a REMOTE/merge (change-origin) transaction empties the doc", () => {
-    // This pins the CENTRAL #248 protection: only a LOCAL user edit may emit the
-    // intentional-clear signal. An emptiness arriving from another client, a bad
-    // merge, or an emptied transclusion is applied as a y-sync transaction tagged
-    // with the ySyncPluginKey meta, which `isChangeOrigin` detects. The extension
-    // must early-return on it and NOT punch the empty write through the server
-    // guard.
-    const editor = makeEditor({
-      type: "doc",
-      content: [
-        { type: "paragraph", content: [{ type: "text", text: "remote content" }] },
-      ],
-    });
-
-    // Build a transaction that empties the non-empty doc and tag it exactly the
-    // way y-tiptap tags a remote y-sync update: `tr.setMeta(ySyncPluginKey,
-    // { isChangeOrigin: true })` (see @tiptap/y-tiptap sync-plugin). This makes
-    // the real `isChangeOrigin(tr)` predicate return true — not a stand-in.
-    const { state } = editor;
-    const tr = state.tr
-      .delete(0, state.doc.content.size)
-      .setMeta(ySyncPluginKey, { isChangeOrigin: true });
-    editor.view.dispatch(tr);
-
-    // The transaction really emptied the doc (became the single empty paragraph)…
-    expect(editor.state.doc.textContent).toBe("");
-    // …yet because it is change-origin, no signal is emitted.
-    expect(sendStateless).not.toHaveBeenCalled();
-    editor.destroy();
-  });
-
-  it("does NOT emit when the doc was already empty", () => {
-    const editor = makeEditor({ type: "doc", content: [{ type: "paragraph" }] });
-
-    // Selecting all + delete on an already-empty doc is a no-op transition.
-    editor.chain().selectAll().deleteSelection().run();
-
-    expect(sendStateless).not.toHaveBeenCalled();
-    editor.destroy();
-  });
-});

apps/client/src/features/editor/extensions/intentional-clear.ts

@@ -1,94 +0,0 @@
-import { Extension } from "@tiptap/core";
-import { isChangeOrigin } from "@tiptap/extension-collaboration";
-import type { Node as PMNode } from "@tiptap/pm/model";
-import type { HocuspocusProvider } from "@hocuspocus/provider";
-
-/**
- * Stateless message type sent to the server when a user deliberately clears a
- * page to empty. Kept in one place so the client emitter and the server
- * consumer (PersistenceExtension.onStateless) agree on the wire format.
- */
-export const INTENTIONAL_CLEAR_MESSAGE_TYPE = "intentional-clear";
-
-export interface IntentionalClearOptions {
-  /** The collab provider used to send the stateless clear signal. */
-  provider: HocuspocusProvider | null;
-}
-
-/**
- * A "document is empty" check that mirrors the server's `isEmptyParagraphDoc`
- * (collaboration.util.ts): exactly one top-level paragraph with no inline
- * content. After a select-all + delete TipTap leaves precisely this shape, so
- * matching it here keeps the client signal aligned with the server guard that
- * consumes it.
- */
-function isEmptyParagraphDoc(doc: PMNode): boolean {
-  if (doc.childCount !== 1) return false;
-  const child = doc.firstChild;
-  return (
-    child !== null &&
-    child !== undefined &&
-    child.type.name === "paragraph" &&
-    child.content.size === 0
-  );
-}
-
-/**
- * #251 — intentional-clear signal.
- *
- * The server's #248 store-side empty-guard unconditionally refuses to overwrite
- * non-empty persisted content with an empty document, because a momentarily
- * empty live Y.Doc (a glitch, a bad merge, an emptying transclusion) is
- * indistinguishable from a real clear *at the store layer*. That protection is
- * correct, but it also blocks a user who genuinely wants to empty the page.
- *
- * This extension supplies the missing distinction. It watches LOCAL, user-driven
- * transactions and, the moment one reduces a non-empty document to the empty
- * single-paragraph shape, it sends a hocuspocus stateless message to the server.
- * The server records a short-lived, single-use "intentional clear pending" flag
- * for this document that the next (debounced) onStoreDocument consumes to let
- * that one empty write through the guard.
- *
- * What counts as an intentional clear (precise definition):
- *  - the transaction actually changed the document (`docChanged`), AND
- *  - it is a LOCAL user edit, not a remote collab application — remote y-sync
- *    transactions are tagged and filtered out via `isChangeOrigin`, so an
- *    emptiness that arrives from another client / a merge never emits a signal,
- *    AND
- *  - the document was non-empty before the transaction and is the empty
- *    single-paragraph doc after it.
- *
- * This is exactly the select-all + Delete / Backspace (or any local command that
- * empties the doc, e.g. clearContent) keystroke path. A transient/programmatic
- * empty serialization that the server might see on the wire does NOT come with
- * this signal, so the guard still blocks it.
- */
-export const IntentionalClear = Extension.create<IntentionalClearOptions>({
-  name: "intentionalClear",
-
-  addOptions() {
-    return {
-      provider: null,
-    };
-  },
-
-  onTransaction({ transaction }) {
-    if (!transaction.docChanged) return;
-    // Only react to local user edits. Remote collaboration steps (and other
-    // y-sync-applied changes) carry the change origin and must never be treated
-    // as an intentional clear, otherwise a remote/merge-induced emptiness would
-    // punch through the server guard.
-    if (isChangeOrigin(transaction)) return;
-
-    const becameEmpty =
-      !isEmptyParagraphDoc(transaction.before) &&
-      isEmptyParagraphDoc(transaction.doc);
-    if (!becameEmpty) return;
-
-    // The server reads the originating document from the connection, so the
-    // payload only needs to declare intent — it cannot target another document.
-    this.options.provider?.sendStateless(
-      JSON.stringify({ type: INTENTIONAL_CLEAR_MESSAGE_TYPE }),
-    );
-  },
-});

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

@@ -1,9 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { htmlToMarkdown } from "@docmost/editor-ext";
-import {
-  normalizeTableColumnWidths,
-  classifyClipboardSelection,
-} from "./markdown-clipboard";
+import { normalizeTableColumnWidths } from "./markdown-clipboard";
 
 // normalizeTableColumnWidths mutates a DOM subtree (jsdom provides document).
 function root(html: string): HTMLElement {
@@ -128,171 +124,3 @@ describe("normalizeTableColumnWidths", () => {
     ).toEqual([null, null]);
   });
 });
-
-describe("classifyClipboardSelection", () => {
-  it("serializes a list of 2+ items as markdown", () => {
-    expect(
-      classifyClipboardSelection([{ name: "bulletList", childCount: 2 }]),
-    ).toEqual({ asMarkdown: true, wrapBareRows: false });
-  });
-
-  it("leaves a single-item list as plain text", () => {
-    expect(
-      classifyClipboardSelection([{ name: "bulletList", childCount: 1 }]),
-    ).toEqual({ asMarkdown: false, wrapBareRows: false });
-  });
-
-  it("serializes a whole table without wrapping bare rows", () => {
-    expect(
-      classifyClipboardSelection([{ name: "table", childCount: 3 }]),
-    ).toEqual({ asMarkdown: true, wrapBareRows: false });
-  });
-
-  it("serializes a partial cell selection (bare rows) and flags wrapping", () => {
-    expect(
-      classifyClipboardSelection([
-        { name: "tableRow", childCount: 2 },
-        { name: "tableRow", childCount: 2 },
-      ]),
-    ).toEqual({ asMarkdown: true, wrapBareRows: true });
-  });
-
-  it("leaves plain paragraphs as plain text", () => {
-    expect(
-      classifyClipboardSelection([{ name: "paragraph", childCount: 1 }]),
-    ).toEqual({ asMarkdown: false, wrapBareRows: false });
-  });
-
-  it("does not wrap when rows are mixed with other block types", () => {
-    expect(
-      classifyClipboardSelection([
-        { name: "tableRow", childCount: 2 },
-        { name: "paragraph", childCount: 1 },
-      ]),
-    ).toEqual({ asMarkdown: false, wrapBareRows: false });
-  });
-});
-
-// Output-level tests for the table clipboard regression: copying a table must
-// yield a real GFM pipe table, NOT one-value-per-line concatenated cells.
-// These exercise the actual markdown produced by htmlToMarkdown (the same
-// serializer step the clipboardTextSerializer runs), so they pin the OUTPUT
-// shape that the classifier-flag tests above do not cover.
-describe("table clipboard markdown output (htmlToMarkdown)", () => {
-  // Trim each line and drop blanks so structural assertions are whitespace-robust.
-  function lines(md: string): string[] {
-    return md
-      .split("\n")
-      .map((l) => l.trim())
-      .filter((l) => l.length > 0);
-  }
-
-  // A GFM separator row like "| --- | --- |" (any number of columns), tolerant
-  // of the padding turndown emits.
-  function isSeparatorRow(line: string): boolean {
-    const compact = line.replace(/\s+/g, "");
-    return /^\|(?:-{3,}\|)+$/.test(compact);
-  }
-
-  // Split a pipe-delimited row into trimmed cell values.
-  function cells(line: string): string[] {
-    return line
-      .replace(/^\|/, "")
-      .replace(/\|$/, "")
-      .split("|")
-      .map((c) => c.trim());
-  }
-
-  it("serializes a header-less partial cell selection (bare rows) as a valid GFM pipe table", () => {
-    // Mirror the serializer's `wrapBareRows` branch exactly: bare <tr> nodes are
-    // wrapped in <table><tbody> and htmlToMarkdown(div.innerHTML) is called.
-    // See markdown-clipboard.ts clipboardTextSerializer:
-    //   const table = document.createElement("table");
-    //   const tbody = document.createElement("tbody");
-    //   tbody.appendChild(fragment); table.appendChild(tbody);
-    //   div.appendChild(table);
-    //   return htmlToMarkdown(div.innerHTML);
-    const div = document.createElement("div");
-    const table = document.createElement("table");
-    const tbody = document.createElement("tbody");
-    for (const [c1, c2] of [
-      ["a", "b"],
-      ["c", "d"],
-    ]) {
-      const tr = document.createElement("tr");
-      const td1 = document.createElement("td");
-      td1.textContent = c1;
-      const td2 = document.createElement("td");
-      td2.textContent = c2;
-      tr.appendChild(td1);
-      tr.appendChild(td2);
-      tbody.appendChild(tr);
-    }
-    table.appendChild(tbody);
-    div.appendChild(table);
-
-    const md = htmlToMarkdown(div.innerHTML);
-    const ls = lines(md);
-
-    // Valid GFM: a header/data separator row is present (an empty header is
-    // synthesized by the GFM turndown plugin for a header-less table — fine).
-    expect(ls.some(isSeparatorRow)).toBe(true);
-    // NOT the old broken "one value per line" shape: every line is pipe-delimited
-    // and no line is a bare cell value on its own.
-    expect(ls.every((l) => l.includes("|"))).toBe(true);
-    expect(md).not.toMatch(/^\s*(a|b|c|d)\s*$/m);
-    // The cell values land in real pipe-delimited data rows.
-    const dataRows = ls.filter((l) => !isSeparatorRow(l)).map(cells);
-    expect(dataRows).toContainEqual(["a", "b"]);
-    expect(dataRows).toContainEqual(["c", "d"]);
-  });
-
-  it("serializes a whole table with a header row as a proper GFM table (headline regression)", () => {
-    // Mirror the serializer's non-wrap branch: the full <table> node is appended
-    // directly (div.appendChild(fragment)) and htmlToMarkdown(div.innerHTML) runs.
-    const div = document.createElement("div");
-    const table = document.createElement("table");
-
-    const thead = document.createElement("thead");
-    const headerRow = document.createElement("tr");
-    for (const h of ["Name", "Age"]) {
-      const th = document.createElement("th");
-      th.textContent = h;
-      headerRow.appendChild(th);
-    }
-    thead.appendChild(headerRow);
-    table.appendChild(thead);
-
-    const tbody = document.createElement("tbody");
-    for (const [name, age] of [
-      ["Alice", "30"],
-      ["Bob", "25"],
-    ]) {
-      const tr = document.createElement("tr");
-      const td1 = document.createElement("td");
-      td1.textContent = name;
-      const td2 = document.createElement("td");
-      td2.textContent = age;
-      tr.appendChild(td1);
-      tr.appendChild(td2);
-      tbody.appendChild(tr);
-    }
-    table.appendChild(tbody);
-    div.appendChild(table);
-
-    const md = htmlToMarkdown(div.innerHTML);
-    const ls = lines(md);
-
-    // Proper GFM structure: separator row + all rows pipe-delimited.
-    expect(ls.some(isSeparatorRow)).toBe(true);
-    expect(ls.every((l) => l.includes("|"))).toBe(true);
-
-    const rows = ls.filter((l) => !isSeparatorRow(l)).map(cells);
-    // Header row comes first, followed by both data rows.
-    expect(rows[0]).toEqual(["Name", "Age"]);
-    expect(rows).toContainEqual(["Alice", "30"]);
-    expect(rows).toContainEqual(["Bob", "25"]);
-    // Headline regression: the table is NOT concatenated one-value-per-line.
-    expect(md).not.toMatch(/^\s*(Name|Age|Alice|Bob|30|25)\s*$/m);
-  });
-});

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

@@ -27,36 +27,24 @@ export const MarkdownClipboard = Extension.create({
         key: new PluginKey("markdownClipboard"),
         props: {
           clipboardTextSerializer: (slice) => {
-            const topLevelNodes: { name: string; childCount: number }[] = [];
+            const listTypes = ["bulletList", "orderedList", "taskList"];
+            let topLevelCount = 0;
+            let hasList = false;
             slice.content.forEach((node) => {
-              topLevelNodes.push({
-                name: node.type.name,
-                childCount: node.childCount,
-              });
+              if (listTypes.includes(node.type.name)) {
+                hasList = true;
+                topLevelCount += node.childCount;
+              } else {
+                topLevelCount++;
+              }
             });
 
-            const { asMarkdown, wrapBareRows } =
-              classifyClipboardSelection(topLevelNodes);
-            if (!asMarkdown) return null;
+            if (!hasList || topLevelCount < 2) return null;
 
             const div = document.createElement("div");
             const serializer = DOMSerializer.fromSchema(this.editor.schema);
             const fragment = serializer.serializeFragment(slice.content);
-
-            if (wrapBareRows) {
-              // A partial table cell-selection serializes to bare <tr> nodes
-              // (prosemirror-tables returns the whole `table` node only when the
-              // entire table is selected). Bare <tr> would be foster-parented
-              // away by the HTML parser inside htmlToMarkdown, so wrap them in
-              // <table><tbody> first for the GFM turndown rule to detect them.
-              const table = document.createElement("table");
-              const tbody = document.createElement("tbody");
-              tbody.appendChild(fragment);
-              table.appendChild(tbody);
-              div.appendChild(table);
-            } else {
-              div.appendChild(fragment);
-            }
+            div.appendChild(fragment);
             return htmlToMarkdown(div.innerHTML);
           },
           handlePaste: (view, event, slice) => {
@@ -165,55 +153,6 @@ export const MarkdownClipboard = Extension.create({
   },
 });
 
-/**
- * Decide whether a copied slice's plain-text clipboard payload should be
- * serialized as Markdown (instead of ProseMirror's default text serializer,
- * which joins block leaves with newlines — the "one value per line" bug for
- * tables).
- *
- * Serialize as Markdown for structured content:
- *  - lists with 2+ total items (a single copied bullet stays literal text);
- *  - a whole table (top-level `table` node);
- *  - a partial table cell-selection, which prosemirror-tables copies as bare
- *    `tableRow` nodes (only a full-table selection yields a `table` node).
- *
- * `wrapBareRows` flags the bare-rows case so the caller wraps the serialized
- * <tr> nodes in <table><tbody> before the HTML->Markdown step. Plain paragraphs
- * return asMarkdown=false so a simple text copy stays literal, and internal
- * copy/paste keeps using the richer text/html clipboard payload.
- */
-export function classifyClipboardSelection(
-  nodes: { name: string; childCount: number }[],
-): { asMarkdown: boolean; wrapBareRows: boolean } {
-  const listTypes = ["bulletList", "orderedList", "taskList"];
-  let topLevelCount = 0;
-  let hasList = false;
-  let hasTable = false;
-  let tableRowCount = 0;
-  let nonRowCount = 0;
-
-  for (const node of nodes) {
-    if (listTypes.includes(node.name)) {
-      hasList = true;
-      topLevelCount += node.childCount;
-      nonRowCount++;
-    } else {
-      if (node.name === "table") hasTable = true;
-      if (node.name === "tableRow") tableRowCount++;
-      else nonRowCount++;
-      topLevelCount++;
-    }
-  }
-
-  // Bare tableRow nodes at the top level only occur for a partial cell
-  // selection; a slice never mixes bare rows with other block types, so
-  // "every top-level node is a row" is a safe signal to wrap-and-serialize.
-  const wrapBareRows = tableRowCount > 0 && nonRowCount === 0;
-  const asMarkdown =
-    (hasList && topLevelCount >= 2) || hasTable || wrapBareRows;
-  return { asMarkdown, wrapBareRows };
-}
-
 /**
  * Reorder/dedup the footnotes of a SELF-CONTAINED pasted markdown block to the
  * canonical invariant (the live footnoteSyncPlugin never reorders an existing

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,189 @@
+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";
+import { pageYdocName } from "@/features/editor/page-ydoc-name";
+import { pageKeys } from "@/features/page/queries/page-query";
+
+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 = pageYdocName(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>(
+            pageKeys.detail(slugId),
+          );
+          if (pageData) {
+            queryClient.setQueryData(pageKeys.detail(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/hooks/use-scroll-position.test.ts

@@ -1,394 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
-import { useScrollPosition, hasSavedReadingPosition } from "./use-scroll-position";
-
-const KEY_PREFIX = "gitmost:scroll-position:";
-
-function setScrollY(value: number): void {
-  Object.defineProperty(window, "scrollY", {
-    configurable: true,
-    value,
-  });
-}
-
-function setScrollHeight(value: number): void {
-  Object.defineProperty(document.documentElement, "scrollHeight", {
-    configurable: true,
-    value,
-  });
-}
-
-function setInnerHeight(value: number): void {
-  Object.defineProperty(window, "innerHeight", {
-    configurable: true,
-    value,
-  });
-}
-
-describe("useScrollPosition", () => {
-  beforeEach(() => {
-    window.sessionStorage.clear();
-    setScrollY(0);
-    setScrollHeight(0);
-    setInnerHeight(800);
-    // jsdom does not implement window.scrollTo; stub it.
-    window.scrollTo = vi.fn();
-    // Ensure no anchor leaks between tests.
-    window.location.hash = "";
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-    vi.useRealTimers();
-    window.location.hash = "";
-  });
-
-  it("(a) saves window.scrollY to sessionStorage under the pageId key, throttled", () => {
-    vi.useFakeTimers();
-    const { unmount } = renderHook(() => useScrollPosition("p1"));
-
-    // Leading-edge save fires immediately.
-    setScrollY(123);
-    act(() => {
-      window.dispatchEvent(new Event("scroll"));
-    });
-    expect(window.sessionStorage.getItem(`${KEY_PREFIX}p1`)).toBe("123");
-
-    // Within the throttle window the next scroll is suppressed.
-    setScrollY(456);
-    act(() => {
-      window.dispatchEvent(new Event("scroll"));
-    });
-    expect(window.sessionStorage.getItem(`${KEY_PREFIX}p1`)).toBe("123");
-
-    // After the throttle window elapses, the next scroll persists again.
-    act(() => {
-      vi.advanceTimersByTime(250);
-    });
-    setScrollY(789);
-    act(() => {
-      window.dispatchEvent(new Event("scroll"));
-    });
-    expect(window.sessionStorage.getItem(`${KEY_PREFIX}p1`)).toBe("789");
-
-    unmount();
-  });
-
-  it("(a2) the restore target is captured at mount and survives a fresh scroll@0 clobber", () => {
-    vi.useFakeTimers();
-    // A previous session saved 500.
-    window.sessionStorage.setItem(`${KEY_PREFIX}clob`, "500");
-
-    const { result } = renderHook(() => useScrollPosition("clob"));
-
-    // On load the page is at the top; a scroll@0 fires and overwrites storage
-    // with 0. This is exactly the clobber the synchronous mount-capture defends
-    // against: the stored value becomes "0", but the target was already captured.
-    setScrollY(0);
-    act(() => {
-      window.dispatchEvent(new Event("scroll"));
-    });
-    expect(window.sessionStorage.getItem(`${KEY_PREFIX}clob`)).toBe("0");
-
-    // Restore still scrolls to 500 (the captured target), NOT the clobbered 0.
-    // If the capture were moved into an effect (after handlers register), it
-    // would read the clobbered 0 and this assertion would fail.
-    setScrollHeight(2000); // maxScroll = 1200 >= 500
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
-  });
-
-  it("(a3) is idempotent: re-asserting the same target does not scroll again", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}once`, "500");
-    setScrollHeight(2000); // tall enough to restore synchronously
-
-    const { result } = renderHook(() => useScrollPosition("once"));
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).toHaveBeenCalledTimes(1);
-
-    // Simulate the browser now being at the restored position.
-    setScrollY(500);
-
-    // A second call (e.g. the wiring effect re-running on [showStatic, editor,
-    // restoreScrollPosition]) must NOT scroll again: the redundancy guard sees
-    // the window is already at the target and does nothing.
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).toHaveBeenCalledTimes(1);
-  });
-
-  it("(b) does not restore when the URL has a #hash anchor", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}p2`, "500");
-    // Content is ALREADY tall enough (maxScroll = 2000 - 800 = 1200 >= 500), so
-    // without the hash guard tryRestore would call scrollTo synchronously on the
-    // first tick. The assertion below therefore genuinely proves the hash guard
-    // short-circuits before any scroll (not just that the poll has not fired).
-    setScrollHeight(2000);
-    window.location.hash = "#some-heading";
-
-    const { result } = renderHook(() => useScrollPosition("p2"));
-    act(() => {
-      result.current.restoreScrollPosition();
-      vi.advanceTimersByTime(5000);
-    });
-
-    expect(window.scrollTo).not.toHaveBeenCalled();
-  });
-
-  it("(f) cancels the in-flight restore poll on unmount (no scroll on the next page)", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}p7`, "500");
-    setInnerHeight(800);
-    setScrollHeight(100); // maxScroll = -700: target not reachable yet, so it polls.
-
-    const { result, unmount } = renderHook(() => useScrollPosition("p7"));
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled(); // still polling
-
-    // Navigate away (the hook unmounts) BEFORE the content grows tall enough.
-    unmount();
-
-    // Content of the NEXT page becomes tall; advancing time must NOT resurrect
-    // the cancelled poll (without the cleanup it would scroll the new page).
-    setScrollHeight(2000);
-    act(() => {
-      vi.advanceTimersByTime(5000);
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-  });
-
-  it("(g) does not restore if the reader scrolled (wheel) before restore fires", () => {
-    window.sessionStorage.setItem(`${KEY_PREFIX}g1`, "500");
-    setScrollHeight(2000); // tall enough to restore synchronously
-
-    const { result } = renderHook(() => useScrollPosition("g1"));
-
-    // The reader shows scroll intent before restore is triggered.
-    act(() => {
-      window.dispatchEvent(new Event("wheel"));
-    });
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    expect(window.scrollTo).not.toHaveBeenCalled();
-  });
-
-  it("(h) aborts an in-flight restore poll when the reader scrolls", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}h1`, "500");
-    setInnerHeight(800);
-    setScrollHeight(100); // maxScroll = -700: target not reachable yet, so it polls.
-
-    const { result } = renderHook(() => useScrollPosition("h1"));
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled(); // still polling
-
-    // The reader takes over mid-poll: this cancels the in-flight poll.
-    act(() => {
-      window.dispatchEvent(new Event("wheel"));
-    });
-
-    // Content of the page grows tall enough and time passes: the cancelled poll
-    // must NOT resurrect and yank the reader.
-    setScrollHeight(2000);
-    act(() => {
-      vi.advanceTimersByTime(5000);
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-  });
-
-  it("(i) a non-scroll keydown does NOT abort restore", () => {
-    window.sessionStorage.setItem(`${KEY_PREFIX}i1`, "500");
-    setScrollHeight(2000); // tall enough to restore synchronously
-
-    const { result } = renderHook(() => useScrollPosition("i1"));
-
-    // A non-scroll key (e.g. typing, a shortcut) must NOT count as scroll intent.
-    act(() => {
-      window.dispatchEvent(new KeyboardEvent("keydown", { key: "a" }));
-    });
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    // Restore still happens: the innocuous keypress did not disable it.
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
-  });
-
-  it("(j) a scroll keydown (Space) DOES abort restore", () => {
-    window.sessionStorage.setItem(`${KEY_PREFIX}j1`, "500");
-    setScrollHeight(2000); // tall enough to restore synchronously
-
-    const { result } = renderHook(() => useScrollPosition("j1"));
-
-    // Space scrolls the page: this is real scroll intent and must abort restore.
-    act(() => {
-      window.dispatchEvent(new KeyboardEvent("keydown", { key: " " }));
-    });
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    expect(window.scrollTo).not.toHaveBeenCalled();
-  });
-
-  it("(c) does nothing when nothing is saved or the saved value is <= 0", () => {
-    // Nothing saved.
-    const a = renderHook(() => useScrollPosition("nope"));
-    act(() => {
-      a.result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-
-    // Saved value <= 0.
-    window.sessionStorage.setItem(`${KEY_PREFIX}zero`, "0");
-    const b = renderHook(() => useScrollPosition("zero"));
-    act(() => {
-      b.result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-  });
-
-  it("(d) scrolls to the saved Y once the content is tall enough", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}p4`, "500");
-    setInnerHeight(800);
-    setScrollHeight(100); // maxScroll = -700, target not yet reachable.
-
-    const { result } = renderHook(() => useScrollPosition("p4"));
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    // Still polling: content not laid out yet.
-    expect(window.scrollTo).not.toHaveBeenCalled();
-
-    // Content becomes tall enough: maxScroll = 2000 - 800 = 1200 >= 500.
-    setScrollHeight(2000);
-    act(() => {
-      vi.advanceTimersByTime(100);
-    });
-
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
-  });
-
-  it("(d2) clamps to the max reachable position after the timeout", () => {
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}p5`, "5000");
-    setInnerHeight(800);
-    setScrollHeight(1000); // maxScroll stays 200, never reaches 5000.
-
-    const { result } = renderHook(() => useScrollPosition("p5"));
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    // Advance past the 5s timeout; restore should fire clamped to maxScroll.
-    act(() => {
-      vi.advanceTimersByTime(5000);
-    });
-
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 200, behavior: "auto" });
-  });
-
-  it("(k) shares ONE timeout budget across re-triggers (does not restart the clock)", () => {
-    // The static->live editor swap re-invokes restore. The shared budget
-    // (restoreStartRef) must measure the MAX_RESTORE_WAIT_MS (5000) deadline
-    // from the FIRST trigger, not restart it on every re-trigger. This pins
-    // the `if (restoreStartRef.current === null)` guard: a mutant that resets
-    // `restoreStartRef.current = Date.now()` on every trigger would push the
-    // deadline out to t=8000 (3000 + 5000) and fail the t=5000 assertion below.
-    vi.useFakeTimers();
-    vi.setSystemTime(0);
-    window.sessionStorage.setItem(`${KEY_PREFIX}k1`, "5000");
-    setInnerHeight(800);
-    setScrollHeight(1000); // maxScroll = 200, never reaches 5000 -> it polls.
-
-    const { result } = renderHook(() => useScrollPosition("k1"));
-
-    // First trigger at t=0: starts the shared budget and begins polling.
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-
-    // Advance to t=3000 (still polling: content short, not yet timed out).
-    act(() => {
-      vi.advanceTimersByTime(3000);
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-
-    // Second trigger at t=3000 (the swap re-assert). Under the real code the
-    // budget is shared, so `start` stays 0; under the reset-mutant it becomes 3000.
-    act(() => {
-      result.current.restoreScrollPosition();
-    });
-
-    // At t=4900 the FIRST budget has not yet elapsed (4900 - 0 < 5000): no clamp.
-    act(() => {
-      vi.advanceTimersByTime(1900);
-    });
-    expect(window.scrollTo).not.toHaveBeenCalled();
-
-    // At t=5000 the shared budget (measured from t=0) times out and clamps to the
-    // furthest reachable position (maxScroll = 200). The reset-mutant, measuring
-    // from t=3000, would still be waiting (5000 - 3000 = 2000 < 5000) and would
-    // NOT have scrolled here -> this assertion fails against that mutant.
-    act(() => {
-      vi.advanceTimersByTime(100);
-    });
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 200, behavior: "auto" });
-  });
-
-  it("(e) never throws when storage access throws", () => {
-    const err = new Error("storage denied");
-    vi.spyOn(window.sessionStorage, "getItem").mockImplementation(() => {
-      throw err;
-    });
-    vi.spyOn(window.sessionStorage, "setItem").mockImplementation(() => {
-      throw err;
-    });
-
-    expect(() => {
-      const { result, unmount } = renderHook(() => useScrollPosition("p6"));
-      act(() => {
-        setScrollY(42);
-        window.dispatchEvent(new Event("scroll"));
-        result.current.restoreScrollPosition();
-      });
-      unmount();
-    }).not.toThrow();
-  });
-});
-
-describe("hasSavedReadingPosition", () => {
-  beforeEach(() => {
-    window.sessionStorage.clear();
-  });
-
-  it("returns false when nothing is saved for the page", () => {
-    expect(hasSavedReadingPosition("none")).toBe(false);
-  });
-
-  it("returns false when the saved value is 0 (page stays at the top)", () => {
-    window.sessionStorage.setItem(`${KEY_PREFIX}zero`, "0");
-    expect(hasSavedReadingPosition("zero")).toBe(false);
-  });
-
-  it("returns true when a positive position is saved", () => {
-    window.sessionStorage.setItem(`${KEY_PREFIX}deep`, "500");
-    expect(hasSavedReadingPosition("deep")).toBe(true);
-  });
-});

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

@@ -1,291 +0,0 @@
-import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
-import type { Editor } from "@tiptap/react";
-
-// Throttle interval for persisting the scroll position while the user reads.
-const SAVE_THROTTLE_MS = 250;
-// Give up polling for the live content height after this long and restore to
-// the furthest reachable position (handles "collab never finishes laying out").
-const MAX_RESTORE_WAIT_MS = 5000;
-// How often to re-check the document height while waiting for content to load.
-const RESTORE_POLL_MS = 100;
-
-// sessionStorage key prefix. sessionStorage survives an F5 in the same tab and
-// is cleared on tab close, which is exactly the lifetime we want for an MVP
-// "remember where I was reading" feature (self-limiting, no cross-tab leak).
-const STORAGE_PREFIX = "gitmost:scroll-position:";
-
-// Keys that scroll the window. Only these count as scroll intent for keydown;
-// other keys (shortcuts, modifiers, typing) must NOT disable scroll restore.
-const SCROLL_KEYS = new Set([
-  "ArrowUp",
-  "ArrowDown",
-  "PageUp",
-  "PageDown",
-  "Home",
-  "End",
-  " ", // Space (and Shift+Space) scroll the page
-]);
-
-function storageKey(pageId: string): string {
-  return `${STORAGE_PREFIX}${pageId}`;
-}
-
-// All storage access is wrapped: private mode / quota / disabled storage must
-// never throw out of the hook and break the page.
-function readStorage(pageId: string): number | null {
-  try {
-    const raw = window.sessionStorage.getItem(storageKey(pageId));
-    if (raw === null) return null;
-    const value = Number.parseInt(raw, 10);
-    return Number.isFinite(value) ? value : null;
-  } catch (err) {
-    // Best-effort feature: storage may be unavailable (private mode / quota).
-    // No user-facing notification (a missed scroll restore is not actionable),
-    // but log per the AGENTS.md "errors must never be swallowed" rule.
-    console.warn("[useScrollPosition] sessionStorage read failed", err);
-    return null;
-  }
-}
-
-function writeStorage(pageId: string, scrollY: number): void {
-  try {
-    window.sessionStorage.setItem(storageKey(pageId), String(Math.round(scrollY)));
-  } catch (err) {
-    // Storage unavailable (private mode / quota). Non-actionable for the user,
-    // but log it rather than swallow silently (AGENTS.md error-handling rule).
-    console.warn("[useScrollPosition] sessionStorage write failed", err);
-  }
-}
-
-/**
- * Whether a positive reading position is saved for this page — i.e. the page
- * will be scrolled away from the top on load. Used by the title editor to avoid
- * auto-focusing (and thus placing the caret in) the now-off-screen title.
- * Returns false when nothing is saved or storage is unavailable.
- */
-export function hasSavedReadingPosition(pageId: string): boolean {
-  const y = readStorage(pageId);
-  return typeof y === "number" && y > 0;
-}
-
-/**
- * Persists and restores the window scroll position per page so a reader keeps
- * their place across a reload (F5) or reopening the document.
- *
- * Returns `restoreScrollPosition`, which the page editor calls from two triggers
- * (early, while the static/cached content is laid out, and again after the
- * static->live editor swap); it is idempotent, so re-asserting the same target is
- * a no-op. The two scroll mechanisms are mutually exclusive: if the URL has a
- * `#hash` anchor, the existing anchor-scroll logic wins and restore is a no-op.
- */
-export function useScrollPosition(pageId: string): {
-  restoreScrollPosition: () => void;
-} {
-  // CONTRACT: this hook assumes PageEditor REMOUNTS per page — page.tsx renders
-  // `<MemoizedFullEditor key={page.id} ...>`, so switching pages creates a fresh
-  // hook instance with fresh refs. Restore is idempotent and interaction-gated
-  // (not single-shot): it may be called from several triggers and re-asserts the
-  // SAME captured target, which is a no-op once the window is already positioned.
-  // The per-mount refs that latch are `initialTargetRef` (the captured target)
-  // and `userInteractedRef` (the reader has taken over scrolling). They are NOT
-  // reset when `pageId` changes in place (only the effect re-runs on [pageId]).
-  // If that `key={page.id}` is ever removed, restore would silently break on the
-  // 2nd page (refs would hold the first page's target / interaction flag) — in
-  // that case the refs must be reset on a pageId change.
-  //
-  // The target Y captured synchronously at mount, BEFORE any scroll/visibility
-  // handler can overwrite the stored value with a fresh 0 (the page starts
-  // scrolled to top on load). `null` means "not yet captured".
-  const initialTargetRef = useRef<number | null>(null);
-  // Set once the reader shows unambiguous scroll intent; restore must never yank
-  // a reader who has already started scrolling.
-  const userInteractedRef = useRef(false);
-  // Holds the in-flight restore poll timer so the cleanup can cancel it: without
-  // this, a fast SPA navigation away mid-poll would let the old page's poll fire
-  // window.scrollTo against the NEW page's document (visible wrong-page scroll).
-  const pollTimerRef = useRef<number | null>(null);
-  // Timestamp of the FIRST restore attempt so re-triggers (e.g. the static→live
-  // editor swap) share ONE bounded timeout budget instead of restarting it.
-  const restoreStartRef = useRef<number | null>(null);
-
-  // Capture the previously-saved value synchronously during render, before the
-  // effect below registers handlers that would persist the current (0) scrollY.
-  if (initialTargetRef.current === null) {
-    const saved = readStorage(pageId);
-    // Store 0 when nothing is saved so the "already captured" check (!== null)
-    // holds; restore treats targetY <= 0 as a no-op anyway.
-    initialTargetRef.current = saved ?? 0;
-  }
-
-  useEffect(() => {
-    let throttleTimer: number | null = null;
-
-    const save = () => {
-      writeStorage(pageId, window.scrollY);
-    };
-
-    // Throttle the high-frequency scroll handler: persist immediately on the
-    // leading edge, then at most once per SAVE_THROTTLE_MS.
-    const onScroll = () => {
-      if (throttleTimer !== null) return;
-      save();
-      throttleTimer = window.setTimeout(() => {
-        throttleTimer = null;
-      }, SAVE_THROTTLE_MS);
-    };
-
-    // pagehide fires on reload/navigation (more reliable than unload); save now.
-    const onPageHide = () => {
-      save();
-    };
-
-    // Save when the tab is being backgrounded — covers mobile where pagehide is
-    // not always emitted.
-    const onVisibilityChange = () => {
-      if (document.visibilityState === "hidden") {
-        save();
-      }
-    };
-
-    // User scroll-intent signals. wheel and touch are unconditional scroll
-    // intent; keydown is filtered to actual scroll keys only (SCROLL_KEYS) so
-    // shortcuts, lone modifiers, and typing do not abort restore. Our own
-    // window.scrollTo does NOT emit these, so restore can never self-abort via
-    // them. Once the reader shows intent we mark it and cancel any in-flight
-    // restore poll so restore can never yank them back. (Scrollbar-drag via
-    // pointer is an accepted small gap — it is not covered here.)
-    const onUserIntent = (event: Event) => {
-      // wheel/touchstart are unambiguous scroll intent; for keydown, only real
-      // scroll keys count — a shortcut or typing must not abort restore.
-      if (
-        event.type === "keydown" &&
-        !SCROLL_KEYS.has((event as KeyboardEvent).key)
-      ) {
-        return;
-      }
-      userInteractedRef.current = true;
-      if (pollTimerRef.current !== null) {
-        window.clearTimeout(pollTimerRef.current);
-        pollTimerRef.current = null;
-      }
-    };
-
-    window.addEventListener("scroll", onScroll, { passive: true });
-    window.addEventListener("pagehide", onPageHide);
-    document.addEventListener("visibilitychange", onVisibilityChange);
-    window.addEventListener("wheel", onUserIntent, { passive: true });
-    window.addEventListener("touchstart", onUserIntent, { passive: true });
-    window.addEventListener("keydown", onUserIntent);
-
-    return () => {
-      window.removeEventListener("scroll", onScroll);
-      window.removeEventListener("pagehide", onPageHide);
-      document.removeEventListener("visibilitychange", onVisibilityChange);
-      window.removeEventListener("wheel", onUserIntent);
-      window.removeEventListener("touchstart", onUserIntent);
-      window.removeEventListener("keydown", onUserIntent);
-      if (throttleTimer !== null) {
-        window.clearTimeout(throttleTimer);
-        throttleTimer = null;
-      }
-      // Cancel any in-flight restore poll so it cannot scroll the next page.
-      if (pollTimerRef.current !== null) {
-        window.clearTimeout(pollTimerRef.current);
-        pollTimerRef.current = null;
-      }
-      // SPA navigation away from this page: persist the final position.
-      save();
-    };
-  }, [pageId]);
-
-  const restoreScrollPosition = useCallback(() => {
-    // The reader took over — never yank them back.
-    if (userInteractedRef.current) return;
-
-    // Anchor priority: a `#hash` in the URL is handled by useEditorScroll.
-    if (window.location.hash) return;
-
-    const targetY = initialTargetRef.current ?? 0;
-    // Nothing meaningful to restore to.
-    if (targetY <= 0) return;
-
-    // Cancel any in-flight poll before (re)starting, so overlapping triggers can
-    // never run two concurrent polls against the same target.
-    if (pollTimerRef.current !== null) {
-      window.clearTimeout(pollTimerRef.current);
-      pollTimerRef.current = null;
-    }
-
-    // Share one timeout budget across re-triggers instead of restarting it.
-    if (restoreStartRef.current === null) {
-      restoreStartRef.current = Date.now();
-    }
-    const start = restoreStartRef.current;
-
-    const tryRestore = () => {
-      // Bail mid-poll if the reader started scrolling while we were waiting.
-      if (userInteractedRef.current) {
-        pollTimerRef.current = null;
-        return;
-      }
-
-      const maxScroll =
-        document.documentElement.scrollHeight - window.innerHeight;
-      const timedOut = Date.now() - start >= MAX_RESTORE_WAIT_MS;
-
-      // Restore once the content is tall enough to reach the target, or bail out
-      // after the timeout and scroll as far as currently possible.
-      if (maxScroll >= targetY || timedOut) {
-        const top = Math.min(targetY, Math.max(maxScroll, 0));
-        // Redundancy guard: re-asserting the SAME target when already positioned
-        // is a no-op, so this hook can be called from multiple triggers safely.
-        if (Math.abs(window.scrollY - top) > 1) {
-          window.scrollTo({ top, behavior: "auto" });
-        }
-        pollTimerRef.current = null;
-        return;
-      }
-
-      // Stored in a ref so the effect cleanup can cancel it on unmount.
-      pollTimerRef.current = window.setTimeout(tryRestore, RESTORE_POLL_MS);
-    };
-
-    tryRestore();
-  }, []);
-
-  return { restoreScrollPosition };
-}
-
-/**
- * Wires `useScrollPosition` to the page editor's static->live swap lifecycle.
- *
- * Extracted from PageEditor so the exact restore triggers (their deps and the
- * post-swap `&& editor` guard) are directly unit-testable rather than mirrored.
- * Behaviour is unchanged: `restoreScrollPosition` is idempotent, so re-asserting
- * the same target from either trigger is a no-op.
- *
- * @param pageId      the page whose scroll position is persisted/restored.
- * @param editor      the tiptap editor instance, or `null` until it is ready.
- * @param showStatic  whether the static (cached) content is still shown.
- */
-export function useScrollRestoreOnSwap(
-  pageId: string,
-  editor: Editor | null,
-  showStatic: boolean,
-): void {
-  const { restoreScrollPosition } = useScrollPosition(pageId);
-
-  // Restore as early as the static (cached) content is laid out, before paint,
-  // so the reader's position is applied without a visible jump. Aborts itself if
-  // the reader has already started scrolling (handled inside the hook).
-  useLayoutEffect(() => {
-    restoreScrollPosition();
-  }, [restoreScrollPosition]);
-
-  // Re-assert once after the static -> live editor swap in case the swap reset
-  // the window scroll. Idempotent: a no-op when the position is already correct,
-  // and a no-op after the reader has interacted.
-  useLayoutEffect(() => {
-    if (!showStatic && editor) restoreScrollPosition();
-  }, [showStatic, editor, restoreScrollPosition]);
-}

apps/client/src/features/editor/hooks/use-title-autofocus.test.ts

@@ -1,50 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
-import { useTitleAutofocus } from "./use-title-autofocus";
-
-const KEY_PREFIX = "gitmost:scroll-position:";
-
-function fakeEditor(overrides = {}) {
-  return { isInitialized: true, commands: { focus: vi.fn() }, ...overrides } as any;
-}
-
-describe("useTitleAutofocus", () => {
-  beforeEach(() => {
-    window.sessionStorage.clear();
-    vi.useFakeTimers();
-  });
-  afterEach(() => {
-    vi.useRealTimers();
-    vi.restoreAllMocks();
-  });
-
-  it("skips auto-focus when a saved reading position exists", () => {
-    window.sessionStorage.setItem(`${KEY_PREFIX}saved`, "500");
-    const editor = fakeEditor();
-    renderHook(() => useTitleAutofocus(editor, "saved"));
-    act(() => vi.advanceTimersByTime(300));
-    expect(editor.commands.focus).not.toHaveBeenCalled();
-  });
-
-  it("auto-focuses a new page (no saved position) with scrollIntoView: false", () => {
-    const editor = fakeEditor();
-    renderHook(() => useTitleAutofocus(editor, "fresh"));
-    act(() => vi.advanceTimersByTime(300));
-    expect(editor.commands.focus).toHaveBeenCalledWith("end", { scrollIntoView: false });
-  });
-
-  it("does not focus before initialization", () => {
-    const editor = fakeEditor({ isInitialized: false });
-    renderHook(() => useTitleAutofocus(editor, "fresh2"));
-    act(() => vi.advanceTimersByTime(300));
-    expect(editor.commands.focus).not.toHaveBeenCalled();
-  });
-
-  it("cancels the pending focus on unmount", () => {
-    const editor = fakeEditor();
-    const { unmount } = renderHook(() => useTitleAutofocus(editor, "fresh3"));
-    unmount();
-    act(() => vi.advanceTimersByTime(300));
-    expect(editor.commands.focus).not.toHaveBeenCalled();
-  });
-});

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

@@ -1,45 +0,0 @@
-import { useEffect, useRef } from "react";
-import type { Editor } from "@tiptap/react";
-import { hasSavedReadingPosition } from "./use-scroll-position";
-
-// Delay before auto-focusing the title on load — guards a tiptap init race
-// ("Cannot access view['hasFocus']" if focused too early).
-const TITLE_AUTOFOCUS_DELAY_MS = 300;
-
-/**
- * Auto-focus the page title shortly after mount — UNLESS a saved reading position
- * will be restored (then the viewport scrolls away from the top, and focusing the
- * top-of-page title would drop the caret off-screen). When it does focus, it uses
- * `{ scrollIntoView: false }` so placing the caret never moves the viewport
- * (tiptap's focus scrolls the focused node into view by default, which otherwise
- * yanks the window to the top and fights scroll-position restoration).
- *
- * Extracted from TitleEditor so this exact decision is unit-testable.
- *
- * CONTRACT: relies on TitleEditor remounting per page (page.tsx renders
- * `<MemoizedFullEditor key={page.id}>`), so `hasSavedScrollRef` is captured fresh
- * per page. It is read synchronously on first render, before any scroll-save
- * handler can clobber the stored value to 0 — matching `useScrollPosition`'s own
- * synchronous capture of `initialTargetRef`.
- */
-export function useTitleAutofocus(
-  titleEditor: Editor | null,
-  pageId: string,
-): void {
-  const hasSavedScrollRef = useRef<boolean | null>(null);
-  if (hasSavedScrollRef.current === null) {
-    hasSavedScrollRef.current = hasSavedReadingPosition(pageId);
-  }
-
-  useEffect(() => {
-    if (hasSavedScrollRef.current) return;
-    const timer = setTimeout(() => {
-      // guard against "Cannot access view['hasFocus']" before init
-      if (!titleEditor?.isInitialized) return;
-      titleEditor?.commands?.focus("end", { scrollIntoView: false });
-    }, TITLE_AUTOFOCUS_DELAY_MS);
-    // Clear the pending focus if the editor changes or the component unmounts
-    // (also fixes the previously-uncancelled timer).
-    return () => clearTimeout(timer);
-  }, [titleEditor]);
-}

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

@@ -1,141 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { render, act } from "@testing-library/react";
-import type { Editor } from "@tiptap/react";
-import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
-
-const KEY_PREFIX = "gitmost:scroll-position:";
-
-// NOTE ON SCOPE (F2 — reviewer-approved lighter variant).
-//
-// The real UX wiring lives in the exported `useScrollRestoreOnSwap` hook (two
-// useLayoutEffects around useScrollPosition), which PageEditor calls with the
-// same signature. A FULL PageEditor component test is impractical here and has no
-// precedent in this client: PageEditor directly constructs a
-// HocuspocusProviderWebsocket + IndexeddbPersistence, a tiptap `useEditor` with
-// collab extensions, reads jotai atoms, react-router params, the shared
-// `queryClient` from main.tsx, i18n, and mounts ~12 editor menu children. Worse,
-// the static->live swap (`showStatic` -> false) is gated on
-// `isCollabSynced(status, isLocalSynced && isRemoteSynced)`, which can only flip
-// by driving the mocked collab provider's async sync callbacks. The heaviest
-// component-test precedent in the repo (comment-hover-preview.test.tsx) mounts a
-// single leaf component with ONE mocked query; nothing mounts a feature root of
-// this weight. Reproducing all of that would test the mocks, not the wiring.
-//
-// So this file tests the REAL `useScrollRestoreOnSwap` hook — the exact code
-// PageEditor imports and calls — driving its `showStatic`/`editor` inputs the way
-// the swap does. Because it exercises the real hook (not a copy), dropping the
-// `&& editor` guard or changing the effect deps makes these tests fail; they
-// guard the production code directly (verified: removing `&& editor` reddens the
-// first test).
-//
-// Both tests observe the real effect via `window.scrollTo`. The stubbed
-// `window.scrollTo` never mutates `window.scrollY`, and the target is left
-// unreached, so every restore invocation that passes the guard yields exactly one
-// `scrollTo` call — making the call count a faithful proxy for restore invocations.
-
-function setScrollY(value: number): void {
-  Object.defineProperty(window, "scrollY", { configurable: true, value });
-}
-function setScrollHeight(value: number): void {
-  Object.defineProperty(document.documentElement, "scrollHeight", {
-    configurable: true,
-    value,
-  });
-}
-function setInnerHeight(value: number): void {
-  Object.defineProperty(window, "innerHeight", { configurable: true, value });
-}
-
-// Minimal stand-in for the tiptap editor: the hook only truthiness-checks it.
-const fakeEditor = { id: "editor" } as unknown as Editor;
-
-// Thin host that calls the REAL hook so a rerender drives showStatic/editor
-// exactly like the page-editor swap does.
-function Host({
-  pageId,
-  showStatic,
-  editor,
-}: {
-  pageId: string;
-  showStatic: boolean;
-  editor: Editor | null;
-}) {
-  useScrollRestoreOnSwap(pageId, editor, showStatic);
-  return null;
-}
-
-describe("PageEditor scroll-restore wiring (useScrollRestoreOnSwap)", () => {
-  beforeEach(() => {
-    window.sessionStorage.clear();
-    setScrollY(0);
-    setScrollHeight(0);
-    setInnerHeight(800);
-    window.scrollTo = vi.fn();
-    window.location.hash = "";
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-    vi.useRealTimers();
-    window.location.hash = "";
-  });
-
-  it("re-invokes restore after the swap, with the [showStatic, editor] deps/guard", () => {
-    // Target is immediately reachable, so each restore that passes the guard
-    // scrolls synchronously. `window.scrollY` stays 0 (stubbed scrollTo never
-    // updates it), so scrollTo is called once per effective restore — a proxy for
-    // the restore invocation count.
-    window.sessionStorage.setItem(`${KEY_PREFIX}guard`, "500");
-    setInnerHeight(800);
-    setScrollHeight(2000); // maxScroll = 1200 >= 500: reachable, no polling.
-
-    // Pre-swap: static content shown, live editor not ready. Only the early
-    // pre-paint restore fires; the post-swap effect's guard (!showStatic) blocks it.
-    const { rerender } = render(
-      <Host pageId="guard" showStatic={true} editor={null} />,
-    );
-    expect(window.scrollTo).toHaveBeenCalledTimes(1);
-
-    // Collab reports synced (showStatic flips false) but the editor is not ready
-    // yet: the swap effect re-runs (deps [showStatic, editor] changed) but the
-    // `&& editor` guard must keep it a no-op. The early effect does NOT re-fire
-    // (its dep [restoreScrollPosition] is a stable useCallback([])).
-    // (Pins the guard: dropping `&& editor` would restore against a null editor,
-    // producing a 2nd scrollTo and failing this expectation.)
-    rerender(<Host pageId="guard" showStatic={false} editor={null} />);
-    expect(window.scrollTo).toHaveBeenCalledTimes(1);
-
-    // The static -> live swap completes (showStatic false AND editor present): the
-    // post-swap effect re-asserts the restore exactly once more, driven solely by
-    // the [showStatic, editor] deps changing.
-    rerender(<Host pageId="guard" showStatic={false} editor={fakeEditor} />);
-    expect(window.scrollTo).toHaveBeenCalledTimes(2);
-  });
-
-  it("the post-swap re-assert drives a REAL restore (window.scrollTo) via the hook", () => {
-    // End-to-end through the real useScrollPosition (inside the hook): the swap
-    // re-invocation is the CAUSE of the scroll (nothing scrolls before it).
-    vi.useFakeTimers();
-    window.sessionStorage.setItem(`${KEY_PREFIX}peg`, "500");
-    setInnerHeight(800);
-    setScrollHeight(100); // maxScroll = -700: target not reachable yet -> polls.
-
-    // Pre-swap: the early restore runs but content is too short, so it starts
-    // polling (a pending timer) without scrolling. We never advance timers, so the
-    // early poll cannot fire on its own — isolating the swap as the sole cause.
-    const { rerender } = render(
-      <Host pageId="peg" showStatic={true} editor={null} />,
-    );
-    expect(window.scrollTo).not.toHaveBeenCalled();
-
-    // The live content is now laid out tall enough to reach the target.
-    setScrollHeight(2000); // maxScroll = 1200 >= 500
-
-    // The static -> live swap: the post-swap useLayoutEffect re-invokes the real
-    // hook, whose synchronous tryRestore now reaches the target and scrolls.
-    act(() => {
-      rerender(<Host pageId="peg" showStatic={false} editor={fakeEditor} />);
-    });
-    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
-  });
-});

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

@@ -6,16 +6,7 @@ import React, {
   useRef,
   useState,
 } from "react";
-import { IndexeddbPersistence } from "y-indexeddb";
-import * as Y from "yjs";
-import {
-  HocuspocusProvider,
-  onStatusParameters,
-  WebSocketStatus,
-  HocuspocusProviderWebsocket,
-  onSyncedParameters,
-  onStatelessParameters,
-} from "@hocuspocus/provider";
+import { WebSocketStatus } from "@hocuspocus/provider";
 import {
   Editor,
   EditorContent,
@@ -28,13 +19,15 @@ import {
   mainExtensions,
 } from "@/features/editor/extensions/extensions";
 import { useAtom, useAtomValue } from "jotai";
-import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
   currentPageEditModeAtom,
+  isLocalSyncedAtom,
+  isRemoteSyncedAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { useEditorProviders } from "@/features/editor/contexts/editor-providers-context";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
   activeCommentIdAtom,
@@ -42,7 +35,6 @@ import {
   showReadOnlyCommentPopupAtom,
 } from "@/features/comment/atoms/comment-atom";
 import CommentDialog from "@/features/comment/components/comment-dialog";
-import CommentHoverPreview from "@/features/comment/components/comment-hover-preview";
 import { EditorBubbleMenu } from "@/features/editor/components/bubble-menu/bubble-menu";
 import { ReadonlyBubbleMenu } from "@/features/editor/components/bubble-menu/readonly-bubble-menu";
 import TableMenu from "@/features/editor/components/table/table-menu.tsx";
@@ -59,10 +51,8 @@ import {
 } from "@/features/editor/components/common/editor-paste-handler.tsx";
 import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
 import DrawioMenu from "./components/drawio/drawio-menu";
-import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
-import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";
-import { useIdle } from "@/hooks/use-idle.ts";
+import { useDebouncedCallback } from "@mantine/hooks";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
@@ -73,12 +63,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 { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
 import ColumnsMenu from "@/features/editor/components/columns/columns-menu.tsx";
 import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";
@@ -105,7 +92,6 @@ export default function PageEditor({
   canComment,
 }: PageEditorProps) {
   const { t } = useTranslation();
-  const collaborationURL = useCollaborationUrl();
   const isComponentMounted = useRef(false);
   const editorRef = useRef<Editor | null>(null);
 
@@ -119,22 +105,10 @@ export default function PageEditor({
   const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
   const [showReadOnlyCommentPopup] = useAtom(showReadOnlyCommentPopupAtom);
-  const [isLocalSynced, setIsLocalSynced] = useState(false);
-  const [isRemoteSynced, setIsRemoteSynced] = useState(false);
   const [yjsConnectionStatus, setYjsConnectionStatus] = useAtom(
     yjsConnectionStatusAtom,
   );
   const menuContainerRef = useRef(null);
-  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
-  // Always holds the latest collab token. The provider effect below runs once
-  // per pageId, so a handler created inside it would otherwise close over a
-  // stale `collabQuery`. Reading the ref gives the current token instead.
-  const collabTokenRef = useRef<string | undefined>(undefined);
-  useEffect(() => {
-    collabTokenRef.current = collabQuery?.token;
-  }, [collabQuery?.token]);
-  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
-  const documentState = useDocumentVisibility();
   const { pageSlug } = useParams();
   const slugId = extractPageSlugId(pageSlug);
   const currentPageEditMode = useAtomValue(currentPageEditModeAtom);
@@ -143,141 +117,27 @@ export default function PageEditor({
     [isComponentMounted],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
-  // Providers only created once per pageId
-  const providersRef = useRef<{
-    local: IndexeddbPersistence;
-    remote: HocuspocusProvider;
-    socket: HocuspocusProviderWebsocket;
-  } | null>(null);
-  const [providersReady, setProvidersReady] = useState(false);
 
-  useEffect(() => {
-    if (!providersRef.current) {
-      const documentName = `page.${pageId}`;
-      const ydoc = new Y.Doc();
-      const local = new IndexeddbPersistence(documentName, ydoc);
-      const socket = new HocuspocusProviderWebsocket({
-        url: collaborationURL,
-      });
-      const onLocalSyncedHandler = () => {
-        setIsLocalSynced(true);
-      };
-      const onStatusHandler = (event: onStatusParameters) => {
-        setYjsConnectionStatus(event.status);
-      };
-      const onSyncedHandler = (event: onSyncedParameters) => {
-        setIsRemoteSynced(event.state);
-      };
-      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
-        try {
-          const message = JSON.parse(payload);
-          if (message?.type !== "page.updated" || !message.updatedAt) return;
-          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-          if (pageData) {
-            queryClient.setQueryData(["pages", slugId], {
-              ...pageData,
-              updatedAt: message.updatedAt,
-              ...(message.lastUpdatedBy && {
-                lastUpdatedBy: message.lastUpdatedBy,
-              }),
-            });
-          }
-        } catch {
-          // ignore unrelated stateless messages
-        }
-      };
-      const onAuthenticationFailedHandler = () => {
-        // Read the latest token via the ref (the closure-captured `collabQuery`
-        // may be stale). Guard the decode: a missing or unparseable token must
-        // not throw "Invalid token specified" and should trigger a refresh so
-        // the editor reconnects even when the initial token fetch failed.
-        const token = collabTokenRef.current;
-        let needsRefresh = true; // no/unparseable token -> fetch a fresh one and reconnect
-        if (token) {
-          try {
-            // A token that decodes but lacks a numeric `exp` must be treated as
-            // expired (`Date.now()/1000 >= undefined` is `false`, which would
-            // otherwise skip the reconnect), so refresh on any missing/non-number exp.
-            const exp = jwtDecode<{ exp?: number }>(token).exp;
-            needsRefresh = typeof exp !== "number" || Date.now() / 1000 >= exp;
-          } catch {
-            needsRefresh = true;
-          }
-        }
-        if (!needsRefresh) return;
-        refetchCollabToken().then((result) => {
-          if (result.data?.token) {
-            socket.disconnect();
-            setTimeout(() => {
-              remote.configuration.token = result.data.token;
-              socket.connect();
-            }, 100);
-          }
-        });
-      };
-      const remote = new HocuspocusProvider({
-        websocketProvider: socket,
-        name: documentName,
-        document: ydoc,
-        token: collabQuery?.token,
-        onAuthenticationFailed: onAuthenticationFailedHandler,
-        onStatus: onStatusHandler,
-        onSynced: onSyncedHandler,
-        onStateless: onStatelessHandler,
-      });
-
-      local.on("synced", onLocalSyncedHandler);
-      providersRef.current = { socket, local, remote };
-      setProvidersReady(true);
-    } else {
-      setProvidersReady(true);
-    }
-    // Only destroy on final unmount
-    return () => {
-      providersRef.current?.socket.destroy();
-      providersRef.current?.remote.destroy();
-      providersRef.current?.local.destroy();
-      providersRef.current = null;
-    };
-  }, [pageId]);
-
-  // Only connect/disconnect on tab/idle, not destroy
-  useEffect(() => {
-    if (!providersReady || !providersRef.current) return;
-    const socket = providersRef.current.socket;
-
-    if (
-      isIdle &&
-      documentState === "hidden" &&
-      yjsConnectionStatus === WebSocketStatus.Connected
-    ) {
-      socket.disconnect();
-      return;
-    }
-    if (
-      documentState === "visible" &&
-      yjsConnectionStatus === WebSocketStatus.Disconnected
-    ) {
-      resetIdle();
-      socket.connect();
-    }
-  }, [isIdle, documentState, providersReady, resetIdle]);
-
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  // Shared providers + Y.Doc lifted into full-editor via context. The provider
+  // lifecycle (creation, idle/visibility connect, attach, destroy, token
+  // refresh) lives in usePageCollabProviders. Null-safe when rendered without
+  // the context (defensive) — in practice full-editor always provides it.
+  const editorProviders = useEditorProviders();
+  const remote = editorProviders?.remote ?? null;
+  const providersReady = editorProviders?.providersReady ?? false;
+  const isLocalSynced = useAtomValue(isLocalSyncedAtom);
+  const isRemoteSynced = useAtomValue(isRemoteSyncedAtom);
 
   const extensions = useMemo(() => {
-    if (!providersReady || !providersRef.current || !currentUser?.user) {
+    if (!providersReady || !remote || !currentUser?.user) {
       return mainExtensions;
     }
 
-    const remoteProvider = providersRef.current.remote;
-
     return [
       ...mainExtensions,
-      ...collabExtensions(remoteProvider, currentUser?.user),
+      ...collabExtensions(remote, currentUser?.user),
     ];
-  }, [providersReady, currentUser?.user]);
+  }, [providersReady, remote, currentUser?.user]);
 
   const editor = useEditor(
     {
@@ -481,11 +341,6 @@ export default function PageEditor({
     }
   }, [yjsConnectionStatus, isSynced]);
 
-  // Restore the reader's scroll position across the static -> live editor swap.
-  // The wiring (early pre-paint restore + post-swap re-assert) lives in the hook
-  // so its triggers/guard are directly unit-testable.
-  useScrollRestoreOnSwap(pageId, editor, showStatic);
-
   return (
     <TransclusionLookupProvider>
       <PageEmbedLookupProvider>
@@ -533,11 +388,6 @@ export default function PageEditor({
           <div ref={menuContainerRef}>
             <EditorContent editor={editor} />
 
-            <CommentHoverPreview
-              pageId={pageId}
-              containerRef={menuContainerRef}
-            />
-
             {editor && (
               <SearchAndReplaceDialog editor={editor} editable={editable} />
             )}
@@ -562,7 +412,7 @@ export default function PageEditor({
             {editor &&
               !editorIsEditable &&
               (editable || canComment) &&
-              providersRef.current && <ReadonlyBubbleMenu editor={editor} />}
+              remote && <ReadonlyBubbleMenu editor={editor} />}
             {showCommentPopup && (
               <CommentDialog editor={editor} pageId={pageId} />
             )}

apps/client/src/features/editor/page-ydoc-name.ts

@@ -0,0 +1,14 @@
+/**
+ * Single source of truth for the IndexedDB / Hocuspocus document name of a
+ * page's collaborative Yjs doc.
+ *
+ * The `page.<id>` convention is shared knowledge across three call sites: the
+ * live editor providers (`use-page-collab-providers`), the offline warm path
+ * (`make-offline`), and the offline purge (`clear-offline-cache`, which matches
+ * the databases to delete by this prefix). Centralizing it here stops those
+ * sites from silently drifting apart.
+ */
+export const PAGE_YDOC_NAME_PREFIX = "page.";
+
+export const pageYdocName = (pageId: string): string =>
+  `${PAGE_YDOC_NAME_PREFIX}${pageId}`;

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

@@ -1,12 +1,9 @@
 .ProseMirror {
   .codeBlock {
-    /* #146: flex column keeps the editable <pre> (first in the DOM so click
-       hit-testing is correct) laid out above any Mermaid diagram. `position:
-       relative` anchors the control panel, which is floated into the top-right
-       corner as an absolute overlay (see `.menuGroup` in code-block.module.css). */
+    /* #146: flex column so the menu (rendered AFTER <pre> in the DOM, so the
+       editable contentDOM is first) is lifted back above the code via `order`. */
     display: flex;
     flex-direction: column;
-    position: relative;
     padding: 4px;
     border-radius: var(--mantine-radius-default);
     background-color: light-dark(var(--mantine-color-gray-0),  var(--mantine-color-dark-8));

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

@@ -14,7 +14,6 @@
 @import "./mention.css";
 @import "./ordered-list.css";
 @import "./highlight.css";
-@import "./spoiler.css";
 @import "./indent.css";
 @import "./columns.css";
 @import "./status.css";

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

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

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

@@ -1,21 +0,0 @@
-.spoiler {
-  background: rgba(0, 0, 0, 0.85);
-  border-radius: 0.25em;
-  cursor: pointer;
-  filter: blur(0.3em);
-  transition: filter 0.15s ease;
-  user-select: none;
-}
-
-.spoiler.is-revealed {
-  filter: none;
-  background: rgba(125, 125, 125, 0.18);
-  user-select: auto;
-}
-
-@media print {
-  .spoiler {
-    filter: none;
-    background: rgba(125, 125, 125, 0.18);
-  }
-}

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

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

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

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

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

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

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

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