@quillmark/svelte 0.1.1 → 0.3.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
 
@@ -147,7 +149,7 @@ The package ships English and a seam to replace it. `strings` is keyed and **par
 	{quill}
 	strings={{
 		cardDelete: 'Supprimer la carte',
-		addCardOfKind: (kind) => `Ajouter : ${kind}`
+		addCard: '+ Ajouter une carte'
 	}}
 	formatDiagnostic={(d) =>
 		d.code === 'validation::must_fill' ? `${d.path} est obligatoire` : undefined}
@@ -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,28 @@ 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.
+
+`--qm-bg` is the **card**, not the column behind it: the plane a document is written on, which is also the sheet the preview paints. Everything else is a step off it, and the column the cards sit in is a step down, so a mounted editor draws its own ground and the cards read as islands on it. Give it the tone you want a card to be — white, in most light themes — and let the column fall out. If you want the column to meet your page instead, set a `background` of your own on `.qm-editor`; your CSS is unlayered and wins.
+
+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` / `#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`    | `#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.
 
@@ -70,7 +78,9 @@ Declared before our sheet it fixes the order outright; declared after, `qm` is a
 
 ### The surface follows your colour scheme
 
-Surfaces step `bg → fg` and ink steps `fg → bg`, mixed in **oklab**, so inverting the two poles inverts the whole scale, including borders and the popover's translucent fill.
+Ink steps `fg → bg` and the borders and hover fills step `bg → fg`, mixed in **oklab**, so inverting the two poles inverts all of them together.
+
+**Planes are the exception**, and deliberately: the raised plane is the brighter one in both schemes, which is what makes a card read as a card rather than as a differently-tinted page. So the column under the cards sinks from `--qm-bg` toward shadow and a floating surface rises from it toward light, and neither reads the ink pole. Each direction takes a step sized to the scheme it is in, which is why pinning a dark palette while your `color-scheme` still says light leaves the column barely off its cards — the one case §"Make it yours" tells you to pin the scheme alongside the poles.
 
 Which way the poles default is **your `color-scheme`**, not the operating system's. Declare the scheme your app is in and the surface lands on it, along with native chrome, which reads the same property:
 
@@ -131,28 +141,41 @@ 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.
+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.
 
 It is **unlayered**, so your own rules beat it by ordinary precedence, exactly as they beat the surfaces. It is also opt-in and side-effect free until imported: nothing that styles your document arrives with a component.
 

package/dist/core/address.d.ts

@@ -1,7 +1,7 @@
-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.
+ * `cards.<kind>[<i>].<field>`, cards keyed by absolute document index.
  *
  * The grammar `parseDocPath` / `formatDocPath` speak, and the one
  * `Diagnostic.path`, `ContentHit.field`, `FieldRegion.field` and
@@ -23,10 +23,27 @@ 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
- * addresses its BODY, which is the leaf `{card: i}` names.
+ * addresses its body, which is the leaf `{card: i}` names.
  *
  * - `{}` → `"main.body"`
  * - `{field}` → `"main.<field>"`
