noteloom 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -6,7 +6,14 @@
 // every export still gets *something* useful rather than `any`. No `.js`/
 // `.jsx` source was changed to produce this file.
 
-import type { ComponentType, ReactNode, ReactElement, CSSProperties, RefObject, ClipboardEvent } from 'react';
+import type {
+  ComponentType,
+  ReactNode,
+  ReactElement,
+  CSSProperties,
+  RefObject,
+  ClipboardEvent,
+} from 'react';
 
 // ---------------------------------------------------------------------------
 // Document shape
@@ -93,11 +100,20 @@ export const OP: {
 };
 
 export namespace operations {
-  export function insertBlock(block: Block, parentId: string, index: number, subtree?: { blocks: Block[]; runs: Run[] }): Operation;
+  export function insertBlock(
+    block: Block,
+    parentId: string,
+    index: number,
+    subtree?: { blocks: Block[]; runs: Run[] },
+  ): Operation;
   export function removeBlock(id: string): Operation;
   export function moveBlock(id: string, toParentId: string, toIndex: number): Operation;
   export function updateBlockProps(id: string, patch: Record<string, unknown>): Operation;
-  export function changeBlockType(id: string, blockType: string, props: Record<string, unknown>): Operation;
+  export function changeBlockType(
+    id: string,
+    blockType: string,
+    props: Record<string, unknown>,
+  ): Operation;
   export function updateRun(id: string, patch: Record<string, unknown>): Operation;
   export function setBlockContentIds(blockId: string, contentIds: string[]): Operation;
   export function replaceRunSpan(blockId: string, oldRunIds: string[], newRuns: Run[]): Operation;
@@ -285,13 +301,21 @@ export function encodeMessage(message: unknown): string;
 export function decodeMessage(raw: string): unknown;
 
 export class PeerConnection {
-  constructor(options: { peerConnection: RTCPeerConnection; dataChannel?: RTCDataChannel; onMessage?: (message: unknown) => void });
+  constructor(options: {
+    peerConnection: RTCPeerConnection;
+    dataChannel?: RTCDataChannel;
+    onMessage?: (message: unknown) => void;
+  });
   send(message: unknown): void;
   close(): void;
 }
 
 export class CollabSession {
-  constructor(options: { history: History | EditorStore; signaling: SignalingChannel; presenceThrottleMs?: number });
+  constructor(options: {
+    history: History | EditorStore;
+    signaling: SignalingChannel;
+    presenceThrottleMs?: number;
+  });
   connect(remotePeerId: string, options: { initiator: boolean }): void;
   disconnect(remotePeerId: string): void;
   destroy(): void;
@@ -321,7 +345,7 @@ export function createAutoPersistence(options: {
   docId: string;
   debounceMs?: number;
   onError?: (error: unknown) => void;
-}): { stop: () => void; flush: () => void };
+}): { stop: () => void; flush: () => Promise<void> };
 
 // ---------------------------------------------------------------------------
 // templates/ (+ the template half of persistence/)
