@quillmark/svelte 0.1.0 → 0.2.0

package/README.md

@@ -26,10 +26,12 @@ Each subpath is its own module root; a bundler pulls only what the entry you imp
 The **consumer** owns the session and the handles, and drives every edit; the surfaces are views over it. The handles come from the `@quillmark/wasm` peer, never re-exported here.
 
 ```ts
-import { Document, Engine, Quill } from '@quillmark/wasm';
+import { Engine } from '@quillmark/wasm';
 import { init } from '@quillmark/svelte/core';
 
-init(); // one-time WASM panic-hook install
+// One-time, and the only door to Quill and Document: the artifact exports
+// neither statically.
+const { Quill, Document } = await init();
 
 const quill = Quill.fromTree(tree); // tree: Map<string, Uint8Array> of the quill dir
 
@@ -49,7 +51,7 @@ const session = await new Engine().open(quill, doc);
 A stored document carries none of its quill's bytes, only a reference: `doc.quillRef` is `name@version`, persisted in the markdown itself. Resolution is **host code**: read the ref, map it to a `Quill`, open. No surface resolves, so one resolution per document holds by construction.
 
 ```ts
-const doc = Document.fromMarkdown(stored);
+const doc = Document.fromMarkdown(stored); // Document, from the gate above
 const quill = await registry.getQuill(doc.quillRef); // your ref → Quill mapping
 const session = await new Engine().open(quill, doc);
 ```
@@ -67,8 +69,8 @@ import { createPreview } from '@quillmark/svelte/preview';
 
 const preview = createPreview(session, {
 	container: document.querySelector('#preview')!,
-	onCaretPick: (hit) => {
-		/* a click resolved to a content position; see the bridge below */
+	onPick: (at) => {
+		/* a click resolved to an address, with a caret where the compile has one */
 	},
 	onError: (err) => {
 		/* a page paint the backend refused; the preview shows its error state either way */
@@ -79,9 +81,9 @@ const preview = createPreview(session, {
 preview.refresh(session.update(doc)); // repaint dirtyPages ∩ visible
 ```
 
-In Svelte, `<Preview {session} onCaretPick={…} />` exposes the same verbs (`refresh`, `scrollToField`, `focusPosition`, `setZoom`) via `bind:this`.
+In Svelte, `<Preview {session} onPick={…} />` exposes the same verbs (`refresh`, `scrollToField`, `focusPosition`, `setZoom`) via `bind:this`.
 
-`<Preview>` binds **once**, at mount: swapping `session`, `margin`, `overlays`, `onCaretPick`, `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.
+`<Preview>` binds **once**, at mount: swapping `session`, `margin`, `overlays`, `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.
 
 ## Visual editor
 
@@ -135,7 +137,7 @@ Hand it a different `doc` and the editor **re-keys itself**: every leaf remounts
 <button onclick={() => editor?.focusField('main.subject')}>Jump to subject</button>
 ```
 
-`insertCard` hands back the new card's `cardId`; `removeCard`, `moveCard` and `setKind` take one. A card key or a path the surface does not hold is a no-op that reports `target-unknown` through `onError` at `dev` severity.
+`insertCard` hands back the new card's `cardId`; `removeCard`, `moveCard` and `setKind` take one. `focusField` reaches any mounted field: a prose leaf takes its view's focus, a form control the same handoff a click on its label takes, and either way the group holding it is revealed first. A card key or a path the surface does not hold is a no-op that reports `target-unknown` through `onError` at `dev` severity.
 
 ### Wording
 
@@ -191,13 +193,15 @@ This shell layer is deliberately yours: the debounce value, what applies at once
 The bridge lives at the **consumer** layer and is opt-in; the editor is unaware of the preview, the preview unaware of the editor. Both hops are pass-throughs: the two surfaces already speak one address grammar, the canonical `DocPath`.
 
 ```ts
-// preview → editor: a click resolved to a content position places the caret.
-onCaretPick: (hit) => visualEditor.setCaret(hit);
+// 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.
 onCaretMove: preview.focusPosition;
 ```
 
+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.references.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.
 
 ## Errors
@@ -223,7 +227,7 @@ This is not the diagnostics channel. A `Diagnostic` is about the **document** an
 el.textContent = doc.toMarkdown();
 ```
 
