@quillmark/svelte 0.20.1 → 0.22.0

package/dist/visual/VisualEditorInner.svelte

@@ -31,8 +31,9 @@
 		type Landing
 	} from '../core/address.js';
 	import { errorMessage, reportError } from '../core/errors.js';
-	import { bloomInside } from '../core/bloom.js';
+	import { bloom } from '../core/bloom.js';
 	import { createLifespan } from '../core/teardown.js';
+	import { spacePx } from '../core/rungs.js';
 	import type {
 		Addr,
 		CardAddr,
@@ -80,11 +81,12 @@
 	} from './diagnostics.js';
 	import { fieldDomIds, groupPanelId } from './domid.js';
 	import { createLeafRegistry, type ActiveProse, type FieldControl } from './leaves.js';
-	import { reorder, reorderArm, reorderTrips } from './motion.js';
+	import { reorder, reorderArm, reorderTrips, scrollSettled, slot } from './motion.js';
 	import { tipsChannel } from './tips.js';
 	import { patchEditorExt } from './ext.js';
 	import { raiseGuidance } from './guidance.js';
 	import Card from './Card.svelte';
+	import Icon from './icons/Icon.svelte';
 	import TipsCard from './TipsCard.svelte';
 	import FormatPopover from './FormatPopover.svelte';
 	// The add trigger and the kind menu draw shared recipes; a component carrying a
@@ -194,6 +196,7 @@
 	type CardHandle = {
 		revealLeaf(key: string): void;
 		scrollIntoViewCard(block: ScrollLogicalPosition): void;
+		focusHeader(): void;
 	};
 	let mainCard = $state<CardHandle | undefined>(undefined);
 	let cardRefs = $state<(CardHandle | undefined)[]>([]);
@@ -217,7 +220,7 @@
 		const card = addr.card;
 		return card != null ? { card, field: addr.field } : { field: addr.field };
 	}
