@@ -22,6 +22,7 @@
     "react-dom": "^19.1.0",
     "react-markdown": "^10.1.0",
     "rehype-katex": "^7.0.1",
+    "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0"
   },
 
@@ -41,11 +41,23 @@ describe("computeHeadingChanges（纯逻辑）", () => {
     expect(r.cursor).toBe(4 + 2 + 2); // 末行行首 + 首行插入 2 + 末行插入 2
   });
 
-  it("已是标题的行跳过不叠加", () => {
+  it("同级别标题行剥除标记（切回普通段）", () => {
+    const r = computeHeadingChanges(Text.of(["### 已有"]), 0, 0, 3);
+    expect(r.changes).toEqual([{ from: 0, to: 4, insert: "" }]);
+    expect(r.cursor).toBe(0);
+  });
+
+  it("不同级别标题行换级（剥旧标记+插新标记）", () => {
+    const r = computeHeadingChanges(Text.of(["## 已有"]), 0, 0, 1);
+    expect(r.changes).toEqual([{ from: 0, to: 3, insert: "# " }]);
+    expect(r.cursor).toBe(2);
+  });
+
+  it("混合选区：普通段插入 / 同级别剥除 / 不同级别换级", () => {
     const r = computeHeadingChanges(doc, 0, doc.length, 2);
-    // 第三行是标题跳过；其余三行插入
-    expect(r.changes).toHaveLength(3);
-    expect(r.changes.some((c) => c.insert === "### ")).toBe(false);
+    expect(r.changes).toHaveLength(4);
+    // 第三行 "### 已有标题" 换级为 "## "（替换 [行首, 行首+4)）
+    expect(r.changes[2]).toEqual({ from: doc.line(3).from, to: doc.line(3).from + 4, insert: "## " });
   });
 
   it("H6 边界：level 夹取 1..6", () => {
@@ -61,10 +73,13 @@ describe("computeHeadingChanges（纯逻辑）", () => {
     expect(r.cursor).toBe(2);
   });
 
-  it("全选已全是标题 → 无变更", () => {
-    const allHeadings = Text.of(["# a", "## b"]);
-    const r = computeHeadingChanges(allHeadings, 0, allHeadings.length, 3);
-    expect(r.changes).toHaveLength(0);
+  it("全选全部同级别 → 全部剥除", () => {
+    const allHeadings = Text.of(["# a", "# b"]);
+    const r = computeHeadingChanges(allHeadings, 0, allHeadings.length, 1);
+    expect(r.changes).toEqual([
+      { from: 0, to: 2, insert: "" },
+      { from: 4, to: 6, insert: "" },
+    ]);
   });
 
   it("CRLF 行尾文档正常处理", () => {
@@ -87,10 +102,20 @@ describe("headingCommand（真实 Command）", () => {
     view.destroy();
   });
 
-  it("已是标题 → 返回 false 无变化", () => {
+  it("同级别标题再点 → 取消回普通段", () => {
     const { view, docOf } = makeView("## 已有");
-    expect(headingCommand(2)(view)).toBe(false);
-    expect(docOf()).toBe("## 已有");
+    expect(headingCommand(2)(view)).toBe(true);
+    expect(docOf()).toBe("已有");
+    // 剥除后光标落新行行首
+    expect(view.state.selection.main.anchor).toBe(0);
+    view.destroy();
+  });
+
+  it("混合行选区：H1 行取消 / H2 行换级", () => {
+    const { view, docOf } = makeView("# a\n## b\nc");
+    view.dispatch({ selection: { anchor: 0, head: 7 } }); // 选 "# a\n## b"（到 'b' 前）
+    headingCommand(1)(view);
+    expect(docOf()).toBe("a\n# b\nc");
     view.destroy();
   });
 
 
@@ -1,16 +1,19 @@
 /**
- * headingCommand — CodeMirror 标题转换命令（v0.14 子项目 A）。
+ * headingCommand — CodeMirror 标题转换命令（v0.14 子项目 A / v0.15 切换语义）。
  *
  * @ai-context: 输入驱动（`## ` 即时生效）之外，工具栏按钮与 Ctrl+1/2/3 快捷键需要
- *              显式命令：对单行/多行选区逐行行首设置 `#`×level；已是标题的行跳过
- *              （重复按不叠加）；光标落末行标记后。不复用 markdownEdit.ts 的
- *              headingLines（字符串+offset 模型）——CM 原生 Text.lines + lineAt
- *              原生支持 CRLF 边界（spec §4.3）。computeHeadingChanges 纯逻辑可单测。
+ *              显式命令：对单行/多行选区逐行 set-or-toggle——行已精确等于所点级别
+ *              则剥掉 `#×level+空格` 切回普通段（v0.15 修复"点 H1 无取消"），
+ *              其他级别/普通段一律置为该级别（原"已是标题跳过"语义废弃——
+ *              按钮高亮态的取消承诺与跳过行为冲突；Overleaf/Obsidian 同款）。
+ *              不复用 markdownEdit.ts 的 headingLines（字符串+offset 模型）——
+ *              CM 原生 Text.lines + lineAt 原生支持 CRLF 边界（spec §4.3）。
+ *              computeHeadingChanges 纯逻辑可单测。
  */
 import { Text, type Extension } from "@codemirror/state";
 import { EditorView, keymap, type Command } from "@codemirror/view";
 
-/** 单行插入变更（行首插入 marker） */
+/** 单行变更（行首插 marker / 剥同级 marker / 换级 = 替换区间） */
 export interface HeadingChange {
   from: number;
   to: number;
@@ -19,13 +22,14 @@ export interface HeadingChange {
 
 export interface HeadingChangeResult {
   changes: HeadingChange[];
-  /** 转换后光标应落的位置（末行标记后） */
+  /** 转换后光标应落的位置（新文档坐标：末行标记后；剥除时落行首） */
   cursor: number;
 }
 
 /**
- * 计算标题转换变更集（纯逻辑）：选区范围 [from, to) 覆盖的每行行首插入
- * `#`×level + 空格；已是标题的行跳过。选区尾恰在行首时该行不纳入（对齐
+ * 计算标题转换变更集（纯逻辑）：选区范围 [from, to) 覆盖的每行逐行判定——
+ * 行已等于目标级别 → 删除 `#×level+空格`；已是其他级别 → 替换为该级别；
+ * 普通段 → 行首插入 `#×level+空格`。选区尾恰在行首时该行不纳入（对齐
  * textarea 版 headingLines 语义）。level 夹取 1..6。
  */
 export function computeHeadingChanges(
@@ -43,17 +47,34 @@ export function computeHeadingChanges(
     end -= 1;
   }
   const changes: HeadingChange[] = [];
-  let insertedBeforeEnd = 0;
-  let endLineGotMarker = false;
+  // 末行之前各行的净变更增量（插入为正、剥除/换级为负）——末行行首平移量
+  let deltaBeforeEnd = 0;
+  // 末行自身变换后光标在"新末行"内的落点（无变换=0；插入/换级=标记后）
+  let endCursorDelta = 0;
   for (let n = start; n <= end; n++) {
     const line = doc.line(n);
-    if (/^#{1,6}\s/.test(line.text)) continue; // 已是标题不叠加
-    changes.push({ from: line.from, to: line.from, insert: marker });
-    if (n < end) insertedBeforeEnd += marker.length;
-    else endLineGotMarker = true;
+    const m = /^(#{1,6})\s/.exec(line.text);
+    if (m) {
+      const cur = m[1].length;
+      if (cur === clamped) {
+        // 同级别 → 剥除（切换取消：H1 按 H1 → 普通段）
+        changes.push({ from: line.from, to: line.from + clamped + 1, insert: "" });
+        if (n < end) deltaBeforeEnd -= clamped + 1;
+      } else {
+        // 其他级别 → 剥旧标记 + 插新标记（净效果=换级）
+        changes.push({ from: line.from, to: line.from + cur + 1, insert: marker });
+        if (n < end) deltaBeforeEnd += marker.length - (cur + 1);
+        else endCursorDelta = marker.length;
+      }
+    } else {
+      // 普通段 → 行首插入
+      changes.push({ from: line.from, to: line.from, insert: marker });
+      if (n < end) deltaBeforeEnd += marker.length;
+      else endCursorDelta = marker.length;
+    }
   }
-  // 光标 = 末行行首 + 末行之前行累计插入 +（末行自身加标记则再 + 标记长）
-  const cursor = doc.line(end).from + insertedBeforeEnd + (endLineGotMarker ? marker.length : 0);
+  // 光标 = 新末行行首 + 末行落点（selection 坐标为新文档坐标）
+  const cursor = doc.line(end).from + deltaBeforeEnd + endCursorDelta;
   return { changes, cursor };
 }
 
 
@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+/**
+ * NoteMarkdown.test.tsx — 换行语义锁定（v0.15 remark-breaks）。
+ *
+ * @ai-context: 修复"编辑态换行、阅读态连上"——单换行（软换行）必须渲染为 <br>；
+ *              段落分隔（\n\n）仍是两段不产生 <br>；`\` 强断行语义保留。
+ *              锁契约防未来 remark 插件顺序回归。
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render } from "@testing-library/react";
+import type { Note } from "../types";
+import NoteMarkdown from "./NoteMarkdown";
+
+const note = (content: string): Note => ({
+  id: 1,
+  title: "标题",
+  content,
+  source: "session",
+  session_id: 42,
+  rule_version: null,
+  purify_stats: null,
+  tags: "[]",
+  properties: null,
+  pin: 0,
+  group_id: null,
+  created_at: 1,
+  updated_at: 2,
+});
+
+const noop = vi.fn();
+
+const renderMd = (content: string) =>
+  render(
+    <NoteMarkdown
+      note={note(content)}
+      searchQuery=""
+      onTaskToggle={noop}
+      onImageOpen={noop}
+    />,
+  );
+
+afterEach(() => cleanup());
+
+describe("NoteMarkdown 换行语义（v0.15 remark-breaks）", () => {
+  it("单换行渲染为 <br>（软换行=所见即所得）", () => {
+    const { container } = renderMd("第一行\n第二行");
+    expect(container.querySelector("br")).toBeTruthy();
+    expect(container.textContent).toContain("第一行");
+    expect(container.textContent).toContain("第二行");
+  });
+
+  it("段落分隔（空行）不产生 <br>，渲染为两个段落", () => {
+    const { container } = renderMd("甲段\n\n乙段");
+    expect(container.querySelector("br")).toBeNull();
+    expect(container.querySelectorAll("p")).toHaveLength(2);
+  });
+
+  it("反斜杠强断行保留为 <br>", () => {
+    const { container } = renderMd("第一行\\\n第二行");
+    expect(container.querySelector("br")).toBeTruthy();
+  });
+
+  it("列表项内单换行同样断行（符合直观）", () => {
+    const { container } = renderMd("- 项一\n续行内容");
+    const li = container.querySelector("li");
+    expect(li).toBeTruthy();
+    // br 打断文本节点——按整段文本断言（queryByText 全文匹配对打断文本失效）
+    expect((li as HTMLElement).textContent).toContain("续行内容");
+    expect((li as HTMLElement).querySelector("br")).toBeTruthy();
+  });
+});
@@ -16,6 +16,7 @@
 import { isValidElement, cloneElement, useMemo, useRef } from "react";
 import type { ReactElement, ReactNode } from "react";
 import ReactMarkdown from "react-markdown";
+import remarkBreaks from "remark-breaks";
 import remarkGfm from "remark-gfm";
 import remarkMath from "remark-math";
 import rehypeKatex from "rehype-katex";
@@ -152,7 +153,10 @@ export default function NoteMarkdown({ note, searchQuery, onTaskToggle, onOpenSe
 
   return (
     <ReactMarkdown
-      remarkPlugins={[remarkGfm, remarkMath, remarkMarkHighlight]}
+      // v0.15：remark-breaks——单换行（软换行）渲染为 <br>，与编辑态所见一致
+      // （CommonMark 标准语义是软换行=空格，导致"编辑态换行、阅读态连上"；
+      // 存量笔记内容零数据变更自动修复；`\` 与两空格强断行语义保留）
+      remarkPlugins={[remarkGfm, remarkMath, remarkMarkHighlight, remarkBreaks]}
       rehypePlugins={[rehypeKatex]}
       components={{
         // v0.14 B：==文本== 荧光笔（remark 插件产出 mark 节点；单色黄，浅/深主题通用）
 
@@ -30,18 +30,23 @@ describe("headingLines", () => {
     expect(r.selEnd).toBe(7);
   });
 
-  it("已是标题的行跳过不叠加（含末行为标题时光标落在末行行首）", () => {
-    // Arrange：第一行正文，第二行已是 H2（## ）——光标在第一行（offset 0）
+  it("切换语义：同级别剥除 / 不同级别换级 / 普通段插入", () => {
+    // Arrange：第一行正文，第二行已是 H2 —— 光标在第一行（offset 0）
     const current = "正文\n## 已有标题\n尾巴";
-    // Act：仅第一行转换
+    // Act：目标 H1——逐行独立判定：第一行插入；第二行不在选区不处理
     const r = headingLines(current, 0, 0, 1);
-    // Assert：第一行加 #；第二行保持 ##（不叠加成 ###）
+    // Assert
     expect(r.value).toBe("# 正文\n## 已有标题\n尾巴");
     expect(r.selStart).toBe(2);
-    // 多行选区含已标题行：末行（## ）不加标记，光标落在末行行首（3 + 前面插入 2）
-    const r2 = headingLines(current, 0, 4, 1);
-    expect(r2.value).toBe("# 正文\n## 已有标题\n尾巴");
-    expect(r2.selStart).toBe(5);
+    // 多行选区（0..5 覆盖前两行）：第一行插入 `# `；第二行 ## 换级为 #
+    const r2 = headingLines(current, 0, 5, 1);
+    expect(r2.value).toBe("# 正文\n# 已有标题\n尾巴");
+    // 光标 = 新末行行首（3 + 前面插入 2）+ 标记后（2）= 7
+    expect(r2.selStart).toBe(7);
+    // 同级别剥除：H1 行再点 H1 → 切回普通段，光标落行首
+    const r3 = headingLines("# 一级", 0, 0, 1);
+    expect(r3.value).toBe("一级");
+    expect(r3.selStart).toBe(0);
   });
 
   it("选区尾恰在行首：不含下一行（选中到上一行结尾止）", () => {