svedit 0.8.0 → 0.10.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:
@@ -48,7 +50,7 @@ Svedit connects eight key pieces:
 **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
 
@@ -255,10 +257,52 @@ const doc = {
 };
 ```
 
+### 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).
 
+Two optional hooks are especially useful when integrating custom media workflows:
+
+- `handle_media_paste(session, pasted_media)`  
+  Called when media is pasted. You can upload/process files, replace an existing media property, or return a node payload to insert new content.  
+  See example implementation in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js).
+
+- `handle_property_deletion(session, path)`  
+  Called when deleting/cutting a property selection. Use it to define app-specific reset behavior (for example clearing an image property or resetting a referenced media node).  
+  See example implementation in [`src/routes/create_demo_session.js`](src/routes/create_demo_session.js).
+
 ```js
 const session_config = {
   // ID generator for creating new nodes
@@ -297,6 +341,7 @@ const session_config = {
 - **`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`.
 
@@ -336,6 +381,18 @@ 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
@@ -345,6 +402,20 @@ tr.insert_nodes(['new_node_id']);
 session.apply(tr);                      // Apply the transaction
 ```
 
+#### Batching history entries
+
+By default, every `session.apply(tr)` creates a new undo/redo entry. Pass `{ batch: true }` to merge the transaction into the previous history entry instead — useful for continuous interactions like dragging, where you want the entire gesture to undo as one step.
+
+```js
+session.apply(tr, { batch: true });
+```
+
+Batched transactions merge into the current history entry as long as they arrive within a 2-second window of the batch start. After 2 seconds of inactivity, the next `apply` starts a fresh entry. To force a new entry immediately (e.g. on pointer up), reset the batch timer:
+
+```js
+session.last_batch_started = undefined;
+```
+
 ### History
 
 ```js
@@ -924,6 +995,16 @@ Svedit provides specialized components for rendering different property types:
 />
 ```
 
+> **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
@@ -1053,8 +1134,59 @@ 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
 
@@ -1132,6 +1264,7 @@ For per-axis control, use `--node-caret-boundary-x` (left/right) and `--node-car
 }
 ```
 
+
 ## Beyond the README
 
 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.

package/dist/AnnotatedTextProperty.svelte

@@ -1,6 +1,13 @@
 <script>
 	import { getContext } from 'svelte';
-	import { char_slice, get_char_length, snake_to_pascal, get_selection_range } from './utils.js';
+	import {
+		char_slice,
+		get_char_length,
+		paths_equal,
+		serialize_path,
+		snake_to_pascal,
+		get_selection_range
+	} from './utils.js';
 
 	/** @import { AnnotatedTextPropertyProps, Annotation, Fragment, SelectionRange } from './types.d.ts'; */
 
@@ -9,10 +16,11 @@
 	/** @type {AnnotatedTextPropertyProps} */
 	let { path, class: css_class, placeholder = '', tag = 'div', style = '', ...rest } = $props();
 
+	let path_str = $derived(serialize_path(path));
+
 	let is_focused = $derived.by(() => {
 		return (
-			svedit.session.selection?.type === 'text' &&
-			path.join('.') === svedit.session.selection?.path.join('.')
+			svedit.session.selection?.type === 'text' && paths_equal(path, svedit.session.selection.path)
 		);
 	});
 
@@ -101,6 +109,7 @@
 
 		return fragments;
 	}
+
 </script>
 
 <!-- ATTENTION: The comments are needed to prevent unwanted text nodes with whitespace. -->
@@ -111,12 +120,11 @@
 <svelte:element
 	this={tag}
 	data-type="text"
-	data-path={path.join('.')}
-	style="anchor-name: --{path.join('-')};{style}"
+	data-path={path_str}
+	style="anchor-name: --{path_str};{style}"
 	class="text svedit-selectable {css_class}"
 	class:empty={is_empty}
 	class:focused={is_focused}
-	class:editable={svedit.editable}
 	{placeholder}
 	{...rest}
 >
@@ -137,11 +145,13 @@
 </svelte:element>
 
 <style>
-	.text {
+	/* Editable text base layout; :where() allows easy override without specificity conflicts. */
+	:where(.text) {
 		white-space: pre-wrap;
 		overflow-wrap: anywhere;
 		box-sizing: content-box;
 	}
+
 	/* 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,
 	[placeholder].empty.focused::after {
@@ -150,13 +160,36 @@
 		color: color-mix(in oklch, currentcolor 50%, transparent);
 	}
 
+	/* A virtual caret: to fix the caret vertical alignment issue in Chrome and Firefox for empty focused contenteditable with placeholders */
+	/* Browser BUG: iOS Safari only considers the caret color set on the top contenteditable element, not on nested elements (e.g. the second selector doesn't work in iOS Safari) */
+	:global(.svedit.editable .svedit-canvas:has([placeholder].empty.focused)),
+	:global(.svedit.editable) [placeholder].empty.focused {
+		caret-color: transparent !important;
+	}
+	:global(.svedit.editable) [placeholder].empty.focused::before {
+		content: "";
+		/* we limit width & height to avoid layout shifts in case the text has a lower natural height */
+		width: 0px;
+		height: 1cap;
+		display: inline-block;
+		/* we use box-shadow to draw the caret shape, matching the native caret */
+		box-shadow:
+			0 -0.4cap 0 0.65px var(--svedit-caret-color, AccentColor),
+			0 0 0 0.65px var(--svedit-caret-color, AccentColor),
+			0 0.4cap 0 0.65px var(--svedit-caret-color, AccentColor);
+		animation: var(
+			--node-caret-animation,
+			node-caret-blink var(--node-caret-blink-duration, 1.1s) ease-in-out infinite
+		);
+	}
+
 	/* Hide flickering: in Chrome, the caret jumps from end of placeholder string to start of text property when we focus */
 	.text:not(.focused) {
 		caret-color: transparent;
 	}
 
 	/* Disable text-transform when editable and focused so users see original text */
-	.text.editable.focused {
+	:global(.svedit.editable) .text.focused {
 		text-transform: none !important;
 	}
 

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":";;;;;AAkIA,2HAAoE"}
+{"version":3,"file":"AnnotatedTextProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/AnnotatedTextProperty.svelte.js"],"names":[],"mappings":";;;;;AA2IA,2HAAoE"}

package/dist/Command.svelte.d.ts

@@ -68,7 +68,6 @@ export class RedoCommand extends Command {
  * Useful for navigating up the document hierarchy.
  */
 export class SelectParentCommand extends Command {
-    is_enabled(): any;
     execute(): void;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"Command.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Command.svelte.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAOC;;;;OAIG;IACH,qBAFW,GAAG,EAIb;IAbD;;;OAGG;IACH,kBAAwC;IAQvC,aAAsB;IAGvB;;;;;OAKG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;OAMG;IACH,WAFa,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhC;CACD;AAED;;GAEG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;GAEG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;;GAGG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;;GAGG;AACH;IACC,0CAGC;IADA,eAA0B;IAG3B,YAAoC;IAEpC,iBAEC;IAED,kBAWC;IAED,gBAEC;CACD;AAED;;;;GAIG;AACH;IACC,kBAUC;IAED,gBAEC;CACD;AAED;;;;GAIG;AACH;IAKC,gBAKC;CACD;AAED;;;GAGG;AACH;IACC,kBAEC;IAED,gBAwGC;CACD;AAED;;;GAGG;AACH;IAUC,gBAIC;CACD"}
+{"version":3,"file":"Command.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Command.svelte.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAOC;;;;OAIG;IACH,qBAFW,GAAG,EAIb;IAbD;;;OAGG;IACH,kBAAwC;IAQvC,aAAsB;IAGvB;;;;;OAKG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;OAMG;IACH,WAFa,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhC;CACD;AAED;;GAEG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;GAEG;AACH;IACC,kBAEC;IAED,gBAEC;CACD;AAED;;;GAGG;AACH;IASC,gBAEC;CACD;AAED;;;GAGG;AACH;IACC,0CAGC;IADA,eAA0B;IAG3B,YAAoC;IAEpC,iBAEC;IAED,kBAqBC;IAED,gBAEC;CACD;AAED;;;;GAIG;AACH;IACC,kBAUC;IAED,gBAEC;CACD;AAED;;;;GAIG;AACH;IAKC,gBAKC;CACD;AAED;;;GAGG;AACH;IACC,kBAEC;IAED,gBAwGC;CACD;AAED;;;GAGG;AACH;IAUC,gBAIC;CACD"}

package/dist/Command.svelte.js

@@ -1,4 +1,5 @@
 import { insert_default_node, break_text_node } from './transforms.svelte.js';
+import { can_switch_annotation_type } from './doc_utils.js';
 import { is_selection_collapsed, is_mobile_browser, get_char_length } from './utils.js';
 
 /**
@@ -93,7 +94,11 @@ export class RedoCommand extends Command {
  */
 export class SelectParentCommand extends Command {
 	is_enabled() {
-		return this.context.editable && this.context.session.selection;
+		return (
+			this.context.editable &&
+			this.context.session.selection &&
+			this.context.session.selection.path.length > 3
+		);
 	}
 
 	execute() {
@@ -119,14 +124,24 @@ export class ToggleAnnotationCommand extends Command {
 
 	is_enabled() {
 		const { session, editable } = this.context;
+		const active_annotation = session.active_annotation();
 		const has_annotation = session.active_annotation(this.node_type);
+		const can_switch_annotation =
+			active_annotation &&
+			!has_annotation &&
+			session.available_annotation_types.includes(this.node_type) &&
+			can_switch_annotation_type(
+				session.schema,
+				session.get(active_annotation.node_id),
+				this.node_type
+			);
 		const no_annotation_and_caret_not_collapsed =
-			!session.active_annotation() && !is_selection_collapsed(session.selection);
+			!active_annotation && !is_selection_collapsed(session.selection);
 
 		return (
 			editable &&
 			session.selection?.type === 'text' &&
-			(has_annotation || no_annotation_and_caret_not_collapsed)
+			(has_annotation || can_switch_annotation || no_annotation_and_caret_not_collapsed)
 		);
 	}
 

package/dist/CustomProperty.svelte

@@ -1,26 +1,25 @@
 <script>
-	import { getContext } from 'svelte';
+	import { serialize_path } from './utils.js';
 
 	/** @import { CustomPropertyProps } from './types.d.ts'; */
-	const svedit = getContext('svedit');
 
 	/** @type {CustomPropertyProps} */
 	let { path, tag = 'div', class: css_class, children, style, ...rest } = $props();
+	let path_str = $derived(serialize_path(path));
+
 </script>
 
 <svelte:element
 	this={tag}
 	class={css_class}
 	data-type="property"
-	data-path={path.join('.')}
-	style="anchor-name: --{path.join('-')};{style ? ` ${style}` : ''}"
+	data-path={path_str}
+	style="anchor-name: --{path_str};{style ? ` ${style}` : ''}"
 	{...rest}
 >
-	{#if svedit.editable}
-		<div class="property-selectable">
-			<div class="svedit-selectable"><br /></div>
-		</div>
-	{/if}
+	<div class="property-selectable">
+		<div class="svedit-selectable"><br /></div>
+	</div>
 
 	{@render children()}
 </svelte:element>
@@ -37,5 +36,17 @@
 		bottom: 0;
 		z-index: 1;
 		outline: none;
+		/* Position the hidden selectable element at the bottom so the
+		   browser's native scroll-to-caret ensures the full property
+		   is visible, not just the top edge. */
+		display: none;
+		align-items: flex-end;
+		justify-content: center;
+	}
+	:global(.svedit.editable) .property-selectable {
+		display: flex;
+	}
+	.svedit-selectable {
+		caret-color: transparent;
 	}
 </style>

package/dist/CustomProperty.svelte.d.ts

@@ -3,5 +3,6 @@ type CustomProperty = {
     $on?(type: string, callback: (e: any) => void): () => void;
     $set?(props: Partial<CustomPropertyProps>): void;
 };
-declare const CustomProperty: import("svelte").Component<import("./types.d.ts").CustomPropertyProps, {}, "">;
+declare const CustomProperty: import("svelte").Component<CustomPropertyProps, {}, "">;
+import type { CustomPropertyProps } from './types.d.ts';
 //# sourceMappingURL=CustomProperty.svelte.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"CustomProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/CustomProperty.svelte.js"],"names":[],"mappings":";;;;;AA6BA,6GAA6D"}
+{"version":3,"file":"CustomProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/CustomProperty.svelte.js"],"names":[],"mappings":";;;;;AA4BA,sFAA6D;yCApBnB,cAAc"}

package/dist/Node.svelte

@@ -1,5 +1,6 @@
 <script>
 	import { getContext } from 'svelte';
+	import { serialize_path } from './utils.js';
 
 	/** @import { NodeProps } from './types.d.ts'; */
 
@@ -9,6 +10,7 @@
 	let { path, children, tag = 'div', class: css_class, style = '', ...rest } = $props();
 
 	let node = $derived(svedit.session.get(path));
+	let path_str = $derived(serialize_path(path));
 
 	const node_array_meta = getContext('node_array_meta');
 	let child_index = $derived(node_array_meta ? parseInt(String(path.at(-1)), 10) : -1);
@@ -17,13 +19,13 @@
 </script>
 
 <svelte:element
-	id={node.id}
 	this={tag}
-	class="{css_class}{is_first ? ' first' : ''}{is_last ? ' last' : ''}"
+	id={node.id}
+	class="node-{node.type} {css_class}{is_first ? ' first' : ''}{is_last ? ' last' : ''}"
 	data-node-id={node.id}
-	data-path={path.join('.')}
+	data-path={path_str}
 	data-type="node"
-	style="anchor-name: --{path.join('-')};{style}"
+	style="anchor-name: --{path_str};{style}"
 	{...rest}
 >
 	{@render children()}
@@ -35,4 +37,4 @@
 		/* 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":";;;;;AA8BA,yFAAmD"}
+{"version":3,"file":"Node.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Node.svelte.js"],"names":[],"mappings":";;;;;AAkCA,yFAAmD"}

package/dist/NodeArrayProperty.svelte

@@ -1,7 +1,7 @@
 <script>
 	import { getContext, setContext } from 'svelte';
 	import UnknownNode from './UnknownNode.svelte';
-	import { snake_to_pascal } from './utils.js';
+	import { serialize_path, snake_to_pascal } from './utils.js';
 	import DefaultNodeGap from './NodeGap.svelte';
 	import DefaultNodeGapMarkers from './NodeGapMarkers.svelte';
 
@@ -14,53 +14,61 @@
 	/** @type {NodeArrayPropertyProps} */
 	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))
+	// Pre-joined once per path change; reused by data-path and by every
+	// NodeGap's should_position_gap call to avoid N+1 joins per render.
+	let path_str = $derived(serialize_path(path));
+
+	let node_ids = $derived(svedit.session.get(path));
+	let nodes = $derived(node_ids.map((id) => svedit.session.get(id)));
+
+	// Mirrors the AnnotatedTextProperty pattern: a `focused` class follows
+	// the model selection. Used by the CSS rule below to hide the empty-array
+	// NodeGap while the caret is in the placeholder, so its <br> isn't a
+	// second arrow-key stop (issue #260).
+	let is_focused = $derived(
+		svedit.session.selection?.type === 'node'
+		&& serialize_path(svedit.session.selection.path) === path_str
 	);
 
 	setContext('node_array_meta', {
-		get length() { return nodes.length; }
+		get length() {
+			return node_ids.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}
+<svelte:element
+	this={tag}
+	class={css_class}
+	class:focused={is_focused}
+	data-type="node_array"
+	data-path={path_str}
+	style="anchor-name: --{path_str};{style ? ` ${style}` : ''}"
+	{...rest}
 >
-	{#if nodes.length === 0 && svedit.editable}
-		<!--
-		Experimental: We'll let .empty-node-array act like a node, so the existing
-		code paths for selection mapping will work as expected.
-
-		TODO: Need to figure out a way to make .empty-node-array customizable.
-		-->
+	{#if node_ids.length === 0 && svedit.editable}
 		<div
-			class="node empty-node-array"
-			data-path={[...path, 0].join('.')}
+			class="empty-node-placeholder"
+			data-path={serialize_path([...path, 0])}
 			data-type="node"
-			style="anchor-name: --{[...path, 0].join(
-				'-'
-			)}; 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 array_path={path} offset={0} count={0} empty />
+			style="anchor-name: --{serialize_path([...path, 0])};"
+		>
+		<NodeGap
+			array_path={path}
+			offset={0}
+			count={0}
+			empty
+		/>
+		</div>
 	{/if}
 	{#each nodes as node, index (index)}
-		{#if svedit.editable}
-			<NodeGap
-				array_path={path}
-				offset={index}
-				count={nodes.length}
-				positioned={svedit.is_near_viewport?.([...path, index]) ?? true}
-			/>
-		{/if}
+		<NodeGap
+			array_path={path}
+			offset={index}
+			count={nodes.length}
+		/>
 		{@const Component = svedit.session.config.node_components[snake_to_pascal(node.type)]}
 		{#if Component}
 			<Component path={[...path, index]} />
@@ -68,15 +76,30 @@
 			<UnknownNode path={[...path, index]} />
 		{/if}
 	{/each}
-	{#if svedit.editable && nodes.length > 0}
+	{#if node_ids.length > 0}
 		<NodeGap
 			array_path={path}
-			offset={nodes.length}
-			count={nodes.length}
-			positioned={svedit.is_near_viewport?.([...path, nodes.length - 1]) ?? true}
+			offset={node_ids.length}
+			count={node_ids.length}
 		/>
 	{/if}
 	{#if svedit.editable && NodeGapMarkers}
-		<NodeGapMarkers {path} />
+		<NodeGapMarkers {path} count={node_ids.length} />
 	{/if}
 </svelte:element>
+
+<style>
+/* position: relative makes this the containing block for the gap's
+   .svedit-selectable, which fills it via inset:0. You may override to
+   position: absolute (e.g. so an empty array doesn't occupy flow space)
+   — still a containing block; then also set position: relative on the
+   parent node-array container so this placeholder's inset:0 resolves
+   against it. */
+	:where(.empty-node-placeholder) {
+		position: relative;
+		inset: 0;
+		min-height: 40px;
+		min-width: 24px;
+		cursor: pointer;
+	}
+</style>

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

@@ -1 +1 @@
-{"version":3,"file":"NodeArrayProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/NodeArrayProperty.svelte.js"],"names":[],"mappings":";;;;;AAkEA,mHAAgE"}
+{"version":3,"file":"NodeArrayProperty.svelte.d.ts","sourceRoot":"","sources":["../src/lib/NodeArrayProperty.svelte.js"],"names":[],"mappings":";;;;;AA4EA,mHAAgE"}

package/dist/NodeCaret.svelte

@@ -11,13 +11,6 @@
 <div class="caret" role="none"></div>
 
 <style>
-	@keyframes node-caret-blink {
-		0%, 60% { opacity: 1; }
-		68% { opacity: 0; }
-		88% { opacity: 0; }
-		100% { opacity: 1; }
-	}
-
 	.caret {
 		--_R: var(--row, 1);
 		--_C: calc(1 - var(--row, 1));