-The playground's debug drawer is the worked version, holding scroll across the swap and showing a throw in place: `packages/playground/src/routes/playground/SourceMirror.svelte`.
+A worked one holds the scroll across the swap and shows a throw in place; the call under it is still the one line above.
 
 ## Theming
 

package/THEMING.md

@@ -2,7 +2,7 @@
 
 `@quillmark/svelte` ships complex UX over a thin skin: the surfaces carry the behavior (direct manipulation, the caret bridge, per-field state) against a neutral visual baseline a consumer restyles to its brand without fighting baked-in design.
 
-There are three depths to that, and most apps stop at the first:
+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                                                 |
 | ----------------- | --------------------- | ------------------------------------------------------- |
@@ -39,20 +39,26 @@ The whole contract is **ten CSS custom properties**. They are dials, not a palet
 }
 ```
 
+### Two of them are not branding
+
+`--qm-bg` and `--qm-fg` are the two a themed host sets before any brand decision. Their defaults are a self-consistent neutral for a bare mounting site, not a guess at your page: an app that paints its own plate and leaves them mounts one plate inside another. Two tones a few percent apart read as a fault rather than as a layer, so meet your page's tone exactly or stand far enough off it to be a layer.
+
+The poles take a colour, not `transparent` or `inherit`: the raised surfaces, the borders and the muted inks are each a `color-mix` against `--qm-bg`, so a transparent pole makes every one of them translucent instead of letting your page through. Hand over the value your page is painted with and the derivation steps off it.
+
 ### The dials
 
-| Token            | Default                                | What it sets                                                                                            |
-| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `--qm-bg`        | `#fff` / `#14171c`                     | Base surface. Cards, fields, the painted page, the popover, and the column behind them step off it.     |
-| `--qm-fg`        | `#1a1a1a` / `#e8eaed`                  | Base ink. Body text, labels, and borders step off it.                                                   |
-| `--qm-accent`    | `#2563eb`                              | Focus rings, active marks, the preview's active field box.                                              |
-| `--qm-danger`    | `#c5221f`                              | Error diagnostics, the required marker, the delete glyph.                                               |
-| `--qm-warning`   | `#b25000`                              | 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`                             | Body text: every control's size, and the anchor the ramp derives up (title) and down (label/meta) from. |
-| `--qm-radius`    | `8px`                                  | Card & popover corner. Interior controls derive a tighter tier (half).                                  |
-| `--qm-space`     | `0.25rem`                              | Spacing base. Gaps and insets are `half`/`1×`/`2×`/`3×`/`4×` multiples of it.                           |
+| Token            | Default                                | What it sets                                                                                                                                                   |
+| ---------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--qm-bg`        | `#fff` / `#14171c`                     | Base surface. Cards, fields, the painted page, the popover, and the column behind them step off it.                                                            |
+| `--qm-fg`        | `#1a1a1a` / `#e8eaed`                  | Base ink. Body text, labels, and borders step off it.                                                                                                          |
+| `--qm-accent`    | `#2563eb`                              | Focus rings, active marks, the preview's active field box.                                                                                                     |
+| `--qm-danger`    | `#c5221f`                              | Error diagnostics, the required marker, the delete glyph.                                                                                                      |
+| `--qm-warning`   | `#b25000`                              | 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. |
+| `--qm-radius`    | `8px`                                  | Card & popover corner. Interior controls derive a tighter tier (half), so a square brand is square throughout.                                                 |
+| `--qm-space`     | `0.25rem`                              | Spacing base. Gaps and insets are `half`/`1×`/`2×`/`3×`/`4×` multiples of it.                                                                                  |
 
 Give a length dial a length: `--qm-space: 4` is a valid custom property and an invalid length, so it substitutes through every `calc()` that reads it. Where `@property` is supported the surface absorbs that, landing on the package default rather than collapsing the padding to zero.
 
@@ -131,26 +137,39 @@ It carries a `--qmh-*` scale for the page, derived from the same ten dials and c
 
 ### The shell, if you are building a tool
 
