@quario/landing 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to @quario/landing are documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-07
+
+### Added
+
+- **First release.** `options()` is the option check two surface elements run
+  per update cycle — first-failure-wins, re-validate-everything, and a commit
+  gate so writing one property cannot clobber what another committed.
+  `Landing` is the render boundary across an element's lifetime: whether a
+  render has ever painted, whether work was abandoned on a disconnect, and the
+  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
+  is painted; what comes and goes is the backing store. `GUTTER` and `GAP`
+  come with it, because the reach walk is measured in them. This adds
+  `@quario/layout` as a runtime dependency, which the sheet paints through.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -0,0 +1,48 @@
+# @quario/landing
+
+**What [quario](https://www.npmjs.com/package/quario)'s two surface elements share below their
+own surfaces.** `@quario/viewer` and `@quario/editor` both take host properties, both carry a
+render boundary across their lifetime, and both draw a panel when something fails. The parts of
+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.
+
+## Install
+
+```bash
+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.
+
+ESM-only, Node 22+, and browser-ready through a standards-based bundler. CSP-safe: no
+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
+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.

package/lib/failure.js

@@ -0,0 +1,77 @@
+/**
+ * The failure a surface is showing, and whether the reader has put it away.
+ *
+ * A panel is a **state**, not a log: it replaces rather than stacks, and the
+ * error event is what takes every failure. This owns which failure is current
+ * and whether it has been dismissed; the markup stays in each surface, where
+ * the class names and the button are its own.
+ *
+ * Whether a repeat announces again is a **policy the caller passes in**, not a
+ * rule settled here. It is downstream of what re-runs the render, which is the
+ * one thing the two surfaces will never share: an editor re-plans on every
+ * keystroke, so an unchanged broken document would fire an event per keypress;
+ * a viewer only re-runs when a host property or the epoch moves, so its rate
+ * is already bounded.
+ */
+
+import { wording } from "./options.js";
+
+/**
+ * Whether an announcement says what the standing one already says. Wording is
+ * the identity for the same reason the option check compares by it: each
+ * failure mints a fresh error, so the objects never match.
+ *
+ * @param {{ label: string, error: unknown } | undefined} failure
+ * @param {string} label
+ * @param {unknown} error
+ */
+export let repeats = (failure, label, error) =>
+  !!failure && failure.label === label && wording(failure.error) === wording(error);
+
+/**
+ * The panel's model for one surface.
+ *
+ * `announce` answers whether anything changed — `false` when the policy
+ * refused a repeat — so a caller knows whether to raise its own event. It
+ * never fires one itself: the event is public API and belongs to the element.
+ *
+ * @param {(failure: { label: string, error: unknown } | undefined, label: string, error: unknown) => boolean} [refuse]
+ *   Whether to say nothing. Defaults to announcing every failure.
+ */
+export let failures = (refuse = () => false) => {
+  /** @type {{ label: string, error: unknown } | undefined} */
+  let failure;
+  let dismissed = false;
+  return {
+    /** What the panel should draw, or `undefined` while there is nothing to
+     * look at — either no failure, or one the reader put away. */
+    get showing() {
+      return dismissed ? undefined : failure;
+    },
+    /** Take the panel down until the next failure worth drawing. */
+    dismiss() {
+      dismissed = true;
+    },
+    /** The dismissal lapses, without announcing anything. A dismissal is
+     * about a subject — a reader who put a failure away did so about the
+     * document they were looking at — so when that changes underneath it, the
+     * standing failure is worth drawing again. Distinct from `clear`, which
+     * is a render landing and takes the failure with it. */
+    reopen() {
+      dismissed = false;
+    },
+    /** A render reached the sheet: the panel says what is wrong with what the
+     * reader is looking at, and this is the moment that stops being true. */
+    clear() {
+      failure = undefined;
+      dismissed = false;
+    },
+    /** @type {(label: string, error: unknown) => boolean} */
+    announce(label, error) {
+      if (refuse(failure, label, error)) return false;
+      failure = { error, label };
+      dismissed = false;
+      return true;
+    },
+  };
+};

package/lib/index.d.ts

@@ -0,0 +1,119 @@
+import type { ReactiveController, ReactiveControllerHost } from "lit";
+
+/** One failure, as a panel draws it: the surface's own label and the value
+ * that was thrown. */
+export interface Failure {
+  label: string;
+  error: unknown;
+}
+
+/** Whether to say nothing about a failure the surface is already showing. */
+export type Refuse = (standing: Failure | undefined, label: string, error: unknown) => boolean;
+
+/** Whether a property changed this update cycle. `hasUpdated` false means the
+ * first cycle, where everything counts as changed. */
+export type Gate = (...keys: string[]) => boolean;
+
+/** One property's check: validate unconditionally, commit under the gate. */
+export type Check = (gate: Gate) => void;
+
+/** What a caught value says. Each check mints a fresh error, so wording rather
+ * than identity is what tells two failures apart. */
+export function wording(error: unknown): string;
+
+/** The option check across one update cycle. `recheck` keeps the first
+ * failure, runs every check whatever any of them threw, and answers whether
+ * the failure changed. */
+export function options(): {
+  readonly invalid: unknown;
+  recheck(
+    hasUpdated: boolean,
+    changed: Map<string, unknown> | Set<string>,
+    checks: Check[],
+  ): boolean;
+};
+
+/** Whether an announcement says what the standing one already says. */
+export function repeats(standing: Failure | undefined, label: string, error: unknown): boolean;
+
+/** The panel's model. `announce` answers whether anything changed, so the
+ * caller knows whether to raise its own event; it never raises one. */
+export function failures(refuse?: Refuse): {
+  readonly showing: Failure | undefined;
+  dismiss(): void;
+  /** The dismissal lapses without announcing: the subject it was about has
+   * changed, so a standing failure is worth drawing again. */
+  reopen(): void;
+  clear(): void;
+  announce(label: string, error: unknown): boolean;
+};
+
+/** The render in flight, so a disconnect can stop it. */
+export interface Aborts {
+  abort(): void;
+}
+
+/**
+ * The render boundary one surface carries across its lifetime. A Lit
+ * `ReactiveController` structurally — nothing is imported from `lit` at run
+ * time.
+ */
+export class Landing implements ReactiveController {
+  constructor(host: ReactiveControllerHost, task: Aborts);
+  /** Whether a render has ever painted the sheet. */
+  landed: boolean;
+  /** Whether work was abandoned rather than finished. */
+  stale: boolean;
+  /** What the render task is keyed on beyond the host's own properties. */
+  epoch: number;
+  /** Whether a run is in flight. The host owns the task, so the host sets it. */
+  pending: boolean;
+  hostConnected(): void;
+  hostDisconnected(): void;
+  /** Ask for a fresh render where one is owed. */
+  wake(): void;
+  /** Whether this run was abandoned: aborted, and the element gone. */
+  dropped(signal: { aborted: boolean }, connected: boolean): boolean;
+  /** Give up on this run, leaving the boundary owing a fresh one. */
+  abandon(): null;
+  /** A render reached the sheet. */
+  land(): void;
+}
+
+/** 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
+ * 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.
+ *
+ * `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
+ * their class names are its public CSS.
+ */
+export function sheet(
+  scroll: HTMLElement,
+  sheetEl: HTMLElement,
+  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. */
+  swap(list: unknown, fonts: unknown): Promise<void>;
+  /** Give every page its CSS size 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[];
+  /** The page width the list carries, or `null` before one arrives. */
+  width(): number | null;
+  pageAt(i: number): HTMLCanvasElement;
+  count(): number;
+};

package/lib/index.js

@@ -0,0 +1,19 @@
+/**
+ * What `@quario/viewer` and `@quario/editor` share below their own surfaces:
+ * the option check they both run per update cycle, the render boundary they
+ * both carry across a lifetime, and the failure state they both draw a panel
+ * from.
+ *
+ * Four modules, and no coupling between them — the option check answers
+ * whether to re-render through a return value, the failure state knows nothing
+ * about the boundary, and the boundary knows neither.
+ *
+ * What is deliberately **not** here: each surface's own checks, its panel
+ * markup, and its public API. The two elements differ in their vocabulary and
+ * in their policy, and only the machinery underneath is one thing
+ * (docs/adr/0059-the-surfaces-share-a-package-not-a-shape.md).
+ */
+export { options, wording } from "./options.js";
+export { Landing } from "./landing.js";
+export { failures, repeats } from "./failure.js";
+export { GAP, GUTTER, sheet } from "./sheet.js";

package/lib/landing.js

@@ -0,0 +1,116 @@
+/**
+ * The render boundary a surface carries across its own lifetime: whether a
+ * render has ever painted the sheet, whether work was abandoned mid-flight,
+ * and the counter that asks for a fresh one.
+ *
+ * A [Lit `ReactiveController`](https://lit.dev/docs/composition/controllers/),
+ * which is a structural interface — a host calls `addController`, and this
+ * answers `hostConnected` and `hostDisconnected`. Nothing is imported from
+ * `lit` at run time, only its type, so this package stays free of it.
+ *
+ * What it owns is the machinery ADR 0043 and ADR 0046 argue about: a
+ * disconnected element abandons work rather than hiding it, and a stale
+ * boundary asks for a new render when it comes back.
+ */
+
+/** @import { ReactiveController, ReactiveControllerHost } from 'lit' */
+
+/**
+ * @typedef {object} Aborts
+ * @property {() => void} abort Stop the render in flight.
+ */
+
+/**
+ * The boundary for one surface element.
+ *
+ * @implements {ReactiveController}
+ */
+export class Landing {
+  /** @type {ReactiveControllerHost} */
+  #host;
+  /** @type {Aborts} */
+  #task;
+  /**
+   * Whether a render has ever painted the sheet: the line between an element
+   * that is mounting and one that is updating (CONTEXT.md, "Landed"). It is
+   * the element's lifetime, not the document's — a new document does not
+   * un-land what is already on screen.
+   */
+  landed = false;
+  /**
+   * Whether work was abandoned rather than finished. A disconnected element
+   * still processes updates, so abandoning is what makes removal stop work
+   * instead of merely hiding it; the boundary stays stale until something
+   * asks for a fresh render.
+   */
+  stale = false;
+  /** What the render task is keyed on beyond the host's own properties: bump
+   * it and the newest state renders again. */
+  epoch = 0;
+
+  /**
+   * @param {ReactiveControllerHost} host
+   * @param {Aborts} task The render in flight, so a disconnect can stop it.
+   */
+  constructor(host, task) {
+    this.#host = host;
+    this.#task = task;
+    host.addController(this);
+  }
+
+  /** Coming back asks for the render that was abandoned, or the one still in
+   * flight when the element left.
+   *
+   * 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
+  hostConnected() {
+    this.wake();
+  }
+
+  /** Removal is not destruction: the properties and the sheet persist, and
+   * 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
+  hostDisconnected() {
+    this.#task.abort();
+  }
+
+  /** Ask for a fresh render, but only where one is owed: a boundary that was
+   * abandoned, or a run that is still going and will be superseded. */
+  wake() {
+    if (this.stale || this.pending) {
+      this.epoch++;
+      this.#host.requestUpdate();
+    }
+  }
+
+  /** Whether a run is in flight. Set by the host, which owns the task. */
+  pending = false;
+
+  /**
+   * Whether this run was abandoned: the engine takes no signal, so the guard
+   * around the body is what abandonment is. It spares only the work that
+   * arrives after a disconnect.
+   *
+   * @param {{ aborted: boolean }} signal
+   * @param {boolean} connected
+   */
+  dropped(signal, connected) {
+    return signal.aborted && !connected;
+  }
+
+  /** Give up on this run, leaving the boundary owing a fresh one. Answers
+   * `null`, the "nothing to show" result a task settles with. */
+  abandon() {
+    this.stale = true;
+    return null;
+  }
+
+  /** A render reached the sheet. */
+  land() {
+    this.landed = true;
+    this.stale = false;
+  }
+}

package/lib/options.js

@@ -0,0 +1,71 @@
+/**
+ * The option check both surfaces run per update cycle.
+ *
+ * A host writes several properties at once and gets one render, so the checks
+ * have to agree on three things that are easy to get subtly wrong and
+ * invisible when they are: 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 a write to one property
+ * does not clobber what another committed.
+ *
+ * The checks themselves stay in each surface — they are its own vocabulary —
+ * and only that agreement lives here.
+ */
+
+/**
+ * What a caught value says. Each check mints a fresh error, so a still-broken
+ * property re-reported on every unrelated write would never compare equal by
+ * identity; its wording is its identity here, and a value with no message of
+ * its own still compares.
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+export let wording = (error) => String(/** @type {any} */ (error)?.message || error);
+
+/**
+ * An option check across one update cycle.
+ *
+ * `recheck` runs every check, whatever any of them threw, and keeps the
+ * **first** failure — one bad property must not stop a good write to another.
+ * Every check re-validates whatever changed, so a property that is still
+ * broken keeps failing rather than being cleared by a write elsewhere. It
+ * answers whether the failure changed, which is what a caller turns into a
+ * fresh render.
+ *
+ * Each check receives a `gate`: the caller validates unconditionally and
+ * commits only under `gate("page")`, so writing `filename` cannot clobber the
+ * mode a reader clicked to or dirty an inherited colour scheme.
+ *
+ * @returns {{
+ *   readonly invalid: unknown,
+ *   recheck: (
+ *     hasUpdated: boolean,
+ *     changed: Map<string, unknown> | Set<string>,
+ *     checks: ((gate: (...keys: string[]) => boolean) => void)[],
+ *   ) => boolean,
+ * }}
+ */
+export let options = () => {
+  /** @type {unknown} */
+  let invalid;
+  return {
+    get invalid() {
+      return invalid;
+    },
+    recheck(hasUpdated, changed, checks) {
+      let was = invalid;
+      invalid = undefined;
+      /** @type {(...keys: string[]) => boolean} */
+      let gate = (...keys) => !hasUpdated || keys.some((key) => changed.has(key));
+      for (let check of checks) {
+        try {
+          check(gate);
+        } catch (error) {
+          invalid ??= error;
+        }
+      }
+      return wording(was) !== wording(invalid);
+    },
+  };
+};

