@quillmark/svelte 0.26.2 → 0.28.0

package/NOTICE

@@ -6,9 +6,9 @@ Copyright 2026 Nibs
 This package contains SVG glyph geometry derived from Lucide, carried in source
 rather than installed.
 
-`visual/icons/nodes.ts` holds eighteen verbatim from @lucide/svelte 1.28.0:
+`visual/icons/nodes.ts` holds seventeen verbatim from @lucide/svelte 1.28.0:
 chevron-right, arrow-right, chevron-down, chevron-up, bold, italic, underline,
-strikethrough, code, link, info, plus, x, trash-2, minus, check, calendar and
+strikethrough, code, link, info, plus, trash-2, minus, check, calendar and
 calendar-check.
 
 `core/codec/table-view.ts` holds grip-horizontal, grip-vertical, align-left,
@@ -33,8 +33,8 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 --------------------------------------------------------------------------------
 
-Twelve of those glyphs — arrow-right, chevron-down, chevron-right, chevron-up,
-code, info, italic, link, minus, plus, trash-2 and x — are drawn exactly as
+Eleven of those glyphs — arrow-right, chevron-down, chevron-right, chevron-up,
+code, info, italic, link, minus, plus and trash-2 — are drawn exactly as
 the Feather project draws them and carry its license as well.
 
 The MIT License (MIT)

package/README.md

@@ -29,12 +29,12 @@ The **consumer** owns the session and the handles, and drives every edit; the su
 import { Engine } from '@quillmark/wasm';
 import { init } from '@quillmark/svelte/core';
 
-// Quill and Document are exported only through init(), which loads the wasm once.
+// Quill and Document are exported only through init().
 const { Quill, Document } = await init();
 
 const quill = Quill.fromTree(tree); // tree: Map<string, Uint8Array> of the quill dir
 
-// A NEW document: seeded from the quill's blueprint.
+// A NEW document: seeded from the quill's schema.
 const doc = quill.seedDocument();
 
 // An EXISTING document: parsed back from what you stored.
