@quillmark/svelte 0.5.1 → 0.6.0

package/dist/visual/EnumField.svelte

@@ -16,8 +16,11 @@
 	import { Select } from 'bits-ui';
 	import Icon from './icons/Icon.svelte';
 	import { syncedLocal } from './synced.svelte.js';
+	import { wording } from './strings.js';
 	import './controls.css';
 
+	const t = wording();
+
 	interface Props {
 		value: string | undefined;
 		values: string[];
@@ -114,8 +117,19 @@
 				     plain string and never picks up the scoping hash. -->
 				<div class="qm-menu-surface qm-select-content" data-qm-root>
 					<Select.Viewport>
-						<Select.Item class="qm-menu-item qm-select-item" value={UNSET} label={ghostText}>
+						<!-- The sentinel renders the `default:`'s own text, so a defaulted enum
+						     lists that word twice: this row, and the member below it. The tag has
+						     to be a word rather than a tone — the ghost is already `ink-label`,
+						     and while the field is unset this is the selected row, so the weight
+						     step pulls the other way. It rides the accessible name for the same
+						     reason. -->
+						<Select.Item
+							class="qm-menu-item qm-select-item qm-select-unset"
+							value={UNSET}
+							label={`${ghostText} ${t.strings.enumUnsetTag}`}
+						>
 							<span class="qm-select-ghost">{ghostText}</span>
+							<span class="qm-select-tag">{t.strings.enumUnsetTag}</span>
 						</Select.Item>
 						<!-- A refused option still draws under `'disable'`, and under either
 						     policy when it is the one selected: a listbox whose selected value
@@ -186,4 +200,22 @@
 	.qm-select-ghost {
 		color: var(--_qm-ink-label);
 	}
+	/* The sentinel's row: the ghost at one end, the tag at the other, so the pair reads
+	   as a value and a note about it rather than as two words. Only this row takes the
+	   split; a member's row is one string and has nothing to distribute. */
+	.qm-select-content :global(.qm-select-unset) {
+		display: flex;
+		align-items: baseline;
+		justify-content: space-between;
+		gap: var(--_qm-space-2);
+	}
+	/* A step down the size ramp, which is what says this is chrome and the word beside
+	   it is the value. The ink is the ghost's own: a second tone here would rank the
+	   tag against the thing it annotates, and there is no rung under `label` to take
+	   (theme.css, "Two rungs, and there is no third"). */
+	.qm-select-tag {
+		flex-shrink: 0;
+		font-size: var(--_qm-text-label);
+		color: var(--_qm-ink-label);
+	}
 </style>

package/dist/visual/Field.svelte

@@ -18,7 +18,7 @@
 	import type { EditorErrorHandler } from '../core/errors.js';
 	import type { LeafRegistry } from './leaves.js';
 	import type { FieldModel, FieldSpan } from './structure.js';
-	import { ghostDefault, stringifyGhost } from './structure.js';
+	import { VARIANT_DISCRIMINANT, ghostDefault, stringifyGhost } from './structure.js';
 	import type { FieldDomIds } from './domid.js';
 	import ProseField from './ProseField.svelte';
 	import TextField from './TextField.svelte';
@@ -28,6 +28,7 @@
 	import DateField from './DateField.svelte';
 	import ArrayField from './ArrayField.svelte';
 	import ObjectField from './ObjectField.svelte';
+	import VariantField from './VariantField.svelte';
 	import DiagnosticList from './DiagnosticList.svelte';
 	import FieldLabel from './FieldLabel.svelte';
 
@@ -91,14 +92,22 @@
 	// control's `YYYY-MM-DD`. An object-valued default does not ghost.
 	const ghost = $derived(ghostDefault(provenance));
 	const defaultStr = $derived(stringifyGhost(ghost));
+	// A variant resolves as one rung whose value is the whole container, so the
+	// discriminant's ghost is that container's own discriminant cell.
+	const ghostMember = $derived(
+		(ghost as Record<string, unknown> | undefined)?.[VARIANT_DISCRIMINANT] as string | undefined
+	);
 
 	// `for` reaches a labelable control and the browser does the rest. The other four
 	// are not labelable (the prose leaf's `contenteditable`, the date field's segment
 	// container, the object subform, an array's N inputs) so `for` there would be
 	// both inert and invalid markup; they take `aria-labelledby` and a click handoff.
+	// A variant is labelable through its discriminant: the select is the one control
+	// the field's label names, and its cells carry composed names of their own.
 	const labelable = $derived(
 		field.control === 'text' ||
 			field.control === 'enum' ||
+			field.control === 'variant' ||
 			field.control === 'number' ||
 			field.control === 'boolean'
 	);
@@ -120,7 +129,7 @@
 	let arrayEl = $state<
 		| {
 				focus: () => void;
-				focusElement: (k: number) => void;
+				focusElement: (k: number, pos?: number) => void;
 				washBox: () => HTMLElement | undefined;
 		  }
 		| undefined
@@ -133,8 +142,8 @@
 	}
 	/** The array's per-ELEMENT landing, for the addresses the preview mints under an
 	 *  array field (`leaves.ts`); read at the call, so it tracks the mounted repeater. */
