From ce1cba9e987156a64f32a19a499c86ea7930c685 Mon Sep 17 00:00:00 2001
From: Johannes <info@johannesmutter.de>
Date: Thu, 21 May 2026 23:36:20 +0200
Subject: [PATCH 1/5] fix: too-early render can no longer strand the cursor

---
 src/lib/Svedit.svelte | 89 ++++++++++++++++++++++++++-----------------
 1 file changed, 53 insertions(+), 36 deletions(-)

diff --git a/src/lib/Svedit.svelte b/src/lib/Svedit.svelte
index 0994f4a2..5c84a05e 100644
--- a/src/lib/Svedit.svelte
+++ b/src/lib/Svedit.svelte
@@ -1186,17 +1186,27 @@ ${fallback_html}`;
 		);
 	}
 
-	function __render_node_selection() {
+	function __render_node_selection(retry_count = 0) {
 		const selection = /** @type {NodeSelection} */ (session.selection);
 		const node_array_path = selection.path;
 		const node_array_path_str = serialize_path(node_array_path);
 		const is_collapsed = is_selection_collapsed(selection);
 		const is_backward = !is_collapsed && selection.anchor_offset > selection.focus_offset;
 
+		// The change that triggered this render (an undo or insert) may not
+		// have mounted its nodes/gaps yet. Retry on the next frame until the
+		// DOM is there — bounded so a genuinely missing target can't loop
+		// forever (~1s at 60fps).
+		const retry_when_dom_settles = () => {
+			if (retry_count < 60 && session.selection?.type === 'node') {
+				requestAnimationFrame(() => __render_node_selection(retry_count + 1));
+			}
+		};
+
 		const node_array_el = canvas_el.querySelector(
 			`[data-path="${node_array_path_str}"][data-type="node_array"]`
 		);
-		if (!node_array_el) return;
+		if (!node_array_el) return retry_when_dom_settles();
 
 		const dom_selection = window.getSelection();
 		const range = window.document.createRange();
@@ -1206,12 +1216,11 @@ ${fallback_html}`;
 
 		if (is_collapsed) {
 			const gap_el = node_array_el.querySelector(gap_selector(selection.anchor_offset));
-			if (!gap_el) return;
 			// Target .svedit-selectable (has a box), not gap_el which is
 			// display:contents and would cause the browser to normalize
 			// the range into the parent, breaking read-back.
-			const selectable = gap_el.querySelector('.svedit-selectable');
-			if (!selectable) return;
+			const selectable = gap_el?.querySelector('.svedit-selectable');
+			if (!selectable) return retry_when_dom_settles();
 			range.setStart(selectable, 1);
 			range.setEnd(selectable, 1);
 			dom_selection.removeAllRanges();
@@ -1219,10 +1228,9 @@ ${fallback_html}`;
 		} else {
 			const anchor_gap = node_array_el.querySelector(gap_selector(selection.anchor_offset));
 			const focus_gap = node_array_el.querySelector(gap_selector(selection.focus_offset));
-			if (!anchor_gap || !focus_gap) return;
-			const anchor_sel = anchor_gap.querySelector('.svedit-selectable');
-			const focus_sel = focus_gap.querySelector('.svedit-selectable');
-			if (!anchor_sel || !focus_sel) return;
+			const anchor_sel = anchor_gap?.querySelector('.svedit-selectable');
+			const focus_sel = focus_gap?.querySelector('.svedit-selectable');
+			if (!anchor_sel || !focus_sel) return retry_when_dom_settles();
 
 			if (is_backward) {
 				dom_selection.removeAllRanges();
@@ -1236,20 +1244,30 @@ ${fallback_html}`;
 		}
 
 		// Scroll the cursor into view, but only when it is genuinely
