svedit 0.11.0 → 0.12.0

package/dist/node_visibility.svelte.js

@@ -15,11 +15,31 @@
  * by viewport visibility. Off-screen NodeGaps remain as zero-size
  * absolute elements with no anchor cost.
  *
- * ## Two observers + a scroll listener
+ * ## Element registration via attachments
  *
- * **Overscan IO** (`rootMargin: 500px`, threshold `[0, 1]`) — fills
- * `near_map` and per-array `array_indices`. Drives `.positioned`
- * activation on adjacent gaps via `sync_gaps_around_node`.
+ * Node elements (Node.svelte and the empty-array placeholder) register
+ * themselves with `{@attach registry.track_node(path)}`; node-array
+ * containers use `{@attach registry.track_array(path)}`. Attachments
+ * re-run whenever Svelte recreates the element or its path changes, so
+ * observation and per-path state follow the DOM's actual lifecycle —
+ * including DOM recreation without a document change (e.g. dev-mode
+ * HMR component swaps), which a document-driven reconciliation pass
+ * would miss.
+ *
+ * During keyed updates several elements can change paths at once
+ * (e.g. 0→1 while a new element claims 0), and Svelte doesn't
+ * guarantee attachment ordering across elements. Per-path ownership
+ * maps make unregistration collision-safe: a teardown only clears a
+ * path's state if that element still owns the path.
+ *
+ * ## Two observers
+ *
+ * **Overscan IO** (`rootMargin: 500px`, threshold `0`) — fills the
+ * per-array `array_indices` sets. NodeGap derives its `.positioned`
+ * class reactively from them. Registration seeds
+ * the state synchronously from one getBoundingClientRect (so there's
+ * no unpositioned flash on mount); the IO owns subsequent viewport
+ * transitions, including layout-shift-induced ones.
  *
  * **Viewport IO** (`rootMargin: 0`, threshold `[0, 1]`) — toggles
  * view classes (`.in-view`, `.fully-in-view`, …) on node elements.
@@ -38,13 +58,26 @@
  * immediately) and a RAF flush that reads only scrollLeft / scrollWidth /
  * clientWidth on the dirty array.
  *
+ * **Document changes** — content changes alter an array's scroll
+ * extent without recreating the array element, so after Svelte
+ * updates the DOM all registered arrays re-sync their edge state in
+ * one batch.
+ *
+ * **Array ResizeObserver** — box-size changes (window resize, sidebar
+ * toggle, responsive breakpoint) can flip an array between fitting
+ * and overflowing without a scroll event or document change; a shared
+ * ResizeObserver on registered arrays re-syncs their edge state.
+ *
  * ## Reactivity
  *
- * State lives in SvelteMap (near_map, edge_map) and per-array SvelteSet
- * (array_indices). Consumers (NodeGap via sync_gap_class, NodeGapMarkers
- * via $derived) read via .has()/.get() — Svelte's runtime tracks at
+ * State lives in per-array SvelteSets (array_indices, the single
+ * source of truth for node nearness) and a SvelteMap (edge_map).
+ * Consumers (NodeGap and NodeGapMarkers, both via
+ * $derived) read via .has()/.get() — Svelte's runtime tracks at
  * per-key granularity, so only consumers whose specific dependencies
- * changed re-evaluate.
+ * changed re-evaluate. Because the `.positioned` class is applied
+ * declaratively by NodeGap, it survives DOM recreation that happens
+ * without a document change (e.g. dev-mode HMR component swaps).
  *
  * View classes are toggled imperatively (no Svelte consumers — they're
  * pure CSS hooks for app code).
@@ -53,12 +86,9 @@
  */
 
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
-import { untrack } from 'svelte';
+import { tick, untrack } from 'svelte';
 import { PATH_SEPARATOR } from './utils.js';
 
