@quario/landing 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,15 +1,73 @@
-# Changelog
+# @quario/landing
 
-All notable changes to @quario/landing are documented in this file.
+## 0.2.1
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+### Patch Changes
 
-## [Unreleased]
+- Updated dependencies
+  - @quario/layout@0.6.0
 
-## [0.1.0] - 2026-09-07
+## 0.2.0
 
-### Added
+### Minor Changes
+
+- **The sheet carries the extent; only the reach carries elements.** `sheet()`
+  gave every page of a display list a sized canvas, so a scale change
+  invalidated one box per page and the browser laid all of them out again — a
+  cost linear in the length of the document, around 10 microseconds a page, so
+  a five-thousand-page report paid roughly 50 ms on every zoom step. The sheet
+  element is now given its own height and width inline, from the paper the
+  list carries, and paints the page silhouettes as a repeating gradient at the
+  page pitch; the pages in the reach are positioned absolutely at the offset
+  `topOf()` reports, and a page leaving the reach is removed rather than
+  emptied. Sizing is now O(reach).
+
+  The extent a reader scrolls through is unchanged, and is still whole and
+  synchronous — more so, since it no longer waits on the browser laying out one
+  box per page to discover it.
+
+- **`pageAt(i)` answers `null` for a page outside the reach**, which has no
+  element and is not given one by being asked for. `count()` still answers the
+  document's length rather than the sheet's child count.
+- **`sheet()` places its own pages.** It writes `position: relative` on the
+  sheet element and `position: absolute` on every page canvas, alongside the
+  offsets and sizes it was already writing. A caller's own stylesheet no longer
+  stacks the pages, and must not: everything that places a page is decided in
+  one place now, and what a surface's CSS keeps is the look of one.
+- **`sheet().at(clientX, clientY)`** — which page a client point is over, and
+  where it lands in that page's own points, or `null` for a point on no page:
+  the gap between two pages, above the first, below the last, or left or right
+  of the sheet. The inverse of `topOf()`, and answered by the same pitch the
+  sheet places its pages at — one division, and one read of the sheet's own
+  box rather than one per page. It answers for any page of the
+  list, with an element or without one — the reach decides what is painted,
+  not what is there — so a surface asking it during a fast scroll gets the
+  page the reader is looking at rather than nothing until the reach catches
+  up.
+
+### Patch Changes
+
+- **Finding the reach no longer walks the document.** Every page of a report is
+  drawn on the same paper, so the pages down a sheet sit one pitch apart and the
+  two ends of the reach are a division rather than a pass over every page. A
+  scroll frame spent 24 microseconds choosing the reach at five thousand pages
+  and now spends one, whatever the document's length. `topOf(i)` answers where
+  page `i` sits, computed from that pitch.
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - @quario/layout@0.5.0
+
+## 0.1.0
+
+### Minor Changes
 
 - **First release.** `options()` is the option check two surface elements run
   per update cycle — first-failure-wins, re-validate-everything, and a commit
@@ -19,12 +77,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   counter that asks for a fresh one. `failures()` is which failure a panel is
   showing and whether the reader put it away, with the announce policy taken
   as an argument rather than settled.
-
 - **`failures().reopen()`** — the dismissal lapses without announcing
   anything. A dismissal is about a subject, so when that changes underneath
   it, a standing failure is worth drawing again. Distinct from `clear()`,
   which is a render landing and takes the failure with it.
-
 - **`sheet()`** — the paged sheet both surfaces paint on: one canvas per page
   of a display list, and the reach among them carrying pixels. Every page
   keeps its CSS size, so the extent a reader scrolls through is whole whatever

package/README.md

@@ -6,7 +6,7 @@ render boundary across their lifetime, and both draw a panel when something fail
 that which are easy to get subtly wrong — and invisible when they are — live here once.
 
 You almost certainly do not install this package. The two surfaces depend on it and run it for
-you; it holds no report vocabulary and renders nothing.
+you. It holds no report vocabulary and renders nothing.
 
 ## Install
 
