@quario/html 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @quario/html
 
+## 0.11.0
+
+### Minor Changes
+
+- **A `capabilities` descriptor.** The target exports what it makes of each declaration the spec's support matrix names — `resolved`, `approximated`, `withdrawn` or `unread` — beside its factory, so a host can ask before it renders rather than reading the prose. It is keyed by the schema name an author writes (`valign`, `break`, `page.margin`, and `column.width` / `slot.width` where one word carries two declarations), hand-written and gated against that matrix. It carries no version of its own: the package that ships it is the version.
+- **`negative` and `zero` reach the markup edge.** The target stringifies through the engine's `format()`, so a cell declaring either presents there too: a negative in parentheses, a zero as a dash.
+- **A collapsed group does not draw its content.** An instance whose group declares `collapsed` renders as its header and footer, with the rows between them left out — a page has nowhere to put a row a reader could open. Aggregates are unchanged, so a footer still totals them.
+- **A run that links becomes an anchor.** A run carrying `href` is wrapped in an `<a>` inside its own span, so the style the run declared paints the link, and the URL is escaped at the one markup edge like every other interpolated value. A real anchor rather than a styled span, because keyboard reachability comes with it. The engine admitted the URL before it crossed, so this target decides nothing about it.
+- **The report header scales with the size it sits in.** The shipped stylesheet's `.q-item.q-report-header` rule is `font-size: 1.4em` rather than `14pt`. A document declaring `"size": 20` now renders its report header at 28pt where it rendered at 14pt, smaller than its own body. This is visible to every host page: an unstyled report's header is now 1.4× the host's own body type rather than a fixed 14pt, so a host whose body is not 10pt sees the headline move. A host rule on the class still wins, as before.
+
+### Patch Changes
+
+- **A cell's own `href` now links its text.** `href` sits on a cell as well as in a run's inline subset, but this target read it only off a run that declared a style of its own, so `{ style: { href } }` on the cell rendered the text with no anchor at all. It now asks the style the run wears rather than the one it declares, which is the cell's wherever the run is silent. A run declaring its own `href` still replaces the cell's rather than nesting inside it.
+- Updated dependencies
+  - quario@0.11.0
+
+## 0.10.0
+
+### Minor Changes
+
+- **A group's `break` names a position, and `break: "page"` is retired.** Its values are `"before"`, `"between"`, `"after"` and `"around"`. Write `break: "before"` where you wrote `break: "page"`. That is the whole of the migration, and it changes nothing the report produces.
+
+  The boundary between two consecutive instances always turns a page. `before` adds the leading edge of the run, so the first instance opens a page of its own. `between` adds neither edge, which keeps the first instance on the page the report header opened — the case the old vocabulary could not express, and the reason for the change. `after` adds the trailing edge, and `around` adds both. A trailing edge turns the page for what follows the run, so a report whose last band is that group reads `after` as `between` and `around` as `before`. A nested group takes its two edges from each instance of the group above it, rather than from the document. `"page"` said which unit a break used, where the four say where it falls; one set cannot say both and still read at a glance.
+
+  **`reset: "page"` turns no page of its own, and now needs a `break` beside it.** It says only that a new `page.number` / `page.total` sequence starts at this instance. A sequence owns whole pages, so `reset` requires `break` to be `"before"` or `"around"`. Any other `break`, and `reset` with no `break` at all, is a definition error the compile reports. Add `break: "before"` to a group that declares `reset` alone today.
+
+  The HTML target adds `q-break` to an instance whose leading edge turns, as before, and the new `q-break-after` to one whose trailing edge turns. `@quario/html/style.css` gains `.q-break-after { break-after: page }` beside the rule it already shipped for `.q-break`.
+
+  The Word target also stops losing a page break a table would swallow. A table carries no paragraph properties, so a break owed where one starts had nowhere to sit and reached the next paragraph instead, on the wrong page or on none. It now gets a paragraph of its own, the same carrier a section break already took.
+
+  The render-event stream states the two edges rather than the four positions. `group-start` carries `break` where a page turns before the instance, and the new `breakAfter` where one turns after it, so a target reads boundaries and never the position that asked for them.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.10.0
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -4,6 +4,18 @@
 definition to an HTML fragment with semantic tables, a stable class contract, and every
 interpolated value escaped.
 
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API](#api)
+- [Output contract](#output-contract)
+- [Unlicensed marking](#unlicensed-marking)
+- [Escaping](#escaping)
+- [Printing to PDF](#printing-to-pdf)
+- [Documentation](#documentation)
+- [License](#license)
+
 ## Install
 
 ```bash
@@ -109,8 +121,9 @@ change.
 | Emits                                              | For                                                                                                                                                                                                                                                                        |
 | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `<div class="q-report">`                           | The fragment's root, holding every band                                                                                                                                                                                                                                    |
+| `<a href>`                                         | A styled run that declares `href`, inside that run's own span. The URL is escaped like every other interpolated value, and the engine admitted it against the host's scheme allowlist before this target saw it                                                            |
 | `<div class="q-item q-<role>">`                    | Every item. Roles: `q-report-header`, `q-empty`, `q-group-header`, `q-detail`, `q-group-footer`, `q-report-footer`                                                                                                                                                         |
-| `<div class="q-group" data-group="name">`          | Each group instance, wrapping its header, nested content, and footer. Adds `q-break` when the group declares `break: "page"` or `reset: "page"`                                                                                                                            |
+| `<div class="q-group" data-group="name">`          | Each group instance, wrapping its header, nested content, and footer. Adds `q-break` where the group's `break` turns a page before the instance, and `q-break-after` where one turns after it                                                                              |
 | `<table class="q-table">`                          | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` around the total rows the walk emits. No `tfoot` when `total` is absent or every row of it is hidden. A spanning cell carries `colspan`                                                                |
 | `<div class="q-item q-image q-<role>">`            | Each image item, holding one `<img>`. Its `src` is a base64 `data:` URI of the event's bytes, and its `width`/`height` are the picture's natural size. `fit` sets `max-width:100%` or `width:100%` on it, paired with `height:auto`. The target escapes the rendered `alt` |
 | `<div class="q-columns" style="column-count:<n>">` | The content between a node's own bands when it declares `columns`. On the root, that is the body between report header and footer. On a group, it is inside that instance's `q-group`                                                                                      |
@@ -124,7 +137,7 @@ Security Policy needs `img-src data:` (see
 Style declarations map to inline CSS (`bold` → `font-weight:bold` or `font-weight:normal`, `size` → `font-size:<n>pt`,
 `family: "mono"` → `font-family:monospace`, …). Occupy-a-line and newline-as-break are **not** inline: they hang off
 `.q-item` and `.q-table th, td` in [`@quario/html/style.css`](#the-reference-stylesheet), the same way `.q-break`
-honors `break: "page"`. The class is the hook. The rule is a reference default a host overrides on source order.
+honors a leading page break. The class is the hook. The rule is a reference default a host overrides on source order.
 A fragment without that sheet still carries the classes and the text, including newlines. It does not occupy or
 break until some stylesheet says so. This target supplies no defaults in the markup: no weight or size per band
 role, no leading, no padding, no spacing between bands, no borders. An inline `style` attribute would beat yours
@@ -133,7 +146,7 @@ instead. The PDF and XLSX targets carry theirs built in, because their consumers
 row set still emits the table, its header, and an empty `<tbody>`. A hidden table cell keeps its `<td>`, empty.
 
 This target paginates nothing: it ignores schema page bands (page furniture belongs to your print CSS)
-and maps `break: "page"` and `reset: "page"` to the `q-break` class. Page columns are laid out:
+and maps each edge a group's `break` turns to its own class. Page columns are laid out:
 a node declaring `columns` wraps the content between its own bands in the `q-columns` container
 above, and the browser flows it.
 
@@ -172,8 +185,8 @@ Host CSS targets these classes:
    `.q-item { min-height: 1lh; white-space: pre-line }` occupies a line and breaks on newlines,
    `.q-group { break-inside: avoid }` keeps a group header with its rows,
    `.q-table tr { break-inside: avoid }` keeps a row whole,
-   `.q-break { break-before: page }` honors the schema's own break hint, and `thead` repeats per
-   printed page. Yours adds the page geometry in `@page`, which only you can decide.
+   `.q-break { break-before: page }` and `.q-break-after { break-after: page }` honor the schema's own
+   break hints, and `thead` repeats per printed page. Yours adds the page geometry in `@page`, which only you can decide.
 3. Print with a headless browser (`page.pdf()` in Playwright or Puppeteer, page numbers via the
    footer template) or a Paged-CSS engine (WeasyPrint or Prince, with page numbers via `@page` margin
    boxes).

package/lib/index.d.ts

@@ -29,3 +29,27 @@ export interface HtmlOptions {
  * described in SCHEMA.md ("The HTML target").
  */
 export function html(options?: HtmlOptions): Target<"html", Promise<string>>;
+
+/** What a target makes of a declaration: CONTEXT.md's fate vocabulary. */
+export type Fate = "resolved" | "approximated" | "withdrawn" | "unread";
+
+/**
+ * What this target makes of each declaration SCHEMA.md's support matrix
+ * names. Hand-written and gated against that matrix rather than generated
+ * from it. It carries no version of its own: the package that ships it is the
+ * version.
+ *
+ * Keyed by the schema name an author writes — `valign`, `break`, `page.margin`
+ * — so a host, a `required` marking and a problem message share one
+ * vocabulary. Two matrix rows share the bare word `width`, so each is
+ * qualified by what carries it: `column.width` and `slot.width`.
+ *
+ * It covers the declarations every official target states one fate for. An
+ * absent key means the matrix states no single fate for that row — a row that
+ * summarises more than one declaration, or that describes a behaviour — never
+ * that this target has no answer.
+ */
+export const capabilities: {
+  readonly target: "html";
+  readonly declarations: Readonly<Record<string, Fate>>;
+};

package/lib/index.js

@@ -9,7 +9,17 @@
  * never carries markup-escaped text.
  */
 
-import { display, format, hostOptions, isReportBand, styledRuns, text, walk } from "quario";
+import {
+  collapse,
+  display,
+  format,
+  hostOptions,
+  isReportBand,
+  splits,
+  styledRuns,
+  text,
+  walk,
+} from "quario";
 
 /** @type {Record<string, string>} */
 let ESC = {
@@ -24,9 +34,8 @@ let esc = (value) => display(value).replace(/[&<>"']/g, (char) => ESC[char]);
 
 // Join a cell's tokens to HTML: literal template text is author-controlled
 // markup and passes verbatim; every interpolated value is escaped, no
-// exceptions. The engine's own `text` join is the other one -- display text,
-// where a literal is words rather than markup -- and an attribute value takes
-// that one, escaped whole.
+// exceptions. An attribute value takes the engine's `text` join instead,
+// escaped whole.
 /** @type {(tokens: any[], style: any, intl: any) => string} */
 let joined = (tokens, style, intl) => {
   let out = "";
@@ -41,32 +50,42 @@ let shown = (value, style, intl) => {
 };
 
 // One styled run: a `<span>` carrying that run's whole resolved inline style,
-// rather than a difference against the cell's -- the engine already composed
-// the two, and a delta would have this target merge them back. An unstyled run
-// stays bare, so a cell with no authored runs emits exactly the markup it
-// always did. The span's own CSS is `esc()`d like any other attribute value.
+// not a difference against the cell's -- the engine already composed the two.
+// An unstyled run stays bare.
 /** @type {(styled: { style: any, tokens: any[] }, style: any, intl: any, map: any) => string} */
-let piece = (styled, style, intl, map) => {
-  let body = joined(styled.tokens, styled.style ?? style, intl);
+let styledRun = (styled, style, intl, map) => {
+  let worn = styled.style ?? style;
+  let body = linked(joined(styled.tokens, worn, intl), worn);
   if (!styled.style) return body;
   let inline = css(styled.style, map);
   return inline ? '<span style="' + esc(inline) + '">' + body + "</span>" : body;
 };
 
+// A run that carries an `href` is wrapped in an anchor, inside its own span so
+// the style the run declared paints the link as well. The style asked is the
+// one the run wears rather than the one it declares, because `href` sits on a
+// cell as well as on a run (SCHEMA.md, "Style declarations") and a cell's own
+// links every run that declared no other. The engine admitted the
+// URL against the host's scheme allowlist before it crossed (docs/adr/0085);
+// this target escapes it like every other interpolated value and decides
+// nothing about it. An `<a>` is keyboard-reachable for nothing, which is why
+// this is a real anchor rather than a styled span with a click handler.
+/** @type {(body: string, style: any) => string} */
+let linked = (body, style) =>
+  style?.href ? '<a href="' + esc(style.href) + '">' + body + "</a>" : body;
+
 // A cell's markup: its styled runs in order. The grouping is the engine's
-// `styledRuns`, so this target cannot drift from the others (SCHEMA.md, "Event
-// stream").
+// `styledRuns`, so this target cannot drift from the others.
 /** @type {(map: any) => (tokens: any[], style?: any, intl?: any) => string} */
 let cellMarkup = (map) => (tokens, style, intl) => {
   let out = "";
-  for (let styled of styledRuns(tokens)) out += piece(styled, style, intl, map);
+  for (let styled of styledRuns(tokens)) out += styledRun(styled, style, intl, map);
   return out;
 };
 
-// base64 for an image's `data:` URI, without Buffer: this package runs in Node
-// and in ES2024 browsers off the same `lib/`, and `btoa` is a standard global
-// in both. The walk is chunked because `fromCharCode(...bytes)` spreads one
-// argument per byte, which a real image exhausts.
+// base64 for an image's `data:` URI, without Buffer: the same `lib/` runs in
+// Node and in browsers, and `btoa` is standard in both. Chunked because
+// `fromCharCode(...bytes)` spreads one argument per byte.
 let CHUNK = 0x8000;
 /** @type {(bytes: Uint8Array) => string} */
 let base64 = (bytes) => {
@@ -91,25 +110,22 @@ let NAMEABLE = /^[A-Za-z0-9 _-]+$/;
 let UNSAFE = /[;}]/;
 /** @type {(value: any) => boolean} */
 let isHex = (value) => typeof value === "string" && HEX.test(value);
-let ALIGNMENTS = ["left", "center", "right"];
 // A slot item's `valign` and `align` as grid placement (see `placed`); the
 // vertical vocabulary is these keys, so the three readers of it agree.
 /** @type {Record<string, string>} */
 let ALIGN_CONTENT = { top: "start", middle: "center", bottom: "end" };
 /** @type {Record<string, string>} */
 let JUSTIFY_ITEMS = { left: "start", center: "center", right: "end" };
-let VALIGNMENTS = Object.keys(ALIGN_CONTENT);
 
 // A group instance's own bands. They sit outside a columned container only when
 // that instance is the node which declared the count — an inner instance's are
 // content like anything else. The report's own bands are the engine's to name.
 let OWN = new Set(["group-header", "group-footer"]);
 // A host font mapping (`html({ fonts })`), lowercased once so lookup matches
-// `pdf({ fonts })`'s. Validated here rather than at render, because a
-// malformed one is host configuration and belongs where the host wrote it --
-// the value itself is trusted and emitted verbatim, as that target's font
-// bytes are. `Error` and the `options.fonts.<name>:` prefix are that target's
-// too: one option, one message shape.
+// `pdf({ fonts })`'s. Validated here rather than at render: a malformed one is
+// host configuration and belongs where the host wrote it. The value itself is
+// trusted and emitted verbatim. `Error` and the `options.fonts.<name>:` prefix
+// match the pdf target's: one option, one message shape.
 /** @type {(path: string, value: any) => string} */
 let cssValue = (path, value) => {
   if (typeof value !== "string" || !value)
@@ -144,11 +160,10 @@ let mapping = (fonts) => {
   );
 };
 
-// Resolve a declared family name against the table the factory built -- the
-// host's mapping laid over the three generics -- then the name itself. A name
-// that is not nameable as it stands resolves to nothing rather than to a
-// rewritten near-miss, so the element falls through to the layer below instead
-// of naming a face that cannot exist (docs/adr/0034).
+// Resolve a declared family name against the table the factory built, then
+// the name itself. A name that is not nameable as it stands resolves to
+// nothing rather than a rewritten near-miss, so the element falls through to
+// the layer below (docs/adr/0034).
 /** @type {(map: Record<string, string>, value: string) => string} */
 let named = (map, value) => {
   // Own-key lookup: `constructor` must not resolve an inherited member.
@@ -156,28 +171,29 @@ let named = (map, value) => {
   if (Object.hasOwn(map, key)) return map[key];
   return NAMEABLE.test(value) ? "'" + value + "'" : "";
 };
-// Exact true/false only: a computed value of the wrong shape contributes
-// nothing, same as omit (SCHEMA.md, Style declarations).
+// A declared flag is `true` or `false`: the engine drops every other shape
+// before a target sees it (SCHEMA.md, "Style declarations"), so a target maps
+// the vocabulary rather than checking it a second time.
 /** @type {(on: string, off: string) => (value: any) => string} */
-let flag = (on, off) => (value) => (value === true ? on : value === false ? off : "");
+let flag = (on, off) => (value) => (value ? on : off);
 /** @type {Record<string, (value: any, map: Record<string, string>) => string>} */
 let CSS = {
+  // A family is the one declaration whose value a host may name, so the map
+  // may still answer with nothing; the value itself is a non-empty string.
   family: (value, map) => {
-    if (typeof value !== "string" || !value) return "";
     let name = named(map, value);
     return name ? "font-family:" + name : "";
   },
-  size: (value) => (Number.isFinite(value) && value > 0 ? "font-size:" + value + "pt" : ""),
+  size: (value) => "font-size:" + value + "pt",
   bold: flag("font-weight:bold", "font-weight:normal"),
   italic: flag("font-style:italic", "font-style:normal"),
-  color: (value) => (isHex(value) ? "color:" + value : ""),
-  background: (value) => (isHex(value) ? "background-color:" + value : ""),
-  align: (value) => (ALIGNMENTS.includes(value) ? "text-align:" + value : ""),
+  color: (value) => "color:" + value,
+  background: (value) => "background-color:" + value,
+  align: (value) => "text-align:" + value,
   // The table reading, on a `<tr>` or a cell: the browser's own sheet gives
-  // cells `vertical-align: inherit`, so a row's reaches them like `bold`
-  // does. A slot item's is placement, and `placed` below lifts the name out
-  // before this map sees it.
-  valign: (value) => (VALIGNMENTS.includes(value) ? "vertical-align:" + value : ""),
+  // cells `vertical-align: inherit`, so a row's reaches them like `bold` does.
+  // `placed` below lifts the name out before this map sees a slot item's.
+  valign: (value) => "vertical-align:" + value,
   // The text itself is untouched, so selection and screen readers get what
   // the author wrote; only its rendering is capitalised.
   uppercase: flag("text-transform:uppercase", "text-transform:none"),
@@ -185,14 +201,12 @@ let CSS = {
 
 let SIDES = ["Top", "Right", "Bottom", "Left"];
 let LINES = ["solid", "dashed", "dotted"];
-/** @type {(value: any) => boolean} */
-let isPad = (value) => Number.isFinite(value) && value >= 0;
 for (let side of SIDES) {
   let edge = side.toLowerCase();
-  CSS["padding" + side] = (value) => (isPad(value) ? "padding-" + edge + ":" + value + "pt" : "");
+  CSS["padding" + side] = (value) => "padding-" + edge + ":" + value + "pt";
 }
-CSS.spaceBefore = (value) => (isPad(value) ? "margin-top:" + value + "pt" : "");
-CSS.spaceAfter = (value) => (isPad(value) ? "margin-bottom:" + value + "pt" : "");
+CSS.spaceBefore = (value) => "margin-top:" + value + "pt";
+CSS.spaceAfter = (value) => "margin-bottom:" + value + "pt";
 
 /** @type {(width: any) => boolean} */
 let isStroke = (width) => Number.isFinite(width) && width > 0;
@@ -219,11 +233,12 @@ let decoLine = (style) => {
   return parts;
 };
 
+// Only called where one of the two names is declared, so a style that draws
+// neither line is a style that turned one off.
 /** @type {(style: any) => string} */
 let decoration = (style) => {
   let parts = decoLine(style);
-  if (parts.length) return "text-decoration:" + parts.join(" ");
-  return style.underline === false || style.strikethrough === false ? "text-decoration:none" : "";
+  return parts.length ? "text-decoration:" + parts.join(" ") : "text-decoration:none";
 };
 
 /** @type {(name: string) => boolean} */
@@ -282,17 +297,15 @@ let css = (style, map) => {
 };
 
 // Compose a resolved style into one escaped inline style attribute. `own` is
-// this target's own structural CSS, which goes first and always emits: page
+// this target's structural CSS, which goes first and always emits: page
 // columns and splits are placement, not the visual defaults this target
-// refuses to supply, so they ride the same escaped attribute path as
-// everything else rather than a second one (CLAUDE.md, the markup edge).
+// refuses to supply.
 /** @type {(fonts: any) => { attr: (event: { style?: any }, own?: string) => string, map: Record<string, string> }} */
 let styling = (fonts) => {
   // The spread is the precedence the option promises: a host mapping is
-  // consulted before the three generics, and may replace one. `mapping`
-  // lowercased its keys to match the ones already here. The table is handed
-  // back beside the attribute writer, because a styled run's span resolves a
-  // `family` against the same one.
+  // consulted before the three generics, and may replace one. Handed back
+  // beside the attribute writer, because a styled run's span resolves a
+  // `family` against the same table.
   let map = { ...FAMILY, ...mapping(fonts) };
   return {
     map,
@@ -304,25 +317,21 @@ let styling = (fonts) => {
 };
 
 // One slot's wrapper. An authored share is that width; a width-less slot
-// divides what the sized ones leave, exactly as a width-less column does.
+// divides what the sized ones leave, as a width-less column does.
 // `display:grid` is what gives a slot's box the split's height rather than its
-// own content's: the wrapper already stretches as a flex item, and a grid makes
-// its single child fill it in both axes. It belongs here and not on the
-// fragment, because a slot's item is the same `q-item` div it would be
-// anywhere else -- nothing about an item's markup depends on where it sits.
+// own content's. It belongs here and not on the fragment: a slot's item is the
+// same `q-item` div it would be anywhere else.
 /** @type {(slot: { width?: number } | undefined) => string} */
 let slotAttr = (slot) =>
   ' style="' +
   esc("display:grid;" + (slot && slot.width != null ? "width:" + slot.width + "%" : "flex:1")) +
   '"';
 
-// A slot item's `valign`. The slot wrapper's grid stretches the item to the
-// split's height, so the item is the box and its content has to move inside
-// it: the item becomes a grid of its own and `align-content` places the
-// content. Not on the wrapper -- `align-items` there would shrink the item
-// back to its content and reopen the gap the grid closed. Lifted out of the
-// style so the cell mapping (`vertical-align`) does not also emit on a div.
-// The result is what `styleAttr` takes: a style and the structural prefix.
+// A slot item's `valign`. The wrapper's grid stretches the item to the split's
+// height, so the item is the box: it becomes a grid of its own and
+// `align-content` places the content. Not on the wrapper -- `align-items`
+// there would shrink the item back and reopen the gap the grid closed. Lifted
+// out of the style so the cell mapping (`vertical-align`) does not also emit.
 /** @type {(event: { style?: any }) => { style?: any, own: string }} */
 let placed = (event) => {
   let valign = event.style?.valign;
@@ -339,9 +348,9 @@ let justified = (own, style) =>
     ? own + ";justify-items:" + JUSTIFY_ITEMS[style.align]
     : own;
 
-// The identity attribute, escaped like every other generated value at this
-// edge. `mark` is the factory's verdict: a render without `paths` maps every
-// event to "" through the same function rather than re-deciding per call site.
+// The identity attribute. `mark` is the factory's verdict: a render without
+// `paths` maps every event to "" through the same function rather than
+// re-deciding per call site.
 /** @type {(event: { path?: string }) => string} */
 let pathAttr = ({ path }) => (path ? ' data-q-path="' + esc(path) + '"' : "");
 /** @type {(list: any[], tag: string, attrs: (event: any) => string, intl: any, markup: any) => string} */
@@ -365,9 +374,7 @@ let cells = (list, tag, attrs, intl, markup) =>
  *
  * `paths` opts the fragment into identity: each element whose event carries a
  * schema `path` gains `data-q-path`, so a consumer can map rendered output
- * back to the definition behind it — the editor's selection seam. Off by
- * default, because the attribute is weight every plain display pays for
- * nothing.
+ * back to the definition behind it. Off by default.
  *
  * `fonts` is this target's font mapping: a declared `family` name to a CSS
  * value, so a host says what the name means on this page. Malformed values
@@ -391,15 +398,12 @@ export function html(options) {
   // The pair every cell carries, bound once rather than threaded as two.
   /** @type {(cell: any) => string} */
   // A span covers several columns; `colspan` is what that is on this surface.
-  // Escaped like every other attribute value this target writes, though the
-  // engine has already vouched the span is a positive integer.
   /** @type {(cell: any) => string} */
   let attrs = (cell) =>
     (cell.span > 1 ? ' colspan="' + esc(cell.span) + '"' : "") + styleAttr(cell) + mark(cell);
   // One table row: the row style on the `<tr>`, from which it inherits into
   // the cells, `valign` included. The box is not among these names — a `<tr>`
-  // could not honour one, and the engine has already resolved that half onto
-  // the cells, where it arrives as ordinary inline CSS.
+  // could not honour one, and the engine resolved that half onto the cells.
   /** @type {(event: any, list: any[], tag: string, intl: any) => string} */
   let tr = (event, list, tag, intl) =>
     "<tr" + styleAttr(event) + ">" + cells(list, tag, attrs, intl, markup) + "</tr>";
@@ -409,8 +413,7 @@ export function html(options) {
       let out = "";
       // The finished `src` of every image this render has already encoded,
       // keyed by the array the source expression yielded. A logo down a
-      // thousand rows is one base64 walk rather than a thousand, and the map
-      // goes with the render — nothing here outlives it.
+      // thousand rows is one base64 walk. Nothing here outlives the render.
       /** @type {Map<Uint8Array, string>} */
       let sources = new Map();
       // Whether a `total-row` already opened `<tfoot>` — markup
@@ -422,35 +425,16 @@ export function html(options) {
       let rooted = false;
       // The page columns a node declared: its `count`, the `owner` depth that
       // declared it (-1 for the report root), and whether the container is
-      // emitted and still to be closed. Null when no node owes one. Never more
-      // than one, because nesting a columned region is a definition error.
+      // emitted and still to be closed. Never more than one, because nesting a
+      // columned region is a definition error.
       /** @type {{ count: number, owner: number, open: boolean } | null} */
       let region = null;
       // How many group instances are open, so the declaring node's own bands
-      // can be told from the content they bracket: a `group-header` or
-      // `group-footer` belongs to the innermost instance, which is the node
-      // that may own the region. Taken from each event rather than counted, so
-      // there is one spelling of a depth the stream already carries.
+      // can be told from the content they bracket. Taken from each event
+      // rather than counted, so one spelling of a depth the stream carries.
       let depth = 0;
-      // The split being filled, if any: the slot geometry the bracket carried
-      // and how many slots have been placed. Splits never nest, so one is
-      // enough. Null whenever the walk is not inside a bracket.
-      /** @type {{ slots: any[], at: number } | null} */
-      let split = null;
       /** @type {{ locale?: string, currency?: string, timeZone?: string } | null} */
       let intl = null;
-      // Place one item's markup: inside a bracket it goes in the next slot,
-      // and everywhere else it is a band item like any other.
-      /** @type {(event: any, fragment: string) => void} */
-      let emit = (event, fragment) => {
-        if (!split) {
-          content(event);
-          out += fragment;
-          return;
-        }
-        out +=
-          '<div class="q-slot"' + slotAttr(split.slots[split.at++]) + ">" + fragment + "</div>";
-      };
       // Does this event stay full-width, outside the columns? The declaring
       // node's own bands do.
       /** @type {(event: any) => boolean} */
@@ -483,14 +467,61 @@ export function html(options) {
         if (fullWidth(event)) close();
         else openColumns();
       };
+      // One item's or picture's own markup, by event type: the stable
+      // `q-item q-<role>` classes are the whole class attribute (print CSS
+      // targets the band-role class for styling and breaks), and a picture is
+      // an item container of its own holding one `<img>`.
+      /** @type {Record<string, (event: any) => string>} */
+      let fragment = {
+        item: (event) => {
+          let slot = placed(event);
+          return (
+            '<div class="q-item q-' +
+            event.role +
+            '"' +
+            styleAttr(slot, slot.own) +
+            mark(event) +
+            ">" +
+            markup(event.tokens, event.style, intl) +
+            "</div>"
+          );
+        },
+        image: (event) => {
+          let slot = placed(event);
+          let source = sources.get(event.bytes);
+          if (source === undefined)
+            sources.set(
+              event.bytes,
+              (source = esc("data:image/" + event.format + ";base64," + base64(event.bytes))),
+            );
+          return (
+            '<div class="q-item q-image q-' +
+            event.role +
+            '"' +
+            styleAttr(slot, justified(slot.own, event.style)) +
+            mark(event) +
+            '><img src="' +
+            source +
+            '" width="' +
+            esc(event.width) +
+            '" height="' +
+            esc(event.height) +
+            '" alt="' +
+            esc(text(event.alt || [])) +
+            '" style="' +
+            (event.fit === "width" ? "" : "max-") +
+            'width:100%;height:auto">' +
+            "</div>"
+          );
+        },
+      };
       // Hidden items never reach the stream and a hidden cell arrives with no
       // tokens, so no visibility checks are needed in any handler below.
-      await walk(stream(data), {
+      await walk(collapse(splits(stream(data))), {
         // Nothing unless the render is unlicensed — then the fragment opens
-        // with the marking badge (LICENSE section 6): the engine's wording in
-        // this target's element, escaped like every other value crossing this
-        // edge, so the badge stays childless whatever stream a host compiles
-        // against.
+        // with the marking badge: the engine's wording in this target's
+        // element, escaped, so the badge stays childless whatever stream a
+        // host compiles against.
         "report-start": (event) => {
           intl = {
             locale: event.locale,
@@ -500,12 +531,10 @@ export function html(options) {
           if (event.marking) out += '<div class="q-unlicensed">' + esc(event.marking) + "</div>";
           if (event.margin != null)
             out += "<style>@page{margin:" + esc(event.margin) + "pt}</style>";
-          // The report root. Always emitted, because the fragment otherwise
-          // has no element for a document-wide declaration to be inherited
-          // from, and the shipped stylesheet's own baseline now hangs off it.
-          // The marking stays outside: inside, an author's `style` would
-          // reach it, and a marking an author can shrink is one ADR 0002
-          // does not allow.
+          // The report root. Always emitted: the fragment otherwise has no
+          // element for a document-wide declaration to inherit from, and the
+          // shipped stylesheet's baseline hangs off it. The marking stays
+          // outside, where an author's `style` cannot reach it (ADR 0002).
           out += '<div class="q-report"' + styleAttr(event) + ">";
           rooted = true;
           if (event.columns) region = { count: event.columns, owner: -1, open: false };
@@ -513,90 +542,54 @@ export function html(options) {
         // The stable `q-item q-<role>` classes are the whole class attribute;
         // print CSS targets the band-role class for styling and breaks.
         item: (event) => {
-          let slot = placed(event);
-          emit(
-            event,
-            '<div class="q-item q-' +
-              event.role +
-              '"' +
-              styleAttr(slot, slot.own) +
-              mark(event) +
-              ">" +
-              markup(event.tokens, event.style, intl) +
-              "</div>",
-          );
+          content(event);
+          out += fragment.item(event);
         },
         // A split places its slots across the content width instead of down
-        // the band. The slot items inside keep their ordinary markup, so a
-        // consumer of this fragment reads the same item container wherever it
-        // sits; only the wrapper around it is new.
-        "split-start": (event) => {
+        // the band. The slot items keep their ordinary markup; only the
+        // wrapper around them is new.
+        split: (event) => {
           content(event);
           out +=
             '<div class="q-split q-' + event.role + '"' + styleAttr(event, "display:flex") + ">";
-          split = { slots: event.slots, at: 0 };
-        },
-        "split-end": () => {
-          split = null;
+          event.items.forEach((/** @type {any} */ slot, /** @type {number} */ at) => {
+            out +=
+              '<div class="q-slot"' +
+              slotAttr(event.slots[at]) +
+              ">" +
+              fragment[slot.type](slot) +
+              "</div>";
+          });
           out += "</div>";
         },
         // An image is an item container of its own holding one `<img>`: the
         // band-role class joins `q-item q-image`, `align`/`background` dress
-        // the container, and `fit` sizes the picture inside it. The `src` is
-        // this target's own base64 of the event's bytes under the MIME type
-        // the engine already sniffed -- generated, but emitted through the
-        // same escaped attribute path as everything else rather than a second
-        // one, and escaped when it is encoded rather than per occurrence. `alt` is report data, so it is the display-text join escaped,
-        // never the markup-passing join a cell body gets; an image without one
-        // carries `alt=""`, the decorative-image convention.
+        // the container, and `fit` sizes the picture inside it. `alt` is report
+        // data, so it takes the display-text join escaped, never the
+        // markup-passing join a cell body gets; without one it is `alt=""`.
         //
-        // `width`/`height` are the event's natural size, which the engine has
-        // already read and vouched for, so a picture reserves its aspect ratio
-        // before it decodes rather than reflowing the page around it. The pair
-        // is a presentational hint, not a ratio on its own, which is why the
-        // `fit` style carries `height:auto`: without it the stated height is a
-        // used height and a picture capped narrower than its file renders
-        // squashed. SCHEMA.md, "The HTML target", states that normatively.
+        // `width`/`height` are the event's natural size, so a picture reserves
+        // its aspect ratio before it decodes. The pair is a presentational
+        // hint rather than a ratio, which is why the `fit` style carries
+        // `height:auto`: without it a picture capped narrower than its file
+        // renders squashed.
         image: (event) => {
-          let slot = placed(event);
-          let source = sources.get(event.bytes);
-          if (source === undefined)
-            sources.set(
-              event.bytes,
-              (source = esc("data:image/" + event.format + ";base64," + base64(event.bytes))),
-            );
-          emit(
-            event,
-            '<div class="q-item q-image q-' +
-              event.role +
-              '"' +
-              styleAttr(slot, justified(slot.own, event.style)) +
-              mark(event) +
-              '><img src="' +
-              source +
-              '" width="' +
-              esc(event.width) +
-              '" height="' +
-              esc(event.height) +
-              '" alt="' +
-              esc(text(event.alt || [])) +
-              '" style="' +
-              (event.fit === "width" ? "" : "max-") +
-              'width:100%;height:auto">' +
-              "</div>",
-          );
+          content(event);
+          out += fragment.image(event);
         },
-        // Each group instance is wrapped in a `q-group` container carrying
-        // the group name, so print CSS can keep a header with its rows
-        // (`break-inside`) or force a break per group (`break-before`). A
-        // declared `break: 'page'` or `reset: 'page'` adds the `q-break` class
-        // for print CSS to map (`.q-break { break-before: page }`).
+        // Each group instance is wrapped in a `q-group` container carrying the
+        // group name, so print CSS can keep a header with its rows or force a
+        // break per group. The stream resolved the group's `break` position
+        // into this instance's two edges, each mapping to its class. Both ride
+        // the opening event: the container is written here and a class cannot
+        // be added to it later.
         "group-start": (event) => {
           content(event);
           depth = event.depth + 1;
           out +=
             '<div class="q-group' +
-            (event.break || event.reset ? " q-break" : "") +
+            (event.break ? " q-break" : "") +
+            (event.breakAfter ? " q-break-after" : "") +
             '"' +
             mark(event) +
             ' data-group="' +
@@ -659,3 +652,53 @@ export function html(options) {
     },
   };
 }
+
+/**
+ * What this target makes of each declaration the support matrix names: one of
+ * the [fates](../../../CONTEXT.md#declaration-and-resolution) — `resolved`,
+ * `approximated`, `withdrawn` or `unread` — so a host can ask before it
+ * renders rather than reading the prose.
+ *
+ * **Hand-written, and gated rather than generated.** SCHEMA.md's matrix is the
+ * description a person maintains and this is the data a host reads; the repo's
+ * `test/capabilities.test.js` holds the two equal, which is the same bargain
+ * ADR 0014 makes for the band-role table. It carries no version of its own:
+ * the package that ships it is the version, and a second copy could only drift
+ * from it.
+ *
+ * Keyed by the **schema name** an author writes, so a host, a `required`
+ * marking and a problem message all index by one vocabulary. Two rows share
+ * the bare word `width`, so each is qualified by what carries it.
+ *
+ * It covers the declarations every official target states one fate for. A
+ * matrix row that summarises more than one declaration, or that describes a
+ * behaviour rather than a declaration, states no single fate and is absent
+ * here — an absent key means the spec does not answer, never that this target
+ * has no answer.
+ */
+export const capabilities = Object.freeze({
+  target: "html",
+  declarations: Object.freeze({
+    "page.header": "unread",
+    "page.footer": "unread",
+    break: "approximated",
+    reset: "withdrawn",
+    "page.margin": "resolved",
+    "header.height": "withdrawn",
+    groups: "resolved",
+    label: "withdrawn",
+    collapsed: "resolved",
+    "column.width": "approximated",
+    "slot.width": "resolved",
+    span: "resolved",
+    uppercase: "resolved",
+    href: "resolved",
+    spaceBefore: "resolved",
+    spaceAfter: "resolved",
+    format: "resolved",
+    family: "resolved",
+    valign: "resolved",
+    runs: "resolved",
+    alt: "resolved",
+  }),
+});

package/lib/style.css

@@ -73,8 +73,10 @@
   white-space: pre-line;
 }
 
+/* 1.4x the size it sits in, so a report default scales its headline with
+   its body. Unstyled, that is the host page's own body size. */
 .q-item.q-report-header {
-  font-size: 14pt;
+  font-size: 1.4em;
   font-weight: bold;
 }
 
@@ -105,7 +107,9 @@
  * Fragmentation. SCHEMA.md calls these the print-CSS contract, so they ship
  * with the look rather than being left to the host to rediscover: `thead`
  * repeats per printed page, a table row stays whole, a group header travels
- * with its rows, and a group declaring `break: "page"` gets one.
+ * with its rows, and each edge a group's `break` position turns gets one. The
+ * trailing edge needs its own rule: `break-before` cannot say what falls after
+ * the last instance of a run.
  *
  * Pages are not the only fragmentation context: the columns case lives in the
  * shared block above, because a sheet with no pages can still have columns.
@@ -132,3 +136,7 @@
 .q-break {
   break-before: page;
 }
+
+.q-break-after {
+  break-after: page;
+}

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@quario/html",
-  "version": "0.9.0",
-  "description": "The HTML render target for quario — in the makings, not yet released",
+  "version": "0.11.0",
+  "description": "Tiny, escape-by-default HTML render target for quario. Semantic tables and a stable class contract.",
+  "keywords": [
+    "csp",
+    "escaping",
+    "html",
+    "quario",
+    "report"
+  ],
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -27,24 +34,25 @@
     "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 --exclude-entrypoints style.css",
-    "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})\""
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.9.0",
+    "quario": "^0.11.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.9.0"
+    "quario": "^0.11.0"
   },
   "size-limit": [
     {