@quillmark/svelte 0.1.1 → 0.3.0

package/dist/visual/VisualEditorInner.svelte

@@ -1,8 +1,8 @@
 <!--
- The federated WYSIWYG surface (VISUAL_EDITOR). A THIN composition over many
- small editors; NOT one PM document spanning the page.
+ The federated WYSIWYG surface (VISUAL_EDITOR). A thin composition over many
+ small editors; not one PM document spanning the page.
 
- MOUNTED ONCE PER DOCUMENT. `VisualEditor` keys this component on `doc`, so
+ Mounted once per document. `VisualEditor` keys this component on `doc`, so
  everything below seeds from a handle that cannot change under it: `cardIds`, the
  id `seq`, the leaf registry, the commit-error map, the active address and the
  card refs are all mount-scoped, and the prose leaves close over the `doc` they
@@ -12,21 +12,21 @@
  It owns:
  • structure: the schema × payload join, re-derived from the live `Document`;
  • stable card identity: a session-id array reordered in lockstep with the
- content, resolved to an index ONLY at the mutation boundary;
+ content, resolved to an index only at the mutation boundary;
  • commit routing: prose leaves lower to `applyChange` (in the codec); scalars/
  arrays/objects go through the typed `writer`; structure through the mutators;
  • focus + the bridge outputs (`onActiveLeafChange`, `onCaretMove`) and the
