@hamster-note/notes 3.1.1 → 3.2.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 (34) hide show
  1. package/README.md +49 -0
  2. package/dist/index.cjs +81 -78
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.js +13068 -12517
  5. package/dist/index.js.map +1 -1
  6. package/dist/lib/editor/NoteDocumentProvider.d.ts.map +1 -1
  7. package/dist/lib/editor/NoteEditor.d.ts +13 -0
  8. package/dist/lib/editor/NoteEditor.d.ts.map +1 -1
  9. package/dist/lib/editor/blockMenu.d.ts +6 -1
  10. package/dist/lib/editor/blockMenu.d.ts.map +1 -1
  11. package/dist/lib/editor/blockReorder.d.ts +2 -2
  12. package/dist/lib/editor/blockReorder.d.ts.map +1 -1
  13. package/dist/lib/editor/documentSession.d.ts +7 -0
  14. package/dist/lib/editor/documentSession.d.ts.map +1 -1
  15. package/dist/lib/editor/documentTypes.d.ts +27 -1
  16. package/dist/lib/editor/documentTypes.d.ts.map +1 -1
  17. package/dist/lib/editor/hostReferences.d.ts +3 -1
  18. package/dist/lib/editor/hostReferences.d.ts.map +1 -1
  19. package/dist/lib/editor/interactionLayout.d.ts +7 -0
  20. package/dist/lib/editor/interactionLayout.d.ts.map +1 -0
  21. package/dist/lib/editor/interactionToolbar.d.ts +5 -0
  22. package/dist/lib/editor/interactionToolbar.d.ts.map +1 -0
  23. package/dist/lib/editor/pictureUpload.d.ts +6 -0
  24. package/dist/lib/editor/pictureUpload.d.ts.map +1 -1
  25. package/dist/lib/editor/session.d.ts.map +1 -1
  26. package/dist/lib/editor/textFormatting.d.ts +17 -0
  27. package/dist/lib/editor/textFormatting.d.ts.map +1 -0
  28. package/dist/lib/hnn/extensions.d.ts.map +1 -1
  29. package/dist/lib/hnn/menuPopover.d.ts +7 -0
  30. package/dist/lib/hnn/menuPopover.d.ts.map +1 -1
  31. package/dist/lib/index.d.ts +1 -1
  32. package/dist/lib/index.d.ts.map +1 -1
  33. package/dist/styles.css +1 -1
  34. package/package.json +1 -1
package/README.md CHANGED
@@ -35,6 +35,45 @@ yarn build
35
35
 
36
36
  ## 公共 API
37
37
 
38
+ ### 3.1.2 宿主引用失效与图片上传
39
+
40
+ `NoteDocumentProvider` 新增可选 `onPictureUpload?: PictureUploadHandler`。提供回调后,各 View 的图片选择、图片粘贴、外部拖入与失败重试/取消均可用;内部拖动不会重复上传。无回调保留原有行为。有到有的回调替换只影响未来 attempt;移除回调会 abort 并清理全部占位,再次提供无需重挂 Provider。
41
+
42
+ ```tsx
43
+ import type { NoteDocumentController, PictureUploadHandler } from "@hamster-note/notes"
44
+
45
+ export function refreshHighlight(controller: NoteDocumentController, resourceId: string) {
46
+ const expectedSessionId = controller.getState().identity?.sessionId
47
+ if (!expectedSessionId) return
48
+ if (!controller.invalidateReferences) throw new Error("Requires notes >= 3.1.2")
49
+ // 先更新宿主数据;若更换 React resolver prop,须在其提交后调用。
50
+ for (const kind of ["mention", "resource"] as const) {
51
+ const result = controller.invalidateReferences({ expectedSessionId,
52
+ scope: { kind: "reference", reference: { kind, resourceId } } })
53
+ if (result.kind !== "accepted") throw new Error(JSON.stringify(result))
54
+ }
55
+ // 全文:controller.invalidateReferences({ expectedSessionId, scope: { kind: "document" } })
56
+ }
57
+
58
+ export const upload: PictureUploadHandler = async (file, { uploadId, attempt, signal }) => {
59
+ const response = await fetch("/images", { method: "POST", body: file, signal,
60
+ headers: { "X-Upload-Id": uploadId, "X-Upload-Attempt": String(attempt) } })
61
+ if (!response.ok) throw new Error(`Upload failed: ${response.status}`)
62
+ // 示例宿主端点通过 Location 返回已上传图片的 http/https URL。
63
+ return { src: response.headers.get("Location") ?? "", alt: file.name }
64
+ }
65
+ ```
66
+
67
+ `invalidateReferences` 在 3.1.2 创建的 Controller 上始终存在;类型上可选以兼容旧结构 adapter。结果为 `accepted`、`noop(stale|not-ready)`、`abort(disposed)` 或 `failure(invalid-scope)`,携带 sessionId。`accepted` 仅表示已受理,异步终态见引用 DOM 的 `data-hnn-resolve-status`:null 为 missing,异常为 error,合法 label 为 resolved。按 kind/resourceId 精确失效或刷新当前文档全部引用;无匹配不发请求,无 View 时安全受理。旧请求收到 abort,忽略 signal 的迟到结果也无效。普通 rerender 或 resolver 函数身份变化不会自动重拉;稳定函数读取外部 store 时,更新 store 后可直接显式失效。
68
+
69
+ 刷新只改变运行时引用展示,保留 session、HNN、metadata、dirty、选区、焦点、共享 history 与保存基线,不触发 onChange/onSave;freeze 期间同样可刷新。不得靠 remount 或正文改写刷新引用。
70
+
71
+ 上传回调接收原始 File 和 `{ uploadId, attempt, signal }`,返回 Promise<{src, alt?}>。成功只接受经过 URL 与 HNN 预算校验的 http/https 地址;结果通过共享正文提交一次,peer 可 undo/redo。失败或非法地址显示失败,用户可重试(同 uploadId、递增 attempt、新 signal)或取消。取消、锚点删除、来源 View detach(即使同 viewId 重开)、Provider dispose、移除回调都会 abort;宿主忽略 signal 的迟到结果仍被隔离,远端资源回收由宿主处理。
72
+
73
+ 上传期间可保存已有持久正文,占位/File/uploadId/attempt 不进入 HNN;saved/clean **不代表上传完成,也不代表可以离开**。存在 uploading、failed 或待提交结果时会话替换被拒绝,freeze acquire 返回既有 failure/pending-edit 且不消费 requestId。完成或取消后可重试同请求;acquire 入队与持有任何 lease 期间禁止新上传/retry。card/drawing 草稿期间也禁止新上传/retry,但先前请求可返回:合法成功结果延后到草稿关闭后重新校验锚点并恰好提交一次,不重新上传;期间取消或卸载可清理。受控导航仍须成功取得自身 freeze lease 并等待保存;强制卸载不保证远端上传资源清理或未完成写入持久化。
74
+
75
+ 公共浏览器契约:`node scripts/check-public-host-browser.mjs`。同一根入口 fixture 也由 `node scripts/verify-pack-consumer.mjs <tarball> 3.1.2 <fresh-directory> --public-host` 在无源码 alias/私有导入的干净安装中运行。HAM-36 仍须升级正式包、接通失效调用后复跑 `hnn-references.spec.ts` 和真实宿主上传;本库验证不代替 Reader 验收。
76
+
38
77
  > ⚠️ **不兼容变更**:本版本整体替换了旧编辑内核。旧的 `NoteContent`、`NoteBlock` 等块模型 API、受限 HTML 渲染、自研 DOM 选区与专有剪贴板 MIME 已从包入口移除,且**不提供旧格式迁移或兼容层**。
