@quillmark/svelte 0.12.0 → 0.13.0

package/dist/core/codec/schema.d.ts

@@ -7,8 +7,8 @@ export declare const blockSchema: Schema<string, string>;
  *  a table cell, which is the same content unit). */
 export declare const inlineSchema: Schema<string, string>;
 /**
- * The inline schema with no mark types at all: a `plaintext` field, whose value is
- * literal text the boundary refuses to coerce back once it carries a mark.
+ * The inline schema with no mark types at all: a `plaintext(inline)` field, whose
+ * value is literal text the boundary refuses to coerce back once it carries a mark.
  *
  * Declaring none is what makes that structural rather than a rule each path
  * restates: `toggleMark` has no type to apply, the mark input rules build nothing,
@@ -16,11 +16,30 @@ export declare const inlineSchema: Schema<string, string>;
  * carrying (CODEC §Inline mode).
  */
 export declare const plaintextSchema: Schema<string, never>;
-/** Whether `schema` can carry formatting at all: false for {@link plaintextSchema}
- *  alone. What a mark command asks before it offers itself. */
+/**
+ * A `plaintext` field without `inline`: paragraphs and hard breaks, no marks, no
+ * islands, no containers, which is the shape `Content::is_plain` admits. Mark-free
+ * for the reason {@link plaintextSchema} is.
+ *
+ * A paragraph and a break both store one `\n`, so a paragraph here is a line and
+ * says so (`data-qm-line`): `prose.css` draws a run of them at the leading, and a
+ * boundary reads as the one line down that a break does.
+ */
+export declare const plainSchema: Schema<"text" | "doc" | "paragraph" | "hard_break", never>;
+/** The schema a leaf of the declared type mounts: `inline` narrows either type to one
+ *  textblock, and `plaintext` takes its marks away. */
+export declare function leafSchema(opts: {
+    plaintext?: boolean;
+    inline?: boolean;
+}): Schema;
+/** Whether `schema` can carry formatting at all: false for the two plaintext schemas.
+ *  What a mark command asks before it offers itself. */
 export declare function hasMarks(schema: Schema): boolean;
-/** True for the constrained inline schema (no block containers); decode branches on it. */
+/** True for the one-line schemas, which declare no `hard_break`; decode branches on it. */
 export declare function isInlineSchema(schema: Schema): boolean;
+/** True for {@link blockSchema}, the one holding blocks past the paragraph: what a
+ *  leaf's island, gap-cursor and slash machinery mounts on. */
+export declare function isBlockSchema(schema: Schema): boolean;
 /** Whether `type` can hold a within-block line break, which a heading cannot (§`heading`).
  *  What a `\n` landing in a textblock is rewritten to turns on it (`breaks.ts`), and so
  *  does what decode puts between a block's continued segments. */

package/dist/core/codec/schema.js

@@ -4,9 +4,10 @@
 // Each set is closed upstream, so the schema names its whole vocabulary and carries
 // nothing inert. `blockSchema` is the full field; `inlineSchema` is the constrained
 // single-textblock form for `richtext(inline)` (one paragraph, no block split, no
-// containers, no islands) and `plaintextSchema` is that one without marks: same
-// decode/lower/position machinery, narrower shape. Anchors are not marks here
-// (decorations).
+// containers, no islands) and `plaintextSchema` is that one without marks, for
+// `plaintext(inline)`; `plainSchema` is a `plaintext` field without `inline`,
+// paragraphs and hard breaks and nothing else. Same decode/lower/position machinery,
+// narrower shapes. Anchors are not marks here (decorations).
 //
 // `toDOM` and `parseDOM` are one tier, not two halves of a rendering: a copy and a
 // paste inside one body run the whole document through them (CODEC §"Markdown at the
@@ -188,8 +189,8 @@ const inlineNodes = {
  *  a table cell, which is the same content unit). */
 export const inlineSchema = new Schema({ nodes: inlineNodes, marks });
 /**
- * The inline schema with no mark types at all: a `plaintext` field, whose value is
- * literal text the boundary refuses to coerce back once it carries a mark.
+ * The inline schema with no mark types at all: a `plaintext(inline)` field, whose
+ * value is literal text the boundary refuses to coerce back once it carries a mark.
  *
  * Declaring none is what makes that structural rather than a rule each path
  * restates: `toggleMark` has no type to apply, the mark input rules build nothing,
@@ -197,14 +198,44 @@ export const inlineSchema = new Schema({ nodes: inlineNodes, marks });
  * carrying (CODEC §Inline mode).
  */
 export const plaintextSchema = new Schema({ nodes: inlineNodes, marks: {} });
