@quillmark/svelte 0.1.1 → 0.3.0

package/dist/visual/ObjectField.svelte

@@ -1,14 +1,13 @@
 <!--
  An `object` field → a nested subform over `properties` (declaration order),
- committing the WHOLE object by value on any nested change. SCALAR properties
+ committing the whole object by value on any nested change. Scalar properties
  only: a nested prose/array/object property renders a placeholder instead of
  recursing.
 
  A property's ghosted `default:` is the static schema `sub.default`, not the
  resolved provenance the top-level ghosts read (FIELD_PROVENANCE): `resolve`
  carries no per-property row (an object field resolves as one row whose value is
- the whole object). Thread it through `ghostDefault` once resolve exposes
- per-property provenance.
+ the whole object).
 -->
 <script lang="ts">
 	import type { QuillFieldSchema } from '@quillmark/wasm';
@@ -24,7 +23,7 @@
 		properties: Record<string, QuillFieldSchema> | undefined;
 		/** Accessible-name prefix for the property controls. */
 		label?: string;
-		/** The field label's own id. A subform is a GROUP of controls, not one control
+		/** The field label's own id. A subform is a group of controls, not one control
 		 * `for` could reach, so the field's label names the set and each property
 		 * control keeps its own composed `aria-label`. */
 		labelledBy?: string;
@@ -37,10 +36,23 @@
 	const entries = $derived(Object.entries(properties ?? {}));
 	const obj = $derived((value ?? {}) as Record<string, unknown>);
 
