@quario/viewer 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,15 +1,52 @@
-# Changelog
-
-All notable changes to @quario/viewer 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.7.0] - 2026-09-07
-
-### Added
+# @quario/viewer
+
+## 0.8.0
+
+### Minor Changes
+
+- **An image's box is now as wide as the container it sits in.** A
+  `background` or `border*` on an image item hugged the picture and now spans
+  the content width, or the slot's share inside a split; the picture itself
+  does not move. See the `@quario/layout` changelog for the rule and for what
+  it costs a report that relied on a border hugging a logo.
+- **Only the pages you can see are on the sheet.** A page outside the reach
+  used to be an empty canvas holding its place; now it has no element at all,
+  and the sheet carries the document's extent itself — its height and width are
+  written from the layout, and it paints the page silhouettes. The stretch a
+  reader scrolls through is exactly what it was, and a scale change no longer
+  costs the browser a relayout of every page: that was around 10 microseconds a
+  page, so a five-thousand-page report paid roughly 50 ms of it each time.
+
+  This changes the sheet's markup, which matters if you style it. `.qv-page` is
+  now absolutely positioned inside `.qv-sheet`, and is present only for the pages
+  on screen and one viewport height either side. A rule that gave a page a
+  margin, or that relied on the pages being a flow of siblings, no longer
+  applies — the sheet places its own pages, and does it with inline styles a
+  stylesheet rule cannot override. `--qv-sheet-shadow` is unchanged.
+
+  One cost, stated: a page outside the reach has no `role="img"` node, so
+  assistive technology sees the few images of the reach renumbering as the
+  reader scrolls rather than a document of named pages.
+
+### Patch Changes
+
+- **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
+  - @quario/landing@0.2.0
+  - quario@0.8.0
+
+## 0.7.0
+
+### Minor Changes
 
 - **`fonts` is validated as a host property.** It was the one the viewer never
   checked, so a malformed record reached the target inside the render and came
@@ -18,9 +55,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   on the target's `options.fonts`. A face that will not parse, or a missing
   parser, is still found while the report is measured and remains a render
   failure there.
-
-### Changed
-
 - **A rejected host property reports as `host-option`.** `ViewerErrorKind`
   gains a fourth member, so a host switching exhaustively over the kind needs
   a case for it. A `page`, `zoom`, `filename`, `colorScheme` or `fonts` the
@@ -33,9 +67,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   are refused where the render begins rather than when the property is written,
   so nothing yet tells them apart from a render that failed.
 
-## [0.6.0] - 2026-09-07
+## 0.6.0
 
-### Changed
+### Minor Changes
 
 - **Numbers presented through `format` now show a fixed two fraction digits**,
   the same as every other target: `1,000.00` where the preview showed `1,000`,
@@ -43,9 +77,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a universal two. The digits come from the engine, so a page on screen and
   the PDF of it agree. A formatted cell is also up to three characters wider,
   so a line that just fitted can wrap and move a page break.
-
-### Fixed
-
 - **A page the browser cannot fully paint no longer fails the render.** An
   image whose pixel data is corrupt past the size in its header left that page
   blank _and_ rejected `renderComplete`, so a host awaiting it saw an unhandled
@@ -55,29 +86,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   fires, and no `error` event is raised. It never rejects for this reason
   again: a page that cannot be drawn is blank, not a failed render.
 
-## [0.5.0] - 2026-09-05
+## 0.5.0
 
-### Changed
+### Minor Changes
 
 - **Previewing with `fonts` now needs `fontkit`, not `@pdf-lib/fontkit`.**
   Install `fontkit` instead. The viewer measures host TrueType faces through
   `@quario/layout`, whose optional parser this is; the old package crashed on
   any OpenType face needing a shaping state machine, so those faces now
   preview where they used to throw.
-
 - **The bar's controls are drawn icons.** The zoom trigger, the menu's check
   and the error panel's dismiss are drawn from Lucide's set rather than by
   hand, at one weight and one grid, and the dismiss no longer relies on the
   host's font to draw a multiplication sign. They paint in `currentColor`, so
   `--qv-icon` and `--qv-icon-active` still recolour them.