-	function handleFocus(addr: Addr): void {
+	function handleFocus(addr: Addr, steps: readonly PathStep[] = []): void {
 		const plain = normalize(addr);
 		activeAddr = plain;
 		activeCardId = cardIdOf(plain);
@@ -225,7 +228,7 @@
 		// to at the offset it still names has to report again.
 		lastCaretField = undefined;
 		lastCaretPos = undefined;
-		const field = pathFor(plain);
+		const field = pathFor(plain, steps);
 		// Both halves or neither: a stale addr names no path and no live card.
 		if (field != null && activeCardId != null)
 			onActiveLeafChange?.({ field, cardId: activeCardId });
@@ -242,11 +245,11 @@
 		return model.cards.map((c) => c.kind);
 	}
 	/**
-	 * A leaf's canonical `DocPath`. `undefined` for an address outside the live card
-	 * array (a stale addr: drop rather than mis-target).
+	 * A leaf's canonical `DocPath`, `steps` down from the field. `undefined` for an
+	 * address outside the live card array (a stale addr: drop rather than mis-target).
 	 */
-	function pathFor(addr: Addr): DocPath | undefined {
-		return fieldPathForAddr(addr, addr.card == null ? NO_KINDS : liveKinds());
+	function pathFor(addr: Addr, steps: readonly PathStep[] = []): DocPath | undefined {
+		return fieldPathForAddr(addr, addr.card == null ? NO_KINDS : liveKinds(), steps);
 	}
 	// The last place reported, so a caret that did not move is not news. A leaf fires
 	// one caret signal per transaction, and a transaction need not have moved the
@@ -377,10 +380,10 @@
 	 * naming one id, on different terms — `center` against `nearest`.
 	 */
 	let scrollTicket = 0;
-	async function scrollCardIntoView(id: string, block: ScrollLogicalPosition): Promise<void> {
+	async function scrollCardIntoView(id: string, block: ScrollLogicalPosition): Promise<boolean> {
 		const ticket = ++scrollTicket;
-		if (!(await span.resumes(tick()))) return;
-		if (ticket !== scrollTicket) return;
+		if (!(await span.resumes(tick()))) return false;
+		if (ticket !== scrollTicket) return false;
 		// A reorder is running by this flush and holds the slot at its pre-move position
 		// for the length of the trip (`motion.ts`), so asking now measures the box the
 		// card is leaving — where a `nearest` would take the stack back to for the card
@@ -390,26 +393,33 @@
 		const slot = slotEls[cardIndexOf(id)];
 		const trips = slot ? reorderTrips(slot) : [];
 		if (trips.length) {
-			if (!(await span.resumes(Promise.allSettled(trips.map((trip) => trip.finished))))) return;
-			if (ticket !== scrollTicket) return;
+			if (!(await span.resumes(Promise.allSettled(trips.map((trip) => trip.finished)))))
+				return false;
+			if (ticket !== scrollTicket) return false;
 		}
 		const i = cardIndexOf(id);
-		if (i >= 0) cardRefs[i]?.scrollIntoViewCard(block);
+		if (i < 0) return false;
+		cardRefs[i]?.scrollIntoViewCard(block);
+		return true;
 	}
 	/** Returns the new card's session key, or `undefined` when the kind seeds nothing
-	 *  or the insert threw: what `insertCard` hands a host that wants to track it. */
-	function addCard(atIndex: number, kind: string): CardId | undefined {
+	 *  or the insert threw: what `insertCard` hands a host that wants to track it. The
+	 *  strip's own add `land`s focus in the new card; a host's leaves focus where it is. */
+	function addCard(atIndex: number, kind: string, land = false): CardId | undefined {
 		try {
 			const overlay = doc.seedOverlay(kind);
 			const card = quill.seedCard(kind, overlay);
 			if (!card) return undefined;
+			const from = document.activeElement;
 			doc.insertCard(card, atIndex);
 			const id = seq.next();
+			arm.arm();
 			cardIds = [...cardIds.slice(0, atIndex), id, ...cardIds.slice(atIndex)];
 			bump('structure', id, atIndex);
 			// Centred: the new card is the subject, and the neighbours it landed between
 			// are what say where it went.
-			void scrollCardIntoView(id, 'center');
+			const scrolled = scrollCardIntoView(id, 'center');
+			if (land) void landInCard(id, scrolled, from);
 			return id;
 		} catch (e) {
 			reportError(onError, {
@@ -421,8 +431,39 @@
 			return undefined;
 		}
 	}
-	// The reorder gesture's arming window (`motion.ts`): the reconcile that moves a slot
-	// is the trip, and every other reconcile that happens to move one is not.
+	/**
+	 * Focus the card the strip just added: its first field, else its body, else its title.
+	 *
+	 * After the centring scroll has run rather than beside it: a control's `focus()`
+	 * takes the browser's own scroll, which cuts a smooth one short wherever it had
+	 * reached. A focus that went elsewhere while the scroll ran was the user's, and stays.
+	 */
+	async function landInCard(
+		id: CardId,
+		scrolled: Promise<boolean>,
+		from: Element | null
+	): Promise<void> {
+		if (!(await scrolled) || !(await span.resumes(scrollSettled()))) return;
+		const now = document.activeElement;
+		if (now !== from && now !== document.body) return;
+		const at = cardIndexOf(id);
+		const shown = model.cards[at];
+		if (!shown) return;
+		const first = (shown.sections.find((s) => s.group == null) ?? shown.sections[0])?.fields[0];
+		const path = first || shown.hasBody ? pathFor({ card: at, field: first?.name }) : undefined;
+		const found = path && (await revealLeaf(path));
+		if (found) await land(found, undefined);
+		else cardRefs[cardIndexOf(id)]?.focusHeader();
+	}
+	// A kind picked off the menu lands focus in the card it added, so the menu's close
+	// hands none back to its trigger; an Escape out of the menu still does.
+	let picked = false;
+	function addPicked(atIndex: number, kind: string): void {
+		picked = addCard(atIndex, kind, true) != null;
+	}
+
+	// The list gesture's arming window (`motion.ts`): the reconcile that moves a slot is
+	// the trip, and every other reconcile that happens to move one is not.
 	const arm = reorderArm();
 	span.onEnd(arm.cancel);
 
@@ -445,7 +486,12 @@
 	function removeCardById(id: string): void {
 		const i = cardIndexOf(id);
 		if (i < 0) return;
+		// Held visibly, which a pointer's press on delete is not: some engines focus a
+		// pressed button, and the hand-on is the keyboard's.
+		const focused = document.activeElement;
+		const held = !!focused && !!slotEls[i]?.contains(focused) && focused.matches(':focus-visible');
 		doc.removeCard(i);
+		arm.arm();
 		cardIds = cardIds.filter((_, k) => k !== i);
 		if (activeCardId === id) {
 			activeCardId = undefined;
@@ -460,6 +506,15 @@
 		// No addr: the removed card has none left and every survivor's shifted. The
 		// stack changed, not a leaf, and the id is the only handle the removal leaves.
 		bump('structure', id);
+		if (held) void focusAfterRemove(i);
+	}
+	/** Hand the focus a removed card held to the title of the card before it, else the
+	 *  one that took its place, else the strip that adds one: a focused node the flush
+	 *  drops leaves the focus on the page's body, and the keyboard's place with it. */
+	async function focusAfterRemove(at: number): Promise<void> {
+		if (!(await span.resumes(tick()))) return;
+		if (cardIds.length) cardRefs[Math.max(at - 1, 0)]?.focusHeader();
+		else rootEl?.querySelector<HTMLElement>('.qm-add-btn')?.focus();
 	}
 	function retypeCardById(id: string, kind: string): void {
 		const i = cardIndexOf(id);
@@ -481,7 +536,10 @@
 			});
 		}
 	}
+	/** A title's blur can fire as the surface is torn down, against a document that may be
+	 *  freed. */
 	function renameCardById(id: string, title: string): void {
+		if (!span.alive) return;
 		const i = cardIndexOf(id);
 		if (i < 0) return;
 		patchEditorExt(doc, { card: i }, { title });
@@ -678,10 +736,10 @@
 		// (where landing a caret changes nothing on screen) or one off-screen, where the
 		// browser's focus-scroll moves the page and leaves the caret to be hunted for.
 		const box = await land(found, at.granularity === 'segment' ? undefined : at.pos);
-		if (span.alive) bloomInside(box);
+		if (span.alive) bloom(box);
 	}
 	/** The active prose leaf: the formatting popover's observation seam. The active
-	 *  field's controller where it registered one, else the by-value leaf focused last
+	 *  field's own leaf where it registered one, else the by-value leaf focused last
 	 *  under it (`leaves.ts`); `undefined` for a form control, which holds no marks to
 	 *  toggle. */
 	export function getActiveLeaf(): ActiveProse | undefined {
@@ -689,7 +747,7 @@
 		const card = activeAddr.card != null ? activeCardId : undefined;
 		const key = fieldKeyToString({ card, field: activeAddr.field });
 		const controller = leaves.prose(key);
-		if (controller) return { views: controller as FieldController & LeafViews, controller };
+		if (controller) return { views: controller as FieldController & LeafViews };
 		const views = leaves.value(key);
 		return views && { views };
 	}
@@ -768,7 +826,7 @@
 		const found = await revealLeaf(field);
 		if (!found) return missed(`no mounted field at ${field}`, field);
 		const box = await land(found, undefined);
-		if (span.alive) bloomInside(box);
+		if (span.alive) bloom(box);
 	}
 	/** Seed a card of `kind` and insert it at `at` (default: the end). Returns the new
 	 *  card's session key, or `undefined` when the quill seeds no card of that kind. */
@@ -892,7 +950,7 @@
 	 rather than being slid across. It is also the shape `animate:` asks for, being the
 	 keyed block's only child. -->
 	{#each model.cards as c, i (c.id)}
-		<div class="qm-card-slot" bind:this={slotEls[i]} animate:reorder={arm.armed}>
+		<div class="qm-card-slot" bind:this={slotEls[i]} animate:reorder={arm.armed} in:slot out:slot>
 			<Card
 				bind:this={cardRefs[i]}
 				card={titled(c)}
@@ -925,9 +983,10 @@
 {#snippet addAffordance(atIndex: number)}
 	{#if kinds.length}
 		<!-- The strip past the last card is the append point, the one a reader looks for
-		 rather than finds by position, so it alone states itself in words at rest. The
-		 gaps between cards stay bare: the strip is the gap, and the pill each fills on
-		 hover draws what a label would state, the space the new card takes. -->
+		 rather than finds by position, so it alone states itself in words at rest. A gap
+		 between cards carries a plus where the words would be: the strip is the gap, the
+		 pill it fills on hover is the space the new card takes, and the plus says what a
+		 press there does. -->
 		{@const marked = atIndex === model.cards.length}
 		<div class={['qm-add-card', { 'qm-add-card-marked': marked }]}>
 			<!-- Marked, the words are the accessible name and no `aria-label` doubles
@@ -936,9 +995,10 @@
 			{#if kinds.length === 1}
 				<button
 					type="button"
-					class="qm-add-btn qm-add-affordance qm-tap-floor"
+					class="qm-add-btn qm-add-affordance qm-tap-floor qm-focus-ring"
 					aria-label={marked ? undefined : merged.addCard}
-					onclick={() => addCard(atIndex, kinds[0])}>{marked ? merged.addCard : ''}</button
+					onclick={() => addCard(atIndex, kinds[0], true)}
+					>{#if marked}{merged.addCard}{:else}<Icon name="plus" class="qm-add-glyph" />{/if}</button
 				>
 			{:else}
 				<!-- Multi-kind add: pick the kind, then seed + insert. A menu rather than a
@@ -948,12 +1008,22 @@
 			 rules below reach it through `:global`. -->
 				<DropdownMenu.Root>
 					<DropdownMenu.Trigger
-						class="qm-add-btn qm-add-affordance qm-tap-floor"
+						class="qm-add-btn qm-add-affordance qm-tap-floor qm-focus-ring"
 						aria-label={marked ? undefined : merged.addCard}
-						>{marked ? merged.addCard : ''}</DropdownMenu.Trigger
+						>{#if marked}{merged.addCard}{:else}<Icon
+								name="plus"
+								class="qm-add-glyph"
+							/>{/if}</DropdownMenu.Trigger
 					>
 					<DropdownMenu.Portal to={rootEl}>
-						<DropdownMenu.Content collisionBoundary={rootEl ?? []} sideOffset={4}>
+						<DropdownMenu.Content
+							collisionBoundary={rootEl ?? []}
+							sideOffset={spacePx(rootEl)}
+							onCloseAutoFocus={(e) => {
+								if (picked) e.preventDefault();
+								picked = false;
+							}}
+						>
 							<!-- Portalled out of the row but into the stack's root, and carrying the
 						     marker itself: floating is still a detached subtree to the
 						     derivation, like FormatPopover and the enum listbox. The root is the
@@ -961,7 +1031,7 @@
 						     the surface where the consumer scrolls one. -->
 							<div class="qm-menu-surface" data-qm-root>
 								{#each kinds as k (k)}
-									<DropdownMenu.Item class="qm-menu-item" onSelect={() => addCard(atIndex, k)}
+									<DropdownMenu.Item class="qm-menu-item" onSelect={() => addPicked(atIndex, k)}
 										>{kindTitle(quill.schema.card_kinds?.[k], k)}</DropdownMenu.Item
 									>
 								{/each}
@@ -1072,9 +1142,10 @@
 	/* Unboxed, like every button, and not dashed: a dashed edge is the placeholder idiom
 	 ("nothing is here yet"), which on a button reads as disabled or as a drop target. It
 	 stays honest in one place, the un-schemable card (`Card.svelte`), which is a state
-	 rather than a control. A bare trigger rests invisible, so the fill is the whole of
-	 what it shows: the pill fills the strip because the strip is what was pressed, and
-	 the strip is the gap, so the fill is the card-to-be drawn where it will land.
+	 rather than a control. A gap's trigger rests invisible, so the fill and the plus are
+	 the whole of what it shows: the pill fills the strip because the strip is what was
+	 pressed, and the strip is the gap, so the fill is the card-to-be drawn where it will
+	 land.
 
 	 No inset of its own: the pill and the gap are the same rectangle, and a bare strip is
 	 a band of gutter, so its height is a rhythm rung. The press floor the box gives up is
@@ -1097,8 +1168,15 @@
 		color: var(--_qm-ink-label);
 		opacity: 0;
 		transition:
-			opacity var(--_qm-reveal),
-			background-color var(--_qm-reveal);
+			opacity var(--_qm-duration-fast) var(--_qm-ease-reverse),
+			background-color var(--_qm-duration-fast) var(--_qm-ease-reverse);
+	}
+	/* The pill's own height, so a turned-down `--qm-space` shrinks the glyph with the
+	   strip rather than spilling it past the pill. */
+	.qm-add-card :global(.qm-add-glyph) {
+		height: 100%;
+		width: auto;
+		aspect-ratio: 1;
 	}
 	/* The strip that holds words at rest takes the height that centres them, and rests dim
 	   rather than absent, having something to be seen. */
@@ -1111,11 +1189,15 @@
 	/* One arrival, three ways in. Keyboard focus, because the fill is the only thing that
 	   reads as the trigger on a bare strip; and an open menu, because it portals out of
 	   the strip, so a pointer moving onto an item has left the row whose hover was drawing
-	   the pill the menu hangs from. */
+	   the pill the menu hangs from. The arrival takes the long trip and the leave the fast
+	   rung, a transition being the state's it ends in. */
 	.qm-add-card :global(.qm-add-btn:hover),
 	.qm-add-card :global(.qm-add-btn:focus-visible),
 	.qm-add-card :global(.qm-add-btn[data-state='open']) {
 		opacity: 1;
 		background: var(--_qm-add-fill);
+		transition:
+			opacity var(--_qm-reveal),
+			background-color var(--_qm-reveal);
 	}
 </style>

package/dist/visual/controls.css

@@ -233,7 +233,8 @@
 :where(.qm-chip:hover) {
 	color: var(--_qm-ink);
 }
-:where(.qm-chip svg) {
+:where(.qm-chip svg),
+:where(.qm-icon-btn svg) {
 	flex-shrink: 0;
 	width: var(--_qm-glyph-control);
 	height: var(--_qm-glyph-control);
@@ -266,6 +267,22 @@
 	transform: translate(-50%, -50%);
 }
 
+/* The arrival wash: a plane over the host's box at rest, which a landing plays
+ (`core/bloom.ts`). On the host from mount, because WebKit resizes a laid-out subgrid's
+ tracks when an out-of-flow box is added to it. */
+:where(.qm-wash) {
+	position: relative;
+}
+:where(.qm-wash)::after {
+	content: '';
+	position: absolute;
+	inset: 0;
+	border-radius: inherit;
+	background: var(--_qm-accent-wash);
+	opacity: 0;
+	pointer-events: none;
+}
+
 /* The capacity ladder: how many tracks a grid of fields steps to, off the width of
  the query container it stands in. One recipe, because three grids read it — a section's
  fields (`Card.svelte`), a subform's properties (`ObjectField`), each over its own
@@ -310,7 +327,8 @@
  highlight the keyboard cannot reach. It fills with the accent held rather than
  the hover rung: the mark is a cursor a keyboard drives, so it has to read at a
  glance from across the list, where a hover only has to confirm the pointer
- already under it.
+ already under it. So the mark is the item's whole focus indicator, and the
+ outline a focused item would draw beside it is taken off.
 
  The resting fill is the recipe's too: an item drawn on a `<button>` carries a UA
  fill to take back, and a scoped block outranks this file, so a caller taking it
@@ -337,6 +355,7 @@
 	background: transparent;
 	cursor: pointer;
 	user-select: none;
+	outline: none;
 }
 :where(.qm-menu-item[data-highlighted]) {
 	background: var(--_qm-accent-tint);

package/dist/visual/icons/Icon.svelte

@@ -9,8 +9,9 @@
 
 	interface Props extends Omit<SVGAttributes<SVGSVGElement>, 'name'> {
 		name: IconName;
-		/** The frame's edge, in px. A chip sizes the glyph from `--_qm-glyph-control`
-		 *  in CSS, which beats this attribute; callers that are not chips pass a size. */
+		/** The frame's edge, in px. A chip or a glyph button sizes the glyph from
+		 *  `--_qm-glyph-control` in CSS, which beats this attribute; other callers pass
+		 *  a size. */
 		size?: number;
 	}
 	let { name, size = 24, ...rest }: Props = $props();

package/dist/visual/icons/Icon.svelte.d.ts

@@ -2,8 +2,9 @@ import { type IconName } from './nodes.js';
 import type { SVGAttributes } from 'svelte/elements';
 interface Props extends Omit<SVGAttributes<SVGSVGElement>, 'name'> {
     name: IconName;
-    /** The frame's edge, in px. A chip sizes the glyph from `--_qm-glyph-control`
-     *  in CSS, which beats this attribute; callers that are not chips pass a size. */
+    /** The frame's edge, in px. A chip or a glyph button sizes the glyph from
+     *  `--_qm-glyph-control` in CSS, which beats this attribute; other callers pass
+     *  a size. */
     size?: number;
 }
 declare const Icon: import("svelte").Component<Props, {}, "">;

package/dist/visual/icons/nodes.d.ts

@@ -15,6 +15,31 @@ export declare const ICONS: {
     readonly 'chevron-up': readonly [readonly ["path", {
         readonly d: "m18 15-6-6-6 6";
     }]];
+    readonly 'grip-vertical': readonly [readonly ["circle", {
+        readonly cx: "9";
+        readonly cy: "12";
+        readonly r: "1";
+    }], readonly ["circle", {
+        readonly cx: "9";
+        readonly cy: "5";
+        readonly r: "1";
+    }], readonly ["circle", {
+        readonly cx: "9";
+        readonly cy: "19";
+        readonly r: "1";
+    }], readonly ["circle", {
+        readonly cx: "15";
+        readonly cy: "12";
+        readonly r: "1";
+    }], readonly ["circle", {
+        readonly cx: "15";
+        readonly cy: "5";
+        readonly r: "1";
+    }], readonly ["circle", {
+        readonly cx: "15";
+        readonly cy: "19";
+        readonly r: "1";
+    }]];
     readonly bold: readonly [readonly ["path", {
         readonly d: "M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8";
     }]];
@@ -62,27 +87,6 @@ export declare const ICONS: {
     }], readonly ["path", {
         readonly d: "M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71";
     }]];
-    readonly hash: readonly [readonly ["line", {
-        readonly x1: "4";
-        readonly x2: "20";
-        readonly y1: "9";
-        readonly y2: "9";
-    }], readonly ["line", {
-        readonly x1: "4";
-        readonly x2: "20";
-        readonly y1: "15";
-        readonly y2: "15";
-    }], readonly ["line", {
-        readonly x1: "10";
-        readonly x2: "8";
-        readonly y1: "3";
-        readonly y2: "21";
-    }], readonly ["line", {
-        readonly x1: "16";
-        readonly x2: "14";
-        readonly y1: "3";
-        readonly y2: "21";
-    }]];
     readonly info: readonly [readonly ["circle", {
         readonly cx: "12";
         readonly cy: "12";

package/dist/visual/icons/nodes.js

@@ -5,7 +5,7 @@
 //
 // Verbatim from lucide 1.28.0 — the version is stated because a glyph that drifts
 // from upstream is otherwise invisible, and because the notices in `NOTICE` are the
-// ones that release carries (ISC, and MIT for the Feather-derived ten).
+// ones that release carries (ISC, and MIT for the Feather-derived glyphs).
 export const ICONS = {
     'chevron-right': [['path', { d: 'm9 18 6-6-6-6' }]],
     'arrow-right': [
@@ -14,6 +14,14 @@ export const ICONS = {
     ],
     'chevron-down': [['path', { d: 'm6 9 6 6 6-6' }]],
     'chevron-up': [['path', { d: 'm18 15-6-6-6 6' }]],
+    'grip-vertical': [
+        ['circle', { cx: '9', cy: '12', r: '1' }],
+        ['circle', { cx: '9', cy: '5', r: '1' }],
+        ['circle', { cx: '9', cy: '19', r: '1' }],
+        ['circle', { cx: '15', cy: '12', r: '1' }],
+        ['circle', { cx: '15', cy: '5', r: '1' }],
+        ['circle', { cx: '15', cy: '19', r: '1' }]
+    ],
     bold: [['path', { d: 'M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8' }]],
     italic: [
         ['line', { x1: '19', x2: '10', y1: '4', y2: '4' }],
@@ -37,12 +45,6 @@ export const ICONS = {
         ['path', { d: 'M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71' }],
         ['path', { d: 'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71' }]
     ],
-    hash: [
-        ['line', { x1: '4', x2: '20', y1: '9', y2: '9' }],
-        ['line', { x1: '4', x2: '20', y1: '15', y2: '15' }],
-        ['line', { x1: '10', x2: '8', y1: '3', y2: '21' }],
-        ['line', { x1: '16', x2: '14', y1: '3', y2: '21' }]
-    ],
     info: [
         ['circle', { cx: '12', cy: '12', r: '10' }],
         ['path', { d: 'M12 16v-4' }],

package/dist/visual/leaves.d.ts

@@ -8,8 +8,8 @@ import type { FieldController, LeafViews } from '../core/codec/index.js';
  */
 export type LandingBox = HTMLElement | undefined | Promise<HTMLElement | undefined>;
 /**
- * A mounted field's landing handle: focus it, and the element the arrival wash blooms
- * inside ({@link import('../core/bloom.js').bloomInside}).
+ * A mounted field's landing handle: focus it, and the `.qm-wash` box the arrival wash
+ * plays over ({@link import('../core/bloom.js').bloom}).
  *
  * A `FieldController` is one, which is what lets the two lanes share a lookup; `Field`
  * builds the same shape over a form control off the handoff a label click already
@@ -71,16 +71,19 @@ export interface LeafRegistry {
     clear(): void;
 }
 export declare function createLeafRegistry(): LeafRegistry;
-/**
- * The active prose leaf as the formatting popover reaches it: the views a selection is
- * read from and a mark toggled at, and the controller where the leaf is a field's. A
- * by-value leaf has none, its anchors being dropped on the parent's value write, so the
- * anchor verbs the controller carries have nothing to act on there.
- */
+/** The active prose leaf as the formatting popover reaches it: the views a selection is
+ *  read from and a mark toggled at. */
 export interface ActiveProse {
     views: LeafViews;
-    controller?: FieldController;
 }
+/**
+ * The steps from a field's control box `root` down to the cell holding `target`, the
+ * reverse of {@link FieldControl.focusPath}: read off the marker each container rung
+ * stamps on the cell it draws, `data-qm-index` on an array's row and `data-qm-prop` on a
+ * key step (an object's property, a variant's cell, a matrix's member and an added
+ * item's title). `[]` for a target on the field's own control.
+ */
+export declare function stepsTo(target: EventTarget | null, root: Element): PathStep[];
 /** The by-value lane with a field's key bound: what a leaf under that field announces
  *  itself through, knowing no key of its own. */
 export interface ValueLeafSeat {

package/dist/visual/leaves.js

@@ -66,6 +66,25 @@ export function createLeafRegistry() {
         }
     };
 }
+/**
+ * The steps from a field's control box `root` down to the cell holding `target`, the
+ * reverse of {@link FieldControl.focusPath}: read off the marker each container rung
+ * stamps on the cell it draws, `data-qm-index` on an array's row and `data-qm-prop` on a
+ * key step (an object's property, a variant's cell, a matrix's member and an added
+ * item's title). `[]` for a target on the field's own control.
+ */
+export function stepsTo(target, root) {
+    const steps = [];
+    for (let el = target instanceof Element ? target : null; el && el !== root; el = el.parentElement) {
+        const index = el.getAttribute('data-qm-index');
+        const key = el.getAttribute('data-qm-prop');
+        if (index != null)
+            steps.push(Number(index));
+        else if (key != null)
+            steps.push(key);
+    }
+    return steps.reverse();
+}
 const SEAT = Symbol('qm-value-leaf');
 /** Seat every by-value leaf under the calling field, at any depth of its containers. */
 export function seatValueLeaves(seat) {

package/dist/visual/motion.d.ts

@@ -1,4 +1,5 @@
 import type { AnimationConfig } from 'svelte/animate';
+import type { TransitionConfig } from 'svelte/transition';
 /** The trips this module is running on `node`. A run holds the slot at its pre-move
  *  position for its whole length, so anything that measures the node's box waits on
  *  these rather than reading the one a transform is holding. */
@@ -23,9 +24,11 @@ export declare function reorderArm(): ReorderArm;
  * `armed` is why this is the reorder and not every reconcile: `animate:` fires wherever
  * a slot's rect moved, and a card growing under the caret moves every slot below it,
  * which is a layout change with no trip in it and one that would draw those slots over
- * the content that displaced them for the length of the run. So the reorder command
- * arms the gesture and the frame it lands in disarms it, which is the admission test
- * read off the endpoints: two positions in the list, not two positions on the page.
+ * the content that displaced them for the length of the run. So a command that moves
+ * slots in the list arms the gesture and the frame it lands in disarms it, which is the
+ * admission test read off the endpoints: two positions in the list, not two positions on
+ * the page. A move is one; so, in the card stack, are an insert and a removal, which move
+ * every slot past them by one.
  *
  * Both endpoints are rest states, so the curve is `--_qm-ease-reverse` (a second click
  * lands mid-slide) and the rung is `slow` (the trip moves the stack around it).
@@ -34,3 +37,22 @@ export declare function reorder(node: HTMLElement, { from, to }: {
     from: DOMRect;
     to: DOMRect;
 }, armed: () => boolean): AnimationConfig;
+/**
+ * A slot entering or leaving the list fades where it stands, while the slots it displaces
+ * take the reorder trip: the stack is what slides, and a card is what appears or goes, under
+ * the slots crossing it. Opacity alone, because a leaving slot is held at its place by a
+ * transform `animate:` writes, which a keyframed transform would override.
+ *
+ * The returned duration is what keeps a leaving slot mounted until its fade has run, and
+ * the fill what keeps it from painting whole in the frame between the two.
+ */
+export declare function slot(node: HTMLElement, _params: unknown, { direction }: {
+    direction: 'in' | 'out' | 'both';
+}): TransitionConfig;
+/**
+ * Resolves once nothing in the document has scrolled for {@link STILL_FRAMES} frames
+ * running. A smooth scroll moves its scroller on every frame until it lands, so stillness
+ * is its end on every engine, whether or not it reports one; a scroll with nowhere to go
+ * is still from the first frame.
+ */
+export declare function scrollSettled(): Promise<void>;