svedit 0.11.1 → 0.13.0

package/dist/Session.svelte.js

@@ -1,575 +1,547 @@
 import Transaction from './Transaction.svelte.js';
-import { char_slice, traverse } from './utils.js';
-import {
-	get as doc_get,
-	property_type as doc_property_type,
-	kind as doc_kind,
-	inspect as doc_inspect,
-	apply_op,
-	count_references as doc_count_references,
-	validate_document_schema,
-	validate_document,
-	validate_node,
-	get_referencing_node_ids,
-	get_active_annotation,
-	validate_selection
-} from './doc_utils.js';
-
-/**
- * @import {
- *   NodeId,
- *   DocumentPath,
- *   Selection,
- *   Annotation,
- *   NodeKind,
- *   DocumentSchema,
- *   DocumentNode,
- *   Document
- * } from './types.d.ts';
- */
-
+import { char_slice, traverse, traverse_ids } from './utils.js';
+import { get as doc_get, property_type as doc_property_type, kind as doc_kind, inspect as doc_inspect, create_document_draft, apply_op_to_draft, count_references as doc_count_references, validate_document_schema, validate_document, validate_config_components, validate_node, is_id_valid, get_referencing_node_ids, get_selected_marks, get_selected_annotations, validate_selection } from './doc_utils.js';
 const BATCH_WINDOW_MS = 1000; // 1 second