@@ -15,8 +15,8 @@ npm install @quario/landing
 ```
 
 One runtime dependency, `@quario/layout`, which the paged sheet paints through. It implements
-Lit's `ReactiveController` protocol, which is structural, so nothing is imported from `lit` at run
-time and this adds none of it to your tree.
+Lit's `ReactiveController` protocol, which is structural, so this package imports nothing from
+`lit` at run time and adds none of it to your tree.
 
 ESM-only, Node 22+, and browser-ready through a standards-based bundler. CSP-safe: no
 string-to-code paths anywhere.
@@ -24,25 +24,39 @@ string-to-code paths anywhere.
 ## What is here
 
 **`options()`** — the option check across one update cycle. A host writes several properties at
-once and gets one render, so the checks have to agree that one bad property does not block a good
-write to another, that a property still broken keeps the element failing rather than being cleared
-by an unrelated write, and that writing one property does not clobber what another committed. The
-checks themselves are each surface's own; only that agreement is here.
-
-**`Landing`** — the render boundary: whether a render has ever painted the sheet, whether work was
-abandoned mid-flight, and the counter that asks for a fresh one. A disconnected element abandons
-work rather than hiding it, and comes back owing a render.
-
-**`sheet()`** — the paged sheet both surfaces paint on: one canvas per page of a display list,
-and the reach among them carrying pixels. Every page keeps its CSS size, so the extent a reader
-scrolls through is whole whatever is painted; what comes and goes is the backing store. It takes a
-`scale()` thunk and the two elements, so scale policy and styling stay with each surface.
-
-**`failures()`** — which failure a panel is showing and whether the reader put it away. Whether a
-repeat announces again is a policy the caller passes in, never a rule settled here: it is
+once and gets one render, so the checks have to agree that:
+
+- one bad property does not block a good write to another,
+- a property still broken keeps the element failing, rather than an unrelated write clearing it,
+- writing one property does not clobber what another committed.
+
+The checks themselves are each surface's own. Only that agreement is here.
+
+**`Landing`** — the render boundary: whether a render has ever painted the sheet, whether the
+element abandoned work mid-flight, and the counter that asks for a fresh one. A disconnected
+element abandons work rather than hiding it, and comes back owing a render.
+
+**`sheet()`** — the paged sheet both surfaces paint on: the extent of a display list, and the
+reach within it carrying elements and pixels. The sheet element takes its own height and width
+from the list's paper and paints the page silhouettes itself, so the extent a reader scrolls
+through is whole whatever is standing. Only the pages in the reach have a canvas, positioned
+absolutely at the offset `topOf()` reports. A list has one paper, so the pages are a pitch apart:
+a position is a multiple of it and the reach's two ends are a division by it. `sheet()` takes a
+`scale()` thunk and the two elements, so scale policy stays with each surface, and so does the
+look of a page — the paper, the shadow, the margins. Everything that places a page is `sheet()`'s
+and needs no stylesheet from the caller.
+
+**`failures()`** — which failure a panel carries and whether the reader dismissed it. Whether
+a repeat announces again is a policy the caller passes in, never a rule settled here. It is
 downstream of what re-runs the render, which is the one thing the two surfaces do not share.
 
 ## What is not here
 
 Each surface's own property checks, its panel markup, and its public API. The two elements differ
-in their vocabulary and in their policy; only the machinery underneath is one thing.
+in their vocabulary and in their policy. Only the machinery underneath is one thing.
+
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare.

package/lib/index.d.ts

@@ -82,14 +82,19 @@ export class Landing implements ReactiveController {
 
 /** The gutter around the sheet, and the gap between pages, in CSS pixels at
  * any scale: both are chrome, so neither scales with the page. A surface reads
- * them rather than restating them — the reach walk is measured in them, and a
+ * them rather than restating them — the reach is measured in them, and a
  * sheet whose CSS disagreed would paint the wrong pages. */
 export const GUTTER: number;
 export const GAP: number;
 
 /**
- * A paged sheet on `scroll`, painting into `sheetEl`: one canvas per page of a
- * display list, and the reach among them carrying pixels.
+ * A paged sheet on `scroll`, painting into `sheetEl`: the extent of a display
+ * list, and the reach within it carrying elements and pixels.
+ *
+ * `sheetEl` is given the extent inline — `position: relative`, its height, its
+ * width and the page silhouettes — and each canvas of the reach its own
+ * `position: absolute` and offset within it, so a caller owes it no stylesheet
+ * (ADR 0065). What a surface's CSS keeps is the look of a page.
  *
  * `scale` is asked afresh every time — CSS pixels per point — so scale policy
  * stays with the surface, and the elements are the surface's too, because
@@ -101,19 +106,31 @@ export function sheet(
   scale: () => number,
   pageClass?: string,
 ): {
-  /** One canvas per page, sized, with the reach painted. Never rejects: a
-   * page the browser will not draw is blank, not a failure. */
+  /** The extent whole at once, with the reach's pages painted. Never rejects:
+   * a page the browser will not draw is blank, not a failure. */
   swap(list: unknown, fonts: unknown): Promise<void>;
-  /** Give every page its CSS size at the current scale. */
+  /** Give the sheet its extent and the reach its sizes at the current scale. */
   sizeAll(): void;
   /** Repaint the reach, releasing what it has left behind. */
   repaint(): Promise<void>;
   /** One reach pass a frame, however many scrolls or resizes ask. */
   follow(): void;
-  /** Where each page starts down the sheet, in CSS pixels. */
-  tops(): number[];
+  /** Where page `i` starts down the sheet, in CSS pixels — the very offset the
+   * sheet places that page at, so an overlay can agree with it. `0` before a
+   * list arrives. */
+  topOf(i: number): number;
   /** The page width the list carries, or `null` before one arrives. */
   width(): number | null;
-  pageAt(i: number): HTMLCanvasElement;
+  /** The canvas standing for page `i`, or `null` for a page outside the reach
+   * — which has no element, and is not minted one by being asked for. */
+  pageAt(i: number): HTMLCanvasElement | null;
+  /** Which page a client point is over, and where it lands in that page's own
+   * points — the inverse of `topOf()`. Answers for any page of the list, with
+   * an element or without one, since the list carries a page's geometry
+   * whether or not the reach has minted a canvas for it. `null` for a point on
+   * no page: the gap between two, above the first, below the last, or left or
+   * right of the sheet. */
+  at(clientX: number, clientY: number): { index: number; x: number; y: number } | null;
+  /** The document's length, which is not the sheet's child count. */
   count(): number;
 };

package/lib/landing.js

@@ -63,7 +63,7 @@ export class Landing {
    *
    * Called by Lit through the controller protocol, never by name here, which
    * is why the dead-code scan cannot see the caller. */
-  // fallow-ignore-next-line unused-class-member
+  // fallow-ignore-next-line unused-class-member -- Lit calls it through the controller protocol, so no caller is in the graph
   hostConnected() {
     this.wake();
   }
@@ -72,7 +72,7 @@ export class Landing {
    * only the work in flight stops. Each surface's own teardown — an observer,
    * a key binding — stays in its `disconnectedCallback`. Called by Lit, as
    * `hostConnected` is. */
-  // fallow-ignore-next-line unused-class-member
+  // fallow-ignore-next-line unused-class-member -- Lit calls it through the controller protocol, so no caller is in the graph
   hostDisconnected() {
     this.#task.abort();
   }

package/lib/sheet.js

@@ -1,12 +1,24 @@
 /**
- * The paged sheet both surfaces paint on: one canvas per page of a display
- * list, and the [reach](../../../CONTEXT.md#reach) among them carrying pixels.
+ * The paged sheet both surfaces paint on: the extent of a display list, and
+ * the [reach](../../../CONTEXT.md#reach) within it carrying elements and
+ * pixels.
  *
- * Every page keeps its CSS size, so the extent a reader scrolls through is
- * whole and synchronous whatever is painted; what comes and goes is the
- * backing store, released by sizing a canvas to 0 x 0. ADR 0043 says what that
- * is worth: painting the whole sheet asked a thousand-page report for
- * gigabytes, and past what the browser would grant the pages came up blank.
+ * The sheet carries its own extent — its height and width are written here
+ * from the list's [paper](../../../CONTEXT.md#paper), and a page canvas is
+ * positioned absolutely at the offset `topOf()` reports. Only the pages in the
+ * reach have an element at all; a page leaving it is removed, which takes its
+ * backing store with it. So the extent a reader scrolls through is whole and
+ * synchronous whatever is painted, without the browser having to lay out one
+ * box per page to discover it (ADR 0065). ADR 0043 says what the reach is
+ * worth: painting the whole sheet asked a thousand-page report for gigabytes,
+ * and past what the browser would grant the pages came up blank.
+ *
+ * **The page silhouettes are a paint, not elements.** A page outside the reach
+ * has nothing to carry white, so the sheet's own background is a repeating
+ * gradient at the page pitch — exact rather than approximate, because a list
+ * has one paper and the pitch is the same one the pages are placed at. One
+ * style write per scale change, and it rasters even with the main thread
+ * wedged.
  *
  * **A page the browser will not paint is blank, not a failure.** `start`
  * swallows and nothing here rejects: the report laid out and the list reached
@@ -16,7 +28,8 @@
  * it draws, so a canvas whose paint is still in flight is *retired* rather
  * than painted over: it comes off the sheet, its pixels go back, and a fresh
  * one stands in its place, so the superseded paint draws into an element
- * nobody is looking at (ADR 0046).
+ * nobody is looking at (ADR 0046). A page that leaves the reach mid-paint is
+ * dropped for the same reason, with nothing standing in.
  *
  * What this does **not** own is scale policy. It takes a `scale()` thunk and
  * asks it afresh every time: the viewer answers a zoom percentage, the editor
@@ -28,16 +41,27 @@ import { paint } from "@quario/layout";
 
 /** The gutter around the sheet, and the gap between pages, in CSS pixels at
  * any scale: both are chrome, so neither scales with the page. Here rather
- * than in each surface because the reach walk reads them, and a sheet whose
- * geometry disagreed with its own reach would paint the wrong pages. */
+ * than in each surface because the reach is measured in them, and a sheet
+ * whose geometry disagreed with its own reach would paint the wrong pages. */
 export const GUTTER = 28;
 export const GAP = 16;
 
+/** The paper a page is drawn on, and what the sheet paints where a page has
+ * no element. Both surfaces' page rules carry the same white; this is the
+ * copy that shows through a canvas with no backing store, and the one a page
+ * outside the reach is made of. */
+const PAPER = "#fff";
+
 /**
  * A paged sheet on `scroll`, painting into `sheetEl`.
  *
  * @param {HTMLElement} scroll The scroll container the reader looks through.
- * @param {HTMLElement} sheetEl What the page canvases are children of.
+ * @param {HTMLElement} sheetEl What the page canvases are children of. Made a
+ *   containing block here, as its pages are made absolute here: a page's
+ *   `top` is meaningless without those two, so they are one decision with it
+ *   rather than an obligation on a caller who would have to be told, and
+ *   pinned, and could still forget. What a surface's stylesheet keeps is the
+ *   look — the paper, the shadow, the margins.
  * @param {() => number} scale CSS pixels per point, asked afresh each time.
  * @param {string} [pageClass] What to name a page element. Each surface's
  *   `q*-` names are its own documented CSS surface, so the class is the
@@ -48,12 +72,16 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
   let list = null;
   /** @type {any} */
   let fonts;
-  /** The page canvases, in order. Its own list rather than `sheetEl.children`:
-   * a sheet may hold more than pages — the editor hangs its box overlay in
-   * the same element, positioned in the sheet's own pixels — and indexing the
-   * children would then read an overlay as a page and a swap would wipe it. */
-  /** @type {HTMLCanvasElement[]} */
-  let pages = [];
+  /**
+   * The page canvases the reach has, by their index in the list. Sparse, and
+   * its own map rather than `sheetEl.children`: a sheet may hold more than
+   * pages — the editor hangs its box overlay in the same element — and
+   * indexing the children would then read an overlay as a page, and could not
+   * say which page a canvas stood for anyway.
+   *
+   * @type {Map<number, HTMLCanvasElement>}
+   */
+  let pages = new Map();
 
   /**
    * What each backed page is carrying: the scale it was painted at, so a page
@@ -64,55 +92,143 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    * and the pages it replaced take their entries with them — which is why the
    * map is weak: nothing has to remember to forget them.
    *
-   * @type {WeakMap<HTMLCanvasElement, { scale: number, painted: Promise<void> }>}
+   * `done` is the third: whether that paint has finished. A promise's settled
+   * state is not synchronously observable and it is the one question the
+   * retirement rule turns on — a canvas whose entry is `done` has nothing left
+   * that could draw into it and can be re-sized in place; one still painting
+   * must be retired instead. It rides the entry rather than a set beside it,
+   * so it is per *paint* for free: `start` mints a fresh entry, and a page
+   * settled at one scale cannot count as settled the moment it begins painting
+   * at the next.
+   *
+   * @typedef {{ scale: number, painted: Promise<void>, done: boolean }} Backing
+   * @type {WeakMap<HTMLCanvasElement, Backing>}
    */
   let backed = new WeakMap();
 
   /**
-   * The canvases whose paint has finished. A promise's settled state is not
-   * synchronously observable and this is the one question the rule below
-   * turns on: a canvas in here has nothing left that could draw into it, so
-   * it can be emptied or re-sized in place; one that is backed but absent
-   * here is still being painted, and must be retired instead. Weak on the
-   * same key as `backed`, so a retired canvas takes its membership with it.
-   *
-   * Membership is per paint, not per canvas — `start` takes a canvas out
-   * before painting it again, or a page settled at one scale would count as
-   * settled the moment it began painting at the next.
-   *
-   * @type {WeakSet<HTMLCanvasElement>}
+   * The list stacked at one scale, in CSS pixels: the
+   * [paper](../../../CONTEXT.md#paper) every page is drawn on, the pitch from
+   * one page's top to the next's, and how tall the sheet has to be to hold them
+   * all. There is no width beside those: the sheet is one paper wide, which is
+   * the claim `extend` writes rather than a second number to keep in step.
+   *
+   * The **pitch** is the paper's height plus the gap — the step down the sheet,
+   * and the period of the silhouette gradient.
+   *
+   * @typedef {{ px: number, paper: { width: number, height: number },
+   *   pitch: number, height: number }} Stacked
    */
-  let settled = new WeakSet();
 
   /**
-   * The canvas standing for page `i` right now. Read through here and never
-   * held: a retired page is a different element, so a canvas taken before an
-   * await may be off the sheet by the time it is used.
+   * The stacking at the applied scale, computed once and held until the scale
+   * moves or a list arrives. **The one reading of the list's paper there is** —
+   * the reach divides by it, the pages are positioned from it, `topOf()`
+   * answers it and the extent is written from it, so none of those can drift
+   * from the others.
    *
-   * @type {(i: number) => HTMLCanvasElement}
+   * @type {Stacked | null}
+   */
+  let stacking = null;
+
+  /** The stacking the sheet element's style already says, so an `extend` that
+   * would write what is there writes nothing.
+   * @type {Stacked | null} */
+  let extended = null;
+
+  /** The stacking itself, at `px` CSS pixels per point: every page a gap below
+   * the one before it, from the sheet's own top. Read off the list's own paper,
+   * which is one width and one height for every page of it (ADR 0069), so a
+   * page's offset is a multiple of the pitch rather than a sum walked up from
+   * the top — and the extent, the silhouettes and the placement all come off
+   * the same two numbers instead of agreeing by hand.
+   *
+   * @type {(px: number) => Stacked}
+   */
+  let stack = (px) => {
+    let paper = { width: list.width * px, height: list.height * px };
+    let pitch = paper.height + GAP;
+    // The trailing gap belongs to no page: the extent ends at the last page's
+    // own bottom, which is where the silhouette gradient's last band ends too.
+    return { px, paper, pitch, height: Math.max(0, list.pages.length * pitch - GAP) };
+  };
+
+  /** @type {() => Stacked} */
+  let measure = () => {
+    let px = scale();
+    return stacking?.px === px ? stacking : (stacking = stack(px));
+  };
+
+  /**
+   * The page silhouettes, as one background over the sheet's own height. This
+   * paints what a page element used to, for the pages that no longer have one
+   * (ADR 0065).
+   *
+   * A band of paper and a gap of nothing, repeated at the pitch — which is the
+   * stacking's own pitch, not a second answer to it. This used to presume the
+   * pitch it painted, reading the first page's height as every page's because
+   * a gradient can only have one; the list states its paper now, so the
+   * gradient asks for what the pages are placed by (ADR 0069). No guard for a
+   * pageless list either: the band flow opens the body's first page whether or
+   * not anything renders on it, and a gradient over a sheet no pages tall
+   * paints nothing regardless.
+   *
+   * @type {(at: Stacked) => string}
+   */
+  let silhouettes = (at) =>
+    `repeating-linear-gradient(${PAPER} 0 ${at.paper.height}px, ` +
+    `transparent ${at.paper.height}px ${at.pitch}px)`;
+
+  /**
+   * Give the sheet the extent of the whole list, and the silhouettes of the
+   * pages it is not showing. Three style writes, whatever the page count: this
+   * is what makes the extent whole without an element per page, and callers
+   * run it before writing scroll offsets back, because the extent those are
+   * clamped against is this one.
    */
-  let pageAt = (i) => pages[i];
+  let extend = () => {
+    let at = measure();
+    // Reference, not value: `measure` hands back the very same object until
+    // the scale moves, so an unchanged stacking costs one compare rather than
+    // three style writes — and a background write invalidates the paint of an
+    // extent that can be hundreds of thousands of pixels tall. The editor's
+    // scale never moves, so every swap after the first takes this branch.
+    if (at === extended) return;
+    extended = at;
+    sheetEl.style.position = "relative";
+    // One paper wide, and as tall as the pages stacked: the sheet has no width
+    // of its own, so this is where that is said rather than a field carrying it.
+    sheetEl.style.width = at.paper.width + "px";
+    sheetEl.style.height = at.height + "px";
+    sheetEl.style.background = silhouettes(at);
+  };
 
   /**
-   * Give a page's canvas its size on screen. The one answer to how big page
-   * `i` is at the applied scale: `pageOf` builds a canvas with it and
-   * `sizeAll` writes it over the sheet after a scale change, so a page
-   * retired between the two cannot arrive sizeless and move the extent the
-   * reader is scrolling through.
+   * Give a page's canvas its size and its place on the sheet. The one answer
+   * to where page `i` sits at the applied scale: `pageOf` builds a canvas with
+   * it and `sizeAll` writes it over the reach after a scale change, so a page
+   * retired between the two cannot arrive sizeless or off its own offset.
    *
-   * @type {(canvas: HTMLElement, i: number, px?: number) => void}
+   * @type {(canvas: HTMLElement, i: number) => void}
    */
-  let sizePage = (canvas, i, px = scale()) => {
-    let each = list.pages[i];
-    canvas.style.width = each.width * px + "px";
-    canvas.style.height = each.height * px + "px";
+  let place = (canvas, i) => {
+    let at = measure();
+    canvas.style.position = "absolute";
+    // `left` written rather than left to the static position, which would be
+    // the sheet's content edge and so would move with a padding neither
+    // surface sets today. `at()` below measures from the padding edge, so the
+    // two agree by construction instead of by that absence.
+    canvas.style.left = "0px";
+    canvas.style.top = i * at.pitch + "px";
+    canvas.style.width = at.paper.width + "px";
+    canvas.style.height = at.paper.height + "px";
   };
 
   /**
-   * One page of the list as a canvas: sized on screen, carrying no pixels
-   * yet, and named for a screen reader. Every canvas on the sheet is built
-   * here — a swap's and a retirement's alike — so a replacement is the same
-   * element in every respect but identity.
+   * One page of the list as a canvas: sized, placed, carrying no pixels yet,
+   * and named for a screen reader. Every canvas on the sheet is built here —
+   * a page entering the reach and a retirement alike — so a replacement is the
+   * same element in every respect but identity.
    *
    * @type {(i: number) => HTMLCanvasElement}
    */
@@ -125,17 +241,94 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
     canvas.height = 0;
     canvas.setAttribute("role", "img");
     canvas.setAttribute("aria-label", "Page " + (i + 1) + " of " + list.pages.length);
-    sizePage(canvas, i);
+    place(canvas, i);
     return canvas;
   };
 
+  /**
+   * The canvas standing for page `i` right now, or `null` for a page outside
+   * the reach — which has no element, and is not minted one by being asked
+   * for: that would make a read a mutation, and would have `keep()`
+   * materialise every page it releases. Read through here and never held: a
+   * retired or released page is gone, so a canvas taken before an await may be
+   * off the sheet by the time it is used.
+   *
+   * @type {(i: number) => HTMLCanvasElement | null}
+   */
+  let pageAt = (i) => pages.get(i) ?? null;
+
+  /**
+   * Which page a client point is over, and where it lands in that page's own
+   * points — or `null` for a point on no page at all.
+   *
+   * **The inverse of `topOf()`, and here because `topOf()` is here.** The
+   * stacking is one arithmetic read two ways: `topOf()` answers where a page
+   * starts, this answers which page a distance is inside. A caller computing
+   * it from `topOf()` would be a second place that knows how pages stack,
+   * which is the drift ADR 0065 bought out by making the offset a fact rather
+   * than a presumption.
+   *
+   * **One division, and one layout read.** The pages step by a fixed pitch, so
+   * the page a distance falls in is that distance over the pitch — the same
+   * arithmetic `inReach()` bounds the reach with, in the other direction, and
+   * flat in the length of the document. The sheet's own box is read afresh
+   * each call, because a point is a client coordinate and nothing else can
+   * turn it into a sheet one. The editor's hit test walked every page to find
+   * the handful with an element and read a rect off the one it landed in; this
+   * replaces that walk, not that read.
+   *
+   * **It answers for a page that has no element.** The reach decides what is
+   * painted, not what is there: a point over a page the reach has not minted
+   * still lands on that page, because the stacking is the list's geometry and
+   * not the elements'. So a fast scroll or a resize cannot make a point over a
+   * page the reader is looking at answer "nowhere" for the frame before the
+   * reach catches up.
+   *
+   * Null in four places, all of them genuinely no page: the gap between two
+   * pages, above the first, below the last, and left or right of the sheet.
+   *
+   * @type {(clientX: number, clientY: number) => { index: number, x: number, y: number } | null}
+   */
+  let at = (clientX, clientY) => {
+    if (!list?.pages.length) return null;
+    let stacked = measure();
+    let box = sheetEl.getBoundingClientRect();
+    // The padding box, not the border box the rect describes: a page is placed
+    // `left: 0` inside this element and resolves against its padding edge, as
+    // does an overlay a surface hangs there with `inset: 0`. `clientLeft` and
+    // `clientTop` are that difference — the border — and are read off the very
+    // element whose rect was just read, so they cost no second flush.
+    let x = clientX - box.left - sheetEl.clientLeft;
+    let y = clientY - box.top - sheetEl.clientTop;
+    // The page whose pitch band `y` falls in. Negative above the first page,
+    // past the end below the last: each runs off its own end of the list.
+    let i = Math.floor(y / stacked.pitch);
+    return i < 0 || i >= list.pages.length ? null : onPage(i, x, y, stacked);
+  };
+
+  /** Page `i`'s own answer for a sheet-space point already known to be in its
+   * pitch band: the point in that page's points, or `null` past its paper —
+   * the gap under it, or the sheet's end — or beside it. The paper's own edges
+   * count as inside, which is what the rect test this replaced said with `<=`.
+   *
+   * Answers the point rather than a yes, so one page's origin is read in one
+   * place instead of being tested here and subtracted in the caller.
+   *
+   * @type {(i: number, x: number, y: number, stacked: Stacked) => { index: number, x: number, y: number } | null} */
+  let onPage = (i, x, y, stacked) => {
+    let top = i * stacked.pitch;
+    if (y > top + stacked.paper.height) return null;
+    if (x < 0 || x > stacked.paper.width) return null;
+    return { index: i, x: x / stacked.px, y: (y - top) / stacked.px };
+  };
+
   /**
    * Take page `i`'s canvas off the sheet and stand a fresh one in its place,
    * answering with the replacement. A paint still in flight holds the old
    * canvas's context and draws into something nobody is looking at, which is
    * how a superseded paint is stopped here — by construction, rather than by
    * a check the painter would have to make above its own draw (ADR 0046).
-   * The retired canvas takes its entries in `backed` and `settled` with it.
+   * The retired canvas takes its entry in `backed` with it, being weak.
    *
    * Its pixels go back at once, by the same 0 × 0 idiom `release` uses: the
    * store is what ADR 0043 rations, and leaving it to be collected whenever
@@ -147,33 +340,42 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    * @type {(i: number) => HTMLCanvasElement}
    */
   let retire = (i) => {
-    let old = pageAt(i);
+    let old = /** @type {HTMLCanvasElement} */ (pageAt(i));
     let fresh = pageOf(i);
     old.replaceWith(fresh);
-    pages[i] = fresh;
+    pages.set(i, fresh);
     old.width = 0;
     old.height = 0;
     return fresh;
   };
 
   /**
-   * Give page `i`'s pixels back. A page whose paint has settled is emptied in
-   * place: sizing the canvas to 0 × 0 is the one idiom that frees the store
-   * synchronously in every engine the viewer runs in, and the CSS size is
-   * untouched, so the page keeps its place in the extent and shows the
-   * sheet's white. A page still painting is retired instead — emptying it
-   * would leave that paint pointed at a canvas the next pass over the reach
-   * re-sizes and re-paints.
+   * Let page `i` go. It leaves the sheet entirely — the element and its
+   * backing store together, since a detached canvas takes its store with it —
+   * and the extent does not move, because the extent is the sheet's own.
+   *
+   * Removal is what makes this safe whether the page's paint has settled or
+   * not: a paint still in flight is left drawing into a detached element, the
+   * same outcome retirement arranges, so there is nothing here to stand in
+   * its place for. Sized to 0 × 0 rather than left to be collected when that
+   * paint lets go of the context, which is the timing ADR 0043 refuses.
    *
    * @type {(i: number) => void}
    */
   let release = (i) => {
     let canvas = pageAt(i);
-    if (!backed.has(canvas)) return;
-    if (!settled.has(canvas)) return void retire(i);
-    backed.delete(canvas);
-    canvas.width = 0;
-    canvas.height = 0;
+    if (!canvas) return;
+    pages.delete(i);
+    canvas.remove();
+    // Only where there is a store to give back: assigning a canvas's width
+    // resets its bitmap whatever the value, so an untouched page would pay for
+    // a reset it has nothing to reset. `backed` is weak and the canvas is now
+    // unreachable, so its entry needs no forgetting — the same reason `retire`
+    // does not forget one either.
+    if (canvas.width) {
+      canvas.width = 0;
+      canvas.height = 0;
+    }
   };
 
   /** Device pixels per point at the applied scale: what a page is
@@ -187,7 +389,7 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    * at it, so no caller can reach a live canvas with a second paint by
    * forgetting to ask first (ADR 0046). A paint that failed is forgotten, so
    * the next pass over the reach tries again instead of counting the page as
-   * painted; one that settles joins `settled`.
+   * painted; one that settles marks its own entry `done`.
    *
    * **The paint this answers with never rejects**, which is the whole of why
    * `swap` does not either. A page that could not be drawn is not a render
@@ -206,23 +408,33 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    * @type {(i: number) => Promise<void>}
    */
   let start = (i) => {
-    let canvas = pageAt(i);
-    if (backed.has(canvas) && !settled.has(canvas)) canvas = retire(i);
-    settled.delete(canvas);
+    let canvas = /** @type {HTMLCanvasElement} */ (pageAt(i));
+    let carrying = backed.get(canvas);
+    if (carrying && !carrying.done) canvas = retire(i);
     let scale = deviceScale();
-    let each = list.pages[i];
-    canvas.width = Math.round(each.width * scale);
-    canvas.height = Math.round(each.height * scale);
+    // The store is the paper in device pixels, rounded to a whole one. Every
+    // page of the list is the same size, so this is the list's paper and not
+    // the page's — a page carries no geometry to ask (ADR 0069).
+    canvas.width = Math.round(list.width * scale);
+    canvas.height = Math.round(list.height * scale);
     let ctx = /** @type {CanvasRenderingContext2D} */ (canvas.getContext("2d"));
-    let painted = paint(ctx, each, { scale, fonts }).then(
+    // The handlers mark the entry they belong to rather than the canvas: a
+    // second `start` on the same canvas replaces the entry, so the superseded
+    // paint marks one nobody reads instead of declaring the new paint settled.
+    // Assigned after the promise and read only from a handler, which cannot
+    // run before this turn ends.
+    /** @type {Backing} */
+    let entry;
+    let painted = paint(ctx, list.pages[i], { scale, fonts }).then(
       () => {
-        settled.add(canvas);
+        entry.done = true;
       },
       () => {
         backed.delete(canvas);
       },
     );
-    backed.set(canvas, { scale, painted });
+    entry = { scale, painted, done: false };
+    backed.set(canvas, entry);
     return painted;
   };
 
@@ -235,12 +447,16 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    *
    * Takes the index, not the canvas: the page it paints may be retired out
    * from under a caller, so a caller that handed one in would be left holding
-   * an element that is no longer on the sheet.
+   * an element that is no longer on the sheet. A page released between the
+   * pass that chose it and the paint that follows has nothing to paint onto,
+   * and is skipped.
    *
    * @type {(i: number) => Promise<void>}
    */
   let paintPage = (i) => {
-    let carrying = backed.get(pageAt(i));
+    let canvas = pageAt(i);
+    if (!canvas) return Promise.resolve();
+    let carrying = backed.get(canvas);
     if (carrying && carrying.scale === deviceScale()) return carrying.painted;
     return start(i);
   };
@@ -255,54 +471,65 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    *
    * It guards repaint against repaint, and nothing else. A repaint chooses
    * its pages once and holds that list across its awaits, so a scroll pass
-   * releasing a page mid-repaint is one this loop will paint anyway; the
-   * store that leaves behind is bounded by the reach and goes back on the
-   * next pass over it.
+   * releasing a page mid-repaint is one this loop skips when it gets there;
+   * the store that leaves behind is bounded by the reach.
    */
   let epoch = 0;
 
   /**
-   * Give every page its CSS size. Callers run this before writing the scroll
-   * offsets back: the extent those offsets are clamped against is this one,
-   * and the reach below is read from the offsets once they are in.
+   * Give the sheet its extent and the reach its sizes, at the current scale.
+   * Callers run this before writing the scroll offsets back: the extent those
+   * offsets are clamped against is this one, and the reach below is read from
+   * the offsets once they are in. O(reach), not O(pages) — which is what ADR
+   * 0065 is for.
    */
   let sizeAll = () => {
     if (!list) return;
-    let px = scale();
-    for (let i = 0; i < list.pages.length; i++) sizePage(pageAt(i), i, px);
+    extend();
+    for (let [i, canvas] of pages) place(canvas, i);
   };
 
   /**
    * The indices of the pages in the reach — the ones the viewport shows, and
-   * everything within one viewport height above or below. Walked over the
-   * list's own geometry (the gutter, each page's height at the applied
-   * scale, the gap), never a layout read, so it costs nothing to ask
-   * mid-scroll — the whole list is walked because a multiply and an add per
-   * page is beneath measuring, and stopping early would be a second rule
-   * about where the reach ends. `clientHeight` is read afresh each time, so a
-   * pane that changed size changes the reach with it.
+   * everything within one viewport height above or below. Read off the pitch
+   * `measure` holds, never a layout read, so it costs nothing to ask
+   * mid-scroll. `clientHeight` is read afresh each time, so a pane that
+   * changed size changes the reach with it.
+   *
+   * **Two divisions rather than a search, because the pages are a pitch
+   * apart.** Page `i` starts at `i * pitch` and ends a paper below that, so
+   * both bounds of the band invert straight into an index — no walk over the
+   * pages, and no search among them either. This was a bisection first (ADR
+   * 0065's amendment); what made it arithmetic is the list stating its paper
+   * once, so the stacking is a pitch rather than an array of offsets to look
+   * through (ADR 0069).
    *
    * @returns {number[]}
    */
   let inReach = () => {
     let view = scroll.clientHeight;
-    let top = scroll.scrollTop - view;
-    let bottom = scroll.scrollTop + 2 * view;
-    let px = scale();
-    let y = GUTTER;
+    let at = measure();
+    // Sheet-space: the sheet starts a gutter down what the reader scrolls, so
+    // the band is measured from the first page's own top rather than the scroll
+    // container's. Converted once, here.
+    let eye = scroll.scrollTop - GUTTER;
+    // The near bound is the first page whose foot the band has reached — its
+    // foot being a paper below its own top — and the far one the first page
+    // past the band's head. Each can only run off its own end of the list: a
+    // band above the sheet gives a negative near bound, one below it a far
+    // bound past the last page.
+    let first = Math.max(0, Math.ceil((eye - view - at.paper.height) / at.pitch));
+    let after = Math.min(list.pages.length, Math.floor((eye + 2 * view) / at.pitch) + 1);
     let found = [];
-    for (let [i, each] of list.pages.entries()) {
-      let height = each.height * px;
-      if (y + height >= top && y <= bottom) found.push(i);
-      y += height + GAP;
-    }
+    for (let i = first; i < after; i++) found.push(i);
     return found;
   };
 
   /**
-   * Release every page the reach has left behind, and answer with the indices
-   * of the ones to keep, in the order they are painted in. The single
-   * definition of which pages carry pixels: the repaint below and the scroll
+   * Bring the sheet's elements to the reach — minting the pages that entered
+   * it, letting go of the ones that left — and answer with the indices in the
+   * order they are painted in. The single definition of which pages carry
+   * pixels, and now of which carry elements: the repaint below and the scroll
    * pass both go through here, and neither holds a page the other released.
    *
    * Indices rather than elements, for the reason `paintPage` takes one: a
@@ -311,16 +538,37 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
    * @type {() => number[]}
    */
   let keep = () => {
-    let wanted = new Set(inReach());
-    let kept = [];
-    // `retire` replaces one for one, so the count is fixed across the walk.
-    for (let i = 0, total = pages.length; i < total; i++) {
-      if (wanted.has(i)) kept.push(i);
-      else release(i);
-    }
+    let kept = inReach();
+    let wanted = new Set(kept);
+    // A `Map` iterator tolerates the entry it is visiting being deleted, which
+    // is the only one `release` takes, so this walks the live map.
+    for (let i of pages.keys()) if (!wanted.has(i)) release(i);
+    mint(kept);
     return kept;
   };
 
+  /**
+   * Give every page of the reach that has none an element. Ascending, each
+   * fresh page inserted after the one before it, so the sheet's page elements
+   * stay in the list's own order and stay one run of children — an overlay the
+   * caller hung in the same element keeps its place after them.
+   *
+   * @type {(kept: number[]) => void}
+   */
+  let mint = (kept) => {
+    let previous = null;
+    for (let i of kept) {
+      let canvas = pageAt(i);
+      if (!canvas) {
+        canvas = pageOf(i);
+        pages.set(i, canvas);
+        if (previous) previous.after(canvas);
+        else sheetEl.prepend(canvas);
+      }
+      previous = canvas;
+    }
+  };
+
   // Paint the reach in order, yielding between pages and giving way to any
   // repaint that started since. Sizing is the caller's, and comes first.
   let repaint = async () => {
@@ -353,54 +601,49 @@ export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
   scroll.addEventListener("scroll", follow);
 
   return {
-    /** Put a list on the sheet: one canvas per page, sized, with the reach
-     * among them painted. Settles behind the reach — never rejects. */
+    /** Put a list on the sheet: the extent whole at once, and the reach among
+     * its pages given elements and painted. Settles behind the reach — never
+     * rejects. */
     /** @type {(next: any, faces: any) => Promise<void>} */
     async swap(next, faces) {
       fonts = faces;
-      for (let el of pages) el.remove();
+      for (let el of pages.values()) el.remove();
+      pages = new Map();
       list = next;
-      pages = next.pages.map((/** @type {any} */ _, /** @type {number} */ i) => pageOf(i));
-      // Prepended through a fragment, never replacing the sheet's children:
-      // whatever else it holds is the caller's and stays where it was.
-      let batch = document.createDocumentFragment();
-      for (let el of pages) batch.append(el);
-      sheetEl.prepend(batch);
+      stacking = null;
+      extended = null;
+      // Before the first page is built, so the extent is whole from the moment
+      // the list arrives rather than from the moment the reach has painted.
+      extend();
       await repaint();
     },
-    /** Give every page its CSS size at the current scale. Callers run this
-     * before writing scroll offsets back: the extent those are clamped
-     * against is this one. */
+    /** Give the sheet its extent and the reach its sizes at the current scale.
+     * Callers run this before writing scroll offsets back: the extent those
+     * are clamped against is this one. */
     sizeAll,
     /** Repaint the reach, releasing what it has left behind. */
     repaint,
     /** One reach pass a frame, however many scrolls or resizes ask. */
     follow,
-    /** Where each page starts down the sheet, in CSS pixels: what an overlay
-     * positioned against the pages has to agree with.
+    /** Where page `i` starts down the sheet, in CSS pixels: what an overlay
+     * positioned against that page has to agree with. `0` before a list
+     * arrives, there being no sheet to sit on.
      *
-     * Presumes the caller's sheet stacks its pages `GAP` apart — both
-     * surfaces do it with `display: flex; gap`. The CSS is the surface's, so
-     * this is the one number the two have to agree on by hand; a sheet that
-     * stacked them differently would place every overlay after the first
-     * against the wrong page. */
-    tops() {
-      let out = [];
-      // Sheet-space, from the sheet's own top — not the scroll-space walk the
-      // reach uses, which starts a gutter down. An overlay hangs inside the
-      // sheet, so this is the origin it is positioned against.
-      let y = 0;
-      for (let page of list ? list.pages : []) {
-        out.push(y);
-        y += page.height * scale() + GAP;
-      }
-      return out;
-    },
+     * The very offset the sheet places its own page at — so the agreement an
+     * overlay needs is a fact rather than the presumption it used to be (ADR
+     * 0065). One page rather than an array of every page's, because the
+     * stacking is a pitch and there is no array: a caller asks for the page it
+     * is placing something against (ADR 0069). */
+    topOf: (/** @type {number} */ i) => (list ? i * measure().pitch : 0),
     /** The page width the list carries, or `null` before one arrives — what a
      * fit is measured against. */
     width: () => (list ? list.width : null),
-    /** @type {(i: number) => HTMLCanvasElement} */
+    /** @type {(i: number) => HTMLCanvasElement | null} */
     pageAt,
+    /** Which page a client point is over, and where in that page's own points
+     * — the inverse of `topOf()`, answering for any page of the list whether or
+     * not the reach has given it an element. */
+    at,
     count: () => (list ? list.pages.length : 0),
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/landing",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "What quario's two surface elements share — the option check, the render boundary and the failure state — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -36,13 +36,13 @@
     "test:browser": "node test/browser/setup.js"
   },
   "dependencies": {
-    "@quario/layout": "^0.4.0"
+    "@quario/layout": "^0.6.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "lit": "^3.3.3",
-    "playwright": "^1.62.1",
+    "playwright": "^1.63.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },