svedit 0.9.0 → 0.11.0

package/src/lib/Svedit.svelte

@@ -1,18 +1,31 @@
 <script>
 	import { flushSync, getContext, setContext } from 'svelte';
 	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 {
+		normalize_line_endings,
+		dedent_plain_text,
+		split_plain_text_paragraphs,
+		normalize_plain_text_for_single_line_property,
+		get_text_property_name,
+		get_text_content,
+		is_text_like_node_payload,
+		get_default_text_node,
+		create_plain_text_nodes_payload
+	} from './paste_utils.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,
@@ -33,14 +46,19 @@
 
 	let canvas_el;
 	let root_node = $derived(session.get(path));
-	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 Overlays = $derived(session.config.system_components?.overlays);
+	let NodeSelectionMarkers = $derived(
+		session.config.system_components?.node_selection_markers ?? DefaultNodeSelectionMarkers
+	);
+	let RootComponent = $derived(session.config.node_components[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());
 	// let is_chrome_desktop = $derived(is_chrome_desktop_browser());
@@ -71,7 +89,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');
@@ -145,14 +207,14 @@
 		if (
 			['deleteContentBackward', 'deleteWordBackward', 'deleteContent'].includes(event.inputType)
 		) {
-			delete_at_selection('backward');
+			session.apply(session.tr.delete_selection('backward'));
 			event.preventDefault();
 			event.stopPropagation();
 			return;
 		}
 
 		if (['deleteContentForward', 'deleteWordForward'].includes(event.inputType)) {
-			delete_at_selection('forward');
+			session.apply(session.tr.delete_selection('forward'));
 			event.preventDefault();
 			event.stopPropagation();
 			return;
@@ -190,10 +252,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 +278,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 +290,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 +326,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 +339,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 +509,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 +545,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,36 +553,82 @@ ${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);
 		}
 
 		if (delete_selection) {
-			delete_at_selection();
+			session.apply(session.tr.delete_selection());
 		}
 	}
 
+	function oncut(event) {
+		if (!editable) return;
+		oncopy(event, true);
+	}
+
+
+
 	/**
-	 * Shared delete logic for cut, backspace, and forward-delete.
-	 * For property selections, delegates to the config's handle_property_deletion hook.
-	 * For text/node selections, uses the standard transaction delete_selection.
-	 *
-	 * @param {'backward' | 'forward'} [direction]
+	 * @returns {NodeSelection|null}
 	 */