-An app that mounts an editor beside a preview over one session needs a screen to put them in, and the SHAPE of that screen is the same every time. Four more classes are that shape, so what you write is the wiring rather than the grid:
+An app that mounts an editor beside a preview over one session needs a screen to put them in, and the SHAPE of that screen is the same every time. Five more classes are that shape, so what you write is the wiring rather than the grid:
 
 ```html
 <div class="qm-workspace">
 	<header class="qm-bar site-head">
 		<span class="site-mark">acme<span class="site-slash">/</span>studio</span>
 	</header>
-	<div class="qm-split">
-		<section class="qm-frame"><!-- <VisualEditor class="qm-pane" /> --></section>
-		<section class="qm-frame"><!-- <Preview /> --></section>
+	<div class="site-body">
+		<div class="qm-switch" role="group" aria-label="Visible pane">
+			<button class="qm-control" aria-pressed="{shown" ="" ="" ="1}" onclick="{()" ="">
+				(shown = 1)}>Editor
+			</button>
+			<button class="qm-control" aria-pressed="{shown" ="" ="" ="2}" onclick="{()" ="">
+				(shown = 2)}>Preview
+			</button>
+		</div>
+		<div class="qm-split" data-qm-show="{shown}">
+			<section class="qm-frame"><!-- <VisualEditor class="qm-pane" /> --></section>
+			<section class="qm-frame"><!-- <Preview /> --></section>
+		</div>
 	</div>
 </div>
 ```
 