-		// off-screen. This runs on every node-selection re-render — a
-		// transaction (type/layout change), select-parent, window refocus
-		// — so an unconditional scroll would yank the viewport on each of
-		// them. cursor_offset is a gap offset and the gap has no box of
-		// its own, so visibility is judged from the nodes flanking it.
-		setTimeout(() => {
+		// off-screen. cursor_offset is a gap offset and the gap has no box
+		// of its own, so visibility is judged from the nodes flanking it.
+		//
+		// Re-run on each animation frame while the cursor stays off-screen:
+		// an undo/insert mounts content whose images and sizing settle
+		// across several frames, so a single scroll computed against the
+		// un-settled layout strands the cursor (this is why a second undo
+		// appeared to "fix" it — by then the layout had settled). The
+		// visibility guard ends the loop the moment the cursor is on
+		// screen; the deadline bounds it otherwise.
+		const selection_snapshot = JSON.stringify(selection);
+		const scroll_deadline = performance.now() + 1000;
+		const scroll_cursor_into_view = () => {
+			// The selection moved on while the layout was settling — stop.
+			if (JSON.stringify(session.selection) !== selection_snapshot) return;
+
 			// Collapsed: anchor === focus, so focus is the gap offset.
 			// Range: cursor sits at the focus end (anchor when backward).
 			const cursor_offset = is_backward ? selection.anchor_offset : selection.focus_offset;
 			const array_length = session.get(node_array_path).length;
 
-			// If either node flanking the cursor is already (even
-			// partially) on screen, the cursor is visible — keep the
-			// viewport stable and scroll nothing. node_before is null at
+			// If either node flanking the cursor is already (even partially)
+			// on screen, the cursor is visible — keep the viewport stable,
+			// scroll nothing, and end the loop. node_before is null at
 			// offset 0: cursor_offset - 1 would be -1, and serialize_path
 			// rejects a negative index.
 			const node_before = cursor_offset > 0
@@ -1261,31 +1279,30 @@ ${fallback_html}`;
 			if (cursor_offset === 0) {
 				node_array_el.scrollLeft = 0;
 				node_array_el.scrollTop = 0;
-				return;
-			}
-			if (cursor_offset >= array_length) {
-				const max_left = Math.max(
+			} else if (cursor_offset >= array_length) {
+				node_array_el.scrollLeft = Math.max(
 					0,
 					node_array_el.scrollWidth - node_array_el.clientWidth
 				);
-				const max_top = Math.max(
+				node_array_el.scrollTop = Math.max(
 					0,
 					node_array_el.scrollHeight - node_array_el.clientHeight
 				);
-				node_array_el.scrollLeft = max_left;
-				node_array_el.scrollTop = max_top;
-				if (max_left === 0 && max_top === 0) {
-					node_before?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-				}
-				return;
+				node_before?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+			} else {
+				// A range selection's selected node IS node_before; scrolling
+				// node_after would reveal the following node and leave the
+				// selection itself off-screen. For a collapsed caret
+				// node_after's leading edge is the cursor.
+				const target = is_collapsed ? node_after : node_before;
+				target?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
 			}
-			// A range selection's selected node IS node_before; scrolling
-			// node_after would reveal the following node and leave the
-			// selection itself off-screen. For a collapsed caret node_after's
-			// leading edge is the cursor, so that stays the right target.
-			const target = is_collapsed ? node_after : node_before;
-			target?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-		}, 0);
+
+			if (performance.now() < scroll_deadline) {
+				requestAnimationFrame(scroll_cursor_into_view);
+			}
+		};
+		requestAnimationFrame(scroll_cursor_into_view);
 	}
 
 	function __render_property_selection() {

From 078fce657111116e64152c17d181d900f2885da1 Mon Sep 17 00:00:00 2001
From: Johannes <info@johannesmutter.de>
Date: Tue, 26 May 2026 20:38:20 +0200
Subject: [PATCH 2/5] Scroll into view: IO watch for node cursor, tick+rAF for
 property/text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A single deferred scroll computed against an un-settled layout strands
the cursor when images / nested mounts continue reflowing after the
triggering action — the "still found cases where the active node
selection isn't revealed" case on #291.

Node selection (__scroll_node_cursor_into_view):
- IntersectionObserver on the two nodes flanking the cursor gap re-fires
  the scroll on each viewport-edge crossing, until the selection moves
  on, the user scrolls (after a 500ms grace so the settling relayout
  and any inertial scroll can't abort it), or a 2s safety timeout fires.
  Replaces the rAF-poll-until-deadline loop with an event-driven watch
  that catches relayout shifts past the first visibility-pass.

Property and text selection:
- setTimeout(fn, 0) -> await tick() then a rAF (with 50ms fallback for
  background-tab rAF throttling). tick() drains Svelte's effect queue
  so the scroll measures the post-flush DOM, not the pre-flush one.
- Job-id cancellation so a fresh render invalidates an older pending
  scroll instead of letting both yank the viewport.
- Text selection captures focusNode.parentElement at run time, not at
  enqueue time, so a focus that moves during the settle window doesn't
  scroll a stale element.

Node-cursor watch starts also bump the property/text job-id, so a node
render cancels any pending property/text scroll scheduled just before
it.

Adopts the deferred-scroll helper shape from #292 for the property/text
generalization; #292 can be closed in favour of this combined approach.
svedit-lab "Run Smoke Tests": 25/25 pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/lib/Svedit.svelte | 243 ++++++++++++++++++++++++++++++++++--------
 1 file changed, 199 insertions(+), 44 deletions(-)

diff --git a/src/lib/Svedit.svelte b/src/lib/Svedit.svelte
index 5c84a05e..14c780ee 100644
--- a/src/lib/Svedit.svelte
+++ b/src/lib/Svedit.svelte
@@ -1,5 +1,5 @@
 <script>
-	import { flushSync, getContext, setContext } from 'svelte';
+	import { flushSync, getContext, setContext, tick } from 'svelte';
 	import {
 		snake_to_pascal,
 		get_char_length,
@@ -48,6 +48,14 @@
 	// to the model. render_selection consumes-and-clears it to skip
 	// rerender on DOM-driven changes (the DOM is already in place).
 	let selection_source_is_dom = false;
+	// Bumped on every deferred scroll-into-view enqueue (property + text
+	// selections); a callback only runs if its id still matches the
+	// counter. Lets a fresh render cancel an older still-pending scroll
+	// without the older one yanking the viewport. Node selections use
+	// their own IO-based cancellation via `cancel_node_scroll_watch`,
+	// and also bump this counter so a node render kills any pending
+	// property/text scroll that was queued just before it.
+	let deferred_scroll_job_id = 0;
 
 
 	// let is_mobile = $derived(is_mobile_browser());
@@ -1186,6 +1194,68 @@ ${fallback_html}`;
 		);
 	}
 
+	/**
+	 * Resolves on the next animation frame, or after `timeout_ms` if rAF
+	 * doesn't fire (background tabs throttle rAF to ~1Hz; the timeout keeps
+	 * scroll-into-view responsive in that case). Either way, exactly one
+	 * scroll attempt happens. Used by property + text selections, where
+	 * the scroll target is a known element and one well-timed shot is
+	 * enough — multi-frame settling correction is the node-selection
+	 * case (see `__scroll_node_cursor_into_view`).
+	 * @param {number} [timeout_ms]
+	 * @returns {Promise<void>}
+	 */
+	function __next_animation_frame_or_timeout(timeout_ms = 50) {
+		return new Promise((resolve) => {
+			let done = false;
+			const timeout_id = setTimeout(finish, timeout_ms);
+			function finish() {
+				if (done) return;
+				done = true;
+				clearTimeout(timeout_id);
+				resolve();
+			}
+			requestAnimationFrame(finish);
+		});
+	}
+
+	/**
+	 * `tick()` waits for Svelte to flush its effect queue, so the new
+	 * subtree from the triggering transaction is mounted. The animation
+	 * frame after that gives the browser one layout/paint pass to size
+	 * the new content before we measure. The bug pattern this fixes is
+	 * `setTimeout(fn, 0)` — that fires on the macrotask queue before
+	 * Svelte's microtask flush, leaving the scroll computed against the
+	 * old DOM.
+	 */
+	async function __wait_for_scroll_frame() {
+		await tick();
+		await __next_animation_frame_or_timeout();
+	}
+
+	/**
+	 * Queue a callback to fire one settled frame from now, with stale-
+	 * scroll cancellation: each call bumps `deferred_scroll_job_id`, and
+	 * the callback only runs if its captured id is still current when
+	 * the frame arrives. A new render between enqueue and fire wins.
+	 * @param {() => void} callback
+	 */
+	function __run_after_scroll_frame(callback) {
+		const job_id = ++deferred_scroll_job_id;
+		void (async () => {
+			await __wait_for_scroll_frame();
+			if (job_id === deferred_scroll_job_id) callback();
+		})();
+	}
+
+	/**
+	 * Cancels the in-flight node-selection scroll watch (ResizeObserver +
+	 * wheel/touch listeners), if one is running. A new node render replaces
+	 * it; the editor unmounting clears it.
+	 * @type {(() => void) | null}
+	 */
+	let cancel_node_scroll_watch = null;
+
 	function __render_node_selection(retry_count = 0) {
 		const selection = /** @type {NodeSelection} */ (session.selection);
 		const node_array_path = selection.path;
@@ -1243,33 +1313,56 @@ ${fallback_html}`;
 			}
 		}
 
+		__scroll_node_cursor_into_view(selection, node_array_el, is_collapsed, is_backward);
+	}
+
+	/**
+	 * Keeps the cursor of a node selection in view while it is off-screen.
+	 *
+	 * The change that triggered the render (an undo or insert) mounts nodes
+	 * whose images and sizing settle across several frames. A scroll
+	 * computed once against that un-settled layout strands the cursor — by
+	 * the time the nodes above finish laying out, the target has moved far
+	 * down the document. (This is why a second undo used to "fix" it: the
+	 * layout had settled by then.)
+	 *
+	 * The cursor sits in a gap flanked by two nodes, so an IntersectionObserver
+	 * watches those nodes against the viewport. It reports both scrolling and
+	 * layout shifts that move a node, so each settling-relayout frame that
+	 * pushes the cursor off-screen re-triggers the scroll until the layout
+	 * stabilises. The watch ends on the first of: a deliberate user scroll
+	 * (honoured only after a short grace period, so the settling relayout and
+	 * any inertial scroll trailing the triggering action do not abort it),
+	 * the selection moving on, or a safety timeout.
+	 *
+	 * @param {NodeSelection} selection
+	 * @param {Element} node_array_el
+	 * @param {boolean} is_collapsed
+	 * @param {boolean} is_backward
+	 */
+	function __scroll_node_cursor_into_view(selection, node_array_el, is_collapsed, is_backward) {
+		// Replace any watch still running from an earlier node render,
+		// and invalidate any pending property/text scroll-into-view from
+		// a render that landed just before this one.
+		cancel_node_scroll_watch?.();
+		deferred_scroll_job_id++;
+
+		const node_array_path = selection.path;
+		const selection_snapshot = JSON.stringify(selection);
+
 		// Scroll the cursor into view, but only when it is genuinely
 		// off-screen. cursor_offset is a gap offset and the gap has no box
 		// of its own, so visibility is judged from the nodes flanking it.
-		//
-		// Re-run on each animation frame while the cursor stays off-screen:
-		// an undo/insert mounts content whose images and sizing settle
-		// across several frames, so a single scroll computed against the
-		// un-settled layout strands the cursor (this is why a second undo
-		// appeared to "fix" it — by then the layout had settled). The
-		// visibility guard ends the loop the moment the cursor is on
-		// screen; the deadline bounds it otherwise.
-		const selection_snapshot = JSON.stringify(selection);
-		const scroll_deadline = performance.now() + 1000;
 		const scroll_cursor_into_view = () => {
-			// The selection moved on while the layout was settling — stop.
-			if (JSON.stringify(session.selection) !== selection_snapshot) return;
-
 			// Collapsed: anchor === focus, so focus is the gap offset.
 			// Range: cursor sits at the focus end (anchor when backward).
 			const cursor_offset = is_backward ? selection.anchor_offset : selection.focus_offset;
 			const array_length = session.get(node_array_path).length;
 
 			// If either node flanking the cursor is already (even partially)
-			// on screen, the cursor is visible — keep the viewport stable,
-			// scroll nothing, and end the loop. node_before is null at
-			// offset 0: cursor_offset - 1 would be -1, and serialize_path
-			// rejects a negative index.
+			// on screen, the cursor is visible — keep the viewport stable and
+			// scroll nothing. node_before is null at offset 0: cursor_offset
+			// - 1 would be -1, and serialize_path rejects a negative index.
 			const node_before = cursor_offset > 0
 				? __get_node_element(node_array_path, cursor_offset - 1)
 				: null;
@@ -1279,30 +1372,83 @@ ${fallback_html}`;
 			if (cursor_offset === 0) {
 				node_array_el.scrollLeft = 0;
 				node_array_el.scrollTop = 0;
-			} else if (cursor_offset >= array_length) {
-				node_array_el.scrollLeft = Math.max(
+				return;
+			}
+			if (cursor_offset >= array_length) {
+				const max_left = Math.max(
 					0,
 					node_array_el.scrollWidth - node_array_el.clientWidth
 				);
-				node_array_el.scrollTop = Math.max(
+				const max_top = Math.max(
 					0,
 					node_array_el.scrollHeight - node_array_el.clientHeight
 				);
-				node_before?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-			} else {
-				// A range selection's selected node IS node_before; scrolling
-				// node_after would reveal the following node and leave the
-				// selection itself off-screen. For a collapsed caret
-				// node_after's leading edge is the cursor.
-				const target = is_collapsed ? node_after : node_before;
-				target?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+				node_array_el.scrollLeft = max_left;
+				node_array_el.scrollTop = max_top;
+				if (max_left === 0 && max_top === 0) {
+					node_before?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+				}
+				return;
 			}
+			// A range selection's selected node IS node_before; scrolling
+			// node_after would reveal the following node and leave the
+			// selection itself off-screen. For a collapsed caret node_after's
+			// leading edge is the cursor, so that stays the right target.
+			const target = is_collapsed ? node_after : node_before;
+			target?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+		};
 
-			if (performance.now() < scroll_deadline) {
-				requestAnimationFrame(scroll_cursor_into_view);
-			}
+		// The two nodes flanking the cursor gap — the cursor is on screen
+		// when either of them is, so the observer watches both.
+		const cursor_offset = is_backward ? selection.anchor_offset : selection.focus_offset;
+		const flank_before = cursor_offset > 0
+			? __get_node_element(node_array_path, cursor_offset - 1)
+			: null;
+		const flank_after = __get_node_element(node_array_path, cursor_offset);
+
+		// With no node to anchor an observer to, nothing's reflow could
+		// re-strand the cursor — a single scroll is all that is possible.
+		if (!flank_before && !flank_after) return scroll_cursor_into_view();
+
+		/** @type {IntersectionObserver | null} */
+		let observer = null;
+		let grace_timeout = 0;
+		let safety_timeout = 0;
+
+		const stop = () => {
+			observer?.disconnect();
+			observer = null;
+			window.clearTimeout(grace_timeout);
+			window.clearTimeout(safety_timeout);
+			window.removeEventListener('wheel', on_user_scroll);
+			window.removeEventListener('touchmove', on_user_scroll);
+			if (cancel_node_scroll_watch === stop) cancel_node_scroll_watch = null;
+		};
+
+		// A deliberate scroll by the user wins over our reveal. These
+		// listeners are attached only once the grace period is over, so the
+		// settling relayout — and any inertial scroll still trailing from the
+		// action that triggered this render — cannot abort the watch.
+		const on_user_scroll = () => stop();
+
+		// Fires when a flanking node crosses the viewport edge — whether the
+		// page scrolled or the settling relayout moved the node. Re-run the
+		// scroll check on each crossing; stop once the selection moves on.
+		const on_intersection = () => {
+			if (JSON.stringify(session.selection) !== selection_snapshot) return stop();
+			scroll_cursor_into_view();
 		};
-		requestAnimationFrame(scroll_cursor_into_view);
+
+		observer = new IntersectionObserver(on_intersection);
+		if (flank_before) observer.observe(flank_before);
+		if (flank_after) observer.observe(flank_after);
+		grace_timeout = window.setTimeout(() => {
+			window.addEventListener('wheel', on_user_scroll, { passive: true });
+			window.addEventListener('touchmove', on_user_scroll, { passive: true });
+		}, 500);
+		// A live editor can keep reflowing; don't watch indefinitely.
+		safety_timeout = window.setTimeout(stop, 2000);
+		cancel_node_scroll_watch = stop;
 	}
 
 	function __render_property_selection() {
@@ -1322,10 +1468,12 @@ ${fallback_html}`;
 		dom_selection.removeAllRanges();
 		dom_selection.addRange(range);
 
-		// Scroll the selection into view
-		setTimeout(() => {
-			el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-		}, 0);
+		// Wait one settled frame before scrolling so layout reflects the
+		// transaction that triggered this render (was `setTimeout(fn, 0)`
+		// before, which fired before Svelte's microtask flush).
+		__run_after_scroll_frame(() => {
+			el?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+		});
 	}
 
 	function __render_text_selection() {
@@ -1420,13 +1568,15 @@ ${fallback_html}`;
 				focus_node_offset
 			);
 
-			// Scroll the selection into view
-			setTimeout(() => {
-				const selectedElement = dom_selection.focusNode.parentElement;
-				if (selectedElement) {
-					selectedElement.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-				}
-			}, 0);
+			// Wait one settled frame before scrolling so layout reflects
+			// the transaction that triggered this render (was `setTimeout
+			// (fn, 0)` before, which fired before Svelte's microtask flush).
+			// Capture focusNode.parentElement at run-time, not enqueue-time:
+			// the focus node may move during the settle window.
+			__run_after_scroll_frame(() => {
+				const selected_element = window.getSelection()?.focusNode?.parentElement;
+				selected_element?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+			});
 		}
 	}
 
