@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/block-id.js

@@ -1,30 +1,41 @@
 // A per-module-instance prefix: a dev-server reload restarts the counter while the live tree
-// still holds ids minted before it, and a repeat collides in Svelte's keyed each.
+// still holds ids created before it, and a repeat collides in Svelte's keyed each.
 const RUN = Math.random().toString(36).slice(2, 8);
 let sequence = 0;
-/**
- * These ids key Svelte's `{#each}`: process uniqueness, not unguessability. `crypto.randomUUID`
- * answers a question nobody asked here, at a per-block cost a large load pays in full
- * (`performance.md`), and is secure-context-only besides.
- */
+/** Keys for Svelte's `{#each}`: unique within the process and cheap per block, not unguessable. */
 export function generateBlockId() {
     sequence += 1;
     return `b${RUN}-${sequence}`;
 }
-// View-typed: one id per slot, content never read — and `childIds` is the
-// bytes-view carve-out, legal to write even on a snapshot-shared node. Sized off `length`
-// rather than mapped, so a `$state` children array costs one proxy read instead of one per slot.
+// `childIds` is the one field safe to write even on a node an undo snapshot shares. Sized from
+// `length`, so a `$state` array costs one proxy read, not one per child.
 export function assignIds(children) {
     const ids = new Array(children.length);
     for (let i = 0; i < ids.length; i++)
         ids[i] = generateBlockId();
     return ids;
 }