39
78
 
40
79
  3.0.0 的公共入口继续保留,并新增共享文档会话:
@@ -190,6 +229,16 @@ Controller 仅公开状态、身份和判别结果,不公开 schema/Editor/tra
190
229
  历史选择性撤销探针单独运行 `corepack yarn test --config vitest.historical.config.ts`,保留一个已知失败;
191
230
  它不属于当前 A 契约,不得把该非零退出报告为全量通过。
192
231
 
232
+ ### 移动交互与下划线兼容性
233
+
234
+ 布局宽度 ≤840px 时隐藏 handle,正文支持 500ms 长按未聚焦顶层块排序,已聚焦块保留原生长按文字选择;未聚焦块从按下到拖动结束临时禁止文字选择,contextmenu 事件始终原生放行;移动聚焦块下方显示中文横向操作工具栏,>840px 的非空文字选区显示加粗、斜体、下划线工具栏。长按前位移超过 10px 会保留原生滚动;震动仅为浏览器可用时的一次 10ms 增强。
235
+
236
+ 下划线是封闭 schema 中的持久 `underline` mark,与加粗/斜体一起支持 HNN、HTML 剪贴板、共享历史及预算校验。HNN 外壳仍为 `schemaVersion:1`;既有不含下划线的文档继续可读,**旧 notes 消费者会拒绝含 underline 的新文档,需先升级消费者,不能直接用旧库无损回退**。Markdown 使用已有 `hamster-note-json-b64` 围栏保存下划线,不新增方言;默认保存流程不变。
237
+
238
+ Web 浏览器验收:`node scripts/check-mobile-interactions.mjs`(需已安装 Playwright Chromium)。脚本自动启动/关闭本仓库 Demo,覆盖 320/390/840/841/1440px、明暗主题、鼠标、键盘和浏览器真实触摸事件;结果、截图和 trace 写入 `evidence/ham124-*`。触摸来自 Chromium CDP,事件 `isTrusted=true`;视口缩高近似键盘遮挡,震动调用为降级契约测试,不是实体设备、系统软键盘或硬件震动证据。本 change 不含原生构建、宿主升级或发布。
239
+
240
+ 长按专项对照:先运行 `node scripts/check-mobile-hold.mjs --before-ref=66034bb`,再运行 `node scripts/check-mobile-hold.mjs`。前者仅通过 Vite 注入该提交的 `blockReorder.ts`,不修改 checkout;两次均使用 CDP 触摸和原生键盘创建的旧选区,分别记录 pending 选择保护、起拖和落点顺序。`selectstart` / `contextmenu` 取消探针明确为合成事件,不作为系统菜单证据。
241
+
193
242
  ### HNN 文档格式
194
243
 
195
244
  ```ts