-/** Whether `schema` can carry formatting at all: false for {@link plaintextSchema}
- *  alone. What a mark command asks before it offers itself. */
+/**
+ * A `plaintext` field without `inline`: paragraphs and hard breaks, no marks, no
+ * islands, no containers, which is the shape `Content::is_plain` admits. Mark-free
+ * for the reason {@link plaintextSchema} is.
+ *
+ * A paragraph and a break both store one `\n`, so a paragraph here is a line and
+ * says so (`data-qm-line`): `prose.css` draws a run of them at the leading, and a
+ * boundary reads as the one line down that a break does.
+ */
+export const plainSchema = new Schema({
+    nodes: {
+        doc: { content: 'paragraph+' },
+        paragraph: { ...blockNodes.paragraph, toDOM: () => ['p', { 'data-qm-line': '' }, 0] },
+        text: inlineLeafNodes.text,
+        hard_break: inlineLeafNodes.hard_break
+    },
+    marks: {}
+});
+/** The schema a leaf of the declared type mounts: `inline` narrows either type to one
+ *  textblock, and `plaintext` takes its marks away. */
+export function leafSchema(opts) {
+    if (opts.plaintext)
+        return opts.inline ? plaintextSchema : plainSchema;
+    return opts.inline ? inlineSchema : blockSchema;
+}
+/** Whether `schema` can carry formatting at all: false for the two plaintext schemas.
+ *  What a mark command asks before it offers itself. */
 export function hasMarks(schema) {
     return Object.keys(schema.marks).length > 0;
 }
-/** True for the constrained inline schema (no block containers); decode branches on it. */
+/** True for the one-line schemas, which declare no `hard_break`; decode branches on it. */
 export function isInlineSchema(schema) {
-    return !schema.nodes.blockquote;
+    return !schema.nodes.hard_break;
+}
+/** True for {@link blockSchema}, the one holding blocks past the paragraph: what a
+ *  leaf's island, gap-cursor and slash machinery mounts on. */
+export function isBlockSchema(schema) {
+    return !!schema.nodes.blockquote;
 }
 /** Whether `type` can hold a within-block line break, which a heading cannot (§`heading`).
  *  What a `\n` landing in a textblock is rewritten to turns on it (`breaks.ts`), and so

package/dist/core/errors.d.ts

@@ -11,8 +11,9 @@ export type EditorErrorCode =
  *  the whole projection instead, so the store is correct and this field's
  *  identity anchors were paid. */
  | 'commit-fallback'
-/** The overwrite fallback also failed: the optimistic PM state stands and the
- *  store is stale for this field. The one code here that leaves damage. */
+/** The overwrite fallback also failed, or the typed writer refused a `plaintext`
+ *  leaf's text: the optimistic PM state stands and the store is stale for this
+ *  field. The one code here that leaves damage. */
  | 'commit-lost'
 /** A card operation (add, move, remove, retype) that threw. The document is
  *  unchanged; the boundary's mutators are transactional. */

package/dist/core/theme.css

@@ -163,13 +163,16 @@
 	   relationship at any mix: a stroke against the surface behind it, not a fill
 	   stacked on one. */
 	--_qm-border-faint: color-mix(in oklab, var(--_qm-bg), var(--_qm-border) 50%);
-	/* Two rungs, and there is no third: a step below `label` lands under 3:1 on the
-	   well a field draws it against, and what would take it — a placeholder, an
-	   unset value, the resolved `default:` — is content a reader has to read
-	   (WCAG 1.4.3), not decoration. So tone carries hierarchy alone, and a leaf
-	   saying shown-never-written says it against the `ink` a written value takes,
-	   in italic where it has no written neighbour to be read against. */
+	/* Three rungs, and nothing under the last: a step below `label` lands under 3:1 on
+	   the well a field draws it against, and what would take it — an example, an unset
+	   value's word — is content a reader has to read (WCAG 1.4.3), not decoration.
+	   `ink` is written. `default` is the resolved `default:` drawn as the value it
+	   prints: near enough to `ink` to read as an answer, a step off it so it never
+	   reads as a written one. `label` is words about a value rather than the value — an
+	   `example:`, `None`, a format hint — and the chrome that names fields; in italic
+	   where it is a leaf's ghost, which has no written neighbour to be read against. */
 	--_qm-ink: var(--_qm-fg);