-	function focusElement(k: number): void {
-		arrayEl?.focusElement(k);
+	function focusElement(k: number, pos?: number): void {
+		arrayEl?.focusElement(k, pos);
 	}
 	// Only where `for` cannot reach; the labelable four are the browser's own, and a
 	// second handler over them would be a focus the label already placed.
@@ -229,6 +238,19 @@
 					{optionAllowed}
 					{enumDisallowed}
 				/>
+			{:else if field.control === 'variant'}
+				<VariantField
+					value={value as Record<string, unknown> | undefined}
+					schema={field.schema}
+					{ghostMember}
+					label={field.label}
+					id={domIds.control}
+					labelledBy={domIds.label}
+					{describedBy}
+					onCommit={onCommitScalar}
+					{optionAllowed}
+					{enumDisallowed}
+				/>
 			{:else if field.control === 'number'}
 				<NumberField
 					value={value as number | undefined}
@@ -265,6 +287,7 @@
 					description={field.description}
 					labelId={domIds.label}
 					descriptionId={domIds.description}
+					idBase={domIds.control}
 					elementContent={(i) => quill.reader(doc).getContentAt(addr, [i])}
 					onCommit={onCommitScalar}
 				/>
@@ -274,6 +297,7 @@
 					value={value as Record<string, unknown> | undefined}
 					properties={field.schema.properties}
 					label={field.label}
+					idBase={domIds.control}
 					labelledBy={domIds.label}
 					{describedBy}
 					onCommit={onCommitScalar}

package/dist/visual/FieldLabel.svelte

@@ -11,8 +11,8 @@
  element is inert and invalid.
 
  Two non-gating label decorations:
- • a persistent required `*` for a field the schema obliges (`must_fill`, which
- derives from a missing `default:`; DOCUMENT_MODEL). Its
+ • a persistent required `*` for a field the schema obliges — one that declares no
+ `default:` (DOCUMENT_MODEL). Its
  accessible name is "required", so a screen reader announces the word, not the
  glyph; inside the `<label>`, so it names the control along with the text
  ("Subject required") rather than announcing as a node adjacent to it;

package/dist/visual/FormatPopover.svelte

@@ -277,6 +277,18 @@
 		sync();
 	}
 
