@quillmark/svelte 0.26.2 → 0.28.0

package/dist/core/errors.d.ts

@@ -1,7 +1,7 @@
 import type { DocPath } from './address.js';
 /**
- * What failed. Stable strings rather than an enum: a consumer switches on them,
- * and a new surface adds a code without moving the ones an app already handles.
+ * What failed. Stable strings rather than an enum: a consumer switches on them, and a new surface
+ * adds a code without moving the ones an app handles.
  */
 export type EditorErrorCode = 
 /** A scalar/array/object write the boundary refused. Also pinned as a
@@ -27,37 +27,26 @@ export type EditorErrorCode =
 /** A tip's markdown did not render: the tip shows as literal text. */
  | 'tip-render-failed'
 /**
- * A prop a surface binds once was swapped in place, and the surface neither
- * 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`).
+ * A prop a surface binds once was swapped in place, and the surface neither re-keyed on it nor
+ * observed it. `dev`: the fix is a remount at the call site. 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 just replaced (`rebind.svelte.ts`).
  */
  | 'rebind-ignored'
 /**
- * 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`.
+ * A landing named a card or a field the surface does not hold: a stale `cardId`, or a `DocPath`
+ * naming no declared field (an array element path included where the array is undeclared or
+ * unmounted). The call is a no-op. `dev`: the fix is at the call site, a host driving the
+ * instance verbs or a preview pick the editor has no field to route to. The preview never
+ * reports it: a field it places nothing for is `scrollToField` returning `false`.
  */
  | 'target-unknown';
 /** A failure a surface recovered from. */
 export interface EditorError {
     code: EditorErrorCode;
     /**
-     * `error` is a runtime failure an app routes to telemetry; `dev` is a contract
-     * violation aimed at whoever is building against the package. Without the
-     * split every consumer's sink filters the dev codes by hand.
+     * `error` is a runtime failure an app routes to telemetry; `dev` a contract violation aimed at
+     * whoever builds against the package.
      */
     severity: 'error' | 'dev';
     /** English, for a log. Not for display: nothing here has a place on screen. */
@@ -72,12 +61,8 @@ export interface EditorError {
 /** The `onError` hook every surface takes. */
 export type EditorErrorHandler = (err: EditorError) => void;
 /**
- * Report `err`, or log it when nothing is listening: a failure the package
- * recovered from is worth seeing in a console.
- *
- * A throwing handler is the consumer's bug and must not become the package's: it
- * is caught, because every call site sits on a recovery path where a second throw
- * would undo the recovery.
+ * Report `err`, or log it when nothing is listening. A throwing handler is caught: every call site
+ * sits on a recovery path where a second throw would undo the recovery.
  */
 export declare function reportError(handler: EditorErrorHandler | undefined, err: EditorError): void;
 /** A thrown value's message, for the `message` field. */

package/dist/core/errors.js

@@ -1,10 +1,6 @@
 /**
- * Report `err`, or log it when nothing is listening: a failure the package
- * recovered from is worth seeing in a console.
- *
- * A throwing handler is the consumer's bug and must not become the package's: it
- * is caught, because every call site sits on a recovery path where a second throw
- * would undo the recovery.
+ * Report `err`, or log it when nothing is listening. A throwing handler is caught: every call site
+ * sits on a recovery path where a second throw would undo the recovery.
  */
 export function reportError(handler, err) {
     if (!handler) {

package/dist/core/index.js

@@ -1,17 +1,12 @@
 // `@quillmark/svelte/core`: what this package owns at the substrate seam.
 //
-// The `@quillmark/wasm` API is not re-exported: import it straight from the peer
-// dependency, the single source of truth (quiver states the same rule). The
-// handles cross this package's surfaces untouched (no wrapper types, per
-// DOCUMENT_MODEL §What the editor owns), so the boundary needs no second door
-// here. What earns a line is what more than one surface speaks and no other
-// package declares: the address vocabulary and the error channel, plus the WASM
-// init gate.
+// The `@quillmark/wasm` API is not re-exported: import it from the peer dependency. What earns a
+// line here is what more than one surface speaks and no other package declares: the address
+// vocabulary, the error channel, and the WASM init gate.
 //
-// No stylesheet: a host reaches this entry where there is no document (a worker,
-// a server), and a dev server serves a side-effect sheet as a module that writes a
-// `<style>` into one. The surface barrels carry the theme; `check:deps` holds it.
+// No stylesheet: a host reaches this entry where there is no document (a worker, a server), and a
+// dev server serves a side-effect sheet as a module that writes a `<style>` into one. The surface
+// barrels carry the theme; `check:deps` holds it.
 export { init } from './lifecycle.js';
-// The hop between that vocabulary and the `Addr` the document verbs take, both
-// directions: a host handed a path by a hook and holding a mutator needs it.
+// The hop between that vocabulary and the `Addr` the document verbs take.
 export { fieldPathForAddr, addrForFieldPath } from './address.js';

package/dist/core/lifecycle.d.ts

@@ -1,23 +1,14 @@
 import { type CoreSurface } from '@quillmark/wasm';
 /**
- * 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.
+ * Instantiate the core WASM build and resolve to its surface. Await once before any other boundary
+ * verb; the promise is memoized, so concurrent callers share one instantiation, and a failed init
+ * clears the memo so a retry is possible. The surface is the artifact's own, handed back unchanged.
  */
 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.
+ * The surface synchronously, for this package's pure verbs (the `DocPath` formatter and the codec
+ * inside a ProseMirror transaction), which cannot await. Package-internal, and read at the call
+ * rather than destructured at module scope. Reaching it before {@link init} resolves throws, naming
+ * the fix.
  */
 export declare function core(): CoreSurface;

package/dist/core/lifecycle.js

@@ -1,21 +1,14 @@
-// `@quillmark/wasm` ships wasm-bindgen's web target: the core build is
-// instantiated by an explicit `await init()`, which resolves to the classes and
-// free functions — the artifact exports none of them statically, so awaiting is
-// the only way to hold one. Instantiation carries the panic hook on its start
-// section, so a Rust panic reaches JS as a stack trace.
+// `@quillmark/wasm` ships wasm-bindgen's web target: the core build is instantiated by an explicit
+// `await init()`, which resolves to the classes and free functions, none of which the artifact
+// exports statically. Instantiation installs the panic hook on its start section.
 import { init as initWasm } from '@quillmark/wasm';
 let started;
 /** The resolved surface, for the sync verbs below that cannot await one. */
 let latched;
 /**
- * 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.
+ * Instantiate the core WASM build and resolve to its surface. Await once before any other boundary
+ * verb; the promise is memoized, so concurrent callers share one instantiation, and a failed init
+ * clears the memo so a retry is possible. The surface is the artifact's own, handed back unchanged.
  */
 export function init() {
     if (started)
@@ -30,14 +23,10 @@ export function init() {
     return started;
 }
 /**
- * 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.
+ * The surface synchronously, for this package's pure verbs (the `DocPath` formatter and the codec
+ * inside a ProseMirror transaction), which cannot await. Package-internal, and read at the call
+ * rather than destructured at module scope. Reaching it before {@link init} resolves throws, naming
+ * the fix.
  */
 export function core() {
     if (!latched) {

package/dist/core/rebind.svelte.d.ts

@@ -4,29 +4,19 @@ export type Bound = Record<string, unknown> & {
     onError?: EditorErrorHandler;
 };
 /**
- * Report the violation, then throw it in a dev build. Both surfaces raise it here; the
- * guards themselves stay separate, since the preview snapshots its props once and the
- * editor re-reads its pair on every re-key.
+ * Report the violation, then throw it in a dev build. Both surfaces raise it here; their guards
+ * stay separate, since the preview snapshots its props once and the editor re-reads its pair on
+ * every re-key.
  *
- * The report alone reaches whoever bound `onError` at mount, and a consumer swapping
- * that handler beside the handle it belongs to is the case this exists for: they are
- * told through the sink they just abandoned. A throw needs no handler to arrive.
- *
- * It costs the surface nothing: an effect that throws neither unmounts its tree nor
- * stops the ones beside it, so the surface goes on serving what it bound, which is the
- * very state being reported.
+ * The report alone reaches whoever bound `onError` at mount, so a consumer swapping that handler
+ * beside its handle is told through the sink they just abandoned; a throw needs no handler. The
+ * throw costs nothing: an effect that throws neither unmounts its tree nor stops its neighbours.
  */
 export declare function reportRebindIgnored(onError: EditorErrorHandler | undefined, message: string): void;
 /**
- * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped
- * in place, and in a dev build throw it after. `remount` closes the message with the
- * surface's own remount spelling (`Remount the preview ({#key session}) to rebind.`).
- *
- * Mounted identities are recorded on the effect's first run, the flush the surface
- * binds in; every later comparison reads them through the same `snapshot`.
- *
- * The report goes to the snapshot's `onError`: every other error these surfaces
- * report reaches the handler they bound, and a swapped `onError` is itself one of
- * the reports.
+ * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped in place, and
+ * in a dev build throw it after. `remount` closes the message with the surface's own remount
+ * spelling. Mounted identities are recorded on the effect's first run. The report goes to the
+ * snapshot's `onError`, which a swap is itself one of the reports for.
  */
 export declare function guardRebind(snapshot: () => Bound, remount: string): void;

package/dist/core/rebind.svelte.js

@@ -1,25 +1,19 @@
-// The remount contract, enforced. `Preview` binds its props once, when its container
-// mounts, and observes nothing after: the vanilla core below it owns scroll position,
-// mounted slots and observer sets that a remount would discard on every apply. So a
-// prop swapped in place is reported, not dropped in silence, and thrown in a dev build.
+// The remount contract, enforced. `Preview` binds its props once, at mount, and observes nothing
+// after: the vanilla core below it owns scroll position, mounted slots and observer sets that a
+// remount would discard. So a prop swapped in place is reported, and thrown in a dev build.
 //
-// A guard over one prop of a set is worse than none: a consumer who learns the
-// surface complains when it ignores a prop reads silence on the rest as reactivity.
-// The snapshot is every once-bound prop, and one report names whichever went stale.
+// A guard over part of a set teaches a consumer to read silence on the rest as reactivity, so the
+// snapshot is every once-bound prop and one report names whichever went stale.
 import { DEV } from 'esm-env';
 import { reportError } from './errors.js';
 /**
- * Report the violation, then throw it in a dev build. Both surfaces raise it here; the
- * guards themselves stay separate, since the preview snapshots its props once and the
- * editor re-reads its pair on every re-key.
+ * Report the violation, then throw it in a dev build. Both surfaces raise it here; their guards
+ * stay separate, since the preview snapshots its props once and the editor re-reads its pair on
+ * every re-key.
  *
- * The report alone reaches whoever bound `onError` at mount, and a consumer swapping
- * that handler beside the handle it belongs to is the case this exists for: they are
- * told through the sink they just abandoned. A throw needs no handler to arrive.
- *
- * It costs the surface nothing: an effect that throws neither unmounts its tree nor
- * stops the ones beside it, so the surface goes on serving what it bound, which is the
- * very state being reported.
+ * The report alone reaches whoever bound `onError` at mount, so a consumer swapping that handler
+ * beside its handle is told through the sink they just abandoned; a throw needs no handler. The
+ * throw costs nothing: an effect that throws neither unmounts its tree nor stops its neighbours.
  */
 export function reportRebindIgnored(onError, message) {
     reportError(onError, { code: 'rebind-ignored', severity: 'dev', message });
@@ -27,16 +21,10 @@ export function reportRebindIgnored(onError, message) {
         throw new Error(`[quillmark/ui] rebind-ignored: ${message}`);
 }
 /**
- * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped
- * in place, and in a dev build throw it after. `remount` closes the message with the
- * surface's own remount spelling (`Remount the preview ({#key session}) to rebind.`).
- *
- * Mounted identities are recorded on the effect's first run, the flush the surface
- * binds in; every later comparison reads them through the same `snapshot`.
- *
- * The report goes to the snapshot's `onError`: every other error these surfaces
- * report reaches the handler they bound, and a swapped `onError` is itself one of
- * the reports.
+ * Report `rebind-ignored` once, at `dev`, when any prop `snapshot` names is swapped in place, and
+ * in a dev build throw it after. `remount` closes the message with the surface's own remount
+ * spelling. Mounted identities are recorded on the effect's first run. The report goes to the
+ * snapshot's `onError`, which a swap is itself one of the reports for.
  */
 export function guardRebind(snapshot, remount) {
     let mounted;

package/dist/core/rungs.d.ts

@@ -1,14 +1,17 @@
-/** The element the scale is declared on, for `node`: its root, or `node` where it stands
- *  outside one (a detached surface, a consumer's own mount). */
+/**
+ * The style of the element the scale is declared on for `node`: its root, or `node` where it stands
+ * outside one.
+ */
 export declare function rungStyle(node: Element): CSSStyleDeclaration;
-/** A duration rung off `style`, in ms; `undefined` where the derivation is out of reach
- *  (an unstyled root, or jsdom, where `getComputedStyle` reports custom properties as
- *  empty). No rung, no motion: a fallback here would be the scale restated in the one
- *  place `check:style` cannot read. */
+/**
+ * A duration rung off `style`, in ms; `undefined` where the derivation is out of reach (an unstyled
+ * root, or jsdom). No rung, no motion: a fallback would restate the scale where `check:style`
+ * cannot read it.
+ */
 export declare function rungMs(style: CSSStyleDeclaration, rung: string): number | undefined;
-/** `steps` of the space rung off `node`'s root, in px: a floating surface's offset from
- *  its anchor. `--_qm-space` is registered, so it computes to px where the rungs derived
- *  from it compute to their expressions; hence the multiple rather than a read of
- *  `--_qm-space-2`. `undefined` where the derivation is out of reach, as for
- *  {@link rungMs}. */
+/**
+ * `steps` of the space rung off `node`'s root, in px: a floating surface's offset from its anchor.
+ * `--_qm-space` is registered so it computes to px, unlike the rungs derived from it. `undefined`
+ * where the derivation is out of reach, as for {@link rungMs}.
+ */
 export declare function spacePx(node: Element | undefined, steps?: number): number | undefined;

package/dist/core/rungs.js

@@ -1,20 +1,18 @@
-// Where a script reads the scale. The derivation declares every `--_qm-*` rung on
-// `[data-qm-root]` and nowhere else (`core/theme.css`), so a descendant's value is that
-// one inherited and the root is the element the question is about: asking a leaf three
-// containers deep is asking an arbitrary element what the surface is set to.
-//
-// The read is also the cost. `getComputedStyle` compounds with nesting depth under jsdom,
-// so a suite that resolves rungs off landed elements pays the depth of whatever it landed
-// on; resolving them off the root pays the root's.
-/** The element the scale is declared on, for `node`: its root, or `node` where it stands
- *  outside one (a detached surface, a consumer's own mount). */
+// Where a script reads the scale. The derivation declares every `--_qm-*` rung on `[data-qm-root]`
+// and nowhere else (`core/theme.css`), so the root is the element to ask. Resolving off the root
+// also costs less: `getComputedStyle` compounds with nesting depth under jsdom.
+/**
+ * The style of the element the scale is declared on for `node`: its root, or `node` where it stands
+ * outside one.
+ */
 export function rungStyle(node) {
     return getComputedStyle(node.closest('[data-qm-root]') ?? node);
 }
-/** A duration rung off `style`, in ms; `undefined` where the derivation is out of reach
- *  (an unstyled root, or jsdom, where `getComputedStyle` reports custom properties as
- *  empty). No rung, no motion: a fallback here would be the scale restated in the one
- *  place `check:style` cannot read. */
+/**
+ * A duration rung off `style`, in ms; `undefined` where the derivation is out of reach (an unstyled
+ * root, or jsdom). No rung, no motion: a fallback would restate the scale where `check:style`
+ * cannot read it.
+ */
 export function rungMs(style, rung) {
     const raw = style.getPropertyValue(rung).trim();
     const n = Number.parseFloat(raw);
@@ -22,11 +20,11 @@ export function rungMs(style, rung) {
         return undefined;
     return raw.endsWith('ms') ? n : n * 1000;
 }
-/** `steps` of the space rung off `node`'s root, in px: a floating surface's offset from
- *  its anchor. `--_qm-space` is registered, so it computes to px where the rungs derived
- *  from it compute to their expressions; hence the multiple rather than a read of
- *  `--_qm-space-2`. `undefined` where the derivation is out of reach, as for
- *  {@link rungMs}. */
+/**
+ * `steps` of the space rung off `node`'s root, in px: a floating surface's offset from its anchor.
+ * `--_qm-space` is registered so it computes to px, unlike the rungs derived from it. `undefined`
+ * where the derivation is out of reach, as for {@link rungMs}.
+ */
 export function spacePx(node, steps = 1) {
     if (!node)
         return undefined;

package/dist/core/teardown.d.ts

@@ -3,15 +3,13 @@ export interface Lifespan {
     /** False once the span has ended. */
     readonly alive: boolean;
     /**
-     * Register work to undo at the end: a registry entry to drop, a timer or frame
-     * to cancel, a handle to free. Cancellers run in registration order, which is
-     * where the order lives. Registering on an ended span runs the canceller at
-     * once: there is no later run to hold it for.
+     * Register work to undo at the end (a registry entry, a timer, a handle), run in registration
+     * order. On an ended span the canceller runs at once.
      */
     onEnd(cancel: () => void): void;
     /**
-     * Await `pending`, then report whether the surface survived the window. `false`
-     * is a continuation to drop: what it captured before the await is gone.
+     * Await `pending`, then report whether the surface survived the window; `false` is a
+     * continuation to drop.
      */
     resumes(pending: Promise<unknown>): Promise<boolean>;
     /** Run the cancellers once and end the span. Idempotent. */

package/dist/core/teardown.js

@@ -1,12 +1,10 @@
-// The teardown order every surface holds: unregister, cancel, then free.
+// The teardown order every surface holds: unregister, cancel, then free. An order rather than a
+// list, because work is deferred: freeing first leaves a scheduled continuation holding what nobody
+// owns, and cancelling while still registered still takes the next event.
 //
-// An order rather than a list, because work is deferred: a surface that frees
-// first leaves a scheduled continuation holding what nobody owns, and one that
-// cancels first but stays registered still takes the next event.
-//
-// `Lifespan` carries it. A surface builds one, registers its cancellers in the
-// order they must run, and ends the span once; continuations that cross an await
-// ask `resumes()` rather than a flag they captured before it.
+// A surface builds a `Lifespan`, registers its cancellers in the order they must run, and ends the
+// span once; continuations that cross an await ask `resumes()` rather than a flag captured before
+// it.
 export function createLifespan() {
     let alive = true;
     const cancels = [];
@@ -26,8 +24,7 @@ export function createLifespan() {
         end() {
             if (!alive)
                 return;
-            // Dead before the cancellers run: one of them may synchronously reach
-            // something that asks, and a span mid-teardown is not alive.
+            // Dead before the cancellers run: one may synchronously ask.
             alive = false;
             for (const cancel of cancels)
                 cancel();