svedit 0.8.0 → 0.10.0

package/src/lib/Svedit.svelte

@@ -3,16 +3,19 @@
 	import {
 		snake_to_pascal,
 		get_char_length,
-		utf16_to_char_offset,
-		char_to_utf16_offset
+		char_to_utf16_offset,
+		deserialize_path,
+		paths_equal,
+		serialize_path,
+		is_selection_collapsed
 	} from './utils.js';
-	import { create_gap_computation } from './node_gap_computation.svelte.js';
+	import { create_node_visibility } from './node_visibility.svelte.js';
 	import DefaultNodeSelectionMarkers from './NodeSelectionMarkers.svelte';
 	import './styles/svedit-colors.css';
+	import './styles/svedit-animations.css';
 
 	/** @import {
 	 *   SveditProps,
-	 *   DocumentPath,
 	 *   Selection,
 	 *   TextSelection,
 	 *   NodeSelection,
@@ -37,9 +40,14 @@
 	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;
+	// Set by onselectionchange before it commits a DOM-derived selection
+	// to the model. render_selection consumes-and-clears it to skip
+	// rerender on DOM-driven changes (the DOM is already in place).
+	let selection_source_is_dom = false;
 
 
 	// let is_mobile = $derived(is_mobile_browser());
@@ -71,7 +79,51 @@
 	};
 
 	setContext('svedit', context);
-	create_gap_computation(context);
+	create_node_visibility(context);
+
+	$effect(() => {
+		check_duplicate_paths();
+	});
+
+	function check_duplicate_paths() {
+		if (!canvas_el) return;
+
+		/** @type {Record<string, true>} */
+		const mounted_paths = Object.create(null);
+
+		for (const element of canvas_el.querySelectorAll('[data-path]')) {
+			if (element.closest('.svedit-canvas') !== canvas_el) continue;
+
+			const path_str = element.getAttribute('data-path');
+			if (!path_str) continue;
+
+			if (mounted_paths[path_str]) {
+				console.warn(
+					`[svedit] Path "${path_str}" is mounted more than once. Within a single Svedit document, each path may be mounted exactly once. To render shared content in multiple places (e.g. header + footer nav), use distinct node_arrays or separate Svedit instances.`
+				);
+			}
+
+			mounted_paths[path_str] = true;
+		}
+	}
+
+	// Test-only hook: expose the svedit context so test specs can read
+	// near_map / edge_map for diagnostics. Gated on `import.meta.env.MODE`
+	// — Vite replaces the literal so the comparison is constant-false in
+	// production and the branch is dead-code-eliminated. Wrapped in an
+	// effect so unmount clears the reference and tests don't leak state
+	// across remounts.
+	if (import.meta.env?.MODE === 'test') {
+		$effect(() => {
+			const g = /** @type {any} */ (globalThis);
+			g.__svedit_ctx_for_test = context;
+			return () => {
+				if (g.__svedit_ctx_for_test === context) {
+					delete g.__svedit_ctx_for_test;
+				}
+			};
+		});
+	}
 
 	// Get KeyMapper from context (may be undefined if not provided)
 	const key_mapper = getContext('key_mapper');
@@ -190,10 +242,9 @@
 	/**
 	 * Handles composition start events for input methods like dead keys
 	 * This occurs when user starts typing a composed character (e.g., backtick for accents)
-	 * @param {CompositionEvent} event
 	 */
