@quillmark/svelte 0.1.1 → 0.2.0

package/dist/visual/VisualEditorInner.svelte

@@ -16,7 +16,7 @@
  • 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;
+ `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,
@@ -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,
@@ -71,7 +72,6 @@
 	} from './structure.js';
 	import {
 		fieldKeyToString,
-		parsePath,
 		resolveCardKey,
 		routeAndResolve,
 		mergeDiagnostics,
@@ -79,6 +79,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 +99,7 @@
 		onError,
 		diagnostics,
 		enumOptionAllowed,
+		enumDisallowed = 'disable',
 		strings,
 		formatDiagnostic,
 		class: className,
@@ -187,8 +189,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.
@@ -204,12 +209,6 @@
 	/** 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. */
 	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),
@@ -670,64 +669,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
 	 * 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
 	 * 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);
+		// (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
 		// 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.
 	 *
-	 * A destroy lands INSIDE this: the leaf is looked up before the flush and
+	 * 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 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 ──────────────────────────────────────────
@@ -738,15 +766,24 @@
 	// 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.
+	// `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,14 +814,51 @@
 		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>
 
@@ -803,12 +877,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
@@ -837,12 +911,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>

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

@@ -1,11 +1,10 @@
-import { type DocPath } from '../core/address.js';
-import type { ContentHit } from '@quillmark/wasm';
+import { type DocPath, type Landing } from '../core/address.js';
 import type { VisualEditorProps } from './props.js';
 import type { CardId } from './signals.js';
 import type { FieldController } from '../core/codec/index.js';
 import './controls.css';
 declare const VisualEditorInner: import("svelte").Component<VisualEditorProps, {
-    setCaret: (hit: ContentHit) => Promise<void>;
+    setCaret: (at: Landing) => Promise<void>;
     getActiveLeaf: () => FieldController | undefined;
     focusField: (field: DocPath) => Promise<void>;
     insertCard: (kind: string, at?: number) => CardId | undefined;

package/dist/visual/controls.css

@@ -17,7 +17,7 @@
 
 @layer qm.chrome {
 	/* The themed focus ring in place of the raw UA outline, as a
-	 RULE rather than a pair of rungs each control assembles. `--_qm-ring-focus`
+	 RULE rather than a pair of rungs each control assembles. `--_qm-ring`
 	 fixes the VALUE; which properties draw a ring, and on what state, is the other
 	 half of the decision, and `check:style` sees a minted literal but never a
 	 divergent rule. A control opts in by carrying the marker class.
@@ -28,7 +28,7 @@
 	 it. That is the only distinction, and this pair is the whole of it. */
 	.qm-focus-ring:focus-visible,
 	.qm-focus-ring-within:focus-within {
-		outline: var(--_qm-ring-focus);
+		outline: var(--_qm-ring);
 		outline-offset: var(--_qm-ring-offset);
 	}
 
@@ -46,9 +46,10 @@
 	 DIFFERENT rungs, which no gate can see: `check:style`'s type axis holds that
 	 each side reads a rung, never that both read the same one.
 
-	 The list is wider than either recipe's chrome: the body leaf withholds the box
+	 The list is wider than either recipe's chrome: a prose leaf withholds the box
 	 and still reads the ramp, so `.qm-prose` is
-	 here and not below.
+	 here and not below. The BODY leaf steps off this rung onto `--_qm-text-paper`
+	 from its own block (`ProseField`).
 
 	 `font` is a shorthand carrying `line-height`, so each family's leading is
 	 declared in the rules BELOW and would be dropped in silence above them. */
@@ -70,9 +71,11 @@
 	 green while a control renders subtly the wrong height).
 
 	 LEADING sits on the wide list rather than on the box's own, because a box's
-	 height is a padding rung plus a line box plus two hairlines: a leaf and the
-	 input beside it agree on height exactly as long as they agree on leading, which
-	 is the whole of what "by construction" buys.
+	 height is an inset rung plus a line box plus two hairlines: a leaf and the
+	 input beside it agree on height exactly as long as they agree on leading and on
+	 size, which is the whole of what "by construction" buys. The body leaf keeps the
+	 leading and steps off the size, which costs it nothing: it draws no box and
+	 stands in no row.
 
 	 COLOUR is the trap one property over: `font` does not carry it either, so an
 	 input or trigger left off this line falls to the UA's own text colour: a second
@@ -90,7 +93,7 @@
 	}
 	.qm-control-box,
 	.qm-input {
-		padding: var(--_qm-space) var(--_qm-space-2);
+		padding: var(--_qm-inset-control);
 		border: var(--_qm-border-width) solid var(--_qm-border);
 		border-radius: var(--_qm-radius-inner);
 		background: var(--_qm-surface);
@@ -137,7 +140,7 @@
 	 which is why it is here and not on one family, and it is what keeps a button off
 	 the host page's leading the way the size rung keeps it off the host page's body
 	 size. A caller whose button carries a LABEL restates the rung it wants from its
-	 own block: the tips foot takes the meta rung, which is that surface's decision,
+	 own block: the tips foot takes the label rung, which is that surface's decision,
 	 not the family's. */
 	.qm-icon-btn,
 	.qm-add-affordance {
@@ -244,10 +247,10 @@
 		-webkit-backdrop-filter: blur(var(--_qm-blur));
 		border: var(--_qm-border-width) solid var(--_qm-border);
 		border-radius: var(--_qm-radius);
-		animation: qm-pop-in var(--_qm-duration-fast) var(--_qm-ease-arrive);
+		animation: qm-pop-in var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
 	.qm-popover-surface[data-ending-style] {
-		animation: qm-pop-out var(--_qm-duration-fast) var(--_qm-ease-depart);
+		animation: qm-pop-out var(--_qm-duration-fast) var(--_qm-ease-reverse);
 	}
 	@keyframes qm-pop-in {
 		from {

package/dist/visual/diagnostics.d.ts

@@ -1,28 +1,20 @@
 import type { Diagnostic } from '@quillmark/wasm';
-/** A field's routing address. `card` is `undefined` for the main card; a
- * composable card slot is a stable session id (the editor's own bookkeeping)
- * once resolved, or an ABSOLUTE document-array index straight off a parsed
- * `DocPath` (resolve via {@link resolveCardKey} before merging with id-keyed
- * sources). `field` `undefined` addresses the body (the field-less leaf). */
+/** A field's routing address, and `/core`'s `Addr` structurally: an `Addr` IS a
+ * positional `FieldKey`, so `addrForFieldPath` is the path→key walk and routing
+ * carries no second copy of the grammar. `card` is `undefined` for the main card; a
+ * composable card slot is a stable session id (the editor's own bookkeeping) once
+ * resolved, or an ABSOLUTE document-array index straight off a parsed `DocPath`
+ * (resolve via {@link resolveCardKey} before merging with id-keyed sources). `field`
+ * `undefined` addresses the body (the field-less leaf). */
 export interface FieldKey {
     card?: string | number;
     field?: string;
 }
 /** Canonical string key for a `FieldKey`: the routing `Map`'s key space. */
 export declare function fieldKeyToString(k: FieldKey): string;
-/**
- * Route a canonical `DocPath` (a `Diagnostic.path`, or a `ContentHit` /
- * `FieldRegion` field address; one grammar) to a `FieldKey`, `card` the ABSOLUTE
- * document-array index. `/core`'s `addrForFieldPath` IS this walk — an `Addr` is a
- * positional `FieldKey` — so routing reads the one public inverse rather than a
- * second copy of the grammar that drifts from it. `undefined` for a path naming no
- * single commit address (a nested / array-element path, a field-rooted one, a
- * malformed one).
- */
-export declare function parsePath(path: string): FieldKey | undefined;
 /**
  * Resolve a positional `FieldKey` (an ABSOLUTE document-array index, straight off
- * {@link parsePath}) to the editor's stable-id keying using the LIVE `cardIds`
+ * `addrForFieldPath`) to the editor's stable-id keying using the LIVE `cardIds`
  * array: re-resolved fresh on every call (never cached), the same "resolve only
  * at the point of use" discipline `cardIndexOf` applies to writes (VISUAL_EDITOR
  * §"The address is the spine"). A key already id-keyed (`card` a string) or main
@@ -37,10 +29,10 @@ export interface RoutedDiagnostic {
 }
 /**
  * Route a path-keyed producer's raw `Diagnostic[]` (validate / external) to the
- * editor's stable-id keying: the ONE door producers #1/#3 take, `parsePath` and
- * `resolveCardKey` in a single pass. An entry drops rather than mis-routes when it
- * carries no `path`, when `parsePath` cannot place it (a nested / array-element
- * address), or when its absolute card index is out of the live `cardIds`.
+ * editor's stable-id keying: the ONE door producers #1/#3 take, `addrForFieldPath`
+ * and `resolveCardKey` in a single pass. An entry drops rather than mis-routes when
+ * it carries no `path`, when the path names no single commit address (a nested /
+ * array-element one), or when its absolute card index is out of the live `cardIds`.
  */
 export declare function routeAndResolve(diagnostics: Diagnostic[] | undefined, cardIds: readonly string[]): RoutedDiagnostic[];
 /**

package/dist/visual/diagnostics.js

@@ -3,21 +3,9 @@ import { addrForFieldPath } from '../core/address.js';
 export function fieldKeyToString(k) {
     return `${k.card ?? 'main'}:${k.field ?? '$body'}`;
 }
-/**
- * Route a canonical `DocPath` (a `Diagnostic.path`, or a `ContentHit` /
- * `FieldRegion` field address; one grammar) to a `FieldKey`, `card` the ABSOLUTE
- * document-array index. `/core`'s `addrForFieldPath` IS this walk — an `Addr` is a
- * positional `FieldKey` — so routing reads the one public inverse rather than a
- * second copy of the grammar that drifts from it. `undefined` for a path naming no
- * single commit address (a nested / array-element path, a field-rooted one, a
- * malformed one).
- */
-export function parsePath(path) {
-    return addrForFieldPath(path);
-}
 /**
  * Resolve a positional `FieldKey` (an ABSOLUTE document-array index, straight off
- * {@link parsePath}) to the editor's stable-id keying using the LIVE `cardIds`
+ * `addrForFieldPath`) to the editor's stable-id keying using the LIVE `cardIds`
  * array: re-resolved fresh on every call (never cached), the same "resolve only
  * at the point of use" discipline `cardIndexOf` applies to writes (VISUAL_EDITOR
  * §"The address is the spine"). A key already id-keyed (`card` a string) or main
@@ -32,17 +20,17 @@ export function resolveCardKey(key, cardIds) {
 }
 /**
  * Route a path-keyed producer's raw `Diagnostic[]` (validate / external) to the
- * editor's stable-id keying: the ONE door producers #1/#3 take, `parsePath` and
- * `resolveCardKey` in a single pass. An entry drops rather than mis-routes when it
- * carries no `path`, when `parsePath` cannot place it (a nested / array-element
- * address), or when its absolute card index is out of the live `cardIds`.
+ * editor's stable-id keying: the ONE door producers #1/#3 take, `addrForFieldPath`
+ * and `resolveCardKey` in a single pass. An entry drops rather than mis-routes when
+ * it carries no `path`, when the path names no single commit address (a nested /
+ * array-element one), or when its absolute card index is out of the live `cardIds`.
  */
 export function routeAndResolve(diagnostics, cardIds) {
     const out = [];
     for (const d of diagnostics ?? []) {
         if (!d.path)
             continue;
-        const key = parsePath(d.path);
+        const key = addrForFieldPath(d.path);
         const resolved = key && resolveCardKey(key, cardIds);
         if (resolved)
             out.push({ key: resolved, diagnostic: d });

package/dist/visual/index.d.ts

@@ -1,3 +1,4 @@
+import '../core/theme.css';
 export { default as VisualEditor } from './VisualEditor.svelte';
 export type { VisualEditorProps } from './props.js';
 export { createField } from '../core/codec/index.js';

package/dist/visual/index.js

@@ -8,6 +8,13 @@
 // The barrel carries what a consumer story wants, and nothing else: a symbol
 // earns its line when a caller outside the package needs it, and grows one when
 // that caller arrives, not before.
+// The theme derivation, which every control on this surface reads through `var()`.
+// Imported at the BARREL because a subpath is what a consumer gets: this surface
+// reaches modules inside `core/` and never its entry, so a sheet hanging off that
+// entry arrives only for a consumer importing `/core` for some other reason. The
+// sheet rather than the entry, because the barrel needs the derivation and not
+// `init`. `check:deps` (rule 4) walks this file's own graph and holds the reach.
+import '../core/theme.css';
 export { default as VisualEditor } from './VisualEditor.svelte';
 // The prose leaf: the vanilla mount API a non-Svelte consumer (or a custom
 // surface) builds on.

package/dist/visual/leaves.d.ts

@@ -0,0 +1,47 @@
+import type { FieldController } from '../core/codec/index.js';
+/**
+ * A mounted field's landing handle: focus it, and the element the arrival wash blooms
+ * inside ({@link import('../core/bloom.js').bloomInside}).
+ *
+ * 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
+ * takes, so `focusField` and a label cannot land in different places.
+ */
+export interface FieldControl {
+    focus(): void;
+    /**
+     * Focus element `index` of a control that HAS elements, resolving the index to the
+     * element's session id at the call; {@link focus}'s own answer for an index past
+     * the live list. Absent on every control without elements.
+     *
+     * The granularity rides the CALL because the registry stays parent-keyed: a
+     * per-element key is positional, in a registry whose doctrine is dodging
+     * positional churn.
+     */
+    focusElement?(index: number): void;
+    readonly el: HTMLElement;
+}
+/**
+ * The registry the editor holds and the mounted tree writes into.
+ *
+ * A LANE IS DROPPED BY ITS OWN OWNER, which is what the symmetric pairs are for: a
+ * card retyped to a kind that declares the same field name at another type swaps the
+ * control under one leaf key without remounting `Field`, so the leaving control and
+ * the arriving prose leaf both touch that key with no order between them to rely on.
+ */
+export interface LeafRegistry {
+    /** A prose leaf, by its controller: the landing handle and the codec seam at once. */
+    registerProse(key: string, controller: FieldController): void;
+    unregisterProse(key: string): void;
+    /** A form control: the landing lane only, having no codec half to offer. */
+    registerControl(key: string, control: FieldControl): void;
+    unregisterControl(key: string): void;
+    /** The landing handle at `key`, whichever lane holds it. */
+    control(key: string): FieldControl | undefined;
+    /** The codec seam at `key`, `undefined` for a form control. */
+    prose(key: string): FieldController | undefined;
+    /** Drop everything: the surface going away as a whole, where a leaf's cleanup
+     *  order relative to the parent's is Svelte's business. */
+    clear(): void;
+}
+export declare function createLeafRegistry(): LeafRegistry;

package/dist/visual/leaves.js

@@ -0,0 +1,31 @@
+export function createLeafRegistry() {
+    const controls = new Map();
+    const proses = new Map();
+    return {
+        registerProse(key, controller) {
+            proses.set(key, controller);
+        },
+        unregisterProse(key) {
+            proses.delete(key);
+        },
+        registerControl(key, control) {
+            controls.set(key, control);
+        },
+        unregisterControl(key) {
+            controls.delete(key);
+        },
+        // The prose map is read SECOND: a controller is a control, so a leaf answers a
+        // landing without a second entry, and a key the two lanes overlap on during a
+        // retype resolves to the form control the tree is currently rendering.
+        control(key) {
+            return controls.get(key) ?? proses.get(key);
+        },
+        prose(key) {
+            return proses.get(key);
+        },
+        clear() {
+            controls.clear();
+            proses.clear();
+        }
+    };
+}