svedit 0.6.4 → 0.7.1

package/README.md

@@ -2,7 +2,8 @@
 
 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.
 
-Try the [demo](https://svedit.dev).
+- 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
 
 ## Why Svedit?
 
@@ -10,32 +11,24 @@ Because Svelte‘s reactivity system is **the perfect fit** for building super-l
 
 ## Getting started
 
-Clone the bare-bones `hello-svedit` repository:
+The fastest way to get started is to clone the `hello-svedit` template and turn it into your own project:
 
 ```bash
 git clone https://github.com/michael/hello-svedit
 cd hello-svedit
-```
-
-Install dependencies:
-
-```bash
 npm install
-```
-
-And run the development server:
-
-```bash
 npm run dev
 ```
 
 Now make it your own. The next thing you probably want to do is define your own [node types](./src/routes/create_demo_session.js), add a [Toolbar](./src/routes/components/Toolbar.svelte), and render custom [Overlays](./src/routes/components/Overlays.svelte). For that just get inspired by the [Svedit demo code](./src/routes).
 
+You can also install Svedit into an existing SvelteKit project with `npm install svedit`, but you'll need to set up the session, schema, config, and components yourself. See the [hello-svedit repo](https://github.com/michael/hello-svedit) or this repo's [`src/routes`](./src/routes) for reference.
+
 ## Principles
 
 **Simplicity over completeness:** Svedit doesn't guess what your app needs or offer ready-made blocks. Instead, we keep the core lean and provide carefully crafted examples showing how to build anything on top — without compromising flexibility.
 
-**White-box library:** We expose the internals of the library to allow you to customize and extend it to your needs. That means a little bit more work upfront, but in return lets you control "everything" — the toolbar, the overlays, or how fast the node cursor blinks.
+**White-box library:** We expose the internals of the library to allow you to customize and extend it to your needs. That means a little bit more work upfront, but in return lets you control "everything" — the toolbar, the overlays, or how fast the node caret blinks.
 
 **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.
 
@@ -69,15 +62,60 @@ Each node has a `kind` that determines its behavior:
 - `text`: A node with editable text content (can be split and joined)
 - `annotation`: An inline annotation applied to text (bold, link, etc.)
 
+### 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
+
+If **any** of those assumptions don't hold, use `kind: 'block'`. Blocks can still have `annotated_text` properties with full editing support (typing, formatting, selection) — they just don't participate in split/join.
+
+> **Common mistake:** A quote node with `content` + `author` properties might seem like `kind: 'text'` because both fields are editable text. But splitting a quote into two half-quotes doesn't make sense, and `join_text_node` hard-codes `node.content` — so Backspace in the `author` field would join the wrong property with the previous block and drop the author text. The correct kind is `'block'`.
+
+<details>
+<summary>Decision tree for choosing a node kind</summary>
+
+```mermaid
+flowchart TD
+    Start(["I need a new node type"])
+    Q1{"Is it inline formatting applied within text?"}
+    Q2{"Is it a top-level routable entry point?"}
+    Q3{"Is text the node's entire purpose?"}
+    Q4{"Does it have exactly one annotated_text property?"}
+    Q5{"Does pressing Enter to split into two nodes make sense?"}
+
+    KindAnnotation["kind: annotation e.g. bold, italic, link"]
+    KindDocument["kind: document e.g. page, article, event"]
+    KindBlock["kind: block e.g. image+caption, quote+author, list, nav, embed"]
+    KindText["kind: text e.g. paragraph, heading, list_item"]
+
+    Start --> Q1
+    Q1 -->|Yes| KindAnnotation
+    Q1 -->|No| Q2
+    Q2 -->|Yes| KindDocument
+    Q2 -->|No| Q3
+    Q3 -->|"No — it has non-text properties or children"| KindBlock
+    Q3 -->|Yes| Q4
+    Q4 -->|"No — multiple text properties"| KindBlock
+    Q4 -->|Yes| Q5
+    Q5 -->|"No — splitting doesn't make sense"| KindBlock
+    Q5 -->|Yes| KindText
+```
+
+</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
 - `boolean`: true or false
-- `string_array`: An array of good old JavaScript strings
-- `integer_array`: An array of integers
+- `datetime`: A date/time string parseable by `Date.parse()`
+- `string_array`: An array of strings
 - `number_array`: An array of numbers
-- `annotated_text`: a plain text string, but with annotations (bold, italic, link etc.)
+- `integer_array`: An array of integers
+- `boolean_array`: An array of booleans
+- `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)
@@ -99,13 +137,21 @@ const document_schema = {
   paragraph: {
     kind: 'text',
     properties: {
-      content: { type: 'annotated_text', allow_newlines: true }
+      content: {
+        type: 'annotated_text',
+        node_types: ['strong', 'emphasis', 'link'],
+        allow_newlines: true
+      }
     }
   },
   list_item: {
     kind: 'text',
     properties: {
-      content: { type: 'annotated_text', allow_newlines: true },
+      content: {
+        type: 'annotated_text',
+        node_types: ['strong', 'emphasis', 'link'],
+        allow_newlines: true
+      },
     }
   },
   list: {
@@ -134,10 +180,26 @@ const document_schema = {
       url: { type: 'string' },
       label: { type: 'string' },
     }
+  },
+  strong: {
+    kind: 'annotation',
+    properties: {}
+  },
+  emphasis: {
+    kind: 'annotation',
+    properties: {}
+  },
+  link: {
+    kind: 'annotation',
+    properties: {
+      href: { type: 'string' }
+    }
   }
 };
 ```
 
+Annotation types are defined as nodes with `kind: 'annotation'`. Simple annotations like `strong` and `emphasis` have no properties, while annotations like `link` can carry data (e.g. `href`). Each `annotated_text` property specifies which annotation types are allowed via `node_types` — this lets you control formatting per property (e.g. allow bold and links in body text, but only emphasis in titles).
+
 ## Document
 
 A document is a plain JavaScript object (POJO) with a `document_id` (the entry point) and a `nodes` object containing all content nodes.
@@ -166,8 +228,7 @@ const doc = {
     },
     paragraph_1: {
       id: 'paragraph_1',
-      type: 'text',
-      layout: 1,
+      type: 'paragraph',
       content: { text: 'Hello world.', annotations: [] }
     },
     list_item_1: {
@@ -203,8 +264,8 @@ const session_config = {
   // ID generator for creating new nodes
   generate_id: () => nanoid(),
   
-  // System components (NodeCursorTrap, Overlays) 
-  system_components: { NodeCursorTrap, Overlays },
+  // User-land overlays and optional system component overrides
+  system_components: { Overlays },
   
   // Map node types to Svelte components
   node_components: { Page, Text, Story, List, Button, ... },
@@ -230,7 +291,9 @@ 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`** - Provides custom NodeCursorTrap and Overlays components
+- **`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.
 - **`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
@@ -268,7 +331,7 @@ session.kind(node)                      // => 'text', 'block', or 'annotation'
 ```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 cursor
+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)
 ```
@@ -333,7 +396,7 @@ Transforms are pure functions that modify a transaction. They encapsulate common
 Transforms take a transaction (`tr`) as their parameter and return `true` if successful or `false` if the transform cannot be applied (e.g., wrong selection type or invalid state).
 
 ```js
-// Example: break a text node at the cursor
+// Example: break a text node at the caret
 import { break_text_node } from 'svedit';
 
 const tr = session.tr;
@@ -347,7 +410,7 @@ if (success) {
 
 Svedit provides several core transforms in [`src/lib/transforms.svelte.js`](src/lib/transforms.svelte.js):
 
-- `break_text_node(tr)` - Split a text node at the cursor position
+- `break_text_node(tr)` - Split a text node at the caret position
 - `join_text_node(tr)` - Join current text node with the previous one
 - `insert_default_node(tr)` - Insert a new node at the current selection
 
@@ -377,7 +440,7 @@ function insert_heading(tr) {
   // 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(selection.path, selection.anchor_offset, [heading_id]);
+  tr.insert_nodes([heading_id]);
   
   return true;
 }
@@ -413,7 +476,7 @@ const new_node_id = tr.build('the_list', {
 		id: 'first_item',
 		type: 'list_item',
 		content: node.content
-	}
+	},
 	the_list: {
 		id: 'the_list',
 		type: 'list',
@@ -425,7 +488,7 @@ const new_node_id = tr.build('the_list', {
 ### Text operations
 
 ```js
-// Insert text at cursor (replaces selection if expanded)
+// Insert text at caret (replaces selection if expanded)
 tr.insert_text('Hello');
 
 // Toggle annotation on selected text
@@ -530,9 +593,9 @@ Svedit provides several [core commands](src/lib/Command.svelte.js) out of the bo
 - `SelectParentCommand` - Select the parent of the current selection
 - `ToggleAnnotationCommand` - Toggle text annotations (bold, italic, etc.)
 - `AddNewLineCommand` - Insert newline character in text
-- `BreakTextNodeCommand` - Split text node at cursor
+- `BreakTextNodeCommand` - Split text node at caret
 - `SelectAllCommand` - Progressively expand selection
-- `InsertDefaultNodeCommand` - Insert a new node at cursor
+- `InsertDefaultNodeCommand` - Insert a new node at caret
 
 #### Using document commands
 
@@ -757,7 +820,13 @@ The KeyMapper tries scopes from top to bottom, so push more specific keymaps las
 
 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 cursor at position 1 in a text property 'content'.
+### Terminology note
+
+- Use "node" as the domain term.
+- Use "node caret" for a collapsed node selection.
+- Use "node gap" for the DOM landing zone between nodes.
+
+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
   {
@@ -828,7 +897,7 @@ A typical node component follows this pattern:
 
 Every node component must wrap its content in the `<Node>` component. This wrapper:
 - Registers the node with the editor
-- Handles selection and cursor behavior
+- Handles selection and caret behavior
 - Provides the foundation for editing interactions
 
 ### Property components
@@ -941,38 +1010,38 @@ const session_config = {
 }
 ```
 
-The key in this map corresponds to the node's `type` property in the schema. Note that the component name should match the node type name. For example, a node with `type: "list_item"` will look for a component registered as `ListItem` in the `node_components` map.
+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`.
 
 ## Mastering contenteditable
 
 Svedit relies on the contenteditable attribute to make elements editable. The below example shows you
-a simplified version of the markup of `<NodeCursorTrap>` and why it is implemented the way it is.
+a simplified version of the markup of `<NodeGap>` and why it is implemented the way it is.
 
 ```html
 <div contenteditable="true">
   <div class="some-wrapper">
     <!--
-      Putting a <br> tag into a div gives you a single addressable cursor position.
+      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 cursor
+      Adding a &ZeroWidthSpace; (or any character) here will lead to 2 caret
       positions (one before, and one after the character)
 
       Using <wbr> will make it only addressable for ArrowLeft and ArrowRight, but not ArrowUp and ArrowDown.
       And using <span></span> will not make it addressable at all.
 
-      Svedit uses this behavior for node-cursor-traps, and when an
+      Svedit uses this behavior for node gaps, and when an
       <AnnotatedTextProperty> is empty.
     -->
-    <div class="cursor-trap"><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 cursor positions. One before, and another one
+      otherwise it will create two additional caret positions. One before, and another one
       after the island.
 
-      The Svedit demo uses this technique in `<NodeCursorTrap>` to create a node-cursor
-      visualization, that doesn't mess with the contenteditable cursor positions.
+      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-cursor">&ZeroWidthSpace;</div>
+    <div contenteditable="false" class="node-caret">&ZeroWidthSpace;</div>
   </div>
 </div>
 ```
@@ -982,11 +1051,14 @@ Further things to consider:
 - If you make a sub-tree `contenteditable="false"`, be aware that you can't create a `contenteditable="true"` segment somewhere inside it. Svedit can only work reliably when there's one contenteditable="true" at root (it's set by `<Svedit`>)
 - `<AnnotatedTextProperty>` and `<CustomProperty>` must not be wrapped in `contenteditable="false"` to work properly.
 - 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.
 
-## Full API docs?
+## Beyond the README
 
-Not yet. Please just [read the code](./src) for now. It's only a couple of files with less than 3000 LOC in total. The files in `routes` are considered example code (copy them and adapt them to your needs), while files in `lib` are considered library code. Read them to understand the API and what's happening behind the scenes.
+The source code is compact and readable — less than 3000 LOC across a handful of files. We encourage you to explore it. The files in [`src/lib`](./src/lib) are the library code, while the files in [`src/routes`](./src/routes) are example code you can copy and adapt to your needs.
 
 ## Developing Svedit
 

package/dist/AnnotatedTextProperty.svelte

@@ -7,7 +7,7 @@
 	const svedit = getContext('svedit');
 
 	/** @type {AnnotatedTextPropertyProps} */
-	let { path, class: css_class, placeholder = '', tag = 'div' } = $props();
+	let { path, class: css_class, placeholder = '', tag = 'div', style = '', ...rest } = $props();
 
 	let is_focused = $derived.by(() => {
 		return (
@@ -26,7 +26,12 @@
 	);
 
 	// Get selection highlight range if not inside an annotation
+	// Only render selection highlight when canvas is NOT focused.
+	// This avoids DOM mutations (splitting text nodes for highlight spans)
+	// while the user is actively selecting, which would cause selection
+	// feedback loops and scroll-to-focus issues.
 	let selection_highlight_range = $derived.by(() => {
+		if (svedit.canvas_focused) return null;
 		if (is_collapsed) return null;
 		if (!is_focused) return null;
 		if (svedit.session.active_annotation()) return null;
@@ -101,18 +106,19 @@
 <!-- ATTENTION: The comments are needed to prevent unwanted text nodes with whitespace. -->
 <!-- We need to use <br> so the element is reachable by Arrow Up/Down navigation. -->
 <!-- But as soon as the element is focused, we get rid of the <br> as it causes issues with caret positioning. -->
-<!-- Before, we were just hiding it on focus, but that caused the cursor to disappear on Safari Desktop (tested with v26). -->
+<!-- Before, we were just hiding it on focus, but that caused the caret to disappear on Safari Desktop (tested with v26). -->
 <!-- Edge Case: Shift Enter stops working if <br> is not present on a non-empty text property. -->
 <svelte:element
 	this={tag}
 	data-type="text"
 	data-path={path.join('.')}
-	style="anchor-name: --{path.join('-')};"
+	style="anchor-name: --{path.join('-')};{style}"
 	class="text svedit-selectable {css_class}"
 	class:empty={is_empty}
 	class:focused={is_focused}
 	class:editable={svedit.editable}
 	{placeholder}
+	{...rest}
 >
 	{#each fragments as fragment, index (index)}
 		{#if typeof fragment === 'string'}{fragment}{:else if fragment.type === 'selection_highlight'}<span
@@ -135,10 +141,6 @@
 		white-space: pre-wrap;
 		overflow-wrap: anywhere;
 		box-sizing: content-box;
-
-		&.heading1 {
-			text-wrap: var(--text-wrap);
-		}
 	}
 	/* We switch from ::before to ::after when the element is focused. So the the caret is always before the placeholder. */
 	[placeholder].empty:not(.focused)::before,
@@ -153,24 +155,19 @@
 		caret-color: transparent;
 	}
 
-	/*.text.focused {
-    background: none;
-    outline: 1px solid var(--editing-stroke-color);
-  }*/
-
 	/* Disable text-transform when editable and focused so users see original text */
 	.text.editable.focused {
 		text-transform: none !important;
 	}
 
 	/* Dim the selection highlight when canvas loses native focus */
-	:global(.svedit-canvas:not(:focus)) .selection-highlight {
-		background: oklch(from var(--editing-fill-color) l 0.02 h / 0.3);
+	:global(.svedit-canvas:not(:focus-within)) .selection-highlight {
+		background: oklch(from var(--svedit-editing-fill) l 0 h / alpha);
 	}
 
-	/* Make a collapsed cursor visible */
-	:global(.svedit-canvas:not(:focus)) .selection-highlight:empty {
+	/* Make a collapsed caret visible */
+	:global(.svedit-canvas:not(:focus-within)) .selection-highlight:empty {
 		background: none;
-		outline: 0.5px solid oklch(from var(--editing-stroke-color) l 0.02 h / 0.3);
+		outline: 0.5px solid oklch(from var(--svedit-editing-stroke) l 0 h / alpha);
 	}
 </style>

package/dist/AnnotatedTextProperty.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnnotatedTextProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AnnotatedTextProperty.svelte.js"],"names":[],"mappings":";;;;;AA6HA,2HAAoE"}
+{"version":3,"file":"AnnotatedTextProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AnnotatedTextProperty.svelte.js"],"names":[],"mappings":";;;;;AAkIA,2HAAoE"}

package/dist/Command.svelte.d.ts

@@ -84,7 +84,7 @@ export class ToggleAnnotationCommand extends Command {
     execute(): void;
 }
 /**
- * Command that adds a new line character at the current cursor position.
+ * Command that adds a new line character at the current caret position.
  * Only works in text selections where newlines are allowed.
  * Disabled on mobile browsers where Shift+Enter has different behavior.
  */
@@ -93,7 +93,7 @@ export class AddNewLineCommand extends Command {
     execute(): void;
 }
 /**
- * Command that breaks a text node at the cursor position.
+ * Command that breaks a text node at the caret position.
  * Creates a new node and splits the content between the current and new node.
  * Only works in text selections.
  */
@@ -109,7 +109,7 @@ export class SelectAllCommand extends Command {
     execute(): void;
 }
 /**
- * Command that inserts a default node at the current cursor position.
+ * Command that inserts a default node at the current caret position.
  * Only works when a collapsed node selection is active.
  */
 export class InsertDefaultNodeCommand extends Command {

package/dist/Command.svelte.js

@@ -120,13 +120,13 @@ export class ToggleAnnotationCommand extends Command {
 	is_enabled() {
 		const { session, editable } = this.context;
 		const has_annotation = session.active_annotation(this.node_type);
-		const no_annotation_and_cursor_not_collapsed =
+		const no_annotation_and_caret_not_collapsed =
 			!session.active_annotation() && !is_selection_collapsed(session.selection);
 
 		return (
 			editable &&
 			session.selection?.type === 'text' &&
-			(has_annotation || no_annotation_and_cursor_not_collapsed)
+			(has_annotation || no_annotation_and_caret_not_collapsed)
 		);
 	}
 
@@ -136,7 +136,7 @@ export class ToggleAnnotationCommand extends Command {
 }
 
 /**
- * Command that adds a new line character at the current cursor position.
+ * Command that adds a new line character at the current caret position.
  * Only works in text selections where newlines are allowed.
  * Disabled on mobile browsers where Shift+Enter has different behavior.
  */
@@ -159,7 +159,7 @@ export class AddNewLineCommand extends Command {
 }
 
 /**
- * Command that breaks a text node at the cursor position.
+ * Command that breaks a text node at the caret position.
  * Creates a new node and splits the content between the current and new node.
  * Only works in text selections.
  */
@@ -293,7 +293,7 @@ export class SelectAllCommand extends Command {
 }
 
 /**
- * Command that inserts a default node at the current cursor position.
+ * Command that inserts a default node at the current caret position.
  * Only works when a collapsed node selection is active.
  */
 export class InsertDefaultNodeCommand extends Command {

package/dist/CustomProperty.svelte

@@ -5,7 +5,7 @@
 	const svedit = getContext('svedit');
 
 	/** @type {CustomPropertyProps} */
-	let { path, tag = 'div', class: css_class, children } = $props();
+	let { path, tag = 'div', class: css_class, children, style, ...rest } = $props();
 </script>
 
 <svelte:element
@@ -13,10 +13,11 @@
 	class={css_class}
 	data-type="property"
 	data-path={path.join('.')}
-	style="anchor-name: --{path.join('-')};"
+	style="anchor-name: --{path.join('-')};{style ? ` ${style}` : ''}"
+	{...rest}
 >
 	{#if svedit.editable}
-		<div class="cursor-trap">
+		<div class="property-selectable">
 			<div class="svedit-selectable"><br /></div>
 		</div>
 	{/if}
@@ -28,7 +29,7 @@
 	[data-type='property'] {
 		position: relative;
 	}
-	.cursor-trap {
+	.property-selectable {
 		position: absolute;
 		top: 0;
 		left: 0;

package/dist/Node.svelte

@@ -1,21 +1,33 @@
 <script>
 	import { getContext } from 'svelte';
+	import DefaultNodeGap from './NodeGap.svelte';
 
 	/** @import { NodeProps } from './types.d.ts'; */
 
 	const svedit = getContext('svedit');
-	let NodeCursorTrap = $derived(svedit.session.config.system_components.NodeCursorTrap);
+	let NodeGap = $derived(svedit.session.config.system_components?.NodeGap ?? DefaultNodeGap);
 
 	/** @type {NodeProps} */
-	let { path, children, tag = 'div', class: css_class } = $props();
+	let { path, children, tag = 'div', class: css_class, style = '', ...rest } = $props();
 
-	// NOTE: When the next to last path segment is a node_array property, the node is wrapped in a node_array
-	let is_inside_node_array = $derived(
-		path.length > 1 && svedit.session.inspect(path.slice(0, -1))?.type === 'node_array'
-	);
 	let node = $derived(svedit.session.get(path));
-	let is_first_node_array_child = $derived(
-		is_inside_node_array && parseInt(String(path.at(-1)), 10) === 0
+
+	// NodeArrayProperty sets this context — its presence means we're in a node_array.
+	// Using context avoids expensive session.inspect() and session.get() calls
+	// that would create O(N) reactive subscriptions to the parent array.
+	const node_array_meta = getContext('node_array_meta');
+	const is_inside_node_array = !!node_array_meta;
+	let child_index = $derived(parseInt(String(path.at(-1)), 10));
+	let is_first_node_array_child = $derived(is_inside_node_array && child_index === 0);
+	let is_last_node_array_child = $derived(
+		is_inside_node_array && child_index === node_array_meta.length - 1
+	);
+
+	// Drives lazy anchor positioning for node gaps. Gaps are always in the
+	// DOM (stable structure for selection), but only anchor-positioned when
+	// near the viewport to avoid O(N) layout cost.
+	let is_near_viewport = $derived(
+		svedit.is_near_viewport?.(path) ?? true
 	);
 </script>
 
@@ -26,19 +38,22 @@
 	data-node-id={node.id}
 	data-path={path.join('.')}
 	data-type="node"
-	style="anchor-name: --{path.join('-')};"
+	style="anchor-name: --{path.join('-')};{style}"
+	{...rest}
 >
 	{#if svedit.editable && is_first_node_array_child}
-		<NodeCursorTrap {path} type="position-zero-cursor-trap" />
+		<NodeGap {path} type="gap-before" positioned={is_near_viewport} />
 	{/if}
 	{@render children()}
 	{#if svedit.editable && is_inside_node_array}
-		<NodeCursorTrap {path} type="after-node-cursor-trap" />
+		<NodeGap {path} type="gap-after" last={is_last_node_array_child} positioned={is_near_viewport} />
 	{/if}
 </svelte:element>
 
 <style>
-	div {
-		position: relative;
+	[data-type='node'] {
+		/** any other position than static will break the anchor positioning of node gaps and node gap-marker */
+		/* For developers who need to position their node with `position: absolute` or `position: relative`, they need to wrap their node in a div */
+		position: static !important;
 	}
-</style>
+</style>

package/dist/Node.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Node.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Node.svelte.js"],"names":[],"mappings":";;;;;AAwCA,yFAAmD"}
+{"version":3,"file":"Node.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Node.svelte.js"],"names":[],"mappings":";;;;;AAoDA,yFAAmD"}