+	--_qm-ink-default: color-mix(in oklab, var(--_qm-fg), var(--_qm-bg) 20%);
 	--_qm-ink-label: color-mix(in oklab, var(--_qm-fg), var(--_qm-bg) 35%);
 	/* The arrival wash (`core/bloom.ts`). Its alpha is a peak, not a tint: the
 	   wash animates from and back to zero, never held, so it reads over the leaf it

package/dist/preview/paint.js

@@ -1,6 +1,11 @@
 // Vertical breathing room between stacked pages; cosmetic only, and a rung like
 // any other gap: the stack breathes on the same rhythm the cards do.
 const PAGE_GAP = 'var(--_qm-space-4)';
+// The least raster density, in device pixels per CSS pixel. Glyphs rasterize
+// unhinted, so a raster at a 1× or fractional ratio (1.25, 1.5; browser zoom)
+// is resampled nearly 1:1 and small text smears; a raster at least twice the
+// box is downsampled instead, which keeps body text legible.
+const MIN_DENSITY = 2;
 export function createPaintLoop(session, container, margin, 
 // Notified when a slot's `session.paint` throws: the loop swallows the throw
 // (see `paintSlot`) so one bad page never aborts the band sweep; the caller
@@ -65,16 +70,19 @@ onPaintError) {
         return { page, size, el };
     }
     // Rasterize `slot` into its canvas (creating the canvas if this is its first
-    // paint since mounting). `layoutScale` is derived from the slot's own current
-    // CSS width, so layout width tracks the container per the zoom settled
-    // decision; `canvas.style.*` is then set from the authoritative PaintResult,
-    // never guessed.
+    // paint since mounting), at the slot's own current CSS width.
     function paintSlot(slot) {
         let canvas = canvases.get(slot.page);
         if (!canvas) {
             canvas = document.createElement('canvas');
             canvas.className = 'qm-page-canvas';
-            Object.assign(canvas.style, { position: 'absolute', inset: '0', display: 'block' });
+            Object.assign(canvas.style, {
+                position: 'absolute',
+                inset: '0',
+                display: 'block',
+                width: '100%',
+                height: '100%'
+            });
         }
         // Contextless canvas: bail before registering, so `updateBand` still sees
         // the page as unmounted and retries instead of keeping a blank page.
@@ -86,11 +94,9 @@ onPaintError) {
             canvases.set(slot.page, canvas);
         }
         const layoutScale = (slot.el.clientWidth || slot.size.widthPt) / slot.size.widthPt;
-        const densityScale = (window.devicePixelRatio || 1) * zoom;
+        const densityScale = Math.max(window.devicePixelRatio || 1, MIN_DENSITY) * zoom;
         try {
-            const result = session.paint(ctx, slot.page, { layoutScale, densityScale });
-            canvas.style.width = `${result.layoutWidth}px`;
-            canvas.style.height = `${result.layoutHeight}px`;
+            session.paint(ctx, slot.page, layoutScale * densityScale);
         }
         catch (err) {
             // A paint that throws must not abort the band loop; `updateBand` runs in
@@ -162,14 +168,12 @@ onPaintError) {
     // Slots are built on the first `refresh` (the controller calls it immediately),
     // not here: reconcile → `session.pageSize` must run after the controller's
     // `pageCount` gate, since `pageSize` throws for a page the count excludes.
-    // ── Keep mounted rasters in step with the display ───────────────────────────
-    // Every paint freezes `canvas.style.width/height` to the box width at that
-    // paint (paintSlot). A page that stays mounted while the container's CSS width
-    // or `devicePixelRatio` shifts would otherwise keep a stale raster the %-space
-    // click/scroll math silently drifts off of: the box tracks the container, the
-    // ink does not. Two observers close the gap by repainting mounted pages from
-    // their current box; canvases are `position:absolute`, so a repaint can't feed
-    // back into layout (and thus can't re-trigger the resize observer).
+    // ── Keep mounted rasters sharp ──────────────────────────────────────────────
+    // A canvas stretches with its slot, so a page that stays mounted while the
+    // container's CSS width or `devicePixelRatio` shifts keeps its place and goes
+    // soft. Two observers repaint mounted pages from their current box; canvases
+    // are `position:absolute`, so a repaint can't feed back into layout (and thus
+    // can't re-trigger the resize observer).
     // Repaint mounted pages (all, or a given subset) from their live geometry: the
     // one path resize, DPR, and zoom share; each `paintSlot` re-reads the slot's
     // current `clientWidth`. A no-op for an unmounted page.

package/dist/visual/ArrayField.svelte

@@ -12,9 +12,9 @@
  neither a screen reader nor a touch user, and the count is the carrier.
 
  An `object` element collapses: the row is its own summary — a box, titled by the
- row's `items.ui.title` template or its first short text cell ({@link rowSummary}) —
- and opens onto {@link ObjectField}, one at a time. Stacking the subforms instead would
- nest a field one level past the depth the subform's own vertical draws, once per row.
+ row's first short text cell ({@link rowSummary}) — and opens onto {@link ObjectField},
+ one at a time. Stacking the subforms instead would nest a field one level past the
+ depth the subform's own vertical draws, once per row.
  Opening is therefore part of a landing rather than something the user does first:
  `focusPath` opens the row it is aimed at before it focuses, and hands the rest of the
  walk to the subform it opened, which is how a row two closed boxes down is reached.
@@ -45,6 +45,13 @@
  and of the values together, the mechanism insert and remove use, so an element keeps
  its id for life and no prose leaf inside it remounts; the open row stays open across
  its own move, and `animate:reorder` holds the moving row as it holds a card.
+
+ An unset array whose `default:` holds elements draws them as its rows, at the default
+ rung (`data-default` on the rows' box), since they are what prints. The rows are the
+ declared literal rather than resolve's form, which completes a record against `items`:
+ every gesture — an edit in a row, Enter, a remove, a move, the add chip — commits the
+ whole array with the change in it, and a take writes only what the author declared.
+ Removing the last row commits `[]`, the empty answer.
 -->
 <script lang="ts">
 	import { wording } from './strings.js';
@@ -58,10 +65,13 @@
 	import { createLifespan } from '../core/teardown.js';
 	import {
 		IdSeq,
+		baseType,
 		controlKind,
+		declaredContent,
 		humanize,
 		obliged,
 		rowSummary,
+		schemaAt,
 		type ArrayLayout
 	} from './structure.js';
 	import { splitDeep, unrouted, type DeepDiagnostic } from './diagnostics.js';
@@ -82,6 +92,8 @@
 
 	interface Props {
 		value: unknown[] | undefined;
+		/** The declared `default:`: the rows an unset array draws, which a gesture takes. */
+		fallback?: unknown[];
 		items: QuillFieldSchema | undefined;
 		/** How the elements draw: the record list, or the table an `array<object>` of
 		 * short cells asks for (`arrayLayout`). */
