svedit 0.11.1 → 0.13.0

package/dist/Transaction.svelte.js

@@ -1,29 +1,16 @@
+import { get_char_length, char_slice, traverse, traverse_ids, get_selection_range, is_selection_collapsed, adjust_ranges_for_deletion, adjust_ranges_for_insertion, are_ranges_exclusive } from './utils.js';
+import { join_text_node } from './transforms.svelte.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, build_reference_counts, visit_node_references, validate_node, is_id_valid, fill_node_defaults, can_switch_mark_type, get_selected_marks, get_selected_annotations, get_selected_range_types, validate_selection } from './doc_utils.js';
 /**
- * @import { NodeId, Selection, Document, DocumentSchema, DocumentPath, Annotation } from './types.d.js'
+ * Check whether a selection-relative range fits within a container length.
  */
-
-import {
-	get_char_length,
-	char_slice,
-	traverse,
-	get_selection_range,
-	is_selection_collapsed
-} from './utils.js';
-import { join_text_node } from './transforms.svelte.js';
-import {
-	get as doc_get,
-	property_type as doc_property_type,
-	kind as doc_kind,
-	inspect as doc_inspect,
-	apply_op,
-	count_references_excluding_deleted,
-	validate_node,
-	fill_node_defaults,
-	get_active_annotation,
-	validate_selection,
-	can_switch_annotation_type
-} from './doc_utils.js';
-
+function is_range_within_bounds(range, length) {
+    return (Number.isInteger(range.start_offset) &&
+        Number.isInteger(range.end_offset) &&
+        range.start_offset >= 0 &&
+        range.start_offset < range.end_offset &&
+        range.end_offset <= length);
+}
 /**
  * Transaction class for managing atomic document operations with undo/redo support.
  *
@@ -40,807 +27,836 @@ import {
  * ```
  */
 export default class Transaction {
-	/**
-	 * Creates a new Transaction with the given state.
-	 *
-	 * @param {DocumentSchema} schema - The document schema
-	 * @param {Document} doc - The document state {document_id, nodes}
-	 * @param {Selection | null} selection - The current selection
-	 * @param {object} config - The document config (including generate_id)
-	 */
-	constructor(schema, doc, selection, config) {
-		this.schema = schema;
-		/** @type {object} */
-		this.doc = doc;
-		/** @type {Selection} */
-		this.selection = selection;
-		this.config = config;
-		// Here we track the ops during the transaction
-		/** @type {Record<string, any>[]} */
-		this.ops = [];
-		/** @type {Record<string, any>[]} */
-		this.inverse_ops = [];
-		// Remember the selection before the transaction started
-		this.selection_before = selection;
-
-		/** @type {NodeId[]} */
-		this.created_node_ids = [];
-		/** @type {NodeId[]} */
-		this.modified_node_ids = [];
-		/** @type {NodeId[]} */
-		this.deleted_node_ids = [];
-	}
-
-	/**
-	 * Gets a value from the document at the specified path.
-	 *
-	 * @param {DocumentPath|string} path - The path to the value in the document, or a string node ID
-	 * @returns {any} The value at the specified path
-	 */
-	get(path) {
-		return doc_get(this.schema, this.doc, path);
-	}
-
-	/**
-	 * Gets the type of a property from the schema.
-	 *
-	 * @param {string} type - The node type
-	 * @param {string} property - The property name
-	 * @returns {string} The property type
-	 */
-	property_type(type, property) {
-		return doc_property_type(this.schema, type, property);
-	}
-
-	/**
-	 * Determines the kind of a node ('block', 'text', or 'annotation').
-	 *
-	 * @param {any} node - The node to check
-	 * @returns {'block'|'text'|'annotation'} The node kind
-	 */
-	kind(node) {
-		return doc_kind(this.schema, node);
-	}
-
-	/**
-	 * Inspects a path to get metadata about the value at that location.
-	 *
-	 * @param {DocumentPath} path - The path to inspect
-	 * @returns {{kind: 'property'|'node', [key: string]: any}} Metadata about the path
-	 */
-	inspect(path) {
-		return doc_inspect(this.schema, this.doc, path);
-	}
-
-	/**
-	 * Generates a new unique ID using the config's generate_id function.
-	 *
-	 * @returns {string} A new unique ID
-	 */
-	generate_id() {
-		return this.config.generate_id();
-	}
-
-	/**
-	 * Validates a node against the document schema.
-	 *
-	 * @param {any} node - The node to validate
-	 * @throws {Error} Throws if the node is invalid
-	 */
-	validate_node(node) {
-		validate_node(node, this.schema, this.doc.nodes, { require_references: false });
-	}
-
-
-	/**
-	 * Gets all nodes referenced by a given node (recursively).
-	 *
-	 * @param {NodeId} node_id - The node ID to get references for
-	 * @returns {NodeId[]} Array of referenced node IDs
-	 */
-	get_referenced_nodes(node_id) {
-		const traversed_nodes = traverse(node_id, this.schema, this.doc.nodes);
-		return traversed_nodes.slice(0, -1).map((node) => node.id);
-	}
-
-	/**
-	 * Gets the available annotation types for the current selection.
-	 *
-	 * @returns {string[]} Array of available annotation type names
-	 */
-	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 || [];
-	}
-
-	/**
-	 * Returns the annotation object that is currently "under the caret".
-	 * 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);
-	}
-
-	/**
-	 * Applies an operation to the document (internal).
-	 *
-	 * @param {Array} op - The operation to apply
-	 * @private
-	 */
-	_apply_op(op) {
-		this.doc = apply_op(this.doc, op);
-	}
-
-	/**
-	 * @param {NodeId[]} node_ids
-	 * @param {NodeId} node_id
-	 * @private
-	 */
-	_track_node_id(node_ids, node_id) {
-		if (!node_ids.includes(node_id)) node_ids.push(node_id);
-	}
-
-	/**
-	 * Sets a property of a node to a new value.
-	 *
-	 * This is the core operation for modifying document properties. It records
-	 * both the forward operation and its inverse for undo support.
-	 *
-	 * @param {DocumentPath} path - Array path to the property (e.g., ["node_1", "title"])
-	 * @param {any} value - The new value to set
-	 * @returns {Transaction} This transaction instance for method chaining
-	 *
-	 * @example
-	 * ```js
-	 * tr.set(["list_1", "list_items"], [1, 2, 3]);
-	 * tr.set(["page_1", "body", "0", "description"], {text: "Hello world", annotations: []});
-	 * ```
-	 */
-	set(path, value) {
-		const path_info = this.inspect(path);
-		if (path_info?.kind !== 'property') {
-			throw new Error(
-				`Transaction.set requires a path that points to a property, got ${JSON.stringify(path)}`
-			);
-		}
-
-		const node = this.get(path.slice(0, -1));
-
-		// Turns ["page_1", "body", "0", "description"]
-		// into ["paragraph_1", "description"].
-		// Important to keep changes of multiple ops invertible.
-		const normalized_path = [node.id, path.at(-1)];
-
-		// Just to be sure, make a deep copy of the old value
-		const property_key = path.at(-1);
-		const property_key_str = String(property_key);
-		const previous_value = structuredClone($state.snapshot(node[property_key_str]));
-
-		// Collect node IDs that might need to be deleted after the set operation
-		const prop_type = this.property_type(node.type, property_key_str);
-		/** @type {NodeId[]} */
-		let removed_node_ids = [];
-
-		if (prop_type === 'node' && typeof previous_value === 'string' && previous_value !== value) {
-			removed_node_ids = [previous_value];
-		} else if (
-			prop_type === 'node_array' &&
-			Array.isArray(previous_value) &&
-			Array.isArray(value)
-		) {
-			// Only include node IDs that were in previous_value but are not in the new value
-			removed_node_ids = previous_value.filter((id) => !value.includes(id));
-		}
-
-		const op = ['set', normalized_path, value];
-		this.ops.push(op);
-		this.inverse_ops.push(['set', normalized_path, previous_value]);
-		this._apply_op(op);
-		this._track_node_id(this.modified_node_ids, node.id);
-
-		// Garbage-collect nodes whose only reference was via this property.
-		// We must use a ref-count-aware sweep instead of unconditional deletion
-		// because a node ID removed from this array may still be referenced
-		// elsewhere — either from a pre-existing reference (e.g. shared nodes)
-		// or from a node created earlier in the same transaction (the
-		// wrap-in-group pattern: create a wrapper that points at the children,
-		// then set the parent array to drop them).
-		if (removed_node_ids.length > 0) {
-			this._cascade_delete_unreferenced_nodes(removed_node_ids);
-		}
-
-		return this;
-	}
-
-	// Takes a subgraph and constructs new nodes from it
-	// NOTE: all ids will be mapped to new unique ids.
-	// NOTE: Omitted properties will be populated with default values.
-	build(node_id, nodes) {
-		const depth_first_nodes = traverse(node_id, this.schema, nodes);
-		// This maps original ids to newly generated ids
-		const id_map = {};
-
-		for (const node of depth_first_nodes) {
-			const new_id = this.generate_id();
-			id_map[node.id] = new_id;
-			let new_node = { ...node, id: new_id };
-			const node_schema = this.schema[node.type];
-
-			// Update all property references to use new IDs
-			for (const [property_name, property_definition] of Object.entries(node_schema.properties)) {
-				const prop_type = property_definition.type;
-				const value = new_node[property_name];
-
-				if (prop_type === 'node_array' && Array.isArray(value)) {
-					new_node[property_name] = value.map((ref_id) => id_map[ref_id]);
-				} else if (prop_type === 'node' && typeof value === 'string') {
-					new_node[property_name] = id_map[value];
-				} else if (prop_type === 'annotated_text' && value) {
-					const annotations = value.annotations.map((annotation) => {
-						const { start_offset, end_offset, node_id } = annotation;
-						return { start_offset, end_offset, node_id: id_map[node_id] || node_id };
-					});
-					new_node[property_name] = { text: value.text, annotations };
-				}
-			}
-
-			new_node = fill_node_defaults(new_node, this.schema);
-			this.create(new_node);
-		}
-
-		return id_map[depth_first_nodes.at(-1).id];
-	}
-
-	/**
-	 * Creates a new node in the document.
-	 *
-	 * The node must have a valid id and must not already exist in the document.
-	 * Omitted properties with schema defaults are filled before validation.
-	 *
-	 * @param {any} node - The node object to create (must include id, type, and required properties)
-	 * @returns {Transaction} This transaction instance for method chaining
-	 * @throws {Error} If the node ID is invalid or if the node already exists
-	 *
-	 * @example
-	 * ```js
-	 * tr.create({
-	 *   id: 'para_123',
-	 *   type: 'paragraph',
-	 *   content: ['Hello world', []]
-	 * });
-	 * ```
-	 */
-	create(node) {
-		const node_with_defaults = fill_node_defaults(node, this.schema);
-
-		// Validate node against schema
-		this.validate_node(node_with_defaults);
-
-		if (this.get(node_with_defaults.id)) {
-			throw new Error('Node with id ' + node_with_defaults.id + ' already exists');
-		}
-
-		const op = ['create', node_with_defaults];
-		this.ops.push(op);
-		this.inverse_ops.push(['delete', node_with_defaults.id]);
-		this._apply_op(op);
-		this._track_node_id(this.created_node_ids, node_with_defaults.id);
-		return this;
-	}
-
-	/**
-	 * Deletes a node from the document by its ID.
-	 *
-	 * The node's current state is captured for undo support before deletion.
-	 *
-	 * NOTE: This is a force-delete and intentionally does NOT check whether
-	 * the node is still referenced from elsewhere — callers (e.g.
-	 * `annotate_text`) sometimes need to remove a node while a stale
-	 * reference to it still exists in the property they are about to update.
-	 * For ref-count-aware cleanup, see how `set` calls
-	 * `_cascade_delete_unreferenced_nodes`.
-	 *
-	 * @param {any} id - The ID of the node to delete
-	 * @returns {Transaction} This transaction instance for method chaining
-	 *
-	 * @example
-	 * ```js
-	 * tr.delete('node_123');
-	 * ```
-	 */
-	delete(id) {
-		const previous_value = this.get(id);
-		if (!previous_value) {
-			console.warn(`Deletion of node ${id} skipped, as it does not exist.`);
-			return this;
-		}
-		// Get nodes referenced by this node BEFORE deleting it.
-		const referenced_nodes = this.get_referenced_nodes(id);
-		const op = ['delete', id];
-		this.ops.push(op);
-		this.inverse_ops.push(['create', previous_value]);
-		this._apply_op(op);
-		this._track_node_id(this.deleted_node_ids, id);
-		// Cascade delete any nodes that are now orphaned after removing this node
-		this._cascade_delete_unreferenced_nodes(referenced_nodes);
-		return this;
-	}
-
-	/**
-	 * Sets the document selection.
-	 *
-	 * @param {Selection} selection - The new selection object
-	 * @returns {Transaction} This transaction instance for method chaining
-	 * @throws {Error} Throws if the selection is invalid or out of bounds
-	 */
-	set_selection(selection) {
-		this._validate_selection(selection);
-		this.selection = selection;
-		return this;
-	}
-
-	/**
-	 * Validates a selection against the current document state.
-	 *
-	 * @param {Selection} selection - The selection to validate
-	 * @throws {Error} Throws if the selection is invalid
-	 * @private
-	 */
-	_validate_selection(selection) {
-		validate_selection(selection, this);
-	}
-
-	/**
-	 * Adds, updates, or removes text annotations in the current selection.
-	 *
-	 * Handles various annotation scenarios including adding new annotations,
-	 * updating existing ones (especially for links), and removing annotations
-	 * when conflicting types are applied.
-	 *
-	 * @param {any} annotation_type - The type of annotation (e.g., 'link', 'bold', 'italic')
-	 * @param {any} annotation_properties - Additional data for the annotation (e.g., href for links)
-	 * @returns {Transaction} This transaction instance for method chaining
-	 *
-	 * @example
-	 * ```js
-	 * // Add a link annotation
-	 * tr.annotate_text('link', { href: 'https://example.com' });
-	 *
-	 * // Add emphasis
-	 * tr.annotate_text('emphasis', {});
-	 * ```
-	 */
-	annotate_text(annotation_type, annotation_properties) {
-		if (this.selection.type !== 'text') return this;
-
-		const range = get_selection_range(this.selection);
-		const annotated_text = structuredClone($state.snapshot(this.get(this.selection.path)));
-		const annotations = annotated_text.annotations;
-		const existing_annotation = this.active_annotation();
-		const existing_annotation_same_type = this.active_annotation(annotation_type);
-		const has_annotation_properties =
-			annotation_properties && Object.keys(annotation_properties).length > 0;
-
-		if (existing_annotation) {
-			// If there's an existing annotation of the same type, remove it
-			if (existing_annotation_same_type) {
-				const index = annotations.findIndex(
-					/** @param {any} anno */ (anno) =>
-						anno.start_offset === existing_annotation.start_offset &&
-						anno.end_offset === existing_annotation.end_offset
-				);
-				if (index !== -1) {
-					// Remove the annotation node from the graph
-					this.delete(annotations[index].node_id);
-					annotations.splice(index, 1);
-				}
-			} else {
-				const existing_annotation_node = this.get(existing_annotation.node_id);
-				const can_switch_annotation =
-					!has_annotation_properties &&
-					this.available_annotation_types.includes(annotation_type) &&
-					can_switch_annotation_type(
-						this.schema,
-						existing_annotation_node,
-						annotation_type
-					);
-
-				if (can_switch_annotation) {
-					this.set([existing_annotation.node_id, 'type'], annotation_type);
-					return this;
-				}
-
-				// If there's an annotation of a different incompatible type, don't add a new one
-				return this;
-			}
-		} else {
-			if (is_selection_collapsed(this.selection)) {
-				return this;
-			}
-			if (!this.available_annotation_types.includes(annotation_type)) {
-				console.warn(`Annotation type ${annotation_type} is not allowed here.`);
-				return this;
-			}
-			const new_annotation_node = {
-				id: this.generate_id(),
-				type: annotation_type,
-				...annotation_properties
-			};
-			this.create(new_annotation_node);
-			// If there's no existing annotation, add the new one
-			annotations.push({
-				start_offset: range.start_offset,
-				end_offset: range.end_offset,
-				node_id: new_annotation_node.id
-			});
-		}
-
-		// Update the annotated text
-		this.set(this.selection.path, annotated_text);
-		return this;
-	}
-
-	/**
-	 * Deletes the currently selected text, node, or property.
-	 *
-	 * Behavior depends on selection type:
-	 * - For node selections: Removes selected nodes and cascades deletion of unreferenced nodes
-	 * - For text selections: Removes selected text and adjusts annotations accordingly
-	 * - For collapsed selections: Deletes the previous character/node (backward) or next character/node (forward)
-	 * - For property selections: Delegates to the config's handle_property_deletion hook
-	 *
-	 * @param {'backward' | 'forward'} [direction] - Direction of deletion for collapsed selections
-	 * @returns {Transaction} This transaction instance for method chaining
-	 */
-	delete_selection(direction = 'backward') {
-		if (!this.selection) return this;
-
-		if (this.selection.type === 'property') {
-			this.config.handle_property_deletion?.(this, this.selection.path);
-			return this;
-		}
-
-		const path = this.selection.path;
-
-		// Get the start and end indices for the selection
-		let start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
-		let end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
-		let length;
-
-		if (this.selection?.type === 'text') {
-			const text_content = this.get(this.selection.path).text;
-			length = get_char_length(text_content);
-		} else if (this.selection?.type === 'node') {
-			const node_array = this.get(this.selection.path);
-			length = node_array.length;
-		}
-
-		// If selection is collapsed we delete the previous char/node (backward)
-		// or the next char/node (forward)
-		if (start === end) {
-			if (direction === 'backward' && start > 0) {
-				start = start - 1;
-			} else if (direction === 'forward' && end < length) {
-				end = end + 1;
-			} else if (direction === 'backward' && start === 0) {
-				join_text_node(this);
-				return this;
-			} else if (direction === 'forward' && end === length) {
-				// At end of text - try to join with next text node
-				const node_index = parseInt(String(this.selection.path.at(-2)), 10);
-				const successor_node = this.get([...this.selection.path.slice(0, -2), node_index + 1]);
-				// Check if next node is a text node
-				if (successor_node && this.kind(successor_node) === 'text') {
-					// Set selection to beginning of next text node
-					this.set_selection({
-						type: 'text',
-						path: [...this.selection.path.slice(0, -2), node_index + 1, 'content'],
-						anchor_offset: 0,
-						focus_offset: 0
-					});
-					// Use join_text_node to merge with previous node
-					join_text_node(this);
-				}
-				return this;
-			}
-		}
-
-		if (this.selection.type === 'node') {
-			const node_array = [...this.get(path)];
-
-			// Remove the selected nodes from the node_array
-			node_array.splice(start, end - start);
-
-			// Update the node_array in the entry (this implicitly records an op via this.set)
-			// Note: this.set() will automatically cascade delete unreferenced nodes
-			this.set(path, node_array);
-
-			// Update the selection to point to the start of the deleted range
-			this.selection = {
-				type: 'node',
-				path,
-				anchor_offset: start,
-				focus_offset: start
-			};
-		} else if (this.selection.type === 'text') {
-			const path = this.selection.path;
-			let text = structuredClone($state.snapshot(this.get(path)));
-
-			// Update the text content using character-based operations
-			const original_text = text.text;
-			text.text =
-				char_slice(original_text, 0, start) +
-				char_slice(original_text, end, get_char_length(original_text));
-
-			// To mark annotation nodes for deletion.
-			/** @type {string[]} */
-			const _deleted_nodes = [];
-			const deletion_length = end - start;
-			const new_annotations = text.annotations
-				.map((/** @type {any} */ annotation) => {
-					const annotation_start = annotation.start_offset;
-					const annotation_end = annotation.end_offset;
-					const node_id = annotation.node_id;
-
-					// Case 1: Annotation is entirely before the deleted range - keep unchanged
-					if (annotation_end <= start) {
-						return annotation;
-					}
-
-					// Case 2: Annotation is entirely after the deleted range - shift it
-					let new_start = annotation_start;
-					if (annotation_start >= end) {
-						new_start = annotation_start - deletion_length;
-					} else if (annotation_start > start) {
-						// Annotation starts inside deleted range
-						new_start = start;
-					}
-
-					// Case 3: Annotation overlaps with deleted range - adjust end
-					let new_end = annotation_end;
-					if (annotation_end >= end) {
-						new_end = annotation_end - deletion_length;
-					} else if (annotation_end > start) {
-						// Annotation ends inside deleted range
-						new_end = start;
-					}
-
-					// If annotation is now empty, mark for deletion
-					if (new_start >= new_end) {
-						_deleted_nodes.push(node_id);
-						return null;
-					}
-
-					return { start_offset: new_start, end_offset: new_end, node_id };
-				})
-				.filter(Boolean);
-
-			text.annotations = new_annotations;
-
-			this.set(path, text);
-
-			// Delete marked annotation nodes only if no other references remain.
-			this._cascade_delete_unreferenced_nodes(_deleted_nodes);
-
-			// Update the selection to the new caret position
-			this.selection = {
-				type: 'text',
-				path,
-				anchor_offset: start,
-				focus_offset: start
-			};
-		}
-
-		return this;
-	}
-
-	/**
-	 * Inserts nodes at the current node selection position.
-	 *
-	 * If the selection is expanded (not collapsed), first deletes the selected nodes
-	 * before inserting the new ones.
-	 *
-	 * @param {NodeId[]} node_ids - Array of node IDs to insert
-	 * @returns {Transaction} This transaction instance for method chaining
-	 */
-	insert_nodes(node_ids) {
-		if (this.selection.type !== 'node') return this;
-
-		// Unless caret is collapsed, delete the selected nodes as a first step
-		if (this.selection.anchor_offset !== this.selection.focus_offset) {
-			this.delete_selection();
-		}
-
-		const path = this.selection.path;
-		const node_array = [...this.get(path)];
-
-		let start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
-
-		// Insert the new nodes
-		node_array.splice(start, 0, ...node_ids);
-		this.set(path, node_array);
-
-		this.selection = {
-			type: 'node',
-			path: [...this.selection.path],
-			anchor_offset: start,
-			focus_offset: start + node_ids.length
-		};
-
-		return this;
-	}
-
-	/**
-	 * Inserts text at the current text selection position.
-	 *
-	 * Handles annotation adjustments when text is inserted, including:
-	 * - Expanding annotations that contain the insertion point
-	 * - Shifting annotations that come after the insertion point
-	 * - Optionally applying new annotations to the inserted text
-	 *
-	 * @param {string} replaced_text - The text to insert
-	 * @param {Array} [annotations] - Optional annotations to apply to the inserted text
-	 * @param {object} [nodes] - Optional node definitions for annotation nodes
-	 * @returns {Transaction} This transaction instance for method chaining
-	 */
-	insert_text(replaced_text, annotations = [], nodes = {}) {
-		if (this.selection?.type !== 'text') return this;
-
-		// Unless selection is collapsed, delete the selected content
-		// NOTE: This makes sure wrapped annotations are disposed correctly
-		if (!is_selection_collapsed(this.selection)) {
-			this.delete_selection();
-		}
-
-		const annotated_text = structuredClone($state.snapshot(this.get(this.selection.path)));
-		const range = get_selection_range(this.selection);
-
-		// Transform the plain text string using character-based operations
-		const text = annotated_text.text;
-		annotated_text.text =
-			char_slice(text, 0, range.start_offset) + replaced_text + char_slice(text, range.end_offset);
-
-		// Calculate the change in length
-		const delta = get_char_length(replaced_text);
-
-		const new_annotations = annotated_text.annotations.map((/** @type {any} */ annotation) => {
-			const annotation_start = annotation.start_offset;
-			const annotation_end = annotation.end_offset;
-			const node_id = annotation.node_id;
-
-			// Annotation is entirely before the insertion point
-			if (annotation_end <= range.start_offset) {
-				return annotation;
-			}
-
-			// Insertion point is inside the annotation (not at the start) - extend it
-			if (annotation_start < range.start_offset && annotation_end >= range.start_offset) {
-				return {
-					start_offset: annotation_start,
-					end_offset: annotation_end + delta,
-					node_id
-				};
-			}
-
-			// Annotation is entirely after the insertion point - shift it
-			if (annotation_start >= range.start_offset) {
-				return {
-					start_offset: annotation_start + delta,
-					end_offset: annotation_end + delta,
-					node_id
-				};
-			}
-			return annotation;
-		});
-
-		annotated_text.annotations = new_annotations;
-		this.set(this.selection.path, annotated_text); // this will update the current state and create a history entry
-
-		// Setting the selection automatically triggers a re-render of the corresponding DOMSelection.
-		/** @type {Selection} */
-		const new_selection = {
-			type: /** @type {const} */ ('text'),
-			path: this.selection.path,
-			anchor_offset: range.start_offset + get_char_length(replaced_text),
-			focus_offset: range.start_offset + get_char_length(replaced_text)
-		};
-		this.selection = new_selection;
-
-		// Now we apply annotations if there are any, but only if there's no active annotation
-		// at the current collapsed caret
-		if (!this.active_annotation() && annotations.length > 0) {
-			const new_annotations = annotations
-				.map((annotation) => {
-					const original_annotation_node = nodes[annotation.node_id];
-					const text_property_definition = this.inspect(this.selection.path);
-					// console.log('original_annotation_node.type', original_annotation_node.type);
-					// console.log('text_property_definition', text_property_definition);
-					if (text_property_definition.node_types.includes(original_annotation_node.type)) {
-						const new_annotation_node_id = this.build(annotation.node_id, nodes);
-						return {
-							start_offset: range.start_offset + annotation.start_offset,
-							end_offset: range.start_offset + annotation.end_offset,
-							node_id: new_annotation_node_id
-						};
-					}
-					return null;
-				})
-				.filter(Boolean);
-			const next_annotated_text = structuredClone(annotated_text);
-			next_annotated_text.annotations = next_annotated_text.annotations.concat(new_annotations);
-			this.set(this.selection.path, next_annotated_text); // this will update the current state and create a history entry
-		}
-
-		return this;
-	}
-
-	/**
-	 * Recursively deletes nodes that are no longer referenced in the document.
-	 *
-	 * This handles the cascade deletion of child nodes when their parent
-	 * references are removed. Uses reference counting to determine which
-	 * nodes are safe to delete.
-	 *
-	 * @param {NodeId[]} potentially_orphaned_nodes - Array of node IDs to check
-	 * @private
-	 */
-	_cascade_delete_unreferenced_nodes(potentially_orphaned_nodes) {
-		/** @type {Record<NodeId, boolean>} */
-		const nodes_to_delete = {};
-		const to_check = [...potentially_orphaned_nodes];
-
-		while (to_check.length > 0) {
-			const node_id = to_check.pop();
-			if (!node_id || nodes_to_delete[node_id]) continue;
-
-			// Count references to this node, excluding nodes already marked for deletion
-			const ref_count = this._count_references_excluding_deleted(node_id, nodes_to_delete);
-
-			if (ref_count === 0) {
-				// No more references, safe to delete this node
-				nodes_to_delete[node_id] = true;
-
-				// Also check all nodes referenced by this node
-				const referenced_nodes = this.get_referenced_nodes(node_id);
-				to_check.push(...referenced_nodes);
-			}
-		}
-
-		// Now perform the actual deletions
-		for (const node_id of Object.keys(nodes_to_delete)) {
-			const previous_value = this.get([node_id]);
-			if (previous_value) {
-				const op = ['delete', node_id];
-				this.ops.push(op);
-				this.inverse_ops.push(['create', previous_value]);
-				this._apply_op(op);
-				this._track_node_id(this.deleted_node_ids, node_id);
-			}
-		}
-	}
-
-	/**
-	 * Counts references to a node, excluding nodes that have been marked for deletion.
-	 *
-	 * This is used during cascade deletion to accurately count remaining references
-	 * as nodes are being deleted.
-	 *
-	 * @param {NodeId} target_node_id - The node ID to count references for
-	 * @param {Record<NodeId, boolean>} nodes_to_delete - Nodes already marked for deletion
-	 * @returns {number} The number of references to the target node
-	 * @private
-	 */
-	_count_references_excluding_deleted(target_node_id, nodes_to_delete) {
-		return count_references_excluding_deleted(
-			this.schema,
-			this.doc,
-			target_node_id,
-			nodes_to_delete
-		);
-	}
+    schema;
+    doc;
+    // NOTE: Typed non-null for historical reasons — most methods assume a
+    // selection is present. A null selection is cast here and would surface at
+    // runtime exactly as before the TypeScript conversion.
+    selection;
+    config;
+    ops;
+    inverse_ops;
+    selection_before;
+    created_node_ids;
+    modified_node_ids;
+    deleted_node_ids;
+    changed_node_types;
+    /**
+     * Creates a new Transaction with the given state.
+     *
+     * @param schema - The document schema
+     * @param doc - The document state {document_id, nodes}
+     * @param selection - The current selection
+     * @param config - The document config (including generate_id)
+     */
+    constructor(schema, doc, selection, config) {
+        this.schema = schema;
+        // The transaction works on a draft: one shallow copy of the nodes map
+        // up front, then ops mutate the draft in place (copying node objects
+        // on write). This keeps the original document untouched and node
+        // identity stable for unchanged nodes, without the previous
+        // one-full-map-copy-per-op cost.
+        this.doc = create_document_draft(doc);
+        this.selection = selection;
+        this.config = config;
+        // Here we track the ops during the transaction
+        this.ops = [];
+        this.inverse_ops = [];
+        // Remember the selection before the transaction started
+        this.selection_before = selection;
+        this.created_node_ids = [];
+        this.modified_node_ids = [];
+        this.deleted_node_ids = [];
+        // True when any op set a node's 'type' property — referrers must be
+        // re-validated against type constraints in that case.
+        this.changed_node_types = false;
+    }
+    /**
+     * Gets a value from the document at the specified path.
+     *
+     * @param path - The path to the value in the document, or a string node ID
+     * @returns The value at the specified path
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get(path) {
+        return doc_get(this.schema, this.doc, path);
+    }
+    /**
+     * Gets the type of a property from the schema.
+     */
+    property_type(type, property) {
+        return doc_property_type(this.schema, type, property);
+    }
+    /**
+     * Determines the kind of a node ('document', 'block', 'text', 'mark', or 'annotation').
+     */
+    kind(node) {
+        return doc_kind(this.schema, node);
+    }
+    /**
+     * Inspects a path to get metadata about the value at that location.
+     */
+    inspect(path) {
+        return doc_inspect(this.schema, this.doc, path);
+    }
+    /**
+     * Generates a new unique ID using the config's generate_id function.
+     */
+    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;
+    }
+    /**
+     * Validates a node against the document schema.
+     *
+     * @throws {Error} Throws if the node is invalid
+     */
+    validate_node(node) {
+        validate_node(node, this.schema, this.doc.nodes, { require_references: false });
+    }
+    /**
+     * Gets all nodes referenced by a given node (recursively).
+     */
+    get_referenced_nodes(node_id) {
+        return traverse_ids(node_id, this.schema, this.doc.nodes).slice(0, -1);
+    }
+    /**
+     * Gets the available mark types for the current selection.
+     */
+    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 || [];
+    }
+    /**
+     * Gets the available annotation types for the current selection.
+     */
+    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 || [];
+    }
+    /**
+     * Returns marks touched by the current selection.
+     */
+    get selected_marks() {
+        return get_selected_marks(this.schema, this.doc, this.selection);
+    }
+    get active_mark() {
+        return this.selected_marks.length === 1 ? this.selected_marks[0] : null;
+    }
+    /**
+     * Returns annotations touched by the current selection.
+     */
+    get selected_annotations() {
+        return get_selected_annotations(this.schema, this.doc, this.selection);
+    }
+    get active_annotation() {
+        return this.selected_annotations.length === 1 ? this.selected_annotations[0] : null;
+    }
+    /**
+     * Applies an operation to the document (internal).
+     */
+    _apply_op(op) {
+        apply_op_to_draft(this.doc, op);
+    }
+    _track_node_id(node_ids, node_id) {
+        if (!node_ids.includes(node_id))
+            node_ids.push(node_id);
+    }
+    /**
+     * Sets a property of a node to a new value.
+     *
+     * This is the core operation for modifying document properties. It records
+     * both the forward operation and its inverse for undo support.
+     *
+     * @param path - Array path to the property (e.g., ["node_1", "title"])
+     * @param value - The new value to set
+     * @returns This transaction instance for method chaining
+     *
+     * @example
+     * ```js
+     * tr.set(["list_1", "list_items"], [1, 2, 3]);
+     * tr.set(["page_1", "body", "0", "description"], {content: "Hello world", marks: [], annotations: []});
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    set(path, value) {
+        const path_info = this.inspect(path);
+        if (path_info?.kind !== 'property') {
+            throw new Error(`Transaction.set requires a path that points to a property, got ${JSON.stringify(path)}`);
+        }
+        const node = this.get(path.slice(0, -1));
+        // Turns ["page_1", "body", "0", "description"]
+        // into ["paragraph_1", "description"].
+        // Important to keep changes of multiple ops invertible.
+        const normalized_path = [node.id, path.at(-1)];
+        // Just to be sure, make a deep copy of the old value
+        const property_key = path.at(-1);
+        const property_key_str = String(property_key);
+        const previous_value = structuredClone($state.snapshot(node[property_key_str]));
+        // Collect node IDs that might need to be deleted after the set operation
+        const prop_type = this.property_type(node.type, property_key_str);
+        let removed_node_ids = [];
+        if (prop_type === 'node' && typeof previous_value === 'string' && previous_value !== value) {
+            removed_node_ids = [previous_value];
+        }
+        else if (prop_type === 'node_array') {
+            const previous_node_ids = previous_value.nodes;
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive local lookup set.
+            const next_node_ids = new Set(value.nodes);
+            // Only include node IDs that were in previous_value but are not in the new value
+            removed_node_ids = previous_node_ids.filter((id) => !next_node_ids.has(id));
+        }
+        const op = ['set', normalized_path, value];
+        this.ops.push(op);
+        this.inverse_ops.push(['set', normalized_path, previous_value]);
+        this._apply_op(op);
+        this._track_node_id(this.modified_node_ids, node.id);
+        if (property_key_str === 'type')
+            this.changed_node_types = true;
+        // Garbage-collect nodes whose only reference was via this property.
+        // We must use a ref-count-aware sweep instead of unconditional deletion
+        // because a node ID removed from this array may still be referenced
+        // elsewhere — either from a pre-existing reference (e.g. shared nodes)
+        // or from a node created earlier in the same transaction (the
+        // wrap-in-group pattern: create a wrapper that points at the children,
+        // then set the parent array to drop them).
+        if (removed_node_ids.length > 0) {
+            this._cascade_delete_unreferenced_nodes(removed_node_ids);
+        }
+        return this;
+    }
+    // Takes a subgraph and constructs new nodes from it
+    // NOTE: all ids will be mapped to new unique ids.
+    // NOTE: Omitted properties will be populated with default values.
+    build(node_id, nodes) {
+        const depth_first_nodes = traverse(node_id, this.schema, nodes);
+        // This maps original ids to newly generated ids
+        const id_map = {};
+        for (const node of depth_first_nodes) {
+            const new_id = this.generate_id();
+            id_map[node.id] = new_id;
+            let new_node = { ...node, id: new_id };
+            const node_schema = this.schema[node.type];
+            // Update all property references to use new IDs
+            for (const [property_name, property_definition] of Object.entries(node_schema.properties)) {
+                const prop_type = property_definition.type;
+                const value = new_node[property_name];
+                const remap_ranges = (ranges) => (ranges ?? []).map(({ start_offset, end_offset, node_id }) => {
+                    return { start_offset, end_offset, node_id: id_map[node_id] || node_id };
+                });
+                if (prop_type === 'node_array' && value && typeof value === 'object') {
+                    new_node[property_name] = {
+                        nodes: value.nodes.map((ref_id) => id_map[ref_id]),
+                        marks: remap_ranges(value.marks),
+                        annotations: remap_ranges(value.annotations)
+                    };
+                }
+                else if (prop_type === 'node' && typeof value === 'string') {
+                    new_node[property_name] = id_map[value];
+                }
+                else if (prop_type === 'text' && value) {
+                    new_node[property_name] = {
+                        content: value.content,
+                        marks: remap_ranges(value.marks),
+                        annotations: remap_ranges(value.annotations)
+                    };
+                }
+            }
+            new_node = fill_node_defaults(new_node, this.schema);
+            this.create(new_node);
+        }
+        return id_map[depth_first_nodes.at(-1).id];
+    }
+    /**
+     * Creates a new node in the document.
+     *
+     * The node must have a valid id and must not already exist in the document.
+     * Omitted properties with schema defaults are filled before validation.
+     *
+     * @param node - The node object to create (must include id, type, and required properties)
+     * @returns This transaction instance for method chaining
+     * @throws {Error} If the node ID is invalid or if the node already exists
+     *
+     * @example
+     * ```js
+     * tr.create({
+     *   id: 'para_123',
+     *   type: 'paragraph',
+     *   content: ['Hello world', []]
+     * });
+     * ```
+     */
+    create(node) {
+        const node_with_defaults = fill_node_defaults(node, this.schema);
+        // Validate node against schema
+        this.validate_node(node_with_defaults);
+        if (this.get(node_with_defaults.id)) {
+            throw new Error('Node with id ' + node_with_defaults.id + ' already exists');
+        }
+        const op = ['create', node_with_defaults];
+        this.ops.push(op);
+        this.inverse_ops.push(['delete', node_with_defaults.id]);
+        this._apply_op(op);
+        this._track_node_id(this.created_node_ids, node_with_defaults.id);
+        return this;
+    }
+    /**
+     * Deletes a node from the document by its ID.
+     *
+     * The node's current state is captured for undo support before deletion.
+     *
+     * NOTE: This is a force-delete and intentionally does NOT check whether
+     * the node is still referenced from elsewhere — callers (e.g.
+     * `toggle_mark`) sometimes need to remove a node while a stale
+     * reference to it still exists in the property they are about to update.
+     * For ref-count-aware cleanup, see how `set` calls
+     * `_cascade_delete_unreferenced_nodes`.
+     *
+     * @param id - The ID of the node to delete
+     * @returns This transaction instance for method chaining
+     *
+     * @example
+     * ```js
+     * tr.delete('node_123');
+     * ```
+     */
+    delete(id) {
+        const previous_value = this.get(id);
+        if (!previous_value) {
+            console.warn(`Deletion of node ${id} skipped, as it does not exist.`);
+            return this;
+        }
+        // Get nodes referenced by this node BEFORE deleting it.
+        const referenced_nodes = this.get_referenced_nodes(id);
+        const op = ['delete', id];
+        this.ops.push(op);
+        this.inverse_ops.push(['create', previous_value]);
+        this._apply_op(op);
+        this._track_node_id(this.deleted_node_ids, id);
+        // Cascade delete any nodes that are now orphaned after removing this node
+        this._cascade_delete_unreferenced_nodes(referenced_nodes);
+        return this;
+    }
+    /**
+     * Sets the document selection.
+     *
+     * @param selection - The new selection object
+     * @returns This transaction instance for method chaining
+     * @throws {Error} Throws if the selection is invalid or out of bounds
+     */
+    set_selection(selection) {
+        this._validate_selection(selection);
+        this.selection = selection;
+        return this;
+    }
+    /**
+     * Validates a selection against the current document state.
+     *
+     * @throws {Error} Throws if the selection is invalid
+     */
+    _validate_selection(selection) {
+        validate_selection(selection, this);
+    }
+    /**
+     * Toggles a mark on the current text or node selection.
+     *
+     * Marks are mutually exclusive. Whole marks are toggled, removed, or
+     * switched; ranges are never truncated or expanded by this command.
+     *
+     * @param mark_type - The type of mark (e.g., 'link', 'strong', 'emphasis')
+     * @param mark_properties - Additional data for the mark (e.g., href for links)
+     * @returns This transaction instance for method chaining
+     *
+     * @example
+     * ```js
+     * // Add a link mark
+     * tr.toggle_mark('link', { href: 'https://example.com' });
+     *
+     * // Add emphasis
+     * tr.toggle_mark('emphasis', {});
+     * ```
+     */
+    toggle_mark(mark_type, mark_properties) {
+        if (this.selection.type !== 'text' && this.selection.type !== 'node')
+            return this;
+        if (this.selection.type === 'node' && is_selection_collapsed(this.selection))
+            return this;
+        if (!this.available_mark_types.includes(mark_type)) {
+            console.warn(`Mark type ${mark_type} is not allowed here.`);
+            return this;
+        }
+        const range = get_selection_range(this.selection);
+        if (!range)
+            return this;
+        const annotated_value = structuredClone($state.snapshot(this.get(this.selection.path)));
+        // All marks compete for toggling, since marks are mutually exclusive.
+        // Annotations never block a mark toggle.
+        const selected_marks = this.selected_marks;
+        const selected_mark_types = get_selected_range_types(selected_marks);
+        if (selected_mark_types.size > 1)
+            return this;
+        if (selected_marks.length === 0) {
+            if (is_selection_collapsed(this.selection)) {
+                return this;
+            }
+            const new_mark_node = {
+                id: this.generate_id(),
+                type: mark_type,
+                ...mark_properties
+            };
+            this.create(new_mark_node);
+            // If there's no existing mark, add the new one
+            annotated_value.marks.push({
+                start_offset: range.start_offset,
+                end_offset: range.end_offset,
+                node_id: new_mark_node.id
+            });
+            this.set(this.selection.path, annotated_value);
+            return this;
+        }
+        const first_selected_mark = selected_marks[0];
+        const selected_mark_type = first_selected_mark.node.type;
+        if (selected_mark_type === mark_type) {
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity
+            const selected_indices = new Set(selected_marks.map(({ index }) => index));
+            const removed_node_ids = selected_marks.map(({ node_id }) => node_id);
+            annotated_value.marks = annotated_value.marks.filter((_, index) => !selected_indices.has(index));
+            this.set(this.selection.path, annotated_value);
+            this._cascade_delete_unreferenced_nodes(removed_node_ids);
+            return this;
+        }
+        if (selected_marks.length === 1 &&
+            can_switch_mark_type(this.schema, selected_mark_type, mark_type)) {
+            const selected_mark = first_selected_mark;
+            this.set([selected_mark.node_id, 'type'], mark_type);
+            this.set_selection({
+                type: this.selection.type,
+                path: this.selection.path,
+                anchor_offset: selected_mark.start_offset,
+                focus_offset: selected_mark.end_offset
+            });
+            return this;
+        }
+        return this;
+    }
+    /**
+     * Toggles an annotation on the current text or node selection.
+     *
+     * Annotations only compete with touched annotations of the same type:
+     * touched same-type annotations are removed, otherwise a new annotation is
+     * created. Marks and other annotation types never block a toggle, and
+     * same-type annotations may still overlap when created through lower-level
+     * APIs.
+     *
+     * @param annotation_type - The type of annotation (e.g., 'comment', 'marker')
+     * @param annotation_properties - Additional data for the annotation
+     * @returns This transaction instance for method chaining
+     *
+     * @example
+     * ```js
+     * // Add a comment annotation
+     * tr.toggle_annotation('comment', { text: 'Please review' });
+     * ```
+     */
+    toggle_annotation(annotation_type, annotation_properties) {
+        if (this.selection.type !== 'text' && this.selection.type !== 'node')
+            return this;
+        if (this.selection.type === 'node' && is_selection_collapsed(this.selection))
+            return this;
+        if (!this.available_annotation_types.includes(annotation_type)) {
+            console.warn(`Annotation type ${annotation_type} is not allowed here.`);
+            return this;
+        }
+        const range = get_selection_range(this.selection);
+        if (!range)
+            return this;
+        const annotated_value = structuredClone($state.snapshot(this.get(this.selection.path)));
+        // Only touched annotations of the same type compete
+        const selected_annotations = this.selected_annotations.filter(({ node }) => node?.type === annotation_type);
+        if (selected_annotations.length === 0) {
+            if (is_selection_collapsed(this.selection)) {
+                return this;
+            }
+            const new_annotation_node = {
+                id: this.generate_id(),
+                type: annotation_type,
+                ...annotation_properties
+            };
+            this.create(new_annotation_node);
+            annotated_value.annotations.push({
+                start_offset: range.start_offset,
+                end_offset: range.end_offset,
+                node_id: new_annotation_node.id
+            });
+            this.set(this.selection.path, annotated_value);
+            return this;
+        }
+        // Remove touched same-type annotations
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const selected_indices = new Set(selected_annotations.map(({ index }) => index));
+        const removed_node_ids = selected_annotations.map(({ node_id }) => node_id);
+        annotated_value.annotations = annotated_value.annotations.filter((_, index) => !selected_indices.has(index));
+        this.set(this.selection.path, annotated_value);
+        this._cascade_delete_unreferenced_nodes(removed_node_ids);
+        return this;
+    }
+    /**
+     * Deletes the currently selected text, node, or property.
+     *
+     * Behavior depends on selection type:
+     * - For node selections: Removes selected nodes and cascades deletion of unreferenced nodes
+     * - For text selections: Removes selected text and adjusts annotations accordingly
+     * - For collapsed selections: Deletes the previous character/node (backward) or next character/node (forward)
+     * - For property selections: Delegates to the config's handle_property_deletion hook
+     *
+     * @param direction - Direction of deletion for collapsed selections
+     * @returns This transaction instance for method chaining
+     */
+    delete_selection(direction = 'backward') {
+        if (!this.selection)
+            return this;
+        if (this.selection.type === 'property') {
+            this.config.handle_property_deletion?.(this, this.selection.path);
+            return this;
+        }
+        const path = this.selection.path;
+        // Get the start and end indices for the selection
+        let start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+        let end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+        let length = 0;
+        if (this.selection?.type === 'text') {
+            const text_content = this.get(this.selection.path).content;
+            length = get_char_length(text_content);
+        }
+        else if (this.selection?.type === 'node') {
+            const node_array = this.get(this.selection.path);
+            length = node_array.nodes.length;
+        }
+        // If selection is collapsed we delete the previous char/node (backward)
+        // or the next char/node (forward)
+        if (start === end) {
+            if (direction === 'backward' && start > 0) {
+                start = start - 1;
+            }
+            else if (direction === 'forward' && end < length) {
+                end = end + 1;
+            }
+            else if (direction === 'backward' && start === 0) {
+                join_text_node(this);
+                return this;
+            }
+            else if (direction === 'forward' && end === length) {
+                // At end of text - try to join with next text node
+                const node_index = this.selection.path.at(-2);
+                const successor_node = this.get([...this.selection.path.slice(0, -2), node_index + 1]);
+                // Check if next node is a text node
+                if (successor_node && this.kind(successor_node) === 'text') {
+                    // Set selection to beginning of next text node
+                    this.set_selection({
+                        type: 'text',
+                        path: [...this.selection.path.slice(0, -2), node_index + 1, 'content'],
+                        anchor_offset: 0,
+                        focus_offset: 0
+                    });
+                    // Use join_text_node to merge with previous node
+                    join_text_node(this);
+                }
+                return this;
+            }
+        }
+        if (this.selection.type === 'node') {
+            const current_value = structuredClone($state.snapshot(this.get(path)));
+            const node_array = [...current_value.nodes];
+            const deletion_length = end - start;
+            // Remove the selected nodes from the node_array
+            node_array.splice(start, deletion_length);
+            const marks_result = adjust_ranges_for_deletion(current_value.marks, start, end);
+            const annotations_result = adjust_ranges_for_deletion(current_value.annotations, start, end);
+            // Update the node_array in the entry (this implicitly records an op via this.set)
+            // Note: this.set() will automatically cascade delete unreferenced nodes
+            this.set(path, {
+                nodes: node_array,
+                marks: marks_result.ranges,
+                annotations: annotations_result.ranges
+            });
+            this._cascade_delete_unreferenced_nodes([
+                ...marks_result.removed_node_ids,
+                ...annotations_result.removed_node_ids
+            ]);
+            // Update the selection to point to the start of the deleted range
+            this.selection = {
+                type: 'node',
+                path,
+                anchor_offset: start,
+                focus_offset: start
+            };
+        }
+        else if (this.selection.type === 'text') {
+            const path = this.selection.path;
+            const text = structuredClone($state.snapshot(this.get(path)));
+            // Update the text content using character-based operations
+            const original_text = text.content;
+            text.content =
+                char_slice(original_text, 0, start) +
+                    char_slice(original_text, end, get_char_length(original_text));
+            const marks_result = adjust_ranges_for_deletion(text.marks, start, end);
+            const annotations_result = adjust_ranges_for_deletion(text.annotations, start, end);
+            text.marks = marks_result.ranges;
+            text.annotations = annotations_result.ranges;
+            this.set(path, text);
+            // Delete removed mark/annotation nodes only if no other references remain.
+            this._cascade_delete_unreferenced_nodes([
+                ...marks_result.removed_node_ids,
+                ...annotations_result.removed_node_ids
+            ]);
+            // Update the selection to the new caret position
+            this.selection = {
+                type: 'text',
+                path,
+                anchor_offset: start,
+                focus_offset: start
+            };
+        }
+        return this;
+    }
+    /**
+     * Inserts nodes at the current node selection position.
+     *
+     * If the selection is expanded (not collapsed), first deletes the selected nodes
+     * before inserting the new ones.
+     *
+     * @param node_ids - Array of node IDs to insert
+     * @param marks - Selection-relative marks to restore
+     * @param annotations - Selection-relative annotations to restore
+     * @param nodes - Node graph for restored marks and annotations
+     * @returns This transaction instance for method chaining
+     */
+    insert_nodes(node_ids, marks = [], annotations = [], nodes = {}) {
+        if (this.selection.type !== 'node')
+            return this;
+        // Unless caret is collapsed, delete the selected nodes as a first step
+        if (this.selection.anchor_offset !== this.selection.focus_offset) {
+            this.delete_selection();
+        }
+        const path = this.selection.path;
+        const current_value = structuredClone($state.snapshot(this.get(path)));
+        const node_array = [...current_value.nodes];
+        const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+        let next_marks = adjust_ranges_for_insertion(current_value.marks, start, node_ids.length);
+        let next_annotations = adjust_ranges_for_insertion(current_value.annotations, start, node_ids.length);
+        // Insert the new nodes
+        node_array.splice(start, 0, ...node_ids);
+        this.selection = {
+            type: 'node',
+            path: [...this.selection.path],
+            anchor_offset: start,
+            focus_offset: start + node_ids.length
+        };
+        const property_definition = this.inspect(path);
+        // Restore marks only when they stay mutually exclusive
+        if (!this.active_mark && marks.length > 0 && are_ranges_exclusive(marks, node_ids.length)) {
+            const restored_marks = marks
+                .map((mark) => {
+                const mark_node = nodes[mark.node_id];
+                if (!property_definition.mark_types?.includes(mark_node?.type))
+                    return null;
+                const new_mark_node_id = this.build(mark.node_id, nodes);
+                return {
+                    start_offset: start + mark.start_offset,
+                    end_offset: start + mark.end_offset,
+                    node_id: new_mark_node_id
+                };
+            })
+                .filter((mark) => mark !== null);
+            const combined_marks = next_marks.concat(restored_marks);
+            if (are_ranges_exclusive(combined_marks)) {
+                next_marks = combined_marks;
+            }
+            else {
+                for (const mark of restored_marks) {
+                    this.delete(mark.node_id);
+                }
+            }
+        }
+        // Restore annotations; overlap is allowed
+        const restored_annotations = annotations
+            .map((annotation) => {
+            if (!is_range_within_bounds(annotation, node_ids.length))
+                return null;
+            const annotation_node = nodes[annotation.node_id];
+            if (!property_definition.annotation_types?.includes(annotation_node?.type))
+                return null;
+            const new_annotation_node_id = this.build(annotation.node_id, nodes);
+            return {
+                start_offset: start + annotation.start_offset,
+                end_offset: start + annotation.end_offset,
+                node_id: new_annotation_node_id
+            };
+        })
+            .filter((annotation) => annotation !== null);
+        next_annotations = next_annotations.concat(restored_annotations);
+        this.set(path, { nodes: node_array, marks: next_marks, annotations: next_annotations });
+        return this;
+    }
+    /**
+     * Inserts text at the current text selection position.
+     *
+     * Handles mark and annotation adjustments when text is inserted, including:
+     * - Expanding ranges that contain the insertion point
+     * - Shifting ranges that come after the insertion point
+     * - Optionally applying new marks and annotations to the inserted text
+     *
+     * @param replaced_text - The text to insert
+     * @param marks - Optional marks to apply to the inserted text
+     * @param annotations - Optional annotations to apply to the inserted text
+     * @param nodes - Optional node definitions for mark and annotation nodes
+     * @returns This transaction instance for method chaining
+     */
+    insert_text(replaced_text, marks = [], annotations = [], nodes = {}) {
+        if (this.selection?.type !== 'text')
+            return this;
+        // Unless selection is collapsed, delete the selected content
+        // NOTE: This makes sure wrapped marks and annotations are disposed correctly
+        if (!is_selection_collapsed(this.selection)) {
+            this.delete_selection();
+        }
+        const text_value = structuredClone($state.snapshot(this.get(this.selection.path)));
+        const range = get_selection_range(this.selection);
+        // Transform the plain text string using character-based operations
+        const current_text = text_value.content;
+        text_value.content =
+            char_slice(current_text, 0, range.start_offset) +
+                replaced_text +
+                char_slice(current_text, range.end_offset);
+        // Calculate the change in length
+        const delta = get_char_length(replaced_text);
+        text_value.marks = adjust_ranges_for_insertion(text_value.marks, range.start_offset, delta);
+        text_value.annotations = adjust_ranges_for_insertion(text_value.annotations, range.start_offset, delta);
+        this.set(this.selection.path, text_value); // this will update the current state and create a history entry
+        // Setting the selection automatically triggers a re-render of the corresponding DOMSelection.
+        const new_selection = {
+            type: 'text',
+            path: this.selection.path,
+            anchor_offset: range.start_offset + get_char_length(replaced_text),
+            focus_offset: range.start_offset + get_char_length(replaced_text)
+        };
+        this.selection = new_selection;
+        const text_property_definition = this.inspect(this.selection.path);
+        const next_text = structuredClone(text_value);
+        let text_changed = false;
+        // Now we apply marks if there are any, but only if there's no active mark
+        // at the current collapsed caret
+        if (!this.active_mark && marks.length > 0 && are_ranges_exclusive(marks, delta)) {
+            const restored_marks = marks
+                .map((mark) => {
+                const original_mark_node = nodes[mark.node_id];
+                if (text_property_definition.mark_types?.includes(original_mark_node?.type)) {
+                    const new_mark_node_id = this.build(mark.node_id, nodes);
+                    return {
+                        start_offset: range.start_offset + mark.start_offset,
+                        end_offset: range.start_offset + mark.end_offset,
+                        node_id: new_mark_node_id
+                    };
+                }
+                return null;
+            })
+                .filter((mark) => mark !== null);
+            const combined_marks = text_value.marks.concat(restored_marks);
+            if (are_ranges_exclusive(combined_marks)) {
+                next_text.marks = combined_marks;
+                text_changed = true;
+            }
+            else {
+                for (const mark of restored_marks) {
+                    this.delete(mark.node_id);
+                }
+            }
+        }
+        // Apply annotations to the inserted text; overlap is allowed
+        if (annotations.length > 0) {
+            const restored_annotations = annotations
+                .map((annotation) => {
+                if (!is_range_within_bounds(annotation, delta))
+                    return null;
+                const original_annotation_node = nodes[annotation.node_id];
+                if (text_property_definition.annotation_types?.includes(original_annotation_node?.type)) {
+                    const new_annotation_node_id = this.build(annotation.node_id, nodes);
+                    return {
+                        start_offset: range.start_offset + annotation.start_offset,
+                        end_offset: range.start_offset + annotation.end_offset,
+                        node_id: new_annotation_node_id
+                    };
+                }
+                return null;
+            })
+                .filter((annotation) => annotation !== null);
+            if (restored_annotations.length > 0) {
+                next_text.annotations = text_value.annotations.concat(restored_annotations);
+                text_changed = true;
+            }
+        }
+        if (text_changed) {
+            this.set(this.selection.path, next_text);
+        }
+        return this;
+    }
+    /**
+     * Recursively deletes nodes that are no longer referenced in the document.
+     *
+     * This handles the cascade deletion of child nodes when their parent
+     * references are removed. Uses reference counting to determine which
+     * nodes are safe to delete.
+     *
+     * @param potentially_orphaned_nodes - Array of node IDs to check
+     */
+    _cascade_delete_unreferenced_nodes(potentially_orphaned_nodes) {
+        if (potentially_orphaned_nodes.length === 0)
+            return;
+        // Build reference counts in ONE full-document scan, then maintain them
+        // incrementally: marking a node deleted decrements the counts of every
+        // node it references (per occurrence). This replaces the previous
+        // per-candidate full-document re-scan, which made deleting M nodes
+        // O(M·N) instead of O(N + M).
+        const ref_counts = build_reference_counts(this.schema, this.doc);
+        const nodes_to_delete = {};
+        const to_check = [...potentially_orphaned_nodes];
+        while (to_check.length > 0) {
+            const node_id = to_check.pop();
+            if (!node_id || nodes_to_delete[node_id])
+                continue;
+            if ((ref_counts.get(node_id) || 0) === 0) {
+                // No more references, safe to delete this node
+                nodes_to_delete[node_id] = true;
+                // Release this node's outgoing references and re-check the
+                // nodes it pointed at — they may have become unreferenced.
+                const node = this.doc.nodes[node_id];
+                if (node) {
+                    visit_node_references(this.schema, node, (referenced_id) => {
+                        const count = ref_counts.get(referenced_id);
+                        if (count !== undefined)
+                            ref_counts.set(referenced_id, count - 1);
+                        to_check.push(referenced_id);
+                    });
+                }
+            }
+        }
+        // Now perform the actual deletions
+        for (const node_id of Object.keys(nodes_to_delete)) {
+            const previous_value = this.get([node_id]);
+            if (previous_value) {
+                const op = ['delete', node_id];
+                this.ops.push(op);
+                this.inverse_ops.push(['create', previous_value]);
+                this._apply_op(op);
+                this._track_node_id(this.deleted_node_ids, node_id);
+            }
+        }
+    }
 }