@quario/viewer 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @quario/viewer
 
+## 0.11.0
+
+### Minor Changes
+
+- **A collapsed group does not draw its content.** The sheet paints the layout's pages, so an instance whose group declares `collapsed` reads as its header and footer alone.
+- **A group's `label` titles its outline row.** The panel lists the layout's marks, so an instance that declares a label reads under it rather than under its first header line.
+- **A linked run is clickable, and reachable with a keyboard.** Every run carrying an `href` now gets a region of its own over the words the page paints, so a reader clicks it or reaches it with Tab and opens it with Enter. A URL is an anchor opening in a tab of its own. An `href` naming a group's `label` is a button that steps the sheet to that instance, the way an outline row does, and a label no instance carries is no region at all. The regions follow the reach as the pages do, and move with the zoom.
+
+  The size budget rises from 8.5 kB to 9.5 kB to hold them.
+
+- **An optional outline panel.** Set `outline` to `true` and the bar carries one more control, which opens a panel beside the sheet. The panel lists the report's group instances, nested by depth, in document order, and a row scrolls the sheet to where that instance begins. The list is the group tree the PDF target writes as bookmarks, so a report declares nothing for it. An instance whose bands all resolve hidden is not in it. The module is off by default. The reader opens and closes the panel.
+
+### Patch Changes
+
+- **An error quario replaces keeps the one it replaced, as `cause`.** A failure inside one of your own functions reaches you named where it happened — `detail[0].value [{{ total() }}]: ...` — which is a copy, rebuilt from the class and a prefixed message. The stack that says which line of your function threw used to go with the original. It now rides along: read `error.cause` for the throw as it happened, and the message for where quario was when it happened.
+
+  The viewer's and the editor's own property checks do the same. A `page` or `fonts` value either element refuses throws a `TypeError` naming the property, and that error now carries the layout's own account of the value behind it.
+
+- **`renderComplete` answers for the newest render at the moment it settles.** A render that starts behind a pending `await` is the one the promise then waits for, so a host awaiting it while properties keep changing waits for the last change's render. Before, the promise could settle for the render in flight when it was asked, or miss one that started behind it.
+- **The viewer reports a target it cannot export, rather than dropping it.** A `targets` entry whose name is not `pdf`, `xlsx`, `csv`, `docx` or `html` used to disappear: no button, no error. It is now a host mistake like any other malformed property. The error panel names the entry by its index and the name it carried, and the last good render stays up. An `html` target is still accepted and not read, so one list can serve both `render` and the viewer.
+- Updated dependencies
+  - quario@0.11.0
+  - @quario/layout@0.8.0
+  - @quario/landing@0.3.1
+
+## 0.10.0
+
+### Minor Changes
+
+- **A viewer you insert again renders once more, unless its last render landed on the sheet.** It used to do that only for a render that stopped mid-flight, which left three ways for the newest render to go missing with nothing owed.
+
+  A render that failed while the element was out of the document is one of them. The error panel reaches nobody there, so the verdict reached nobody, and the element came back showing the previous pages with no panel and no re-render owed. A property the host rejected while the element was out of the document behaved the same way. So did a property written while it was out of the document.
+
+  All three now leave the render owed, and inserting the element collects it. What you see on reconnect is the panel the failure earns, or the pages the newest properties produce.
+
+  A failure the panel already showed is owed again too. Removing and inserting such an element re-runs the render and reports the same failure once. It is not announced twice.
+
+### Patch Changes
+
+- Updated dependencies
+  - @quario/layout@0.7.0
+  - quario@0.10.0
+  - @quario/landing@0.3.0
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -10,6 +10,23 @@ list, painted page by page. You pass the export targets you want, and the viewer
 to each (`"pdf"`, `"xlsx"`, `"csv"`, `"docx"`). The bar always carries the zoom control. With no
 exportable target it carries nothing else.
 
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Properties](#properties)
+- [Events and `renderComplete`](#events-and-rendercomplete)
+- [Lifecycle](#lifecycle)
+- [Using with React, Vue and Svelte](#using-with-react-vue-and-svelte)
+- [Zoom](#zoom)
+- [Outline](#outline)
+- [Links](#links)
+- [What the preview is](#what-the-preview-is)
+- [Errors](#errors)
+- [Color scheme](#color-scheme)
+- [Documentation](#documentation)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -66,11 +83,14 @@ package to install. See [Using with React, Vue and Svelte](#using-with-react-vue
 | `fonts`       | The font mapping, as passed to `pdf({ fonts })` | none        |
 | `filename`    | Export download name, without extension         | `"report"`  |
 | `colorScheme` | `"light"`, `"dark"`, or `"auto"`                | `"light"`   |
+| `outline`     | `true` to offer the outline panel               | `false`     |
 
 Properties, not attributes: `report`, `targets`, `data`, `page` and `fonts` are values no attribute
 could carry. `targets` mirrors `report.render(target, data)` for the exports:
 `"pdf"`/`"xlsx"`/`"csv"`/`"docx"` targets become export buttons, in the order given, and the
-sheet needs none of them. The quario instance (and with it the license and the registry) stays
+sheet needs none of them. An `"html"` target is accepted and not read, so one list can serve
+`render` and the viewer. Any other name is a host mistake: the viewer reports it on the error panel
+with the entry's index, and renders nothing. The quario instance (and with it the license and the registry) stays
 yours: the element takes the compiled report, never a schema.
 
 Assigning `data` (or any of the others) re-renders. Rapid successive writes render only the newest
@@ -100,8 +120,9 @@ inline `onerror` attribute on the element would fire too. `window.onerror` never
 `renderComplete` awaits the newest render settling: `true` when it landed on the sheet with the pages
 on screen finished trying to paint, `false` when it failed or there was nothing to render. It never
 rejects. Failures arrive on the `error` event. `rendered` fires at that same moment. Like every
-outcome here, it answers for the newest render only. A superseded render's failure reaches no
-one.
+outcome here, it answers for the newest render only: the render that is newest when the promise
+settles, so a render that starts behind your `await` is the one it then waits for. A superseded
+render's failure reaches no one.
 
 An image the browser cannot decode — pixel data corrupt past the size in its header, which is all
 the engine reads — is drawn as nothing, and the page is drawn around it. That is not a render
@@ -115,11 +136,12 @@ option property, becomes a `TypeError` naming the property, on the `error` event
 
 ## Lifecycle
 
-There is no `destroy()`. Removing the element from the DOM abandons in-flight work and releases
-its observers. An export that settles after removal downloads nothing. The properties persist, and
-re-inserting the element re-renders from them, so reparenting is safe, and discarding a viewer is
-just discarding the element. Two viewers, or a viewer beside your own components, coexist: each
-element owns its own shadow root.
+There is no `destroy()`. Removal from the DOM stops the work in flight and releases the
+observers. An export that settles after removal downloads nothing. The properties and the pages
+persist. The element still owes a render that did not land on the sheet. It therefore renders
+once more when you insert it, unless its last render landed. Reparenting is safe, and you
+discard a viewer by discarding the element. Two viewers, or a viewer beside your own components,
+coexist: each element owns its own shadow root.
 
 ## Using with React, Vue and Svelte
 
@@ -234,6 +256,18 @@ Every page keeps its size, so the scrollbar and the scroll extent are the whole
 start. A page further off is blank paper until you scroll to it, which is why a zoom step costs the
 same on a thousand-page report as on a five-page one.
 
+## Links
+
+A run that carries an [`href`](https://github.com/getquario/quario/blob/main/SCHEMA.md#style-declarations) gets a region of its own over the words the page
+paints. The reader clicks it, or reaches it with the Tab key and opens it with Enter. You
+declare nothing for this and turn nothing on.
+
+A URL opens in a tab of its own, so a reader reading a report never loses it. The engine
+admitted that URL against your instance's `schemes` allowlist before the viewer saw it,
+which is where you decide what a report may point at. An `href` that starts with `#` names
+a group's `label` and steps the sheet to that instance, the way an outline row does. A
+label no instance carries is no region, and the words stay as they are.
+
 ## What the preview is
 
 The pages on screen are the pages the PDF export writes: both consume one layout, `@quario/layout`'s
@@ -242,6 +276,8 @@ longer one is as many pages as the layout breaks it into, stacked down the sheet
 container to a viewer that draws a short report therefore reserves a full page. Set `zoom` to a
 percentage small enough where the box has to stay small.
 
+The reader reads and does not reorder. The viewer paints the layout's pages and offers no sort, because a page is not a grid; a host that wants sorted rows renders the report again with them sorted. The XLSX target's `filter` option is where a reader gets a control of their own.
+
 Each page is a canvas, and text on it is drawn in the face the document will use. The viewer
 registers a TrueType family you pass as `fonts` from your own bytes and draws it as the browser
 shapes it —
@@ -303,6 +339,19 @@ data is the message itself, if your own registry functions interpolate a row int
 That is your call, and the panel puts it on screen as text, never as markup. Compile errors are not
 part of this: `q.report(schema)` raises those before the viewer is ever handed a report.
 
+## Outline
+
+Set `outline` to `true` and the bar carries one more control. It opens a panel beside the sheet
+that lists the report's group instances, nested by depth, in document order. A row scrolls the
+sheet to where that instance begins. The list is the group tree the PDF target writes as
+bookmarks, and a row reads the group's `label` where one is declared. A group instance whose bands all resolve
+hidden is not in the list. The property turns the module on. The reader opens and closes the
+panel, and the panel opens when the module turns on.
+
+```js
+view.outline = true;
+```
+
 ## Color scheme
 
 `colorScheme` paints the **chrome** — backdrop, bar, controls, progress strip, error

package/lib/button.js

@@ -1,8 +1,6 @@
 /**
  * The shared `qv-button` template. Every control the viewer renders comes
- * from here — the zoom menu's trigger, the export downloads, the error
- * panel's dismiss — so they agree on the class, the `type` and how they are
- * named.
+ * from here, so they agree on the class, the `type` and how they are named.
  */
 import { css, html, nothing } from "lit";
 
@@ -26,16 +24,28 @@ export let BUTTON = css`
     cursor: pointer;
   }
 
-  .qv-button:hover {
+  /* The interaction treatment, written once for every <button> the viewer
+   draws. A menu row (\`menu.js\`) and an outline row (\`outline.js\`) are
+   buttons too: a different shape — full width, left-aligned — but hovering
+   and focusing them mean the same thing, and stating that twice is how the
+   two drifted apart before the palette landed. Where a row differs it says
+   so itself. */
+  .qv-button:hover,
+  .qv-menuitem:hover,
+  .qv-outline-row:hover {
     background: var(--_hover);
     color: var(--_icon-active);
   }
 
-  .qv-button:active {
+  .qv-button:active,
+  .qv-menuitem:active,
+  .qv-outline-row:active {
     background: var(--_active);
   }
 
-  .qv-button:focus-visible {
+  .qv-button:focus-visible,
+  .qv-menuitem:focus-visible,
+  .qv-outline-row:focus-visible {
     outline: 2px solid var(--_focus);
     outline-offset: 1px;
   }
@@ -67,15 +77,12 @@ let fallback = (value, otherwise) => value ?? otherwise;
  *
  * @param {{ title: string, label?: string, disabled?: boolean, name?: string,
  *   popover?: string, click?: () => void,
- *   content?: import('lit').TemplateResult }} control
- *   `content` is the icon a control draws and `label` the visible text it
- *   reads as; an export button carries both, the zoom trigger and the panel's
- *   dismiss the icon alone. Neither is ever the accessible name — `title` is,
- *   which is why the icons are `aria-hidden`. `name` marks an export button
- *   with the target it downloads, and
- *   `popover` names the menu this button opens — the platform then owns the
- *   opening and the invoker's own `aria-expanded`, which is why such a button
- *   needs no click of its own.
+ *   content: import('lit').TemplateResult }} control
+ *   `content` is the icon every control draws and `label` the visible text it
+ *   reads as. Neither is ever the accessible name — `title` is, which is why
+ *   the icons are `aria-hidden`. `name` marks an export button with the target
+ *   it downloads. `popover` names the menu this button opens, and the platform
+ *   then owns the opening and the invoker's `aria-expanded`.
  * @returns {import('lit').TemplateResult}
  */
 export let button = ({ title, label, disabled, name, popover, click, content }) => html`
@@ -90,6 +97,6 @@ export let button = ({ title, label, disabled, name, popover, click, content })
     ?disabled=${disabled}
     @click=${click}
   >
-    ${content ?? nothing}${label ?? nothing}
+    ${content}${label ?? nothing}
   </button>
 `;

package/lib/check.js

@@ -1,20 +1,26 @@
 /**
- * What the host got wrong, named. The element's own mistakes — a report that
- * is not compiled, a malformed option property — are definition-shaped: they
- * describe the embedding, not the report, so each check here throws a
- * `TypeError` naming the property and the expectation. The element rethrows
- * them from its render task, which is how one channel (the error event and
- * the panel) carries every failure a host can cause.
+ * What the host got wrong, named. Each check throws a `TypeError` naming the
+ * property and the expectation; the element rethrows them from its render
+ * task, so one channel carries every failure a host can cause.
  *
  * Pure policy, no DOM: this module is what the Node suite pins.
  */
 
 import { checkFonts, pageBox } from "@quario/layout";
+import { EXPORTS } from "./toolbar.js";
 import { STEPS } from "./zoom.js";
 
-/** @type {(message: string) => never} */
-let fail = (message) => {
-  throw new TypeError("quario-viewer: " + message);
+/**
+ * Name the mistake on the property that carries it. An `Error` stands in for
+ * its own message and rides along as `cause`: a replacement is a claim about
+ * what went wrong, and only the error it replaced can contradict it
+ * (docs/adr/0084).
+ *
+ * @type {(said: string | Error) => never}
+ */
+let fail = (said) => {
+  let message = said instanceof Error ? said.message : said;
+  throw new TypeError("quario-viewer: " + message, said instanceof Error ? { cause: said } : {});
 };
 
 let REPORT = [
@@ -26,10 +32,19 @@ let REPORT = [
 /** @type {(report: any) => boolean} */
 let compiled = (report) => REPORT.every((check) => check(report));
 
+// The one target the viewer accepts and never reads: a host that hands one
+// list to `render` and to the viewer carries it, and the sheet is the
+// layout's own. Every other name the export map does not hold is a mistake,
+// because the viewer would drop it without a button and without a word.
+let UNREAD = ["html"];
+let ACCEPTED = [...Object.keys(EXPORTS), ...UNREAD];
+let NAMES = ACCEPTED.map((name) => '"' + name + '"').join(", ");
+
 /**
  * The shapes a render needs: a compiled report, and the export targets as an
  * array — possibly empty, since the sheet is the layout's own and needs no
- * target of the host's.
+ * target of the host's. Each entry names a target the viewer exports or the
+ * one it leaves unread; anything else is named on its index.
  *
  * @param {any} report
  * @param {any} targets
@@ -37,6 +52,19 @@ let compiled = (report) => REPORT.every((check) => check(report));
 export let exports = (report, targets) => {
   if (!compiled(report)) fail("report: expected a compiled report from a quario instance");
   if (!Array.isArray(targets)) fail("targets: expected an array of render targets");
+  targets.forEach(named);
+};
+
+/** What a rejected entry carried, in the message's words. */
+/** @type {(target: any) => string} */
+let carried = (target) =>
+  target?.name === undefined ? "a value with no name" : JSON.stringify(target.name);
+
+/** One entry of `targets`, named on its index when the viewer would drop it. */
+/** @type {(target: any, i: number) => void} */
+let named = (target, i) => {
+  if (ACCEPTED.includes(target?.name)) return;
+  fail("targets[" + i + "]: expected a target named one of " + NAMES + ", got " + carried(target));
 };
 
 /**
@@ -51,15 +79,14 @@ export let geometry = (page) => {
   try {
     return pageBox(page, "page");
   } catch (error) {
-    return fail(/** @type {Error} */ (error).message);
+    return fail(/** @type {Error} */ (error));
   }
 };
 
 /**
  * The font mapping from the `fonts` property. Only the shape reaches here: a
- * face that will not parse, or a missing parser, is found while the report is
- * measured and is a render failure there. The layout names the mistake; this
- * names the property, the way `geometry` does.
+ * face that will not parse is found while the report is measured and is a
+ * render failure there.
  *
  * @param {any} fonts
  */
@@ -67,7 +94,7 @@ export let faces = (fonts) => {
   try {
     checkFonts(fonts, "fonts");
   } catch (error) {
-    fail(/** @type {Error} */ (error).message);
+    fail(/** @type {Error} */ (error));
   }
 };
 
@@ -76,12 +103,10 @@ let inRange = (mode, floor, ceiling) =>
   [Number.isFinite(mode), mode >= floor, mode <= ceiling].every(Boolean);
 
 /**
- * The zoom mode from the `zoom` property. Fit is the default: the host owns
- * the box, and a report nobody can read until they touch a control is not
- * much of a preview. A host may author any percentage from 25 to 200 —
- * continuous, not one of the menu's own stops; fit itself computes anything
- * at or below 100, so this deliberately validates less than the element can
- * display.
+ * The zoom mode from the `zoom` property, fit by default. A host may author
+ * any percentage from 25 to 200 — continuous, not one of the menu's stops.
+ * Fit itself computes anything at or below 100, so this deliberately
+ * validates less than the element can display.
  *
  * @param {any} zoom
  * @returns {"fit" | number}
@@ -110,15 +135,27 @@ export let name = (filename) => {
   return base;
 };
 
+/**
+ * Whether the outline module is on, from the `outline` property, off by
+ * default. A flag, so anything but a boolean or nothing is a mistake.
+ *
+ * @param {any} outline
+ * @returns {boolean}
+ */
+export let outlined = (outline) => {
+  if (outline !== undefined && typeof outline !== "boolean")
+    fail("outline: expected true or false");
+  return outline === true;
+};
+
 /** The schemes the property accepts. Two are their own CSS value; `auto` is
  * the one that is not, so it is the only wording written here. */
 let SCHEMES = ["light", "dark", "auto"];
 
 /**
- * The used `color-scheme` from the `colorScheme` property. Light is the
- * default: embedding is the product, and following the OS would paint a light
- * toolbar in a host that already chose dark. `"auto"` is the opt-in that
- * follows, as CSS `light dark`.
+ * The used `color-scheme` from the `colorScheme` property, light by default:
+ * following the OS would paint a light toolbar in a host that already chose
+ * dark. `"auto"` is the opt-in that follows, as CSS `light dark`.
  *
  * @param {any} colorScheme
  * @returns {string}

package/lib/chrome.js

@@ -4,37 +4,23 @@
  * `stage.js` keeps it paper.
  *
  * This module also owns the **default palette**: the `:host` block below is
- * the one place a `--qv-*` fallback is written, and every sheet — this one
- * included — paints from the `--_*` alias it declares. That is what makes a
- * color one edit rather than a hunt, and `viewer.test.js` holds both halves:
- * `--qv-` appears in no other module, and the aliases read are exactly the
- * ones declared. The fallbacks are `light-dark()`, so a `color-scheme` pin on
- * the host paints chrome without a class.
+ * the one place a `--qv-*` fallback is written, and every sheet paints from
+ * the `--_*` alias it declares. The fallbacks are `light-dark()`, so a
+ * `color-scheme` pin on the host paints chrome without a class. The other
+ * sheets therefore paint only where this one is adopted too — presence, not
+ * order, since a custom property resolves down the inherited chain.
  *
- * The cost is that the other sheets no longer stand alone — they paint only
- * where this one is adopted too. It is presence, not order: a custom property
- * resolves down the inherited chain, so where CHROME sits in `static styles`
- * does not matter, only that it is there.
+ * The two halves are written differently on purpose. A host token must always
+ * win, so a default is a `var()` fallback — which applies only when the token
+ * is unset — never a `:host { --qv-border: … }` rule, whose pseudo-class
+ * specificity would beat the host's own `quario-viewer` rule (ADR 0018). The
+ * private aliases invert that: `:host` outranks the host rule, so nothing
+ * outside can shadow one by accident.
  *
- * Host tokens always win, and `:host` is what makes that survive here. A
- * `:host { --qv-border: … }` *default* would carry pseudo-class specificity
- * and beat a host's own `quario-viewer` rule — the seam ADR 0018 declines to
- * make a lie. A `var()` fallback applies only when the token is unset, so it
- * loses to a host token at any specificity. The private half inverts that on
- * purpose: `:host` outranks that same host rule, so nothing outside can
- * shadow an alias by accident.
- *
- * One of the fifteen is the sheet's rather than the chrome's: a color scheme
- * paints chrome only (ADR 0018), so `--qv-sheet-shadow` is the sheet's edge
- * against the backdrop. It is in the block because it has no exceptions, not
- * because it follows the pin.
- * `--qv-focus` and `--qv-progress` repeat the accent rather than chain a third
- * alias — a host is free to move one alone.
- *
- * What is not here is what another module owns: `stage.js` the surface a
- * report is scaled on, `panel.js` the error panel, `button.js` the controls
- * every group in the bar is built from. The element composes their templates
- * and stylesheets; the imports run one way only.
+ * `--qv-sheet-shadow` is the sheet's edge against the backdrop rather than
+ * chrome (a color scheme paints chrome only, ADR 0018); it sits here because
+ * it has no exceptions. `--qv-focus` and `--qv-progress` repeat the accent
+ * rather than chain a third alias, so a host can move one alone.
  */
 import { css, html, nothing } from "lit";
 
@@ -80,13 +66,13 @@ export let CHROME = css`
     font: 13px/1.4 system-ui, sans-serif;
   }
 
-  /* Everything below the bar. It exists to be the box the error panel is
-   positioned against: anchored to the viewer instead, the panel would cover
-   the bar's own controls. */
+  /* Everything below the bar: the outline panel when it is open, then the
+   stage. It exists to be the box the error panel is positioned against:
+   anchored to the viewer instead, the panel would cover the bar's own
+   controls. */
   .qv-body {
     position: relative;
     display: flex;
-    flex-direction: column;
     flex: 1;
     min-height: 0;
   }
@@ -162,6 +148,10 @@ export let CHROME = css`
     margin-right: auto;
   }
 
+  .qv-outline-toggle {
+    display: flex;
+  }
+
   .qv-exports {
     display: flex;
     gap: 2px;
@@ -188,9 +178,8 @@ export let CHROME = css`
 `;
 
 /**
- * The render indicator. Idle it stays out of the accessibility tree — an
- * unstarted progressbar has nothing to announce — and the stylesheet above
- * hooks on the viewer's `aria-busy` to show it.
+ * The render indicator. Idle it stays out of the accessibility tree, and the
+ * stylesheet above hooks on the viewer's `aria-busy` to show it.
  *
  * @param {boolean} busy
  * @returns {import('lit').TemplateResult}

package/lib/icons.js

@@ -21,5 +21,8 @@ export let check = icon(svg`<path d="M20 6 9 17l-5-5"/>`);
 export let download = icon(
   svg`<path d="M12 15V3"/><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><path d="m7 10 5 5 5-5"/>`,
 );
+export let listTree = icon(
+  svg`<path d="M8 5h13"/><path d="M13 12h8"/><path d="M13 19h8"/><path d="M3 10a2 2 0 0 0 2 2h3"/><path d="M3 5v12a2 2 0 0 0 2 2h3"/>`,
+);
 export let search = icon(svg`<path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/>`);
 export let x = icon(svg`<path d="M18 6 6 18"/><path d="m6 6 12 12"/>`);

package/lib/index.d.ts

@@ -56,8 +56,9 @@ export interface ViewerErrorDetail {
  * element up with the panel saying why. A superseded render's failure is
  * reported to no one.
  *
- * Removing the element abandons in-flight work and releases its observers;
- * the properties persist, and reconnecting re-renders from them. There is no
+ * Removing the element stops the work in flight and releases its observers;
+ * the properties persist, and reconnecting renders them again unless the last
+ * render landed. There is no
  * `destroy()` — removal is destruction only in the garbage-collection sense,
  * and reparenting is safe. An export settling after removal downloads
  * nothing.
@@ -96,6 +97,14 @@ export class QuarioViewer extends LitElement {
    * follows the OS via CSS `color-scheme`. The sheet stays white.
    */
   colorScheme: "light" | "dark" | "auto" | undefined;
+  /**
+   * Whether the outline module is on. Off by default. On, the bar carries a
+   * toggle and a panel beside the sheet lists the report's group instances,
+   * nested by depth, in document order; a row scrolls to where that instance
+   * begins. The list is the one the PDF target writes as bookmarks, so
+   * nothing in the report declares it, and a hollow instance is not in it.
+   */
+  outline: boolean | undefined;
   /**
    * The newest render settling: `true` when it landed on the sheet with the
    * pages on screen finished trying to paint, `false` when it failed or there