@@ -1513,6 +1663,11 @@ ${fallback_html}`;
 		if (!canvas_focused) return;
 		render_selection(dom_driven);
 	});
+
+	// Stop any in-flight node-selection scroll watch when the editor unmounts.
+	$effect(() => {
+		return () => cancel_node_scroll_watch?.();
+	});
 </script>
 
 <!--

From 52f3b98211cff1720c166704e33a938adc7c223d Mon Sep 17 00:00:00 2001
From: Johannes <info@johannesmutter.de>
Date: Thu, 28 May 2026 11:49:54 +0200
Subject: [PATCH 3/5] fix: mid gaps not being placed when height exceeds
 overscan px constant

---
 src/lib/NodeGapMarkers.svelte     | 12 ++++++++----
 src/lib/node_visibility.svelte.js | 14 ++++++++++----
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/src/lib/NodeGapMarkers.svelte b/src/lib/NodeGapMarkers.svelte
index 5c223fd1..427db67b 100644
--- a/src/lib/NodeGapMarkers.svelte
+++ b/src/lib/NodeGapMarkers.svelte
@@ -94,10 +94,14 @@
 		if (sorted[0] === 0 && edge_state?.first === true) {
 			add_offset(0);
 		}
-		// Mid gaps: between consecutive visible nodes. The gap at offset N
-		// sits between node N-1 and node N — emit when both are visible.
-		for (let i = 0; i < sorted.length - 1; i++) {
-			if (sorted[i + 1] === sorted[i] + 1) add_offset(sorted[i + 1]);
+		// Mid gaps: anchor to the previous node. Emit a marker whenever the
+		// prev flank is visible, even if next falls outside the overscan —
+		// mirrors the NodeGap gate in node_visibility.svelte.js. Wrap/grid
+		// layouts whose row height exceeds the overscan (e.g. tetris with
+		// tall cells) would otherwise lose every between-row marker even
+		// while the user can see and click the underlying NodeGap.
+		for (const i of sorted) {
+			if (i + 1 > 0 && i + 1 < count) add_offset(i + 1);
 		}
 		// Edge gap-after.last: same gate as gap-before but on the trailing edge.
 		if (sorted[sorted.length - 1] === count - 1 && edge_state?.last === true) {
diff --git a/src/lib/node_visibility.svelte.js b/src/lib/node_visibility.svelte.js
index 1009baa3..40985299 100644
--- a/src/lib/node_visibility.svelte.js
+++ b/src/lib/node_visibility.svelte.js
@@ -710,9 +710,15 @@ function should_position_gap_imperative(registry, array_path_str, offset, is_las
 			return registry.edge_map.get(array_path_str)?.last === true;
 		}
 
-		return (
-			registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}${offset - 1}`) &&
-			registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}${offset}`)
-		);
+		// Anchor to prev: gap-after's `position-anchor` is the previous node,
+		// and `position-visibility: anchors-visible` already hides the gap
+		// once that anchor is off-viewport. Gating `.positioned` on the next
+		// flank being near as well would strand every between-row gap in a
+		// wrap/grid layout whose row height exceeds ~OVERSCAN_PX (the next
+		// row's leading node sits far outside the overscan even when the
+		// previous row's trailing node is right under the user's cursor).
+		// Checking prev alone is sufficient — visibility is handled by the
+		// CSS rule, not by withholding `.positioned`.
+		return registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}${offset - 1}`);
 	});
 }

