@quillmark/svelte 0.4.3 → 0.5.1

package/README.md

@@ -81,7 +81,7 @@ const preview = createPreview(session, {
 preview.refresh(session.update(doc)); // repaint dirtyPages ∩ visible
 ```
 
-In Svelte, `<Preview {session} onPick={…} />` exposes the same verbs (`refresh`, `scrollToField`, `focusPosition`, `setZoom`) via `bind:this`.
+In Svelte, `<Preview {session} onPick={…} />` exposes the same verbs (`refresh`, `scrollToField`, `focusPosition`, `endFollow`, `setZoom`) via `bind:this`.
 
 `<Preview>` binds **once**, at mount: swapping `session`, `margin`, `onPick`, `onError` or `strings` in place changes nothing on screen and reports `rebind-ignored` through `onError` at `dev` severity, naming the prop. Swap by remounting (`{#key session}`); drive in-place edits through `refresh(change)`. `class` and `style` are the exceptions, landing on the root element and staying live.
 
@@ -152,7 +152,7 @@ The package ships English and a seam to replace it. `strings` is keyed and **par
 		addCard: '+ Ajouter une carte'
 	}}
 	formatDiagnostic={(d) =>
-		d.code === 'validation::must_fill' ? `${d.path} est obligatoire` : undefined}
+		d.code === 'validation::type_mismatch' ? `${d.path} : type incorrect` : undefined}
 />
 ```
 
@@ -184,7 +184,7 @@ function recompileNow() {
 }
 ```
 
-`session.warnings` is a **getter on a handle Svelte does not track**: pull it per apply, or the editor shows the previous compile's diagnostics.
+`session.warnings` is a **getter on a handle Svelte does not track**: pull it per apply, or the editor shows the previous compile's errors.
 
 This shell layer is deliberately yours: the debounce value, what applies at once, and which surfaces refresh are host policy, so the package ships no scheduler over them. Three obligations ride with that: an edit of your own (an import, an undo, a direct `doc` write) recompiles by the same calls, since nothing polls the document; a compile owes the diagnostics re-read above, since nothing polls the session; and teardown clears the timer **before** freeing the handles, so a pending recompile never touches a freed session.
 
@@ -196,10 +196,14 @@ The bridge lives at the **consumer** layer and is opt-in; the editor is unaware
 // preview → editor: a click resolved to an address lands in the field it names.
 onPick: (at) => visualEditor.setCaret(at);
 
-// editor → preview: a caret move scrolls the preview to follow it.
+// editor → preview: a caret move scrolls the preview to follow it,
+// and a focus into a leaf with no caret to report ends the follow.
 onCaretMove: preview.focusPosition;