- `setCaret(hit)` entry wired to the preview;
- • the ONE formatting popover (`FormatPopover`, mounted once, observing the
+ `setCaret(at)` entry wired to the preview;
+ • the one formatting popover (`FormatPopover`, mounted once, observing the
  active leaf via `getActiveLeaf`) and diagnostics routing (`diagnostics.ts`:
  quill.validate + local commit errors + the external `diagnostics` prop,
  merged into `diagByKey` and threaded to each `<Field>`/card body).
 
- REACTIVITY ACROSS THE WASM HANDLE. The `Document` is opaque to Svelte, so a
+ Reactivity across the WASM handle. The `Document` is opaque to Svelte, so a
  `revision` counter is bumped after every scalar/structure mutation and the card
- tree is `$derived` by RE-READING `doc.main`/`doc.cards`/`quill.schema`. Prose
- leaves are mounted ONCE per stable leaf key (keyed `<Card>`/`<ProseField>`);
- they commit to the doc directly and do NOT bump `revision`, so a re-derive never
+ tree is `$derived` by re-reading `doc.main`/`doc.cards`/`quill.schema`. Prose
+ leaves are mounted once per stable leaf key (keyed `<Card>`/`<ProseField>`);
+ they commit to the doc directly and do not bump `revision`, so a re-derive never
  remounts them or drops a caret. `doc.main`/`doc.cards` allocate per read: read
  once per derive.
 -->
@@ -34,24 +34,25 @@
 	import { onDestroy, tick } from 'svelte';
 	import { DropdownMenu } from 'bits-ui';
 	import { isQuillmarkError, MAIN_CARD_ADDR } from '@quillmark/wasm';
-	import { cardPath, fieldPathForAddr, type DocPath } from '../core/address.js';
+	import {
+		addrForFieldPath,
+		cardPath,
+		elementAddrForFieldPath,
+		fieldPathForAddr,
+		type DocPath,
+		type Landing
+	} from '../core/address.js';
 	import { errorMessage, reportError } from '../core/errors.js';
 	import { bloomInside } from '../core/bloom.js';
 	import { createLifespan } from '../core/teardown.js';
-	import type {
-		Addr,
-		CardAddr,
-		ContentHit,
-		Diagnostic,
-		Resolved,
-		ResolvedField
-	} from '@quillmark/wasm';
+	import type { Addr, CardAddr, Diagnostic, Resolved, ResolvedField } from '@quillmark/wasm';
 	import type { VisualEditorProps } from './props.js';
 	import { mergeStrings, setWording } from './strings.js';
 	import type { CardId, ChangeSource } from './signals.js';
 	import type { FieldController } from '../core/codec/index.js';
 	import {
 		IdSeq,
+		controlKind,
 		fieldModels,
 		groupOrder,
 		groupSections,
@@ -65,13 +66,11 @@
 		stringifyGhost,
 		resolveBodyGhost,
 		NO_RESOLVED_ROWS,
-		type BodyPlaceholder,
 		type CardModel,
 		type ResolvedCardRows
 	} from './structure.js';
 	import {
 		fieldKeyToString,
-		parsePath,
 		resolveCardKey,
 		routeAndResolve,
 		mergeDiagnostics,
@@ -79,6 +78,7 @@
 		type RoutedDiagnostic
 	} from './diagnostics.js';
 	import { fieldDomIds, groupPanelId } from './domid.js';
+	import { createLeafRegistry, type FieldControl } from './leaves.js';
 	import { reorder } from './motion.js';
 	import { tipsChannel } from './tips.js';
 	import { patchEditorExt } from './ext.js';
@@ -98,6 +98,7 @@
 		onError,
 		diagnostics,
 		enumOptionAllowed,
+		enumDisallowed = 'disable',
 		strings,
 		formatDiagnostic,
 		class: className,
@@ -120,7 +121,7 @@
 	// ── Reactivity + session identity ───────────────────────────────────────────
 	let revision = $state(0);
 	// This editor's own id, prefixed onto every field's DOM ids (`domid.ts`). The
-	// leaf-key space is unique per EDITOR, not per page: two editors mounted
+	// leaf-key space is unique per editor, not per page: two editors mounted
 	// side-by-side both hold `main:subject`, and a duplicate `id` makes `for` resolve
 	// to whichever mounted first. `$props.id()` is stable across SSR and hydration,
 	// which a module counter is not.
@@ -148,13 +149,13 @@
 	/**
 	 * Re-derive the card tree and report the edit. Called for the two lanes that go
 	 * through this component; a prose leaf commits itself and reports through
-	 * `proseChanged`, which does NOT bump the revision (bumping it would re-derive
+	 * `proseChanged`, which does not bump the revision (bumping it would re-derive
 	 * and remount every leaf, costing the caret on every keystroke).
 	 *
 	 * `cardId` is passed rather than derived from `at`: the sites below hold the id
 	 * already, and the removal has no address to derive one from. `at` is an `Addr` for
-	 * a leaf and a CARD INDEX for a structure op, whose subject is the card rather than
-	 * anything inside it; either way the path is minted HERE, after the bump, because
+	 * a leaf and a card index for a structure op, whose subject is the card rather than
+	 * anything inside it; either way the path is minted here, after the bump, because
 	 * an op's own index is only addressable against the tree the bump re-derived (an
 	 * insert's card does not exist in the previous one, and a retype's kind is the
 	 * previous kind).
@@ -179,7 +180,7 @@
 	}
 
 	// ── Teardown (core/teardown.ts: unregister, cancel, then free) ──────────────
-	// A document swap is a REMOUNT (see the remount contract above), so a destroy is
+	// A document swap is a remount (see the remount contract above), so a destroy is
 	// the only way this surface ends and one span covers both. Cancellers register
 	// below in the order they run: the registry that resolves new work first, then
 	// the work already scheduled. The document handle is the consumer's to free, so
@@ -187,8 +188,11 @@
 	const span = createLifespan();
 	onDestroy(() => span.end());
 
-	// ── Leaf registry (setCaret target lookup + the active-leaf seam) ───────────
-	const leaves = new Map<string, FieldController>();
+	// ── Leaf registry (landing target lookup + the active-leaf seam) ────────────
+	// Every mounted field is in it, prose leaf and form control alike (`leaves.ts`):
+	// a landing needs a focus and a box to bloom, which every control has, and the
+	// codec lane is asked for only where there is an offset to place.
+	const leaves = createLeafRegistry();
 	// Each leaf unregisters itself on its own teardown; this covers the surface
 	// going away as a whole, where a leaf's cleanup order relative to the parent's
 	// is Svelte's business and not something to depend on.
@@ -202,14 +206,8 @@
 	let mainCard = $state<CardHandle | undefined>(undefined);
 	let cardRefs = $state<(CardHandle | undefined)[]>([]);
 	/** The stack's own element: it carries `data-qm-root`, so it is what the kind
-	 * menu portals INTO, the way each leaf's surface resolves its nearest root. */
+	 * menu portals into, the way each leaf's surface resolves its nearest root. */
 	let rootEl = $state<HTMLElement | undefined>(undefined);
-	function register(key: string, controller: FieldController): void {
-		leaves.set(key, controller);
-	}
-	function unregister(key: string): void {
-		leaves.delete(key);
-	}
 
 	// ── Focus + bridge outputs ──────────────────────────────────────────────────
 	// `activeCardId` is the id-keyed half of `activeAddr` (whose `card` is positional),
@@ -235,7 +233,7 @@
 	 *  common case allocates nothing. */
 	const NO_KINDS: readonly string[] = [];
 	/**
-	 * The live kinds by content index, off the DERIVED card tree rather than
+	 * The live kinds by content index, off the derived card tree rather than
 	 * `doc.cards`: they are already in hand, and `doc.cards` serializes every card on
 	 * each read, which is not a thing to do per keystroke.
 	 */
@@ -249,13 +247,13 @@
 	function pathFor(addr: Addr): DocPath | undefined {
 		return fieldPathForAddr(addr, addr.card == null ? NO_KINDS : liveKinds());
 	}
-	// The last PLACE reported, so a caret that did not move is not news. A leaf fires
+	// 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
 	// caret to exist: a mark toggle over the same range, an anchor op, a plugin's own
 	// bookkeeping. The memo is the editor's rather than each leaf's, because a place
 	// spans leaves: a caret that leaves `main.body` at 5 for a card leaf and comes
 	// back to 5 made two moves, and a per-leaf memo would swallow the second. An edit
-	// that reflows the page UNDER a caret holding its offset is the case this drops,
+	// that reflows the page under a caret holding its offset is the case this drops,
 	// and a preview does not need the signal to answer it: the place is unchanged, so
 	// the one it already followed is the one its recompile re-locates.
 	let lastCaretField: DocPath | undefined;
@@ -277,18 +275,18 @@
 
 	// ── Commit routing ──────────────────────────────────────────────────────────
 	// Scalars / arrays / objects → the typed writer (schema-checked). Prose leaves
-	// commit themselves via the codec (applyChange) and do NOT pass through here.
+	// commit themselves via the codec (applyChange) and do not pass through here.
 	// A scalar control commits `undefined` for a cleared entry: the unset lane
 	// below (`doc.removeField`), not a write.
 	//
-	// A bad value makes `writer.set` THROW a `QuillmarkError`, whose
+	// A bad value makes `writer.set` throw a `QuillmarkError`, whose
 	// `diagnostics[0]` carries a `code` and a canonical `path` (e.g.
 	// `edit::field_coercion_failed` at `main.font_size`, or `edit::unknown_field`). The
-	// editor already KNOWS the field/card being committed, so it KEYS the entry
-	// from THAT address: id-keyed so it survives a later card reorder, never
+	// editor already knows the field/card being committed, so it keys the entry
+	// from that address: id-keyed so it survives a later card reorder, never
 	// parsed from the positional path; while surfacing the thrown diagnostic
 	// verbatim (its `code`/`message`) as the payload (VISUAL_EDITOR §Diagnostics,
-	// producer #2). It is stashed in `commitErrors`; a subsequent SUCCESSFUL commit
+	// producer #2). It is stashed in `commitErrors`; a subsequent successful commit
 	// for the same field clears it. Nothing here gates: the value is not written
 	// (the document is unchanged on throw, per the boundary's own transactional
 	// contract) and editing continues.
@@ -297,14 +295,14 @@
 		const keyStr = fieldKeyToString(key);
 		try {
 			if (value === undefined) {
-				// The UNSET rung of the commitment ladder (a cleared scalar control,
-				// VISUAL_EDITOR §"Structure mirrors the schema"): REMOVE the field so the
+				// The unset rung of the commitment ladder (a cleared scalar control,
+				// VISUAL_EDITOR §"Structure mirrors the schema"): remove the field so the
 				// engine's authored › `default:` › zero-fill resolve renders the
 				// default, rather than baking a snapshot the schema can't track
 				// (canon SCHEMAS.md: the engine never persists a default; nor do we).
 				// Removal writes no value, so there is nothing for a schema to conform:
 				// it goes through the quill-free `doc.removeField` (bare string = main
-				// `{ field }`; `{ card, field }` for a card), NOT the typed writer.
+				// `{ field }`; `{ card, field }` for a card), not the typed writer.
 				if (isMain) {
 					doc.removeField(name);
 				} else {
@@ -437,7 +435,7 @@
 			});
 		// No addr: the removed card has no address left, and the surviving cards'
 		// addresses all shifted. The stack changed, not a leaf. The id still names
-		// WHICH card went, which is the one thing a host keying on it needs, and the
+		// which card went, which is the one thing a host keying on it needs, and the
 		// only handle the removal leaves it.
 		bump('structure', id);
 	}
@@ -463,7 +461,7 @@
 		bump('structure', id, i);
 	}
 	/**
-	 * Clear the tips channel: the dismissal write, and the ONLY write
+	 * Clear the tips channel: the dismissal write, and the only write
 	 * tips make. `undefined` drops the key while `title` and any later sibling ride
 	 * through; `ext.ts` holds why that matters.
 	 */
