@quario/viewer 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @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

package/README.md

@@ -19,6 +19,8 @@ exportable target it carries nothing else.
 - [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)
@@ -81,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
@@ -115,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
@@ -250,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
@@ -258,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 —
@@ -319,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

@@ -24,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;
   }
@@ -65,8 +77,8 @@ 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
+ *   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
@@ -85,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

@@ -7,11 +7,20 @@
  */
 
 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 = [
@@ -23,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
@@ -34,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));
 };
 
 /**
@@ -48,7 +79,7 @@ export let geometry = (page) => {
   try {
     return pageBox(page, "page");
   } catch (error) {
-    return fail(/** @type {Error} */ (error).message);
+    return fail(/** @type {Error} */ (error));
   }
 };
 
@@ -63,7 +94,7 @@ export let faces = (fonts) => {
   try {
     checkFonts(fonts, "fonts");
   } catch (error) {
-    fail(/** @type {Error} */ (error).message);
+    fail(/** @type {Error} */ (error));
   }
 };
 
@@ -104,6 +135,19 @@ 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"];

package/lib/chrome.js

@@ -66,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;
   }
@@ -148,6 +148,10 @@ export let CHROME = css`
     margin-right: auto;
   }
 
+  .qv-outline-toggle {
+    display: flex;
+  }
+
   .qv-exports {
     display: flex;
     gap: 2px;

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

@@ -97,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

package/lib/index.js

@@ -28,8 +28,10 @@ import { Landing, failures, options } from "@quario/landing";
 import { layout } from "@quario/layout";
 import { BUTTON } from "./button.js";
 import { CHROME, progress } from "./chrome.js";
-import { exports, faces, geometry, level, name, scheme } from "./check.js";
+import { LINKS } from "./links.js";
+import { exports, faces, geometry, level, name, outlined, scheme } from "./check.js";
 import { MENU, zoomMenu } from "./menu.js";
+import { OUTLINE, outlinePanel, outlineToggle } from "./outline.js";
 import { PANEL, label, panel } from "./panel.js";
 import { SURFACE, stage } from "./stage.js";
 import { EXPORTS, exportGroup, saveAs } from "./toolbar.js";
@@ -60,7 +62,7 @@ export class QuarioViewer extends LitElement {
   // CHROME declares the default palette every other sheet paints from, so it
   // has to be in this list -- but anywhere in it: a custom property resolves
   // down the inherited chain, not by stylesheet order.
-  static styles = [CHROME, BUTTON, MENU, SURFACE, PANEL];
+  static styles = [CHROME, BUTTON, MENU, OUTLINE, SURFACE, LINKS, PANEL];
 
   // Properties only, no attributes: `report`, `targets`, `data` and `page`
   // are values no attribute could carry, and one door beats two.
@@ -73,6 +75,7 @@ export class QuarioViewer extends LitElement {
     fonts: { attribute: false },
     filename: { attribute: false },
     colorScheme: { attribute: false },
+    outline: { attribute: false },
   };
 
   // The stage is built once and never rebuilt: it is the one imperative thing
@@ -101,17 +104,15 @@ export class QuarioViewer extends LitElement {
   #reapply = false;
   /** @type {Set<string>} The exports in flight; their buttons disable. */
   #exporting = new Set();
+  /** Whether the outline module is on, committed from the property. */
+  #outlined = false;
+  /** Whether the reader has the panel open. The reader's, so a property
+   * write does not close what they opened. */
+  #outlineOpen = true;
+  /** @type {readonly any[]} The newest landed list's marks: the outline. */
+  #marks = [];
   /** @type {(() => void) | undefined} */
   #unwatch;
-  /**
-   * The newest swap's paint, which `renderComplete` waits behind. Bare, with
-   * no catch of its own: the stage settles a page it cannot draw rather than
-   * rejecting, so the chain below is reached whatever the pixels did.
-   *
-   * @type {Promise<void>}
-   */
-  #painting = Promise.resolve();
-
   // The whole async pipeline: keyed on the render properties, re-run when one
   // changes — `page` and `fonts` among them, since either moves where the
   // pages break. Side effects live only in the callbacks below, which the
@@ -135,24 +136,33 @@ export class QuarioViewer extends LitElement {
       return { list, fonts };
     },
     onComplete: (result) => {
-      if (result === null || !this.isConnected) return;
+      if (result === null || !this.isConnected) return this.#landing.nothing();
       // The swap sizes every page before it settles, so the reader's place
       // is held; the paint it awaits is what `rendered` waits for.
       // The boundary takes the paint rather than a promise to report back
       // with: it reads which run this is here, while this run is still the
-      // newest one.
-      this.#painting = this.#landing.land(this.#stage.swap(result.list, result.fonts)).then(() => {
-        // A render that landed on the sheet takes the panel down: the panel
-        // says what is wrong with what the reader is looking at, and this is
-        // the moment that stops being true. A successful export is not that
-        // moment.
-        this.#failures.clear();
-        // After the paint, so the update the task queued has already run.
-        this.requestUpdate();
-        this.dispatchEvent(new CustomEvent("rendered"));
-      });
+      // newest one. The work after the paint rides inside it, so the run
+      // ends — and `renderComplete` settles — once `rendered` has fired.
+      // Bare, with no catch: the stage settles a page it cannot draw rather
+      // than rejecting, so the chain is reached whatever the pixels did.
+      this.#marks = result.list.marks;
+      // `void`: the boundary owns this promise now, and a caller awaiting the
+      // paint asks `renderComplete` rather than holding a field of its own.
+      void this.#landing.land(
+        this.#stage.swap(result.list, result.fonts).then(() => {
+          // A render that landed on the sheet takes the panel down: the panel
+          // says what is wrong with what the reader is looking at, and this is
+          // the moment that stops being true. A successful export is not that
+          // moment.
+          this.#failures.clear();
+          // After the paint, so the update the task queued has already run.
+          this.requestUpdate();
+          this.dispatchEvent(new CustomEvent("rendered"));
+        }),
+      );
     },
     onError: (error) => {
+      this.#landing.fail();
       if (!this.isConnected) return;
       this.#announce(error, this.#kindOf(error));
     },
@@ -179,6 +189,8 @@ export class QuarioViewer extends LitElement {
     this.filename = undefined;
     /** @type {"light" | "dark" | "auto" | undefined} */
     this.colorScheme = undefined;
+    /** @type {boolean | undefined} */
+    this.outline = undefined;
   }
 
   /**
@@ -188,19 +200,17 @@ export class QuarioViewer extends LitElement {
    * render still landed, so `true` promises the sheet is done changing, not
    * that every page carries pixels. It never rejects — a failed
    * render is handled, on the panel and through the error event — and like
-   * every outcome here it answers for the newest render only.
+   * every outcome here it answers for the newest render only: the one that
+   * is newest when it settles, so a run starting behind it is the one it
+   * then waits for.
+   *
+   * After `updateComplete`, because a property written just before the ask
+   * starts its run in the update this waits for.
    *
    * @returns {Promise<boolean>}
    */
   get renderComplete() {
-    return this.updateComplete.then(() =>
-      this.#task.status === TaskStatus.INITIAL
-        ? this.#landing.landed
-        : this.#task.taskComplete.then(
-            () => this.#painting.then(() => this.#landing.landed),
-            () => false,
-          ),
-    );
+    return this.updateComplete.then(() => this.#landing.complete);
   }
 
   /** @param {Map<string, unknown>} changed */
@@ -226,6 +236,7 @@ export class QuarioViewer extends LitElement {
       <div class="qv-viewer" aria-busy=${String(busy)}>
         <div class="qv-bar">
           ${progress(busy)}
+          ${this.#outlineControl()}
           ${zoomMenu({
             mode: this.#mode,
             percent: Math.round(this.#stage.percent()),
@@ -238,6 +249,7 @@ export class QuarioViewer extends LitElement {
         </div>
         <div class="qv-body">
           ${this.#failures.showing ? panel(this.#failures.showing, () => this.#dismiss()) : ""}
+          ${this.#outlineAside()}
           ${this.#stage.element}
         </div>
       </div>
@@ -341,6 +353,15 @@ export class QuarioViewer extends LitElement {
         let used = scheme(this.colorScheme);
         if (gate("colorScheme")) this.style.colorScheme = used;
       },
+      // The panel opens with the module: turning it on is what a reader would
+      // do next, and the toggle is there to close it.
+      (gate) => {
+        let on = outlined(this.outline);
+        if (gate("outline")) {
+          this.#outlined = on;
+          this.#outlineOpen = true;
+        }
+      },
     ]);
     if (moved) this.#landing.epoch++;
   }
@@ -404,6 +425,29 @@ export class QuarioViewer extends LitElement {
     this.requestUpdate();
   }
 
+  /** The bar's outline toggle, while the module is on. */
+  #outlineControl() {
+    if (!this.#outlined) return "";
+    return outlineToggle({ open: this.#outlineOpen, toggle: () => this.#toggleOutline() });
+  }
+
+  /** The outline panel, while the module is on and the reader has it open. */
+  #outlineAside() {
+    if (!this.#outlined || !this.#outlineOpen) return "";
+    return outlinePanel({
+      marks: this.#marks,
+      go: (mark) => this.#stage.reveal(mark.page, mark.y),
+    });
+  }
+
+  /** Open or close the outline panel. Chrome moves; nothing re-renders the
+   * report, and a fitted sheet follows its narrower or wider box through the
+   * observer `watch()` started. */
+  #toggleOutline() {
+    this.#outlineOpen = !this.#outlineOpen;
+    this.requestUpdate();
+  }
+
   /**
    * Report one failure, wherever it came from: the panel for the reader, the
    * event for the host. Failures that reach neither — a superseded render's,

package/lib/links.js

@@ -0,0 +1,221 @@
+/**
+ * The links on the sheet: one focusable region per linked run, over the very
+ * rectangle the painter drew it in.
+ *
+ * `@quario/layout` writes one text op per run, carrying the destination the
+ * engine admitted beside the `x`, `y`, `w` and `h` it drew at (`docs/adr/0085`),
+ * so the geometry is the list's own and nothing here re-measures. A run that
+ * wraps across two lines is two ops, which is two regions — the correct
+ * rendering rather than a degradation, as it is in the PDF.
+ *
+ * **A region is an element, because a painted one is not reachable.** ADR 0085
+ * makes focusability and Enter activation part of done: a link a pointer can
+ * reach and a keyboard cannot is an accessibility defect shipped as a feature.
+ * An `<a>` and a `<button>` carry both from the platform, so this module owns
+ * where they sit and nothing about how they are worked.
+ *
+ * The two destinations take the two elements. A URL leaves the page, which is
+ * what an anchor is for, and it opens in a tab of its own so a reader reading a
+ * report never loses it. An `href` naming a group's `label` moves the sheet,
+ * which is what a button is for — the same step the outline panel takes, and
+ * `reveal` is the one that takes it.
+ *
+ * **A destination the report does not hold is no region at all**, as it is in
+ * the PDF: a surface cannot invent a place, and a dead link is worse than plain
+ * text. The first instance wins a repeated label, which is what `SCHEMA.md` asks
+ * an author to declare labels that differ for.
+ *
+ * This is the viewer's own, and it is **not** the editor's hit box (ADR 0061,
+ * ADR 0085): it carries a destination and no path, and a link in the editor's
+ * preview stays deliberately unclickable, because the author is editing the
+ * document rather than reading it.
+ *
+ * The sheet carries elements only in the [reach](../../../CONTEXT.md#reach)
+ * (ADR 0043), and so does this: the regions are rebuilt when the band of pages
+ * under the reader moves, or when the scale does. Nothing here is markup — the
+ * text goes in as a property and the destination as an attribute — so the
+ * viewer still has no markup edge.
+ */
+
+import { css } from "lit";
+
+/** How far either side of the view the regions reach, in pages. The editor's
+ *  overlay uses the same one page: enough that a scroll landing between two
+ *  frames never shows a linked run with nothing over it. */
+let PAD = 1;
+
+export let LINKS = css`
+  /* Above the page canvases, which are appended after this layer on every
+     swap. Both are positioned, so one line settles the order. */
+  .qv-links {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+  }
+
+  /* A region shows nothing: the run under it is already painted. What it
+     carries is the pointer, the focus ring and the platform's activation. */
+  .qv-link {
+    position: absolute;
+    display: block;
+    padding: 0;
+    border: none;
+    background: transparent;
+    cursor: pointer;
+  }
+
+  .qv-link:focus-visible {
+    outline: 2px solid var(--_focus);
+    outline-offset: 1px;
+  }
+`;
+
+/**
+ * @typedef {{ title: string, page: number, x: number, y: number }} Mark
+ * @typedef {{ op: any, page: number }} Linked A linked text op, and its page.
+ */
+
+/**
+ * The linked runs on pages `first` through `last`, in document order. Scans
+ * those pages rather than the document, because this is asked on every swap and
+ * every scroll and the answer is bounded by the view.
+ *
+ * @param {any} list A layout list.
+ * @param {number} first
+ * @param {number} last
+ * @returns {Linked[]}
+ */
+export let linksOn = (list, first, last) => {
+  /** @type {Linked[]} */
+  let out = [];
+  for (let page = first; page <= last; page++)
+    for (let op of list.pages[page].ops) if (op.kind === "text" && op.href) out.push({ op, page });
+  return out;
+};
+
+/**
+ * The document's named destinations, by label. The first instance wins a
+ * repeated one, as a reader scrolling to the first match would — the rule the
+ * PDF target's annotations follow, and the one `SCHEMA.md` states.
+ *
+ * @param {readonly Mark[]} marks The list's own outline entries.
+ * @returns {Map<string, Mark>}
+ */
+export let destinations = (marks) => {
+  /** @type {Map<string, Mark>} */
+  let byLabel = new Map();
+  for (let mark of marks) if (!byLabel.has(mark.title)) byLabel.set(mark.title, mark);
+  return byLabel;
+};
+
+/**
+ * Where one `href` goes: out of the document, to a place in it, or nowhere.
+ *
+ * @param {string} href The destination the engine admitted.
+ * @param {Map<string, Mark>} byLabel
+ * @returns {{ url: string, mark: null } | { url: null, mark: Mark } | null}
+ */
+export let destination = (href, byLabel) => {
+  if (!href.startsWith("#")) return { url: href, mark: null };
+  let mark = byLabel.get(href.slice(1));
+  return mark ? { url: null, mark } : null;
+};
+
+/**
+ * The layer of regions over one sheet.
+ *
+ * @param {{ sheet: HTMLElement, paged: any, ratio: () => number,
+ *   view: () => { top: number, bottom: number },
+ *   reveal: (page: number, y: number) => void }} of What the stage owns: the
+ *   element the regions hang in, the sheet that places its pages, the scale on
+ *   screen, the band the reader is looking at, and the step a named destination
+ *   takes.
+ */
+export let overlay = ({ sheet, paged, ratio, view, reveal }) => {
+  let layer = document.createElement("div");
+  layer.className = "qv-links";
+  sheet.append(layer);
+
+  /** @type {any} */
+  let list = null;
+  /** @type {Map<string, Mark>} */
+  let byLabel = new Map();
+  /** What is standing: the band it was built for and the scale it was placed
+   *  at. A scroll inside one band and a repaint at one scale both cost the
+   *  compare and nothing else. */
+  let standing = "";
+
+  /** @type {(el: HTMLElement, op: any, page: number) => void} */
+  let place = (el, op, page) => {
+    let px = ratio();
+    el.style.left = op.x * px + "px";
+    el.style.top = paged.topOf(page) + op.y * px + "px";
+    el.style.width = op.w * px + "px";
+    el.style.height = op.h * px + "px";
+  };
+
+  /** One region, or nothing where the destination is not in the document. The
+   *  run's text is the region's name: the words are painted on the canvas,
+   *  which is nothing but an image to a screen reader. */
+  /** @type {(found: Linked) => HTMLElement | null} */
+  let region = ({ op, page }) => {
+    let where = destination(op.href, byLabel);
+    if (!where) return null;
+    let el = where.url === null ? step(where.mark) : anchor(where.url);
+    el.className = "qv-link";
+    el.setAttribute("aria-label", op.text);
+    place(el, op, page);
+    return el;
+  };
+
+  /** @type {(url: string) => HTMLElement} */
+  let anchor = (url) => {
+    let el = document.createElement("a");
+    el.href = url;
+    el.target = "_blank";
+    el.rel = "noopener noreferrer";
+    return el;
+  };
+
+  /** @type {(mark: Mark) => HTMLElement} */
+  let step = (mark) => {
+    let el = document.createElement("button");
+    el.type = "button";
+    el.addEventListener("click", () => reveal(mark.page, mark.y));
+    return el;
+  };
+
+  let update = () => {
+    let band = view();
+    let span = paged.pagesIn(band.top, band.bottom, PAD);
+    // Nothing on the sheet has nothing to lay a region over. The resize
+    // observer the stage starts reports once as it begins watching, which is
+    // before any list has arrived.
+    if (!span) return;
+    let wanted = span.first + ":" + span.last + ":" + ratio();
+    if (wanted === standing) return;
+    standing = wanted;
+    layer.replaceChildren();
+    for (let found of linksOn(list, span.first, span.last)) {
+      let el = region(found);
+      if (el) layer.append(el);
+    }
+  };
+
+  return {
+    /** Take the list the sheet is now showing, and build the regions under the
+     *  reader. A list with nothing to show leaves an empty layer. */
+    /** @type {(next: any) => void} */
+    swap(next) {
+      list = next;
+      byLabel = destinations(next.marks);
+      // The band and the scale may be the very ones the last list stood at,
+      // so the key is dropped rather than compared: what changed is the list.
+      standing = "";
+      layer.replaceChildren();
+      update();
+    },
+    /** Rebuild where the band or the scale has moved, and nowhere else. */
+    update,
+  };
+};

package/lib/menu.js

@@ -74,14 +74,12 @@ export let MENU = css`
     cursor: pointer;
   }
 