-const NODE_SELECTOR = '[data-type="node"][data-path]';
-const GAP_SELECTOR = '.node-gap[data-gap-array-path]';
-
 /**
  * Overscan margin around the viewport (px). Nodes within this distance
  * of the viewport get anchor positioning activated and gap markers
@@ -78,17 +108,17 @@ const EDGE_TOLERANCE_PX = 10;
 
 /**
  * Single source of truth for "which node DOM elements are near or in
- * the viewport". Owns the IntersectionObserver and the reactive maps
- * consumed by NodeGap and NodeGapMarkers.
+ * the viewport". Owns the IntersectionObservers and the reactive maps
+ * consumed by NodeGap and NodeGapMarkers. Elements register through
+ * the track_node / track_array attachments.
  */
 class VisibilityRegistry {
-	/** Per-node "in overscan zone" flag. NodeGap reads via `.has(path)`. */
-	near_map = new SvelteMap();
-
 	/**
-	 * Per-array set of near child indices. NodeGapMarkers iterates the
-	 * set for its array. Stable references — once a SvelteSet is created
-	 * for an array path it survives re-renders so consumers stay subscribed.
+	 * Per-array set of near ("in overscan zone") child indices — the
+	 * single source of truth for node nearness. NodeGap reads via
+	 * `.has(index)`, NodeGapMarkers iterates the set for its array.
+	 * Stable references — once a SvelteSet is created for an array path
+	 * it survives re-renders so consumers stay subscribed.
 	 *
 	 * @type {Map<string, SvelteSet<number>>}
 	 */
@@ -98,10 +128,11 @@ class VisibilityRegistry {
 	 * Per-array edge-proximity state. `first` is true when the first
 	 * node's leading edge is within EDGE_TOLERANCE_PX of the array
 	 * container's leading edge; `last` is the symmetric trailing-edge
-	 * check on the last node. Recomputed on scroll/resize via BCR
-	 * because IntersectionObserver only fires on intersection-ratio
-	 * threshold crossings and would otherwise miss horizontal-overflow
-	 * scroll changes that don't change the visibility ratio.
+	 * check on the last node. Recomputed on scroll, on array box
+	 * resize and after document changes because IntersectionObserver
+	 * only fires on intersection-ratio threshold crossings and would
+	 * otherwise miss horizontal-overflow scroll changes that don't
+	 * change the visibility ratio.
 	 *
 	 * NodeGap and NodeGapMarkers read this to gate edge gaps so they
 	 * only render when the edge node has actually reached the matching
@@ -117,9 +148,43 @@ class VisibilityRegistry {
 	/** @type {IntersectionObserver | null} */
 	#view_io = null;
 
+	/**
+	 * Re-syncs edge state when a registered array's box changes size
+	 * (window resize, sidebar toggle, responsive breakpoint, late-
+	 * loading content). Size changes can flip an array between fitting
+	 * and overflowing without firing a scroll event or a document
+	 * change, so neither of the other two triggers would catch them.
+	 * Writes are change-detected, so redundant firings are no-ops.
+	 *
+	 * @type {ResizeObserver | null}
+	 */
+	#array_ro = null;
+
+	/**
+	 * Registered node elements and the path each was registered under.
+	 * The attachment closure carries the path, so a stale data-path
+	 * attribute can never desync state.
+	 *
+	 * @type {Map<HTMLElement, string>}
+	 */
+	#registered_paths = new Map();
+
+	/**
+	 * Which element currently owns a node path. Guards unregistration
+	 * against keyed-update collisions (see module doc).
+	 *
+	 * @type {Map<string, HTMLElement>}
+	 */
+	#path_owners = new Map();
+
 	/** @type {Set<HTMLElement>} */
-	#pending_view_sync = new Set();
-	#pending_view_raf = 0;
+	#near_nodes = new Set();
+
+	/** Registered node-array container elements. @type {Set<Element>} */
+	#array_els = new Set();
+
+	/** Which element currently owns an array path. @type {Map<string, Element>} */
+	#array_owners = new Map();
 
 	/**
 	 * When true, a second IO (rootMargin 0, actual viewport) toggles
@@ -138,14 +203,10 @@ class VisibilityRegistry {
 	view_classes = true;
 
 	/**
-	 * When true, the overscan IO populates near_map and gates
-	 * `.positioned` on gap elements by viewport proximity. When false,
-	 * the overscan IO is skipped entirely: observe() pre-populates
-	 * near_map / array_indices as if every node were always in the
-	 * overscan zone, so every gap is `.positioned` and every marker
-	 * renders. Useful for diagnosing whether a layout bug originates
-	 * in the IO culling logic vs. the underlying CSS / anchor
-	 * positioning.
+	 * When true, the overscan IO populates array_indices and NodeGap gates
+	 * `.positioned` by viewport proximity. When false, the overscan IO
+	 * is skipped and every registered node counts as near, so every gap
+	 * is `.positioned` and every marker renders.
 	 *
 	 * Disabling makes anchor positioning O(N) over every node in the
 	 * document and is intended for debugging only; large documents
@@ -174,6 +235,11 @@ class VisibilityRegistry {
 				threshold: [0, 1]
 			});
 		}
+		if (!this.#array_ro) {
+			this.#array_ro = new ResizeObserver((entries) => {
+				for (const entry of entries) this.sync_edge_state(entry.target);
+			});
+		}
 	}
 
 	stop() {
@@ -181,10 +247,13 @@ class VisibilityRegistry {
 		this.#io = null;
 		this.#view_io?.disconnect();
 		this.#view_io = null;
-		cancelAnimationFrame(this.#pending_view_raf);
-		this.#pending_view_raf = 0;
-		this.#pending_view_sync.clear();
-		this.near_map.clear();
+		this.#array_ro?.disconnect();
+		this.#array_ro = null;
+		this.#registered_paths.clear();
+		this.#path_owners.clear();
+		this.#near_nodes.clear();
+		this.#array_els.clear();
+		this.#array_owners.clear();
 		this.edge_map.clear();
 		for (const set of this.#array_indices.values()) set.clear();
 	}
@@ -195,6 +264,13 @@ class VisibilityRegistry {
 	 * subscription — the same set is returned on subsequent calls so
 	 * Svelte's per-set tracking remains intact across re-evaluations.
 	 *
+	 * IMPORTANT: hold the returned set in its own $derived and read
+	 * membership from a different one (see NodeGap / NodeGapMarkers).
+	 * Svelte does not track dependencies on state created inside the
+	 * currently-evaluating reaction, so a consumer that lazily creates
+	 * the set and reads `.has()` in the same derived never subscribes
+	 * and never re-evaluates.
+	 *
 	 * @param {string} array_path_str
 	 * @returns {SvelteSet<number>}
 	 */
@@ -207,85 +283,148 @@ class VisibilityRegistry {
 		return set;
 	}
 
-	/** @param {HTMLElement} el */
-	observe(el) {
-		if (this.visibility_culling) {
-			this.#io?.observe(el);
-		} else {
-			// No overscan IO: treat every node as always near with no
-			// clipping. near_map / array_indices population mirrors what
-			// the IO would write on its first callback, just without the
-			// per-node viewport check. Sibling gaps still need a sync
-			// pass because no IO callback will fire to drive it.
-			//
-			// untrack() is critical: the bootstrap loop calls observe()
-			// from inside the create_node_visibility $effect, and the
-			// .has() reads on reactive Map/Set would subscribe that
-			// effect to the same maps we then write to — invalidating
-			// itself and re-running the cleanup→start cycle infinitely.
-			const path = el.dataset?.path;
-			if (path) {
+	/**
+	 * Attachment factory for node elements (Node.svelte and the
+	 * empty-array placeholder). Registers the element under `path`,
+	 * seeds its near / view-class state synchronously from one BCR, and
+	 * hands the element to the IntersectionObservers for subsequent
+	 * viewport transitions. Re-runs when the element is recreated or
+	 * its path changes; the teardown unregisters collision-safely.
+	 *
+	 * @param {string} path
+	 */
+	track_node(path) {
+		return (/** @type {HTMLElement} */ el) => {
+			this.#register_node(el, path);
+			return () => this.#unregister_node(el, path);
+		};
+	}
+
+	/**
+	 * Attachment factory for node-array container elements. Registered
+	 * arrays get their edge state synced on mount, on scroll (via the
+	 * document scroll listener) and after document changes.
+	 *
+	 * @param {string} path
+	 */
+	track_array(path) {
+		return (/** @type {Element} */ el) => {
+			this.start();
+			this.#array_els.add(el);
+			this.#array_owners.set(path, el);
+			this.#array_ro?.observe(el);
+			// Sync synchronously — the RO's initial callback fires a frame
+			// later and would flash edge gaps un-positioned on mount.
+			this.sync_edge_state(el);
+			return () => {
+				this.#array_els.delete(el);
+				this.#array_ro?.unobserve(el);
 				untrack(() => {
-					let any_change = false;
-					if (!this.near_map.has(path)) {
-						this.near_map.set(path, true);
-						any_change = true;
-					}
-					const split = this.#split_path(path);
-					if (split) {
-						const set = this.get_array_indices(split.array_path);
-						if (!set.has(split.index)) {
-							set.add(split.index);
-							any_change = true;
-						}
+					if (this.#array_owners.get(path) === el) {
+						this.#array_owners.delete(path);
+						this.edge_map.delete(path);
 					}
-					if (any_change) this.sync_gaps_around_node(el);
 				});
-			}
+			};
+		};
+	}
+
+	/**
+	 * Whether an element is a registered node-array container of this
+	 * registry instance. Scopes the document-level scroll listener to
+	 * this editor without any DOM traversal.
+	 *
+	 * @param {Element} el
+	 */
+	has_array(el) {
+		return this.#array_els.has(el);
+	}
+
+	/**
+	 * Re-sync edge state for every registered array. Called after
+	 * document changes: content changes alter scroll extents without
+	 * recreating the array element, so the attachments can't see them.
+	 */
+	sync_all_edge_states() {
+		for (const el of this.#array_els) {
+			if (el.isConnected) this.sync_edge_state(el);
 		}
-		this.#view_io?.observe(el);
 	}
 
-	/** @param {HTMLElement} el */
-	unobserve(el) {
+	/**
+	 * @param {HTMLElement} el
+	 * @param {string} path
+	 */
+	#register_node(el, path) {
+		this.start();
+		untrack(() => {
+			this.#registered_paths.set(el, path);
+			this.#path_owners.set(path, el);
+			this.#io?.observe(el);
+			this.#view_io?.observe(el);
+
+			// Seed state synchronously so freshly mounted (or recreated)
+			// elements don't wait a frame for the IO's initial callback —
+			// that would flash gaps un-positioned. The IO owns all later
+			// transitions.
+			const needs_rect = this.visibility_culling || this.view_classes;
+			const bcr = needs_rect ? el.getBoundingClientRect() : null;
+			const vh = window.innerHeight;
+			const vw = window.innerWidth;
+			const is_near =
+				!this.visibility_culling ||
+				(bcr.bottom > -OVERSCAN_PX &&
+					bcr.top < vh + OVERSCAN_PX &&
+					bcr.right > -OVERSCAN_PX &&
+					bcr.left < vw + OVERSCAN_PX);
+			if (is_near) this.#add_near_node(el, path);
+
+			if (this.view_classes) {
+				const in_viewport = bcr.bottom > 0 && bcr.top < vh && bcr.right > 0 && bcr.left < vw;
+				this.#apply_view_classes(el, in_viewport, bcr, vh);
+			}
+		});
+	}
+
+	/**
+	 * @param {HTMLElement} el
+	 * @param {string} path
+	 */
+	#unregister_node(el, path) {
+		this.#registered_paths.delete(el);
+		this.#near_nodes.delete(el);
 		this.#io?.unobserve(el);
 		this.#view_io?.unobserve(el);
-		const path = el.dataset?.path;
-		if (path) this.#forget(path);
+		untrack(() => {
+			// Ownership guard: during keyed updates another element may
+			// have already claimed this path — its state must survive.
+			if (this.#path_owners.get(path) === el) {
+				this.#path_owners.delete(path);
+				const split = this.#split_path(path);
+				if (split) this.#array_indices.get(split.array_path)?.delete(split.index);
+			}
+		});
 	}
 
 	/**
-	 * Imperatively toggle .positioned on a single gap element based on
-	 * current near_map / edge_map state. Reads dataset + classList for
-	 * gap context (no Svelte reactivity).
-	 *
-	 * @param {Element} gap_el
+	 * @param {HTMLElement} el
+	 * @param {string} path
 	 */
-	sync_gap_class(gap_el) {
-		const el = /** @type {HTMLElement} */ (gap_el);
-		const arr = el.dataset.gapArrayPath;
-		if (!arr) return;
-		const offset = parseInt(el.dataset.gapOffset, 10);
-		const is_last = el.classList.contains('last');
-		const empty = el.classList.contains('empty');
-		el.classList.toggle(
-			'positioned',
-			should_position_gap_imperative(this, arr, offset, is_last, empty)
-		);
+	#add_near_node(el, path) {
+		this.#near_nodes.add(el);
+		const split = this.#split_path(path);
+		if (split) this.get_array_indices(split.array_path).add(split.index);
 	}
 
 	/**
-	 * Toggle .positioned on the two gap elements adjacent to a node
-	 * element. Used after near_map writes triggered by IO, MO, or
-	 * bootstrap. O(1) DOM sibling traversal.
-	 *
-	 * @param {Element} node_el
+	 * @param {HTMLElement} el
+	 * @param {string} path
 	 */
-	sync_gaps_around_node(node_el) {
-		const prev = node_el.previousElementSibling;
-		if (prev?.classList.contains('node-gap')) this.sync_gap_class(prev);
-		const next = node_el.nextElementSibling;
-		if (next?.classList.contains('node-gap')) this.sync_gap_class(next);
+	#remove_near_node(el, path) {
+		this.#near_nodes.delete(el);
+		if (this.#path_owners.get(path) !== el) return;
+		const split = this.#split_path(path);
+		if (split) this.#array_indices.get(split.array_path)?.delete(split.index);
 	}
 
 	/**
@@ -314,13 +453,11 @@ class VisibilityRegistry {
 		const path = /** @type {HTMLElement} */ (array_el).dataset.path;
 		if (!path) return false;
 
-		const sl = array_el.scrollLeft;
-		const sw = array_el.scrollWidth;
-		const cw = array_el.clientWidth;
-		const st = array_el.scrollTop;
-		const sh = array_el.scrollHeight;
-		const ch = array_el.clientHeight;
-
+		// Check computed overflow BEFORE touching scroll metrics. Reading
+		// scrollLeft/scrollWidth forces a synchronous layout when the DOM is
+		// dirty, while getComputedStyle only forces style recalc. Non-clipping
+		// arrays — the common case (a plain column body) — resolve to
+		// first=last=true without any scroll-metric read.
 		const style = getComputedStyle(array_el);
 		const clips_x = style.overflowX !== 'visible';
 		const clips_y = style.overflowY !== 'visible';
@@ -329,12 +466,18 @@ class VisibilityRegistry {
 		// Normal wrapping/grid node arrays often have harmless layout overflow
 		// (scrollWidth > clientWidth) while overflow remains visible; treating
 		// that as scroll position would incorrectly hide edge gaps.
-		const first =
-			(!clips_x || sl <= EDGE_TOLERANCE_PX) &&
-			(!clips_y || st <= EDGE_TOLERANCE_PX);
-		const last =
-			(!clips_x || sl + cw >= sw - EDGE_TOLERANCE_PX) &&
-			(!clips_y || st + ch >= sh - EDGE_TOLERANCE_PX);
+		let first = true;
+		let last = true;
+		if (clips_x) {
+			const sl = array_el.scrollLeft;
+			first = sl <= EDGE_TOLERANCE_PX;
+			last = sl + array_el.clientWidth >= array_el.scrollWidth - EDGE_TOLERANCE_PX;
+		}
+		if (clips_y) {
+			const st = array_el.scrollTop;
+			first = first && st <= EDGE_TOLERANCE_PX;
+			last = last && st + array_el.clientHeight >= array_el.scrollHeight - EDGE_TOLERANCE_PX;
+		}
 
 		return untrack(() => {
 			const prev = this.edge_map.get(path);
@@ -344,81 +487,6 @@ class VisibilityRegistry {
 		});
 	}
 
-	/**
-	 * Sync edge state and toggle .positioned on first/last gaps. Early-
-	 * exits when edge_map is unchanged — for the structural-mutation
-	 * path where the edge gap may need re-evaluation regardless of
-	 * edge_map, see resync_array_edge_gaps below.
-	 *
-	 * @param {Element} array_el
-	 */
-	sync_array_edge_gaps(array_el) {
-		if (!this.sync_edge_state(array_el)) return;
-		this.#sync_first_last_gaps(array_el);
-	}
-
-	/**
-	 * Force-resync first/last gaps after a structural mutation. The
-	 * trailing gap is a reused Svelte component whose `.positioned`
-	 * state may need re-deriving even when edge_map didn't change.
-	 *
-	 * @param {Element} array_el
-	 */
-	resync_array_edge_gaps(array_el) {
-		this.sync_edge_state(array_el);
-		this.#sync_first_last_gaps(array_el);
-	}
-
-	/** @param {Element} array_el */
-	#sync_first_last_gaps(array_el) {
-		const first_gap = array_el.querySelector(':scope > .node-gap.gap-before:not(.empty)');
-		const last_gap = array_el.querySelector(':scope > .node-gap.gap-after.last');
-		if (first_gap) this.sync_gap_class(first_gap);
-		if (last_gap) this.sync_gap_class(last_gap);
-	}
-
-	/**
-	 * Queue a node for deferred view-class sync. Unobserves from the
-	 * viewport IO immediately to prevent its initial callback from
-	 * racing with the RAF, then re-observes in #flush_view_sync after
-	 * classes are applied via BCR. Multiple MO-triggered insertions
-	 * coalesce into a single RAF / layout pass.
-	 *
-	 * @param {HTMLElement} el
-	 */
-	schedule_view_sync(el) {
-		if (!this.view_classes) return;
-		this.#view_io?.unobserve(el);
-		this.#pending_view_sync.add(el);
-		if (!this.#pending_view_raf) {
-			this.#pending_view_raf = requestAnimationFrame(() => this.#flush_view_sync());
-		}
-	}
-
-	#flush_view_sync() {
-		this.#pending_view_raf = 0;
-		const vh = window.innerHeight;
-		const vw = window.innerWidth;
-		// Read all BCRs first, then write all classes. A read-write-read
-		// interleave (the natural single-pass shape) forces a layout
-		// flush on every iteration when the toggled classes affect
-		// layout — which user apps are free to do via `.in-view` /
-		// `.fully-in-view` / etc. Two passes batch the layout reads into
-		// one flush regardless of what the consumer wires up.
-		/** @type {Array<{el: HTMLElement, bcr: DOMRectReadOnly}>} */
-		const items = [];
-		for (const el of this.#pending_view_sync) {
-			if (el.isConnected) items.push({ el, bcr: el.getBoundingClientRect() });
-		}
-		for (const { el, bcr } of items) {
-			const in_viewport =
-				bcr.bottom > 0 && bcr.top < vh && bcr.right > 0 && bcr.left < vw;
-			this.#apply_view_classes(el, in_viewport, bcr, vh);
-			this.#view_io?.observe(el);
-		}
-		this.#pending_view_sync.clear();
-	}
-
 	/**
 	 * @param {HTMLElement} el
 	 * @param {boolean} in_viewport
@@ -440,18 +508,6 @@ class VisibilityRegistry {
 		}
 	}
 
-	/** @param {string} path */
-	#forget(path) {
-		this.near_map.delete(path);
-		const split = this.#split_path(path);
-		if (split) {
-			const set = this.#array_indices.get(split.array_path);
-			set?.delete(split.index);
-			// Keep the SvelteSet alive — its NodeGapMarkers consumer may
-			// still be mounted. Recreating would orphan the subscription.
-		}
-	}
-
 	/**
 	 * @param {string} path
 	 * @returns {{ array_path: string, index: number } | null}
@@ -465,39 +521,21 @@ class VisibilityRegistry {
 	}
 
 	/**
-	 * Overscan IO callback. Manages near_map and array_indices, then
-	 * imperatively toggles .positioned on adjacent gaps.
+	 * Overscan IO callback. Manages the array_indices sets; NodeGap
+	 * reacts to the map writes and updates .positioned declaratively.
 	 *
 	 * @param {IntersectionObserverEntry[]} entries
 	 */
 	#process_near(entries) {
 		for (const entry of entries) {
 			const el = /** @type {HTMLElement} */ (entry.target);
-			const path = el.dataset.path;
-			if (!path) continue;
+			const path = this.#registered_paths.get(el);
+			if (!path || !el.isConnected) continue;
 
 			const is_near = entry.isIntersecting;
-
-			let any_change = false;
-
-			if (is_near) {
-				if (!this.near_map.has(path)) {
-					this.near_map.set(path, true);
-					any_change = true;
-				}
-			} else if (this.near_map.has(path)) {
-				this.near_map.delete(path);
-				any_change = true;
-			}
-
-			const split = this.#split_path(path);
-			if (split) {
-				const set = this.get_array_indices(split.array_path);
-				if (is_near) set.add(split.index);
-				else set.delete(split.index);
-			}
-
-			if (any_change) this.sync_gaps_around_node(el);
+			if (is_near === this.#near_nodes.has(el)) continue;
+			if (is_near) this.#add_near_node(el, path);
+			else this.#remove_near_node(el, path);
 		}
 	}
 
@@ -512,25 +550,21 @@ class VisibilityRegistry {
 		const vh = window.innerHeight;
 		for (const entry of entries) {
 			const el = /** @type {HTMLElement} */ (entry.target);
-			if (!el.dataset.path) continue;
+			if (!this.#registered_paths.has(el) || !el.isConnected) continue;
 			this.#apply_view_classes(el, entry.isIntersecting, entry.boundingClientRect, vh);
 		}
 	}
-
-	// #clip_bits and clip_map were removed: their only consumer was the
-	// edge-gap visibility check, and they went stale on nested horizontal
-	// scroll (IO doesn't re-fire when the intersection ratio doesn't
-	// cross a threshold). Replaced by edge_map, derived from the array's
-	// own scrollLeft / clientWidth / scrollWidth — one element, six
-	// property reads per dirty array per RAF, no per-node BCRs.
 }
 
 /**
- * Install the visibility registry on the svedit context and wire up
- * the IntersectionObserver + MutationObserver lifecycle to editable
- * state.
+ * Install the visibility registry on the svedit context.
  *
- * @param {object} svedit - Svedit context (session, editable, canvas_el)
+ * Elements register themselves via the track_node / track_array
+ * attachments, so registration follows the DOM's actual lifecycle.
+ * The IntersectionObservers own viewport changes; document changes
+ * only trigger an edge-state re-sync over the registered arrays.
+ *
+ * @param {object} svedit - Svedit context (session, editable)
  */
 export function create_node_visibility(svedit) {
 	const registry = new VisibilityRegistry();
@@ -540,35 +574,7 @@ export function create_node_visibility(svedit) {
 
 	$effect(() => {
 		if (typeof window === 'undefined') return;
-
-		// Empty node-array placeholders only exist in edit mode, so re-run
-		// the bootstrap when editability changes to observe them reliably.
-		svedit.editable;
-
 		registry.start();
-		// Observe every existing node. NO getBoundingClientRect — it
-		// would force layout on each call, and at 2000+ nodes the
-		// bootstrap interleaves with Svelte's mount work, retriggering
-		// layout for the growing DOM (~1.5 s of forced reflow when
-		// traced). IO populates near_map / array_indices on its first
-		// callback, ~1 frame after observe(). The lag is invisible:
-		// un-positioned NodeGaps have zero layout presence.
-		for (const el of document.querySelectorAll(NODE_SELECTOR)) {
-			registry.observe(/** @type {HTMLElement} */ (el));
-		}
-
-		// Bootstrap edge_map for arrays already in the DOM. One-time
-		// scrollLeft/clientWidth pass — cheap (one element, six property
-		// reads each) and never repeated outside this mount.
-		for (const arr of document.querySelectorAll('[data-type="node_array"]')) {
-			registry.sync_array_edge_gaps(arr);
-		}
-
-		const canvas =
-			untrack(() => svedit.canvas_el) || document.querySelector('.svedit-canvas');
-		/** @type {MutationObserver | null} */
-		let mo = null;
-		let raf = 0;
 
 		/**
 		 * Scroll listener for nested scroll containers. IntersectionObserver
@@ -588,7 +594,7 @@ export function create_node_visibility(svedit) {
 		function flush_scroll_sync() {
 			scroll_raf = 0;
 			for (const arr of pending_scroll_arrays) {
-				if (arr.isConnected) registry.sync_array_edge_gaps(arr);
+				if (arr.isConnected) registry.sync_edge_state(arr);
 			}
 			pending_scroll_arrays.clear();
 		}
@@ -596,123 +602,81 @@ export function create_node_visibility(svedit) {
 		function on_scroll(event) {
 			const target = /** @type {Element | null} */ (event.target);
 			const arr = target?.closest?.('[data-type="node_array"]');
-			if (!arr) return;
+			if (!arr || !registry.has_array(arr)) return;
 			pending_scroll_arrays.add(arr);
 			if (!scroll_raf) scroll_raf = requestAnimationFrame(flush_scroll_sync);
 		}
 		document.addEventListener('scroll', on_scroll, { capture: true, passive: true });
 
-		if (canvas) {
-			mo = new MutationObserver((mutations) => {
-				/** @type {Set<Element>} */
-				// eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive per-mutation queue.
-				const dirty_arrays = new Set();
-				for (const m of mutations) {
-					for (const added of m.addedNodes) {
-						if (added.nodeType !== Node.ELEMENT_NODE) continue;
-						const el = /** @type {HTMLElement} */ (added);
-						if (el.matches(NODE_SELECTOR)) {
-							registry.observe(el);
-							registry.schedule_view_sync(el);
-							const arr = el.closest('[data-type="node_array"]');
-							if (arr) dirty_arrays.add(arr);
-						}
-						// Newly-mounted gaps need immediate .positioned sync —
-						// the IO won't fire for the EXISTING adjacent node
-						// (its intersection didn't change), so the gap would
-						// stay un-positioned until the next scroll.
-						if (el.matches(GAP_SELECTOR)) {
-							registry.sync_gap_class(el);
-						}
-						for (const child of el.querySelectorAll(NODE_SELECTOR)) {
-							const node_el = /** @type {HTMLElement} */ (child);
-							registry.observe(node_el);
-							registry.schedule_view_sync(node_el);
-							const arr = node_el.closest('[data-type="node_array"]');
-							if (arr) dirty_arrays.add(arr);
-						}
-						for (const child of el.querySelectorAll(GAP_SELECTOR)) {
-							registry.sync_gap_class(child);
-						}
-					}
-					for (const removed of m.removedNodes) {
-						if (removed.nodeType !== Node.ELEMENT_NODE) continue;
-						const el = /** @type {HTMLElement} */ (removed);
-						if (el.matches(NODE_SELECTOR)) registry.unobserve(el);
-						for (const child of el.querySelectorAll(NODE_SELECTOR)) {
-							registry.unobserve(/** @type {HTMLElement} */ (child));
-						}
-					}
-				}
-				for (const arr of dirty_arrays) registry.resync_array_edge_gaps(arr);
-			});
-			// Defer one frame to skip the initial Svelte mount burst,
-			// which the bootstrap above already covered.
-			raf = requestAnimationFrame(() => {
-				mo.observe(canvas, { childList: true, subtree: true });
-			});
-		}
-
 		return () => {
 			document.removeEventListener('scroll', on_scroll, true);
-			cancelAnimationFrame(raf);
 			cancelAnimationFrame(scroll_raf);
 			pending_scroll_arrays.clear();
-			mo?.disconnect();
 			registry.stop();
 		};
 	});
+
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+
+		// Structural inputs whose changes can alter array scroll extents
+		// without recreating array elements. Selection intentionally does
+		// not participate; NodeGapMarkers tracks it directly for caret state.
+		svedit.session.doc;
+		svedit.editable;
+
+		let cancelled = false;
+		tick().then(() => {
+			if (!cancelled) registry.sync_all_edge_states();
+		});
+
+		return () => {
+			cancelled = true;
+		};
+	});
 }
 
 /**
- * Non-reactive visibility check used by the imperative .positioned
- * toggle. Reads near_map / edge_map inside untrack() because this is
- * called from sync_gap_class which can run transitively from the
- * bootstrap $effect, and a subscription here would self-invalidate
- * (the same effect writes to these maps and would re-run forever).
- * `is_last` and `empty` come from the gap element's classList, so we
- * don't need `count` here.
+ * Pure visibility check for a gap's `.positioned` class. NodeGap calls
+ * this from a $derived, so the `near.has()` reads are tracked at
+ * per-key granularity — a gap re-evaluates only when its own
+ * dependencies change. Applying the class declaratively means it
+ * survives DOM recreation without a document change (e.g. dev-mode
+ * HMR component swaps).
  *
- * @param {VisibilityRegistry} registry
- * @param {string} array_path_str
+ * `near` must come from `get_array_indices` held in a SEPARATE
+ * $derived (see the note there): membership reads on a set created
+ * within the same derived are not tracked by Svelte.
+ *
+ * @param {SvelteSet<number>} near - near child indices of the array
+ * @param {{ first: boolean, last: boolean } | undefined} edge_state
  * @param {number} offset
  * @param {boolean} is_last
  * @param {boolean} empty
  */
-function should_position_gap_imperative(registry, array_path_str, offset, is_last, empty) {
-	if (!registry) return false;
-
-	// untrack() is critical: this function is called transitively from
-	// the bootstrap $effect (via sync_array_edge_gaps → sync_gap_class),
-	// and the reactive-Map `.has()` / `.get()` reads here would
-	// otherwise subscribe that effect to the same maps the bootstrap
-	// then writes to — infinite re-run cycle that empties near_map
-	// every time the IO tries to populate it.
-	return untrack(() => {
-		if (empty) {
-			return registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}0`);
-		}
+export function should_position_gap(near, edge_state, offset, is_last, empty) {
+	if (!near) return false;
 
-		// Edge gaps gate on near_map AND edge_map. edge_map is the
-		// scroll-aware BCR-based check that the adjacent edge node has
-		// actually reached the matching end of its array container
-		// (within EDGE_TOLERANCE_PX). We can't rely on IO clip_map here
-		// because IO only fires on intersection-ratio threshold
-		// crossings and misses scroll changes within a horizontal-
-		// overflow container that don't change the visibility ratio.
-		if (offset === 0) {
-			if (!registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}0`)) return false;
-			return registry.edge_map.get(array_path_str)?.first === true;
-		}
+	if (empty) {
+		return near.has(0);
+	}
 
-		if (is_last) {
-			if (!registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}${offset - 1}`)) return false;
-			return registry.edge_map.get(array_path_str)?.last === true;
-		}
+	// Edge gaps gate on nearness AND edge state. edge_state is the
+	// scroll-aware check that the adjacent edge node has actually
+	// reached the matching end of its array container (within
+	// EDGE_TOLERANCE_PX). We can't rely on the IO here because it only
+	// fires on intersection-ratio threshold crossings and misses scroll
+	// changes within a horizontal-overflow container that don't change
+	// the visibility ratio.
+	if (offset === 0) {
+		if (!near.has(0)) return false;
+		return edge_state?.first === true;
+	}
 
-		return (
-			registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}${offset - 1}`) &&
-			registry.near_map.has(`${array_path_str}${PATH_SEPARATOR}${offset}`)
-		);
-	});
+	if (is_last) {
+		if (!near.has(offset - 1)) return false;
+		return edge_state?.last === true;
+	}
+
+	return near.has(offset - 1) && near.has(offset);
 }