+	/**
+	 * A fresh anchor id: 128 random bits as hex, the id being opaque to the
+	 * boundary and needing only to be unique. `crypto.randomUUID` is
+	 * secure-context-only, and absent on a page served over plain `http` to
+	 * something other than localhost; `getRandomValues` is there either way.
+	 */
+	function mintAnchorId(): string {
+		return [...crypto.getRandomValues(new Uint8Array(16))]
+			.map((b) => b.toString(16).padStart(2, '0'))
+			.join('');
+	}
+
 	/**
 	 * Toggle an identity anchor over the selection: the `anchor`
 	 * button's answer to a formatting toggle. If the selection already covers
@@ -292,7 +304,7 @@
 		const { from, to } = leaf.selectionRange();
 		const covered = leaf.anchorsInRange(from, to);
 		if (covered.length) covered.forEach((id) => leaf.removeAnchor(id));
-		else leaf.insertAnchor(crypto.randomUUID(), from);
+		else leaf.insertAnchor(mintAnchorId(), from);
 		view.focus();
 		sync();
 	}

package/dist/visual/ObjectField.svelte

@@ -4,6 +4,23 @@
  only: a nested prose/array/object property renders a placeholder instead of
  recursing.
 
+ The nesting is a band: two full-width horizontals at `--_qm-border`, the figure the
+ card draws around its own metadata (`.qm-meta-top` / `.qm-meta-bottom`) one octave
+ down. Nothing insets, so a property's control keeps the card's left and right columns
+ exactly as a field's does, and the field's own label caps the band from outside it —
+ name, rule under the name, content, closing rule.
+
+ That absent inset is also what puts the properties on the section's own column tracks
+ (below), so a subform's cells share edges with the fields above them rather than
+ keeping a rhythm of their own.
+
+ Which edges draw is {@link Props.edges}, and the rule is that a boundary is stated
+ once: where a box already sits against the subform, that box IS the boundary and a
+ stroke under it would say so twice. So a field-level subform takes the band, and a
+ subform hanging off a control — a variant's cells under their discriminant, an
+ array element's properties under its summary row — takes the closing rule alone.
+ Sometimes two strokes and sometimes one: the open figure the card's bracket is.
+
  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
@@ -11,7 +28,10 @@
 -->
 <script lang="ts">
 	import type { QuillFieldSchema } from '@quillmark/wasm';
-	import { controlKind, humanize } from './structure.js';
+	import { controlKind, humanize, obliged } from './structure.js';
+	import { wording } from './strings.js';
+	import { propertyDomIds } from './domid.js';
+	import FieldLabel from './FieldLabel.svelte';
 	import TextField from './TextField.svelte';
 	import EnumField from './EnumField.svelte';
 	import NumberField from './NumberField.svelte';
@@ -21,21 +41,53 @@
 	interface Props {
 		value: Record<string, unknown> | undefined;
 		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
-		 * `for` could reach, so the field's label names the set and each property
-		 * control keeps its own composed `aria-label`. */
+		 * `for` could reach, so the field's label names the set; each property carries
+		 * its own `<label for>` inside it. */
 		labelledBy?: string;
 		/** The parked `description` (FieldLabel): announced on entering the group. */
 		describedBy?: string;
+		/**
+		 * The parent control's DOM id: the base each property's own three names derive
+		 * from ({@link propertyDomIds}). Absent — a subform mounted with no field around
+		 * it — the properties fall back to `aria-label`, which names them without a
+		 * `for` target to click.
+		 */
+		idBase?: string;
+		/** Accessible-name prefix used only on the `aria-label` fallback above. */
+		label?: string;
+		/** Which strokes the subform draws; see the note above. */
+		edges?: 'band' | 'close';
 		onCommit: (obj: Record<string, unknown>) => void;
 	}
-	let { value, properties, label, labelledBy, describedBy, onCommit }: Props = $props();
+	let {
+		value,
+		properties,
+		labelledBy,
+		describedBy,
+		idBase,
+		label,
+		edges = 'band',
+		onCommit
+	}: Props = $props();
 
+	const t = wording();
 	const entries = $derived(Object.entries(properties ?? {}));
 	const obj = $derived((value ?? {}) as Record<string, unknown>);
 
