From acbc463d76c233f46550dc8f447a47c9e934c3dc Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 11:45:58 +0800
Subject: [PATCH 01/12] fix(muya): move preview toolbar to the block's
 top-right (#4733) (#4734)

The HTML/math block preview toolbar was anchored at the top-left corner
inside the block (placement `left-start` + `mainAxis: -95`), overlapping the
rendered content. Mirror it to the top-right (`right-start`, same `-95`
inset), where left-aligned content leaves the corner free.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/muya/src/ui/previewToolBar/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/muya/src/ui/previewToolBar/index.ts b/packages/muya/src/ui/previewToolBar/index.ts
index 8ab52b1c57..0bb402f615 100644
--- a/packages/muya/src/ui/previewToolBar/index.ts
+++ b/packages/muya/src/ui/previewToolBar/index.ts
@@ -12,7 +12,7 @@ import ICONS from './config';
 import './index.css';
 
 const defaultOptions = {
-    placement: 'left-start' as const,
+    placement: 'right-start' as const,
     offsetOptions: {
         mainAxis: -95,
         crossAxis: 5,

From 6fd3ee6b5070217644a399b5da7f904ac93ac46a Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 11:50:42 +0800
Subject: [PATCH 02/12] fix(renderer): hide muya float tools in source-code
 mode (#4732)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In source mode the muya editor is sent behind the source editor via
`z-index: -1` but stays in the DOM. Several muya float tools listen on a
document-level mousemove and locate the hovered block with
`document.elementsFromPoint`, which ignores z-index — so hovering over the
source editor re-triggered the paragraph front button/menu, the table
drag/column toolbars and the preview toolbar on top of CodeMirror.

Add `pointer-events: none` to `.editor-wrapper.source` so the hidden editor
subtree is excluded from hit-testing; the floats can no longer be
re-triggered, while CodeMirror (a sibling, not a descendant) stays
interactive.

Fixes #4731

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/renderer/src/components/editorWithTabs/editor.vue    | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/desktop/src/renderer/src/components/editorWithTabs/editor.vue b/packages/desktop/src/renderer/src/components/editorWithTabs/editor.vue
index 88434680dd..8d2d8ca244 100644
--- a/packages/desktop/src/renderer/src/components/editorWithTabs/editor.vue
+++ b/packages/desktop/src/renderer/src/components/editorWithTabs/editor.vue
@@ -2028,6 +2028,11 @@ onBeforeUnmount(() => {
   top: 0;
   left: 0;
   overflow: hidden;
+  /* `z-index: -1` only hides the editor visually; `document.elementsFromPoint`
+     ignores stacking, so muya's mousemove-driven float tools (front button/menu,
+     table drag/column toolbars, preview toolbar) still re-trigger over the source
+     editor. Drop the subtree from hit-testing too so they cannot (#4731). */
+  pointer-events: none;
 }
 
 .editor-component {

From 68f4b43171f7a27bad690da1ef757e7b418dc1f9 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 12:47:49 +0800
Subject: [PATCH 03/12] fix(desktop): hide the in-app title bar under the
 native title bar style (#4210) (#4630)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

With the native title bar (non-macOS, `frame: true`), the OS draws a title
bar showing document.title while the in-app custom title bar rendered the same
filename — the title appeared twice. The in-app `<title-bar>` was mounted
unconditionally.

Gate the in-app title bar DOM behind `shouldShowInAppTitleBar(titleBarStyle,
isOsx)` (hidden when `native` and not macOS; macOS windows are always
frameless so it still shows). The `document.title` watcher stays in
`<script setup>` and keeps updating the native OS bar while the in-app bars
are hidden.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/titleBar/index.vue         |  7 +++++++
 .../src/components/titleBar/visibility.ts     |  3 +++
 .../unit/specs/titlebar-visibility.spec.ts    | 21 +++++++++++++++++++
 3 files changed, 31 insertions(+)
 create mode 100644 packages/desktop/src/renderer/src/components/titleBar/visibility.ts
 create mode 100644 packages/desktop/test/unit/specs/titlebar-visibility.spec.ts

diff --git a/packages/desktop/src/renderer/src/components/titleBar/index.vue b/packages/desktop/src/renderer/src/components/titleBar/index.vue
index 3d6ccc00bb..57498ec1f3 100644
--- a/packages/desktop/src/renderer/src/components/titleBar/index.vue
+++ b/packages/desktop/src/renderer/src/components/titleBar/index.vue
@@ -1,10 +1,12 @@
 <template>
   <div>
     <div
+      v-if="showTitleBar"
       class="title-bar-editor-bg"
       :class="{ 'tabs-visible': showTabBar }"
     />
     <div
+      v-if="showTitleBar"
       class="title-bar"
       :class="[
         { active: active },
@@ -142,6 +144,7 @@ import { storeToRefs } from 'pinia'
 import { minimizePath, restorePath, maximizePath, closePath } from '../../assets/window-controls.js'
 import { PATH_SEPARATOR } from '../../config'
 import { isOsx as isOsxPlatform } from '@/util'
+import { shouldShowInAppTitleBar } from './visibility'
 import { useEditorStore } from '@/store/editor'
 import { useI18n } from 'vue-i18n'
 import { ArrowRight } from '@element-plus/icons-vue'
@@ -219,6 +222,10 @@ const showCustomTitleBar = computed(() => {
   return titleBarStyle.value === 'custom' && !isOsx
 })
 
+const showTitleBar = computed(() => {
+  return shouldShowInAppTitleBar(titleBarStyle.value, isOsx)
+})
+
 watch(
   () => props.filename,
   (value) => {
diff --git a/packages/desktop/src/renderer/src/components/titleBar/visibility.ts b/packages/desktop/src/renderer/src/components/titleBar/visibility.ts
new file mode 100644
index 0000000000..0e8940a0bb
--- /dev/null
+++ b/packages/desktop/src/renderer/src/components/titleBar/visibility.ts
@@ -0,0 +1,3 @@
+export function shouldShowInAppTitleBar(titleBarStyle: string, isOsx: boolean): boolean {
+  return titleBarStyle !== 'native' || isOsx
+}
diff --git a/packages/desktop/test/unit/specs/titlebar-visibility.spec.ts b/packages/desktop/test/unit/specs/titlebar-visibility.spec.ts
new file mode 100644
index 0000000000..8738a17c78
--- /dev/null
+++ b/packages/desktop/test/unit/specs/titlebar-visibility.spec.ts
@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest'
+import { shouldShowInAppTitleBar } from '@/components/titleBar/visibility'
+
+// #4210: with the native title bar (non-macOS, `frame: true`), the OS draws a
+// title bar showing document.title AND the in-app custom title bar rendered the
+// same filename — the title appeared twice. The in-app bar must be hidden when
+// the native title bar is active. On macOS the window is always frameless, so
+// the in-app bar must still show.
+describe('shouldShowInAppTitleBar (#4210)', () => {
+  it('hides the in-app title bar for the native style on non-macOS', () => {
+    expect(shouldShowInAppTitleBar('native', false)).toBe(false)
+  })
+
+  it('still shows the in-app title bar on macOS even with the native style', () => {
+    expect(shouldShowInAppTitleBar('native', true)).toBe(true)
+  })
+
+  it('shows the in-app title bar for the custom style', () => {
+    expect(shouldShowInAppTitleBar('custom', false)).toBe(true)
+  })
+})

From 4d65a4aaa22a6806431911efe6fca64a2fdeb15b Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 13:10:56 +0800
Subject: [PATCH 04/12] fix(muya): pull a list item's nested sublist up on
 forward-delete merge (#1845) (#4725)

Forward-Delete at the end of an empty list item merged only the next
item's paragraph text and removed that paragraph. When the next item also
held a nested sublist as a sibling of its paragraph, the sublist was
stranded as the item's sole child and serialized with a doubled bullet
(`* - D`).

Relocate the merged paragraph's trailing siblings into the target item
before removing the now-empty source item, so the whole content travels
up with the text.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/muya/src/block/base/format.ts        | 31 +++++++++++--
 .../__tests__/deleteMerge.spec.ts             | 46 +++++++++++++++++++
 2 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/packages/muya/src/block/base/format.ts b/packages/muya/src/block/base/format.ts
index 7bc63bd835..831e03a888 100644
--- a/packages/muya/src/block/base/format.ts
+++ b/packages/muya/src/block/base/format.ts
@@ -11,6 +11,7 @@ import type { IImageInfo } from '../../utils/image';
 import type AtxHeading from '../commonMark/atxHeading';
 import type BulletList from '../commonMark/bulletList';
 import type SetextHeading from '../commonMark/setextHeading';
+import type Parent from './parent';
 import type TreeNode from './treeNode';
 import Content from '../../block/base/content';
 import { ScrollPage } from '../../block/scrollPage';
@@ -1482,9 +1483,32 @@ class Format extends Content {
 
         event.preventDefault();
 
-        const paragraphBlock = nextBlock.parent;
-        let needRemovedBlock = paragraphBlock;
+        const paragraphBlock = nextBlock.parent!;
 
+        this.text = text + nextBlock.text;
+        this.setCursor(start.offset, end.offset, true);
+
+        // When the merge crosses a list-item boundary, blocks that followed the
+        // next paragraph inside its item (e.g. a nested sublist) must travel up
+        // with the merged text. Left behind they become the sole child of the
+        // now-empty item and serialize with a doubled bullet (#1845).
+        const paragraph = this.parent;
+        if (paragraph && paragraphBlock.parent !== paragraph.parent) {
+            const trailing: TreeNode[] = [];
+            let sibling = paragraphBlock.next;
+            while (sibling) {
+                trailing.push(sibling);
+                sibling = sibling.next;
+            }
+
+            let anchor: Parent = paragraph;
+            for (const block of trailing) {
+                block.insertInto(paragraph.parent!, anchor.next as Nullable<Parent>);
+                anchor = block as Parent;
+            }
+        }
+
+        let needRemovedBlock: Nullable<Parent> = paragraphBlock;
         while (
             needRemovedBlock
             && needRemovedBlock.isOnlyChild()
@@ -1492,9 +1516,6 @@ class Format extends Content {
         ) {
             needRemovedBlock = needRemovedBlock.parent;
         }
-
-        this.text = text + nextBlock.text;
-        this.setCursor(start.offset, end.offset, true);
         needRemovedBlock!.remove();
     }
 
diff --git a/packages/muya/src/block/content/paragraphContent/__tests__/deleteMerge.spec.ts b/packages/muya/src/block/content/paragraphContent/__tests__/deleteMerge.spec.ts
index 063cee5779..93e7dfa19a 100644
--- a/packages/muya/src/block/content/paragraphContent/__tests__/deleteMerge.spec.ts
+++ b/packages/muya/src/block/content/paragraphContent/__tests__/deleteMerge.spec.ts
@@ -121,6 +121,52 @@ describe('forward Delete at end-of-paragraph — merge with next block', () => {
     });
 });
 
+// #1845 — forward-Delete at the end of an empty list item must pull the next
+// item's WHOLE content up, not just its paragraph. The next item held a nested
+// sublist (`- D`) as a sibling of its paragraph; merging only the paragraph and
+// removing it stranded that sublist as the item's sole child, which serializes
+// with a doubled bullet (`* - D`).
+describe('forward Delete merging a list item that owns a nested sublist (#1845)', () => {
+    function emptyFirstItemThenDelete(muya: Muya): void {
+        const first = contentByText(muya, 'a');
+        first.text = '';
+        deleteAtEnd(muya, first);
+    }
+
+    it('does not strand the nested sublist with a doubled bullet', async () => {
+        const muya = bootMuya('* a\n\n* C\n  \n  - D\n');
+
+        emptyFirstItemThenDelete(muya);
+
+        await flush();
+        const markdown = muya.getMarkdown();
+        expect(markdown).not.toMatch(/\*\s+-\s+D/);
+        expect(markdown).toContain('  - D');
+    });
+
+    it('moves the merged text and sublist into the first item and drops the empty one', async () => {
+        const muya = bootMuya('* a\n\n* C\n  \n  - D\n');
+
+        emptyFirstItemThenDelete(muya);
+
+        await flush();
+        const state = muya.getState();
+        expect(state.length).toBe(1);
+        const list = state[0] as { name: string; children: unknown[] };
+        expect(list.name).toBe('bullet-list');
+        expect(list.children.length).toBe(1);
+        const item = list.children[0] as { name: string; children: unknown[] };
+        expect(item.name).toBe('list-item');
+        expect(item.children[0]).toMatchObject({ name: 'paragraph', text: 'C' });
+        expect(item.children[1]).toMatchObject({ name: 'bullet-list' });
+        const sublist = item.children[1] as { children: Array<{ children: unknown[] }> };
+        expect(sublist.children[0].children[0]).toMatchObject({
+            name: 'paragraph',
+            text: 'D',
+        });
+    });
+});
+
 describe('forward Delete at end of a code block — no merge', () => {
     it('leaves the state unchanged (codeBlockContent has no merging deleteHandler)', async () => {
         const muya = bootMuya('```js\nx\n```\n');

From bfb7a5341b4fa3ef6d72bec8911e2dcbe5cce044 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 13:31:45 +0800
Subject: [PATCH 05/12] fix(muya): rebuild nested wrapper raw when toggling an
 inner inline format off (#2063) (#4727)

Removing the inner format from a nested run (e.g. un-italicizing
bold-italic `***foo***`) was a silent no-op. `clearFormat` splices the
inner token's children up into the surrounding wrapper's `children` array,
but the wrapper's cached `raw` is left stale; `generator` then serialized
that unchanged raw, so the text never lost the inner markers.

Add an opt-in `rebuildWrappers` mode to `generator` that reconstructs a
marker-wrapped token (strong/em/del/html_tag) from its children instead of
trusting `raw`, and use it from the three `format()` serialization points.
`backspaceHandler`, which deliberately trims a marker char off `token.raw`,
keeps the default raw-verbatim behavior.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../block/base/__tests__/formatToggle.spec.ts | 30 +++++++++++++++++++
 packages/muya/src/block/base/format.ts        |  6 ++--
 packages/muya/src/inlineRenderer/lexer.ts     | 26 ++++++++++++++--
 3 files changed, 57 insertions(+), 5 deletions(-)

diff --git a/packages/muya/src/block/base/__tests__/formatToggle.spec.ts b/packages/muya/src/block/base/__tests__/formatToggle.spec.ts
index ea3415d7dc..377ab6cd10 100644
--- a/packages/muya/src/block/base/__tests__/formatToggle.spec.ts
+++ b/packages/muya/src/block/base/__tests__/formatToggle.spec.ts
@@ -140,6 +140,36 @@ describe('format.format() toggle-off with the caret inside the formatted run', (
     });
 });
 
+// #2063 — toggling the INNER format off a nested run (e.g. removing italic from
+// bold-italic `***foo***`). `clearFormat` splices the inner token's children up
+// into the ancestor wrapper's `children` array, but the ancestor's cached `raw`
+// goes stale; the serializer must rebuild the wrapper from its children, not
+// trust that raw, or the toggle is a silent no-op.
+describe('format.format() toggle-off the inner format of a nested run (#2063)', () => {
+    it('em inside strong: selecting `foo` in `***foo***` un-italics to `**foo**`', () => {
+        // Raw offsets: `bar ***foo*** bar` → `foo` spans 7..10 (inside both the
+        // strong 4..13 and the em 6..11 token ranges).
+        const content = selectInFirstBlock(bootMuya('bar ***foo*** bar\n'), 7, 10);
+        content.format('em');
+        expect(content.text).toBe('bar **foo** bar');
+    });
+
+    it('the un-italic also drops the inner markers from the serialized markdown', async () => {
+        const muya = bootMuya('bar ***foo*** bar\n');
+        selectInFirstBlock(muya, 7, 10).format('em');
+        await vi.waitFor(() => {
+            expect(muya.getMarkdown().trim()).toBe('bar **foo** bar');
+        });
+    });
+
+    it('strong inside del: selecting `b` in `~~a **b** a~~` un-bolds to `~~a b a~~`', () => {
+        // `~~a **b** a~~`: the strong `**b**` raw spans 5..10, text `b` at 7..8.
+        const content = selectInFirstBlock(bootMuya('~~a **b** a~~\n'), 7, 8);
+        content.format('strong');
+        expect(content.text).toBe('~~a b a~~');
+    });
+});
+
 describe('format.format() apply-ON over a non-collapsed selection', () => {
     it('strong: selecting `abc` and applying wraps it in `**…**`', async () => {
         const muya = bootMuya('abc\n');
diff --git a/packages/muya/src/block/base/format.ts b/packages/muya/src/block/base/format.ts
index 831e03a888..63a2de0b95 100644
--- a/packages/muya/src/block/base/format.ts
+++ b/packages/muya/src/block/base/format.ts
@@ -1631,7 +1631,7 @@ class Format extends Content {
             start.offset += start.delta;
             end.offset += end.delta;
 
-            this.text = generator(tokens);
+            this.text = generator(tokens, true);
         }
         else if (currentFormats.length) {
             for (const token of currentFormats)
@@ -1639,7 +1639,7 @@ class Format extends Content {
 
             start.offset += start.delta;
             end.offset += end.delta;
-            this.text = generator(tokens);
+            this.text = generator(tokens, true);
         }
         else {
             if (currentNeighbors.length) {
@@ -1649,7 +1649,7 @@ class Format extends Content {
 
             start.offset += start.delta;
             end.offset += end.delta;
-            this.text = generator(tokens);
+            this.text = generator(tokens, true);
 
             this._addFormat(type, { start, end });
 
diff --git a/packages/muya/src/inlineRenderer/lexer.ts b/packages/muya/src/inlineRenderer/lexer.ts
index 91b9430ed5..66bc84d829 100644
--- a/packages/muya/src/inlineRenderer/lexer.ts
+++ b/packages/muya/src/inlineRenderer/lexer.ts
@@ -900,11 +900,33 @@ export function tokenizer(src: string, {
 
 // transform `tokens` to text ignore the range of token
 // the opposite of tokenizer
-export function generator(tokens: Token[]) {
+// Rebuild a marker-wrapped token from its children instead of its stale cached
+// `raw` (#2063). Link/image keep their stored raw.
+function rebuildWrapperToken(token: Token): string {
+    switch (token.type) {
+        case 'strong':
+        case 'em':
+        case 'del':
+            return token.marker + generator(token.children, true) + token.marker;
+
+        case 'html_tag':
+            if (token.openTag != null && token.closeTag != null && token.children != null)
+                return token.openTag + generator(token.children, true) + token.closeTag;
+
+            return token.raw;
+
+        default:
+            return token.raw;
+    }
+}
+
+// `rebuildWrappers` is opt-in: only `format()` mutates a wrapper's children;
+// `backspaceHandler` trims a marker off `raw` and needs it echoed verbatim.
+export function generator(tokens: Token[], rebuildWrappers = false) {
     let result = '';
 
     for (const token of tokens)
-        result += token.raw;
+        result += rebuildWrappers ? rebuildWrapperToken(token) : token.raw;
 
     return result;
 }

From f2178a1035d0eec58f9e68d9e749f04243ead875 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 14:04:10 +0800
Subject: [PATCH 06/12] docs: add commenting guidelines (#4738)

* docs: add commenting guidelines and link from CONTRIBUTING

Add a Commenting Guidelines document distilled from A Philosophy of
Software Design (ch. 12-16) and reference it from the contributing
guide's style section so reviewers check new and changed comments
against it.

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

* docs: require comment review per commenting guidelines in CLAUDE.md

Point Claude at .github/COMMENTING-GUIDELINES.md so generated code
follows the same rule and its comments are reviewed before finishing
a change.

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/COMMENTING-GUIDELINES.md | 148 +++++++++++++++++++++++++++++++
 .github/CONTRIBUTING.md          |   5 ++
 CLAUDE.md                        |   4 +
 3 files changed, 157 insertions(+)
 create mode 100644 .github/COMMENTING-GUIDELINES.md

diff --git a/.github/COMMENTING-GUIDELINES.md b/.github/COMMENTING-GUIDELINES.md
new file mode 100644
index 0000000000..4d17097297
--- /dev/null
+++ b/.github/COMMENTING-GUIDELINES.md
@@ -0,0 +1,148 @@
+# Commenting Guidelines
+
+Distilled from John Ousterhout's *A Philosophy of Software Design* (ch. 12–16).
+One rule governs everything below:
+
+> **Comments should describe things that aren't obvious from the code.**
+
+A comment captures what was in the designer's mind but couldn't be expressed in
+the code itself — the rationale, the constraints, the abstraction. If a comment
+only restates the code, it has no value.
+
+---
+
+## What goes in a comment
+
+There is real design information that code cannot express: the informal meaning
+of a method, the units of a value, why a line exists, the rule the author
+followed ("always call `a` before `b`"). Comments exist to record exactly this.
+
+Comments also make abstraction possible. An abstraction hides complexity so you
+can use a module without reading its implementation — and the only way to
+describe an abstraction is in prose. Without comments, the sole abstraction of a
+function is its signature, which leaves out too much to be useful (does
+`substring(start, end)` include `end`? what if `start > end`?).
+
+So a comment is good when it sits at a **different level of detail** than the
+code: either lower (more precise) or higher (more intuitive). A comment at the
+same level as the code is just restating it.
+
+---
+
+## Rules
+
+**Don't repeat the code.** Before keeping a comment, ask: *could someone write
+this just by looking at the code next to it?* If yes, delete it. A special case
+of this: don't build the comment out of the words already in the name —
+`// Normalize the resource name` above `getNormalizedResourceName()` adds nothing.
+
+**Lower-level comments add precision.** Most valuable on declarations —
+instance variables, parameters, return values, where the name and type aren't
+enough. Spell out: units; whether bounds are inclusive or exclusive; what `null`
+means if allowed; who owns/frees a resource; any invariant ("this list always
+has at least one entry"). Describe what a variable *is*, not how the code
+mutates it — think nouns, not verbs.
+
+**Higher-level comments add intuition.** One sentence on what a block *does* and
+why, omitting the mechanics. A reader who has that sentence can explain the rest
+of the code themselves — and judge whether it's correct. These are harder to
+write: ask yourself "what is the simplest thing I can say that explains
+everything here?"
+
+**Separate interface from implementation comments.** Interface comments tell a
+caller what they need to use the thing — they *are* the abstraction.
+Implementation comments explain how it works inside. Never let one leak into the
+other. A caller should not have to read a method's body to call it correctly.
+
+  - *Class:* the abstraction it provides, what an instance represents, its
+    limitations. No method-by-method detail.
+  - *Method:* behavior from the caller's view; every parameter and the return
+    value, precisely; side effects; exceptions; preconditions. Keep
+    preconditions few, but document the ones that remain.
+  - The test for any fact: *does a caller need it to use this?* Wire formats,
+    internal data structures, transparent crash recovery — no, those are
+    implementation. A comparison being string-vs-integer, or whether requests
+    fire concurrently (affects performance) — yes.
+
+**Implementation comments say what and why, not how.** Most short methods need
+none. For longer ones, put a high-level line before each major block or
+non-trivial loop. Always explain anything subtle the code can't show — a
+bug-fix whose purpose isn't obvious gets a comment (reference the issue rather
+than restating it: `// Fixes #436 — autolink overrun on pasted URLs`).
+
+**Cross-module decisions need a findable home.** When a decision spans several
+files, document it where developers will actually trip over it — e.g. at the enum
+declaration they must edit, list every other place that needs updating. If
+there's no natural center, keep a `designNotes` file and point to it from each
+site (`// See "Zombies" in designNotes`).
+
+---
+
+## Write the comments first
+
+Comments written last are bad comments: by then you've checked out mentally, your
+memory of the design is fuzzy, and you write them by reading the code — so they
+repeat it.
+
+Instead, for a new class:
+
+1. Write the class interface comment.
+2. Write interface comments and signatures for the key public methods; leave the
+   bodies empty.
+3. Iterate until the structure feels right.
+4. Write declarations and comments for the key instance variables.
+5. Fill in the bodies, adding implementation comments as needed.
+
+When the code is done, the comments are done — there's no backlog. And it costs
+almost nothing: typing code and comments together is a small fraction of total
+development time.
+
+**A comment is a complexity detector.** The comment for a method or variable
+should be short *and* complete. If you can't write one that's both, the thing
+you're describing is probably badly designed — that's the signal to fix the
+design, not the comment.
+
+> 🚩 If the interface comment has to describe the implementation, the method is
+> too shallow. 🚩 If a comment merely repeats the code, it's noise. 🚩 If
+> something is hard to describe, the design has a problem.
+
+---
+
+## Keep them alive
+
+**Put the comment next to the code it describes.** The farther away, the less
+likely it gets updated. A method's interface comment belongs right by its body,
+not in a separate header. Push implementation comments down to the narrowest
+scope they cover rather than stacking them at the top. As a corollary: the
+farther a comment is from its code, the more abstract it should be.
+
+**Comments belong in the code, not the commit log.** If a future developer will
+need the information, put it where they'll see it. A commit message explaining a
+subtle fix is invisible to the next person who "simplifies" it back into a bug.
+
+**Don't duplicate.** Document each decision once, in the most obvious place, and
+reference it from the others. Don't re-document one module inside another, and
+don't restate things already in an external spec or manual — link to them.
+
+**Check the diff before committing.** Scan every change and confirm the
+surrounding comments still hold. This also catches stray debug code and stale
+TODOs.
+
+**Higher-level comments are easier to maintain** — they survive minor code
+changes because they don't depend on details. Reserve precise, detailed comments
+for the places that genuinely need them.
+
+---
+
+## Names are documentation too (ch. 14)
+
+A good name reduces the need for comments. Make names **precise** — `getCount()`
+counts *what*? — and make them **paint an image** of what the thing is and isn't,
+in two or three words. A single vague name once cost the author a six-month bug
+hunt: `block` meant both a disk block and a file block; `diskBlock` / `fileBlock`
+would have prevented it. Don't settle for "close enough."
+
+---
+
+**The test for any comment:** is it something you *couldn't* read off the code,
+and is it both short and complete?
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 30b36037d5..33b6928388 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -10,6 +10,7 @@ We are really excited that you are interested in contributing to MarkText :tada:
 - [Quick start](#quick-start)
   - [Build instructions](#build-instructions)
   - [Style guide](#style-guide)
+  - [Commenting guidelines](#commenting-guidelines)
 - [Developer documentation](#developer-documentation)
 
 ## Philosophy
@@ -87,6 +88,10 @@ You can run ESLint (`pnpm run lint`) to help you to follow the style guide.
 - no semicolons
 - documentation: [JSDoc](https://github.com/jsdoc/jsdoc) 
 
+### Commenting Guidelines
+
+When writing comments, please follow our [Commenting Guidelines](./COMMENTING-GUIDELINES.md). In short: a comment should describe what isn't obvious from the code — the rationale, units, invariants, and abstractions — rather than restating it. Reviewers check new and changed comments against these guidelines.
+
 ## Developer Documentation
 
 Please [click here](https://marktext.me/docs/dev/overview) for more details.
diff --git a/CLAUDE.md b/CLAUDE.md
index ea575424c0..374e3349d5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -221,6 +221,10 @@ Enforced by ESLint + Prettier. Run `pnpm run lint` and `pnpm run typecheck` befo
 - IPC channels are typed via the contract in `packages/desktop/src/shared/types/ipc.ts`
 - The renderer is fully sandboxed — every IPC and Node access goes through `window.electron.*` / `window.fileUtils.*` etc. (typed in `packages/desktop/src/types/global.d.ts`)
 
+### Comments
+
+Follow `.github/COMMENTING-GUIDELINES.md` for every comment you write. The core rule: a comment must describe what isn't obvious from the code — rationale, units, invariants, ownership, the abstraction a caller needs — never restate the code or echo the words already in the name. Before finishing any change, review the comments you added or touched against that document, and delete any that only repeat the code. Prefer self-explanatory names over comments; when a comment is genuinely needed, keep it short and complete and place it next to the code it describes.
+
 ## Architecture: Three-Process Electron Model
 
 All Electron processes live in `packages/desktop/`. Muya is a separate

From ca063503d2e1b6c699249ffdf0155e9d8b17317b Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 14:04:35 +0800
Subject: [PATCH 07/12] fix(muya): escape parentheses in inserted image paths
 so they don't truncate (#3060) (#4728)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A markdown image destination ends at the first unbalanced `)` (CommonMark),
so inserting an image whose file path contains a parenthesis — e.g.
`/home/user/My Photos)/photo.png` — produced `![](/home/user/My%20Photos)/...)`
whose URL was cut at the `)`, dropping the rest of the path into plain text.

The five image-insert sites each percent-encoded only spaces and `#`. Extract
a shared `encodeImageSrc` helper that also percent-encodes `(`/`)` (note
`encodeURIComponent` leaves parentheses untouched, so they are encoded
explicitly) and route every site through it. The encoded path is decoded again
when the image loads, so the file still resolves.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/__tests__/imageInsertEscape.spec.ts   | 80 +++++++++++++++++++
 packages/muya/src/block/base/format.ts        |  9 +--
 packages/muya/src/clipboard/pasteImage.ts     | 16 ++--
 packages/muya/src/muya.ts                     |  3 +-
 packages/muya/src/utils/image.ts              | 11 +++
 5 files changed, 101 insertions(+), 18 deletions(-)
 create mode 100644 packages/muya/src/__tests__/imageInsertEscape.spec.ts

diff --git a/packages/muya/src/__tests__/imageInsertEscape.spec.ts b/packages/muya/src/__tests__/imageInsertEscape.spec.ts
new file mode 100644
index 0000000000..d514eba836
--- /dev/null
+++ b/packages/muya/src/__tests__/imageInsertEscape.spec.ts
@@ -0,0 +1,80 @@
+// @vitest-environment happy-dom
+
+import type Format from '../block/base/format';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { tokenizer } from '../inlineRenderer/lexer';
+import { Muya } from '../muya';
+
+// #3060 — an image whose file path contains a parenthesis must escape it, or the
+// unbalanced `)` terminates the markdown image destination early (CommonMark:
+// the destination ends at the first unbalanced `)`), truncating the path and
+// spilling the tail into plain text. `insertImage` already percent-encodes
+// spaces and `#`; parentheses belong to the same class.
+
+const bootedHosts: HTMLElement[] = [];
+let originalVersion: string | undefined;
+let hadVersion = false;
+
+beforeEach(() => {
+    hadVersion = 'MUYA_VERSION' in window;
+    originalVersion = window.MUYA_VERSION;
+    window.MUYA_VERSION = 'test';
+});
+
+afterEach(() => {
+    while (bootedHosts.length)
+        bootedHosts.pop()!.remove();
+    document.getSelection()?.removeAllRanges();
+    if (hadVersion)
+        window.MUYA_VERSION = originalVersion as string;
+    else
+        delete (window as Partial<Window>).MUYA_VERSION;
+});
+
+function bootMuya(markdown: string): Muya {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const muya = new Muya(host, { markdown } as ConstructorParameters<typeof Muya>[1]);
+    muya.init();
+    bootedHosts.push(muya.domNode);
+    return muya;
+}
+
+function insertImageAtStart(muya: Muya, src: string): Format {
+    const block = muya.editor.scrollPage!.firstContentInDescendant() as unknown as Format;
+    muya.editor.activeContentBlock = block as never;
+    block.setCursor(0, 0, true);
+    muya.insertImage({ src });
+    return block;
+}
+
+// Re-parse the block's markdown and return the single image token's destination,
+// decoded back to a real path. A truncated `)` would split the image so either
+// no image token is produced or its src stops short.
+function roundTripImageSrc(text: string): string {
+    const tokens = tokenizer(text, { options: {} as never });
+    const image = tokens.find(t => t.type === 'image');
+    if (!image)
+        throw new Error(`no image token parsed from ${JSON.stringify(text)}`);
+    return decodeURIComponent((image as { src: string }).src);
+}
+
+describe('insertImage escapes parentheses in the path (#3060)', () => {
+    it('an unbalanced `)` in the path round-trips instead of truncating', () => {
+        const muya = bootMuya('\n');
+        const block = insertImageAtStart(muya, '/home/user/My Photos)/photo.png');
+        expect(roundTripImageSrc(block.text)).toBe('/home/user/My Photos)/photo.png');
+    });
+
+    it('a `)` followed by a `(` round-trips', () => {
+        const muya = bootMuya('\n');
+        const block = insertImageAtStart(muya, '/a)b(c.png');
+        expect(roundTripImageSrc(block.text)).toBe('/a)b(c.png');
+    });
+
+    it('still encodes spaces and keeps balanced parens loadable', () => {
+        const muya = bootMuya('\n');
+        const block = insertImageAtStart(muya, '/a (b)/c.png');
+        expect(roundTripImageSrc(block.text)).toBe('/a (b)/c.png');
+    });
+});
diff --git a/packages/muya/src/block/base/format.ts b/packages/muya/src/block/base/format.ts
index 63a2de0b95..1926475377 100644
--- a/packages/muya/src/block/base/format.ts
+++ b/packages/muya/src/block/base/format.ts
@@ -28,7 +28,7 @@ import Selection, { getCursorReference } from '../../selection';
 import { getTextContent } from '../../selection/dom';
 import { isListItemState } from '../../state/types';
 import { conflict, isHTMLElement, isMouseEvent } from '../../utils';
-import { correctImageSrc, getImageInfo } from '../../utils/image';
+import { correctImageSrc, encodeImageSrc, getImageInfo } from '../../utils/image';
 import logger from '../../utils/logger';
 
 interface IOffset {
@@ -372,11 +372,8 @@ class Format extends Content {
                 imageText += alt;
 
             imageText += '](';
-            if (src) {
-                imageText += src
-                    .replace(/ /g, encodeURI(' '))
-                    .replace(/#/g, encodeURIComponent('#'));
-            }
+            if (src)
+                imageText += encodeImageSrc(src);
 
             if (title)
                 imageText += ` "${title}"`;
diff --git a/packages/muya/src/clipboard/pasteImage.ts b/packages/muya/src/clipboard/pasteImage.ts
index ec415046e5..51c10a57a6 100644
--- a/packages/muya/src/clipboard/pasteImage.ts
+++ b/packages/muya/src/clipboard/pasteImage.ts
@@ -5,7 +5,7 @@ import type Clipboard from './index';
 import { CLASS_NAMES } from '../config';
 import { SelectionType } from '../selection/types';
 import { getUniqueId } from '../utils';
-import { getImageInfo } from '../utils/image';
+import { encodeImageSrc, getImageInfo } from '../utils/image';
 import { readFileAsDataURL, resolveClipboardImagePath } from '../utils/paste';
 
 /**
@@ -15,7 +15,7 @@ import { readFileAsDataURL, resolveClipboardImagePath } from '../utils/paste';
  * Inline images in muya are plain markdown text (`![](src)`) on a content
  * block; rendering turns the token into an image. We replace any
  * collapsed/expanded range and place the cursor after it. The src is
- * escaped the same way as {@link Format.replaceImage} so spaces and `#`
+ * escaped via {@link encodeImageSrc} so spaces, `#`, and parentheses
  * survive in the path.
  */
 function insertImageText(anchorBlock: Content, src: string, alt = ''): string {
@@ -25,9 +25,7 @@ function insertImageText(anchorBlock: Content, src: string, alt = ''): string {
 
     const { start, end } = cursor;
     const { text: content } = anchorBlock;
-    const escapedSrc = src
-        .replace(/ /g, encodeURI(' '))
-        .replace(/#/g, encodeURIComponent('#'));
+    const escapedSrc = encodeImageSrc(src);
     const imageText = `![${alt}](${escapedSrc})`;
 
     anchorBlock.text
@@ -55,9 +53,7 @@ function replacePlaceholderImage(
     if (index === -1)
         return;
 
-    const escapedSrc = src
-        .replace(/ /g, encodeURI(' '))
-        .replace(/#/g, encodeURIComponent('#'));
+    const escapedSrc = encodeImageSrc(src);
     const imageText = `![](${escapedSrc})`;
 
     anchorBlock.text
@@ -187,9 +183,7 @@ function spliceImageText(
     src: string,
     alt = '',
 ): string {
-    const escapedSrc = src
-        .replace(/ /g, encodeURI(' '))
-        .replace(/#/g, encodeURIComponent('#'));
+    const escapedSrc = encodeImageSrc(src);
     const imageText = `![${alt}](${escapedSrc})`;
 
     block.text
diff --git a/packages/muya/src/muya.ts b/packages/muya/src/muya.ts
index a6e8125636..bb72cf90e6 100644
--- a/packages/muya/src/muya.ts
+++ b/packages/muya/src/muya.ts
@@ -31,6 +31,7 @@ import {
 import { isAnyListState, isAtxHeadingState, isCodeBlockState } from './state/types';
 import { Ui } from './ui/ui';
 import { deepClone } from './utils';
+import { encodeImageSrc } from './utils/image';
 import './assets/styles/blockSyntax.css';
 import './assets/styles/index.css';
 import './assets/styles/inlineSyntax.css';
@@ -994,7 +995,7 @@ export class Muya {
         else if (DATA_URL_REG.test(src))
             imgUrl = src;
         else
-            imgUrl = src.replace(/ /g, encodeURI(' ')).replace(/#/g, encodeURIComponent('#'));
+            imgUrl = encodeImageSrc(src);
 
         const { start, end } = cursor;
         const { text } = block;
diff --git a/packages/muya/src/utils/image.ts b/packages/muya/src/utils/image.ts
index 401e77f39d..28ae86fa3f 100644
--- a/packages/muya/src/utils/image.ts
+++ b/packages/muya/src/utils/image.ts
@@ -177,6 +177,17 @@ export async function checkImageContentType(url: string) {
     }
 }
 
+// Percent-encode the chars that break a markdown image destination — an
+// unbalanced `)` truncates the path (#3060). `encodeURIComponent` leaves `(`/`)`
+// untouched, so encode them explicitly.
+export function encodeImageSrc(src: string): string {
+    return src
+        .replace(/ /g, encodeURI(' '))
+        .replace(/#/g, encodeURIComponent('#'))
+        .replace(/\(/g, '%28')
+        .replace(/\)/g, '%29');
+}
+
 export function correctImageSrc(src: string) {
     if (src) {
     // Fix ASCII and UNC paths on Windows (#1997).

From 0823599e23b0ca18c9d6e80f49fe954aa85cba28 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 14:27:41 +0800
Subject: [PATCH 08/12] fix(muya): decode HTML entities in a fetched page title
 when pasting a URL (#2525) (#4729)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copying a bare URL from a browser pastes a markdown link whose anchor text is
the page `<title>`. `getPageTitle` plucked the title with a raw regex, so HTML
entities in it (e.g. `&ndash;`, `&uuml;`) were assigned verbatim as the link's
textContent and showed up literally as `&ndash;` / `&uuml;` in the document.

Parse the fetched body with `DOMParser` (inert — no script/resource loading)
and read the `<title>` element's textContent, which decodes the entities. The
existing getPageTitle spec ran in the node env; it now declares the jsdom env
since the helper legitimately needs the DOM (its sibling normalizePastedHTML
already does).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/utils/__tests__/getPageTitle.spec.ts  |  2 +
 .../__tests__/pasteUrlTitleEntities.spec.ts   | 48 +++++++++++++++++++
 packages/muya/src/utils/paste.ts              | 10 ++--
 3 files changed, 55 insertions(+), 5 deletions(-)
 create mode 100644 packages/muya/src/utils/__tests__/pasteUrlTitleEntities.spec.ts

diff --git a/packages/muya/src/utils/__tests__/getPageTitle.spec.ts b/packages/muya/src/utils/__tests__/getPageTitle.spec.ts
index b0b65c7437..ed95c85c71 100644
--- a/packages/muya/src/utils/__tests__/getPageTitle.spec.ts
+++ b/packages/muya/src/utils/__tests__/getPageTitle.spec.ts
@@ -1,3 +1,5 @@
+// @vitest-environment jsdom
+
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 // Regression for marktext commit 141d25d8 (#1344).
diff --git a/packages/muya/src/utils/__tests__/pasteUrlTitleEntities.spec.ts b/packages/muya/src/utils/__tests__/pasteUrlTitleEntities.spec.ts
new file mode 100644
index 0000000000..d7351db5af
--- /dev/null
+++ b/packages/muya/src/utils/__tests__/pasteUrlTitleEntities.spec.ts
@@ -0,0 +1,48 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getPageTitle, normalizePastedHTML } from '../paste';
+
+// #2525 — copying a bare URL from a browser pastes a markdown link whose anchor
+// text is the page `<title>`. The title is fetched as raw HTML, so entities such
+// as `&ndash;` / `&uuml;` must be decoded before they become the link text;
+// otherwise the literal `&ndash;` shows up in the document.
+function mockFetchReturningTitle(titleInnerHtml: string) {
+    const body = `<!doctype html><html><head><title>${titleInnerHtml}</title></head><body>x</body></html>`;
+    return vi.fn(async () => ({
+        status: 200,
+        headers: {
+            get: (h: string) => (h.toLowerCase() === 'content-type' ? 'text/html; charset=utf-8' : null),
+        },
+        text: async () => body,
+    }));
+}
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+
+describe('getPageTitle decodes HTML entities (#2525)', () => {
+    it('decodes named entities in the fetched page title', async () => {
+        vi.stubGlobal(
+            'fetch',
+            mockFetchReturningTitle('On Statistical Data Compression &ndash; Digitale Bibliothek Th&uuml;ringen'),
+        );
+
+        const title = await getPageTitle('https://www.db-thueringen.de/receive/dbt_mods_00027239');
+
+        expect(title).toBe('On Statistical Data Compression – Digitale Bibliothek Thüringen');
+    });
+
+    it('a pasted bare URL becomes a link whose anchor text has decoded entities', async () => {
+        vi.stubGlobal('fetch', mockFetchReturningTitle('Foo &ndash; B&uuml;cher'));
+
+        const out = await normalizePastedHTML(
+            '<a href="https://www.db-thueringen.de/x">https://www.db-thueringen.de/x</a>',
+        );
+
+        expect(out).toContain('Foo – Bücher');
+        expect(out).not.toContain('ndash');
+    });
+});
diff --git a/packages/muya/src/utils/paste.ts b/packages/muya/src/utils/paste.ts
index 116d392720..6faf512d27 100644
--- a/packages/muya/src/utils/paste.ts
+++ b/packages/muya/src/utils/paste.ts
@@ -45,13 +45,13 @@ export async function getPageTitle(url: string) {
         if (res.status !== 200 || !contentType || !/text\/html/i.test(contentType))
             return '';
 
-        // The response is HTML — read it as text and pluck `<title>`.
-        // Reading it as `res.json()` would always throw and make the helper
-        // silently return ''.
+        // Parse inertly and read `<title>` textContent, which decodes HTML
+        // entities so they don't leak into the pasted link text (#2525).
         const body = await res.text();
-        const match = body.match(/<title>([\s\S]*?)<\/title>/i);
+        const doc = new DOMParser().parseFromString(body, 'text/html');
+        const title = doc.querySelector('title')?.textContent?.trim();
 
-        return match && match[1] ? match[1].trim() : '';
+        return title || '';
     }
     catch {
         return '';

From 13491fde08e29afaa66ede43a4630b2e77fb6a79 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 14:46:30 +0800
Subject: [PATCH 09/12] fix(muya): reset search state when the document is
 replaced (#1932) (#4730)

Switching tabs replaces the document via `Editor.setContent`, which rebuilds
the block tree but left the Search module holding its old `matches`. Those
referenced detached blocks from the previous tab, so the search bar kept the
old match count and "Find Next" acted on orphaned blocks.

Add `Search.reset()` (clears value/matches/index) and call it from
`setContent` after the tree is rebuilt.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/muya/src/editor/index.ts             |  1 +
 .../__tests__/searchResetOnSetContent.spec.ts | 80 +++++++++++++++++++
 packages/muya/src/search/index.ts             |  8 ++
 3 files changed, 89 insertions(+)
 create mode 100644 packages/muya/src/search/__tests__/searchResetOnSetContent.spec.ts

diff --git a/packages/muya/src/editor/index.ts b/packages/muya/src/editor/index.ts
index a040dd4637..60e046bdfd 100644
--- a/packages/muya/src/editor/index.ts
+++ b/packages/muya/src/editor/index.ts
@@ -499,6 +499,7 @@ export class Editor {
 
         this.scrollPage!.updateState(state);
         this.history.clear();
+        this.searchModule.reset();
 
         if (autoFocus)
             this.focus();
diff --git a/packages/muya/src/search/__tests__/searchResetOnSetContent.spec.ts b/packages/muya/src/search/__tests__/searchResetOnSetContent.spec.ts
new file mode 100644
index 0000000000..34ac010074
--- /dev/null
+++ b/packages/muya/src/search/__tests__/searchResetOnSetContent.spec.ts
@@ -0,0 +1,80 @@
+// @vitest-environment happy-dom
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { Muya } from '../../muya';
+
+// #1932 — switching tabs replaces the document via `Editor.setContent`, which
+// rebuilds the block tree. The Search module kept its old `matches` (now
+// pointing at detached blocks) and its old match count/value, so the search bar
+// still showed the previous tab's results and "Find Next" operated on orphaned
+// blocks. setContent must reset the search state.
+
+const bootedHosts: HTMLElement[] = [];
+let originalVersion: string | undefined;
+let hadVersion = false;
+
+beforeEach(() => {
+    hadVersion = 'MUYA_VERSION' in window;
+    originalVersion = window.MUYA_VERSION;
+    window.MUYA_VERSION = 'test';
+});
+
+afterEach(() => {
+    while (bootedHosts.length)
+        bootedHosts.pop()!.remove();
+    document.getSelection()?.removeAllRanges();
+    if (hadVersion)
+        window.MUYA_VERSION = originalVersion as string;
+    else
+        delete (window as Partial<Window>).MUYA_VERSION;
+});
+
+function bootMuya(markdown: string): Muya {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const muya = new Muya(host, { markdown } as ConstructorParameters<typeof Muya>[1]);
+    muya.init();
+    bootedHosts.push(muya.domNode);
+    return muya;
+}
+
+describe('search resets when the document content is replaced (#1932)', () => {
+    it('clears stale matches/index/value on setContent', () => {
+        const muya = bootMuya('foo foo foo\n');
+        const search = muya.editor.searchModule;
+        search.search('foo');
+        expect(search.matches.length).toBe(3);
+        expect(search.value).toBe('foo');
+
+        muya.editor.setContent('bar baz\n');
+
+        expect(search.matches).toEqual([]);
+        expect(search.index).toBe(-1);
+        expect(search.value).toBe('');
+    });
+
+    it('find next after a tab switch is a no-op (no stale matches to act on)', () => {
+        const muya = bootMuya('foo foo\n');
+        const search = muya.editor.searchModule;
+        search.search('foo');
+        expect(search.matches.length).toBe(2);
+
+        muya.editor.setContent('unrelated content\n');
+
+        expect(() => search.find('next')).not.toThrow();
+        expect(search.matches).toEqual([]);
+        expect(search.index).toBe(-1);
+    });
+
+    it('a fresh search after setContent finds matches in the new document', () => {
+        const muya = bootMuya('foo\n');
+        const search = muya.editor.searchModule;
+        search.search('foo');
+
+        muya.editor.setContent('foo foo\n');
+        search.search('foo');
+
+        expect(search.matches.length).toBe(2);
+        expect(search.matches.every(m => m.block.parent !== null)).toBe(true);
+    });
+});
diff --git a/packages/muya/src/search/index.ts b/packages/muya/src/search/index.ts
index 8b52bda25f..521824d300 100644
--- a/packages/muya/src/search/index.ts
+++ b/packages/muya/src/search/index.ts
@@ -21,6 +21,14 @@ export class Search {
 
     constructor(private _muya: Muya) {}
 
+    // Drop match state when the document is replaced (e.g. a tab switch), so
+    // stale matches don't reference the previous document's blocks (#1932).
+    reset() {
+        this._value = '';
+        this.matches = [];
+        this.index = -1;
+    }
+
     private _updateMatches(isClear = false) {
         const { matches, index } = this;
         let i;

From 0b52b6904560dd0541948168cdf423ca309d35a4 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 14:54:41 +0800
Subject: [PATCH 10/12] fix(muya): split on Enter over a cross-block selection
 instead of corrupting the DOM (#2443) (#4735)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The document-level cross-block keydown handler only `preventDefault()`ed
Backspace/Delete. For Enter it ran `cutHandler()` (deleting the selection) but
let the browser's native Enter fire on top, splitting/`<br>`-corrupting the
contenteditable — the selection collapsed with no usable new paragraph.

Handle Enter explicitly: suppress the native key, delete the selection via
`cutHandler()`, then split at the collapsed caret through the active block's
`enterHandler` — mirroring the same-block selection+Enter behaviour. A
Shift+Enter is left as a plain deletion (no soft break) rather than corrupting.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../tests/editing/cross-block-enter.spec.ts   | 47 +++++++++++++++++++
 packages/muya/src/clipboard/index.ts          | 12 +++++
 2 files changed, 59 insertions(+)
 create mode 100644 packages/muya/e2e/tests/editing/cross-block-enter.spec.ts

diff --git a/packages/muya/e2e/tests/editing/cross-block-enter.spec.ts b/packages/muya/e2e/tests/editing/cross-block-enter.spec.ts
new file mode 100644
index 0000000000..4423684bc7
--- /dev/null
+++ b/packages/muya/e2e/tests/editing/cross-block-enter.spec.ts
@@ -0,0 +1,47 @@
+import { expect, test } from '../fixtures/muya';
+import { getMarkdown } from '../helpers/api';
+import { loadMarkdown } from '../helpers/keyboard';
+import { editor } from '../helpers/selectors';
+
+// #2443 — pressing Enter while a selection spans two blocks. The cross-block
+// keydown handler only `preventDefault()`ed Backspace/Delete, so the browser's
+// native Enter ran on top of the model edit and split/`<br>`-corrupted the
+// contenteditable. Enter should behave like the same-block case: delete the
+// selection and split at the caret into a new paragraph.
+
+async function selectAcrossParagraphs(
+    page: import('@playwright/test').Page,
+    startOffset: number,
+    endOffset: number,
+): Promise<void> {
+    await page.evaluate(({ startOffset, endOffset }) => {
+        const paras = document.querySelectorAll('.mu-paragraph');
+        const firstText = (el: Element): Text => {
+            const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+            return walker.nextNode() as Text;
+        };
+        const n1 = firstText(paras[0]);
+        const n2 = firstText(paras[1]);
+        const range = document.createRange();
+        range.setStart(n1, startOffset);
+        range.setEnd(n2, endOffset);
+        const sel = window.getSelection()!;
+        sel.removeAllRanges();
+        sel.addRange(range);
+        document.dispatchEvent(new Event('selectionchange'));
+    }, { startOffset, endOffset });
+}
+
+test.describe('cross-block selection + Enter (#2443)', () => {
+    test('replaces the selection with a paragraph break, not native DOM corruption', async ({ page }) => {
+        await loadMarkdown(page, 'Hello world\n\nFoo bar\n');
+        await page.locator(editor.paragraph).first().click();
+
+        // Select "world\n\nFoo": from after "Hello " (p1 offset 6) to after
+        // "Foo" (p2 offset 3).
+        await selectAcrossParagraphs(page, 6, 3);
+        await page.keyboard.press('Enter');
+
+        expect(await getMarkdown(page)).toBe('Hello \n\n bar\n');
+    });
+});
diff --git a/packages/muya/src/clipboard/index.ts b/packages/muya/src/clipboard/index.ts
index d9c6032637..784f007554 100644
--- a/packages/muya/src/clipboard/index.ts
+++ b/packages/muya/src/clipboard/index.ts
@@ -1,5 +1,6 @@
 import type { Muya } from '../muya';
 import type { IClipboardPayload } from './copyData';
+import Format from '../block/base/format';
 import { isClipboardEvent, isKeyboardEvent } from '../utils';
 import { getClipboardData, writeClipboardData } from './copyData';
 import { cutSelection, deleteTableSelection } from './cut';
@@ -81,6 +82,17 @@ class Clipboard {
             if (!shouldCrossBlockCut(key, metaKey, event.ctrlKey))
                 return;
 
+            // Enter over a cross-block selection: suppress the corrupting native
+            // Enter and mirror the same-block path — delete then split (#2443).
+            if (key === 'Enter') {
+                event.preventDefault();
+                this.cutHandler();
+                const block = this.muya.editor.activeContentBlock;
+                if (!event.shiftKey && block instanceof Format)
+                    block.enterHandler(event);
+                return;
+            }
+
             if (key === 'Backspace' || key === 'Delete')
                 event.preventDefault();
 

From ca9c27e1adc881325ecc4582cb5cbad4131b3791 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 15:19:49 +0800
Subject: [PATCH 11/12] fix(muya): let Enter pass through to the block when
 only the format toolbar is shown (#3196) (#4736)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Selecting text pops the InlineFormatToolbar, which declared
`capturesContentKeydown = true`. The UI keydown gate then returned `true`
(blocking the block handler) for any shown float on a content-nav key, so
pressing Enter over a selection did nothing — it was never deleted or split.

Two coordinated changes:
- `Ui.handleContentKeydown` now blocks the block handler only when a shown
  float actually captures the key (a navigated menu/picker), not merely
  because some float is open.
- The InlineFormatToolbar is passive (it never navigates with Enter/Tab/
  arrows), so it opts out with `capturesContentKeydown = false`.

Navigated menus (quick-insert, emoji, table/code pickers) still capture
their nav keys and are unaffected.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../block/base/__tests__/formatToggle.spec.ts | 22 +++++++++++++++++++
 .../__tests__/uiHandleContentKeydown.spec.ts  |  6 +++--
 .../muya/src/ui/inlineFormatToolbar/index.ts  |  4 +++-
 packages/muya/src/ui/ui.ts                    |  7 +++++-
 4 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/packages/muya/src/block/base/__tests__/formatToggle.spec.ts b/packages/muya/src/block/base/__tests__/formatToggle.spec.ts
index 377ab6cd10..bdc82e61b2 100644
--- a/packages/muya/src/block/base/__tests__/formatToggle.spec.ts
+++ b/packages/muya/src/block/base/__tests__/formatToggle.spec.ts
@@ -282,6 +282,28 @@ function makeFakeEvent(): Event {
     } as unknown as Event;
 }
 
+// #3196 — the inline format toolbar pops up on any text selection. It must be a
+// passive (non-capturing) float, otherwise the UI keydown gate swallows Enter
+// while it is shown and a selection can no longer be replaced with a line break.
+describe('inline format toolbar is a passive float (#3196)', () => {
+    it('does not capture content keydown, so Enter passes through the UI gate', () => {
+        const muya = bootMuya('hello world\n');
+        const toolbar = new InlineFormatToolbar(muya);
+
+        expect(toolbar.capturesContentKeydown).toBe(false);
+
+        // Simulate the toolbar being the only shown float (as it is whenever
+        // text is selected) and assert the gate lets Enter through.
+        muya.ui.shownFloat.add(toolbar as unknown as Parameters<typeof muya.ui.shownFloat.add>[0]);
+        const event = { key: 'Enter', preventDefault: vi.fn() } as unknown as KeyboardEvent;
+
+        expect(muya.ui.handleContentKeydown(event)).toBe(false);
+        expect(event.preventDefault).not.toHaveBeenCalled();
+
+        toolbar.destroy();
+    });
+});
+
 describe('format picker collapses after link creation', () => {
     it('selecting the link button runs content.format(\'link\') and hides the picker', () => {
         const muya = bootMuya('abc\n');
diff --git a/packages/muya/src/ui/__tests__/uiHandleContentKeydown.spec.ts b/packages/muya/src/ui/__tests__/uiHandleContentKeydown.spec.ts
index ee5a65e201..5e8eda6165 100644
--- a/packages/muya/src/ui/__tests__/uiHandleContentKeydown.spec.ts
+++ b/packages/muya/src/ui/__tests__/uiHandleContentKeydown.spec.ts
@@ -38,12 +38,14 @@ describe('ui.handleContentKeydown', () => {
         expect(event.preventDefault).not.toHaveBeenCalled();
     });
 
-    it('skips block handling but does not preventDefault for a non-capturing float', () => {
+    it('lets the block handle the key (and does not preventDefault) for a non-capturing float (#3196)', () => {
+        // A passive float (e.g. the inline format toolbar shown on selection)
+        // must not block Enter/Tab/arrows from reaching the block handler.
         const ui = makeUi();
         ui.shownFloat.add(fakeFloat(false));
         const event = keyEvent('Enter');
 
-        expect(ui.handleContentKeydown(event)).toBe(true);
+        expect(ui.handleContentKeydown(event)).toBe(false);
         expect(event.preventDefault).not.toHaveBeenCalled();
     });
 
diff --git a/packages/muya/src/ui/inlineFormatToolbar/index.ts b/packages/muya/src/ui/inlineFormatToolbar/index.ts
index 9aec4a0d48..0923119e4a 100644
--- a/packages/muya/src/ui/inlineFormatToolbar/index.ts
+++ b/packages/muya/src/ui/inlineFormatToolbar/index.ts
@@ -56,7 +56,9 @@ const NON_EDITING_KEYS = new Set([
  */
 export class InlineFormatToolbar extends BaseFloat {
     static pluginName = 'formatPicker';
-    public override capturesContentKeydown = true;
+    // Passive float: must not capture nav keys, or Enter over a selection is
+    // swallowed while it's shown (#3196).
+    public override capturesContentKeydown = false;
 
     /** Previous virtual node for patching */
     private _oldVNode: VNode | null = null;
diff --git a/packages/muya/src/ui/ui.ts b/packages/muya/src/ui/ui.ts
index 549992ae87..77d22474c6 100644
--- a/packages/muya/src/ui/ui.ts
+++ b/packages/muya/src/ui/ui.ts
@@ -48,13 +48,18 @@ export class Ui {
             return false;
         }
 
+        // Block the content handler only when a shown float actually captures
+        // the key; a passive float (e.g. the format toolbar) must let it through
+        // so Enter/Tab/arrows over a selection still work (#3196).
+        let captured = false;
         for (const tool of this.shownFloat) {
             if (tool.capturesContentKeydown) {
                 event.preventDefault();
+                captured = true;
                 break;
             }
         }
 
-        return true;
+        return captured;
     }
 }

From 4a3d89883a1799aac0041a467afa13d6329b61b4 Mon Sep 17 00:00:00 2001
From: Ran Luo <luoran1988@126.com>
Date: Fri, 26 Jun 2026 15:27:57 +0800
Subject: [PATCH 12/12] fix(muya): stop trailing punctuation after a link from
 wrapping to its own line (#2258, #3025) (#4737)

With the caret outside a link, its `](url)` markers render as zero-size
`.mu-hide.mu-remove` spans. As `inline-block` (atomic) boxes they introduce
soft-wrap opportunities between the link and the following text, so a trailing
period/comma could break onto its own line.

Render the hidden syntax markers as plain `inline` text instead (kept invisible
with `font-size: 0`, with `white-space: nowrap` so the hidden URL's own break
characters don't re-introduce the wrap). Scoped to `.mu-remove` so the
preview-bearing `.mu-hide` variants (math/ruby/emoji) keep their inline-block
layout.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../inline/link-punctuation-wrap.spec.ts      | 37 +++++++++++++++++++
 .../muya/src/assets/styles/inlineSyntax.css   | 15 ++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 packages/muya/e2e/tests/inline/link-punctuation-wrap.spec.ts

diff --git a/packages/muya/e2e/tests/inline/link-punctuation-wrap.spec.ts b/packages/muya/e2e/tests/inline/link-punctuation-wrap.spec.ts
new file mode 100644
index 0000000000..32bf4058ac
--- /dev/null
+++ b/packages/muya/e2e/tests/inline/link-punctuation-wrap.spec.ts
@@ -0,0 +1,37 @@
+import { expect, test } from '../fixtures/muya';
+
+// #2258 / #3025 — punctuation right after a link wraps to its own line. With the
+// caret outside a link its `](url)` markers render as zero-size `.mu-hide
+// .mu-remove` spans. As `inline-block` (atomic) boxes they introduce soft-wrap
+// opportunities between the link and the following text, so a trailing period
+// can break onto its own line. This drives the REAL stylesheet rule: a hidden
+// marker sandwiched between a word and a period, in a container just wide enough
+// for the word, must not push the period to a new line.
+
+test.describe('punctuation after a link does not wrap (#2258/#3025)', () => {
+    test('a zero-size hidden marker introduces no wrap opportunity before a period', async ({ page }) => {
+        await page.goto('http://localhost:5174/');
+
+        const sameLine = await page.evaluate(() => {
+            const host = document.createElement('div');
+            host.style.cssText = 'position:absolute;top:0;left:0;font-size:16px;line-height:1.5;white-space:normal;';
+            host.innerHTML
+                = '<span id="w">aaaa</span>'
+                + '<span class="mu-hide mu-remove">](http://example.com)</span>'
+                + '<span id="d">.</span>';
+            document.body.appendChild(host);
+
+            const w = document.getElementById('w')!;
+            // Just wide enough for the word — the period is the only overflow
+            // candidate, so it wraps iff a break opportunity exists before it.
+            host.style.width = `${Math.ceil(w.getBoundingClientRect().width) + 2}px`;
+
+            const wTop = Math.round(w.getBoundingClientRect().top);
+            const dTop = Math.round(document.getElementById('d')!.getBoundingClientRect().top);
+            host.remove();
+            return dTop <= wTop;
+        });
+
+        expect(sameLine).toBe(true);
+    });
+});
diff --git a/packages/muya/src/assets/styles/inlineSyntax.css b/packages/muya/src/assets/styles/inlineSyntax.css
index a7ed455ec1..cb4e3e1099 100644
--- a/packages/muya/src/assets/styles/inlineSyntax.css
+++ b/packages/muya/src/assets/styles/inlineSyntax.css
@@ -14,6 +14,21 @@
     vertical-align: middle;
 }
 
+/* Hide syntax markers as zero-size `inline` text, not `inline-block` — atomic
+   boxes create a wrap opportunity that breaks punctuation after a link onto its
+   own line (#2258 / #3025). `nowrap` stops the hidden URL's `/`,`.` from
+   wrapping. Scoped to `.mu-remove` so math/ruby/emoji previews keep inline-block. */
+.mu-hide.mu-remove,
+.mu-hide.mu-remove .mu-highlight,
+.mu-hide.mu-remove .mu-selection {
+    display: inline;
+    width: auto;
+    height: auto;
+
+    font-size: 0;
+    white-space: nowrap;
+}
+
 /* link and auto-link and reference link */
 a.mu-inline-rule,
 span.mu-inline-rule.mu-link {