@@ -346,7 +370,10 @@ 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 captureBlockTemplate(
+  store: EditorStore | History,
+  blockIds: string[],
+): BlockTemplate;
 export function insertBlockTemplate(
   store: EditorStore | History,
   template: BlockTemplate,
@@ -364,7 +391,10 @@ export interface BlockTemplateDefinition {
 }
 
 /** 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 registerBlockTemplates(
+  registry: BlockRegistry,
+  templates: BlockTemplateDefinition[],
+): void;
 
 export function useTemplates(options?: { scope?: 'document' | 'block' }): {
   templates: StoredTemplate[];
@@ -434,7 +464,10 @@ export function useDocumentVersions(docId: string | null | undefined): {
  * `.be-version-diff-removed` spans. Used internally by `<VersionHistory>`'s
  * "Changes" tab; exported for building a custom version-history UI.
  */
-export function diffDocumentsHTML(prevDoc: DocumentJSON | null | undefined, nextDoc: DocumentJSON): string;
+export function diffDocumentsHTML(
+  prevDoc: DocumentJSON | null | undefined,
+  nextDoc: DocumentJSON,
+): string;
 
 export interface VersionHistoryProps {
   docId: string;
@@ -458,18 +491,37 @@ export interface CommentRange {
 }
 
 /** 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;
+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;
+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;
+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;
+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 removeCommentMarkEverywhere(
+  store: EditorStore | History,
+  commentId: string,
+): Operation[];
 
 export function useComments(): CommentThread[];
 
@@ -555,7 +607,10 @@ export type BlockTypeDefinition = BlockTypeEntry;
 export type InlineTypeDefinition = InlineTypeEntry;
 
 export function registerBuiltInBlocks(registry: BlockRegistry): void;
-export function registerBlocks(registry: BlockRegistry, types: Record<string, BlockTypeDefinition>): void;
+export function registerBlocks(
+  registry: BlockRegistry,
+  types: Record<string, BlockTypeDefinition>,
+): void;
 export const TABLE_BLOCKS: Record<string, BlockTypeDefinition>;
 export const LAYOUT_BLOCKS: Record<string, BlockTypeDefinition>;
 
@@ -577,7 +632,10 @@ export const embedBlockType: BlockTypeDefinition;
 export const canvasBlockType: BlockTypeDefinition;
 
 export function registerBuiltInInlineTypes(inlineRegistry: InlineRegistry): void;
-export function registerInlineTypes(inlineRegistry: InlineRegistry, types: Record<string, InlineTypeDefinition>): void;
+export function registerInlineTypes(
+  inlineRegistry: InlineRegistry,
+  types: Record<string, InlineTypeDefinition>,
+): void;
 export const TABLE_SELECT_INLINE_TYPES: Record<string, InlineTypeDefinition>;
 
 export const selectInlineType: InlineTypeDefinition;
@@ -586,6 +644,120 @@ export const checkboxInlineType: InlineTypeDefinition;
 export const tableSelectInlineType: InlineTypeDefinition;
 export const emojiInlineType: InlineTypeDefinition;
 
+// ---------------------------------------------------------------------------
+// registry/define.js, starter-kit.js — the defineBlock/defineInline factories
+// ---------------------------------------------------------------------------
+
+export interface DefineBlockConfig {
+  /** Unique — used as the block `type`. */
+  name: string;
+  /** React component, receives `{ id }`. */
+  component: ComponentType<{ id: string }>;
+  /** 'blocks' (default, holds child blocks) | 'runs' | 'void' (both leaves). */
+  contentModel?: 'blocks' | 'runs' | 'void';
+  /** Escape hatch — set `isLeaf` directly instead of `contentModel`. */
+  isLeaf?: boolean;
+  defaultProps?: Record<string, unknown>;
+  toHTML?: (block: Block, ctx: unknown) => string;
+  fromHTML?: (node: unknown, ctx: unknown) => unknown;
+  toPlainText?: (block: Block, ctx: unknown) => string;
+  toMarkdown?: (block: Block, ctx: unknown) => string;
+  slashCommand?: unknown;
+  slashCommands?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface DefineInlineConfig {
+  name: string;
+  component: ComponentType<{ id: string }>;
+  /** Only `true` (the default) is supported today. */
+  atomic?: boolean;
+  isAtomic?: boolean;
+  toHTML?: (run: Run, ctx: unknown) => string;
+  fromHTML?: (node: unknown, ctx: unknown) => unknown;
+  toPlainText?: (run: Run, ctx: unknown) => string;
+  slashCommand?: unknown;
+  slashCommands?: unknown[];
+  atCommand?: unknown;
+  atCommands?: unknown[];
+  [key: string]: unknown;
+}
+
+/** A `defineBlock()` result — a `BlockRegistry` entry tagged `kind: 'block'`. */
+export type BlockDefinition = BlockTypeDefinition & { name: string; kind: 'block' };
+/** A `defineInline()` result — an `InlineRegistry` entry tagged `kind: 'inline'`. */
+export type InlineDefinition = InlineTypeDefinition & { name: string; kind: 'inline' };
+/** A `defineExtension()` result — a named bundle of block/inline definitions and/or behavior. */
+export interface ExtensionBundle {
+  name: string;
+  kind: 'extension';
+  blocks: BlockDefinition[];
+  inlineTypes: InlineDefinition[];
+  keymap?: Record<string, KeymapHandler>;
+  onBeforeInput?: ExtensionEventHandler;
+  onPaste?: ExtensionEventHandler;
+  setup?: (ctx: ExtensionCtx) => void | (() => void);
+  [key: string]: unknown;
+}
+export type Extension = BlockDefinition | InlineDefinition | ExtensionBundle;
+
+/** The stable facade passed to every `defineExtension()` behavior handler. */
+export interface ExtensionCtx {
+  store: EditorStore | History;
+  registry: BlockRegistry;
+  inlineRegistry: InlineRegistry;
+  /** The editor's root element (null before mount). */
+  readonly container: HTMLElement | null;
+  getBlock(id: string): Block | undefined;
+  getRun(id: string): Run | undefined;
+  getRootId(): string | null;
+  /** Apply an operation, flushing React synchronously so the DOM is current before `setCaret`. */
+  applyOperation(op: Operation): void;
+  applyOperations(ops: Operation[]): void;
+  getSelection(): { blockId: string; runId: string; startOffset: number; endOffset: number } | null;
+  getCaret(): { blockId: string; runId: string; offset: number } | null;
+  setCaret(runId: string, offset: number): void;
+  subscribe(listener: () => void): () => void;
+}
+
+/** A keymap handler — return truthy to mark the key handled. */
+export type KeymapHandler = (ctx: ExtensionCtx, event: KeyboardEvent) => boolean | void;
+/** A beforeinput/paste handler — return truthy to mark the event handled. */
+export type ExtensionEventHandler = (ctx: ExtensionCtx, event: Event) => boolean | void;
+
+export interface DefineExtensionConfig {
+  /** Label for the bundle / diagnostics. */
+  name: string;
+  blocks?: BlockDefinition[];
+  inlineTypes?: InlineDefinition[];
+  /** `{ 'Mod-Shift-x': (ctx, event) => boolean }` — `Mod` is Ctrl/Cmd. */
+  keymap?: Record<string, KeymapHandler>;
+  onBeforeInput?: ExtensionEventHandler;
+  onPaste?: ExtensionEventHandler;
+  /** Runs once on mount; may return a cleanup function. */
+  setup?: (ctx: ExtensionCtx) => void | (() => void);
+  [key: string]: unknown;
+}
+
+export function defineBlock(config: DefineBlockConfig): BlockDefinition;
+export function defineInline(config: DefineInlineConfig): InlineDefinition;
+/** Groups block/inline definitions and/or behavior (keymap/onBeforeInput/onPaste/setup) under one name. */
+export function defineExtension(config: DefineExtensionConfig): ExtensionBundle;
+
+/** Opt-in typing behavior: straight quotes -> curly. */
+export function smartQuotes(): ExtensionBundle;
+/** Opt-in typing behavior: auto-close `(` `[` `{`. */
+export function autoPairBrackets(): ExtensionBundle;
+
+/** Registers a flat/nested array of `defineBlock()` / `defineInline()` results (and `defineExtension()` bundles) onto the given registries. */
+export function registerExtensions(
+  extensions: ReadonlyArray<Extension | ReadonlyArray<Extension>>,
+  registries: { registry?: BlockRegistry; inlineRegistry?: InlineRegistry },
+): void;
+
+/** Every built-in block + inline type as an `extensions` array. `exclude` drops types by name. */
+export function starterKit(options?: { exclude?: string[] }): Extension[];
+
 // ---------------------------------------------------------------------------
 // react/ — provider, core hooks
 // ---------------------------------------------------------------------------
@@ -601,6 +773,15 @@ export interface EditorProviderProps {
   getBlockClassName?: (block: Block) => string | undefined;
   /** Current user's id for authoring comments through the built-in comment UI -- see useCommentAuthorId. */
   commentAuthorId?: string;
+  /** Whether CodeBlock renders its line-number gutter -- see useShowLineNumbers. */
+  showLineNumbers?: boolean;
+  /** Sends a picked/dropped EmbedBlock file somewhere real (local disk, S3, any other cloud storage) instead of inlining it as a data: URL -- see useFileUpload's own doc comment for the full contract. */
+  uploadFile?: (
+    file: File,
+    ctx: { kind: 'image' | 'video' | 'audio' | 'file' },
+  ) => Promise<{ src: string; name?: string; mimeType?: string }>;
+  /** Byte cap for the in-document data: URL fallback ONLY (no effect once uploadFile is configured) -- an oversized file is rejected with a clear error instead of bloating the document. */
+  maxFileSize?: number;
   children?: ReactNode;
 }
 
@@ -614,12 +795,25 @@ 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;
+/** Whether CodeBlock should render its line-number gutter -- see EditorProviderProps.showLineNumbers. */
+export function useShowLineNumbers(): boolean;
+/** `{ uploadFile, maxFileSize }` from EditorProvider -- see EditorProviderProps and useFileUpload's own doc comment for the full contract. */
+export function useFileUpload(): {
+  uploadFile?: (
+    file: File,
+    ctx: { kind: 'image' | 'video' | 'audio' | 'file' },
+  ) => Promise<{ src: string; name?: string; mimeType?: string }>;
+  maxFileSize?: number;
+};
 export function useFieldTypeEditor(): {
   editingFieldTypeId: string | null;
   openFieldTypeEditor: (id: string | null) => void;
   closeFieldTypeEditor: () => void;
 };
-export function useBlockClassName(baseClassName: string | undefined, block: Block): string | undefined;
+export function useBlockClassName(
+  baseClassName: string | undefined,
+  block: Block,
+): string | undefined;
 
 export function injectDefaultStyles(): void;
 
@@ -642,9 +836,15 @@ export function usePersistedDocument(options: {
   docId: string;
   debounceMs?: number;
   onError?: (error: unknown) => void;
-}): { isLoaded: boolean };
+  /** Wires Ctrl/Cmd+S to save() and blocks the browser's own save-page dialog. Default true. */
+  saveShortcut?: boolean;
+  /** Fires after every save() completes (shortcut-triggered or manual). */
+  onSave?: () => void;
+}): { isLoaded: boolean; save: () => Promise<void> };
 
