@pm-cm/core 0.0.1 → 0.0.2

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Schema, Node } from 'prosemirror-model';
+import { Node, Schema } from 'prosemirror-model';
 import { Transaction } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
 
@@ -24,7 +24,84 @@ type ErrorEvent = {
  * - `'serialize-error'` — failed to serialize a ProseMirror document to text.
  */
 type OnError = (event: ErrorEvent) => void;
+/** Describes the changed region between two text strings. */
+type TextDiff = {
+    /** Byte offset where the two strings first differ. */
+    start: number;
+    /** End of the changed region in the old (previous) text. */
+    endA: number;
+    /** End of the changed region in the new (incoming) text. */
+    endB: number;
+};
+/**
+ * Result of an incremental parse. Either a plain `Node` (the bridge will
+ * diff against `prevDoc` to find changed positions), or an object with
+ * pre-computed document positions so the bridge can skip tree diffing entirely.
+ */
+type IncrementalParseResult = Node | {
+    doc: Node;
+    from: number;
+    to: number;
+    toB: number;
+};
+/**
+ * Optional incremental parser that re-parses only the changed region.
+ *
+ * Receives the previous document, previous/next text, and the text-level diff
+ * computed by the library. Returns an {@link IncrementalParseResult}, or `null`
+ * to fall back to the full {@link Parse} function.
+ *
+ * When the result includes document positions (`{ doc, from, to, toB }`),
+ * the bridge skips `findDiffStart`/`findDiffEnd` entirely.
+ */
+type IncrementalParse = (args: {
+    prevDoc: Node;
+    prevText: string;
+    text: string;
+    diff: TextDiff;
+    schema: Schema;
+}) => IncrementalParseResult | null;
+/** Writer that tracks text offsets for cursor mapping. */
+type CursorMapWriter = {
+    /** Write unmapped text (e.g. syntax like `> `, `**`, `[`, `](url)`). */
+    write(text: string): void;
+    /**
+     * Write mapped text: content from a PM text node at `[pmStart, pmEnd)`.
+     * Must be called in PM document order (ascending `pmStart`).
+     */
+    writeMapped(pmStart: number, pmEnd: number, text: string): void;
+};
+/** Serializer that writes to a {@link CursorMapWriter} for exact cursor mapping. */
+type SerializeWithMap = (doc: Node, writer: CursorMapWriter) => void;
+/** A single contiguous run within a match result. */
+type MatchRun = {
+    /** Start offset within the PM text node content (0-based). */
+    contentStart: number;
+    /** End offset within the PM text node content (exclusive). */
+    contentEnd: number;
+    /** Start offset in the serialized text. */
+    textStart: number;
+    /** End offset in the serialized text (exclusive). */
+    textEnd: number;
+};
+/** Result of a successful match from a {@link Matcher}. */
+type MatchResult = {
+    /** Contiguous runs mapping PM content to serialized text. */
+    runs: MatchRun[];
+    /** Position from which the next node's search should start. */
+    nextSearchFrom: number;
+};
+/**
+ * Format-specific matching function for use with {@link wrapSerialize}.
+ *
+ * Given a PM text node's content, the full serialized text, and a search-from
+ * position, return a {@link MatchResult} describing how the content maps to
+ * the serialized text, or `null` if no match is found.
+ */
+type Matcher = (serialized: string, nodeText: string, searchFrom: number) => MatchResult | null;
 
+/** Compute the changed region between two strings. */
+declare function diffText(a: string, b: string): TextDiff;
 /** Configuration for {@link createViewBridge}. */
 type ViewBridgeConfig = {
     schema: Schema;
@@ -33,11 +110,32 @@ type ViewBridgeConfig = {
     normalize?: Normalize;
     /** Called on non-fatal errors (e.g. parse failures). Defaults to `console.error`. */
     onError?: OnError;
+    /**
+     * Optional incremental parser for large documents.
+     * When provided, the bridge computes a text-level diff and passes it to this
+     * function instead of calling the full {@link Parse}. Return `null` to fall
+     * back to full parse.
+     */
+    incrementalParse?: IncrementalParse;
+    /** Maximum number of parse results to cache. Defaults to `8`. Set `0` to disable. */
+    parseCacheSize?: number;
 };
 /** Options for {@link ViewBridgeHandle.applyText}. */
 type ApplyTextOptions = {
     /** Set `false` to prevent the change from being added to undo history. Default `true`. */
     addToHistory?: boolean;
+    /**
+     * Pre-computed text diff from the editor's change set.
+     * When provided, skips the internal `diffText` O(n) scan.
+     * The diff describes the changed region between the previous and incoming
+     * **normalized** text.
+     */
+    diff?: TextDiff;
+    /**
+     * Set `true` when the caller guarantees the text is already normalized
+     * (no `\r` characters). Skips the `normalize` pass entirely.
+     */
+    normalized?: boolean;
 };
 /**
  * Discriminated-union result of {@link ViewBridgeHandle.applyText}.
@@ -103,22 +201,33 @@ type CursorMap = {
     skippedNodes: number;
 };
 /**
- * Locate a text-node string within the serialized output.
- * Return the starting index, or -1 if not found.
- * Default: `(serialized, nodeText, from) => serialized.indexOf(nodeText, from)`
+ * Create a {@link CursorMapWriter} that tracks offsets and builds segments.
+ *
+ * Call `getText()` to retrieve the full serialized text.
+ * Call `finish(doc)` to produce the final {@link CursorMap}.
  */
-type LocateText = (serialized: string, nodeText: string, searchFrom: number) => number;
+declare function createCursorMapWriter(): CursorMapWriter & {
+    getText(): string;
+    finish(doc: Node): CursorMap;
+    getMappedCount(): number;
+};
 /**
  * Build a cursor map that aligns ProseMirror positions with serialized-text offsets.
  *
- * Walks the document tree and locates each text node within the serialized output,
- * producing a sorted list of {@link TextSegment}s.
+ * Accepts either a plain {@link Serialize} `(doc) => string` or a
+ * {@link SerializeWithMap} `(doc, writer) => void`. Detection is automatic:
+ * if the serializer uses the writer, the exact-by-construction path is used;
+ * if it returns a string, an internal `indexOf`-based forward match is applied.
+ *
+ * The plain `Serialize` path uses exact `indexOf` matching (format-agnostic).
+ * For better mapping quality with serializers that transform text (escaping,
+ * entity encoding, etc.), use {@link wrapSerialize} with a format-specific
+ * {@link Matcher}, or implement {@link SerializeWithMap} directly.
  *
  * @param doc - The ProseMirror document to map.
- * @param serialize - Serializer used to produce the full text.
- * @param locate - Optional custom text-location function. Defaults to `indexOf`.
+ * @param serialize - A plain serializer or a writer-based serializer.
  */
-declare function buildCursorMap(doc: Node, serialize: Serialize, locate?: LocateText): CursorMap;
+declare function buildCursorMap(doc: Node, serialize: Serialize | SerializeWithMap): CursorMap;
 /**
  * Look up a ProseMirror position in a cursor map and return the corresponding text offset.
  * Returns `null` when the map has no segments.
@@ -129,5 +238,22 @@ declare function cursorMapLookup(map: CursorMap, pmPos: number): number | null;
  * Returns `null` when the map has no segments.
  */
 declare function reverseCursorMapLookup(map: CursorMap, cmOffset: number): number | null;
+/**
+ * Wrap a plain {@link Serialize} function as a {@link SerializeWithMap}.
+ *
+ * When called without a `matcher`, the wrapper uses `indexOf` internally
+ * (identical to the default `buildCursorMap` path — useful only for type
+ * compatibility).
+ *
+ * When called with a format-specific {@link Matcher}, the wrapper uses
+ * `indexOf` first for each text node, falling back to the matcher when
+ * `indexOf` fails. This enables multi-run mapping for serializers that
+ * transform text (escaping, entity encoding, etc.).
+ *
+ * @param serialize - A plain `(doc: Node) => string` serializer.
+ * @param matcher - Optional format-specific matcher for improved mapping.
+ * @returns A {@link SerializeWithMap} that can be passed to {@link buildCursorMap}.
+ */
+declare function wrapSerialize(serialize: Serialize, matcher?: Matcher): SerializeWithMap;
 
-export { type ApplyTextOptions, type ApplyTextResult, type BoundViewBridgeHandle, type CursorMap, type ErrorCode, type ErrorEvent, type LocateText, type Normalize, type OnError, type Parse, type Serialize, type TextSegment, type ViewBridgeConfig, type ViewBridgeHandle, buildCursorMap, createBoundViewBridge, createViewBridge, cursorMapLookup, reverseCursorMapLookup };
+export { type ApplyTextOptions, type ApplyTextResult, type BoundViewBridgeHandle, type CursorMap, type CursorMapWriter, type ErrorCode, type ErrorEvent, type IncrementalParse, type IncrementalParseResult, type MatchResult, type MatchRun, type Matcher, type Normalize, type OnError, type Parse, type Serialize, type SerializeWithMap, type TextDiff, type TextSegment, type ViewBridgeConfig, type ViewBridgeHandle, buildCursorMap, createBoundViewBridge, createCursorMapWriter, createViewBridge, cursorMapLookup, diffText, reverseCursorMapLookup, wrapSerialize };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Schema, Node } from 'prosemirror-model';
+import { Node, Schema } from 'prosemirror-model';
 import { Transaction } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
 
@@ -24,7 +24,84 @@ type ErrorEvent = {
  * - `'serialize-error'` — failed to serialize a ProseMirror document to text.
  */
 type OnError = (event: ErrorEvent) => void;
+/** Describes the changed region between two text strings. */
+type TextDiff = {
+    /** Byte offset where the two strings first differ. */
+    start: number;
+    /** End of the changed region in the old (previous) text. */
+    endA: number;
+    /** End of the changed region in the new (incoming) text. */
+    endB: number;
+};
+/**
+ * Result of an incremental parse. Either a plain `Node` (the bridge will
+ * diff against `prevDoc` to find changed positions), or an object with
+ * pre-computed document positions so the bridge can skip tree diffing entirely.
+ */
+type IncrementalParseResult = Node | {
+    doc: Node;
+    from: number;
+    to: number;
+    toB: number;
+};
+/**
+ * Optional incremental parser that re-parses only the changed region.
+ *
+ * Receives the previous document, previous/next text, and the text-level diff
+ * computed by the library. Returns an {@link IncrementalParseResult}, or `null`
+ * to fall back to the full {@link Parse} function.
+ *
+ * When the result includes document positions (`{ doc, from, to, toB }`),
+ * the bridge skips `findDiffStart`/`findDiffEnd` entirely.
+ */
+type IncrementalParse = (args: {
+    prevDoc: Node;
+    prevText: string;
+    text: string;
+    diff: TextDiff;
+    schema: Schema;
+}) => IncrementalParseResult | null;
+/** Writer that tracks text offsets for cursor mapping. */
+type CursorMapWriter = {
+    /** Write unmapped text (e.g. syntax like `> `, `**`, `[`, `](url)`). */
+    write(text: string): void;
+    /**
+     * Write mapped text: content from a PM text node at `[pmStart, pmEnd)`.
+     * Must be called in PM document order (ascending `pmStart`).
+     */
+    writeMapped(pmStart: number, pmEnd: number, text: string): void;
+};
+/** Serializer that writes to a {@link CursorMapWriter} for exact cursor mapping. */
+type SerializeWithMap = (doc: Node, writer: CursorMapWriter) => void;
+/** A single contiguous run within a match result. */
+type MatchRun = {
+    /** Start offset within the PM text node content (0-based). */
+    contentStart: number;
+    /** End offset within the PM text node content (exclusive). */
+    contentEnd: number;
+    /** Start offset in the serialized text. */
+    textStart: number;
+    /** End offset in the serialized text (exclusive). */
+    textEnd: number;
+};
+/** Result of a successful match from a {@link Matcher}. */
+type MatchResult = {
+    /** Contiguous runs mapping PM content to serialized text. */
+    runs: MatchRun[];
+    /** Position from which the next node's search should start. */
+    nextSearchFrom: number;
+};
+/**
+ * Format-specific matching function for use with {@link wrapSerialize}.
+ *
+ * Given a PM text node's content, the full serialized text, and a search-from
+ * position, return a {@link MatchResult} describing how the content maps to
+ * the serialized text, or `null` if no match is found.
+ */
+type Matcher = (serialized: string, nodeText: string, searchFrom: number) => MatchResult | null;
 
+/** Compute the changed region between two strings. */
+declare function diffText(a: string, b: string): TextDiff;
 /** Configuration for {@link createViewBridge}. */
 type ViewBridgeConfig = {
     schema: Schema;
@@ -33,11 +110,32 @@ type ViewBridgeConfig = {
     normalize?: Normalize;
     /** Called on non-fatal errors (e.g. parse failures). Defaults to `console.error`. */
     onError?: OnError;
+    /**
+     * Optional incremental parser for large documents.
+     * When provided, the bridge computes a text-level diff and passes it to this
+     * function instead of calling the full {@link Parse}. Return `null` to fall
+     * back to full parse.
+     */
+    incrementalParse?: IncrementalParse;
+    /** Maximum number of parse results to cache. Defaults to `8`. Set `0` to disable. */
+    parseCacheSize?: number;
 };
 /** Options for {@link ViewBridgeHandle.applyText}. */
 type ApplyTextOptions = {
     /** Set `false` to prevent the change from being added to undo history. Default `true`. */
     addToHistory?: boolean;
+    /**
+     * Pre-computed text diff from the editor's change set.
+     * When provided, skips the internal `diffText` O(n) scan.
+     * The diff describes the changed region between the previous and incoming
+     * **normalized** text.
+     */
+    diff?: TextDiff;
+    /**
+     * Set `true` when the caller guarantees the text is already normalized
+     * (no `\r` characters). Skips the `normalize` pass entirely.
+     */
+    normalized?: boolean;
 };
 /**
  * Discriminated-union result of {@link ViewBridgeHandle.applyText}.
@@ -103,22 +201,33 @@ type CursorMap = {
     skippedNodes: number;
 };
 /**
- * Locate a text-node string within the serialized output.
- * Return the starting index, or -1 if not found.
- * Default: `(serialized, nodeText, from) => serialized.indexOf(nodeText, from)`
+ * Create a {@link CursorMapWriter} that tracks offsets and builds segments.
+ *
+ * Call `getText()` to retrieve the full serialized text.
+ * Call `finish(doc)` to produce the final {@link CursorMap}.
  */
-type LocateText = (serialized: string, nodeText: string, searchFrom: number) => number;
+declare function createCursorMapWriter(): CursorMapWriter & {
+    getText(): string;
+    finish(doc: Node): CursorMap;
+    getMappedCount(): number;
+};
 /**
  * Build a cursor map that aligns ProseMirror positions with serialized-text offsets.
  *
- * Walks the document tree and locates each text node within the serialized output,
- * producing a sorted list of {@link TextSegment}s.
+ * Accepts either a plain {@link Serialize} `(doc) => string` or a
+ * {@link SerializeWithMap} `(doc, writer) => void`. Detection is automatic:
+ * if the serializer uses the writer, the exact-by-construction path is used;
+ * if it returns a string, an internal `indexOf`-based forward match is applied.
+ *
+ * The plain `Serialize` path uses exact `indexOf` matching (format-agnostic).
+ * For better mapping quality with serializers that transform text (escaping,
+ * entity encoding, etc.), use {@link wrapSerialize} with a format-specific
+ * {@link Matcher}, or implement {@link SerializeWithMap} directly.
  *
  * @param doc - The ProseMirror document to map.
- * @param serialize - Serializer used to produce the full text.
- * @param locate - Optional custom text-location function. Defaults to `indexOf`.
+ * @param serialize - A plain serializer or a writer-based serializer.
  */
-declare function buildCursorMap(doc: Node, serialize: Serialize, locate?: LocateText): CursorMap;
+declare function buildCursorMap(doc: Node, serialize: Serialize | SerializeWithMap): CursorMap;
 /**
  * Look up a ProseMirror position in a cursor map and return the corresponding text offset.
  * Returns `null` when the map has no segments.
@@ -129,5 +238,22 @@ declare function cursorMapLookup(map: CursorMap, pmPos: number): number | null;
  * Returns `null` when the map has no segments.
  */
 declare function reverseCursorMapLookup(map: CursorMap, cmOffset: number): number | null;
+/**
+ * Wrap a plain {@link Serialize} function as a {@link SerializeWithMap}.
+ *
+ * When called without a `matcher`, the wrapper uses `indexOf` internally
+ * (identical to the default `buildCursorMap` path — useful only for type
+ * compatibility).
+ *
+ * When called with a format-specific {@link Matcher}, the wrapper uses
+ * `indexOf` first for each text node, falling back to the matcher when
+ * `indexOf` fails. This enables multi-run mapping for serializers that
+ * transform text (escaping, entity encoding, etc.).
+ *
+ * @param serialize - A plain `(doc: Node) => string` serializer.
+ * @param matcher - Optional format-specific matcher for improved mapping.
+ * @returns A {@link SerializeWithMap} that can be passed to {@link buildCursorMap}.
+ */
+declare function wrapSerialize(serialize: Serialize, matcher?: Matcher): SerializeWithMap;
 
-export { type ApplyTextOptions, type ApplyTextResult, type BoundViewBridgeHandle, type CursorMap, type ErrorCode, type ErrorEvent, type LocateText, type Normalize, type OnError, type Parse, type Serialize, type TextSegment, type ViewBridgeConfig, type ViewBridgeHandle, buildCursorMap, createBoundViewBridge, createViewBridge, cursorMapLookup, reverseCursorMapLookup };
+export { type ApplyTextOptions, type ApplyTextResult, type BoundViewBridgeHandle, type CursorMap, type CursorMapWriter, type ErrorCode, type ErrorEvent, type IncrementalParse, type IncrementalParseResult, type MatchResult, type MatchRun, type Matcher, type Normalize, type OnError, type Parse, type Serialize, type SerializeWithMap, type TextDiff, type TextSegment, type ViewBridgeConfig, type ViewBridgeHandle, buildCursorMap, createBoundViewBridge, createCursorMapWriter, createViewBridge, cursorMapLookup, diffText, reverseCursorMapLookup, wrapSerialize };