From 6b911986eead79ebf45cb96bac88059754217da7 Mon Sep 17 00:00:00 2001
From: Johannes <info@johannesmutter.de>
Date: Thu, 28 May 2026 13:01:36 +0200
Subject: [PATCH 4/5] Fix issue Michael reported regarding last node gap not
 getting focused when typing in a button in story.buttons node array where the
 text caret touches the end edge of an overflowing container: use scroll
 padding to leave "breathing" room

---
 src/lib/NodeArrayProperty.svelte | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/lib/NodeArrayProperty.svelte b/src/lib/NodeArrayProperty.svelte
index 7b03900c..004632ec 100644
--- a/src/lib/NodeArrayProperty.svelte
+++ b/src/lib/NodeArrayProperty.svelte
@@ -102,4 +102,23 @@
 		min-width: 24px;
 		cursor: pointer;
 	}
+
+	/* Reserve room at the scroll edges so the browser's caret-follow scroll
+	   (when typing at the end of an overflowing node) can't pin the caret
+	   flush against the array's clip edge. Without this padding, scrollLeft
+	   stops just short of `scrollWidth - clientWidth - EDGE_TOLERANCE_PX`,
+	   leaving `edge_map.last` false; the trailing gap never gains
+	   `.positioned`, and the user sees the caret at the edge with no gap to
+	   click. The default is 2 × edge-gap (≈ enough for the gap plus a
+	   click margin); override per-array via the custom properties. */
+	:global([data-type="node_array"]) {
+		scroll-padding-inline: var(
+			--node-caret-scroll-padding-inline,
+			calc(var(--node-caret-edge-gap, 24px) * 2)
+		);
+		scroll-padding-block: var(
+			--node-caret-scroll-padding-block,
+			calc(var(--node-caret-edge-gap, 24px) * 2)
+		);
+	}
 </style>
