@quillmark/svelte 0.2.0 → 0.3.0

package/dist/preset/scale.css

@@ -1,12 +1,15 @@
-/* THE HOST'S DERIVATION: the same public dials in, a closed `--qmh-*` scale for the
-   page AROUND the surfaces out. `core/theme.css` is the same shape one level down
-   (dials in, `--_qm-*` out), and the two are calibrated against each other: the mixes
-   here are the percentages there (4pp between surface steps, 17% border, 45% and 60%
-   ink), so a host plate and a card on it agree about which way "raised" goes and land
-   on the same tone at both poles.
+/* The host'S derivation: the same public dials in, a closed `--qmh-*` scale for the
+   page around the surfaces out. `core/theme.css` is the same shape one level down
+   (dials in, `--_qm-*` out), and the two are calibrated against each other: the
+   figures here are the figures there (the ground step's two arms, 8% hover, 17%
+   border, 45% and 60% ink) and the dial means the same plane in both, so a host plate
+   and a card on it land on the same tone at both poles and a host page meets an
+   editor's own column exactly. The well under the ground has no counterpart here: a
+   host's own controls are boxed and carry a hairline, so nothing on a page needs the
+   step an edgeless field does.
 
-   TWO SCALES rather than one because they answer to different roots. `--_qm-*` is
-   declared ON each mounted root, out of reach from an ancestor, so a surface holds its
+   Two scales rather than one because they answer to different roots. `--_qm-*` is
+   declared on each mounted root, out of reach from an ancestor, so a surface holds its
    scale wherever it is dropped. A host scale has the opposite job: it is the document,
    so it is declared at `:root` and everything on the page reads it. A single namespace
    could not be both.
@@ -14,26 +17,34 @@
    Literals live here and nowhere else in the preset: `check:style` runs its axes over
    `recipes.css` beside it, with this file exempt as the place the defaults are minted.
 
-   The poles fall back to the SYSTEM colours, so a host that turns no dial still lands
-   where its own unstyled text does. The dials sit in front, so `--qm-bg`/`--qm-fg` on
-   an ancestor retunes page and surface together. */
+   The poles fall back to the system colours, so a host that turns no dial still lands
+   where its own unstyled text does — `Canvas` being the plane the UA would have
+   painted a page with, which is what a plate should be. The dials sit in front, so
+   `--qm-bg`/`--qm-fg` on an ancestor retunes page and surface together. */
 
 :root {
 	/* ── Colour ──────────────────────────────────────────────────────────────── */
-	--qmh-page: var(--qm-bg, Canvas);
+	/* The dial is the plate, exactly as it is the card one level down: a plate beside
+	   a mounted editor is the same plane as a card in it, so both read the pole and
+	   the page sinks from it by the same two arms. That is what puts a host page and
+	   an editor's own column on one tone rather than a plane apart. Planes step by
+	   light and everything else by ink, which is the package's own split
+	   (ARCHITECTURE §Styling); the figures are its figures. */
+	--qmh-surface: var(--qm-bg, Canvas);
+	--qmh-page: light-dark(
+		oklab(from var(--qmh-surface) calc(l - 0.0214) calc(a - 0.00065) calc(b - 0.00158)),
+		oklab(from var(--qmh-surface) calc(l - 0.0553) calc(a - 0.00048) calc(b + 0.00165))
+	);
 	--qmh-ink: var(--qm-fg, CanvasText);
-	--qmh-ink-meta: color-mix(in oklab, var(--qmh-ink), var(--qmh-page) 45%);
-	--qmh-ghost: color-mix(in oklab, var(--qmh-ink), var(--qmh-page) 60%);
-	/* Two planes behind content, 4pp apart exactly as the surfaces step, so a host
-	   plate and a card on it agree about which way "raised" goes in both schemes. */
-	--qmh-surface: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 4%);
-	--qmh-surface-hover: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 8%);
-	--qmh-border: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 17%);
+	--qmh-ink-meta: color-mix(in oklab, var(--qmh-ink), var(--qmh-surface) 45%);
+	--qmh-ghost: color-mix(in oklab, var(--qmh-ink), var(--qmh-surface) 60%);
+	--qmh-surface-hover: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 8%);
+	--qmh-border: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 17%);
 	/* The edge that says "engaged" where the hairline says "edge": a pressed switch,
 	   the underline under a link. */
