svedit 0.6.4 → 0.7.1

package/src/lib/Svedit.svelte

@@ -1,11 +1,14 @@
 <script>
-	import { getContext, setContext } from 'svelte';
+	import { flushSync, getContext, setContext } from 'svelte';
 	import {
 		snake_to_pascal,
 		get_char_length,
 		utf16_to_char_offset,
 		char_to_utf16_offset
 	} from './utils.js';
+	import { create_gap_computation } from './node_gap_computation.svelte.js';
+	import DefaultNodeSelectionMarkers from './NodeSelectionMarkers.svelte';
+	import './styles/svedit-colors.css';
 
 	/** @import {
 	 *   SveditProps,
@@ -30,12 +33,15 @@
 
 	let canvas_el;
 	let root_node = $derived(session.get(path));
-	let Overlays = $derived(session.config.system_components.Overlays);
+	let Overlays = $derived(session.config.system_components?.Overlays);
+	let NodeSelectionMarkers = $derived(session.config.system_components?.NodeSelectionMarkers ?? DefaultNodeSelectionMarkers);
 	let RootComponent = $derived(session.config.node_components[snake_to_pascal(root_node.type)]);
 
 	let is_composing = $state(false);
+	let canvas_focused = $state(false);
 	let before_composition_selection = null;
 
+
 	// let is_mobile = $derived(is_mobile_browser());
 	// let is_chrome_desktop = $derived(is_chrome_desktop_browser());
 
@@ -58,10 +64,14 @@
 		get canvas_el() {
 			return canvas_el;
 		},
+		get canvas_focused() {
+			return canvas_focused;
+		},
 		focus_canvas
 	};
 
 	setContext('svedit', context);
+	create_gap_computation(context);
 
 	// Get KeyMapper from context (may be undefined if not provided)
 	const key_mapper = getContext('key_mapper');
@@ -71,16 +81,6 @@
 		session.initialize_commands(context);
 	});
 
-	// Handle focus - push session's keymap onto stack
-	function handle_canvas_focus() {
-		key_mapper?.push_scope(session.keymap);
-	}
-
-	// Handle blur - pop document's keymap from stack
-	function handle_canvas_blur() {
-		key_mapper?.pop_scope();
-	}
-
 	/**
 	 * @param {InputEvent} event
 	 */