+onActiveLeafChange: preview.endFollow;
 ```
 
+Both editor→preview hops or neither. A control reports its focus and no caret — there is no offset a date field could name — so without the second the preview keeps following the leaf the focus left, and every recompile pulls the pane back to it. A prose leaf restarts the follow with its next caret. A host that reads the active leaf for its own chrome calls `endFollow` from its handler.
+
 A pick carries a caret where the compile tracks the content under the point, and the field alone where it tracks only the placement — a scalar the plate prints without tracking. `setCaret` takes both: an absent `pos` reveals and focuses the field, which is the whole of what a click on plate-placed ink can mean. The address may name an array element (`main.keywords[0]`), which lands on that row.
 
 A consumer holding an `Addr` of its own maps it with `fieldPathForAddr` (from `@quillmark/svelte/core`). The playground app's split-pane route is the full reference shell: one session, both bridge directions, the preview following edits, and diagnostics routed inline.

package/THEMING.md

@@ -4,11 +4,11 @@
 
 There are three depths to that. An app mounting into an unstyled page stops at the first; an app with a plate of its own starts at the second:
 
-|                   | You write             | You get                                                 |
-| ----------------- | --------------------- | ------------------------------------------------------- |
-| **Drop it in**    | nothing               | a mounted surface that looks right in a bare `<div>`    |
-| **Make it yours** | ten custom properties | the whole surface rescaled and recolored to your brand  |
-| **Match ours**    | one CSS import        | the page around the surface, drawn the way we draw ours |
+|                   | You write              | You get                                                 |
+| ----------------- | ---------------------- | ------------------------------------------------------- |
+| **Drop it in**    | nothing                | a mounted surface that looks right in a bare `<div>`    |
+| **Make it yours** | nine custom properties | the whole surface rescaled and recolored to your brand  |
+| **Match ours**    | one CSS import         | the page around the surface, drawn the way we draw ours |
 
 ## Drop it in
 
@@ -28,7 +28,7 @@ Nothing to import and nothing to set. The package pulls its own stylesheet, and
 
 ## Make it yours
 
-The whole contract is **ten CSS custom properties**. They are dials, not a palette: each derives a closed private scale that every component reads, so one override rescales or recolors the whole surface. Set them on any ancestor of a mounted surface (the app, or one pane):
+The whole contract is **nine CSS custom properties**. They are dials, not a palette: each derives a closed private scale that every component reads, so one override rescales or recolors the whole surface. Set them on any ancestor of a mounted surface (the app, or one pane):
 
 ```css
 .my-editor {
@@ -54,8 +54,7 @@ The poles take a colour, not `transparent` or `inherit`: the raised surfaces, th
 | `--qm-bg`        | `#fff` / `#272729`                     | Base surface: a card, and the preview's sheet. Fields, the popover and the column behind the cards each step off it.                                           |
 | `--qm-fg`        | `#1c1c1c` / `#d7dadc`                  | Base ink. Body text, labels, and borders step off it.                                                                                                          |
 | `--qm-accent`    | `#71717a` / `#a1a1aa`                  | Focus rings, active marks, the preview's active field box. The surface spends no hue of its own, so this is the one it wears.                                  |
-| `--qm-danger`    | `#c5221f` / `#ff9c94`                  | Error diagnostics, the required marker, the delete glyph.                                                                                                      |
-| `--qm-warning`   | `#b25000` / `#e0b44c`                  | Warning diagnostics.                                                                                                                                           |
+| `--qm-danger`    | `#9e1518` / `#f9786c`                  | Error diagnostics, the required marker, the delete glyph.                                                                                                      |
 | `--qm-font`      | `ui-sans-serif, system-ui, sans-serif` | The editor surface's font family. Controls and buttons take it too, in place of the UA face.                                                                   |
 | `--qm-font-mono` | `ui-monospace, monospace`              | The monospace face: the JSON array control, the tips card.                                                                                                     |
 | `--qm-font-size` | `0.875rem`                             | Chrome text: every control's size, the anchor the ramp derives up (title) and down (label/meta) from, and the anchor a document body sits one small step over. |
@@ -106,9 +105,9 @@ Setting the poles yourself wins over the default in both schemes, so a fixed pal
 }
 ```
 
-That cuts both ways for the status hues: `--qm-danger` and `--qm-warning` each default to a pair calibrated against the card at both poles, and one pinned value replaces both arms, so a red measured against white carries into the dark scheme unmeasured. Pin them under your own scheme rule (`.dark { --qm-danger: … }`) where the colour your app means by error is itself scheme-aware.
+That cuts both ways for the status hue: `--qm-danger` defaults to a pair calibrated against the card at both poles, and one pinned value replaces both arms, so a red measured against white carries into the dark scheme unmeasured. Pin it under your own scheme rule (`.dark { --qm-danger: … }`) where the colour your app means by error is itself scheme-aware.
 
-A palette **pinned against** your own scheme still wants a second line, for a smaller reason than it used to be: the planes read your card's lightness, so the surface itself lands right either way, but the poles' own defaults, the status hues and native chrome all still read `color-scheme`. Pin it with them (`.my-editor { color-scheme: dark }`). Skip that line and what the browser paints — the selection highlight, the scrollbar, the spinner — stays on whichever scheme the host inherits, and a status hue you left to us is measured against the wrong card.
+A palette **pinned against** your own scheme still wants a second line, for a smaller reason than it used to be: the planes read your card's lightness, so the surface itself lands right either way, but the poles' own defaults, the status hue and native chrome all still read `color-scheme`. Pin it with them (`.my-editor { color-scheme: dark }`). Skip that line and what the browser paints — the selection highlight, the scrollbar, the spinner — stays on whichever scheme the host inherits, and a status hue you left to us is measured against the wrong card.
 
 Pinning **one mount** rather than a page is the `style` prop, which lands on the same root: `<Preview style="color-scheme: dark" />`. There is no `scheme` prop, and deliberately — an inline declaration of ours would be the one thing your own CSS could not beat.
 
@@ -131,7 +130,7 @@ import '@quillmark/svelte/preset';
 
 This is the stylesheet our own apps import: the playground and studio draw with these rules and nothing else, so what you get is what we ship, not a reduction of it.
 
-It carries a `--qmh-*` scale for the page, derived from the same ten dials and calibrated against the surfaces' own steps, so a plate of yours and a card of ours agree about which way "raised" goes. Turning a dial moves both.
+It carries a `--qmh-*` scale for the page, derived from the same nine dials and calibrated against the surfaces' own steps, so a plate of yours and a card of ours agree about which way "raised" goes. Turning a dial moves both.
 
 | Class         | What it is                                                                                                                           |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -139,7 +138,7 @@ It carries a `--qmh-*` scale for the page, derived from the same ten dials and c
 | `.qm-panel`   | The plate your controls and readouts sit on: one rung off the page, a hairline, a corner.                                            |
 | `.qm-label`   | A run of chrome type: a section label, the name over a value.                                                                        |
 | `.qm-readout` | A value read back out of the session, monospace and tabular. `<pre class="qm-readout">` is the block form.                           |
-| `.qm-status`  | A phase line. `.qm-status-error` and `.qm-status-warn` are the two it fails to.                                                      |
+| `.qm-status`  | A phase line. `.qm-status-error` is the one it fails to.                                                                             |
 | `.qm-control` | A boxed button or select, which is what a host's controls are and the package's are not.                                             |
 | `.qm-measure` | A reading column at the width a passage wants.                                                                                       |
 

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

@@ -132,7 +132,7 @@ export interface LeafViews {
     /** Every view nested inside this leaf, in mount order: one per table cell. */
     nestedViews(): EditorView[];
 }
-/** The canonical empty `Content`: one empty `para` line. The zero value a prose
+/** The canonical empty `Content`: one empty `para` line. The empty a prose
  * leaf (or an array's prose element) seeds from. */
 export declare function emptyContent(): Content;
 export declare function createField(opts: CreateFieldOpts): FieldController;

package/dist/core/codec/field.js

@@ -70,7 +70,7 @@ function anchorPlugin(seed) {
 function readLeaf(reader, addr) {
     return reader.getContent(addr) ?? emptyContent();
 }
-/** The canonical empty `Content`: one empty `para` line. The zero value a prose
+/** The canonical empty `Content`: one empty `para` line. The empty a prose
  * leaf (or an array's prose element) seeds from. */
 export function emptyContent() {
     return { text: '', lines: [{ containers: [], kind: 'para' }], marks: [], islands: [] };
@@ -133,9 +133,22 @@ export function createField(opts) {
     const slash = inline ? undefined : opts.onSlash;
     const state = buildState(reconciler.last);
     index = buildLineIndex(state.doc);
+    // The clearance PM's reveal keeps around the caret, in this leaf's own line box.
+    // Its default is 5px, which is a caret visible and unusable: the next line typed
+    // lands past the fold, the reason the preview's own scroll clears a target by the
+    // target's height (PREVIEW.md §"Follow-the-caret scroll"). Measured off the
+    // mounted box rather than restated from the rung, and dropped where the
+    // derivation is out of reach (jsdom), a fallback there being the scale written
+    // where `check:style` cannot read it.
+    const lineBox = Number.parseFloat(getComputedStyle(container).lineHeight);
+    const clearance = Number.isFinite(lineBox) ? lineBox : undefined;
     view = new EditorView(container, {
         state,
         attributes: proseAttributes(opts),
+        // Both terms, one line each: when a flagged dispatch moves the scrollport
+        // (`scrollThreshold`) and what it leaves at the edge (`scrollMargin`).
+        scrollThreshold: clearance,
+        scrollMargin: clearance,
         // Islands are block-schema only, so an inline leaf mounts no node view at all.
         nodeViews: inline
             ? undefined
@@ -270,8 +283,15 @@ export function createField(opts) {
             // be non-inline (before an island/rule block, or doc-level in an empty
             // nested textblock), where a raw TextSelection is invalid.
             const sel = Selection.near(view.state.doc.resolve(pm));
-            view.dispatch(view.state.tr.setSelection(sel));
+            // Focus first, then the caret: the order a click's own pair arrives in, and the
+            // one a consumer that ends its caret follow on the arrival needs — the other
+            // way round, the arrival ends the follow this call just started.
+            //
+            // Flagged, because PM focuses with `preventScroll` and a landing is a caret
+            // move like any other: unflagged, the caret an arrow key would have revealed
+            // is left off screen by the click that placed it.
             view.focus();
+            view.dispatch(view.state.tr.setSelection(sel).scrollIntoView());
         },
         applyExternal() {
             const current = readLeaf(reader, addr);
@@ -296,6 +316,10 @@ export function createField(opts) {
         },
         focus() {
             view.focus();
+            // The placement rung's reveal: no caret to flag a transaction with, so the
+            // trip is the element's, `nearest` and no clearance — the one the control
+            // lane's own focus takes, for the landing that means the same thing there.
+            view.dom.scrollIntoView({ block: 'nearest' });
         },
         getContent() {
             return readLeaf(reader, addr);

package/dist/core/theme.css

@@ -89,16 +89,15 @@
 		/* Neutral: the surface spends no hue on a state it can draw in grey. The pair
 		   clears WCAG 2.4.11's 3:1 against the card at both poles, at 4.8:1 and 5.8:1. */
 		--_qm-accent: var(--qm-accent, light-dark(#71717a, #a1a1aa));
-		/* The two hues the surface does spend, and it spends them on a state. Each pole
-		   is its own figure rather than one ink shown twice: a hue calibrated against
-		   white reads as a stain on a dark card. All four clear WCAG 1.4.3's 4.5:1
-		   against the card, which is the bar the label rung asks for and the one the
-		   glyphs drawn in these hues clear on the way past 1.4.11's 3:1 — 5.8:1 and
-		   5.2:1 light, 7.4:1 and 7.7:1 dark. The figures are the host scale's
-		   (`preset/scale.css`), so a page's status line and a card's diagnostic carry
-		   one colour meaning error and one meaning warning. */
-		--_qm-danger: var(--qm-danger, light-dark(#c5221f, #ff9c94));
-		--_qm-warning: var(--qm-warning, light-dark(#b25000, #e0b44c));
+		/* The one hue the surface spends, and it spends it on a state. Each pole is
+		   its own figure rather than one ink shown twice: a hue calibrated against
+		   white reads as a stain on a dark card. Both clear WCAG 1.4.3's 4.5:1 against
+		   the card, which is the bar the label rung asks for and the one the glyphs
+		   drawn in this hue clear on the way past 1.4.11's 3:1. Dark enough at its own
+		   pole to carry a label at 4.5:1, so a filled chip needs no third figure. The
+		   figures are the host scale's (`preset/scale.css`), so a page's status line
+		   and a card's diagnostic carry one colour meaning error. */
+		--_qm-danger: var(--qm-danger, light-dark(#9e1518, #f9786c));
 		--_qm-font: var(--qm-font, ui-sans-serif, system-ui, sans-serif);
 		--_qm-font-mono: var(--qm-font-mono, ui-monospace, monospace);
 

package/dist/preset/recipes.css

@@ -247,10 +247,6 @@ pre.qm-readout {
 	overflow-wrap: anywhere;
 }
 
-.qm-status-warn {
-	color: var(--qmh-warn);
-}
-
 /* ── Surfaces ──────────────────────────────────────────────────────────────── */
 
 /* The instrument plate: what a host puts its controls and readouts on. The same plane a

package/dist/preset/scale.css

@@ -2,7 +2,7 @@
    page around the surfaces out. `core/theme.css` is the same shape one level down
    (dials in, `--_qm-*` out), and the two are calibrated against each other: the
    figures here are the figures there (the ground step's ramp, 8% hover, 17%
-   border, 45% ink, the ring's width, the status hues at both poles) and the
+   border, 45% ink, the ring's width, the status hue at both poles) and the
    dial means the same plane in both, so a host plate and a card on it land on the same
    tone at both poles and a host page meets an editor's own column exactly. The well
    under the ground has no counterpart here: a host's own controls are boxed and carry a
@@ -45,13 +45,12 @@
 	   the underline under a link. */
 	--qmh-border-strong: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 40%);
 
-	/* The two hues a host spends, and it spends them on a message. The figures are the
-	   surfaces' own, so a page carries one colour meaning error and one meaning warning
-	   rather than a second pair beside the surfaces'. Each pole is its own figure: a hue
-	   calibrated against white reads as a stain on a dark page. The dial sits in front
-	   of the pair, as every pole's does, so a host that turns one owns both schemes. */
-	--qmh-alert: var(--qm-danger, light-dark(#c5221f, #ff9c94));
-	--qmh-warn: var(--qm-warning, light-dark(#b25000, #e0b44c));
+	/* The hue a host spends on a failure. The figures are the surfaces' own, so a
+	   page's status line and a card's diagnostic carry one colour meaning error.
+	   Each pole is its own figure: a hue calibrated against white reads as a stain
+	   on a dark page. The dial sits in front of the pair, as every pole's does, so
+	   a host that turns one owns both schemes. */
+	--qmh-alert: var(--qm-danger, light-dark(#9e1518, #f9786c));
 
 	/* ── Rhythm ──────────────────────────────────────────────────────────────── */
 	/* One base and its multiples, the same four steps the surfaces derive. A host

package/dist/preview/Preview.svelte

@@ -3,8 +3,8 @@
   container div on mount and tears it down on unmount. No logic beyond wiring;
   paint.ts/bridge.ts/controller.ts own the behavior. Exposes the
   `PreviewController` verbs as instance methods (`bind:this`) for a consumer
-  that drives `refresh`/`scrollToField`/`focusPosition`/`setZoom` imperatively
-  (e.g. after `session.apply` elsewhere).
+  that drives `refresh`/`scrollToField`/`focusPosition`/`endFollow`/`setZoom`
+  imperatively (e.g. after `session.apply` elsewhere).
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
@@ -78,6 +78,11 @@
 	export function focusPosition(at: Place): void {
 		controller?.focusPosition(at);
 	}
+	/** The follow ends on a focus change ({@link PreviewController}), and the editor's
+	 *  own signal is one: `onActiveLeafChange={preview.endFollow}`. */
+	export function endFollow(): void {
+		controller?.endFollow();
+	}
 	export function setZoom(scale: number): void {
 		controller?.setZoom(scale);
 	}

package/dist/preview/Preview.svelte.d.ts

@@ -32,6 +32,7 @@ declare const Preview: import("svelte").Component<Props, {
     refresh: (change: ChangeSet) => void;
     scrollToField: (field: DocPath) => boolean;
     focusPosition: (at: Place) => void;
+    endFollow: () => void;
     setZoom: (scale: number) => void;
 }, "">;
 type Preview = ReturnType<typeof Preview>;

package/dist/preview/controller.d.ts

@@ -38,6 +38,17 @@ export interface PreviewController {
      * `ContentHit` carries both members and fits here too.
      */
     focusPosition(at: Place): void;
+    /**
+     * End the follow: the pane stays where the user left it until the next
+     * `focusPosition`.
+     *
+     * The editor's `onActiveLeafChange` is the signal, firing for a form control as for
+     * a prose leaf: `onActiveLeafChange={preview.endFollow}`. A control has no caret
+     * coordinate to report, so unwired the follow keeps naming the leaf the focus left
+     * and every recompile pulls the pane back there. A prose leaf restarts it with its
+     * own next caret.
+     */
+    endFollow(): void;
     /** Fold a density multiplier into every future paint (crispness, not layout). */
     setZoom(scale: number): void;
     destroy(): void;

package/dist/preview/controller.js

@@ -83,13 +83,13 @@ export function createPreview(session, opts) {
         }
     }
     render(session.pageCount, []);
-    // The last place the editor put the caret, re-located after every recompile.
-    // `session.locate` answers against the last compiled layout and a consumer
-    // debounces `update`, so a caret typed past that layout's content is off-content
-    // for the whole burst: `focusPosition` no-ops and the pane sits still, and a
-    // caret event is otherwise the only thing that asks again. The re-locate is the
-    // preview's, not the consumer's: the staleness sits between two session queries
-    // this module owns both ends of.
+    // The last place the editor put the caret, re-located after every recompile and
+    // dropped on a focus change. `session.locate` answers against the last compiled
+    // layout and a consumer debounces `update`, so a caret typed past that layout's
+    // content is off-content for the whole burst: `focusPosition` no-ops and the pane
+    // sits still, and a caret event is otherwise the only thing that asks again. The
+    // re-locate is the preview's, not the consumer's: the staleness sits between two
+    // session queries this module owns both ends of.
     let followed;
     return {
         refresh(change) {
@@ -106,6 +106,9 @@ export function createPreview(session, opts) {
             followed = at;
             bridge?.focusPosition(at.field, at.pos);
         },
+        endFollow() {
+            followed = undefined;
+        },
         setZoom(scale) {
             paintLoop.setDensityZoom(scale);
         },

package/dist/visual/ArrayField.svelte

@@ -2,11 +2,12 @@
  An `array` field → an add/remove repeater. Elements commit by value: every
  edit / add / remove rebuilds the whole array and hands it to the parent's typed
  `writer.set(field, wholeArray)` (arrays are not op-addressed). Element control
- by `items.type`: `string` / `plaintext` → text input, `richtext` → a prose element
+ by `items.type`: `richtext` / `plaintext` → a prose element
  ({@link ProseArrayElement}), `object` → a minimal JSON editor, keeping the prior
- element value on an entry that does not parse. The add affordance sits in the
- label header row (space-between with the field label); {@link Field} skips its
- own label for array controls and hands this component the label track with it.
+ element value on an entry that does not parse, everything else → a text input. The
+ add affordance sits in the label header row (space-between with the field label);
+ {@link Field} skips its own label for array controls and hands this component the
+ label track with it.
 
  The remove is inside the element: a slab over the end of the element's own box, taking
  its two end-side corners. So a row's box is the element's box, and an array's rows end
@@ -54,22 +55,31 @@
 		labelId?: string;
 		/** Where the description parks, for the group's `aria-describedby`. */
 		descriptionId?: string;
+		/** Element `i`'s content, decoded by the boundary through the codec `items`
+		 * names (`Field`, `reader.getContentAt`). Asked only for a content-typed
+		 * element: on any other the read is not content and throws. `undefined` for a
+		 * row the stored value does not reach — a slot this control has spliced in and
+		 * whose commit has yet to land, or was refused. */
+		elementContent: (i: number) => Content | undefined;
 		onCommit: (arr: unknown[]) => void;
 	}
-	let { value, items, label, required, description, labelId, descriptionId, onCommit }: Props =
-		$props();
+	let {
+		value,
+		items,
+		label,
+		required,
+		description,
+		labelId,
+		descriptionId,
+		elementContent,
+		onCommit
+	}: Props = $props();
 
-	// The element control is the item schema's own, with one departure: a `plaintext`
-	// element is a text input where the scalar field of that type is a prose leaf. A
-	// `plaintext` value rests as its literal string (canon SCHEMAS.md §"Content fields
-	// rest per codec"), and the read that decodes a resting value to `Content` addresses
-	// a field, never an element (`getContent`; borb-sh/quillmark#1243), so a string is
-	// what the row is handed and a string is what it commits. The prose element stays
-	// the `richtext` arm: `Content` after a bound load or a commit, the authored
-	// string through the transport door, lowered in the row for the same reason.
-	//
-	// An array declaring no `items` has text elements.
-	const control = $derived(items && items.type !== 'plaintext' ? controlKind(items) : 'text');
+	// The element control is the item schema's own, with no departure: a content-typed
+	// element mounts the prose leaf its scalar field mounts, reading through
+	// `elementContent` whatever the element rests as. An array declaring no `items`
+	// has text elements.
+	const control = $derived(items ? controlKind(items) : 'text');
 	const arr = $derived((value ?? []) as unknown[]);
 
 	// Parallel stable ids, one per element, kept in lockstep with the data below.
@@ -264,7 +274,8 @@
 				{#if control === 'prose'}
 					<ProseArrayElement
 						bind:this={els[id]}
-						value={(arr[k] ?? emptyElement()) as Content | string}
+						content={() => elementContent(k) ?? emptyContent()}
+						plaintext={items?.type === 'plaintext'}
 						label={label != null ? `${label} ${k + 1}` : undefined}
 						onChange={(rt) => commitElement(k, rt)}
 						onKey={(e) => onElementKey(e, k)}

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

@@ -1,4 +1,4 @@
-import type { QuillFieldSchema } from '@quillmark/wasm';
+import type { Content, QuillFieldSchema } from '@quillmark/wasm';
 import './controls.css';
 interface Props {
     value: unknown[] | undefined;
@@ -15,6 +15,12 @@ interface Props {
     labelId?: string;
     /** Where the description parks, for the group's `aria-describedby`. */
     descriptionId?: string;
+    /** Element `i`'s content, decoded by the boundary through the codec `items`
+     * names (`Field`, `reader.getContentAt`). Asked only for a content-typed
+     * element: on any other the read is not content and throws. `undefined` for a
+     * row the stored value does not reach — a slot this control has spliced in and
+     * whose commit has yet to land, or was refused. */
+    elementContent: (i: number) => Content | undefined;
     onCommit: (arr: unknown[]) => void;
 }
 declare const ArrayField: import("svelte").Component<Props, {

package/dist/visual/DiagnosticList.svelte

@@ -1,9 +1,9 @@
 <!--
- Inline diagnostic display (VISUAL_EDITOR §Diagnostics), severity-styled via
- CSS vars, non-gating: purely additive, never disables the field it sits
- under. Shared by `Field.svelte` (a scalar/prose field) and `Card.svelte` (the
- body leaf, which has no `Field.svelte` wrapper), so a card's body diagnostics
- render the same way a field's do.
+ Inline diagnostic display (VISUAL_EDITOR §Diagnostics). Errors only, non-gating:
+ purely additive, never disables the field it sits under. Shared by `Field.svelte`
+ (a scalar/prose field) and `Card.svelte` (the body leaf, which has no
+ `Field.svelte` wrapper), so a card's body diagnostics render the same way a
+ field's do.
 -->
 <script lang="ts">
 	import type { Diagnostic } from '@quillmark/wasm';
@@ -27,9 +27,7 @@
 	<!-- role=status: commit errors appear mid-typing; announce without stealing focus. -->
 	<div class="qm-diag-list" role="status">
 		{#each diagnostics as d, i (i)}
-			<span class="qm-diag-line" data-severity={d.severity}
-				>{diagnosticText(d, t.formatDiagnostic)}</span
-			>
+			<span class="qm-diag-line">{diagnosticText(d, t.formatDiagnostic)}</span>
 		{/each}
 	</div>
 {/if}
@@ -42,9 +40,6 @@
 	}
 	.qm-diag-line {
 		font-size: var(--_qm-text-label);
-		color: var(--_qm-warning);
-	}
-	.qm-diag-line[data-severity='error'] {
 		color: var(--_qm-danger);
 	}
 </style>

package/dist/visual/EnumField.svelte

@@ -80,8 +80,8 @@
 <span class="qm-select-wrap" bind:this={wrapEl}>
 	<!-- `allowDeselect={false}`: the unset sentinel is the clear-to-default
 	 affordance, so the primitive's own deselect must stay off. It reports a
-	 deselect as `''`: indistinguishable from picking the empty-string enum
-	 member the reference quill actually declares. -->
+	 deselect as `''`, the boundary's blank: a written value, where the sentinel's
+	 clear is an absence. -->
 	<Select.Root
 		type="single"
 		allowDeselect={false}

package/dist/visual/Field.svelte

@@ -11,7 +11,7 @@
  `diagnostics` is the routed `Diagnostic[]` for this field (VisualEditor's
  `diagByKey`, merging `quill.validate`, local commit errors, and the external
  `diagnostics` prop (VISUAL_EDITOR §Diagnostics)) rendered via the shared
- `DiagnosticList`, severity-styled, non-gating.
+ `DiagnosticList`, non-gating.
 -->
 <script lang="ts">
 	import type { Document, Quill, Addr, Diagnostic, ResolvedField } from '@quillmark/wasm';
@@ -265,6 +265,7 @@
 					description={field.description}
 					labelId={domIds.label}
 					descriptionId={domIds.description}
+					elementContent={(i) => quill.reader(doc).getContentAt(addr, [i])}
 					onCommit={onCommitScalar}
 				/>
 			{:else if field.control === 'object'}

package/dist/visual/FieldLabel.svelte

@@ -11,8 +11,8 @@
  element is inert and invalid.
 
  Two non-gating label decorations:
- • a persistent required `*` when the field has no `default:`: the
- "Unendorsed"/must_fill set (DOCUMENT_MODEL: no separate `required` axis). Its
+ • a persistent required `*` for a field the schema obliges (`must_fill`, which
+ derives from a missing `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/ProseArrayElement.svelte

