@quillmark/svelte 0.11.0 → 0.12.0

package/dist/visual/VariantField.svelte

@@ -10,12 +10,16 @@
  container with one cell written — and cells outside the drawn world ride through
  untouched rather than needing to be merged back. A content cell reads at the key it
  declares: the boundary's schema walk unions the worlds, so a dormant cell reads absent
- rather than raising.
+ rather than raising. A cell may be a container of its own, which the subform draws at
+ the next rung.
 -->
 <script lang="ts">
 	import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
 	import EnumField from './EnumField.svelte';
 	import ObjectField from './ObjectField.svelte';
+	import DiagnosticList from './DiagnosticList.svelte';
+	import type { DeepDiagnostic } from './diagnostics.js';
+	import type { LandingBox } from './leaves.js';
 	import {
 		VARIANT_DISCRIMINANT,
 		commitDiscriminant,
@@ -43,6 +47,10 @@
 		onCommit: (v: Record<string, unknown> | undefined) => void;
 		optionAllowed?: (value: string) => boolean;
 		enumDisallowed?: 'hide' | 'disable';
+		/** The diagnostics routed into this field, each with its steps still to walk: one
+		 * naming a live cell draws under it; the rest — the discriminant's, a dormant
+		 * world's — draw at the field's foot. */
+		diagnostics?: readonly DeepDiagnostic[];
 	}
 	let {
 		value,
@@ -55,12 +63,52 @@
 		contentAt,
 		onCommit,
 		optionAllowed,
-		enumDisallowed
+		enumDisallowed,
+		diagnostics
 	}: Props = $props();
 
 	const member = $derived(variantMember(value, ghostMember));
 	const cells = $derived(variantCells(schema, member));
 	const discriminant = $derived(value?.[VARIANT_DISCRIMINANT] as string | undefined);
+
+	type Subform = {
+		focus: () => void;
+		focusPath: (steps: readonly PathStep[], pos?: number) => LandingBox;
+	};
+	let cellsEl = $state<Subform | undefined>();
+
+	/** Whether a step names a cell the live world draws. The one test the landing and
+	 *  the diagnostics both read, so the cell a caret lands in is the cell a message
+	 *  draws under. The discriminant is the field's own control and no world's cell. */
+	function live(step: PathStep | undefined): boolean {
+		return (
+			typeof step === 'string' &&
+			step !== VARIANT_DISCRIMINANT &&
+			!!cells &&
+			Object.hasOwn(cells, step)
+		);
+	}
+	// The cells' own, and the field's: a diagnostic naming the discriminant or a world
+	// that is not drawn has no cell to sit under, and the subform's foot is inside a box
+	// holding the live world alone. So it draws under the field, where the control it is
+	// about is.
+	const inside = $derived((diagnostics ?? []).filter((d) => live(d.steps[0])));
+	const foot = $derived(
+		(diagnostics ?? []).filter((d) => !live(d.steps[0])).map((d) => d.diagnostic)
+	);
+
+	/** Take the caret: the discriminant's trigger, the field's own control. */
+	export function focus(): void {
+		if (id) document.getElementById(id)?.focus();
+	}
+	/** Land at `steps`: a live cell, and the rest of the walk inside it where the cell is
+	 *  a container; the discriminant, a dormant world's cell and a key no world declares
+	 *  land on the trigger ({@link FieldControl.focusPath}). */
+	export function focusPath(steps: readonly PathStep[], pos?: number): LandingBox {
+		if (live(steps[0]) && cellsEl) return cellsEl.focusPath(steps, pos);
+		focus();
+		return undefined;
+	}
 </script>
 
 <div class="qm-variant">
