prosemirror-rs 0.3.0

package/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "prosemirror-rs-node"
+version = "0.3.0"
+authors = [
+    "Johannes Wilm <johannes@fiduswriter.org>",
+    "Daniel Seiler <me@dseiler.eu>",
+]
+edition = "2021"
+license = "MIT"
+description = "Node.js bindings for prosemirror-rs"
+repository = "https://github.com/fiduswriter/prosemirror-rs"
+homepage = "https://github.com/fiduswriter/prosemirror-rs"
+# This crate is published via npm/napi-rs, not crates.io
+publish = false
+
+[lib]
+name = "prosemirror_rs"
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "2", features = ["napi4"] }
+napi-derive = "2"
+prosemirror = { path = ".." }
+serde_json = "1"
+
+[build-dependencies]
+napi-build = "2"

package/README.md

@@ -0,0 +1,129 @@
+# prosemirror-rs — Node.js bindings
+
+Node.js bindings for [`prosemirror`](https://crates.io/crates/prosemirror), a Rust
+implementation of [ProseMirror](https://prosemirror.net)'s document model and
+transform pipeline.
+
+## Installation
+
+```bash
+npm install prosemirror-rs
+```
+
+## Design goals
+
+- **Zero unnecessary copies.** The schema and document live entirely in Rust
+  memory. Only JSON strings cross the JavaScript/Rust boundary.
+- **Wire-efficient.** Steps arriving as JSON (e.g. from a WebSocket) can be
+  passed directly to `applyStepsJson()` without any JS-level parsing.
+- **Database-efficient.** `docJson()` serializes the document in Rust and
+  returns a plain JS `string`, ready to write to a database with no
+  intermediate objects.
+
+## Quick start
+
+```js
+const { Editor } = require('prosemirror-rs');
+
+const schemaJson = JSON.stringify({
+    nodes: {
+        doc:       { content: 'paragraph+' },
+        paragraph: { content: 'text*', group: 'block' },
+        text:      { group: 'inline' },
+    },
+    marks: { strong: {}, em: {} },
+});
+
+const docJson = JSON.stringify({
+    type: 'doc',
+    content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello' }] }],
+});
+
+const editor = new Editor(schemaJson, docJson);
+console.log(editor.version);   // 0
+
+// Typical server loop: steps arrive as raw JSON from a WebSocket client
+wss.on('message', (raw) => {
+    const data = JSON.parse(raw);                     // parse envelope only
+    const ok = editor.applyStepsJson(                 // steps stay as JSON string
+        JSON.stringify(data.steps)
+    );
+    if (ok) {
+        db.execute('UPDATE docs SET body = $1', [editor.docJson()]);
+    }
+});
+```
+
+## Building from source
+
+```bash
+cd node
+npm run build   # runs cargo build --release + copies the .node artifact
+npm test        # build + run the test suite
+```
+
+## API reference
+
+### `new Editor(schemaJson, docJson)`
+
+Create an editor. Both arguments are JSON strings (schema spec and initial
+document). Throws `Error` on malformed input.
+
+### `editor.applyStep(stepJson) → boolean`
+
+Apply one step supplied as a JSON string. Returns `true` on success, `false`
+if the step cannot be applied (document is left unchanged). Throws `Error`
+on invalid JSON.
+
+### `editor.applyStepsJson(stepsJson) → boolean`
+
+**Preferred method for incoming network data.** Accepts a JSON *array* of
+steps as a single string — passed directly to Rust and parsed there, so
+nothing touches JS's JSON machinery.
+
+The batch is **atomic**: if any step fails the document and version are rolled
+back entirely and `false` is returned. Throws `Error` on invalid JSON.
+
+### `editor.applySteps(steps) → boolean`
+
+Convenience method for when steps are constructed or modified in JavaScript.
+Each element of `steps` is a JSON string for one step.
+
+The batch is **atomic**: if any step fails the document and version are rolled
+back entirely and `false` is returned. Throws `Error` on invalid JSON.
+
+### `editor.reset(docJson)`
+
+Replace the document with a new one, reusing the already-parsed schema.
+Resets the version counter to zero. Throws `Error` on malformed input.
+
+### `editor.docJson() → string`
+
+Return the current document as a compact JSON string. Serialized entirely in
+Rust; only the final string is passed to JavaScript — suitable for direct
+database writes with no intermediate objects.
+
+### `editor.version` *(number, read-only)*
+
+Number of steps successfully applied since construction or the last `reset()`.
+Use as a document version counter in collaborative-editing protocols.
+
+## Credits
+
+The underlying Rust library was originally written by
+**Daniel Seiler** ([Xiphoseer](https://github.com/Xiphoseer), <me@dseiler.eu>),
+who designed and implemented the document model, transform pipeline, and
+runtime schema system. Currently maintained by
+**Johannes Wilm** ([FidusWriter](https://fiduswriter.org),
+<johannes@fiduswriter.org>).
+
+ProseMirror is by **Marijn Haverbeke** and contributors —
+see [prosemirror.net](https://prosemirror.net).
+
+## License
+
+MIT — see [LICENSE](../LICENSE).
+
+Copyright 2026 Johannes Wilm
+Copyright 2020 Daniel Seiler
+Copyright 2015–2026 Marijn Haverbeke and others

package/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    napi_build::setup();
+}

package/copy-artifact.mjs

@@ -0,0 +1,39 @@
+/**
+ * Copies the compiled Rust native addon to a platform-specific .node file.
+ *
+ * The filename follows the napi-rs triple convention so that index.js can
+ * load the correct binary at runtime.  Called automatically by `npm run build`
+ * after `cargo build --release`.
+ */
+import { cpSync } from 'fs';
+import { platform, arch } from 'os';
+import { fileURLToPath } from 'url';
+import { join, dirname } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Map OS → shared library extension
+function libExtension() {
+  const p = platform();
+  if (p === 'win32') return '.dll';
+  if (p === 'darwin') return '.dylib';
+  return '.so';
+}
+
+// Map Node platform+arch → napi-rs triple
+function triple() {
+  const p = platform();
+  const a = arch();
+  if (p === 'darwin' && a === 'x64')       return 'darwin-x64';
+  if (p === 'darwin' && a === 'arm64')     return 'darwin-arm64';
+  if (p === 'linux'  && a === 'x64')       return 'linux-x64-gnu';
+  if (p === 'linux'  && a === 'arm64')     return 'linux-arm64-gnu';
+  if (p === 'win32'  && a === 'x64')       return 'win32-x64-msvc';
+  throw new Error(`Unsupported platform/arch: ${p}-${a}`);
+}
+
+const src  = join(__dirname, '..', 'target', 'release', `libprosemirror_rs${libExtension()}`);
+const dest = join(__dirname, `prosemirror-rs.${triple()}.node`);
+
+cpSync(src, dest);
+console.log(`Copied ${src} → ${dest}`);

package/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Node.js bindings for prosemirror-rs.
+ *
+ * Provides a memory- and CPU-efficient interface to ProseMirror's document
+ * model and transform pipeline.  Document state lives entirely in Rust; only
+ * JSON strings cross the JavaScript/Rust boundary.
+ *
+ * Schema caching:
+ * - The first `new Editor(schemaJson, ...)` call parses the schema and stores
+ *   it in a global Rust cache keyed by the exact schema-JSON string.
+ * - All subsequent `Editor` constructions with the same string reuse the
+ *   cached schema at the cost of a single `Arc` clone.
+ */
+export declare class Editor {
+    /**
+     * Create a new Editor.
+     *
+     * The parsed schema is cached inside Rust (keyed by the exact
+     * `schemaJson` string), so repeated construction with the same schema
+     * only parses it once.
+     *
+     * @param schemaJson ProseMirror schema specification as a JSON string.
+     * @param docJson Initial document state as a JSON string.
+     * @throws {Error} If either string is not valid JSON, or the schema /
+     *   document does not conform to the ProseMirror spec.
+     */
+    constructor(schemaJson: string, docJson: string);
+
+    /**
+     * Apply a single step to the document.
+     *
+     * @param stepJson The step as a JSON string.
+     * @returns `true` if applied successfully, `false` if the step could not
+     *   be applied (document is left unchanged).
+     * @throws {Error} If `stepJson` is not valid JSON or not a recognised step type.
+     */
+    applyStep(stepJson: string): boolean;
+
+    /**
+     * Apply a batch of steps supplied as a single JSON array string, atomically.
+     *
+     * Preferred method when steps arrive from a network client: the string is
+     * passed directly to Rust and parsed there, so nothing touches JS's JSON
+     * machinery.
+     *
+     * All steps are parsed before any are applied, so a malformed array throws
+     * without mutating the document.
+     *
+     * The batch is fully atomic: if any step fails to apply the document is
+     * rolled back to its state before the call, leaving it completely unchanged.
+     * The version counter is likewise rolled back.
+     *
+     * @param stepsJson A JSON array of step objects, e.g.
+     *   `'[{"stepType":"replace",...},...]'`.
+     * @returns `true` if every step applied successfully; `false` if any step
+     *   failed (document and version are rolled back entirely).
+     * @throws {Error} If `stepsJson` is not a valid JSON array of steps.
+     */
+    applyStepsJson(stepsJson: string): boolean;
+
+    /**
+     * Apply a batch of steps from a JS array of JSON strings, atomically.
+     *
+     * Use this when steps are constructed or modified in JS.  For steps arriving
+     * directly from a network client prefer `applyStepsJson` to avoid unnecessary
+     * JS-level JSON parsing.
+     *
+     * All steps are parsed before any are applied, so a bad JSON string throws
+     * without mutating the document.
+     *
+     * The batch is fully atomic: if any step fails to apply the document is
+     * rolled back to its state before the call, leaving it completely unchanged.
+     * The version counter is likewise rolled back.
+     *
+     * @param steps An array where each element is a JSON string for one step.
+     * @returns `true` if every step applied successfully; `false` if any step
+     *   failed (document and version are rolled back entirely).
+     * @throws {Error} If any element is not valid step JSON.
+     */
+    applySteps(steps: string[]): boolean;
+
+    /**
+     * Reset the document to a new state, reusing the already-parsed schema.
+     *
+     * More efficient than constructing a brand-new `Editor` when you need to
+     * restore a snapshot (e.g. after an unrecoverable conflict), because the
+     * schema is never re-parsed — only the document JSON is processed.
+     * The version counter is reset to zero.
+     *
+     * @param docJson The replacement document as a JSON string.
+     * @throws {Error} If `docJson` is not valid JSON or does not conform to
+     *   the schema.
+     */
+    reset(docJson: string): void;
+
+    /**
+     * Serialize the current document to a JSON string.
+     *
+     * Serialization happens entirely in Rust; only the resulting string is
+     * passed to JavaScript.  Suitable for saving directly to a database without
+     * creating any intermediate JS objects.
+     *
+     * @returns The current document as a compact JSON string.
+     */
+    docJson(): string;
+
+    /**
+     * Number of steps successfully applied since construction or last `reset()`.
+     *
+     * Use as a document version counter in collaborative-editing protocols.
+     */
+    readonly version: number;
+}

package/index.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { existsSync } = require('fs');
+const { join } = require('path');
+
+const { platform, arch } = process;
+
+// Map Node.js platform + arch → napi-rs platform triple.
+// Every triple listed here must have a corresponding build in the CI matrix.
+const TRIPLES = {
+  'darwin-x64':   'prosemirror-rs.darwin-x64.node',
+  'darwin-arm64': 'prosemirror-rs.darwin-arm64.node',
+  'linux-x64':    'prosemirror-rs.linux-x64-gnu.node',
+  'linux-arm64':  'prosemirror-rs.linux-arm64-gnu.node',
+  'win32-x64':    'prosemirror-rs.win32-x64-msvc.node',
+};
+
+const key = `${platform}-${arch}`;
+const filename = TRIPLES[key];
+
+if (!filename) {
+  throw new Error(
+    `Unsupported platform/architecture: ${key}. ` +
+    `prosemirror-rs distributes prebuilt binaries for ` +
+    `darwin-x64, darwin-arm64, linux-x64, linux-arm64, and win32-x64.`,
+  );
+}
+
+const localPath = join(__dirname, filename);
+if (!existsSync(localPath)) {
+  throw new Error(
+    `No native binary found for ${key} at ${filename}. ` +
+    `Try reinstalling the package, or build from source with \`npm run build\`.`,
+  );
+}
+
+module.exports = require(localPath);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "prosemirror-rs",
+  "version": "0.3.0",
+  "description": "Node.js bindings for prosemirror-rs: a Rust implementation of ProseMirror's document model and transform pipeline",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "cargo build --release && node copy-artifact.mjs",
+    "test": "npm run build && node --test tests/editor.test.js"
+  },
+  "keywords": [
+    "prosemirror",
+    "collaborative-editing",
+    "editor",
+    "document",
+    "napi",
+    "rust"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fiduswriter/prosemirror-rs"
+  },
+  "homepage": "https://github.com/fiduswriter/prosemirror-rs#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/lib.rs

@@ -0,0 +1,285 @@
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex, OnceLock};
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use prosemirror::dynamic::types::Dyn;
+use prosemirror::dynamic::{DynamicNode, DynamicSchema};
+use prosemirror::transform::Step;
+
+// ---------------------------------------------------------------------------
+// Schema cache
+// ---------------------------------------------------------------------------
+
+/// Global cache mapping raw schema-JSON strings → parsed schemas.
+///
+/// Keyed by the exact bytes of the JSON string, so two textually-identical
+/// strings always hit the same entry.  Parsing a schema is the expensive
+/// part of Editor construction; once cached, every subsequent `Editor::new`
+/// for the same schema is just an `Arc` clone + a document parse.
+static SCHEMA_CACHE: OnceLock<Mutex<HashMap<String, Arc<DynamicSchema>>>> = OnceLock::new();
+
+fn get_or_create_schema(schema_json: &str) -> napi::Result<Arc<DynamicSchema>> {
+    let cache = SCHEMA_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+    // Recover from a poisoned lock (would only happen if a previous thread panicked mid-insert).
+    let mut guard = cache.lock().unwrap_or_else(|e| e.into_inner());
+
+    if let Some(existing) = guard.get(schema_json) {
+        return Ok(Arc::clone(existing));
+    }
+
+    let schema_val: serde_json::Value = serde_json::from_str(schema_json)
+        .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid schema JSON: {e}")))?;
+    let schema = DynamicSchema::from_json(&schema_val)
+        .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid schema: {e}")))?;
+
+    let arc = Arc::new(schema);
+    guard.insert(schema_json.to_owned(), Arc::clone(&arc));
+    Ok(arc)
+}
+
+// ---------------------------------------------------------------------------
+// Editor
+// ---------------------------------------------------------------------------
+
+/// A stateful ProseMirror document editor backed by Rust.
+///
+/// The schema and document state live entirely in Rust memory.  Only JSON
+/// strings cross the JavaScript/Rust boundary, keeping data-transfer overhead
+/// to the absolute minimum for each operation:
+///
+/// * Steps arrive as a JSON string → parsed in Rust → applied in Rust.
+/// * The document is serialized in Rust → returned as a plain JS `string`.
+///
+/// The parsed schema is automatically cached inside Rust, keyed by the exact
+/// schema-JSON string.  Constructing many `Editor` objects that share the
+/// same schema therefore only pays the parse cost once.
+#[napi]
+pub struct Editor {
+    schema: Arc<DynamicSchema>,
+    doc: DynamicNode,
+    version: usize,
+}
+
+#[napi]
+impl Editor {
+    /// Create a new Editor.
+    ///
+    /// The parsed schema is cached inside Rust (keyed by the exact
+    /// `schemaJson` string), so repeated construction with the same schema
+    /// only parses it once.
+    ///
+    /// @param schemaJson ProseMirror schema specification as a JSON string.
+    /// @param docJson Initial document state as a JSON string.
+    /// @throws {Error} If either string is not valid JSON, or the schema /
+    ///   document does not conform to the ProseMirror spec.
+    #[napi(constructor)]
+    pub fn new(schema_json: String, doc_json: String) -> napi::Result<Self> {
+        let schema = get_or_create_schema(&schema_json)?;
+
+        let doc_val: serde_json::Value = serde_json::from_str(&doc_json)
+            .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid document JSON: {e}")))?;
+        let doc = schema
+            .node_from_json(&doc_val)
+            .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid document: {e}")))?;
+
+        Ok(Editor { schema, doc, version: 0 })
+    }
+
+    /// Apply a single step to the document.
+    ///
+    /// @param stepJson The step as a JSON string.
+    /// @returns `true` if applied successfully, `false` if the step could not
+    ///   be applied (document is left unchanged).
+    /// @throws {Error} If `stepJson` is not valid JSON or not a recognised step type.
+    #[napi]
+    pub fn apply_step(&mut self, step_json: String) -> napi::Result<bool> {
+        let result = {
+            let schema = &self.schema;
+            let doc = &self.doc;
+            schema.with_types(|| -> napi::Result<Option<DynamicNode>> {
+                let step: Step<Dyn> = serde_json::from_str(&step_json)
+                    .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid step JSON: {e}")))?;
+                Ok(step.apply(doc).ok())
+            })
+        }?;
+
+        if let Some(new_doc) = result {
+            self.doc = new_doc;
+            self.version += 1;
+            Ok(true)
+        } else {
+            Ok(false)
+        }
+    }
+
+    /// Apply a batch of steps supplied as a single JSON array string, atomically.
+    ///
+    /// **This is the preferred method when steps arrive from a network client.**
+    /// The entire string is handed to Rust and parsed there in one pass — no
+    /// JS JSON machinery is involved, and no intermediate JS objects are created.
+    ///
+    /// All steps are parsed before any are applied, so a malformed JSON array
+    /// throws without mutating the document.
+    ///
+    /// The batch is fully atomic: if any step fails to apply the document is
+    /// rolled back to its state before the call, leaving it completely
+    /// unchanged.  The version counter is likewise rolled back.
+    ///
+    /// @param stepsJson A JSON array of step objects, e.g.
+    ///   `'[{"stepType":"replace",...},...]'`.
+    /// @returns `true` if every step applied successfully; `false` if any
+    ///   step failed (document and version are rolled back entirely).
+    /// @throws {Error} If `stepsJson` is not a valid JSON array of steps.
+    #[napi]
+    pub fn apply_steps_json(&mut self, steps_json: String) -> napi::Result<bool> {
+        // Phase 1: parse the whole array before touching the document.
+        let steps: Vec<Step<Dyn>> = {
+            let schema = &self.schema;
+            schema.with_types(|| {
+                serde_json::from_str(&steps_json)
+                    .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid steps JSON: {e}")))
+            })?
+        };
+
+        // A snapshot is only needed when there are at least two steps: with a
+        // single step the document is either untouched (failure) or cleanly
+        // advanced (success), so no previously-committed state can need rolling back.
+        let mut snapshot: Option<(DynamicNode, usize)> = if steps.len() > 1 {
+            Some((self.doc.clone(), self.version))
+        } else {
+            None
+        };
+
+        // Phase 2: apply each step; roll back and return false on the first failure.
+        for step in steps {
+            let result = {
+                let schema = &self.schema;
+                let doc = &self.doc;
+                schema.with_types(|| step.apply(doc))
+            };
+            match result {
+                Ok(new_doc) => {
+                    self.doc = new_doc;
+                    self.version += 1;
+                }
+                Err(_) => {
+                    // Option::take moves the contents out via &mut self rather
+                    // than an unconditional move, which the borrow checker would
+                    // reject inside a loop body.
+                    if let Some((snap_doc, snap_version)) = snapshot.take() {
+                        self.doc = snap_doc;
+                        self.version = snap_version;
+                    }
+                    return Ok(false);
+                }
+            }
+        }
+        Ok(true)
+    }
+
+    /// Apply a batch of steps from a JS array of JSON strings, atomically.
+    ///
+    /// Use this when steps are constructed or modified in JS (e.g.
+    /// programmatically building a step object and calling `JSON.stringify`).
+    /// For steps that arrive directly from a network client prefer
+    /// `applyStepsJson` to avoid unnecessary JS-level parsing.
+    ///
+    /// All steps are parsed before any are applied, so a bad JSON string
+    /// throws without mutating the document.
+    ///
+    /// The batch is fully atomic: if any step fails to apply the document is
+    /// rolled back to its state before the call, leaving it completely
+    /// unchanged.  The version counter is likewise rolled back.
+    ///
+    /// @param steps An array where each element is a JSON string for one step.
+    /// @returns `true` if every step applied successfully; `false` if any
+    ///   step failed (document and version are rolled back entirely).
+    /// @throws {Error} If any element is not valid step JSON.
+    #[napi]
+    pub fn apply_steps(&mut self, steps: Vec<String>) -> napi::Result<bool> {
+        // Parse all steps up-front so that a bad step throws
+        // before any mutation takes place.
+        let parsed: Vec<Step<Dyn>> = {
+            let schema = &self.schema;
+            schema.with_types(|| {
+                steps
+                    .iter()
+                    .map(|s| {
+                        serde_json::from_str::<Step<Dyn>>(s)
+                            .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid step JSON: {e}")))
+                    })
+                    .collect::<napi::Result<Vec<_>>>()
+            })?
+        };
+
+        // Snapshot the pre-batch state so we can roll back cheaply.
+        let snapshot = self.doc.clone();
+        let snapshot_version = self.version;
+
+        for step in parsed {
+            let result = {
+                let schema = &self.schema;
+                let doc = &self.doc;
+                schema.with_types(|| step.apply(doc))
+            };
+            match result {
+                Ok(new_doc) => {
+                    self.doc = new_doc;
+                    self.version += 1;
+                }
+                Err(_) => {
+                    self.doc = snapshot;
+                    self.version = snapshot_version;
+                    return Ok(false);
+                }
+            }
+        }
+        Ok(true)
+    }
+
+    /// Reset the document to a new state, reusing the already-parsed schema.
+    ///
+    /// This is more efficient than constructing a brand-new `Editor` when
+    /// you need to restore a snapshot (e.g. after an unrecoverable conflict),
+    /// because the schema is never re-parsed — only the document JSON is
+    /// processed.  The version counter is reset to zero.
+    ///
+    /// @param docJson The replacement document as a JSON string.
+    /// @throws {Error} If `docJson` is not valid JSON or does not conform to
+    ///   the schema.
+    #[napi]
+    pub fn reset(&mut self, doc_json: String) -> napi::Result<()> {
+        let doc_val: serde_json::Value = serde_json::from_str(&doc_json)
+            .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid document JSON: {e}")))?;
+        let doc = self
+            .schema
+            .node_from_json(&doc_val)
+            .map_err(|e| napi::Error::new(Status::InvalidArg, format!("Invalid document: {e}")))?;
+        self.doc = doc;
+        self.version = 0;
+        Ok(())
+    }
+
+    /// Serialize the current document to a JSON string.
+    ///
+    /// Serialization happens entirely in Rust; only the resulting string is
+    /// passed to JavaScript.  This makes the method suitable for saving the
+    /// document directly to a database without creating any intermediate
+    /// JS objects.
+    ///
+    /// @returns The document as a compact JSON string.
+    #[napi]
+    pub fn doc_json(&self) -> napi::Result<String> {
+        serde_json::to_string(&self.doc)
+            .map_err(|e| napi::Error::new(Status::GenericFailure, format!("Serialization error: {e}")))
+    }
+
+    /// Number of steps successfully applied since construction (or last `reset()`).
+    ///
+    /// Use as a document version counter in collaborative-editing protocols.
+    #[napi(getter)]
+    pub fn version(&self) -> u32 {
+        self.version as u32
+    }
+}

package/tests/editor.test.js

@@ -0,0 +1,303 @@
+'use strict';
+/**
+ * Tests for the prosemirror-rs Node.js bindings.
+ *
+ * Covers: construction, docJson, applyStep, applyStepsJson, applySteps,
+ * reset, version, error handling, atomicity, and schema caching.
+ *
+ * Run via:  npm test  (from the node/ directory)
+ * Or:       node --test tests/  (after building the native addon)
+ */
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Editor } = require('../index.js');
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const SCHEMA = JSON.stringify({
+    nodes: {
+        doc:       { content: 'paragraph+' },
+        paragraph: { content: 'text*', group: 'block' },
+        text:      { group: 'inline' },
+    },
+    marks: { strong: {}, em: {} },
+});
+
+const DOC = JSON.stringify({
+    type: 'doc',
+    content: [{ type: 'paragraph', content: [
+        { type: 'text', text: 'hello' },
+    ]}],
+});
+
+// Replace step: insert 'x' at position 2 (inside first paragraph, after 'h').
+// Stays valid across repeated inserts because the paragraph grows each time.
+const INSERT_STEP = JSON.stringify({
+    stepType: 'replace',
+    from: 2,
+    to: 2,
+    slice: { content: [{ type: 'text', text: 'x' }] },
+});
+
+// A step that points way past the end of the document → always fails to apply.
+const BAD_POSITION_STEP = JSON.stringify({
+    stepType: 'replace',
+    from: 9999,
+    to: 9999,
+    slice: { content: [{ type: 'text', text: 'x' }] },
+});
+
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+
+test('creates an editor with initial version 0', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    assert.equal(editor.version, 0);
+});
+
+test('constructor throws on invalid schema JSON', () => {
+    assert.throws(
+        () => new Editor('not-valid-json', DOC),
+        /Invalid schema JSON/,
+    );
+});
+
+test('constructor throws on invalid doc JSON', () => {
+    assert.throws(
+        () => new Editor(SCHEMA, 'not-valid-json'),
+        /Invalid document JSON/,
+    );
+});
+
+test('constructor throws when doc JSON is not a node object', () => {
+    // A JSON array cannot be deserialized as a document node.
+    assert.throws(
+        () => new Editor(SCHEMA, JSON.stringify([])),
+        /Invalid document/,
+    );
+});
+
+// ---------------------------------------------------------------------------
+// docJson
+// ---------------------------------------------------------------------------
+
+test('docJson returns a valid JSON string containing the initial text', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const raw = editor.docJson();
+    assert.equal(typeof raw, 'string');
+    const doc = JSON.parse(raw);
+    assert.equal(doc.type, 'doc');
+    assert.ok(raw.includes('hello'), `Expected "hello" in: ${raw}`);
+});
+
+// ---------------------------------------------------------------------------
+// applyStep
+// ---------------------------------------------------------------------------
+
+test('applyStep returns true on success and increments version', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const ok = editor.applyStep(INSERT_STEP);
+    assert.equal(ok, true);
+    assert.equal(editor.version, 1);
+});
+
+test('applyStep mutates the document', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    editor.applyStep(INSERT_STEP);
+    const doc = JSON.parse(editor.docJson());
+    // The inserted 'x' should appear in the serialised document.
+    assert.ok(JSON.stringify(doc).includes('x'));
+});
+
+test('applyStep accumulates version across multiple calls', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    editor.applyStep(INSERT_STEP);
+    editor.applyStep(INSERT_STEP);
+    editor.applyStep(INSERT_STEP);
+    assert.equal(editor.version, 3);
+});
+
+test('applyStep returns false when the step cannot be applied', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const ok = editor.applyStep(BAD_POSITION_STEP);
+    assert.equal(ok, false);
+    assert.equal(editor.version, 0);
+});
+
+test('applyStep leaves the document unchanged on failure', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const before = editor.docJson();
+    editor.applyStep(BAD_POSITION_STEP);
+    assert.equal(editor.docJson(), before);
+});
+
+test('applyStep throws on invalid JSON', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    assert.throws(() => editor.applyStep('not-json'), /Invalid step JSON/);
+});
+
+// ---------------------------------------------------------------------------
+// applyStepsJson
+// ---------------------------------------------------------------------------
+
+test('applyStepsJson applies all steps from a JSON array string', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const stepsJson = JSON.stringify([
+        JSON.parse(INSERT_STEP),
+        JSON.parse(INSERT_STEP),
+    ]);
+    const ok = editor.applyStepsJson(stepsJson);
+    assert.equal(ok, true);
+    assert.equal(editor.version, 2);
+});
+
+test('applyStepsJson is atomic: rolls back version on step failure', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const stepsJson = JSON.stringify([
+        JSON.parse(INSERT_STEP),
+        JSON.parse(BAD_POSITION_STEP),
+    ]);
+    const ok = editor.applyStepsJson(stepsJson);
+    assert.equal(ok, false);
+    assert.equal(editor.version, 0);
+});
+
+test('applyStepsJson is atomic: rolls back document on step failure', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const before = editor.docJson();
+    const stepsJson = JSON.stringify([
+        JSON.parse(INSERT_STEP),
+        JSON.parse(BAD_POSITION_STEP),
+    ]);
+    editor.applyStepsJson(stepsJson);
+    assert.equal(editor.docJson(), before);
+});
+
+test('applyStepsJson succeeds for an empty array', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const ok = editor.applyStepsJson('[]');
+    assert.equal(ok, true);
+    assert.equal(editor.version, 0);
+});
+
+test('applyStepsJson throws on invalid JSON', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    assert.throws(() => editor.applyStepsJson('not-json'), /Invalid steps JSON/);
+});
+
+// ---------------------------------------------------------------------------
+// applySteps
+// ---------------------------------------------------------------------------
+
+test('applySteps applies all steps from an array of JSON strings', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const ok = editor.applySteps([INSERT_STEP, INSERT_STEP]);
+    assert.equal(ok, true);
+    assert.equal(editor.version, 2);
+});
+
+test('applySteps is atomic: rolls back version on step failure', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const ok = editor.applySteps([INSERT_STEP, BAD_POSITION_STEP]);
+    assert.equal(ok, false);
+    assert.equal(editor.version, 0);
+});
+
+test('applySteps is atomic: rolls back document on step failure', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const before = editor.docJson();
+    editor.applySteps([INSERT_STEP, BAD_POSITION_STEP]);
+    assert.equal(editor.docJson(), before);
+});
+
+test('applySteps succeeds for an empty array', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const ok = editor.applySteps([]);
+    assert.equal(ok, true);
+    assert.equal(editor.version, 0);
+});
+
+test('applySteps throws on an invalid step JSON string', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    assert.throws(() => editor.applySteps(['not-json']), /Invalid step JSON/);
+});
+
+test('applySteps throws before mutating when a later element is invalid JSON', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    const before = editor.docJson();
+    // All steps are parsed first, so the bad second element prevents any mutation.
+    assert.throws(() => editor.applySteps([INSERT_STEP, 'not-json']));
+    assert.equal(editor.docJson(), before);
+    assert.equal(editor.version, 0);
+});
+
+// ---------------------------------------------------------------------------
+// reset
+// ---------------------------------------------------------------------------
+
+test('reset restores version to 0', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    editor.applyStep(INSERT_STEP);
+    editor.applyStep(INSERT_STEP);
+    assert.equal(editor.version, 2);
+
+    editor.reset(DOC);
+    assert.equal(editor.version, 0);
+});
+
+test('reset replaces the document', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    editor.applyStep(INSERT_STEP);  // mutate
+
+    editor.reset(DOC);
+    // After reset the document should match the original (no 'x' inserted).
+    const doc = JSON.parse(editor.docJson());
+    assert.equal(doc.type, 'doc');
+    assert.ok(!JSON.stringify(doc.content).startsWith('[{"type":"paragraph","content":[{"type":"text","text":"x'));
+});
+
+test('reset allows applying steps again after rollback', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    editor.applyStep(INSERT_STEP);
+    editor.reset(DOC);
+
+    const ok = editor.applyStep(INSERT_STEP);
+    assert.equal(ok, true);
+    assert.equal(editor.version, 1);
+});
+
+test('reset throws on invalid JSON', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    assert.throws(() => editor.reset('not-json'), /Invalid document JSON/);
+});
+
+test('reset throws when new doc JSON is not a node object', () => {
+    const editor = new Editor(SCHEMA, DOC);
+    // A JSON array cannot be deserialized as a document node.
+    assert.throws(() => editor.reset(JSON.stringify([])), /Invalid document/);
+});
+
+// ---------------------------------------------------------------------------
+// Schema caching
+// ---------------------------------------------------------------------------
+
+test('multiple editors with the same schema all work correctly', () => {
+    const editors = Array.from({ length: 5 }, () => new Editor(SCHEMA, DOC));
+    for (const editor of editors) {
+        assert.equal(editor.version, 0);
+        const doc = JSON.parse(editor.docJson());
+        assert.equal(doc.type, 'doc');
+    }
+});
+
+test('editors with the same schema do not share document state', () => {
+    const editorA = new Editor(SCHEMA, DOC);
+    const editorB = new Editor(SCHEMA, DOC);
+
+    editorA.applyStep(INSERT_STEP);
+    assert.equal(editorA.version, 1);
+    assert.equal(editorB.version, 0);  // B is untouched
+});