svedit 0.9.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # Svedit
 
-Svedit (think Svelte Edit) is a tiny library for building editable websites in Svelte. You can model your content in JSON, render it with custom Svelte components, and (this is the kicker) site owners can **edit their site directly in the layout** — no CMS needed.
+Svedit (think Svelte Edit) is a tiny library for building editable websites in Svelte. Model content in JSON, render it with custom components, and let site owners **edit directly in the layout** — no CMS needed.
 
 - Try the [Svedit demo](https://svedit.dev) — watch the debug output at the bottom of the page
 - Try [Editable Website](https://editable.website) — utilizes Svedit to enable CMS-free editable websites
@@ -32,6 +32,8 @@ You can also install Svedit into an existing SvelteKit project with `npm install
 
 **Chromeless canvas:** Svedit keeps the editing canvas chromeless, meaning there are no UI elements like toolbars or menus mingled with the content. You can interact with text directly, but everything else happens via tools shown in separate overlays or in the fixed toolbar.
 
+**Native-first:** Svedit favors standardized native browser solutions over custom ones whenever possible — using browser-based rendering and the browser's selection APIs underneath, rather than reimplementing them (e.g. by building on [pretext](https://github.com/chenglou/pretext)). When we hit browser bugs, we try to get them fixed upstream (in collaboration with the W3C editing working group). Workarounds we add are intended to be temporary, until the underlying issue is fixed by browser vendors. And where we believe there's a better way to solve a problem than what's currently specified, we lobby for it to become a new (or improved) web standard.
+
 ## How it works
 
 Svedit connects eight key pieces:
@@ -46,9 +48,10 @@ Svedit connects eight key pieces:
 8. **Commands** - User actions (bold text, insert node, undo/redo) that modify the session
 
 **The flow:**
+
 - Define a schema → create a session → provide config → render with `<Svedit>` component
 - User interactions trigger commands → commands create transactions → which run transforms to modify the document → session applies the transaction → Svelte's reactivity updates the UI
-- Selection state syncs bidirectionally with the DOM
+- Native DOM selections are mapped to Svedit's internal selection model
 
 ## Schema
 
@@ -57,6 +60,7 @@ You can use a simple JSON-compatible schema definition language to enforce const
 First off, everything is a node. The page is a node, and so is a paragraph, a list, a list item, a nav and a nav item.
 
 Each node has a `kind` that determines its behavior:
+
 - `document`: A top-level node accessible via a route (e.g. a page, event)
 - `block`: A structured node that contains other nodes or properties
 - `text`: A node with editable text content (can be split and joined)
@@ -65,6 +69,7 @@ Each node has a `kind` that determines its behavior:
 ### Choosing between `text` and `block`
 
 `kind: 'text'` opts into the split/join system (`break_text_node`, `join_text_node`), which assumes:
+
 - The node has exactly **one** `annotated_text` property named **`content`**
 - Pressing Enter splits the node into two nodes of the same type
 - Pressing Backspace at position 0 joins it with the previous node
@@ -106,6 +111,7 @@ flowchart TD
 </details>
 
 Properties of nodes can hold values:
+
 - `string`: A good old JavaScript string
 - `number`: Just like a number in JavaScript
 - `integer`: A number for which Number.isInteger(number) returns true
@@ -118,83 +124,83 @@ Properties of nodes can hold values:
 - `annotated_text`: A plain text string with annotations (bold, italic, link etc.). Set `allow_newlines: true` to let users insert line breaks with Shift+Enter, or `false` to keep content single-line (e.g. for titles).
 
 Or references:
+
 - `node`: References a single node (e.g. an image node can reference a global asset node)
 - `node_array`: References a sequence of nodes (e.g. page.body references paragraph and list nodes)
 
-
 ```js
 const document_schema = {
-  page: {
-    kind: 'document',
-    properties: {
-      body: {
-        type: 'node_array',
-        node_types: ['nav', 'paragraph', 'list'],
-        default_node_type: 'paragraph',
-      }
-    }
-  },
-  paragraph: {
-    kind: 'text',
-    properties: {
-      content: {
-        type: 'annotated_text',
-        node_types: ['strong', 'emphasis', 'link'],
-        allow_newlines: true
-      }
-    }
-  },
-  list_item: {
-    kind: 'text',
-    properties: {
-      content: {
-        type: 'annotated_text',
-        node_types: ['strong', 'emphasis', 'link'],
-        allow_newlines: true
-      },
-    }
-  },
-  list: {
-    kind: 'block',
-    properties: {
-      list_items: {
-        type: 'node_array',
-        node_types: ['list_item'],
-        default_node_type: 'list_item',
-      }
-    }
-  },
-  nav: {
-    kind: 'block',
-    properties: {
-      nav_items: {
-        type: 'node_array',
-        node_types: ['nav_item'],
-        default_node_type: 'nav_item',
-      }
-    }
-  },
-  nav_item: {
-    kind: 'block',
-    properties: {
-      url: { type: 'string' },
-      label: { type: 'string' },
-    }
-  },
-  strong: {
-    kind: 'annotation',
-    properties: {}
-  },
-  emphasis: {
-    kind: 'annotation',
-    properties: {}
-  },
-  link: {
-    kind: 'annotation',
-    properties: {
-      href: { type: 'string' }
-    }
-  }
+	page: {
+		kind: 'document',
+		properties: {
+			body: {
+				type: 'node_array',
+				node_types: ['nav', 'paragraph', 'list'],
+				default_node_type: 'paragraph'
+			}
+		}
+	},
+	paragraph: {
+		kind: 'text',
+		properties: {
+			content: {
+				type: 'annotated_text',
+				node_types: ['strong', 'emphasis', 'link'],
+				allow_newlines: true
+			}
+		}
+	},
+	list_item: {
+		kind: 'text',
+		properties: {
+			content: {
+				type: 'annotated_text',
+				node_types: ['strong', 'emphasis', 'link'],
+				allow_newlines: true
+			}
+		}
+	},
+	list: {
+		kind: 'block',
+		properties: {
+			list_items: {
+				type: 'node_array',
+				node_types: ['list_item'],
+				default_node_type: 'list_item'
+			}
+		}
+	},
+	nav: {
+		kind: 'block',
+		properties: {
+			nav_items: {
+				type: 'node_array',
+				node_types: ['nav_item'],
+				default_node_type: 'nav_item'
+			}
+		}
+	},
+	nav_item: {
+		kind: 'block',
+		properties: {
+			url: { type: 'string' },
+			label: { type: 'string' }
+		}
+	},
+	strong: {
+		kind: 'annotation',
+		properties: {}
+	},
+	emphasis: {
+		kind: 'annotation',
+		properties: {}
+	},
+	link: {
+		kind: 'annotation',
+		properties: {
+			href: { type: 'string' }
+		}
+	}
 };
 ```
 
@@ -205,6 +211,7 @@ Annotation types are defined as nodes with `kind: 'annotation'`. Simple annotati
 A document is a plain JavaScript object (POJO) with a `document_id` (the entry point) and a `nodes` object containing all content nodes.
 
 Rules:
+
 - All nodes must be reachable from the document node (unreachable nodes are discarded)
 - No cyclic references allowed
 - Text content uses `{ text: '', annotations: [] }` format
@@ -213,48 +220,80 @@ Here's an example document:
 
 ```js
 const doc = {
-  document_id: 'page_1',
-  nodes: {
-    nav_item_1: {
-      id: 'nav_item_1',
-      type: 'nav_item',
-      url: '/homepage',
-      label: 'Home'
-    },
-    nav_1: {
-      id: 'nav_1',
-      type: 'nav',
-      nav_items: ['nav_item_1']
-    },
-    paragraph_1: {
-      id: 'paragraph_1',
-      type: 'paragraph',
-      content: { text: 'Hello world.', annotations: [] }
-    },
-    list_item_1: {
-      id: 'list_item_1',
-      type: 'list_item',
-      content: { text: 'First list item', annotations: [] }
-    },
-    list_item_2: {
-      id: 'list_item_2',
-      type: 'list_item',
-      content: { text: 'Second list item', annotations: [] }
-    },
-    list_1: {
-      id: 'list_1',
-      type: 'list',
-      list_items: ['list_item_1', 'list_item_2']
-    },
-    page_1: {
-      id: 'page_1',
-      type: 'page',
-      body: ['nav_1', 'paragraph_1', 'list_1']
-    }
-  }
+	document_id: 'page_1',
+	nodes: {
+		nav_item_1: {
+			id: 'nav_item_1',
+			type: 'nav_item',
+			url: '/homepage',
+			label: 'Home'
+		},
+		nav_1: {
+			id: 'nav_1',
+			type: 'nav',
+			nav_items: ['nav_item_1']
+		},
+		paragraph_1: {
+			id: 'paragraph_1',
+			type: 'paragraph',
+			content: { text: 'Hello world.', annotations: [] }
+		},
+		list_item_1: {
+			id: 'list_item_1',
+			type: 'list_item',
+			content: { text: 'First list item', annotations: [] }
+		},
+		list_item_2: {
+			id: 'list_item_2',
+			type: 'list_item',
+			content: { text: 'Second list item', annotations: [] }
+		},
+		list_1: {
+			id: 'list_1',
+			type: 'list',
+			list_items: ['list_item_1', 'list_item_2']
+		},
+		page_1: {
+			id: 'page_1',
+			type: 'page',
+			body: ['nav_1', 'paragraph_1', 'list_1']
+		}
+	}
+};
+```
+
+### Document schema changes
+
+Svedit validates documents against the current schema when you create a `Session`. If you change the schema, you are responsible for migrating existing documents before loading them.
+
+For simple additive changes, defaults can help. When you add a new property, you can call `fill_document_defaults` before creating the session:
+
+```js
+import { Session, fill_document_defaults } from 'svedit';
+
+const document_schema = {
+	paragraph: {
+		kind: 'text',
+		properties: {
+			layout: { type: 'integer', default: 1 },
+			content: {
+				type: 'annotated_text',
+				allow_newlines: true
+			}
+		}
+	}
 };
+
+const migrated_doc = fill_document_defaults(existing_doc, document_schema);
+const session = new Session(document_schema, migrated_doc, config);
 ```
 
+This only fills properties that are missing. Explicit schema `default` values are used when present; otherwise Svedit uses built-in defaults for value types such as strings, numbers, booleans, arrays, `node_array`, and `annotated_text`. Existing values are preserved, and the original document object is not mutated.
+
+Defaults make it safe to add new defaultable properties, but they are not a replacement for real document migrations. If you rename a property, remove a property, split one property into several, change node types, or need to transform existing data, write your own migration first and use `fill_document_defaults` only as a helper where appropriate.
+
+`tr.create` and `tr.build` also fill omitted defaults for newly-created nodes. For document migrations, declare explicit defaults whenever the built-in type default is not the value you want. Do not rely on default filling for schema changes that need a real migration.
+
 ## Config
 
 Documents need a config object that tells Svedit how to render and manipulate your content. See the full example in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js).
@@ -273,13 +312,13 @@ Two optional hooks are especially useful when integrating custom media workflows
 const session_config = {
   // ID generator for creating new nodes
   generate_id: () => nanoid(),
-  
+
   // User-land overlays and optional system component overrides
-  system_components: { Overlays },
-  
+  system_components: { overlays: Overlays },
+
   // Map node types to Svelte components
-  node_components: { Page, Text, Story, List, Button, ... },
-  
+  node_components: { page: Page, text: Text, story: Story, list: List, button: Button, ... },
+
   // Functions that create and insert new nodes
   inserters: {
     text: (tr, content = {text: '', annotations: []}) => {
@@ -288,10 +327,10 @@ const session_config = {
       tr.insert_nodes([text_id]);
     }
   },
-  
+
   // Returns { commands, keymap } for the editor instance
   create_commands_and_keymap: (context) => { ... },
-  
+
   // Optional: handle image paste events
   handle_image_paste: (session, images) => { ... }
 };
@@ -302,11 +341,12 @@ const session_config = {
 - **`generate_id`** - Function that generates unique IDs for new nodes
 - **`node_components`** - Maps each node type from your schema to a Svelte component
 - **`system_components`** - Optional overrides for internal editor components and a slot for your own overlays:
-  - `Overlays` — A Svelte component rendered inside `<Svedit>` but outside the content canvas. Use it to add floating UI like link editors, image toolbars, or annotation popovers that appear near the current selection. See [`src/routes/components/Overlays.svelte`](src/routes/components/Overlays.svelte) for an example.
-  - `NodeGap`, `NodeGapMarkers`, `NodeSelectionMarkers` — Override the default system components if you need custom visuals for node gaps or selection indicators.
+  - `overlays` — A Svelte component rendered inside `<Svedit>` but outside the content canvas. Use it to add floating UI like link editors, image toolbars, or annotation popovers that appear near the current selection. See [`src/routes/components/Overlays.svelte`](src/routes/components/Overlays.svelte) for an example.
+  - `node_gap`, `node_gap_markers`, `node_selection_markers` — Override the default system components if you need custom visuals for node gaps or selection indicators.
 - **`inserters`** - Functions that create blank nodes of each type and set up the selection
 - **`create_commands_and_keymap`** - Factory function that creates commands and keybindings for an editor instance
 - **`handle_image_paste`** - Optional handler for image paste events
+- **`view_classes`** - Viewport visibility classes. Every node element gets `.in-view`, `.seen`, `.fully-in-view`, `.visible-top`, `.visible-bottom` toggled as it scrolls through the viewport. Useful for scrollytelling and reveal animations driven from CSS. **On by default**. Set `view_classes: false` to opt out — saves ~5 classList ops per IO entry (measurable scroll-FPS win at 200+ nodes) and narrows the IntersectionObserver thresholds from `[0, 0.98]` to `[0]` (halves callback frequency during scroll). Disable if your app doesn't read these classes from CSS.
 
 The config is accessible throughout your app via `session.config`.
 
@@ -329,30 +369,42 @@ const session = new Session(schema, doc, config);
 ### Reading the graph
 
 ```js
-session.get(['page_1', 'body'])         // => ['nav_1', 'paragraph_1', 'list_1']
-session.get(['nav_1'])                  // => { id: 'nav_1', type: 'nav', ... }
-session.get('nav_1')                    // => shorthand for above (single node ID)
-session.inspect(['page_1', 'body'])     // => { kind: 'property', type: 'node_array', node_types: [...] }
-session.kind(node)                      // => 'text', 'block', or 'annotation'
+session.get(['page_1', 'body']); // => ['nav_1', 'paragraph_1', 'list_1']
+session.get(['nav_1']); // => { id: 'nav_1', type: 'nav', ... }
+session.get('nav_1'); // => shorthand for above (single node ID)
+session.inspect(['page_1', 'body']); // => { kind: 'property', type: 'node_array', node_types: [...] }
+session.kind(node); // => 'text', 'block', or 'annotation'
 ```
 
 ### Selection and state
 
 ```js
-session.selection                       // Current selection (text, node, or property)
-session.selected_node                   // The currently selected node (derived)
-session.active_annotation('strong')     // Check if annotation is active at caret
-session.can_insert('paragraph')         // Check if node type can be inserted
-session.available_annotation_types      // Annotation types allowed at current selection (derived)
+session.selection; // Current selection (text, node, or property)
+session.selected_node; // The currently selected node (derived)
+session.active_annotation('strong'); // Check if annotation is active at caret
+session.can_insert('paragraph'); // Check if node type can be inserted
+session.available_annotation_types; // Annotation types allowed at current selection (derived)
 ```
 
+#### Native selection as source of truth
+
+Every selection that can exist in Svedit must have a DOM representation. This is a core design decision: the browser's native selection determines where the selection is, and `session.selection` is derived from it — not the other way around. If the DOM selection stops being the source of truth, selection mapping becomes ambiguous and Svedit loses the simplicity and determinism that the editor is built on.
+
+This applies to all selection types:
+
+- Text selections are native selections inside an `annotated_text` property.
+- Node selections are native selections whose anchor and focus land inside the selected node range.
+- Property selections are native selections inside the DOM representation of that property.
+
+For example, a multi-node selection is still represented as a native browser selection that starts somewhere inside one node and ends somewhere inside another. Svedit maps that DOM selection to an internal node selection, hides the browser's visual selection, and renders `NodeSelectionMarkers` instead. The native selection remains in the DOM behind the scenes because `contenteditable` still needs it to do its job: pressing an arrow key should move the cursor from the current focus point to the closest valid next position, and Shift+Arrow should expand the selection from that same focus point. Without a native selection rendered at all times, the browser has no reliable starting point for cursor movement, selection expansion, or other editing behavior.
+
 ### Making changes
 
 ```js
-const tr = session.tr;                  // Create a transaction
+const tr = session.tr; // Create a transaction
 tr.set(['nav_1', 'label'], 'Home');
 tr.insert_nodes(['new_node_id']);
-session.apply(tr);                      // Apply the transaction
+session.apply(tr); // Apply the transaction
 ```
 
 #### Batching history entries
@@ -372,10 +424,10 @@ session.last_batch_started = undefined;
 ### History
 
 ```js
-session.can_undo                        // Boolean (derived)
-session.can_redo                        // Boolean (derived)
-session.undo()
-session.redo()
+session.can_undo; // Boolean (derived)
+session.can_redo; // Boolean (derived)
+session.undo();
+session.redo();
 ```
 
 ### Detecting unsaved changes
@@ -385,18 +437,18 @@ Because document state is immutable, you can detect unsaved changes by comparing
 ```js
 let last_saved_doc = $state(null);
 let has_unsaved_changes = $derived.by(() => {
-  if (!last_saved_doc) {
-    // No save yet — use undo history as indicator
-    return session.can_undo;
-  } else {
-    // Compare current doc reference against last saved
-    return last_saved_doc !== session.doc;
-  }
+	if (!last_saved_doc) {
+		// No save yet — use undo history as indicator
+		return session.can_undo;
+	} else {
+		// Compare current doc reference against last saved
+		return last_saved_doc !== session.doc;
+	}
 });
 
 function save() {
-  // ... save to server ...
-  last_saved_doc = session.doc;
+	// ... save to server ...
+	last_saved_doc = session.doc;
 }
 ```
 
@@ -405,12 +457,12 @@ This works because of Svedit's copy-on-write strategy: only modified parts of th
 ### Utilities
 
 ```js
-session.doc.document_id                 // The document's root ID
-session.generate_id()                   // Generate a new unique ID
-session.config                          // Access the config object
-session.validate_doc()                  // Validate all nodes against schema
-session.traverse(node_id)               // Get all nodes reachable from a node
-session.select_parent()                 // Select parent of current selection
+session.doc.document_id; // The document's root ID
+session.generate_id(); // Generate a new unique ID
+session.config; // Access the config object
+session.validate_doc(); // Validate all nodes against schema
+session.traverse(node_id); // Get all nodes reachable from a node
+session.select_parent(); // Select parent of current selection
 ```
 
 ## Transforms
@@ -426,7 +478,7 @@ import { break_text_node } from 'svedit';
 const tr = session.tr;
 const success = break_text_node(tr);
 if (success) {
-  session.apply(tr);
+	session.apply(tr);
 }
 ```
 
@@ -444,10 +496,10 @@ Transforms are composable. You can build higher-level transforms from lower-leve
 
 ```js
 function custom_transform(tr) {
-  // Compose multiple transforms
-  if (!break_text_node(tr)) return false;
-  if (!insert_default_node(tr)) return false;
-  return true;
+	// Compose multiple transforms
+	if (!break_text_node(tr)) return false;
+	if (!insert_default_node(tr)) return false;
+	return true;
 }
 ```
 
@@ -457,16 +509,16 @@ You're encouraged to write custom transforms for your application's specific nee
 
 ```js
 function insert_heading(tr) {
-  const selection = tr.selection;
-  
-  if (selection?.type !== 'node') return false;
-  
-  // Create and insert a heading node
-  const heading_id = tr.generate_id();
-  tr.create({ id: heading_id, type: 'heading', content: { text: '', annotations: [] } });
-  tr.insert_nodes([heading_id]);
-  
-  return true;
+	const selection = tr.selection;
+
+	if (selection?.type !== 'node') return false;
+
+	// Create and insert a heading node
+	const heading_id = tr.generate_id();
+	tr.create({ id: heading_id, type: 'heading', content: { text: '', annotations: [] } });
+	tr.insert_nodes([heading_id]);
+
+	return true;
 }
 ```
 
@@ -477,9 +529,9 @@ Transactions group multiple operations into atomic units that can be applied and
 ### Basic usage
 
 ```js
-const tr = session.tr;                      // Create a new transaction
-tr.set(['node_1', 'title'], 'New Title');   // Modify properties
-session.apply(tr);                          // Apply atomically
+const tr = session.tr; // Create a new transaction
+tr.set(['node_1', 'title'], 'New Title'); // Modify properties
+session.apply(tr); // Apply atomically
 ```
 
 ### Node operations
@@ -496,7 +548,7 @@ tr.insert_nodes(['paragraph_1', 'list_1']);
 
 // Build a subgraph from existing nodes (generates new IDs)
 const new_node_id = tr.build('the_list', {
-  first_item: {
+	first_item: {
 		id: 'first_item',
 		type: 'list_item',
 		content: node.content
@@ -528,19 +580,17 @@ tr.delete_selection();
 ```js
 // Set the selection after operations
 tr.set_selection({
-  type: 'text',
-  path: ['node_1', 'content'],
-  anchor_offset: 0,
-  focus_offset: 5
+	type: 'text',
+	path: ['node_1', 'content'],
+	anchor_offset: 0,
+	focus_offset: 5
 });
 ```
 
 All transaction methods return `this` for chaining:
 
 ```js
-tr.create(node)
-  .insert_nodes([node.id])
-  .set_selection(new_selection);
+tr.create(node).insert_nodes([node.id]).set_selection(new_selection);
 ```
 
 ## Commands
@@ -548,6 +598,7 @@ tr.create(node)
 Commands provide a structured way to implement user actions. Commands are stateful and UI-aware, unlike transforms which are pure functions.
 
 There are two types of commands in Svedit:
+
 - **Document-scoped commands** - Bound to a specific Svedit instance/document and only active when that editor has focus
 - **App-level commands** - Operate at the application level, independent of any specific document
 
@@ -565,13 +616,13 @@ Extend the `Command` base class and implement the `is_enabled()` and `execute()`
 import { Command } from 'svedit';
 
 class ToggleStrongCommand extends Command {
-  is_enabled() {
-    return this.context.editable && this.context.session.selection?.type === 'text';
-  }
+	is_enabled() {
+		return this.context.editable && this.context.session.selection?.type === 'text';
+	}
 
-  execute() {
-    this.context.session.apply(this.context.session.tr.annotate_text('strong'));
-  }
+	execute() {
+		this.context.session.apply(this.context.session.tr.annotate_text('strong'));
+	}
 }
 ```
 
@@ -627,32 +678,33 @@ Commands are created by passing them a context object from the Svedit component.
 
 ```js
 create_commands_and_keymap: (context) => {
-  const commands = {
-    undo: new UndoCommand(context),
-    redo: new RedoCommand(context),
-    toggle_strong: new ToggleAnnotationCommand('strong', context),
-    toggle_emphasis: new ToggleAnnotationCommand('emphasis', context),
-    // ... more commands
-  };
-
-  const keymap = define_keymap({
-    'meta+z,ctrl+z': [commands.undo],
-    'meta+b,ctrl+b': [commands.toggle_strong],
-    // ... more keybindings
-  });
-
-  return { commands, keymap };
-}
+	const commands = {
+		undo: new UndoCommand(context),
+		redo: new RedoCommand(context),
+		toggle_strong: new ToggleAnnotationCommand('strong', context),
+		toggle_emphasis: new ToggleAnnotationCommand('emphasis', context)
+		// ... more commands
+	};
+
+	const keymap = define_keymap({
+		'meta+z,ctrl+z': [commands.undo],
+		'meta+b,ctrl+b': [commands.toggle_strong]
+		// ... more keybindings
+	});
+
+	return { commands, keymap };
+};
 ```
 
 Bind commands to UI elements in your components:
 
 ```svelte
-<button 
-  disabled={document_commands.toggle_strong.disabled}
-  class:active={document_commands.toggle_strong.active}
-  onclick={() => document_commands.toggle_strong.execute()}>
-  Bold
+<button
+	disabled={document_commands.toggle_strong.disabled}
+	class:active={document_commands.toggle_strong.active}
+	onclick={() => document_commands.toggle_strong.execute()}
+>
+	Bold
 </button>
 ```
 
@@ -662,34 +714,33 @@ Commands can have derived state for reactive UI binding. The `active` property i
 
 ```js
 class ToggleEmphasisCommand extends Command {
-  // Automatically recomputes when annotation state changes
-  active = $derived(this.context.session.active_annotation('emphasis'));
+	// Automatically recomputes when annotation state changes
+	active = $derived(this.context.session.active_annotation('emphasis'));
 
-  is_enabled() {
-    return this.context.editable && this.context.session.selection?.type === 'text';
-  }
+	is_enabled() {
+		return this.context.editable && this.context.session.selection?.type === 'text';
+	}
 
-  execute() {
-    this.context.session.apply(this.context.session.tr.annotate_text('emphasis'));
-  }
+	execute() {
+		this.context.session.apply(this.context.session.tr.annotate_text('emphasis'));
+	}
 }
 ```
 
 The `disabled` property is automatically derived from `is_enabled()` on all commands.
 
-
 #### DOM access in commands
 
 Commands can access the DOM through the context or global APIs:
 
 ```js
 class FocusNextSelectableCommand extends Command {
-  execute() {
-    const selectables = this.context.canvas_el.querySelectorAll('.svedit-selectable');
-    const next = selectables[0]; // Find next based on current selection
-    const path = next.closest('[data-path]').dataset.path.split('.');
-    this.context.session.selection = { type: 'text', path, anchor_offset: 0, focus_offset: 0 };
-  }
+	execute() {
+		const selectables = this.context.canvas_el.querySelectorAll('.svedit-selectable');
+		const next = selectables[0]; // Find next based on current selection
+		const path = next.closest('[data-path]').dataset.path.split('.');
+		this.context.session.selection = { type: 'text', path, anchor_offset: 0, focus_offset: 0 };
+	}
 }
 ```
 
@@ -705,6 +756,7 @@ Svedit uses a scope hierarchy (scope stack) to manage which commands are active
 2. **Document-level scope** (per Svedit instance) - Commands bound to a specific document/editor
 
 When a Svedit instance gains focus:
+
 - The previous document's scope is **popped** from the stack (its commands become inactive)
 - The newly focused document's scope is **pushed** onto the stack (its commands become active)
 
@@ -718,24 +770,24 @@ App-level commands have their own context, separate from any specific document:
 import { Command } from 'svedit';
 
 class SaveCommand extends Command {
-  is_enabled() {
-    return this.context.editable;
-  }
-
-  async execute() {
-    await this.context.save_all_documents();
-    this.context.show_notification('All changes saved');
-  }
+	is_enabled() {
+		return this.context.editable;
+	}
+
+	async execute() {
+		await this.context.save_all_documents();
+		this.context.show_notification('All changes saved');
+	}
 }
 
 class ToggleEditModeCommand extends Command {
-  is_enabled() {
-    return !this.context.editable;
-  }
+	is_enabled() {
+		return !this.context.editable;
+	}
 
-  execute() {
-    this.context.editable = true;
-  }
+	execute() {
+		this.context.editable = true;
+	}
 }
 ```
 
@@ -745,23 +797,23 @@ The app-level context contains application-wide state and methods:
 
 ```js
 const app_context = {
-  get editable() {
-    return editable; // App-level editable state
-  },
-  set editable(value) {
-    editable = value;
-  },
-  get session() {
-    return session;
-  },
-  get app_el() {
-    return app_el;
-  }
+	get editable() {
+		return editable; // App-level editable state
+	},
+	set editable(value) {
+		editable = value;
+	},
+	get session() {
+		return session;
+	},
+	get app_el() {
+		return app_el;
+	}
 };
 
 const app_commands = {
-  save: new SaveCommand(app_context),
-  toggle_edit: new ToggleEditCommand(app_context)
+	save: new SaveCommand(app_context),
+	toggle_edit: new ToggleEditCommand(app_context)
 };
 ```
 
@@ -778,9 +830,9 @@ const key_mapper = new KeyMapper();
 
 // Define a keymap
 const keymap = define_keymap({
-  'meta+z,ctrl+z': [document_commands.undo],
-  'meta+b,ctrl+b': [document_commands.bold],
-  'enter': [document_commands.break_text_node]
+	'meta+z,ctrl+z': [document_commands.undo],
+	'meta+b,ctrl+b': [document_commands.bold],
+	enter: [document_commands.break_text_node]
 });
 
 // Push the keymap onto the scope stack
@@ -788,7 +840,7 @@ key_mapper.push_scope(keymap);
 
 // Handle keydown events
 window.addEventListener('keydown', (event) => {
-  key_mapper.handle_keydown(event);
+	key_mapper.handle_keydown(event);
 });
 ```
 
@@ -805,10 +857,10 @@ Commands are wrapped in arrays to support fallback behavior:
 
 ```js
 define_keymap({
-  'meta+b,ctrl+b': [
-    document_commands.bold,      // Try this first
-    document_commands.fallback   // Use this if first is disabled
-  ]
+	'meta+b,ctrl+b': [
+		document_commands.bold, // Try this first
+		document_commands.fallback // Use this if first is disabled
+	]
 });
 ```
 
@@ -819,15 +871,15 @@ Use `push_scope()` and `pop_scope()` to manage different keyboard contexts:
 ```js
 // App-level keymap (always active)
 const app_keymap = define_keymap({
-  'meta+s,ctrl+s': [app_commands.save],
-  'meta+n,ctrl+n': [app_commands.new_document]
+	'meta+s,ctrl+s': [app_commands.save],
+	'meta+n,ctrl+n': [app_commands.new_document]
 });
 key_mapper.push_scope(app_keymap);
 
 // Document-level keymap (active when editor has focus)
 const doc_keymap = define_keymap({
-  'meta+z,ctrl+z': [document_commands.undo],
-  'meta+b,ctrl+b': [document_commands.bold]
+	'meta+z,ctrl+z': [document_commands.undo],
+	'meta+b,ctrl+b': [document_commands.bold]
 });
 
 // When editor gains focus:
@@ -839,7 +891,6 @@ key_mapper.pop_scope();
 
 The KeyMapper tries scopes from top to bottom, so push more specific keymaps last.
 
-
 ## Selection
 
 Selections are at the heart of Svedit. There are just three types of selections:
@@ -852,39 +903,39 @@ Selections are at the heart of Svedit. There are just three types of selections:
 
 1. **Text Selection**: A text selection spans across a range of characters in a string. E.g. the below example has a collapsed caret at position 1 in a text property 'content'.
 
-  ```js
-  {
-    type: 'text',
-    path: ['page_1234', 'body', 0, 'content'],
-    anchor_offset: 1,
-    focus_offset: 1
-  }
-  ```
+```js
+{
+  type: 'text',
+  path: ['page_1234', 'body', 0, 'content'],
+  anchor_offset: 1,
+  focus_offset: 1
+}
+```
 
 2. **Node Selection**: A node selection spans across a range of nodes inside a node_array. The below example selects the nodes at index 3 and 4.
 
-  ```js
-  {
-    type: 'node',
-    path: ['page_1234', 'body'],
-    anchor_offset: 2,
-    focus_offset: 4
-  }
-  ```
+```js
+{
+  type: 'node',
+  path: ['page_1234', 'body'],
+  anchor_offset: 2,
+  focus_offset: 4
+}
+```
 
 3. **Property Selection**: A property selection addresses one particular property of a node.
 
-  ```js
-  {
-    type: "property",
-    path: [
-      "page_1",
-      "body",
-      11,
-      "image"
-    ]
-  }
-  ```
+```js
+{
+  type: "property",
+  path: [
+    "page_1",
+    "body",
+    11,
+    "image"
+  ]
+}
+```
 
 You can access the current selection through `session.selection` anytime. And you can programmatically set the selection using `session.selection = new_selection`.
 
@@ -906,20 +957,21 @@ A typical node component follows this pattern:
 
 ```svelte
 <script>
-  import { Node, AnnotatedTextProperty } from 'svedit';
-  let { path } = $props();
+	import { Node, AnnotatedTextProperty } from 'svedit';
+	let { path } = $props();
 </script>
 
 <Node {path}>
-  <div class="my-node">
-    <AnnotatedTextProperty path={[...path, 'content']} />
-  </div>
+	<div class="my-node">
+		<AnnotatedTextProperty path={[...path, 'content']} />
+	</div>
 </Node>
 ```
 
 ### The `<Node>` wrapper
 
 Every node component must wrap its content in the `<Node>` component. This wrapper:
+
 - Registers the node with the editor
 - Handles selection and caret behavior
 - Provides the foundation for editing interactions
@@ -932,29 +984,36 @@ Svedit provides specialized components for rendering different property types:
 
 ```svelte
 <AnnotatedTextProperty
-  tag="p"
-  class="body"
-  path={[...path, 'content']}
-  placeholder="Enter text here"
+	tag="p"
+	class="body"
+	path={[...path, 'content']}
+	placeholder="Enter text here"
 />
 ```
 
 **`<NodeArrayProperty>`** - For container properties that hold multiple nodes:
 
 ```svelte
-<NodeArrayProperty 
-  class="list-items"
-  path={[...path, 'list_items']} 
-/>
+<NodeArrayProperty class="list-items" path={[...path, 'list_items']} />
 ```
 
+> **One path = one DOM mount.** Within a single Svedit document, each node path
+> may be mounted exactly once. Mounting the same path twice (e.g. rendering the
+> same `nav_items` array in both header and footer) breaks anchor positioning,
+> intersection tracking, id uniqueness, and selection mapping.
+> Svedit logs an error if it detects a duplicate mount.
+>
+> If you need to render shared content in multiple places, model it as distinct
+> node_arrays (`header_nav`, `footer_nav`) in the same document, or render it
+> from a separate Svedit instance.
+
 **`<CustomProperty>`** - For custom properties like images or other non-text content:
 
 ```svelte
 <CustomProperty class="image-wrapper" path={[...path, 'image']}>
-  <div contenteditable="false">
-    <img src={node.image} alt={node.title.text} />
-  </div>
+	<div contenteditable="false">
+		<img src={node.image} alt={node.title.text} />
+	</div>
 </CustomProperty>
 ```
 
@@ -964,12 +1023,12 @@ Use the Svedit context to access node data:
 
 ```svelte
 <script>
-  import { getContext } from 'svelte';
-  const svedit = getContext('svedit');
-  
-  let { path } = $props();
-  let node = $derived(svedit.session.get(path));
-  let layout = $derived(node.layout || 1);
+	import { getContext } from 'svelte';
+	const svedit = getContext('svedit');
+
+	let { path } = $props();
+	let node = $derived(svedit.session.get(path));
+	let layout = $derived(node.layout || 1);
 </script>
 ```
 
@@ -979,25 +1038,25 @@ Here's a complete example of a text node component that supports multiple layout
 
 ```svelte
 <script>
-  import { getContext } from 'svelte';
-  import { Node, AnnotatedTextProperty } from 'svedit';
-
-  const svedit = getContext('svedit');
-  let { path } = $props();
-  let node = $derived(svedit.session.get(path));
-  let layout = $derived(node.layout || 1);
-  let tag = $derived(layout === 1 ? 'p' : `h${layout - 1}`);
+	import { getContext } from 'svelte';
+	import { Node, AnnotatedTextProperty } from 'svedit';
+
+	const svedit = getContext('svedit');
+	let { path } = $props();
+	let node = $derived(svedit.session.get(path));
+	let layout = $derived(node.layout || 1);
+	let tag = $derived(layout === 1 ? 'p' : `h${layout - 1}`);
 </script>
 
 <Node {path}>
-  <div class="text layout-{layout}">
-    <AnnotatedTextProperty
-      {tag}
-      class="body"
-      path={[...path, 'content']}
-      placeholder="Enter text"
-    />
-  </div>
+	<div class="text layout-{layout}">
+		<AnnotatedTextProperty
+			{tag}
+			class="body"
+			path={[...path, 'content']}
+			placeholder="Enter text"
+		/>
+	</div>
 </Node>
 ```
 
@@ -1007,14 +1066,14 @@ A simple list component that renders child items:
 
 ```svelte
 <script>
-  import { Node, NodeArrayProperty } from 'svedit';
-  let { path } = $props();
+	import { Node, NodeArrayProperty } from 'svedit';
+	let { path } = $props();
 </script>
 
 <Node {path}>
-  <div class="list">
-    <NodeArrayProperty path={[...path, 'list_items']} />
-  </div>
+	<div class="list">
+		<NodeArrayProperty path={[...path, 'list_items']} />
+	</div>
 </Node>
 ```
 
@@ -1024,17 +1083,17 @@ Node components are registered in the document config's `node_components` map:
 
 ```js
 const session_config = {
-  node_components: {
-    Text,
-    Story,
-    List,
-    ListItem,
-    // ... other components
-  }
-}
+	node_components: {
+		text: Text,
+		story: Story,
+		list: List,
+		list_item: ListItem
+		// ... other components
+	}
+};
 ```
 
-The keys must be PascalCase versions of the snake_case node types in your schema. Svedit converts node types automatically (e.g. `list_item` → `ListItem`, `image_grid` → `ImageGrid`), so a node with `type: "list_item"` will look for a component registered as `ListItem`.
+The keys must be the snake_case node types in your schema. Svedit looks up node components directly by node type, so a node with `type: "list_item"` will look for a component registered as `list_item`.
 
 ## Mastering contenteditable
 
@@ -1043,8 +1102,8 @@ a simplified version of the markup of `<NodeGap>` and why it is implemented the
 
 ```html
 <div contenteditable="true">
-  <div class="some-wrapper">
-    <!--
+	<div class="some-wrapper">
+		<!--
       Putting a <br> tag into a div gives you a single addressable caret position.
 
       Adding a &ZeroWidthSpace; (or any character) here will lead to 2 caret
@@ -1056,8 +1115,8 @@ a simplified version of the markup of `<NodeGap>` and why it is implemented the
       Svedit uses this behavior for node gaps, and when an
       <AnnotatedTextProperty> is empty.
     -->
-    <div class="node-gap"><br></div>
-    <!--
+		<div class="node-gap"><br /></div>
+		<!--
       If you create a contenteditable="false" island, there needs to be some content in it,
       otherwise it will create two additional caret positions. One before, and another one
       after the island.
@@ -1065,8 +1124,8 @@ a simplified version of the markup of `<NodeGap>` and why it is implemented the
       The Svedit demo uses this technique in `<NodeGap>` to create a node-caret
       visualization, that doesn't mess with the contenteditable caret positions.
     -->
-    <div contenteditable="false" class="node-caret">&ZeroWidthSpace;</div>
-  </div>
+		<div contenteditable="false" class="node-caret">&ZeroWidthSpace;</div>
+	</div>
 </div>
 ```
 
@@ -1077,8 +1136,61 @@ Further things to consider:
 - Never apply `position: relative` to the direct parent of `<AnnotatedTextProperty>`, it will cause a [weird Safari bug](https://bsky.app/profile/michaelaufreiter.com/post/3lxvdqyxc622s) to destroy the DOM.
 - Never apply `position: relative`, `position: absolute`, `position: fixed` to `<Node.svelte>` (data-type="node") in edit mode. Only `position: static` is permitted to allow css anchor positioning queries to resolve correctly.
 - Never use an `<a>` tag inside a `contenteditable="true"` element, as it will cause unexpected behavior. Make it a `<div>` while editing, and an `<a>` in read-only mode (when `svedit.editable` is `false` ).
-- Avoid CSS selectors like `:last-child` or `:first-child` on nodes (e.g., `[data-type="node"]:last-child`) because `<NodeGap>` elements are inserted in edit mode and will become the actual first or last child. This can cause unexpected layout shifts (e.g., if you have `.paragraph-node:last-child { margin-bottom: 10px }`, the margin won't apply as expected).
-- Avoid adding css `margin` to nodes inside node arrays when using flex or grid layouts. Use `gap` on the container instead. This ensure `NodeGap` and `NodeGapMarkers` render consistently. If you need to add a margin, add it to child element of Node.
+- Avoid adding css `margin` to nodes inside node arrays when using flex or grid layouts. Use `gap` on the container instead. This ensures `NodeGap` and `NodeGapMarkers` render consistently. If you need to add a margin, add it to a child element of Node.
+
+### Consistent DOM structure across modes
+
+`<NodeArrayProperty>` always renders a `.node-gap` element before each node, regardless of whether the editor is in edit or read-only mode. In edit mode, this is the full `<NodeGap>` component with anchor positioning, hit areas, and caret support. In read-only mode, it's a plain `<div class="node-gap"></div>`.
+
+This means the DOM structure is identical in both modes:
+
+```html
+<!-- Same structure in edit and read-only mode -->
+<div data-type="node_array">
+	<div class="node-gap">...</div>
+	<!-- First element is a node-gap -->
+	<div data-type="node"><!-- first node --></div>
+	<div class="node-gap">...</div>
+	<div data-type="node"><!-- second node --></div>
+	...
+	<div class="node-gap">...</div>
+	<!-- Last element is a node-gap -->
+</div>
+```
+
+The `.node-gap` element uses `display: contents`, so it has no layout impact — it doesn't generate a box, doesn't affect flex/grid item counts, and doesn't consume space. It only serves as a DOM placeholder for consistent selector targeting.
+
+Because `.node-gap` is always the actual first and last child, do not use `:first-child` or `:last-child` on nodes — they will never match. Use `:nth-child(1 of [data-type="node"])` and `:nth-last-child(1 of [data-type="node"])` instead.
+
+CSS sibling selectors that target node adjacency only need one form:
+
+```css
+/* Works in both edit and read-only mode */
+.node-text + .node-gap + .node-media {
+	margin-block-start: 1rem;
+}
+```
+
+For `:nth-child` selectors, use the `of <selector>` syntax to skip over `.node-gap` elements and count only nodes:
+
+```css
+/* Even nodes */
+.list-node-array > :nth-child(2n of [data-type='node']) {
+	background: var(--zebra-stripe);
+}
+
+/* Odd nodes */
+.list-node-array > :nth-child(2n-1 of [data-type='node']) {
+	background: var(--zebra-stripe);
+}
+
+/* Last node */
+.list-node-array > :nth-last-child(1 of [data-type='node']) {
+	border-bottom: none;
+}
+```
+
+Without the `of` filter, plain `:nth-child(even)` would count `.node-gap` divs and produce incorrect results. The [`of <selector>`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:nth-child#syntax) form is Baseline 2023 and supported in all modern browsers.
 
 ### Node array CSS tokens
 
@@ -1088,9 +1200,9 @@ Further things to consider:
 
 ```css
 .my-horizontal-layout :global(.grid-items) {
-  --row: 1;
-  display: flex;
-  flex-wrap: wrap;
+	--row: 1;
+	display: flex;
+	flex-wrap: wrap;
 }
 ```
 
@@ -1099,11 +1211,11 @@ Further things to consider:
 ```
 Without --node-caret-boundary                  With --node-caret-boundary
 
-: . . . . . . . . . . . . . . . :      
+: . . . . . . . . . . . . . . . :
 : +---------------------------+ :             +-----------------------------+
 : | Toolbar / UI              | : ← overlap   | Toolbar / UI                |
 : +---------------------------+ :             +-----------------------------+
-:                               :      
+:                               :
 :     edge gap (unbounded)      :   boudary → +-----------------------------+
 : . . . . . . . . . . . . . . . :             | : . . . . . . . . . . . . : |
                                               | :   edge gap (clamped)    : |
@@ -1119,22 +1231,22 @@ Without --node-caret-boundary                  With --node-caret-boundary
                                               | :   edge gap (clamped)    : |
 : . . . . . . . . . . . . . . . :             | : . . . . . . . . . . . . : |
 :     edge gap (unbounded)      :   boudary → +-----------------------------+
-:                               :      
+:                               :
 : +---------------------------+ :             +-----------------------------+
 : | Footer / UI               | : ← overlap   | Footer / UI                 |
 : +---------------------------+ :             +-----------------------------+
-: . . . . . . . . . . . . . . . : 
+: . . . . . . . . . . . . . . . :
 ```
 
 Set `--node-caret-boundary` to the `anchor-name` of a parent element to clamp edge gaps to that element's edges:
 
 ```css
 .editor-wrapper {
-  anchor-name: --editor-boundary;
-  padding: 24px;
+	anchor-name: --editor-boundary;
+	padding: 24px;
 }
-.editor-wrapper [data-type="node_array"] {
-  --node-caret-boundary: --editor-boundary;
+.editor-wrapper [data-type='node_array'] {
+	--node-caret-boundary: --editor-boundary;
 }
 ```
 
@@ -1143,16 +1255,16 @@ When set, edge gaps clamp to the boundary element's edges instead. When not set,
 Since `--node-caret-boundary` inherits to nested node arrays, you may need to unset it on inner containers that should not be clamped:
 
 ```css
-.inner-container [data-type="node_array"] {
-  --node-caret-boundary: initial;
+.inner-container [data-type='node_array'] {
+	--node-caret-boundary: initial;
 }
 ```
 
 For per-axis control, use `--node-caret-boundary-x` (left/right) and `--node-caret-boundary-y` (top/bottom). They take precedence over `--node-caret-boundary` when set:
 
 ```css
-.editor-wrapper [data-type="node_array"] {
-  --node-caret-boundary-x: --editor-boundary;
+.editor-wrapper [data-type='node_array'] {
+	--node-caret-boundary-x: --editor-boundary;
 }
 ```