@quillmark/svelte 0.4.3 → 0.5.0

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.
 
@@ -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

@@ -54,8 +54,8 @@ 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-warning`   | `#926510` / `#fdc776`                  | Warning diagnostics.                                                                                                                                           |
 | `--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. |

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

@@ -93,12 +93,14 @@
 		   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));
+		   glyphs drawn in these hues clear on the way past 1.4.11's 3:1 — 8.2:1 and
+		   5.1:1 light, 5.6:1 and 9.7:1 dark. Each is also 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 and one meaning
+		   warning. */
+		--_qm-danger: var(--qm-danger, light-dark(#9e1518, #f9786c));
+		--_qm-warning: var(--qm-warning, light-dark(#926510, #fdc776));
 		--_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/scale.css

@@ -50,8 +50,8 @@
 	   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));
+	--qmh-alert: var(--qm-danger, light-dark(#9e1518, #f9786c));
+	--qmh-warn: var(--qm-warning, light-dark(#926510, #fdc776));
 
 	/* ── 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/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

@@ -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

@@ -58,6 +58,7 @@
 	} from './structure.js';
 	import {
 		fieldKeyToString,
+		inlineShown,
 		resolveCardKey,
 		routeAndResolve,
 		mergeDiagnostics,
@@ -206,6 +207,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 +241,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 +281,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,10 +486,12 @@
 	});
 
 	// 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 the obligation warning is
+	// withheld from the boundary's lane, the label's `*` being where the surface
+	// states that (`inlineShown`).
 	const diagByKey = $derived.by(() => {
-		const fromValidate = routeAndResolve(validation, cardIds);
+		const fromValidate = routeAndResolve(validation.filter(inlineShown), cardIds);
 		const fromExternal = routeAndResolve(diagnostics, cardIds);
 		return mergeDiagnostics(fromValidate, fromExternal, [...commitErrors.values()]);
 	});

package/dist/visual/diagnostics.d.ts

@@ -27,6 +27,20 @@ export interface RoutedDiagnostic {
     key: FieldKey;
     diagnostic: Diagnostic;
 }
+/**
+ * Whether a validation diagnostic is the surface's to show under a control
+ * (VISUAL_EDITOR §Diagnostics). Obligation is not: the label's `*` already states
+ * it, from the same schema, for the same cells, and it states it whether or not the
+ * cell has been answered — so the warning is a second copy of a mark on screen, once
+ * per obliged field, on every document nobody has finished. That is every obliged
+ * field of a fresh seed, which is what a consumer's first mount is.
+ *
+ * Withheld from the boundary's own validation lane only. A consumer's `diagnostics`
+ * prop passes whole: what a host hands the surface, the host asked to see. And
+ * nothing is suppressed at the source — `quill.validate(doc)` is the completeness
+ * read, unchanged and still the host's to make.
+ */
+export declare function inlineShown(d: Diagnostic): boolean;
 /**
  * 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`

package/dist/visual/diagnostics.js

@@ -18,6 +18,22 @@ export function resolveCardKey(key, cardIds) {
     const id = key.card >= 0 && key.card < cardIds.length ? cardIds[key.card] : undefined;
     return id != null ? { card: id, field: key.field } : undefined;
 }
+/**
+ * Whether a validation diagnostic is the surface's to show under a control
+ * (VISUAL_EDITOR §Diagnostics). Obligation is not: the label's `*` already states
+ * it, from the same schema, for the same cells, and it states it whether or not the
+ * cell has been answered — so the warning is a second copy of a mark on screen, once
+ * per obliged field, on every document nobody has finished. That is every obliged
+ * field of a fresh seed, which is what a consumer's first mount is.
+ *
+ * Withheld from the boundary's own validation lane only. A consumer's `diagnostics`
+ * prop passes whole: what a host hands the surface, the host asked to see. And
+ * nothing is suppressed at the source — `quill.validate(doc)` is the completeness
+ * read, unchanged and still the host's to make.
+ */
+export function inlineShown(d) {
+    return d.code !== 'validation::must_fill';
+}
 /**
  * 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`

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;
     /**

package/dist/visual/structure.d.ts

@@ -17,12 +17,12 @@ 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); the `must_fill` `validate` warning remains the unmet-ness signal.
+     * 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.0",
 	"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": {