@@ -120,7 +120,7 @@ In Svelte, `<Preview {session} onPick={…} />` exposes the same verbs (`refresh
 />
 ```
 
-Hand it a different `doc` and the editor **re-keys itself**: every leaf remounts against the new handle, and the id state, the commit-error map and the active address seed fresh. Nothing to key at the call site. `quill` is not part of that key — the schema is re-read on every derive, so a quill swap re-projects on its own; swapping it _without_ the doc reports `rebind-ignored`.
+Hand it a different `doc` and the editor **re-keys itself**: every leaf remounts against the new handle, and the id state, the commit-error map and the active address seed fresh. `quill` is not part of that key — the schema is re-read on every derive, so a quill swap re-projects on its own; swapping it _without_ the doc reports `rebind-ignored`.
 
 ### Driving it from outside
 
@@ -165,6 +165,26 @@ The package ships English and a seam to replace it. `strings` is keyed and **par
 
 `formatDiagnostic` gets the whole `Diagnostic` and returns `undefined` to take its own message. Validation and edit diagnostics re-word from `code`, `path` and `args`; parse errors and render warnings carry their detail inside English text and stand as they are ([VISUAL_EDITOR.md](prose/canon/VISUAL_EDITOR.md)).
 
+### Fonts
+
+A run of text can be set in a font family the **host** supplies, spelled `<qm-span family="…">` in markdown. Build the engine with the font files (`.ttf`, `.otf`, `.ttc`, `.otc`) and hand the editor the faces it lists: the format popover then offers each family, and the editor registers the faces with the page so a run draws in the face the preview sets it in.
+
+```ts
+const carlito = new Uint8Array(await (await fetch('/fonts/Carlito-Regular.ttf')).arrayBuffer());
+const engine = new Engine({ fonts: [carlito] });
+```
+
+```svelte
+<script lang="ts">
+	let fonts = $state<FontFace[]>([]);
+	engine.fontFaces(quill).then((faces) => (fonts = faces));
+</script>
+
+<VisualEditor {doc} {quill} {fonts} />
+```
+
+[`@quillmark/fonts`](../fonts) is the library every Quillmark client builds its engine over, so a family a document names sets the same way in each; a host's own files go after it. `fontFaces` loads the render build, as `open` does, so mount the editor first and let the faces arrive behind it. A family the document already sets edits with no library at all, and the picker offers it so it can be cleared.
+
 ### Recompiling
 
 `onChange` is the signal to recompile, and it covers **all three lanes**: a prose keystroke, a scalar write, a card operation. `onCaretMove` is a _selection_ signal, not a change signal: it fires on a bare arrow key, so a recompile hung off it recompiles on every one.
@@ -193,7 +213,7 @@ function recompileNow() {
 
 `session.warnings` is a **getter on a handle Svelte does not track**: pull it per apply, or the editor shows the previous compile's errors.
 
-This shell layer is deliberately yours: the debounce value, what applies at once, and which surfaces refresh are host policy, so the package ships no scheduler over them. Three obligations ride with that: an edit of your own (an import, an undo, a direct `doc` write) recompiles by the same calls, since nothing polls the document; a compile owes the diagnostics re-read above, since nothing polls the session; and teardown clears the timer **before** freeing the handles, so a pending recompile never touches a freed session.
+The schedule is host policy, so the package ships no scheduler. Obligations: an edit of your own (an import, an undo, a direct `doc` write) recompiles by the same calls, since nothing polls the document; a compile re-reads the diagnostics; and teardown clears the timer **before** freeing the handles.
 
 ## The caret bridge
 
@@ -217,7 +237,7 @@ A consumer holding an `Addr` of its own maps it with `fieldPathForAddr` (from `@
 
 ## Errors
 
-Every surface takes `onError`. It reports failures the surface **recovered from**: a commit the boundary refused, a card operation that threw, a page paint that failed, a serialize that threw. None of them stop editing. Wire nothing and each lands in the console, which an app cannot route, filter or count.
+Every surface takes `onError`. It reports failures the surface **recovered from**: a commit the boundary refused, a card operation that threw, a page paint that failed, a serialize that threw. None of them stop editing. Wire nothing and each lands in the console.
 
 ```ts
 onError: (err) => {
@@ -238,8 +258,6 @@ This is not the diagnostics channel. A `Diagnostic` is about the **document** an
 el.textContent = doc.toMarkdown();
 ```
 
-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
 
 The surfaces carry the behavior against a neutral, overridable visual baseline: a set of `--qm-*` CSS custom properties you override on any ancestor. See [`THEMING.md`](THEMING.md).
@@ -250,7 +268,7 @@ This package is one workspace of [`quillmark-js`](../..); the gates are the root
 
 ```sh
 npm run build -w packages/svelte   # svelte-package → dist/
-npm run test  -w packages/svelte   # Vitest (codec, diagnostics, geometry, chain)
+npm run test  -w packages/svelte   # Vitest
 npm run check -w packages/svelte   # svelte-check
 npm run dev                        # the playground, from the root
 ```

package/THEMING.md

@@ -18,7 +18,7 @@ There are three depths to that. An app mounting into an unstyled page stops at t
 
 Nothing to import and nothing to set. The package pulls its own stylesheet, and each surface owns its whole **column**, not only the cards in it: the gutter the stack sits in, the tone behind it, and (for the preview) the desk the painted sheet floats on. A bare `<div>` is a mounting site.
 
-**Mounting into a fixed-height pane**: pass `class="qm-pane"`. The surface becomes its own scroll container and takes a scroll tail, so the last card can be read at the middle of your pane rather than against its bottom edge. Without it the editor grows to its content and your page scrolls, which is what you want when the editor _is_ the page. The preview always scrolls: a viewport onto a document has nothing else to be.
+**Mounting into a fixed-height pane**: pass `class="qm-pane"`. The surface becomes its own scroll container and takes a scroll tail, so the last card can be read at the middle of your pane rather than against its bottom edge. The gutter around the cards narrows, since your frame already stands the stack off your page. Without it the editor grows to its content and your page scrolls, which is what you want when the editor _is_ the page. The preview always scrolls: a viewport onto a document has nothing else to be.
 
 `.qm-pane` is opt-in on the editor rather than the default because the editor is what its own popovers portal into, and a scroll container clips them. In a pane you would have had that clipping from your own scrolling frame anyway; in a page you should not have it at all.
 
@@ -127,7 +127,7 @@ import '@quillmark/svelte/preset';
 </body>
 ```
 
-This is the stylesheet our own apps import: the playground and studio draw with these rules and nothing else, so what you get is what we ship, not a reduction of it.
+This is the stylesheet our own apps import: the playground, studio and quillkit's app client draw with these rules and nothing else, so what you get is what we ship, not a reduction of it.
 
 It carries a `--qmh-*` scale for the page, derived from the same nine dials and calibrated against the surfaces' own steps, so a plate of yours and a card of ours agree about which way "raised" goes. Turning a dial moves both.
 
@@ -173,13 +173,15 @@ An app that mounts an editor beside a preview over one session needs a screen to
 | `.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.                                                                          |
+| `.qm-frame`     | The mounting site: an edge, a corner, and the clip that holds a surface to them. Under the split's threshold it keeps only its top and bottom rules. 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 comes back to them — it rasters nothing at a box it has none of, and repaints only where it returns to a box that draws its pages at another scale. A preview scroll asked for while it was hidden is held and run on the way back, so it opens at the caret rather than several edits behind it. 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.
 
+Every rule behind the five is wrapped in `:where()`, so it computes at specificity zero: a rule of yours on the same element wins at any specificity and in any sheet order, which is what lets a stylesheet written by someone other than the app's author (an `app.css` over quillkit's app client) restyle a band without knowing which shell rules set it.
+
 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** and at ordinary specificity, so your own rules beat it by ordinary precedence. It is also opt-in and side-effect free until imported: nothing that styles your document arrives with a component.
+It is **unlayered**, and nothing in it outranks a rule of yours aimed at the same element: the page, type, status and control recipes compute at ordinary specificity, so your own rules beat them by ordinary precedence, and the shell and the app chrome compute at specificity zero, as the surfaces do. It is also opt-in and side-effect free until imported: nothing that styles your document arrives with a component.
 
 One rule in it earns its place regardless of whether you take the rest, and you want it if you draw a focus ring of your own — cut the mounted surfaces out of the blanket:
 
@@ -191,6 +193,38 @@ One rule in it earns its place regardless of whether you take the rest, and you
 
 A blanket `:focus-visible` of yours outranks ours, including on the controls that already draw one, so a ring written for the controls that draw none repaints the ones that do. The cut-out leaves yours everywhere else, and `:not(:where(…))` contributes no specificity, so your rule ranks exactly as it would without it.
 
+### The app chrome
+
+A tool's bands are yours, since a tool's head is the most app-specific thing on its screen. An app whose whole page is one form to fill in has less to say there: a name, the action the page leads to, and a line signing it. Four classes draw that much, quillkit's app client wears them, and a host of its own takes them the same way:
+
+| Class             | What it is                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| `.qm-app-header`  | The band naming the app: a plate, a gutter and a hairline under it. Put it beside `.qm-bar`.                    |
+| `.qm-app-title`   | What the app is called, at the title rung: the one line on the screen read as a name.                           |
+| `.qm-app-footer`  | The line signing the app, in meta type on the head's plate under a hairline; its links take the line's own ink. |
+| `.qm-app-primary` | The one action the page leads to: the control wearing `--qm-accent`, standing at the touch floor.               |
+
+They compute at specificity zero, as the shell does, so `.qm-app-header { background: #00308f; color: #fff; }` is the whole of rebranding the head.
+
+## What a stylesheet may aim at
+
+A stylesheet you write against a mounted surface, or one an author writes over an app someone else built, may aim at these and nothing else:
+
+- the nine dials (§"The dials");
+- the surface roots, `.qm-editor` and `.qm-preview`, and `.qm-pane`;
+- `data-qm-card="<kind>"`, on the box of every card the editor draws, its value the card's kind and `main` for the main card;
+- the preset's classes, on your own DOM, if you import it (§"Match ours").
+
+`data-qm-card` is the one hook named by the schema rather than by the package: a rule aimed at a kind lands on that kind's cards wherever the editor puts them, which is the one thing a quill-specific restyle needs and a dial cannot say.
+
+```css
+[data-qm-card='indorsement'] {
+	border-left: 3px solid var(--qm-accent);
+}
+```
+
+Nothing names a field or a property. Every other `data-qm-*` attribute the surfaces carry, `data-qm-prop` among them, is something the surface queries itself, and moves when it does.
+
 ## What is deliberately not public
 
 The two root classes and `.qm-pane` are the whole class contract on the surfaces. Every other `qm-*` class inside them is internal and renames without notice: a class contract over the interior would freeze the DOM shape the surfaces are free to re-cut, and the dials already reach the values a restyle wants. The preset's classes are a contract of their own: they land on _your_ DOM, so they freeze nothing of ours.
@@ -200,3 +234,5 @@ The derived surface scale (surface / border / ink rungs, the blur radius, the po
 ## Requirements
 
 `:where()`, `color-mix()`, `light-dark()` and relative colour syntax (`oklab(from …)`): Baseline since 2021, 2023, 2024 and 2024 respectively — the last is what lets a plane step by the card's own lightness. `@property` is the one feature the surface does not require: where it is missing, an invalid length dial collapses the surface rather than falling back.
+
+Build your stylesheets for browsers that carry `light-dark()` natively. A minifier targeting older ones lowers each pole to a pair of variables only an element declaring `color-scheme` defines, and the preset states its poles at `:root`, where that pair is two colours at once and no colour: the primary press and the error hue draw nothing. Under Vite, `build.cssTarget: ['chrome123', 'edge123', 'firefox128', 'safari18']`.

package/dist/core/address.d.ts

@@ -1,22 +1,16 @@
 import type { Addr, HitGranularity, PathStep } from '@quillmark/wasm';
 /**
- * A canonical field address: `main.<field>` / `main.body` /
- * `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
- * `session.regions()` keys already use. An alias over `string`: the boundary
- * exports the parser and the segment type, not a nominal type, so this names the
- * grammar at a signature rather than inventing a checked one.
+ * A canonical field address: `main.<field>` / `main.body` / `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 `session.regions()` keys use. An
+ * alias over `string`: the boundary exports no nominal type.
  */
 export type DocPath = string;
 /**
- * A place in the document: a field and a caret within it. What the editor reports
- * when its caret moves and what the preview scrolls to, so the editor→preview hop
- * is `onCaretMove={preview.focusPosition}` and translates nothing.
- *
- * `pos` is USV, the shared content coordinate on both sides of the boundary: a
- * `ContentHit` is a `Place` with its own extras, and fits wherever one is taken.
+ * A place in the document: a field and a caret within it. What the editor reports when its caret
+ * moves and what the preview scrolls to, so `onCaretMove={preview.focusPosition}` translates
+ * nothing. `pos` is USV, the coordinate shared on both sides of the boundary; a `ContentHit` is a
+ * `Place` with extras.
  */
 export interface Place {
     field: DocPath;
@@ -24,13 +18,10 @@ export interface Place {
     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.
+ * Where a preview click landed: what the preview surfaces and 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 the landing is
+ * a focus.
  */
 export interface Landing {
     field: DocPath;
@@ -41,67 +32,47 @@ export interface Landing {
     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.
+ * 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.
  *
  * - `{}` → `"main.body"`
  * - `{field}` → `"main.<field>"`
  * - `{card: i}` → `"cards.<kind>[i].body"`
  * - `{card: i, field}` → `"cards.<kind>[i].<field>"`
  *
- * `steps` descend from the field to a leaf inside it, the inverse of
- * {@link nestedAddrForFieldPath}: `{field: 'contact'}` with `['email']` is
- * `"main.contact.email"`, `{field: 'keywords'}` with `[0]` is `"main.keywords[0]"`. A body
- * holds no cells, so a field-less address with steps is `undefined`.
- *
- * `cards[i]` stands in for an unknown or blank kind. The index is the addr's own: no
- * per-kind counting, since `DocPath` addresses cards by document-array index.
+ * `steps` descend from the field to a leaf inside it, the inverse of {@link
+ * nestedAddrForFieldPath}: `{field: 'keywords'}` with `[0]` is `"main.keywords[0]"`. A body holds
+ * no cells, so a field-less address with steps is `undefined`. `cards[i]` stands in for an unknown
+ * or blank kind; the index is the addr's own, `DocPath` addressing cards by document-array index.
  */
 export declare function fieldPathForAddr(addr: Addr, kinds: readonly string[], steps?: readonly PathStep[]): DocPath | undefined;
 /**
- * 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`.
+ * A card's own path (`cards.<kind>[i]`), what a structure op names. `undefined` for an index
+ * outside `kinds`.
  */
 export declare function cardPath(index: number, kinds: readonly string[]): DocPath | 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.keywords[0]`, which {@link nestedAddrForFieldPath} and
- * {@link nearestAddrForFieldPath} take 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.
+ * 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 (see {@link
+ * nestedAddrForFieldPath} and {@link nearestAddrForFieldPath}), a field-rooted one, or a malformed
+ * one. A bare card and a `.body` terminal both land on the field-less `{card: i}`. Needs no
+ * `kinds`: the path carries the absolute index.
  */
 export declare function addrForFieldPath(path: DocPath): Addr | undefined;
 /**
- * The nearest ancestor a commit address can name: {@link addrForFieldPath} where the
- * path has one, else the root and its first field. `main.contact.email` and
- * `main.keywords[0]` land on their field, any deeper nesting on the top-level field
- * it hangs off. `undefined` where those two segments name nothing — a field-rooted
- * (config-space) or malformed path.
- *
- * An `Addr` reaches a root and one field, so two segments is the whole search: a
- * deeper prefix is unaddressable by arity alone. Addressability being `Addr`'s reach
- * rather than the grammar's is what makes the truncation a consumer's to make
- * (VISUAL_EDITOR §Diagnostics).
+ * The nearest ancestor a commit address can name: {@link addrForFieldPath} where the path has one,
+ * else the root and its first field (`main.contact.email` and `main.keywords[0]` land on their
+ * field). `undefined` for a field-rooted (config-space) or malformed path. An `Addr` reaches a root
+ * and one field, so the truncation is a consumer's to make (VISUAL_EDITOR §Diagnostics).
  */
 export declare function nearestAddrForFieldPath(path: DocPath): Addr | undefined;
 /**
- * A nested address, split: the field's `Addr`, and the steps from it to the leaf.
- * `main.keywords[0]` is `{field: keywords, steps: [0]}`,
- * `main.vectors[0].tours[2].title` is `[0, 'tours', 2, 'title']`, and
- * `main.contact.email` is `['email']`: an index segment reads as a number and a key as
- * a string, the `PathStep` grammar `reader.getContentAt` walks. Anything
- * {@link addrForFieldPath} can name — a field, a body, a card — has no steps and lands
- * here as `undefined`; so does a body with something after it, a body holding no
- * cells. Whether the schema declares each step is the caller's to check: this module
- * holds the grammar and no schema. `regions()`, `positionAt` and `formatDocPath` all
- * spell the index segment bracketed, so there is one spelling to read and none to
- * bridge.
+ * A nested address, split: the field's `Addr`, and the steps from it to the leaf (the `PathStep`
+ * grammar `reader.getContentAt` walks). `main.keywords[0]` is `{field: keywords, steps: [0]}`,
+ * `main.contact.email` is `['email']`, `main.vectors[0].tours[2].title` is `[0, 'tours', 2,
+ * 'title']`. Anything {@link addrForFieldPath} can name has no steps and lands here as `undefined`,
+ * as does a body with something after it. Whether the schema declares each step is the caller's to
+ * check.
  */
 export declare function nestedAddrForFieldPath(path: DocPath): NestedAddr | undefined;
 /** A nested address: the field's `Addr`, and the steps from it to the leaf. */

package/dist/core/address.js

@@ -1,27 +1,21 @@
 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
-// (`doc.cards.map(c => c.kind)`), which is all the card segment needs. The editor
-// mints it off its own derived card tree rather than re-reading `doc.cards`, which
-// serializes every card per read and is not a thing to do per keystroke.
+// The one hop between the two vocabularies, pure and document-free: `kinds` is the kind of each
+// card by content index (`doc.cards.map(c => c.kind)`). The editor mints it off its own derived
+// card tree, since `doc.cards` serializes every card per read.
 /**
- * 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.
+ * 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.
  *
  * - `{}` → `"main.body"`
  * - `{field}` → `"main.<field>"`
  * - `{card: i}` → `"cards.<kind>[i].body"`
  * - `{card: i, field}` → `"cards.<kind>[i].<field>"`
  *
- * `steps` descend from the field to a leaf inside it, the inverse of
- * {@link nestedAddrForFieldPath}: `{field: 'contact'}` with `['email']` is
- * `"main.contact.email"`, `{field: 'keywords'}` with `[0]` is `"main.keywords[0]"`. A body
- * holds no cells, so a field-less address with steps is `undefined`.
- *
- * `cards[i]` stands in for an unknown or blank kind. The index is the addr's own: no
- * per-kind counting, since `DocPath` addresses cards by document-array index.
+ * `steps` descend from the field to a leaf inside it, the inverse of {@link
+ * nestedAddrForFieldPath}: `{field: 'keywords'}` with `[0]` is `"main.keywords[0]"`. A body holds
+ * no cells, so a field-less address with steps is `undefined`. `cards[i]` stands in for an unknown
+ * or blank kind; the index is the addr's own, `DocPath` addressing cards by document-array index.
  */
 export function fieldPathForAddr(addr, kinds, steps = []) {
     const head = cardHead(addr.card, kinds);
@@ -35,57 +29,41 @@ export function fieldPathForAddr(addr, kinds, steps = []) {
     return core().formatDocPath(segs);
 }
 /**
- * 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`.
+ * A card's own path (`cards.<kind>[i]`), what a structure op names. `undefined` for an index
+ * outside `kinds`.
  */
 export function cardPath(index, kinds) {
     const head = cardHead(index, kinds);
     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.keywords[0]`, which {@link nestedAddrForFieldPath} and
- * {@link nearestAddrForFieldPath} take 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.
+ * 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 (see {@link
+ * nestedAddrForFieldPath} and {@link nearestAddrForFieldPath}), a field-rooted one, or a malformed
+ * one. A bare card and a `.body` terminal both land on the field-less `{card: i}`. Needs no
+ * `kinds`: the path carries the absolute index.
  */
 export function addrForFieldPath(path) {
     const segs = segsOf(path);
     return segs && addrForSegs(segs);
 }
 /**
- * The nearest ancestor a commit address can name: {@link addrForFieldPath} where the
- * path has one, else the root and its first field. `main.contact.email` and
- * `main.keywords[0]` land on their field, any deeper nesting on the top-level field
- * it hangs off. `undefined` where those two segments name nothing — a field-rooted
- * (config-space) or malformed path.
- *
- * An `Addr` reaches a root and one field, so two segments is the whole search: a
- * deeper prefix is unaddressable by arity alone. Addressability being `Addr`'s reach
- * rather than the grammar's is what makes the truncation a consumer's to make
- * (VISUAL_EDITOR §Diagnostics).
+ * The nearest ancestor a commit address can name: {@link addrForFieldPath} where the path has one,
+ * else the root and its first field (`main.contact.email` and `main.keywords[0]` land on their
+ * field). `undefined` for a field-rooted (config-space) or malformed path. An `Addr` reaches a root
+ * and one field, so the truncation is a consumer's to make (VISUAL_EDITOR §Diagnostics).
  */
 export function nearestAddrForFieldPath(path) {
     const segs = segsOf(path);
     return segs && addrForSegs(segs.slice(0, 2));
 }
 /**
- * A nested address, split: the field's `Addr`, and the steps from it to the leaf.
- * `main.keywords[0]` is `{field: keywords, steps: [0]}`,
- * `main.vectors[0].tours[2].title` is `[0, 'tours', 2, 'title']`, and
- * `main.contact.email` is `['email']`: an index segment reads as a number and a key as
- * a string, the `PathStep` grammar `reader.getContentAt` walks. Anything
- * {@link addrForFieldPath} can name — a field, a body, a card — has no steps and lands
- * here as `undefined`; so does a body with something after it, a body holding no
- * cells. Whether the schema declares each step is the caller's to check: this module
- * holds the grammar and no schema. `regions()`, `positionAt` and `formatDocPath` all
- * spell the index segment bracketed, so there is one spelling to read and none to
- * bridge.
+ * A nested address, split: the field's `Addr`, and the steps from it to the leaf (the `PathStep`
+ * grammar `reader.getContentAt` walks). `main.keywords[0]` is `{field: keywords, steps: [0]}`,
+ * `main.contact.email` is `['email']`, `main.vectors[0].tours[2].title` is `[0, 'tours', 2,
+ * 'title']`. Anything {@link addrForFieldPath} can name has no steps and lands here as `undefined`,
+ * as does a body with something after it. Whether the schema declares each step is the caller's to
+ * check.
  */
 export function nestedAddrForFieldPath(path) {
     const segs = segsOf(path);
@@ -105,9 +83,10 @@ export function nestedAddrForFieldPath(path) {
     }
     return { field, steps };
 }
-/** `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. */
+/**
+ * `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.
+ */
 function segsOf(path) {
     const { parseDocPath } = core();
     try {
@@ -117,8 +96,7 @@ function segsOf(path) {
         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. */
+/** {@link addrForFieldPath} over already-parsed segments. */
 function addrForSegs(segs) {
     const [head, ...rest] = segs;
     if (!head)
@@ -141,8 +119,10 @@ function addrForSegs(segs) {
         return { ...addr, field: tail.name };
     return undefined;
 }
-/** The head segment a card index resolves to, or `undefined` when it is out of the
- *  live array. `null` kind is the unknown-kind form the grammar spells `cards[i]`. */
+/**
+ * The head segment a card index resolves to, or `undefined` when out of the live array. A falsy
+ * kind is the unknown-kind form `cards[i]`.
+ */
 function cardHead(index, kinds) {
     if (index == null)
         return { seg: 'main' };

package/dist/core/bloom.d.ts

@@ -1,13 +1,7 @@
 /**
- * Run one wash over `host`, a `.qm-wash` box, resolving the dwell off its root so the
- * number is single-sourced in CSS (`core/rungs.ts`).
- *
- * 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
- * number and the one half CSS cannot hand over.
- *
- * A run in flight on the same host is cancelled first: two quick landings on one leaf
- * must not stack two alphas over it.
+ * Run one wash over `host`, a `.qm-wash` box, resolving the dwell off its root so the number is
+ * single-sourced in CSS (`core/rungs.ts`). `--_qm-bloom-dwell` already shortens under
+ * `prefers-reduced-motion`, so `matchMedia` here only picks the frame list. A run in flight on the
+ * same host is cancelled first, so two quick landings do not stack alphas.
  */
 export declare function bloom(host: HTMLElement): void;

package/dist/core/bloom.js

@@ -1,24 +1,17 @@
-// The arrival wash: a soft accent bloom that rises over a leaf the editor just
-// landed on and decays to nothing. A landing is an event, not a state, so a
-// highlight that outlives the hop that caused it is ink nothing asked for.
+// The arrival wash: a soft accent bloom that rises over a leaf the editor just landed on and decays
+// to nothing. A landing is an event, not a state, so a highlight that outlives the hop is ink
+// nothing asked for.
 //
-// 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.
-//
-// The wash is the host's `::after` (`.qm-wash`, controls.css), drawn from mount: this
-// module plays it and adds nothing to the tree.
+// Opacity is the animated property, never the colour: the wash's alpha is a peak fixed by
+// `--_qm-accent-wash`, so the scale stays in CSS where `color-mix` resolves. The wash is the host's
+// `::after` (`.qm-wash`, controls.css); this module plays it and adds nothing to the tree.
 import { rungStyle } from './rungs.js';
 const WASH = '::after';
-/** The dwell used when the derivation is out of reach (an unstyled root, or jsdom,
- *  where `getComputedStyle` reports custom properties as empty). A fallback is the
- *  absence of the scale, not a copy of it. */
+/** The dwell used when the derivation is out of reach (an unstyled root, or jsdom). */
 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
-// ramps are dropped entirely: the wash holds at full for a beat and cuts, which
-// still answers "here" with nothing to track.
+// Rise fast, hold, then leave slowly: a highlighter's decay. A keyframe's easing governs the
+// segment that starts at it. Under reduced motion the ramps are dropped: the wash holds at full for
+// a beat and cuts.
 const FRAMES = [
     { opacity: 0, offset: 0, easing: 'ease-out' },
     { opacity: 1, offset: 0.08 },
@@ -27,16 +20,10 @@ const FRAMES = [
 ];
 const FRAMES_REDUCED = [{ opacity: 1 }, { opacity: 1 }];
 /**
- * Run one wash over `host`, a `.qm-wash` box, resolving the dwell off its root so the
- * number is single-sourced in CSS (`core/rungs.ts`).
- *
- * 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
- * number and the one half CSS cannot hand over.
- *
- * A run in flight on the same host is cancelled first: two quick landings on one leaf
- * must not stack two alphas over it.
+ * Run one wash over `host`, a `.qm-wash` box, resolving the dwell off its root so the number is
+ * single-sourced in CSS (`core/rungs.ts`). `--_qm-bloom-dwell` already shortens under
+ * `prefers-reduced-motion`, so `matchMedia` here only picks the frame list. A run in flight on the
+ * same host is cancelled first, so two quick landings do not stack alphas.
  */
 export function bloom(host) {
     if (typeof host.animate !== 'function')