-	--qmh-border-strong: color-mix(in oklab, var(--qmh-page), var(--qmh-ink) 40%);
+	--qmh-border-strong: color-mix(in oklab, var(--qmh-surface), var(--qmh-ink) 40%);
 
-	/* The two hues a host spends, and it spends them on a message. Both read the DIAL,
+	/* The two hues a host spends, and it spends them on a message. Both read the dial,
 	   so a page carries one colour meaning error and one meaning warning rather than a
 	   second pair beside the surfaces'. The dark half is a lift the dials do not carry:
 	   a hue calibrated against white reads as a stain on a dark page. */
@@ -42,7 +53,7 @@
 
 	/* ── Rhythm ──────────────────────────────────────────────────────────────── */
 	/* One base and its multiples, the same four steps the surfaces derive. A host
-	   separating SECTIONS down a page wants steps above these; it derives them from
+	   separating sections down a page wants steps above these; it derives them from
 	   this base rather than minting them, which is what keeps its ramp one ramp. */
 	--qmh-space: var(--qm-space, 0.25rem);
 	--qmh-space-half: calc(var(--qmh-space) / 2);
@@ -58,7 +69,7 @@
 	   so it does not derive from the spacing dial. */
 	--qmh-measure: 34rem;
 
-	/* The floor under a control a THUMB lands on. Hand geometry rather than rhythm, which
+	/* The floor under a control a thumb lands on. Hand geometry rather than rhythm, which
 	   is why it does not derive from the spacing dial either: 44px is where both platform
 	   guidelines and WCAG put a touch target, and a control padded to a pointer's size is
 	   under it whatever rung the padding reads. */
@@ -73,7 +84,7 @@
 	--qmh-font: var(--qm-font, ui-sans-serif, system-ui, sans-serif);
 	--qmh-font-mono: var(--qm-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
 
-	/* The page's own ramp, and it does NOT read `--qm-font-size`: that dial anchors the
+	/* The page's own ramp, and it does not read `--qm-font-size`: that dial anchors the
 	   surfaces' ramp, which is chrome inside a card, and a page's body text is a
 	   different job at a different size. A host that wants them locked sets both. */
 	--qmh-text: 1rem;
@@ -94,7 +105,7 @@
 	--qmh-ease-reverse: cubic-bezier(0.4, 0, 0.6, 1);
 }
 