-export function usePresence(session: CollabSession | null | undefined): Map<string, Record<string, unknown>>;
+export function usePresence(
+  session: CollabSession | null | undefined,
+): Map<string, Record<string, unknown>>;
 
 export function useServiceWorkerUpdate(): { updateAvailable: boolean; applyUpdate: () => void };
 
@@ -677,7 +877,12 @@ export const MobileActionBar: ComponentType<{ containerRef: RefObject<HTMLElemen
 export const MobileBlockPickerSheet: ComponentType<Record<string, unknown>>;
 export const MobileBlockOptionsSheet: ComponentType<Record<string, unknown>>;
 export const EditableBlockContent: ComponentType<Record<string, unknown>>;
-export const Modal: ComponentType<{ isOpen?: boolean; onClose?: () => void; children?: ReactNode; [key: string]: unknown }>;
+export const Modal: ComponentType<{
+  isOpen?: boolean;
+  onClose?: () => void;
+  children?: ReactNode;
+  [key: string]: unknown;
+}>;
 export const Select: ComponentType<Record<string, unknown>>;
 export const EditorTrailingSpace: ComponentType<Record<string, unknown>>;
 
@@ -712,11 +917,47 @@ export function deserializeClipboard(...args: unknown[]): unknown;
 export function walkDomToBlocks(...args: unknown[]): unknown;
 export function textToParagraphs(...args: unknown[]): 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 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;
-export function importDocumentSimpleJSON(json: unknown, registry: BlockRegistry, inlineRegistry: InlineRegistry): DocumentJSON;
+export function exportDocumentMarkdown(
+  store: EditorStore | History,
+  registry: BlockRegistry,
+  inlineRegistry?: InlineRegistry,
+): string;
+export function exportDocumentWordHTML(
+  store: EditorStore | History,
+  registry: BlockRegistry,
+  inlineRegistry?: InlineRegistry,
+): string;
+/** A `{ id, type, data, children? }` block in the simple document format. */
+export interface SimpleBlock {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+  children?: SimpleBlock[];
+}
+/** The canonical interchange format — see docs/document.schema.json. */
+export interface SimpleDocument {
+  version: 1;
+  blocks: SimpleBlock[];
+}
+export function exportDocumentSimpleJSON(
+  store: EditorStore | History,
+  registry: BlockRegistry,
+  inlineRegistry: InlineRegistry,
+  options?: { pretty?: boolean },
+): string;
+export function importDocumentSimpleJSON(
+  json: string | SimpleDocument,
+  registry: BlockRegistry,
+  inlineRegistry: InlineRegistry,
+): DocumentJSON;
+/** True when `doc` is a `SimpleDocument` rather than the internal `DocumentJSON` shape. */
+export function isSimpleDocument(doc: unknown): doc is SimpleDocument;
 export const DocumentExportButton: ComponentType<Record<string, unknown>>;
 
 // ---------------------------------------------------------------------------
@@ -744,9 +985,15 @@ export interface SlashMenuProps {
 }
 
 export const SlashMenu: ComponentType<SlashMenuProps>;
-export function useSlashMenuTrigger(containerRef: RefObject<HTMLElement | null>): CommandMenuTriggerState;
-export function useEmojiMenuTrigger(containerRef: RefObject<HTMLElement | null>): CommandMenuTriggerState;
-export function useAtMenuTrigger(containerRef: RefObject<HTMLElement | null>): CommandMenuTriggerState;
+export function useSlashMenuTrigger(
+  containerRef: RefObject<HTMLElement | null>,
+): CommandMenuTriggerState;
+export function useEmojiMenuTrigger(
+  containerRef: RefObject<HTMLElement | null>,
+): CommandMenuTriggerState;
+export function useAtMenuTrigger(
+  containerRef: RefObject<HTMLElement | null>,
+): CommandMenuTriggerState;
 
 export interface FloatingToolbarProps {
   isOpen: boolean;
@@ -785,6 +1032,12 @@ export function renameColumn(...args: unknown[]): unknown;
 export function setColumnType(...args: unknown[]): unknown;
 export function setColumnOptions(...args: unknown[]): unknown;
 export function setColumnWidth(...args: unknown[]): unknown;
+export function sortTableByColumn(...args: unknown[]): unknown;
+export function setColumnAggregate(...args: unknown[]): unknown;
+export function computeColumnAggregate(...args: unknown[]): unknown;
+export function formatAggregateValue(value: number | null): string;
+export const AGGREGATE_TYPES: string[];
+export const AGGREGATE_LABELS: Record<string, string>;
 export function resolveColumns(...args: unknown[]): unknown;
 export function createDefaultColumns(...args: unknown[]): unknown;
 export function createCellForColumn(...args: unknown[]): unknown;
@@ -836,8 +1089,14 @@ export function copyBlockRangeToClipboard(...args: unknown[]): unknown;
 // ---------------------------------------------------------------------------
 
 export function createSelectFieldType(options: Record<string, unknown>): InlineTypeDefinition;
-export function registerStoredFieldTypes(inlineRegistry: InlineRegistry, fieldTypes: FieldType[]): void;
-export function useRegisterFieldTypes(inlineRegistry: InlineRegistry, fieldTypes: FieldType[]): void;
+export function registerStoredFieldTypes(
+  inlineRegistry: InlineRegistry,
+  fieldTypes: FieldType[],
+): void;
+export function useRegisterFieldTypes(
+  inlineRegistry: InlineRegistry,
+  fieldTypes: FieldType[],
+): void;
 export const FieldTypeEditorModal: ComponentType<Record<string, unknown>>;
 
 // ---------------------------------------------------------------------------
@@ -845,15 +1104,17 @@ export const FieldTypeEditorModal: ComponentType<Record<string, unknown>>;
 // ---------------------------------------------------------------------------
 
 export interface UseEditorOptions {
-  /** Starting document; defaults to one empty paragraph. */
-  doc?: DocumentJSON;
+  /** Starting document; defaults to one empty paragraph. Accepts either the simple format (`SimpleDocument`, what `editor.toJSON()` returns) or the internal engine shape (`DocumentJSON`) — auto-detected. */
+  doc?: DocumentJSON | SimpleDocument;
   /** true (default): store is undo/redo-aware (a History instance). false: a plain EditorStore. */
   history?: boolean;
   /** Stamped as every edit's actorId (History's defaultActorId) -- used by createAutoVersionHistory/VersionHistory for "who changed this", with no separate identity plumbing needed. Ignored when history: false. */
   currentUserId?: string | null;
-  /** Replaces registerBuiltInBlocks for an opt-in subset of block types. */
+  /** Recommended: an array of `defineBlock()` / `defineInline()` results (nesting allowed), e.g. `[...starterKit(), myBlock]`. Passing it turns off automatic built-in registration; `registerBlocks`/`registerInlineTypes`, if also given, still run afterward. */
+  extensions?: ReadonlyArray<Extension | ReadonlyArray<Extension>>;
+  /** Callback form: replaces registerBuiltInBlocks for an opt-in subset of block types. Runs after `extensions` if both are given. */
   registerBlocks?: (registry: BlockRegistry) => void;
-  /** Replaces registerBuiltInInlineTypes for an opt-in subset of inline types. */
+  /** Callback form: replaces registerBuiltInInlineTypes for an opt-in subset of inline types. Runs after `extensions` if both are given. */
   registerInlineTypes?: (inlineRegistry: InlineRegistry) => void;
 }
 
@@ -861,6 +1122,10 @@ export interface UseEditorResult {
   store: History | EditorStore;
   registry: BlockRegistry;
   inlineRegistry: InlineRegistry;
+  /** The flattened `extensions` list, forwarded to `<NoteloomEditor>` for the behavior half. */
+  extensions: Extension[];
+  /** Read the live document out. `'simple'` (default) → `SimpleDocument`; `'internal'` → `DocumentJSON`. */
+  toJSON(options?: { format?: 'simple' | 'internal' }): SimpleDocument | DocumentJSON;
 }
 
 /** The one-call path to a working editor — see the README's Quick start. */
@@ -878,8 +1143,103 @@ export interface NoteloomEditorProps {
   commentAuthorId?: string;
   /** Renders CommentsPanel (right-side, Notion/Google Docs-style thread list) automatically. */
   showCommentsPanel?: boolean;
+  /** Sends a picked/dropped EmbedBlock file somewhere real (local disk, S3, any other cloud storage) instead of inlining it as a data: URL -- see useFileUpload's own doc comment for the full contract. */
+  uploadFile?: (
+    file: File,
+    ctx: { kind: 'image' | 'video' | 'audio' | 'file' },
+  ) => Promise<{ src: string; name?: string; mimeType?: string }>;
+  /** Byte cap for the in-document data: URL fallback ONLY (no effect once uploadFile is configured). */
+  maxFileSize?: number;
   children?: ReactNode;
 }
 
 /** Renders the object useEditor() returned, with every built-in interaction wired up. */
 export function NoteloomEditor(props: NoteloomEditorProps): ReactElement;
+
+export interface FindMatch {
+  blockId: string;
+  runId: string;
+  offset: number;
+  length: number;
+}
+
+/** Finds every occurrence of `query` in the document, in reading order — single-run matches only (see the implementation's own doc comment for scope). */
+export function findMatches(
+  store: EditorStore | History,
+  query: string,
+  options?: { caseSensitive?: boolean; wholeWord?: boolean },
+): FindMatch[];
+/** Replaces one match's own slice of its run's text, one atomic write. */
+export function replaceMatch(
+  store: EditorStore | History,
+  match: FindMatch,
+  replacement: string,
+): void;
+/** Replaces every given match, one write per affected run, one atomic undo step. */
+export function replaceAllMatches(
+  store: EditorStore | History,
+  matches: FindMatch[],
+  replacement: string,
+): void;
+
+export interface UseFindInDocumentResult {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  query: string;
+  setQuery: (value: string) => void;
+  caseSensitive: boolean;
+  setCaseSensitive: (value: boolean) => void;
+  wholeWord: boolean;
+  setWholeWord: (value: boolean) => void;
+  isReplaceOpen: boolean;
+  setIsReplaceOpen: (value: boolean) => void;
+  replacement: string;
+  setReplacement: (value: string) => void;
+  matches: FindMatch[];
+  currentIndex: number;
+  next: () => void;
+  prev: () => void;
+  replaceCurrent: () => void;
+  replaceAll: () => void;
+  queryInputRef: RefObject<HTMLInputElement | null>;
+}
+
+/** Ctrl/Cmd+F (while `containerRef` has focus) find/replace — see NoteloomEditor's own doc comment for scope. Pair with `<FindBar>`, or build custom chrome off this hook's returned state/actions directly. */
+export function useFindInDocument(
+  containerRef: RefObject<HTMLElement | null>,
+): UseFindInDocumentResult;
+export function FindBar(props: UseFindInDocumentResult): ReactElement | null;
+
+// ---------------------------------------------------------------------------
+// people/people.js, react/usePeople.js — a document's own people list
+// ---------------------------------------------------------------------------
+
+export interface Person {
+  id: string;
+  name: string;
+  color?: string;
+  [key: string]: unknown;
+}
+
+export function addPerson(
+  store: EditorStore | History,
+  person: { name: string; color?: string },
+): string;
+export function updatePerson(
+  store: EditorStore | History,
+  id: string,
+  patch: Partial<Person>,
+): void;
+export function removePerson(store: EditorStore | History, id: string): void;
+/** Reactive view of the document's `people` collection. */
+export function usePeople(): Person[];
+
+// ---------------------------------------------------------------------------
+// react/useSmartQuotes.js, react/useAutoPairBrackets.js — optional typing behaviors
+// ---------------------------------------------------------------------------
+
+/** Straight `"`/`'` typed while composing becomes the contextually correct curly quote (one char in, one out). */
+export function useSmartQuotes(): void;
+/** Typing `(`/`[`/`{` inserts the matching closer and puts the caret between them; excludes quotes (that's `useSmartQuotes`). Off inside `code` blocks. */
+export function useAutoPairBrackets(): void;