-  .qv-menuitem:hover {
-    background: var(--_hover);
-    color: var(--_icon-active);
-  }
-
-  /* Inset, so the ring stays inside the menu's own padding. */
-  .qv-menuitem:focus-visible {
-    outline: 2px solid var(--_focus);
+  /* A row's hover, active and focus treatment is \`button.js\`'s, shared with
+   every other <button> the viewer draws. The one difference is the ring's
+   side: inset, so it stays inside the menu's own padding. Narrower on
+   specificity rather than on where this sheet sits in \`static styles\` —
+   reordering that array must not silently put the ring back outside. */
+  .qv-viewer .qv-menuitem:focus-visible {
     outline-offset: -2px;
   }
 

package/lib/outline.js

@@ -0,0 +1,166 @@
+/**
+ * The outline panel: the report's group tree as a list of rows beside the
+ * sheet, each one a step to where that instance begins. The tree is the
+ * layout list's own `marks` — the entries the PDF target writes as bookmarks
+ * — so the panel derives it exactly as that target does, and an author
+ * declares nothing for it (`docs/adr/0044` for the icon, ADR 0047 for the
+ * chrome). A hollow instance is not a mark, so it is not a row.
+ *
+ * Optional: a host turns it on with the `outline` property, and the bar then
+ * carries one toggle. The reader opens and closes the panel; the property
+ * says only whether the module is there at all.
+ *
+ * A title goes in as a template value, never as markup — a group's key is
+ * report data — so this module has no markup edge to escape at (hard
+ * constraint 4).
+ */
+import { css, html } from "lit";
+import { button } from "./button.js";
+import { listTree } from "./icons.js";
+
+export let OUTLINE = css`
+  .qv-outline {
+    flex: none;
+    width: 220px;
+    min-width: 0;
+    overflow: auto;
+    padding: 6px;
+    background: var(--_bar);
+    border-right: 1px solid var(--_border);
+  }
+
+  .qv-outline ol {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* Each level steps in by one indent, written on the list rather than the
+   row, so a row's own box stays the full width the hover fills. */
+  .qv-outline ol ol {
+    padding-left: 12px;
+  }
+
+  .qv-outline-row {
+    display: block;
+    width: 100%;
+    padding: 4px 8px;
+    border: none;
+    border-radius: 5px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    text-align: left;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    cursor: pointer;
+  }
+
+  .qv-outline-empty {
+    margin: 0;
+    padding: 4px 8px;
+    color: var(--_icon);
+  }
+`;
+
+/**
+ * @typedef {{ title: string, depth: number, page: number, x: number, y: number }} Mark
+ * @typedef {{ mark: Mark, children: Node[] }} Node
+ */
+
+/**
+ * The marks as a tree: a mark is a child of the nearest mark before it at
+ * the depth above. Depth is the group's nesting, so the walk that emitted
+ * the marks in document order has already put every child after its parent.
+ *
+ * @param {readonly Mark[]} marks
+ * @returns {Node[]}
+ */
+export let tree = (marks) => {
+  /** @type {Node[]} */
+  let roots = [];
+  /** @type {Node[]} */
+  let open = [];
+  for (let mark of marks) {
+    /** @type {Node} */
+    let node = { mark, children: [] };
+    open.length = mark.depth;
+    (open[mark.depth - 1]?.children ?? roots).push(node);
+    open.push(node);
+  }
+  return roots;
+};
+
+/** @type {(event: HTMLElement) => HTMLElement[]} */
+let rows = (panel) => /** @type {HTMLElement[]} */ ([...panel.querySelectorAll(".qv-outline-row")]);
+
+/** @type {Record<string, (list: HTMLElement[], at: number) => HTMLElement>} */
+let MOVE = {
+  ArrowDown: (list, at) => list[Math.min(at + 1, list.length - 1)],
+  ArrowUp: (list, at) => list[Math.max(at - 1, 0)],
+  Home: (list) => list[0],
+  End: (list) => list[list.length - 1],
+};
+
+/**
+ * Arrow keys walk the rows in document order, whatever their depth; Tab
+ * leaves the panel as it left the bar. The platform owns activation.
+ *
+ * @param {KeyboardEvent} event
+ */
+let navigate = (event) => {
+  let move = MOVE[event.key];
+  if (!move) return;
+  event.preventDefault();
+  let list = rows(/** @type {HTMLElement} */ (event.currentTarget));
+  let at = list.indexOf(/** @type {HTMLElement} */ (event.target));
+  move(list, at).focus();
+};
+
+/**
+ * @param {Node[]} nodes
+ * @param {(mark: Mark) => void} go
+ * @returns {import('lit').TemplateResult}
+ */
+let branch = (nodes, go) => html`
+  <ol>
+    ${nodes.map(
+      (node) => html`
+        <li>
+          <button type="button" class="qv-outline-row" @click=${() => go(node.mark)}>
+            ${node.mark.title}
+          </button>
+          ${node.children.length ? branch(node.children, go) : ""}
+        </li>
+      `,
+    )}
+  </ol>
+`;
+
+/**
+ * The bar's toggle, drawn only while the module is on.
+ *
+ * @param {{ open: boolean, toggle: () => void }} state
+ */
+export let outlineToggle = ({ open, toggle }) => html`
+  <div class="qv-outline-toggle">
+    ${button({ title: open ? "Hide outline" : "Show outline", click: toggle, content: listTree })}
+  </div>
+`;
+
+/**
+ * The panel itself. A report with no groups has no tree, and the panel says
+ * so rather than standing empty.
+ *
+ * @param {{ marks: readonly Mark[], go: (mark: Mark) => void }} state
+ */
+export let outlinePanel = ({ marks, go }) => html`
+  <nav class="qv-outline" aria-label="Outline" @keydown=${navigate}>
+    ${
+      marks.length
+        ? branch(tree(marks), go)
+        : html`<p class="qv-outline-empty">This report has no groups.</p>`
+    }
+  </nav>
+`;

package/lib/stage.js

@@ -37,6 +37,12 @@
  * sees swapped under it — accepted, because the alternative is a second
  * element per page on a sheet ADR 0043 exists to keep cheap.
  *
+ * The linked runs get a **focusable region each**, in `links.js`, hung on the
+ * sheet over the rectangles the painter drew them in and rebuilt as the band
+ * under the reader or the scale moves. They follow the reach for the reason the
+ * pages do, and this file owns the two numbers they need: the band, and the
+ * scale on screen.
+ *
  * What the stage does not decide is which percentage to show: `fit()`
  * measures what would make one page span the width available, and `zoom.js`
  * owns the policy over that answer. `percent()` reports what is on screen, so
@@ -46,6 +52,7 @@
 import { css } from "lit";
 import { GUTTER, sheet } from "@quario/landing";
 import { PX_PER_POINT } from "@quario/layout";
+import { overlay } from "./links.js";
 
 // `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,
@@ -101,6 +108,7 @@ export let SURFACE = css`
  *   percent: () => number, scale: (percent: number) => void,
  *   resize: (geometry: PageBox) => void,
  *   swap: (list: any, fonts: any) => Promise<void>,
+ *   reveal: (page: number, y: number) => void,
  *   watch: (changed: () => void) => () => void }} Stage
  */
 
@@ -140,7 +148,42 @@ export let stage = () => {
    * the elements above stay this file's, because the CSS is the viewer's own
    * public surface. */
   let paged = sheet(scroll, sheetEl, ratio);
-  return {
+
+  /** The band of the sheet the reader is looking at, in the sheet's own CSS
+   *  pixels: the frame a page is placed in. The sheet starts one gutter down
+   *  the scroll extent, which is the same offset `reveal` scrolls through. */
+  let view = () => {
+    let top = scroll.scrollTop - GUTTER;
+    return { top, bottom: top + scroll.clientHeight };
+  };
+
+  /** The focusable regions over the linked runs. The viewer's own and not the
+   *  editor's, which is the whole of ADR 0085's "a link in the editor's
+   *  preview is not clickable". */
+  let links = overlay({
+    sheet: sheetEl,
+    paged,
+    ratio,
+    view,
+    reveal: (page, y) => api.reveal(page, y),
+  });
+
+  /** One region pass a frame, however many scrolls ask — the same coalescing
+   *  the sheet's own reach pass uses, and a separate listener because the two
+   *  answer different questions about the same scroll. */
+  let following = false;
+  let follow = () => {
+    if (following) return;
+    following = true;
+    requestAnimationFrame(() => {
+      following = false;
+      links.update();
+    });
+  };
+  scroll.addEventListener("scroll", follow);
+
+  /** @type {Stage} */
+  let api = {
     element: scroll,
 
     /**
@@ -174,7 +217,7 @@ export let stage = () => {
      * Only the reach is repainted, and only where the scale actually changed.
      */
     scale: (percent) => {
-      let held = paged.count() > 0 && {
+      let held = paged.width() !== null && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
         height: scroll.clientHeight,
@@ -189,6 +232,7 @@ export let stage = () => {
         scroll.scrollLeft = (held.left + held.width / 2) * ratioOf - held.width / 2;
       }
       void paged.repaint();
+      links.update();
     },
 
     /**
@@ -213,7 +257,7 @@ export let stage = () => {
     swap: async (next, faces) => {
       // Reading the offsets flushes layout, so only an actual reswap pays for
       // it: with no list standing there is nothing scrolled to preserve.
-      let held = paged.count() > 0 && {
+      let held = paged.width() !== null && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
       };
@@ -222,6 +266,24 @@ export let stage = () => {
         scroll.scrollTop = held.top;
         scroll.scrollLeft = held.left;
       }
+      // After the offsets go back, so the band the regions are built for is
+      // the one the reader is left looking at.
+      links.swap(next);
+    },
+
+    /**
+     * Scroll so that a point on a page sits at the top of the view: the
+     * outline's step to where an instance begins. The offset is the sheet's
+     * own — `topOf()` is where the sheet places that page, and the point
+     * scales as the page does — so this restates no stacking (ADR 0070).
+     * Horizontal stays where the reader left it.
+     *
+     * @param {number} page
+     * @param {number} y In points, down that page.
+     */
+    reveal: (page, y) => {
+      scroll.scrollTop = GUTTER + paged.topOf(page) + y * ratio();
+      paged.follow();
     },
 
     /**
@@ -235,10 +297,12 @@ export let stage = () => {
         // A resize that changes the fit repaints through `changed()`; one
         // that does not still moved the viewport the reach is measured in.
         paged.follow();
+        follow();
         changed();
       });
       observer.observe(scroll);
       return () => observer.disconnect();
     },
   };
+  return api;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/viewer",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Tiny, embeddable report viewer for quario. A custom element that pages on screen and exports what you hand it.",
   "keywords": [
     "csp",
@@ -40,19 +40,20 @@
     "access": "public"
   },
   "scripts": {
-    "check": "npm run size && npm test && npm run test:browser",
+    "check": "npm run size && npm test",
+    "coverage:check": "c8 report --src lib/ --temp-directory=../../coverage/tmp --reporter=text --check-coverage --100",
     "size": "size-limit",
-    "test": "npm run test:unit && npm run test:types",
+    "test": "npm run test:unit && npm run test:browser && npm run test:types && npm run coverage:check",
     "test:browser": "node test/browser/setup.js",
     "test:types": "tsc && attw --pack . --profile esm-only",
-    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "test:unit": "c8 --clean=false --src lib/ --reporter=none --temp-directory=../../coverage/tmp 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})\""
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/landing": "^0.3.0",
-    "@quario/layout": "^0.7.0",
+    "@quario/landing": "^0.3.1",
+    "@quario/layout": "^0.8.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
@@ -60,12 +61,12 @@
     "@cantoo/pdf-lib": "~2.9.1",
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
-    "quario": "^0.10.0",
+    "quario": "^0.11.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.10.0"
+    "quario": "^0.11.0"
   },
   "size-limit": [
     {
@@ -77,7 +78,7 @@
         "lit",
         "@lit/task"
       ],
-      "limit": "8.5 kB"
+      "limit": "9.5 kB"
     }
   ],
   "engines": {