@aionbuilders/nabu 0.1.0-beta.0 → 0.1.1

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 (308) hide show
  1. package/CHANGELOG.md +531 -0
  2. package/LICENSE +21 -0
  3. package/README.md +72 -341
  4. package/dist/behaviors/text/RichText.svelte +24 -4
  5. package/dist/behaviors/text/markdown-shortcuts.extension.d.ts +3 -0
  6. package/dist/behaviors/text/markdown-shortcuts.extension.js +35 -10
  7. package/dist/behaviors/text/markdown-syntax.d.ts +42 -0
  8. package/dist/behaviors/text/markdown-syntax.js +81 -0
  9. package/dist/behaviors/text/rich-text.extension.d.ts +3 -0
  10. package/dist/behaviors/text/rich-text.extension.js +95 -38
  11. package/dist/behaviors/text/text.behavior.svelte.d.ts +195 -55
  12. package/dist/behaviors/text/text.behavior.svelte.js +531 -103
  13. package/dist/behaviors/text/typography.extension.d.ts +2 -1
  14. package/dist/behaviors/text/typography.extension.js +3 -2
  15. package/dist/blocks/BlockList.svelte +48 -0
  16. package/dist/blocks/BlockList.svelte.d.ts +17 -0
  17. package/dist/blocks/Nabu.svelte +169 -25
  18. package/dist/blocks/Nabu.svelte.d.ts +13 -0
  19. package/dist/blocks/block.extension.d.ts +3 -0
  20. package/dist/blocks/block.extension.js +4 -7
  21. package/dist/blocks/block.svelte.d.ts +350 -86
  22. package/dist/blocks/block.svelte.js +370 -59
  23. package/dist/blocks/blockquote/Blockquote.svelte +1 -2
  24. package/dist/blocks/blockquote/blockquote.extension.d.ts +4 -1
  25. package/dist/blocks/blockquote/blockquote.extension.js +14 -5
  26. package/dist/blocks/blockquote/blockquote.svelte.d.ts +19 -11
  27. package/dist/blocks/blockquote/blockquote.svelte.js +58 -13
  28. package/dist/blocks/callout/Callout.svelte +6 -8
  29. package/dist/blocks/callout/callout.extension.d.ts +4 -1
  30. package/dist/blocks/callout/callout.extension.js +19 -3
  31. package/dist/blocks/callout/callout.svelte.d.ts +5 -3
  32. package/dist/blocks/callout/callout.svelte.js +11 -6
  33. package/dist/blocks/chunks.d.ts +49 -0
  34. package/dist/blocks/chunks.js +90 -0
  35. package/dist/blocks/code/Code.svelte +7 -8
  36. package/dist/blocks/code/code.extension.d.ts +4 -1
  37. package/dist/blocks/code/code.extension.js +22 -2
  38. package/dist/blocks/code/code.svelte.d.ts +9 -2
  39. package/dist/blocks/code/code.svelte.js +49 -25
  40. package/dist/blocks/container.utils.d.ts +85 -13
  41. package/dist/blocks/container.utils.js +338 -178
  42. package/dist/blocks/dialogue/Dialogue.svelte +8 -4
  43. package/dist/blocks/dialogue/dialogue.svelte.d.ts +33 -2
  44. package/dist/blocks/dialogue/dialogue.svelte.js +58 -4
  45. package/dist/blocks/dialogue/hooks/onBeforeInput.hook.d.ts +2 -2
  46. package/dist/blocks/dialogue/hooks/onBeforeInput.hook.js +6 -4
  47. package/dist/blocks/dialogue/index.d.ts +12 -1
  48. package/dist/blocks/dialogue/index.js +51 -35
  49. package/dist/blocks/divider/divider.extension.d.ts +23 -1
  50. package/dist/blocks/divider/divider.extension.js +85 -19
  51. package/dist/blocks/divider/divider.svelte.d.ts +7 -2
  52. package/dist/blocks/divider/divider.svelte.js +9 -4
  53. package/dist/blocks/file/File.svelte +13 -6
  54. package/dist/blocks/file/file.extension.d.ts +4 -1
  55. package/dist/blocks/file/file.extension.js +9 -1
  56. package/dist/blocks/file/file.svelte.d.ts +3 -3
  57. package/dist/blocks/file/file.svelte.js +20 -14
  58. package/dist/blocks/heading/Heading.svelte +1 -2
  59. package/dist/blocks/heading/heading.svelte.d.ts +23 -11
  60. package/dist/blocks/heading/heading.svelte.js +68 -13
  61. package/dist/blocks/heading/hooks/onBeforeInput.hook.js +7 -5
  62. package/dist/blocks/heading/index.d.ts +2 -2
  63. package/dist/blocks/heading/index.js +33 -8
  64. package/dist/blocks/image/Image.svelte +5 -2
  65. package/dist/blocks/image/image.extension.d.ts +4 -1
  66. package/dist/blocks/image/image.extension.js +9 -1
  67. package/dist/blocks/image/image.svelte.d.ts +17 -6
  68. package/dist/blocks/image/image.svelte.js +33 -11
  69. package/dist/blocks/index.d.ts +1 -1
  70. package/dist/blocks/index.js +1 -1
  71. package/dist/blocks/list/List.svelte +1 -0
  72. package/dist/blocks/list/ListItem.svelte +1 -0
  73. package/dist/blocks/list/convert.d.ts +20 -0
  74. package/dist/blocks/list/convert.js +92 -0
  75. package/dist/blocks/list/hooks/onBeforeInput.hook.js +49 -28
  76. package/dist/blocks/list/html-flat.d.ts +78 -0
  77. package/dist/blocks/list/html-flat.js +244 -0
  78. package/dist/blocks/list/indent.d.ts +86 -0
  79. package/dist/blocks/list/indent.js +205 -0
  80. package/dist/blocks/list/index.d.ts +6 -3
  81. package/dist/blocks/list/index.js +42 -31
  82. package/dist/blocks/list/list-item.svelte.d.ts +32 -18
  83. package/dist/blocks/list/list-item.svelte.js +99 -100
  84. package/dist/blocks/list/list.behavior.svelte.d.ts +4 -1
  85. package/dist/blocks/list/list.behavior.svelte.js +6 -1
  86. package/dist/blocks/list/list.svelte.d.ts +89 -18
  87. package/dist/blocks/list/list.svelte.js +129 -125
  88. package/dist/blocks/list/markdown.d.ts +149 -0
  89. package/dist/blocks/list/markdown.js +442 -0
  90. package/dist/blocks/list/normalize.d.ts +11 -0
  91. package/dist/blocks/list/normalize.js +396 -0
  92. package/dist/blocks/list/paste.d.ts +45 -0
  93. package/dist/blocks/list/paste.js +242 -0
  94. package/dist/blocks/list/step-back.d.ts +24 -0
  95. package/dist/blocks/list/step-back.js +87 -0
  96. package/dist/blocks/list/to-list.d.ts +7 -0
  97. package/dist/blocks/list/to-list.js +44 -0
  98. package/dist/blocks/list/todos-toggle.d.ts +20 -0
  99. package/dist/blocks/list/todos-toggle.js +48 -0
  100. package/dist/blocks/media/markdown.d.ts +12 -0
  101. package/dist/blocks/media/markdown.js +26 -0
  102. package/dist/blocks/media/media-block.svelte.d.ts +77 -2
  103. package/dist/blocks/media/media-block.svelte.js +124 -12
  104. package/dist/blocks/media/media.helpers.d.ts +6 -1
  105. package/dist/blocks/media/media.helpers.js +43 -6
  106. package/dist/blocks/megablock.svelte.d.ts +50 -19
  107. package/dist/blocks/megablock.svelte.js +114 -74
  108. package/dist/blocks/move.d.ts +23 -0
  109. package/dist/blocks/move.js +92 -0
  110. package/dist/blocks/nabu.svelte.d.ts +764 -71
  111. package/dist/blocks/nabu.svelte.js +1753 -189
  112. package/dist/blocks/paragraph/Paragraph.svelte +1 -2
  113. package/dist/blocks/paragraph/index.d.ts +2 -2
  114. package/dist/blocks/paragraph/index.js +35 -13
  115. package/dist/blocks/paragraph/paragraph.svelte.d.ts +46 -14
  116. package/dist/blocks/paragraph/paragraph.svelte.js +77 -16
  117. package/dist/blocks/paragraph/table.html.d.ts +9 -0
  118. package/dist/blocks/paragraph/table.html.js +111 -0
  119. package/dist/blocks/paragraph/table.markdown.d.ts +32 -0
  120. package/dist/blocks/paragraph/table.markdown.js +90 -0
  121. package/dist/blocks/region/Region.svelte +264 -0
  122. package/dist/blocks/region/Region.svelte.d.ts +11 -0
  123. package/dist/blocks/region/actions.d.ts +135 -0
  124. package/dist/blocks/region/actions.js +402 -0
  125. package/dist/blocks/region/close.d.ts +35 -0
  126. package/dist/blocks/region/close.js +130 -0
  127. package/dist/blocks/region/commands.d.ts +6 -0
  128. package/dist/blocks/region/commands.js +277 -0
  129. package/dist/blocks/region/create.d.ts +72 -0
  130. package/dist/blocks/region/create.js +208 -0
  131. package/dist/blocks/region/end-marker.d.ts +35 -0
  132. package/dist/blocks/region/end-marker.js +51 -0
  133. package/dist/blocks/region/facts.d.ts +69 -0
  134. package/dist/blocks/region/facts.js +152 -0
  135. package/dist/blocks/region/format.d.ts +91 -0
  136. package/dist/blocks/region/format.js +260 -0
  137. package/dist/blocks/region/index.d.ts +14 -0
  138. package/dist/blocks/region/index.js +14 -0
  139. package/dist/blocks/region/insert.d.ts +59 -0
  140. package/dist/blocks/region/insert.js +102 -0
  141. package/dist/blocks/region/messages.d.ts +254 -0
  142. package/dist/blocks/region/messages.js +131 -0
  143. package/dist/blocks/region/normalize.d.ts +7 -0
  144. package/dist/blocks/region/normalize.js +170 -0
  145. package/dist/blocks/region/region.extension.d.ts +58 -0
  146. package/dist/blocks/region/region.extension.js +119 -0
  147. package/dist/blocks/region/region.svelte.d.ts +221 -0
  148. package/dist/blocks/region/region.svelte.js +582 -0
  149. package/dist/blocks/region/regions.svelte.d.ts +141 -0
  150. package/dist/blocks/region/regions.svelte.js +276 -0
  151. package/dist/blocks/region/serialize.d.ts +57 -0
  152. package/dist/blocks/region/serialize.js +112 -0
  153. package/dist/blocks/region/types.d.ts +255 -0
  154. package/dist/blocks/region/types.js +204 -0
  155. package/dist/blocks/selection.svelte.d.ts +106 -8
  156. package/dist/blocks/selection.svelte.js +622 -74
  157. package/dist/blocks/subthread.d.ts +80 -0
  158. package/dist/blocks/subthread.js +167 -0
  159. package/dist/blocks/text-block.svelte.d.ts +35 -14
  160. package/dist/blocks/text-block.svelte.js +42 -8
  161. package/dist/blocks/toggle/Toggle.svelte +4 -15
  162. package/dist/blocks/toggle/markdown.d.ts +20 -0
  163. package/dist/blocks/toggle/markdown.js +112 -0
  164. package/dist/blocks/toggle/toggle.extension.d.ts +4 -1
  165. package/dist/blocks/toggle/toggle.extension.js +6 -0
  166. package/dist/blocks/toggle/toggle.svelte.d.ts +55 -8
  167. package/dist/blocks/toggle/toggle.svelte.js +134 -34
  168. package/dist/blocks/undo-selection.d.ts +175 -0
  169. package/dist/blocks/undo-selection.js +360 -0
  170. package/dist/blocks/video/Video.svelte +5 -2
  171. package/dist/blocks/video/video.extension.d.ts +4 -1
  172. package/dist/blocks/video/video.extension.js +9 -1
  173. package/dist/blocks/video/video.svelte.d.ts +6 -5
  174. package/dist/blocks/video/video.svelte.js +18 -9
  175. package/dist/extend.d.ts +55 -0
  176. package/dist/extend.js +88 -0
  177. package/dist/files/assets.clipboard.d.ts +77 -0
  178. package/dist/files/assets.clipboard.js +152 -0
  179. package/dist/files/files.svelte.d.ts +321 -19
  180. package/dist/files/files.svelte.js +847 -43
  181. package/dist/files/index.d.ts +3 -1
  182. package/dist/files/index.js +3 -1
  183. package/dist/files/outbox.d.ts +69 -0
  184. package/dist/files/outbox.js +48 -0
  185. package/dist/files/status.d.ts +65 -0
  186. package/dist/files/status.js +87 -0
  187. package/dist/files/store.d.ts +97 -0
  188. package/dist/files/store.js +65 -0
  189. package/dist/files/uploads.svelte.d.ts +174 -0
  190. package/dist/files/uploads.svelte.js +504 -0
  191. package/dist/index.d.ts +68 -9
  192. package/dist/index.js +117 -10
  193. package/dist/nabu-theme.css +21 -1
  194. package/dist/paste/html.paste.d.ts +74 -3
  195. package/dist/paste/html.paste.js +550 -86
  196. package/dist/paste/markdown-inline.d.ts +86 -0
  197. package/dist/paste/markdown-inline.js +528 -0
  198. package/dist/paste/markdown.paste.d.ts +2 -8
  199. package/dist/paste/markdown.paste.js +78 -94
  200. package/dist/paste/nabu.paste.d.ts +3 -0
  201. package/dist/paste/nabu.paste.js +29 -3
  202. package/dist/paste/plain-text.paste.d.ts +2 -2
  203. package/dist/paste/plain-text.paste.js +3 -3
  204. package/dist/persistence/asset-store.d.ts +51 -0
  205. package/dist/persistence/asset-store.js +103 -0
  206. package/dist/persistence/autosave.d.ts +53 -0
  207. package/dist/persistence/autosave.js +62 -0
  208. package/dist/persistence/compact.d.ts +162 -0
  209. package/dist/persistence/compact.js +141 -0
  210. package/dist/persistence/history.d.ts +77 -0
  211. package/dist/persistence/history.js +176 -0
  212. package/dist/persistence/indexeddb.d.ts +190 -4
  213. package/dist/persistence/indexeddb.js +333 -29
  214. package/dist/persistence/merge.d.ts +38 -0
  215. package/dist/persistence/merge.js +36 -0
  216. package/dist/persistence/outbox.d.ts +25 -0
  217. package/dist/persistence/outbox.js +40 -0
  218. package/dist/persistence/persistence.d.ts +70 -9
  219. package/dist/persistence/persistence.js +507 -35
  220. package/dist/persistence/recovery.d.ts +79 -0
  221. package/dist/persistence/recovery.js +79 -0
  222. package/dist/persistence/release.d.ts +34 -0
  223. package/dist/persistence/release.js +64 -0
  224. package/dist/persistence/state.svelte.d.ts +53 -0
  225. package/dist/persistence/state.svelte.js +48 -0
  226. package/dist/persistence/sync.d.ts +39 -0
  227. package/dist/persistence/sync.js +138 -0
  228. package/dist/persistence/tail.d.ts +42 -0
  229. package/dist/persistence/tail.js +103 -0
  230. package/dist/presets.d.ts +29 -26
  231. package/dist/presets.js +35 -13
  232. package/dist/themes/atelier.css +318 -0
  233. package/dist/ui/CommandChooser.svelte +153 -0
  234. package/dist/ui/CommandChooser.svelte.d.ts +13 -0
  235. package/dist/ui/CommandInvite.svelte +99 -0
  236. package/dist/ui/CommandInvite.svelte.d.ts +12 -0
  237. package/dist/ui/DragHandle.svelte +97 -21
  238. package/dist/ui/FloatingToolbar.svelte +75 -27
  239. package/dist/ui/FloatingToolbar.svelte.d.ts +10 -0
  240. package/dist/ui/SlashMenu.svelte +147 -15
  241. package/dist/ui/SlashMenu.svelte.d.ts +20 -0
  242. package/dist/ui/anchor.d.ts +112 -0
  243. package/dist/ui/anchor.js +136 -0
  244. package/dist/ui/index.d.ts +7 -1
  245. package/dist/ui/index.js +12 -1
  246. package/dist/ui/slash-menu.svelte.d.ts +79 -7
  247. package/dist/ui/slash-menu.svelte.js +85 -51
  248. package/dist/utils/command-confirm.svelte.d.ts +349 -0
  249. package/dist/utils/command-confirm.svelte.js +673 -0
  250. package/dist/utils/commands.d.ts +328 -0
  251. package/dist/utils/commands.js +416 -0
  252. package/dist/utils/composition.d.ts +28 -0
  253. package/dist/utils/composition.js +51 -0
  254. package/dist/utils/dom-scope.d.ts +14 -0
  255. package/dist/utils/dom-scope.js +20 -0
  256. package/dist/utils/drop.d.ts +160 -0
  257. package/dist/utils/drop.js +305 -0
  258. package/dist/utils/extensions.d.ts +439 -45
  259. package/dist/utils/extensions.js +271 -29
  260. package/dist/utils/html.d.ts +44 -0
  261. package/dist/utils/html.js +183 -0
  262. package/dist/utils/index.d.ts +3 -0
  263. package/dist/utils/index.js +3 -0
  264. package/dist/utils/keys.d.ts +120 -0
  265. package/dist/utils/keys.js +248 -0
  266. package/dist/utils/links.d.ts +22 -0
  267. package/dist/utils/links.js +34 -0
  268. package/dist/utils/placeholders.d.ts +81 -3
  269. package/dist/utils/placeholders.js +73 -3
  270. package/dist/utils/selection.svelte.d.ts +48 -20
  271. package/dist/utils/selection.svelte.js +60 -10
  272. package/dist/utils/spellcheck.d.ts +9 -0
  273. package/dist/utils/spellcheck.js +17 -0
  274. package/dist/utils/tab.d.ts +31 -0
  275. package/dist/utils/tab.js +117 -0
  276. package/dist/utils/words.d.ts +42 -0
  277. package/dist/utils/words.js +147 -0
  278. package/dist/vite.d.ts +9 -3
  279. package/dist/vite.js +19 -8
  280. package/package.json +56 -20
  281. package/dist/blocks/variable.svelte.d.ts +0 -47
  282. package/dist/blocks/variable.svelte.js +0 -51
  283. package/dist/blocks/zone/TemplateEditor.svelte +0 -308
  284. package/dist/blocks/zone/TemplateEditor.svelte.d.ts +0 -11
  285. package/dist/blocks/zone/Zone.svelte +0 -272
  286. package/dist/blocks/zone/Zone.svelte.d.ts +0 -11
  287. package/dist/blocks/zone/ZoneEditor.svelte +0 -289
  288. package/dist/blocks/zone/ZoneEditor.svelte.d.ts +0 -11
  289. package/dist/blocks/zone/ZoneTemplatesList.svelte +0 -188
  290. package/dist/blocks/zone/ZoneTemplatesList.svelte.d.ts +0 -11
  291. package/dist/blocks/zone/hooks/onBeforeInput.hook.d.ts +0 -3
  292. package/dist/blocks/zone/hooks/onBeforeInput.hook.js +0 -30
  293. package/dist/blocks/zone/index.d.ts +0 -2
  294. package/dist/blocks/zone/index.js +0 -2
  295. package/dist/blocks/zone/zone.extension.d.ts +0 -2
  296. package/dist/blocks/zone/zone.extension.js +0 -237
  297. package/dist/blocks/zone/zone.svelte.d.ts +0 -221
  298. package/dist/blocks/zone/zone.svelte.js +0 -608
  299. package/dist/overlays/context/Context.svelte +0 -182
  300. package/dist/overlays/context/Context.svelte.d.ts +0 -17
  301. package/dist/overlays/context/collect.d.ts +0 -17
  302. package/dist/overlays/context/collect.js +0 -33
  303. package/dist/overlays/context/context.extension.d.ts +0 -2
  304. package/dist/overlays/context/context.extension.js +0 -8
  305. package/dist/overlays/context/context.svelte.d.ts +0 -82
  306. package/dist/overlays/context/context.svelte.js +0 -159
  307. package/dist/overlays/context/index.d.ts +0 -3
  308. package/dist/overlays/context/index.js +0 -3