package/lib/sheet.js

@@ -0,0 +1,406 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * **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
+ * the sheet, which is all a render promised.
+ *
+ * **A canvas is never re-pointed at a second paint.** `paint()` awaits before
+ * 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).
+ *
+ * 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
+ * answers a constant. Nor the elements — each surface builds and styles its
+ * own scroll container and sheet, and hands them in.
+ */
+
+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. */
+export const GUTTER = 28;
+export const GAP = 16;
+
+/**
+ * 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 {() => 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
+ *   caller's to choose and this only supplies the viewer's as a default.
+ */
+export let sheet = (scroll, sheetEl, scale, pageClass = "qv-page") => {
+  /** @type {any} The list on the sheet. */
+  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 = [];
+
+  /**
+   * What each backed page is carrying: the scale it was painted at, so a page
+   * re-entering the reach at that scale is not repainted and a scale change
+   * invalidates it, and the paint itself, so whoever asks second waits behind
+   * the paint the first caller started rather than being told it is done.
+   * Keyed by the canvas, so a swap's new pages start with nothing remembered
+   * 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> }>}
+   */
+  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>}
+   */
+  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.
+   *
+   * @type {(i: number) => HTMLCanvasElement}
+   */
+  let pageAt = (i) => pages[i];
+
+  /**
+   * 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.
+   *
+   * @type {(canvas: HTMLElement, i: number, px?: 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";
+  };
+
+  /**
+   * 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.
+   *
+   * @type {(i: number) => HTMLCanvasElement}
+   */
+  let pageOf = (i) => {
+    let canvas = document.createElement("canvas");
+    canvas.className = pageClass;
+    // A canvas is 300 x 150 until told otherwise, and that store counts. A
+    // page starts with none and takes one once it is inside the reach.
+    canvas.width = 0;
+    canvas.height = 0;
+    canvas.setAttribute("role", "img");
+    canvas.setAttribute("aria-label", "Page " + (i + 1) + " of " + list.pages.length);
+    sizePage(canvas, i);
+    return canvas;
+  };
+
+  /**
+   * 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.
+   *
+   * 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
+   * the superseded paint lets go of the context is the timing that ADR
+   * refuses. `paint()` does its whole `save`/draw/`restore` after its awaits,
+   * so emptying the canvas between them unbalances nothing — it just leaves
+   * every op clipped to nothing, which spares the raster work too.
+   *
+   * @type {(i: number) => HTMLCanvasElement}
+   */
+  let retire = (i) => {
+    let old = pageAt(i);
+    let fresh = pageOf(i);
+    old.replaceWith(fresh);
+    pages[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.
+   *
+   * @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;
+  };
+
+  /** Device pixels per point at the applied scale: what a page is
+   * painted at, and what its backing store is sized in. */
+  let deviceScale = () => scale() * (globalThis.devicePixelRatio || 1);
+
+  /**
+   * Start painting page `i`, and answer with that paint. **The one place a
+   * paint begins, and the one place the rule is enforced**: a canvas whose
+   * paint is still in flight is retired here before a second one is pointed
+   * 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`.
+   *
+   * **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
+   * that failed: the report laid out and the list reached the sheet, so there
+   * is nothing for the error panel to say and nothing to report through the
+   * error event. Swallowed here, the one place a paint begins, so no caller
+   * has to remember to; one bad page then costs its own pixels rather than
+   * every page after it in the reach, which this loop awaits one at a time.
+   *
+   * See the header for how little can still reach it — the layout absorbs a
+   * bad image and refuses a bad face while measuring — and why it stays
+   * anyway. A paint that failed is forgotten so the next pass over the reach
+   * tries again, which is what makes a failure for a passing reason
+   * recoverable.
+   *
+   * @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 scale = deviceScale();
+    let each = list.pages[i];
+    canvas.width = Math.round(each.width * scale);
+    canvas.height = Math.round(each.height * scale);
+    let ctx = /** @type {CanvasRenderingContext2D} */ (canvas.getContext("2d"));
+    let painted = paint(ctx, each, { scale, fonts }).then(
+      () => {
+        settled.add(canvas);
+      },
+      () => {
+        backed.delete(canvas);
+      },
+    );
+    backed.set(canvas, { scale, painted });
+    return painted;
+  };
+
+  /**
+   * Paint one page and answer with that paint — or with the paint already
+   * under way at this scale, which is what makes scrolling back over ground
+   * already covered free. Answering with the paint rather than with a
+   * resolved promise is what lets two callers share one page's paint and both
+   * settle behind its pixels.
+   *
+   * 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.
+   *
+   * @type {(i: number) => Promise<void>}
+   */
+  let paintPage = (i) => {
+    let carrying = backed.get(pageAt(i));
+    if (carrying && carrying.scale === deviceScale()) return carrying.painted;
+    return start(i);
+  };
+
+  /**
+   * Bumped per repaint, so a repaint overtaken by the next stops walking.
+   * What that guards is the backing store, not the pixels: a superseded loop
+   * would paint at the *current* scale — `paintPage` reads it afresh — but
+   * onto pages the newer reach has since dropped, re-backing pages that
+   * should be blank (ADR 0043). Stale pixels are `retire`'s business, not
+   * this one, so neither guard stands in for the other.
+   *
+   * 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.
+   */
+  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.
+   */
+  let sizeAll = () => {
+    if (!list) return;
+    let px = scale();
+    for (let i = 0; i < list.pages.length; i++) sizePage(pageAt(i), i, px);
+  };
+
+  /**
+   * 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.
+   *
+   * @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 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;
+    }
+    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
+   * pass both go through here, and neither holds a page the other released.
+   *
+   * Indices rather than elements, for the reason `paintPage` takes one: a
+   * page can be retired between this pass and the paint that follows it.
+   *
+   * @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);
+    }
+    return kept;
+  };
+
+  // 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 () => {
+    if (!list) return;
+    let mine = ++epoch;
+    for (let i of keep()) {
+      if (mine !== epoch) return;
+      await paintPage(i);
+    }
+  };
+
+  /**
+   * One reach pass a frame, however many scrolls and resizes ask for one. It
+   * keeps no epoch of its own, so a swap painting behind it is never cut off
+   * part-painted, and a page it starts is one a swap arriving at the same page
+   * waits behind rather than skips. Nothing awaits these paints here: a scroll
+   * is not a render, and a page that will not paint is blank whoever asked for
+   * it — `start` settles either way, so there is nothing here to catch.
+   */
+  let pending = false;
+  let follow = () => {
+    if (pending) return;
+    pending = true;
+    requestAnimationFrame(() => {
+      pending = false;
+      if (!list) return;
+      for (let i of keep()) void paintPage(i);
+    });
+  };
+  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. */
+    /** @type {(next: any, faces: any) => Promise<void>} */
+    async swap(next, faces) {
+      fonts = faces;
+      for (let el of pages) el.remove();
+      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);
+      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. */
+    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.
+     *
+     * 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 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} */
+    pageAt,
+    count: () => (list ? list.pages.length : 0),
+  };
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@quario/landing",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/landing"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "test:types": "tsc && attw --pack . --profile esm-only",
+    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\"",
+    "test:browser": "node test/browser/setup.js"
+  },
+  "dependencies": {
+    "@quario/layout": "^0.4.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "lit": "^3.3.3",
+    "playwright": "^1.62.1",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "limit": "6 kB",
+      "ignore": [
+        "@quario/layout"
+      ]
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}