@@ -1,7 +1,7 @@
 <!--
- One element of an array-of-`richtext` field (fixture `keywords`). Array
- elements are not `applyChange`-addressable: `Addr.field` is a flat name, so
- `keywords[0]` has no op address. So
+ One element of an array of `richtext` (fixture `keywords`) or `plaintext`
+ (`errata`). Array elements are not `applyChange`-addressable: `Addr.field` is a
+ flat name, so `keywords[0]` has no op address. So
  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
@@ -9,24 +9,35 @@
  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).
 
- A transport-door document rests each element as the authored string. A scalar
- leaf reads that through `getContent`; `getContent` names a field, never an
- element, so this row calls the boundary's `importMarkdown` itself. That is
- the richtext codec, which is this row's `items` type; `decode` is the PM
- mapping and assumes `Content`. A string here is the missing element read,
- not a codec failure.
+ The content is read, not passed: `reader.getContentAt(addr, [k])` decodes an
+ element through the codec its `items` type declares, so what the element rests
+ as — the content object, a `plaintext` literal, the authored string a transport
+ door left — stops being this row's business. Read once, at mount, since that is
+ when this leaf takes its state.
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
 	import { EditorState } from 'prosemirror-state';
 	import { EditorView } from 'prosemirror-view';
-	import { decode, pmToContent, inlineSchema, proseLeafPlugins } from '../core/codec/index.js';
-	import { core } from '../core/lifecycle.js';
+	import {
+		decode,
+		pmToContent,
+		inlineSchema,
+		plaintextSchema,
+		proseLeafPlugins
+	} from '../core/codec/index.js';
 	import './controls.css';
 	import type { Content } from '@quillmark/wasm';
 
 	interface Props {
-		value: Content | string;
+		/** This element's content, read at mount (`ArrayField`, through the boundary's
+		 * element read). A thunk rather than a value: the parent re-derives per
+		 * revision and this leaf takes its state once, so a value prop would be a
+		 * boundary read per row per render, all but one of them discarded. */
+		content: () => Content;
+		/** The mark-free schema (a `plaintext` item): literal text, no formatting,
+		 * exactly as the scalar field of that type mounts. */
+		plaintext?: boolean;
 		/** Accessible name for the editable region (the array has no per-element label). */
 		label?: string;
 		onChange: (rt: Content) => void;
@@ -35,15 +46,20 @@
 		 * keymap, so the state it reads is the one this keystroke has yet to change. */
 		onKey?: (e: KeyboardEvent) => void;
 	}
-	let { value, label, onChange, onKey }: Props = $props();
+	let { content, plaintext = false, 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
 	 * focus, not the element's: a PM view restores its selection, where a bare DOM
-	 * focus on a contenteditable leaves the caret unplaced. */
+	 * focus on a contenteditable leaves the caret unplaced. And the reveal beside it,
+	 * since PM's focus prevents the scroll a `string` element's input takes by
+	 * default — an array whose two item types revealed differently is one row of it
+	 * landing off screen. */
 	export function focus(): void {
-		view?.focus();
+		if (!view) return;
+		view.focus();
+		view.dom.scrollIntoView({ block: 'nearest' });
 	}
 
 	onMount(() => {
@@ -52,11 +68,15 @@
 		// 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.
-		const rt = typeof value === 'string' ? core().importMarkdown(value) : value;
-		const pmDoc = decode(rt, inlineSchema);
+		//
+		// The schema is the declared type's, as `createField` picks it: `plaintext`
+		// declares no mark types, so there is nothing to toggle, to paste in, or to
+		// mint a shorthand with.
+		const schema = plaintext ? plaintextSchema : inlineSchema;
+		const pmDoc = decode(content(), schema);
 		const state = EditorState.create({
 			doc: pmDoc,
-			plugins: proseLeafPlugins(inlineSchema, { inline: true })
+			plugins: proseLeafPlugins(schema, { inline: true })
 		});
 		const mounted = new EditorView(containerEl, {
 			state,

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

@@ -1,7 +1,14 @@
 import './controls.css';
 import type { Content } from '@quillmark/wasm';
 interface Props {
-    value: Content | string;
+    /** This element's content, read at mount (`ArrayField`, through the boundary's
+     * element read). A thunk rather than a value: the parent re-derives per
+     * revision and this leaf takes its state once, so a value prop would be a
+     * boundary read per row per render, all but one of them discarded. */
+    content: () => Content;
+    /** The mark-free schema (a `plaintext` item): literal text, no formatting,
+     * exactly as the scalar field of that type mounts. */
+    plaintext?: boolean;
     /** Accessible name for the editable region (the array has no per-element label). */
     label?: string;
     onChange: (rt: Content) => void;

package/dist/visual/VisualEditorInner.svelte

@@ -206,6 +206,10 @@
 		const plain = normalize(addr);
 		activeAddr = plain;
 		activeCardId = cardIdOf(plain);
+		// The arrival ends the caret memo's run (`lastCaretField` below): a leaf returned
+		// to at the offset it still names has to report again.
+		lastCaretField = undefined;
+		lastCaretPos = undefined;
 		const field = pathFor(plain);
 		if (field != null) onActiveLeafChange?.({ field, cardId: activeCardId });
 	}
@@ -236,6 +240,10 @@
 	// that reflows the page under a caret holding its offset is the case this drops,
 	// and a preview does not need the signal to answer it: the place is unchanged, so
 	// the one it already followed is the one its recompile re-locates.
+	//
+	// A focus clears it, and must: a focus into a leaf with no caret to report ends a
+	// consumer's follow (PREVIEW §"Follow-the-caret scroll"), and the return to the
+	// offset the memo still names is the only thing that would restart it.
 	let lastCaretField: DocPath | undefined;
 	let lastCaretPos: number | undefined;
 	function handleCaret(addr: Addr, pos: number): void {
@@ -272,7 +280,7 @@
 			if (value === undefined) {
 				// The unset rung of the commitment ladder (VISUAL_EDITOR §"Structure mirrors
 				// the schema"): removing the field leaves the engine's authored › `default:`
-				// › zero-fill resolve to render the default, where writing one bakes a
+				// › blank-fill resolve to render the default, where writing one bakes a
 				// snapshot the schema cannot track (canon SCHEMAS.md: the engine never
 				// persists a default; nor do we). Removal writes no value, so there is
 				// nothing for a schema to conform and the lane is the quill-free one.
@@ -477,8 +485,9 @@
 	});
 
 	// All three producers. The two positional ones resolve their `.path` to the live
-	// stable-id keying; commit errors are id-keyed already. Nothing is dropped:
-	// diagnostics never gate, so nothing here hides one either.
+	// stable-id keying; commit errors are id-keyed already. Nothing is dropped for
+	// being unwelcome — diagnostics never gate — but warnings do not draw: only
+	// errors reach a control (`routeAndResolve`).
 	const diagByKey = $derived.by(() => {
 		const fromValidate = routeAndResolve(validation, cardIds);
 		const fromExternal = routeAndResolve(diagnostics, cardIds);

package/dist/visual/diagnostics.d.ts

@@ -30,15 +30,18 @@ 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, `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`.
+ * and `resolveCardKey` in a single pass. Warnings do not draw (VISUAL_EDITOR
+ * §Diagnostics): obligation, completeness, a render note — none of them is a value
+ * the field cannot hold. An entry also 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`. Completeness
+ * stays a read the host makes on `quill.validate(doc)`.
  */
 export declare function routeAndResolve(diagnostics: Diagnostic[] | undefined, cardIds: readonly string[]): RoutedDiagnostic[];
 /**
  * Merge N routed groups into `Map<fieldKeyToString(key), Diagnostic[]>`.
  * Dedupes an identical `(severity, message)` pair landing on the same key from
- * more than one group (e.g. the same warning present in both `validate()` and
- * an external feed); within a key, errors sort before warnings.
+ * more than one group (e.g. the same error present in both `validate()` and
+ * an external feed). Producer order within a key.
  */
 export declare function mergeDiagnostics(...groups: RoutedDiagnostic[][]): Map<string, Diagnostic[]>;

package/dist/visual/diagnostics.js

@@ -21,14 +21,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, `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`.
+ * and `resolveCardKey` in a single pass. Warnings do not draw (VISUAL_EDITOR
+ * §Diagnostics): obligation, completeness, a render note — none of them is a value
+ * the field cannot hold. An entry also 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`. Completeness
+ * stays a read the host makes on `quill.validate(doc)`.
  */
 export function routeAndResolve(diagnostics, cardIds) {
     const out = [];
     for (const d of diagnostics ?? []) {
-        if (!d.path)
+        if (d.severity !== 'error' || !d.path)
             continue;
         const key = addrForFieldPath(d.path);
         const resolved = key && resolveCardKey(key, cardIds);
@@ -37,13 +40,11 @@ export function routeAndResolve(diagnostics, cardIds) {
     }
     return out;
 }
-/** Severity ordering: errors sort before warnings within a field's list (never dropped, just ranked: VISUAL_EDITOR §Diagnostics "nothing gates" extends to nothing hides). */
-const SEVERITY_RANK = { error: 0, warning: 1 };
 /**
  * Merge N routed groups into `Map<fieldKeyToString(key), Diagnostic[]>`.
  * Dedupes an identical `(severity, message)` pair landing on the same key from
- * more than one group (e.g. the same warning present in both `validate()` and
- * an external feed); within a key, errors sort before warnings.
+ * more than one group (e.g. the same error present in both `validate()` and
+ * an external feed). Producer order within a key.
  */
 export function mergeDiagnostics(...groups) {
     const byKey = new Map();
@@ -64,8 +65,5 @@ export function mergeDiagnostics(...groups) {
                 byKey.set(k, [diagnostic]);
         }
     }
-    for (const arr of byKey.values()) {
-        arr.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
-    }
     return byKey;
 }

package/dist/visual/props.d.ts

@@ -17,6 +17,11 @@ export interface VisualEditorProps {
      * The active leaf: its canonical `DocPath` and the session key of the card holding
      * it, which is what a host tracking the active card keeps across a reorder
      * (`CardId`).
+     *
+     * It fires for a form control as for a prose leaf, which makes it the other half of
+     * the preview bridge: a control has no caret coordinate to report, so
+     * `onActiveLeafChange={preview.endFollow}` is what stops the pane following the leaf
+     * the focus left.
      */
     onActiveLeafChange?: (active: ActiveLeaf) => void;
     /**
@@ -56,7 +61,7 @@ export interface VisualEditorProps {
     onError?: EditorErrorHandler;
     /**
      * External diagnostics, routed by `.path` and merged with `quill.validate`
-     * and local commit errors (VISUAL_EDITOR §Diagnostics).
+     * and local commit errors (VISUAL_EDITOR §Diagnostics). Warnings do not draw.
      */
     diagnostics?: Diagnostic[];
     /**

package/dist/visual/strings.d.ts

@@ -66,12 +66,12 @@ export interface VisualStrings extends TableChromeStrings, SlashStrings {
  * interpolates, keyed by name. What it can re-word tracks what that type carries per
  * lane (VISUAL_EDITOR §Diagnostics for why each lands where it does):
  *
- * - **`validation::enum_violation`, `type_mismatch`, `format_violation`,
- *   `must_fill`**: the constraint re-words from the quill's schema at `path`, the
- *   offending value from `args` (`value` / `sourceToken` / `actual`, the engine
- *   testifying to what it saw) and never from the document at `path`: validation
- *   runs post-coercion, so the validator read a value the document does not hold and
- *   a sentence built from `path` names a spelling the user never typed.
+ * - **`validation::enum_violation`, `type_mismatch`, `format_violation`**: the
+ *   constraint re-words from the quill's schema at `path`, the offending value from
+ *   `args` (`value` / `sourceToken` / `actual`, the engine testifying to what it
+ *   saw) and never from the document at `path`: validation runs post-coercion, so
+ *   the validator read a value the document does not hold and a sentence built from
+ *   `path` names a spelling the user never typed.
  * - **`edit::field_coercion_failed`**: re-words from the app's own control state, the
  *   refused value being in neither document (unchanged on throw) nor schema.
  * - **`parse::yaml_error_with_location`, `invalid_structure`**: does not re-word. No

package/dist/visual/structure.d.ts

@@ -17,12 +17,11 @@ export interface FieldModel {
      * undefined when the field declares none. Chrome-only; never gates. */
     description: string | undefined;
     /**
-     * Required-ness: a field with no `default:` is "Unendorsed": its
-     * seed carries a `!must_fill` marker (DOCUMENT_MODEL: there is no separate
-     * `required` axis). Drives a persistent label `*`, complementary to the ghosted
-     * `default:` (a required field has no default to ghost). Persistent (schema-
-     * derived, survives filling); the on-commit `must_fill` `validate` warning
-     * remains the unmet-ness signal. Label chrome only; never gates.
+     * Required-ness: the schema's `must_fill` obligation, which derives from
+     * `default:`'s absence when the field declares none (DOCUMENT_MODEL). Drives a
+     * persistent label `*`; a field can carry both it and a ghosted `default:`,
+     * since the two axes are independent. Persistent (schema-derived, survives
+     * filling). Label chrome only; never gates.
      */
     required: boolean;
     /** Prose-leaf flags (only meaningful when `control === 'prose'` / array items). */

package/dist/visual/structure.js

@@ -89,7 +89,7 @@ export function fieldModels(cardSchema) {
         compact: !!schema.ui?.compact,
         label: schema.ui?.title ?? humanize(name),
         description: schema.description,
-        required: schema.default === undefined,
+        required: schema.must_fill ?? schema.default === undefined,
         inline: !!schema.inline,
         plaintext: schema.type === 'plaintext'
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/svelte",
-	"version": "0.4.3",
+	"version": "0.5.1",
 	"description": "Editor, live-preview and source surfaces over a Quillmark WASM session.",
 	"repository": {
 		"type": "git",
@@ -66,7 +66,7 @@
 		"check": "svelte-check --tsconfig ./tsconfig.json"
 	},
 	"peerDependencies": {
-		"@quillmark/wasm": ">=0.104.0-0",
+		"@quillmark/wasm": ">=0.105.0-0",
 		"svelte": "^5.0.0"
 	},
 	"dependencies": {