-/**
- * Initialize `childIds` before a freshly-parsed subtree is spliced into the live tree: a
- * reused container reads it in its keyed-each synchronously, so a missing array surfaces
- * as `undefined` keys.
- */
+/** Ids for `next`, a re-read of `previous`: an unchanged run at either end keeps its ids, the first
+ *  changed block keeps its own (the edit was in it), and each block the re-read made is new. */
+export function idsAcrossReread(previous, ids, next) {
+    if (!ids || ids.length !== previous.length)
+        return undefined;
+    const same = (a, b) => a.kind === b.kind && a.leadingTrivia === b.leadingTrivia && a.raw === b.raw;
+    const shorter = Math.min(previous.length, next.length);
+    let head = 0;
+    while (head < shorter && same(previous[head], next[head]))
+        head++;
+    let tail = 0;
+    while (tail < shorter - head &&
+        same(previous[previous.length - 1 - tail], next[next.length - 1 - tail])) {
+        tail++;
+    }
+    const changed = previous.length - head - tail;
+    const created = Array.from({ length: next.length - head - tail }, (_, i) => i === 0 && changed > 0 ? ids[head] : generateBlockId());
+    return [...ids.slice(0, head), ...created, ...ids.slice(previous.length - tail)];
+}
+/** Call before a freshly parsed subtree is spliced in: a reused container reads `childIds` in its
+ *  keyed each synchronously, so a missing array shows up as `undefined` keys. */
 export function assignChildIdsDeep(node) {
     if (node.children && node.children.length > 0 && !node.childIds) {
         node.childIds = assignIds(node.children);

package/dist/bounded-memo.d.ts

@@ -1,9 +1,9 @@
 /**
- * A bounded, LRU-evicting memo for expensive render work — the cache primitive a plugin
- * renderer builds on (see the plugin guide's renderer recipe). Async needs no variant:
- * the caller stores the Promise, so an in-flight render is shared and a rejection is
- * cached verbatim. `cloneOnRead` covers the one case a bare cache cannot — a value
- * holding a live DOM node, which cannot occupy two places at once.
+ * A size-limited cache that evicts the least recently used entry, for expensive render work;
+ * what a plugin renderer builds its cache on (see the plugin guide's renderer recipe). Async
+ * needs no separate version: the caller stores the Promise, so a render in progress is shared
+ * and a rejection is cached as is. `cloneOnRead` covers the one case a plain cache cannot: a
+ * value holding a live DOM node, which cannot be in two places at once.
  */
 export interface BoundedMemoOptions<V> {
     /** Maximum live entries; the least-recently-used is evicted past it. */

package/dist/bounded-memo.js

@@ -1,9 +1,9 @@
 /**
- * A bounded, LRU-evicting memo for expensive render work — the cache primitive a plugin
- * renderer builds on (see the plugin guide's renderer recipe). Async needs no variant:
- * the caller stores the Promise, so an in-flight render is shared and a rejection is
- * cached verbatim. `cloneOnRead` covers the one case a bare cache cannot — a value
- * holding a live DOM node, which cannot occupy two places at once.
+ * A size-limited cache that evicts the least recently used entry, for expensive render work;
+ * what a plugin renderer builds its cache on (see the plugin guide's renderer recipe). Async
+ * needs no separate version: the caller stores the Promise, so a render in progress is shared
+ * and a rejection is cached as is. `cloneOnRead` covers the one case a plain cache cannot: a
+ * value holding a live DOM node, which cannot be in two places at once.
  */
 import { devWarn } from './dev-warn';
 export function createBoundedMemo(options) {
@@ -11,7 +11,7 @@ export function createBoundedMemo(options) {
     // Reported at creation, not per read: a non-positive cap would otherwise behave as 1
     // unnoticed, so the author who meant "no caching" gets caching with nothing to read.
     if (options.cap < 1) {
-        devWarn('bounded-memo', `cap must be at least 1; got ${options.cap} — using 1`);
+        devWarn('bounded-memo', `cap must be at least 1; got ${options.cap}, using 1`);
     }
     const cap = Math.max(1, options.cap);
     const cache = new Map();

package/dist/components/BlockDragHandle.svelte

@@ -4,8 +4,8 @@
 	import { alignDragHandle } from './drag-handle';
 </script>
 
-<!-- aria-hidden + non-focusable: keyboard reorder (Alt+Arrow) is the operable,
-	screen-reader-visible path, so this mouse-only grip stays out of the tab/SR flow. -->
+<!-- Hidden from assistive tech and the tab order: keyboard reorder (Alt+Arrow) is the
+	accessible path. -->
 <span
 	class="block-drag-handle"
 	aria-hidden="true"
@@ -18,16 +18,12 @@
 <style>
 	.block-drag-handle {
 		position: absolute;
-		/* Sits inside the editor's own left padding, so the grip clears the block's left
-		   border instead of being clipped behind it (overflow-x:auto). */
+		/* In the editor's left padding, so the block's `overflow-x: auto` cannot clip it. */
 		left: -1.25rem;
-		/* Spans gutter to content-left (width === |left|) so a pointer gliding from the
-		   block never crosses an un-hovered gap, which would hide the handle and — being
-		   pointer-events:none once hidden — strand it. Stopping AT content-left keeps
-		   line-start caret/marker clicks from being hijacked into a drag. */
+		/* Reaches the content's left edge, so a pointer moving out of the block never crosses a
+		   gap that would hide the handle, and stops there so the first character stays clickable. */
 		width: 1.25rem;
-		/* Full-height hit strip so the handle is reachable at ANY height; the visible
-		   grip sits on the block's first line. */
+		/* A full-height strip; the visible handle sits on the block's first line. */
 		top: 0;
 		bottom: 0;
 		opacity: 0;
@@ -37,17 +33,15 @@
 		color: var(--color-ui-muted, #a4a4a4);
 	}
 
-	/* Flush left in the strip (the glyph ends a few px clear of the content), centred on the
-	   measured band that `alignDragHandle` writes as an inline `top`.
-
-	   ALWAYS hittable, unlike the strip around it: a grip reachable only by first hovering its
-	   block is a flyout you traverse the block to get to. Its own box, not the full-height
-	   strip, which would swallow every gutter click the block has. */
+	/* Centred on the line `alignDragHandle` measures. Always clickable, unlike the strip, so
+	   the handle needs no hover first without the strip swallowing every gutter click. */
 	.grip {
 		position: absolute;
 		left: 0;
 		width: 100%;
 		height: 1.25rem;
+		/* The `em` fallback is for browsers without `lh` (Safari before 16.4). */
+		top: 0.75em;
 		top: 0.5lh;
 		transform: translateY(-50%);
 		display: flex;
@@ -56,16 +50,15 @@
 		pointer-events: auto;
 	}
 
-	/* The hit target is bigger than the glyph: a 16px box in a gutter is a target the pointer
-	   misses between two rows, and a miss here reads as the grip belonging to the block above.
-	   Never past the strip's right edge, which is the content's first character. */
+	/* A click target bigger than the 16px glyph, which a pointer misses between rows; it never
+	   passes the strip's right edge, the content's first character. */
 	.grip::before {
 		content: '';
 		position: absolute;
 		inset: -8px 0 -8px -4px;
 	}
 
-	/* Touch never fires the hover reveal, so the handle shows unasked. */
+	/* Touch never triggers the hover rule, so the handle is shown from the start. */
 	@media (hover: none) {
 		.block-drag-handle {
 			opacity: 1;

package/dist/components/BlockHost.svelte

@@ -7,27 +7,25 @@
 		type BlockComponentExports
 	} from '../block-component';
 	import type { NodeView } from '../core/node-views';
-	import type { BlockDecoration } from '../decorations/types';
-	import { acceptedBlockAttrs } from '../decorations/reserved-attrs';
-	import { mountDecorationWidget } from '../decorations/widget-dom';
+	import { useBlockDecorations } from '../decorations/use-block-decorations.svelte';
 	import SelectionOverlay from './SelectionOverlay.svelte';
 	import DecorationOverlay from './DecorationOverlay.svelte';
 	import BlockDragHandle from './BlockDragHandle.svelte';
 	import { showsDragHandle } from './drag-handle';
 	import TextEditableBlock from './blocks/text/TextEditableBlock.svelte';
 	import { defaultRegistryView } from '../schema/registry-view';
+	import { isGridDescriptor } from '../schema/block-kind-descriptor';
 	import { FAILED_BLOCK_LABEL } from '../a11y-strings';
 	import {
 		EDITOR_DOC_KEY,
 		EDITOR_POLICIES_KEY,
 		EDITOR_SERVICES_KEY,
-		RECORD_BLOCK_HEIGHT_KEY,
-		type BlockMeasureChannel,
 		type EditorDoc,
 		type EditorPolicies,
 		type EditorServices
 	} from '../editor-keys';
 	import { useMountGauge } from '../perf/use-mount-gauge.svelte';
+	import { useMeasuredChild } from '../reactivity/use-measured-child.svelte';
 	import { publishRefSlot, type RefSlots } from '../reactivity/publish-ref.svelte';
 	import { devWarn } from '../dev-warn';
 
@@ -49,68 +47,64 @@
 		reorderable?: boolean;
 	} = $props();
 
-	// Optional throughout: bare unit harnesses mount BlockHost without the editor
-	// shell, so every read here (and both overlays') is written for absence.
+	// The services and document contexts are optional here and in both overlays, for a partial
+	// test mount; the policies carry the editor's own getters, so a mount always has them.
 	const services = getContext<EditorServices | undefined>(EDITOR_SERVICES_KEY);
 	const editorEvents = services?.events;
 	const engine = services?.decorations;
-	// Per-instance enablement reaches the render path through the view; bare mounts
-	// read the global default.
+	// A bare mount reads the global registry view.
 	const registryView = services?.registryView ?? defaultRegistryView;
-	const getDoc = getContext<EditorDoc | undefined>(EDITOR_DOC_KEY)?.doc;
+	const editorDoc = getContext<EditorDoc | undefined>(EDITOR_DOC_KEY);
+	const getDoc = editorDoc?.doc;
 	// Stable object, so a plain read rather than a getter.
 	const rects = services?.rects;
-	const policies = getContext<EditorPolicies | undefined>(EDITOR_POLICIES_KEY);
-	const getDragHandles = policies?.blockDragHandles;
-	// $derived, not a mount-time snapshot: a runtime prop toggle must reach blocks
-	// that window in after the change.
-	const dragHandles = $derived(getDragHandles?.() ?? false);
-	// The affordance opt-in already folds reading mode in, but a picture's grip does not wait
-	// for that opt-in, so reading mode is asked here too.
-	const isReading = $derived(policies?.presentationMode?.() === 'reading');
-	// A reorder unit without a grip (a paragraph) is still a drop neighbour and keyboard-movable.
-	const showsHandle = $derived(reorderable && !isReading && showsDragHandle(node, dragHandles));
+	const policies = getContext<EditorPolicies>(EDITOR_POLICIES_KEY);
+	// $derived, so a runtime toggle reaches blocks that mount after it.
+	const dragHandles = $derived(policies.blockDragHandles());
+	// Checked here too, because an image's handle does not go through the drag-handle prop.
+	const isReading = $derived(policies.presentationMode() === 'reading');
+	// A bare mount has no editor reading: every installed plugin's syntax, no link definitions.
+	const inlineReading = editorDoc?.reading ?? {
+		grammar: registryView.grammar,
+		resolver: undefined,
+		resolverSignature: ''
+	};
+	// A block with no drag handle (a paragraph) can still be dropped next to and moved by key.
+	const showsHandle = $derived(
+		reorderable && !isReading && showsDragHandle(node, dragHandles, inlineReading)
+	);
 
 	let myPath = $derived([...parentPath, index]);
 
-	const NO_BLOCK_DECORATIONS: BlockDecoration[] = [];
-	const blockDecs = $derived(
-		engine ? engine.blockDecorationsForPath(myPath) : NO_BLOCK_DECORATIONS
-	);
-
 	let descriptor = $derived(registryView.descriptor(node.kind));
 	let isContainer = $derived(descriptor.isContainer);
-	// Who paints this block's rects, decided ONCE here and handed to both overlays —
-	// duplicated, the two drift and a container paints over its own children. Delegation
-	// needs children with hosts: a childless container and a grid have none.
+	// Decided once for both overlays: a container with children (not a grid) leaves painting its
+	// rectangles to the children's own hosts.
 	let delegatesPainting = $derived(
-		isContainer && (node.children?.length ?? 0) > 0 && descriptor.containerContract !== 'grid'
+		isContainer && (node.children?.length ?? 0) > 0 && !isGridDescriptor(descriptor)
 	);
 
 	let hostEl: HTMLElement | null = $state(null);
-	// The one point that resolves a block's published surface (leaf exports vs
-	// containerApi); every consumer of this host's ref reads what it returns.
+	// The one place a block's published interface is resolved; every reader of the ref gets it.
 	let instance: BlockComponentExports | undefined = $state();
 	let ref: BlockComponent | undefined = $derived(resolveBlockSurface(instance));
 
-	// Neither conjunct is redundant though both look it: the shim gives every container
-	// `measurePartialRects`, so that term guards only a hand-rolled one omitting it, and
-	// the delegation term guards a hand-rolled child-bearing non-grid container.
+	// Both halves count: a hand-written container can lack `measurePartialRects`, or have children
+	// and not be a grid.
 	let containerPaintsRects = $derived(
 		isContainer && !delegatesPainting && !!ref?.measurePartialRects
 	);
 
 	let entry = $derived(registryView.component(node.kind));
 
-	// A kind with no registered component falls back to the raw-editable surface below
+	// A kind with no registered component falls back to the plain editable block below
 	// rather than silently rendering nothing.
 	$effect(() => {
 		if (!entry) devWarn('block-host', 'no component for kind, rendering raw', node.kind);
 	});
 
-	// The error boundary sticks on its fallback until reset() runs, so restoring
-	// DIFFERENT bytes retries the render while an unchanged raw can't loop.
-	// Plain lets, not $state: the effect keys on node.raw alone and reads these live.
+	// The error boundary retries only when the bytes change, so a failing render cannot loop.
+	// Plain `let`s, so the effect keys on `node.raw` alone.
 	let failedRaw: string | null = null;
 	let retryFailedRender: (() => void) | null = null;
 
@@ -135,103 +129,33 @@
 		return publishRefSlot(slots, index, ref, hostEl);
 	});
 
-	// No `focus` means neither sanctioned shape was published. `defineBlockComponent`
-	// types this; the guard catches a registration that got in through a cast.
+	// `defineBlockComponent` types this; the check catches a registration cast past it.
 	$effect(() => {
 		if (ref && typeof ref.focus !== 'function')
 			devWarn('block-host', 'component published no BlockComponent surface', node.kind);
 	});
 
-	const measureChannel = getContext<BlockMeasureChannel | undefined>(RECORD_BLOCK_HEIGHT_KEY);
-
 	useMountGauge();
 
-	// Enroll in the scope's batched measure pass rather than measuring inline: a
-	// per-block read interleaved with a sibling's model write costs one reflow per
-	// mounted block on a fling (VR-4). Re-registers on path change.
-	$effect(() => {
-		void myPath;
-		if (!measureChannel) return;
-		return measureChannel.register(myPath, index, id, () =>
-			hostEl ? hostEl.getBoundingClientRect().height : 0
-		);
-	});
-
-	// An edit resizes this one block; re-measure it directly. Skip the MOUNT run — the
-	// batched pass above owns mount measurement, and a per-block read on a fling is the
-	// thrash it exists to remove (VR-4).
-	let firstRun = true;
-	$effect(() => {
-		void node.raw;
-		if (firstRun) {
-			firstRun = false;
-			return;
-		}
-		measureChannel?.measureNow(id);
-	});
-
-	// A block can grow after mount without its `raw` changing (async content decoding
-	// in), which the effect above never sees, and overflow-anchor is off so the growth
-	// would slide the viewport. The scope gates on the height it last applied.
-	$effect(() => {
-		if (!hostEl || !measureChannel) return;
-		const observer = new ResizeObserver((entries) => {
-			const box = entries[0]?.borderBoxSize?.[0];
-			const height = box ? box.blockSize : entries[0]?.contentRect.height;
-			if (height != null) measureChannel.measureOnResize(id, height);
-		});
-		observer.observe(hostEl);
-		return () => observer.disconnect();
+	useMeasuredChild({
+		getId: () => id,
+		getPath: () => myPath,
+		getEl: () => hostEl,
+		getRaw: () => node.raw
 	});
 
-	// Set imperatively, not spread, so a source change or dispose removes exactly the
-	// keys it applied and leaves the host's own attributes alone.
-	$effect(() => {
-		const decs = blockDecs;
-		const el = hostEl;
-		if (!el || decs.length === 0) return;
-		const appliedKeys: string[] = [];
-		for (const dec of decs) {
-			for (const [key, value] of acceptedBlockAttrs(dec.attrs, myPath)) {
-				el.setAttribute(key, value);
-				appliedKeys.push(key);
-			}
-		}
-		return () => {
-			for (const key of appliedKeys) el.removeAttribute(key);
-		};
-	});
+	const kindCue = services?.kindCue;
+	// A nested host's fade bubbles here, so only this host's own animation ends the cue.
+	function endKindCue(event: AnimationEvent): void {
+		if (event.target === hostEl && event.animationName === 'kind-cue-fade')
+			kindCue?.dismiss(myPath);
+	}
 
-	// Badges prepend BEFORE the block component, so BLOCK_CONTENT_SELECTOR
-	// (block-content-selector.ts) excludes `.decoration-badge` — keep it in step if
-	// this wrapper class changes.
-	$effect(() => {
-		const decs = blockDecs;
-		const el = hostEl;
-		if (!el) return;
-		const destroys: Array<() => void> = [];
-		const badges = document.createDocumentFragment();
-		for (const dec of decs) {
-			if (!dec.badge) continue;
-			const handle = mountDecorationWidget(dec.badge, dec, (error) =>
-				editorEvents?.emit('error', { origin: 'render', error, context: { path: myPath } })
-			);
-			if (!handle) continue;
-			const wrapper = document.createElement('div');
-			wrapper.className = 'decoration-badge';
-			wrapper.setAttribute('contenteditable', 'false');
-			wrapper.appendChild(handle.el);
-			badges.appendChild(wrapper);
-			destroys.push(() => {
-				handle.destroy();
-				wrapper.remove();
-			});
-		}
-		if (destroys.length === 0) return;
-		el.insertBefore(badges, el.firstChild);
-		return () => {
-			for (const destroy of destroys) destroy();
-		};
+	const blockDecorations = useBlockDecorations({
+		getPath: () => myPath,
+		getEl: () => hostEl,
+		engine,
+		onRenderError: (error) => editorEvents?.emit('error', error)
 	});
 </script>
 
@@ -239,10 +163,12 @@
 	class={[
 		'block-host',
 		{ 'reorder-host': reorderable && dragHandles, 'handle-host': showsHandle },
-		...blockDecs.flatMap((d) => d.class ?? [])
+		...blockDecorations.classes
 	]}
 	data-block-path={JSON.stringify(myPath)}
 	data-block-kind={node.kind}
+	data-kind-cue={kindCue?.labelAt(myPath)}
+	onanimationend={endKindCue}
 	bind:this={hostEl}
 >
 	<svelte:boundary onerror={onRenderError}>
@@ -278,8 +204,7 @@
 			</div>
 		{/snippet}
 	</svelte:boundary>
-	<!-- hostEl is null until mount; safe because SelectionState is only populated by
-		 user gesture, and the overlay's $effect guards on !blockEl. -->
+	<!-- hostEl is null until mount; the overlay checks for a missing blockEl. -->
 	<SelectionOverlay
 		path={myPath}
 		blockRef={ref}
@@ -294,8 +219,7 @@
 		{isContainer}
 		{containerPaintsRects}
 	/>
-	<!-- Rendered LAST so the block-el lookup still resolves block content as its
-		 first match. -->
+	<!-- Last, so the block-element lookup finds the block content first. -->
 	{#if showsHandle}
 		<BlockDragHandle />
 	{/if}
@@ -306,10 +230,8 @@
 		position: relative;
 	}
 
-	/* Pure-CSS hover reveal: no per-block reactive state on a path whose cost scales
-	   with mounted-component count. Global because handle hosts nest; the `:not(:has(
-	   ...))` reveals the innermost hovered handle, not a staircase of ancestors. A gripless
-	   unit (a paragraph in a quote) is no host, so hovering it reveals its container's. */
+	/* Hover by CSS alone, so no reactive state per block; the `:not(:has(...))` shows only the
+	   innermost hovered host's handle. */
 	:global(.handle-host:hover:not(:has(.handle-host:hover)) > .block-drag-handle),
 	:global(.block-drag-handle:hover) {
 		opacity: 1;

package/dist/components/BlockList.svelte

@@ -15,12 +15,12 @@
 	import { gapEligibleAmong } from '../selection/gap-caret';
 	import { pathsEqual } from '../selection/path-math';
 	import { sliceWindow } from '../reactivity/window-slice';
+	import { useWindowFloor } from '../reactivity/use-window-floor.svelte';
 	import BlockHost from './BlockHost.svelte';
 	import GapCaret from './GapCaret.svelte';
 
-	// `slots` is owner-supplied: a `bind:` $bindable array desyncs from the owner's state
-	// across cross-effect mutations. `reorderable` is true only when these children ARE
-	// reorder units (document root, list, blockquote).
+	// `slots` comes from the owner, since a `bind:` array falls out of step when two effects
+	// write it. `reorderable` means these children are what a drag reorders.
 	let {
 		children,
 		blockIds,
@@ -45,25 +45,25 @@
 	let end = $derived(bounds.end);
 	let slice = $derived(children.slice(start, end));
 
-	// Read like BlockHost's, `| undefined` included: a bare-mounted list in a harness provides
-	// none. The two action bundles are read HERE because they are scope-local — this list's own
-	// position answers them, unlike the root facets GapCaret reads for itself.
+	let listEl: HTMLElement | undefined = $state();
+	useWindowFloor(
+		() => listEl,
+		() => win
+	);
+
+	// Optional, like BlockHost's reads: a list mounted alone in a test has no editor context.
 	const selection = getContext<EditorServices | undefined>(EDITOR_SERVICES_KEY)?.selection;
 	const focusActions = getContext<FocusActions | undefined>(FOCUS_KEY);
 	const blockEdit = getContext<BlockEditActions | undefined>(BLOCK_EDIT_KEY);
 
-	// Only a surface that paints inline content paints one, so the prefix is withheld from a
-	// first child that would ignore it — a code block, a nested list, a container. Withheld, not
-	// handed over and dropped: a prefix a child does not paint but does count is an offset the
-	// walk has no bytes for. Painting the marker for those shapes is open (GH #43).
+	// Only a prose first child gets the container's marker prefix: one that counted it without
+	// painting it would hold an offset with no bytes behind it.
 	function ambientFor(node: NodeView): AmbientPrefix {
 		return isProseKind(node.kind) ? ambientPrefixForFirst : '';
 	}
 
-	// The boundary index the live gap addresses in THIS scope, when the slice reaches it.
-	// Eligibility is re-read against the children as they stand: the state cannot see an edit
-	// that changed the kinds facing this boundary, and a caret must never paint where no
-	// gesture could have parked one.
+	// The gap caret's index in this list, re-checked against the current children, since an
+	// edit can change the kinds either side of a stored gap.
 	let gapIndex = $derived.by(() => {
 		const gap = selection?.gapCaret;
 		if (!gap || !pathsEqual(gap.parentPath, parentPath)) return null;
@@ -72,14 +72,18 @@
 	});
 </script>
 
-<div class="block-list">
+<!-- A nested reorderable list marks itself, so a drag inside it can show its bounds. -->
+<div
+	class="block-list"
+	data-reorder-scope={reorderable && parentPath.length > 0 ? '' : undefined}
+	bind:this={listEl}
+>
 	{#if active}
 		<div class="vr-spacer" style="height: {win!.topSpacerPx}px"></div>
 	{/if}
 	{#each slice as node, localIndex (blockIds[start + localIndex])}
 		{@const absoluteIndex = start + localIndex}
-		<!-- ABSOLUTE-INDEX INVARIANT: index/id/key are `start + localIndex`, never the
-		     local loop index — paths and structural ops key off it. -->
+		<!-- Paths and structural edits key off the absolute index, never the loop index. -->
 		{#if gapIndex === absoluteIndex}
 			<GapCaret index={absoluteIndex} {focusActions} {blockEdit} />
 		{/if}
@@ -93,8 +97,7 @@
 			{reorderable}
 		/>
 	{/each}
-	<!-- The slice's trailing boundary: the scope end when the slice reaches it, and
-	     otherwise the seam with the next windowed-out block. -->
+	<!-- A gap caret at the end of the rendered range, which may be before an unmounted block. -->
 	{#if gapIndex === end}
 		<GapCaret index={end} {focusActions} {blockEdit} />
 	{/if}

package/dist/components/DecorationOverlay.svelte

@@ -21,8 +21,8 @@
 		path: number[];
 		blockRef: BlockComponent | undefined;
 		blockEl: HTMLElement | null | undefined;
-		/** Containers paint nothing — children self-paint — except grids, whose cells
-		 *  aren't BlockHosted and so paint whole-cell marks here. */
+		/** Containers paint nothing, since their children paint themselves, except grids:
+		 *  their cells have no BlockHost of their own, so whole-cell marks paint here. */
 		isContainer?: boolean;
 		/** Decided at BlockHost, which hands the same value to SelectionOverlay. */
 		containerPaintsRects?: boolean;
@@ -30,11 +30,11 @@
 
 	const services = getContext<EditorServices | undefined>(EDITOR_SERVICES_KEY);
 	const engine = services?.decorations;
-	// Optional for the same reason `services` is: a bare mount provides no shell.
+	// Optional for the same reason `services` is: a mount without the editor shell has none.
 	const getEditorRoot = getContext<EditorDoc | undefined>(EDITOR_DOC_KEY)?.editorRoot;
 
-	/** A mark's `interactive.onClick` is author code on a user gesture, so it routes to
-	 *  the same error seam as every other decoration entry point (editor.md §12). */
+	/** A mark's `interactive.onClick` is plugin code, so its errors go to the `error` event like
+	 *  every other decoration entry point's. */
 	function runInteraction(run: () => void): void {
 		try {
 			run();
@@ -43,8 +43,8 @@
 		}
 	}
 
-	// A grid supplies cellRect, so its descendant cell marks — which get no BlockHost
-	// overlay of their own — paint as whole cells here.
+	// A grid supplies cellRect, so marks on its cells, which have no BlockHost overlay
+	// of their own, paint as whole cells here.
 	const containerPaintsCells = $derived(isContainer && !!blockRef?.cellRect);
 
 	interface Painted {
@@ -62,9 +62,8 @@
 		const eng = engine,
 			ref = blockRef,
 			el = blockEl;
-		// Read the bucket up front so this effect registers the reactive decoration set
-		// as a dependency: `sourceCount` is a plain counter, so a source added after
-		// mount would otherwise never re-run it.
+		// Read up front so the effect depends on the decoration set: `sourceCount` is a plain
+		// counter, and a source added after mount would never re-run it.
 		const marks = eng
 			? containerPaintsCells
 				? eng.marksForDescendants(path)

package/dist/components/DecorationOverlay.svelte.d.ts

@@ -3,8 +3,8 @@ type $$ComponentProps = {
     path: number[];
     blockRef: BlockComponent | undefined;
     blockEl: HTMLElement | null | undefined;
-    /** Containers paint nothing — children self-paint — except grids, whose cells
-     *  aren't BlockHosted and so paint whole-cell marks here. */
+    /** Containers paint nothing, since their children paint themselves, except grids:
+     *  their cells have no BlockHost of their own, so whole-cell marks paint here. */
     isContainer?: boolean;
     /** Decided at BlockHost, which hands the same value to SelectionOverlay. */
     containerPaintsRects?: boolean;