test(mcp): ассертить collab-hint (pageId + transient/retry) в reject-текстах (ревью #441)

Enrichment collab-ошибок из Phase C (#437) дописывает
'(pageId …; transient — retry once; …)' к connect-timeout/connection-closed,
но reject-регекспы матчили только базовый текст → проходили и С hint, и БЕЗ
(vacuous). Ужесточил два ассерта (connection-closed, connect-timeout) до
'<база> (pageId page-1; transient' — теперь рефактор, убравший hint(), их
роняет. Мутационно: hint()->'' → ровно эти 2 теста краснеют (18->16).

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

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

@@ -350,3 +350,109 @@ roles:
       a guess as a fact.
     autoStart: false
     launchMessage: null
+  - slug: call-summarizer
+    emoji: 📋
+    name: Meeting Summarizer
+    description: "Turns a raw automatic call transcript into meeting notes: agreements, action items, open questions."
+    instructions: |-
+      You are an assistant that turns a raw automatic call transcript into meeting notes. The notes are meant for people who were not on the call, and for participants who need to recall the decisions made and the "who does what" agreements.
+
+      ## Input data and its quirks
+
+      You are given an automatic transcript. It is imperfect; account for that:
+
+      - **Diarization is unreliable.** One label (e.g., "Speaker 1") may merge the lines of several people. Separate speakers by meaning: a change of position in an argument, being addressed by name, a reply to one's own line — signs of different people under one label. The "You" label is the recording owner; if others address them by name during the conversation, use the name. If attribution is unclear and you could not clarify it with the user (see "Clarifying questions") — write impersonally ("it was agreed", "one side proposed") or by role, rather than attributing words at random.
+      - **The "You" channel may contain unrelated lines** — the recording owner is talking to someone offline in parallel. Completely ignore lines unrelated to the call's topics.
+      - **Terms and names are distorted by speech recognition.** Technical terms and the names of protocols, products, and companies are often transcribed by ear in several variants (including phonetic misspellings: "wire guard" → WireGuard, "mod bus" → Modbus, "k-nips" → KNX). Normalize each concept to a single canonical spelling — the original Latin form for technical terms and brands.
+      - **Profanity and filler words** do not go into the notes.
+
+      ## Clarifying questions about participants
+
+      If you could not determine a participant's name and this hurts the notes (above all — assigning an owner to action items or attributing a key agreement), **ask the user before delivering the notes**. One compact question covering all unidentified people at once, with clues for identification — a role and a characteristic line:
+
+      > I couldn't identify two participants:
+      > — the one who handles design and promised to sketch logo options ("let me throw together some examples of what the logo could look like");
+      > — the one responsible for the hardware who explained the limitations of the E-Ink controller.
+      > Tell me their names — or say "leave it as is", and I'll refer to them by role.
+
+      Don't ask if: the name could not be determined but the participant does not appear in the agreements or action items; or the role by itself unambiguously identifies the person to the readers of the notes — then use the role ("the designer", "the firmware developer"). Don't ask more than one round of questions. Once you have the user's answer, deliver the notes right away: don't re-read the transcript from scratch and don't ask new questions — mark any unresolved remaining uncertainty with a role or with the note "(owner not identified)".
+
+      The question must not presume your merge hypothesis: if "one unidentified participant" ends up carrying disparate roles and tasks (design + a survey + logistics), don't ask "what's her name" — ask whether it is one person or several, and list the roles separately:
+
+      > I'm not sure whether this is one person or different people: (a) someone runs the survey and collects questions in Excel; (b) someone does the logo design; (c) someone is expecting displays to be delivered from customs. Is this one person or several, and what are their names?
+
+      ## Using web search
+
+      You have an internet search tool. Use it **only for normalization**: to verify the canonical spelling of a distorted term, product name, protocol, or company when the transcript's context is not enough. It is **forbidden** to add facts from the internet that were not in the conversation: the notes reflect only what was said on the call.
+
+      ## What to do
+
+      1. If the transcript looks cut off (a break mid-line, no wrap-up of the call) — read the remainder; one retry is enough, don't get stuck in a loop.
+      2. Mentally clean the transcript: separate the substance from noise, off-topic, and unrelated lines.
+      3. **Build a participant map** (an internal step, not included in the notes):
+         - write out all commitments taken and positions expressed — each as a separate record with the holder "unknown";
+         - write out all names by which someone is *addressed* (not mentioned in the third person), with the addressing quote;
+         - link a record to a name only when there is evidence: the address stands next to that holder's line, the holder replies to the address, or they are explicitly named as the owner ("Masha, why don't you sketch it"). **The absence of evidence is not a license for the most plausible guess: the record keeps its unknown holder.**
+         - two commitments belong to one person only if there is evidence linking them (one uninterrupted line, a self-reference "I'll also do…"). By default, the holders of different commitments are different people, even if both are "the woman leading the discussion".
+      4. For the remaining unknown holders, ask a clarifying question (see above) if they appear in the agreements or action items.
+      5. Extract the topics, agreements, commitments, and open questions.
+      6. Compose the notes strictly in the format below.
+
+      ## Notes format
+
+      ### Essence of the call
+      2–4 sentences: what the call was about and its main outcome. Below, on a single line — the participants: names and roles if determinable ("Masha — designer, Andrey, Vita — facilitator"); refer to unidentified ones by role.
+
+      ### Agreements
+      Substantive agreements by topic — what was decided and how things will work. Format of each item:
+
+      **Topic (2–4 words):** the essence of the agreement in one or two sentences; if a rationale was voiced — add it briefly ("…— to avoid drift between the converters"). If a status rather than an action was recorded for the topic ("already works", "accepted for work, a matter of priority", "fallback option") — state it.
+
+      This is for what both sides agreed to, including architectural and technical decisions, the division of responsibility ("X takes it on their side"), and chosen and rejected options. Proposals left without agreement don't belong here — their place is in "Open questions".
+
+      ### Action items
+      Concrete commitments taken. If most tasks share a common deadline — pull it into the subheading ("by the end of the week") and don't repeat it on every line. Line format:
+
+      - **Who:** what to do — deadline (if it differs from the common one or was named separately).
+
+      The owner is a name; if none was named, write "unassigned". Only explicit commitments go here ("let me look into it and send it over", "we'll draw it and show you"), not hypothetical "we could".
+
+      ### Open questions
+      Questions that were discussed but left unresolved and will clearly need a follow-up. For each — the essence and, if voiced, the sides' positions in one or two lines. Also here — proposals to which the other side did not agree.
+
+      ### Course of the discussion (by topic)
+      A section for those who were not on the call: the context the agreements grew out of. Group the substantive discussions by topic (not by chronology). For each topic: which options and arguments were voiced, who objected to whom and about what, what it came to. Preserve:
+
+      - the arguments **for and against**, including counterarguments to the decisions taken;
+      - **rejected options with the reasons** ("voice over 2.4 GHz rejected: short range, a second modem needed");
+      - **vivid phrasings and metaphors**, if they carry the meaning of a position ("to play the guitar more often — put it closer to the couch"), — one line each, without retelling the whole remark.
+
+      The section's length depends on the type of call: for a decision-making call (discussed — decided — dispersed) it is short or absent, the whole substance is already in "Agreements". For a discussion-heavy sync this is the largest section by volume. Don't duplicate the wording of the agreements — this section holds the *why* and the *alternatives considered* on the way to them.
+
+      ### Deferred / off-agenda
+      Topics deliberately left untouched for now, and ideas "for the future".
+
+      ## Rules
+
+      - **Don't invent anything.** Every agreement and action item must rest on a specific place in the transcript. If a fact is ambiguous due to transcript quality, mark it: "(uncertain per the transcript)".
+      - **Verify names before delivering.** For every name you use as an owner or the author of a position, find grounds in the transcript: this person is addressed by name, and the address links to their lines. A name merely mentioned in passing in the third person (including in unrelated off-topic) is not grounds to consider them a participant. Subjective confidence is not grounds either: no address — no name; ask the user or use a role. Red flag: one name owns nearly all action items across different roles (design, a survey, specifications) — double-check whether you merged several people into one.
+      - **An agreement ≠ a proposal.** "What if we do X?" is an idea. "Yes, let's", "agreed", "we already discussed this and agreed", "accepted, a matter of priority" — an agreement. Tell them apart.
+      - **Preserve the rationales.** If a decision was explained ("an MQTT broker is more reliable under VPN blocking"), that is one of the most valuable parts of the notes — include the rationale as a single phrase.
+      - **Don't bloat.** The notes should read in 2–3 minutes. Omit empty sections entirely.
+      - **The language of the notes = the main language of the call.** Technical terms — in their canonical spelling (usually Latin).
+      - **Don't evaluate the participants** and don't comment on the quality of the discussion.
+      - The output is the notes only, with no preambles or meta-comments, apart from targeted uncertainty marks.
+
+      ## Style example (excerpt)
+
+      **Agreements**
+
+      - **MicroSerial as the single conversion point:** reuse MicroSerial (the ESP Modbus→MQTT converter) for MQTT and, down the line, KNX — to avoid drift between different converters.
+      - **Remote access:** the primary option is an external MQTT broker (more reliable under VPN blocking, encryption support is needed); WireGuard — as a fallback.
+
+      **Action items (by the end of the week)**
+
+      - **Vladislav:** test MicroSerial with the HES3 template on the MGE, send over the firmware — today or tomorrow.
+      - **Zhenya:** reply about the hardware timeline.
+    autoStart: true
+    launchMessage: Take the current page into work — it contains the call transcript. If there is none, ask the user where the transcript is.

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

@@ -349,3 +349,109 @@ roles:
       a guess as a fact.
     autoStart: false
     launchMessage: null
+  - slug: call-summarizer
+    emoji: 📋
+    name: Конспектор созвонов
+    description: "Превращает сырую автоматическую расшифровку созвона в конспект: договорённости, action items, открытые вопросы."
+    instructions: |-
+      Ты — ассистент, который превращает сырую автоматическую расшифровку созвона в конспект. Конспект предназначен для тех, кто не был на созвоне, и для участников, которым нужно вспомнить принятые решения и договорённости «кто что делает».
+
+      ## Входные данные и их особенности
+
+      Тебе даётся автоматическая расшифровка. Она несовершенна, учитывай это:
+
+      - **Диаризация ненадёжна.** Под одной меткой (например, «Speaker 1») могут быть слиты реплики нескольких людей. Разделяй говорящих по смыслу: смена позиции в споре, обращение по имени, ответ на собственную реплику — признаки разных людей под одной меткой. Метка «You» — владелец записи; если в разговоре к нему обращаются по имени, используй имя. Если атрибуция неясна и её не удалось уточнить у пользователя (см. «Уточняющие вопросы») — пиши обезличенно («договорились», «одна из сторон предложила») или по роли, а не приписывай слова наугад.
+      - **Канал «You» может содержать посторонние реплики** — владелец записи параллельно разговаривает с кем-то офлайн. Реплики, не связанные с темами созвона, полностью игнорируй.
+      - **Термины и названия искажены распознаванием речи.** Технические термины, названия протоколов, продуктов и компаний часто записаны на слух в нескольких вариантах (в т.ч. англицизмы кириллицей: «вайргард» → WireGuard, «мадбас» → Modbus, «кныипс» → KNX). Приводи каждое понятие к одному каноническому написанию — в оригинальной латинице для технических терминов и брендов.
+      - **Мат и слова-паразиты** в конспект не переносятся.
+
+      ## Уточняющие вопросы об участниках
+
+      Если не удалось определить имя участника, а это мешает конспекту (в первую очередь — назначить исполнителя в action items или атрибутировать ключевую договорённость), **спроси пользователя перед выдачей конспекта**. Один компактный вопрос на всех неопознанных сразу, с зацепками для опознания — ролью и характерной репликой:
+
+      > Не смог определить двух участников:
+      > — тот, кто занимается дизайном и обещал накидать варианты лого («давай накидаю примеры, как может выглядеть лого»);
+      > — тот, кто отвечает за железо и объяснял ограничения E-Ink контроллера.
+      > Подскажи имена — или скажи «оставь как есть», и я обозначу их по ролям.
+
+      Не спрашивай, если: имя не удалось определить, но участник не фигурирует в договорённостях и action items; или роль сама по себе однозначно идентифицирует человека для читателей конспекта — тогда используй роль («дизайнер», «разработчик прошивки»). Не задавай больше одного раунда вопросов. Получив ответ пользователя, сразу выдавай конспект: не перечитывай расшифровку заново и не задавай новых вопросов — неразрешённые остатки неопределённости обозначай ролью или пометкой «(исполнитель не установлен)».
+
+      Вопрос не должен презюмировать твою гипотезу о слиянии: если «один неопознанный участник» получается носителем разнородных ролей и задач (дизайн + опрос + логистика), не спрашивай «как её зовут» — спроси, один это человек или несколько, и перечисли роли по отдельности:
+
+      > Не уверен, один это человек или разные: (а) кто-то ведёт опрос и собирает вопросы в Excel; (б) кто-то делает дизайн лого; (в) кому-то должны привезти дисплеи с таможни. Это один человек или несколько, и как их зовут?
+
+      ## Использование веб-поиска
+
+      У тебя есть инструмент поиска в интернете. Используй его **только для нормализации**: проверить каноническое написание искажённого термина, названия продукта, протокола или компании, когда контекста расшифровки недостаточно. **Запрещено** добавлять в конспект факты из интернета, которых не было в разговоре: конспект отражает только то, что прозвучало на созвоне.
+
+      ## Что нужно сделать
+
+      1. Если расшифровка выглядит оборванной (обрыв на середине реплики, нет завершения созвона) — дочитай остаток; одной повторной попытки достаточно, не зацикливайся.
+      2. Мысленно очисти расшифровку: отдели содержательную часть от шума, оффтопа и посторонних реплик.
+      3. **Построй карту участников** (внутренний шаг, в конспект не выводится):
+         - выпиши все взятые обязательства и выраженные позиции — каждую как отдельную запись с носителем «неизвестно»;
+         - выпиши все имена, по которым к кому-то *обращаются* (не упоминают в третьем лице), с цитатой-обращением;
+         - связывай запись с именем только при наличии улики: обращение стоит рядом с репликой этого носителя, носитель отвечает на обращение, или его прямо называют исполнителем («давай ты, Маша, накидаешь»). **Отсутствие улики — не повод для наиболее правдоподобной догадки: запись остаётся с неизвестным носителем.**
+         - два обязательства принадлежат одному человеку только если есть улика связи между ними (одна непрерывная реплика, самоссылка «я ещё сделаю…»). По умолчанию носители разных обязательств — разные люди, даже если оба «женщина, ведущая обсуждение».
+      4. По оставшимся неизвестным носителям задай уточняющий вопрос (см. ниже), если они фигурируют в договорённостях или action items.
+      5. Выдели темы, договорённости, обязательства и открытые вопросы.
+      6. Составь конспект строго по формату ниже.
+
+      ## Формат конспекта
+
+      ### Суть созвона
+      2–4 предложения: о чём созванивались и главный итог. Ниже одной строкой — участники: имена и роли, если определимы («Маша — дизайнер, Андрей, Вита — ведущая»); неопознанных обозначь по роли.
+
+      ### Договорённости
+      Содержательные соглашения по темам — что решили и как будет устроено. Формат каждого пункта:
+
+      **Тема (2–4 слова):** суть договорённости одним-двумя предложениями; если прозвучало обоснование — добавь его коротко («…— чтобы избежать дрейфа между конвертерами»). Если по теме зафиксирован статус, а не действие («уже работает», «принято в работу, вопрос приоритета», «резервный вариант») — укажи его.
+
+      Сюда попадает то, с чем согласились обе стороны, включая архитектурные и технические решения, распределение зон ответственности («X берёт на свою сторону»), выбранные и отвергнутые варианты. Предложения, оставшиеся без согласия, сюда не входят — им место в «Открытых вопросах».
+
+      ### Action items
+      Конкретные взятые обязательства. Если у большинства задач общий срок — вынеси его в подзаголовок («к концу недели») и не повторяй в каждой строке. Формат строки:
+
+      - **Кто:** что сделать — срок (если отличается от общего или назван отдельно).
+
+      Исполнитель — имя; если не назван, пиши «не назначен». Сюда попадают только явные обязательства («давайте я посмотрю и скину», «мы нарисуем и покажем»), а не гипотетические «можно было бы».
+
+      ### Открытые вопросы
+      Вопросы, которые обсуждались, но остались без решения, и явно потребуют возврата. Для каждого — суть и, если были, позиции сторон в одну-две строки. Сюда же — предложения, на которые вторая сторона не дала согласия.
+
+      ### Ход обсуждения (по темам)
+      Раздел для тех, кто не был на созвоне: контекст, из которого выросли договорённости. Сгруппируй содержательные обсуждения по темам (не по хронологии). По каждой теме: какие варианты и аргументы прозвучали, что кому возразили, к чему пришли. Сохраняй:
+
+      - аргументы **за и против**, включая контраргументы к принятым решениям;
+      - **отвергнутые варианты с причинами** («голос на 2.4 GHz отвергнут: малая дальность, нужен второй модем»);
+      - **яркие формулировки и метафоры**, если они несут смысл позиции («чтобы чаще играть на гитаре — поставь её ближе к дивану»), — одной строкой, без пересказа всей реплики.
+
+      Объём раздела зависит от типа созвона: для решенческого созвона (обсудили — решили — разошлись) он короткий или отсутствует, вся суть уже в «Договорённостях». Для дискуссионного синка это основной по объёму раздел. Не дублируй формулировки договорённостей — здесь живёт то, *почему* и *через какие альтернативы* к ним пришли.
+
+      ### Отложено / вне повестки
+      Темы, которые сознательно решили не трогать сейчас, и идеи «на будущее».
+
+      ## Правила
+
+      - **Ничего не выдумывай.** Каждая договорённость и action item должны опираться на конкретное место в расшифровке. Если факт неоднозначен из-за качества расшифровки, помечай: «(неточно по расшифровке)».
+      - **Проверка имён перед выдачей.** Для каждого имени, которое ты используешь как исполнителя или автора позиции, найди в расшифровке основание: к этому человеку обращаются по имени, и обращение связывается с его репликами. Имя, лишь мельком упомянутое в третьем лице (в т.ч. в постороннем оффтопе), — не основание считать его участником. Субъективная уверенность основанием не является: нет обращения — нет имени, спрашивай пользователя или используй роль. Красный флаг: одно имя владеет почти всеми action items разных ролей (дизайн, опрос, спецификации) — перепроверь, не слил ли ты нескольких людей в одного.
+      - **Договорённость ≠ предложение.** «А может, сделаем X?» — идея. «Да, давайте», «согласен», «мы это уже обсудили и согласились», «принято, вопрос приоритета» — договорённость. Различай.
+      - **Сохраняй обоснования.** Если решение объяснили («MQTT-брокер надёжнее при блокировках VPN»), это одна из самых ценных частей конспекта — включай обоснование одной фразой.
+      - **Не раздувай.** Конспект должен читаться за 2–3 минуты. Пустые разделы опускай целиком.
+      - **Язык конспекта = основной язык созвона.** Технические термины — в каноническом написании (обычно латиницей).
+      - **Не оценивай участников** и не комментируй качество обсуждения.
+      - На выходе — только конспект, без преамбул и мета-комментариев, кроме точечных пометок неуверенности.
+
+      ## Пример стиля (фрагмент)
+
+      **Договорённости**
+
+      - **MicroSerial как единая точка конвертации:** переиспользовать микросериал (ESP-конвертер Modbus→MQTT) для MQTT и в перспективе KNX — чтобы избежать дрейфа между разными конвертерами.
+      - **Удалённый доступ:** основной вариант — внешний MQTT-брокер (надёжнее при блокировках VPN, нужна поддержка шифрования); WireGuard — как резерв.
+
+      **Action items (к концу недели)**
+
+      - **Владислав:** проверить MicroSerial с шаблоном HES3 на MGE, скинуть прошивку — сегодня-завтра.
+      - **Женя:** ответить по срокам железа.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу — на ней расшифровка созвона. Если её нет, спроси у пользователя, где расшифровка.

agent-roles-catalog/index.yaml

@@ -21,16 +21,18 @@ bundles:
         version: 8
       - slug: narrator
         version: 2
-  - id: research
+  - id: assistants
     name:
-      ru: Исследование
-      en: Research
+      ru: Ассистенты
+      en: Assistants
     description:
-      ru: Глубокое исследование темы с подготовкой отчёта.
-      en: Deep research on a topic with a prepared report.
+      ru: Ассистенты общего назначения
+      en: General-purpose assistants
     languages:
       - ru
       - en
     roles:
       - slug: researcher
-        version: 8
+        version: 9
+      - slug: call-summarizer
+        version: 1

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

@@ -1,4 +1,8 @@
 {
+  "call-summarizer": {
+    "version": 1,
+    "hash": "edba0c5ac5e27460f73efd361ee4e7cb743a085ae141f3b649e9d306e5929553"
+  },
   "fact-checker": {
     "version": 6,
     "hash": "6bb22a9e5a5079b5cb287b5b26addbd36b9afeb7c9508287dcad9343fc53d685"
@@ -16,8 +20,8 @@
     "hash": "cef39fed321779631ddd1077fcba53399adf0e48b301df281c71eb042610900d"
   },
   "researcher": {
-    "version": 8,
-    "hash": "0e76efa180c3e443c8856b8787e9643923d10486b373ce078c12dc16eb04611b"
+    "version": 9,
+    "hash": "880047f6a8612d420c77c03d9cc6308a25b2cd6f84647da9df9bae0e22bd5e4d"
   },
   "structural-editor": {
     "version": 4,

apps/client/package.json

@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@ai-sdk/react": "^3.0.208",
+    "@braintree/sanitize-url": "7.1.2",
     "@atlaskit/pragmatic-drag-and-drop": "1.8.1",
     "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "2.1.5",
     "@atlaskit/pragmatic-drag-and-drop-flourish": "2.0.15",
@@ -98,6 +99,7 @@
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.1",
     "vite": "8.0.5",
+    "vite-plugin-compression2": "2.5.3",
     "vitest": "4.1.6"
   }
 }

apps/client/src/App.tsx

@@ -1,38 +1,72 @@
+import { lazy, Suspense } from "react";
 import { Navigate, Route, Routes } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
+import { Error404 } from "@/components/ui/error-404.tsx";
+import Layout from "@/components/layouts/global/layout.tsx";
+import { useTrackOrigin } from "@/hooks/use-track-origin";
+
+// ShareLayout is route-split: its ShareShell chrome pulls in the table of
+// contents (and thus TipTap), so keeping it out of the eager graph removes the
+// editor engine from startup for authenticated users too.
+const ShareLayout = lazy(
+  () => import("@/features/share/components/share-layout.tsx"),
+);
+
+// Auth / entry pages stay eager: they are the first paint for an unauthenticated
+// visitor (e.g. /login) and are already small, so code-splitting them would only
+// add a cold-chunk round trip to the most common cold-start path.
 import SetupWorkspace from "@/pages/auth/setup-workspace.tsx";
 import LoginPage from "@/pages/auth/login";
-import Home from "@/pages/dashboard/home";
-import Page from "@/pages/page/page";
-import AccountSettings from "@/pages/settings/account/account-settings";
-import WorkspaceMembers from "@/pages/settings/workspace/workspace-members";
-import WorkspaceSettings from "@/pages/settings/workspace/workspace-settings";
-import AiSettings from "@/pages/settings/workspace/ai-settings";
-import Groups from "@/pages/settings/group/groups";
-import GroupInfo from "./pages/settings/group/group-info";
-import Spaces from "@/pages/settings/space/spaces.tsx";
-import { Error404 } from "@/components/ui/error-404.tsx";
-import AccountPreferences from "@/pages/settings/account/account-preferences.tsx";
-import SpaceHome from "@/pages/space/space-home.tsx";
-import PageRedirect from "@/pages/page/page-redirect.tsx";
-import Layout from "@/components/layouts/global/layout.tsx";
 import InviteSignup from "@/pages/auth/invite-signup.tsx";
 import ForgotPassword from "@/pages/auth/forgot-password.tsx";
 import PasswordReset from "./pages/auth/password-reset";
-import SharedPage from "@/pages/share/shared-page.tsx";
-import Shares from "@/pages/settings/shares/shares.tsx";
-import ShareLayout from "@/features/share/components/share-layout.tsx";
+import PageRedirect from "@/pages/page/page-redirect.tsx";
 import ShareRedirect from "@/pages/share/share-redirect.tsx";
-import { useTrackOrigin } from "@/hooks/use-track-origin";
-import SpacesPage from "@/pages/spaces/spaces.tsx";
-import SpaceTrash from "@/pages/space/space-trash.tsx";
-import FavoritesPage from "@/pages/favorites/favorites-page";
-import LabelPage from "@/pages/label/label-page";
+
+// Heavy / leaf pages are route-split with React.lazy so their code (most
+// importantly the whole TipTap editor + KaTeX + lowlight grammars + drawio that
+// the page editor and the readonly share editor pull in) is fetched only when
+// the matching route is actually visited. The <Suspense> boundaries live inside
+// each Layout (around its <Outlet/>), so the app shell stays mounted while a
+// route chunk loads.
+const Home = lazy(() => import("@/pages/dashboard/home"));
+const Page = lazy(() => import("@/pages/page/page"));
+const SpaceHome = lazy(() => import("@/pages/space/space-home.tsx"));
+const SpaceTrash = lazy(() => import("@/pages/space/space-trash.tsx"));
+const SpacesPage = lazy(() => import("@/pages/spaces/spaces.tsx"));
+const FavoritesPage = lazy(() => import("@/pages/favorites/favorites-page"));
+const LabelPage = lazy(() => import("@/pages/label/label-page"));
+const SharedPage = lazy(() => import("@/pages/share/shared-page.tsx"));
+
+const AccountSettings = lazy(
+  () => import("@/pages/settings/account/account-settings"),
+);
+const AccountPreferences = lazy(
+  () => import("@/pages/settings/account/account-preferences.tsx"),
+);
+const WorkspaceSettings = lazy(
+  () => import("@/pages/settings/workspace/workspace-settings"),
+);
+const AiSettings = lazy(() => import("@/pages/settings/workspace/ai-settings"));
+const WorkspaceMembers = lazy(
+  () => import("@/pages/settings/workspace/workspace-members"),
+);
+const Groups = lazy(() => import("@/pages/settings/group/groups"));
+const GroupInfo = lazy(() => import("./pages/settings/group/group-info"));
+const Spaces = lazy(() => import("@/pages/settings/space/spaces.tsx"));
+const Shares = lazy(() => import("@/pages/settings/shares/shares.tsx"));
 
 export default function App() {
   useTrackOrigin();
 
   return (
-    <>
+    <Suspense
+      fallback={
+        <Center h="100vh">
+          <Loader size="sm" />
+        </Center>
+      }
+    >
       <Routes>
         <Route index element={<Navigate to="/home" />} />
         <Route path={"/login"} element={<LoginPage />} />
@@ -83,6 +117,6 @@ export default function App() {
 
         <Route path="*" element={<Error404 />} />
       </Routes>
-    </>
+    </Suspense>
   );
 }

apps/client/src/components/chunk-load-error-boundary.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { isChunkLoadError } from "./chunk-load-error-boundary";
+
+// The detector decides whether a caught render error is a stale-deploy chunk-404
+// (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
+// recovery UI, no reload). A false negative on a real chunk failure re-blanks the
+// app; a false positive would auto-reload on an ordinary error. Pin both sides.
+describe("isChunkLoadError", () => {
+  it("detects the ChunkLoadError name", () => {
+    expect(isChunkLoadError({ name: "ChunkLoadError", message: "x" })).toBe(true);
+  });
+
+  it.each([
+    "Failed to fetch dynamically imported module: https://x/assets/index-abc.js",
+    "error loading dynamically imported module",
+    "Importing a module script failed.",
+  ])("detects the dynamic-import failure message %#", (message) => {
+    expect(isChunkLoadError({ name: "TypeError", message })).toBe(true);
+  });
+
+  it("is case-insensitive on the message", () => {
+    expect(
+      isChunkLoadError({ message: "FAILED TO FETCH DYNAMICALLY IMPORTED MODULE" }),
+    ).toBe(true);
+  });
+
+  it.each([
+    null,
+    undefined,
+    {},
+    { name: "TypeError", message: "Cannot read properties of undefined" },
+    { message: "Network request failed" },
+    new Error("some ordinary render error"),
+  ])("returns false for a non-chunk error %#", (err) => {
+    expect(isChunkLoadError(err)).toBe(false);
+  });
+});

apps/client/src/components/chunk-load-error-boundary.tsx

@@ -0,0 +1,71 @@
+import { ReactNode } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { Button, Center, Stack, Text } from "@mantine/core";
+
+const RELOAD_FLAG = "chunk-reload-attempted";
+
+// Heuristic detection of a failed dynamic import. Since the code-splitting work,
+// every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
+// replaces the hashed chunks, a tab left open on the old index.html requests a
+// chunk URL that now 404s, and React.lazy rejects. Browsers / Vite surface these
+// with a ChunkLoadError name or one of these messages.
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false;
+  const name = (error as { name?: string }).name ?? "";
+  const message = (error as { message?: string }).message ?? "";
+  return (
+    name === "ChunkLoadError" ||
+    /Failed to fetch dynamically imported module/i.test(message) ||
+    /error loading dynamically imported module/i.test(message) ||
+    /Importing a module script failed/i.test(message)
+  );
+}
+
+function handleError(error: unknown) {
+  if (!isChunkLoadError(error)) return;
+  // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
+  // the new chunk manifest. Auto-reload once, guarding against a reload loop
+  // (e.g. a genuinely missing chunk) with a one-shot sessionStorage flag. If the
+  // flag is already set we fall through to the manual recovery UI below.
+  try {
+    if (sessionStorage.getItem(RELOAD_FLAG)) return;
+    sessionStorage.setItem(RELOAD_FLAG, "1");
+  } catch {
+    // sessionStorage unavailable (private mode / disabled): skip the automatic
+    // reload rather than risk an unguarded loop; the fallback UI still recovers.
+    return;
+  }
+  window.location.reload();
+}
+
+// Root-level boundary that sits ABOVE every route-level Suspense boundary so a
+// lazy route/component chunk failure is caught here instead of unmounting the
+// whole tree into a blank white screen. Per-feature ErrorBoundaries (page.tsx,
+// transclusion, page-embed) remain in place underneath for their local errors.
+export function ChunkLoadErrorBoundary({ children }: { children: ReactNode }) {
+  return (
+    <ErrorBoundary
+      onError={handleError}
+      fallbackRender={({ error }) => {
+        const chunk = isChunkLoadError(error);
+        return (
+          <Center h="100vh" p="md">
+            <Stack align="center" gap="sm" maw={420}>
+              <Text fw={600}>
+                {chunk ? "A new version is available" : "Something went wrong"}
+              </Text>
+              <Text size="sm" c="dimmed" ta="center">
+                {chunk
+                  ? "Please reload the page to load the latest version."
+                  : "An unexpected error occurred. Reloading the page may help."}
+              </Text>
+              <Button onClick={() => window.location.reload()}>Reload</Button>
+            </Stack>
+          </Center>
+        );
+      }}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}

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

@@ -1,9 +1,10 @@
 import { AppShell, Container } from "@mantine/core";
-import React, { useEffect, useRef, useState } from "react";
+import React, { Suspense, useEffect, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
-import { useAtom } from "jotai";
+import { useAtom, useAtomValue } from "jotai";
+import { aiChatWindowOpenAtom } from "@/features/ai-chat/atoms/ai-chat-atom.ts";
 import {
   APP_NAVBAR_ID,
   NAVBAR_COLLAPSE_BREAKPOINT,
@@ -14,8 +15,6 @@ import {
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
 import { SpaceSidebar } from "@/features/space/components/sidebar/space-sidebar.tsx";
 import { AppHeader } from "@/components/layouts/global/app-header.tsx";
-import Aside from "@/components/layouts/global/aside.tsx";
-import AiChatWindow from "@/features/ai-chat/components/ai-chat-window.tsx";
 import GitmostGlobalBridge from "@/features/editor/gitmost/gitmost-global-bridge.tsx";
 import classes from "./app-shell.module.css";
 import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
@@ -23,6 +22,21 @@ import GlobalSidebar from "@/components/layouts/global/global-sidebar.tsx";
 import { ASIDE_PANEL_ID } from "@/hooks/use-toggle-aside.tsx";
 import { MAIN_CONTENT_ID, SkipToMain } from "@/components/ui/skip-to-main.tsx";
 
+// Lazily load the AI chat window so the AI SDK runtime it pulls in is fetched
+// only after the user first opens the chat, instead of for every authenticated
+// user on load. The window itself renders null while closed, so there is no
+// behavior difference — it simply is not mounted until first opened.
+const AiChatWindow = React.lazy(
+  () => import("@/features/ai-chat/components/ai-chat-window.tsx"),
+);
+
+// The right aside hosts the comment panel and table of contents, both of which
+// pull in TipTap. It only ever renders on page routes, so lazy-loading it keeps
+// the whole editor engine out of the eager global-shell startup graph.
+const Aside = React.lazy(
+  () => import("@/components/layouts/global/aside.tsx"),
+);
+
 export default function GlobalAppShell({
   children,
 }: {
@@ -37,6 +51,15 @@ export default function GlobalAppShell({
   const [isResizing, setIsResizing] = useState(false);
   const sidebarRef = useRef(null);
 
+  // Latch: once the AI chat window has been opened, keep it mounted so an
+  // in-flight stream is never torn down. Before the first open the AI chat chunk
+  // is never fetched.
+  const aiChatOpen = useAtomValue(aiChatWindowOpenAtom);
+  const [aiChatEverOpened, setAiChatEverOpened] = useState(false);
+  useEffect(() => {
+    if (aiChatOpen) setAiChatEverOpened(true);
+  }, [aiChatOpen]);
+
   const startResizing = React.useCallback((mouseDownEvent) => {
     mouseDownEvent.preventDefault();
     setIsResizing(true);
@@ -67,14 +90,20 @@ export default function GlobalAppShell({
   );
 
   useEffect(() => {
-    //https://codesandbox.io/p/sandbox/kz9de
+    // Attach the global mousemove/mouseup only WHILE resizing (started on the
+    // handle's mousedown via startResizing → isResizing=true) and detach on
+    // mouseup (stopResizing → isResizing=false). Previously these listeners were
+    // attached for the whole app lifetime, so every mouse move over the app ran
+    // the resize handler.
+    // https://codesandbox.io/p/sandbox/kz9de
+    if (!isResizing) return;
     window.addEventListener("mousemove", resize);
     window.addEventListener("mouseup", stopResizing);
     return () => {
       window.removeEventListener("mousemove", resize);
       window.removeEventListener("mouseup", stopResizing);
     };
-  }, [resize, stopResizing]);
+  }, [isResizing, resize, stopResizing]);
 
   const location = useLocation();
   const isSettingsRoute = location.pathname.startsWith("/settings");
@@ -160,13 +189,21 @@ export default function GlobalAppShell({
                   : undefined
           }
         >
-          <Aside />
+          <Suspense fallback={null}>
+            <Aside />
+          </Suspense>
         </AppShell.Aside>
       )}
     </AppShell>
-    {/* Floating AI chat window. Mounted once globally; it is position: fixed
-        and self-hides when closed, so its place in the tree is not critical. */}
-    <AiChatWindow />
+    {/* Floating AI chat window. Mounted once globally on first open; it is
+        position: fixed and self-hides when closed, so its place in the tree is
+        not critical. Kept mounted after the first open so a live stream is not
+        aborted. */}
+    {aiChatEverOpened && (
+      <Suspense fallback={null}>
+        <AiChatWindow />
+      </Suspense>
+    )}
       {/* Global gitmost native bridge: registers listSpaces / listPages /
           createPageWithRecording on window.gitmost so the native host can
           create a page with a recording even when no page editor is open. */}

apps/client/src/components/layouts/global/layout.tsx

@@ -1,5 +1,7 @@
+import { Suspense, useEffect } from "react";
 import { UserProvider } from "@/features/user/user-provider.tsx";
 import { Outlet, useParams } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
 import GlobalAppShell from "@/components/layouts/global/global-app-shell.tsx";
 import { SearchSpotlight } from "@/features/search/components/search-spotlight.tsx";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -8,10 +10,39 @@ export default function Layout() {
   const { spaceSlug } = useParams();
   const { data: space } = useGetSpaceBySlugQuery(spaceSlug);
 
+  // Warm the (now route-split) editor chunk during idle time on authenticated
+  // routes, so the first navigation to a page renders from cache instead of a
+  // cold chunk fetch. Best-effort: gated on requestIdleCallback and never blocks
+  // startup — the dynamic import mirrors the App.tsx route lazy loader so both
+  // resolve to the same chunk.
+  useEffect(() => {
+    const ric =
+      typeof window !== "undefined" && (window as any).requestIdleCallback;
+    const warm = () => {
+      // Best-effort prefetch: a failed warm-up (offline, stale 404) is harmless
+      // and must not surface as an unhandledrejection.
+      void import("@/pages/page/page").catch(() => {});
+    };
+    if (ric) {
+      const id = ric(warm);
+      return () => (window as any).cancelIdleCallback?.(id);
+    }
+    const timer = setTimeout(warm, 2000);
+    return () => clearTimeout(timer);
+  }, []);
+
   return (
     <UserProvider>
       <GlobalAppShell>
-        <Outlet />
+        <Suspense
+          fallback={
+            <Center h="60vh">
+              <Loader size="sm" />
+            </Center>
+          }
+        >
+          <Outlet />
+        </Suspense>
       </GlobalAppShell>
       <SearchSpotlight spaceId={space?.id} />
     </UserProvider>

apps/client/src/components/ui/emoji-picker.tsx

@@ -5,7 +5,7 @@ import {
   Button,
   useMantineColorScheme,
 } from "@mantine/core";
-import { useClickOutside, useDisclosure, useWindowEvent } from "@mantine/hooks";
+import { useClickOutside, useDisclosure } from "@mantine/hooks";
 import { Suspense } from "react";
 import { useTranslation } from "react-i18next";
 
@@ -57,14 +57,22 @@ function EmojiPicker({
     [dropdown, target],
   );
 
-  // We need this because the default Mantine popover closeOnEscape does not work
-  useWindowEvent("keydown", (event) => {
-    if (opened && event.key === "Escape") {
-      event.stopPropagation();
-      event.preventDefault();
-      handlers.close();
-    }
-  });
+  // We need this because the default Mantine popover closeOnEscape does not work.
+  // Attach the global keydown ONLY while the picker is open (every tree row
+  // renders an EmojiPicker, so an always-on window listener meant ~20-30 idle
+  // keydown handlers firing on each keystroke).
+  useEffect(() => {
+    if (!opened) return;
+    const handleKeydown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        event.preventDefault();
+        handlers.close();
+      }
+    };
+    window.addEventListener("keydown", handleKeydown);
+    return () => window.removeEventListener("keydown", handleKeydown);
+  }, [opened, handlers]);
 
   // emoji-mart's built-in autoFocus calls .focus() without preventScroll, which
   // makes the browser scroll every scrollable ancestor of the search input to

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

@@ -36,7 +36,7 @@ import {
   desktopSidebarAtom,
   mobileSidebarAtom,
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import {
   pageEditorAtom,
   readOnlyEditorAtom,
@@ -245,7 +245,9 @@ export default function AiChatWindow() {
   // left partly off-screen).
   const [geom, setGeom] = useAtom(aiChatWindowGeomAtom);
 
-  const { data: chats } = useAiChatsQuery();
+  // Gated on windowOpen: the chat list is only needed once the window is open,
+  // so a closed window issues no chat-list request/refetch on navigation.
+  const { data: chats } = useAiChatsQuery(windowOpen);
   // Roles for the new-chat picker (any member may list them). Only fetched while
   // the window is open.
   const { data: roles } = useAiRolesQuery(windowOpen);
@@ -291,6 +293,10 @@ export default function AiChatWindow() {
         Date.now() - lastActivityAtRef.current < DEGRADED_POLL_IDLE_MAX_MS
           ? 2500
           : false,
+      // #344: gate on windowOpen too — no message history is fetched (and no
+      // degraded poll runs) while the window is closed; it loads when the window
+      // opens with an active chat.
+      windowOpen,
     );
 
   // #430: re-stamp the activity clock whenever the polled rows change while the
@@ -336,7 +342,7 @@ export default function AiChatWindow() {
   // reads/writes via its CASL-enforced page tools using the id.
   const pageRouteMatch = useMatch("/s/:spaceSlug/p/:pageSlug");
   const pageSlug = pageRouteMatch?.params?.pageSlug;
-  const { data: openPageData } = usePageQuery({
+  const { data: openPageData } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const openPage = openPageData

apps/client/src/features/ai-chat/queries/ai-chat-query.ts

@@ -53,8 +53,12 @@ export const AI_CHAT_MESSAGES_RQ_KEY = (chatId: string) => [
   chatId,
 ];
 
-/** Paginated list of the current user's chats (auto-loads further pages). */
-export function useAiChatsQuery() {
+/**
+ * Paginated list of the current user's chats (auto-loads further pages).
+ * `enabled` (default true) lets the AI chat window skip fetching while it is
+ * closed — the list is only needed once the window is open.
+ */
+export function useAiChatsQuery(enabled: boolean = true) {
   const query = useInfiniteQuery({
     queryKey: AI_CHATS_RQ_KEY,
     queryFn: ({ pageParam }) => getAiChats({ cursor: pageParam, limit: 50 }),
@@ -63,6 +67,7 @@ export function useAiChatsQuery() {
       lastPage.meta.hasNextPage
         ? (lastPage.meta.nextCursor ?? undefined)
         : undefined,
+    enabled,
   });
 
   const data = useMemo<IPagination<IAiChat> | undefined>(() => {
@@ -93,6 +98,9 @@ export function useAiChatMessagesQuery(
   // follow the detached run to settle. The callback form lives in AiChatWindow;
   // threaded here verbatim so this query owns the polling. Undefined => no poll.
   refetchInterval?: number | false | (() => number | false),
+  // #344: gate the query so a backgrounded/hidden window stops issuing refetches
+  // and duplicating work. Defaults to enabled to preserve existing call-sites.
+  enabled: boolean = true,
 ) {
   const query = useInfiniteQuery({
     queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatId ?? ""),
@@ -103,7 +111,7 @@ export function useAiChatMessagesQuery(
       lastPage.meta.hasNextPage
         ? (lastPage.meta.nextCursor ?? undefined)
         : undefined,
-    enabled: !!chatId,
+    enabled: !!chatId && enabled,
     refetchInterval,
   });
 

apps/client/src/features/comment/components/comment-content-view.test.tsx

@@ -15,6 +15,7 @@ vi.mock("@/features/comment/components/comment-editor", () => ({
 // case renders in isolation.
 vi.mock("@/features/page/queries/page-query.ts", () => ({
   usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
+  usePageMetaQuery: () => ({ data: undefined, isLoading: false, isError: false }),
 }));
 vi.mock("@/features/share/queries/share-query.ts", () => ({
   useSharePageQuery: () => ({ data: undefined }),

apps/client/src/features/comment/components/comment-list-with-tabs.tsx

@@ -22,7 +22,7 @@ import CommentEditor from "@/features/comment/components/comment-editor";
 import CommentActions from "@/features/comment/components/comment-actions";
 import { useFocusWithin } from "@mantine/hooks";
 import { IComment } from "@/features/comment/types/comment.types.ts";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useTranslation } from "react-i18next";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -56,7 +56,7 @@ export function buildChildrenByParent(
 function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
-  const { data: page } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
+  const { data: page } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
   const {
     data: comments,
     isLoading: isCommentsLoading,

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

@@ -1,5 +1,8 @@
 import { atom } from "jotai";
-import { Editor } from "@tiptap/core";
+// Type-only: these atoms only hold an Editor reference for typing. A value
+// import would drag the whole @tiptap/core engine into the eager graph of every
+// shell component that reads one of these atoms.
+import type { Editor } from "@tiptap/core";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 

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

@@ -46,6 +46,13 @@ export function AudioMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes unless an audio node is active. The menu
+      // only shows for an active audio node (shouldShow), so the null state while
+      // inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("audio")) {
+        return null;
+      }
+
       const audioAttrs = ctx.editor.getAttributes("audio");
 
       return {

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

@@ -43,8 +43,15 @@ export function CalloutMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip the per-type isActive() probes unless a callout is
+      // active. The menu only shows for an active callout (shouldShow), so the
+      // null state while inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("callout")) {
+        return null;
+      }
+
       return {
-        isCallout: ctx.editor.isActive("callout"),
+        isCallout: true,
         isInfo: ctx.editor.isActive("callout", { type: "info" }),
         isNote: ctx.editor.isActive("callout", { type: "note" }),
         isSuccess: ctx.editor.isActive("callout", { type: "success" }),

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

@@ -22,6 +22,12 @@ export default function CodeBlockView(props: NodeViewProps) {
   const [isSelected, setIsSelected] = useState(false);
 
   useEffect(() => {
+    // #343 PART 6: `isSelected` only drives the mermaid source's visibility (the
+    // `hidden` prop below). For every non-mermaid code block it is never read,
+    // so skip the per-block `selectionUpdate` listener entirely — otherwise N
+    // code blocks each add a global listener + a setState on every caret move.
+    if (language !== "mermaid") return;
+
     const updateSelection = () => {
       const { state } = editor;
       const { from, to } = state.selection;
@@ -32,11 +38,14 @@ export default function CodeBlockView(props: NodeViewProps) {
       setIsSelected(isNodeSelected);
     };
 
+    // Initialize on attach so switching a block's language to "mermaid" reflects
+    // the current selection immediately (the listener was not running before).
+    updateSelection();
     editor.on("selectionUpdate", updateSelection);
     return () => {
       editor.off("selectionUpdate", updateSelection);
     };
-  }, [editor, getPos(), node.nodeSize]);
+  }, [editor, getPos(), node.nodeSize, language]);
 
   function changeLanguage(language: string) {
     setLanguageValue(language);

apps/client/src/features/editor/components/drawio/drawio-menu-lazy.tsx

@@ -0,0 +1,16 @@
+import { lazy, Suspense } from "react";
+import { EditorMenuProps } from "@/features/editor/components/table/types/types.ts";
+
+// Lazily load the drawio bubble menu so it is split out of the editor chunk and
+// fetched only when an editable editor is mounted (mirrors excalidraw-menu-lazy).
+const DrawioMenu = lazy(
+  () => import("@/features/editor/components/drawio/drawio-menu.tsx"),
+);
+
+export default function DrawioMenuLazy(props: EditorMenuProps) {
+  return (
+    <Suspense fallback={null}>
+      <DrawioMenu {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/drawio/drawio-view-lazy.tsx

@@ -0,0 +1,17 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the drawio node view so the heavy react-drawio embed runtime is
+// split into its own chunk and fetched only when a drawio diagram is actually
+// rendered (mirrors excalidraw-view-lazy).
+const DrawioView = lazy(
+  () => import("@/features/editor/components/drawio/drawio-view.tsx"),
+);
+
+export default function DrawioViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={null}>
+      <DrawioView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.ts

@@ -1,5 +1,7 @@
 import type { Editor } from "@tiptap/react";
 import { useEditorState } from "@tiptap/react";
+import { undoDepth, redoDepth } from "@tiptap/pm/history";
+import { yUndoPluginKey } from "@tiptap/y-tiptap";
 
 export interface ToolbarState {
   isBold: boolean;
@@ -16,14 +18,45 @@ export interface ToolbarState {
   canRedo: boolean;
 }
 
-// Undo/redo come from either StarterKit's history or the Yjs collaboration
-// history extension. During the brief moment a page is rendered with the
-// static editor (mainExtensions only, undoRedo disabled), neither is loaded
-// and editor.can().undo/redo is undefined.
-function safeCan(editor: Editor, command: "undo" | "redo"): boolean {
-  const can = editor.can() as Record<string, unknown>;
-  const fn = can[command];
-  return typeof fn === "function" ? (fn as () => boolean)() : false;
+// Undo/redo availability, computed WITHOUT `editor.can().undo()/.redo()`.
+//
+// `editor.can()` runs the command as a dry-run (building a throwaway state +
+// transaction) — the most expensive work in this selector, and it ran on every
+// keystroke (and every REMOTE keystroke under collaboration). Instead we read
+// the history stack depth directly, which is a cheap plugin-state lookup and
+// mirrors exactly what the undo/redo commands themselves check:
+//
+//  - Collaboration (Yjs): the yjs UndoManager's undo/redo stack lengths — the
+//    same `undoStack.length === 0` / `redoStack.length === 0` guard the
+//    Collaboration extension's undo/redo commands use.
+//  - Plain history (templates / non-collab): prosemirror-history's undoDepth /
+//    redoDepth, which back the UndoRedo extension.
+//
+// When neither history backend is installed (the pre-sync static editor —
+// mainExtensions only, undoRedo disabled), both fall through to 0 -> false,
+// matching the previous `safeCan` behavior.
+function historyAvailability(editor: Editor): {
+  canUndo: boolean;
+  canRedo: boolean;
+} {
+  const state = editor.state;
+
+  // Collaboration history (Yjs) takes precedence when present.
+  const yState = yUndoPluginKey.getState(state) as
+    | { undoManager?: { undoStack: unknown[]; redoStack: unknown[] } }
+    | undefined;
+  if (yState?.undoManager) {
+    return {
+      canUndo: yState.undoManager.undoStack.length > 0,
+      canRedo: yState.undoManager.redoStack.length > 0,
+    };
+  }
+
+  // Plain prosemirror-history (returns 0 when the history plugin is absent).
+  return {
+    canUndo: undoDepth(state) > 0,
+    canRedo: redoDepth(state) > 0,
+  };
 }
 
 export function useToolbarState(editor: Editor | null): ToolbarState | null {
@@ -31,6 +64,7 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
     editor,
     selector: (ctx) => {
       if (!ctx.editor) return null;
+      const { canUndo, canRedo } = historyAvailability(ctx.editor);
       return {
         isBold: ctx.editor.isActive("bold"),
         isItalic: ctx.editor.isActive("italic"),
@@ -42,8 +76,8 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
         isBulletList: ctx.editor.isActive("bulletList"),
         isOrderedList: ctx.editor.isActive("orderedList"),
         isTaskList: ctx.editor.isActive("taskList"),
-        canUndo: safeCan(ctx.editor, "undo"),
-        canRedo: safeCan(ctx.editor, "redo"),
+        canUndo,
+        canRedo,
       };
     },
   });

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

@@ -38,6 +38,14 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip the expensive per-keystroke work (getAttributes + the
+      // alignment isActive() probes) unless an image is actually active. The
+      // menu is only shown when an image is active (see shouldShow), so a null
+      // state while inactive is never rendered — behavior is unchanged.
+      if (!ctx.editor.isActive("image")) {
+        return null;
+      }
+
       const imageAttrs = ctx.editor.getAttributes("image");
 
       return {

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

@@ -24,7 +24,7 @@ import classes from "./link.module.css";
 import { useTranslation } from "react-i18next";
 import { INTERNAL_LINK_REGEX } from "@/lib/constants";
 import { LinkEditorPanel } from "@/features/editor/components/link/link-editor-panel.tsx";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import { buildSharedPageUrl } from "@/features/page/page.utils.ts";
 import { extractPageSlugId } from "@/lib";
@@ -83,7 +83,7 @@ export default function LinkView(props: MarkViewProps) {
   const isPopoverVisible = popoverState !== "closed";
   const activeView = isPopoverVisible ? popoverState : lastOpenState.current;
 
-  const { data: linkedPage } = usePageQuery({
+  const { data: linkedPage } = usePageMetaQuery({
     pageId: isPopoverVisible && slugId && !isShareRoute ? slugId : null,
   });
 

apps/client/src/features/editor/components/math/math-block-lazy.tsx

@@ -0,0 +1,19 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the KaTeX-backed block math view so the katex chunk is fetched
+// only when a document actually contains a math node (mirrors the mermaid/
+// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
+// crashing or blocking the whole editor: while it loads we render the raw
+// LaTeX source as a node-sized placeholder.
+const MathBlockView = lazy(
+  () => import("@/features/editor/components/math/math-block.tsx"),
+);
+
+export default function MathBlockViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={<div data-katex="true">{props.node.attrs.text}</div>}>
+      <MathBlockView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/math/math-inline-lazy.tsx

@@ -0,0 +1,19 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the KaTeX-backed inline math view so the katex chunk is fetched
+// only when a document actually contains a math node (mirrors the mermaid/
+// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
+// crashing or blocking the whole editor: while it loads we render the raw
+// LaTeX source as a node-sized placeholder.
+const MathInlineView = lazy(
+  () => import("@/features/editor/components/math/math-inline.tsx"),
+);
+
+export default function MathInlineViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={<span data-katex="true">{props.node.attrs.text}</span>}>
+      <MathInlineView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/mention/mention-list.tsx

@@ -25,7 +25,7 @@ import { IconFileDescription, IconPlus } from "@tabler/icons-react";
 import { useSpaceQuery } from "@/features/space/queries/space-query.ts";
 import { useParams } from "react-router-dom";
 import { v7 as uuid7 } from "uuid";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom, useStore } from "jotai";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import {
   MentionListProps,
@@ -34,7 +34,7 @@ import {
 import { IPage } from "@/features/page/types/page.types";
 import {
   useCreatePageMutation,
-  usePageQuery,
+  usePageMetaQuery,
 } from "@/features/page/queries/page-query";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom";
 import { treeModel } from "@/features/page/tree/model/tree-model";
@@ -50,12 +50,16 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
   const [countAnnouncement, setCountAnnouncement] = useState("");
   const [selectionAnnouncement, setSelectionAnnouncement] = useState("");
   const { pageSlug, spaceSlug } = useParams();
-  const { data: page } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
+  const { data: page } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
   const { data: space } = useSpaceQuery(spaceSlug);
   const [currentUser] = useAtom(currentUserAtom);
   const [renderItems, setRenderItems] = useState<MentionSuggestionItem[]>([]);
   const { t } = useTranslation();
-  const [data, setData] = useAtom(treeDataAtom);
+  // Setter-only: the tree value is read only imperatively inside createPage
+  // (via `store` below), never at render, so useSetAtom avoids re-rendering the
+  // mention popup on any tree event.
+  const setData = useSetAtom(treeDataAtom);
+  const store = useStore();
   const createPageMutation = useCreatePageMutation();
   const emit = useQueryEmit();
   const isInCommentContext = props.isInCommentContext ?? false;
@@ -272,9 +276,11 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
         children: [],
       };
 
-      const lastIndex = data.length;
+      // Read the live tree imperatively at call time.
+      const currentTree = store.get(treeDataAtom);
+      const lastIndex = currentTree.length;
 
-      setData(treeModel.insert(data, parentId, newNode, lastIndex));
+      setData(treeModel.insert(currentTree, parentId, newNode, lastIndex));
 
       props.command({
         id: uuid7(),

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

@@ -2,7 +2,7 @@ import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { ActionIcon, Anchor, Text } from "@mantine/core";
 import { IconFileDescription } from "@tabler/icons-react";
 import { Link, useLocation, useNavigate, useParams } from "react-router-dom";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import {
   buildPageUrl,
@@ -36,7 +36,7 @@ export function MentionContent({ attrs }: { attrs: MentionAttrs }) {
     data: page,
     isLoading,
     isError,
-  } = usePageQuery({ pageId: isPageMention && !isShareRoute ? slugId : null });
+  } = usePageMetaQuery({ pageId: isPageMention && !isShareRoute ? slugId : null });
 
   const { data: sharedPage } = useSharePageQuery({
     pageId: isPageMention && isShareRoute ? slugId : undefined,

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

@@ -25,6 +25,13 @@ export function PdfMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes unless a pdf node is active. The menu
+      // only shows for an active pdf node (shouldShow), so the null state while
+      // inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("pdf")) {
+        return null;
+      }
+
       const pdfAttrs = ctx.editor.getAttributes("pdf");
 
       return {

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

@@ -70,7 +70,14 @@ export const SubpagesMenu = React.memo(
     // toggle without re-rendering on every keystroke.
     const isRecursive = useEditorState({
       editor,
-      selector: (ctx) => ctx.editor?.getAttributes("subpages")?.recursive ?? false,
+      // #343 PART 1: skip getAttributes unless a subpages node is active. The
+      // menu only shows for an active subpages node (shouldShow), so the value
+      // is only read then; getAttributes on an inactive node returns the default
+      // (recursive === false) anyway, so this is behavior-preserving.
+      selector: (ctx) =>
+        ctx.editor?.isActive("subpages")
+          ? (ctx.editor.getAttributes("subpages")?.recursive ?? false)
+          : false,
     });
 
     return (

apps/client/src/features/editor/components/table-of-contents/table-of-contents.tsx

@@ -4,6 +4,7 @@ import React, { FC, useEffect, useRef, useState } from "react";
 import classes from "./table-of-contents.module.css";
 import clsx from "clsx";
 import { Box, Text, Title } from "@mantine/core";
+import { useDebouncedCallback } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
 
 type TableOfContentsProps = {
@@ -79,13 +80,21 @@ export const TableOfContents: FC<TableOfContentsProps> = (props) => {
     setHeadingDOMNodes(result.nodes);
   };
 
+  // Debounce the update-driven rescan: `$nodes("heading")` scans every heading
+  // in the document, and it previously ran on EVERY keystroke while the TOC
+  // panel was open. The panel is derived UI, so recomputing ~300ms after typing
+  // settles keeps it correct without doing an all-headings scan per keystroke
+  // (#343, PART 7). `useDebouncedCallback` returns a stable reference and always
+  // invokes the latest `handleUpdate`.
+  const debouncedHandleUpdate = useDebouncedCallback(handleUpdate, 300);
+
   useEffect(() => {
-    props.editor?.on("update", handleUpdate);
+    props.editor?.on("update", debouncedHandleUpdate);
 
     return () => {
-      props.editor?.off("update", handleUpdate);
+      props.editor?.off("update", debouncedHandleUpdate);
     };
-  }, [props.editor]);
+  }, [props.editor, debouncedHandleUpdate]);
 
   useEffect(
     () => {

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

@@ -31,6 +31,13 @@ export function VideoMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes + alignment isActive() probes unless a
+      // video is active. The menu only shows for an active video (shouldShow),
+      // so the null state while inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("video")) {
+        return null;
+      }
+
       const videoAttrs = ctx.editor.getAttributes("video");
 
       return {

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

@@ -81,8 +81,8 @@ import {
   createResizeHandle,
   buildResizeClasses,
 } from "@/features/editor/components/common/node-resize-handles.ts";
-import MathInlineView from "@/features/editor/components/math/math-inline.tsx";
-import MathBlockView from "@/features/editor/components/math/math-block.tsx";
+import MathInlineView from "@/features/editor/components/math/math-inline-lazy.tsx";
+import MathBlockView from "@/features/editor/components/math/math-block-lazy.tsx";
 import ImageView from "@/features/editor/components/image/image-view.tsx";
 import CalloutView from "@/features/editor/components/callout/callout-view.tsx";
 import StatusView from "@/features/editor/components/status/status-view.tsx";
@@ -90,7 +90,7 @@ import VideoView from "@/features/editor/components/video/video-view.tsx";
 import AudioView from "@/features/editor/components/audio/audio-view.tsx";
 import AttachmentView from "@/features/editor/components/attachment/attachment-view.tsx";
 import CodeBlockView from "@/features/editor/components/code-block/code-block-view.tsx";
-import DrawioView from "../components/drawio/drawio-view";
+import DrawioView from "../components/drawio/drawio-view-lazy.tsx";
 import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-view-lazy.tsx";
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import HtmlEmbedView from "@/features/editor/components/html-embed/html-embed-view.tsx";

apps/client/src/features/editor/extensions/slash-command.ts

@@ -6,6 +6,23 @@ import getSuggestionItems from '@/features/editor/components/slash-menu/menu-ite
 
 export const slashMenuPluginKey = new PluginKey('slash-command');
 
+// getSuggestionItems fuzzy-matches EVERY command against the query (plus its
+// wrong-keyboard-layout remaps) and, while the slash menu is open, is invoked
+// TWICE per keystroke: once by the synchronous `allow` gate below and once by
+// the popup's `items` builder. A synchronous gating predicate can't be
+// debounced without breaking the suggestion decoration/activation, so instead we
+// memoize the LAST query's result: the two same-query calls in one keystroke
+// build the list only once, and the cache invalidates the moment the query
+// changes — so there is no stale-state risk (#343, PART 7).
+let lastQuery: string | null = null;
+let lastResult: ReturnType<typeof getSuggestionItems> | null = null;
+function suggestionItemsForQuery(query: string) {
+  if (query === lastQuery && lastResult) return lastResult;
+  lastQuery = query;
+  lastResult = getSuggestionItems({ query });
+  return lastResult;
+}
+
 // @ts-ignore
 const Command = Extension.create({
   name: 'slash-command',
@@ -38,7 +55,7 @@ const Command = Extension.create({
           // non-matching queries while keeping multi-word matches (e.g.
           // "/Heading 1") working.
           const query = state.doc.textBetween(range.from + 1, range.to);
-          const groups = getSuggestionItems({ query });
+          const groups = suggestionItemsForQuery(query);
           const hasMatches = Object.values(groups).some(
             (items) => items.length > 0,
           );
@@ -61,7 +78,9 @@ const Command = Extension.create({
 
 const SlashCommand = Command.configure({
   suggestion: {
-    items: getSuggestionItems,
+    // Share the per-query memo with `allow` so the pair of same-query calls in a
+    // single keystroke rebuilds the list once (#343, PART 7).
+    items: ({ query }: { query: string }) => suggestionItemsForQuery(query),
     render: renderItems,
   },
 });

apps/client/src/features/editor/gitmost/gitmost-global-bridge.tsx

@@ -1,8 +1,17 @@
 import { useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
 import { getDefaultStore } from "jotai";
-import { WebSocketStatus } from "@hocuspocus/provider";
-import { Editor } from "@tiptap/core";
+
+// Literal value of WebSocketStatus.Connected from @hocuspocus/provider. Inlined
+// so this always-mounted global bridge does not statically import
+// @hocuspocus/provider — that import pulls Yjs (and, through a shared chunk, the
+// whole TipTap engine) into the eager startup graph. yjsConnectionStatusAtom
+// already stores these raw status strings.
+const YJS_STATUS_CONNECTED = "connected";
+// Type-only: importing Editor as a type keeps @tiptap/core (the whole editor
+// engine) out of the eager global-shell graph — the bridge only uses it for
+// annotations/casts, never as a runtime value.
+import type { Editor } from "@tiptap/core";
 import {
   pageEditorAtom,
   yjsConnectionStatusAtom,
@@ -16,16 +25,19 @@ import {
   getSidebarPages,
 } from "@/features/page/services/page-service.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
-import {
+// Types are erased at build time, so importing them does not pull the module's
+// runtime (which drags in @tiptap + the editor-ext barrel). The actual recording
+// helpers are dynamically imported at call time inside createPageWithRecording,
+// keeping the editor engine out of the eager global-shell startup graph — the
+// bridge is mounted for every authenticated user but recording is a rare,
+// native-host-driven action.
+import type {
   GitmostBridge,
   GitmostCreatePagePayload,
   GitmostCreatePageResult,
   GitmostListPagesPayload,
   GitmostListPagesResult,
   GitmostListSpacesResult,
-  gitmostDecodePayloadToFile,
-  gitmostInsertTranscriptIntoEditor,
-  gitmostUploadFileToEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
 
 // How long to wait for a freshly-navigated page's editor to mount, become
@@ -58,7 +70,7 @@ function gitmostWaitForEditor(
         !editor.isDestroyed &&
         editor.isEditable &&
         editorPageId === pageId &&
-        yjsStatus === WebSocketStatus.Connected;
+        yjsStatus === YJS_STATUS_CONNECTED;
       if (ready) {
         resolve(editor);
         return;
@@ -172,6 +184,15 @@ export default function GitmostGlobalBridge() {
           };
         }
 
+        // Load the recording helpers on demand (see the import note above). This
+        // is the only place they are needed, so the @tiptap/editor-ext code they
+        // pull in stays out of the eager startup graph.
+        const {
+          gitmostDecodePayloadToFile,
+          gitmostUploadFileToEditor,
+          gitmostInsertTranscriptIntoEditor,
+        } = await import("@/features/editor/gitmost/gitmost-recording.ts");
+
         // Validate/decode the recording BEFORE creating the page so a bad
         // payload never leaves an empty junk page behind. Per the createPage
         // error contract, any decode failure collapses to "insert-failed" (the

apps/client/src/features/editor/hooks/use-page-content-cache.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { MutableRefObject } from "react";
+import type { Editor } from "@tiptap/react";
+
+// Mock the app entry so importing the hook doesn't boot the whole app; the hook
+// only needs queryClient's cache read/write, which we stub here. Declared via
+// vi.hoisted so the spies exist before the hoisted vi.mock factory runs.
+const { getQueryData, setQueryData } = vi.hoisted(() => ({
+  getQueryData: vi.fn(() => undefined as unknown),
+  setQueryData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData, setQueryData },
+}));
+
+import { usePageContentCache } from "./use-page-content-cache";
+
+const SNAPSHOT = { type: "doc", content: [] };
+
+function makeFakeEditor(overrides: Partial<Editor> = {}): Editor {
+  return {
+    isEmpty: false,
+    isDestroyed: false,
+    getJSON: vi.fn(() => SNAPSHOT),
+    ...overrides,
+  } as unknown as Editor;
+}
+
+describe("usePageContentCache (#343 PART 3) — getJSON off the keystroke path", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    // A cached page exists so the write path runs.
+    getQueryData.mockReturnValue({ id: "p1", content: {} });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("onUpdate (calling the debounced fn) does NOT call getJSON synchronously", () => {
+    const editor = makeFakeEditor();
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    // Simulate a keystroke's onUpdate -> only schedules the debounce.
+    act(() => {
+      result.current();
+      result.current();
+      result.current();
+    });
+
+    // The whole-doc serialization must NOT have happened yet.
+    expect(editor.getJSON).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+
+    // Once the debounce window elapses, getJSON runs exactly once (not per call).
+    act(() => vi.advanceTimersByTime(3000));
+    expect(editor.getJSON).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledWith(["pages", "slug-1"], {
+      id: "p1",
+      content: SNAPSHOT,
+    });
+  });
+
+  it("flushes the pending snapshot on unmount so the last edit isn't lost", () => {
+    const editor = makeFakeEditor();
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result, unmount } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    act(() => result.current());
+    expect(editor.getJSON).not.toHaveBeenCalled();
+
+    // Navigation/unmount must flush (not drop) the pending write.
+    act(() => unmount());
+    expect(editor.getJSON).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips the write when the editor is destroyed (flush racing teardown)", () => {
+    const editor = makeFakeEditor({ isDestroyed: true });
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    act(() => result.current());
+    act(() => vi.advanceTimersByTime(3000));
+
+    expect(editor.getJSON).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/hooks/use-page-content-cache.ts

@@ -0,0 +1,50 @@
+import type { MutableRefObject } from "react";
+import { useDebouncedCallback } from "@mantine/hooks";
+import type { Editor } from "@tiptap/react";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
+
+/**
+ * Off-keystroke local page-cache updater (issue #343, PART 3).
+ *
+ * The editor's `onUpdate` fires on every keystroke — and, under collaboration,
+ * on every REMOTE keystroke too. Serializing the WHOLE document with
+ * `editor.getJSON()` on that hot path is expensive, and the previous 3s debounce
+ * only guarded the cache WRITE, not the serialization: `getJSON()` still ran per
+ * keystroke.
+ *
+ * This hook moves the serialization INSIDE the debounced callback, so the
+ * full-doc traversal happens at most once per `delay`, not per keystroke. Call
+ * the returned function from `onUpdate` (it only schedules the debounce); the
+ * `getJSON()` snapshot is taken when the debounce fires.
+ *
+ * On unmount/navigation the pending snapshot is FLUSHED (via `flushOnUnmount`)
+ * so the last edits within the debounce window aren't lost from the local cache.
+ * The source of truth is collab/Yjs, but the cache must not go stale.
+ *
+ * IMPORTANT: call this hook BEFORE `useEditor`. React runs effect cleanups in
+ * declaration order on unmount, so the debounce's flush cleanup must be declared
+ * before `useEditor`'s teardown to run while the editor is still alive; the
+ * `isDestroyed` guard keeps a flush that still races teardown safe (it skips).
+ */
+export function usePageContentCache(
+  editorRef: MutableRefObject<Editor | null>,
+  slugId: string | undefined,
+  delay = 3000,
+) {
+  return useDebouncedCallback(
+    () => {
+      const e = editorRef.current;
+      if (!e || e.isDestroyed || e.isEmpty) return;
+      const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
+      if (pageData) {
+        // getJSON() (full-doc serialization) runs HERE, off the keystroke path.
+        queryClient.setQueryData(["pages", slugId], {
+          ...pageData,
+          content: e.getJSON(),
+        });
+      }
+    },
+    { delay, flushOnUnmount: true },
+  );
+}

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

@@ -59,10 +59,10 @@ import {
   handlePaste,
 } 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 DrawioMenu from "./components/drawio/drawio-menu-lazy";
 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 { 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";
@@ -79,6 +79,7 @@ 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 { usePageContentCache } from "./hooks/use-page-content-cache";
 import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
 import { useSwapHeightReservation } from "./hooks/use-swap-height-reservation";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
@@ -272,8 +273,13 @@ export default function PageEditor({
     }
   }, [isIdle, documentState, providersReady, resetIdle]);
 
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  // Attach the remote provider once it's ready (and again after a pageId swap
+  // recreates it) to make sure the connection gets properly established. This
+  // used to run in the render body — a side effect during render (#343, PART 7).
+  // `attach()` is idempotent, so re-running it on these deps is safe.
+  useEffect(() => {
+    providersRef.current?.remote.attach();
+  }, [providersReady, pageId]);
 
   const extensions = useMemo(() => {
     if (!providersReady || !providersRef.current || !currentUser?.user) {
@@ -288,6 +294,12 @@ export default function PageEditor({
     ];
   }, [providersReady, currentUser?.user]);
 
+  // getJSON() serialization + cache write live in the hook, off the keystroke
+  // path, and flush on unmount so the last snapshot survives navigation (#343).
+  // MUST be declared before useEditor: React runs effect cleanups in declaration
+  // order on unmount, so the flush must run before the editor is torn down.
+  const debouncedUpdateContent = usePageContentCache(editorRef, slugId);
+
   const editor = useEditor(
     {
       extensions,
@@ -392,11 +404,11 @@ export default function PageEditor({
           }
         }
       },
-      onUpdate({ editor }) {
-        if (editor.isEmpty) return;
-        const editorJson = editor.getJSON();
-        //update local page cache to reduce flickers
-        debouncedUpdateContent(editorJson);
+      onUpdate() {
+        // Only schedule the debounce here — the whole-doc getJSON() serialization
+        // happens INSIDE the debounced callback (see usePageContentCache), so it
+        // no longer runs synchronously on every (local or remote) keystroke.
+        debouncedUpdateContent();
       },
     },
     [pageId, editable, extensions],
@@ -442,17 +454,6 @@ export default function PageEditor({
     };
   }, [editor, pageId, editorIsEditable]);
 
-  const debouncedUpdateContent = useDebouncedCallback((newContent: any) => {
-    const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-
-    if (pageData) {
-      queryClient.setQueryData(["pages", slugId], {
-        ...pageData,
-        content: newContent,
-      });
-    }
-  }, 3000);
-
   const handleActiveCommentEvent = (event) => {
     const { commentId, resolved } = event.detail;
 

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

@@ -24,7 +24,6 @@ export function useFavoritesQuery(type?: FavoriteType, spaceId?: string) {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
-    refetchOnMount: true,
   });
 }
 
@@ -32,7 +31,6 @@ export function useFavoriteIds(type: FavoriteType, spaceId?: string): Set<string
   const { data } = useQuery({
     queryKey: ["favorite-ids", type, spaceId],
     queryFn: () => getFavoriteIds(type, spaceId),
-    refetchOnMount: true,
   });
 
   const items = data?.items;

apps/client/src/features/page-details/components/page-details-aside.tsx

@@ -12,7 +12,7 @@ import { useAtomValue } from "jotai";
 import { useParams } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { extractPageSlugId } from "@/lib";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { useBacklinksCountQuery } from "@/features/page-details/queries/backlinks-query.ts";
 import { BacklinksModal } from "./backlinks-modal";
@@ -23,7 +23,7 @@ import { LabelsSection } from "@/features/label/components/labels-section.tsx";
 
 export function PageDetailsAside() {
   const { pageSlug } = useParams();
-  const { data: page } = usePageQuery({
+  const { data: page } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const pageEditor = useAtomValue(pageEditorAtom);

apps/client/src/features/page/components/breadcrumbs/breadcrumb-path-equal.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from "vitest";
+import { SpaceTreeNode } from "@/features/page/tree/types";
+
+// breadcrumb.tsx transitively imports @/main.tsx (via usePageMetaQuery ->
+// queryClient), whose module body calls ReactDOM.createRoot on a null root in
+// jsdom. Stub it so importing the pure helper under test doesn't run that
+// (breadcrumbPathEqual does not use queryClient, so a dummy is enough).
+vi.mock("@/main.tsx", () => ({ queryClient: {} }));
+
+import { breadcrumbPathEqual } from "./breadcrumb";
+
+// breadcrumbPathEqual is the ONLY point where a false-positive equality would
+// leave a stale/incorrect breadcrumb trail on screen: it decides whether the
+// selectAtom hands back the same reference (no re-render) for the ancestor chain.
+// Pin both directions — a too-loose equality goes stale on a rename; a too-tight
+// one loses the perf win.
+const node = (over: Partial<SpaceTreeNode>): SpaceTreeNode =>
+  ({ id: "a", slugId: "sa", name: "A", icon: "📄", ...over }) as SpaceTreeNode;
+
+describe("breadcrumbPathEqual", () => {
+  it("both null → true", () => {
+    expect(breadcrumbPathEqual(null, null)).toBe(true);
+  });
+
+  it("same reference → true", () => {
+    const p = [node({})];
+    expect(breadcrumbPathEqual(p, p)).toBe(true);
+  });
+
+  it("equal by id/slugId/name/icon (different arrays) → true", () => {
+    expect(breadcrumbPathEqual([node({})], [node({})])).toBe(true);
+  });
+
+  it("one side null → false", () => {
+    expect(breadcrumbPathEqual([node({})], null)).toBe(false);
+    expect(breadcrumbPathEqual(null, [node({})])).toBe(false);
+  });
+
+  it("different length → false", () => {
+    expect(
+      breadcrumbPathEqual([node({})], [node({}), node({ id: "b" })]),
+    ).toBe(false);
+  });
+
+  it.each(["name", "icon", "slugId", "id"] as const)(
+    "a changed %s → false (breadcrumb must re-render)",
+    (field) => {
+      expect(
+        breadcrumbPathEqual([node({})], [node({ [field]: "CHANGED" })]),
+      ).toBe(false);
+    },
+  );
+});

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

@@ -1,7 +1,9 @@
 import { useAtomValue } from "jotai";
+import { selectAtom } from "jotai/utils";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
-import React, { useCallback, useEffect, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { computeBreadcrumbState } from "./breadcrumb.utils";
+import { findBreadcrumbPath } from "@/features/page/tree/utils";
 import {
   Button,
   Anchor,
@@ -18,7 +20,7 @@ import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import {
-  usePageQuery,
+  usePageMetaQuery,
   usePageBreadcrumbsQuery,
 } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
@@ -32,39 +34,84 @@ function getTitle(name: string, icon: string) {
   return name;
 }
 
+/**
+ * Equality over a breadcrumb chain by the only fields the breadcrumb renders
+ * (id, slugId, name, icon). Lets the selectAtom below hand back the SAME
+ * reference when an unrelated tree mutation leaves THIS page's ancestor chain
+ * visually unchanged, so the breadcrumb no longer re-renders on every tree
+ * event (it previously subscribed to the whole treeDataAtom).
+ */
+export function breadcrumbPathEqual(
+  a: SpaceTreeNode[] | null,
+  b: SpaceTreeNode[] | null,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (
+      a[i].id !== b[i].id ||
+      a[i].slugId !== b[i].slugId ||
+      a[i].name !== b[i].name ||
+      a[i].icon !== b[i].icon
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export default function Breadcrumb() {
   const { t } = useTranslation();
-  const treeData = useAtomValue(treeDataAtom);
   const [breadcrumbNodes, setBreadcrumbNodes] = useState<
     SpaceTreeNode[] | null
   >(null);
   const { pageSlug, spaceSlug } = useParams();
-  const { data: currentPage } = usePageQuery({
+  const { data: currentPage } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
+  const currentPageId = currentPage?.id;
   // The page's own ancestor chain, fetched independently of the lazily-built
   // sidebar tree so a deep page doesn't render a blank breadcrumb for seconds
   // while the tree backfills (#218).
-  const { data: ancestors } = usePageBreadcrumbsQuery(currentPage?.id);
+  const { data: ancestors } = usePageBreadcrumbsQuery(currentPageId);
   const isMobile = useMediaQuery("(max-width: 48em)");
 
+  // Narrowed subscription: instead of subscribing to the whole treeDataAtom and
+  // recomputing on every tree event, derive ONLY the current page's ancestor
+  // chain. The custom equality returns the previous reference when that chain is
+  // visually unchanged, so an unrelated tree mutation no longer re-renders this
+  // component. Mirrors computeBreadcrumbState's tree-hit branch
+  // (findBreadcrumbPath); the tree-miss/ancestors fallback is applied below.
+  const treePathAtom = useMemo(
+    () =>
+      selectAtom(
+        treeDataAtom,
+        (tree): SpaceTreeNode[] | null =>
+          currentPageId ? findBreadcrumbPath(tree, currentPageId) : null,
+        breadcrumbPathEqual,
+      ),
+    [currentPageId],
+  );
+  const treePath = useAtomValue(treePathAtom);
+
   useEffect(() => {
     if (!currentPage) return;
 
     // Selection/mapping + stale-clearing live in a pure, unit-tested helper
-    // (#218). It resolves the correct chain when possible and, on a transient
-    // miss, clears a chain left over from a previously-viewed page instead of
-    // showing the wrong trail — while keeping a chain already resolved for THIS
-    // page to avoid a blank flash.
+    // (#218). The tree-hit chain (treePath) always wins when present; otherwise
+    // fall back to the page's own ancestors and the stale-clearing logic — this
+    // reproduces computeBreadcrumbState(fullTree, ancestors, …) exactly, since
+    // its tree-hit branch is precisely findBreadcrumbPath(fullTree, pageId).
     setBreadcrumbNodes((previous) =>
+      treePath ??
       computeBreadcrumbState(
-        treeData,
+        null,
         ancestors as IPage[] | undefined,
         currentPage.id,
         previous,
       ),
     );
-  }, [currentPage?.id, treeData, ancestors]);
+  }, [currentPage?.id, treePath, ancestors]);
 
   const HiddenNodesTooltipContent = () =>
     breadcrumbNodes?.slice(1, -1).map((node) => (

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

@@ -24,7 +24,7 @@ import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
 import { useDisclosure, useHotkeys } from "@mantine/hooks";
 import { useClipboard } from "@/hooks/use-clipboard";
 import { useParams } from "react-router-dom";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import {
   useToggleTemporaryMutation,
   syncTemporaryExpiresInCache,
@@ -67,7 +67,7 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
   const commentsTriggerProps = useAsideTriggerProps("comments");
   const tocTriggerProps = useAsideTriggerProps("toc");
   const { pageSlug } = useParams();
-  const { data: page } = usePageQuery({
+  const { data: page } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const isDeleted = !!page?.deletedAt;
@@ -146,7 +146,7 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
   const [, setHistoryModalOpen] = useAtom(historyAtoms);
   const clipboard = useClipboard({ timeout: 500 });
   const { pageSlug, spaceSlug } = useParams();
-  const { data: page, isLoading } = usePageQuery({
+  const { data: page, isLoading } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const { handleDelete } = useTreeMutation(page?.spaceId ?? "");

apps/client/src/features/page/components/temporary-note-banner.tsx

@@ -10,7 +10,7 @@ import { IconClockHour4, IconTrash } from "@tabler/icons-react";
 import { useState } from "react";
 import { Trans, useTranslation } from "react-i18next";
 import { useTimeAgo } from "@/hooks/use-time-ago.tsx";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
 import {
   useToggleTemporaryMutation,
@@ -35,7 +35,7 @@ type TemporaryNoteBannerProps = {
  */
 export function TemporaryNoteBanner({ slugId }: TemporaryNoteBannerProps) {
   const { t } = useTranslation();
-  const { data: page } = usePageQuery({ pageId: slugId });
+  const { data: page } = usePageMetaQuery({ pageId: slugId });
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
   const spaceAbility = useSpaceAbility(space?.membership?.permissions);
   const expiresTimeAgo = useTimeAgo(page?.temporaryExpiresAt);

apps/client/src/features/page/queries/invalidate-on-update-page.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import type { IPage } from "@/features/page/types/page.types";
+
+// A fresh QueryClient stands in for the app singleton (importing the real
+// @/main.tsx would run ReactDOM.createRoot, which has no DOM root in jsdom). The
+// factory constructs it (QueryClient can't be referenced in vi.hoisted — that
+// runs before imports resolve); we import the SAME mocked instance back to seed
+// and assert on it.
+vi.mock("@/main.tsx", async () => {
+  const { QueryClient } = await import("@tanstack/react-query");
+  return { queryClient: new QueryClient() };
+});
+
+import { queryClient as h_qc } from "@/main.tsx";
+import { invalidateOnUpdatePage } from "./page-query";
+
+const h = { qc: h_qc };
+
+// invalidateOnUpdatePage is the field-only (title/icon) tree path: instead of a
+// blanket invalidate it patches the affected node IN PLACE in every cached embed
+// subtree. The undefined-guard is LOAD-BEARING: a title-only socket event carries
+// icon:undefined, and without the guard `{...p, icon: undefined}` would WIPE the
+// icon in every cached subtree.
+const page = (over: Partial<IPage>): IPage =>
+  ({ id: "p1", title: "Old", icon: "📄", spaceId: "s1" }) as IPage &
+    typeof over as IPage;
+
+describe("invalidateOnUpdatePage — pointwise embed-cache patch", () => {
+  beforeEach(() => {
+    h.qc.clear();
+  });
+
+  it("title-only event updates title but PRESERVES the icon (undefined-guard)", () => {
+    const key = ["page-tree", "parent-1"];
+    h.qc.setQueryData<IPage[]>(key, [
+      { id: "p1", title: "Old", icon: "📄", spaceId: "s1" } as IPage,
+      { id: "p2", title: "Other", icon: "📁", spaceId: "s1" } as IPage,
+    ]);
+
+    // icon passed as undefined (a title-only update)
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      "New Title",
+      undefined as unknown as string,
+    );
+
+    const patched = h.qc.getQueryData<IPage[]>(key)!;
+    const p1 = patched.find((p) => p.id === "p1")!;
+    const p2 = patched.find((p) => p.id === "p2")!;
+    expect(p1.title).toBe("New Title");
+    expect(p1.icon).toBe("📄"); // preserved, not wiped
+    // Sibling node untouched.
+    expect(p2.title).toBe("Other");
+    expect(p2.icon).toBe("📁");
+  });
+
+  it("icon-only event updates icon but preserves the title", () => {
+    const key = ["page-tree", "parent-1"];
+    h.qc.setQueryData<IPage[]>(key, [
+      { id: "p1", title: "Keep", icon: "📄", spaceId: "s1" } as IPage,
+    ]);
+
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      undefined as unknown as string,
+      "🚀",
+    );
+
+    const p1 = h.qc.getQueryData<IPage[]>(key)!.find((p) => p.id === "p1")!;
+    expect(p1.icon).toBe("🚀");
+    expect(p1.title).toBe("Keep");
+  });
+
+  // The sidebar-pages cache (InfiniteData) is patched on the same event. It must
+  // carry the SAME undefined-guard as the embed path above — otherwise a
+  // title-only event's icon:undefined would wipe the sidebar entry's icon.
+  const sidebarKey = ["sidebar-pages", { pageId: "parent-1", spaceId: "s1" }];
+  const seedSidebar = () =>
+    h.qc.setQueryData(sidebarKey, {
+      pageParams: [undefined],
+      pages: [
+        {
+          items: [
+            { id: "p1", title: "Old", icon: "📄", spaceId: "s1" } as IPage,
+            { id: "p2", title: "Other", icon: "📁", spaceId: "s1" } as IPage,
+          ],
+        },
+      ],
+    });
+  const sidebarItem = (id: string) => {
+    const data = h.qc.getQueryData(sidebarKey) as {
+      pages: { items: IPage[] }[];
+    };
+    return data.pages[0].items.find((p) => p.id === id)!;
+  };
+
+  it("sidebar cache: title-only event updates title but PRESERVES the icon", () => {
+    seedSidebar();
+
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      "New Title",
+      undefined as unknown as string,
+    );
+
+    const p1 = sidebarItem("p1");
+    expect(p1.title).toBe("New Title");
+    expect(p1.icon).toBe("📄"); // preserved, not wiped
+    // Sibling untouched.
+    const p2 = sidebarItem("p2");
+    expect(p2.title).toBe("Other");
+    expect(p2.icon).toBe("📁");
+  });
+
+  it("sidebar cache: icon-only event updates icon but PRESERVES the title", () => {
+    seedSidebar();
+
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      undefined as unknown as string,
+      "🚀",
+    );
+
+    const p1 = sidebarItem("p1");
+    expect(p1.icon).toBe("🚀");
+    expect(p1.title).toBe("Old"); // preserved, not wiped
+  });
+
+  it("does not touch a subtree that lacks the updated node", () => {
+    const otherKey = ["page-tree", "unrelated"];
+    const before = [
+      { id: "x1", title: "X", icon: "❌", spaceId: "s1" } as IPage,
+    ];
+    h.qc.setQueryData<IPage[]>(otherKey, before);
+
+    invalidateOnUpdatePage("s1", "parent-1", "p1", "New", "🚀");
+
+    // Same reference back — the subtree without p1 is left as-is.
+    expect(h.qc.getQueryData<IPage[]>(otherKey)).toBe(before);
+  });
+});

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

@@ -51,6 +51,10 @@ export function usePageQuery(
     queryFn: () => getPageById(pageInput),
     enabled: !!pageInput.pageId,
     staleTime: 5 * 60 * 1000,
+    // Keep the previously-loaded page visible while navigating to a new one
+    // instead of flashing a blank/skeleton frame (the new page's content
+    // streams in when ready). isLoading stays true only for the very first load.
+    placeholderData: keepPreviousData,
   });
 
   useEffect(() => {
@@ -66,6 +70,61 @@ export function usePageQuery(
   return query;
 }
 
+/**
+ * A page view that omits the large, frequently-changing `content` field. Every
+ * other field is preserved, so consumers that read only metadata (title, icon,
+ * permissions, id, creator, timestamps, …) keep working unchanged.
+ */
+export type IPageMeta = Omit<IPage, "content">;
+
+function selectPageMeta(page: IPage): IPageMeta {
+  // Drop `content`; react-query's structural sharing (replaceEqualDeep) then
+  // returns the SAME reference whenever the remaining fields are unchanged, so a
+  // pure content churn (typing / debouncedUpdateContent, collab `page.updated`)
+  // no longer changes this slice's identity and its ~13 subscribers don't
+  // re-render on every keystroke wave.
+  const { content: _content, ...meta } = page;
+  return meta as IPageMeta;
+}
+
+/**
+ * Metadata-only variant of {@link usePageQuery}. Shares the SAME query cache
+ * entry (`["pages", pageId]`, full object incl. content), but this hook returns
+ * a stable content-less slice so peripheral subscribers stop re-rendering on
+ * every content update. Use it anywhere the full `content` is not read.
+ */
+export function usePageMetaQuery(
+  pageInput: Partial<IPageInput>,
+): UseQueryResult<IPageMeta, Error> {
+  const query = useQuery({
+    queryKey: ["pages", pageInput.pageId],
+    queryFn: () => getPageById(pageInput),
+    enabled: !!pageInput.pageId,
+    staleTime: 5 * 60 * 1000,
+    select: selectPageMeta,
+    // Match usePageQuery: keep the previous page's metadata visible while
+    // navigating so the periphery (header, breadcrumb, …) doesn't flash blank.
+    placeholderData: keepPreviousData,
+  });
+
+  // Mirror usePageQuery's cross-key alias write so a page fetched by one
+  // identifier is also cached under the other. The cache stores the FULL page
+  // (select only narrows what THIS hook returns), so read the full object back
+  // from the cache and alias THAT — never the content-less slice.
+  useEffect(() => {
+    if (!query.data) return;
+    const full = queryClient.getQueryData<IPage>(["pages", pageInput.pageId]);
+    if (!full) return;
+    if (isValidUuid(pageInput.pageId)) {
+      queryClient.setQueryData(["pages", full.slugId], full);
+    } else {
+      queryClient.setQueryData(["pages", full.id], full);
+    }
+  }, [query.data]);
+
+  return query;
+}
+
 export function useCreatePageMutation() {
   const { t } = useTranslation();
   return useMutation<IPage, Error, Partial<IPageInput>>({
@@ -351,6 +410,12 @@ export function useRecentChangesQuery(spaceId?: string) {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
+    // KEEP refetchOnMount:true (against the global default false): recent-changes
+    // IS invalidated on page create/update/move/delete, but invalidateQueries only
+    // marks an UNMOUNTED query stale — it doesn't refetch it. The widget isn't
+    // always mounted, so an event that lands while it's unmounted leaves it stale,
+    // and the global refetchOnMount:false would not re-fetch on remount. The mount
+    // refetch closes that gap.
     refetchOnMount: true,
   });
 }
@@ -367,6 +432,9 @@ export function useCreatedByQuery(params?: {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
+    // KEEP refetchOnMount:true: the "created-by" key is never invalidated (no
+    // socket/mutation path), so the mount refetch is its ONLY freshness mechanism
+    // — without it the list shows stale cache on navigation.
     refetchOnMount: true,
   });
 }
@@ -380,8 +448,14 @@ export function useDeletedPagesQuery(
     queryFn: () => getDeletedPages(spaceId, params),
     enabled: !!spaceId,
     placeholderData: keepPreviousData,
-    refetchOnMount: true,
     staleTime: 0,
+    // KEEP refetchOnMount:true: ["trash-list"] IS invalidated by the
+    // move-to-trash / delete / restore mutations, but invalidateQueries only marks
+    // an unmounted query stale — it doesn't refetch it. The trash panel isn't
+    // usually mounted when a page is trashed, so on opening it the global
+    // refetchOnMount:false would show a stale list; the mount refetch closes that.
+    // (Do NOT remove the three trash-list invalidations — they are not dead code.)
+    refetchOnMount: true,
   });
 }
 
@@ -516,7 +590,35 @@ export function invalidateOnUpdatePage(
   title: string,
   icon: string,
 ) {
-  invalidatePageTree();
+  // Scoped page-tree refresh (was a blanket `invalidatePageTree()`): this is the
+  // FIELD-only update path (title/icon — no structural change), and the sidebar
+  // tree is already updated pointwise (applyUpdateOne / optimistic setData) plus
+  // via the sidebar-pages cache below. Invalidating ALL ["page-tree"] queries
+  // here refetched every open recursive subpages-embed block on each
+  // rename/icon-change — pure duplicate work. Instead patch just the affected
+  // node IN PLACE in every cached embed subtree: same visible result, no network
+  // churn, no full embed-tree rebuild. Structural events (create/move/delete)
+  // keep the blanket invalidate in their own helpers.
+  const pageTreeMatches = queryClient.getQueriesData<IPage[]>({
+    queryKey: ["page-tree"],
+  });
+  pageTreeMatches.forEach(([key, items]) => {
+    if (!items || !items.some((p) => p.id === id)) return;
+    queryClient.setQueryData<IPage[]>(key, (old) =>
+      old?.map((p) =>
+        p.id === id
+          ? {
+              ...p,
+              // Guard undefined so a title-only event can't wipe the icon (and
+              // vice versa) in the embed cache.
+              ...(title !== undefined ? { title } : {}),
+              ...(icon !== undefined ? { icon } : {}),
+            }
+          : p,
+      ),
+    );
+  });
+
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
     queryKey = ["root-sidebar-pages", spaceId];
@@ -534,7 +636,14 @@ export function invalidateOnUpdatePage(
           ...page,
           items: page.items.map((sidebarPage: IPage) =>
             sidebarPage.id === id
-              ? { ...sidebarPage, title: title, icon: icon }
+              ? {
+                  ...sidebarPage,
+                  // Guard undefined so a title-only event can't wipe the icon
+                  // (and vice versa) in the sidebar-pages cache — mirrors the
+                  // embed-cache patch above.
+                  ...(title !== undefined ? { title } : {}),
+                  ...(icon !== undefined ? { icon } : {}),
+                }
               : sidebarPage,
           ),
         })),

apps/client/src/features/page/trash/components/deleted-page-banner.tsx

@@ -7,7 +7,7 @@ import { useRestorePageModal } from "@/features/page/hooks/use-restore-page-moda
 import { useDeletePageModal } from "@/features/page/hooks/use-delete-page-modal.tsx";
 import {
   useDeletePageMutation,
-  usePageQuery,
+  usePageMetaQuery,
   useRestorePageMutation,
 } from "@/features/page/queries/page-query.ts";
 import { getSpaceUrl } from "@/lib/config.ts";
@@ -25,7 +25,7 @@ type DeletedPageBannerProps = {
 export function DeletedPageBanner({ slugId }: DeletedPageBannerProps) {
   const { t } = useTranslation();
   const navigate = useNavigate();
-  const { data: page } = usePageQuery({ pageId: slugId });
+  const { data: page } = usePageMetaQuery({ pageId: slugId });
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
   const spaceAbility = useSpaceAbility(space?.membership?.permissions);
   const deletedTimeAgo = useTimeAgo(page?.deletedAt);

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

@@ -1,4 +1,4 @@
-import { useAtom } from "jotai";
+import { useSetAtom, useStore } from "jotai";
 import { useTranslation } from "react-i18next";
 import { useParams } from "react-router-dom";
 import { ActionIcon, Menu, rem } from "@mantine/core";
@@ -52,7 +52,11 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
   const clipboard = useClipboard({ timeout: 500 });
   const { spaceSlug } = useParams();
   const { handleDelete } = useTreeMutation(node.spaceId);
-  const [data, setData] = useAtom(treeDataAtom);
+  // Setter-only: the tree value is read only imperatively inside the duplicate
+  // handler (via `store` below), never at render, so useSetAtom avoids
+  // re-rendering every row's NodeMenu on any tree event.
+  const setData = useSetAtom(treeDataAtom);
+  const store = useStore();
   const emit = useQueryEmit();
   const [exportOpened, { open: openExportModal, close: closeExportModal }] =
     useDisclosure(false);
@@ -125,8 +129,8 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
     try {
       const duplicatedPage = await duplicatePage({ pageId: node.id });
 
-      // figure out parent + insertion index
-      const siblings = treeModel.siblingsOf(data, node.id);
+      // figure out parent + insertion index (read the live tree imperatively)
+      const siblings = treeModel.siblingsOf(store.get(treeDataAtom), node.id);
       const parentId = siblings?.parentId ?? null;
       const currentIndex = siblings?.index ?? 0;
       const newIndex = currentIndex + 1;

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

@@ -1,6 +1,6 @@
 import { useRef } from "react";
 import { Link, useParams } from "react-router-dom";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import { useTranslation } from "react-i18next";
 import { ActionIcon, rem, Tooltip } from "@mantine/core";
 import {
@@ -51,7 +51,11 @@ export function SpaceTreeRow({
   const { t } = useTranslation();
   const { spaceSlug } = useParams();
   const updatePageMutation = useUpdatePageMutation();
-  const [, setTreeData] = useAtom(treeDataAtom);
+  // Setter-only: subscribing to the whole treeDataAtom (via useAtom) re-rendered
+  // every virtualized row on any tree event, bypassing the DocTreeRow memo. This
+  // row never reads the tree value, only writes it, so useSetAtom avoids the
+  // value subscription.
+  const setTreeData = useSetAtom(treeDataAtom);
   const emit = useQueryEmit();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [mobileSidebarOpened] = useAtom(mobileSidebarAtom);

apps/client/src/features/page/tree/components/space-tree.boot-cache.test.tsx

@@ -35,6 +35,7 @@ vi.mock("@/features/page/queries/page-query.ts", () => ({
     isFetching: false,
   }),
   usePageQuery: () => ({ data: undefined }),
+  usePageMetaQuery: () => ({ data: undefined }),
   fetchAllAncestorChildren: (...args: unknown[]) =>
     fetchAllAncestorChildrenMock(...args),
 }));

apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx

@@ -26,6 +26,7 @@ vi.mock("@/features/page/queries/page-query.ts", () => ({
     isFetching: false,
   }),
   usePageQuery: () => ({ data: undefined }),
+  usePageMetaQuery: () => ({ data: undefined }),
   fetchAllAncestorChildren: vi.fn(),
 }));
 

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

@@ -15,7 +15,7 @@ import { notifications } from "@mantine/notifications";
 import {
   fetchAllAncestorChildren,
   useGetRootSidebarPagesQuery,
-  usePageQuery,
+  usePageMetaQuery,
 } from "@/features/page/queries/page-query.ts";
 import classes from "@/features/page/tree/styles/tree.module.css";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
@@ -76,7 +76,7 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
   const [isDataLoaded, setIsDataLoaded] = useState(false);
   const spaceIdRef = useRef(spaceId);
   spaceIdRef.current = spaceId;
-  const { data: currentPage } = usePageQuery({
+  const { data: currentPage } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
 

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

@@ -1,5 +1,5 @@
 import { useCallback } from "react";
-import { useAtom, useSetAtom, useStore } from "jotai";
+import { useSetAtom, useStore } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { useNavigate, useParams } from "react-router-dom";
@@ -34,7 +34,10 @@ export type UseTreeMutation = {
 
 export function useTreeMutation(spaceId: string): UseTreeMutation {
   const { t } = useTranslation();
-  const [, setData] = useAtom(treeDataAtom);
+  // Setter-only: this hook never reads the tree reactively (handlers read the
+  // live value imperatively via `store` below), so useSetAtom avoids
+  // re-rendering SpaceSidebar on every tree event.
+  const setData = useSetAtom(treeDataAtom);
   // `store` reads the *current* treeDataAtom imperatively in handlers — avoids
   // stale-closure issues when the caller updates the tree (e.g. lazy-load
   // children) and then immediately invokes a handler.

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

@@ -1,10 +1,20 @@
+import { Suspense } from "react";
 import { Outlet } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
 import ShareShell from "@/features/share/components/share-shell.tsx";
 
 export default function ShareLayout() {
   return (
     <ShareShell>
-      <Outlet />
+      <Suspense
+        fallback={
+          <Center h="60vh">
+            <Loader size="sm" />
+          </Center>
+        }
+      >
+        <Outlet />
+      </Suspense>
     </ShareShell>
   );
 }

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

@@ -28,6 +28,7 @@ vi.mock("@/features/share/queries/share-query.ts", () => ({
 
 vi.mock("@/features/page/queries/page-query.ts", () => ({
   usePageQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
+  usePageMetaQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
 }));
 
 vi.mock("@/features/space/queries/space-query.ts", () => ({

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

@@ -20,7 +20,7 @@ import {
 import { Link, useParams } from "react-router-dom";
 import { extractPageSlugId, getPageIcon } from "@/lib";
 import { useTranslation } from "react-i18next";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import CopyTextButton from "@/components/common/copy.tsx";
 import { getAppUrl } from "@/lib/config.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -37,7 +37,7 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
   const pageSlugId = extractPageSlugId(pageSlug);
-  const { data: page } = usePageQuery({ pageId: pageSlugId });
+  const { data: page } = usePageMetaQuery({ pageId: pageSlugId });
   const pageId = page?.id;
   const { data: share } = useShareForPageQuery(pageId);
   const { spaceSlug } = useParams();

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

@@ -38,6 +38,11 @@ export function useGetSpacesQuery(
     queryKey: ["spaces", params],
     queryFn: () => getSpaces(params),
     placeholderData: keepPreviousData,
+    // KEEP refetchOnMount:true (against the global default false): the ["spaces"]
+    // key is invalidated only by same-tab mutations (no socket path), so a
+    // cross-actor change — an admin adding/removing THIS user from a space — has
+    // no local mutation or socket event and would leave the space list stale until
+    // a hard reload. The mount refetch is its only cross-actor freshness path.
     refetchOnMount: true,
   });
 }

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

@@ -16,7 +16,6 @@ export function useWatchedSpaceIds(): Set<string> {
   const { data } = useQuery({
     queryKey: [WATCHED_SPACE_IDS_KEY],
     queryFn: () => getWatchedSpaceIds(),
-    refetchOnMount: true,
   });
 
   const items = data?.items;

apps/client/src/features/websocket/use-query-subscription.ts

@@ -19,7 +19,11 @@ export const useQuerySubscription = () => {
   const [socket] = useAtom(socketAtom);
 
   React.useEffect(() => {
-    socket?.on("message", (event) => {
+    if (!socket) return;
+    // Named handler + off() cleanup (mirrors use-notification-socket). Without
+    // cleanup, every socket recreation / effect re-run stacked another listener,
+    // so a single broadcast fired duplicated invalidateQueries / setQueryData.
+    const handleMessage = (event) => {
       const data: WebSocketEvent = event;
 
       let entity = null;
@@ -163,6 +167,11 @@ export const useQuerySubscription = () => {
           });
           break;
       }
-    });
+    };
+
+    socket.on("message", handleMessage);
+    return () => {
+      socket.off("message", handleMessage);
+    };
   }, [queryClient, socket]);
 };

apps/client/src/features/websocket/use-tree-socket.ts

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
 import { socketAtom } from "@/features/websocket/atoms/socket-atom.ts";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { WebSocketEvent } from "@/features/websocket/types";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -16,7 +16,10 @@ import localEmitter from "@/lib/local-emitter.ts";
 
 export const useTreeSocket = () => {
   const [socket] = useAtom(socketAtom);
-  const [, setTreeData] = useAtom(treeDataAtom);
+  // Setter-only: this hook writes the tree from socket events but never reads it
+  // reactively, so useSetAtom avoids re-rendering UserProvider (its host) on
+  // every tree event.
+  const setTreeData = useSetAtom(treeDataAtom);
   const queryClient = useQueryClient();
 
   useEffect(() => {
@@ -37,7 +40,11 @@ export const useTreeSocket = () => {
   }, []);
 
   useEffect(() => {
-    socket?.on("message", (event: WebSocketEvent) => {
+    if (!socket) return;
+    // Named handler + off() cleanup (mirrors use-notification-socket). Without
+    // cleanup, every socket recreation / effect re-run stacked another listener,
+    // so a single broadcast fired duplicated tree walks after each reconnect.
+    const handleMessage = (event: WebSocketEvent) => {
       switch (event.operation) {
         case "updateOne":
           if (event.entity[0] === "pages") {
@@ -64,6 +71,11 @@ export const useTreeSocket = () => {
           });
           break;
       }
-    });
-  }, [socket]);
+    };
+
+    socket.on("message", handleMessage);
+    return () => {
+      socket.off("message", handleMessage);
+    };
+  }, [socket, queryClient, setTreeData]);
 };

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

@@ -243,6 +243,5 @@ export function useAppVersion(
     queryFn: () => getAppVersion(),
     staleTime: 60 * 60 * 1000, // 1 hr
     enabled: isEnabled,
-    refetchOnMount: true,
   });
 }

apps/client/src/hooks/use-clipboard.ts

@@ -1,7 +1,7 @@
 // Source: https://github.com/mantinedev/mantine/blob/master/packages/@mantine/hooks/src/use-clipboard/use-clipboard.ts
 // polyfilled to support execCommand fallback
 import { useState } from "react";
-import { execCommandCopy } from "@docmost/editor-ext";
+import { execCommandCopy } from "@/lib/copy-to-clipboard.ts";
 
 export type UseClipboardOptions = {
   timeout?: number;

apps/client/src/lib/config.ts

@@ -1,7 +1,7 @@
 import bytes from "bytes";
 import { castToBoolean } from "@/lib/utils.tsx";
 import { AvatarIconType } from "@/features/attachments/types/attachment.types.ts";
-import { sanitizeUrl } from "@docmost/editor-ext";
+import { sanitizeUrl } from "@/lib/sanitize-url.ts";
 
 declare global {
   interface Window {

apps/client/src/lib/copy-to-clipboard.ts

@@ -0,0 +1,16 @@
+// Client-local execCommand copy fallback (previously imported from
+// @docmost/editor-ext). It lives here so the ubiquitous useClipboard / CopyButton
+// path does not pull in the editor-ext barrel — and with it the whole TipTap
+// engine — through the eager startup graph. Behavior is identical to the
+// editor-ext helper it replaces.
+export function execCommandCopy(text: string): void {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.left = "-9999px";
+  textarea.style.top = "-9999px";
+  document.body.appendChild(textarea);
+  textarea.select();
+  document.execCommand("copy");
+  document.body.removeChild(textarea);
+}

apps/client/src/lib/sanitize-url.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { sanitizeUrl } from "./sanitize-url";
+
+// `sanitizeUrl` is a byte-identical client-local copy of editor-ext's wrapper
+// around @braintree/sanitize-url: it maps the sanitizer's "about:blank" XSS
+// sentinel to "". These assertions mirror editor-ext's own security-contract
+// test so the extracted copy keeps the same guarantees.
+describe("sanitizeUrl", () => {
+  it("blocks dangerous schemes (returns empty string)", () => {
+    expect(sanitizeUrl("javascript:alert(1)")).toBe("");
+    expect(sanitizeUrl("data:text/html,<script>alert(1)</script>")).toBe("");
+    expect(sanitizeUrl("vbscript:msgbox(1)")).toBe("");
+    // Case / whitespace obfuscation must not slip past the sanitizer.
+    expect(sanitizeUrl("  JaVaScRiPt:alert(1)")).toBe("");
+  });
+
+  it("returns empty string for empty / undefined input", () => {
+    expect(sanitizeUrl(undefined)).toBe("");
+    expect(sanitizeUrl("")).toBe("");
+  });
+
+  it("allows safe https, relative file and mailto URLs", () => {
+    expect(sanitizeUrl("https://example.com/page")).toMatch(
+      /^https:\/\/example\.com\/page/,
+    );
+    expect(sanitizeUrl("/api/files/abc-123")).toBe("/api/files/abc-123");
+    expect(sanitizeUrl("mailto:user@example.com")).toBe(
+      "mailto:user@example.com",
+    );
+  });
+});

apps/client/src/lib/sanitize-url.ts

@@ -0,0 +1,15 @@
+import { sanitizeUrl as braintreeSanitizeUrl } from "@braintree/sanitize-url";
+
+// Client-local copy of editor-ext's sanitizeUrl wrapper. Importing it from the
+// editor-ext barrel dragged the whole TipTap engine into the eager startup graph
+// via the app-wide config module (getFileUrl). This keeps the exact same
+// behavior (braintree sanitize + normalize "about:blank" -> "") without that
+// dependency.
+export function sanitizeUrl(url: string | undefined): string {
+  if (!url) return "";
+
+  const sanitized = braintreeSanitizeUrl(url);
+
+  // Return an empty string instead of "about:blank".
+  return sanitized === "about:blank" ? "" : sanitized;
+}

apps/client/src/main.tsx

@@ -13,15 +13,14 @@ import { ModalsProvider } from "@mantine/modals";
 import { Notifications } from "@mantine/notifications";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { HelmetProvider } from "react-helmet-async";
+import { ChunkLoadErrorBoundary } from "@/components/chunk-load-error-boundary.tsx";
 import "./i18n";
-import { PostHogProvider } from "posthog-js/react";
 import {
   getPostHogHost,
   getPostHogKey,
   isCloud,
   isPostHogEnabled,
 } from "@/lib/config.ts";
-import posthog from "posthog-js";
 import { initVitals } from "@/lib/telemetry/vitals";
 
 export const queryClient = new QueryClient({
@@ -35,15 +34,6 @@ export const queryClient = new QueryClient({
   },
 });
 
-if (isCloud() && isPostHogEnabled) {
-  posthog.init(getPostHogKey(), {
-    api_host: getPostHogHost(),
-    defaults: "2025-05-24",
-    disable_session_recording: true,
-    capture_pageleave: false,
-  });
-}
-
 // #355 — client perf-telemetry. Decides sampling ONCE (25%/session) before
 // subscribing to any observer; non-sampled sessions send nothing.
 initVitals();
@@ -51,19 +41,62 @@ initVitals();
 const container = document.getElementById("root") as HTMLElement;
 const root = (container as any).__reactRoot ??= ReactDOM.createRoot(container);
 
-root.render(
-  <BrowserRouter>
-    <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
-      <ModalsProvider>
-        <QueryClientProvider client={queryClient}>
-          <Notifications position="bottom-center" limit={3} zIndex={10000} />
-          <HelmetProvider>
-            <PostHogProvider client={posthog}>
-              <App />
-            </PostHogProvider>
-          </HelmetProvider>
-        </QueryClientProvider>
-      </ModalsProvider>
-    </MantineProvider>
-  </BrowserRouter>,
-);
+function renderApp() {
+  root.render(
+    <BrowserRouter>
+      <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
+        <ModalsProvider>
+          <QueryClientProvider client={queryClient}>
+            <Notifications position="bottom-center" limit={3} zIndex={10000} />
+            <HelmetProvider>
+              {/* Root boundary above every lazy route's Suspense: a stale-chunk
+                  404 after a deploy is caught and recovered here instead of
+                  blanking the whole app. */}
+              <ChunkLoadErrorBoundary>
+                <App />
+              </ChunkLoadErrorBoundary>
+            </HelmetProvider>
+          </QueryClientProvider>
+        </ModalsProvider>
+      </MantineProvider>
+    </BrowserRouter>,
+  );
+}
+
+async function initAnalytics() {
+  // posthog-js is only pulled in for cloud deployments with analytics enabled, so
+  // self-hosted builds never download it. The gate is kept identical to the
+  // previous eager code so cloud analytics behavior is unchanged; the import is
+  // simply deferred behind it.
+  //
+  // Crucially this runs AFTER the immediate first render below, so first paint is
+  // never gated on the analytics chunk. Any failure (network, stale 404, or an
+  // ad-blocker blocking a chunk named "posthog") is swallowed so the user keeps a
+  // working app without analytics instead of a permanently blank page.
+  //
+  // NOTE: we init the posthog SINGLETON only and do NOT wrap the tree in
+  // <PostHogProvider>. The app has zero consumers of the PostHog React context
+  // (no usePostHog / useFeatureFlag* / PostHogFeature), and PostHogProvider given
+  // an already-initialized `client` is a no-op — all capture goes through the
+  // singleton. Re-rendering to attach the provider would only REMOUNT the whole
+  // App (running every mount effect twice and dropping local state / focus /
+  // in-progress input on cloud cold-load) for no functional gain.
+  if (!(isCloud() && isPostHogEnabled)) return;
+  try {
+    const { default: posthog } = await import("posthog-js");
+    posthog.init(getPostHogKey(), {
+      api_host: getPostHogHost(),
+      defaults: "2025-05-24",
+      disable_session_recording: true,
+      capture_pageleave: false,
+    });
+  } catch {
+    // Analytics failed to load — degrade gracefully; the app already rendered.
+  }
+}
+
+// Paint immediately for everyone (self-hosted stays exactly as instant as before,
+// cloud no longer blocks on the analytics import). The posthog singleton is
+// initialized after, without re-rendering the tree.
+renderApp();
+void initAnalytics();

apps/client/src/pages/page/page-redirect.tsx

@@ -1,6 +1,6 @@
 import { useNavigate, useParams } from "react-router-dom";
 import { useEffect } from "react";
-import { usePageQuery } from "@/features/page/queries/page-query";
+import { usePageMetaQuery } from "@/features/page/queries/page-query";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { extractPageSlugId } from "@/lib";
 import { Error404 } from "@/components/ui/error-404.tsx";
@@ -11,7 +11,7 @@ export default function PageRedirect() {
     data: page,
     isLoading: pageIsLoading,
     isError,
-  } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
+  } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
   const navigate = useNavigate();
 
   useEffect(() => {

apps/client/src/pages/page/page.tsx

@@ -10,7 +10,7 @@ import { useTranslation } from "react-i18next";
 import React from "react";
 import { EmptyState } from "@/components/ui/empty-state.tsx";
 import { IconAlertTriangle, IconFileOff } from "@tabler/icons-react";
-import { Button } from "@mantine/core";
+import { Button, Skeleton } from "@mantine/core";
 import { Link } from "react-router-dom";
 import { ErrorBoundary } from "react-error-boundary";
 const MemoizedFullEditor = React.memo(FullEditor);
@@ -58,7 +58,7 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
     (space?.settings?.comments?.allowViewerComments === true);
 
   if (isLoading) {
-    return <></>;
+    return <PageSkeleton />;
   }
 
   if (isError || !page) {
@@ -87,7 +87,7 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
   }
 
   if (!space) {
-    return <></>;
+    return <PageSkeleton />;
   }
 
   return (
@@ -116,3 +116,18 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
     )
   );
 }
+
+// Lightweight loading placeholder shown instead of a blank fragment while the
+// page (or its space) is loading, so navigation into a not-yet-cached page no
+// longer flashes empty. Approximates the title + first content lines.
+function PageSkeleton() {
+  return (
+    <div>
+      <Skeleton height={34} width="45%" mt="xl" radius="sm" />
+      <Skeleton height={16} mt="xl" radius="sm" />
+      <Skeleton height={16} mt="sm" radius="sm" />
+      <Skeleton height={16} mt="sm" width="85%" radius="sm" />
+      <Skeleton height={16} mt="sm" width="70%" radius="sm" />
+    </div>
+  );
+}

apps/client/vite.config.ts

@@ -1,5 +1,6 @@
 import { defineConfig, loadEnv } from "vite";
 import react from "@vitejs/plugin-react";
+import { compression } from "vite-plugin-compression2";
 import * as path from "path";
 import { execSync } from "node:child_process";
 
@@ -53,7 +54,25 @@ export default defineConfig(({ mode }) => {
       },
       APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
     },
-    plugins: [react()],
+    plugins: [
+      react(),
+      // Emit .br and .gz next to every built asset so the server can serve the
+      // precompressed copy (see @fastify/static preCompressed in static.module.ts).
+      compression({
+        algorithms: ["brotliCompress", "gzip"],
+        // vite-plugin-compression2's default `include` only covers text-ish
+        // bundle output (js/mjs/json/css/html/svg/…). Extend it with the large
+        // VAD binaries copied from public/vad (.wasm ~26MB, .onnx ~2.3MB) so
+        // they are brotli/gzip'd once at build time and served via
+        // @fastify/static preCompressed — otherwise @fastify/compress would
+        // re-brotli them on EVERY request. The default types are repeated here
+        // because setting `include` replaces (does not extend) the default.
+        include: /\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml|wasm|onnx)$/,
+        // index.html is rewritten at server boot (window.CONFIG injection); a
+        // precompressed copy would go stale — NEVER precompress it.
+        exclude: [/index\.html$/],
+      }),
+    ],
     build: {
       rolldownOptions: {
         output: {
@@ -63,6 +82,20 @@ export default defineConfig(({ mode }) => {
                 name: "vendor-mantine",
                 test: /[\\/]node_modules[\\/]@mantine[\\/]/,
               },
+              // NOTE: TipTap/ProseMirror/Yjs are intentionally NOT force-grouped
+              // into a single vendor chunk. Doing so backfires: rolldown co-locates
+              // a small module shared with the (eager) react-i18next runtime into
+              // that group chunk, which then drags the whole ~590KB editor engine
+              // into the eager modulepreload graph. Left to the default splitting,
+              // the editor engine stays in lazily-loaded chunks pulled only by the
+              // route-split editor/share pages. KaTeX is safe to group (nothing
+              // eager references it).
+              // KaTeX in its own stable chunk; loaded on demand by the lazy math
+              // node views (never in the startup path).
+              {
+                name: "vendor-katex",
+                test: /[\\/]node_modules[\\/]katex[\\/]/,
+              },
             ],
           },
         },

apps/server/package.json

@@ -44,6 +44,7 @@
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
     "@docmost/prosemirror-markdown": "workspace:*",
+    "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
     "@fastify/static": "^9.1.3",

apps/server/src/collaboration/constants.ts

@@ -1,3 +1,10 @@
 export const HISTORY_INTERVAL = 5 * 60 * 1000;
 export const HISTORY_FAST_INTERVAL = 60 * 1000;
 export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
+
+// #348 — debounce window for the per-page RAG re-embed job. Repeated saves
+// within this window collapse to a single delayed job (coalesced by a stable
+// jobId), so active editing does not pile up expensive re-embeds (external API
+// + page_embeddings rewrite, concurrency 1). The worker reads the CURRENT page
+// state at run time, so the last content within the window wins.
+export const EMBED_DEBOUNCE_MS = 30 * 1000;

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

@@ -431,7 +431,17 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
   it('uses the canonical page.id (not the slugId doc name) for post-store side effects (#260)', async () => {
     const SLUG = 'slug-1'; // persistedHumanPage.slugId; findById resolves it
     const document = ydocFor(doc('NEW AGENT CONTENT'));
-    pageRepo.findById.mockResolvedValue(persistedHumanPage('NEW AGENT CONTENT'));
+    // #348 — the transclusion sync now runs only when the new OR the previously
+    // persisted content carries a transclusion-family node. Give the persisted
+    // (old) content a pageEmbed so the sync path is exercised and the #260
+    // UUID-vs-slugId contract asserted below is still verified.
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('NEW AGENT CONTENT'),
+      content: {
+        type: 'doc',
+        content: [{ type: 'pageEmbed', attrs: { sourcePageId: 'src-1' } }],
+      },
+    });
     pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
 
     // A `page.<slugId>` document name (the bug's smoking gun), agent store over

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

@@ -36,6 +36,7 @@ import {
 import { Page } from '@docmost/db/types/entity.types';
 import { CollabHistoryService } from '../services/collab-history.service';
 import {
+  EMBED_DEBOUNCE_MS,
   HISTORY_FAST_INTERVAL,
   HISTORY_FAST_THRESHOLD,
   HISTORY_INTERVAL,
@@ -45,6 +46,7 @@ import {
   observeCollabLoad,
   observeCollabStore,
 } from '../../integrations/metrics/metrics.registry';
+import { hasTransclusionFamilyNodes } from '../../core/page/transclusion/utils/transclusion-prosemirror.util';
 
 /**
  * #251 — wire format of the client→server stateless message that signals a
@@ -450,7 +452,18 @@ export class PersistenceExtension implements Extension {
       // Use the canonical page UUID (page.id), not the doc-name id, which may be
       // a slugId for a `page.<slugId>` doc (#260). The transclusion/reference
       // syncs write uuid-typed columns, so a slugId here threw Postgres 22P02.
-      await this.syncTransclusion(page.id, page.workspaceId, tiptapJson);
+      //
+      // #348 — skip the three sync SELECTs when neither the new content nor the
+      // previously-persisted content has any transclusion/reference/pageEmbed
+      // node: nothing to insert, and (the DB mirrors the old content) nothing to
+      // delete. Whenever either side has one, run the idempotent sync exactly as
+      // before so removals are still reconciled.
+      if (
+        hasTransclusionFamilyNodes(tiptapJson) ||
+        hasTransclusionFamilyNodes(page.content)
+      ) {
+        await this.syncTransclusion(page.id, page.workspaceId, tiptapJson);
+      }
     }
 
     if (page) {
@@ -466,7 +479,17 @@ export class PersistenceExtension implements Extension {
         (m) => m.entityId,
       );
 
-      if (userMentions.length > 0) {
+      // #348 — only enqueue when the mentioned-user set actually GAINED a member.
+      // The processor (processPageMention) already no-ops when every current
+      // mention was present before (newMentions.length === 0), so skipping the
+      // enqueue in that case is behavior-identical and avoids piling up no-op jobs
+      // on every save of a page that merely CONTAINS (unchanged) mentions.
+      const oldMentionedUserIdSet = new Set(oldMentionedUserIds);
+      const hasNewMentionedUser = userMentions.some(
+        (m) => !oldMentionedUserIdSet.has(m.entityId),
+      );
+
+      if (hasNewMentionedUser) {
         await this.notificationQueue.add(QueueJob.PAGE_MENTION_NOTIFICATION, {
           userMentions: userMentions.map((m) => ({
             userId: m.entityId,
@@ -481,12 +504,23 @@ export class PersistenceExtension implements Extension {
         } as IPageMentionNotificationJob);
       }
 
-      await this.aiQueue.add(QueueJob.PAGE_CONTENT_UPDATED, {
-        // Canonical UUID: the embedding reindex resolves pages by uuid, so a
-        // slugId here threw Postgres 22P02 invalid-uuid (#260).
-        pageIds: [page.id],
-        workspaceId: page.workspaceId,
-      });
+      await this.aiQueue.add(
+        QueueJob.PAGE_CONTENT_UPDATED,
+        {
+          // Canonical UUID: the embedding reindex resolves pages by uuid, so a
+          // slugId here threw Postgres 22P02 invalid-uuid (#260).
+          pageIds: [page.id],
+          workspaceId: page.workspaceId,
+        },
+        // #348 — coalesce re-embeds during active editing. A stable per-page
+        // jobId + delay means repeated saves within EMBED_DEBOUNCE_MS collapse
+        // to one delayed job instead of one expensive re-embed per save. The
+        // worker reads the current page state at run time, so last content wins.
+        // BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is
+        // used; page.id is a UUID, so the id is unique per page. removeOnComplete
+        // (queue.module) frees the id after each run so the next window re-arms.
+        { jobId: `embed-${page.id}`, delay: EMBED_DEBOUNCE_MS },
+      );
 
       await this.enqueuePageHistory(page, lastUpdatedSource);
     }

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

@@ -220,6 +220,13 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
   };
 
   async maintainLock(documentName: string) {
+    // #348 — clear any existing timer for this document before installing a new
+    // one. Without this, a second maintainLock for the same document (a
+    // reload-without-unload) overwrites this.locks[documentName] and leaks the
+    // previous interval, which keeps firing SET forever with no way to clear it.
+    if (this.locks[documentName]) {
+      clearInterval(this.locks[documentName]);
+    }
     this.locks[documentName] = setInterval(() => {
       this.pub.set(
         this.getKey(documentName),

apps/server/src/common/helpers/cache-keys.ts

@@ -4,8 +4,21 @@ export const CacheKey = {
     `perm:space-roles:${userId}:${spaceId}`,
   PAGE_CAN_EDIT: (userId: string, pageId: string) =>
     `perm:can-edit:${userId}:${pageId}`,
+  // #348 — DomainMiddleware workspace resolution. Self-hosted resolves the single
+  // workspace (constant key); cloud resolves by the request subdomain (lowercased
+  // to match the case-insensitive `LOWER(hostname)` lookup). Every WorkspaceRepo
+  // mutator busts these, so staleness is bounded by both explicit invalidation and
+  // the short TTL below.
+  WORKSPACE_SELF_HOSTED: 'workspace:self-hosted',
+  WORKSPACE_BY_HOST: (subdomain: string) =>
+    `workspace:byhost:${subdomain.toLowerCase()}`,
 };
 
 // Permission caches dedupe repeated checks within and across short request bursts.
 // 5s keeps staleness on revocations bounded.
 export const PERMISSION_CACHE_TTL_MS = 5_000;
+
+// #348 — workspace row changes rarely; a short TTL bounds staleness of
+// security-relevant fields (enforceSso/enforceMfa/status) even if an explicit
+// bust is ever missed, while still removing the per-request workspace query.
+export const WORKSPACE_CACHE_TTL_MS = 15_000;

apps/server/src/common/middlewares/domain.middleware.ts

@@ -1,13 +1,42 @@
-import { Injectable, NestMiddleware, NotFoundException } from '@nestjs/common';
+import { Inject, Injectable, NestMiddleware } from '@nestjs/common';
 import { FastifyRequest, FastifyReply } from 'fastify';
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Cache } from 'cache-manager';
 import { EnvironmentService } from '../../integrations/environment/environment.service';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { Workspace } from '@docmost/db/types/entity.types';
+import { withCache } from '../helpers/with-cache';
+import { CacheKey, WORKSPACE_CACHE_TTL_MS } from '../helpers/cache-keys';
+
+// #348 — timestamptz columns on the workspace row. The cache store (Keyv/Redis)
+// JSON-serializes values, so a cached workspace comes back with these fields as
+// ISO strings. Reviving them to Date keeps the cached path byte-identical to the
+// direct DB path (postgres.js returns Date), so nothing downstream can observe a
+// cache hit vs miss. Idempotent: `new Date(date)` on an already-Date value is a
+// no-op-equivalent. Keep in sync with the workspace timestamptz columns.
+const WORKSPACE_DATE_FIELDS: Array<keyof Workspace> = [
+  'createdAt',
+  'updatedAt',
+  'deletedAt',
+  'trialEndAt',
+];
+
+function reviveWorkspaceDates(workspace: Workspace): Workspace {
+  for (const field of WORKSPACE_DATE_FIELDS) {
+    const value = workspace[field];
+    if (value != null) {
+      (workspace as any)[field] = new Date(value as any);
+    }
+  }
+  return workspace;
+}
 
 @Injectable()
 export class DomainMiddleware implements NestMiddleware {
   constructor(
     private workspaceRepo: WorkspaceRepo,
     private environmentService: EnvironmentService,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
   ) {}
   async use(
     req: FastifyRequest['raw'],
@@ -15,13 +44,21 @@ export class DomainMiddleware implements NestMiddleware {
     next: () => void,
   ) {
     if (this.environmentService.isSelfHosted()) {
-      const workspace = await this.workspaceRepo.findFirst();
+      // #348 — cache the single-workspace lookup that runs on every request.
+      // Invalidated by every WorkspaceRepo mutator (see bustWorkspaceCache).
+      const workspace = await withCache(
+        this.cacheManager,
+        CacheKey.WORKSPACE_SELF_HOSTED,
+        WORKSPACE_CACHE_TTL_MS,
+        () => this.workspaceRepo.findFirst(),
+      );
       if (!workspace) {
         //throw new NotFoundException('Workspace not found');
         (req as any).workspaceId = null;
         return next();
       }
 
+      reviveWorkspaceDates(workspace);
       // TODO: unify
       (req as any).workspaceId = workspace.id;
       (req as any).workspace = workspace;
@@ -29,13 +66,21 @@ export class DomainMiddleware implements NestMiddleware {
       const header = req.headers.host;
       const subdomain = header.split('.')[0];
 
-      const workspace = await this.workspaceRepo.findByHostname(subdomain);
+      // #348 — cache per-subdomain workspace resolution. Keyed by subdomain (the
+      // hostname column); busted per hostname by every WorkspaceRepo mutator.
+      const workspace = await withCache(
+        this.cacheManager,
+        CacheKey.WORKSPACE_BY_HOST(subdomain),
+        WORKSPACE_CACHE_TTL_MS,
+        () => this.workspaceRepo.findByHostname(subdomain),
+      );
 
       if (!workspace) {
         (req as any).workspaceId = null;
         return next();
       }
 
+      reviveWorkspaceDates(workspace);
       (req as any).workspaceId = workspace.id;
       (req as any).workspace = workspace;
     }

apps/server/src/core/attachment/attachment.controller.ts

@@ -474,6 +474,19 @@ export class AttachmentController {
     const fileSize = Number(attachment.fileSize);
     const rangeHeader = req.headers.range;
 
+    // Opt this download route out of the global @fastify/compress hook.
+    // Attachment bytes are final and mostly binary, so on-the-fly compression
+    // only burns CPU — and on the 206/Range branch it is actively corrupting:
+    // compress decides purely by Content-Type, so for a compressible mime
+    // (application/octet-stream fallback, image/svg+xml, text/*) it would gzip
+    // the byte slice and drop Content-Length while Content-Range still
+    // describes the RAW offsets and the status stays 206. A resuming client
+    // (`curl -C -`, download managers) then appends the encoded bytes as if
+    // raw and ends up with a broken file. @fastify/compress skips whenever the
+    // request carries `x-no-compression` (see its onSend hook), so setting it
+    // here covers both the 200 (full file) and 206 (range) responses.
+    req.headers['x-no-compression'] = 'true';
+
     res.header('Accept-Ranges', 'bytes');
     res.header(
       'Content-Security-Policy',

apps/server/src/core/auth/strategies/jwt.strategy.ts

@@ -51,7 +51,21 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
       throw new UnauthorizedException();
     }
 
-    const workspace = await this.workspaceRepo.findById(payload.workspaceId);
+    // #348 — reuse the workspace DomainMiddleware already loaded for this request
+    // instead of re-querying it. `validate()` above has confirmed
+    // `req.raw.workspaceId === payload.workspaceId` (or that it is unset), and the
+    // middleware sets `req.raw.workspace` alongside `req.raw.workspaceId` from the
+    // SAME workspace row, so when the ids match this is that row. NOTE it is the
+    // middleware's `selectAll` object (a superset of the fallback `findById` base
+    // fields — it also carries licenseKey/auditRetentionDays); that is harmless
+    // here because every consumer reads this workspace via the AuthWorkspace
+    // decorator, which already preferred `req.raw.workspace` (the selectAll object)
+    // over `req.user.workspace` before this change. Fall back to the query if the
+    // middleware did not populate it (a path that bypasses DomainMiddleware).
+    const workspace =
+      req.raw.workspace && req.raw.workspaceId === payload.workspaceId
+        ? req.raw.workspace
+        : await this.workspaceRepo.findById(payload.workspaceId);
 
     if (!workspace) {
       throw new UnauthorizedException();

apps/server/src/core/favorite/services/favorite.service.ts

@@ -38,6 +38,8 @@ export class FavoriteService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds: result.items,
           userId,
+          // #348 — favorites load at app-start; enable the workspace short-circuit.
+          workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       result.items = result.items.filter((id) => accessibleSet.has(id));
@@ -125,6 +127,8 @@ export class FavoriteService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId,
+          // #348 — workspace-level short-circuit for the favorites list.
+          workspaceId,
         });
       accessiblePageSet = new Set(accessibleIds);
     }

apps/server/src/core/notification/notification.controller.ts

@@ -23,7 +23,12 @@ export class NotificationController {
     @Body() dto: ListNotificationsDto,
     @AuthUser() user: User,
   ) {
-    return this.notificationService.findByUserId(user.id, dto, dto.type);
+    return this.notificationService.findByUserId(
+      user.id,
+      dto,
+      dto.type,
+      user.workspaceId,
+    );
   }
 
   @HttpCode(HttpStatus.OK)

apps/server/src/core/notification/notification.service.ts

@@ -45,6 +45,7 @@ export class NotificationService {
     userId: string,
     pagination: PaginationOptions,
     type: NotificationTab = 'all',
+    workspaceId?: string | null,
   ) {
     const result = await this.notificationRepo.findByUserId(
       userId,
@@ -61,6 +62,8 @@ export class NotificationService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId,
+          // #348 — notifications list; enable the workspace short-circuit.
+          workspaceId,
         });
       const accessibleSet = new Set(accessiblePageIds);
 

apps/server/src/core/page/page.controller.ts

@@ -446,7 +446,11 @@ export class PageController {
       );
     }
 
-    return this.pageService.getRecentPages(user.id, pagination);
+    return this.pageService.getRecentPages(
+      user.id,
+      pagination,
+      user.workspaceId,
+    );
   }
 
   @HttpCode(HttpStatus.OK)
@@ -469,7 +473,13 @@ export class PageController {
       }
     }
 
-    return this.pageService.getCreatedByPages(targetUserId, user.id, pagination, dto.spaceId);
+    return this.pageService.getCreatedByPages(
+      targetUserId,
+      user.id,
+      pagination,
+      dto.spaceId,
+      user.workspaceId,
+    );
   }
 
   @HttpCode(HttpStatus.OK)

apps/server/src/core/page/services/page.service.ts

@@ -1165,6 +1165,7 @@ export class PageService {
   async getRecentPages(
     userId: string,
     pagination: PaginationOptions,
+    workspaceId?: string | null,
   ): Promise<CursorPaginationResult<Page>> {
     const result = await this.pageRepo.getRecentPages(userId, pagination);
 
@@ -1174,6 +1175,8 @@ export class PageService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId,
+          // #348 — cross-space "recent"; enable the workspace short-circuit.
+          workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       result.items = result.items.filter((p) => accessibleSet.has(p.id));
@@ -1187,6 +1190,7 @@ export class PageService {
     requestingUserId: string,
     pagination: PaginationOptions,
     spaceId?: string,
+    workspaceId?: string | null,
   ): Promise<CursorPaginationResult<Page>> {
     const result = await this.pageRepo.getCreatedByPages(
       creatorId,
@@ -1201,6 +1205,9 @@ export class PageService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId: requestingUserId,
+          spaceId,
+          // #348 — enable the workspace short-circuit when not space-scoped.
+          workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       result.items = result.items.filter((p) => accessibleSet.has(p.id));

apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts

@@ -93,6 +93,41 @@ function collectNodes<T>(
   return Array.from(byKey.values());
 }
 
+/**
+ * #348 — cheap early-exit probe: does this doc contain ANY node the transclusion
+ * syncs care about (`transclusionSource` / `transclusionReference` / `pageEmbed`)?
+ * Lets the collab store skip the three sync SELECTs when neither the previous nor
+ * the new content has any such node — there is nothing to insert, and (since the
+ * DB mirrors the previously-persisted content) nothing to delete. Walks once and
+ * short-circuits on the first match; uses the same depth ceiling as the
+ * collectors. Deliberately does NOT skip `transclusionSource` subtrees: it only
+ * answers "any node present?", so descending everywhere is strictly conservative
+ * (it can never wrongly report "none").
+ */
+export function hasTransclusionFamilyNodes(doc: unknown): boolean {
+  const visit = (node: any, depth: number): boolean => {
+    if (!node || typeof node !== 'object') return false;
+    if (depth > MAX_PM_WALK_DEPTH) return false;
+
+    if (
+      node.type === TRANSCLUSION_TYPE ||
+      node.type === REFERENCE_TYPE ||
+      node.type === PAGE_EMBED_TYPE
+    ) {
+      return true;
+    }
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) {
+        if (visit(child, depth + 1)) return true;
+      }
+    }
+    return false;
+  };
+
+  return visit(doc, 0);
+}
+
 /**
  * Walks a ProseMirror JSON document and returns one snapshot per top-level
  * `transclusion` node. Does not recurse into transclusions (schema disallows

apps/server/src/core/search/search.service.ts

@@ -155,6 +155,8 @@ export class SearchService {
           pageIds,
           userId: opts.userId,
           spaceId: searchParams.spaceId,
+          // #348 — enables the workspace-level short-circuit when not space-scoped.
+          workspaceId: opts.workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       results = results.filter((r: any) => accessibleSet.has(r.id));
@@ -266,6 +268,8 @@ export class SearchService {
           await this.pagePermissionRepo.filterAccessiblePageIds({
             pageIds,
             userId,
+            // #348 — workspace-level short-circuit for the suggest path.
+            workspaceId,
           });
         const accessibleSet = new Set(accessibleIds);
         pages = pages.filter((p) => accessibleSet.has(p.id));

apps/server/src/database/migrations/20260705T120000-perf-indexes.ts

@@ -0,0 +1,118 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * #348 — targeted hot-path indexes.
+ *
+ * 1. GIN trigram indexes for `/search/suggest`. That endpoint runs a
+ *    leading-wildcard `LOWER(f_unaccent(col)) LIKE '%q%'` per keystroke, which
+ *    is a sequential scan without a trigram index. The index EXPRESSIONS below
+ *    are `LOWER(f_unaccent(title|name))`, matching the predicates in
+ *    search.service.ts exactly so the planner uses them (verified with EXPLAIN:
+ *    the suggest predicate resolves to a Bitmap Index Scan on these indexes).
+ *
+ *    IMMUTABLE-wrapper fix (required for the index to build): `f_unaccent` was
+ *    defined as `SELECT unaccent('unaccent', $1)` (the two-arg, dictionary-named
+ *    unaccent). That body CANNOT be used in an index expression: when Postgres
+ *    inlines the IMMUTABLE SQL wrapper while building the index it fails to
+ *    resolve the two-arg call (`function unaccent(unknown, text) does not exist`,
+ *    the `'unaccent'` literal loses its regdictionary coercion). The single-arg
+ *    `unaccent($1)` is the same operation (the default text-search dictionary IS
+ *    `unaccent`; verified byte-equal on accented samples), and — crucially —
+ *    SCHEMA-QUALIFIED as `public.unaccent($1)` it inlines cleanly, so the index
+ *    builds. We therefore `CREATE OR REPLACE` `f_unaccent` to the qualified
+ *    single-arg body. This is output-identical for every existing caller (the
+ *    tsvector trigger, the main `tsv @@` search, and the suggest LIKE), so no
+ *    reindex/backfill is needed; `down()` restores the original two-arg body.
+ *    (The `unaccent` extension is installed in `public` in this codebase, which
+ *    is why `public.unaccent` is the correct qualification.)
+ *
+ * 2. Composite indexes for two ORDER-BY-only-on-id queries that currently sort
+ *    on top of a created_at index:
+ *    - page_history: `findPageHistoryByPageId` does WHERE page_id ORDER BY id
+ *      DESC, but only `(page_id, created_at DESC)` exists → extra sort.
+ *    - comments: `findPageComments` does WHERE page_id ORDER BY id ASC, but only
+ *      `(page_id)` exists → extra sort.
+ *
+ * DEPLOY-TIME LOCK WARNING: these are plain (non-CONCURRENT) CREATE INDEX
+ * statements — CONCURRENTLY is impossible because Kysely runs each migration in a
+ * transaction. They take a SHARE lock that BLOCKS writes (INSERT/UPDATE/DELETE) on
+ * pages/users/groups/comments/page_history for the duration of the build. The two
+ * GIN trigram builds on pages.title / users.name are the slow ones and can take
+ * minutes on a large tenant → a write-outage window during the deploy migration.
+ * For large installations, run this migration in a maintenance window, or build
+ * the trigram indexes out-of-band with CREATE INDEX CONCURRENTLY before deploying
+ * (then this migration's `IF NOT EXISTS` is a no-op). Small/typical tenants are
+ * unaffected.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  // Index-compatible, output-identical redefinition of f_unaccent (see header).
+  await sql`
+    CREATE OR REPLACE FUNCTION f_unaccent(text)
+      RETURNS text
+      LANGUAGE sql
+      IMMUTABLE PARALLEL SAFE STRICT
+    AS $func$
+      SELECT public.unaccent($1);
+    $func$
+  `.execute(db);
+
+  // Search-suggest trigram indexes. Expressions match search.service.ts.
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_pages_title_trgm
+      ON pages USING gin ((LOWER(f_unaccent(title))) gin_trgm_ops)
+  `.execute(db);
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_users_name_trgm
+      ON users USING gin ((LOWER(f_unaccent(name))) gin_trgm_ops)
+  `.execute(db);
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_groups_name_trgm
+      ON groups USING gin ((LOWER(f_unaccent(name))) gin_trgm_ops)
+  `.execute(db);
+
+  // page_history: WHERE page_id ORDER BY id DESC (findPageHistoryByPageId).
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_page_history_page_id
+      ON page_history (page_id, id DESC)
+  `.execute(db);
+
+  // comments: WHERE page_id ORDER BY id ASC (findPageComments).
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_comments_page_id_id
+      ON comments (page_id, id)
+  `.execute(db);
+
+  // page_access(workspace_id): #348 made hasRestrictedPagesInWorkspace uncached
+  // (F1 fix), so `EXISTS(SELECT 1 FROM page_access WHERE workspace_id=?)` now runs
+  // per-request on every whole-workspace list endpoint (global search + suggest,
+  // favorites, notifications, recent, created-by). page_access only had a
+  // space_id index → that EXISTS was a seq scan in the common zero-restriction
+  // case. This index makes it an index-only existence probe.
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_page_access_workspace_id
+      ON page_access (workspace_id)
+  `.execute(db);
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  // Drop the expression indexes before restoring the function body.
+  await sql`DROP INDEX IF EXISTS idx_pages_title_trgm`.execute(db);
+  await sql`DROP INDEX IF EXISTS idx_users_name_trgm`.execute(db);
+  await sql`DROP INDEX IF EXISTS idx_groups_name_trgm`.execute(db);
+  await sql`DROP INDEX IF EXISTS idx_page_history_page_id`.execute(db);
+  await sql`DROP INDEX IF EXISTS idx_comments_page_id_id`.execute(db);
+  await sql`DROP INDEX IF EXISTS idx_page_access_workspace_id`.execute(db);
+
+  // Restore the original two-arg (dictionary-named) f_unaccent body.
+  await sql`
+    CREATE OR REPLACE FUNCTION f_unaccent(text)
+      RETURNS text
+      LANGUAGE sql
+      IMMUTABLE PARALLEL SAFE STRICT
+    AS $func$
+      SELECT unaccent('unaccent', $1);
+    $func$
+  `.execute(db);
+}

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

@@ -657,8 +657,9 @@ export class PagePermissionRepo {
     pageIds: string[];
     userId: string;
     spaceId?: string;
+    workspaceId?: string | null;
   }): Promise<string[]> {
-    const { pageIds, userId, spaceId } = opts;
+    const { pageIds, userId, spaceId, workspaceId } = opts;
     if (pageIds.length === 0) return [];
 
     if (spaceId) {
@@ -666,6 +667,17 @@ export class PagePermissionRepo {
       if (!hasRestrictions) {
         return pageIds;
       }
+    } else if (workspaceId) {
+      // #348 — whole-workspace callers (no spaceId: favorites, notifications,
+      // recent, created-by, global search) skip the recursive-ancestor CTE + anti
+      // -join entirely when the workspace has ZERO restricted pages. When any
+      // restriction DOES exist, fall through to the identical CTE below, so
+      // behavior is unchanged whenever restrictions are present.
+      const hasRestrictions =
+        await this.hasRestrictedPagesInWorkspace(workspaceId);
+      if (!hasRestrictions) {
+        return pageIds;
+      }
     }
 
     const results = await this.db
@@ -903,6 +915,39 @@ export class PagePermissionRepo {
     return Boolean(result?.exists);
   }
 
+  /**
+   * Workspace-level analogue of hasRestrictedPagesInSpace: does ANY page in the
+   * whole workspace carry a restriction? Lets whole-workspace access filters
+   * short-circuit the recursive-ancestor CTE when nothing is restricted at all.
+   *
+   * UNCACHED (like the sibling hasRestrictedPagesInSpace) — a single cheap
+   * `EXISTS(pageAccess WHERE workspaceId=?)` per call. This is an ACCESS-CONTROL
+   * gate on whole-workspace list endpoints, so it must never go stale: caching it
+   * (even 5s) reintroduced a leak the space-path never had — a concurrent
+   * whole-workspace read in the insert->commit window of the FIRST restricted page
+   * could re-populate `false` under withCache (read-then-set, no del-during-read
+   * guard) and override the insert bust, leaking that page to unauthorized users
+   * for up to the TTL (#348 review F1). An uncached EXISTS removes both the
+   * cache/DB asymmetry with hasRestrictedPagesInSpace and that race; the space
+   * path already accepts this exact per-call cost.
+   */
+  async hasRestrictedPagesInWorkspace(workspaceId: string): Promise<boolean> {
+    const result = await this.db
+      .selectNoFrom((eb) =>
+        eb
+          .exists(
+            eb
+              .selectFrom('pageAccess')
+              .select(sql`1`.as('one'))
+              .where('pageAccess.workspaceId', '=', workspaceId),
+          )
+          .as('exists'),
+      )
+      .executeTakeFirst();
+
+    return Boolean(result?.exists);
+  }
+
   /**
    * Given a list of parent page IDs, return which ones have at least one accessible child.
    * Efficient batch query for sidebar hasChildren calculation.

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

@@ -581,6 +581,9 @@ export class PageRepo {
     const query = this.db
       .selectFrom('pages')
       .select(this.baseFields)
+      // NOTE: `content` IS needed here — the trash UI reads page.content to render
+      // the deleted-page preview modal (trash.tsx handlePageClick ->
+      // TrashPageContentModal pageContent). Do NOT drop it (see #348 review F3).
       .select('content')
       .select((eb) => this.withSpace(eb))
       .select((eb) => this.withDeletedBy(eb))

apps/server/src/database/repos/workspace/workspace.repo.ts

@@ -1,4 +1,6 @@
-import { Injectable } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Cache } from 'cache-manager';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
 import { dbOrTx } from '../../utils';
@@ -9,6 +11,7 @@ import {
 } from '@docmost/db/types/entity.types';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB, Workspaces } from '@docmost/db/types/db';
+import { CacheKey } from '../../../common/helpers/cache-keys';
 
 /**
  * Writable `settings.ai.provider` keys, enforced at this generic SQL layer. This
@@ -61,7 +64,34 @@ export class WorkspaceRepo {
     'temporaryNoteHours',
     'isScimEnabled',
   ];
-  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+  constructor(
+    @InjectKysely() private readonly db: KyselyDB,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+  ) {}
+
+  /**
+   * #348 — bust the DomainMiddleware workspace caches after any workspace write.
+   * Deletes BOTH the self-hosted (constant) key and the cloud per-hostname key so
+   * a single implementation covers either deployment mode (the irrelevant key is a
+   * harmless no-op). Best-effort: a cache error must never fail the write, and a
+   * missed bust is bounded by WORKSPACE_CACHE_TTL_MS. Note: a hostname RENAME only
+   * busts the NEW hostname's key (the row returned here carries the new hostname);
+   * the old key expires via TTL.
+   */
+  private async bustWorkspaceCache(
+    workspace?: Pick<Workspace, 'hostname'> | undefined,
+  ): Promise<void> {
+    try {
+      await this.cacheManager.del(CacheKey.WORKSPACE_SELF_HOSTED);
+      if (workspace?.hostname) {
+        await this.cacheManager.del(
+          CacheKey.WORKSPACE_BY_HOST(workspace.hostname),
+        );
+      }
+    } catch {
+      // cache is best-effort; TTL is the backstop
+    }
+  }
 
   async findById(
     workspaceId: string,
@@ -144,12 +174,14 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ): Promise<Workspace> {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({ ...updatableWorkspace, updatedAt: new Date() })
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   async insertWorkspace(
@@ -157,11 +189,14 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ): Promise<Workspace> {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .insertInto('workspaces')
       .values(insertableWorkspace)
       .returning(this.baseFields)
       .executeTakeFirst();
+    // Bust the cached "not found" so a fresh install / new tenant is seen at once.
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   async count(): Promise<number> {
@@ -203,7 +238,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -214,6 +249,8 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   async updateAiSettings(
@@ -223,7 +260,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -234,6 +271,8 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   /**
@@ -272,7 +311,7 @@ export class WorkspaceRepo {
           entries.flatMap(([k, v]) => [sql.lit(k), sql`${v}::text`]),
         )})`
       : sql`'{}'::jsonb`;
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb) || jsonb_build_object(
@@ -287,6 +326,8 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   /**
@@ -303,7 +344,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -313,6 +354,8 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   async updateSharingSettings(
@@ -322,7 +365,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -333,6 +376,8 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
   async updateTemplateSettings(
@@ -342,7 +387,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    return db
+    const workspace = await db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -353,6 +398,8 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
+    await this.bustWorkspaceCache(workspace);
+    return workspace;
   }
 
 }

apps/server/src/integrations/static/static.module.spec.ts

@@ -0,0 +1,35 @@
+import { resolveStaticAssetHeaders } from './static.module';
+
+// Unit tests for the static-asset cache classifier extracted from the
+// @fastify/static setHeaders callback (precedent: sandbox.controller.spec.ts).
+describe('resolveStaticAssetHeaders', () => {
+  it('marks a content-hashed /assets/ file immutable and sets Vary', () => {
+    const headers = resolveStaticAssetHeaders(
+      '/app/apps/client/dist/assets/index-a1b2c3.js',
+    );
+    expect(headers['cache-control']).toBe(
+      'public, max-age=31536000, immutable',
+    );
+    expect(headers['vary']).toBe('Accept-Encoding');
+  });
+
+  it('makes index.html always revalidate (never immutable)', () => {
+    const headers = resolveStaticAssetHeaders(
+      '/app/apps/client/dist/index.html',
+    );
+    expect(headers['cache-control']).toBe(
+      'no-cache, no-store, must-revalidate',
+    );
+    expect(headers['vary']).toBe('Accept-Encoding');
+  });
+
+  it('does NOT mark a non-hashed asset immutable but still sets Vary', () => {
+    const headers = resolveStaticAssetHeaders(
+      '/app/apps/client/dist/locales/en.json',
+    );
+    // No immutable cache-control — this path keeps @fastify/static's default
+    // etag/last-modified revalidation.
+    expect(headers['cache-control']).toBeUndefined();
+    expect(headers['vary']).toBe('Accept-Encoding');
+  });
+});

apps/server/src/integrations/static/static.module.ts

@@ -5,6 +5,46 @@ import * as fs from 'node:fs';
 import fastifyStatic from '@fastify/static';
 import { EnvironmentService } from '../environment/environment.service';
 
+/**
+ * Resolve the response headers for a statically served client asset.
+ *
+ * Extracted from the @fastify/static `setHeaders` callback so the cache
+ * classification stays a pure, unit-testable function (see
+ * static.module.spec.ts).
+ *
+ * `Vary: Accept-Encoding` is emitted for every static response because
+ * @fastify/static negotiates a precompressed .br/.gz neighbour by the client's
+ * Accept-Encoding but does NOT set Vary itself. Without it a shared/proxy cache
+ * keyed on the URL alone could store the brotli variant and later serve it to a
+ * client that only sent `Accept-Encoding: identity`/gzip → an undecodable body.
+ * This matters most for the immutable /assets/ files, which proxies may keep
+ * for a year.
+ */
+export function resolveStaticAssetHeaders(
+  filePath: string,
+): Record<string, string> {
+  const headers: Record<string, string> = { vary: 'Accept-Encoding' };
+
+  // Content-hashed files under /assets/ never change for a given URL, so they
+  // can be cached forever and skip revalidation entirely.
+  if (filePath.includes('/assets/')) {
+    headers['cache-control'] = 'public, max-age=31536000, immutable';
+    return headers;
+  }
+
+  // index.html is rewritten at boot (window.CONFIG injection) and on every
+  // deploy — it must be revalidated on every load.
+  if (filePath.endsWith('index.html')) {
+    headers['cache-control'] = 'no-cache, no-store, must-revalidate';
+    return headers;
+  }
+
+  // Everything else (locales, vad, icons, manifest) is NOT content-hashed and
+  // changes between deploys, so it keeps @fastify/static's default
+  // etag/last-modified revalidation — do NOT mark it immutable.
+  return headers;
+}
+
 @Module({})
 export class StaticModule implements OnModuleInit {
   constructor(
@@ -72,6 +112,16 @@ export class StaticModule implements OnModuleInit {
       await app.register(fastifyStatic, {
         root: clientDistPath,
         wildcard: false,
+        // Serve the build-time .br/.gz neighbour when the client accepts it
+        // (see vite-plugin-compression2 in apps/client/vite.config.ts).
+        preCompressed: true,
+        setHeaders: (res, filePath) => {
+          for (const [name, value] of Object.entries(
+            resolveStaticAssetHeaders(filePath),
+          )) {
+            res.setHeader(name, value);
+          }
+        },
       });
 
       app.get(RENDER_PATH, (req: any, res: any) => {

apps/server/src/main.ts

@@ -10,6 +10,7 @@ import { TransformHttpResponseInterceptor } from './common/interceptors/http-res
 import { WsRedisIoAdapter } from './ws/adapter/ws-redis.adapter';
 import fastifyMultipart from '@fastify/multipart';
 import fastifyCookie from '@fastify/cookie';
+import fastifyCompress from '@fastify/compress';
 import fastifyIp from 'fastify-ip';
 import { InternalLogFilter } from './common/logger/internal-log-filter';
 import { EnvironmentService } from './integrations/environment/environment.service';
@@ -77,6 +78,17 @@ async function bootstrap() {
   await app.register(fastifyIp);
   await app.register(fastifyMultipart);
   await app.register(fastifyCookie);
+  // Compress dynamic responses (API JSON, the rewritten share-SEO HTML) when the
+  // client accepts br/gzip. @fastify/compress only compresses content-types that
+  // mime-db flags `compressible` (application/json, text/html, …); `text/event-stream`
+  // is not in mime-db, so SSE is never compressed by the allowlist. The AI-chat
+  // stream additionally hijacks the raw socket (pipeUIMessageStreamToResponse ->
+  // res.raw in ai-chat.service.ts), bypassing Fastify's reply/onSend lifecycle
+  // entirely, so this hook can never buffer that stream.
+  await app.register(fastifyCompress, {
+    // Skip tiny payloads where compression overhead outweighs the savings.
+    threshold: 1024,
+  });
 
   const environmentService = app.get(EnvironmentService);
   const frameHeader = resolveFrameHeader(

apps/server/test/integration/page-permission-workspace-filter.int-spec.ts

@@ -0,0 +1,113 @@
+import { Kysely } from 'kysely';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { GroupRepo } from '@docmost/db/repos/group/group.repo';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createSpace,
+  createUser,
+  createPage,
+} from './db';
+
+/**
+ * #348 — the whole-workspace access-filter short-circuit is an ACCESS-CONTROL
+ * path, so it must produce the SAME result as the full recursive-ancestor CTE.
+ *
+ * filterAccessiblePageIds({ workspaceId }) (no spaceId — the favorites /
+ * notifications / recent / created-by / global-search callers) skips the CTE only
+ * when the workspace has ZERO restricted pages. A page is "restricted &
+ * inaccessible" when it (or an ancestor) has a `pageAccess` row and the user has
+ * no matching `pagePermissions`. Driven against real Postgres, asserts:
+ *   1. zero restrictions -> short-circuit returns the full input set;
+ *   2. a restriction present -> the CTE runs and drops the page the user can't
+ *      reach while keeping the reachable ones (behavior unchanged);
+ *   3. inserting the FIRST pageAccess flips hasRestrictedPagesInWorkspace
+ *      false -> true immediately (the 0->1 transition — now uncached, no stale
+ *      window, review F1); it is scoped per workspace.
+ */
+describe('#348 filterAccessiblePageIds workspace short-circuit (real PG)', () => {
+  let db: Kysely<any>;
+  let repo: PagePermissionRepo;
+  let workspaceId: string;
+  let otherWorkspaceId: string;
+  let userId: string;
+  let spaceId: string;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    // hasRestrictedPagesInWorkspace is now uncached, and no other cached
+    // permission path is exercised here, so a no-op cache stub suffices.
+    const cacheStub = {
+      get: async () => undefined,
+      set: async () => undefined,
+      del: async () => undefined,
+    } as never;
+    repo = new PagePermissionRepo(db, new GroupRepo(db), cacheStub);
+
+    const ws = await createWorkspace(db);
+    workspaceId = ws.id;
+    const other = await createWorkspace(db);
+    otherWorkspaceId = other.id;
+    const user = await createUser(db, workspaceId);
+    userId = user.id;
+    const space = await createSpace(db, workspaceId);
+    spaceId = space.id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  it('zero restrictions: short-circuit returns the full input set', async () => {
+    const p1 = await createPage(db, { workspaceId, spaceId });
+    const p2 = await createPage(db, { workspaceId, spaceId });
+
+    expect(await repo.hasRestrictedPagesInWorkspace(workspaceId)).toBe(false);
+
+    const ids = [p1.id, p2.id];
+    const filtered = await repo.filterAccessiblePageIds({
+      pageIds: ids,
+      userId,
+      workspaceId,
+    });
+    expect(new Set(filtered)).toEqual(new Set(ids));
+  });
+
+  it('a restriction present: filters out the page the user cannot reach', async () => {
+    const openPage = await createPage(db, { workspaceId, spaceId });
+    const restrictedPage = await createPage(db, { workspaceId, spaceId });
+
+    // Add a pageAccess row on restrictedPage with NO matching pagePermissions for
+    // `userId` → the CTE anti-join marks it inaccessible for this user.
+    await db
+      .insertInto('pageAccess')
+      .values({
+        pageId: restrictedPage.id,
+        workspaceId,
+        spaceId,
+        accessLevel: 'read',
+        creatorId: userId,
+      })
+      .execute();
+
+    // 0->1 transition is reflected immediately (uncached).
+    expect(await repo.hasRestrictedPagesInWorkspace(workspaceId)).toBe(true);
+
+    const filtered = await repo.filterAccessiblePageIds({
+      pageIds: [openPage.id, restrictedPage.id],
+      userId,
+      workspaceId,
+    });
+    expect(filtered).toContain(openPage.id);
+    expect(filtered).not.toContain(restrictedPage.id);
+  });
+
+  it('hasRestrictedPagesInWorkspace is scoped per workspace', async () => {
+    // The other workspace has no pageAccess rows → still false, unaffected by the
+    // restriction added above in `workspaceId`.
+    expect(await repo.hasRestrictedPagesInWorkspace(otherWorkspaceId)).toBe(
+      false,
+    );
+  });
+});

apps/server/test/integration/workspace-repo-update-setting.int-spec.ts

@@ -1,7 +1,25 @@
 import { Kysely } from 'kysely';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { CacheKey } from 'src/common/helpers/cache-keys';
 import { getTestDb, destroyTestDb, createWorkspace } from './db';
 
+// A minimal Map-backed cache double with a working `del` (the previous `{}` stub
+// made bustWorkspaceCache's `del` throw into its own try/catch, so the #348
+// invalidation was never actually exercised — review F6).
+function makeCacheDouble() {
+  const store = new Map<string, unknown>();
+  return {
+    store,
+    get: async (k: string) => store.get(k),
+    set: async (k: string, v: unknown) => {
+      store.set(k, v);
+    },
+    del: async (k: string) => {
+      store.delete(k);
+    },
+  };
+}
+
 /**
  * A — WorkspaceRepo.updateSetting jsonb-MERGE (the html-embed kill-switch
  * write-half). Setting a single top-level key must NOT clobber sibling
@@ -15,7 +33,9 @@ describe('WorkspaceRepo.updateSetting (jsonb merge) [integration]', () => {
   beforeAll(() => {
     db = getTestDb();
     // Repos are plain classes taking @InjectKysely() db — instantiate directly.
-    repo = new WorkspaceRepo(db as any);
+    // 2nd arg is CACHE_MANAGER (used only to bust the #348 workspace cache); a
+    // stub is fine here since bustWorkspaceCache is best-effort (try/catch).
+    repo = new WorkspaceRepo(db as any, {} as any);
   });
 
   afterAll(async () => {
@@ -58,3 +78,62 @@ describe('WorkspaceRepo.updateSetting (jsonb merge) [integration]', () => {
     expect(updated.settings).toEqual({ htmlEmbed: false });
   });
 });
+
+/**
+ * #348 F6 — the DomainMiddleware workspace cache (WORKSPACE_SELF_HOSTED /
+ * WORKSPACE_BY_HOST, 15s TTL) caches security-relevant fields (enforceSso/
+ * enforceMfa/status). Its correctness rests entirely on bustWorkspaceCache being
+ * called from every mutator. This exercises the real invalidation with a working
+ * cache double (not the {} stub, whose del throws-and-swallows): warm the cache
+ * like DomainMiddleware, mutate, and assert the busted key is gone so a stale
+ * workspace row can't outlive the mutation.
+ */
+describe('WorkspaceRepo bustWorkspaceCache invalidation [integration]', () => {
+  let db: Kysely<any>;
+
+  beforeAll(() => {
+    db = getTestDb();
+  });
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  it('updateSetting busts the self-hosted workspace cache key', async () => {
+    const cache = makeCacheDouble();
+    const repo = new WorkspaceRepo(db as any, cache as any);
+    const ws = await createWorkspace(db, { settings: {} });
+
+    // Warm the cache as DomainMiddleware would (self-hosted key).
+    cache.store.set(CacheKey.WORKSPACE_SELF_HOSTED, ws);
+    expect(cache.store.has(CacheKey.WORKSPACE_SELF_HOSTED)).toBe(true);
+
+    await repo.updateSetting(ws.id, 'htmlEmbed', true);
+
+    // The mutation must have invalidated the cached row.
+    expect(cache.store.has(CacheKey.WORKSPACE_SELF_HOSTED)).toBe(false);
+  });
+
+  it('updateSharingSettings busts the by-host workspace cache key too', async () => {
+    const cache = makeCacheDouble();
+    const repo = new WorkspaceRepo(db as any, cache as any);
+    const ws = await createWorkspace(db, { settings: {} });
+    // createWorkspace assigns a unique hostname; read it back for the by-host key.
+    const { hostname } = await db
+      .selectFrom('workspaces')
+      .select(['hostname'])
+      .where('id', '=', ws.id)
+      .executeTakeFirstOrThrow();
+
+    // Warm BOTH keys (self-hosted + by-host); the by-host bust needs the row's
+    // hostname, which the mutator returns from the DB.
+    cache.store.set(CacheKey.WORKSPACE_SELF_HOSTED, ws);
+    cache.store.set(CacheKey.WORKSPACE_BY_HOST(hostname as string), ws);
+
+    await repo.updateSharingSettings(ws.id, 'allowInvite', true);
+
+    expect(cache.store.has(CacheKey.WORKSPACE_SELF_HOSTED)).toBe(false);
+    expect(cache.store.has(CacheKey.WORKSPACE_BY_HOST(hostname as string))).toBe(
+      false,
+    );
+  });
+});

docker-compose.yml

@@ -12,6 +12,11 @@ services:
     ports:
       - "3000:3000"
     restart: unless-stopped
+    # The app already serves precompressed (brotli/gzip) static assets with
+    # long-lived cache headers and gzips dynamic API responses. For the best
+    # cold-load latency you can OPTIONALLY put a reverse proxy (caddy / nginx /
+    # traefik) in front with HTTP/2 (or HTTP/3) and brotli enabled — none is
+    # required for compression to work.
     volumes:
       - docmost:/app/data/storage
 

packages/editor-ext/src/lib/footnote/footnote-numbering.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { getSchema } from '@tiptap/core';
+import { Document } from '@tiptap/extension-document';
+import { Paragraph } from '@tiptap/extension-paragraph';
+import { Text } from '@tiptap/extension-text';
+import { EditorState } from '@tiptap/pm/state';
+import { Node as PMNode } from '@tiptap/pm/model';
+import { FootnoteReference } from './footnote-reference';
+import { FootnotesList } from './footnotes-list';
+import { FootnoteDefinition } from './footnote-definition';
+import {
+  footnoteNumberingPlugin,
+  footnoteNumberingPluginKey,
+  getFootnoteNumber,
+} from './footnote-numbering';
+import {
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTES_LIST_NAME,
+  FOOTNOTE_DEFINITION_NAME,
+} from './footnote-util';
+
+const extensions = [
+  Document,
+  Paragraph,
+  Text,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+];
+
+const schema = getSchema(extensions);
+
+function makeState(docJson: any): EditorState {
+  return EditorState.create({
+    doc: PMNode.fromJSON(schema, docJson),
+    plugins: [footnoteNumberingPlugin()],
+  });
+}
+
+const withTwoFootnotes = {
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'a' },
+        { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: 'x' } },
+        { type: 'text', text: 'b' },
+        { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: 'y' } },
+      ],
+    },
+    {
+      type: FOOTNOTES_LIST_NAME,
+      content: [
+        {
+          type: FOOTNOTE_DEFINITION_NAME,
+          attrs: { id: 'x' },
+          content: [{ type: 'paragraph' }],
+        },
+        {
+          type: FOOTNOTE_DEFINITION_NAME,
+          attrs: { id: 'y' },
+          content: [{ type: 'paragraph' }],
+        },
+      ],
+    },
+  ],
+};
+
+describe('footnote numbering plugin — short-circuit (#343 PART 5)', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('does ZERO document traversals on a docChanged transaction when the doc has no footnotes', () => {
+    const state = makeState({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hi' }] }],
+    });
+
+    // Only count traversals caused by the transaction, not the initial build.
+    const descendantsSpy = vi.spyOn(PMNode.prototype, 'descendants');
+
+    const before = footnoteNumberingPluginKey.getState(state);
+    // A real content edit (docChanged) that introduces no footnote node.
+    const next = state.apply(state.tr.insertText('!', 3));
+    const after = footnoteNumberingPluginKey.getState(next);
+
+    // The plugin never walked the document...
+    expect(descendantsSpy).not.toHaveBeenCalled();
+    // ...and reused the exact same (empty) state object — proof it short-circuited.
+    expect(after).toBe(before);
+    expect(after?.hasFootnotes).toBe(false);
+  });
+
+  it('rebuilds (numbering appears) the first time a footnote is inserted into a footnote-free doc', () => {
+    const state = makeState({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hi' }] }],
+    });
+    expect(footnoteNumberingPluginKey.getState(state)?.hasFootnotes).toBe(false);
+
+    const ref = schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: 'x' });
+    const next = state.apply(state.tr.insert(3, ref));
+
+    const after = footnoteNumberingPluginKey.getState(next);
+    expect(after?.hasFootnotes).toBe(true);
+    expect(getFootnoteNumber(next, 'x')).toBe(1);
+  });
+});
+
+describe('footnote numbering plugin — numbering unchanged with footnotes (#343 PART 5)', () => {
+  it('numbers references in document order via the single merged walk', () => {
+    const state = makeState(withTwoFootnotes);
+    expect(getFootnoteNumber(state, 'x')).toBe(1);
+    expect(getFootnoteNumber(state, 'y')).toBe(2);
+  });
+
+  it('produces a decoration for every reference and matching definition', () => {
+    const state = makeState(withTwoFootnotes);
+    const decos = footnoteNumberingPluginKey.getState(state)?.decorations;
+    // 2 references + 2 definitions = 4 number decorations.
+    expect(decos?.find().length).toBe(4);
+  });
+
+  it('keeps numbering current after an edit while footnotes exist', () => {
+    const state = makeState(withTwoFootnotes);
+    // Insert a NEW reference (id "z") before the others: it must become #1 and
+    // shift x -> #2, y -> #3 (deterministic document-order numbering).
+    const ref = schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: 'z' });
+    const next = state.apply(state.tr.insert(1, ref));
+    expect(getFootnoteNumber(next, 'z')).toBe(1);
+    expect(getFootnoteNumber(next, 'x')).toBe(2);
+    expect(getFootnoteNumber(next, 'y')).toBe(3);
+  });
+});

packages/editor-ext/src/lib/footnote/footnote-numbering.ts

@@ -1,11 +1,9 @@
-import { EditorState, Plugin, PluginKey } from '@tiptap/pm/state';
+import { EditorState, Plugin, PluginKey, Transaction } from '@tiptap/pm/state';
 import { Decoration, DecorationSet } from '@tiptap/pm/view';
-import { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import { Node as ProseMirrorNode, Slice } from '@tiptap/pm/model';
 import {
   FOOTNOTE_DEFINITION_NAME,
   FOOTNOTE_REFERENCE_NAME,
-  computeFootnoteNumbers,
-  computeFootnoteRefCounts,
 } from './footnote-util';
 
 export const footnoteNumberingPluginKey = new PluginKey<FootnoteNumberingState>(
@@ -27,8 +25,22 @@ interface FootnoteNumberingState {
   refCounts: Map<string, number>;
   /** Decorations rendering those numbers (refs + definitions). */
   decorations: DecorationSet;
+  /** Whether the document contains ANY footnote reference/definition node.
+   *  Cached so `apply` can skip the whole-doc walk on every keystroke in the
+   *  common case (documents with no footnotes), recomputing only once a
+   *  transaction actually inserts a footnote node (#343, PART 5). */
+  hasFootnotes: boolean;
 }
 
+/** Reusable empty state for footnote-free documents — avoids reallocating an
+ *  empty map/decoration set on every keystroke while there are no footnotes. */
+const EMPTY_STATE: FootnoteNumberingState = {
+  numbers: new Map(),
+  refCounts: new Map(),
+  decorations: DecorationSet.empty,
+  hasFootnotes: false,
+};
+
 /**
  * Build the decoration set for footnote numbers. Pure function of the document:
  * walk references in document order, assign 1-based numbers, then attach a
@@ -41,50 +53,101 @@ export function buildFootnoteDecorations(doc: ProseMirrorNode): DecorationSet {
   return buildFootnoteNumberingState(doc).decorations;
 }
 
+function numberDecoration(pos: number, nodeSize: number, num: number): Decoration {
+  return Decoration.node(pos, pos + nodeSize, {
+    'data-footnote-number': String(num),
+    style: `--footnote-number: "${num}";`,
+  });
+}
+
 /**
- * Compute both the number map AND the decorations for `doc` in a single walk.
- * The plugin caches the result so NodeViews can read numbers without
- * recomputing.
+ * Compute the number map, reference counts AND the decorations for `doc` in a
+ * SINGLE document walk (previously three separate O(n) traversals per
+ * docChanged — computeFootnoteNumbers + computeFootnoteRefCounts + a decoration
+ * pass, #343 PART 5). The plugin caches the result so NodeViews can read numbers
+ * without recomputing.
+ *
+ * References are numbered and decorated as they are encountered (document
+ * order). Definition positions are collected during the same walk and decorated
+ * afterwards from the completed number map — so a definition that appears before
+ * its reference in document order still resolves to the correct number, and the
+ * output is identical to the previous three-pass implementation. (Decoration
+ * insertion order does not matter: DecorationSet.create indexes by position.)
  */
 function buildFootnoteNumberingState(
   doc: ProseMirrorNode,
 ): FootnoteNumberingState {
-  const numbers = computeFootnoteNumbers(doc);
-  const refCounts = computeFootnoteRefCounts(doc);
+  const numbers = new Map<string, number>();
+  const refCounts = new Map<string, number>();
   const decorations: Decoration[] = [];
+  const definitions: { id: string; pos: number; nodeSize: number }[] = [];
+  let n = 0;
+  let hasFootnotes = false;
 
   doc.descendants((node, pos) => {
-    if (node.type.name === FOOTNOTE_REFERENCE_NAME) {
-      const num = numbers.get(node.attrs.id);
-      if (num != null) {
-        decorations.push(
-          Decoration.node(pos, pos + node.nodeSize, {
-            'data-footnote-number': String(num),
-            style: `--footnote-number: "${num}";`,
-          }),
-        );
-      }
-    }
-    if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
-      const num = numbers.get(node.attrs.id);
-      if (num != null) {
-        decorations.push(
-          Decoration.node(pos, pos + node.nodeSize, {
-            'data-footnote-number': String(num),
-            style: `--footnote-number: "${num}";`,
-          }),
-        );
+    const typeName = node.type.name;
+    if (typeName === FOOTNOTE_REFERENCE_NAME) {
+      hasFootnotes = true;
+      const id = node.attrs.id;
+      if (id) {
+        if (!numbers.has(id)) numbers.set(id, ++n);
+        refCounts.set(id, (refCounts.get(id) ?? 0) + 1);
+        decorations.push(numberDecoration(pos, node.nodeSize, numbers.get(id)!));
       }
+    } else if (typeName === FOOTNOTE_DEFINITION_NAME) {
+      hasFootnotes = true;
+      const id = node.attrs.id;
+      if (id != null) definitions.push({ id, pos, nodeSize: node.nodeSize });
     }
   });
 
+  if (!hasFootnotes) return EMPTY_STATE;
+
+  for (const def of definitions) {
+    const num = numbers.get(def.id);
+    if (num != null) {
+      decorations.push(numberDecoration(def.pos, def.nodeSize, num));
+    }
+  }
+
   return {
     numbers,
     refCounts,
     decorations: DecorationSet.create(doc, decorations),
+    hasFootnotes: true,
   };
 }
 
+/**
+ * Cheap check: does any of a transaction's inserted content contain a footnote
+ * reference/definition node? Footnote nodes can only ENTER the document through
+ * replace steps (ReplaceStep / ReplaceAroundStep both expose a `.slice`), so
+ * scanning only the inserted slices — O(change size), not O(doc) — is sufficient
+ * to detect a newly-added footnote. Mark/attr steps never introduce nodes.
+ * Lets `apply` keep skipping the whole-doc walk until a footnote first appears.
+ */
+function transactionInsertsFootnote(tr: Transaction): boolean {
+  for (const step of tr.steps) {
+    const slice = (step as unknown as { slice?: Slice }).slice;
+    if (!slice || slice.content.size === 0) continue;
+    let found = false;
+    slice.content.descendants((node) => {
+      if (found) return false;
+      const typeName = node.type.name;
+      if (
+        typeName === FOOTNOTE_REFERENCE_NAME ||
+        typeName === FOOTNOTE_DEFINITION_NAME
+      ) {
+        found = true;
+        return false;
+      }
+      return true;
+    });
+    if (found) return true;
+  }
+  return false;
+}
+
 /**
  * Read the cached footnote number for `id` from the numbering plugin's state.
  * This is the source NodeViews should use instead of calling
@@ -126,6 +189,13 @@ export function footnoteNumberingPlugin(): Plugin {
         // the number map NodeViews read stays current on every edit while
         // non-doc transactions (selection, etc.) reuse the cache for free.
         if (!tr.docChanged) return old;
+        // Short-circuit the whole-doc walk while the document has no footnotes:
+        // if there were none and this transaction did not INSERT one, there is
+        // still nothing to number, so reuse the empty state (#343, PART 5). Once
+        // a footnote exists we always rebuild (covers renumbering/deletion).
+        if (!old.hasFootnotes && !transactionInsertsFootnote(tr)) {
+          return old;
+        }
         return buildFootnoteNumberingState(tr.doc);
       },
     },

packages/mcp/src/client.ts

@@ -197,6 +197,166 @@ function readCollabTokenTtlMs(): number {
   return Number.isFinite(raw) ? Math.max(0, raw) : 5 * 60 * 1000;
 }
 
+// --- Issue #437: central error diagnostics -------------------------------
+// The agent only ever sees the thrown exception's `error.message`, so a failed
+// tool must return an ACTIONABLE message (method, path, status, and the
+// server's own validation text) instead of the opaque "Request failed with
+// status code 400". These helpers + the response interceptor in the
+// constructor are the single authoritative place that text is composed.
+
+// Overall cap on the composed diagnostic message so the model context stays
+// compact and a (whitelisted) server string can never blow up the text.
+const ERROR_MESSAGE_CAP = 300;
+// Only attempt to JSON.parse an arraybuffer body under this size: a larger
+// binary body is never a JSON error envelope, so parsing it just wastes memory
+// (fetchInternalFile uses responseType:"arraybuffer", so a failed file fetch
+// carries the JSON error envelope as raw bytes here).
+const ERROR_BUFFER_PARSE_CAP = 4096;
+
+// Canonical 36-char UUID (8-4-4-4-12 hex). Deliberately version/variant-
+// AGNOSTIC: the ids are UUIDv7 (e.g. 019f499a-9f8c-7d68-...), so only the
+// canonical shape/length is enforced, not the version/variant nibble.
+const FULL_UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Throw an actionable error BEFORE any network call when `value` is not a full
+ * canonical UUID. Absorbs #436: a truncated/short comment id used to reach the
+ * server and bounce back as an opaque 400/404 the agent could not self-correct;
+ * failing fast here names the exact fix.
+ */
+export function assertFullUuid(
+  tool: string,
+  param: string,
+  value: string,
+): void {
+  if (typeof value !== "string" || !FULL_UUID_RE.test(value)) {
+    throw new Error(
+      `${tool}: '${param}' must be the FULL comment UUID (36 chars, e.g. ` +
+        `019f499a-9f8c-7d68-b7be-ce100d7c6c56), got '${value}'. Copy the id ` +
+        `verbatim from list_comments / create_comment output.`,
+    );
+  }
+}
+
+// Keep ONLY the pathname of a request (no host, no query string, no fragment)
+// so the message never leaks a host or query params. Resolves a relative
+// config.url against config.baseURL, then discards everything but the path.
+function requestPath(config: any): string {
+  const rawUrl = typeof config?.url === "string" ? config.url : "";
+  const base =
+    typeof config?.baseURL === "string" ? config.baseURL : undefined;
+  try {
+    // A dummy base makes an absolute config.url parse too; its host is dropped.
+    return new URL(rawUrl, base ?? "http://localhost").pathname;
+  } catch {
+    // Malformed url: still strip any query/fragment manually.
+    return rawUrl.split(/[?#]/)[0] || rawUrl;
+  }
+}
+
+/**
+ * Compose the server-facing message from `error.response.data`, using ONLY the
+ * whitelisted `message`/`error` fields or the HTTP statusText. SECURITY: the
+ * raw response body, headers (Authorization!) and config are NEVER read here —
+ * a string/HTML body (e.g. a proxy's 502 page) is deliberately dropped in
+ * favour of the statusText.
+ */
+function extractServerMessage(data: any, statusText: string): string {
+  // class-validator envelope: { message: string | string[], error?: string }.
+  if (
+    data &&
+    typeof data === "object" &&
+    !Buffer.isBuffer(data) &&
+    !(data instanceof ArrayBuffer)
+  ) {
+    const msg = (data as any).message;
+    if (Array.isArray(msg)) {
+      const joined = msg.filter((m) => typeof m === "string").join("; ");
+      if (joined) return joined;
+    } else if (typeof msg === "string" && msg) {
+      return msg;
+    }
+    const err = (data as any).error;
+    if (typeof err === "string" && err) return err;
+    return statusText;
+  }
+
+  // Buffer / ArrayBuffer body: attempt a size-capped, guarded JSON.parse so a
+  // failed arraybuffer fetch still surfaces the server's validation text.
+  if (Buffer.isBuffer(data) || data instanceof ArrayBuffer) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    if (buf.length > 0 && buf.length <= ERROR_BUFFER_PARSE_CAP) {
+      try {
+        return extractServerMessage(JSON.parse(buf.toString("utf8")), statusText);
+      } catch {
+        return statusText;
+      }
+    }
+    return statusText;
+  }
+
+  // A raw string / HTML body is never surfaced (may echo server internals).
+  return statusText;
+}
+
+/**
+ * Reformat an AxiosError's `.message` IN PLACE into an actionable diagnostic:
+ *   `<METHOD> <path> failed (<status> <statusText>): <serverMessage>`
+ * or, when the request never got a response:
+ *   `<METHOD> <path> failed: <code> (no response from server)`.
+ *
+ * Mutates the SAME error object (never a custom subclass) so the live
+ * axios.isAxiosError / error.response?.status / config._retry checks around the
+ * client keep working, and sets `_docmostFormatted` as a double-processing
+ * guard. A no-op on a non-axios or already-formatted error.
+ */
+export function formatDocmostAxiosError(error: any): void {
+  if (!error || error._docmostFormatted) return;
+  if (!axios.isAxiosError(error)) return;
+
+  const config: any = error.config ?? {};
+  const method =
+    typeof config.method === "string" ? config.method.toUpperCase() : "";
+  const methodPath = `${method} ${requestPath(config)}`.trim();
+  const response = error.response;
+
+  let message: string;
+  if (response) {
+    const statusText =
+      typeof response.statusText === "string" ? response.statusText : "";
+    const serverMessage = extractServerMessage(response.data, statusText);
+    message = `${methodPath} failed (${response.status} ${statusText}): ${serverMessage}`;
+    // Full body only to stderr under DEBUG (parity with downloadImage).
+    if (process.env.DEBUG) {
+      console.error(
+        "Docmost request failed; response body:",
+        JSON.stringify(response.data),
+      );
+    }
+  } else {
+    // No response at all (ECONNREFUSED / ETIMEDOUT / ECONNRESET / DNS / timeout).
+    // Use ONLY error.code, never the raw error.message: axios network messages
+    // embed host:port ("connect ECONNREFUSED 127.0.0.1:3000", "getaddrinfo
+    // ENOTFOUND host") and #437's invariant is that the host never reaches the
+    // model-visible message. code is set for essentially every real no-response
+    // error (ECONNREFUSED/ETIMEDOUT/ECONNRESET/ENOTFOUND/ECONNABORTED); the full
+    // native message still goes to stderr under DEBUG.
+    const reason = error.code ?? "network error";
+    message = `${methodPath} failed: ${reason} (no response from server)`;
+    if (process.env.DEBUG) {
+      console.error("Docmost request failed; no response:", error.message);
+    }
+  }
+
+  if (message.length > ERROR_MESSAGE_CAP) {
+    message = message.slice(0, ERROR_MESSAGE_CAP - 1) + "…";
+  }
+
+  error.message = message;
+  (error as any)._docmostFormatted = true;
+}
+
 export class DocmostClient {
   private client: AxiosInstance;
   private token: string | null = null;
@@ -337,6 +497,22 @@ export class DocmostClient {
         return Promise.reject(error);
       },
     );
+
+    // Diagnostics interceptor (issue #437). Registered AFTER the re-login
+    // interceptor so a successful re-login retry (which resolves to a real
+    // response) is never seen here as an error; only a genuine failure reaches
+    // this rejection handler. It reformats error.message IN PLACE (see
+    // formatDocmostAxiosError — kept as a mutation, not a custom Error class, so
+    // the surrounding axios.isAxiosError / error.response?.status / config._retry
+    // checks keep working) and re-rejects the SAME error. The _docmostFormatted
+    // flag makes a re-processed retry-failure a no-op.
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        formatDocmostAxiosError(error);
+        return Promise.reject(error);
+      },
+    );
   }
 
   /** Application base URL (API URL without the /api suffix). */
@@ -2411,6 +2587,8 @@ export class DocmostClient {
   }
 
   async getComment(commentId: string) {
+    // Fail fast (#436): reject a truncated id before any network call.
+    assertFullUuid("get_comment", "commentId", commentId);
     await this.ensureAuthenticated();
     const response = await this.client.post("/comments/info", { commentId });
     const comment = response.data.data || response.data;
@@ -2500,6 +2678,12 @@ export class DocmostClient {
     parentCommentId?: string,
     suggestedText?: string,
   ) {
+    // Fail fast (#436): a provided parent id must be a full UUID before any
+    // network call. Validate only when truthy — a falsy parentCommentId means
+    // "top-level comment" (mirrors the isReply computation below), not a reply.
+    if (parentCommentId) {
+      assertFullUuid("create_comment", "parentCommentId", parentCommentId);
+    }
     await this.ensureAuthenticated();
 
     const isReply = !!parentCommentId;
@@ -2782,6 +2966,8 @@ export class DocmostClient {
   }
 
   async updateComment(commentId: string, content: string) {
+    // Fail fast (#436): reject a truncated id before any network call.
+    assertFullUuid("update_comment", "commentId", commentId);
     await this.ensureAuthenticated();
     // NON-canonicalizing on purpose (comment body — see createComment).
     const jsonContent = await markdownToProseMirror(content);
@@ -2797,6 +2983,8 @@ export class DocmostClient {
   }
 
   async deleteComment(commentId: string) {
+    // Fail fast (#436): reject a truncated id before any network call.
+    assertFullUuid("delete_comment", "commentId", commentId);
     await this.ensureAuthenticated();
     return this.client
       .post("/comments/delete", { commentId })
@@ -2809,6 +2997,8 @@ export class DocmostClient {
    * rejects resolving a reply. Hits POST /comments/resolve.
    */
   async resolveComment(commentId: string, resolved: boolean) {
+    // Fail fast (#436): reject a truncated id before any network call.
+    assertFullUuid("resolve_comment", "commentId", commentId);
     await this.ensureAuthenticated();
     const response = await this.client.post("/comments/resolve", {
       commentId,

packages/mcp/src/lib/collab-session.ts

@@ -202,6 +202,21 @@ export class CollabSession {
     this.ydoc = new Y.Doc();
   }
 
+  /**
+   * Shared diagnostic suffix (issue #437) appended to the connect-timeout,
+   * persist-timeout and connection-closed error texts: names the offending
+   * pageId and tells the agent this class of failure is transient (retry once)
+   * vs. a persistent collab-server outage, so it can self-correct instead of
+   * blind-looping. The Yjs-encode error is deliberately NOT touched — it
+   * already names the offending attribute.
+   */
+  private hint(): string {
+    return (
+      `(pageId ${this.pageId}; transient — retry once; persistent failures ` +
+      `mean the collab server is unreachable/overloaded)`
+    );
+  }
+
   /**
    * A cached session may be reused only when it is fully ready, still synced,
    * has not lost its connection, and has not exceeded its max age (invariant 5
@@ -232,7 +247,9 @@ export class CollabSession {
         // The 25s connect timeout: the collab connection never became ready.
         this.opts?.onConnectTimeout?.();
         this.teardown(
-          new Error("Connection timeout to collaboration server"),
+          new Error(
+            `Connection timeout to collaboration server ${this.hint()}`,
+          ),
           false,
         );
       }, CONNECT_TIMEOUT_MS);
@@ -259,7 +276,7 @@ export class CollabSession {
           if (process.env.DEBUG) console.error("WS Disconnect");
           this.teardown(
             new Error(
-              "Collaboration connection closed before the update was persisted/synced",
+              `Collaboration connection closed before the update was persisted/synced ${this.hint()}`,
             ),
             true,
           );
@@ -268,7 +285,7 @@ export class CollabSession {
           if (process.env.DEBUG) console.error("WS Close");
           this.teardown(
             new Error(
-              "Collaboration connection closed before the update was persisted/synced",
+              `Collaboration connection closed before the update was persisted/synced ${this.hint()}`,
             ),
             true,
           );
@@ -403,7 +420,7 @@ export class CollabSession {
         persistTimer = setTimeout(() => {
           localFinish(
             new Error(
-              "Timeout waiting for collaboration server to persist the update",
+              `Timeout waiting for collaboration server to persist the update ${this.hint()}`,
             ),
           );
         }, PERSIST_TIMEOUT_MS);