@@ -0,0 +1,162 @@
1
+ /** @import { Nabu } from '../blocks/nabu.svelte.js' */
2
+ /** @import { AssetStore } from '../files/store.js' */
3
+ /** @import { CompactOptions } from './history.js' */
4
+ /**
5
+ * @typedef {'busy' | 'detached' | 'pending-uploads' | 'unsaved-changes' | 'nothing-to-compact' | 'archive-failed' | 'verification-failed' | 'save-failed' | 'failed'} CompactRefusal
6
+ */
7
+ /**
8
+ * What `nabu.compact()` resolves with. It never throws for a refusal: `compacted: false` + `reason`, and NOTHING was dropped.
9
+ * @typedef {Object} CompactResult
10
+ * @property {boolean} compacted
11
+ * @property {CompactRefusal} [reason] why nothing was compacted
12
+ * @property {unknown} [error] the error behind `archive-failed` / `save-failed` / `failed`
13
+ * @property {number} [bytesBefore] size of the complete snapshot (what `onBeforeCompact` received)
14
+ * @property {number} [bytesAfter] size of the compacted snapshot that was saved
15
+ * @property {string[]} [released] files (`sha256-…`) no kept version references any more (removed from this document's index)
16
+ * @property {string[]} [deleted] the released files whose bytes were deleted from the store (no other document used them)
17
+ * @property {string[]} [skipped] released files nobody references but whose bytes were kept for now (`files.releaseGraceMs`): they stay in
18
+ * this document's `docRefs` and are reconsidered by its next compaction / `clearPersistence()`
19
+ * @property {Uint8Array} [snapshot] the compacted (shallow) snapshot that was saved
20
+ */
21
+ /**
22
+ * The persisted editor's side of a compaction (see {@link runCompaction}).
23
+ * @typedef {Object} CompactContext
24
+ * @property {Nabu} nabu
25
+ * @property {AssetStore} store
26
+ * @property {boolean} compacting a compaction is running
27
+ * @property {() => { peer: `${number}`, counter: number }[] | undefined} base frontiers of the previous compaction made by this session, if any
28
+ * @property {() => boolean} isDirty whether the document has changes that were not saved yet
29
+ * @property {() => Promise<void>} flush save now
30
+ * @property {<T>(fn: () => Promise<T>) => Promise<T>} lock run `fn` with the saves held back (they queue behind it)
31
+ * @property {(snapshot: Uint8Array, frontiers: { peer: `${number}`, counter: number }[], key: string) => Promise<void>} commit
32
+ * write the compacted snapshot, refresh `docRefs`, and from now on save shallow at `frontiers` (`key` = version that snapshot contains)
33
+ * @property {(doc: import('loro-crdt').LoroDoc) => string} versionKey
34
+ * @property {() => Promise<Set<string>>} candidates the files this document lists: its index plus the ones a previous release skipped
35
+ * @property {() => Set<string>} held files kept by a previous release (grace period): still listed in `docRefs`, reconsidered now
36
+ * @property {(hashes: Iterable<string>) => void} setHeld replace that set
37
+ * @property {() => Promise<void>} saveRefs write `docRefs` (index + held)
38
+ */
39
+ /**
40
+ * Compact the history of a persisted document (ADR 014 §3.6). Every safeguard is here:
41
+ *
42
+ * 1. only when called (the caller decides: explicit `nabu.compact()` or `history: { mode: 'compact' }` at open);
43
+ * 2. REFUSES (`{ compacted: false, reason }`, no throw, nothing dropped) when a file upload is pending / running
44
+ * (`pending-uploads`: the local copy is the only copy), when the document has unsaved or uncommitted changes
45
+ * (`unsaved-changes`), when it is checked out to an old version (`detached`), or when another compaction runs (`busy`);
46
+ * 3. the kept version is chosen by {@link retentionFrontiers} (timestamps of the changes); nothing to drop = `nothing-to-compact`;
47
+ * 4. `onBeforeCompact(fullSnapshot)` is awaited BEFORE anything is changed or written; a throw / rejection ABORTS (`archive-failed`).
48
+ * The kept version is fixed at the same instant as that snapshot, so everything dropped is in the archive;
49
+ * 5. the compacted snapshot is a Loro SHALLOW snapshot at the kept version; it is checked (imported in a scratch document and
50
+ * compared with the live state) before being written, then saved; only then are files released;
51
+ * 6. files no kept version references are removed from the document's index and released ({@link releaseFiles}); bytes recently
52
+ * added (grace period, multi-tab safety) are skipped and reconsidered next time;
53
+ * 7. the undo stack is cleared (its steps could point at history that is gone / files that were released).
54
+ *
55
+ * The live in-memory document is NOT swapped (Loro cannot trim a document in place): it keeps its full history until the editor
56
+ * is opened again; from now on every save of this editor is a shallow snapshot at the kept version (see `persistence.js`).
57
+ * @param {CompactContext} ctx
58
+ * @param {CompactOptions} options
59
+ * @param {{ flush?: boolean }} [internal] `flush`: save pending changes first (used when opening, never an unsaved-changes refusal then)
60
+ * @returns {Promise<CompactResult>}
61
+ * @throws {TypeError} when `options` is invalid (`retain` is required)
62
+ */
63
+ export function runCompaction(ctx: CompactContext, options: CompactOptions, { flush }?: {
64
+ flush?: boolean;
65
+ }): Promise<CompactResult>;
66
+ export type CompactRefusal = "busy" | "detached" | "pending-uploads" | "unsaved-changes" | "nothing-to-compact" | "archive-failed" | "verification-failed" | "save-failed" | "failed";
67
+ /**
68
+ * What `nabu.compact()` resolves with. It never throws for a refusal: `compacted: false` + `reason`, and NOTHING was dropped.
69
+ */
70
+ export type CompactResult = {
71
+ compacted: boolean;
72
+ /**
73
+ * why nothing was compacted
74
+ */
75
+ reason?: CompactRefusal | undefined;
76
+ /**
77
+ * the error behind `archive-failed` / `save-failed` / `failed`
78
+ */
79
+ error?: unknown;
80
+ /**
81
+ * size of the complete snapshot (what `onBeforeCompact` received)
82
+ */
83
+ bytesBefore?: number | undefined;
84
+ /**
85
+ * size of the compacted snapshot that was saved
86
+ */
87
+ bytesAfter?: number | undefined;
88
+ /**
89
+ * files (`sha256-…`) no kept version references any more (removed from this document's index)
90
+ */
91
+ released?: string[] | undefined;
92
+ /**
93
+ * the released files whose bytes were deleted from the store (no other document used them)
94
+ */
95
+ deleted?: string[] | undefined;
96
+ /**
97
+ * released files nobody references but whose bytes were kept for now (`files.releaseGraceMs`): they stay in
98
+ * this document's `docRefs` and are reconsidered by its next compaction / `clearPersistence()`
99
+ */
100
+ skipped?: string[] | undefined;
101
+ /**
102
+ * the compacted (shallow) snapshot that was saved
103
+ */
104
+ snapshot?: Uint8Array<ArrayBufferLike> | undefined;
105
+ };
106
+ /**
107
+ * The persisted editor's side of a compaction (see {@link runCompaction}).
108
+ */
109
+ export type CompactContext = {
110
+ nabu: Nabu;
111
+ store: AssetStore;
112
+ /**
113
+ * a compaction is running
114
+ */
115
+ compacting: boolean;
116
+ /**
117
+ * frontiers of the previous compaction made by this session, if any
118
+ */
119
+ base: () => {
120
+ peer: `${number}`;
121
+ counter: number;
122
+ }[] | undefined;
123
+ /**
124
+ * whether the document has changes that were not saved yet
125
+ */
126
+ isDirty: () => boolean;
127
+ /**
128
+ * save now
129
+ */
130
+ flush: () => Promise<void>;
131
+ /**
132
+ * run `fn` with the saves held back (they queue behind it)
133
+ */
134
+ lock: <T>(fn: () => Promise<T>) => Promise<T>;
135
+ /**
136
+ * write the compacted snapshot, refresh `docRefs`, and from now on save shallow at `frontiers` (`key` = version that snapshot contains)
137
+ */
138
+ commit: (snapshot: Uint8Array, frontiers: {
139
+ peer: `${number}`;
140
+ counter: number;
141
+ }[], key: string) => Promise<void>;
142
+ versionKey: (doc: import("loro-crdt").LoroDoc) => string;
143
+ /**
144
+ * the files this document lists: its index plus the ones a previous release skipped
145
+ */
146
+ candidates: () => Promise<Set<string>>;
147
+ /**
148
+ * files kept by a previous release (grace period): still listed in `docRefs`, reconsidered now
149
+ */
150
+ held: () => Set<string>;
151
+ /**
152
+ * replace that set
153
+ */
154
+ setHeld: (hashes: Iterable<string>) => void;
155
+ /**
156
+ * write `docRefs` (index + held)
157
+ */
158
+ saveRefs: () => Promise<void>;
159
+ };
160
+ import type { CompactOptions } from './history.js';
161
+ import type { Nabu } from '../blocks/nabu.svelte.js';
162
+ import type { AssetStore } from '../files/store.js';
@@ -0,0 +1,141 @@
1
+ import { Files } from '../files/files.svelte.js';
2
+ import { parseRetain, retentionFrontiers, referencedHashes, snapshotMatches } from './history.js';
3
+ import { releaseFiles } from './release.js';
4
+
5
+ /** @import { Nabu } from '../blocks/nabu.svelte.js' */
6
+ /** @import { AssetStore } from '../files/store.js' */
7
+ /** @import { CompactOptions } from './history.js' */
8
+
9
+ /**
10
+ * @typedef {'busy' | 'detached' | 'pending-uploads' | 'unsaved-changes' | 'nothing-to-compact' | 'archive-failed' | 'verification-failed' | 'save-failed' | 'failed'} CompactRefusal
11
+ */
12
+
13
+ /**
14
+ * What `nabu.compact()` resolves with. It never throws for a refusal: `compacted: false` + `reason`, and NOTHING was dropped.
15
+ * @typedef {Object} CompactResult
16
+ * @property {boolean} compacted
17
+ * @property {CompactRefusal} [reason] why nothing was compacted
18
+ * @property {unknown} [error] the error behind `archive-failed` / `save-failed` / `failed`
19
+ * @property {number} [bytesBefore] size of the complete snapshot (what `onBeforeCompact` received)
20
+ * @property {number} [bytesAfter] size of the compacted snapshot that was saved
21
+ * @property {string[]} [released] files (`sha256-…`) no kept version references any more (removed from this document's index)
22
+ * @property {string[]} [deleted] the released files whose bytes were deleted from the store (no other document used them)
23
+ * @property {string[]} [skipped] released files nobody references but whose bytes were kept for now (`files.releaseGraceMs`): they stay in
24
+ * this document's `docRefs` and are reconsidered by its next compaction / `clearPersistence()`
25
+ * @property {Uint8Array} [snapshot] the compacted (shallow) snapshot that was saved
26
+ */
27
+
28
+ /**
29
+ * The persisted editor's side of a compaction (see {@link runCompaction}).
30
+ * @typedef {Object} CompactContext
31
+ * @property {Nabu} nabu
32
+ * @property {AssetStore} store
33
+ * @property {boolean} compacting a compaction is running
34
+ * @property {() => { peer: `${number}`, counter: number }[] | undefined} base frontiers of the previous compaction made by this session, if any
35
+ * @property {() => boolean} isDirty whether the document has changes that were not saved yet
36
+ * @property {() => Promise<void>} flush save now
37
+ * @property {<T>(fn: () => Promise<T>) => Promise<T>} lock run `fn` with the saves held back (they queue behind it)
38
+ * @property {(snapshot: Uint8Array, frontiers: { peer: `${number}`, counter: number }[], key: string) => Promise<void>} commit
39
+ * write the compacted snapshot, refresh `docRefs`, and from now on save shallow at `frontiers` (`key` = version that snapshot contains)
40
+ * @property {(doc: import('loro-crdt').LoroDoc) => string} versionKey
41
+ * @property {() => Promise<Set<string>>} candidates the files this document lists: its index plus the ones a previous release skipped
42
+ * @property {() => Set<string>} held files kept by a previous release (grace period): still listed in `docRefs`, reconsidered now
43
+ * @property {(hashes: Iterable<string>) => void} setHeld replace that set
44
+ * @property {() => Promise<void>} saveRefs write `docRefs` (index + held)
45
+ */
46
+
47
+ /**
48
+ * Compact the history of a persisted document (ADR 014 §3.6). Every safeguard is here:
49
+ *
50
+ * 1. only when called (the caller decides: explicit `nabu.compact()` or `history: { mode: 'compact' }` at open);
51
+ * 2. REFUSES (`{ compacted: false, reason }`, no throw, nothing dropped) when a file upload is pending / running
52
+ * (`pending-uploads`: the local copy is the only copy), when the document has unsaved or uncommitted changes
53
+ * (`unsaved-changes`), when it is checked out to an old version (`detached`), or when another compaction runs (`busy`);
54
+ * 3. the kept version is chosen by {@link retentionFrontiers} (timestamps of the changes); nothing to drop = `nothing-to-compact`;
55
+ * 4. `onBeforeCompact(fullSnapshot)` is awaited BEFORE anything is changed or written; a throw / rejection ABORTS (`archive-failed`).
56
+ * The kept version is fixed at the same instant as that snapshot, so everything dropped is in the archive;
57
+ * 5. the compacted snapshot is a Loro SHALLOW snapshot at the kept version; it is checked (imported in a scratch document and
58
+ * compared with the live state) before being written, then saved; only then are files released;
59
+ * 6. files no kept version references are removed from the document's index and released ({@link releaseFiles}); bytes recently
60
+ * added (grace period, multi-tab safety) are skipped and reconsidered next time;
61
+ * 7. the undo stack is cleared (its steps could point at history that is gone / files that were released).
62
+ *
63
+ * The live in-memory document is NOT swapped (Loro cannot trim a document in place): it keeps its full history until the editor
64
+ * is opened again; from now on every save of this editor is a shallow snapshot at the kept version (see `persistence.js`).
65
+ * @param {CompactContext} ctx
66
+ * @param {CompactOptions} options
67
+ * @param {{ flush?: boolean }} [internal] `flush`: save pending changes first (used when opening, never an unsaved-changes refusal then)
68
+ * @returns {Promise<CompactResult>}
69
+ * @throws {TypeError} when `options` is invalid (`retain` is required)
70
+ */
71
+ export async function runCompaction(ctx, options, { flush = false } = {}) {
72
+ const retainMs = parseRetain(options?.retain);
73
+ const archive = options.onBeforeCompact;
74
+ if (archive !== undefined && typeof archive !== 'function') throw new TypeError('compact: "onBeforeCompact" must be a function');
75
+ const { nabu, store } = ctx;
76
+ const doc = nabu.doc;
77
+ /** @param {CompactRefusal} reason @param {unknown} [error] @returns {CompactResult} */
78
+ const refuse = (reason, error) => ({ compacted: false, reason, ...(error === undefined ? {} : { error }) });
79
+
80
+ if (ctx.compacting) return refuse('busy');
81
+ ctx.compacting = true;
82
+ try {
83
+ const files = Files.get(nabu);
84
+ await files.whenIdle(); // pastes / imports / migration in progress belong to what is compacted
85
+ if (await files.pendingUploads()) return refuse('pending-uploads'); // before the flush: a refusal writes nothing
86
+ if (flush) await ctx.flush();
87
+ if (await files.pendingUploads()) return refuse('pending-uploads');
88
+
89
+ // ── no await from here to the archive export: the kept version and the archived snapshot are the same instant ──
90
+ if (doc.isDetached()) return refuse('detached');
91
+ if (doc.getPendingTxnLength() > 0 || ctx.isDirty()) return refuse('unsaved-changes');
92
+ const frontiers = retentionFrontiers(doc, retainMs, Date.now(), ctx.base());
93
+ if (!frontiers) return refuse('nothing-to-compact');
94
+ const full = doc.export({ mode: 'snapshot' });
95
+
96
+ if (archive) {
97
+ try {
98
+ await archive(full);
99
+ } catch (error) {
100
+ nabu.warn(`history: compaction aborted, onBeforeCompact failed (nothing was dropped): ${error}`);
101
+ return refuse('archive-failed', error);
102
+ }
103
+ }
104
+
105
+ return await ctx.lock(async () => {
106
+ // the document may have moved on while the archive was awaited: what happened after `frontiers` is kept as it is
107
+ if (doc.isDetached()) return refuse('detached');
108
+ if (await files.pendingUploads()) return refuse('pending-uploads');
109
+ try {
110
+ const used = referencedHashes(doc, frontiers);
111
+ const released = [...(await ctx.candidates())].filter((hash) => !used.has(hash));
112
+ const urls = files.hostUrls(released);
113
+ await files.releaseIndex(released);
114
+ const key = ctx.versionKey(doc);
115
+ const snapshot = doc.export({ mode: 'shallow-snapshot', frontiers });
116
+ if (!snapshotMatches(doc, snapshot)) {
117
+ nabu.warn('history: compaction aborted, the compacted snapshot does not restore the document (nothing was dropped)');
118
+ return refuse('verification-failed');
119
+ }
120
+ const previouslyHeld = ctx.held();
121
+ ctx.setHeld([]); // the release below must not find the document's own docRefs protecting these files
122
+ try {
123
+ await ctx.commit(snapshot, frontiers, key);
124
+ } catch (error) {
125
+ ctx.setHeld(previouslyHeld);
126
+ nabu.warn(`history: compaction aborted, the compacted snapshot could not be saved: ${error}`);
127
+ return refuse('save-failed', error);
128
+ }
129
+ nabu.undoManager.clear();
130
+ const { deleted, skipped } = await releaseFiles(nabu, store, released, urls);
131
+ if (skipped.length) { ctx.setHeld(skipped); await ctx.saveRefs().catch((error) => nabu.warn(`history: could not record the files kept for later: ${error}`)); }
132
+ return { compacted: true, bytesBefore: full.length, bytesAfter: snapshot.length, released, deleted, skipped, snapshot };
133
+ } catch (error) {
134
+ nabu.warn(`history: compaction failed (nothing was dropped): ${error}`);
135
+ return refuse('failed', error);
136
+ }
137
+ });
138
+ } finally {
139
+ ctx.compacting = false;
140
+ }
141
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Parse `retain` into milliseconds. Strict: a finite number >= 0, or `<number><s|m|h|d|w>` (e.g. `'30d'`, `'1.5h'`).
3
+ * @param {unknown} value
4
+ * @returns {number}
5
+ * @throws {TypeError}
6
+ */
7
+ export function parseRetain(value: unknown): number;
8
+ /**
9
+ * Normalize the `history` option of `createPersistedEditor`: `'full'` (default) or `{ mode: 'compact', retain, onBeforeCompact }`.
10
+ * @param {unknown} history
11
+ * @returns {HistoryConfig}
12
+ * @throws {TypeError} for anything else (a typo must not silently pick a mode)
13
+ */
14
+ export function parseHistory(history: unknown): HistoryConfig;
15
+ /**
16
+ * The version a compaction keeps as the START of the remaining history (the frontiers handed to the shallow snapshot), or
17
+ * `null` when there is nothing to drop.
18
+ *
19
+ * - `retainMs === 0`: the current version (no past history survives, only the state and what happens next).
20
+ * - otherwise: the latest version made ONLY of changes older than `now - retainMs`. Changes are walked in causal order
21
+ * (Loro lamport order), the version is the longest prefix whose changes are all older than the cutoff. A change without a
22
+ * timestamp (written before timestamps were recorded) counts as old only if a LATER change with a known timestamp is itself
23
+ * old (it happened before it); an undated history is therefore never windowed away: only `retain: 0` compacts it.
24
+ * A margin of Loro's change-merge interval keeps a change that may have grown after its timestamp.
25
+ *
26
+ * `base` is the version the document was already compacted to (its shallow start or the last compaction of this session); a result
27
+ * that does not go strictly past it is `null`.
28
+ * @param {LoroDoc} doc
29
+ * @param {number} retainMs
30
+ * @param {number} [nowMs]
31
+ * @param {OpId[]} [base] frontiers of the previous compaction point, if any
32
+ * @returns {OpId[] | null}
33
+ */
34
+ export function retentionFrontiers(doc: LoroDoc, retainMs: number, nowMs?: number, base?: OpId[]): OpId[] | null;
35
+ /**
36
+ * The files (`sha256-…` ids) a compaction to `frontiers` still needs: referenced by the CURRENT state, by the state AT `frontiers`
37
+ * (the oldest version still reachable) or by any operation after it. Anything else is referenced by no version that survives.
38
+ * Works on a scratch copy of `doc` (the live document is not touched; no `forkAt`, which Loro does not support on shallow
39
+ * documents). Generic: it only looks for `nabu-asset:sha256-…` strings.
40
+ * @param {LoroDoc} doc @param {OpId[]} frontiers
41
+ * @returns {Set<string>}
42
+ */
43
+ export function referencedHashes(doc: LoroDoc, frontiers: OpId[]): Set<string>;
44
+ /**
45
+ * Check that `snapshot` (a shallow snapshot) restores exactly the current state of `doc`: it is imported into a scratch document
46
+ * and compared. A compaction that fails this check is aborted before anything is written.
47
+ * @param {LoroDoc} doc @param {Uint8Array} snapshot
48
+ * @returns {boolean}
49
+ */
50
+ export function snapshotMatches(doc: LoroDoc, snapshot: Uint8Array): boolean;
51
+ export type OpId = {
52
+ peer: `${number}`;
53
+ counter: number;
54
+ };
55
+ /**
56
+ * What an integrator may pass as `compact({ ... })` / `history: { mode: 'compact', ... }`.
57
+ */
58
+ export type CompactOptions = {
59
+ /**
60
+ * how much PAST history survives: a duration in ms, or a string `<number><unit>` with unit
61
+ * `s`, `m`, `h`, `d` or `w` (`'30d'`, `'12h'`), or `0` = keep no past history. Required (there is no default that drops data).
62
+ */
63
+ retain: number | string;
64
+ /**
65
+ * awaited with the COMPLETE snapshot (all the
66
+ * history) before anything is dropped; archive it. If it throws / rejects the compaction is ABORTED and nothing is lost.
67
+ */
68
+ onBeforeCompact?: ((fullSnapshot: Uint8Array) => void | Promise<void>) | undefined;
69
+ };
70
+ export type HistoryConfig = {
71
+ mode: "full";
72
+ } | {
73
+ mode: "compact";
74
+ retain: number;
75
+ onBeforeCompact?: CompactOptions["onBeforeCompact"];
76
+ };
77
+ import { LoroDoc } from 'loro-crdt';
@@ -0,0 +1,176 @@
1
+ import { LoroDoc, VersionVector } from 'loro-crdt';
2
+
3
+ /**
4
+ * History helpers of the persisted editor (ADR 014 §3.6, lot 3): parsing of the `history` option and of `retain`, the choice
5
+ * of the version a compaction keeps, and the scan of the files a kept history still references. Pure functions over Loro
6
+ * documents: nothing here knows a block type (the document is only searched for `nabu-asset:sha256-…` strings).
7
+ */
8
+
9
+ /**
10
+ * What an integrator may pass as `compact({ ... })` / `history: { mode: 'compact', ... }`.
11
+ * @typedef {Object} CompactOptions
12
+ * @property {number | string} retain how much PAST history survives: a duration in ms, or a string `<number><unit>` with unit
13
+ * `s`, `m`, `h`, `d` or `w` (`'30d'`, `'12h'`), or `0` = keep no past history. Required (there is no default that drops data).
14
+ * @property {(fullSnapshot: Uint8Array) => void | Promise<void>} [onBeforeCompact] awaited with the COMPLETE snapshot (all the
15
+ * history) before anything is dropped; archive it. If it throws / rejects the compaction is ABORTED and nothing is lost.
16
+ */
17
+
18
+ /**
19
+ * @typedef {{ mode: 'full' } | { mode: 'compact', retain: number, onBeforeCompact?: CompactOptions['onBeforeCompact'] }} HistoryConfig
20
+ */
21
+
22
+ const UNITS = /** @type {Record<string, number>} */ ({ s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 });
23
+
24
+ /**
25
+ * Parse `retain` into milliseconds. Strict: a finite number >= 0, or `<number><s|m|h|d|w>` (e.g. `'30d'`, `'1.5h'`).
26
+ * @param {unknown} value
27
+ * @returns {number}
28
+ * @throws {TypeError}
29
+ */
30
+ export function parseRetain(value) {
31
+ if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
32
+ if (typeof value === 'string') {
33
+ const match = /^(\d+(?:\.\d+)?)(s|m|h|d|w)?$/.exec(value.trim());
34
+ if (match && match[2]) return Number(match[1]) * UNITS[match[2]];
35
+ if (match && Number(match[1]) === 0) return 0;
36
+ }
37
+ throw new TypeError(`history: invalid "retain" ${JSON.stringify(value)}: use a number of milliseconds, 0, or a string like '30d' / '12h' (units s, m, h, d, w)`);
38
+ }
39
+
40
+ /**
41
+ * Normalize the `history` option of `createPersistedEditor`: `'full'` (default) or `{ mode: 'compact', retain, onBeforeCompact }`.
42
+ * @param {unknown} history
43
+ * @returns {HistoryConfig}
44
+ * @throws {TypeError} for anything else (a typo must not silently pick a mode)
45
+ */
46
+ export function parseHistory(history) {
47
+ if (history === undefined || history === null || history === 'full') return { mode: 'full' };
48
+ const config = /** @type {any} */ (history);
49
+ if (typeof history === 'object' && (config.mode === undefined || config.mode === 'full')) return { mode: 'full' };
50
+ if (typeof history === 'object' && config.mode === 'compact') {
51
+ if (config.onBeforeCompact !== undefined && typeof config.onBeforeCompact !== 'function') throw new TypeError('history: "onBeforeCompact" must be a function');
52
+ return { mode: 'compact', retain: parseRetain(config.retain), onBeforeCompact: config.onBeforeCompact };
53
+ }
54
+ throw new TypeError(`history: expected 'full' or { mode: 'compact', retain, onBeforeCompact }, got ${JSON.stringify(history)}`);
55
+ }
56
+
57
+ /** Loro merges consecutive commits closer than this (seconds) into ONE change, stamped with the first one's time. */
58
+ const CHANGE_MERGE_SECONDS = 1000;
59
+
60
+ /** @typedef {{ peer: `${number}`, counter: number }} OpId */
61
+
62
+ /**
63
+ * Whether version `a` strictly contains version `b`.
64
+ * @param {LoroDoc} doc @param {OpId[]} a @param {OpId[]} b
65
+ */
66
+ function isAfter(doc, a, b) {
67
+ return doc.frontiersToVV(a).compare(doc.frontiersToVV(b)) === 1;
68
+ }
69
+
70
+ /**
71
+ * The version a compaction keeps as the START of the remaining history (the frontiers handed to the shallow snapshot), or
72
+ * `null` when there is nothing to drop.
73
+ *
74
+ * - `retainMs === 0`: the current version (no past history survives, only the state and what happens next).
75
+ * - otherwise: the latest version made ONLY of changes older than `now - retainMs`. Changes are walked in causal order
76
+ * (Loro lamport order), the version is the longest prefix whose changes are all older than the cutoff. A change without a
77
+ * timestamp (written before timestamps were recorded) counts as old only if a LATER change with a known timestamp is itself
78
+ * old (it happened before it); an undated history is therefore never windowed away: only `retain: 0` compacts it.
79
+ * A margin of Loro's change-merge interval keeps a change that may have grown after its timestamp.
80
+ *
81
+ * `base` is the version the document was already compacted to (its shallow start or the last compaction of this session); a result
82
+ * that does not go strictly past it is `null`.
83
+ * @param {LoroDoc} doc
84
+ * @param {number} retainMs
85
+ * @param {number} [nowMs]
86
+ * @param {OpId[]} [base] frontiers of the previous compaction point, if any
87
+ * @returns {OpId[] | null}
88
+ */
89
+ export function retentionFrontiers(doc, retainMs, nowMs = Date.now(), base) {
90
+ const latest = doc.oplogFrontiers();
91
+ if (!latest.length) return null;
92
+ /** @type {OpId[] | null} */
93
+ let target = null;
94
+ if (retainMs === 0) {
95
+ target = latest;
96
+ } else {
97
+ const cutoff = Math.floor((nowMs - retainMs) / 1000) - CHANGE_MERGE_SECONDS;
98
+ const changes = [...doc.getAllChanges().values()].flat();
99
+ changes.sort((a, b) => a.lamport - b.lamport || (a.peer < b.peer ? -1 : a.peer > b.peer ? 1 : 0));
100
+ // effective time of each change: its own, or the next known one (it happened before it)
101
+ const effective = new Array(changes.length);
102
+ let next = Infinity;
103
+ for (let i = changes.length - 1; i >= 0; i--) {
104
+ if (changes[i].timestamp > 0) next = changes[i].timestamp;
105
+ effective[i] = next;
106
+ }
107
+ let count = 0;
108
+ while (count < changes.length && effective[count] <= cutoff) count++;
109
+ if (count === 0) return null;
110
+ /** @type {Map<`${number}`, number>} */
111
+ const end = new Map();
112
+ for (const [peer, counter] of doc.shallowSinceVV().toJSON()) end.set(peer, counter); // never go before the shallow start
113
+ for (let i = 0; i < count; i++) {
114
+ const c = changes[i];
115
+ end.set(c.peer, Math.max(end.get(c.peer) ?? 0, c.counter + c.length));
116
+ }
117
+ target = doc.vvToFrontiers(new VersionVector(end));
118
+ }
119
+ if (!target?.length) return null;
120
+ const floor = base?.length ? base : doc.isShallow() ? doc.shallowSinceFrontiers() : null;
121
+ if (floor && !isAfter(doc, target, floor)) return null;
122
+ return target;
123
+ }
124
+
125
+ /** Hash ids referenced as `nabu-asset:sha256-<64 hex>` anywhere in `text`. @param {string} text @param {Set<string>} into */
126
+ function collectRefs(text, into) {
127
+ for (const match of text.matchAll(/nabu-asset:(sha256-[0-9a-f]{64})/g)) into.add(match[1]);
128
+ }
129
+
130
+ /**
131
+ * Canonical JSON (sorted keys, bytes as hex) used to compare two document states.
132
+ * @param {any} value @returns {string}
133
+ */
134
+ function canonical(value) {
135
+ return JSON.stringify(value, (_key, v) => {
136
+ if (ArrayBuffer.isView(v)) return 'bytes:' + [...new Uint8Array(v.buffer, v.byteOffset, v.byteLength)].join(',');
137
+ if (v && typeof v === 'object' && !Array.isArray(v)) return Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]));
138
+ return v;
139
+ });
140
+ }
141
+
142
+ /**
143
+ * The files (`sha256-…` ids) a compaction to `frontiers` still needs: referenced by the CURRENT state, by the state AT `frontiers`
144
+ * (the oldest version still reachable) or by any operation after it. Anything else is referenced by no version that survives.
145
+ * Works on a scratch copy of `doc` (the live document is not touched; no `forkAt`, which Loro does not support on shallow
146
+ * documents). Generic: it only looks for `nabu-asset:sha256-…` strings.
147
+ * @param {LoroDoc} doc @param {OpId[]} frontiers
148
+ * @returns {Set<string>}
149
+ */
150
+ export function referencedHashes(doc, frontiers) {
151
+ const scratch = new LoroDoc();
152
+ scratch.import(doc.export({ mode: 'snapshot' }));
153
+ /** @type {Set<string>} */
154
+ const found = new Set();
155
+ collectRefs(JSON.stringify(scratch.toJSON()), found); // current state
156
+ collectRefs(JSON.stringify(scratch.exportJsonUpdates(scratch.frontiersToVV(frontiers))), found); // every op after the kept version
157
+ scratch.checkout(frontiers);
158
+ collectRefs(JSON.stringify(scratch.toJSON()), found); // state at the kept version
159
+ return found;
160
+ }
161
+
162
+ /**
163
+ * Check that `snapshot` (a shallow snapshot) restores exactly the current state of `doc`: it is imported into a scratch document
164
+ * and compared. A compaction that fails this check is aborted before anything is written.
165
+ * @param {LoroDoc} doc @param {Uint8Array} snapshot
166
+ * @returns {boolean}
167
+ */
168
+ export function snapshotMatches(doc, snapshot) {
169
+ try {
170
+ const scratch = new LoroDoc();
171
+ scratch.import(snapshot);
172
+ return canonical(scratch.toJSON()) === canonical(doc.toJSON());
173
+ } catch {
174
+ return false;
175
+ }
176
+ }