-| Class           | What it is                                                                                                                                             |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `.qm-workspace` | The screen: pinned to the viewport, three bands (a head, the body, an optional foot), the body taking what is left and the document scrolling nowhere. |
-| `.qm-bar`       | The row a band puts its parts on, wrapping and centred. The rule under it, the gutter beside it and its depth stay yours: that is your page shell.     |
-| `.qm-split`     | Two even tracks for two surfaces, the page gap between them. Below `60rem` they stack, each at `--qmh-pane`; which element scrolls then is yours.      |
-| `.qm-frame`     | The mounting site: an edge, a corner, and the clip that holds a surface to them. What is inside it is the surface's own.                               |
+| Class           | What it is                                                                                                                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.qm-workspace` | The screen: pinned to the viewport, three bands (a head, the body, an optional foot), the body taking what is left and the document scrolling nowhere.                                            |
+| `.qm-bar`       | The row a band puts its parts on, wrapping and centred. The rule under it, the gutter beside it and its depth stay yours: that is your page shell.                                                |
+| `.qm-split`     | Two even tracks for two surfaces, the page gap between them. Under `50rem` wide or `30rem` tall, one track at a time; `data-qm-show="1"\|"2"` says which.                                         |
+| `.qm-switch`    | The band that says which track is showing, and nothing at the widths where both are. Its controls read as even halves and stand at the touch floor (`--qmh-tap`, 44px); depth past that is yours. |
+| `.qm-frame`     | The mounting site: an edge, a corner, and the clip that holds a surface to them. What is inside it is the surface's own.                                                                          |
+
+The narrow shape is one mount at a time, not two of them stacked: half a narrow viewport is under the width either surface reads at. The track you are not showing is `display: none`, so it leaves the tab order, hit-testing and the accessibility tree together: you need no `inert` on it, and no breakpoint in your JS, since the only state you hold is which of the two you last asked for. Keep both MOUNTED: the hidden pane keeps its pixels, its caret and its scroll, and repaints itself when it comes back. A click that lands in the hidden pane is the one thing the shape adds to your wiring, so send the caret and reveal the track together, or the hit goes somewhere the reader cannot see.
 
 The shape is shared; the LOOK of a band is not. Your wordmark, your nav and the depth of your head are the most app-specific things on the screen, and a preset that drew them would hand every tool built on this the same face, so they read `--qmh-*` like everything else and you write the rules. `.qm-split`'s gap is a default rather than a fact about splitting: close it to `0` and carry a hairline on one pane if you want the two mounts to meet instead of stand apart.
 

package/dist/core/address.d.ts

@@ -1,4 +1,4 @@
-import { type Addr } from '@quillmark/wasm';
+import type { Addr, HitGranularity } from '@quillmark/wasm';
 /**
  * A canonical field address: `main.<field>` / `main.body` /
  * `cards.<kind>[<i>].<field>`, cards keyed by ABSOLUTE document index.
@@ -23,6 +23,23 @@ export interface Place {
     /** The caret in USV. */
     pos: number;
 }
+/**
+ * Where a preview click landed. What the preview surfaces and what the editor's
+ * `setCaret` takes.
+ *
+ * **An absent `pos` is the PLACEMENT rung**, not a caret at zero: the click resolved
+ * a field the plate places without tracking its content (`fieldAt` answers,
+ * `positionAt` does not), so there is no offset and the landing is a focus. A `Place`
+ * is a landing carrying its caret, and a `ContentHit` is one too.
+ */
+export interface Landing {
+    field: DocPath;
+    /** The caret in USV, absent on the placement rung. */
+    pos?: number;
+    /** Whether `pos` is cluster-exact or floored to a segment start; the boundary's
+     *  own marker, carried through untouched. */
+    granularity?: HitGranularity;
+}
 /**
  * A field's canonical `DocPath`, or `undefined` when `addr.card` is outside the live
  * `kinds` array (a stale address: drop it rather than mis-target). A field-less card
@@ -46,11 +63,29 @@ export declare function cardPath(index: number, kinds: readonly string[]): DocPa
 /**
  * The inverse: a canonical `DocPath` back to the `Addr` the document verbs take, or
  * `undefined` for a path that names no single commit address — a nested or
- * array-element path (`main.references.0`), a field-rooted one, or a malformed one
- * (which `parseDocPath` throws on). A bare card and a `.body` terminal both land on
- * the field-less `{card: i}` the body leaf answers to.
+ * array-element path (`main.references.0`, which {@link elementAddrForFieldPath}
+ * takes instead), a field-rooted one, or a malformed one. A bare card and a `.body`
+ * terminal both land on the field-less `{card: i}` the body leaf answers to.
  *
  * Needs no `kinds`: the path carries the absolute index, and the kind in it is
  * decoration the `Addr` has no room for.
  */
 export declare function addrForFieldPath(path: DocPath): Addr | undefined;
+/**
+ * An ARRAY ELEMENT's address, split. `main.references.0` and `main.references[0]`
+ * both land here; anything {@link addrForFieldPath} can name, and anything whose
+ * trailing segment is not an index, does not.
+ *
+ * Both spellings, because the boundary mints one and formats the other: `regions()`
+ * and `positionAt` emit `main.references.0`, which `parseDocPath` reads as a field
+ * literally named `"0"`, while `formatDocPath` spells the index segment
+ * `main.references[0]`. A trailing all-digits field name is therefore an index that
+ * lost its brackets — but only under a field the SCHEMA declares an array, the
+ * caller's guard to apply: this module holds the grammar and no schema.
+ */
+export declare function elementAddrForFieldPath(path: DocPath): ElementAddr | undefined;
+/** An array element's address: the ARRAY's `Addr`, and which element of it. */
+export interface ElementAddr {
+    field: Addr;
+    index: number;
+}

package/dist/core/address.js

@@ -1,15 +1,4 @@
-// The one address vocabulary the surfaces speak in public: canonical `DocPath`
-// strings for places, `Addr` for the document verbs. Declared HERE because both
-// `/preview` and `/visual` name a place in their hooks, and a type declared twice
-// structurally is drift with nothing to catch it: `/core` is the module both
-// already import.
-//
-// Slogan: paths for places, indexes for structure ops. `Addr` (`{card?, field?}`,
-// from `@quillmark/wasm`) is the mutator currency; the conversions at the foot of
-// this module are the hop between the two. `fieldPathForAddr` and `addrForFieldPath`
-// are public, because a host given a path by a hook and holding a verb that takes an
-// `Addr` needs them; `cardPath` is the editor's own.
-import { formatDocPath, parseDocPath } from '@quillmark/wasm';
+import { core } from './lifecycle.js';
 // ── Addr ↔ DocPath ──────────────────────────────────────────────────────────
 // The one hop between the two vocabularies, both directions, pure and
 // document-free: `kinds` is the kind of each composable card by content index
@@ -34,7 +23,7 @@ export function fieldPathForAddr(addr, kinds) {
     if (!head)
         return undefined;
     const tail = addr.field != null ? { seg: 'field', name: addr.field } : { seg: 'body' };
-    return formatDocPath([head, tail]);
+    return core().formatDocPath([head, tail]);
 }
 /**
  * A CARD's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
@@ -43,26 +32,65 @@ export function fieldPathForAddr(addr, kinds) {
  */
 export function cardPath(index, kinds) {
     const head = cardHead(index, kinds);
-    return head ? formatDocPath([head]) : undefined;
+    return head ? core().formatDocPath([head]) : undefined;
 }
 /**
  * The inverse: a canonical `DocPath` back to the `Addr` the document verbs take, or
  * `undefined` for a path that names no single commit address — a nested or
- * array-element path (`main.references.0`), a field-rooted one, or a malformed one
- * (which `parseDocPath` throws on). A bare card and a `.body` terminal both land on
- * the field-less `{card: i}` the body leaf answers to.
+ * array-element path (`main.references.0`, which {@link elementAddrForFieldPath}
+ * takes instead), a field-rooted one, or a malformed one. A bare card and a `.body`
+ * terminal both land on the field-less `{card: i}` the body leaf answers to.
  *
  * Needs no `kinds`: the path carries the absolute index, and the kind in it is
  * decoration the `Addr` has no room for.
  */
 export function addrForFieldPath(path) {
-    let segs;
+    const segs = segsOf(path);
+    return segs && addrForSegs(segs);
+}
+/**
+ * An ARRAY ELEMENT's address, split. `main.references.0` and `main.references[0]`
+ * both land here; anything {@link addrForFieldPath} can name, and anything whose
+ * trailing segment is not an index, does not.
+ *
+ * Both spellings, because the boundary mints one and formats the other: `regions()`
+ * and `positionAt` emit `main.references.0`, which `parseDocPath` reads as a field
+ * literally named `"0"`, while `formatDocPath` spells the index segment
+ * `main.references[0]`. A trailing all-digits field name is therefore an index that
+ * lost its brackets — but only under a field the SCHEMA declares an array, the
+ * caller's guard to apply: this module holds the grammar and no schema.
+ */
+export function elementAddrForFieldPath(path) {
+    const segs = segsOf(path);
+    if (!segs)
+        return undefined;
+    const last = segs[segs.length - 1];
+    const index = last?.seg === 'index'
+        ? last.index
+        : last?.seg === 'field' && /^\d+$/.test(last.name)
+            ? Number(last.name)
+            : undefined;
+    if (index == null)
+        return undefined;
+    const field = addrForSegs(segs.slice(0, -1));
+    // A body has no elements: the parent must name a FIELD.
+    return field?.field != null ? { field, index } : undefined;
+}
+/** `parseDocPath`, with a malformed path as `undefined` rather than a throw. The gate
+ *  is read OUTSIDE the try: an uninitialized core is not a malformed path, and would
+ *  otherwise leave here as one. */
+function segsOf(path) {
+    const { parseDocPath } = core();
     try {
-        segs = parseDocPath(path);
+        return parseDocPath(path);
     }
     catch {
         return undefined;
     }
+}
+/** {@link addrForFieldPath} over already-parsed segments, so the element walk reuses
+ *  it for the head of a path rather than re-serializing one. */
+function addrForSegs(segs) {
     const [head, ...rest] = segs;
     if (!head)
         return undefined;

package/dist/core/codec/encode.js

@@ -1,4 +1,5 @@
-import { mapPos, isAnchorMark } from '@quillmark/wasm';
+import { isAnchorMark } from '@quillmark/wasm';
+import { core } from '../lifecycle.js';
 import { codePoints, usvLength } from './decode.js';
 import { ISLAND_SLOT, islandEntryFromNode } from './islands.js';
 import { contentDescriptorFromPM, descriptorOf, markKey } from './marks.js';
@@ -386,6 +387,8 @@ function shiftPastIslands(pos, insertedAt, assoc) {
 /** Formatting/unknown marks → add/remove ops; anchors → add/removeAnchor by id. */
 function diffMarks(oldRt, newRt, delta, insertedAt, opts) {
     const ops = [];
+    // Read the gate once per diff rather than once per mark.
+    const { mapPos } = core();
     // Rebase old marks through BOTH text-moving channels to final coords, exactly
     // as `applyChange` does internally (start assoc `after`, end assoc `before`).
     const rebase = (pos, assoc) => shiftPastIslands(delta ? mapPos(delta, pos, assoc) : pos, insertedAt, assoc);

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

@@ -74,7 +74,7 @@ export interface FieldController {
     /** The mounted `container`: the leaf's element, for a caller that has to reach the
      *  DOM the view sits in (the arrival wash, `core/bloom.ts`) rather than re-find it. */
     readonly el: HTMLElement;
-    /** Place the caret at USV `pos` (preview onCaretPick → usvToPM → here). */
+    /** Place the caret at USV `pos` (preview onPick → usvToPM → here). */
     setCaret(pos: number): void;
     /** External content change → re-hydrate this leaf (gated by reconcile). */
     applyExternal(): void;

package/dist/core/codec/prose.css

@@ -20,13 +20,13 @@
    re-measured here rather than in `theme.css` because a layered rule loses to that
    unlayered stylesheet: equal specificity and a later import is what wins. */
 .ProseMirror-selectednode {
-	outline: var(--_qm-ring-width) solid var(--_qm-accent);
+	outline: var(--_qm-ring);
 }
 /* Upstream's `-32px` is measured against the UA's 40px list indent, which the list
    rule below replaces with a rung. The offset moves with it, or a selected item's
    outline hangs into the margin by the difference. */
 li.ProseMirror-selectednode::after {
-	border: var(--_qm-ring-width) solid var(--_qm-accent);
+	border: var(--_qm-ring);
 	left: calc(var(--_qm-space-4) * -1);
 }
 
@@ -96,14 +96,25 @@ li.ProseMirror-selectednode::after {
    `--_qm-surface-raised` and the only rung over it is `--_qm-surface-hover`, the
    hover lane, so a chip at rest would read as a hovered button.
 
-   ONE selector for the mark and the block: a `code_block` renders `pre > code`
-   (`schema.ts`), so every character of it is inside a `code` element and the `pre`
-   needs no face of its own. `pre` takes no `overflow-x` either, because there is no
-   overflow: ProseMirror's own stylesheet sets `white-space: pre-wrap` there, so a
-   long line wraps. A scroller means overriding that to `pre` inside an editable
-   `code` textblock, which is an editing change, not a display rule. */
-.ProseMirror code {
+   The withheld properties are DECLARED at their zero, which is what makes the
+   paragraph above true of a MOUNTED leaf: a chip on these tags is an ordinary page
+   rule, so left off, these are the two tags the host draws rather than the surface.
+   The other marks are ink, weight and decoration, which the leaf sets or safely
+   inherits, so the box is this mark's alone and the zeros are not a reset.
+
+   BOTH tags, where the face alone needs only one: a `code_block` renders `pre > code`
+   (`schema.ts`), so every character is inside a `code` element and the face reaches it
+   there — but the block's BOX is the `pre`, outside that element and styled by the
+   host on its own. `pre` still takes no `overflow-x`, because there is no overflow:
+   ProseMirror's own stylesheet sets `white-space: pre-wrap` there, so a long line
+   wraps. A scroller means overriding that to `pre` inside an editable `code`
+   textblock, which is an editing change, not a display rule. */
+.ProseMirror :is(code, pre) {
 	font-family: var(--_qm-font-mono);
+	padding: 0;
+	border-radius: 0;
+	background: none;
+	font-size: inherit;
 }
 
 /* A link takes the surface's ink (the UA's blue is the `#8cf` defect again) and a