-
 - **An export button names its format in words.** Each one is a download icon
   with `PDF`, `XLSX` or `CSV` beside it, in place of the sheet drawing that
   lettered the format inside itself. The buttons are wider; the accessible
   name is unchanged.
-
-### Fixed
-
 - **A zoom no longer leaves a page part-drawn.** Changing the zoom while a
   page was still painting could leave that page carrying content at the old
   scale on a canvas sized for the new one — the rest of it blank — and nothing
@@ -85,27 +111,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   whose paint is still in flight is now replaced rather than reused, so the
   superseded paint has nowhere to land.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Added
+### Minor Changes
 
 - **`fonts`.** The font mapping a host passes to `pdf({ fonts })`, so the
   preview measures and draws in the same TrueType faces the document embeds.
-
-### Changed
-
 - **`renderComplete` and `rendered` settle once the pages on screen are
   painted.** Both already answered for the newest render reaching the sheet;
   what that means is now stated: the pages the reader can see carry their
   pixels, and the pages further down the report do not hold the promise up.
   A screenshot or a pixel-reading test taken at that moment sees what the
   reader sees.
-
 - **A split slot's box now fills the split's height.** A slot's background and
   border stopped at that slot's own content and now take the split's height,
   the way a table cell's take their row's. See the `@quario/layout` changelog
   for the rule and for what it costs a report that relied on the short box.
-
 - **The sheet has pages, and they break where the PDF's do.** The viewer
   depends on `@quario/layout` and paints the same display list the pdf target
   writes, one canvas per page, in the faces the document itself uses.
@@ -115,9 +136,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `page` change re-lays the report out rather than resizing a sheet. The
   unlicensed marking is painted per page from the list; the `--qv-mark`
   token is gone with the DOM stamps.
-
-### Fixed
-
 - **A long report no longer asks for a backing store per page.** The viewer
   paints the pages near the viewport — the ones on screen and one screenful
   either side — and keeps every other page sized but blank. A report of a
@@ -128,23 +146,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the first frame, and a zoom step now repaints a handful of pages instead of
   walking the document.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Changed
+### Minor Changes
 
 - **Report and group containers are flex columns.** Adjacent authored
   `spaceBefore` / `spaceAfter` margins add rather than collapse, matching
   the html reference stylesheet.
-
-### Fixed
-
 - **The adopted sheet occupies a line and preserves authored newlines.**
   Same `min-height: 1lh` and `white-space: pre-line` the html reference
   stylesheet now carries on `.q-item`, and `pre-line` on table cells.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Changed
+### Minor Changes
 
 - **The sheet is now page-shaped, so short reports reserve a full page.**
   `page` sized the sheet's width and padding and ignored its height, so a
@@ -163,9 +178,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **The adopted sheet's baseline face moved onto `.q-report`.** It was on
   `.q-item` and `.q-table`, where a direct rule would have beaten a report's
   own declared family. Same look; the fragment's new root is what carries it.
-
-### Fixed
-
 - **The sheet no longer draws report text in the platform's own face.** It
   hard-coded `system-ui`, which is SF Pro on macOS, Segoe UI on Windows and
   Roboto on Android — so the same report showed a different typeface to every
@@ -174,9 +186,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   resolves to Helvetica. The viewer's own chrome keeps `system-ui`, which is
   what a toolbar should do.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **An embeddable `<quario-viewer>`.** Assign a compiled report, the targets
   to render with, and data; it shows the HTML report on a continuous sheet,

package/README.md