-	function delete_at_selection(direction = 'backward') {
-		if (session.selection?.type === 'property') {
-			if (session.config.handle_property_deletion) {
-				session.config.handle_property_deletion(session, session.selection.path);
-			}
-		} else {
-			session.apply(session.tr.delete_selection(direction));
+	function get_root_node_insert_caret() {
+		const root_node = session.get(path);
+		const root_schema = root_node ? session.schema[root_node.type] : null;
+		if (!root_schema?.properties) return null;
+
+		const preferred_property_name =
+			root_schema.properties.body?.type === 'node_array'
+				? 'body'
+				: Object.entries(root_schema.properties).find(([, property_definition]) => {
+						return property_definition.type === 'node_array';
+					})?.[0];
+		if (!preferred_property_name) return null;
+
+		const node_array_path = [...path, preferred_property_name];
+		const node_array = session.get(node_array_path);
+		if (!Array.isArray(node_array)) return null;
+
+		return {
+			type: /** @type {const} */ ('node'),
+			path: node_array_path,
+			anchor_offset: node_array.length,
+			focus_offset: node_array.length
+		};
+	}
+
+	/**
+	 * @param {Selection|null} [selection]
+	 * @returns {NodeSelection|null}
+	 */
+	function get_target_node_insert_caret(selection = session.selection) {
+		if (selection?.type === 'node') {
+			return selection;
 		}
+
+		const next_node_insert_caret = session.get_next_node_insert_caret(selection);
+		if (next_node_insert_caret?.type === 'node') {
+			return next_node_insert_caret;
+		}
+
+		return get_root_node_insert_caret();
 	}
 
-	function oncut(event) {
-		if (!editable) return;
-		oncopy(event, true);
+	/**
+	 * @param {Selection|null} [selection]
+	 * @returns {NodeSelection|null}
+	 */
+	function get_node_insert_caret_after_text_selection(selection = session.selection) {
+		if (selection?.type !== 'text') return null;
+		const node_index = parseInt(String(selection.path.at(-2)), 10);
+		if (Number.isNaN(node_index)) return null;
+
+		return {
+			type: /** @type {const} */ ('node'),
+			path: selection.path.slice(0, -2),
+			anchor_offset: node_index + 1,
+			focus_offset: node_index + 1
+		};
 	}
 
 	/**
@@ -528,40 +639,46 @@ ${fallback_html}`;
 	 * @returns {boolean} True if the paste operation was successful, false otherwise
 	 */
 	function try_node_paste(pasted_json, selection) {
-		const { nodes, main_nodes } = pasted_json;
+		const { nodes, main_nodes } = pasted_json || {};
+		if (!nodes || !main_nodes?.length) return false;
 
-		// NOTE: At this point, nodes contains a subgraph from the copy
-		// with original ids.
 		let tr = session.tr;
 		if (selection) {
 			tr.set_selection(selection);
 		}
+		if (tr.selection?.type !== 'node') return false;
 
-		// We can safely assume we're dealing with a node_array property
 		const property_definition = session.inspect(tr.selection.path);
-		const first_compatible_text_node_type = property_definition.node_types.find(
-			(type) => session.kind({ type }) === 'text'
-		);
+		if (property_definition?.type !== 'node_array') return false;
+
+		const default_text_node_type = get_default_text_node(property_definition, session.schema);
+		const target_text_property_name = get_text_property_name(default_text_node_type, session.schema);
 
 		const nodes_to_insert = [];
 		let rejected = false;
 		for (const node_id of main_nodes) {
 			const node = nodes[node_id];
+			if (!node) {
+				rejected = true;
+				break;
+			}
+
 			if (!property_definition.node_types.includes(node.type)) {
-				// Incompatible node type detected
-				if (session.kind(node) === 'text' && first_compatible_text_node_type) {
+				const text_content = get_text_content(node, session.schema);
+				if (
+					is_text_like_node_payload(node, session.schema) &&
+					default_text_node_type &&
+					target_text_property_name
+				) {
 					const new_node_id = tr.build('the_node', {
 						the_node: {
 							id: 'the_node',
-							type: first_compatible_text_node_type,
-							content: node.content
+							type: default_text_node_type,
+							[target_text_property_name]: text_content || { text: '', annotations: [] }
 						}
 					});
 					nodes_to_insert.push(new_node_id);
 				} else {
-					console.log(
-						`rejected ${node.type}. Only ${property_definition.node_types.join(', ')} allowed.`
-					);
 					rejected = true;
 					break;
 				}
@@ -575,12 +692,12 @@ ${fallback_html}`;
 			tr.insert_nodes(nodes_to_insert);
 			session.apply(tr);
 			return true;
-		} else {
-			if (tr.selection.path.length >= 2) {
-				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);
-				}
+		}
+
+		if (tr.selection.path.length >= 2) {
+			const next_node_insert_caret = session.get_next_node_insert_caret(tr.selection);
+			if (next_node_insert_caret) {
+				return try_node_paste(pasted_json, next_node_insert_caret);
 			}
 		}
 		return false;
@@ -599,7 +716,11 @@ ${fallback_html}`;
 		// 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/') || item.type.startsWith('video/') || item.type.startsWith('audio/')) {
+			if (
+				item.type.startsWith('image/') ||
+				item.type.startsWith('video/') ||
+				item.type.startsWith('audio/')
+			) {
 				const blob = item.getAsFile();
 				const data_url = URL.createObjectURL(blob);
 				pasted_media.push({
@@ -612,9 +733,9 @@ ${fallback_html}`;
 		}
 
 		if (pasted_media.length > 0) {
-			const handle_media_paste = session.config.handle_media_paste || session.config.handle_image_paste
+			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;
@@ -625,8 +746,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;
 			}
 
@@ -636,28 +757,51 @@ ${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) {
-					pasted_json = {
-						main_nodes: [],
-						nodes: []
-					};
-					for (let i = 0; i < plain_text_fragments.length; i++) {
-						const fragment = plain_text_fragments[i];
-						pasted_json.nodes['fragment_' + i] = {
-							id: 'fragment_' + i,
-							type: 'text',
-							content: {
-								text: fragment,
-								annotations: []
+				plain_text = normalize_line_endings(plain_text);
+				plain_text = dedent_plain_text(plain_text);
+				const plain_text_fragments = split_plain_text_paragraphs(plain_text);
+				const has_multiple_paragraphs = plain_text_fragments.length > 1;
+
+				if (session.selection?.type === 'text') {
+					const property_definition = session.inspect(session.selection.path);
+					if (property_definition?.type === 'annotated_text' && !property_definition.allow_newlines) {
+						plain_text = normalize_plain_text_for_single_line_property(plain_text);
+					}
+
+					const owner_node = session.get(session.selection.path.slice(0, -1));
+					const owner_is_text_node = owner_node && session.kind(owner_node) === 'text';
+
+					if (owner_is_text_node && has_multiple_paragraphs) {
+						const node_array_property_definition = session.inspect(
+							session.selection.path.slice(0, -2)
+						);
+						const default_text_node_type = get_default_text_node(node_array_property_definition, session.schema);
+						const node_insert_caret = get_node_insert_caret_after_text_selection(session.selection);
+						const plain_text_nodes_payload = create_plain_text_nodes_payload(
+							plain_text_fragments,
+							default_text_node_type,
+							session.schema
+						);
+
+						if (node_insert_caret && plain_text_nodes_payload) {
+							const did_paste_nodes = try_node_paste(plain_text_nodes_payload, node_insert_caret);
+							if (did_paste_nodes) {
+								return;
 							}
-						};
-						pasted_json.main_nodes.push('fragment_' + i);
+						}
+					}
+				} else {
+					const target_node_insert_caret = get_target_node_insert_caret(session.selection);
+					if (target_node_insert_caret) {
+						const node_array_property_definition = session.inspect(target_node_insert_caret.path);
+						const default_text_node_type = get_default_text_node(node_array_property_definition, session.schema);
+						pasted_json = create_plain_text_nodes_payload(
+							plain_text_fragments,
+							default_text_node_type,
+							session.schema
+						);
 					}
 				}
 			}
@@ -695,46 +839,57 @@ ${fallback_html}`;
 		} else if (
 			session.selection?.type === 'text' &&
 			pasted_json?.main_nodes?.length === 1 &&
-			session.kind(pasted_json?.nodes[pasted_json.main_nodes[0]]) === 'text'
+			is_text_like_node_payload(pasted_json?.nodes[pasted_json.main_nodes[0]], session.schema)
 		) {
 			// 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)
+			const text_property = get_text_content(
+				pasted_json.nodes[pasted_json.main_nodes[0]],
+				session.schema
 			);
+			if (text_property) {
+				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 caret
-			const next_node_insert_caret = session.get_next_node_insert_caret(session.selection);
-			try_node_paste(pasted_json, next_node_insert_caret);
+			const target_node_insert_caret = get_target_node_insert_caret(session.selection);
+			if (target_node_insert_caret) {
+				try_node_paste(pasted_json, target_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()));
-		} else {
-			console.log('Could not paste.');
+			session.apply(session.tr.insert_text(plain_text));
 		}
 	}
 
-	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') {
@@ -744,7 +899,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));
 		}
 	}
 
@@ -753,18 +908,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
@@ -794,11 +943,13 @@ ${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"]`
+			)
 		);
 	}
 
@@ -821,13 +972,34 @@ ${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]')
-		);
+		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',
@@ -837,16 +1009,18 @@ ${fallback_html}`;
 			};
 		}
 
-		let focus_root = __resolve_node_from_gap(focus_node)
-			?? /** @type {HTMLElement} */ (focus_node.closest('[data-path][data-type="node"]'));
+		let focus_root =
+			__resolve_node_from_gap(focus_node) ??
+			/** @type {HTMLElement} */ (focus_node.closest('[data-path][data-type="node"]'));
 		if (!focus_root) return null;
 
-		let anchor_root = __resolve_node_from_gap(anchor_node)
-			?? /** @type {HTMLElement} */ (anchor_node.closest('[data-path][data-type="node"]'));
+		let anchor_root =
+			__resolve_node_from_gap(anchor_node) ??
+			/** @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;
 
@@ -856,30 +1030,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;
 			}
 		}
@@ -893,16 +1065,13 @@ ${fallback_html}`;
 		const parent_property = session.inspect(parent_array_path);
 		if (!parent_property || parent_property.type !== 'node_array') return null;
 
-		let anchor_offset = parseInt(anchor_root_path.at(-1));
-		let focus_offset = parseInt(focus_root_path.at(-1));
+		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.
@@ -961,7 +1130,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;
@@ -1004,19 +1173,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;
 		}
 
@@ -1024,7 +1204,7 @@ ${fallback_html}`;
 			return null;
 		}
 
-		const path = focus_root.dataset.path.split('.');
+		const path = deserialize_path(focus_root.dataset.path);
 
 		if (!path) return null;
 
@@ -1033,12 +1213,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' &&
@@ -1046,7 +1228,10 @@ ${fallback_html}`;
 		) {
 			// Find the last non-comment child node (comments are inserted by Svelte)
 			let last_element_index = child_nodes.length - 1;
-			while (last_element_index >= 0 && child_nodes[last_element_index].nodeType === Node.COMMENT_NODE) {
+			while (
+				last_element_index >= 0 &&
+				child_nodes[last_element_index].nodeType === Node.COMMENT_NODE
+			) {
 				last_element_index--;
 			}
 
@@ -1059,43 +1244,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
@@ -1115,19 +1278,34 @@ ${fallback_html}`;
 	}
 
 	function __get_node_element(node_array_path, node_offset) {
+		if (!canvas_el) return null;
 		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;
 
@@ -1135,7 +1313,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));
@@ -1168,24 +1346,59 @@ ${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();
@@ -1198,10 +1411,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);
 	}
 
@@ -1209,7 +1419,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();
@@ -1296,7 +1506,6 @@ ${fallback_html}`;
 				focus_node,
 				focus_node_offset
 			);
-			el.focus(); // needed?
 
 			// Scroll the selection into view
 			setTimeout(() => {
@@ -1311,6 +1520,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();
 
@@ -1333,12 +1588,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>
 
@@ -1349,10 +1609,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'}
@@ -1365,6 +1635,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}
@@ -1385,7 +1656,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.
@@ -1396,7 +1667,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);
 	}