@@ -476,7 +474,7 @@
 	}
 
 	// ── Addressing + per-card op bundle ─────────────────────────────────────────
-	/** A LIVE card address: `card` is a getter, so a reorder re-targets in place. */
+	/** A live card address: `card` is a getter, so a reorder re-targets in place. */
 	function cardAddr(id: string, field?: string): Addr {
 		return field != null
 			? ({
@@ -497,9 +495,7 @@
 	}
 
 	// ── Diagnostics routing (VISUAL_EDITOR §Diagnostics) ────────────────────────
-	// Producer #1: quill.validate(doc), re-run every revision (empirically always
-	// `[]` for usaf_memo (no field in the fixture carries a `!must_fill` marker)
-	// but the routing exists for the general contract, not just this fixture).
+	// Producer #1: quill.validate(doc), re-run every revision.
 	const validation = $derived.by(() => {
 		revision; // re-run on every mutation, per VISUAL_EDITOR §Diagnostics
 		try {
@@ -526,7 +522,7 @@
 		return mergeDiagnostics(fromValidate, fromExternal, [...commitErrors.values()]);
 	});
 	function opsFor(id: string, isMain: boolean) {
-		// ONE identity per field: the leaf registry, the DOM's three names, and the
+		// One identity per field: the leaf registry, the DOM's three names, and the
 		// diagnostics map all key off this string, so a leaf, its label and its
 		// diagnostics can only ever resolve together.
 		const leafKey = (field?: string) => fieldKeyToString({ card: isMain ? undefined : id, field });
@@ -548,33 +544,6 @@
 		};
 	}
 
-	// ── The empty-body ghost's consumer wording ─────────────────────────────────
-	// The hook is consulted once per KIND and its answer kept for the session, which
-	// is the whole determinism guarantee: a hook that samples a witty set at random
-	// is impure by design, and this cache is what makes its answer look chosen:
-	// same string for every card of a kind, and the same one after a remount or any
-	// re-derive. Keyed by kind rather than by card id deliberately: two empty cards
-	// that are the same kind ARE the same invitation, and disagreeing ghosts read as
-	// a glitch. Retyping a card crosses to another key and re-asks, which is right:
-	// it is a different card now. Plain (non-`$state`) on purpose: memoization, so
-	// filling it during a derive must not feed back into one.
-	let ghostHook: BodyPlaceholder | undefined;
-	const ghostByKind = new Map<string, string | undefined>();
-	function customBodyGhost(kind: string, isMain: boolean): string | undefined {
-		const bodyPlaceholder = merged.bodyPlaceholder;
-		// A swapped hook invalidates every answer the old one gave.
-		if (bodyPlaceholder !== ghostHook) {
-			ghostByKind.clear();
-			ghostHook = bodyPlaceholder;
-		}
-		if (!bodyPlaceholder) return undefined;
-		// `main` is not a `card_kinds` key, so a kind that spells it collides without
-		// the flag in the key.
-		const key = `${isMain ? '1' : '0'}\0${kind}`;
-		if (!ghostByKind.has(key)) ghostByKind.set(key, bodyPlaceholder({ kind, isMain }));
-		return ghostByKind.get(key);
-	}
-
 	// ── The derived card tree (schema × payload join) ───────────────────────────
 	function buildCard(
 		id: string,
@@ -613,12 +582,14 @@
 			// same text-ghost projection `<Field>` applies to a field's row; and falls
 			// back to an invitation where a scalar shows nothing, because an empty body
 			// is a surface to write on and an empty control is a value not yet given.
-			// Asked only for a card that HAS a body, so the hook is never consulted
-			// about one that renders none.
+			// Asked only for a card that has a body, so the hook is never consulted
+			// about one that renders none. The hook is pure by contract, so it is called
+			// straight from the derive and its answer kept nowhere: a ghost holds still
+			// across a re-derive because the function does.
 			bodyGhost: hasBody
 				? resolveBodyGhost(
 						stringifyGhost(ghostDefault(rows.body ?? undefined)),
-						customBodyGhost(kind, isMain),
+						merged.bodyPlaceholder?.({ cardId: id, kind, isMain }),
 						merged.bodyGhost
 					)
 				: undefined
@@ -670,64 +641,93 @@
 
 	// ── Public entry points ─────────────────────────────────────────────────────
 	/**
-	 * Resolve a preview `ContentHit` to a mounted leaf and place its caret.
+	 * Resolve a preview {@link Landing} to a mounted leaf and land in it.
 	 *
-	 * Async because the reveal has to RENDER before the landing: a collapsed group
+	 * Async because the reveal has to render before the landing: a collapsed group
 	 * is `inert`, which swallows a focus silently, so a caret placed in the same
 	 * tick as the reveal would go nowhere and report nothing. The consumer's
-	 * `onCaretPick` ignores the promise: awaiting it is for a caller that wants to
+	 * `onPick` ignores the promise: awaiting it is for a caller that wants to
 	 * observe where the caret went.
 	 *
-	 * A destroy lands INSIDE this one: `leaf` is looked up before the flush and
+	 * A destroy lands inside this one: `leaf` is looked up before the flush and
 	 * dispatched into after it, and a PM view destroyed in that window throws on the
-	 * dispatch. A consumer's `onCaretPick` outlives the surface it points at too, so
-	 * the span is asked on the way in as well as after the await.
+	 * dispatch. A consumer's `onPick` outlives the surface it points at too, so the
+	 * span is asked on the way in as well as after the await.
 	 */
-	export async function setCaret(hit: ContentHit): Promise<void> {
-		const leaf = await revealLeaf(hit.field);
-		if (!leaf) return;
+	export async function setCaret(at: Landing): Promise<void> {
+		const found = await revealLeaf(at.field);
+		if (!found) return missed(`no mounted field at ${at.field}`, at.field);
 		// A `'segment'` hit landed on origin-less ink (list markers, a code fence's
-		// interior): `pos` is the segment START, not a cluster-exact caret
-		// (HitGranularity), so just focus the leaf rather than snap the caret to a
-		// spot the click did not resolve. `'cluster'` (and an absent granularity:
-		// the backend did not report it, treat as exact) places the caret.
-		if (hit.granularity === 'segment') leaf.focus();
-		else leaf.setCaret(hit.pos);
+		// interior): `pos` is the segment start, not a cluster-exact caret
+		// (HitGranularity), so it is dropped rather than snapped to a spot the click
+		// did not resolve. `'cluster'` (and an absent granularity: the backend did not
+		// report it, treat as exact) places the caret. An absent `pos` is the placement
+		// rung and reaches the same floor.
+		land(found, at.granularity === 'segment' ? undefined : at.pos);
 		// The arrival cue. Unconditional, unlike the preview side's change-guarded
 		// bloom: a preview click is one discrete act, and its commonest target is the
-		// leaf ALREADY focused (where landing a caret changes nothing on screen) or
+		// 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 in a long form.
-		bloomInside(leaf.el);
+		bloomInside(found.control.el);
 	}
-	/** The active leaf's controller: the formatting popover's observation seam. */
+	/** The active leaf's controller: the formatting popover's observation seam.
+	 *  `undefined` for a focused form control, which holds no marks to toggle. */
 	export function getActiveLeaf(): FieldController | undefined {
 		if (!activeAddr) return undefined;
 		const card = activeAddr.card != null ? activeCardId : undefined;
-		return leaves.get(fieldKeyToString({ card, field: activeAddr.field }));
+		return leaves.prose(fieldKeyToString({ card, field: activeAddr.field }));
 	}
 
 	/**
-	 * Reveal the leaf at `field` and hand back its controller, once the reveal has
-	 * RENDERED. The shared half of the two landing verbs: a collapsed group is clipped
-	 * to zero height and sits inside an `inert` panel, which swallows a focus silently,
-	 * so a caret placed in the same tick as the reveal goes nowhere and reports
-	 * nothing. Exactly one card holds the key; the rest do nothing.
+	 * Reveal the field at `field` and hand back its landing handle plus the target it
+	 * resolved to, once the reveal has rendered. The shared half of the two landing
+	 * verbs: a collapsed group is clipped to zero height and sits inside an `inert`
+	 * panel, which swallows a focus silently, so a caret placed in the same tick as the
+	 * reveal goes nowhere and reports nothing. Exactly one card holds the key; the rest
+	 * do nothing.
+	 *
+	 * The target comes back with the handle because the caller needs its key to ask for
+	 * the codec lane (`leaves.prose`), and minting it twice would be two parses of one
+	 * path. The reveal itself is the key's: a group holds the field, and an element
+	 * address opens the same group its array sits in.
 	 *
-	 * A destroy lands INSIDE this: the leaf is looked up before the flush and
+	 * A destroy lands inside this: the field is looked up before the flush and
 	 * dispatched into after it, and a PM view destroyed in that window throws on the
 	 * dispatch. A consumer's call outlives the surface it points at too, so the span is
 	 * asked on the way in as well as after the await.
 	 */
-	async function revealLeaf(field: DocPath): Promise<FieldController | undefined> {
+	async function revealLeaf(field: DocPath): Promise<Landed | undefined> {
 		if (!span.alive) return undefined;
-		const key = leafKeyForHit(field);
-		const leaf = key == null ? undefined : leaves.get(key);
-		if (!leaf) return undefined;
-		mainCard?.revealLeaf(key!);
-		for (const card of cardRefs) card?.revealLeaf(key!);
+		const target = leafTargetFor(field);
+		const control = target && leaves.control(target.key);
+		if (!target || !control) return undefined;
+		mainCard?.revealLeaf(target.key);
+		for (const card of cardRefs) card?.revealLeaf(target.key);
 		if (!(await span.resumes(tick()))) return undefined;
-		return leaf;
+		return { ...target, control };
+	}
+
+	/**
+	 * Put the caret in a revealed target, at the finest grain it can take.
+	 *
+	 * - An element address focuses that row, with no caret inside it: an array element
+	 *   is no `createField` leaf and its handle is a bare focus.
+	 * - A prose leaf with a `pos` takes the caret at that USV offset.
+	 * - Everything else takes the focus alone: the offset is a position in rendered
+	 *   content and a form control has no coordinate to spend it in (an
+	 *   `<input type="number">` refuses a selection outright), which is also the whole
+	 *   of what a click on plate-placed ink can mean.
+	 */
+	function land(found: Landed, pos: number | undefined): void {
+		if (found.element != null && found.control.focusElement) {
+			return found.control.focusElement(found.element);
+		}
+		if (pos != null) {
+			const prose = leaves.prose(found.key);
+			if (prose) return prose.setCaret(pos);
+		}
+		found.control.focus();
 	}
 
 	// ── The verbs, as instance exports ──────────────────────────────────────────
@@ -737,16 +737,25 @@
 	// They speak the public vocabulary — a `DocPath` for a place, a `CardId` for a
 	// card — so a host drives them with what the hooks handed it.
 	//
-	// A target the surface does not hold is a NO-OP that reports `target-unknown` at
-	// `dev`: the chrome cannot mint a bad one, so it only ever fires on a host holding
-	// a key from a previous session or a card already removed.
+	// A target the surface does not hold is a no-op that reports `target-unknown` at
+	// `dev`: a key from a previous session or a card already removed, or a path naming
+	// no declared field — an element path (`main.references.0`) whose array is
+	// undeclared or unmounted included, that being the only way one misses. `setCaret`
+	// reports it too, being the verb a preview click drives: a landing that resolved
+	// nothing is indistinguishable from one that landed, and a consumer wiring the
+	// bridge reads the difference off nothing else.
 
-	/** Reveal and focus the leaf at `field`, without placing a caret inside it. */
+	/**
+	 * Reveal and focus the field at `field`, without placing a caret inside it. Any
+	 * mounted field: a prose leaf takes its view's focus, a form control takes the same
+	 * handoff a click on its label does (`Field`, `leaves.ts`), and an element address
+	 * takes its own row.
+	 */
 	export async function focusField(field: DocPath): Promise<void> {
-		const leaf = await revealLeaf(field);
-		if (!leaf) return missed(`no mounted leaf at ${field}`, field);
-		leaf.focus();
-		bloomInside(leaf.el);
+		const found = await revealLeaf(field);
+		if (!found) return missed(`no mounted field at ${field}`, field);
+		land(found, undefined);
+		bloomInside(found.control.el);
 	}
 	/** 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. */
@@ -777,19 +786,56 @@
 		reportError(onError, { code: 'target-unknown', severity: 'dev', message, path });
 	}
 
-	/** Map a `ContentHit.field` (a canonical `DocPath`) to a mounted leaf key: the
-	 * same `addrForFieldPath` route the diagnostics take, the absolute card index
-	 * resolved to its live stable id, then the shared `fieldKeyToString` form. */
-	function leafKeyForHit(field: string): string | undefined {
-		const key = parsePath(field);
-		if (!key) return undefined;
-		const resolved = resolveCardKey(key, cardIds);
-		return resolved ? fieldKeyToString(resolved) : undefined;
+	/** What a `DocPath` resolves to in the mounted tree: a leaf key, and the array
+	 *  element within it when the address names one. */
+	interface LeafTarget {
+		key: string;
+		element?: number;
+	}
+	/** A resolved target with the handle the registry holds for it. */
+	type Landed = LeafTarget & { control: FieldControl };
+
+	/**
+	 * Map a landing's `field` (a canonical `DocPath`) to a mounted target: the
+	 * `addrForFieldPath` route the diagnostics take, the absolute card index resolved
+	 * to its live stable id, then the shared `fieldKeyToString` form.
+	 *
+	 * Two rungs, because the boundary mints addresses at a finer granularity than
+	 * `Addr` can name: a `richtext[]` element surfaces as `main.references.0`, which
+	 * the grammar reads as a field literally named `"0"`. The second rung reads that
+	 * trailing segment as an index, 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.
+	 */
+	function leafTargetFor(field: DocPath): LeafTarget | undefined {
+		const direct = addrForFieldPath(field);
+		if (direct) {
+			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;
+	}
+
+	/** Whether `addr` names a field this document renders as an array repeater: 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;
+		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';
 	}
 </script>
 
 <div class="qm-editor {className ?? ''}" {style} data-qm-root bind:this={rootEl}>
-	<!-- `main` and the tips card are ONE block in the stack: the tips card tucks under
+	<!-- `main` and the tips card are one block in the stack: the tips card tucks under
 	 `main`'s bottom corners, so the two share a seam rather than a gutter and the
 	 wrapper is what holds them to it. -->
 	<div class="qm-primary">
@@ -803,12 +849,12 @@
 			isLast={true}
 			{kinds}
 			ops={opsFor('main', true)}
+			{enumDisallowed}
 			onFocus={handleFocus}
 			onCaretMove={handleCaret}
 			onChange={proseChanged}
 			{onError}
-			{register}
-			{unregister}
+			{leaves}
 		/>
 
 		<!-- The tips card: a fixed slot after `main`, ahead of the cards, so
@@ -821,7 +867,7 @@
 	</div>
 
 	{@render addAffordance(0)}
-	<!-- A card and the gap under it are one SLOT, which is what a reorder moves: the
+	<!-- A card and the gap under it are one slot, which is what a reorder moves: the
 	 strip below a card is the same strip wherever the card lands, so it rides along
 	 rather than being slid across. It is also the shape `animate:` asks for, being the
 	 keyed block's only child. -->
@@ -837,12 +883,12 @@
 				isLast={i === model.cards.length - 1}
 				{kinds}
 				ops={opsFor(c.id, false)}
+				{enumDisallowed}
 				onFocus={handleFocus}
 				onCaretMove={handleCaret}
 				onChange={proseChanged}
 				{onError}
-				{register}
-				{unregister}
+				{leaves}
 			/>
 			{@render addAffordance(i + 1)}
 		</div>
@@ -851,47 +897,46 @@
 
 <FormatPopover {getActiveLeaf} />
 
-<!-- Cards always render; the ADD affordance is gated on the schema declaring
+<!-- Cards always render; the add affordance is gated on the schema declaring
  `card_kinds`, since there is nothing to seed otherwise. A card already in the
  document shows regardless of its kind: a kind with no schema (foreign, or a
  schema with no `card_kinds` at all) degrades to a recovery shell inside <Card>
  (retype + delete), never gated away, so its content is neither dropped nor
- trapped. The gate lives HERE rather than at each call site: the strip is one
+ trapped. The gate lives here rather than at each call site: the strip is one
  decision, and two copies of it drift into a stack with a gap at one end. -->
 {#snippet addAffordance(atIndex: number)}
 	{#if kinds.length}
-		<!-- The strip past the last card is the APPEND point, the one a reader looks for
+		<!-- 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
+		 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. -->
 		{@const marked = atIndex === model.cards.length}
 		<div class="qm-add-card" class:qm-add-card-marked={marked}>
-			<!-- Marked, the words ARE the accessible name and no `aria-label` doubles
-			 them; bare, the kind is the whole reading, the one with no geometry to
-			 carry it. -->
+			<!-- Marked, the words are the accessible name and no `aria-label` doubles
+			 them; bare, the same words land as the label, the strip having no
+			 geometry to carry them. -->
 			{#if kinds.length === 1}
 				<button
 					type="button"
-					class="qm-add-btn qm-add-affordance"
-					aria-label={marked ? undefined : merged.addCardOfKind(humanize(kinds[0]))}
-					onclick={() => addCard(atIndex, kinds[0])}
-					>{marked ? merged.addCardMark(humanize(kinds[0])) : ''}</button
+					class="qm-add-btn qm-add-affordance qm-tap-floor"
+					aria-label={marked ? undefined : merged.addCard}
+					onclick={() => addCard(atIndex, kinds[0])}>{marked ? merged.addCard : ''}</button
 				>
 			{:else}
-				<!-- Multi-kind add: pick the kind, then seed + insert. A MENU rather than a
+				<!-- Multi-kind add: pick the kind, then seed + insert. A menu rather than a
 			 disclosure: it floats out of the stack, so raising it moves no card, and
 			 it dismisses on pick, on Escape and on a click outside, none of which a
 			 `<details>` does. The trigger is bits-ui's `<button>`, which is why the
 			 rules below reach it through `:global`. -->
 				<DropdownMenu.Root>
 					<DropdownMenu.Trigger
-						class="qm-add-btn qm-add-affordance"
+						class="qm-add-btn qm-add-affordance qm-tap-floor"
 						aria-label={marked ? undefined : merged.addCard}
-						>{marked ? merged.addCardMarkAny : ''}</DropdownMenu.Trigger
+						>{marked ? merged.addCard : ''}</DropdownMenu.Trigger
 					>
 					<DropdownMenu.Portal to={rootEl}>
 						<DropdownMenu.Content sideOffset={4}>
-							<!-- Portalled out of the row but INTO the stack's root, and carrying the
+							<!-- 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. -->
 							<div class="qm-menu-surface" data-qm-root>
@@ -911,33 +956,40 @@
 
 <style>
 	/* The private scale lands via `data-qm-root` on the root element above: this is
-	 a DETACHED root, one of those core/theme.css applies the derivation to. The
+	 a detached root, one of those core/theme.css applies the derivation to. The
 	 root rule also carries the baseline font and colour, so nothing here restates
 	 them. Nothing here mints; `check:style` enforces that. */
-	/* The COLUMN, not only the cards in it: the gutter the stack sits in and the tone
+	/* The column, not only the cards in it: the gutter the stack sits in and the tone
 	   behind it are the surface's own, so a bare `<div>` is a mounting site and
 	   nothing is owed before the editor looks right. Consumer CSS is unlayered and
 	   beats all of it, which is how a host that wants the column back takes it.
-	   `border-box`, so a height from the caller is the height this draws. */
+	   `border-box`, so a height from the caller is the height this draws.
+
+	   The sunken rung, which is what makes a card an island: the cards are the base
+	   plane and this is the one they float on, so the gutter reads as ground rather
+	   than as more card (ARCHITECTURE §Styling). The inset is the widest rung on the
+	   ramp, which is what gives the ground enough of itself to read as ground: at a
+	   narrower one the stack meets whatever frames the surface and the islands are
+	   back to being one block clipped at its edges. */
 	.qm-editor {
 		box-sizing: border-box;
 		display: flex;
 		flex-direction: column;
 		gap: var(--_qm-space-2);
-		padding: var(--_qm-space-2);
-		background: var(--_qm-surface);
+		padding: var(--_qm-space-4);
+		background: var(--_qm-surface-sunken);
 		color: var(--_qm-ink);
 	}
-	/* A fixed-height pane, which the stack is NOT by default, and the four popovers
+	/* A fixed-height pane, which the stack is not by default, and the four popovers
 	   are the reason: each resolves its portal target with
 	   `closest('[data-qm-root]')`, which is this element, so an `overflow` here
 	   clips the menu a leaf raised. Mounted in a page that scrolls, nothing clips;
 	   mounted in a pane that does, the host says so and takes the clipping it would
-	   have had from its own scrolling frame either way. The TAIL rides with the
+	   have had from its own scrolling frame either way. The tail rides with the
 	   scroller because it is only meaningful under one: dead space below the last
 	   card, so it can be read mid-pane rather than against the bottom edge.
 
-	   The HEIGHT is what makes the rest of the rule mean anything, and it is the
+	   The height is what makes the rest of the rule mean anything, and it is the
 	   pane's rather than a number of ours: `overflow` on a box that grows to its
 	   content never has anything to scroll, so the stack would run past the pane
 	   and be clipped by whatever the host frames it with. Taking the pane's height
@@ -955,7 +1007,7 @@
 		padding-block-end: var(--_qm-tail);
 	}
 	/* The stack's one gapless seam, which `TipsCard` draws and this holds the two
-	 blocks to. `main` has to paint OVER the tip: a later sibling paints over an earlier
+	 blocks to. `main` has to paint over the tip: a later sibling paints over an earlier
 	 one otherwise, and the tip's background would cover the corners it is there to
 	 fill. `isolation` keeps that z-index local, so one wrapper owns the ordering and no
 	 card below inherits an argument about it. The wrapper is a single flex item, so the
@@ -977,56 +1029,71 @@
 		gap: var(--_qm-space-2);
 	}
 	/* The strip between two blocks, and the whole of it is the target: a gap is found
-	 by POSITION, so reveal and hit region are the full-bleed row rather than a word
-	 to aim at in the middle of it. It takes the editor's gap back on BOTH sides, so
-	 it is not a control sitting in the gutter; it IS the gutter: what separates two
-	 cards is the trigger's own height at the tap floor and nothing else, and the
-	 pill it fills on hover is edge to edge the space the new card opens into. No
-	 band is held back as miss-tolerance: gutter that reads as the trigger and
-	 inserts nothing unsays what the fill claims, so a press anywhere between two
-	 cards inserts. Absorbed rather than removed, because `gap` is also what separates
-	 the one seam no strip sits in: every card from the next under a quill declaring no
-	 kinds, where the affordance does not render at all. */
+	 by position, so reveal and hit region are the full-bleed row rather than a word
+	 to aim at in the middle of it. It takes the editor's gap back on both sides, so
+	 it is not a control sitting in the gutter; it is the gutter: what separates two
+	 cards is the trigger's own height and nothing else, and the pill it fills on hover
+	 is edge to edge the space the new card opens into. No band is held back as
+	 miss-tolerance: gutter that reads as the trigger and inserts nothing unsays what
+	 the fill claims, so a press anywhere between two cards inserts. Absorbed rather
+	 than removed, because `gap` is also what separates the one seam no strip sits in:
+	 every card from the next under a quill declaring no kinds, where the affordance
+	 does not render at all. */
 	.qm-add-card {
 		display: flex;
 		margin-top: calc(var(--_qm-space-2) * -1);
 		margin-bottom: calc(var(--_qm-space-2) * -1);
 	}
 	/* Unboxed, like every button, and not dashed: a
-	 dashed edge is the PLACEHOLDER idiom ("nothing is here yet") which on a button
+	 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
+	 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. Every gap is an equal entry point,
 	 reached by the name rather than by a mark: a card goes anywhere in the stack, not
 	 just after the last one.
 
+	 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
+	 `.qm-tap-floor`'s (controls.css); what it overhangs is the card's own inset above and
+	 below, which holds no target, so the floor costs a neighbour nothing.
+
+	 Ink is pinned to the label tone in every state, taking back the family's hover step:
+	 the trigger arrives and leaves on opacity, and a tone moving under an opacity already
+	 moving reads as two trips at different speeds.
+
 	 `:global`, because the multi-kind trigger is bits-ui's own element and a `class`
 	 passed to a primitive is a plain string that never picks up the scoping hash:
 	 the same seam the enum trigger is styled through. */
 	.qm-add-card :global(.qm-add-btn) {
-		/* No inset of its own: the pill and the gap are the same rectangle, and the tap
-		   floor is the whole of the height, which is what the marked strip's words
-		   centre in. */
 		display: flex;
 		align-items: center;
 		justify-content: center;
 		width: 100%;
+		height: var(--_qm-space-4);
+		color: var(--_qm-ink-label);
+		opacity: 0;
+		transition:
+			opacity var(--_qm-reveal),
+			background-color var(--_qm-reveal);
 	}
-	/* Words at rest, so the marked strip restates the rung they take: the LABEL rung,
-	   chrome's size, off the body size the family's type rule hands every button
-	   (`controls.css`), which is the size the fields above are READ at. */
+	/* The strip that holds words at rest takes the height that centres them, and rests dim
+	   rather than absent, having something to be seen. */
 	.qm-add-card-marked :global(.qm-add-btn) {
+		height: var(--_qm-tap-min);
 		font-size: var(--_qm-text-label);
+		font-weight: var(--_qm-weight-mid);
+		opacity: var(--_qm-opacity-idle);
 	}
-	/* The two engaged states the shared `:hover` rung does not cover, both filling the
-	   same pill it does. 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
+	/* 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. */
+	.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']) {
-		background: var(--_qm-surface-hover);
+		opacity: 1;
+		background: var(--_qm-add-fill);
 	}
 </style>