@@ -219,7 +219,7 @@
 	function oncompositionend(event) {
 		console.log('DEBUG: oncompositionend, insert:', event.data, event);
 		if (!canvas_el?.contains(document.activeElement)) return;
-		if (canvas_el?.contains(document.activeElement) && session.selection?.type === 'text') {
+		if (session.selection?.type === 'text') {
 			// We need to remember the user's selection, as it might have changed in the process
 			// of finishing a composition. For instance, the user might have selected a different
 			// part of the text while composing.
@@ -260,6 +260,7 @@
 	// Map DOM selection to internal model
 	function onselectionchange() {
 		if (!editable) return;
+		if (!canvas_focused) return;
 		const dom_selection = window.getSelection();
 		if (!dom_selection.rangeCount) return;
 
@@ -502,7 +503,7 @@ ${fallback_html}`;
 	 * Attempts to paste JSON data as a node at the current selection.
 	 *
 	 * @param {string|object} pasted_json - The JSON data to paste, either as a string or parsed object
-	 * @param {Selection} [selection] - Optional selection (node cursor) where the payload should be pasted
+	 * @param {Selection} [selection] - Optional selection (node caret) where the payload should be pasted
 	 * @returns {boolean} True if the paste operation was successful, false otherwise
 	 */
 	function try_node_paste(pasted_json, selection) {
@@ -555,9 +556,9 @@ ${fallback_html}`;
 			return true;
 		} else {
 			if (tr.selection.path.length >= 2) {
-				const next_node_insert_cursor = session.get_next_node_insert_cursor(tr.selection);
-				if (next_node_insert_cursor) {
-					try_node_paste(pasted_json, next_node_insert_cursor);
+				const next_node_insert_caret = session.get_next_node_insert_caret(tr.selection);
+				if (next_node_insert_caret) {
+					try_node_paste(pasted_json, next_node_insert_caret);
 				}
 			}
 		}
@@ -572,15 +573,15 @@ ${fallback_html}`;
 
 		let plain_text,
 			pasted_json,
-			pasted_images = [];
+			pasted_media = [];
 
 		// NOTE: For some reason, await navigator.clipboard.read()
 		const clipboard_items = event.clipboardData?.items || [];
 		for (const item of clipboard_items || []) {
-			if (item.type.startsWith('image/')) {
+			if (item.type.startsWith('image/') || item.type.startsWith('video/') || item.type.startsWith('audio/')) {
 				const blob = item.getAsFile();
 				const data_url = URL.createObjectURL(blob);
-				pasted_images.push({
+				pasted_media.push({
 					blob,
 					data_url,
 					type: item.type,
@@ -589,11 +590,12 @@ ${fallback_html}`;
 			}
 		}
 
-		if (pasted_images.length > 0) {
-			pasted_json = await session.config.handle_image_paste(session, pasted_images);
-			console.log('pasted_json_after_image_paste', pasted_json);
+		if (pasted_media.length > 0) {
+			const handle_media_paste = session.config.handle_media_paste || session.config.handle_image_paste
+			pasted_json = await handle_media_paste(session, pasted_media);
+			console.log('pasted_json_after_media_paste', pasted_json);
 			// NOTE: If no pasted_json is returned from the custom handler, we assume that content creation has been
-			// handled inside handle_image_paste already.
+			// handled inside handle_media_paste already.
 			if (!pasted_json) return;
 		} else {
 			// First try to extract svedit data from HTML format
@@ -640,8 +642,8 @@ ${fallback_html}`;
 			}
 		}
 
-		console.log('plain_text', plain_text);
-		console.log('pasted_json', pasted_json);
+		// console.log('plain_text', plain_text);
+		// console.log('pasted_json', pasted_json);
 
 		if (pasted_json?.main_nodes && session.selection?.type === 'node') {
 			// Paste nodes at a node selection
@@ -674,15 +676,15 @@ ${fallback_html}`;
 			pasted_json?.main_nodes?.length === 1 &&
 			session.kind(pasted_json?.nodes[pasted_json.main_nodes[0]]) === 'text'
 		) {
-			// Paste a single text node, at a text cursor
+			// Paste a single text node, at a text caret
 			const text_property = pasted_json.nodes[pasted_json.main_nodes[0]].content;
 			session.apply(
 				session.tr.insert_text(text_property.text, text_property.annotations, pasted_json.nodes)
 			);
 		} else if (['text', 'property'].includes(session.selection?.type) && pasted_json?.nodes) {
-			// Paste nodes at a text or property selection by finding the next valid insert cursor
-			const next_node_insert_cursor = session.get_next_node_insert_cursor(session.selection);
-			try_node_paste(pasted_json, next_node_insert_cursor);
+			// Paste nodes at a text or property selection by finding the next valid insert caret
+			const next_node_insert_caret = session.get_next_node_insert_caret(session.selection);
+			try_node_paste(pasted_json, next_node_insert_caret);
 		} else if (typeof plain_text === 'string') {
 			// External paste: Fallback to plain text when no svedit data is found
 			session.apply(session.tr.insert_text(plain_text.trim()));
@@ -693,19 +695,19 @@ ${fallback_html}`;
 
 	function render_selection() {
 		const selection = /** @type {Selection} */ (session.selection);
-		let prev_selection =
-			__get_property_selection_from_dom() ||
-			__get_text_selection_from_dom() ||
-			__get_node_selection_from_dom();
 
 		if (!selection) {
-			// No model selection -> just leave things as they are'
+			// No model selection -> just leave things as they are
 			let dom_selection = window.getSelection();
 			dom_selection.removeAllRanges();
 			return;
 		}
 
 		// NOTE: Skip rerender only when the selection is the same and the focus is already within the canvas
+		let prev_selection =
+			__get_property_selection_from_dom() ||
+			__get_text_selection_from_dom() ||
+			__get_node_selection_from_dom();
 		if (
 			JSON.stringify(selection) === JSON.stringify(prev_selection) &&
 			canvas_el?.contains(document.activeElement)
@@ -725,9 +727,41 @@ ${fallback_html}`;
 		}
 	}
 
+	// Handle focus - push session's keymap onto stack
+	function handle_canvas_focus() {
+		// Use flushSync so highlight spans are removed from the DOM
+		// immediately, before the browser processes the click's selection.
+		flushSync(() => {
+			// Clear the model selection so render_selection() does not call
+			// setBaseAndExtent() with the old position, which would battle
+			// with the new selection the user is making (the click/drag that
+			// triggered this focus). The browser will place the caret and
+			// fire selectionchange, which sets the model selection correctly.
+			session.selection = null;
+			canvas_focused = true;
+		});
+		key_mapper?.push_scope(session.keymap);
+	}
+
+	// Handle blur - pop document's keymap from stack
+	function handle_canvas_blur() {
+		// Use flushSync so the selection highlight span (with its CSS anchor)
+		// is in the DOM immediately, before any popover/dialog tries to
+		// position itself.
+		flushSync(() => {
+			canvas_focused = false;
+		});
+		key_mapper?.pop_scope();
+	}
+
 	function focus_canvas() {
-		// We just render the selection (which will return focus to the canvas) implicitly
-		render_selection();
+		// Use flushSync so highlight spans are removed from the DOM
+		// immediately, before we focus and render_selection walks the
+		// text nodes.
+		flushSync(() => {
+			canvas_focused = true;
+		});
+		canvas_el?.focus();
 	}
 
 	/**
@@ -749,14 +783,14 @@ ${fallback_html}`;
 		if (focus_node.nodeType !== Node.ELEMENT_NODE) focus_node = focus_node.parentElement;
 		if (anchor_node.nodeType !== Node.ELEMENT_NODE) anchor_node = anchor_node.parentElement;
 
-		// EDGE CASE: Let's first check if we are in a cursor trap for node cursors
-		let after_node_cursor_trap =
-			focus_node && focus_node?.closest('[data-type="after-node-cursor-trap"]');
-		if (after_node_cursor_trap && focus_node === anchor_node) {
-			// Find the node that this cursor trap belongs to
-			let node = /** @type {HTMLElement} */ (after_node_cursor_trap.closest('[data-type="node"]'));
+		// EDGE CASE: Let's first check if we are in a node gap for node carets
+		let gap_after_el =
+			focus_node && focus_node?.closest('[data-type="gap-after"]');
+		if (gap_after_el && focus_node === anchor_node) {
+			// Find the node that this gap belongs to
+			let node = /** @type {HTMLElement} */ (gap_after_el.closest('[data-type="node"]'));
 			if (!node) {
-				console.log('No corresponding node found for after-node-cursor-trap');
+				console.log('No corresponding node found for gap-after');
 				return null;
 			}
 			const node_path = /** @type {DocumentPath} */ (node.dataset.path.split('.'));
@@ -770,11 +804,11 @@ ${fallback_html}`;
 			};
 		}
 
-		// EDGE CASE: Let's check if we are in a position-zero-cursor-trap for node_arrays.
-		let position_zero_cursor_trap = focus_node.closest('[data-type="position-zero-cursor-trap"]');
-		if (position_zero_cursor_trap && focus_node === anchor_node) {
+		// EDGE CASE: Let's check if we are in a gap-before for node_arrays.
+		let gap_before_el = focus_node.closest('[data-type="gap-before"]');
+		if (gap_before_el && focus_node === anchor_node) {
 			const node_array_el = /** @type {HTMLElement} */ (
-				position_zero_cursor_trap.closest('[data-type="node_array"]')
+				gap_before_el.closest('[data-type="node_array"]')
 			);
 			const node_array_path = node_array_el.dataset.path.split('.');
 			return {
@@ -804,22 +838,38 @@ ${fallback_html}`;
 		let focus_node_depth = focus_root_path.length;
 		let anchor_node_depth = anchor_root_path.length;
 
-		// HACK: this works only for one level nesting - should be done recursively to work generally
-		if (focus_root_path.length > anchor_root_path.length) {
-			focus_root = focus_root.parentElement.closest('[data-path][data-type="node"]');
-			if (!focus_root) return null;
-			focus_root_path = focus_root.dataset.path.split('.');
-		} else if (anchor_root_path.length > focus_root_path.length) {
-			anchor_root = anchor_root.parentElement.closest('[data-path][data-type="node"]');
-			if (!anchor_root) return null;
-			anchor_root_path = anchor_root.dataset.path.split('.');
-		}
-
-		const is_same_node_array =
-			focus_root_path.slice(0, -1).join('.') === anchor_root_path.slice(0, -1).join('.');
-		if (!is_same_node_array) {
-			console.log('invalid selection, not same node_array');
-			return null;
+		// Walk both endpoints up the DOM until they share the same parent node_array.
+		// This handles selections that span across arbitrarily nested node arrays by
+		// finding the lowest common ancestor node_array and projecting each endpoint
+		// onto its index within that array.
+		let focus_walked_up = false;
+		let anchor_walked_up = false;
+		while (
+			focus_root_path.slice(0, -1).join('.') !== anchor_root_path.slice(0, -1).join('.')
+		) {
+			if (focus_root_path.length > anchor_root_path.length) {
+				// Focus is deeper — walk it up
+				focus_root = focus_root.parentElement?.closest('[data-path][data-type="node"]');
+				if (!focus_root) return null;
+				focus_root_path = focus_root.dataset.path.split('.');
+				focus_walked_up = true;
+			} else if (anchor_root_path.length > focus_root_path.length) {
+				// Anchor is deeper — walk it up
+				anchor_root = anchor_root.parentElement?.closest('[data-path][data-type="node"]');
+				if (!anchor_root) return null;
+				anchor_root_path = anchor_root.dataset.path.split('.');
+				anchor_walked_up = true;
+			} else {
+				// Same depth but different node arrays — walk both up
+				focus_root = focus_root.parentElement?.closest('[data-path][data-type="node"]');
+				if (!focus_root) return null;
+				focus_root_path = focus_root.dataset.path.split('.');
+				focus_walked_up = true;
+				anchor_root = anchor_root.parentElement?.closest('[data-path][data-type="node"]');
+				if (!anchor_root) return null;
+				anchor_root_path = anchor_root.dataset.path.split('.');
+				anchor_walked_up = true;
+			}
 		}
 
 		let anchor_offset = parseInt(anchor_root_path.at(-1));
@@ -833,19 +883,24 @@ ${fallback_html}`;
 			focus_offset += 1;
 		}
 
-		// EDGE CASE: Exclude first node when anchor_node is an afer-node-cursor-trap
-		// in a non-collapsed forward selection
+		// EDGE CASE: Exclude first node when anchor_node is a gap-after
+		// in a non-collapsed forward selection.
+		// Only apply when anchor wasn't walked up — if it was, the gap is at a
+		// deeper nesting level and no longer relevant to the resolved node array.
 		if (
-			anchor_node.parentElement?.dataset.type === 'after-node-cursor-trap' &&
+			!anchor_walked_up &&
+			anchor_node.parentElement?.dataset.type === 'gap-after' &&
 			!is_backwards &&
 			anchor_offset !== focus_offset
 		) {
 			anchor_offset += 1;
 		}
-		// EDGE CASE: Exclude first node when focus_node is an afer-node-cursor-trap
-		// in a non-collapsed backward selection
+		// EDGE CASE: Exclude first node when focus_node is a gap-after
+		// in a non-collapsed backward selection.
+		// Only apply when focus wasn't walked up — same reasoning as above.
 		else if (
-			focus_node.parentElement?.dataset.type === 'after-node-cursor-trap' &&
+			!focus_walked_up &&
+			focus_node.parentElement?.dataset.type === 'gap-after' &&
 			is_backwards &&
 			anchor_offset !== focus_offset &&
 			// EDGE CASE: Only do correction when drag started from a deeper or equally deep anchor node
@@ -931,7 +986,7 @@ ${fallback_html}`;
 		let focus_root, anchor_root;
 
 		if (focus_node === anchor_node && focus_node.dataset?.type === 'text') {
-			// EDGE CASE 1: Either text node is empty (only a <br> is present), or cursor is after a <br> at the very end of the text node
+			// EDGE CASE 1: Either text node is empty (only a <br> is present), or caret is after a <br> at the very end of the text node
 			focus_root = anchor_root = focus_node;
 		} else {
 			focus_root = /** @type {HTMLElement} */ (
@@ -952,10 +1007,10 @@ ${fallback_html}`;
 
 		if (!path) return null;
 
-		// EDGE CASE 1B: Cursor after trailing <br> at end of text
+		// EDGE CASE 1B: Caret after trailing <br> at end of text
 		//
 		// AnnotatedTextProperty renders a trailing <br> for non-empty or non-focused text.
-		// When the user places their cursor after this <br>, focusNode is the container
+		// When the user places their caret after this <br>, focusNode is the container
 		// element (not a text node), and normal processing would return position 0.
 		// We detect this and return text_length instead.
 		const text_content = session.get(path).text;
@@ -974,7 +1029,7 @@ ${fallback_html}`;
 				last_element_index--;
 			}
 
-			// Check if cursor is at or after the trailing <br>
+			// Check if caret is at or after the trailing <br>
 			if (
 				last_element_index >= 0 &&
 				child_nodes[last_element_index].nodeName === 'BR' &&
@@ -1078,16 +1133,19 @@ ${fallback_html}`;
 		const range = window.document.createRange();
 
 		if (is_collapsed) {
-			// Cursor position in between two nodes or at the very beginning/end of a node_array
-			// IMPORTANT: We need to look for direct children of anchor_node to find the right cursor trap.
-			const cursor_trap_el = anchor_node.querySelector(
-				selection.anchor_offset === 0
-					? ':scope > .position-zero-cursor-trap'
-					: ':scope > .after-node-cursor-trap'
-			);
-
-			range.setStart(cursor_trap_el, 1);
-			range.setEnd(cursor_trap_el, 1);
+			// Caret position in between two nodes or at the very beginning/end of a node_array
+			// IMPORTANT: We need to look for direct children of anchor_node to find the right node gap.
+			const gap_selector = selection.anchor_offset === 0
+				? '.gap-before'
+				: '.gap-after';
+			// In empty arrays the node gap is a sibling of the placeholder, not a child
+			const gap_el =
+				anchor_node.querySelector(`:scope > ${gap_selector}`) ??
+				anchor_node.parentElement?.querySelector(`:scope > ${gap_selector}`);
+
+			if (!gap_el) return;
+			range.setStart(gap_el, 1);
+			range.setEnd(gap_el, 1);
 			dom_selection.removeAllRanges();
 			dom_selection.addRange(range);
 		} else {
@@ -1145,12 +1203,12 @@ ${fallback_html}`;
 		const el = canvas_el.querySelector(
 			`[data-path="${selection.path.join('.')}"][data-type="property"]`
 		);
-		const cursor_trap_selectable = el.querySelector('.svedit-selectable');
+		const gap_selectable = el.querySelector('.svedit-selectable');
 		const range = window.document.createRange();
 		const dom_selection = window.getSelection();
 
-		// Select the entire cursor trap element contents and collapse to start
-		range.selectNodeContents(cursor_trap_selectable);
+		// Select the entire gap element contents and collapse to start
+		range.selectNodeContents(gap_selectable);
 		range.collapse(true); // Collapse to start position
 		dom_selection.removeAllRanges();
 		dom_selection.addRange(range);
@@ -1233,7 +1291,7 @@ ${fallback_html}`;
 		// EDGE CASE: When text is empty, we need to set a different DOM selection
 		if (start_offset === end_offset && start_offset === 0 && empty_text) {
 			// Markup for empty text looks like this `<div data-type="text"><br></div>`.
-			// And the correct cursor position is after the <br> element.
+			// And the correct caret position is after the <br> element.
 			anchor_node = el;
 			anchor_node_offset = 1;
 			focus_node = el;
@@ -1293,7 +1351,10 @@ ${fallback_html}`;
 	}
 
 	// Whenever the model selection changes, render the selection
+	// Skip when canvas is not focused to avoid stealing focus back
+	// (e.g., when a dialog is open and selection highlight fragments re-render)
 	$effect(() => {
+		if (!canvas_focused) return;
 		render_selection();
 	});
 </script>
@@ -1306,10 +1367,13 @@ ${fallback_html}`;
 
 <!-- TODO: move oncut/copy/paste handlers inside .svedit -->
 <div class="svedit">
+	<!-- Overlays must be before canvas so they initialize first. -->
+	<NodeSelectionMarkers />
+	{#if Overlays}<Overlays />{/if}
 	<div
 		class="svedit-canvas {css_class}"
 		class:hide-selection={session.selection?.type === 'node'}
-		class:node-cursor={session.selection?.type === 'node' &&
+		class:node-caret={session.selection?.type === 'node' &&
 			session.selection.anchor_offset === session.selection.focus_offset}
 		class:property-selection={session.selection?.type === 'property'}
 		bind:this={canvas_el}
@@ -1334,21 +1398,23 @@ ${fallback_html}`;
 	>
 		<RootComponent {path} />
 	</div>
-	<Overlays />
 </div>
 
 <style>
 	.svedit-canvas {
-		--layout-orientation: vertical;
-		caret-color: var(--editing-stroke-color);
+		caret-color: var(--svedit-editing-stroke);
 		caret-shape: bar;
+		/* Default to vertical/ column flow with: --row: 0; (the most common case)
+		Prevents silent failures when developers forget to set the row property in their top level node component.
+		TODO: Warn developers in dev mode via console if they forget to set the --row property and use a different flow.*/
+		--row: 0;
 		&:focus {
 			outline: none;
 		}
 	}
 
 	.svedit-canvas :global(::selection) {
-		background: var(--editing-fill-color);
+		background: var(--svedit-editing-fill);
 	}
 
 	@media not (pointer: coarse) {
@@ -1357,8 +1423,8 @@ ${fallback_html}`;
 		}
 	}
 
-	/* When the cursor is in a cursor-trap we never want to see the caret */
-	.svedit-canvas.node-cursor,
+	/* When the caret is in a node gap we never want to see the caret */
+	.svedit-canvas.node-caret,
 	.svedit-canvas.property-selection {
 		caret-color: transparent;
 	}

package/src/lib/Transaction.svelte.js

@@ -18,7 +18,8 @@ import {
 	apply_op,
 	count_references_excluding_deleted,
 	validate_node,
-	get_active_annotation
+	get_active_annotation,
+	validate_selection
 } from './doc_utils.js';
 
 /**
@@ -145,7 +146,7 @@ export default class Transaction {
 	}
 
 	/**
-	 * Returns the annotation object that is currently "under the cursor".
+	 * 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
@@ -336,6 +337,7 @@ export default class Transaction {
 		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);
@@ -343,9 +345,7 @@ export default class Transaction {
 		this.ops.push(op);
 		this.inverse_ops.push(['create', previous_value]);
 		this._apply_op(op);
-		// Check if the nodes that were referenced by the deleted node are now orphaned
-		// NOTE: We don't do this yet, because we still have some manual child node removal code
-		// that causes errors. But we should soon implement this only here.
+		// Cascade delete any nodes that are now orphaned after removing this node
 		this._cascade_delete_unreferenced_nodes(referenced_nodes);
 		return this;
 	}
@@ -371,50 +371,7 @@ export default class Transaction {
 	 * @private
 	 */
 	_validate_selection(selection) {
-		if (!selection) return;
-
-		const selection_type = selection.type;
-		if (!['node', 'text', 'property'].includes(selection_type)) {
-			throw new Error(`Invalid selection type: ${selection_type}`);
-		}
-
-		if (selection_type === 'node') {
-			const node_array = this.get(selection.path);
-
-			if (!Array.isArray(node_array)) {
-				throw new Error('Node selection path must point to a node_array');
-			}
-
-			const max_offset = node_array.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}.`
-				);
-			}
-			if (selection.focus_offset < 0 || selection.focus_offset > max_offset) {
-				throw new Error(
-					`Node selection focus_offset (${selection.focus_offset}) is out of bounds. Max is ${max_offset}.`
-				);
-			}
-		} else if (selection_type === 'text') {
-			const annotated_text = this.get(selection.path);
-
-			if (!annotated_text || typeof annotated_text.text !== 'string') {
-				throw new Error('Text selection path must point to annotated_text');
-			}
-
-			const char_length = get_char_length(annotated_text.text);
-			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}.`
-				);
-			}
-			if (selection.focus_offset < 0 || selection.focus_offset > char_length) {
-				throw new Error(
-					`Text selection focus_offset (${selection.focus_offset}) is out of bounds. Max is ${char_length}.`
-				);
-			}
-		}
+		validate_selection(selection, this);
 	}
 
 	/**
@@ -653,7 +610,7 @@ export default class Transaction {
 	insert_nodes(node_ids) {
 		if (this.selection.type !== 'node') return this;
 
-		// Unless cursor is collapsed, delete the selected nodes as a first step
+		// Unless caret is collapsed, delete the selected nodes as a first step
 		if (this.selection.anchor_offset !== this.selection.focus_offset) {
 			this.delete_selection();
 		}
@@ -661,14 +618,7 @@ export default class Transaction {
 		const path = this.selection.path;
 		const node_array = [...this.get(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);
-
-		if (start !== end) {
-			// Remove the selected nodes from the node_array
-			node_array.splice(start, end - start);
-		}
 
 		// Insert the new nodes
 		node_array.splice(start, 0, ...node_ids);
@@ -744,16 +694,6 @@ export default class Transaction {
 					node_id
 				};
 			}
-
-			// Insertion point is inside the annotation - extend the annotation
-			if (annotation_start < range.start_offset && annotation_end > range.start_offset) {
-				return {
-					start_offset: annotation_start,
-					end_offset: annotation_end + delta,
-					node_id
-				};
-			}
-
 			return annotation;
 		});
 
@@ -771,7 +711,7 @@ export default class Transaction {
 		this.selection = new_selection;
 
 		// Now we apply annotations if there are any, but only if there's no active annotation
-		// at the current collapsed cursor
+		// at the current collapsed caret
 		if (!this.active_annotation() && annotations.length > 0) {
 			const new_annotations = annotations
 				.map((annotation) => {