+	/** Take the caret: the first property's control, a subform having no single control
+	 * of its own to land on. Resolved off the DOM rather than a ref per property: every
+	 * property is a scalar control the DOM already knows how to focus (the date field's
+	 * segments carry `tabindex`, the `literal` separators between them do not), so a
+	 * handle each would be five refs restating document order. An empty or wholly
+	 * unsupported subform lands nothing. */
+	let rootEl = $state<HTMLElement | undefined>();
+	export function focus(): void {
+		rootEl
+			?.querySelector<HTMLElement>('input, select, button, [tabindex]:not([tabindex="-1"])')
+			?.focus();
+	}
+
 	function commitProp(key: string, v: unknown): void {
 		if (v === undefined) {
 			// A nested control cleared (the unset rung): drop the key so the property
-			// is ABSENT in the committed object (resolving to its own `default:`)
+			// is absent in the committed object (resolving to its own `default:`)
 			// rather than an `undefined` hole carried through `writer.set`.
 			const rest = { ...obj };
 			delete rest[key];
@@ -51,7 +63,13 @@
 	}
 </script>
 
-<div class="qm-object" role="group" aria-labelledby={labelledBy} aria-describedby={describedBy}>
+<div
+	bind:this={rootEl}
+	class="qm-object"
+	role="group"
+	aria-labelledby={labelledBy}
+	aria-describedby={describedBy}
+>
 	{#each entries as [key, sub] (key)}
 		{@const kind = controlKind(sub)}
 		{@const propLabel = `${label != null ? `${label} ` : ''}${sub.ui?.title ?? humanize(key)}`}
@@ -115,9 +133,10 @@
 	}
 	.qm-object-label {
 		font-size: var(--_qm-text-label);
-		/* Soft (500), a rung under the top-level field label's 600: a nested object
-		   prop reads as secondary. Resolves the label-weight disagreement. */
-		font-weight: var(--_qm-weight-soft);
+		/* The chrome weight, the same one the field label above it takes: what says
+		   this name is nested is the subform's rule and its inset, so a weight step
+		   here would state it twice and rank two names the ramp does not separate. */
+		font-weight: var(--_qm-weight-mid);
 		/* A label is a line, not a passage, so it overrides the root's reading
 		   rhythm the way every other label rung does. */
 		line-height: var(--_qm-leading-tight);

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

@@ -4,7 +4,7 @@ interface Props {
     properties: Record<string, QuillFieldSchema> | undefined;
     /** Accessible-name prefix for the property controls. */
     label?: string;
-    /** The field label's own id. A subform is a GROUP of controls, not one control
+    /** The field label's own id. A subform is a group of controls, not one control
      * `for` could reach, so the field's label names the set and each property
      * control keeps its own composed `aria-label`. */
     labelledBy?: string;
@@ -12,6 +12,8 @@ interface Props {
     describedBy?: string;
     onCommit: (obj: Record<string, unknown>) => void;
 }
-declare const ObjectField: import("svelte").Component<Props, {}, "">;
+declare const ObjectField: import("svelte").Component<Props, {
+    focus: () => void;
+}, "">;
 type ObjectField = ReturnType<typeof ObjectField>;
 export default ObjectField;

package/dist/visual/ProseArrayElement.svelte

@@ -1,13 +1,13 @@
 <!--
  One element of an array-of-`richtext` field (fixture `references`). Array
- elements are NOT `applyChange`-addressable: `Addr.field` is a flat name, so
+ elements are not `applyChange`-addressable: `Addr.field` is a flat name, so
  `references.0` has no op address. So
- this is NOT a `createField` leaf: it mounts a minimal PM view over the codec's
+ this is not a `createField` leaf: it mounts a minimal PM view over the codec's
  decode/encode + inline schema, and on every edit hands the re-encoded
- `Content` UP to the parent {@link ArrayField}, which commits the WHOLE array
+ `Content` up to the parent {@link ArrayField}, which commits the whole array
  by value (`writer.set(field, arrayWithElementReplaced)`). Anchors within an
  element are dropped on that value write: acceptable for inline refs. Mounts
- ONCE per stable element id (no reset on the parent's re-derive).
+ once per stable element id (no reset on the parent's re-derive).
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
@@ -24,16 +24,15 @@
 		label?: string;
 		onChange: (rt: Content) => void;
 		/** Raw keydown, for a container whose own keys run through this element: the
-		 * array repeater's Enter/Backspace (`ArrayField`). Fires BEFORE the view's own
+		 * array repeater's Enter/Backspace (`ArrayField`). Fires before the view's own
 		 * keymap, so the state it reads is the one this keystroke has yet to change. */
 		onKey?: (e: KeyboardEvent) => void;
-		onFocusEl?: () => void;
 	}
-	let { value, plaintext, label, onChange, onKey, onFocusEl }: Props = $props();
+	let { value, plaintext, label, onChange, onKey }: Props = $props();
 
 	let containerEl: HTMLDivElement | undefined = $state();
 	let view: EditorView | undefined;
-	/** Take the caret: what a parent placing focus on this element calls. The VIEW's
+	/** Take the caret: what a parent placing focus on this element calls. The view's
 	 * focus, not the element's: a PM view restores its selection, where a bare DOM
 	 * focus on a contenteditable leaves the caret unplaced. */
 	export function focus(): void {
@@ -42,7 +41,7 @@
 
 	onMount(() => {
 		if (!containerEl) return;
-		// An array element is an inline, value-by-value leaf: the SAME keymap and
+		// An array element is an inline, value-by-value leaf: the same keymap and
 		// plugin stack a `createField` leaf mounts (shared `proseLeafPlugins`), minus
 		// the anchor-position plugin (element anchors are dropped on the array's value
 		// write, per the header). Its own `dispatchTransaction` hands `Content` up.
@@ -62,10 +61,6 @@
 				if (tr.docChanged) onChange(pmToContent(next.doc));
 			},
 			handleDOMEvents: {
-				focus: () => {
-					onFocusEl?.();
-					return false;
-				},
 				keydown: (_v, e) => {
 					onKey?.(e);
 					return false;
@@ -84,15 +79,13 @@
  an array of `string` render rows of equal height. No floor: the reset in
  `core/codec/prose.css` makes one line of prose measure one line. Width is the
  row's to give: the element fills the track it is placed in (`ArrayField`). -->
-<div bind:this={containerEl} class="qm-array-prose qm-control-box"></div>
+<div bind:this={containerEl} class="qm-array-prose qm-control-box qm-focus-ring-within"></div>
 
 <style>
-	/* Caret-primary, matching ProseField: the contenteditable outline is dropped
-	   and the active element is cued by the wrapper border tint below, not a ring. */
+	/* Caret-primary, matching ProseField: the contenteditable's own outline is
+	   dropped and the ring rides the wrapper (`qm-focus-ring-within`,
+	   controls.css), which is where the box is. */
 	.qm-array-prose :global(.ProseMirror) {
 		outline: none;
 	}
-	.qm-array-prose:focus-within {
-		border-color: var(--_qm-accent);
-	}
 </style>

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

@@ -7,10 +7,9 @@ interface Props {
     label?: string;
     onChange: (rt: Content) => void;
     /** Raw keydown, for a container whose own keys run through this element: the
-     * array repeater's Enter/Backspace (`ArrayField`). Fires BEFORE the view's own
+     * array repeater's Enter/Backspace (`ArrayField`). Fires before the view's own
      * keymap, so the state it reads is the one this keystroke has yet to change. */
     onKey?: (e: KeyboardEvent) => void;
-    onFocusEl?: () => void;
 }
 declare const ProseArrayElement: import("svelte").Component<Props, {
     focus: () => void;

package/dist/visual/ProseField.svelte

@@ -1,15 +1,14 @@
 <!--
- One content prose leaf: a thin Svelte mount of the codec's `createField`
- (VISUAL_EDITOR §Surface). Mounts ONCE per stable leaf key and tears down on
- unmount; the leaf owns its PM state, history, and per-keystroke `applyChange`
- commit, so this wrapper adds no logic beyond wiring and registration. The
- `addr` is supplied by the parent as a LIVE object (its `card` a getter over the
- stable-id→index map), so a card reorder re-targets this leaf's commits without
- a remount: the caret rides the untouched PM view.
+ One content prose leaf: a Svelte mount of the codec's `createField`
+ (VISUAL_EDITOR §Surface), which owns the PM state, the history and the
+ per-keystroke commit, so this wrapper is wiring and registration. `addr` is a
+ live object the parent builds, so a card reorder re-targets this leaf's commits
+ with the caret riding the untouched view.
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import { createField, type FieldController, type SlashState } from '../core/codec/index.js';
+	import type { LeafRegistry } from './leaves.js';
 	import SlashMenu from './SlashMenu.svelte';
 	import { wording } from './strings.js';
 	import './controls.css';
@@ -19,32 +18,28 @@
 	interface Props {
 		doc: Document;
 		/** The schema this leaf reads its content through: `createField` binds a reader
-		 *  off it, so a stored string decodes by declared type rather than by guess. */
+		 *  off it, so a stored string decodes by its declared type. */
 		quill: Quill;
 		addr: Addr;
 		inline?: boolean;
 		plaintext?: boolean;
 		/**
-		 * Draw no box: the card body's leaf, and nothing else. A property
-		 * of the SLOT rather than of the leaf: `block` is not the same predicate, since
-		 * a `richtext` field without `inline` is block prose and still a control in a
-		 * row of controls. Only the body is paper, and only its caller knows it is.
+		 * Draw no box: the card body's leaf, and nothing else. Not `block`, which is a
+		 * different predicate: a `richtext` field without `inline` is block prose and
+		 * still a control in a row of controls, so only the caller knows what is paper.
 		 */
 		unframed?: boolean;
-		/** Accessible name for a leaf NOTHING else names: an array element, or the
-		 * card body. A leaf with a field label takes `labelledBy` instead. */
+		/** Accessible name for a leaf nothing else names: an array element, or the
+		 * card body. A leaf with a field label takes `labelledBy`. */
 		label?: string;
 		/** The field label's own id → `aria-labelledby` on the editable region. `for`
-		 * cannot reach a `contenteditable` (not a labelable element) so the
-		 * association runs the other way, and the label's click comes back through
-		 * the controller's `focus`. */
+		 * cannot reach a `contenteditable`, so the association runs the other way and
+		 * the label's click comes back through the controller's `focus`. */
 		labelledBy?: string;
 		/** The parked `description` (FieldLabel) → `aria-describedby`. */
 		describedBy?: string;
-		/** Ghost shown on the empty leaf. An inline leaf's is the resolved `default:`
-		 * or nothing; a body's always has text, falling back to an invitation
-		 * (`resolveBodyGhost`). Reactive: a change is pushed into the mounted view,
-		 * never a remount. */
+		/** Ghost shown on the empty leaf: an inline leaf's resolved `default:` or
+		 * nothing, a body's always text (`resolveBodyGhost`). */
 		placeholder?: string;
 		/** Stable identity for the registry, stamped on the DOM node so a remount is
 		 *  visible as one. */
@@ -54,8 +49,9 @@
 		/** A commit landed on this leaf: the prose change lane. */
 		onChange?: (addr: Addr) => void;
 		onError?: EditorErrorHandler;
-		register?: (key: string, controller: FieldController) => void;
-		unregister?: (key: string) => void;
+		/** The editor's leaf registry (`leaves.ts`). Registering the controller is what
+		 *  makes this leaf a caret target and not merely a focus one. */
+		leaves?: LeafRegistry;
 	}
 
 	let {
@@ -74,39 +70,29 @@
 		onCaretMove,
 		onChange,
 		onError,
-		register,
-		unregister
+		leaves
 	}: Props = $props();
 
 	let containerEl: HTMLDivElement | undefined = $state();
 
-	// The island chrome's wording, read where every other surface reads it. Passed as
-	// a GETTER: the codec draws that chrome on each render, so a locale swap reaches a
-	// mounted table without remounting the leaf and losing the caret.
+	// Handed to the codec as a getter: the island chrome redraws on each render, so a
+	// locale swap reaches a mounted table without remounting the leaf and losing the caret.
 	const t = wording();
 
-	/** The insert menu's live state, pushed by the leaf's trigger plugin. Held HERE
-	 * rather than in the shell: a trigger belongs to one caret in one leaf, so the
-	 * menu is the leaf's surface, unlike the one format popover that follows whichever
-	 * leaf is active. A constrained leaf never receives one (`createField` mounts the
-	 * trigger on the block schema alone). */
+	/** The insert menu's live state, pushed by the leaf's trigger plugin: the menu is
+	 * the leaf's surface rather than the shell's (VISUAL_EDITOR §Chrome). A constrained
+	 * leaf never receives one, the trigger mounting on the block schema alone. */
 	let slash: SlashState | undefined = $state();
 
-	// Block prose vs a control in a row of controls: the SAME predicate the codec
-	// picks its schema by (`createField`: `plaintext` implies `inline`), so the box a
-	// leaf draws and the schema it holds cannot disagree. Keyed on `inline` alone, a
-	// `plaintext`-only field would take the body's floor while holding one paragraph.
+	// The codec's own schema predicate (`createField`: `plaintext` implies `inline`), so
+	// the box a leaf draws and the schema it holds cannot disagree. On `inline` alone a
+	// `plaintext` field would take the block floor while holding one paragraph.
 	const block = $derived(!(inline || plaintext));
 
-	// An absent richtext field (a `default:`-only field like `tag_line`) is handled
-	// by the codec itself: `createField` decodes an empty content and overwrites on
-	// the first edit; so this wrapper adds no pre-seeding, and an untouched field
-	// stays absent (its default rendering intact) until actually edited.
 	let controller: FieldController | undefined;
 
-	/** Take the caret: what the label click calls. The CONTROLLER's focus, not the
-	 * container's: a PM view restores a selection that an `HTMLElement.focus` on
-	 * the wrapper leaves unplaced. */
+	/** Take the caret: what the label's click calls. The controller's focus, not the
+	 * container's, which leaves the PM selection unplaced. */
 	export function focus(): void {
 		controller?.focus();
 	}
@@ -125,7 +111,6 @@
 			describedBy,
 			placeholder,
 			tableStrings: () => t.strings,
-			slashStrings: () => t.strings,
 			onSlash: (next) => {
 				slash = next;
 			},
@@ -134,18 +119,16 @@
 			onChange,
 			onError
 		});
-		register?.(leafKey, controller);
+		leaves?.registerProse(leafKey, controller);
 		return () => {
-			unregister?.(leafKey);
+			leaves?.unregisterProse(leafKey);
 			controller?.destroy();
 			controller = undefined;
 		};
 	});
 
-	// The ghost outlives no remount of its own: the leaf is keyed by the card's
-	// session id, so a card RETYPED to another kind keeps this view and would keep
-	// the old kind's wording. Push it instead: the caret is worth more than the
-	// simplicity of rebuilding.
+	// A retype does not remount the leaf (its key is the card's session id), so the new
+	// kind's ghost is pushed into the live view rather than paid for with the caret.
 	$effect(() => {
 		controller?.setPlaceholder(placeholder);
 	});
@@ -155,53 +138,47 @@
 	bind:this={containerEl}
 	class="qm-prose"
 	class:qm-control-box={!unframed}
+	class:qm-focus-ring-within={!unframed}
 	class:qm-prose-block={block}
 	data-leaf-key={leafKey}
 ></div>
 <SlashMenu menu={slash} leaf={() => controller} label={t.strings.slashLabel} />
 
 <style>
-	/* The box is `.qm-control-box` (controls.css): the same rule the input beside it
-	 draws, so the two agree on height by construction rather than by two floors
-	 tuned to match. Nothing here restates it, and there is no
-	 `min-height`: `core/codec/prose.css` resets the paragraph box, so one line of
-	 prose in this box measures one line of text in that one. */
+	/* The box is `.qm-control-box` (controls.css), the same rule the input beside it
+	 draws, so the two agree on height by construction. No `min-height` with it:
+	 `core/codec/prose.css` resets the paragraph box, so one line of prose in this box
+	 measures one line of text in that one. */
 	.qm-prose {
-		/* Positioned for the arrival wash `setCaret` inserts (`core/bloom.ts`): an
-		 inset child, so it covers the text without fading it or tinting the leaf's
-		 own surface. */
+		/* Containing block for the arrival wash's inset child (`core/bloom.ts`). */
 		position: relative;
 	}
-	/* A leaf the inline schema does NOT constrain (the body) is paper rather than a
-	 cell in a row of controls, so it opens at a few lines and grows. The floor is
-	 three LINE BOXES, not a length: size times leading is what one line measures, so
-	 both factors are named or the expression stops meaning the three lines it claims.
-	 It moves with the type ramp and with nothing else. Three is what an EMPTY body
-	 costs, which is the only state the floor is ever the height: the ghost takes the
-	 first line, so the opening reads as an invitation with room under it rather than
-	 as a drop. */
-	.qm-prose-block {
-		min-height: calc(var(--_qm-text-body) * var(--_qm-leading-body) * 3);
+	/* A leaf the inline schema does not constrain is prose rather than a cell in a row of
+	 controls, so it opens at three line boxes and grows: the ghost takes the first,
+	 leaving room under it. `1em`, not a size rung, which is the rule below's to name.
+
+	 On the editable rather than on the wrapper, which is what makes those lines part of
+	 the body: height the wrapper holds is height outside the `contenteditable`, where a
+	 press lands no caret. Inside it, the browser answers a press past the last line at
+	 the end of it. */
+	.qm-prose-block :global(.ProseMirror) {
+		min-height: calc(1em * var(--_qm-leading-body) * 3);
+	}
+	/* Paper, and the withheld box is what says so. Not `block` alone: `inline` is the
+	 quill's to declare, so a schema omitting it on a richtext field puts a block leaf in
+	 a field row, where this rung would break the height agreement above. */
+	.qm-prose-block:not(.qm-control-box) {
+		font-size: var(--_qm-text-paper);
 	}
-	/* The caret is the prose leaf's focus indicator, not a ring: a ring around a
-	 contenteditable reads as form chrome rather than as paper. So the outline is
-	 dropped; a boxed leaf tints its wrapper border below. */
+	/* The caret is the body's focus indicator: a ring around the one surface in a card
+	 that is paper reads as form chrome. So the contenteditable's own outline is dropped
+	 everywhere, and a boxed leaf takes the shared ring on its wrapper instead
+	 (`qm-focus-ring-within`, controls.css). */
 	.qm-prose :global(.ProseMirror) {
 		outline: none;
 	}
-	/* Active-leaf cue: tint the hairline to the focus hue, shared with the scalar
-	 ring and the preview active box: no added box (the editor↔preview address).
-	 Scoped to the leaves that HAVE a hairline: the body has none, and the caret is
-	 the whole indicator there: one surface per card, and the largest in it, so
-	 "which leaf am I in" is not a question it raises. A rule drawn to answer it
-	 would be a stroke bought back to replace the one unframing removed. */
-	.qm-prose.qm-control-box:focus-within {
-		border-color: var(--_qm-accent);
-	}
-	/* Empty-leaf ghost: the resolved `default:` as dim/italic ghost,
-	   matching the scalar ghost rung. Rendered from a node decoration's data attr so
-	   it stays out of the
-	   document; `float`/`height:0` keep it from displacing the caret. */
+	/* Empty-leaf ghost, at the scalar ghost rung: a node decoration's data attr, so it
+	 stays out of the document; `float`/`height: 0` keep it from displacing the caret. */
 	.qm-prose :global(.ProseMirror .qm-prose-placeholder::before) {
 		content: attr(data-placeholder);
 		color: var(--_qm-ink-ghost);

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

@@ -1,36 +1,32 @@
-import { type FieldController } from '../core/codec/index.js';
+import type { LeafRegistry } from './leaves.js';
 import './controls.css';
 import type { Document, Quill, Addr } from '@quillmark/wasm';
 import type { EditorErrorHandler } from '../core/errors.js';
 interface Props {
     doc: Document;
     /** The schema this leaf reads its content through: `createField` binds a reader
-     *  off it, so a stored string decodes by declared type rather than by guess. */
+     *  off it, so a stored string decodes by its declared type. */
     quill: Quill;
     addr: Addr;
     inline?: boolean;
     plaintext?: boolean;
     /**
-     * Draw no box: the card body's leaf, and nothing else. A property
-     * of the SLOT rather than of the leaf: `block` is not the same predicate, since
-     * a `richtext` field without `inline` is block prose and still a control in a
-     * row of controls. Only the body is paper, and only its caller knows it is.
+     * Draw no box: the card body's leaf, and nothing else. Not `block`, which is a
+     * different predicate: a `richtext` field without `inline` is block prose and
+     * still a control in a row of controls, so only the caller knows what is paper.
      */
     unframed?: boolean;
-    /** Accessible name for a leaf NOTHING else names: an array element, or the
-     * card body. A leaf with a field label takes `labelledBy` instead. */
+    /** Accessible name for a leaf nothing else names: an array element, or the
+     * card body. A leaf with a field label takes `labelledBy`. */
     label?: string;
     /** The field label's own id → `aria-labelledby` on the editable region. `for`
-     * cannot reach a `contenteditable` (not a labelable element) so the
-     * association runs the other way, and the label's click comes back through
-     * the controller's `focus`. */
+     * cannot reach a `contenteditable`, so the association runs the other way and
+     * the label's click comes back through the controller's `focus`. */
     labelledBy?: string;
     /** The parked `description` (FieldLabel) → `aria-describedby`. */
     describedBy?: string;
-    /** Ghost shown on the empty leaf. An inline leaf's is the resolved `default:`
-     * or nothing; a body's always has text, falling back to an invitation
-     * (`resolveBodyGhost`). Reactive: a change is pushed into the mounted view,
-     * never a remount. */
+    /** Ghost shown on the empty leaf: an inline leaf's resolved `default:` or
+     * nothing, a body's always text (`resolveBodyGhost`). */
     placeholder?: string;
     /** Stable identity for the registry, stamped on the DOM node so a remount is
      *  visible as one. */
@@ -40,8 +36,9 @@ interface Props {
     /** A commit landed on this leaf: the prose change lane. */
     onChange?: (addr: Addr) => void;
     onError?: EditorErrorHandler;
-    register?: (key: string, controller: FieldController) => void;
-    unregister?: (key: string) => void;
+    /** The editor's leaf registry (`leaves.ts`). Registering the controller is what
+     *  makes this leaf a caret target and not merely a focus one. */
+    leaves?: LeafRegistry;
 }
 declare const ProseField: import("svelte").Component<Props, {
     focus: () => void;

package/dist/visual/SlashMenu.svelte

@@ -1,19 +1,21 @@
 <!--
  The slash menu. The leaf's own surface, not the
  shell's: the trigger belongs to one caret in one leaf, so it is mounted by
- `ProseField` beside the view it reads from, unlike the ONE shell-owned format
+ `ProseField` beside the view it reads from, unlike the one shell-owned format
  popover that follows whichever leaf is active.
 
- The MODEL is the codec's (`codec/slash.ts`: the trigger run, the query, the
+ The model is the codec's (`codec/slash.ts`: the trigger run, the query, the
  highlighted index, and what each pick does). This component draws it and nothing
  else. The keys are the leaf's keymap for the same reason: the caret stays in the
  contenteditable while the menu is open, so a focus-taking listbox would move the
- selection the insert is measured against. What is left here is the POINTER's half:
- buttons that pick, and that swallow their own mousedown so the caret stays put.
+ selection the insert is measured against. What is left here is mostly the pointer's
+ half: buttons that pick, and that swallow their own mousedown so the caret stays put.
 
- The highlight has ONE lane: `data-highlighted` marks whichever item the codec's
- index names, and a pointer entering an item MOVES that index rather than painting a
+ The highlight has one lane: `data-highlighted` marks whichever item the codec's
+ index names, and a pointer entering an item moves that index rather than painting a
  second highlight the keyboard cannot reach (controls.css, the shared menu recipe).
+ The keyboard's one claim here is the scroll: the arrows move an index, and only the
+ chrome knows the port that index has to stay inside.
 -->
 <script lang="ts">
 	import { Popover } from 'bits-ui';
@@ -32,7 +34,7 @@
 	let { menu, leaf, label }: Props = $props();
 
 	/** Raised whenever the codec reports offers. Mirrored into local state rather than
-	 * derived, because the primitive OWNS this prop: its own dismissal layer (an
+	 * derived, because the primitive owns this prop: its own dismissal layer (an
 	 * outside press) writes it, and a derived it cannot write to is an error rather
 	 * than a dismissal. The next report re-syncs, so the codec stays the authority on
 	 * whether a run is live. */
@@ -41,11 +43,21 @@
 		open = !!menu && menu.items.length > 0;
 	});
 
-	/** The root to portal INTO, resolved from the leaf's own DOM so the menu lands
+	/** The root to portal into, resolved from the leaf's own DOM so the menu lands
 	 * inside whichever `[data-qm-root]` raised it and inherits the consumer's dials;
 	 * `undefined` falls back to bits-ui's `document.body`. */
 	const portalTarget = $derived(leaf()?.el.closest<HTMLElement>('[data-qm-root]') ?? undefined);
 
+	let surface = $state<HTMLElement | undefined>();
+
+	/** Keep the keyboard's cursor in the port: the arrows move an index rather than a
+	 *  focus, so a row the list scrolled past has nothing bringing it back. `nearest`
+	 *  scrolls the least that works, and no ancestor the row is already visible in. */
+	$effect(() => {
+		void menu?.index;
+		surface?.querySelector('[data-highlighted]')?.scrollIntoView({ block: 'nearest' });
+	});
+
 	/** Swallow the item's own mousedown: without it the browser focuses the item and
 	 *  blurs the leaf, taking the trigger run's caret with it. */
 	function keepFocus(e: MouseEvent): void {
@@ -55,12 +67,17 @@
 
 <Popover.Root bind:open>
 	<Popover.Portal to={portalTarget}>
+		<!-- Hung off the trigger and flush against it: the anchor is the `/` itself
+		     (`codec/slash.ts`), so the surface's top left corner sits at the line's bottom
+		     edge under the character that opened the menu, and stays there as the query is
+		     typed. Zero offset, because a gap reads as a surface floating near the caret
+		     rather than one growing out of it. -->
 		<Popover.Content
 			customAnchor={menu?.anchor ?? null}
 			side="bottom"
 			align="start"
 			trapFocus={false}
-			sideOffset={6}
+			sideOffset={0}
 			onOpenAutoFocus={(e: Event) => e.preventDefault()}
 			onCloseAutoFocus={(e: Event) => e.preventDefault()}
 		>
@@ -74,22 +91,26 @@
 					     a thing to click, tab into, or read. -->
 					<div
 						{...props}
+						bind:this={surface}
 						class="qm-slash-menu qm-menu-surface"
 						data-qm-root
 						role="group"
 						aria-label={label}
 						inert={!raised}
 					>
-						{#each menu?.items ?? [] as item, i (item.id)}
+						<!-- The row is the command as typed, leading `/` and all: the menu is a
+						     completion of the run in the text, so the row and the run read the
+						     same. -->
+						{#each menu?.items ?? [] as name, i (name)}
 							<button
 								type="button"
 								class="qm-menu-item qm-slash-item"
 								data-highlighted={i === menu?.index ? '' : undefined}
 								onmousedown={keepFocus}
-								onclick={() => leaf()?.slashPick(item.id)}
-								onpointerenter={() => leaf()?.slashFocus(item.id)}
+								onclick={() => leaf()?.slashPick(name)}
+								onpointerenter={() => leaf()?.slashFocus(name)}
 							>
-								{item.label}
+								/{name}
 							</button>
 						{/each}
 					</div>
@@ -104,20 +125,25 @@
 	   `.qm-menu-surface` / `.qm-menu-item` (controls.css): the same recipe the enum
 	   listbox and the card stack's kind menu draw, because all three are lists picked
 	   from. What is here is this menu's own: a measure, so a long label does not stretch
-	   the surface across the card, and a scroll for a filtered list that stays long. */
+	   the surface across the card, a scroll for a filtered list that stays long, and the
+	   face. Monospace, where the sibling menus are not: they offer values of the document
+	   and read as the prose around them, where these are commands, and the surface
+	   already spells a literal in that face (the `code` mark, `codec/prose.css`). */
 	.qm-slash-menu {
 		min-width: 12rem;
 		max-height: 16rem;
 		overflow-y: auto;
+		font-family: var(--_qm-font-mono);
 	}
 	/* An item is a row of text, not a glyph: the whole row is the target, and the label
 	   is the accessible name with nothing beside it. A button is a button, so the UA's
-	   own box is taken back; what is left is the shared item recipe. */
+	   own box is taken back; what is left is the shared item recipe. The fill is not
+	   taken back here: a scoped block is unlayered, so a reset would outrank the recipe's
+	   highlight; the resting transparent is the recipe's own (controls.css). */
 	.qm-slash-item {
 		display: block;
 		width: 100%;
 		border: none;
-		background: none;
 		font: inherit;
 		color: inherit;
 		text-align: left;