@@ -314,6 +314,13 @@ reference seam, not a frozen vocabulary: backdrop and bar (`--qv-backdrop`, `--q
 The report itself is paint, not markup: there is no report stylesheet to restyle, because what
 you see is the layout the PDF target writes.
 
+## 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, and
+[`@quario/viewer`](https://getquario.com/docs/reference/viewer/) is this element's own API.
+
 ## License
 
 Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer

package/lib/icons.js

@@ -4,7 +4,7 @@
  * default, 14px in the gutter and the menu's tick slot — because `x` appears
  * in two contexts at once (ADR 0044).
  *
- * Generated by `scripts/icons.mjs` from lucide 1.40.0. Do not edit:
+ * Generated by `scripts/icons.mjs` from lucide 1.42.0. Do not edit:
  * `npm run icons` rewrites it, and `npm run check` regenerates it into a
  * temp directory and compares.
  *

package/lib/stage.js

@@ -1,9 +1,9 @@
 /**
  * The stage: the surface the pages are painted on. It owns the scroll
  * container the reader looks through, the wrapper that carries the gutter,
- * and the sheet — one canvas per page of the layout list, painted by
- * `@quario/layout`'s `paint` — their elements, their CSS, and every number
- * relating them.
+ * and the sheet — the layout list's whole extent, with a canvas for each page
+ * of the reach painted by `@quario/layout`'s `paint` — their elements, their
+ * CSS, and every number relating them.
  *
  * Zoom is a repaint, not a transform: each page canvas is sized to the
  * percentage in CSS pixels and painted at that scale times the device pixel
@@ -11,15 +11,17 @@
  * reader saw. The list never changes under a zoom — the preview scales and
  * never reflows (zoom.js says why).
  *
- * Every page keeps its CSS size, but only the
- * [reach](../../../CONTEXT.md#reach) carries pixels — the pages on screen and
- * one viewport height either side. The extent the 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 × 0. A scroll or a resize
- * runs the same arithmetic over the list's own geometry, coalesced to one
- * pass a frame. ADR 0043 says what that is worth: painting the whole sheet
- * asked a thousand-page report for gigabytes of backing store, and past what
- * the browser would grant the pages simply came up blank.
+ * The sheet carries the whole list's extent, but only the
+ * [reach](../../../CONTEXT.md#reach) carries elements and pixels — the pages
+ * on screen and one viewport height either side. The extent the reader scrolls
+ * through is whole and synchronous whatever is standing, because the sheet is
+ * given its height and width inline and paints the page silhouettes itself; a
+ * page leaving the reach is removed, which takes its backing store with it
+ * (ADR 0065). A scroll or a resize runs the same arithmetic over the list's own
+ * geometry, coalesced to one pass a frame. ADR 0043 says what the reach is
+ * worth: painting the whole sheet asked a thousand-page report for gigabytes of
+ * backing store, and past what the browser would grant the pages simply 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
@@ -39,13 +41,14 @@
  * *retired* rather than painted over or emptied: 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. A canvas whose paint has
- * settled has nothing that could land late and is re-sized or emptied in
- * place as before. Without this a zoom landing mid-paint could leave a page
+ * settled has nothing that could land late and is re-sized in place as before;
+ * a page leaving the reach is removed either way, which takes its pixels with
+ * it whether that paint has landed or not. Without this a zoom landing mid-paint could leave a page
  * carrying old-scale content on a new-scale canvas, with the memo below
  * calling it painted so that nothing repainted it again (ADR 0046).
  *
- * Retirement is lazy, and only the paint is guarded. A scale change sizes
- * every page's CSS box at once but retires a page only when the repaint loop
+ * Retirement is lazy, and only the paint is guarded. A scale change sizes the
+ * reach's CSS boxes at once but retires a page only when the repaint loop
  * reaches it, so a page further down the reach shows its old pixels stretched
  * into the new box until its turn comes — the ordinary look of a zoom in
  * progress, not the artefact above. The cost is that a retired page is a
@@ -70,12 +73,14 @@
  */
 
 import { css } from "lit";
-import { GAP, GUTTER, sheet } from "@quario/landing";
+import { GUTTER, sheet } from "@quario/landing";
 import { PX_PER_POINT } from "@quario/layout";
 
-// `GUTTER` and `GAP` come from `@quario/landing`, which walks the reach over
-// them: the CSS below and the sheet's own arithmetic have to agree about where
-// a page sits, and two copies of that is a reach that paints the wrong pages.
+// `GUTTER` comes from `@quario/landing`, which walks the reach over it: the CSS
+// below and the sheet's own arithmetic have to agree about where a page sits,
+// and two copies of that is a reach that paints the wrong pages. The gap
+// between pages is that package's too, and is not named here at all — the sheet
+// positions its own pages now, so this file has nothing to space.
 
 export let SURFACE = css`
 /* Where scrollbars take width, the gutter is held whether one is showing or
@@ -101,16 +106,17 @@ export let SURFACE = css`
   margin: ${GUTTER}px auto;
 }
 
-/* The sheet is the stack of pages. */
-.qv-sheet {
-  display: flex;
-  flex-direction: column;
-  gap: ${GAP}px;
-}
+/* The sheet is the whole document's extent, and the pages of the reach are
+   positioned inside it. It has no rule here because it has no look: its
+   position, its height, its width and its page silhouettes are all written
+   inline by \`@quario/landing\` from the list's own geometry, which is the one
+   place any of them is decided (ADR 0065). A page outside the reach has no
+   element, so what shows there is the sheet's own paint.
 
-/* One page. The painter fills it white; the background here is what a page
-   outside the reach shows, and what one inside it shows between being sized
-   and being painted. */
+   One page of the reach, at the size and offset the sheet gives it. The
+   painter fills it white; the background here is what it shows between being
+   placed and being painted, and the shadow is what lifts it off the sheet —
+   the two this file does decide. */
 .qv-page {
   display: block;
   background: #fff;
@@ -191,14 +197,17 @@ export let stage = () => {
      * offset; horizontally the wrapper is centred by auto margins while it
      * fits — which is exactly when `scrollLeft` is 0 anyway — and its margins
      * are 0 once it overflows, so the plain ratio holds wherever it can be
-     * seen. The browser clamps whatever it cannot honour. An empty sheet has
-     * no view to hold, which is what mounting at an authored zoom takes.
+     * seen. The browser clamps whatever it cannot honour. A sheet with no list
+     * on it has no view to hold, which is what mounting at an authored zoom
+     * takes. Asked of the list rather than of the sheet's children, which
+     * since ADR 0065 are the reach's and can be none of them while a list is
+     * standing — and it saves a DOM read besides.
      *
      * Only the reach is repainted, and only where the scale actually changed,
      * so a zoom step costs a handful of pages however long the report is.
      */
     scale: (percent) => {
-      let held = sheetEl.firstChild && {
+      let held = paged.count() > 0 && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
         height: scroll.clientHeight,
@@ -228,12 +237,12 @@ export let stage = () => {
 
     /**
      * Put a laid-out report on the sheet, keeping the reader where they
-     * were: one canvas per page, the reach among them painted at the applied
-     * scale. The order is the point of the method: the pages come off
-     * `pageOf` already at their size, so the browser clamps the offsets going
-     * back against the extent the sheet will have rather than the one it had
-     * — and the reach is read from those offsets, so it is chosen after they
-     * are in. What the
+     * were: the extent whole at once, with the reach's pages painted at the
+     * applied scale. The order is the point of the method: the sheet takes its
+     * height from the list before anything else, so the browser clamps the
+     * offsets going back against the extent the sheet will have rather than
+     * the one it had — and the reach is read from those offsets, so it is
+     * chosen after they are in. What the
      * returned promise settles behind is the reach, which is what the caller's
      * `renderComplete` means by "the pages on screen have finished trying to
      * paint" — and **it never rejects**, because `start` swallows a page the
@@ -241,8 +250,8 @@ export let stage = () => {
      */
     swap: async (next, faces) => {
       // Reading the offsets flushes layout, so only an actual reswap pays for
-      // it: on an empty sheet there is nothing scrolled to preserve.
-      let held = sheetEl.firstChild && {
+      // it: with no list standing there is nothing scrolled to preserve.
+      let held = paged.count() > 0 && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/viewer",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The embeddable report viewer shell for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -44,8 +44,8 @@
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/landing": "^0.1.0",
-    "@quario/layout": "^0.4.0",
+    "@quario/landing": "^0.2.0",
+    "@quario/layout": "^0.5.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
@@ -54,12 +54,12 @@
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
     "exceljs": "^4.4.0",
-    "quario": "^0.7.0",
+    "quario": "^0.8.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.7.0"
+    "quario": "^0.8.0"
   },
   "size-limit": [
     {