noteloom 0.2.0 → 0.3.0

package/README.md

@@ -243,7 +243,7 @@ User-created types are persisted in the document's own `fieldTypes` collection (
 ```js
 import { exportDocumentJSON, exportDocumentHTML, exportDocumentText } from 'noteloom';
 
-exportDocumentJSON(store); // { rootId, blocks, runs } — feed straight back into `useEditor({ doc })`
+exportDocumentJSON(store); // a JSON *string* — JSON.parse() it to get { version, rootId, blocks, runs }, usable as useEditor({ doc })
 exportDocumentHTML(store, registry, inlineRegistry);
 exportDocumentText(store, registry, inlineRegistry);
 ```
@@ -296,6 +296,186 @@ One existing, by-design limitation carried over from clipboard paste: an atomic
 
 This is purely an additive, alternate *interchange* format — the internal engine format above is unaffected either way, and this is not a replacement for it.
 
+## Templates
+
+Two kinds — a **document template** seeds a whole new editor (`useEditor({ doc })`), a **block template** is a saved snippet insertable anywhere via "/". Both are developer-definable in code and end-user-creatable/persisted (IndexedDB, alongside `usePersistedDocument`'s own storage but a separate object store — a template isn't tied to any one document). `examples/05-templates/` is a complete runnable app combining every piece below.
+
+**Block templates — reusable snippets, insertable via "/":**
+
+```js
+import { EditorStore, captureBlockTemplate, registerBlockTemplates, registerBuiltInBlocks } from 'noteloom';
+
+// Build once (a throwaway store is fine — only its content is captured):
+const draftStore = new EditorStore({
+  rootId: 'root',
+  blocks: [
+    { id: 'root', type: 'page', parentId: null, contentIds: ['h1', 'li1'], props: {} },
+    { id: 'h1', type: 'heading', parentId: 'root', contentIds: ['r1'], props: { level: 2 } },
+    { id: 'li1', type: 'listItem', parentId: 'root', contentIds: [], props: { ordered: true, titleRunIds: ['r2'] } },
+  ],
+  runs: [
+    { id: 'r1', type: 'text', value: 'Meeting agenda', marks: {} },
+    { id: 'r2', type: 'text', value: 'Review previous action items', marks: {} },
+  ],
+});
+const agendaSnippet = captureBlockTemplate(draftStore, ['h1', 'li1']);
+
+const editor = useEditor({
+  registerBlocks: (registry) => {
+    registerBuiltInBlocks(registry);
+    registerBlockTemplates(registry, [{ id: 'agenda', label: 'Meeting agenda', keywords: ['agenda'], roots: agendaSnippet.roots }]);
+  },
+});
+```
+
+Typing "/agenda" now shows "Meeting agenda" in the slash menu, same as any built-in block — no changes needed to `SlashMenu`/`useSlashMenuTrigger`, since `registerBlockTemplates` registers under the hood exactly the way a real block type does (just one that's never actually rendered — only its *captured content*, which already has real block types, gets inserted). `insertBlockTemplate(store, template, { parentId, index })` does the same insertion directly, if you want a button instead of/alongside "/".
+
+**Document templates — starter documents:** no new primitives needed — a document template *is* a `DocumentJSON`, so `useEditor({ doc: someTemplate.doc })` already covers "start a new editor from it." To apply one to an **already-mounted** editor instead, use `applyDocumentTemplate(store, doc)`.
+
+**Saving/browsing a library of templates** (either kind), persisted so it survives reload:
+
+```jsx
+import { useEditor, NoteloomEditor, useTemplates, TemplatePicker, saveTemplate, exportDocumentJSON } from 'noteloom';
+
+function NewDocumentScreen({ onPick }) {
+  const { templates, isLoaded } = useTemplates({ scope: 'document' }); // or 'block', or omit for both
+  if (!isLoaded) return <p>Loading…</p>;
+  return <TemplatePicker templates={templates} onSelect={(template) => onPick(template.doc)} />;
+}
+
+// Saving the current document as a reusable template:
+async function saveCurrentAsTemplate(store, name) {
+  await saveTemplate({
+    id: crypto.randomUUID(),
+    scope: 'document',
+    name,
+    doc: JSON.parse(exportDocumentJSON(store)), // exportDocumentJSON returns a JSON *string* — parse it first
+  });
+}
+```
+
+`TemplatePicker` is deliberately just a plain list (name + description + a "Use" button) — wrap it in the exported `Modal` component yourself, or render it inline, whichever fits; what `onSelect` actually does (apply it, insert it, just read `.doc`) is up to you, since that differs by scope. `saveTemplate`/`loadTemplate`/`deleteTemplate`/`listTemplates` are the raw storage operations `useTemplates` is built on, for anywhere the hook's all-in-one behavior doesn't fit.
+
+**Importing a template from a file** — since a stored template is already plain JSON, this needs no new format or function, just `saveTemplate(JSON.parse(fileText))`:
+
+```jsx
+async function handleImport(event) {
+  const template = JSON.parse(await event.target.files[0].text());
+  await saveTemplate(template);
+}
+```
+
+(Exporting one for sharing is the mirror image — `JSON.stringify(template)`, downloaded as a `.json` file — ordinary front-end code, not something this package needs to provide.)
+
+## Comments
+
+Select a range, leave a comment on it; click or hover the highlighted text later to view/reply/resolve/delete it — `examples/06-comments/` is a complete runnable app. Two ways to wire it up:
+
+### The built-in UI (zero comment-authoring code of your own)
+
+Pass `commentAuthorId` — the current user's id — to `<NoteloomEditor>` and the whole experience just works, Notion/Google Docs-style:
+
+```jsx
+<NoteloomEditor editor={editor} commentAuthorId={currentUser.id} showCommentsPanel />
+```
+
+- The floating format toolbar's Comment button opens a small inline composer (a textarea, matching the rest of the toolbar's minimal chrome) and creates the comment on submit.
+- Clicking (or hovering) any highlighted comment opens a popover right there with the thread's messages and Reply/Resolve/Delete — mirroring how the existing link hover card works, just triggered by click too, not hover alone.
+- `showCommentsPanel` (optional) adds a right-side panel listing every thread in the document, unresolved first — the "extra feature" for apps that want a persistent overview alongside the inline popovers, not instead of them. It's `position: fixed` by default (see `.be-comments-panel` in style.css) so it needs no layout changes on your end; override that rule for a different placement.
+
+Every reply/new-comment composed through any of these built-in surfaces is attributed to `commentAuthorId`. Omit it and the toolbar's Comment button disappears, the click/hover popover on existing comments still works (viewing/resolving/deleting need no identity) but hides its Reply composer, and `showCommentsPanel` still lists threads read-only in the same way.
+
+For the granular API, render the pieces yourself anywhere under an `<EditorProvider commentAuthorId={currentUser.id}>`: `<FloatingToolbar commentAuthorId={...} .../>` for the toolbar button, `<CommentsPanel authorId={...} />` for the sidebar — the click/hover popover (`CommentPopover`) is mounted automatically inside every block's editable content, same as the link hover card, so there's nothing extra to render for it.
+
+### Full control (bring your own UI)
+
+Pass `onComment` instead of `commentAuthorId` — it's called with the selected range and you decide what happens next (open your own modal, pick the author yourself):
+
+```jsx
+import { addComment, replyToComment, resolveComment, deleteComment, useComments, resolveMultiRunSelection } from 'noteloom';
+
+<NoteloomEditor
+  editor={editor}
+  onComment={(range) => {
+    const text = window.prompt('Comment text?');
+    if (text) addComment(editor.store, range, { authorId: currentUser.id, text });
+  }}
+/>;
+
+// Outside the floating toolbar entirely, resolve the selection yourself:
+function AddCommentButton({ store }) {
+  function handleClick() {
+    const range = resolveMultiRunSelection(); // { blockId, startRunId, startOffset, endRunId, endOffset }
+    if (!range) return; // no non-collapsed selection
+    addComment(store, range, { authorId: currentUser.id, text: 'Can we tighten this up?' });
+  }
+  return <button onClick={handleClick}>Add comment</button>;
+}
+
+// A hand-rolled list, using useComments() directly instead of CommentsPanel/CommentThreadCard:
+function CommentsSidebar({ store }) {
+  const comments = useComments();
+  return (
+    <ul>
+      {comments.map((thread) => (
+        <li key={thread.id}>
+          {thread.messages.map((m) => <p key={m.id}>{m.authorId}: {m.text}</p>)}
+          <button onClick={() => replyToComment(store, thread.id, { authorId: currentUser.id, text: '...' })}>Reply</button>
+          <button onClick={() => resolveComment(store, thread.id, !thread.resolved)}>{thread.resolved ? 'Reopen' : 'Resolve'}</button>
+          <button onClick={() => deleteComment(store, thread.id)}>Delete</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+`onComment` (given to `<NoteloomEditor>` or `<FloatingToolbar>` directly) always takes priority over `commentAuthorId`'s built-in composer, so the two can't fight over the same button. The Comment button only appears for a same-block selection either way — `addCommentMarkOverRange` doesn't support a cross-block range yet, the same single-block scope every mark-toggle command already has for its own splitting logic.
+
+A comment thread is `{ id, blockId, anchorRunIds, resolved, messages: [{ id, authorId, text, createdAt }] }`. `CommentThreadCard`/`CommentComposer` (the pieces `CommentPopover`/`CommentsPanel` are built from) are exported too, for reusing the built-in look while customizing the surrounding layout.
+
+**Scope, stated plainly:** a thread's own metadata (text, author, replies, resolved flag) is fully collaboration-aware — it broadcasts live to connected peers and undoes/redoes normally. The *highlighted range* it's anchored to is local-only in collaboration for v1: a newly-joining peer sees it correctly (full document snapshots always include it), but an already-connected peer won't see someone else's brand-new highlight appear live until their next resync. This isn't a new gap introduced by comments — every other range-based formatting operation (bold, italic, highlight, ...) already has this exact scope today, since none of them have a CRDT-safe wire representation yet.
+
+`thread.anchorRunIds` is a creation-time hint only, meant for jumping to roughly where a comment was made — it is **not** re-validated after a later formatting edit splits or re-mints run ids in that range. To reliably find where a comment's highlight actually lives right now, look at which runs' `marks.commentIds` include it (exactly what `deleteComment` itself does internally via `removeCommentMarkEverywhere`), not `anchorRunIds`.
+
+## Version history
+
+Point-in-time document snapshots, stored in IndexedDB (a third object store, alongside `usePersistedDocument`'s `documents` and Templates' `templates`) — periodic, manual, or both. `examples/07-version-history/` is a complete runnable app with a version list and one-click restore.
+
+```jsx
+import { createPeriodicVersionSnapshotter, useDocumentVersions, saveDocumentVersion, applyDocumentTemplate, exportDocumentJSON } from 'noteloom';
+
+// Automatic: snapshot every few minutes, keep the most recent 50.
+useEffect(() => {
+  const snapshotter = createPeriodicVersionSnapshotter({ store: editor.store, docId, intervalMs: 5 * 60 * 1000 });
+  return () => snapshotter.stop();
+}, [editor.store, docId]);
+
+// Manual: "save a version now" button.
+async function saveNow(label) {
+  const doc = JSON.parse(exportDocumentJSON(editor.store)); // exportDocumentJSON returns a JSON *string* — parse it first
+  await saveDocumentVersion({ id: crypto.randomUUID(), docId, timestamp: Date.now(), label, doc });
+}
+
+// A version list:
+function VersionList({ docId }) {
+  const { versions, isLoaded } = useDocumentVersions(docId); // newest first
+  if (!isLoaded) return <p>Loading…</p>;
+  return (
+    <ul>
+      {versions.map((v) => (
+        <li key={v.id}>
+          {v.label ?? '(untitled)'} — {new Date(v.timestamp).toLocaleString()}
+          <button onClick={() => applyDocumentTemplate(editor.store, v.doc)}>Restore</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Restoring needs no new function — it's the exact same `applyDocumentTemplate(store, doc)` Templates already uses to wholesale-replace a live editor's content. `saveDocumentVersion`/`loadDocumentVersion`/`deleteDocumentVersion`/`listDocumentVersions` are the raw storage operations `useDocumentVersions` is built on. `createPeriodicVersionSnapshotter({ store, docId, intervalMs?, label?, maxVersions? })` prunes the oldest version past `maxVersions` (default 50) after each snapshot, so a long-running document doesn't grow the store unbounded.
+
 ## Right-to-left / multi-language text
 
 Every block defaults to `dir="auto"` — the browser's own Unicode bidi algorithm detects direction per block from its first strong character, so a document mixing LTR and RTL blocks (an English heading over an Arabic paragraph, say) just works with zero configuration. For the cases `auto` can't infer on its own (most commonly an empty block, which has no text yet to detect a direction from), set an explicit override:
@@ -499,7 +679,7 @@ What presence *contains* is entirely up to you — a cursor position, a display
 - Concurrent inserts (even at the same position) — both survive, converging to the same order on every peer.
 - Concurrent delete vs. edit of the same block — the delete wins.
 - Concurrent type-conversion of the same block ("Turn into") — one type wins deterministically (the same one, on every peer), not two duplicate blocks.
-- Concurrent edits to a run's text — whole-value last-write-wins (the newer edit replaces the older one entirely; character-level interleaving is not implemented).
+- Concurrent edits to a run's text — merge at the *character* level (a real per-run CRDT, the same ordered-list mechanism blocks already use, just one level down): two peers editing different parts of the same run both survive, and two peers inserting at the exact same position both survive too, interleaved deterministically (identically on every peer) rather than one silently overwriting the other.
 
 ### Tombstone garbage collection
 
@@ -519,11 +699,18 @@ Or call `store.pruneTombstones({ maxAgeMs })` yourself on whatever schedule you
 
 **Why a time-based threshold is safe here specifically:** this only works because of how `CollabSession` reconnects — a peer rejoining after any absence gets a full document *snapshot* (`syncResponse`), never a replay of the ops it missed. That means a peer offline longer than the GC threshold never needs an old tombstone to resolve a stale reference; it just adopts the current state directly. The only residual risk is a single *already-connected* peer somehow stalling for exactly as long as the threshold and then delivering a queued message afterward — implausible for a live, reliable, ordered WebRTC data channel (which disconnects long before that under any real interruption), but not impossible, which is why this is opt-in rather than automatic.
 
+### Reconnecting reliably
+
+`CollabSession`/`createWebSocketSignaling` deliberately don't retry anything themselves (see the class doc comment) — a dropped connection is a transport-layer concern left to the host app, on purpose, so this stays a small library rather than growing an opinionated retry/backoff policy no two apps would agree on. `examples/lan-collab/` is a complete, runnable reference for the two pieces most apps end up needing on top:
+
+- **A watchdog that actually reconnects.** `createWebSocketSignaling` exposes no `close`/`error` event for the relay connection dying silently (a sleeping laptop, a WiFi drop, the relay restarting) — so periodically checking "do I currently have zero live peers, and has it been a while since I last tried" and, if so, tearing down and recreating the whole signaling + session is the only reliable way to notice and recover. Also worth reacting to the browser's own `online` event immediately, rather than waiting for the next timer tick.
+- **Actually catching up, not just resuming.** A reconnecting peer that keeps its existing (non-empty) store — the right default, so a solo editing session isn't wiped by a network blip — never re-triggers `CollabSession`'s adopt-a-snapshot path, since that only fires when a store is genuinely empty (see "A peer joining with their own existing document" below). Left alone, this peer silently misses everything the room changed while it was away. The fix: on a genuine *reconnect* (never the very first connection) where nothing was typed locally in the gap, reset the store back to that same empty shape first — the same field-level reset `usePersistedDocument` uses internally — so the ordinary adopt-on-empty flow does the catching-up. If local edits *were* made while disconnected, keep them as-is; there's no safe way to both preserve them and adopt someone else's snapshot without a real merge (see the next limitation).
+
 **Known limitations — read before relying on this in production:**
-- **Undo is local-only, and can overwrite a peer's edit to the same run.** Your undo/redo never touches a peer's changes directly — but because text merges as *whole-value* LWW (see above), undoing your own past edit to a run replays an old full-string snapshot, which will clobber anything a peer has since typed into that same run. Avoid undoing text you know a peer may have touched; a true fix requires character-level text merging, which is a deliberately larger, not-yet-built change.
+- **Undo is local-only, and only ever touches your own edits.** Undo/redo of a text edit works by tombstoning/restoring the exact character ids *you* inserted/deleted (not by replaying an old whole-string snapshot), so undoing your own past edit to a run can never remove a peer's concurrent edit to that same run, no matter how they're interleaved. One narrower case remains open: concurrent *formatting* (bold/italic, which splits a run into new runs with new ids) racing a concurrent *edit* of the exact same run is a run-list-level (not character-level) concern this doesn't cover.
 - **Deleted content isn't garbage-collected automatically, but can be — opt-in.** Tombstones are kept by default (needed so a late-arriving concurrent operation can still resolve correctly), which means unbounded memory growth over a long enough session unless you do something about it. `store.pruneTombstones({ maxAgeMs })` (default 24h) removes tombstones older than that safely — see "Tombstone garbage collection" above. Nothing calls this automatically; wire up `createPeriodicTombstoneGC` (or call it yourself) if you want it handled for you.
-- **A peer joining with their own existing (different) document does not merge with yours.** `CollabSession` only adopts a peer's document wholesale when your own side is still empty — the common "open a shared link and get the document" flow. Reconciling two independently-created, already-diverged documents on first contact is a fundamentally harder problem (no shared id space) and isn't attempted.
-- **Reconnecting after a dropped connection re-syncs the full document**, not just what was missed — simple and correct, at the cost of O(document size) traffic per reconnect.
+- **A peer joining with their own existing (different) document does not merge with yours.** `CollabSession` only adopts a peer's document wholesale when your own side is still empty — the common "open a shared link and get the document" flow. Reconciling two independently-created, already-diverged documents on first contact is a fundamentally harder problem (no shared id space) and isn't attempted. This is also why the reconnect pattern above only ever resets a store that has no unsynced local edits of its own.
+- **Reconnecting after a dropped connection re-syncs the full document**, not just what was missed — simple and correct, at the cost of O(document size) traffic per reconnect. See "Reconnecting reliably" above for making the reconnect itself actually happen.
 - Only structural block changes and field edits (props, type, run text) are collaboration-aware. A few coarse "resync" operations (`setBlockContentIds`, `replaceRunSpan`, `setBlockRuns` — used for DOM-reconciliation escape hatches like paste-into-contentEditable or IME composition) remain local-only for now.
 - Large single messages (e.g. an embedded video/file's `data:` URL, or a full-document `syncResponse` for a big document) are transparently fragmented, flow-controlled against the data channel's own backpressure, and reassembled under the hood — you don't need to do anything for this, but very large embeds mean more individual send calls and somewhat higher latency to fully arrive.
 
@@ -637,3 +824,4 @@ See `examples/README.md` for the rest of the runnable examples, and `CONTRIBUTIN
 - RTL support covers direction resolution (`dir="auto"` + per-block/document override) and the highest-impact visual pieces (list markers, blockquote border, block gutter position) — a full logical-properties rewrite of every hardcoded pixel value in `style.css` is a bigger follow-up, not yet done.
 - Voice typing (`useVoiceTyping`) only acts on *finalized* speech results, not interim/in-progress ones, and command detection requires a spoken command to be its own complete utterance — there's no explicit "command mode" trigger (push-to-command, wake phrase) yet, just pause-based auto-detection.
 - Automated tests run under jsdom; there is no automated real-browser test suite. If you hit an edge case jsdom can't reproduce (anything involving actual native `contentEditable` browser quirks, or the real Web Speech API), please file an issue with the exact browser/OS and steps.
+- A comment's highlighted range is local-only in collaboration for v1 (same scope every other range-based formatting operation already has — see [Comments](#comments)); a comment thread's `anchorRunIds` is a creation-time hint only, not re-validated after later formatting edits reshape that range.

package/dist/index.d.ts

@@ -38,11 +38,28 @@ export interface FieldType {
   [key: string]: unknown;
 }
 
+export interface CommentMessage {
+  id: string;
+  authorId: string;
+  text: string;
+  createdAt: number;
+}
+
+export interface CommentThread {
+  id: string;
+  blockId: string;
+  /** Creation-time hint only, not re-validated after later formatting edits -- see the README's documented limitation. */
+  anchorRunIds: string[];
+  resolved: boolean;
+  messages: CommentMessage[];
+}
+
 export interface DocumentJSON {
   rootId: string;
   blocks: Block[];
   runs: Run[];
   fieldTypes?: FieldType[];
+  comments?: CommentThread[];
 }
 
 export type Operation = { type: string; [key: string]: unknown };
@@ -68,6 +85,11 @@ export const OP: {
   ADD_FIELD_TYPE: 'addFieldType';
   UPDATE_FIELD_TYPE: 'updateFieldType';
   REMOVE_FIELD_TYPE: 'removeFieldType';
+  ADD_COMMENT_THREAD: 'addCommentThread';
+  REMOVE_COMMENT_THREAD: 'removeCommentThread';
+  ADD_COMMENT_REPLY: 'addCommentReply';
+  REMOVE_COMMENT_REPLY: 'removeCommentReply';
+  RESOLVE_COMMENT: 'resolveComment';
 };
 
 export namespace operations {
@@ -83,6 +105,11 @@ export namespace operations {
   export function addFieldType(fieldType: FieldType): Operation;
   export function updateFieldType(id: string, patch: Partial<FieldType>): Operation;
   export function removeFieldType(id: string): Operation;
+  export function addCommentThread(thread: CommentThread): Operation;
+  export function removeCommentThread(commentId: string): Operation;
+  export function addCommentReply(commentId: string, message: CommentMessage): Operation;
+  export function removeCommentReply(commentId: string, messageId: string): Operation;
+  export function resolveComment(commentId: string, resolved: boolean): Operation;
 }
 
 // ---------------------------------------------------------------------------
@@ -95,11 +122,16 @@ export class EditorStore {
   runs: Map<string, Run>;
   rootId: string | null;
   fieldTypes: Map<string, FieldType>;
+  comments: Map<string, CommentThread>;
 
   getBlock(id: string): Block | undefined;
   getRun(id: string): Run | undefined;
   getFieldTypes(): FieldType[];
   getFieldType(id: string): FieldType | undefined;
+  getComments(): CommentThread[];
+  getComment(id: string): CommentThread | undefined;
+  /** Every run id in the whole document, regardless of reachability from the root -- see removeCommentMarkEverywhere. */
+  getAllRunIds(): string[];
   getRootId(): string | null;
   subscribe(id: string, listener: () => void): () => void;
   subscribeAll(listener: () => void): () => void;
@@ -145,6 +177,9 @@ export class History {
   getRootId(): string | null;
   getFieldTypes(): FieldType[];
   getFieldType(id: string): FieldType | undefined;
+  getComments(): CommentThread[];
+  getComment(id: string): CommentThread | undefined;
+  getAllRunIds(): string[];
   subscribe(id: string, listener: () => void): () => void;
   subscribeAll(listener: () => void): () => void;
   getTombstoneCount(): number;
@@ -284,6 +319,164 @@ export function createAutoPersistence(options: {
   onError?: (error: unknown) => void;
 }): { stop: () => void; flush: () => void };
 
+// ---------------------------------------------------------------------------
+// templates/ (+ the template half of persistence/)
+// ---------------------------------------------------------------------------
+
+/** One captured block-template root — see captureBlockTemplate. */
+export interface BlockTemplate {
+  roots: CapturedSubtree[];
+}
+
+export interface StoredTemplate {
+  id: string;
+  scope: 'document' | 'block';
+  name: string;
+  description?: string;
+  /** A full DocumentJSON for scope 'document', or a BlockTemplate ({ roots }) for scope 'block'. */
+  doc: DocumentJSON | BlockTemplate;
+}
+
+export function saveTemplate(template: StoredTemplate): Promise<void>;
+export function loadTemplate(id: string): Promise<StoredTemplate | null>;
+export function deleteTemplate(id: string): Promise<void>;
+export function listTemplates(): Promise<StoredTemplate[]>;
+
+export function captureBlockTemplate(store: EditorStore | History, blockIds: string[]): BlockTemplate;
+export function insertBlockTemplate(
+  store: EditorStore | History,
+  template: BlockTemplate,
+  position: { parentId: string; index: number },
+): void;
+/** Wholesale-replaces an already-mounted editor's content with a document template. To start a NEW editor from one instead, just pass it as useEditor({ doc }). */
+export function applyDocumentTemplate(store: EditorStore | History, doc: DocumentJSON): void;
+
+export interface BlockTemplateDefinition {
+  id: string;
+  label: string;
+  icon?: ComponentType<{ size?: number }>;
+  keywords?: string[];
+  roots: CapturedSubtree[];
+}
+
+/** Registers block templates as slash commands, discoverable/insertable via "/" alongside every built-in block — no SlashMenu/BlockRegistry changes needed. */
+export function registerBlockTemplates(registry: BlockRegistry, templates: BlockTemplateDefinition[]): void;
+
+export function useTemplates(options?: { scope?: 'document' | 'block' }): {
+  templates: StoredTemplate[];
+  isLoaded: boolean;
+  refresh: () => Promise<void>;
+};
+
+export interface TemplatePickerProps {
+  templates: StoredTemplate[];
+  onSelect: (template: StoredTemplate) => void;
+  emptyLabel?: string;
+}
+
+export const TemplatePicker: ComponentType<TemplatePickerProps>;
+
+// ---------------------------------------------------------------------------
+// versions/ (+ the version half of persistence/)
+// ---------------------------------------------------------------------------
+
+export interface DocumentVersion {
+  id: string;
+  docId: string;
+  timestamp: number;
+  label?: string;
+  doc: DocumentJSON;
+}
+
+export function saveDocumentVersion(version: DocumentVersion): Promise<void>;
+export function loadDocumentVersion(id: string): Promise<DocumentVersion | null>;
+export function deleteDocumentVersion(id: string): Promise<void>;
+/** All versions saved for docId, newest first. */
+export function listDocumentVersions(docId: string): Promise<DocumentVersion[]>;
+
+/** Periodically snapshots a live document into the versions store; prunes oldest beyond maxVersions for this docId. Restore with applyDocumentTemplate(store, version.doc). */
+export function createPeriodicVersionSnapshotter(options: {
+  store: History | EditorStore;
+  docId: string;
+  intervalMs?: number;
+  label?: string;
+  maxVersions?: number;
+  onSnapshot?: (version: DocumentVersion) => void;
+  onError?: (error: unknown) => void;
+}): { stop: () => void };
+
+export function useDocumentVersions(docId: string | null | undefined): {
+  versions: DocumentVersion[];
+  isLoaded: boolean;
+  refresh: () => Promise<void>;
+};
+
+// ---------------------------------------------------------------------------
+// comments/
+// ---------------------------------------------------------------------------
+
+export interface CommentRange {
+  blockId: string;
+  startRunId: string;
+  startOffset: number;
+  endRunId: string;
+  endOffset: number;
+}
+
+/** Creates a comment thread anchored to `range`, highlighting it and creating the thread as one atomic undo step. Returns the new comment's id. */
+export function addComment(store: EditorStore | History, range: CommentRange, message: { authorId: string; text: string }): string;
+/** Appends a reply to an existing thread. Returns the new message's id. */
+export function replyToComment(store: EditorStore | History, commentId: string, message: { authorId: string; text: string }): string;
+/** Flips a thread's resolved flag (defaults to true). */
+export function resolveComment(store: EditorStore | History, commentId: string, resolved?: boolean): void;
+/** Removes a thread and strips its highlight from every run that still carries it, as one atomic undo step. */
+export function deleteComment(store: EditorStore | History, commentId: string): void;
+
+/** Computes (does not apply) the op that highlights `range` with `commentId` -- for advanced use; addComment already calls this. Returns null for a collapsed/unresolvable range. */
+export function addCommentMarkOverRange(store: EditorStore | History, range: CommentRange, commentId: string): Operation | null;
+/** Computes (does not apply) the ops that strip `commentId` from every run in the document that carries it. */
+export function removeCommentMarkEverywhere(store: EditorStore | History, commentId: string): Operation[];
+
+export function useComments(): CommentThread[];
+
+export interface CommentComposerProps {
+  /** Renders the composer's own avatar preview -- does not decide who the message is attributed to (the caller still passes authorId to addComment/replyToComment). */
+  authorId?: string;
+  placeholder?: string;
+  autoFocus?: boolean;
+  onSubmit: (text: string) => void;
+  /** Renders a Cancel button when given. */
+  onCancel?: () => void;
+}
+
+/** An avatar + textarea + send button for composing one comment message -- the shared piece CommentThreadCard's reply flow and FloatingToolbar's built-in Comment composer both use. */
+export const CommentComposer: ComponentType<CommentComposerProps>;
+
+export interface CommentAvatarProps {
+  authorId?: string;
+  size?: number;
+}
+
+/** A small colored circle with the author's initials, deterministically generated from authorId -- this package has no profile-picture/identity concept of its own. */
+export const CommentAvatar: ComponentType<CommentAvatarProps>;
+
+export interface CommentThreadCardProps {
+  store: EditorStore | History;
+  thread: CommentThread;
+  /** Hides the Reply action when not given -- composing a message needs an author. */
+  authorId?: string;
+}
+
+/** One comment thread -- messages, then Reply/Resolve/Delete. Shared by CommentPopover (click/hover on highlighted text, mounted automatically) and CommentsPanel. */
+export const CommentThreadCard: ComponentType<CommentThreadCardProps>;
+
+export interface CommentsPanelProps {
+  authorId?: string;
+}
+
+/** The opt-in right-side comments panel (Notion/Google Docs-style) -- see NoteloomEditorProps.showCommentsPanel, or render it yourself anywhere under an EditorProvider for the granular API. */
+export const CommentsPanel: ComponentType<CommentsPanelProps>;
+
 // ---------------------------------------------------------------------------
 // registry/, blocks/, inlineTypes/
 // ---------------------------------------------------------------------------
@@ -347,6 +540,7 @@ export const codeBlockType: BlockTypeDefinition;
 export const toggleHeadingBlockType: BlockTypeDefinition;
 export const buttonBlockType: BlockTypeDefinition;
 export const embedBlockType: BlockTypeDefinition;
+export const canvasBlockType: BlockTypeDefinition;
 
 export function registerBuiltInInlineTypes(inlineRegistry: InlineRegistry): void;
 export function registerInlineTypes(inlineRegistry: InlineRegistry, types: Record<string, InlineTypeDefinition>): void;
@@ -371,6 +565,8 @@ export interface EditorProviderProps {
   style?: CSSProperties;
   theme?: 'default' | 'none';
   getBlockClassName?: (block: Block) => string | undefined;
+  /** Current user's id for authoring comments through the built-in comment UI -- see useCommentAuthorId. */
+  commentAuthorId?: string;
   children?: ReactNode;
 }
 
@@ -382,6 +578,8 @@ export function useWholeDocumentSelection(): [boolean, (value: boolean) => void]
 export function useBlockRangeSelection(): [string[], (ids: string[]) => void];
 export function useSelectedBlock(): [string | null, (id: string | null) => void];
 export function usePreviewMode(): [boolean, (value: boolean) => void];
+/** The commentAuthorId passed to EditorProvider/NoteloomEditor, or undefined if not configured -- see NoteloomEditorProps.commentAuthorId. */
+export function useCommentAuthorId(): string | undefined;
 export function useFieldTypeEditor(): {
   editingFieldTypeId: string | null;
   openFieldTypeEditor: (id: string | null) => void;
@@ -453,13 +651,34 @@ export const EditorTrailingSpace: ComponentType<Record<string, unknown>>;
 // clipboard/
 // ---------------------------------------------------------------------------
 
+export interface CapturedSubtree {
+  rootId: string;
+  blocks: Block[];
+  runs: Run[];
+}
+
+export interface RemappedSubtree {
+  block: Block;
+  runs: Run[];
+  subtreeBlocks: Block[];
+}
+
 export const APP_MIME: string;
-export function serializeBlockRange(...args: unknown[]): unknown;
-export function remapSubtreeIds(...args: unknown[]): unknown;
+export function serializeBlockRange(
+  store: EditorStore | History,
+  registry: BlockRegistry,
+  blockIds: string[],
+  inlineRegistry?: InlineRegistry,
+): { html: string; text: string; json: string };
+/** Read-only capture of one block + its descendants, with original ids intact — see also captureBlockTemplate for capturing several sibling roots at once. */
+export function captureSubtree(store: EditorStore | History, rootId: string): CapturedSubtree;
+/** Gives a captured subtree fresh ids, ready to insert elsewhere without colliding with existing content. */
+export function remapSubtreeIds(captured: CapturedSubtree): RemappedSubtree;
 export function deserializeClipboard(...args: unknown[]): unknown;
 export function walkDomToBlocks(...args: unknown[]): unknown;
 export function textToParagraphs(...args: unknown[]): unknown;
-export function exportDocumentJSON(store: EditorStore | History): unknown;
+/** Returns a JSON *string* (pretty-printed by default) — parse it (`JSON.parse`) to get back a plain `{ version, rootId, blocks, runs }` object usable as `useEditor({ doc })`. */
+export function exportDocumentJSON(store: EditorStore | History, options?: { pretty?: boolean }): string;
 export function exportDocumentHTML(store: EditorStore | History, registry: BlockRegistry): string;
 export function exportDocumentText(store: EditorStore | History, registry: BlockRegistry): string;
 export function exportDocumentSimpleJSON(store: EditorStore | History, registry: BlockRegistry, inlineRegistry: InlineRegistry): unknown;
@@ -503,6 +722,10 @@ export interface FloatingToolbarProps {
   crossSelection: unknown;
   marks: Record<string, unknown>;
   store: EditorStore | History;
+  /** Adds a Comment button (same-block selections only) that calls this with the CommentRange under the current selection. Takes priority over commentAuthorId's built-in composer when both are given. */
+  onComment?: (range: CommentRange) => void;
+  /** Adds a Comment button using a built-in inline composer (addComment(store, range, {authorId: commentAuthorId, text})) instead of onComment -- see NoteloomEditorProps.commentAuthorId. */
+  commentAuthorId?: string;
 }
 
 export const FloatingToolbar: ComponentType<FloatingToolbarProps>;
@@ -613,6 +836,12 @@ export interface NoteloomEditorProps {
   style?: CSSProperties;
   theme?: 'default' | 'none';
   getBlockClassName?: (block: Block) => string | undefined;
+  /** Adds a Comment button to the floating format toolbar, fully host-controlled — see FloatingToolbarProps.onComment. */
+  onComment?: (range: CommentRange) => void;
+  /** Current user's id -- enables the whole built-in comments UI (floating toolbar composer, click/hover popover on existing highlights, CommentsPanel) with no host UI code. Ignored by the floating toolbar's button when onComment is also given. */
+  commentAuthorId?: string;
+  /** Renders CommentsPanel (right-side, Notion/Google Docs-style thread list) automatically. */
+  showCommentsPanel?: boolean;
   children?: ReactNode;
 }