@hamster-note/notes 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (251) hide show
  1. package/README.md +205 -59
  2. package/dist/index.cjs +227 -57
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.js +42042 -22960
  5. package/dist/index.js.map +1 -1
  6. package/dist/lib/editor/HnnDataDrawer.d.ts +18 -0
  7. package/dist/lib/editor/HnnDataDrawer.d.ts.map +1 -0
  8. package/dist/lib/editor/HostReferenceUI.d.ts +22 -0
  9. package/dist/lib/editor/HostReferenceUI.d.ts.map +1 -0
  10. package/dist/lib/editor/MarkdownExport.d.ts +29 -0
  11. package/dist/lib/editor/MarkdownExport.d.ts.map +1 -0
  12. package/dist/lib/editor/NoteEditor.d.ts +19 -0
  13. package/dist/lib/editor/NoteEditor.d.ts.map +1 -0
  14. package/dist/lib/editor/NoteSaveStatus.d.ts +22 -0
  15. package/dist/lib/editor/NoteSaveStatus.d.ts.map +1 -0
  16. package/dist/lib/editor/blockMenu.d.ts +19 -0
  17. package/dist/lib/editor/blockMenu.d.ts.map +1 -0
  18. package/dist/lib/editor/blockReorder.d.ts +77 -0
  19. package/dist/lib/editor/blockReorder.d.ts.map +1 -0
  20. package/dist/lib/editor/hostReferenceInteractions.d.ts +34 -0
  21. package/dist/lib/editor/hostReferenceInteractions.d.ts.map +1 -0
  22. package/dist/lib/editor/hostReferences.d.ts +40 -0
  23. package/dist/lib/editor/hostReferences.d.ts.map +1 -0
  24. package/dist/lib/editor/nativeClipboard.d.ts +8 -0
  25. package/dist/lib/editor/nativeClipboard.d.ts.map +1 -0
  26. package/dist/lib/editor/pictureUpload.d.ts +27 -0
  27. package/dist/lib/editor/pictureUpload.d.ts.map +1 -0
  28. package/dist/lib/editor/session.d.ts +71 -0
  29. package/dist/lib/editor/session.d.ts.map +1 -0
  30. package/dist/lib/editor/sessionKey.d.ts +6 -0
  31. package/dist/lib/editor/sessionKey.d.ts.map +1 -0
  32. package/dist/lib/editor/types.d.ts +143 -0
  33. package/dist/lib/editor/types.d.ts.map +1 -0
  34. package/dist/lib/hnn/budgetedTransaction.d.ts +44 -0
  35. package/dist/lib/hnn/budgetedTransaction.d.ts.map +1 -0
  36. package/dist/lib/hnn/cardPayload.d.ts +48 -0
  37. package/dist/lib/hnn/cardPayload.d.ts.map +1 -0
  38. package/dist/lib/hnn/codec.d.ts +21 -0
  39. package/dist/lib/hnn/codec.d.ts.map +1 -0
  40. package/dist/lib/hnn/directoryEntries.d.ts +12 -0
  41. package/dist/lib/hnn/directoryEntries.d.ts.map +1 -0
  42. package/dist/lib/hnn/drawingPayload.d.ts +26 -0
  43. package/dist/lib/hnn/drawingPayload.d.ts.map +1 -0
  44. package/dist/lib/hnn/extensions.d.ts +50 -0
  45. package/dist/lib/hnn/extensions.d.ts.map +1 -0
  46. package/dist/lib/hnn/limits.d.ts +30 -0
  47. package/dist/lib/hnn/limits.d.ts.map +1 -0
  48. package/dist/lib/hnn/markdown.d.ts +29 -0
  49. package/dist/lib/hnn/markdown.d.ts.map +1 -0
  50. package/dist/lib/hnn/menuPopover.d.ts +46 -0
  51. package/dist/lib/hnn/menuPopover.d.ts.map +1 -0
  52. package/dist/lib/hnn/nodeId.d.ts +20 -0
  53. package/dist/lib/hnn/nodeId.d.ts.map +1 -0
  54. package/dist/lib/hnn/persistedStringBudget.d.ts +21 -0
  55. package/dist/lib/hnn/persistedStringBudget.d.ts.map +1 -0
  56. package/dist/lib/hnn/schema.d.ts +6 -0
  57. package/dist/lib/hnn/schema.d.ts.map +1 -0
  58. package/dist/lib/hnn/stringBytes.d.ts +29 -0
  59. package/dist/lib/hnn/stringBytes.d.ts.map +1 -0
  60. package/dist/lib/hnn/tableEdgeControls.d.ts +39 -0
  61. package/dist/lib/hnn/tableEdgeControls.d.ts.map +1 -0
  62. package/dist/lib/hnn/urlPolicy.d.ts +8 -0
  63. package/dist/lib/hnn/urlPolicy.d.ts.map +1 -0
  64. package/dist/lib/index.d.ts +6 -6
  65. package/dist/lib/index.d.ts.map +1 -1
  66. package/dist/styles.css +1 -1
  67. package/package.json +13 -8
  68. package/dist/lib/BlockActionMenu.d.ts +0 -55
  69. package/dist/lib/BlockActionMenu.d.ts.map +0 -1
  70. package/dist/lib/BlockActionMenuTypes.d.ts +0 -23
  71. package/dist/lib/BlockActionMenuTypes.d.ts.map +0 -1
  72. package/dist/lib/BottomBlockControls.d.ts +0 -17
  73. package/dist/lib/BottomBlockControls.d.ts.map +0 -1
  74. package/dist/lib/CardInspector.d.ts +0 -10
  75. package/dist/lib/CardInspector.d.ts.map +0 -1
  76. package/dist/lib/CardLinkOverlay.d.ts +0 -13
  77. package/dist/lib/CardLinkOverlay.d.ts.map +0 -1
  78. package/dist/lib/LinkMentionMenu.d.ts +0 -9
  79. package/dist/lib/LinkMentionMenu.d.ts.map +0 -1
  80. package/dist/lib/NoteBlockEditingControls.d.ts +0 -20
  81. package/dist/lib/NoteBlockEditingControls.d.ts.map +0 -1
  82. package/dist/lib/NoteBlockFocus.d.ts +0 -15
  83. package/dist/lib/NoteBlockFocus.d.ts.map +0 -1
  84. package/dist/lib/NoteCalloutBlock.d.ts +0 -10
  85. package/dist/lib/NoteCalloutBlock.d.ts.map +0 -1
  86. package/dist/lib/NoteCardBlock.d.ts +0 -10
  87. package/dist/lib/NoteCardBlock.d.ts.map +0 -1
  88. package/dist/lib/NoteChecklistBlock.d.ts +0 -10
  89. package/dist/lib/NoteChecklistBlock.d.ts.map +0 -1
  90. package/dist/lib/NoteCodeEditorBlock.d.ts +0 -10
  91. package/dist/lib/NoteCodeEditorBlock.d.ts.map +0 -1
  92. package/dist/lib/NoteCollapsibleBlock.d.ts +0 -10
  93. package/dist/lib/NoteCollapsibleBlock.d.ts.map +0 -1
  94. package/dist/lib/NoteContent.d.ts +0 -9
  95. package/dist/lib/NoteContent.d.ts.map +0 -1
  96. package/dist/lib/NoteContentBlocks.d.ts +0 -6
  97. package/dist/lib/NoteContentBlocks.d.ts.map +0 -1
  98. package/dist/lib/NoteContentEditing.d.ts +0 -58
  99. package/dist/lib/NoteContentEditing.d.ts.map +0 -1
  100. package/dist/lib/NoteDirectoryBlock.d.ts +0 -10
  101. package/dist/lib/NoteDirectoryBlock.d.ts.map +0 -1
  102. package/dist/lib/NoteDrawingBlock.d.ts +0 -10
  103. package/dist/lib/NoteDrawingBlock.d.ts.map +0 -1
  104. package/dist/lib/NoteFormulaBlock.d.ts +0 -10
  105. package/dist/lib/NoteFormulaBlock.d.ts.map +0 -1
  106. package/dist/lib/NoteListBlock.d.ts +0 -12
  107. package/dist/lib/NoteListBlock.d.ts.map +0 -1
  108. package/dist/lib/NoteParagraphBlock.d.ts +0 -12
  109. package/dist/lib/NoteParagraphBlock.d.ts.map +0 -1
  110. package/dist/lib/NotePictureBlock.d.ts +0 -10
  111. package/dist/lib/NotePictureBlock.d.ts.map +0 -1
  112. package/dist/lib/NoteQuoteBlock.d.ts +0 -11
  113. package/dist/lib/NoteQuoteBlock.d.ts.map +0 -1
  114. package/dist/lib/NoteTableBlock.d.ts +0 -5
  115. package/dist/lib/NoteTableBlock.d.ts.map +0 -1
  116. package/dist/lib/NoteTextBlockLayouts.d.ts +0 -27
  117. package/dist/lib/NoteTextBlockLayouts.d.ts.map +0 -1
  118. package/dist/lib/NoteTextBlocks.d.ts +0 -11
  119. package/dist/lib/NoteTextBlocks.d.ts.map +0 -1
  120. package/dist/lib/NoteTodoBlock.d.ts +0 -11
  121. package/dist/lib/NoteTodoBlock.d.ts.map +0 -1
  122. package/dist/lib/PictureUploadMenuItem.d.ts +0 -9
  123. package/dist/lib/PictureUploadMenuItem.d.ts.map +0 -1
  124. package/dist/lib/SelectionPopover.d.ts +0 -28
  125. package/dist/lib/SelectionPopover.d.ts.map +0 -1
  126. package/dist/lib/TableDragHandle.d.ts +0 -15
  127. package/dist/lib/TableDragHandle.d.ts.map +0 -1
  128. package/dist/lib/TableOperationMenu.d.ts +0 -16
  129. package/dist/lib/TableOperationMenu.d.ts.map +0 -1
  130. package/dist/lib/blockContainerDom.d.ts +0 -11
  131. package/dist/lib/blockContainerDom.d.ts.map +0 -1
  132. package/dist/lib/blockContainerMove.d.ts +0 -17
  133. package/dist/lib/blockContainerMove.d.ts.map +0 -1
  134. package/dist/lib/blockConversion.d.ts +0 -57
  135. package/dist/lib/blockConversion.d.ts.map +0 -1
  136. package/dist/lib/blockDowngrade.d.ts +0 -21
  137. package/dist/lib/blockDowngrade.d.ts.map +0 -1
  138. package/dist/lib/blockDragBindingKey.d.ts +0 -3
  139. package/dist/lib/blockDragBindingKey.d.ts.map +0 -1
  140. package/dist/lib/blockDragDesktop.d.ts +0 -13
  141. package/dist/lib/blockDragDesktop.d.ts.map +0 -1
  142. package/dist/lib/blockDragDom.d.ts +0 -24
  143. package/dist/lib/blockDragDom.d.ts.map +0 -1
  144. package/dist/lib/blockDragTarget.d.ts +0 -15
  145. package/dist/lib/blockDragTarget.d.ts.map +0 -1
  146. package/dist/lib/blockDragTouch.d.ts +0 -17
  147. package/dist/lib/blockDragTouch.d.ts.map +0 -1
  148. package/dist/lib/blockEditing.d.ts +0 -36
  149. package/dist/lib/blockEditing.d.ts.map +0 -1
  150. package/dist/lib/blockSourceConversion.d.ts +0 -41
  151. package/dist/lib/blockSourceConversion.d.ts.map +0 -1
  152. package/dist/lib/blockSourceInsertion.d.ts +0 -17
  153. package/dist/lib/blockSourceInsertion.d.ts.map +0 -1
  154. package/dist/lib/blockSourceMove.d.ts +0 -39
  155. package/dist/lib/blockSourceMove.d.ts.map +0 -1
  156. package/dist/lib/blockSourceOperations.d.ts +0 -37
  157. package/dist/lib/blockSourceOperations.d.ts.map +0 -1
  158. package/dist/lib/blockSourceSplit.d.ts +0 -4
  159. package/dist/lib/blockSourceSplit.d.ts.map +0 -1
  160. package/dist/lib/cardData.d.ts +0 -6
  161. package/dist/lib/cardData.d.ts.map +0 -1
  162. package/dist/lib/cardGeometry.d.ts +0 -14
  163. package/dist/lib/cardGeometry.d.ts.map +0 -1
  164. package/dist/lib/drawingData.d.ts +0 -37
  165. package/dist/lib/drawingData.d.ts.map +0 -1
  166. package/dist/lib/editableSelection.d.ts +0 -6
  167. package/dist/lib/editableSelection.d.ts.map +0 -1
  168. package/dist/lib/externalNoteDrag.d.ts +0 -55
  169. package/dist/lib/externalNoteDrag.d.ts.map +0 -1
  170. package/dist/lib/externalNoteDropTarget.d.ts +0 -11
  171. package/dist/lib/externalNoteDropTarget.d.ts.map +0 -1
  172. package/dist/lib/inlineFormulaRendering.d.ts +0 -37
  173. package/dist/lib/inlineFormulaRendering.d.ts.map +0 -1
  174. package/dist/lib/inlineMarkdownShortcut.d.ts +0 -75
  175. package/dist/lib/inlineMarkdownShortcut.d.ts.map +0 -1
  176. package/dist/lib/inlineSelectionFormatting.d.ts +0 -164
  177. package/dist/lib/inlineSelectionFormatting.d.ts.map +0 -1
  178. package/dist/lib/markdownShortcut.d.ts +0 -71
  179. package/dist/lib/markdownShortcut.d.ts.map +0 -1
  180. package/dist/lib/noteAtomicMutation.d.ts +0 -5
  181. package/dist/lib/noteAtomicMutation.d.ts.map +0 -1
  182. package/dist/lib/noteBoundarySplice.d.ts +0 -6
  183. package/dist/lib/noteBoundarySplice.d.ts.map +0 -1
  184. package/dist/lib/noteClipboardBlockCodec.d.ts +0 -4
  185. package/dist/lib/noteClipboardBlockCodec.d.ts.map +0 -1
  186. package/dist/lib/noteClipboardLimits.d.ts +0 -4
  187. package/dist/lib/noteClipboardLimits.d.ts.map +0 -1
  188. package/dist/lib/noteClipboardRegionSlice.d.ts +0 -4
  189. package/dist/lib/noteClipboardRegionSlice.d.ts.map +0 -1
  190. package/dist/lib/noteClipboardSlices.d.ts +0 -35
  191. package/dist/lib/noteClipboardSlices.d.ts.map +0 -1
  192. package/dist/lib/noteContentUndoRedo.d.ts +0 -34
  193. package/dist/lib/noteContentUndoRedo.d.ts.map +0 -1
  194. package/dist/lib/noteId.d.ts +0 -3
  195. package/dist/lib/noteId.d.ts.map +0 -1
  196. package/dist/lib/noteNestedMutation.d.ts +0 -7
  197. package/dist/lib/noteNestedMutation.d.ts.map +0 -1
  198. package/dist/lib/notePointerSelection.d.ts +0 -6
  199. package/dist/lib/notePointerSelection.d.ts.map +0 -1
  200. package/dist/lib/noteRegionCodec.d.ts +0 -9
  201. package/dist/lib/noteRegionCodec.d.ts.map +0 -1
  202. package/dist/lib/noteSelectAll.d.ts +0 -2
  203. package/dist/lib/noteSelectAll.d.ts.map +0 -1
  204. package/dist/lib/noteSelectionRestore.d.ts +0 -14
  205. package/dist/lib/noteSelectionRestore.d.ts.map +0 -1
  206. package/dist/lib/noteSnapshotMutation.d.ts +0 -8
  207. package/dist/lib/noteSnapshotMutation.d.ts.map +0 -1
  208. package/dist/lib/noteStructuredClipboard.d.ts +0 -17
  209. package/dist/lib/noteStructuredClipboard.d.ts.map +0 -1
  210. package/dist/lib/noteStructuredPaste.d.ts +0 -10
  211. package/dist/lib/noteStructuredPaste.d.ts.map +0 -1
  212. package/dist/lib/noteStructuredTail.d.ts +0 -3
  213. package/dist/lib/noteStructuredTail.d.ts.map +0 -1
  214. package/dist/lib/noteTextFlow.d.ts +0 -23
  215. package/dist/lib/noteTextFlow.d.ts.map +0 -1
  216. package/dist/lib/noteTextOffset.d.ts +0 -4
  217. package/dist/lib/noteTextOffset.d.ts.map +0 -1
  218. package/dist/lib/noteTransferReplacement.d.ts +0 -10
  219. package/dist/lib/noteTransferReplacement.d.ts.map +0 -1
  220. package/dist/lib/quoteLineEditing.d.ts +0 -5
  221. package/dist/lib/quoteLineEditing.d.ts.map +0 -1
  222. package/dist/lib/restrictedHtml.d.ts +0 -7
  223. package/dist/lib/restrictedHtml.d.ts.map +0 -1
  224. package/dist/lib/syntaxHighlight.d.ts +0 -9
  225. package/dist/lib/syntaxHighlight.d.ts.map +0 -1
  226. package/dist/lib/tableDragPreview.d.ts +0 -15
  227. package/dist/lib/tableDragPreview.d.ts.map +0 -1
  228. package/dist/lib/tableDragTarget.d.ts +0 -13
  229. package/dist/lib/tableDragTarget.d.ts.map +0 -1
  230. package/dist/lib/tableEditing.d.ts +0 -35
  231. package/dist/lib/tableEditing.d.ts.map +0 -1
  232. package/dist/lib/tableKeyboardNavigation.d.ts +0 -14
  233. package/dist/lib/tableKeyboardNavigation.d.ts.map +0 -1
  234. package/dist/lib/tableMoveFocus.d.ts +0 -11
  235. package/dist/lib/tableMoveFocus.d.ts.map +0 -1
  236. package/dist/lib/types.d.ts +0 -302
  237. package/dist/lib/types.d.ts.map +0 -1
  238. package/dist/lib/useBlockDrag.d.ts +0 -11
  239. package/dist/lib/useBlockDrag.d.ts.map +0 -1
  240. package/dist/lib/useBlockEditing.d.ts +0 -9
  241. package/dist/lib/useBlockEditing.d.ts.map +0 -1
  242. package/dist/lib/useDraggedTouchClickSuppression.d.ts +0 -7
  243. package/dist/lib/useDraggedTouchClickSuppression.d.ts.map +0 -1
  244. package/dist/lib/useExternalNoteDrag.d.ts +0 -15
  245. package/dist/lib/useExternalNoteDrag.d.ts.map +0 -1
  246. package/dist/lib/useTableMoveFocus.d.ts +0 -11
  247. package/dist/lib/useTableMoveFocus.d.ts.map +0 -1
  248. package/dist/lib/useTableOperationMenus.d.ts +0 -19
  249. package/dist/lib/useTableOperationMenus.d.ts.map +0 -1
  250. package/dist/lib/utils.d.ts +0 -10
  251. package/dist/lib/utils.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,13 +1,17 @@