@@ -38,7 +55,7 @@ export interface Place {
  */
 export declare function fieldPathForAddr(addr: Addr, kinds: readonly string[]): DocPath | undefined;
 /**
- * A CARD's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
+ * A card's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
  * where the change is the card rather than anything inside it. `undefined` for an
  * index outside `kinds`.
  */
@@ -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
@@ -19,7 +8,7 @@ import { formatDocPath, parseDocPath } from '@quillmark/wasm';
 /**
  * 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
- * addresses its BODY, which is the leaf `{card: i}` names.
+ * addresses its body, which is the leaf `{card: i}` names.
  *
  * - `{}` → `"main.body"`
  * - `{field}` → `"main.<field>"`
@@ -34,35 +23,74 @@ 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,
+ * A card's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
  * where the change is the card rather than anything inside it. `undefined` for an
  * index outside `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/bloom.d.ts

@@ -9,12 +9,12 @@ export interface BloomTiming {
 /**
  * Resolve the timing off `el`, so the dwell is single-sourced in CSS.
  *
- * ONE property, both motion preferences: `--_qm-bloom-dwell` already shortens under
+ * One property, both motion preferences: `--_qm-bloom-dwell` already shortens under
  * `prefers-reduced-motion` in the derivation, so what is left to `matchMedia` here is
- * the SHAPE: a hold and a cut carry no ramps, which is a frame list rather than a
+ * the shape: a hold and a cut carry no ramps, which is a frame list rather than a
  * number and the one half CSS cannot hand over.
  *
- * Read ONCE PER BATCH, not per element: `getComputedStyle` forces a style recalc and
+ * Read once per batch, not per element: `getComputedStyle` forces a style recalc and
  * `animate` re-dirties style, so a read inside a loop flushes once per element (~0.15ms
  * each). The rungs inherit, so every element in a batch resolves the same numbers.
  */
@@ -27,10 +27,10 @@ export declare function bloomTiming(el: HTMLElement): BloomTiming;
  */
 export declare function bloom(el: HTMLElement, elapsed?: number, timing?: BloomTiming): Animation | undefined;
 /**
- * Bloom over `host`'s CONTENT: an inset child, so the wash neither tints the host's
+ * Bloom over `host`'s content: an inset child, so the wash neither tints the host's
  * own background nor fades the text under it. `host` must be positioned.
  *
- * ONE wash node per host, reused while it lives: two quick landings on the same leaf
+ * One wash node per host, reused while it lives: two quick landings on the same leaf
  * must not stack two alphas over it. No `elapsed` seam: the surfaces that use this
  * (editor leaves) are not rebuilt under the animation the way the preview's boxes are.
  */

package/dist/core/bloom.js

@@ -1,12 +1,12 @@
 // The correlation bloom: a soft accent wash that rises over a target and decays to
-// nothing. The editor↔preview address is an EVENT, not a state: the preview claims
+// nothing. The editor↔preview address is an event, not a state: the preview claims
 // to be the rendered output, so it carries no resting ink, and a highlight that
 // outlives the hop that caused it is ink the document did not ask for. Both
 // directions land here: the preview's field boxes bloom themselves (they are already
 // empty rects over the page), an editor leaf blooms a transient child over its
 // surface.
 //
-// OPACITY is the animated property, never the colour. The wash's alpha is a peak
+// Opacity is the animated property, never the colour. The wash's alpha is a peak
 // fixed by `--_qm-accent-wash`, so interpolating 0→1→0 keeps the scale in CSS where
 // `color-mix` resolves, instead of in keyframe values a script would have to
 // pre-resolve and re-resolve on a theme change.
@@ -23,7 +23,7 @@ const WASH = 'var(--_qm-accent-wash)';
  *  absence of the scale, not a copy of it. */
 const FALLBACK_MS = 1100;
 // Rise fast, hold, then leave slowly: a highlighter's decay, not a linear fade. A
-// keyframe's easing governs the segment that STARTS at it. Under reduced motion the
+// keyframe's easing governs the segment that starts at it. Under reduced motion the
 // ramps are dropped entirely: the wash holds at full for a beat and cuts, which
 // still answers "here" with nothing to track.
 const FRAMES = [
@@ -40,12 +40,12 @@ export function primeWash(el) {
 /**
  * Resolve the timing off `el`, so the dwell is single-sourced in CSS.
  *
- * ONE property, both motion preferences: `--_qm-bloom-dwell` already shortens under
+ * One property, both motion preferences: `--_qm-bloom-dwell` already shortens under
  * `prefers-reduced-motion` in the derivation, so what is left to `matchMedia` here is
- * the SHAPE: a hold and a cut carry no ramps, which is a frame list rather than a
+ * the shape: a hold and a cut carry no ramps, which is a frame list rather than a
  * number and the one half CSS cannot hand over.
  *
- * Read ONCE PER BATCH, not per element: `getComputedStyle` forces a style recalc and
+ * Read once per batch, not per element: `getComputedStyle` forces a style recalc and
  * `animate` re-dirties style, so a read inside a loop flushes once per element (~0.15ms
  * each). The rungs inherit, so every element in a batch resolves the same numbers.
  */
@@ -74,10 +74,10 @@ export function bloom(el, elapsed = 0, timing) {
     return anim;
 }
 /**
- * Bloom over `host`'s CONTENT: an inset child, so the wash neither tints the host's
+ * Bloom over `host`'s content: an inset child, so the wash neither tints the host's
  * own background nor fades the text under it. `host` must be positioned.
  *
- * ONE wash node per host, reused while it lives: two quick landings on the same leaf
+ * One wash node per host, reused while it lives: two quick landings on the same leaf
  * must not stack two alphas over it. No `elapsed` seam: the surfaces that use this
  * (editor leaves) are not rebuilt under the animation the way the preview's boxes are.
  */

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

@@ -8,7 +8,7 @@ export interface RangeAnchor {
 /**
  * A virtual anchor over one PM range, measured when asked rather than when made.
  *
- * The measure is TOTAL. `coordsAtPos` reads layout, and layout can be gone: a
+ * The measure is total. `coordsAtPos` reads layout, and layout can be gone: a
  * position the document has since invalidated, a leaf inside a collapsed section, a
  * view torn down between a scroll firing and the measure running. `autoUpdate` calls
  * this at moments none of its callers choose, so an unmeasurable anchor returns the

package/dist/core/codec/anchor.js

@@ -1,7 +1,7 @@
 /**
  * A virtual anchor over one PM range, measured when asked rather than when made.
  *
- * The measure is TOTAL. `coordsAtPos` reads layout, and layout can be gone: a
+ * The measure is total. `coordsAtPos` reads layout, and layout can be gone: a
  * position the document has since invalidated, a leaf inside a collapsed section, a
  * view torn down between a scroll firing and the measure running. `autoUpdate` calls
  * this at moments none of its callers choose, so an unmeasurable anchor returns the

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

@@ -0,0 +1,10 @@
+import { type Command } from 'prosemirror-state';
+import type { Schema } from 'prosemirror-model';
+/**
+ * The block-atom bindings for a block-schema leaf: `{}` for the inline/plaintext
+ * schemas, which hold no block to be against.
+ *
+ * Both keys are the same command on opposite sides, because what a delete against an
+ * atom means does not depend on which side the caret approached from.
+ */
+export declare function atomKeymap(schema: Schema): Record<string, Command>;

package/dist/core/codec/atoms.js

@@ -0,0 +1,78 @@
+// The block-atom link of the body's Backspace/Delete chains: a delete against an
+// island or a divider selects it, and the press after that deletes it.
+//
+// This is the neighbour half of the rule the leaf already holds for a key typed over a
+// selection (CODEC §"The table island"): a selection is the subject of the next
+// command, never a thing armed for replacement. Without it the base keymap's
+// `joinBackward` / `joinForward` reach their "the neighbour is an atom, delete it" arm
+// and a table goes in one keystroke, from the paragraph a table insert parks the caret
+// in — with nothing drawn first to say what is about to go.
+//
+// It runs last of the links, after the list ones: a Backspace at the start of a list's
+// first item lifts the item, and that stays the item's answer whatever sits above the
+// list.
+import { NodeSelection, TextSelection } from 'prosemirror-state';
+/** The caret, when it sits at a textblock edge with an empty selection: the only place
+ *  a delete is about a neighbour rather than about a character. `null` everywhere else,
+ *  which is where the key keeps its ordinary meaning. */
+function atEdge(state, side) {
+    const { selection } = state;
+    if (!(selection instanceof TextSelection) || !selection.empty)
+        return null;
+    const $head = selection.$head;
+    const at = side < 0 ? 0 : $head.parent.content.size;
+    return $head.parentOffset === at ? $head : null;
+}
+/**
+ * The cut the caret's block sits against on `side`: the shallowest boundary with a
+ * sibling beyond it. `prosemirror-commands` walks the same one to find the node a join
+ * would reach; this reads it to find the node a delete would take.
+ */
+function cutAt($pos, side) {
+    if ($pos.parent.type.spec.isolating)
+        return null;
+    for (let d = $pos.depth - 1; d >= 0; d--) {
+        if (side < 0) {
+            if ($pos.index(d) > 0)
+                return $pos.doc.resolve($pos.before(d + 1));
+        }
+        else if ($pos.index(d) + 1 < $pos.node(d).childCount) {
+            return $pos.doc.resolve($pos.after(d + 1));
+        }
+        if ($pos.node(d).type.spec.isolating)
+            break;
+    }
+    return null;
+}
+/** Select the block atom the caret is against, rather than deleting it. Declines when
+ *  the neighbour is anything a caret can enter, so a paragraph, a heading, a quote and
+ *  a list all keep the join the base keymap gives them. */
+function selectAtom(side) {
+    return (state, dispatch) => {
+        const $head = atEdge(state, side);
+        const $cut = $head && cutAt($head, side);
+        if (!$cut)
+            return false;
+        const node = side < 0 ? $cut.nodeBefore : $cut.nodeAfter;
+        if (!node || !node.isAtom || !node.isBlock || !NodeSelection.isSelectable(node))
+            return false;
+        const at = side < 0 ? $cut.pos - node.nodeSize : $cut.pos;
+        dispatch?.(state.tr.setSelection(NodeSelection.create(state.doc, at)).scrollIntoView());
+        return true;
+    };
+}
+/**
+ * The block-atom bindings for a block-schema leaf: `{}` for the inline/plaintext
+ * schemas, which hold no block to be against.
+ *
+ * Both keys are the same command on opposite sides, because what a delete against an
+ * atom means does not depend on which side the caret approached from.
+ */
+export function atomKeymap(schema) {
+    if (!schema.nodes.island_block)
+        return {};
+    return {
+        Backspace: selectAtom(-1),
+        Delete: selectAtom(1)
+    };
+}