-/* Collapse the SCALE, not each transition: every animated recipe reads the rung, so one
+/* Collapse the scale, not each transition: every animated recipe reads the rung, so one
    override reaches all of them with no `*` rule touching mounted package elements. */
 @media (prefers-reduced-motion: reduce) {
 	:root {

package/dist/preview/Preview.svelte

@@ -4,7 +4,7 @@
   paint.ts/overlay.ts/bridge.ts/controller.ts own the behavior. Exposes the
   `PreviewController` verbs as instance methods (`bind:this`) for a consumer
   that drives `refresh`/`scrollToField`/`focusPosition`/`setZoom` imperatively
-  (e.g. after `session.apply` elsewhere); pure passthrough, no added logic.
+  (e.g. after `session.apply` elsewhere).
 -->
 <script lang="ts">
 	import { onMount } from 'svelte';
@@ -16,10 +16,10 @@
 	import type { EditorErrorHandler } from '../core/errors.js';
 
 	/**
-	 * REMOUNT CONTRACT. `createPreview` binds once in `onMount`; a later change to any
+	 * Remount contract. `createPreview` binds once in `onMount`; a later change to any
 	 * prop it closed over (`session`, `margin`, `overlays`, `onPick`, `onError`,
-	 * `strings`) is NOT observed, and each reports `rebind-ignored` when swapped. Swap
-	 * the session by REMOUNTING (`{#key session}`, as the playground does); drive
+	 * `strings`) is not observed, and each reports `rebind-ignored` when swapped. Swap
+	 * the session by remounting (`{#key session}`, as the playground does); drive
 	 * in-place edits through the `refresh(change)` method, not a prop change.
 	 *
 	 * `onError` is itself once-bound, so a swapped handler means the report of its own
@@ -97,15 +97,17 @@
 <div bind:this={containerEl} class="qm-preview {className ?? ''}" {style} data-qm-root></div>
 
 <style>
-	/* A DETACHED root: the preview is not a descendant of the editor, so it carries
+	/* A detached root: the preview is not a descendant of the editor, so it carries
 	   `data-qm-root` for the page/overlay rungs paint.ts and overlay.ts read
 	   (core/theme.css).
 
-	   The DESK as well as the paper: a sheet is at `--_qm-surface` (paint.ts), so the
-	   tone behind it is one rung raised and the gutter is the margin the sheet floats
-	   in. Both are the surface's own, so a bare `<div>` is a mounting site. The
+	   The desk as well as the paper: a sheet is at `--_qm-surface` (paint.ts), so the
+	   tone behind it is the sunken rung and the gutter is the margin the sheet floats
+	   in. Paper is the brighter plane at both poles, exactly as a card is over the
+	   editor's own column, so the two panes step the same way. Both are
+	   the surface's own, so a bare `<div>` is a mounting site. The
 	   padding is safe against the paint loop: a slot is a `width: 100%` child and
-	   measures the CONTENT box, and the container's own `clientWidth` is read only as
+	   measures the content box, and the container's own `clientWidth` is read only as
 	   a change detector, which a constant inset does not disturb. */
 	.qm-preview {
 		box-sizing: border-box;
@@ -114,6 +116,6 @@
 		height: 100%;
 		overflow-y: auto;
 		padding: var(--_qm-space-4);
-		background: var(--_qm-surface-raised);
+		background: var(--_qm-surface-sunken);
 	}
 </style>

package/dist/preview/Preview.svelte.d.ts

@@ -3,10 +3,10 @@ import type { LiveSession, ChangeSet } from '@quillmark/wasm';
 import type { DocPath, Landing, Place } from '../core/address.js';
 import type { EditorErrorHandler } from '../core/errors.js';
 /**
- * REMOUNT CONTRACT. `createPreview` binds once in `onMount`; a later change to any
+ * Remount contract. `createPreview` binds once in `onMount`; a later change to any
  * prop it closed over (`session`, `margin`, `overlays`, `onPick`, `onError`,
- * `strings`) is NOT observed, and each reports `rebind-ignored` when swapped. Swap
- * the session by REMOUNTING (`{#key session}`, as the playground does); drive
+ * `strings`) is not observed, and each reports `rebind-ignored` when swapped. Swap
+ * the session by remounting (`{#key session}`, as the playground does); drive
  * in-place edits through the `refresh(change)` method, not a prop change.
  *
  * `onError` is itself once-bound, so a swapped handler means the report of its own

package/dist/preview/bridge.js

@@ -1,10 +1,10 @@
 import { boxesForField, rectToPercent, clickToPdfPt, applyPercentRect } from './geometry.js';
 export function createBridge(session, container, slots, onPick) {
     const unlisten = [];
-    // TWO RUNGS: `positionAt` over span-tracked content, `fieldAt` over every placement
+    // Two rungs: `positionAt` over span-tracked content, `fieldAt` over every placement
     // the compile tracks, a strict superset of it (PREVIEW.md §"Click bridge" carries
     // the measurement). The second fires where a field is placed without its content
-    // being tracked, and the pick carries NO `pos` there: a fabricated `0` would be an
+    // being tracked, and the pick carries no `pos` there: a fabricated `0` would be an
     // invented offset wearing a real one's type. No third rung hit-tests `regions()`,
     // whose rects bound ink the field does not fill.
     if (onPick) {
@@ -53,7 +53,7 @@ export function createBridge(session, container, slots, onPick) {
         else if (target.right > port.right)
             container.scrollLeft += target.right - port.right;
     }
-    // Clear of the fold is the target's OWN height of clearance at each edge, not bare
+    // Clear of the fold is the target's own height of clearance at each edge, not bare
     // intersection: a caret rect flush against one is visible and unusable, and the
     // next line typed lands past it. Derived from the target rather than a margin
     // dial, so it scales with zoom exactly as the caret does.
@@ -81,7 +81,7 @@ export function createBridge(session, container, slots, onPick) {
             const slot = slots[region.page];
             if (!slot)
                 return;
-            // The CONTINUOUS hop: one call per keystroke and per arrow key, so it moves
+            // The continuous hop: one call per keystroke and per arrow key, so it moves
             // the pane only when the caret has left the fold. Centring unconditionally
             // takes the scrollport back from the user on every one of them, including
             // the ones that changed nothing about where the caret already was.

package/dist/preview/controller.js

@@ -83,8 +83,8 @@ export function createPreview(session, opts) {
             showMessage(pageCount === 0 ? t.noPages : t.unsupported, pageCount === 0 ? EMPTY_CLASS : UNSUPPORTED_CLASS);
             return;
         }
-        // Read the count against the current slots BEFORE reconcile moves it, and
-        // clear any prior message BEFORE painting so a paint that throws mid-refresh
+        // Read the count against the current slots before reconcile moves it, and
+        // clear any prior message before painting so a paint that throws mid-refresh
         // leaves its error surfaced rather than have `hideMessage` clobber it.
         const countChanged = pageCount !== paintLoop.slots.length;
         hideMessage();
@@ -104,7 +104,7 @@ export function createPreview(session, opts) {
     }
     render(session.pageCount, []);
     // The last place the editor put the caret, re-located after every recompile.
-    // `session.locate` answers against the LAST COMPILED layout and a consumer
+    // `session.locate` answers against the last compiled layout and a consumer
     // debounces `update`, so a caret typed past that layout's content is off-content
     // for the whole burst: `focusPosition` no-ops and the pane sits still, and a
     // caret event is otherwise the only thing that asks again. The re-locate is the

package/dist/preview/geometry.d.ts

@@ -15,7 +15,7 @@ export interface PdfPoint {
 }
 /**
  * An address's boxes: `fieldBoxes`'s union, else its own `regions()` rects, else the
- * rects of everything UNDER it. The one rule the overlay and the scroll both read, so
+ * rects of everything under it. The one rule the overlay and the scroll both read, so
  * an address `regions()` names never draws nothing (PREVIEW.md §"Three
  * responsibilities").
  *
@@ -43,7 +43,7 @@ export declare function rectToPercent(rect: PdfRect, pageSize: PageSize): Percen
 export declare function applyPercentRect(el: HTMLElement, pct: PercentRect): void;
 /**
  * Inverse: a click at CSS px `(px, py)` within a page element of CSS size
- * `(cssW, cssH)` -> PDF-pt. The EXACT inverse of {@link rectToPercent}: the
+ * `(cssW, cssH)` -> PDF-pt. The exact inverse of {@link rectToPercent}: the
  * fraction `rectToPercent` would place a point's box corner at is the same
  * fraction this reads back from `px/cssW`, `py/cssH`; DPR-independent, since
  * the page element's CSS size (not its canvas backing store) is the only input.

package/dist/preview/geometry.js

@@ -1,6 +1,6 @@
 /**
  * An address's boxes: `fieldBoxes`'s union, else its own `regions()` rects, else the
- * rects of everything UNDER it. The one rule the overlay and the scroll both read, so
+ * rects of everything under it. The one rule the overlay and the scroll both read, so
  * an address `regions()` names never draws nothing (PREVIEW.md §"Three
  * responsibilities").
  *
@@ -50,7 +50,7 @@ export function applyPercentRect(el, pct) {
 }
 /**
  * Inverse: a click at CSS px `(px, py)` within a page element of CSS size
- * `(cssW, cssH)` -> PDF-pt. The EXACT inverse of {@link rectToPercent}: the
+ * `(cssW, cssH)` -> PDF-pt. The exact inverse of {@link rectToPercent}: the
  * fraction `rectToPercent` would place a point's box corner at is the same
  * fraction this reads back from `px/cssW`, `py/cssH`; DPR-independent, since
  * the page element's CSS size (not its canvas backing store) is the only input.

package/dist/preview/index.js

@@ -1,12 +1,12 @@
 // `@quillmark/svelte/preview`: the live-preview surface.
 //
 // `createPreview(session)` (vanilla-TS core) + a thin `<Preview>` Svelte wrapper
-// land here. RESERVED-PACKAGE INVARIANT: this subpath imports no editor-side code
+// land here. Reserved-package invariant: this subpath imports no editor-side code
 // (the codec, the VisualEditor) so a `@quillmark/preview` promotion stays a
 // re-export, not a refactor: it may reach `/core` (the shared WASM boundary) and
 // nothing else. Enforced by `check:deps`, which walks the subpath's import graph.
 // The theme derivation, which the page slots and the overlay read through `var()`.
-// Imported at the BARREL because a subpath is what a consumer gets: this surface
+// Imported at the barrel because a subpath is what a consumer gets: this surface
 // reaches modules inside `core/` and never its entry, so a sheet hanging off that
 // entry arrives only for a consumer importing `/core` for some other reason. The
 // sheet rather than the entry, because the barrel needs the derivation and not
@@ -14,7 +14,7 @@
 import '../core/theme.css';
 export { createPreview } from './controller.js';
 export { default as Preview } from './Preview.svelte';
-// What the preview SAYS when there is nothing to paint. Keyed and partial; the
+// What the preview says when there is nothing to paint. Keyed and partial; the
 // English is exported so a consumer composes against it rather than restating it.
 // The merge is the surface's own: a consumer hands `strings` to a prop, never
 // merges one.

package/dist/preview/overlay.d.ts

@@ -3,7 +3,7 @@ import type { PageSlot } from './paint.js';
 export interface OverlayController {
     /** Re-read geometry and rebuild every box; call after a layout-affecting refresh. */
     refresh(): void;
-    /** Bloom the boxes at `field` AND under it: transient, and a no-op when `field`
+    /** Bloom the boxes at `field` and under it: transient, and a no-op when `field`
      *  is already the marked one. */
     flashField(field: string): void;
     destroy(): void;

package/dist/preview/overlay.js

@@ -9,7 +9,7 @@ export function createOverlay(session, slots) {
         slot.el.appendChild(layer);
         return layer;
     });
-    // The marked address, and with it the bloom's start. ONE variable does both jobs:
+    // The marked address, and with it the bloom's start. One variable does both jobs:
     // the change guard has to outlive the decay (a caret move after the wash ended
     // must not re-mark the same field), and `bloom` refuses an `elapsed` past the
     // decay, so a spent flash is inert on every later rebuild and never needs
@@ -20,7 +20,7 @@ export function createOverlay(session, slots) {
     let flash;
     /** field → its boxes, rebuilt with them. The bloom's only lookup. */
     let byField = new Map();
-    // The boxes a flash covers: the address's own, plus every one UNDER it, since the
+    // The boxes a flash covers: the address's own, plus every one under it, since the
     // boxes are keyed as `regions()` names them (`main.references.0`) and an
     // editor-side signal names the declared field (`main.references`). Resolved per
     // apply rather than at `flashField`, so a rebuild picks up boxes the recompile
@@ -33,7 +33,7 @@ export function createOverlay(session, slots) {
         }
         return els;
     }
-    // Start or RESUME the bloom on whatever boxes exist for it now: one path, because
+    // Start or resume the bloom on whatever boxes exist for it now: one path, because
     // starting is resuming at ~0. A field surfaces several boxes and they share
     // `startedAt`, so they bloom in step rather than shimmering unevenly.
     function applyFlash() {

package/dist/preview/paint.js

@@ -33,14 +33,13 @@ onPaintError) {
     }, { root: container, threshold: 0 });
     function makeSlot(page) {
         const size = session.pageSize(page);
-        // The sheet's own edge, and the only thing separating it from the desk: the
-        // page is at `--_qm-surface`, and the tone behind it is the host's, which
-        // THEMING permits to be plain `--qm-bg` (the same value). A hairline holds at
-        // both poles where a shadow's offset does not, and the
-        // boundary of the paper is not a mark on it, so the overlay's no-ink-at-rest
-        // rule is untouched (PREVIEW §Overlay). `border-box`, so the stroke lands
-        // inside the width the container gives and `clientWidth` below still measures
-        // the paper.
+        // The sheet is a plane and the desk is the one under it: paper sits at
+        // `--_qm-surface` and the container paints `--_qm-surface-sunken`, so the
+        // edge is where two tones meet and no stroke is drawn around it
+        // (ARCHITECTURE §Styling). It leaves the overlay's no-ink-at-rest rule
+        // untouched, since a boundary that is not painted is not a mark on the page
+        // (PREVIEW §Overlay). `border-box` costs nothing here and keeps a slot a
+        // consumer insets from measuring wider than its paper.
         const el = document.createElement('div');
         el.className = 'qm-page';
         // The page's index, in the DOM. `pageByEl` is this module's and a consumer
@@ -52,8 +51,7 @@ onPaintError) {
             boxSizing: 'border-box',
             width: '100%',
             aspectRatio: `${size.widthPt} / ${size.heightPt}`,
-            background: 'var(--_qm-surface)',
-            border: 'var(--_qm-border-width) solid var(--_qm-border)'
+            background: 'var(--_qm-surface)'
         });
         if (page > 0)
             el.style.marginTop = PAGE_GAP;