-	function oncompositionstart(event) {
-		console.log('DEBUG: oncompositionstart', event.data);
+	function oncompositionstart(/*event*/) {
+		// console.log('DEBUG: oncompositionstart', event.data);
 		if (session.selection.type !== 'text') {
 			// Remove all ranges - completely clears the selection
 			window.getSelection()?.removeAllRanges();
@@ -217,7 +268,7 @@
 	 * This occurs when composition is complete (e.g., after typing 'a' following backtick to get 'à')
 	 */
 	function oncompositionend(event) {
-		console.log('DEBUG: oncompositionend, insert:', event.data, event);
+		// console.log('DEBUG: oncompositionend, insert:', event.data, event);
 		if (!canvas_el?.contains(document.activeElement)) return;
 		if (session.selection?.type === 'text') {
 			// We need to remember the user's selection, as it might have changed in the process
@@ -229,12 +280,16 @@
 			// native undo command. Then the DOM will be in sync again with the editor's internal state.
 			document.execCommand('undo', false, null);
 
+			// Firefox may not undo native composition DOM. If the composed text is
+			// still present, remove it manually before applying the Svedit transaction.
+			__remove_native_composition_text(before_composition_selection, event.data);
+
 			// Set the selection to where the user initiated the composition, make changes, and apply.
 			// NOTE: We need to check for valid selection here, as there is a rare race condition
 			// where the user had no text selection at the start of composition.
 			if (before_composition_selection) {
 				session.selection = before_composition_selection;
-				console.log('event.data', event.data);
+				// console.log('event.data', event.data);
 				const tr = session.tr;
 				tr.insert_text(event.data);
 				session.apply(tr);
@@ -261,6 +316,7 @@
 	function onselectionchange() {
 		if (!editable) return;
 		if (!canvas_focused) return;
+		if (is_composing) return;
 		const dom_selection = window.getSelection();
 		if (!dom_selection.rangeCount) return;
 
@@ -273,6 +329,7 @@
 			// structurally identical — prevents a redundant $effect cycle
 			// (render_selection → scrollIntoView) on every DOM layout change.
 			if (JSON.stringify(selection) === JSON.stringify(session.selection)) return;
+			selection_source_is_dom = true;
 			session.selection = selection;
 		}
 	}
@@ -442,25 +499,24 @@ ${fallback_html}`;
 			annotated_text = session.get_selected_annotated_text();
 			const fallback_html = `<span>${annotated_text.text}</span>`;
 
-			console.log('Text copy:', {
-				annotated_text,
-				plain_text,
-				html
-			});
+			// console.log('Text copy:', {
+			// 	annotated_text,
+			// 	plain_text,
+			// 	html
+			// });
 
 			html = create_svedit_html_format(annotated_text, fallback_html);
 		} else if (session.selection?.type === 'node') {
 			const selected_nodes = session.get_selected_nodes();
 			const { nodes, main_nodes } = prepare_copy_payload(selected_nodes);
-
 			const json_data = { nodes, main_nodes };
 
-			console.log('Node copy:', {
-				selected_nodes,
-				nodes,
-				total_nodes: Object.keys(nodes).length,
-				operation: delete_selection ? 'cut' : 'copy'
-			});
+			// console.log('Node copy:', {
+			// 	selected_nodes,
+			// 	nodes,
+			// 	total_nodes: Object.keys(nodes).length,
+			// 	operation: delete_selection ? 'cut' : 'copy'
+			// });
 
 			// Generate fallback HTML for cross-app compatibility
 			const selected_node_objects = main_nodes.map((id) => nodes[id]);
@@ -479,7 +535,6 @@ ${fallback_html}`;
 				type: property_definition.type,
 				value
 			};
-			console.log('Property copy:', json_data);
 			html = create_svedit_html_format(json_data, `<span>${value}</span>`);
 			plain_text = String(value);
 		}
@@ -488,7 +543,6 @@ ${fallback_html}`;
 		try {
 			event.clipboardData?.setData('text/plain', plain_text || '');
 			event.clipboardData?.setData('text/html', html || '');
-			console.log('Data copied to clipboard successfully');
 		} catch (err) {
 			console.error('Failed to copy data: ', err);
 		}
@@ -498,6 +552,8 @@ ${fallback_html}`;
 		}
 	}
 
+
+
 	function oncut(event) {
 		if (!editable) return;
 		oncopy(event, true);
@@ -542,9 +598,9 @@ ${fallback_html}`;
 					});
 					nodes_to_insert.push(new_node_id);
 				} else {
-					console.log(
-						`rejected ${node.type}. Only ${property_definition.node_types.join(', ')} allowed.`
-					);
+					// console.log(
+					// 	`rejected ${node.type}. Only ${property_definition.node_types.join(', ')} allowed.`
+					// );
 					rejected = true;
 					break;
 				}
@@ -597,7 +653,6 @@ ${fallback_html}`;
 		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_media_paste already.
 			if (!pasted_json) return;
@@ -608,8 +663,8 @@ ${fallback_html}`;
 				if (html_content) {
 					pasted_json = extract_svedit_data_from_html(html_content);
 				}
-			} catch (e) {
-				console.log('No HTML format available or failed to extract svedit data:', e);
+			} catch {
+				// No HTML format available or failed to extract svedit data
 				pasted_json = undefined;
 			}
 
@@ -619,13 +674,18 @@ ${fallback_html}`;
 				console.error('Failed to paste any content:', e);
 			}
 
-			// Try to contruct a node payload from plain text when applicable
+			// Try to construct a node payload from plain text when applicable
 			if (!pasted_json && typeof plain_text === 'string') {
 				const plain_text_fragments = plain_text
 					.split('\n\n')
 					.map((fragment) => fragment.trim())
 					.filter(Boolean);
-				if (plain_text_fragments.length > 1) {
+				// Also create a node payload for single paragraphs at a node gap —
+				// without this, insert_text bails out (requires text selection) and
+				// the paste is silently dropped.
+				const needs_node_payload = plain_text_fragments.length > 1
+					|| (plain_text_fragments.length === 1 && session.selection?.type === 'node');
+				if (needs_node_payload) {
 					pasted_json = {
 						main_nodes: [],
 						nodes: []
@@ -692,32 +752,36 @@ ${fallback_html}`;
 		} 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()));
-		} else {
-			console.log('Could not paste.');
 		}
 	}
 
-	function render_selection() {
+	function render_selection(dom_driven = false) {
 		const selection = /** @type {Selection} */ (session.selection);
 
 		if (!selection) {
 			// No model selection -> just leave things as they are
-			let dom_selection = window.getSelection();
-			dom_selection.removeAllRanges();
+			// NOTE: removeAllRanges() makes the document lose selection on
+			// refocus of the window, hence I disable it for now.
+			// 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)
-		) {
-			// Skip. No need to rerender.
-			return;
+		// DOM-driven updates already reflect the new selection — skip
+		// the rerender when DOM matches model. Model-driven updates
+		// (insert/undo) can have DOM matching by coincidence (Svelte
+		// reuses gap elements with shifted data-gap-offset), so for those
+		// we always rerender to scroll the cursor into view.
+		const is_empty_text_selection =
+			selection.type === 'text' && session.get(selection.path).text.length === 0;
+		if (dom_driven && !is_empty_text_selection) {
+			const prev_selection = __get_selection_from_dom();
+			if (
+				JSON.stringify(selection) === JSON.stringify(prev_selection) &&
+				canvas_el?.contains(document.activeElement)
+			) {
+				return;
+			}
 		}
 
 		if (selection?.type === 'text') {
@@ -727,7 +791,7 @@ ${fallback_html}`;
 		} else if (selection?.type === 'property') {
 			__render_property_selection();
 		} else {
-			console.log('unsupported selection', $state.snapshot(selection));
+			console.warn('unsupported selection', $state.snapshot(selection));
 		}
 	}
 
@@ -736,18 +800,12 @@ ${fallback_html}`;
 		// 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
+	// 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
@@ -777,11 +835,11 @@ ${fallback_html}`;
 	function __resolve_node_from_gap(el) {
 		const gap = /** @type {HTMLElement | null} */ (el.closest('[data-gap-array-path]'));
 		if (!gap) return null;
-		const array_path = gap.dataset.gapArrayPath;
+		const array_path = deserialize_path(gap.dataset.gapArrayPath);
 		const offset = parseInt(gap.dataset.gapOffset, 10);
 		const node_idx = offset > 0 ? offset - 1 : 0;
 		return /** @type {HTMLElement | null} */ (
-			canvas_el.querySelector(`[data-path="${array_path}.${node_idx}"][data-type="node"]`)
+			canvas_el.querySelector(`[data-path="${serialize_path([...array_path, node_idx])}"][data-type="node"]`)
 		);
 	}
 
@@ -804,13 +862,36 @@ ${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: Collapsed selection inside an empty node placeholder.
+		// Firefox can place the DOM selection on the placeholder node itself,
+		// which otherwise looks like selecting node index 0 in an empty array.
+		const focus_empty_placeholder = /** @type {HTMLElement | null} */ (
+			focus_node.closest('.empty-node-placeholder[data-path][data-type="node"]')
+		);
+		const anchor_empty_placeholder = /** @type {HTMLElement | null} */ (
+			anchor_node.closest('.empty-node-placeholder[data-path][data-type="node"]')
+		);
+		if (focus_empty_placeholder && focus_empty_placeholder === anchor_empty_placeholder) {
+			const empty_placeholder_path = deserialize_path(focus_empty_placeholder.dataset.path);
+			const array_path = empty_placeholder_path.slice(0, -1);
+			const node_array = session.get(array_path);
+			if (Array.isArray(node_array) && node_array.length === 0) {
+				return {
+					type: 'node',
+					path: array_path,
+					anchor_offset: 0,
+					focus_offset: 0
+				};
+			}
+		}
+
 		// EDGE CASE: Collapsed selection inside a node gap (gap-after or gap-before).
 		// Gaps are siblings of nodes with data-gap-array-path and data-gap-offset.
 		const gap_el = /** @type {HTMLElement | null} */ (
 			focus_node.closest('[data-gap-array-path]')
 		);
 		if (gap_el && focus_node === anchor_node) {
-			const array_path = gap_el.dataset.gapArrayPath.split('.');
+			const array_path = deserialize_path(gap_el.dataset.gapArrayPath);
 			const gap_offset = parseInt(gap_el.dataset.gapOffset, 10);
 			return {
 				type: 'node',
@@ -828,8 +909,8 @@ ${fallback_html}`;
 			?? /** @type {HTMLElement} */ (anchor_node.closest('[data-path][data-type="node"]'));
 		if (!anchor_root) return null;
 
-		let focus_root_path = focus_root.dataset.path.split('.');
-		let anchor_root_path = anchor_root.dataset.path.split('.');
+		let focus_root_path = deserialize_path(focus_root.dataset.path);
+		let anchor_root_path = deserialize_path(anchor_root.dataset.path);
 		let focus_node_depth = focus_root_path.length;
 		let anchor_node_depth = anchor_root_path.length;
 
@@ -839,30 +920,28 @@ ${fallback_html}`;
 		// 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('.')
-		) {
+		while (!paths_equal(focus_root_path.slice(0, -1), anchor_root_path.slice(0, -1))) {
 			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_root_path = deserialize_path(focus_root.dataset.path);
 				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_root_path = deserialize_path(anchor_root.dataset.path);
 				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_root_path = deserialize_path(focus_root.dataset.path);
 				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_root_path = deserialize_path(anchor_root.dataset.path);
 				anchor_walked_up = true;
 			}
 		}
@@ -871,16 +950,18 @@ ${fallback_html}`;
 		// (e.g. selecting between nav and page body). The resulting path would be empty.
 		if (anchor_root_path.length <= 1) return null;
 
-		let anchor_offset = parseInt(anchor_root_path.at(-1));
-		let focus_offset = parseInt(focus_root_path.at(-1));
+		const parent_array_path = anchor_root_path.slice(0, -1);
+		// A node selection is only valid inside a node_array property.
+		const parent_property = session.inspect(parent_array_path);
+		if (!parent_property || parent_property.type !== 'node_array') return null;
+
+		let anchor_offset = Number(anchor_root_path.at(-1));
+		let focus_offset = Number(focus_root_path.at(-1));
 
 		// Check if it's a backwards selection
 		const is_backwards = __is_dom_selection_backwards();
-		if (is_backwards) {
-			anchor_offset += 1;
-		} else {
-			focus_offset += 1;
-		}
+		if (is_backwards) anchor_offset += 1;
+		else focus_offset += 1;
 
 		// EDGE CASE: Exclude first node when anchor_node is a gap-after
 		// in a non-collapsed forward selection.
@@ -910,7 +991,7 @@ ${fallback_html}`;
 
 		return {
 			type: 'node',
-			path: anchor_root_path.slice(0, -1),
+			path: parent_array_path,
 			anchor_offset: anchor_offset,
 			focus_offset: focus_offset
 		};
@@ -939,7 +1020,7 @@ ${fallback_html}`;
 		if (focus_root === anchor_root) {
 			return {
 				type: 'property',
-				path: focus_root.dataset.path.split('.')
+				path: deserialize_path(focus_root.dataset.path)
 			};
 		}
 		return null;
@@ -982,19 +1063,30 @@ ${fallback_html}`;
 			range = dom_selection.getRangeAt(0);
 		}
 
+		function get_text_root(node) {
+			if (!node) return null;
+
+			if (node.nodeType === Node.ELEMENT_NODE) {
+				return /** @type {HTMLElement | null} */ (
+					node.closest?.('[data-path][data-type="text"]') ?? null
+				);
+			}
+
+			return /** @type {HTMLElement | null} */ (
+				node.parentElement?.closest('[data-path][data-type="text"]') ?? null
+			);
+		}
+
 		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 caret is after a <br> at the very end of the text node
 			focus_root = anchor_root = focus_node;
 		} else {
-			focus_root = /** @type {HTMLElement} */ (
-				focus_node.parentElement?.closest('[data-path][data-type="text"]')
-			);
+			focus_root = get_text_root(focus_node);
 			if (!focus_root) return null;
-			anchor_root = /** @type {HTMLElement} */ (
-				anchor_node.parentElement?.closest('[data-path][data-type="text"]')
-			);
+
+			anchor_root = get_text_root(anchor_node);
 			if (!anchor_root) return null;
 		}
 
@@ -1002,7 +1094,7 @@ ${fallback_html}`;
 			return null;
 		}
 
-		const path = focus_root.dataset.path.split('.');
+		const path = deserialize_path(focus_root.dataset.path);
 
 		if (!path) return null;
 
@@ -1011,12 +1103,14 @@ ${fallback_html}`;
 		// AnnotatedTextProperty renders a trailing <br> for non-empty or non-focused text.
 		// 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;
-		const text_length = get_char_length(text_content);
+		// We detect this and return the current DOM text length instead.
+		// During compositionend, the browser has already inserted the composed
+		// character into the DOM, while the Svedit model still has the old text.
+		const dom_text_length = get_char_length(focus_root.textContent ?? '');
 		const child_nodes = focus_root.childNodes;
 
 		if (
+			range.collapsed &&
 			focus_node === anchor_node &&
 			focus_node === focus_root &&
 			focus_root.dataset?.type === 'text' &&
@@ -1037,43 +1131,21 @@ ${fallback_html}`;
 				return {
 					type: 'text',
 					path,
-					anchor_offset: text_length,
-					focus_offset: text_length
+					anchor_offset: dom_text_length,
+					focus_offset: dom_text_length
 				};
 			}
 		}
 
-		let start_offset = 0;
-		let end_offset = 0;
-		let current_offset = 0;
-
-		function processNode(node) {
-			if (node.nodeType === Node.TEXT_NODE) {
-				const nodeText = node.textContent;
-				const nodeCharLength = get_char_length(nodeText);
-				if (node === range.startContainer) {
-					// Convert UTF-16 offset to character offset
-					const char_start_offset = utf16_to_char_offset(nodeText, range.startOffset);
-					start_offset = current_offset + char_start_offset;
-				}
-				if (node === range.endContainer) {
-					// Convert UTF-16 offset to character offset
-					const char_end_offset = utf16_to_char_offset(nodeText, range.endOffset);
-					end_offset = current_offset + char_end_offset;
-				}
-				current_offset += nodeCharLength;
-			} else if (node.nodeType === Node.ELEMENT_NODE) {
-				for (const childNode of node.childNodes) {
-					processNode(childNode);
-				}
-			}
-			return end_offset !== 0;
+		function get_text_offset(container, offset) {
+			const offset_range = window.document.createRange();
+			offset_range.setStart(focus_root, 0);
+			offset_range.setEnd(container, offset);
+			return get_char_length(offset_range.toString());
 		}
 
-		// Process nodes to find offsets
-		for (const childNode of focus_root.childNodes) {
-			if (processNode(childNode)) break;
-		}
+		const start_offset = get_text_offset(range.startContainer, range.startOffset);
+		const end_offset = get_text_offset(range.endContainer, range.endOffset);
 
 		// Check if it's a backward selection
 		// When range is provided, we can't detect backward selection from the range alone
@@ -1094,18 +1166,35 @@ ${fallback_html}`;
 
 	function __get_node_element(node_array_path, node_offset) {
 		return canvas_el.querySelector(
-			`[data-path="${node_array_path}.${node_offset}"][data-type="node"]`
+			`[data-path="${serialize_path([...node_array_path, node_offset])}"][data-type="node"]`
+		);
+	}
+
+	/**
+	 * True when any part of the element's border box overlaps the window
+	 * viewport. Used to keep node-selection re-renders from scrolling a
+	 * cursor that is already on screen. Tests the window viewport, so a
+	 * node clipped only by an inner scroll container still counts visible.
+	 * @param {Element | null | undefined} el
+	 */
+	function __intersects_viewport(el) {
+		if (!el) return false;
+		const r = el.getBoundingClientRect();
+		return (
+			r.bottom > 0 && r.top < window.innerHeight &&
+			r.right > 0 && r.left < window.innerWidth
 		);
 	}
 
 	function __render_node_selection() {
 		const selection = /** @type {NodeSelection} */ (session.selection);
-		const node_array_path = selection.path.join('.');
-		const is_collapsed = selection.anchor_offset === selection.focus_offset;
+		const node_array_path = selection.path;
+		const node_array_path_str = serialize_path(node_array_path);
+		const is_collapsed = is_selection_collapsed(selection);
 		const is_backward = !is_collapsed && selection.anchor_offset > selection.focus_offset;
 
 		const node_array_el = canvas_el.querySelector(
-			`[data-path="${node_array_path}"][data-type="node_array"]`
+			`[data-path="${node_array_path_str}"][data-type="node_array"]`
 		);
 		if (!node_array_el) return;
 
@@ -1113,7 +1202,7 @@ ${fallback_html}`;
 		const range = window.document.createRange();
 
 		const gap_selector = (offset) =>
-			`[data-gap-array-path="${node_array_path}"][data-gap-offset="${offset}"]`;
+			`[data-gap-array-path="${node_array_path_str}"][data-gap-offset="${offset}"]`;
 
 		if (is_collapsed) {
 			const gap_el = node_array_el.querySelector(gap_selector(selection.anchor_offset));
@@ -1146,24 +1235,66 @@ ${fallback_html}`;
 			}
 		}
 
-		node_array_el.focus();
-		const scroll_node_offset = is_collapsed
-			? Math.max(0, selection.anchor_offset - 1)
-			: (is_backward ? selection.focus_offset : selection.anchor_offset);
-		const scroll_node = __get_node_element(node_array_path, scroll_node_offset);
-		if (scroll_node) {
-			setTimeout(() => {
-				scroll_node.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-			}, 0);
-		}
+		// Scroll the cursor into view, but only when it is genuinely
+		// off-screen. This runs on every node-selection re-render — a
+		// transaction (type/layout change), select-parent, window refocus
+		// — so an unconditional scroll would yank the viewport on each of
+		// them. cursor_offset is a gap offset and the gap has no box of
+		// its own, so visibility is judged from the nodes flanking it.
+		setTimeout(() => {
+			// Collapsed: anchor === focus, so focus is the gap offset.
+			// Range: cursor sits at the focus end (anchor when backward).
+			const cursor_offset = is_backward ? selection.anchor_offset : selection.focus_offset;
+			const array_length = session.get(node_array_path).length;
+
+			// If either node flanking the cursor is already (even
+			// partially) on screen, the cursor is visible — keep the
+			// viewport stable and scroll nothing. node_before is null at
+			// offset 0: cursor_offset - 1 would be -1, and serialize_path
+			// rejects a negative index.
+			const node_before = cursor_offset > 0
+				? __get_node_element(node_array_path, cursor_offset - 1)
+				: null;
+			const node_after = __get_node_element(node_array_path, cursor_offset);
+			if (__intersects_viewport(node_before) || __intersects_viewport(node_after)) return;
+
+			if (cursor_offset === 0) {
+				node_array_el.scrollLeft = 0;
+				node_array_el.scrollTop = 0;
+				return;
+			}
+			if (cursor_offset >= array_length) {
+				const max_left = Math.max(
+					0,
+					node_array_el.scrollWidth - node_array_el.clientWidth
+				);
+				const max_top = Math.max(
+					0,
+					node_array_el.scrollHeight - node_array_el.clientHeight
+				);
+				node_array_el.scrollLeft = max_left;
+				node_array_el.scrollTop = max_top;
+				if (max_left === 0 && max_top === 0) {
+					node_before?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+				}
+				return;
+			}
+			// A range selection's selected node IS node_before; scrolling
+			// node_after would reveal the following node and leave the
+			// selection itself off-screen. For a collapsed caret node_after's
+			// leading edge is the cursor, so that stays the right target.
+			const target = is_collapsed ? node_after : node_before;
+			target?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+		}, 0);
 	}
 
 	function __render_property_selection() {
 		const selection = session.selection;
 		// The element that holds the property
 		const el = canvas_el.querySelector(
-			`[data-path="${selection.path.join('.')}"][data-type="property"]`
+			`[data-path="${serialize_path(selection.path)}"][data-type="property"]`
 		);
+
 		const gap_selectable = el.querySelector('.svedit-selectable');
 		const range = window.document.createRange();
 		const dom_selection = window.getSelection();
@@ -1176,10 +1307,7 @@ ${fallback_html}`;
 
 		// Scroll the selection into view
 		setTimeout(() => {
-			const selectedElement = dom_selection.focusNode.parentElement;
-			if (selectedElement) {
-				selectedElement.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-			}
+			el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
 		}, 0);
 	}
 
@@ -1187,7 +1315,7 @@ ${fallback_html}`;
 		const selection = /** @type {any} */ (session.selection);
 		// The element that holds the annotated string
 		const el = canvas_el.querySelector(
-			`[data-path="${selection.path.join('.')}"][data-type="text"]`
+			`[data-path="${serialize_path(selection.path)}"][data-type="text"]`
 		);
 		const empty_text = session.get(selection.path).text.length === 0;
 		const dom_selection = window.getSelection();
@@ -1274,7 +1402,6 @@ ${fallback_html}`;
 				focus_node,
 				focus_node_offset
 			);
-			el.focus(); // needed?
 
 			// Scroll the selection into view
 			setTimeout(() => {
@@ -1289,6 +1416,52 @@ ${fallback_html}`;
 	// Utils
 	// --------------------------
 
+	function __remove_native_composition_text(selection, inserted_text) {
+		if (!selection || selection.type !== 'text' || !inserted_text) return;
+
+		const text_el = canvas_el.querySelector(
+			`[data-path="${serialize_path(selection.path)}"][data-type="text"]`
+		);
+		if (!text_el) return;
+
+		const model_text = session.get(selection.path).text;
+		if ((text_el.textContent ?? '') === model_text) return;
+
+		let current_offset = 0;
+		function get_dom_text_position(root, target_offset) {
+			for (const node of root.childNodes) {
+				if (node.nodeType === Node.TEXT_NODE) {
+					const node_text = node.textContent ?? '';
+					const node_length = get_char_length(node_text);
+					if (current_offset + node_length >= target_offset) {
+						return {
+							node,
+							offset: char_to_utf16_offset(node_text, target_offset - current_offset)
+						};
+					}
+					current_offset += node_length;
+				} else if (node.nodeType === Node.ELEMENT_NODE) {
+					const position = get_dom_text_position(node, target_offset);
+					if (position) return position;
+				}
+			}
+			return null;
+		}
+
+		const start_offset = Math.min(selection.anchor_offset, selection.focus_offset);
+		const end_offset = start_offset + get_char_length(inserted_text);
+		current_offset = 0;
+		const start_position = get_dom_text_position(text_el, start_offset);
+		current_offset = 0;
+		const end_position = get_dom_text_position(text_el, end_offset);
+		if (!start_position || !end_position) return;
+
+		const range = window.document.createRange();
+		range.setStart(start_position.node, start_position.offset);
+		range.setEnd(end_position.node, end_position.offset);
+		range.deleteContents();
+	}
+
 	function __is_dom_selection_backwards() {
 		const dom_selection = window.getSelection();
 
@@ -1311,12 +1484,17 @@ ${fallback_html}`;
 		return comparisonRange.collapsed;
 	}
 
-	// Whenever the model selection changes, render the selection
+	// 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)
+	// (e.g., when a dialog is open and selection highlight fragments re-render).
+	// Consume the dom-driven flag at the top so it never carries stale
+	// state into the next change, even when we early-return.
 	$effect(() => {
+		session.selection;
+		const dom_driven = selection_source_is_dom;
+		selection_source_is_dom = false;
 		if (!canvas_focused) return;
-		render_selection();
+		render_selection(dom_driven);
 	});
 </script>
 
@@ -1327,10 +1505,20 @@ ${fallback_html}`;
 <svelte:document {onselectionchange} {oncut} {oncopy} {onpaste} />
 
 <!-- TODO: move oncut/copy/paste handlers inside .svedit -->
-<div class="svedit">
+<div class="svedit" class:editable>
 	<!-- Overlays must be before canvas so they initialize first. -->
-	<NodeSelectionMarkers />
+	{#if editable}<NodeSelectionMarkers />{/if}
 	{#if Overlays}<Overlays />{/if}
+	<!--
+		inputmode is derived from the model selection: when a custom property
+		(image, embed, etc.) is selected, set inputmode="none" so iOS does
+		not open the virtual keyboard. For any other selection (text, node,
+		none), allow the keyboard via inputmode="text". The browser's native
+		selection-change flow updates session.selection on tap, which flips
+		this attribute before iOS decides whether to show the keyboard — no
+		imperative state tracking, drag detection, or click/pointerdown
+		handlers are required for keyboard suppression.
+	-->
 	<div
 		class="svedit-canvas {css_class}"
 		class:hide-selection={session.selection?.type === 'node'}
@@ -1343,6 +1531,7 @@ ${fallback_html}`;
 		{oncompositionend}
 		onfocus={handle_canvas_focus}
 		onblur={handle_canvas_blur}
+		inputmode={session.selection?.type === 'text' ? 'text' : 'none'}
 		contenteditable={editable ? 'true' : 'false'}
 		tabindex="-1"
 		{autocapitalize}
@@ -1363,7 +1552,7 @@ ${fallback_html}`;
 
 <style>
 	.svedit-canvas {
-		caret-color: var(--svedit-editing-stroke);
+		caret-color: var(--svedit-caret-color);
 		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.
@@ -1374,7 +1563,11 @@ ${fallback_html}`;
 		}
 	}
 
-	.svedit-canvas :global(::selection) {
+	/* Selection paint — wrapped in :where() so consumers can override with
+	   a plain `::selection` rule. Svelte still adds the scope hash inside
+	   the :where(), but the wrapper zeroes its specificity contribution.
+	   Final specificity is just (0,0,1), trivially beatable. */
+	:where(.svedit-canvas) :global(::selection) {
 		background: var(--svedit-editing-fill);
 	}