svedit 0.6.4 → 0.7.0

package/dist/types.d.ts

@@ -93,59 +93,53 @@ export type PrimitiveType = ScalarType | ArrayType | RichType;
  */
 export type PropertyType = PrimitiveType | ReferenceType;
 
-/**
- * Document schema primitive types - all possible property types in document schemas.
- */
-export type DocumentSchemaPrimitive =
-	| 'string'
-	| 'number'
-	| 'boolean'
-	| 'integer'
-	| 'datetime'
-	| 'string_array'
-	| 'number_array'
-	| 'boolean_array'
-	| 'integer_array'
-	| 'annotated_text'
-	| 'node'
-	| 'node_array';
-
-/**
- * Maps document schema types to their JavaScript runtime types.
- */
-export type DocumentSchemaValueToJs<T> = T extends 'string'
-	? string
-	: T extends 'number'
-		? number
-		: T extends 'boolean'
-			? boolean
-			: T extends 'integer'
-				? number
-				: T extends 'datetime'
-					? string
-					: T extends 'string_array'
-						? Array<string>
-						: T extends 'number_array'
-							? Array<number>
-							: T extends 'boolean_array'
-								? Array<boolean>
-								: T extends 'integer_array'
-									? Array<number>
-									: T extends 'annotated_text'
-										? AnnotatedText
-										: T extends 'node'
-											? string
-											: T extends 'node_array'
-												? Array<string>
-												: never;
-
-/**
- * Converts a document node schema definition to its inferred JS type.
- * Handles the {type: "..."} wrapper structure used in document schemas.
- */
-export type DocumentNodeToJs<S extends NodeSchema> = { id: string; type: string } & {
-	[K in keyof S['properties']]: DocumentSchemaValueToJs<S['properties'][K]['type']>;
-};
+// TODO: We may later want more sophisticated type inference, so that typing
+// e.g. `session.get('image')` auto-completes the node's properties based on
+// the schema definition. The types below are a starting point for that.
+//
+// export type DocumentSchemaPrimitive =
+// 	| 'string'
+// 	| 'number'
+// 	| 'boolean'
+// 	| 'integer'
+// 	| 'datetime'
+// 	| 'string_array'
+// 	| 'number_array'
+// 	| 'boolean_array'
+// 	| 'integer_array'
+// 	| 'annotated_text'
+// 	| 'node'
+// 	| 'node_array';
+//
+// export type DocumentSchemaValueToJs<T> = T extends 'string'
+// 	? string
+// 	: T extends 'number'
+// 		? number
+// 		: T extends 'boolean'
+// 			? boolean
+// 			: T extends 'integer'
+// 				? number
+// 				: T extends 'datetime'
+// 					? string
+// 					: T extends 'string_array'
+// 						? Array<string>
+// 						: T extends 'number_array'
+// 							? Array<number>
+// 							: T extends 'boolean_array'
+// 								? Array<boolean>
+// 								: T extends 'integer_array'
+// 									? Array<number>
+// 									: T extends 'annotated_text'
+// 										? AnnotatedText
+// 										: T extends 'node'
+// 											? string
+// 											: T extends 'node_array'
+// 												? Array<string>
+// 												: never;
+//
+// export type DocumentNodeToJs<S extends NodeSchema> = { id: string; type: string } & {
+// 	[K in keyof S['properties']]: DocumentSchemaValueToJs<S['properties'][K]['type']>;
+// };
 
 /**
  * A property that stores an annotated text with required allow_newlines setting.
@@ -337,6 +331,8 @@ export type AnnotatedTextPropertyProps = {
 	class?: string;
 	/** A placeholder to be rendered for empty content */
 	placeholder?: string;
+	/** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
+	[key: string]: any;
 };
 
 /**
@@ -351,6 +347,8 @@ export type CustomPropertyProps = {
 	class?: string;
 	/** The content of the custom property (e.g. an image) */
 	children: Snippet;
+	/** Rest props to spread onto the rendered element */
+	[key: string]: any;
 };
 
 /**
@@ -361,10 +359,10 @@ export type NodeArrayPropertyProps = {
 	path: DocumentPath;
 	/** Optional custom HTML tag */
 	tag?: string;
