svedit 0.11.0 → 0.12.0

package/src/lib/doc_utils.js

@@ -4,7 +4,7 @@
  * These functions operate on the core document state (schema, doc, selection, config)
  * without any history management or transaction tracking.
  *
- * @import { NodeId, DocumentPath, PrimitiveType, NodeProperty, NodeArrayProperty, NodeSchema, DocumentSchema, Selection, Annotation, Document, AnnotatedTextProperty, AnnotatedText, ValidateDocumentSchema } from './types'
+ * @import { NodeId, DocumentPath, PrimitiveType, NodeProperty, NodeArrayProperty, NodeSchema, DocumentSchema, Selection, Attachment, Mark, Annotation, Document, TextProperty, AnnotatedText, ValidateDocumentSchema } from './types'
  */
 
 import {
@@ -12,7 +12,8 @@ import {
 	is_path_string_segment_valid,
 	get_selection_range,
 	get_char_length,
-	serialize_path
+	serialize_path,
+	are_ranges_exclusive
 } from './utils.js';
 
 /**
@@ -39,7 +40,7 @@ export function is_primitive_type(type) {
 		'boolean',
 		'integer',
 		'datetime',
-		'annotated_text',
+		'text',
 		'string_array',
 		'number_array',
 		'boolean_array',
@@ -74,8 +75,8 @@ export function get_property_default(property_definition) {
 	if (property_definition.type === 'integer') return 0;
 	if (property_definition.type === 'number') return 0;
 	if (property_definition.type === 'boolean') return false;
-	if (property_definition.type === 'annotated_text') return { text: '', annotations: [] };
-	if (property_definition.type === 'node_array') return [];
+	if (property_definition.type === 'text') return { content: '', marks: [], annotations: [] };
+	if (property_definition.type === 'node_array') return { nodes: [], marks: [], annotations: [] };
 	if (
 		property_definition.type === 'string_array' ||
 		property_definition.type === 'number_array' ||
@@ -161,6 +162,42 @@ export function validate_document_schema(document_schema) {
 					);
 				}
 			}
+			if (prop_def.type === 'text' || prop_def.type === 'node_array') {
+				// mark_types must reference kind 'mark', annotation_types kind 'annotation'
+				for (const [key, expected_kind] of [
+					['mark_types', 'mark'],
+					['annotation_types', 'annotation']
+				]) {
+					const invalid_types = (prop_def[key] ?? []).filter(
+						(ref_type) => document_schema[ref_type]?.kind !== expected_kind
+					);
+					if (invalid_types.length > 0) {
+						throw new Error(
+							`Node type "${node_type}" property "${prop_name}" ${key} must reference node types of kind '${expected_kind}', got: ${invalid_types.join(', ')}.`
+						);
+					}
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Validate that no annotation node type has a registered component.
+ *
+ * Marks render in-place via components; annotations are data-only overlay
+ * ranges that must be interpreted by the app (via CSS classes or props).
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {any} config - The Svedit config
+ * @throws {Error} Throws if a kind 'annotation' type has a registered component
+ */
+export function validate_config_components(schema, config) {
+	for (const [node_type, node_schema] of Object.entries(schema)) {
+		if (node_schema.kind === 'annotation' && config?.node_components?.[node_type]) {
+			throw new Error(
+				`Annotation type "${node_type}" must not have a registered component. Annotations are data-only; use kind 'mark' for in-place rendered ranges.`
+			);
 		}
 	}
 }
@@ -183,11 +220,12 @@ function validate_primitive_value(type, value) {
 			return Number.isInteger(value);
 		case 'datetime':
 			return typeof value === 'string' && !isNaN(Date.parse(value));
-		case 'annotated_text':
+		case 'text':
 			return (
 				typeof value === 'object' &&
 				value !== null &&
-				typeof value.text === 'string' &&
+				typeof value.content === 'string' &&
+				Array.isArray(value.marks) &&
 				Array.isArray(value.annotations)
 			);
 		case 'string_array':
@@ -204,79 +242,153 @@ function validate_primitive_value(type, value) {
 }
 
 /**
- * Validate annotated text annotations for bounds, references, allowed types, and exclusivity.
+ * Validate ranges (marks or annotations) for bounds, references, and allowed types.
  *
  * @param {string} node_id - Owner node id, used for error messages
  * @param {string} prop_name - Owner property name, used for error messages
- * @param {AnnotatedText} value - Annotated text value to validate
- * @param {AnnotatedTextProperty} prop_def - Annotated text property definition
+ * @param {'mark' | 'annotation'} label - Range label, used for error messages
+ * @param {Array<Attachment>} ranges - Ranges to validate
+ * @param {number} container_length - Length of the annotated text or node array
+ * @param {Array<string> | null | undefined} allowed_types - Allowed node types
  * @param {Record<string, any>} all_nodes - All document nodes
  * @param {boolean} require_references - Whether referenced nodes must already exist
- * @throws {Error} Throws if annotations are invalid
+ * @throws {Error} Throws if ranges are invalid
  */
-function validate_annotated_text_property(node_id, prop_name, value, prop_def, all_nodes, require_references) {
-	const char_length = get_char_length(value.text);
-	const annotations = value.annotations;
-
-	for (const [index, annotation] of annotations.entries()) {
+function validate_range_array(
+	node_id,
+	prop_name,
+	label,
+	ranges,
+	container_length,
+	allowed_types,
+	all_nodes,
+	require_references
+) {
+	for (const [index, range] of ranges.entries()) {
 		if (
-			typeof annotation !== 'object' ||
-			annotation === null ||
-			!Number.isInteger(annotation.start_offset) ||
-			!Number.isInteger(annotation.end_offset) ||
-			!is_id_valid(annotation.node_id)
+			typeof range !== 'object' ||
+			range === null ||
+			!Number.isInteger(range.start_offset) ||
+			!Number.isInteger(range.end_offset) ||
+			!is_id_valid(range.node_id)
 		) {
 			throw new Error(
-				`Node ${node_id} property ${prop_name} has an invalid annotation at index ${index}. Annotations must have integer start_offset/end_offset and a valid node_id.`
+				`Node ${node_id} property ${prop_name} has an invalid ${label} at index ${index}. Ranges must have integer start_offset/end_offset and a valid node_id.`
 			);
 		}
 
-		if (annotation.start_offset < 0 || annotation.end_offset > char_length) {
+		if (range.start_offset < 0 || range.end_offset > container_length) {
 			throw new Error(
-				`Node ${node_id} property ${prop_name} annotation ${annotation.node_id} is out of bounds: ${annotation.start_offset}-${annotation.end_offset}, text length is ${char_length}.`
+				`Node ${node_id} property ${prop_name} ${label} ${range.node_id} is out of bounds: ${range.start_offset}-${range.end_offset}, container length is ${container_length}.`
 			);
 		}
 
-		if (annotation.start_offset >= annotation.end_offset) {
+		if (range.start_offset >= range.end_offset) {
 			throw new Error(
-				`Node ${node_id} property ${prop_name} annotation ${annotation.node_id} must not be empty or reversed: ${annotation.start_offset}-${annotation.end_offset}.`
+				`Node ${node_id} property ${prop_name} ${label} ${range.node_id} must not be empty or reversed: ${range.start_offset}-${range.end_offset}.`
 			);
 		}
 
-		const referenced_node = all_nodes[annotation.node_id];
+		const referenced_node = all_nodes[range.node_id];
 		if (!referenced_node) {
 			if (require_references) {
 				throw new Error(
-					`Node ${node_id} property ${prop_name} annotation references missing node ${annotation.node_id}.`
+					`Node ${node_id} property ${prop_name} ${label} references missing node ${range.node_id}.`
 				);
 			}
 			continue;
 		}
 
-		if (prop_def.node_types?.length && !prop_def.node_types.includes(referenced_node.type)) {
+		if (allowed_types?.length && !allowed_types.includes(referenced_node.type)) {
 			throw new Error(
-				`Node ${node_id} property ${prop_name} annotation references node ${annotation.node_id} of type ${referenced_node.type}, but only types [${prop_def.node_types.join(', ')}] are allowed.`
+				`Node ${node_id} property ${prop_name} ${label} references node ${range.node_id} of type ${referenced_node.type}, but only types [${allowed_types.join(', ')}] are allowed.`
 			);
 		}
 	}
+}
 
-	const sorted_annotations = annotations
-		.map((annotation, index) => ({ annotation, index }))
-		.sort((a, b) =>
-			a.annotation.start_offset - b.annotation.start_offset ||
-			a.annotation.end_offset - b.annotation.end_offset
+/**
+ * Validate marks and annotations of an annotated container (text or node array).
+ *
+ * Marks must be mutually exclusive; annotations may overlap.
+ *
+ * @param {string} node_id - Owner node id, used for error messages
+ * @param {string} prop_name - Owner property name, used for error messages
+ * @param {{ marks: Array<Mark>, annotations: Array<Annotation> }} value - Annotated value to validate
+ * @param {{ mark_types?: string[], annotation_types?: string[] }} prop_def - Property definition
+ * @param {number} container_length - Length of the annotated text or node array
+ * @param {Record<string, any>} all_nodes - All document nodes
+ * @param {boolean} require_references - Whether referenced nodes must already exist
+ * @throws {Error} Throws if marks or annotations are invalid
+ */
+function validate_marks_and_annotations(
+	node_id,
+	prop_name,
+	value,
+	prop_def,
+	container_length,
+	all_nodes,
+	require_references
+) {
+	validate_range_array(
+		node_id,
+		prop_name,
+		'mark',
+		value.marks,
+		container_length,
+		prop_def.mark_types,
+		all_nodes,
+		require_references
+	);
+
+	if (!are_ranges_exclusive(value.marks, container_length)) {
+		throw new Error(
+			`Node ${node_id} property ${prop_name} has overlapping marks. Marks must be mutually exclusive.`
 		);
+	}
 
-	for (let index = 1; index < sorted_annotations.length; index++) {
-		const previous = sorted_annotations[index - 1];
-		const current = sorted_annotations[index];
+	validate_range_array(
+		node_id,
+		prop_name,
+		'annotation',
+		value.annotations,
+		container_length,
+		prop_def.annotation_types,
+		all_nodes,
+		require_references
+	);
+}
 
-		if (current.annotation.start_offset < previous.annotation.end_offset) {
-			throw new Error(
-				`Node ${node_id} property ${prop_name} has overlapping annotations: annotation index ${previous.index} (${previous.annotation.node_id}, ${previous.annotation.start_offset}-${previous.annotation.end_offset}) overlaps annotation index ${current.index} (${current.annotation.node_id}, ${current.annotation.start_offset}-${current.annotation.end_offset}). Annotations must be exclusive.`
-			);
-		}
-	}
+/**
+ * Validate text property marks and annotations for bounds, references, allowed
+ * types, and mark exclusivity.
+ *
+ * @param {string} node_id - Owner node id, used for error messages
+ * @param {string} prop_name - Owner property name, used for error messages
+ * @param {AnnotatedText} value - Annotated text value to validate
+ * @param {TextProperty} prop_def - Text property definition
+ * @param {Record<string, any>} all_nodes - All document nodes
+ * @param {boolean} require_references - Whether referenced nodes must already exist
+ * @throws {Error} Throws if marks or annotations are invalid
+ */
+function validate_text_property(
+	node_id,
+	prop_name,
+	value,
+	prop_def,
+	all_nodes,
+	require_references
+) {
+	const char_length = get_char_length(value.content);
+	validate_marks_and_annotations(
+		node_id,
+		prop_name,
+		value,
+		prop_def,
+		char_length,
+		all_nodes,
+		require_references
+	);
 }
 
 /**
@@ -318,12 +430,12 @@ export function validate_node(node, schema, all_nodes = {}, options = {}) {
 				);
 			}
 		}
-		if (prop_def.type === 'annotated_text') {
-			validate_annotated_text_property(
+		if (prop_def.type === 'text') {
+			validate_text_property(
 				node.id,
 				prop_name,
 				value,
-				/** @type {AnnotatedTextProperty} */ (prop_def),
+				/** @type {TextProperty} */ (prop_def),
 				all_nodes,
 				require_references
 			);
@@ -354,15 +466,27 @@ export function validate_node(node, schema, all_nodes = {}, options = {}) {
 		// Check node arrays
 		else if (prop_def.type === 'node_array') {
 			if (
-				!Array.isArray(value) ||
-				!value.every((id) => typeof id === 'string' && is_id_valid(id))
+				!value ||
+				typeof value !== 'object' ||
+				!Array.isArray(value.nodes) ||
+				!Array.isArray(value.marks) ||
+				!Array.isArray(value.annotations)
 			) {
 				throw new Error(
-					`Node ${node.id} has an invalid property: ${prop_name} must be an array of node ids.`
+					`Node ${node.id} has an invalid property: ${prop_name} must be an object with nodes, marks and annotations.`
+				);
+			}
+
+			const node_array_nodes = value.nodes;
+
+			if (!node_array_nodes.every((id) => typeof id === 'string' && is_id_valid(id))) {
+				throw new Error(
+					`Node ${node.id} has an invalid property: ${prop_name} must contain valid node ids.`
 				);
 			}
+
 			// Check if all referenced nodes exist and are of allowed types
-			for (const ref_id of value) {
+			for (const ref_id of node_array_nodes) {
 				const referenced_node = all_nodes[ref_id];
 				if (!referenced_node) {
 					if (require_references) {
@@ -378,6 +502,15 @@ export function validate_node(node, schema, all_nodes = {}, options = {}) {
 					);
 				}
 			}
+			validate_marks_and_annotations(
+				node.id,
+				prop_name,
+				value,
+				prop_def,
+				node_array_nodes.length,
+				all_nodes,
+				require_references
+			);
 		}
 	}
 }
@@ -393,7 +526,13 @@ export function validate_document(doc, schema) {
 	if (!is_id_valid(doc.document_id)) {
 		throw new Error(`Document ${doc.document_id} has an invalid id.`);
 	}
-	for (const node of Object.values(doc.nodes)) {
+	for (const [node_id, node] of Object.entries(doc.nodes)) {
+		if (!is_id_valid(node_id)) {
+			throw new Error(`Document node map contains an invalid id: ${node_id}.`);
+		}
+		if (node.id !== node_id) {
+			throw new Error(`Document node map key ${node_id} does not match node id ${node.id}.`);
+		}
 		validate_node(node, schema, doc.nodes);
 	}
 }
@@ -424,9 +563,9 @@ export function get(schema, doc, path) {
 			if (property_type(schema, val.type, path_segment_str) === 'node_array') {
 				val = val[path_segment];
 				val_type = 'node_array';
-			} else if (property_type(schema, val.type, path_segment_str) === 'annotated_text') {
+			} else if (property_type(schema, val.type, path_segment_str) === 'text') {
 				val = val[path_segment];
-				val_type = 'annotated_text';
+				val_type = 'text';
 			} else if (property_type(schema, val.type, path_segment_str) === 'node') {
 				val = doc.nodes[val[path_segment]];
 				val_type = 'node';
@@ -442,27 +581,48 @@ export function get(schema, doc, path) {
 				val_type = 'value';
 			}
 		} else if (val_type === 'node_array') {
+			if (path_segment === 'nodes') {
+				val = val.nodes;
+				val_type = 'node_id_array';
+			} else if (path_segment === 'marks') {
+				val = val.marks;
+				val_type = 'range_array';
+			} else if (path_segment === 'annotations') {
+				val = val.annotations;
+				val_type = 'range_array';
+			} else if (typeof path_segment === 'number' || /^\d+$/.test(String(path_segment))) {
+				val = doc.nodes[val.nodes[path_segment]];
+				val_type = 'node';
+			} else {
+				throw new Error(
+					`Invalid path segment "${path_segment}" for node_array. Use "nodes", "marks" or "annotations".`
+				);
+			}
+		} else if (val_type === 'node_id_array') {
 			val = doc.nodes[val[path_segment]];
 			val_type = 'node';
 		} else if (val_type === 'value_array') {
 			val = val[path_segment];
 			val_type = 'value';
-		} else if (val_type === 'annotated_text') {
-			if (path_segment === 'text') {
-				val = val.text;
+		} else if (val_type === 'text') {
+			if (path_segment === 'content') {
+				val = val.content;
 				val_type = 'value';
+			} else if (path_segment === 'marks') {
+				val = val.marks;
+				val_type = 'range_array';
 			} else if (path_segment === 'annotations') {
 				val = val.annotations;
-				val_type = 'annotation_array';
+				val_type = 'range_array';
 			} else {
 				throw new Error(
-					`Invalid path segment "${path_segment}" for annotated_text. Use "text" or "annotations".`
+					`Invalid path segment "${path_segment}" for text. Use "content", "marks" or "annotations".`
 				);
 			}
-		} else if (val_type === 'annotation_array') {
+		} else if (val_type === 'range_array') {
 			val = val[path_segment];
-			val_type = 'annotation';
-		} else if (val_type === 'annotation') {
+			val_type = 'range';
+		} else if (val_type === 'range') {
 			if (path_segment === 'node_id') {
 				val = doc.nodes[val.node_id];
 				val_type = 'node';
@@ -474,7 +634,7 @@ export function get(schema, doc, path) {
 				val_type = 'value';
 			} else {
 				throw new Error(
-					`Invalid path segment "${path_segment}" for annotation. Use "start_offset", "end_offset", or "node_id".`
+					`Invalid path segment "${path_segment}" for range. Use "start_offset", "end_offset", or "node_id".`
 				);
 			}
 		}
@@ -505,41 +665,16 @@ export function property_type(schema, type, property) {
 }
 
 /**
- * Determines the kind of a node ('block', 'text', or 'annotation').
+ * Determines the kind of a node ('block', 'text', 'mark', or 'annotation').
  *
  * @param {object} schema - The document schema
  * @param {any} node - The node to check
- * @returns {'block'|'text'|'annotation'} The node kind
+ * @returns {'block'|'text'|'mark'|'annotation'} The node kind
  */
 export function kind(schema, node) {
 	return schema[node.type].kind;
 }
 
-/**
- * Checks whether an annotation node can be switched to another annotation type
- * without losing data.
- *
- * @param {DocumentSchema} schema - The document schema
- * @param {any} annotation_node - The annotation node to switch
- * @param {string} target_annotation_type - The target annotation type
- * @returns {boolean} True if the annotation can be switched safely
- */
-export function can_switch_annotation_type(schema, annotation_node, target_annotation_type) {
-	if (!annotation_node || annotation_node.type === target_annotation_type) return false;
-
-	const source_schema = schema[annotation_node.type];
-	const target_schema = schema[target_annotation_type];
-	if (source_schema?.kind !== 'annotation' || target_schema?.kind !== 'annotation') return false;
-
-	const source_has_properties = Object.keys(source_schema.properties ?? {}).length > 0;
-	const target_has_properties = Object.keys(target_schema.properties ?? {}).length > 0;
-	if (source_has_properties || target_has_properties) return false;
-
-	// eslint-disable-next-line no-unused-vars
-	const { id, type, ...extra_properties } = annotation_node;
-	return Object.keys(extra_properties).length === 0;
-}
-
 /**
  * Inspects a path to get metadata about the value at that location.
  *
@@ -569,45 +704,62 @@ export function inspect(schema, doc, path) {
 }
 
 /**
- * Applies an operation to a document and returns the new document.
- * Uses copy-on-write semantics.
+ * Creates a mutable draft of a document: a new document object with a new
+ * nodes map, sharing the (immutable) node objects with the original.
  *
- * @param {Document} doc - The document to apply the operation to
+ * apply_op_to_draft mutates the draft's nodes map but copies node objects
+ * before changing them, so node identity is preserved for unchanged nodes
+ * (fine-grained rendering relies on this) and the original document is
+ * never touched.
+ *
+ * @param {Document} doc - The document to create a draft of
+ * @returns {Document} A draft document safe to mutate via apply_op_to_draft
+ */
+export function create_document_draft(doc) {
+	return {
+		...doc,
+		nodes: { ...doc.nodes }
+	};
+}
+
+/**
+ * Applies an operation to a document draft in place.
+ *
+ * The draft's nodes map is mutated, but node objects are copied on write —
+ * one nodes-map copy per draft (see create_document_draft) replaces the
+ * previous one-copy-per-op behavior, which made transactions with many ops
+ * (paste, cascade delete) O(N·ops).
+ *
+ * @param {Document} draft - A draft created via create_document_draft
  * @param {Array} op - The operation to apply [type, ...args]
- * @returns {Document} The new document with the operation applied
+ * @returns {Document} The same draft, for convenience
  */
-export function apply_op(doc, op) {
+export function apply_op_to_draft(draft, op) {
 	const [type, ...args] = op;
 	if (type === 'set') {
 		const [node_id, property] = args[0];
-		const value = structuredClone(args[1]);
-		return {
-			...doc,
-			nodes: {
-				...doc.nodes,
-				[node_id]: {
-					...doc.nodes[node_id],
-					[property]: value
-				}
-			}
+		draft.nodes[node_id] = {
+			...draft.nodes[node_id],
+			[property]: structuredClone(args[1])
 		};
 	} else if (type === 'create') {
-		return {
-			...doc,
-			nodes: {
-				...doc.nodes,
-				[args[0].id]: structuredClone(args[0])
-			}
-		};
+		draft.nodes[args[0].id] = structuredClone(args[0]);
 	} else if (type === 'delete') {
-		// eslint-disable-next-line
-		const { [args[0]]: _removed, ...remaining_nodes } = doc.nodes;
-		return {
-			...doc,
-			nodes: remaining_nodes
-		};
+		delete draft.nodes[args[0]];
 	}
-	return doc;
+	return draft;
+}
+
+/**
+ * Applies an operation to a document and returns the new document.
+ * Uses copy-on-write semantics.
+ *
+ * @param {Document} doc - The document to apply the operation to
+ * @param {Array} op - The operation to apply [type, ...args]
+ * @returns {Document} The new document with the operation applied
+ */
+export function apply_op(doc, op) {
+	return apply_op_to_draft(create_document_draft(doc), op);
 }
 
 /**
@@ -627,11 +779,17 @@ export function count_references(schema, doc, node_id) {
 
 			const prop_type = property_type(schema, node.type, property);
 
-			if (prop_type === 'node_array' && Array.isArray(value)) {
-				count += value.filter((id) => id === node_id).length;
+			if (prop_type === 'node_array') {
+				count += value.nodes.filter((id) => id === node_id).length;
 			} else if (prop_type === 'node' && value === node_id) {
 				count += 1;
 			}
+
+			if ((prop_type === 'text' || prop_type === 'node_array') && value) {
+				count += [...value.marks, ...value.annotations].filter(
+					(range) => range.node_id === node_id
+				).length;
+			}
 		}
 	}
 
@@ -639,41 +797,93 @@ export function count_references(schema, doc, node_id) {
 }
 
 /**
- * Gets the currently active annotation at the selection, optionally filtered by type.
+ * @param {DocumentSchema} schema - The document schema
+ * @param {string} from_type - Current mark type
+ * @param {string} to_type - Target mark type
+ * @returns {boolean} Whether a mark can be switched between these types
+ */
+export function can_switch_mark_type(schema, from_type, to_type) {
+	const from_schema = schema[from_type];
+	const to_schema = schema[to_type];
+	return (
+		from_schema?.kind === 'mark' &&
+		to_schema?.kind === 'mark' &&
+		Object.keys(from_schema.properties ?? {}).length === 0 &&
+		Object.keys(to_schema.properties ?? {}).length === 0
+	);
+}
+
+/**
+ * Gets ranges of the given key ('marks' or 'annotations') touched by the
+ * current selection.
  *
- * An annotation is considered "active" if it overlaps with the current selection in any way:
- * - Annotation contains the selection start
- * - Annotation contains the selection end
- * - Selection fully contains the annotation
+ * Non-collapsed selections use strict half-open range intersection, so merely
+ * adjacent boundaries do not count as touching. Collapsed text carets are only
+ * inside a range when they are strictly between start and end; a caret at
+ * either boundary is not active.
  *
  * @param {DocumentSchema} schema - The document schema
  * @param {Document} doc - The document containing nodes
- * @param {Selection} [selection] - The current selection
- * @param {string} [annotation_type] - Optional annotation type to filter by
- * @returns {Annotation | null} The active annotation, or null if none found
+ * @param {Selection | null | undefined} selection - The current selection
+ * @param {'marks' | 'annotations'} key - Which range array to inspect
+ * @returns {(Attachment & { index: number, node: any })[]} Selected attachment records
  */
-export function get_active_annotation(schema, doc, selection, annotation_type) {
-	if (selection?.type !== 'text') return null;
+function get_selected_ranges(schema, doc, selection, key) {
+	if (selection?.type !== 'text' && selection?.type !== 'node') return [];
 	const range = get_selection_range(selection);
-	if (!range) return null;
-
-	const annotated_text = get(schema, doc, selection.path);
-	const annotations = annotated_text.annotations;
-
-	const active_annotation =
-		annotations.find(
-			(/** @type {Annotation} */ { start_offset, end_offset }) =>
-				(start_offset <= range.start_offset && end_offset > range.start_offset) ||
-				(start_offset < range.end_offset && end_offset >= range.end_offset) ||
-				(start_offset >= range.start_offset && end_offset <= range.end_offset)
-		) || null;
-
-	if (annotation_type && active_annotation) {
-		const annotation_node = get(schema, doc, [active_annotation.node_id]);
-		return annotation_node?.type === annotation_type ? active_annotation : null;
-	} else {
-		return active_annotation;
-	}
+	if (!range) return [];
+
+	const annotated_prop = get(schema, doc, selection.path);
+	const ranges = annotated_prop?.[key] ?? [];
+	const is_collapsed = range.start_offset === range.end_offset;
+
+	return ranges
+		.map((/** @type {Attachment} */ attachment, index) => {
+			const node = doc.nodes[attachment.node_id];
+			return {
+				...attachment,
+				index,
+				node
+			};
+		})
+		.filter(({ start_offset, end_offset }) => {
+			if (is_collapsed) {
+				return start_offset < range.start_offset && end_offset > range.start_offset;
+			}
+			return start_offset < range.end_offset && end_offset > range.start_offset;
+		});
+}
+
+/**
+ * Gets marks touched by the current selection.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {Document} doc - The document containing nodes
+ * @param {Selection} [selection] - The current selection
+ * @returns {(Mark & { index: number, node: any })[]} Selected mark records
+ */
+export function get_selected_marks(schema, doc, selection) {
+	return get_selected_ranges(schema, doc, selection, 'marks');
+}
+
+/**
+ * Gets annotations touched by the current selection.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {Document} doc - The document containing nodes
+ * @param {Selection} [selection] - The current selection
+ * @returns {(Annotation & { index: number, node: any })[]} Selected annotation records
+ */
+export function get_selected_annotations(schema, doc, selection) {
+	return get_selected_ranges(schema, doc, selection, 'annotations');
+}
+
+/**
+ * @param {(Attachment & { index: number, node: any })[]} selected_ranges
+ * @returns {Set<string>} Node types represented in the selected ranges
+ */
+export function get_selected_range_types(selected_ranges) {
+	return new Set(selected_ranges.map(({ node }) => node?.type).filter(Boolean));
 }
 
 /**
@@ -696,13 +906,15 @@ export function count_references_excluding_deleted(schema, doc, target_node_id,
 
 			const prop_type = property_type(schema, node.type, property);
 
-			if (prop_type === 'node_array' && Array.isArray(value)) {
-				count += value.filter((id) => id === target_node_id).length;
+			if (prop_type === 'node_array') {
+				count += value.nodes.filter((id) => id === target_node_id).length;
 			} else if (prop_type === 'node' && value === target_node_id) {
 				count += 1;
-			} else if (prop_type === 'annotated_text' && value && value.annotations) {
-				count += value.annotations.filter(
-					(annotation) => annotation.node_id === target_node_id
+			}
+
+			if ((prop_type === 'text' || prop_type === 'node_array') && value) {
+				count += [...value.marks, ...value.annotations].filter(
+					(range) => range.node_id === target_node_id
 				).length;
 			}
 		}
@@ -711,6 +923,60 @@ export function count_references_excluding_deleted(schema, doc, target_node_id,
 	return count;
 }
 
+/**
+ * Iterates all node references going out of a node, invoking the visitor
+ * once per occurrence (multiplicity matters for reference counting).
+ * Covers the same reference kinds as count_references_excluding_deleted:
+ * a `node` property, `node_array` .nodes ids, and the mark/annotation
+ * node_ids carried on `text` and `node_array` properties.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {any} node - The node whose outgoing references to visit
+ * @param {(referenced_id: NodeId) => void} visit - Called per reference occurrence
+ */
+export function visit_node_references(schema, node, visit) {
+	const node_schema = schema[node.type];
+	if (!node_schema) return;
+
+	for (const [property, prop_def] of Object.entries(node_schema.properties)) {
+		const value = node[property];
+		if (value === undefined || value === null) continue;
+
+		const prop_type = prop_def.type;
+
+		if (prop_type === 'node_array') {
+			for (const id of value.nodes) visit(id);
+		} else if (prop_type === 'node' && typeof value === 'string') {
+			visit(value);
+		}
+
+		if ((prop_type === 'text' || prop_type === 'node_array') && value) {
+			for (const range of value.marks) visit(range.node_id);
+			for (const range of value.annotations) visit(range.node_id);
+		}
+	}
+}
+
+/**
+ * Builds reference counts for every referenced node in one full-document
+ * scan. Used by cascade deletion so the fixpoint can decrement counts
+ * incrementally instead of re-scanning the document per candidate node.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {Document} doc - The document containing nodes
+ * @returns {Map<NodeId, number>} Reference count per referenced node id
+ */
+export function build_reference_counts(schema, doc) {
+	/** @type {Map<NodeId, number>} */
+	const counts = new Map();
+	for (const node of Object.values(doc.nodes)) {
+		visit_node_references(schema, node, (id) => {
+			counts.set(id, (counts.get(id) || 0) + 1);
+		});
+	}
+	return counts;
+}
+
 /**
  * Gets ids of nodes that reference any of the target nodes.
  *
@@ -730,16 +996,22 @@ export function get_referencing_node_ids(schema, doc, target_node_ids) {
 
 			const prop_type = property_type(schema, node.type, property);
 
-			if (prop_type === 'node_array' && Array.isArray(value)) {
-				if (value.some((id) => target_ids.has(id))) {
+			if (prop_type === 'node_array') {
+				if (value.nodes.some((id) => target_ids.has(id))) {
 					referencing_node_ids.add(node.id);
 				}
 			} else if (prop_type === 'node' && target_ids.has(value)) {
 				referencing_node_ids.add(node.id);
-			} else if (prop_type === 'annotated_text' && value?.annotations) {
-				if (value.annotations.some((annotation) => target_ids.has(annotation.node_id))) {
-					referencing_node_ids.add(node.id);
-				}
+			}
+
+			if (
+				(prop_type === 'text' || prop_type === 'node_array') &&
+				value &&
+				[...value.marks, ...value.annotations].some((range) =>
+					target_ids.has(range.node_id)
+				)
+			) {
+				referencing_node_ids.add(node.id);
 			}
 		}
 	}
@@ -764,13 +1036,13 @@ export function validate_selection(selection, session_or_transaction) {
 	}
 
 	if (selection_type === 'node') {
-		const node_array = session_or_transaction.get(selection.path);
+		const node_array_prop = session_or_transaction.get(selection.path);
 
-		if (!Array.isArray(node_array)) {
+		if (!node_array_prop || !Array.isArray(node_array_prop.nodes)) {
 			throw new Error('Node selection path must point to a node_array');
 		}
 
-		const max_offset = node_array.length;
+		const max_offset = node_array_prop.nodes.length;
 		if (selection.anchor_offset < 0 || selection.anchor_offset > max_offset) {
 			throw new Error(
 				`Node selection anchor_offset (${selection.anchor_offset}) is out of bounds. Max is ${max_offset}.`
@@ -782,13 +1054,13 @@ export function validate_selection(selection, session_or_transaction) {
 			);
 		}
 	} else if (selection_type === 'text') {
-		const annotated_text = session_or_transaction.get(selection.path);
+		const text = session_or_transaction.get(selection.path);
 
-		if (!annotated_text || typeof annotated_text.text !== 'string') {
-			throw new Error('Text selection path must point to annotated_text');
+		if (!text || typeof text.content !== 'string') {
+			throw new Error('Text selection path must point to text');
 		}
 
-		const char_length = get_char_length(annotated_text.text);
+		const char_length = get_char_length(text.content);
 		if (selection.anchor_offset < 0 || selection.anchor_offset > char_length) {
 			throw new Error(
 				`Text selection anchor_offset (${selection.anchor_offset}) is out of bounds. Max is ${char_length}.`