\ No newline at end of file

From e97b097c2c9c32165a8ddb9ebbd12a6f3095c9bc Mon Sep 17 00:00:00 2001
From: Johannes <info@johannesmutter.de>
Date: Thu, 28 May 2026 14:01:51 +0200
Subject: [PATCH 5/5] Scroll-into-view: address Michael's PR feedback +
 regression tests

Three changes to __scroll_node_cursor_into_view in Svedit.svelte:

- Drop the wheel/touchmove cancellation path and shorten the safety cap
  from 2000 ms to 500 ms. At 500 ms a deliberate user scroll inside the
  watch isn't a coherent human gesture, so the cancellation event
  sources Michael flagged as race-prone are no longer needed.

- Use the nearest scrollable ancestor as the IntersectionObserver root,
  and give __intersects_viewport an optional `root` parameter. When
  Svedit is mounted inside an overflow:auto container, the observer
  and the visibility check both test the surface the user actually
  scrolls instead of the window viewport.

- Restructure the edge branches: cursor at offset 0 / trailing now
  skips the flank-visibility guard (the cursor sits past its single
  flank, so flank visibility tells us nothing about the cursor). Each
  edge branch sets the matching internal scroll, then falls through to
  scrollIntoView on the flank only when the flank is still off-screen.
  This unblocks two cases the previous "max_left === 0 && max_top === 0"
  gate missed:
    - Typing at the right edge of an overflowing button + arrow-right
      -> trailing gap reveal (combined with NodeArrayProperty's scroll-
      padding default, the trailing gap stays positioned through typing).
    - #288 offscreen-array-undo: 10 buttons -> delete -> scroll to bottom
      -> undo. Previously the trailing branch's scrollIntoView was gated
      on both max_left and max_top being 0 and skipped in horizontal-
      overflow + offscreen-vertically scenarios.