-
-/**
- * @typedef {Object} SessionOptions
- * @property {Selection} [selection] - Initial selection state
- */
-
 export default class Session {
-	/** @type {Selection | null} */
-	#selection = $state.raw(null);
-
-	/** @type {DocumentSchema} */
-	schema = $state.raw();
-
-	/** @type {Document} */
-	doc = $state.raw();
-
-	/** @type {any} */
-	config = $state.raw();
-
-	history = $state.raw([]);
-	history_index = $state.raw(-1);
-	last_batch_started = $state.raw(undefined); // Timestamp for debounced batching
-
-	// Commands and keymap - initialized by Svedit when ready
-	// NOTE: Assumes single Svedit instance per session
-	commands = $state.raw({});
-	keymap = $state.raw({});
-
-	// Reactive helpers for UI state
-	can_undo = $derived(this.history_index >= 0);
-	can_redo = $derived(this.history_index < this.history.length - 1);
-
-	// Reactive variable for selected node
-	selected_node = $derived(this.get_selected_node());
-	available_annotation_types = $derived(this.get_available_annotation_types());
-
-
-	/**
-	 * @param {DocumentSchema} schema - The document schema
-	 * @param {Document} doc - The document
-	 * @param {object} config - configuration object
-	 * @param {Object} [options]
-	 * @param {Selection} [options.selection] - Initial selection state
-	 */
-	constructor(schema, doc, config, options = {}) {
-		// Validate the schema first
-		validate_document_schema(schema);
-
-		this.schema = schema;
-		this.doc = doc;
-		this.config = config;
-		validate_document(this.doc, this.schema);
-
-		// Set selection after doc is initialized so validation can work properly
-		this.selection = options.selection ?? null;
-	}
-
-	/**
-	 * Gets the current selection
-	 * @returns {Selection | null}
-	 */
-	get selection() {
-		return this.#selection;
-	}
-
-	/**
-	 * Sets the selection with validation
-	 * @param {Selection | null} value - The new selection
-	 * @throws {Error} Throws if the selection is invalid
-	 */
-	set selection(value) {
-		this._validate_selection(value);
-		this.#selection = value;
-	}
-
-	/**
-	 * Validates that a selection is within bounds and refers to valid paths.
-	 *
-	 * @param {Selection} selection - The selection to validate
-	 * @throws {Error} Throws if the selection is invalid
-	 * @private
-	 */
-	_validate_selection(selection) {
-		validate_selection(selection, this);
-	}
-
-	/**
-	 * Gets the document_id from the doc
-	 * @returns {string}
-	 */
-	get document_id() {
-		return this.doc.document_id;
-	}
-
-	/**
-	 * Validates the parts of a transaction result that can be affected by the transaction.
-	 *
-	 * This is intentionally narrower than full document validation. It validates all
-	 * created/modified nodes, plus nodes that still reference created, modified, or
-	 * deleted nodes. That catches local node invariants and dangling references left
-	 * behind by deletes without scanning every node on every apply.
-	 *
-	 * @param {Transaction} transaction - The transaction result to validate
-	 * @throws {Error} Throws if the transaction result is invalid
-	 */
-	validate_transaction_result(transaction) {
-		const doc = transaction.doc;
-		/** @type {NodeId[]} */
-		const affected_node_ids = [];
-
-		function add_node_id(node_id) {
-			if (!affected_node_ids.includes(node_id)) affected_node_ids.push(node_id);
-		}
-
-		for (const node_id of transaction.created_node_ids) add_node_id(node_id);
-		for (const node_id of transaction.modified_node_ids) add_node_id(node_id);
-		for (const node_id of get_referencing_node_ids(this.schema, doc, transaction.created_node_ids)) {
-			add_node_id(node_id);
-		}
-		for (const node_id of get_referencing_node_ids(this.schema, doc, transaction.modified_node_ids)) {
-			add_node_id(node_id);
-		}
-		for (const node_id of get_referencing_node_ids(this.schema, doc, transaction.deleted_node_ids)) {
-			add_node_id(node_id);
-		}
-
-		for (const node_id of affected_node_ids) {
-			const node = doc.nodes[node_id];
-			if (node) validate_node(node, this.schema, doc.nodes);
-		}
-	}
-
-	generate_id() {
-		if (this.config?.generate_id) {
-			return this.config.generate_id();
-		} else {
-			return crypto.randomUUID();
-		}
-	}
-
-	/**
-	 * Initialize commands and keymap for this session.
-	 * Called by Svedit component when it has the necessary context.
-	 *
-	 * NOTE: This assumes a single Svedit instance per session.
-	 * For multiple editors on the same document, this architecture would need
-	 * to be refactored to support multiple sessions per document.
-	 *
-	 * @param {object} context - The svedit context with session, editable, canvas, etc.
-	 */
-	initialize_commands(context) {
-		if (this.config?.create_commands_and_keymap) {
-			const { commands, keymap } = this.config.create_commands_and_keymap(context);
-			this.commands = commands;
-			this.keymap = keymap;
-		}
-	}
-
-	get_available_annotation_types() {
-		if (this.selection?.type !== 'text') return [];
-		const path = this.selection.path;
-		const property_definition = this.inspect(path);
-		return property_definition.node_types || [];
-	}
-
-	// Helper function to get the currently selected node
-	get_selected_node() {
-		if (!this.selection) return null;
-
-		if (this.selection.type === 'node') {
-			const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
-			const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
-			// Only consider selection of a single node
-			if (end - start !== 1) return null;
-			const node_array = this.get(this.selection.path);
-			const node_id = node_array[start];
-			return node_id ? this.get(node_id) : null;
-		} else {
-			// we are assuming we are either in a text or property (=custom) selection
-			const owner_node_path = this.selection?.path?.slice(0, -1);
-			if (!owner_node_path) return null;
-			const owner_node = this.get(owner_node_path);
-			return owner_node;
-		}
-	}
-
-	/**
-	 * Creates a new transaction for making atomic changes to the document.
-	 *
-	 * @returns {Transaction} A new transaction instance
-	 */
-	get tr() {
-		// We create a copy of the current state to avoid modifying the original
-		return new Transaction(this.schema, this.doc, this.selection, this.config);
-	}
-
-	/**
-	 * Applies a transaction to the document.
-	 * Auto-batches history entries with debounced behavior (max one entry per 2 seconds) when batch is true.
-	 *
-	 * @param {Transaction} transaction - The transaction to apply
-	 * @param {object} [options] - Optional configuration
-	 * @param {boolean} [options.batch=false] - Whether to allow batching with previous transaction
-	 */
-	apply(transaction, { batch = false } = {}) {
-		this.validate_transaction_result(transaction);
-		this.doc = transaction.doc;
-		// Make sure selection gets a new reference (is rerendered)
-		this.selection = structuredClone(transaction.selection);
-		if (this.history_index < this.history.length - 1) {
-			this.history = this.history.slice(0, this.history_index + 1);
-		}
-
-		const now = Date.now();
-		const should_batch =
-			batch &&
-			this.last_batch_started !== undefined &&
-			now - this.last_batch_started < BATCH_WINDOW_MS;
-
-		if (should_batch) {
-			// Append to existing history entry (within 2s of batch start)
-			const last_entry = this.history[this.history_index];
-			last_entry.ops.push(...transaction.ops);
-			last_entry.inverse_ops.push(...transaction.inverse_ops);
-			last_entry.selection_after = this.selection;
-			// Trigger update
-			this.history = [...this.history];
-		} else {
-			// Create new history entry (more than 2s since batch started, or first edit, or batch not requested)
-			this.history = [
-				...this.history,
-				{
-					ops: transaction.ops,
-					inverse_ops: transaction.inverse_ops,
-					selection_before: transaction.selection_before,
-					selection_after: this.selection
-				}
-			];
-			this.history_index = this.history_index + 1;
-			// Only set last_batch_started if batching was requested
-			if (batch) {
-				this.last_batch_started = now;
-			} else {
-				this.last_batch_started = undefined;
-			}
-		}
-
-		return this;
-	}
-
-	undo() {
-		if (this.history_index < 0) {
-			return;
-		}
-		const change = this.history[this.history_index];
-		let doc = this.doc;
-		change.inverse_ops
-			.slice()
-			.reverse()
-			.forEach((op) => {
-				doc = apply_op(doc, op);
-			});
-		this.doc = doc;
-		this.selection = change.selection_before;
-		this.history_index = this.history_index - 1;
-		return this;
-	}
-
-	redo() {
-		if (this.history_index >= this.history.length - 1) {
-			return;
-		}
-		this.history_index = this.history_index + 1;
-		const change = this.history[this.history_index];
-		let doc = this.doc;
-		change.ops.forEach((op) => {
-			doc = apply_op(doc, op);
-		});
-		this.doc = doc;
-		this.selection = change.selection_after;
-		return this;
-	}
-
-	/**
-	 * Gets a node instance or property value at the specified path.
-	 * @param {DocumentPath|string} path - Path to the node or property
-	 * @returns {any} Either a node instance object or the value of a property
-	 * @example
-	 * // Get a node by ID
-	 * session.get('list_1') // => { type: 'list', id: 'list_1', ... }
-	 *
-	 * @example
-	 * // Get a node array property
-	 * session.get(['list_1', 'list_items']) // => [ 'list_item_1', 'list_item_2' ]
-	 *
-	 * @example
-	 * // Get a specific node from an array
-	 * session.get(['page_1', 'body', 3, 'list_items', 0]) // => { type: 'list_item', id: 'list_item_1', ... }
-	 *
-	 * @example
-	 * // Get an annotated text property
-	 * session.get(['page_1', 'cover', 'title']) // => {text: 'Hello world', annotations: []}
-	 */
-	get(path) {
-		return doc_get(this.schema, this.doc, path);
-	}
-
-	/**
-	 * While .get gives you the value of a path, inspect gives you
-	 * the type info of that value.
-	 *
-	 * @todo The layout of these should be improved and more explictly typed
-	 *
-	 * @example
-	 * session.inspect(['page_1', 'body']) => {
-	 *   kind: 'property',
-	 *   name: 'body',
-	 *   type: 'node_array',
-	 *   node_types: ['text', 'story', 'list'],
-	 *   default_node_type: 'text'
-	 * }
-	 *
-	 * @example
-	 * session.inspect(['page_1', 'body', 1]) => {
-	 *   kind: 'node',
-	 *   id: 'paragraph_234',
-	 *   type: 'paragraph',
-	 *   properties: {...}
-	 * }
-	 *
-	 * @param {DocumentPath} path
-	 * @returns {{kind: 'property'|'node', [key: string]: any}}
-	 */
-	inspect(path) {
-		return doc_inspect(this.schema, this.doc, path);
-	}
-
-	/**
-	 * Determines the kind of a node ('block' for structured blocks, 'text' for pure
-	 * text nodes or 'annotation' for annotation nodes.
-	 * @param {any} node
-	 * @returns {NodeKind}
-	 */
-	kind(node) {
-		return doc_kind(this.schema, node);
-	}
-
-	/**
-	 * Determines whether a node type can be inserted at a given selection.
-	 * @param {string} node_type - The type of node to insert.
-	 * @param {Selection} [selection] - The selection at which to insert the node.
-	 * @returns {boolean} True if the node type can be inserted, false otherwise.
-	 */
-	can_insert(node_type, selection = this.selection) {
-		if (selection?.type === 'node') {
-			const property_definition = this.inspect(selection.path);
-			if (property_definition.node_types.includes(node_type)) {
-				return true;
-			}
-		}
-
-		// No insert position found yet, and root not reached, try one level up if possible
-		let next_node_insert_caret = this.get_next_node_insert_caret(selection);
-		if (!next_node_insert_caret) return false;
-		return this.can_insert(node_type, next_node_insert_caret);
-	}
-
-	/**
-	 * Compute next possible insert position from a given selection
-	 *
-	 * @param {Selection} [selection] - Reference selection
-	 * @returns {Selection|null} The next node insert caret selection, or null if none is available
-	 */
-	get_next_node_insert_caret(selection = this.selection) {
-		// There's no parent path to insert into
-		if (!selection || selection.path.length <= 2) {
-			return null;
-		}
-
-		const node_offset = parseInt(String(selection.path.at(-2)), 10) + 1;
-		return {
-			type: 'node',
-			path: selection.path.slice(0, -2),
-			anchor_offset: node_offset,
-			focus_offset: node_offset
-		};
-	}
-
-	/**
-	 * Returns the annotation object that is currently "under the cursor".
-	 * NOTE: Annotations in Svedit are exclusive, so there can only be one active_annotation
-	 *
-	 * @param {string} [annotation_type] Optional annotation type to filter by
-	 * @returns {Annotation|null}
-	 */
-	active_annotation(annotation_type) {
-		return get_active_annotation(this.schema, this.doc, this.selection, annotation_type);
-	}
-
-	get_selected_annotated_text() {
-		if (this.selection?.type !== 'text') return null;
-
-		const selection_start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
-		const selection_end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
-		const annotated_text = this.get(this.selection.path);
-		const text = char_slice(annotated_text.text, selection_start, selection_end);
-		const nodes = {};
-		const annotations = annotated_text.annotations
-			.map((a) => {
-				if (selection_start < a.end_offset && selection_end > a.start_offset) {
-					const sub_graph = this.traverse(a.node_id);
-					for (const node of sub_graph) {
-						if (!nodes[node.id]) {
-							nodes[node.id] = node;
-						}
-					}
-					return {
-						start_offset: Math.max(a.start_offset - selection_start, 0),
-						end_offset: Math.min(a.end_offset - selection_start, selection_end - selection_start),
-						node_id: a.node_id
-					};
-				} else {
-					return null;
-				}
-			})
-			.filter(Boolean);
-
-		return { text, annotations, nodes };
-	}
-
-	// TODO: think about ways how we can also turn a node selection into plain text.
-	get_selected_plain_text() {
-		if (this.selection?.type !== 'text') return null;
-
-		const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
-		const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
-		const annotated_text = this.get(this.selection.path);
-		return char_slice(annotated_text.text, start, end);
-	}
-
-	get_selected_nodes() {
-		if (this.selection?.type !== 'node') return null;
-
-		const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
-		const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
-		const node_array = this.get(this.selection.path);
-		return $state.snapshot(node_array.slice(start, end));
-	}
-
-	select_parent() {
-		if (!this.selection) return;
-		if (['text', 'property'].includes(this.selection?.type)) {
-			// For text and property selections (e.g. ['page_1', 'body', 0, 'image']), we need to go up two levels
-			// in the path
-			if (this.selection.path.length > 3) {
-				const parent_path = this.selection.path.slice(0, -2);
-				const current_index = parseInt(String(this.selection.path[this.selection.path.length - 2]));
-				this.selection = {
-					type: 'node',
-					path: parent_path,
-					anchor_offset: current_index,
-					focus_offset: current_index + 1
-				};
-			} else {
-				this.selection = null;
-			}
-		} else if (this.selection.type === 'node') {
-			// For node selections, we go up one level
-			if (this.selection.path.length > 3) {
-				const parent_path = this.selection.path.slice(0, -2);
-				const current_index = parseInt(String(this.selection.path[this.selection.path.length - 2]));
-
-				this.selection = {
-					type: 'node',
-					path: parent_path,
-					anchor_offset: current_index,
-					focus_offset: current_index + 1
-				};
-			} else {
-				this.selection = null;
-			}
-		} else {
-			this.selection = null;
-		}
-	}
-
-	/**
-	 * Traverses the document and returns a list of nodes in depth-first order.
-	 *
-	 * The traversal order is:
-	 * 1. Leaf nodes first
-	 * 2. Branch nodes second
-	 * 3. Root node (entry point) last
-	 *
-	 * @param {string} node_id - The ID of the node to start traversing from
-	 * @returns {Array<DocumentNode>} Array of nodes in depth-first order
-	 * @note Nodes that are not reachable from the entry point node will not be included
-	 */
-	traverse(node_id) {
-		return traverse(node_id, this.schema, $state.snapshot(this.doc.nodes));
-	}
-
-	/**
-	 * Convert the document to a clean format for persistence.
-	 *
-	 * We make a traversal to ensure that orphaned nodes are not included,
-	 * and that leaf nodes go first, followed by branches and the root node at last.
-	 *
-	 * @returns {Document} The document
-	 */
-	to_json() {
-		// this will order the nodes (depth-first traversal)
-		const nodes_array = this.traverse(this.document_id);
-		// convert nodes array to object with node IDs as keys
-		const nodes = Object.fromEntries(nodes_array.map((node) => [node.id, node]));
-		return {
-			document_id: this.document_id,
-			nodes
-		};
-	}
-
-	// property_type('page', 'body') => 'node_array'
-	// property_type('paragraph', 'content') => 'annotated_text'
-	property_type(type, property) {
-		return doc_property_type(this.schema, type, property);
-	}
-
-	// Count how many times a node is referenced in the document
-	count_references(node_id) {
-		return doc_count_references(this.schema, this.doc, node_id);
-	}
-
-	// Get all nodes referenced by a given node (recursively)
-	/**
-	 * @param {NodeId} node_id
-	 * @returns {NodeId[]}
-	 */
-	get_referenced_nodes(node_id) {
-		const traversed_nodes = this.traverse(node_id);
-
-		// Extract IDs and exclude the last element (root node)
-		return traversed_nodes.slice(0, -1).map((node) => node.id);
-	}
+    #selection = $state.raw(null);
+    schema = $state.raw();
+    doc = $state.raw();
+    config = $state.raw({});
+    history = $state.raw([]);
+    history_index = $state.raw(-1);
+    last_batch_started = $state.raw(undefined); // Timestamp for debounced batching
+    // Commands and keymap - initialized by Svedit when ready
+    // NOTE: Assumes single Svedit instance per session
+    commands = $state.raw({});
+    keymap = $state.raw({});
+    // Reactive helpers for UI state
+    can_undo = $derived(this.history_index >= 0);
+    can_redo = $derived(this.history_index < this.history.length - 1);
+    // Reactive variable for selected node
+    selected_node = $derived(this.get_selected_node());
+    available_mark_types = $derived(this.get_available_mark_types());
+    available_annotation_types = $derived(this.get_available_annotation_types());
+    selected_marks = $derived(get_selected_marks(this.schema, this.doc, this.selection));
+    active_mark = $derived(this.selected_marks.length === 1 ? this.selected_marks[0] : null);
+    selected_annotations = $derived(get_selected_annotations(this.schema, this.doc, this.selection));
+    active_annotation = $derived(this.selected_annotations.length === 1 ? this.selected_annotations[0] : null);
+    /**
+     * @param schema - The document schema
+     * @param doc - The document
+     * @param config - configuration object
+     * @param options - Optional settings (e.g. initial selection state)
+     */
+    constructor(schema, doc, config, options = {}) {
+        // Validate the schema first
+        validate_document_schema(schema);
+        this.schema = schema;
+        this.doc = doc;
+        this.config = config;
+        validate_document(this.doc, this.schema);
+        validate_config_components(this.schema, this.config);
+        // Set selection after doc is initialized so validation can work properly
+        this.selection = options.selection ?? null;
+    }
+    /**
+     * Gets the current selection
+     */
+    get selection() {
+        return this.#selection;
+    }
+    /**
+     * Sets the selection with validation
+     * @throws {Error} Throws if the selection is invalid
+     */
+    set selection(value) {
+        this._validate_selection(value);
+        this.#selection = value;
+    }
+    /**
+     * Validates that a selection is within bounds and refers to valid paths.
+     *
+     * @throws {Error} Throws if the selection is invalid
+     */
+    _validate_selection(selection) {
+        validate_selection(selection, this);
+    }
+    /**
+     * Gets the document_id from the doc
+     */
+    get document_id() {
+        return this.doc.document_id;
+    }
+    /**
+     * Validates the parts of a transaction result that can be affected by the transaction.
+     *
+     * This is intentionally narrower than full document validation. It validates all
+     * created/modified nodes, plus nodes that still reference created, modified, or
+     * deleted nodes. That catches local node invariants and dangling references left
+     * behind by deletes without scanning every node on every apply.
+     *
+     * @throws {Error} Throws if the transaction result is invalid
+     */
+    validate_transaction_result(transaction) {
+        const doc = transaction.doc;
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive local dedup set.
+        const affected_node_ids = new Set([
+            ...transaction.created_node_ids,
+            ...transaction.modified_node_ids
+        ]);
+        // A full-document referrer scan is only needed when a reference held
+        // by an UNTOUCHED node can have become invalid:
+        // - deletions can leave dangling references behind
+        // - a 'type' change can violate a referrer's node/mark/annotation type
+        //   constraint
+        // References to created nodes can only live in nodes that were
+        // themselves created or modified in this transaction (the reference
+        // did not exist before), and modifying a node's other properties
+        // cannot invalidate its referrers — so those cases are already
+        // covered by the affected set and need no scan.
+        if (transaction.deleted_node_ids.length > 0 || transaction.changed_node_types) {
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive local dedup set.
+            const scan_targets = new Set([
+                ...transaction.created_node_ids,
+                ...transaction.modified_node_ids,
+                ...transaction.deleted_node_ids
+            ]);
+            for (const node_id of get_referencing_node_ids(this.schema, doc, scan_targets)) {
+                affected_node_ids.add(node_id);
+            }
+        }
+        for (const node_id of affected_node_ids) {
+            const node = doc.nodes[node_id];
+            if (node)
+                validate_node(node, this.schema, doc.nodes);
+        }
+    }
+    generate_id() {
+        const id = this.config?.generate_id ? this.config.generate_id() : `node_${crypto.randomUUID()}`;
+        if (!is_id_valid(id)) {
+            throw new Error(`Generated node id ${JSON.stringify(id)} is invalid. Node ids must be non-empty strings that start with a letter or underscore, contain only letters, numbers, underscores, or dashes, and must not contain "__".`);
+        }
+        return id;
+    }
+    /**
+     * Initialize commands and keymap for this session.
+     * Called by Svedit component when it has the necessary context.
+     *
+     * NOTE: This assumes a single Svedit instance per session.
+     * For multiple editors on the same document, this architecture would need
+     * to be refactored to support multiple sessions per document.
+     *
+     * @param context - The svedit context with session, editable, canvas, etc.
+     */
+    initialize_commands(context) {
+        if (this.config?.create_commands_and_keymap) {
+            const { commands, keymap } = this.config.create_commands_and_keymap(context);
+            this.commands = commands;
+            this.keymap = keymap;
+        }
+    }
+    get_available_mark_types() {
+        if (this.selection?.type !== 'text' && this.selection?.type !== 'node')
+            return [];
+        const property_definition = this.inspect(this.selection.path);
+        return property_definition.mark_types || [];
+    }
+    get_available_annotation_types() {
+        if (this.selection?.type !== 'text' && this.selection?.type !== 'node')
+            return [];
+        const property_definition = this.inspect(this.selection.path);
+        return property_definition.annotation_types || [];
+    }
+    // Helper function to get the currently selected node
+    get_selected_node() {
+        if (!this.selection)
+            return null;
+        if (this.selection.type === 'node') {
+            const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+            const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+            // Only consider selection of a single node
+            if (end - start !== 1)
+                return null;
+            const node_array = this.get(this.selection.path);
+            const node_id = node_array.nodes[start];
+            return node_id ? this.get(node_id) : null;
+        }
+        else {
+            // we are assuming we are either in a text or property (=custom) selection
+            const owner_node_path = this.selection?.path?.slice(0, -1);
+            if (!owner_node_path)
+                return null;
+            const owner_node = this.get(owner_node_path);
+            return owner_node;
+        }
+    }
+    /**
+     * Creates a new transaction for making atomic changes to the document.
+     */
+    get tr() {
+        // We create a copy of the current state to avoid modifying the original
+        return new Transaction(this.schema, this.doc, this.selection, this.config);
+    }
+    /**
+     * Applies a transaction to the document.
+     * Auto-batches history entries with debounced behavior (max one entry per second) when batch is true.
+     *
+     * @param transaction - The transaction to apply
+     * @param options - Optional configuration (batch: whether to allow batching with previous transaction)
+     */
+    apply(transaction, { batch = false } = {}) {
+        this.validate_transaction_result(transaction);
+        // Only swap the doc when something changed. The transaction draft is
+        // always a fresh object, and assigning it for an ops-less transaction
+        // (e.g. selection-only) would needlessly invalidate every doc-dependent
+        // derived in the component tree.
+        if (transaction.ops.length > 0) {
+            this.doc = transaction.doc;
+        }
+        // Make sure selection gets a new reference (is rerendered)
+        this.selection = structuredClone(transaction.selection);
+        if (this.history_index < this.history.length - 1) {
+            this.history = this.history.slice(0, this.history_index + 1);
+        }
+        const now = Date.now();
+        const should_batch = batch &&
+            this.last_batch_started !== undefined &&
+            now - this.last_batch_started < BATCH_WINDOW_MS;
+        if (should_batch) {
+            // Append to existing history entry (within the batch window)
+            const last_entry = this.history[this.history_index];
+            last_entry.ops.push(...transaction.ops);
+            last_entry.inverse_ops.push(...transaction.inverse_ops);
+            last_entry.selection_after = this.selection;
+            // Trigger update
+            this.history = [...this.history];
+        }
+        else {
+            // Create new history entry (batch window elapsed, first edit, or batch not requested)
+            this.history = [
+                ...this.history,
+                {
+                    ops: transaction.ops,
+                    inverse_ops: transaction.inverse_ops,
+                    selection_before: transaction.selection_before,
+                    selection_after: this.selection
+                }
+            ];
+            this.history_index = this.history_index + 1;
+            // Only set last_batch_started if batching was requested
+            if (batch) {
+                this.last_batch_started = now;
+            }
+            else {
+                this.last_batch_started = undefined;
+            }
+        }
+        return this;
+    }
+    undo() {
+        if (this.history_index < 0) {
+            return;
+        }
+        const change = this.history[this.history_index];
+        // One draft for the whole change set — ops mutate the draft with
+        // node-level copy-on-write instead of copying the nodes map per op.
+        const doc = create_document_draft(this.doc);
+        change.inverse_ops
+            .slice()
+            .reverse()
+            .forEach((op) => {
+            apply_op_to_draft(doc, op);
+        });
+        this.doc = doc;
+        this.selection = change.selection_before;
+        this.history_index = this.history_index - 1;
+        // History navigation ends any open typing batch, so the next batched
+        // apply starts a fresh entry instead of appending to a stale one.
+        this.last_batch_started = undefined;
+        return this;
+    }
+    redo() {
+        if (this.history_index >= this.history.length - 1) {
+            return;
+        }
+        this.history_index = this.history_index + 1;
+        const change = this.history[this.history_index];
+        const doc = create_document_draft(this.doc);
+        change.ops.forEach((op) => {
+            apply_op_to_draft(doc, op);
+        });
+        this.doc = doc;
+        this.selection = change.selection_after;
+        // Redo ends any open typing batch, matching undo().
+        this.last_batch_started = undefined;
+        return this;
+    }
+    /**
+     * Gets a node instance or property value at the specified path.
+     *
+     * The result type defaults to `any` because a path can address a node or
+     * any property value. Annotate the target to type the result.
+     *
+     * @example
+     * // Get a node by ID
+     * session.get('list_1') // => { type: 'list', id: 'list_1', ... }
+     *
+     * @example
+     * // Get a node array property
+     * session.get(['list_1', 'list_items']) // => [ 'list_item_1', 'list_item_2' ]
+     *
+     * @example
+     * // Get a specific node from an array
+     * session.get(['page_1', 'body', 3, 'list_items', 0]) // => { type: 'list_item', id: 'list_item_1', ... }
+     *
+     * @example
+     * // Get a text property
+     * session.get(['page_1', 'cover', 'title']) // => {content: 'Hello world', marks: [], annotations: []}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get(path) {
+        return doc_get(this.schema, this.doc, path);
+    }
+    /**
+     * While .get gives you the value of a path, inspect gives you
+     * the type info of that value.
+     *
+     * @todo The layout of these should be improved and more explictly typed
+     *
+     * @example
+     * session.inspect(['page_1', 'body']) => {
+     *   kind: 'property',
+     *   name: 'body',
+     *   type: 'node_array',
+     *   node_types: ['text', 'story', 'list'],
+     *   default_node_type: 'text'
+     * }
+     *
+     * @example
+     * session.inspect(['page_1', 'body', 1]) => {
+     *   kind: 'node',
+     *   id: 'paragraph_234',
+     *   type: 'paragraph',
+     *   properties: {...}
+     * }
+     */
+    inspect(path) {
+        return doc_inspect(this.schema, this.doc, path);
+    }
+    /**
+     * Determines the kind of a node ('document' for root nodes, 'block' for
+     * structured blocks, 'text' for pure text nodes, 'mark' for mark nodes or
+     * 'annotation' for annotation nodes).
+     */
+    kind(node) {
+        return doc_kind(this.schema, node);
+    }
+    /**
+     * Determines whether a node type can be inserted at a given selection.
+     *
+     * @param node_type - The type of node to insert.
+     * @param selection - The selection at which to insert the node.
+     * @returns True if the node type can be inserted, false otherwise.
+     */
+    can_insert(node_type, selection = this.selection) {
+        if (selection?.type === 'node') {
+            const property_definition = this.inspect(selection.path);
+            if (property_definition.node_types.includes(node_type)) {
+                return true;
+            }
+        }
+        // No insert position found yet, and root not reached, try one level up if possible
+        let next_node_insert_caret = this.get_next_node_insert_caret(selection);
+        if (!next_node_insert_caret)
+            return false;
+        return this.can_insert(node_type, next_node_insert_caret);
+    }
+    /**
+     * Compute next possible insert position from a given selection
+     *
+     * @param selection - Reference selection
+     * @returns The next node insert caret selection, or null if none is available
+     */
+    get_next_node_insert_caret(selection = this.selection) {
+        // There's no parent path to insert into
+        if (!selection || selection.path.length <= 2) {
+            return null;
+        }
+        const node_offset = selection.path.at(-2) + 1;
+        return {
+            type: 'node',
+            path: selection.path.slice(0, -2),
+            anchor_offset: node_offset,
+            focus_offset: node_offset
+        };
+    }
+    get_selected_text() {
+        if (this.selection?.type !== 'text')
+            return null;
+        const selection_start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+        const selection_end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+        const text_value = this.get(this.selection.path);
+        const selected_text = char_slice(text_value.content, selection_start, selection_end);
+        const nodes = {};
+        const clip_ranges = (ranges) => ranges
+            .map((range) => {
+            if (selection_start < range.end_offset && selection_end > range.start_offset) {
+                const sub_graph = this.traverse(range.node_id);
+                for (const node of sub_graph) {
+                    if (!nodes[node.id]) {
+                        nodes[node.id] = node;
+                    }
+                }
+                return {
+                    start_offset: Math.max(range.start_offset - selection_start, 0),
+                    end_offset: Math.min(range.end_offset - selection_start, selection_end - selection_start),
+                    node_id: range.node_id
+                };
+            }
+            else {
+                return null;
+            }
+        })
+            .filter((range) => range !== null);
+        const marks = clip_ranges(text_value.marks);
+        const annotations = clip_ranges(text_value.annotations);
+        return { content: selected_text, marks, annotations, nodes };
+    }
+    get_selected_annotated_nodes() {
+        if (this.selection?.type !== 'node')
+            return null;
+        const selection_start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+        const selection_end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+        const node_array = this.get(this.selection.path);
+        const main_nodes = node_array.nodes.slice(selection_start, selection_end);
+        const nodes = {};
+        const add_subgraph = (node_id) => {
+            for (const node of this.traverse(node_id)) {
+                if (!nodes[node.id])
+                    nodes[node.id] = node;
+            }
+        };
+        for (const node_id of main_nodes)
+            add_subgraph(node_id);
+        const clip_ranges = (ranges) => ranges
+            .map((range) => {
+            if (selection_start >= range.end_offset || selection_end <= range.start_offset) {
+                return null;
+            }
+            add_subgraph(range.node_id);
+            return {
+                start_offset: Math.max(range.start_offset - selection_start, 0),
+                end_offset: Math.min(range.end_offset - selection_start, selection_end - selection_start),
+                node_id: range.node_id
+            };
+        })
+            .filter((range) => range !== null);
+        const marks = clip_ranges(node_array.marks);
+        const annotations = clip_ranges(node_array.annotations);
+        return { nodes, main_nodes, marks, annotations };
+    }
+    // TODO: think about ways how we can also turn a node selection into plain text.
+    get_selected_plain_text() {
+        if (this.selection?.type !== 'text')
+            return null;
+        const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+        const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+        const text = this.get(this.selection.path);
+        return char_slice(text.content, start, end);
+    }
+    get_selected_nodes() {
+        if (this.selection?.type !== 'node')
+            return null;
+        const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+        const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+        const node_array = this.get(this.selection.path);
+        // node_array.nodes is a plain array of id strings (doc is $state.raw),
+        // so a slice is already a safe fresh copy.
+        return node_array.nodes.slice(start, end);
+    }
+    select_parent() {
+        if (!this.selection)
+            return;
+        if (['text', 'property'].includes(this.selection.type)) {
+            // For text and property selections (e.g. ['page_1', 'body', 0, 'image']), we need to go up two levels
+            // in the path
+            if (this.selection.path.length > 3) {
+                const parent_path = this.selection.path.slice(0, -2);
+                const current_index = this.selection.path[this.selection.path.length - 2];
+                this.selection = {
+                    type: 'node',
+                    path: parent_path,
+                    anchor_offset: current_index,
+                    focus_offset: current_index + 1
+                };
+            }
+            else {
+                this.selection = null;
+            }
+        }
+        else if (this.selection.type === 'node') {
+            // For node selections, we go up one level
+            if (this.selection.path.length > 3) {
+                const parent_path = this.selection.path.slice(0, -2);
+                const current_index = this.selection.path[this.selection.path.length - 2];
+                this.selection = {
+                    type: 'node',
+                    path: parent_path,
+                    anchor_offset: current_index,
+                    focus_offset: current_index + 1
+                };
+            }
+            else {
+                this.selection = null;
+            }
+        }
+        else {
+            this.selection = null;
+        }
+    }
+    /**
+     * Traverses the document and returns a list of nodes in depth-first order.
+     *
+     * The traversal order is:
+     * 1. Leaf nodes first
+     * 2. Branch nodes second
+     * 3. Root node (entry point) last
+     *
+     * Nodes that are not reachable from the entry point node will not be included.
+     */
+    traverse(node_id) {
+        // doc is $state.raw, so doc.nodes is a plain (non-proxied) object —
+        // traverse() reads it directly and deep-clones each visited node.
+        // The previous $state.snapshot(this.doc.nodes) here deep-cloned the
+        // ENTIRE document per call, which made copying M nodes O(M·N).
+        return traverse(node_id, this.schema, this.doc.nodes);
+    }
+    /**
+     * Convert the document to a clean format for persistence.
+     *
+     * We make a traversal to ensure that orphaned nodes are not included,
+     * and that leaf nodes go first, followed by branches and the root node at last.
+     */
+    to_json() {
+        // this will order the nodes (depth-first traversal)
+        const nodes_array = this.traverse(this.document_id);
+        // convert nodes array to object with node IDs as keys
+        const nodes = Object.fromEntries(nodes_array.map((node) => [node.id, node]));
+        return {
+            document_id: this.document_id,
+            nodes
+        };
+    }
+    // property_type('page', 'body') => 'node_array'
+    // property_type('paragraph', 'content') => 'text'
+    property_type(type, property) {
+        return doc_property_type(this.schema, type, property);
+    }
+    // Count how many times a node is referenced in the document
+    count_references(node_id) {
+        return doc_count_references(this.schema, this.doc, node_id);
+    }
+    // Get all nodes referenced by a given node (recursively)
+    get_referenced_nodes(node_id) {
+        // Id-only traversal — no need to deep-clone the subgraph for ids.
+        return traverse_ids(node_id, this.schema, this.doc.nodes).slice(0, -1);
+    }
 }