@@ -63,7 +61,7 @@ onPaintError) {
         return { page, size, el };
     }
     // Rasterize `slot` into its canvas (creating the canvas if this is its first
-    // paint since mounting). `layoutScale` is derived from the slot's OWN current
+    // paint since mounting). `layoutScale` is derived from the slot's own current
     // CSS width, so layout width tracks the container per the zoom settled
     // decision; `canvas.style.*` is then set from the authoritative PaintResult,
     // never guessed.
@@ -74,7 +72,7 @@ onPaintError) {
             canvas.className = 'qm-page-canvas';
             Object.assign(canvas.style, { position: 'absolute', inset: '0', display: 'block' });
         }
-        // Contextless canvas: bail BEFORE registering, so `updateBand` still sees
+        // Contextless canvas: bail before registering, so `updateBand` still sees
         // the page as unmounted and retries instead of keeping a blank page.
         const ctx = canvas.getContext('2d');
         if (!ctx)
@@ -108,7 +106,7 @@ onPaintError) {
         canvases.delete(page);
     }
     // Mount pages newly inside [min(visible)-margin, max(visible)+margin], unmount
-    // pages that fell outside it. Only touches pages CHANGING band membership;
+    // pages that fell outside it. Only touches pages changing band membership;
     // an already-mounted page in the band is left alone (paint contract: an idle
     // canvas keeps its pixels for free; repainting it here would be pure waste).
     function updateBand() {
@@ -158,13 +156,13 @@ onPaintError) {
         }
     }
     // Slots are built on the first `refresh` (the controller calls it immediately),
