svedit 0.11.1 → 0.13.0

package/src/lib/node_visibility.svelte.ts

@@ -0,0 +1,658 @@
+/**
+ * Dual-observer viewport visibility tracking for node arrays.
+ *
+ * ## Why this exists
+ *
+ * CSS anchor positioning is O(N) — the browser must resolve anchor()
+ * functions for every positioned element on every layout pass. Gap
+ * markers (NodeGapMarkers) also grow at O(N). At ~200+ nodes this
+ * causes frame drops during scroll/resize; at 500+ it's unusable.
+ *
+ * ## Design principle: structurally stable DOM
+ *
+ * NodeGap elements are always present in the DOM when editable. The
+ * `.positioned` class (which activates anchor() resolution) is gated
+ * by viewport visibility. Off-screen NodeGaps remain as zero-size
+ * absolute elements with no anchor cost.
+ *
+ * ## Element registration via attachments
+ *
+ * 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.
+ * OPT-IN via `session.config.view_classes`. A separate observer is
+ * required because the overscan IO fires its thresholds while nodes
+ * are still 500px outside the real viewport.
+ *
+ * **Document scroll listener** (capture, passive) — fills `edge_map`,
+ * a per-array `{first, last}` flag indicating whether the leading/
+ * trailing node has reached the matching container edge within
+ * EDGE_TOLERANCE_PX. IntersectionObserver doesn't re-fire on scrolls
+ * inside non-root scroll containers (the intersection ratio doesn't
+ * cross any threshold), so this is the only reliable way to track
+ * horizontal-overflow scroll position. The handler is hot but cheap:
+ * a single `.closest()` early-out (page scroll → null → returns
+ * 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 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. 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).
+ *
+ * @module
+ */
+
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { tick, untrack } from 'svelte';
+import { PATH_SEPARATOR } from './utils.js';
+
+/**
+ * Overscan margin around the viewport (px). Nodes within this distance
+ * of the viewport get anchor positioning activated and gap markers
+ * computed. 500px provides enough buffer for fast scrolling without
+ * a measurable FPS hit.
+ */
+const OVERSCAN_PX = 500;
+
+/**
+ * Distance (in CSS pixels) the leading/trailing edge of an edge node is
+ * allowed to overshoot the array container's matching edge while still
+ * counting as "at the edge". Picks up small overflow from sub-pixel
+ * layout and gives a forgiving hit area near the boundary so a 1-2px
+ * jitter from scroll/animation doesn't cause the edge gap to flicker.
+ */
+const EDGE_TOLERANCE_PX = 10;
+
+/**
+ * Single source of truth for "which node DOM elements are near or in
+ * 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-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.
+	 *
+	 */
+	#array_indices: Map<string, SvelteSet<number>> = new Map();
+
+	/**
+	 * 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, 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
+	 * end of its container.
+	 *
+	 */
+	edge_map: SvelteMap<string, { first: boolean; last: boolean }> = new SvelteMap();
+
+	#io: IntersectionObserver | null = null;
+
+	#view_io: IntersectionObserver | null = 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.
+	 *
+	 */
+	#array_ro: ResizeObserver | null = 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.
+	 *
+	 */
+	#registered_paths: Map<HTMLElement, string> = new Map();
+
+	/**
+	 * Which element currently owns a node path. Guards unregistration
+	 * against keyed-update collisions (see module doc).
+	 *
+	 */
+	#path_owners: Map<string, HTMLElement> = new Map();
+
+	#near_nodes: Set<HTMLElement> = new Set();
+
+	/** Registered node-array container elements. */
+	#array_els: Set<Element> = new Set();
+
+	/** Which element currently owns an array path. */
+	#array_owners: Map<string, Element> = new Map();
+
+	/**
+	 * When true, a second IO (rootMargin 0, actual viewport) toggles
+	 * `.in-view` / `.seen` / `.fully-in-view` / `.visible-top` /
+	 * `.visible-bottom` on node elements — useful for scrollytelling
+	 * and reveal animations.
+	 *
+	 * A separate observer is required because the overscan IO (rootMargin
+	 * 500px) fires its thresholds while nodes are still outside the real
+	 * viewport — by the time a node scrolls into view, both thresholds
+	 * have already been crossed and no further callback fires.
+	 *
+	 * Opt out via `session.config.view_classes = false` to skip the
+	 * second observer entirely.
+	 */
+	view_classes = true;
+
+	/**
+	 * 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
+	 * (hundreds of nodes) can become unresponsive without the culling.
+	 *
+	 * Opt out via `session.config.visibility_culling = false`.
+	 */
+	visibility_culling = true;
+
+	start() {
+		if (typeof window === 'undefined') return;
+		// Overscan IO: threshold [0] is enough — #process_near only reads
+		// entry.isIntersecting (a boolean) and writes are change-detected,
+		// so extra firings at threshold[1] would be no-ops.
+		if (this.visibility_culling && !this.#io) {
+			this.#io = new IntersectionObserver((entries) => this.#process_near(entries), {
+				rootMargin: `${OVERSCAN_PX}px`,
+				threshold: [0]
+			});
+		}
+		// View IO: threshold [0, 1] is load-bearing — #apply_view_classes
+		// toggles .fully-in-view, which flips when the node crosses the
+		// fully-visible boundary at ratio 1.
+		if (this.view_classes && !this.#view_io) {
+			this.#view_io = new IntersectionObserver((entries) => this.#process_view(entries), {
+				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() {
+		this.#io?.disconnect();
+		this.#io = null;
+		this.#view_io?.disconnect();
+		this.#view_io = null;
+		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();
+	}
+
+	/**
+	 * Returns the (lazily created, stable) SvelteSet for an array path.
+	 * Callers should hold the returned reference for the lifetime of the
+	 * 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.
+	 *
+	 */
+	get_array_indices(array_path_str: string): SvelteSet<number> {
+		let set = this.#array_indices.get(array_path_str);
+		if (!set) {
+			set = new SvelteSet();
+			this.#array_indices.set(array_path_str, set);
+		}
+		return set;
+	}
+
+	/**
+	 * 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.
+	 *
+	 */
+	track_node(path: string) {
+		return (el: HTMLElement) => {
+			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.
+	 *
+	 */
+	track_array(path: string) {
+		return (el: Element) => {
+			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(() => {
+					if (this.#array_owners.get(path) === el) {
+						this.#array_owners.delete(path);
+						this.edge_map.delete(path);
+					}
+				});
+			};
+		};
+	}
+
+	/**
+	 * 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.
+	 *
+	 */
+	has_array(el: Element): boolean {
+		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);
+		}
+	}
+
+	#register_node(el: HTMLElement, path: string): void {
+		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);
+			}
+		});
+	}
+
+	#unregister_node(el: HTMLElement, path: string): void {
+		this.#registered_paths.delete(el);
+		this.#near_nodes.delete(el);
+		this.#io?.unobserve(el);
+		this.#view_io?.unobserve(el);
+		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);
+			}
+		});
+	}
+
+	#add_near_node(el: HTMLElement, path: string): void {
+		this.#near_nodes.add(el);
+		const split = this.#split_path(path);
+		if (split) this.get_array_indices(split.array_path).add(split.index);
+	}
+
+	#remove_near_node(el: HTMLElement, path: string): void {
+		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);
+	}
+
+	/**
+	 * Update edge_map for an array from its scrollLeft/scrollWidth/
+	 * clientWidth (and the y-axis equivalents). Returns true when the
+	 * state actually changed. Uses only the array's own scroll metrics
+	 * — no BCRs, no per-node measurements, no querying children — so
+	 * each call is ~6 property reads on one element regardless of how
+	 * many nodes the array has.
+	 *
+	 * For a non-overflowing array (scrollWidth === clientWidth, etc.)
+	 * both checks pass, so first/last gaps stay visible as expected.
+	 * For an overflowing array, first is true only when scrolled to
+	 * the start and last only when scrolled to the end (within
+	 * EDGE_TOLERANCE_PX).
+	 *
+	 * Writes to edge_map are wrapped in untrack() so this can be
+	 * called transitively from $effect contexts without self-
+	 * invalidation.
+	 *
+	 */
+	sync_edge_state(array_el: Element): boolean {
+		if (!array_el) return false;
+		const path = (array_el as HTMLElement).dataset.path;
+		if (!path) return false;
+
+		// 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';
+
+		// Only use scroll metrics on axes where this array actually clips/scrolls.
+		// 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.
+		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);
+			if (prev && prev.first === first && prev.last === last) return false;
+			this.edge_map.set(path, { first, last });
+			return true;
+		});
+	}
+
+	#apply_view_classes(
+		el: HTMLElement,
+		in_viewport: boolean,
+		bcr: DOMRectReadOnly,
+		vh: number
+	): void {
+		const cl = el.classList;
+		cl.toggle('in-view', in_viewport);
+		if (in_viewport) {
+			cl.add('seen');
+			const top_clipped = bcr.top < -0.5;
+			const bottom_clipped = bcr.bottom > vh + 0.5;
+			cl.toggle('fully-in-view', !top_clipped && !bottom_clipped);
+			cl.toggle('visible-top', !top_clipped && bottom_clipped);
+			cl.toggle('visible-bottom', top_clipped && !bottom_clipped);
+		} else {
+			cl.remove('fully-in-view', 'visible-top', 'visible-bottom');
+		}
+	}
+
+	#split_path(path: string): { array_path: string; index: number } | null {
+		const sep = path.lastIndexOf(PATH_SEPARATOR);
+		if (sep < 0) return null;
+		const index = parseInt(path.slice(sep + PATH_SEPARATOR.length), 10);
+		if (Number.isNaN(index)) return null;
+		return { array_path: path.slice(0, sep), index };
+	}
+
+	/**
+	 * Overscan IO callback. Manages the array_indices sets; NodeGap
+	 * reacts to the map writes and updates .positioned declaratively.
+	 *
+	 */
+	#process_near(entries: IntersectionObserverEntry[]): void {
+		for (const entry of entries) {
+			const el = entry.target as HTMLElement;
+			const path = this.#registered_paths.get(el);
+			if (!path || !el.isConnected) continue;
+
+			const is_near = entry.isIntersecting;
+			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);
+		}
+	}
+
+	/**
+	 * Viewport IO callback. Toggles view classes on node elements.
+	 * Runs on a separate observer with rootMargin 0 so thresholds
+	 * fire at actual viewport edges, not the overscan boundary.
+	 *
+	 */
+	#process_view(entries: IntersectionObserverEntry[]): void {
+		const vh = window.innerHeight;
+		for (const entry of entries) {
+			const el = entry.target as HTMLElement;
+			if (!this.#registered_paths.has(el) || !el.isConnected) continue;
+			this.#apply_view_classes(el, entry.isIntersecting, entry.boundingClientRect, vh);
+		}
+	}
+}
+
+/**
+ * Install the visibility registry on the svedit context.
+ *
+ * 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 svedit - Svedit context (session, editable)
+ */
+export function create_node_visibility(svedit: {
+	session: {
+		config?: { view_classes?: boolean; visibility_culling?: boolean };
+		doc: unknown;
+	};
+	editable: boolean;
+	visibility_registry?: VisibilityRegistryApi;
+}): void {
+	const registry = new VisibilityRegistry();
+	registry.view_classes = svedit.session?.config?.view_classes !== false;
+	registry.visibility_culling = svedit.session?.config?.visibility_culling !== false;
+	svedit.visibility_registry = registry;
+
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+		registry.start();
+
+		/**
+		 * Scroll listener for nested scroll containers. IntersectionObserver
+		 * doesn't reliably re-fire when the user scrolls inside a non-root
+		 * scrollable element (Chrome's IO samples on viewport scroll, not on
+		 * intermediate scroll-container scrolls), so we listen for scroll
+		 * events on the document in capture phase. The handler is hot but
+		 * cheap: a single `.closest()` check exits in O(1) for the common
+		 * case (page scroll → target is document/body, not an array) and
+		 * coalesces array scrolls into one RAF that reads only scrollLeft /
+		 * scrollWidth / clientWidth — no per-node BCRs.
+		 */
+		// eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive RAF queue.
+		const pending_scroll_arrays: Set<Element> = new Set();
+		let scroll_raf = 0;
+		function flush_scroll_sync() {
+			scroll_raf = 0;
+			for (const arr of pending_scroll_arrays) {
+				if (arr.isConnected) registry.sync_edge_state(arr);
+			}
+			pending_scroll_arrays.clear();
+		}
+		function on_scroll(event: Event) {
+			const target = event.target as Element | null;
+			const arr = target?.closest?.('[data-type="node_array"]');
+			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 });
+
+		return () => {
+			document.removeEventListener('scroll', on_scroll, true);
+			cancelAnimationFrame(scroll_raf);
+			pending_scroll_arrays.clear();
+			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;
+		};
+	});
+}
+
+export type VisibilityRegistryApi = {
+	edge_map: SvelteMap<string, { first: boolean; last: boolean }>;
+	get_array_indices(array_path_str: string): SvelteSet<number>;
+	track_node(path: string): (el: HTMLElement) => () => void;
+	track_array(path: string): (el: Element) => () => void;
+};
+
+/**
+ * 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).
+ *
+ * `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 near - near child indices of the array
+ */
+export function should_position_gap(
+	near: SvelteSet<number>,
+	edge_state: { first: boolean; last: boolean } | undefined,
+	offset: number,
+	is_last: boolean,
+	empty: boolean
+): boolean {
+	if (!near) return false;
+
+	if (empty) {
+		return near.has(0);
+	}
+
+	// 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;
+	}
+
+	if (is_last) {
+		if (!near.has(offset - 1)) return false;
+		return edge_state?.last === true;
+	}
+
+	return near.has(offset - 1) && near.has(offset);
+}