@@ -121,6 +133,7 @@
 	}
 	let {
 		value,
+		fallback,
 		items,
 		layout = 'list',
 		max,
@@ -142,7 +155,17 @@
 	const control = $derived(items ? controlKind(items) : 'text');
 	const table = $derived(layout === 'table' && control === 'object');
 	const columns = $derived(Object.entries(items?.properties ?? {}));
-	const arr = $derived((value ?? []) as unknown[]);
+	const defaulted = $derived(value == null && (fallback?.length ?? 0) > 0);
+	const arr = $derived((value ?? fallback ?? []) as unknown[]);
+	/** The rows' content read: the boundary's, or, while the rows are the default, the
+	 *  literal's own leaf at the codec its declared type names. */
+	function readAt(path: PathStep[]): Content | undefined {
+		if (!defaulted) return contentAt(path);
+		const leaf = schemaAt({ type: 'array', items }, path);
+		let v: unknown = arr;
+		for (const step of path) v = (v as Record<string | number, unknown> | undefined)?.[step];
+		return leaf ? declaredContent(v, baseType(leaf) === 'richtext') : undefined;
+	}
 	const atCap = $derived(max != null && arr.length >= max);
 	const routed = $derived(splitDeep(diagnostics));
 	const foot = $derived(
@@ -154,7 +177,7 @@
 	// an effect-only seed mounts every element editor in a second render.
 	const seq = new IdSeq();
 	// svelte-ignore state_referenced_locally
-	let ids = $state<string[]>(seq.take((value ?? []).length));
+	let ids = $state<string[]>(seq.take((value ?? fallback ?? []).length));
 	// Length reconcile (defend against an out-of-band length change);
 	// order is maintained by the mutators, not here.
 	$effect(() => {
@@ -239,8 +262,7 @@
 	// one, else this instance's own.
 	const uid = $props.id();
 	const countId = $derived(`${idBase ?? `qm-${uid}`}-count`);
-	const columnTitle = (key: string, sub: QuillFieldSchema): string =>
-		sub.ui?.title ?? humanize(key);
+	const columnTitle = (key: string, sub: QuillFieldSchema): string => sub.title ?? humanize(key);
 
 	// The awaited flush below is the only work that outlives a gesture here, so the
 	// span carries the reorder's frame and nothing else: it is the liveness
@@ -444,14 +466,14 @@
 		if (v === undefined || v === '') return true;
 		return typeof v === 'object' && v !== null && 'text' in v && (v as Content).text === '';
 	}
-	/** Whether element `k` reads empty to the user. A text element's committed value
-	 * lags the input: a cleared field commits at `change`, not per keystroke
-	 * ({@link TextField}); so the input's own value is the truth. A prose element
-	 * commits every edit, so the committed `Content` is; an authored string, the
-	 * transport-door rest, is empty when it has no characters. A table's row is empty
-	 * when the cell under the caret is and so is every cell beside it — beside, because
-	 * the caret's own committed value is the one that lags, and counting it twice would
-	 * hold the row full until a blur. */
+	/** Whether element `k` reads empty to the user. A text element's input is the truth,
+	 * being the control the keystroke lands in. A prose element commits every edit, so
+	 * the committed `Content` is; an authored string, the transport-door rest, is empty
+	 * when it has no characters. A table's row is empty when the cell under the caret is
+	 * and so is every cell beside it, read off the row: a cell showing only its schema
+	 * default holds nothing written, as in a row just added. The caret's cell is read off
+	 * its control, which a default the cell holds unwritten leaves full while the
+	 * committed row has no key. */
 	function elementEmpty(k: number, target: EventTarget | null, column?: string): boolean {
 		if (control === 'prose') {
 			const el = arr[k];
@@ -556,7 +578,12 @@
 	<!-- Three lists, one per row shape, because `animate:` is granted only to a keyed
 	     each block's one child: a branch inside the block would stand between them. -->
 	{#if table}
-		<div class="qm-array-rows qm-array-table" class:empty={ids.length === 0} bind:this={rowsEl}>
+		<div
+			class="qm-array-rows qm-array-table"
+			class:empty={ids.length === 0}
+			data-default={defaulted ? '' : undefined}
+			bind:this={rowsEl}
+		>
 			<div class="qm-array-table-scroller" style:--table-cols={columns.length}>
 				<!-- The header names the columns, so a cell carries no label of its own: its
 				     accessible name is the row's and the column's composed (`ObjectField`). The
@@ -582,7 +609,7 @@
 							value={(arr[k] ?? {}) as Record<string, unknown>}
 							properties={items?.properties}
 							label={rowName(k)}
-							contentAt={(path) => contentAt([k, ...path])}
+							contentAt={(path) => readAt([k, ...path])}
 							onCommit={(obj) => commitElement(k, obj)}
 							onCellKey={(e, column) => onElementKey(e, k, column)}
 							diagnostics={routed.below.get(k)}
@@ -593,7 +620,12 @@
 			</div>
 		</div>
 	{:else if control === 'object'}
-		<div class="qm-array-rows" class:empty={ids.length === 0} bind:this={rowsEl}>
+		<div
+			class="qm-array-rows"
+			class:empty={ids.length === 0}
+			data-default={defaulted ? '' : undefined}
+			bind:this={rowsEl}
+		>
 			{#each ids as id, k (id)}
 				<!-- svelte-ignore a11y_no_static_element_interactions -->
 				<!-- The handler catches a key from the controls inside the row and adds no
@@ -637,7 +669,7 @@
 							properties={items?.properties}
 							label={rowName(k)}
 							idBase={idBase != null ? `${idBase}-e-${id}` : undefined}
-							contentAt={(path) => contentAt([k, ...path])}
+							contentAt={(path) => readAt([k, ...path])}
 							onCommit={(obj) => commitElement(k, obj)}
 							diagnostics={routed.below.get(k)}
 						/>
@@ -650,14 +682,19 @@
 			{/each}
 		</div>
 	{:else}
-		<div class="qm-array-rows" class:empty={ids.length === 0} bind:this={rowsEl}>
+		<div
+			class="qm-array-rows"
+			class:empty={ids.length === 0}
+			data-default={defaulted ? '' : undefined}
+			bind:this={rowsEl}
+		>
 			{#each ids as id, k (id)}
 				<div class="qm-array-row" bind:this={rowEls[id]}>
 					{#if control === 'prose'}
 						<ProseValue
 							bind:this={els[id]}
-							content={() => contentAt([k]) ?? emptyContent()}
-							plaintext={items?.type === 'plaintext'}
+							content={() => readAt([k])}
+							plaintext={items != null && baseType(items) === 'plaintext'}
 							label={rowName(k)}
 							onChange={(rt) => commitElement(k, rt)}
 							onKey={(e) => onElementKey(e, k)}
@@ -762,6 +799,13 @@
 	.qm-array-rows.empty {
 		display: none;
 	}
+	/* The default's rows are what prints and nothing written: every value they draw takes
+	   the default rung (theme.css), and the first gesture, writing them, takes it off. */
+	.qm-array-rows[data-default] :global(:is(.qm-input, .ProseMirror, .qm-date)),
+	.qm-array-rows[data-default] :global(.qm-select:not([data-ghosted])),
+	.qm-array-rows[data-default] .qm-element-title:not(.untitled) {
+		color: var(--_qm-ink-default);
+	}
 	/* A grid rather than a block: an `<input>` is inline-level and would sit on a
 	 baseline, standing the row a descender taller than the box the slab measures itself
 	 against. `minmax(0, …)` because a long unbroken value grows an `auto` track, and the

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

@@ -5,6 +5,8 @@ import type { LandingBox } from './leaves.js';
 import './controls.css';
 interface Props {
     value: unknown[] | undefined;
+    /** The declared `default:`: the rows an unset array draws, which a gesture takes. */
+    fallback?: unknown[];
     items: QuillFieldSchema | undefined;
     /** How the elements draw: the record list, or the table an `array<object>` of
      * short cells asks for (`arrayLayout`). */

package/dist/visual/BooleanField.svelte

@@ -4,6 +4,12 @@
  Styled rather than a native checkbox: the native box's face is UA-owned shadow
  DOM, so no dial reaches it. The a11y comes with the primitive:
  Switch.Root renders `role="switch"` with its checked state and keyboard handling.
+
+ An unset `boolean?` prints `none`, which neither face of a switch says, so it draws a
+ third: the thumb at the track's centre. `role="switch"` admits no third state (a
+ `mixed` there reads as false), so an optional boolean's control is a `checkbox`, the
+ toggle role that does, announcing `mixed` while unset. A press from unset writes
+ `true`; nothing here returns the cell to unset.
 -->
 <script lang="ts">
 	import { Switch } from 'bits-ui';
@@ -13,6 +19,8 @@
 	interface Props {
 		value: boolean | undefined;
 		fallback?: boolean;
+		/** A `boolean?` cell, which has a third state: unset, printing `none`. */
+		optional?: boolean;
 		/** Accessible name for a switch nothing else names: an object property, whose
 		 * name is the field label plus the property's. A field's own switch takes `id`
 		 * instead and is named by the `<label for>` beside it. */
@@ -26,32 +34,42 @@
 		describedBy?: string;
 		onCommit: (v: boolean) => void;
 	}
-	let { value, fallback, label, id, describedBy, onCommit }: Props = $props();
+	let { value, fallback, optional = false, label, id, describedBy, onCommit }: Props = $props();
 
 	// Local toggle state synced to `value`; own-toggles stay local, only an external
 	// change reconciles back in (see `syncedLocal`). The primitive is driven
 	// controlled (`checked` + `onCheckedChange`, never `bind:`) so reconciliation
 	// stays the package's: a two-way bind hands the primitive a lane around it,
-	// which repeats the reconciliation hazard in miniature.
-	const local = syncedLocal(() => value ?? fallback ?? false);
+	// which repeats the reconciliation hazard in miniature. `undefined` is the unset
+	// optional cell, the one state with no default to stand in for it.
+	const local = syncedLocal<boolean | undefined>(
+		() => value ?? fallback ?? (optional ? undefined : false)
+	);
+	const unset = $derived(local.value === undefined);
+	const tristate = $derived(
+		optional ? { role: 'checkbox', 'aria-checked': unset ? ('mixed' as const) : !!local.value } : {}
+	);
 </script>
 
 <!-- Not `.qm-switch`: that name is the preset's pane band, whose narrow-viewport rule
  stands every child of it at `--qmh-tap`, so a track wearing it grows a thumb three times
  its own height over the labels around it (`preset/recipes.css`, held by `check:style`). -->
-<span class="qm-toggle-wrap">
+<span class="qm-toggle-wrap" data-unset={unset ? '' : undefined}>
 	<Switch.Root
 		class="qm-toggle qm-focus-ring qm-tap-floor"
-		checked={local.value}
+		checked={!!local.value}
 		{id}
 		aria-label={id ? undefined : label}
 		aria-describedby={describedBy}
 		onCheckedChange={(v) => {
+			// From unset the primitive reads the unchecked face, so its toggle is `true`.
 			local.value = v;
 			onCommit(v);
 		}}
 	>
-		<Switch.Thumb class="qm-toggle-thumb" />
+		{#snippet child({ props })}
+			<button {...props} {...tristate}><Switch.Thumb class="qm-toggle-thumb" /></button>
+		{/snippet}
 	</Switch.Root>
 </span>
 
@@ -95,4 +113,8 @@
 	.qm-toggle-wrap :global(.qm-toggle-thumb[data-state='checked']) {
 		translate: 0.75rem;
 	}
+	/* Unset, the thumb stands at neither end: halfway along its travel. */
+	.qm-toggle-wrap[data-unset] :global(.qm-toggle-thumb) {
+		translate: 0.375rem;
+	}
 </style>

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

@@ -2,6 +2,8 @@ import './controls.css';
 interface Props {
     value: boolean | undefined;
     fallback?: boolean;
+    /** A `boolean?` cell, which has a third state: unset, printing `none`. */
+    optional?: boolean;
     /** Accessible name for a switch nothing else names: an object property, whose
      * name is the field label plus the property's. A field's own switch takes `id`
      * instead and is named by the `<label for>` beside it. */

package/dist/visual/Card.svelte

@@ -15,7 +15,7 @@
 	import type { EditorErrorHandler } from '../core/errors.js';
 	import type { LeafRegistry } from './leaves.js';
 	import type { CardModel, FieldModel } from './structure.js';
-	import { placeFields, humanize, initialExpandedGroup } from './structure.js';
+	import { placeFields, humanize, initialExpandedGroup, kindTitle, mountKey } from './structure.js';
 	import { holdInView } from './hold.js';
 	import type { FieldDomIds } from './domid.js';
 	import Field from './Field.svelte';
@@ -333,7 +333,7 @@
 
 {#snippet sectionFields(fields: FieldModel[])}
 	<div class="qm-fields qm-tracks">
-		{#each placeFields(fields) as { field: f, span } (f.name)}
+		{#each placeFields(fields) as { field: f, span } (mountKey(f.name, f.schema))}
 			<Field
 				field={f}
 				{span}
@@ -402,7 +402,7 @@
 
 {#snippet kindOptions()}
 	{#each kinds as k (k)}
-		<option value={k}>{humanize(k)}</option>
+		<option value={k}>{kindTitle(quill.schema.card_kinds?.[k], k)}</option>
 	{/each}
 {/snippet}