Add react-native support (#63)

Reviewed-on: https://home.schmelczer.dev/git/git/andras/reconcile/pulls/63

reconcile-js/src/core.ts

@@ -0,0 +1,400 @@
+// Shared, platform-agnostic wrapper around the generated wasm-bindgen surface.
+//
+// The actual wasm bindings are injected by a platform-specific entrypoint:
+//   - `index.ts`     (web/node) instantiates the real WebAssembly module lazily
+//                    on first use via `initSync`.
+//   - `index.rn.ts`  (React Native / Hermes) links a wasm2js (pure-JS)
+//                    implementation, since Hermes does not expose a runtime
+//                    `WebAssembly` global. See `scripts/build-rn.mjs`.
+
+type WasmModule = typeof import('reconcile-text');
+
+/**
+ * The generated wasm-bindgen surface this library wraps, plus a hook to make
+ * sure the underlying module is ready. Supplied by a platform entrypoint.
+ */
+export interface WasmBackend {
+  CursorPosition: WasmModule['CursorPosition'];
+  TextWithCursors: WasmModule['TextWithCursors'];
+  reconcile: WasmModule['reconcile'];
+  reconcileWithHistory: WasmModule['reconcileWithHistory'];
+  diff: WasmModule['diff'];
+  undiff: WasmModule['undiff'];
+  /**
+   * Make the wasm module ready for use. Invoked before every operation, so it
+   * must be cheap and idempotent (a no-op once initialised).
+   */
+  ensureReady(): void;
+}
+
+// Define the enum values as a const array to avoid duplication
+const BUILTIN_TOKENIZERS = ['Character', 'Line', 'Markdown', 'Word'] as const;
+
+/**
+ * Tokenisation strategies for text merging.
+ *
+ * These correspond to the built-in tokenizers available in the underlying WASM module.
+ */
+export type BuiltinTokenizer = (typeof BUILTIN_TOKENIZERS)[number];
+
+/**
+ * History classification for text spans in merge results.
+ *
+ * Indicates the origin of each text span in the merged document.
+ */
+export type History =
+  | 'Unchanged'
+  | 'AddedFromLeft'
+  | 'AddedFromRight'
+  | 'RemovedFromLeft'
+  | 'RemovedFromRight';
+
+/**
+ * Represents a text document with associated cursor positions.
+ *
+ * This interface is used both as input to reconcile functions (to specify where
+ * cursors are positioned in the original documents) and as output (with cursors
+ * automatically repositioned after merging).
+ */
+export interface TextWithCursors {
+  /** The document's entire content as a string */
+  text: string;
+
+  /**
+   * Array of cursor positions within the text. Can be empty if there are no cursors to track.
+   * Each cursor has a unique ID and position.
+   */
+  cursors: CursorPosition[];
+}
+
+/**
+ * Like `TextWithCursors`, but cursors may be null or undefined (treated as empty).
+ * Used as input where cursor tracking is optional.
+ */
+export interface TextWithOptionalCursors {
+  /** The document's entire content as a string */
+  text: string;
+
+  /**
+   * Array of cursor positions within the text. Can be null, undefined, or empty
+   * if there are no cursors to track. Each cursor has a unique ID and position.
+   */
+  cursors: null | undefined | CursorPosition[];
+}
+
+/**
+ * Represents a cursor position within a text document.
+ *
+ * Cursors are automatically repositioned during text merging to maintain their
+ * relative positions as text is inserted, deleted, or modified around them.
+ */
+export interface CursorPosition {
+  /** Unique identifier for the cursor (can be any number, must be unique within the document) */
+  id: number;
+
+  /** Character position in the text, 0-based index from the beginning of the document */
+  position: number;
+}
+
+/**
+ * Represents a merged text document with cursor positions and detailed change history.
+ *
+ * This is the return type of `reconcileWithHistory()` and provides complete information
+ * about how the merge was performed, including which parts of the final text came from
+ * which source documents.
+ */
+export interface TextWithCursorsAndHistory {
+  /** The merged document's entire content */
+  text: string;
+
+  /**
+   * Array of cursor positions within the merged text. Can be empty if there are no cursors to track.
+   * All cursors are automatically repositioned from the left and right documents.
+   */
+  cursors: CursorPosition[];
+
+  /**
+   * Detailed provenance information showing the origin of each text span in the result.
+   * Each span indicates whether it was unchanged, added from left, added from right, etc.
+   */
+  history: SpanWithHistory[];
+}
+
+/**
+ * Represents a span of text in the merged result with its change history.
+ *
+ * This shows exactly which source document contributed each piece of text to the
+ * final merged result. Useful for understanding merge decisions and creating
+ * visualisations of how documents were combined.
+ */
+export interface SpanWithHistory {
+  /** The text content of this span */
+  text: string;
+
+  /** The origin of this text span in the merge result */
+  history: History;
+}
+
+/** The public, synchronous API surface, identical across platforms. */
+export interface ReconcileApi {
+  /**
+   * Merges three versions of text using intelligent conflict resolution.
+   *
+   * This is the primary function for 3-way text merging. Unlike traditional merge tools
+   * that produce conflict markers, this function automatically resolves conflicts by
+   * applying both sets of changes where possible.
+   *
+   * @param original - The original/base version of the text that both sides diverged from
+   * @param left - The left version of the text (either string or TextWithCursors with cursor positions)
+   * @param right - The right version of the text (either string or TextWithCursors with cursor positions)
+   * @param tokenizer - The tokenisation strategy: "Word" (default, recommended for prose),
+   *                    "Character" (fine-grained), "Line" (similar to git merge), or
+   *                    "Markdown" (splits on Markdown structure)
+   * @returns The reconciled text with automatically repositioned cursor positions
+   *
+   * @example
+   * ```typescript
+   * const original = "Hello world";
+   * const left = "Hello beautiful world";    // Added "beautiful"
+   * const right = "Hi world";                // Changed "Hello" to "Hi"
+   *
+   * const result = reconcile(original, left, right);
+   * console.log(result.text); // "Hi beautiful world"
+   * ```
+   */
+  reconcile(
+    original: string,
+    left: string | TextWithOptionalCursors,
+    right: string | TextWithOptionalCursors,
+    tokenizer?: BuiltinTokenizer
+  ): TextWithCursors;
+
+  /**
+   * Generates a compact diff representation between an original and changed text.
+   *
+   * These can be parsed and unpacked using the `undiff` function or the Rust crate's EditedText::from_diff.
+   * Cursor positions are omitted from the diff result.
+   *
+   * This function computes the differences between two versions of text and returns
+   * a compact representation of those changes.
+   *
+   * @param original - The original/base version of the text
+   * @param changed - The modified version of the text (either string or TextWithCursors with cursor positions)
+   * @param tokenizer - The tokenisation strategy, which is the same as used in `reconcile`.
+   * @returns An array of inserts (strings), deletes (negative integers), and retained spans (positive integers).
+   */
+  diff(
+    original: string,
+    changed: string | TextWithOptionalCursors,
+    tokenizer?: BuiltinTokenizer
+  ): Array<number | string>;
+
+  /**
+   * Applies a compact diff to an original text to reconstruct the changed version.
+   *
+   * This function takes an original text and a compact diff representation (as produced
+   * by the `diff` function) and reconstructs the modified text.
+   *
+   * @param original - The original/base version of the text
+   * @param diff - The compact diff array (inserts as strings, deletes as negative integers, retained spans as positive integers)
+   * @param tokenizer - The tokenisation strategy, which is the same as used in `reconcile`.
+   * @returns The reconstructed changed text as a string.
+   */
+  undiff(
+    original: string,
+    diff: Array<number | bigint | string>,
+    tokenizer?: BuiltinTokenizer
+  ): string;
+
+  /**
+   * Merges three versions of text and returns detailed provenance information.
+   *
+   * This function behaves like `reconcile()` but also provides
+   * detailed historical information about the origin of each text span in the result.
+   * This is valuable for understanding how the merge was performed and which changes
+   * came from which source.
+   *
+   * Note: Computing the history is computationally more expensive than the basic merge.
+   *
+   * @param original - The original/base version of the text that both sides diverged from
+   * @param left - The left version of the text (either string or TextWithCursors with cursor positions)
+   * @param right - The right version of the text (either string or TextWithCursors with cursor positions)
+   * @param tokenizer - The tokenisation strategy: "Word" (default, recommended for prose),
+   *                    "Character" (fine-grained), "Line" (similar to git merge), or
+   *                    "Markdown" (splits on Markdown structure)
+   * @returns The reconciled text with cursor positions and detailed change history
+   *
+   * @example
+   * ```typescript
+   * const original = "Hello world";
+   * const left = "Hello beautiful world";
+   * const right = "Hi world";
+   *
+   * const result = reconcileWithHistory(original, left, right);
+   * console.log(result.text); // "Hi beautiful world"
+   * console.log(result.history); // Array of SpanWithHistory objects showing change origins
+   * ```
+   */
+  reconcileWithHistory(
+    original: string,
+    left: string | TextWithOptionalCursors,
+    right: string | TextWithOptionalCursors,
+    tokenizer?: BuiltinTokenizer
+  ): TextWithCursorsAndHistory;
+}
+
+const UNSUPPORTED_TOKENIZER_ERROR = `Unsupported tokenizer, only ${BUILTIN_TOKENIZERS.join(
+  ', '
+)} are supported`;
+
+/**
+ * Build the public {@link ReconcileApi} on top of a {@link WasmBackend}.
+ *
+ * Each operation calls `backend.ensureReady()` first, then marshals JS values
+ * into the wasm representation, invokes the binding, and frees the wasm-side
+ * objects. The behaviour is identical regardless of whether the backend is a
+ * real WebAssembly module or its wasm2js translation.
+ */
+export function makeReconcileApi(backend: WasmBackend): ReconcileApi {
+  function assertTokenizer(tokenizer: BuiltinTokenizer): void {
+    if (!BUILTIN_TOKENIZERS.includes(tokenizer)) {
+      throw new Error(UNSUPPORTED_TOKENIZER_ERROR);
+    }
+  }
+
+  function toWasmTextWithCursors(text: string | TextWithOptionalCursors) {
+    const isInputString = typeof text === 'string';
+    const innerText = isInputString ? text : text.text;
+    const innerCursors = isInputString ? [] : (text.cursors ?? []);
+
+    return new backend.TextWithCursors(
+      innerText,
+      innerCursors.map(({ id, position }) => new backend.CursorPosition(id, position))
+    );
+  }
+
+  function toTextWithCursors(textWithCursor: {
+    text(): string;
+    cursors(): Array<{ id(): number; characterIndex(): number; free(): void }>;
+  }): TextWithCursors {
+    const wasmCursors = textWithCursor.cursors();
+    const cursors = wasmCursors.map((cursor) => ({
+      id: cursor.id(),
+      position: cursor.characterIndex(),
+    }));
+    for (const cursor of wasmCursors) {
+      cursor.free();
+    }
+
+    return {
+      text: textWithCursor.text(),
+      cursors,
+    };
+  }
+
+  function toSpanWithHistory(span: {
+    text(): string;
+    history(): History;
+    free(): void;
+  }): SpanWithHistory {
+    const result = {
+      text: span.text(),
+      history: span.history(),
+    };
+    span.free();
+    return result;
+  }
+
+  function reconcile(
+    original: string,
+    left: string | TextWithOptionalCursors,
+    right: string | TextWithOptionalCursors,
+    tokenizer: BuiltinTokenizer = 'Word'
+  ): TextWithCursors {
+    backend.ensureReady();
+    assertTokenizer(tokenizer);
+
+    const leftCursor = toWasmTextWithCursors(left);
+    const rightCursor = toWasmTextWithCursors(right);
+
+    const result = backend.reconcile(original, leftCursor, rightCursor, tokenizer);
+
+    leftCursor.free();
+    rightCursor.free();
+
+    const jsResult = toTextWithCursors(result);
+    result.free();
+
+    return jsResult;
+  }
+
+  function diff(
+    original: string,
+    changed: string | TextWithOptionalCursors,
+    tokenizer: BuiltinTokenizer = 'Word'
+  ): Array<number | string> {
+    backend.ensureReady();
+    assertTokenizer(tokenizer);
+
+    const changedWasm = toWasmTextWithCursors(changed);
+
+    const result = backend.diff(original, changedWasm, tokenizer);
+
+    changedWasm.free();
+
+    return result.map((item) => (typeof item === 'bigint' ? Number(item) : item));
+  }
+
+  function undiff(
+    original: string,
+    diffValue: Array<number | bigint | string>,
+    tokenizer: BuiltinTokenizer = 'Word'
+  ): string {
+    backend.ensureReady();
+    assertTokenizer(tokenizer);
+
+    // The real-WebAssembly backend's `diff` emits BigInt spans, whereas the
+    // wasm2js (React Native) backend rejects BigInt outright. Normalise to
+    // plain numbers - exactly as `diff` does on the way out - so a `diff`
+    // result round-trips through `undiff` identically on every platform.
+    return backend.undiff(
+      original,
+      diffValue.map((item) => (typeof item === 'bigint' ? Number(item) : item)),
+      tokenizer
+    );
+  }
+
+  function reconcileWithHistory(
+    original: string,
+    left: string | TextWithOptionalCursors,
+    right: string | TextWithOptionalCursors,
+    tokenizer: BuiltinTokenizer = 'Word'
+  ): TextWithCursorsAndHistory {
+    backend.ensureReady();
+    assertTokenizer(tokenizer);
+
+    const leftCursor = toWasmTextWithCursors(left);
+    const rightCursor = toWasmTextWithCursors(right);
+
+    const result = backend.reconcileWithHistory(
+      original,
+      leftCursor,
+      rightCursor,
+      tokenizer
+    );
+
+    leftCursor.free();
+    rightCursor.free();
+
+    const jsResult = toTextWithCursors(result);
+    const history = result.history().map(toSpanWithHistory);
+    result.free();
+
+    return {
+      ...jsResult,
+      history,
+    };
+  }
+
+  return { reconcile, diff, undiff, reconcileWithHistory };
+}

reconcile-js/src/index.rn.ts

@@ -0,0 +1,47 @@
+// React Native entrypoint (resolved via the `react-native` package field).
+//
+// Hermes — the default React Native engine since RN 0.84 / Expo SDK 56 — does
+// not expose a runtime `WebAssembly` global, so the normal `new
+// WebAssembly.Module(...)` path used by `index.ts` throws
+// `ReferenceError: Property 'WebAssembly' doesn't exist`.
+//
+// Instead we link a wasm2js translation of the module: pure JavaScript that
+// needs no `WebAssembly` global and is instantiated synchronously at import
+// time. The public API and its synchronous signatures are unchanged, so
+// callers need no modification. The `pkg-rn` directory is generated by
+// `scripts/build-rn.mjs`.
+
+import {
+  CursorPosition as wasmCursorPosition,
+  TextWithCursors as wasmTextWithCursors,
+  reconcile as wasmReconcile,
+  reconcileWithHistory as wasmReconcileWithHistory,
+  diff as wasmDiff,
+  undiff as wasmUndiff,
+} from '../pkg-rn/reconcile_text.js';
+
+import { makeReconcileApi, type WasmBackend } from './core';
+
+const backend: WasmBackend = {
+  CursorPosition: wasmCursorPosition,
+  TextWithCursors: wasmTextWithCursors,
+  reconcile: wasmReconcile,
+  reconcileWithHistory: wasmReconcileWithHistory,
+  diff: wasmDiff,
+  undiff: wasmUndiff,
+  // The wasm2js module initialises itself at import time, so this is a no-op.
+  ensureReady() {},
+};
+
+export const { reconcile, diff, undiff, reconcileWithHistory } =
+  makeReconcileApi(backend);
+
+export type {
+  BuiltinTokenizer,
+  History,
+  CursorPosition,
+  TextWithCursors,
+  TextWithOptionalCursors,
+  TextWithCursorsAndHistory,
+  SpanWithHistory,
+} from './core';

reconcile-js/src/index.test.ts

@@ -1,4 +1,5 @@
-import { reconcile, reconcileWithHistory, diff, undiff } from './index';
+import * as webApi from './index';
+import * as rnApi from './index.rn';
 import { installWasmLeakDetector, checkForWasmLeaks } from './wasm-leak-detector';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -17,7 +18,18 @@ afterEach(() => {
   }
 });
 