Four new tests pin the regressions:
- selection_scroll: model-driven selection on an offscreen
  horizontally-overflowing array scrolls it into view (#288 regression).
- gap_visibility: mid gap stays .positioned when only the prev flank is
  in near_map (locks in the wrap/grid prev-only rule).
- gap_visibility: mid gap-marker emits when only the prev flank is in
  array_indices (matching rule for NodeGapMarkers).
- gap_visibility: scroll-padding-inline / -block default is non-zero on
  every node-array (locks in the typing-edge fix).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/lib/Svedit.svelte                    | 131 ++++++++++++++++-------
 src/test/gap_visibility.svelte.test.js   | 100 +++++++++++++++++
 src/test/selection_scroll.svelte.test.js |  59 ++++++++++
 3 files changed, 254 insertions(+), 36 deletions(-)

diff --git a/src/lib/Svedit.svelte b/src/lib/Svedit.svelte
index 14c780ee..1d76035f 100644
--- a/src/lib/Svedit.svelte
+++ b/src/lib/Svedit.svelte
@@ -1179,21 +1179,58 @@ ${fallback_html}`;
 	}
 
 	/**
-	 * True when any part of the element's border box overlaps the window
-	 * viewport. Used to keep node-selection re-renders from scrolling a
-	 * cursor that is already on screen. Tests the window viewport, so a
-	 * node clipped only by an inner scroll container still counts visible.
+	 * True when any part of the element's border box overlaps the given
+	 * root's box (or the window viewport when `root` is null). Used to
+	 * keep node-selection re-renders from scrolling a cursor that is
+	 * already on screen. Passing the editor's actual scroll container
+	 * (when Svedit is mounted inside an overflow:auto ancestor) keeps the
+	 * test honest — using the window viewport there would call a node
+	 * "visible" while the user can't see it.
 	 * @param {Element | null | undefined} el
+	 * @param {Element | null} [root]
 	 */
-	function __intersects_viewport(el) {
+	function __intersects_viewport(el, root = null) {
 		if (!el) return false;
 		const r = el.getBoundingClientRect();
+		if (root) {
+			const rr = root.getBoundingClientRect();
+			return (
+				r.bottom > rr.top && r.top < rr.bottom &&
+				r.right > rr.left && r.left < rr.right
+			);
+		}
 		return (
 			r.bottom > 0 && r.top < window.innerHeight &&
 			r.right > 0 && r.left < window.innerWidth
 		);
 	}
 
+	/**
+	 * Nearest ancestor that establishes its own scrollable area
+	 * (`overflow-x` or `overflow-y` `auto`/`scroll`, AND content actually
+	 * overflowing), or null when the editor scrolls with the window. Used
+	 * as the IntersectionObserver root for the cursor-scroll watch, so
+	 * the watch fires for the surface the user actually scrolls when
+	 * Svedit is embedded inside an overflowing container.
+	 * @param {Element | null | undefined} el
+	 * @returns {Element | null}
+	 */
+	function __nearest_scroll_root(el) {
+		let cur = el?.parentElement;
+		while (cur && cur !== document.body && cur !== document.documentElement) {
+			const cs = getComputedStyle(cur);
+			const scrolls_y =
+				(cs.overflowY === 'auto' || cs.overflowY === 'scroll') &&
+				cur.scrollHeight > cur.clientHeight;
+			const scrolls_x =
+				(cs.overflowX === 'auto' || cs.overflowX === 'scroll') &&
+				cur.scrollWidth > cur.clientWidth;
+			if (scrolls_y || scrolls_x) return cur;
+			cur = cur.parentElement;
+		}
+		return null;
+	}
+
 	/**
 	 * Resolves on the next animation frame, or after `timeout_ms` if rAF
 	 * doesn't fire (background tabs throttle rAF to ~1Hz; the timeout keeps
@@ -1327,13 +1364,14 @@ ${fallback_html}`;
 	 * layout had settled by then.)
 	 *
 	 * The cursor sits in a gap flanked by two nodes, so an IntersectionObserver
-	 * watches those nodes against the viewport. It reports both scrolling and
-	 * layout shifts that move a node, so each settling-relayout frame that
-	 * pushes the cursor off-screen re-triggers the scroll until the layout
-	 * stabilises. The watch ends on the first of: a deliberate user scroll
-	 * (honoured only after a short grace period, so the settling relayout and
-	 * any inertial scroll trailing the triggering action do not abort it),
-	 * the selection moving on, or a safety timeout.
+	 * watches those nodes against the editor's actual scroll surface
+	 * (window or nearest overflowing ancestor). It reports both scrolling
+	 * and layout shifts that move a node, so each settling-relayout frame
+	 * that pushes the cursor off-screen re-triggers the scroll until the
+	 * layout stabilises. The watch ends on a selection change or after a
+	 * 500 ms safety cap — short enough that a deliberate user scroll
+	 * inside it isn't a coherent gesture for a human, so no separate
+	 * cancellation event source is needed.
 	 *
 	 * @param {NodeSelection} selection
 	 * @param {Element} node_array_el
@@ -1350,6 +1388,12 @@ ${fallback_html}`;
 		const node_array_path = selection.path;
 		const selection_snapshot = JSON.stringify(selection);
 
+		// For Svedit mounted inside an overflowing ancestor, that ancestor —
+		// not the window — is the scrollable surface. Discover it once so
+		// the observer root and the visibility check below match the
+		// surface the user actually scrolls.
+		const scroll_root = __nearest_scroll_root(node_array_el);
+
 		// Scroll the cursor into view, but only when it is genuinely
 		// off-screen. cursor_offset is a gap offset and the gap has no box
 		// of its own, so visibility is judged from the nodes flanking it.
@@ -1359,19 +1403,33 @@ ${fallback_html}`;
 			const cursor_offset = is_backward ? selection.anchor_offset : selection.focus_offset;
 			const array_length = session.get(node_array_path).length;
 
-			// If either node flanking the cursor is already (even partially)
-			// on screen, the cursor is visible — keep the viewport stable and
-			// scroll nothing. node_before is null at offset 0: cursor_offset
-			// - 1 would be -1, and serialize_path rejects a negative index.
+			// node_before is null at offset 0: cursor_offset - 1 would be
+			// -1, and serialize_path rejects a negative index.
 			const node_before = cursor_offset > 0
 				? __get_node_element(node_array_path, cursor_offset - 1)
 				: null;
 			const node_after = __get_node_element(node_array_path, cursor_offset);
-			if (__intersects_viewport(node_before) || __intersects_viewport(node_after)) return;
 