@@ -128,21 +139,33 @@ li.ProseMirror-selectednode::after {
 }
 
 /* The UA's 40px list indent is the one box the reset above does not take (it is
-   padding, not margin), and it is a length nothing chose. A rung replaces it. The
-   MARKERS stay the UA's: `disc` and `decimal` are already right, and restating them
-   buys nothing. Per-item spacing is untouched, which is the point of putting this on
-   the list rather than the item: the sibling-gap rule deliberately omits `ul`/`ol`,
-   and padding on the container cannot reintroduce what it withholds. */
+   padding, not margin), and it is a length nothing chose. A rung replaces it.
+   Per-item spacing is untouched, which is the point of putting this on the list
+   rather than the item: the sibling-gap rule deliberately omits `ul`/`ol`, and
+   padding on the container cannot reintroduce what it withholds.
+
+   The MARKERS are the UA's, RECLAIMED rather than inherited. `disc` and `decimal`
+   are right and this restates neither: a host reset (Tailwind's preflight sets
+   `list-style: none` on `ol, ul, menu`) is the common case, and against one an
+   unstated default is no default at all — bullets and numbers vanish from the leaf
+   while the preview beside it still draws them, which is an editor/paper
+   divergence on the plainest formatting there is. `revert` over a named type
+   because the UA's markers step by DEPTH (disc, circle, square) and the schema
+   nests (`lists.ts`: Tab sinks an item); naming `disc` would flatten that ramp to
+   hold the first level. Same reclaim for `strong`/`em`/`u`/`s` above if a reset
+   that takes those ever turns up: the positive half states what it leaves to the
+   UA, and what a reset takes is what has to be asked back. */
 .ProseMirror :is(ul, ol) {
 	padding-left: var(--_qm-space-4);
+	list-style: revert;
 }
 
 /* Six levels, one weight, no size step. The quill reads no level at all, so a size
    ramp here would be the editor predicting a hierarchy the paper does not set; the
    level stays in the model, which is where the codec round-trips it. It is also all
-   the ramp could carry: `--_qm-text-title` is one 1.125 step over the body, the
-   body sits on `--_qm-text-body` by decision, and leading alone is what separates
-   paper from chrome. Six levels do not fit in one step, and
+   the ramp could carry: this leaf renders at `--_qm-text-paper` and the next rung up
+   is `--_qm-text-title`, a chrome rung a heading inside a document has no business
+   reading. Six levels do not fit in the gap, and
    minting five more is the drift the scale exists to prevent. */
 .ProseMirror :is(h1, h2, h3, h4, h5, h6) {
 	font-size: inherit;
@@ -431,7 +454,7 @@ li.ProseMirror-selectednode::after {
 .qm-table-handle:focus-visible,
 .qm-table-seam:focus-visible,
 .qm-table-align-item:focus-visible {
-	outline: var(--_qm-ring-focus);
+	outline: var(--_qm-ring);
 	outline-offset: var(--_qm-ring-offset);
 }
 

package/dist/core/codec/table.js

@@ -15,7 +15,8 @@
 // the codec already runs (one paragraph, no containers, no islands) is exactly its
 // shape, so a cell decodes and projects through the same machinery a
 // `richtext(inline)` field does.
-import { isAnchorMark, mapPos } from '@quillmark/wasm';
+import { isAnchorMark } from '@quillmark/wasm';
+import { core } from '../lifecycle.js';
 import { contentEdit, pmToContent } from './encode.js';
 /** The alignments a column can take: the four the content declares, `none` first
  *  because it is what a column arrives at and what a set is cleared back to. */
@@ -201,6 +202,7 @@ export function cellFromDoc(doc, prior) {
     if (!anchors.length)
         return { text, marks: projected.marks };
     const delta = contentEdit(cellContent(prior), cellContent({ text, marks: [] })).delta;
+    const { mapPos } = core();
     const rebased = anchors.map((a) => {
         const pos = delta ? mapPos(delta, a.start, 'after') : a.start;
         return { ...a, start: pos, end: pos };

package/dist/core/errors.d.ts

@@ -30,14 +30,24 @@ export type EditorErrorCode =
  * re-keyed on it nor observed it. The mounted surface still names the previous
  * handle. `dev` throughout: the fix is a remount at the call site, so this is
  * aimed at whoever wired it and never at a running app's telemetry.
+ *
+ * The one code that is also THROWN, in a dev build, once reported: a swapped
+ * `onError` is itself a rebind, so the handler this arrives at may be the one the
+ * consumer just replaced (`rebind.svelte.ts`).
  */
  | 'rebind-ignored'
 /**
- * An instance verb named a card or a field the surface does not hold: a `cardId`
- * from a previous session or an already-removed card, a `DocPath` naming no
- * mounted leaf. The call is a no-op and the document is untouched. `dev`: the
- * editor's own chrome cannot mint a bad target, so this only ever reports a host
- * driving the verbs from outside.
+ * A landing named a card or a field the surface does not hold: a `cardId` from a
+ * previous session or an already-removed card, or a `DocPath` naming no declared
+ * field — an array ELEMENT path included, where the array itself is undeclared or
+ * unmounted. The call is a no-op and the document is untouched.
+ *
+ * `dev`, because the fix is at the call site: a host driving the instance verbs
+ * from outside, or a preview pick the editor has no field to route to. Every
+ * MOUNTED field is a target, prose leaf and form control alike, and an array's
+ * elements are targets through it, so this is not how a scalar or an element
+ * reports. The preview never reports it at all: a field it places nothing for is
+ * `scrollToField` returning `false`.
  */
  | 'target-unknown';
 /** A failure a surface recovered from. */

package/dist/core/index.d.ts

@@ -1,5 +1,5 @@
 import './theme.css';
 export { init } from './lifecycle.js';
-export type { DocPath, Place } from './address.js';
+export type { DocPath, Landing, Place } from './address.js';
 export { fieldPathForAddr, addrForFieldPath } from './address.js';
 export type { EditorError, EditorErrorCode, EditorErrorHandler } from './errors.js';

package/dist/core/index.js

@@ -1,8 +1,9 @@
 // The theme derivation: the public dials → the private `--_qm-*` scale, applied
-// to every `data-qm-root` element. Imported HERE because `core/` is the one module
-// both `preview/` and `visual/` already pull, so a consumer cannot forget it and
-// the derivation is minted once rather than re-declared per detached root
-// (THEMING.md).
+// to every `data-qm-root` element (THEMING.md). Imported at every barrel a
+// consumer can enter through — here, `/visual`, `/preview` — because a subpath is
+// what a consumer gets, and a surface reaching a module INSIDE `core/` reaches
+// nothing this file imports. One sheet however many barrels name it: the
+// derivation is minted once rather than re-declared per detached root.
 import './theme.css';
 // `@quillmark/svelte/core`: what this package OWNS at the substrate seam.
 //

package/dist/core/lifecycle.d.ts

@@ -1,7 +1,23 @@
+import { type CoreSurface } from '@quillmark/wasm';
 /**
- * Instantiate the core WASM build. Await once before any other boundary verb,
- * from any surface's setup path; the promise is memoized, so concurrent callers
- * share one instantiation and repeat calls are free. A failed init clears the
- * memo, leaving a retry possible.
+ * Instantiate the core WASM build and resolve to its surface. Await once before
+ * any other boundary verb, from any surface's setup path; the promise is memoized,
+ * so concurrent callers share one instantiation and repeat calls are free. A failed
+ * init clears the memo, leaving a retry possible.
+ *
+ * The surface is the artifact's own, handed back unchanged: `const { Quill, Document }
+ * = await init()` is the whole of a host's access to the classes, and this package
+ * re-declares none of it.
  */
-export declare function init(): Promise<void>;
+export declare function init(): Promise<CoreSurface>;
+/**
+ * The surface synchronously, for this package's pure verbs: the `DocPath` formatter
+ * on the public API and the codec inside a ProseMirror transaction, neither of which
+ * can await. Package-internal, and read at the call rather than destructured at
+ * module scope, so no module's import graph carries an ordering constraint.
+ *
+ * Reaching one before {@link init} resolves throws, naming the fix. This is the seam
+ * that turns an awaited surface back into sync verbs, so it is the one place the
+ * precondition the gate made structural has to be stated again.
+ */
+export declare function core(): CoreSurface;