@quario/html 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @quario/html
 
+## 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
@@ -110,7 +122,7 @@ change.
 | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `<div class="q-report">`                           | The fragment's root, holding every band                                                                                                                                                                                                                                    |
 | `<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 +136,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 +145,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 +184,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.js

@@ -9,7 +9,7 @@
  * never carries markup-escaped text.
  */
 
-import { display, format, hostOptions, isReportBand, styledRuns, text, walk } from "quario";
+import { display, format, hostOptions, isReportBand, splits, styledRuns, text, walk } from "quario";
 
 /** @type {Record<string, string>} */
 let ESC = {
@@ -24,9 +24,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,10 +40,8 @@ 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);
@@ -54,8 +51,7 @@ let piece = (styled, style, intl, map) => {
 };
 
 // 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 = "";
@@ -63,10 +59,9 @@ let cellMarkup = (map) => (tokens, style, intl) => {
   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) => {
@@ -105,11 +100,10 @@ let VALIGNMENTS = Object.keys(ALIGN_CONTENT);
 // 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 +138,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.
@@ -174,9 +167,8 @@ let CSS = {
   background: (value) => (isHex(value) ? "background-color:" + value : ""),
   align: (value) => (ALIGNMENTS.includes(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.
+  // 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) => (VALIGNMENTS.includes(value) ? "vertical-align:" + value : ""),
   // The text itself is untouched, so selection and screen readers get what
   // the author wrote; only its rendering is capitalised.
@@ -282,17 +274,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 +294,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 +325,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 +351,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 +375,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 +390,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 +402,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 +444,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(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 +508,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 +519,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="' +

package/lib/style.css

@@ -105,7 +105,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 +134,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.10.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": {
@@ -39,12 +46,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.9.0",
+    "quario": "^0.10.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.9.0"
+    "quario": "^0.10.0"
   },
   "size-limit": [
     {