1
1
  # @hamster-note/notes
2
2
 
3
- 一个基于 React 19 和 Vite 的笔记内容组件库项目,包含可本地预览的 Demo 页面,以及基于 Git Tag 的 GitHub Actions 发布流程。
3
+ 一个基于 React 19 和 Vite 的笔记组件库,编辑内核为 TipTap/ProseMirror,持久化格式为 HNN,并支持 GFM + HamsterNote 围栏的 Markdown 导入/导出。包含可本地预览的 Demo 页面,以及基于 Git Tag 的 GitHub Actions 发布流程。
4
+
5
+ **[在线 Demo](https://hamsternote.github.io/notes/)**
4
6
 
5
7
  ## 特性
6
8
 
7
9
  - React 19 组件库入口,包名为 `@hamster-note/notes`
10
+ - 以 TipTap/ProseMirror 为唯一文档与交互内核:原生选区、剪贴板、撤销/重做
11
+ - HNN 持久化:`{ schemaVersion: 1, data: <ProseMirror JSON> }`,严格校验、无损往返
12
+ - 封闭 schema:不向宿主开放自定义扩展/schema 注入
8
13
  - 使用 Vite 构建库产物和 Demo 页面
9
- - TypeScript 6 beta 严格类型检查
10
- - ESLint + Prettier 代码质量与格式化
14
+ - TypeScript 6 beta 严格类型检查,ESLint + Prettier
11
15
  - 局域网可访问的本地开发服务器,端口 `9235`
12
16
  - GitHub CI 校验 + Tag 驱动 npm 发布
13
17
 
@@ -29,84 +33,226 @@ yarn build
29
33
  - `yarn build:lib` 生成组件库产物到 `dist/`
30
34
  - `yarn build:demo` 生成 Demo 静态站点到 `dist/demo/`
31
35
 
32
- ## 使用方式
36
+ ## 公共 API
33
37
 
34
- ```tsx
35
- import { NoteContent } from "@hamster-note/notes"
38
+ > ⚠️ **不兼容变更**:本版本整体替换了旧编辑内核。旧的 `NoteContent`、`NoteBlock` 等块模型 API、受限 HTML 渲染、自研 DOM 选区与专有剪贴板 MIME 已从包入口移除,且**不提供旧格式迁移或兼容层**。
39
+
40
+ 包入口仅导出以下内容:
41
+
42
+ - 组件:`NoteEditor`、`NoteSaveStatus`、`MarkdownExport`
43
+ - 编解码:`decodeHnn`、`encodeHnn`、`HnnCodecError`、`importMarkdown`、`exportMarkdown`
44
+ - 类型:新组件 props、HNN/Markdown codec 类型,以及宿主回调契约(`NoteSave*`、`InitialLoadError*`、`EditorSession*`、`PictureUpload*`、`HostReference*`、`HostCandidate*` 等)
45
+
46
+ ```ts
47
+ import {
48
+ NoteEditor,
49
+ decodeHnn,
50
+ encodeHnn,
51
+ HnnCodecError,
52
+ importMarkdown,
53
+ exportMarkdown,
54
+ type HnnDocument,
55
+ } from "@hamster-note/notes"
36
56
  import "@hamster-note/notes/styles.css"
37
57
  ```
38
58
 
39
- 如果使用公式块,再按需导入 KaTeX 样式:
59
+ ### 装载与编辑
60
+
61
+ `NoteEditor` 由 `documentId` 与 `loadKey` 共同定义一次编辑会话。`initialDocument` 的类型是 `unknown`:宿主只需传入 HNN 外壳(`{ schemaVersion: 1, data }`),**严格校验由库自身完成**,无需(也不应)在宿主侧预先构造内部文档。
40
62
 
41
63
  ```tsx
42
- import "@hamster-note/notes/formula.css"
64
+ import { NoteEditor, type HnnDocument, type NoteSave } from "@hamster-note/notes"
65
+ import "@hamster-note/notes/styles.css"
66
+
67
+ // 合法最小 HNN:schemaVersion 固定为 1,data 为 ProseMirror JSON;持久节点带合法 UUID nodeId。
68
+ const document: HnnDocument = {
69
+ schemaVersion: 1,
70
+ data: {
71
+ type: "doc",
72
+ content: [
73
+ {
74
+ type: "paragraph",
75
+ attrs: { nodeId: "123e4567-e89b-42d3-a456-426614174000" },
76
+ content: [{ type: "text", text: "你好" }],
77
+ },
78
+ ],
79
+ },
80
+ }
81
+
82
+ function Editor({
83
+ documentId,
84
+ loadKey,
85
+ revision,
86
+ onSave,
87
+ }: {
88
+ documentId: string
89
+ loadKey: string | number
90
+ revision?: string
91
+ onSave: NoteSave
92
+ }) {
93
+ return (
94
+ <NoteEditor
95
+ documentId={documentId}
96
+ loadKey={loadKey}
97
+ initialDocument={document}
98
+ initialRevision={revision}
99
+ onSave={onSave}
100
+ onChange={(snapshot) => {
101
+ // 每次文档变化都会收到完整 HNN 快照(仅通知,不代表已保存)
102
+ }}
103
+ onInitialLoadError={(error, { documentId, loadKey }) => {
104
+ // 初始 HNN 严格校验失败:库不会用损坏输入构造降级会话
105
+ }}
106
+ theme="light"
107
+ />
108
+ )
109
+ }
110
+ ```
111
+
112
+ 从任意外部输入得到可传入的 HNN:
113
+
114
+ ```ts
115
+ import { decodeHnn, encodeHnn } from "@hamster-note/notes"
116
+
117
+ // decodeHnn 是公开编解码函数,返回经严格校验的 ProseMirror doc,而不是 HNN 外壳;
118
+ // 需要可持久化 / 可装载的 HNN 时,必须再 encode 一次:
119
+ const hnn = encodeHnn(decodeHnn(unknownInput)) // 类型为 HnnDocument,可传 NoteEditor.initialDocument
120
+ ```
121
+
122
+ 会话语义:
123
+
124
+ - 同一 `documentId` 与 `loadKey` 下,后续 `initialDocument` **与 `initialRevision`** 的变化都会被忽略,不会覆盖用户当前编辑。
125
+ - 任一 `documentId` 或 `loadKey` 变化,都会以当次已验证 HNN 重建整个会话(文档、选区、撤销历史、baseline 全部重置)。
126
+ - 若新 `documentId`/`loadKey` 对应的初始 HNN 校验失败,**当前会话保持不变**(不会切到损坏文档),错误经 `onInitialLoadError` 通知宿主。
127
+ - 撤销/重做由库内封闭装配的 history 提供,宿主不能注入或替换 schema/extensions/history。
128
+
129
+ ### 保存(宿主 CAS)
130
+
131
+ ```ts
132
+ import type { NoteSave } from "@hamster-note/notes"
133
+
134
+ const onSave: NoteSave = async (snapshot, { documentId, baseRevision, signal }) => {
135
+ // 宿主必须以 documentId + baseRevision 实施 CAS,并对真实存储负责。
136
+ const result = await host.writeIfUnchanged(documentId, snapshot, baseRevision)
137
+ return result.conflict ? { kind: "conflict" } : { kind: "saved", revision: result.revision }
138
+ }
139
+ ```
140
+
141
+ - 保存回调签名:`onSave(snapshot, { documentId, baseRevision?, signal })`,返回 `{ kind: "saved", revision? }` 或 `{ kind: "conflict" }`。
142
+ - 每个会话同时最多一个在途保存(单飞)。
143
+ - `signal`/abort **只隔离库内状态**,不能替代宿主的原子存储事务;即使宿主忽略了 abort,陈旧请求仍可能落盘,因此必须靠宿主的 CAS 防御。
144
+ - 冲突不自动合并:库只暴露冲突态,由宿主以新的 `initialDocument` + 新 `loadKey` 重载远端,或按自身策略重试本地保存。
145
+ - Demo 宿主的 `hostStore` 演示了一个真实原子实现:每次保存与「模拟另一客户端写入」都在**同一个持久化 key 的排他 Web Lock 内**完成 read→compare→write;`saveWithCas`/`overwriteExternal` 因此是异步 API。
146
+ - Web Locks 仅在**安全上下文(HTTPS 或 localhost)**且浏览器支持时可用。若运行环境不提供 Web Locks,宿主**fail closed**:抛出显式错误且**绝不写入**,绝不降级为「read-check-write」这种非原子的伪 CAS。在线 Demo 即为 HTTPS/localhost 场景。
147
+
148
+ ### HNN 文档格式
149
+
150
+ ```ts
151
+ import { decodeHnn, encodeHnn, HnnCodecError } from "@hamster-note/notes"
152
+
153
+ try {
154
+ decodeHnn(unknownInput) // 严格校验
155
+ } catch (error) {
156
+ if (error instanceof HnnCodecError) {
157
+ // 未知 schemaVersion / 未知节点 / 未知 mark / 非法 attrs / 结构非法 一律硬错误
158
+ }
159
+ }
160
+ ```
161
+
162
+ - 完整 HNN v1 外壳的 UTF-8 编码上限为 **512 KiB**;此外还受树深度、节点总数、单 attr 大小等限制。
163
+ - 遇到未知 `schemaVersion`、未知节点类型、未知 mark、非法 attrs 或不满足 schema 的结构,一律抛出 `HnnCodecError`,**不提供降级或静默覆盖**;失败时不产生可保存的替代文档,原文保持不变。
164
+
165
+ ### Markdown 导入 / 导出
166
+
167
+ ```ts
168
+ import { importMarkdown, exportMarkdown } from "@hamster-note/notes"
169
+
170
+ const imported = importMarkdown(markdownText)
171
+ if (imported.document !== undefined) {
172
+ // 转成 HNN 可编辑文档;default 保存始终是 HNN
173
+ const hnn = imported.document
174
+ } else {
175
+ // imported.failure: "input-too-large" | "conversion-failed"
176
+ // 导入失败绝不替换源 Markdown;调用方保留原始输入
177
+ }
178
+
179
+ const exported = exportMarkdown(hnnDocument)
180
+ // exported.markdown 为 GFM + HamsterNote 围栏方言
181
+ // exported.diagnostics 列出无法无损表达而发生的降级;诊断非空时必须由用户显式确认后才交给宿主写出
43
182
  ```
44
183
 
45
- ## 撤销 / 恢复
184
+ - 导入:Markdown → ProseMirror doc;导出为可选能力,无法无损表达时**必须产出降级诊断**,不得静默降级。
185
+ - 保存默认始终写 HNN,Markdown 导出仅在用户显式触发并经诊断确认后调用宿主写出回调。
46
186
 
47
- `NoteContent` 的撤销/恢复历史由 `use-undo` 驱动,组件本身仍然保持受控语义。消费者可以使用 `useNoteContentUndoRedo` hook 管理标题、摘要和 blocks 的历史,并把控制器与组件 ref 绑定:
187
+ ### 图片上传(仅 `picture`)
48
188
 
49
189
  ```tsx
50
- import { useRef } from "react"
51
- import {
52
- NoteContent,
53
- useNoteContentUndoRedo,
54
- type NoteContentUndoRedoHandle,
55
- } from "@hamster-note/notes"
190
+ <NoteEditor
191
+ documentId={documentId}
192
+ loadKey={loadKey}
193
+ initialDocument={document}
194
+ onPictureUpload={async (file, { uploadId, attempt, signal }) => {
195
+ // 宿主必须按 uploadId 幂等;retry 时 uploadId 不变、attempt 递增
196
+ const uploaded = await host.uploadImage(file, { uploadId, attempt, signal })
197
+ return { src: uploaded.httpsUrl, alt: uploaded.alt } // src 必须是 http/https
198
+ }}
199
+ />
200
+ ```
56
201
 
57
- const undoRedo = useNoteContentUndoRedo({
58
- title: "Example",
59
- summary: "Editable summary",
60
- blocks: initialBlocks,
61
- })
62
-
63
- const noteRef = useRef<NoteContentUndoRedoHandle>(null)
64
-
65
- return (
66
- <>
67
- <button disabled={!undoRedo.canUndo} onClick={() => noteRef.current?.undo()}>
68
- Undo
69
- </button>
70
- <button disabled={!undoRedo.canRedo} onClick={() => noteRef.current?.redo()}>
71
- Redo
72
- </button>
73
- <NoteContent
74
- ref={noteRef}
75
- undoRedoController={undoRedo.controller}
76
- editable
77
- title={undoRedo.present.title}
78
- summary={undoRedo.present.summary}
79
- blocks={undoRedo.present.blocks}
80
- onTitleChange={undoRedo.setTitle}
81
- onSummaryChange={undoRedo.setSummary}
82
- onBlocksChange={undoRedo.setBlocks}
83
- onNoteTransaction={({ snapshot }) => undoRedo.commitTransaction(snapshot)}
84
- />
85
- </>
86
- )
202
+ - 每个文件一个稳定 `uploadId`,首次 `attempt` 为 1,retry 只递增 `attempt`;宿主应据此去重。
203
+ - 成功时宿主返回可持久化的 `http`/`https` `src` 与可选 `alt`;库仅以一个 transaction 写入图片。
204
+ - 上传临时态、文件、`uploadId`、`attempt` 均为内存/DOM 桥状态,**绝不进入 HNN**;失败可重试或取消。
205
+
206
+ ### 宿主引用(mention / resource / externalItem)
207
+
208
+ 文档只持久 `resourceId` 与展示 `name`(绝不写入解析内容),真实内容由宿主在运行时解析:
209
+
210
+ ```tsx
211
+ <NoteEditor
212
+ documentId={documentId}
213
+ loadKey={loadKey}
214
+ initialDocument={document}
215
+ onReferenceCandidates={async (kind, query, { documentId, signal }) =>
216
+ host.searchReferences(kind, query, { documentId, signal }) // [{ resourceId, name }]
217
+ }
218
+ onReferenceActivate={(reference, { documentId, signal }) => {
219
+ host.openReference(reference, { documentId, signal }) // 库不会自行跳转
220
+ }}
221
+ onReferenceResolve={async ({ kind, resourceId }, { documentId, signal }) =>
222
+ host.resolveReference(kind, resourceId, { documentId, signal }) // { label, description? } | null
223
+ }
224
+ />
87
225
  ```
88
226
 
89
- 该 hook 只管理 `NoteContent` 负责渲染的内容字段(`title`、`summary`、`blocks`)。Demo 中使用了自定义的全文档控制器,用来把 `tagLabel` 等外层字段也纳入同一份历史。
227
+ - 解析结果只用于运行时占位展示(`loading`/`resolved`/`missing`/`error`),**不写入文档、不接受 HTML**。
228
+ - 无回调时受控为空/缺失占位,不破坏文档;文档/baseline/history 不受影响。
229
+
230
+ ### 主题与公式样式
90
231
 
91
- ## 连续文本选区
232
+ ```tsx
233
+ <NoteEditor ... theme="dark" />
234
+ ```
92
235
 
93
- 标题、摘要和正文按阅读顺序组成同一条笔记文本流。普通富文本按字符参与选择;图片、画板、卡片、目录、独立公式块和表格行作为不可拆分的原子选择单元参与。代码块在笔记文本流中以纯文本参与,但仍通过独立的原生文本区域编辑,因此行内格式不会写入代码内容。
236
+ `theme` 仅切换 `hn-*` token 修饰类。公式渲染所需的 KaTeX 样式按需导入:
94
237
 
95
- `onNoteTransaction` 接收一次操作后的完整 `{ title, summary, blocks }` 快照和操作元数据。跨标题、摘要或正文字段的删除、剪切、替换和格式化只调用该回调一次,以保证宿主只观察到一个状态变化,并可将操作记为一个 undo/redo 历史项。未提供该回调时:
238
+ ```tsx
239
+ import "@hamster-note/notes/formula.css"
240
+ ```
96
241
 
97
- - 跨字段选择和复制仍然可用,但跨字段修改会被阻止。
98
- - 仅涉及正文的连续修改会降级为一次 `onBlocksChange` 调用。
99
- - 单一区域编辑继续使用 `onTitleChange`、`onSummaryChange` 或 `onBlocksChange`。
242
+ ## Demo
100
243
 
101
- 标题、摘要和正文富文本均使用字段级白名单净化的受限 HTML。标题和摘要支持粗体、斜体、下划线、删除线及行内代码;正文还支持安全链接、颜色和 HamsterNote 行内公式、mention 元数据。危险元素、事件属性和不安全 URL 会在渲染与提交边界移除。
244
+ ### 在线 Demo
102
245
 
103
- 连续选区复制会同时写入:
246
+ 访问 [https://hamsternote.github.io/notes/](https://hamsternote.github.io/notes/) 查看在线演示。
104
247
 
105
- - `text/plain`
106
- - `text/html`
107
- - `application/x-hamsternote-fragment+json`
248
+ ### 本地运行 Demo
108
249
 
109
- 内部 MIME 当前版本为 v2,按阅读顺序保存富文本内容块、代码块、原子选择单元和表格行。粘贴到另一个 HamsterNote 实例时会保留中间结构、重建持久化 ID,并将首尾文本片段与目标残片融合;外部剪贴板则使用净化后的 HTML 或转义的纯文本。
250
+ ```bash
251
+ yarn install
252
+ yarn dev
253
+ ```
254
+
255
+ 默认会在 `0.0.0.0:9235` 启动 Demo 页面。
110
256
 
111
257
  ## 发布规则
112
258