-	/** Optional custom HTML tag */
-	tag?: string;
 	/** The `class` attribute on the container element */
 	class?: string;
+	/** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
+	[key: string]: any;
 };
 
 /**
@@ -379,22 +377,12 @@ export type NodeProps = {
 	class?: string;
 	/** The type-specific content of the node */
 	children: Snippet;
+	/** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
+	[key: string]: any;
 };
 
 /**
- * Props for the CustomProperty component
- */
-export type CustomPropertyProps = {
-	/** The full path to the property */
-	path: DocumentPath;
-	/** The `class` attribute on the content element */
-	class?: string;
-	/** The content of the custom property (e.g. an image) */
-	children: Snippet;
-};
-
-/**
- * Props for the CustomProperty component
+ * Props for the Svedit component
  */
 export type SveditProps = {
 	/** The session instance */

package/dist/utils.d.ts

@@ -1,6 +1,3 @@
-/**
- * @import { Annotation, AnnotatedText, SelectionRange, Selection } from './types.d.ts';
- */
 /**
  * Detect if the current browser is on a mobile device
  * @returns {boolean} true if mobile browser, false otherwise

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/lib/utils.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,qCAFa,OAAO,CAanB;AAED;;;GAGG;AACH,6CAFa,OAAO,CAUnB;AAED;;;;;;;;;;;;;GAaG;AACH,qCARW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;;;;GAcG;AACH,iCATW,MAAM,SACN,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;;;;;;;;;;GAcG;AACH,gCATW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CAalB;AAED;;;;;;;;;;;;;GAaG;AACH,0CARW,MAAM,gBACN,MAAM,GACJ,MAAM,CAoBlB;AAED;;;;;;;;;;;;;GAaG;AACH,0CARW,MAAM,eACN,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,4DAZW,aAAa,eACb,MAAM,GACJ,CAAC,aAAa,EAAE,aAAa,CAAC,CA6C1C;AAED;;;;;;;;;;;;;GAaG;AACH,gDARW,aAAa,eACb,aAAa,GACX,aAAa,CA4CzB;AAED;;;;;;;;GAQG;AACH,qCANW,MAAM,GACJ,MAAM,CAUlB;AAED,uEAgCC;AAED;;;;;GAKG;AACH,gDAHW,SAAS,GACP,cAAc,GAAG,IAAI,CAWjC;AAED,gEAMC;mCAhVwE,cAAc;+BAAd,cAAc;oCAAd,cAAc"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/lib/utils.js"],"names":[],"mappings":"AAMA;;;GAGG;AACH,qCAFa,OAAO,CAanB;AAGD;;;GAGG;AACH,6CAFa,OAAO,CAUnB;AAED;;;;;;;;;;;;;GAaG;AACH,qCARW,MAAM,GACJ,MAAM,CASlB;AAID;;;;;;;;;;;;;;GAcG;AACH,iCATW,MAAM,SACN,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;;;;GAcG;AACH,gCATW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;;;;;GAaG;AACH,0CARW,MAAM,gBACN,MAAM,GACJ,MAAM,CAmBlB;AAED;;;;;;;;;;;;;GAaG;AACH,0CARW,MAAM,eACN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,4DAZW,aAAa,eACb,MAAM,GACJ,CAAC,aAAa,EAAE,aAAa,CAAC,CA6C1C;AAED;;;;;;;;;;;;;GAaG;AACH,gDARW,aAAa,eACb,aAAa,GACX,aAAa,CA4CzB;AAED;;;;;;;;GAQG;AACH,qCANW,MAAM,GACJ,MAAM,CAUlB;AAED,uEAgCC;AAED;;;;;GAKG;AACH,gDAHW,SAAS,GACP,cAAc,GAAG,IAAI,CAWjC;AAED,gEAMC;mCAhVwE,cAAc;+BAAd,cAAc;oCAAd,cAAc"}

package/dist/utils.js

@@ -2,6 +2,8 @@
  * @import { Annotation, AnnotatedText, SelectionRange, Selection } from './types.d.ts';
  */
 
+const SEGMENTER = new Intl.Segmenter('en', { granularity: 'grapheme' });
+
 /**
  * Detect if the current browser is on a mobile device
  * @returns {boolean} true if mobile browser, false otherwise
@@ -19,6 +21,7 @@ export function is_mobile_browser() {
 	);
 }
 
+// ‼️‼️‼️‼️‼️‼️ UNUSED UTILITY BELOW ‼️‼️‼️‼️‼️‼️ 
 /**
  * Detect if the current browser is Chrome on desktop
  * @returns {boolean} true if Chrome desktop browser, false otherwise
@@ -48,10 +51,11 @@ export function is_chrome_desktop_browser() {
  * get_char_length('👋🏽') // Returns: 1 (not 4 - skin tone modifier treated as single char)
  */
 export function get_char_length(str) {
-	const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
-	return [...segmenter.segment(str)].length;
+	return [...SEGMENTER.segment(str)].length;
 }
 
+
+// ‼️‼️‼️‼️‼️‼️ UNUSED UTILITY BELOW ‼️‼️‼️‼️‼️‼️ 
 /**
  * Get a single character at the specified position (accounting for multi-byte characters)
  *
@@ -68,8 +72,7 @@ export function get_char_length(str) {
  * get_char_at('👋🏽', 0) // Returns: '👋🏽' (skin tone modifier included)
  */
 export function get_char_at(str, index) {
-	const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
-	const segments = [...segmenter.segment(str)];
+	const segments = [...SEGMENTER.segment(str)];
 	return segments[index].segment;
 }
 
@@ -89,8 +92,7 @@ export function get_char_at(str, index) {
  * char_slice('a👋🏽b', 1, 2) // Returns: '👋🏽' (skin tone modifier included)
  */
 export function char_slice(str, start, end = undefined) {
-	const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
-	const segments = [...segmenter.segment(str)];
+	const segments = [...SEGMENTER.segment(str)];
 	return segments
 		.slice(start, end)
 		.map((s) => s.segment)
@@ -112,8 +114,7 @@ export function char_slice(str, start, end = undefined) {
  * utf16_to_char_offset("a😀b", 3) // Returns: 2 (position after emoji)
  */
 export function utf16_to_char_offset(str, utf16_offset) {
-	const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
-	const segments = [...segmenter.segment(str)];
+	const segments = [...SEGMENTER.segment(str)];
 	let char_offset = 0;
 	let utf16_count = 0;
 
@@ -142,8 +143,7 @@ export function utf16_to_char_offset(str, utf16_offset) {
  * char_to_utf16_offset("a😀b", 2) // Returns: 3 (UTF-16 position after emoji)
  */
 export function char_to_utf16_offset(str, char_offset) {
-	const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
-	const segments = [...segmenter.segment(str)];
+	const segments = [...SEGMENTER.segment(str)];
 	let utf16_offset = 0;
 
 	for (let i = 0; i < Math.min(char_offset, segments.length); i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svedit",
-	"version": "0.6.4",
+	"version": "0.7.0",
 	"license": "MIT",
 	"scripts": {
 		"dev": "vite dev",
@@ -39,29 +39,29 @@
 		"svelte": "^5.0.0"
 	},
 	"devDependencies": {
-		"@eslint/compat": "^1.4.1",
-		"@eslint/js": "^9.39.1",
+		"@eslint/compat": "^2.0.3",
+		"@eslint/js": "^10.0.1",
 		"@sveltejs/adapter-auto": "^7.0.0",
-		"@sveltejs/kit": "^2.48.4",
-		"@sveltejs/package": "^2.5.4",
-		"@sveltejs/vite-plugin-svelte": "^6.2.1",
-		"@typescript-eslint/eslint-plugin": "^8.46.3",
-		"@typescript-eslint/parser": "^8.46.3",
-		"@vitest/browser": "^4.0.8",
-		"@vitest/browser-preview": "^4.0.8",
-		"eslint": "^9.39.1",
+		"@sveltejs/kit": "^2.55.0",
+		"@sveltejs/package": "^2.5.7",
+		"@sveltejs/vite-plugin-svelte": "^7.0.0",
+		"@typescript-eslint/eslint-plugin": "^8.57.0",
+		"@typescript-eslint/parser": "^8.57.0",
+		"@vitest/browser": "^4.1.0",
+		"@vitest/browser-preview": "^4.1.0",
+		"eslint": "^10.0.3",
 		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-svelte": "^3.13.0",
-		"globals": "^16.5.0",
+		"eslint-plugin-svelte": "^3.15.1",
+		"globals": "^17.4.0",
 		"nanoid": "^5.1.6",
-		"prettier": "^3.6.2",
-		"prettier-plugin-svelte": "^3.4.0",
-		"publint": "^0.3.15",
-		"svelte": "^5.43.4",
-		"svelte-check": "^4.3.3",
-		"vite": "^7.2.2",
+		"prettier": "^3.8.1",
+		"prettier-plugin-svelte": "^3.5.1",
+		"publint": "^0.3.18",
+		"svelte": "^5.53.12",
+		"svelte-check": "^4.4.5",
+		"vite": "^8.0.0",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.8",
-		"vitest-browser-svelte": "^2.0.1"
+		"vitest": "^4.1.0",
+		"vitest-browser-svelte": "^2.1.0"
 	}
 }

package/src/lib/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/src/lib/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/src/lib/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/src/lib/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/src/lib/NodeArrayProperty.svelte

@@ -1,24 +1,39 @@
 <script>
-	import { getContext } from 'svelte';
+	import { getContext, setContext } from 'svelte';
 	import UnknownNode from './UnknownNode.svelte';
 	import { snake_to_pascal } from './utils.js';
+	import DefaultNodeGap from './NodeGap.svelte';
+	import DefaultNodeGapMarkers from './NodeGapMarkers.svelte';
 
 	/** @import { NodeArrayPropertyProps } 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);
+	let NodeGapMarkers = $derived(svedit.session.config.system_components?.NodeGapMarkers ?? DefaultNodeGapMarkers);
 
 	/** @type {NodeArrayPropertyProps} */
-	let { path, tag = 'div', class: css_class } = $props();
+	let { path, tag = 'div', class: css_class, style = '', ...rest } = $props();
 
 	let nodes = $derived(
 		svedit.session
 			.get(path)
 			.map(/** @param {string} node_id */ (node_id) => svedit.session.get(node_id))
 	);
-</script>
 
-<svelte:element this={tag} class={css_class} data-type="node_array" data-path={path.join('.')}>
+	// Expose array metadata to child Node.svelte instances via context,
+	// avoiding expensive session.inspect() / session.get() calls per node.
+	setContext('node_array_meta', {
+		get length() { return nodes.length; }
+	});
+</script>
+<!-- we use the anchor of node_array in Overlays.svelte to position the last insertion point in a horizontal layout based on the right edge of the container -->
+<svelte:element 
+	this={tag} 
+	class={css_class} 
+	data-type="node_array" 
+	data-path={path.join('.')} 
+	style="anchor-name: --{path.join('-')};{style ? ` ${style}` : ''}" {...rest}
+>
 	{#if nodes.length === 0 && svedit.editable}
 		<!--
 		Experimental: We'll let .empty-node-array act like a node, so the existing
@@ -32,10 +47,12 @@
 			data-type="node"
 			style="anchor-name: --{[...path, 0].join(
 				'-'
-			)}; position: relative; min-height: 40px; min-width: 40px;"
-		>
-			<NodeCursorTrap path={[...path, 0]} type="position-zero-cursor-trap" />
-		</div>
+			)}; min-height: 40px; min-width: 24px;"
+		></div>
+		<!-- Sibling (not child) of .empty-node-array so its .svedit-selectable
+		     resolves anchor positioning against the shared containing block,
+		     not the placeholder which inherits .node positioning styles. -->
+		<NodeGap path={[...path, 0]} type="gap-before" empty />
 	{/if}
 	{#each nodes as node, index (index)}
 		{@const Component = svedit.session.config.node_components[snake_to_pascal(node.type)]}
@@ -45,4 +62,7 @@
 			<UnknownNode path={[...path, index]} />
 		{/if}
 	{/each}
+	{#if svedit.editable && NodeGapMarkers}
+		<NodeGapMarkers {path} />
+	{/if}
 </svelte:element>