+			// Array edges: the cursor sits past its single flank, so the
+			// flank being on-screen tells us nothing about whether the
+			// cursor is. First adjust the array's own scrollLeft/Top to
+			// the matching extreme so the trailing/leading position is
+			// revealed inside the array. Then, if the flank is STILL off-
+			// screen, the array itself is out of view (e.g. user scrolled
+			// to the bottom of the page then pressed undo to restore
+			// content above) — `scrollIntoView` brings ancestors with it.
+			// The "still off-screen" check matters: in a horizontally-
+			// overflowing array whose row is visible (the row-buttons
+			// case), the scrollLeft adjustment alone reveals the flank,
+			// and an unconditional scrollIntoView there would disturb the
+			// array's own scroll position back from `max_left` in some
+			// browsers.
 			if (cursor_offset === 0) {
 				node_array_el.scrollLeft = 0;
 				node_array_el.scrollTop = 0;
+				if (!__intersects_viewport(node_after, scroll_root)) {
+					node_after?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+				}
 				return;
 			}
 			if (cursor_offset >= array_length) {
@@ -1385,11 +1443,20 @@ ${fallback_html}`;
 				);
 				node_array_el.scrollLeft = max_left;
 				node_array_el.scrollTop = max_top;
-				if (max_left === 0 && max_top === 0) {
+				if (!__intersects_viewport(node_before, scroll_root)) {
 					node_before?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
 				}
 				return;
 			}
+
+			// Middle case: if either flanking node is already (even
+			// partially) on screen, the cursor between them is too — keep
+			// the viewport stable and scroll nothing.
+			if (
+				__intersects_viewport(node_before, scroll_root) ||
+				__intersects_viewport(node_after, scroll_root)
+			) return;
+
 			// A range selection's selected node IS node_before; scrolling
 			// node_after would reveal the following node and leave the
 			// selection itself off-screen. For a collapsed caret node_after's
@@ -1412,26 +1479,16 @@ ${fallback_html}`;
 
 		/** @type {IntersectionObserver | null} */
 		let observer = null;
-		let grace_timeout = 0;
 		let safety_timeout = 0;
 
 		const stop = () => {
 			observer?.disconnect();
 			observer = null;
-			window.clearTimeout(grace_timeout);
 			window.clearTimeout(safety_timeout);
-			window.removeEventListener('wheel', on_user_scroll);
-			window.removeEventListener('touchmove', on_user_scroll);
 			if (cancel_node_scroll_watch === stop) cancel_node_scroll_watch = null;
 		};
 
-		// A deliberate scroll by the user wins over our reveal. These
-		// listeners are attached only once the grace period is over, so the
-		// settling relayout — and any inertial scroll still trailing from the
-		// action that triggered this render — cannot abort the watch.
-		const on_user_scroll = () => stop();
-
-		// Fires when a flanking node crosses the viewport edge — whether the
+		// Fires when a flanking node crosses the root's edge — whether the
 		// page scrolled or the settling relayout moved the node. Re-run the
 		// scroll check on each crossing; stop once the selection moves on.
 		const on_intersection = () => {
@@ -1439,15 +1496,17 @@ ${fallback_html}`;
 			scroll_cursor_into_view();
 		};
 
-		observer = new IntersectionObserver(on_intersection);
+		observer = new IntersectionObserver(on_intersection, { root: scroll_root });
 		if (flank_before) observer.observe(flank_before);
 		if (flank_after) observer.observe(flank_after);
-		grace_timeout = window.setTimeout(() => {
-			window.addEventListener('wheel', on_user_scroll, { passive: true });
-			window.addEventListener('touchmove', on_user_scroll, { passive: true });
-		}, 500);
-		// A live editor can keep reflowing; don't watch indefinitely.
-		safety_timeout = window.setTimeout(stop, 2000);
+		// 500 ms safety cap. A deliberate user scroll inside this window
+		// isn't a coherent human gesture at that timescale, so we don't
+		// need a separate wheel/touch cancellation path — its race with
+		// the settling relayout was the main reason this stretched to 2 s
+		// before. If genuine slow layout (e.g. late-loading images) needs
+		// more headroom, the right fix is deterministic dimensions on the
+		// model rather than a longer watch here.
+		safety_timeout = window.setTimeout(stop, 500);
 		cancel_node_scroll_watch = stop;
 	}
 
diff --git a/src/test/gap_visibility.svelte.test.js b/src/test/gap_visibility.svelte.test.js
index b5869e79..1e45c8fa 100644
--- a/src/test/gap_visibility.svelte.test.js
+++ b/src/test/gap_visibility.svelte.test.js
@@ -269,6 +269,106 @@ describe('NodeGap visibility & placement', () => {
 				expect(gap.classList.contains('positioned')).toBe(true);
 			}
 		});
+
+		// Regression for the wrap/grid layout case (figma-config-presentation):
+		// when a row's height exceeds the 500 px overscan, the next row's first
+		// node never enters `near_map` even while the previous row's trailing
+		// node is right under the user. The mid-gap gate USED to require both
+		// flanks to be in near_map and stranded the between-row gap; the fix
+		// gates on prev only (the gap's CSS position-anchor + position-visibility
+		// already hide it when the anchor is off-viewport).
+		it('positions mid gaps when only the previous flank is in near_map', async () => {
+			const session = make_image_grid_session(5);
+			const { container } = render(SveditTest, { session });
+			await settle_grid();
+
+			const array_el = find_image_grid_array(container);
+			expect(array_el).not.toBeNull();
+
+			const ctx = /** @type {any} */ (globalThis).__svedit_ctx_for_test;
+			expect(ctx).toBeTruthy();
+			const near_map = ctx.visibility_registry.near_map;
+			const array_path = array_el.dataset.path;
+
+			// Force state: only item 1 is near (e.g. the user is scrolled
+			// such that row 1 is in view but row 2 is far below overscan).
+			near_map.clear();
+			near_map.set(`${array_path}__1`, true);
+
+			const gap = array_el.querySelector(
+				':scope > .node-gap.gap-after[data-gap-offset="2"]:not(.last)'
+			);
+			expect(gap).not.toBeNull();
+			ctx.visibility_registry.sync_gap_class(gap);
+
+			expect(
+				gap.classList.contains('positioned'),
+				'mid gap should be positioned when only prev flank is in near_map'
+			).toBe(true);
+		});
+
+		// Companion to the gap-positioning regression above: NodeGapMarkers
+		// emit a mid `.gap-marker` based on `array_indices` (the per-array
+		// view of near_map). The marker logic USED to require two consecutive
+		// indices and silently dropped the between-row marker even after the
+		// underlying gap had `.positioned`. This test pins the matching
+		// "prev-only" rule on the marker.
+		it('emits a mid gap-marker when only the previous flank is in array_indices', async () => {
+			const session = make_image_grid_session(5);
+			const { container } = render(SveditTest, { session });
+			await settle_grid();
+
+			const array_el = find_image_grid_array(container);
+			expect(array_el).not.toBeNull();
+
+			const ctx = /** @type {any} */ (globalThis).__svedit_ctx_for_test;
+			expect(ctx).toBeTruthy();
+			const array_path = array_el.dataset.path;
+			const indices = ctx.visibility_registry.get_array_indices(array_path);
+
+			// Force state: only item 1 is in the visible-indices set.
+			indices.clear();
+			indices.add(1);
+			await settle_grid();
+
+			const marker = container.querySelector(
+				`.gap-marker.gap-mid[data-gap-offset="2"]`
+			);
+			expect(
+				marker,
+				'mid gap-marker should be emitted when only prev is in array_indices'
+			).not.toBeNull();
+		});
+	});
+
+	// Regression for the typing-at-overflow-edge issue: when a button's text
+	// overflows the array's horizontal scroll, the browser's caret-follow
+	// scroll lands `scrollLeft` flush against the array edge — leaving
+	// edge_map.last false (it requires reaching scrollWidth - clientWidth
+	// within EDGE_TOLERANCE_PX) and stranding the trailing gap as
+	// unpositioned. The fix is `scroll-padding-inline/block` on every
+	// node-array, so the browser leaves room when scrolling the caret into
+	// view. This test pins the default and its computed value.
+	describe('scroll-padding defaults on node arrays', () => {
+		it('applies non-zero scroll-padding-inline and -block on every node-array', async () => {
+			const session = make_story_session(3);
+			const { container } = render(SveditTest, { session });
+			await settle();
+
+			const array_el = find_buttons_array(container);
+			expect(array_el).not.toBeNull();
+
+			const cs = getComputedStyle(array_el);
+			// 2 × --node-caret-edge-gap = 48 px default. Don't pin an exact
+			// value here — the default is intentionally configurable via
+			// `--node-caret-scroll-padding-inline/block` — but non-zero is
+			// the load-bearing assertion: zero would let the caret-follow
+			// scroll pin flush against the edge and re-introduce the bug.
+			expect(parseFloat(cs.scrollPaddingInlineStart)).toBeGreaterThan(0);
+			expect(parseFloat(cs.scrollPaddingInlineEnd)).toBeGreaterThan(0);
+			expect(parseFloat(cs.scrollPaddingBlockStart)).toBeGreaterThan(0);
+			expect(parseFloat(cs.scrollPaddingBlockEnd)).toBeGreaterThan(0);
+		});
 	});
 
 	describe('edge_map state', () => {
diff --git a/src/test/selection_scroll.svelte.test.js b/src/test/selection_scroll.svelte.test.js
index e139fa44..e3462525 100644
--- a/src/test/selection_scroll.svelte.test.js
+++ b/src/test/selection_scroll.svelte.test.js
@@ -213,6 +213,65 @@ describe('node-selection scroll-into-view (wrap-grid image_grid)', () => {
 	});
 });
 
+describe('node-selection scroll-into-view (offscreen array)', () => {
+	beforeEach(() => {
+		window.scrollTo(0, 0);
+	});
+
+	// Regression for issue #288: user adds 10 buttons, deletes them,
+	// scrolls to the bottom of the page, then presses undo. The restored
+	// buttons used to land off-screen and require a SECOND undo to scroll
+	// back into view — because the trailing-branch only set the array's
+	// own scrollLeft/Top (which doesn't move ancestors), and the previous
+	// `if (max_left === 0 && max_top === 0)` gate skipped `scrollIntoView`
+	// in horizontally-overflowing arrays even when the array itself was
+	// off-screen vertically. The new condition gates on the flanking node
+	// not being in viewport AFTER the inside-array scroll adjustment.
+	it('reveals an offscreen horizontally-overflowing array when a model-driven node selection lands on it', async () => {
+		const session = make_story_session(10);
+		const { container } = render(SveditTest, { session });
+		await settle();
+
+		const arr = find_buttons_array(container);
+		expect(arr).not.toBeNull();
+		expect(arr.scrollWidth).toBeGreaterThan(arr.clientWidth + 100);
+
+		// vitest's default viewport is small — the story alone may not be
+		// taller than the viewport, so window.scrollTo would no-op. Inject
+		// a tall sentinel below the editor so the page is scrollable past
+		// the buttons array.
+		const sentinel = document.createElement('div');
+		sentinel.style.height = '5000px';
+		sentinel.id = '__svedit_scroll_test_sentinel';
+		document.body.appendChild(sentinel);
+
+		try {
+			window.scrollTo(0, document.documentElement.scrollHeight);
+			await settle();
+			const before = arr.getBoundingClientRect();
+			expect(before.bottom, `array should be above viewport before; rect=${JSON.stringify({t:before.top, b:before.bottom})}`).toBeLessThan(0);
+
+			// Model-driven selection landing on the (offscreen) array —
+			// equivalent to undo restoring buttons + selection.
+			const canvas = container.querySelector('.svedit-canvas');
+			canvas.focus();
+			session.selection = {
+				type: 'node',
+				path: ['page_1', 'body', 0, 'buttons'],
+				anchor_offset: 0,
+				focus_offset: 10
+			};
+			await settle();
+
+			const after = arr.getBoundingClientRect();
+			const in_viewport = after.bottom > 0 && after.top < window.innerHeight;
+			expect(in_viewport, `array rect=${JSON.stringify({ t: after.top, b: after.bottom, vh: window.innerHeight })}`).toBe(true);
+		} finally {
+			sentinel.remove();
+		}
+	});
+});
+
 describe('node-selection: DOM-driven vs. model-driven', () => {
 	beforeEach(() => {
 		window.scrollTo(0, 0);