@@ -81,6 +129,7 @@
 	{#if cells}
 		{#key member}
 			<ObjectField
+				bind:this={cellsEl}
 				value={value ?? {}}
 				properties={cells}
 				{label}
@@ -89,9 +138,13 @@
 				{describedBy}
 				{contentAt}
 				onCommit={(obj) => onCommit(obj)}
+				diagnostics={inside}
 			/>
 		{/key}
 	{/if}
+	<!-- The field's own foot, drawn whether or not a world is: what the live world
+	     cannot hold belongs under the field rather than inside the box its cells sit in. -->
+	<DiagnosticList diagnostics={foot} />
 </div>
 
 <style>

package/dist/visual/VariantField.svelte.d.ts

@@ -1,4 +1,6 @@
 import type { Content, PathStep, QuillFieldSchema } from '@quillmark/wasm';
+import type { DeepDiagnostic } from './diagnostics.js';
+import type { LandingBox } from './leaves.js';
 interface Props {
     /** The stored container, or undefined while the field is unset. */
     value: Record<string, unknown> | undefined;
@@ -19,7 +21,14 @@ interface Props {
     onCommit: (v: Record<string, unknown> | undefined) => void;
     optionAllowed?: (value: string) => boolean;
     enumDisallowed?: 'hide' | 'disable';
+    /** The diagnostics routed into this field, each with its steps still to walk: one
+     * naming a live cell draws under it; the rest — the discriminant's, a dormant
+     * world's — draw at the field's foot. */
+    diagnostics?: readonly DeepDiagnostic[];
 }
-declare const VariantField: import("svelte").Component<Props, {}, "">;
+declare const VariantField: import("svelte").Component<Props, {
+    focus: () => void;
+    focusPath: (steps: readonly PathStep[], pos?: number) => LandingBox;
+}, "">;
 type VariantField = ReturnType<typeof VariantField>;
 export default VariantField;

package/dist/visual/VisualEditorInner.svelte

@@ -24,7 +24,7 @@
 	import {
 		addrForFieldPath,
 		cardPath,
-		elementAddrForFieldPath,
+		nestedAddrForFieldPath,
 		fieldPathForAddr,
 		type DocPath,
 		type Landing
@@ -36,7 +36,9 @@
 		Addr,
 		CardAddr,
 		Diagnostic,
+		PathStep,
 		PayloadItem,
+		QuillFieldSchema,
 		Resolved,
 		ResolvedField
 	} from '@quillmark/wasm';
@@ -47,6 +49,8 @@
 	import {
 		IdSeq,
 		controlKind,
+		isContainer,
+		schemaAt,
 		fieldModels,
 		groupOrder,
 		groupSections,
@@ -75,7 +79,7 @@
 	} from './diagnostics.js';
 	import { fieldDomIds, groupPanelId } from './domid.js';
 	import { createLeafRegistry, type FieldControl } from './leaves.js';
-	import { reorder, reorderTrips } from './motion.js';
+	import { reorder, reorderArm, reorderTrips } from './motion.js';
 	import { tipsChannel } from './tips.js';
 	import { patchEditorExt } from './ext.js';
 	import Card from './Card.svelte';
@@ -424,26 +428,17 @@
 			return undefined;
 		}
 	}
-	// The reorder gesture's arming window: the reconcile that moves a
-	// slot is the trip, and every other reconcile that happens to move one is not. Read
-	// through a getter rather than passed as a value, so the flag stays out of the
-	// template and needs no reactivity for it: `animate:` asks at apply time, which is a
-	// microtask after the mutation and well inside the frame that disarms it.
-	let reordering = false;
-	let reorderFrame = 0;
-	function armReorder(): void {
-		reordering = true;
-		reorderFrame = requestAnimationFrame(() => (reordering = false));
-	}
-	span.onEnd(() => cancelAnimationFrame(reorderFrame));
-	const isReordering = (): boolean => reordering;
+	// 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.
+	const arm = reorderArm();
+	span.onEnd(arm.cancel);
 
 	function moveCardById(id: string, dir: -1 | 1): void {
 		const from = cardIndexOf(id);
 		if (from < 0) return;
 		const to = from + dir;
 		if (to < 0 || to >= doc.cardCount) return;
-		armReorder();
+		arm.arm();
 		doc.moveCard(from, to);
 		const w = cardIds.slice();
 		const [x] = w.splice(from, 1);
@@ -691,7 +686,8 @@
 		// click is one discrete act, and its commonest target is the leaf already focused
 		// (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.
-		bloomInside(land(found, at.granularity === 'segment' ? undefined : at.pos));
+		const box = await land(found, at.granularity === 'segment' ? undefined : at.pos);
+		if (span.alive) bloomInside(box);
 	}
 	/** The active leaf's controller: the formatting popover's observation seam.
 	 *  `undefined` for a focused form control, which holds no marks to toggle. */
@@ -730,20 +726,22 @@
 
 	/**
 	 * Put the caret in a revealed target, at the finest grain it can take: a USV offset
-	 * in a prose leaf or an array element, a bare focus everywhere else. A form control
-	 * has no coordinate to spend an offset in (an `<input type="number">` refuses a
-	 * selection outright), which is also the whole of what a click on plate-placed ink
-	 * can mean. An element is no `createField` leaf, so the offset goes down the element
-	 * lane instead, where what it means is the row control's (`leaves.ts`).
+	 * in a prose leaf or a nested content cell, a bare focus everywhere else. A form
+	 * control has no coordinate to spend an offset in (an `<input type="number">`
+	 * refuses a selection outright), which is also the whole of what a click on
+	 * plate-placed ink can mean. A cell is no `createField` leaf, so the offset goes
+	 * down the container's walk instead, where what it means is the leaf's (`leaves.ts`).
 	 *
 	 * Hands back the box the arrival wash blooms in, which is the landing's own
-	 * granularity rather than the registry's: an element lands in one row and says so
-	 * over that row, and everything else — the field, and a row the document has since
-	 * dropped — over the field's box.
+	 * granularity rather than the registry's: a walk lands in one row and says so over
+	 * the innermost row it opened, and everything else — the field, a property under a
+	 * field-level subform, and a row the document has since dropped — over the field's
+	 * box. Async because a row two closed boxes down exists only once the row above it
+	 * has opened and flushed.
 	 */
-	function land(found: Landed, pos: number | undefined): HTMLElement {
-		if (found.element != null && found.control.focusElement) {
-			return found.control.focusElement(found.element, pos) ?? found.control.el;
+	async function land(found: Landed, pos: number | undefined): Promise<HTMLElement> {
+		if (found.steps && found.control.focusPath) {
+			return (await found.control.focusPath(found.steps, pos)) ?? found.control.el;
 		}
 		if (pos != null) {
 			const prose = leaves.prose(found.key);
@@ -772,7 +770,8 @@
 	export async function focusField(field: DocPath): Promise<void> {
 		const found = await revealLeaf(field);
 		if (!found) return missed(`no mounted field at ${field}`, field);
-		bloomInside(land(found, undefined));
+		const box = await land(found, undefined);
+		if (span.alive) bloomInside(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. */
@@ -802,11 +801,11 @@
 		reportError(onError, { code: 'target-unknown', severity: 'dev', message, path });
 	}
 
-	/** What a `DocPath` resolves to in the mounted tree: a leaf key, and the array
-	 *  element within it when the address names one. */
+	/** What a `DocPath` resolves to in the mounted tree: a leaf key, and the steps from
+	 *  that field to the leaf when the address names one inside it. */
 	interface LeafTarget {
 		key: string;
-		element?: number;
+		steps?: PathStep[];
 	}
 	/** A resolved target with the handle the registry holds for it. */
 	type Landed = LeafTarget & { control: FieldControl };
@@ -816,11 +815,13 @@
 	 * diagnostics take.
 	 *
 	 * Two rungs, because the boundary mints addresses at a finer granularity than
-	 * `Addr` can name: a `richtext[]` element surfaces as `main.keywords[0]`. The
-	 * second rung reads that trailing index segment under a field the schema declares
-	 * an array — which is why the ladder is the editor's (VISUAL_EDITOR.md §Surface):
-	 * the preview carries no schema, and truncating the address there is worse than
-	 * guessing, since `pos` is an offset into the element's own content.
+	 * `Addr` can name: a `richtext[]` element surfaces as `main.keywords[0]`, a nested
+	 * row's cell as `main.vectors[0].tours[2].title`. The second rung reads the steps
+	 * past the field against the schema, rung by rung — an index under a declared
+	 * array, a key under a declared object, variant or matrix — which is why the ladder
+	 * is the editor's (VISUAL_EDITOR.md §Surface): the preview carries no schema, and
+	 * truncating the address there is worse than guessing, since `pos` is an offset
+	 * into the leaf's own content.
 	 */
 	function leafTargetFor(field: DocPath): LeafTarget | undefined {
 		const direct = addrForFieldPath(field);
@@ -828,22 +829,25 @@
 			const resolved = resolveCardKey(direct, cardIds);
 			return resolved ? { key: fieldKeyToString(resolved) } : undefined;
 		}
-		const element = elementAddrForFieldPath(field);
-		if (!element || !isArrayField(element.field)) return undefined;
-		const resolved = resolveCardKey(element.field, cardIds);
-		return resolved ? { key: fieldKeyToString(resolved), element: element.index } : undefined;
+		const nested = nestedAddrForFieldPath(field);
+		if (!nested) return undefined;
+		const declared = declaredField(nested.field);
+		if (!declared || !isContainer(controlKind(declared))) return undefined;
+		if (!schemaAt(declared, nested.steps)) return undefined;
+		const resolved = resolveCardKey(nested.field, cardIds);
+		return resolved ? { key: fieldKeyToString(resolved), steps: nested.steps } : undefined;
 	}
 
-	/** The guard the element rung stands on. Asked of `controlKind`, so what the ladder
-	 *  tests is the control the tree mounted — the one holding a `focusElement` — and
-	 *  not a second reading of the schema beside it. */
-	function isArrayField(addr: Addr): boolean {
-		if (addr.field == null) return false;
+	/** The schema the field at `addr` declares, off the live card's kind: the guard the
+	 *  nested rung stands on. Asked of `controlKind` and `schemaAt`, so what the ladder
+	 *  tests is the control the tree mounted — the one holding a `focusPath` — and not a
+	 *  second reading of the schema beside it. */
+	function declaredField(addr: Addr): QuillFieldSchema | undefined {
+		if (addr.field == null) return undefined;
 		const kind = addr.card == null ? undefined : model.cards[addr.card]?.kind;
 		const schema = quill.schema;
 		const card = addr.card == null ? schema.main : kind ? schema.card_kinds?.[kind] : undefined;
-		const declared = card?.fields?.[addr.field];
-		return !!declared && controlKind(declared) === 'array';
+		return card?.fields?.[addr.field];
 	}
 </script>
 
@@ -883,7 +887,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={isReordering}>
+		<div class="qm-card-slot" bind:this={slotEls[i]} animate:reorder={arm.armed}>
 			<Card
 				bind:this={cardRefs[i]}
 				card={titled(c)}

package/dist/visual/controls.css

@@ -255,6 +255,37 @@
 	transform: translate(-50%, -50%);
 }
 
+/* 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
+ container, and a compact matrix's members (`MatrixField`) — and a ladder kept in
+ several files agrees until one is retuned. Capacity is
+ the container's, not JavaScript's: nothing measures, so there is no observer to loop
+ and no re-packing to restructure the DOM under a prose leaf.
+
+ It steps 1 → 2 → 4, skipping 3: each rung is the width at which a track still clears
+ the comfortable field minimum, and an even capacity is what lets the half a subform
+ of one takes (`--cols-half`) land on a track boundary. A field ends on its track's
+ own edge, so a rung is `n * 220px + gaps`. A subform three rungs in stands three
+ `--_qm-nest` and three verticals narrower than its section, and steps down where the
+ section does not: the count is the width the tracks actually get. */
+:where(.qm-tracks) {
+	--cols: 1;
+	--cols-half: 1;
+}
+@container (min-width: 28rem) {
+	:where(.qm-tracks) {
+		--cols: 2;
+		--cols-half: 1;
+	}
+}
+@container (min-width: 57rem) {
+	:where(.qm-tracks) {
+		--cols: 4;
+		--cols-half: 2;
+	}
+}
+
 /* A floating list of choices: the enum's listbox and the card stack's kind menu.
  Both portal into the nearest `[data-qm-root]`, and both are picked from, so the
  surface (its edge, its inset, its ink) and the item (its pad, its radius, the

package/dist/visual/diagnostics.d.ts

@@ -1,4 +1,4 @@
-import type { Diagnostic } from '@quillmark/wasm';
+import type { Diagnostic, PathStep } from '@quillmark/wasm';
 /** A field's routing address, and `/core`'s `Addr` structurally: an `Addr` is a
  * positional `FieldKey`, so `nearestAddrForFieldPath` is the path→key walk and
  * routing carries no second copy of the grammar. `card` is `undefined` for the main
@@ -40,10 +40,34 @@ export interface RoutedDiagnostic {
  * Completeness stays a read the host makes on `quill.validate(doc)`.
  */
 export declare function routeAndResolve(diagnostics: Diagnostic[] | undefined, cardIds: readonly string[]): RoutedDiagnostic[];
+/** A diagnostic with the steps still to walk from the control holding it. */
+export interface DeepDiagnostic {
+    steps: readonly PathStep[];
+    diagnostic: Diagnostic;
+}
+/** A field's routed diagnostics, each with its steps past the field: none for a
+ *  diagnostic anchored at the field itself, or one whose path is not a nested one
+ *  (a local commit error carries the field's own path). */
+export declare function deepen(diagnostics: Diagnostic[] | undefined): DeepDiagnostic[];
+/** One rung of the walk: the diagnostics anchored here, and the rest bucketed by the
+ *  step they take next, each with that step consumed. */
+export interface DeepSplit {
+    here: Diagnostic[];
+    below: Map<PathStep, DeepDiagnostic[]>;
+}
+export declare function splitDeep(list: readonly DeepDiagnostic[] | undefined): DeepSplit;
+/** The diagnostics a rung cannot hand down: the ones anchored here, plus every one
+ *  whose next step names nothing in `held`. Drawn at the rung's own foot, so a leaf the
+ *  tree does not draw still has its message read somewhere the user can see. */
+export declare function unrouted(split: DeepSplit, held: (step: PathStep) => boolean): Diagnostic[];
 /**
  * Merge N routed groups into `Map<fieldKeyToString(key), Diagnostic[]>`.
- * Dedupes an identical `(severity, message)` pair landing on the same key from
+ * Dedupes an identical `(path, severity, message)` quad landing on the same key from
  * more than one group (e.g. the same error present in both `validate()` and
  * an external feed). Producer order within a key.
+ *
+ * The key is the field, but the walk past it is the `path`'s ({@link deepen}), so two
+ * cells of one container share a key and differ only there: without `path` in the
+ * quad, one message failing two rows draws on the first row alone.
  */
 export declare function mergeDiagnostics(...groups: RoutedDiagnostic[][]): Map<string, Diagnostic[]>;

package/dist/visual/diagnostics.js

@@ -1,4 +1,4 @@
-import { nearestAddrForFieldPath } from '../core/address.js';
+import { nearestAddrForFieldPath, nestedAddrForFieldPath } from '../core/address.js';
 /** Canonical string key for a `FieldKey`: the routing `Map`'s key space. */
 export function fieldKeyToString(k) {
     return `${k.card ?? 'main'}:${k.field ?? '$body'}`;
@@ -42,11 +42,53 @@ export function routeAndResolve(diagnostics, cardIds) {
     }
     return out;
 }
+/** A field's routed diagnostics, each with its steps past the field: none for a
+ *  diagnostic anchored at the field itself, or one whose path is not a nested one
+ *  (a local commit error carries the field's own path). */
+export function deepen(diagnostics) {
+    return (diagnostics ?? []).map((d) => ({
+        steps: (d.path && nestedAddrForFieldPath(d.path)?.steps) || [],
+        diagnostic: d
+    }));
+}
+export function splitDeep(list) {
+    const here = [];
+    const below = new Map();
+    for (const d of list ?? []) {
+        if (d.steps.length === 0) {
+            here.push(d.diagnostic);
+            continue;
+        }
+        const [step, ...rest] = d.steps;
+        const bucket = below.get(step);
+        const next = { steps: rest, diagnostic: d.diagnostic };
+        if (bucket)
+            bucket.push(next);
+        else
+            below.set(step, [next]);
+    }
+    return { here, below };
+}
+/** The diagnostics a rung cannot hand down: the ones anchored here, plus every one
+ *  whose next step names nothing in `held`. Drawn at the rung's own foot, so a leaf the
+ *  tree does not draw still has its message read somewhere the user can see. */
+export function unrouted(split, held) {
+    const out = [...split.here];
+    for (const [step, list] of split.below)
+        if (!held(step))
+            for (const d of list)
+                out.push(d.diagnostic);
+    return out;
+}
 /**
  * Merge N routed groups into `Map<fieldKeyToString(key), Diagnostic[]>`.
- * Dedupes an identical `(severity, message)` pair landing on the same key from
+ * Dedupes an identical `(path, severity, message)` quad landing on the same key from
  * more than one group (e.g. the same error present in both `validate()` and
  * an external feed). Producer order within a key.
+ *
+ * The key is the field, but the walk past it is the `path`'s ({@link deepen}), so two
+ * cells of one container share a key and differ only there: without `path` in the
+ * quad, one message failing two rows draws on the first row alone.
  */
 export function mergeDiagnostics(...groups) {
     const byKey = new Map();
@@ -54,9 +96,14 @@ export function mergeDiagnostics(...groups) {
     for (const group of groups) {
         for (const { key, diagnostic } of group) {
             const k = fieldKeyToString(key);
-            // Collision-proof key: JSON-encode the triple so arbitrary `message` text
-            // can never merge two distinct triples into one (a real diagnostic dropped).
-            const dedupeKey = JSON.stringify([k, diagnostic.severity, diagnostic.message]);
+            // Collision-proof key: JSON-encode the quad so arbitrary `message` text
+            // can never merge two distinct quads into one (a real diagnostic dropped).
+            const dedupeKey = JSON.stringify([
+                k,
+                diagnostic.path ?? null,
+                diagnostic.severity,
+                diagnostic.message
+            ]);
             if (seen.has(dedupeKey))
                 continue;
             seen.add(dedupeKey);

package/dist/visual/hold.js

@@ -2,7 +2,7 @@
 // the layout, and what fills the viewport as a section collapses is that section's own
 // content, whose top never moves.
 import { flushSync } from 'svelte';
-import { rungMs } from './motion.js';
+import { rungMs, rungStyle } from '../core/rungs.js';
 /**
  * Run `change` and keep `anchor` inside the fold for the length of the move.
  *
@@ -26,7 +26,7 @@ export function holdInView(anchor, change) {
     flushSync();
     const reveal = () => anchor.scrollIntoView({ block: 'nearest', behavior: 'instant' });
     reveal();
-    const rung = rungMs(getComputedStyle(anchor), '--_qm-duration-slow');
+    const rung = rungMs(rungStyle(anchor), '--_qm-duration-slow');
     if (rung === undefined)
         return;
     const until = performance.now() + rung;

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

@@ -116,6 +116,9 @@ export declare const ICONS: {
     readonly minus: readonly [readonly ["path", {
         readonly d: "M5 12h14";
     }]];
+    readonly check: readonly [readonly ["path", {
+        readonly d: "M20 6 9 17l-5-5";
+    }]];
 };
 /** The closed set. A name that is not here is a compile error at the call site,
  *  which is what a string key buys over thirteen imported components. */

package/dist/visual/icons/nodes.js

@@ -63,5 +63,6 @@ export const ICONS = {
         ['path', { d: 'M3 6h18' }],
         ['path', { d: 'M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2' }]
     ],
-    minus: [['path', { d: 'M5 12h14' }]]
+    minus: [['path', { d: 'M5 12h14' }]],
+    check: [['path', { d: 'M20 6 9 17l-5-5' }]]
 };

package/dist/visual/leaves.d.ts

@@ -1,4 +1,12 @@
+import type { PathStep } from '@quillmark/wasm';
 import type { FieldController } from '../core/codec/index.js';
+/**
+ * What a landing at depth hands back: the box the arrival wash blooms in, now or once
+ * the row it had to open has rendered. A row two closed boxes down does not exist
+ * until the row above it opens and flushes, so the innermost box is a promise wherever
+ * the walk had to open something on the way.
+ */
+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}).
@@ -10,22 +18,27 @@ import type { FieldController } from '../core/codec/index.js';
 export interface FieldControl {
     focus(): void;
     /**
-     * Land in element `index` of a control that has elements, at USV `pos` where the
-     * row's control can take one; resolving the index to the element's session id at
-     * the call, with {@link focus}'s own answer for an index past the live list. Absent
-     * on every control without elements.
+     * Land at `steps` inside a control that has an inside — an array's element, an
+     * object's property, a variant's cell, a matrix's member, and any of them under any
+     * other — at USV `pos` where the leaf the walk ends in can take one. Each rung
+     * resolves its own step at the call (an index to a session id, a key to a mounted
+     * cell) and hands the rest to the control it opened, so nothing positional is
+     * carried. A step the tree does not hold falls back to that rung's own
+     * {@link focus}: the field is right and the row is gone. Absent on every control
+     * with no inside.
      *
      * A landing, not a focus: an absent `pos` is the placement rung, exactly as on
-     * `Landing`, and what a `pos` means is the row control's, the same way focusing is.
-     * The place rides the call because the registry stays parent-keyed: a per-element
-     * key is positional, in a registry whose doctrine is dodging positional churn.
+     * `Landing`, and what a `pos` means is the leaf's, the same way focusing is. The
+     * place rides the call because the registry stays parent-keyed: a per-element key is
+     * positional, in a registry whose doctrine is dodging positional churn.
      *
-     * Returns the element's own box, which is what the wash blooms in: the address
-     * named one row, and a wash over the whole repeater says the field where the click
-     * said the row. `undefined` is the fallback the index past the live list took, and
-     * reads as {@link el}.
+     * Returns the innermost row the address named, which is what the wash blooms in: a
+     * box wider than the one the click resolved says the field where the pick said the
+     * row. `undefined` is a landing that named no row — a property under a field-level
+     * subform, or the fallback an index past the live list took — and reads as
+     * {@link el}.
      */
-    focusElement?(index: number, pos?: number): HTMLElement | undefined;
+    focusPath?(steps: readonly PathStep[], pos?: number): LandingBox;
     readonly el: HTMLElement;
 }
 /**

package/dist/visual/motion.d.ts

@@ -3,11 +3,20 @@ import type { AnimationConfig } from 'svelte/animate';
  *  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. */
 export declare function reorderTrips(node: HTMLElement): Animation[];
-/** A duration rung off `style`, in ms; `undefined` where the derivation is out of reach
- *  (an unstyled root, or jsdom, where `getComputedStyle` reports custom properties as
- *  empty). No rung, no motion: a fallback here would be the scale restated in the one
- *  place `check:style` cannot read. */
-export declare function rungMs(style: CSSStyleDeclaration, rung: string): number | undefined;
+/**
+ * The reorder gesture's arming window, for a keyed list that takes the trip. The
+ * reconcile that moves a slot is the trip, and every other reconcile that happens to
+ * move one is not; so the command arms the gesture and the frame it lands in disarms
+ * it, `animate:` asking at apply time, a microtask after the mutation and well inside
+ * that frame. `armed` is a getter rather than a value, so the flag stays out of the
+ * template and needs no reactivity for it. `cancel` is for the surface's teardown.
+ */
+export interface ReorderArm {
+    arm(): void;
+    armed(): boolean;
+    cancel(): void;
+}
+export declare function reorderArm(): ReorderArm;
 /**
  * Slide a keyed slot from where it was to where it now is.
  *