-describe('reconcile', () => {
+// `./index` is the web/node build (real WebAssembly); `./index.rn` is the React
+// Native build (the wasm2js pure-JS translation). Both are thin backends over the
+// same `src/core.ts` wrapper and expose an identical public API, so the behavioural
+// suite below runs against both to guarantee they stay in lock-step.
+const backends = [
+  { name: 'web/node (WebAssembly)', api: webApi },
+  { name: 'React Native (wasm2js)', api: rnApi },
+];
+
+describe.each(backends)('reconcile [$name]', ({ api }) => {
+  const { reconcile, reconcileWithHistory, diff, undiff } = api;
+
   it('call reconcile without cursors', () => {
     expect(reconcile('Hello', 'Hello world', 'Hi world').text).toEqual('Hi world');
   });
@@ -60,9 +72,26 @@ describe('reconcile', () => {
     expect(result.text).toEqual('Hi world');
     expect(result.history.length).toBeGreaterThan(0);
   });
+
+  it('undiff accepts bigint entries (per the Array<number | bigint | string> type)', () => {
+    const original = 'Hello world';
+    const changed = 'Hello cruel world';
+
+    // `diff` returns plain numbers; emulate a caller that supplies BigInt, which the
+    // public signature permits. The wasm2js build rejects raw BigInt, so the shared
+    // wrapper must normalise it — running this on both backends asserts the contract.
+    const withBigints = diff(original, changed).map((item) =>
+      typeof item === 'number' ? BigInt(item) : item
+    );
+
+    expect(withBigints.some((item) => typeof item === 'bigint')).toBe(true);
+    expect(undiff(original, withBigints)).toEqual(changed);
+  });
 });
 
-describe('test_diff_and_undiff_are_inverse', () => {
+describe.each(backends)('diff and undiff are inverse [$name]', ({ api }) => {
+  const { diff, undiff } = api;
+
   const resourcesPath = path.join(__dirname, '../../tests/resources');
 
   const readFileSlice = (fileName: string, start: number, end: number): string => {
@@ -93,3 +122,31 @@ describe('test_diff_and_undiff_are_inverse', () => {
     });
   });
 });
+
+// React-Native-only: Hermes exposes no `WebAssembly` global, which is the whole reason
+// the RN entry point links a wasm2js build. Only the wasm2js backend can satisfy this.
+describe('React Native (wasm2js) Hermes parity', () => {
+  const { reconcile, reconcileWithHistory, diff, undiff } = rnApi;
+
+  it('runs every operation with no WebAssembly global', () => {
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'WebAssembly');
+    delete (globalThis as { WebAssembly?: unknown }).WebAssembly;
+    try {
+      expect((globalThis as { WebAssembly?: unknown }).WebAssembly).toBeUndefined();
+
+      expect(reconcile('Hello', 'Hello world', 'Hi world').text).toEqual('Hi world');
+
+      const changes = diff('Hello world', 'Hello cruel world');
+      expect(undiff('Hello world', changes)).toEqual('Hello cruel world');
+
+      expect(
+        reconcileWithHistory('Hello', 'Hello world', 'Hi world').history.length
+      ).toBeGreaterThan(0);
+    } finally {
+      // Restore the global so the leak check and later suites are unaffected.
+      if (descriptor) {
+        Object.defineProperty(globalThis, 'WebAssembly', descriptor);
+      }
+    }
+  });
+});

reconcile-js/src/index.ts

@@ -1,8 +1,7 @@
 import {
   CursorPosition as wasmCursorPosition,
-  reconcile as wasmReconcile,
   TextWithCursors as wasmTextWithCursors,
-  SpanWithHistory as wasmSpanWithHistory,
+  reconcile as wasmReconcile,
   reconcileWithHistory as wasmReconcileWithHistory,
   diff as wasmDiff,
   undiff as wasmUndiff,
@@ -11,341 +10,40 @@ import {
 
 import wasmBytes from 'reconcile-text/reconcile_text_bg.wasm';
 
-// Define the enum values as const arrays to avoid duplication
-const BUILTIN_TOKENIZERS = ['Character', 'Line', 'Markdown', 'Word'] as const;
-const HISTORY_VALUES = [
-  'Unchanged',
-  'AddedFromLeft',
-  'AddedFromRight',
-  'RemovedFromLeft',
-  'RemovedFromRight',
-] as const;
-
-/**
- * Tokenisation strategies for text merging.
- *
- * These correspond to the built-in tokenizers available in the underlying WASM module.
- */
-export type BuiltinTokenizer = (typeof BUILTIN_TOKENIZERS)[number];
-
-/**
- * History classification for text spans in merge results.
- *
- * Indicates the origin of each text span in the merged document.
- */
-export type History = (typeof HISTORY_VALUES)[number];
-
-/**
- * Represents a text document with associated cursor positions.
- *
- * This interface is used both as input to reconcile functions (to specify where
- * cursors are positioned in the original documents) and as output (with cursors
- * automatically repositioned after merging).
- */
-export interface TextWithCursors {
-  /** The document's entire content as a string */
-  text: string;
-
-  /**
-   * Array of cursor positions within the text. Can be empty if there are no cursors to track.
-   * Each cursor has a unique ID and position.
-   */
-  cursors: CursorPosition[];
-}
-
-/**
- * Like `TextWithCursors`, but cursors may be null or undefined (treated as empty).
- * Used as input where cursor tracking is optional.
- */
-export interface TextWithOptionalCursors {
-  /** The document's entire content as a string */
-  text: string;
-
-  /**
-   * Array of cursor positions within the text. Can be null, undefined, or empty
-   * if there are no cursors to track. Each cursor has a unique ID and position.
-   */
-  cursors: null | undefined | CursorPosition[];
-}
-
-/**
- * Represents a cursor position within a text document.
- *
- * Cursors are automatically repositioned during text merging to maintain their
- * relative positions as text is inserted, deleted, or modified around them.
- */
-export interface CursorPosition {
-  /** Unique identifier for the cursor (can be any number, must be unique within the document) */
-  id: number;
-
-  /** Character position in the text, 0-based index from the beginning of the document */
-  position: number;
-}
-
-/**
- * Represents a merged text document with cursor positions and detailed change history.
- *
- * This is the return type of `reconcileWithHistory()` and provides complete information
- * about how the merge was performed, including which parts of the final text came from
- * which source documents.
- */
-export interface TextWithCursorsAndHistory {
-  /** The merged document's entire content */
-  text: string;
-
-  /**
-   * Array of cursor positions within the merged text. Can be empty if there are no cursors to track.
-   * All cursors are automatically repositioned from the left and right documents.
-   */
-  cursors: CursorPosition[];
-
-  /**
-   * Detailed provenance information showing the origin of each text span in the result.
-   * Each span indicates whether it was unchanged, added from left, added from right, etc.
-   */
-  history: SpanWithHistory[];
-}
-
-/**
- * Represents a span of text in the merged result with its change history.
- *
- * This shows exactly which source document contributed each piece of text to the
- * final merged result. Useful for understanding merge decisions and creating
- * visualisations of how documents were combined.
- */
-export interface SpanWithHistory {
-  /** The text content of this span */
-  text: string;
-
-  /** The origin of this text span in the merge result */
-  history: History;
-}
-
-const UNSUPPORTED_TOKENIZER_ERROR = `Unsupported tokenizer, only ${BUILTIN_TOKENIZERS.join(
-  ', '
-)} are supported`;
+import { makeReconcileApi, type WasmBackend } from './core';
 
 let isInitialised = false;
 
-/**
- * Merges three versions of text using intelligent conflict resolution.
- *
- * This is the primary function for 3-way text merging. Unlike traditional merge tools
- * that produce conflict markers, this function automatically resolves conflicts by
- * applying both sets of changes where possible.
- *
- * @param original - The original/base version of the text that both sides diverged from
- * @param left - The left version of the text (either string or TextWithCursors with cursor positions)
- * @param right - The right version of the text (either string or TextWithCursors with cursor positions)
- * @param tokenizer - The tokenisation strategy: "Word" (default, recommended for prose),
- *                    "Character" (fine-grained), or "Line" (similar to git merge)
- * @returns The reconciled text with automatically repositioned cursor positions
- *
- * @example
- * ```typescript
- * const original = "Hello world";
- * const left = "Hello beautiful world";    // Added "beautiful"
- * const right = "Hi world";                // Changed "Hello" to "Hi"
- *
- * const result = reconcile(original, left, right);
- * console.log(result.text); // "Hi beautiful world"
- * ```
- */
-export function reconcile(
-  original: string,
-  left: string | TextWithOptionalCursors,
-  right: string | TextWithOptionalCursors,
-  tokenizer: BuiltinTokenizer = 'Word'
-): TextWithCursors {
-  init();
+const backend: WasmBackend = {
+  CursorPosition: wasmCursorPosition,
+  TextWithCursors: wasmTextWithCursors,
+  reconcile: wasmReconcile,
+  reconcileWithHistory: wasmReconcileWithHistory,
+  diff: wasmDiff,
+  undiff: wasmUndiff,
+  ensureReady() {
+    if (isInitialised) {
+      return;
+    }
 
-  if (!BUILTIN_TOKENIZERS.includes(tokenizer)) {
-    throw new Error(UNSUPPORTED_TOKENIZER_ERROR);
-  }
+    const wasmBinary = Uint8Array.from(atob(wasmBytes as unknown as string), (c) =>
+      c.charCodeAt(0)
+    );
+    initSync({ module: wasmBinary });
 
-  const leftCursor = toWasmTextWithCursors(left);
-  const rightCursor = toWasmTextWithCursors(right);
+    isInitialised = true;
+  },
+};
 
-  const result = wasmReconcile(original, leftCursor, rightCursor, tokenizer);
+export const { reconcile, diff, undiff, reconcileWithHistory } =
+  makeReconcileApi(backend);
 
-  leftCursor.free();
-  rightCursor.free();
-
-  const jsResult = toTextWithCursors(result);
-  result.free();
-
-  return jsResult;
-}
-
-/**
- * Generates a compact diff representation between an original and changed text.
- *
- * These can be parsed and unpacked using the `undiff` function or the Rust crate's EditedText::from_diff.
- * Cursor positions are omitted from the diff result.
- *
- * This function computes the differences between two versions of text and returns
- * a compact representation of those changes.
- *
- * @param original - The original/base version of the text
- * @param changed - The modified version of the text (either string or TextWithCursors with cursor positions)
- * @param tokenizer - The tokenisation strategy, which is the same as used in `reconcile`.
- * @returns An array of inserts (strings), deletes (negative integers), and retained spans (positive integers).
- */
-export function diff(
-  original: string,
-  changed: string | TextWithOptionalCursors,
-  tokenizer: BuiltinTokenizer = 'Word'
-): Array<number | string> {
-  init();
-
-  if (!BUILTIN_TOKENIZERS.includes(tokenizer)) {
-    throw new Error(UNSUPPORTED_TOKENIZER_ERROR);
-  }
-
-  const changedWasm = toWasmTextWithCursors(changed);
-
-  const result = wasmDiff(original, changedWasm, tokenizer);
-
-  changedWasm.free();
-
-  return result.map((item) => (typeof item === 'bigint' ? Number(item) : item));
-}
-
-/**
- * Applies a compact diff to an original text to reconstruct the changed version.
- *
- * This function takes an original text and a compact diff representation (as produced
- * by the `diff` function) and reconstructs the modified text.
- *
- * @param original - The original/base version of the text
- * @param diff - The compact diff array (inserts as strings, deletes as negative integers, retained spans as positive integers)
- * @param tokenizer - The tokenisation strategy, which is the same as used in `reconcile`.
- * @returns The reconstructed changed text as a string.
- */
-export function undiff(
-  original: string,
-  diff: Array<number | bigint | string>,
-  tokenizer: BuiltinTokenizer = 'Word'
-): string {
-  init();
-
-  if (!BUILTIN_TOKENIZERS.includes(tokenizer)) {
-    throw new Error(UNSUPPORTED_TOKENIZER_ERROR);
-  }
-
-  return wasmUndiff(original, diff, tokenizer);
-}
-
-/**
- * Merges three versions of text and returns detailed provenance information.
- *
- * This function behaves like `reconcile()` but also provides
- * detailed historical information about the origin of each text span in the result.
- * This is valuable for understanding how the merge was performed and which changes
- * came from which source.
- *
- * Note: Computing the history is computationally more expensive than the basic merge.
- *
- * @param original - The original/base version of the text that both sides diverged from
- * @param left - The left version of the text (either string or TextWithCursors with cursor positions)
- * @param right - The right version of the text (either string or TextWithCursors with cursor positions)
- * @param tokenizer - The tokenisation strategy: "Word" (default, recommended for prose),
- *                    "Character" (fine-grained), or "Line" (similar to git merge)
- * @returns The reconciled text with cursor positions and detailed change history
- *
- * @example
- * ```typescript
- * const original = "Hello world";
- * const left = "Hello beautiful world";
- * const right = "Hi world";
- *
- * const result = reconcileWithHistory(original, left, right);
- * console.log(result.text); // "Hi beautiful world"
- * console.log(result.history); // Array of SpanWithHistory objects showing change origins
- * ```
- */
-export function reconcileWithHistory(
-  original: string,
-  left: string | TextWithOptionalCursors,
-  right: string | TextWithOptionalCursors,
-  tokenizer: BuiltinTokenizer = 'Word'
-): TextWithCursorsAndHistory {
-  init();
-
-  if (!BUILTIN_TOKENIZERS.includes(tokenizer)) {
-    throw new Error(UNSUPPORTED_TOKENIZER_ERROR);
-  }
-
-  const leftCursor = toWasmTextWithCursors(left);
-  const rightCursor = toWasmTextWithCursors(right);
-
-  const result = wasmReconcileWithHistory(original, leftCursor, rightCursor, tokenizer);
-
-  leftCursor.free();
-  rightCursor.free();
-
-  const jsResult = toTextWithCursors(result);
-  const history = result.history().map(toSpanWithHistory);
-  result.free();
-
-  return {
-    ...jsResult,
-    history,
-  };
-}
-
-function init() {
-  if (isInitialised) {
-    return;
-  }
-
-  const wasmBinary = Uint8Array.from(atob(wasmBytes as unknown as string), (c) =>
-    c.charCodeAt(0)
-  );
-  initSync({ module: wasmBinary });
-
-  isInitialised = true;
-}
-
-function toWasmTextWithCursors(
-  text: string | TextWithOptionalCursors
-): wasmTextWithCursors {
-  const isInputString = typeof text === 'string';
-  const leftText = isInputString ? text : text.text;
-  const leftCursors = isInputString ? [] : (text.cursors ?? []);
-
-  return new wasmTextWithCursors(leftText, leftCursors.map(toWasmCursorPosition));
-}
-
-function toWasmCursorPosition({ id, position }: CursorPosition): wasmCursorPosition {
-  return new wasmCursorPosition(id, position);
-}
-
-function toTextWithCursors(textWithCursor: wasmTextWithCursors): TextWithCursors {
-  const wasmCursors = textWithCursor.cursors();
-  const cursors = wasmCursors.map(toCursorPosition);
-  for (const cursor of wasmCursors) {
-    cursor.free();
-  }
-
-  return {
-    text: textWithCursor.text(),
-    cursors,
-  };
-}
-
-function toCursorPosition(cursor: wasmCursorPosition): CursorPosition {
-  return {
-    id: cursor.id(),
-    position: cursor.characterIndex(),
-  };
-}
-
-function toSpanWithHistory(span: wasmSpanWithHistory): SpanWithHistory {
-  const result = {
-    text: span.text(),
-    history: span.history(),
-  };
-  span.free();
-  return result;
-}
+export type {
+  BuiltinTokenizer,
+  History,
+  CursorPosition,
+  TextWithCursors,
+  TextWithOptionalCursors,
+  TextWithCursorsAndHistory,
+  SpanWithHistory,
+} from './core';