-    // NOT here: reconcile → `session.pageSize` must run AFTER the controller's
+    // not here: reconcile → `session.pageSize` must run after the controller's
     // `supportsCanvas`/`pageCount` gate, since a `supportsCanvas: false` compile with
     // pages would throw on `pageSize` (runtime.d.ts: it succeeds iff `supportsCanvas`)
     // before the controller can surface its "unsupported" message.
     // ── Keep mounted rasters in step with the display ───────────────────────────
-    // Every paint freezes `canvas.style.width/height` to the box width AT THAT
-    // PAINT (paintSlot). A page that stays mounted while the container's CSS width
+    // Every paint freezes `canvas.style.width/height` to the box width at that
+    // paint (paintSlot). A page that stays mounted while the container's CSS width
     // or `devicePixelRatio` shifts would otherwise keep a stale raster the %-space
     // overlay/click math silently drifts off of: the box tracks the container, the
     // ink does not. Two observers close the gap by repainting mounted pages from
@@ -212,7 +210,7 @@ onPaintError) {
     resizeObserver?.observe(container);
     // `devicePixelRatio` changes (window dragged to a different-DPI monitor, browser
     // zoom) leave CSS-px width untouched, so the ResizeObserver never sees them;
-    // watch DPR directly. A `(resolution: …dppx)` query pins the CURRENT ratio and
+    // watch DPR directly. A `(resolution: …dppx)` query pins the current ratio and
     // is therefore one-shot: re-arm it against the new ratio on each change. Guarded
     // for environments (jsdom) without `matchMedia`.
     let dprQuery;