+	/** Obligation, read off the cell exactly as `fieldModels` reads it off a field
+	 *  ({@link obliged}). `validate` anchors it per leaf, so a property with no
+	 *  `default:` is obliged in its own right and the container around it holds none
+	 *  (VISUAL_EDITOR §"Enum variants"). */
+	const required = obliged;
+
+	const title = (key: string, sub: QuillFieldSchema): string => sub.ui?.title ?? humanize(key);
+	/** The `aria-label` fallback, for a subform mounted without a field's id space:
+	 *  the field's name and the property's, since nothing else names the control. */
+	const fallbackName = (key: string, sub: QuillFieldSchema): string =>
+		`${label != null ? `${label} ` : ''}${title(key, sub)}` +
+		(required(sub) ? ` ${t.strings.fieldRequired}` : '');
+
 	/** 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
@@ -43,10 +95,19 @@
 	 * handle each would be five refs restating document order. An empty or wholly
 	 * unsupported subform lands nothing. */
 	let rootEl = $state<HTMLElement | undefined>();
+	const FOCUSABLE = 'input, select, button, [tabindex]:not([tabindex="-1"])';
 	export function focus(): void {
-		rootEl
-			?.querySelector<HTMLElement>('input, select, button, [tabindex]:not([tabindex="-1"])')
-			?.focus();
+		rootEl?.querySelector<HTMLElement>(FOCUSABLE)?.focus();
+	}
+	/** A label click for the one property `for` cannot reach: the date control, whose
+	 *  focus lives on a segment. Scoped to that property's own cell, so the click lands
+	 *  where the label is rather than on the subform's first control. */
+	function focusProp(key: string): void {
+		// Matched on the dataset: a key is the schema's own string, and spelling one into
+		// a selector needs `CSS.escape`, which the test DOM does not carry.
+		for (const cell of rootEl?.querySelectorAll<HTMLElement>('[data-qm-prop]') ?? []) {
+			if (cell.dataset.qmProp === key) return cell.querySelector<HTMLElement>(FOCUSABLE)?.focus();
+		}
 	}
 
 	function commitProp(key: string, v: unknown): void {
@@ -66,18 +127,38 @@
 <div
 	bind:this={rootEl}
 	class="qm-object"
+	class:close={edges === 'close'}
 	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)}`}
-		<div class="qm-object-prop">
-			<span class="qm-object-label">{sub.ui?.title ?? humanize(key)}</span>
+		{@const ids = idBase ? propertyDomIds(idBase, key) : undefined}
+		{@const named = ids ? undefined : fallbackName(key, sub)}
+		{@const describes = sub.description && ids ? ids.description : undefined}
+		<!-- `for` reaches the four labelable controls; the date field's focus lives on a
+		     segment, so it takes the click handoff instead, exactly as `Field` does one
+		     level up. -->
+		{@const labelable =
+			kind === 'text' || kind === 'enum' || kind === 'number' || kind === 'boolean'}
+		<div class="qm-object-prop" data-qm-prop={key}>
+			{#if ids}
+				<FieldLabel
+					label={title(key, sub)}
+					controlId={labelable ? ids.control : undefined}
+					id={ids.label}
+					descriptionId={describes}
+					onActivate={labelable ? undefined : () => focusProp(key)}
+					required={required(sub)}
+					description={sub.description}
+				/>
+			{/if}
 			{#if kind === 'enum'}
 				<EnumField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as string | undefined}
 					values={sub.values ?? []}
 					fallback={sub.default as string | undefined}
@@ -85,7 +166,9 @@
 				/>
 			{:else if kind === 'number'}
 				<NumberField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as number | undefined}
 					integer={sub.type === 'integer'}
 					fallback={sub.default as number | undefined}
@@ -93,54 +176,93 @@
 				/>
 			{:else if kind === 'boolean'}
 				<BooleanField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as boolean | undefined}
 					fallback={sub.default as boolean | undefined}
 					onCommit={(v) => commitProp(key, v)}
 				/>
 			{:else if kind === 'date'}
 				<DateField
-					label={propLabel}
+					label={named}
+					labelledBy={ids?.label}
+					describedBy={describes}
 					value={obj[key] as string | undefined}
 					onCommit={(v) => commitProp(key, v)}
 				/>
 			{:else if kind === 'text'}
 				<TextField
-					label={propLabel}
+					label={named}
+					id={ids?.control}
+					describedBy={describes}
 					value={obj[key] as string | undefined}
 					placeholder={sub.default != null ? String(sub.default) : undefined}
 					onCommit={(v) => commitProp(key, v)}
 				/>
 			{:else}
-				<span class="qm-unsupported">({kind} property — not editable in V1)</span>
+				<!-- A property the subform does not recurse into. What it says is what the
+				     user can do about it, which is edit the field from the source surface;
+				     a version number is the roadmap talking to somebody filling in a form. -->
+				<span class="qm-unsupported">{t.strings.nestedUnsupported(kind)}</span>
 			{/if}
 		</div>
 	{/each}
 </div>
 
 <style>
+	/* The band. `border-block` draws both strokes as one declaration, which is what
+	   makes the figure symmetric by construction rather than by two lines agreeing;
+	   `padding-block` at the same rung on both sides is the other half of that.
+
+	   `--_qm-border` and not `--_qm-border-faint`: this is the stroke that structures
+	   (ARCHITECTURE §"A plane is a tone"), the one the metadata bracket and the open
+	   section's vertical read. `faint` separates without structuring — a table's
+	   interior lines under a frame that is doing the structuring — which is the other
+	   job.
+
+	   The columns are the section's, arrived at by arithmetic rather than by `subgrid`:
+	   the band insets nothing horizontally, so this box spans exactly what `.qm-fields`
+	   spans, and equal tracks at the same count over the same width with the same column
+	   gap fall on the same edges. `subgrid` would want the tracks chained through the
+	   three wrappers between the section grid and here (`Field.svelte`), none of which is
+	   a grid. `--cols` inherits instead, so the container query stepping the section's
+	   capacity steps the subform's with it — no second query container, no second set of
+	   rungs, nothing measured. */
 	.qm-object {
-		display: flex;
-		flex-direction: column;
+		display: grid;
+		grid-template-columns: repeat(var(--cols), 1fr);
 		gap: var(--_qm-space-2);
-		border-left: var(--_qm-border-width) solid var(--_qm-border);
-		padding-left: var(--_qm-space-2);
+		border-block: var(--_qm-border-width) solid var(--_qm-border);
+		padding-block: var(--_qm-space-2);
+	}
+	/* Hanging off a control (a variant's discriminant, an array element's summary row):
+	   that box is the top boundary already, and a stroke under it would state the
+	   boundary twice. The closing rule is not optional in the same breath — without it
+	   the properties float between the box above and whatever follows. */
+	.qm-object.close {
+		border-block-start: none;
+		padding-block-start: 0;
 	}
+	/* A property measures like a field: two tracks over the subform's own rows, so a
+	   label wrapping in one column leaves its control on the row's baseline rather than a
+	   line below it — `Field.svelte`'s rule for a row-sharing field, one level in. The
+	   tracks are this grid's own; the section's belong to the fields.
+
+	   `min-width: 0` is what holds the arithmetic above: a property overflowing its `1fr`
+	   grows the track, and the subform's edges leave the section's with it. */
 	.qm-object-prop {
-		display: flex;
-		flex-direction: column;
-		gap: var(--_qm-space-half);
+		display: grid;
+		grid-row: span 2;
+		grid-template-rows: subgrid;
+		row-gap: var(--_qm-space-half);
+		align-items: start;
+		min-width: 0;
 	}
-	.qm-object-label {
-		font-size: var(--_qm-text-label);
-		/* 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);
-		color: var(--_qm-ink-label);
+	/* A subform of one takes half the capacity, the way a packable run of one does
+	   (`.qm-field.lone`): at full capacity a single track reads as truncated. */
+	.qm-object-prop:only-child {
+		grid-column: span var(--cols-half);
 	}
 	.qm-unsupported {
 		font-size: var(--_qm-text-body);

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

@@ -2,14 +2,23 @@ import type { QuillFieldSchema } from '@quillmark/wasm';
 interface Props {
     value: Record<string, unknown> | undefined;
     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
-     * `for` could reach, so the field's label names the set and each property
-     * control keeps its own composed `aria-label`. */
+     * `for` could reach, so the field's label names the set; each property carries
+     * its own `<label for>` inside it. */
     labelledBy?: string;
     /** The parked `description` (FieldLabel): announced on entering the group. */
     describedBy?: string;
+    /**
+     * The parent control's DOM id: the base each property's own three names derive
+     * from ({@link propertyDomIds}). Absent — a subform mounted with no field around
+     * it — the properties fall back to `aria-label`, which names them without a
+     * `for` target to click.
+     */
+    idBase?: string;
+    /** Accessible-name prefix used only on the `aria-label` fallback above. */
+    label?: string;
+    /** Which strokes the subform draws; see the note above. */
+    edges?: 'band' | 'close';
     onCommit: (obj: Record<string, unknown>) => void;
 }
 declare const ObjectField: import("svelte").Component<Props, {

package/dist/visual/ProseArrayElement.svelte

@@ -17,14 +17,16 @@
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
-	import { EditorState } from 'prosemirror-state';
+	import { EditorState, Selection } from 'prosemirror-state';
 	import { EditorView } from 'prosemirror-view';
 	import {
 		decode,
 		pmToContent,
 		inlineSchema,
 		plaintextSchema,
-		proseLeafPlugins
+		proseLeafPlugins,
+		buildLineIndex,
+		usvToPM
 	} from '../core/codec/index.js';
 	import './controls.css';
 	import type { Content } from '@quillmark/wasm';
@@ -61,6 +63,24 @@
 		view.focus();
 		view.dom.scrollIntoView({ block: 'nearest' });
 	}
+	/** Take the caret to USV `pos` in this element's own content: what a landing on an
+	 * element address resolves to when the compile answered a cluster-exact offset
+	 * (`leaves.ts`). `createField`'s body over the view this component owns.
+	 *
+	 * The index is built here rather than held: a landing is a discrete act, and one
+	 * doc walk per click is cheaper than a cache to invalidate per keystroke. `usvToPM`
+	 * clamps, so an offset past a value the compile has moved on from lands the end.
+	 *
+	 * `Selection.near`, not `TextSelection.create`: the mapped position can be
+	 * non-inline. Focus first, then the caret, flagged for scroll — the order and the
+	 * reasons are `FieldController.setCaret`'s (`codec/field.ts`). */
+	export function setCaret(pos: number): void {
+		if (!view) return;
+		const pm = usvToPM(buildLineIndex(view.state.doc), pos);
+		const sel = Selection.near(view.state.doc.resolve(pm));
+		view.focus();
+		view.dispatch(view.state.tr.setSelection(sel).scrollIntoView());
+	}
 
 	onMount(() => {
 		if (!containerEl) return;

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

@@ -19,6 +19,7 @@ interface Props {
 }
 declare const ProseArrayElement: import("svelte").Component<Props, {
     focus: () => void;
+    setCaret: (pos: number) => void;
 }, "">;
 type ProseArrayElement = ReturnType<typeof ProseArrayElement>;
 export default ProseArrayElement;

package/dist/visual/TipsCard.svelte

@@ -97,27 +97,34 @@
 	 paints over the rest. The two read as one block, which is what document-level
 	 guidance is: the main card's, not a card of its own. Still in-flow, no lift.
 
-	 It takes the card's hairline, and the tuck makes the two outlines one: the slip's top
-	 stroke and the tops of its sides run under `main`, so what shows starts at the card's
-	 bottom corners.
+	 No stroke of its own. A tint below the card reads as a slip; the same tint inside an
+	 outline reads as a second card, which is the one thing the tuck exists to deny. What
+	 shows below the seam is fill, and `main`'s hairline is the pair's only edge.
 
 	 The bottom corners take the inner rung where the card above takes the outer: a slip
 	 is cut crisper than the thing it is tucked under, at every setting of the dial.
 
-	 The insets are asymmetric so the ink is not: the top takes the tuck back, and the
-	 bottom gives up a rung to the foot's control, whose box stands on the tap floor
-	 rather than on its own one-line label. The horizontal is the card's inset plus the
-	 body's margin (ProseField), so the tip starts under the prose rather than under the
-	 fields. */
+	 Down, the insets are the document's own rhythm and they are measured to the ink, not
+	 to the boxes. The top is a block gap below the seam, what two of the body's paragraphs
+	 take, so the tip reads as the block after the prose; the bottom is the card's inset
+	 rung; and the foot sits at half of either, being the message's own foot rather than
+	 the next thing after it. The control gives its tap floor back as margin for that to
+	 hold: a box standing on the floor rather than on its one-line label carries a rung of
+	 slack at each edge, and spent inside the gap that is enough to make the tightest space
+	 in the card measure as the widest.
+
+	 Across, the inset is `main`'s stroke and the two nested insets under it, the card's
+	 own and the prose control's, so the tip starts on the prose's edge rather than short
+	 of it. */
 	.qm-tips {
 		margin-top: calc(var(--_qm-radius) * -1);
-		border: var(--_qm-border-width) solid var(--_qm-border);
 		border-radius: 0 0 var(--_qm-radius-inner) var(--_qm-radius-inner);
-		padding: calc(var(--_qm-space-3) + var(--_qm-radius)) var(--_qm-space-5) var(--_qm-space-2);
+		padding: calc(var(--_qm-space-3) + var(--_qm-radius))
+			calc(var(--_qm-border-width) + var(--_qm-space-3) * 2) var(--_qm-space-3);
 		background: var(--_qm-tips-surface);
 		display: flex;
 		flex-direction: column;
-		gap: var(--_qm-space-2);
+		gap: var(--_qm-space);
 		font-family: var(--_qm-tips-font);
 		font-size: var(--_qm-text-body);
 		line-height: var(--_qm-leading-body);
@@ -168,7 +175,11 @@
 	 the spacing one — the foot's button clears the floor and walks the whole set from
 	 the tip the card opens on, so no tip is reachable only by a dot. State is three
 	 steps of one ink on the recede ladder, never a second hue and never a size: a dot
-	 that grew would move the row it sits in. */
+	 that grew would move the row it sits in.
+
+	 `color` is restated because a button takes the UA's and not its parent's, so
+	 `currentColor` is the card's ink only once it is inherited; left to the UA it is
+	 `buttontext`, which is the one neutral on a card that carries no neutrals. */
 	.qm-tips-dot {
 		box-sizing: content-box;
 		width: 5px;
@@ -176,6 +187,7 @@
 		padding: var(--_qm-space-half);
 		border: none;
 		border-radius: var(--_qm-radius-pill);
+		color: inherit;
 		background: currentColor;
 		background-clip: content-box;
 		opacity: var(--_qm-opacity-idle);
@@ -192,8 +204,16 @@
 	   overrides is everything the family sets for a glyph among callers of its own
 	   colour, a labelled control on a warm card wanting none of it. The hover included:
 	   the family's neutral step would read as lent from the document above. Unlayered,
-	   so it beats the base rule without out-specifying it. */
+	   so it beats the base rule without out-specifying it.
+
+	   The box is the tap target and the label is what the rhythm measures, so both axes
+	   give the difference back as margin: the inline rung lands the label on the body's
+	   edge above, and the block rung takes the floor's slack out of the foot's height.
+	   The box, and the hover it paints, still reaches past the label the way a control
+	   does. */
 	.qm-tips-action {
+		margin-block: calc(var(--_qm-space) * -1);
+		margin-right: calc(var(--_qm-space-2) * -1);
 		padding: var(--_qm-space-half) var(--_qm-space-2);
 		font-family: inherit;
 		font-size: inherit;