@quario/html 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-02
+
+### Added
+
+- **`format` stringifies at the markup edge.** The kind is presented through
+  the engine's `format()` helper from the instance locale, then escaped like
+  any other interpolated value.
+
+- **`page.margin` becomes `@page{margin:<n>pt}`.** Report-header `height`
+  is unread: a CSS height would pin in the body box, not from the page top.
+
+- **`spaceBefore` / `spaceAfter` map to `margin-top` / `margin-bottom`.**
+  Report and group containers are flex columns so adjacent authored gaps add
+  rather than collapse.
+
+- **Padding and complete border sides map to inline CSS.**
+  `box-sizing:border-box` rides the same attribute. A side that does not
+  resolve all three names emits nothing, so a missing colour never becomes
+  the browser's solid black. Header-row, row, and total-row boxes are
+  withdrawn from `<tr>` — CSS does not box a table row — while other row
+  styles still inherit.
+
+### Changed
+
+- **`<tfoot>` holds every total row.** Extra rows are extra `<tr>`; the
+  section still closes at `table-end`.
+
+- **A visible text item occupies a line, and a literal newline is a break.**
+  Before, an empty item collapsed and a newline became a space. The honor
+  rules now hang off `.q-item` and `.q-table th, td` in the reference
+  stylesheet, the same pattern as `.q-break` — class is the hook, the rule
+  is overridable. Empty table cells still collapse. Host CSS still owns
+  leading; this is not `line-height: 1.4`.
+
+### Fixed
+
+- **A declared `false` flag now emits its CSS off-value.** `bold: false` used
+  to emit nothing, so the reference stylesheet's band-role `font-weight: bold`
+  still won on screen while PDF rendered regular. Exact `false` now writes
+  `font-weight:normal` (and the matching off-value for italic, uppercase, and
+  the decorations), which beats the sheet. Omit and a non-boolean result still
+  emit nothing.
+
+## [0.2.0] - 2026-09-01
+
+### Added
+
+- **`html({ fonts })` says what a family name means on your page.** A report
+  declares the typeface it wants — `family: "Instrument Sans"`, or the
+  portable `family: "mono"` — and this option resolves that name to whatever
+  CSS means on the page it is displayed in:
+  `html({ fonts: { "Instrument Sans": "var(--font-instrument-sans)" } })`. Any
+  CSS `font-family` value works, so a custom property, a font stack or a
+  quoted name are all fine; a value containing `;` or `}` throws from `html()`
+  rather than at render. Names match case-insensitively, and `sans`, `serif`
+  and `mono` can be mapped like any other, which is what lets one definition
+  say "the mono one" and each surface answer for itself. Useful wherever your
+  faces are registered under names you do not control — a build tool that
+  hashes `@font-face` names, for instance. The mapping resolves families a
+  report declares; the face of text that declares none stays your
+  stylesheet's, so it is still one CSS rule away.
+
+- **The report default rides a report root.** Every fragment is now wrapped in
+  one `<div class="q-report">`, and a report that declares a `style` carries it
+  there as an inline `font-family`/`font-size` — written once for the document
+  rather than repeated on every item, with CSS inheritance doing the rest. The
+  unlicensed marking stays outside the root, as the fragment's first element
+  and the root's sibling, so no authored style can reach it.
+
+- **`uppercase` maps to `text-transform:uppercase`.** The markup carries the
+  text exactly as authored and only its rendering is capitalised, so what a
+  reader selects, copies, or hears from a screen reader is your own casing.
+
+- **Splits render as a flex row of sized slots.** A
+  [split](https://getquario.com/docs) becomes
+  `<div class="q-split q-<role>">` carrying inline `display:flex`, with each
+  slot a `<div class="q-slot">` sized inline — `width:<n>%` for an authored
+  share, `flex:1` for a width-less one. The slot item inside keeps its
+  ordinary `q-item` container, so an item's markup never depends on where it
+  sits. Placement is emitted inline for the same reason page columns are: it
+  is document structure, not one of the visual defaults this target leaves to
+  your stylesheet.
+- **`html({ paths: true })` maps rendered output back to the schema.** Each
+  element whose event carries a schema path gains `data-q-path`: item and
+  image containers, each group instance's container, the table, and every
+  `<th>`/`<td>` (the column definition's path; total cells their own entry).
+  One definition renders many times, so one path appears on every instance of
+  it. Escaped like every generated attribute, and off by default — the
+  attribute is weight a plain display pays for nothing.
+
+### Changed
+
+- **A family name that could not be written as CSS now falls back instead of
+  being rewritten.** A `family` carrying characters that cannot appear in a
+  family name was stripped down to whatever survived and emitted anyway, which
+  named a face that could not exist — `family: "var(--my-font)"` became
+  `font-family:'var--my-font'`. Such a name now contributes nothing, so the
+  text renders in the face above it: the report default, or your stylesheet's
+  baseline. Ordinary names are unaffected. To resolve a name your page knows
+  under a different one, map it with `html({ fonts })`.
+
+- **The fragment now has a root element.** `<div class="q-report">` wraps every
+  render, whether or not a report declares a default. Host CSS that assumed
+  items and tables were the fragment's top-level children needs a descendant
+  selector; nothing else about the markup moved.
+
+- **The reference stylesheet's baseline face moved onto `.q-report`.** It was
+  on `.q-item`, `.q-table` and `.q-unlicensed` — a direct rule, which would
+  have beaten the report default an author writes on the document. The marking
+  keeps its own rule, being outside the root. Same look, one rule up.
+
+- **A bare `Date` escapes to ISO 8601 UTC, the same on every machine.**
+  Interpolated `Date` values rendered through `String(date)`, which bakes the
+  host's timezone and locale into the markup. They now render as
+  `toISOString()` text through the engine's shared display rule — escaped
+  like every other value — so the same report produces the same HTML
+  everywhere. Formatted dates keep coming from registered functions.
+
+### Fixed
+
+- **The reference stylesheet sets a base font family.** A fragment dropped
+  into a page with no font of its own inherited the browser default — a serif
+  — where every other target rendered a grotesque. `@quario/html/style.css`
+  now sets `sans-serif` on report text, as an ordinary rule any host overrides
+  by source order.
+
 ## [0.1.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -47,16 +47,18 @@ const page = await report.render(html(), data);
 ```
 
 ```html
-<div class="q-group" data-group="region">
-  <div class="q-item q-group-header" style="font-weight:bold">North</div>
-  <table class="q-table">
-    <colgroup><col><col></colgroup>
-    <thead><tr><th>Product</th><th>Amount</th></tr></thead>
-    <tbody><tr><td>Desk</td><td style="text-align:right">$500.00</td></tr></tbody>
-  </table>
-  <div class="q-item q-group-footer">Subtotal $500.00</div>
+<div class="q-report">
+  <div class="q-group" data-group="region">
+    <div class="q-item q-group-header" style="font-weight:bold">North</div>
+    <table class="q-table">
+      <colgroup><col><col></colgroup>
+      <thead><tr><th>Product</th><th>Amount</th></tr></thead>
+      <tbody><tr><td>Desk</td><td style="text-align:right">$500.00</td></tr></tbody>
+    </table>
+    <div class="q-item q-group-footer">Subtotal $500.00</div>
+  </div>
+  <div class="q-item q-report-footer">Grand total $500.00</div>
 </div>
-<div class="q-item q-report-footer">Grand total $500.00</div>
 ```
 
 The output is a **fragment**: no `<html>`, no `<head>`, no styles of its own. Wrap it in your own
@@ -64,12 +66,16 @@ page shell and stylesheet.
 
 ## API
 
-### `html()`
+### `html(options?)`
 
-The target factory takes no options and returns the target you pass to `render`.
+The target factory returns the target you pass to `render`.
 `report()` compiles once and `report.render(html(), data)` resolves the fragment. Compile at
 startup and render per request. Definition problems throw at `report()`, at compile time.
 
+One option: `{ paths: true }` stamps `data-q-path="<schema path>"` on each element whose event
+carries one (items, images, group containers, the table and its cells), mapping rendered output
+back to the definition behind it. Off by default.
+
 ```js
 const report = quario().report(schema, funcs);
 const page = await report.render(html(), data);
@@ -97,20 +103,22 @@ change.
 | `<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"` |
 | `<table class="q-table">`                 | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` when totals are declared                                                    |
 | `<div class="q-item q-image q-<role>">`   | Each image item, holding one `<img>` whose `src` is a base64 `data:` URI of the event's bytes; the rendered `alt` is escaped                    |
+| `<div class="q-split q-<role>">`          | Each split, carrying inline `display:flex`; its slots are `<div class="q-slot">` sized inline, each holding the slot item's ordinary container  |
 
 A column `width` becomes an inline `width:<n>%` on its `<col>`. The classes above belong to this
 target. The schema never speaks in CSS. Displaying a fragment that contains images under a Content
 Security Policy needs `img-src data:`.
 
-Style declarations map to inline CSS (`bold` → `font-weight:bold`, `size` → `font-size:<n>pt`,
-`family: "mono"` → `font-family:monospace`, …). Only those mappings appear in the markup. 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 unstyled report renders as unstyled markup, and the
-classes above are where a stylesheet supplies the look. An inline `style` attribute would beat
-yours in the cascade and force `!important` on you; the defaults ship as an ordinary stylesheet
-instead, at [`@quario/html/style.css`](#the-reference-stylesheet). The PDF and XLSX targets carry
-theirs built in, because their consumers have no stylesheet. An empty row set still emits the
-table, its header, and an empty `<tbody>`. A hidden table cell keeps its `<td>`, empty.
+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.
+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
+in the cascade and force `!important` on you; the defaults and the honor rules ship as an ordinary stylesheet
+instead. The PDF and XLSX targets carry theirs built in, because their consumers have no stylesheet. An empty
+row set still emits the table, its header, and an empty `<tbody>`. A hidden table cell keeps its `<td>`, empty.
 
 This target is unpaginated: 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 accepted on
@@ -144,6 +152,7 @@ Host CSS targets these classes:
 1. Render the fragment and wrap it in a document with two stylesheets inlined, in order:
    `@quario/html/style.css` below, then your own.
 2. The shipped sheet already puts band behavior on the emitted 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-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.
@@ -154,8 +163,9 @@ Host CSS targets these classes:
 ### The reference stylesheet
 
 The package ships the default look as a real stylesheet, `@quario/html/style.css`: the band-role
-weights and sizes, the table look, and the four pagination rules above. Link it, import it through
-a bundler, or read and inline it. Plain Node cannot `import` a `.css` file, so on the server:
+weights and sizes, the table look, occupy and newline-as-break on `.q-item` and table cells, and
+the four pagination rules above. Link it, import it through a bundler, or read and inline it.
+Plain Node cannot `import` a `.css` file, so on the server:
 
 ```js
 import { readFileSync } from "node:fs";

package/lib/index.d.ts

@@ -1,8 +1,25 @@
 import type { Target } from "quario";
 
+export interface HtmlOptions {
+  /**
+   * Emit `data-q-path` on each element whose event carries a schema `path`,
+   * mapping rendered output back to the definition behind it — the editor's
+   * selection seam. Off by default.
+   */
+  paths?: boolean;
+  /**
+   * This target's font mapping: a declared `family` name to a CSS
+   * `font-family` value — `{ "Instrument Sans": "var(--font-instrument-sans)" }`.
+   * Names match case-insensitively, and the generics `sans` / `serif` / `mono`
+   * may be mapped like any other. A value containing `;` or `}` throws from
+   * `html()`. See SCHEMA.md, "The HTML target" → Fonts.
+   */
+  fonts?: Record<string, string>;
+}
+
 /**
  * The HTML render target:
  * `quario().report(schema).render(html(), data)` resolves the fragment
  * described in SCHEMA.md ("The HTML target").
  */
-export function html(): Target<"html", Promise<string>>;
+export function html(options?: HtmlOptions): Target<"html", Promise<string>>;

package/lib/index.js

@@ -9,24 +9,30 @@
  * never carries markup-escaped text.
  */
 
-import { isReportBand, text, walk } from "quario";
+import { display, format, isReportBand, text, walk } from "quario";
 
 /** @type {Record<string, string>} */
 let ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
 /** @type {(value: any) => string} */
-let esc = (value) => String(value ?? "").replace(/[&<>"']/g, (char) => ESC[char]);
+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.
-/** @type {(tokens: any[]) => string} */
-let markup = (tokens) => {
+/** @type {(tokens: any[], style?: any, intl?: any) => string} */
+let markup = (tokens, style, intl) => {
   let out = "";
-  for (let token of tokens) out += "literal" in token ? token.literal : esc(token.value);
+  for (let token of tokens)
+    out += "literal" in token ? token.literal : esc(shown(token.value, style, intl));
   return out;
 };
+/** @type {(value: any, style: any, intl: any) => any} */
+let shown = (value, style, intl) => {
+  let text = format(value, style?.format, intl);
+  return text != null ? text : value;
+};
 
 // 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
@@ -47,9 +53,13 @@ let base64 = (bytes) => {
 // smuggle CSS of its own into the attribute. Unknown names are ignored.
 /** @type {Record<string, string>} */
 let FAMILY = { sans: "sans-serif", serif: "serif", mono: "monospace" };
-/** @type {(value: any) => boolean} */
-let finite = (value) => typeof value === "number" && Number.isFinite(value);
 let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+// A family name usable as it stands. Anything else would have to be rewritten
+// to be emitted, and a rewritten name names a face that cannot exist.
+let NAMEABLE = /^[A-Za-z0-9 _-]+$/;
+// What a host's CSS value may not carry: `;` is what would turn one option
+// into two declarations.
+let UNSAFE = /[;}]/;
 /** @type {(value: any) => boolean} */
 let isHex = (value) => typeof value === "string" && HEX.test(value);
 let ALIGNMENTS = ["left", "center", "right"];
@@ -58,41 +68,118 @@ let ALIGNMENTS = ["left", "center", "right"];
 // 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"]);
-/** @type {(value: string) => string} */
-let named = (value) => {
-  let key = value.toLowerCase();
+// 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.
+/** @type {(path: string, value: any) => string} */
+let cssValue = (path, value) => {
+  if (typeof value !== "string" || !value) throw Error(path + ": expected a CSS font-family value");
+  if (UNSAFE.test(value)) throw Error(path + ": cannot contain ';' or '}'");
+  return value;
+};
+
+/** @type {(fonts: any) => Record<string, string>} */
+let mapping = (fonts) => {
+  if (fonts == null) return {};
+  if (typeof fonts !== "object")
+    throw Error("options.fonts: expected an object of family names to CSS values");
+  return Object.fromEntries(
+    Object.entries(fonts).map(([name, value]) => [
+      name.toLowerCase(),
+      cssValue("options.fonts." + name, value),
+    ]),
+  );
+};
+
+// 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).
+/** @type {(map: Record<string, string>, value: string) => string} */
+let named = (map, value) => {
   // Own-key lookup: `constructor` must not resolve an inherited member.
-  if (Object.hasOwn(FAMILY, key)) return FAMILY[key];
-  let name = value.replace(/[^A-Za-z0-9 _-]/g, "");
-  return name ? "'" + name + "'" : "";
+  let key = value.toLowerCase();
+  if (Object.hasOwn(map, key)) return map[key];
+  return NAMEABLE.test(value) ? "'" + value + "'" : "";
 };
-/** @type {Record<string, (value: any) => string>} */
+// Exact true/false only: a computed value of the wrong shape contributes
+// nothing, same as omit (SCHEMA.md, Style declarations).
+/** @type {(on: string, off: string) => (value: any) => string} */
+let flag = (on, off) => (value) => (value === true ? on : value === false ? off : "");
+/** @type {Record<string, (value: any, map: Record<string, string>) => string>} */
 let CSS = {
-  family: (value) => {
+  family: (value, map) => {
     if (typeof value !== "string" || !value) return "";
-    let name = named(value);
+    let name = named(map, value);
     return name ? "font-family:" + name : "";
   },
-  size: (value) => (finite(value) && value > 0 ? "font-size:" + value + "pt" : ""),
-  bold: (value) => (value ? "font-weight:bold" : ""),
-  italic: (value) => (value ? "font-style:italic" : ""),
+  size: (value) => (Number.isFinite(value) && value > 0 ? "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 : ""),
+  // 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"),
+};
+
+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.spaceBefore = (value) => (isPad(value) ? "margin-top:" + value + "pt" : "");
+CSS.spaceAfter = (value) => (isPad(value) ? "margin-bottom:" + value + "pt" : "");
+
+/** @type {(width: any) => boolean} */
+let isStroke = (width) => Number.isFinite(width) && width > 0;
+
+/** @type {(style: any, side: string) => string[]} */
+let borderSide = (style, side) => {
+  let width = style["border" + side + "Width"];
+  let line = style["border" + side + "Style"];
+  let color = style["border" + side + "Color"];
+  if (!isStroke(width) || !LINES.includes(line) || !isHex(color)) return [];
+  let edge = side.toLowerCase();
+  return [
+    "border-" + edge + "-width:" + width + "pt",
+    "border-" + edge + "-style:" + line,
+    "border-" + edge + "-color:" + color,
+  ];
 };
 
-/** @type {(name: string, value: any) => string} */
-let decl = (name, value) => {
-  if (value == null || !Object.hasOwn(CSS, name)) return "";
-  return CSS[name](value);
+/** @type {(name: string) => boolean} */
+let isBox = (name) => name.startsWith("padding") || name.startsWith("border");
+
+/** @type {(style: any) => any} */
+let unbox = (style) => {
+  if (!style) return;
+  let names = Object.keys(style).filter((name) => !isBox(name));
+  if (!names.length) return;
+  return Object.fromEntries(names.map((name) => [name, style[name]]));
+};
+
+/** @type {(style: any) => string[]} */
+let decoLine = (style) => {
+  let parts = [];
+  if (style.underline === true) parts.push("underline");
+  if (style.strikethrough === true) parts.push("line-through");
+  return parts;
 };
 
 /** @type {(style: any) => string} */
 let decoration = (style) => {
-  let parts = [];
-  if (style.underline) parts.push("underline");
-  if (style.strikethrough) parts.push("line-through");
-  return parts.length ? "text-decoration:" + parts.join(" ") : "";
+  let parts = decoLine(style);
+  if (parts.length) return "text-decoration:" + parts.join(" ");
+  return style.underline === false || style.strikethrough === false ? "text-decoration:none" : "";
 };
 
 /** @type {(name: string) => boolean} */
@@ -106,37 +193,88 @@ let pushDecoration = (out, style, seen) => {
   if (deco) out.push(deco);
 };
 
-/** @type {(out: string[], name: string, value: any) => void} */
-let pushDecl = (out, name, value) => {
-  let declaration = decl(name, value);
+/** @type {(out: string[], name: string, value: any, map: Record<string, string>) => void} */
+let pushDecl = (out, name, value, map) => {
+  if (value == null || !Object.hasOwn(CSS, name)) return;
+  let declaration = CSS[name](value, map);
   if (declaration) out.push(declaration);
 };
 
+/** @type {(out: string[], style: any, seen: { box: boolean, sizing: boolean }) => void} */
+let pushBox = (out, style, seen) => {
+  if (seen.box) return;
+  seen.box = true;
+  let start = out.length;
+  for (let side of SIDES) out.push(...borderSide(style, side));
+  if (out.length > start) seen.sizing = true;
+};
+
+/** @type {(seen: { sizing: boolean }, name: string, added: boolean) => void} */
+let notePad = (seen, name, added) => {
+  if (added && name.startsWith("padding")) seen.sizing = true;
+};
+
+/** @type {(out: string[], name: string, style: any, seen: { decoration: boolean, box: boolean, sizing: boolean }, map: Record<string, string>) => void} */
+let emitDecl = (out, name, style, seen, map) => {
+  if (isDecoration(name)) return pushDecoration(out, style, seen);
+  if (name.startsWith("border")) return pushBox(out, style, seen);
+  let start = out.length;
+  pushDecl(out, name, style[name], map);
+  notePad(seen, name, out.length > start);
+};
+
 // Serialize a resolved style object to inline CSS, in declaration order.
 // underline and strikethrough share one CSS property, so the first of either
-// in authored order emits the composed value and the second is skipped.
-/** @type {(style: any) => string} */
-let css = (style) => {
+// in authored order emits the composed value and the second is skipped. A
+// border side emits only when width, style and colour all resolve, so a
+// missing name never becomes a browser-default solid black stroke.
+/** @type {(style: any, map: Record<string, string>) => string} */
+let css = (style, map) => {
   let out = /** @type {string[]} */ ([]);
-  let seen = { decoration: false };
-  for (let name in style) {
-    if (isDecoration(name)) pushDecoration(out, style, seen);
-    else pushDecl(out, name, style[name]);
-  }
+  let seen = { decoration: false, box: false, sizing: false };
+  for (let name in style) emitDecl(out, name, style, seen, map);
+  if (seen.sizing) out.push("box-sizing:border-box");
   return out.join(";");
 };
 
-// Compose a resolved style into one escaped inline style attribute.
-/** @type {(event: { style?: any }) => string} */
-let styleAttr = ({ style }) => {
-  let out = style ? css(style) : "";
-  return out ? ' style="' + esc(out) + '"' : "";
+// 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
+// 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).
+/** @type {(fonts: any) => (event: { style?: any }, own?: 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.
+  let map = { ...FAMILY, ...mapping(fonts) };
+  return ({ style }, own = "") => {
+    let out = [own, style && css(style, map)].filter(Boolean).join(";");
+    return out ? ' style="' + esc(out) + '"' : "";
+  };
 };
 
-/** @type {(list: any[], tag: string) => string} */
-let cells = (list, tag) =>
+// 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.
+/** @type {(slot: { width?: number } | undefined) => string} */
+let slotAttr = (slot) =>
+  ' style="' + esc(slot && slot.width != null ? "width:" + slot.width + "%" : "flex:1") + '"';
+
+// 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.
+/** @type {(event: { path?: string }) => string} */
+let pathAttr = ({ path }) => (path ? ' data-q-path="' + esc(path) + '"' : "");
+/** @type {() => string} */
+let noAttr = () => "";
+
+/** @type {(list: any[], tag: string, attrs: (event: any) => string, intl: any) => string} */
+let cells = (list, tag, attrs, intl) =>
   list
-    .map((cell) => "<" + tag + styleAttr(cell) + ">" + markup(cell.tokens) + "</" + tag + ">")
+    .map(
+      (cell) =>
+        "<" + tag + attrs(cell) + ">" + markup(cell.tokens, cell.style, intl) + "</" + tag + ">",
+    )
     .join("");
 
 /**
@@ -149,10 +287,31 @@ let cells = (list, tag) =>
  * fragment, so `report-start.page` band closures are ignored — page furniture
  * belongs to the host's print CSS.
  *
+ * `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.
+ *
+ * `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
+ * throw from here (docs/adr/0034).
+ *
+ * The options are described once, in the hand-written public declarations,
+ * and read back here -- a second copy in JSDoc is a copy that drifts.
+ * @import { HtmlOptions } from './index.d.ts'
+ *
+ * @param {HtmlOptions} [options] Host options for this target.
  * @returns {{name: "html", compile: (stream: any) => (data?: any) => Promise<string>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
-export function html() {
+export function html(options) {
+  let mark = options?.paths ? pathAttr : noAttr;
+  // The factory's verdict, like `mark`: the mapping is validated once, here.
+  let styleAttr = styling(options?.fonts);
+  // The pair every cell carries, bound once rather than threaded as two.
+  /** @type {(cell: any) => string} */
+  let attrs = (cell) => styleAttr(cell) + mark(cell);
   return {
     name: "html",
     compile: (stream) => async (data) => {
@@ -163,9 +322,13 @@ export function html() {
       // goes with the render — nothing here outlives it.
       /** @type {Map<Uint8Array, string>} */
       let sources = new Map();
-      // Whether a `total-row` already closed the `<tbody>` — markup
+      // Whether a `total-row` already opened `<tfoot>` — markup
       // bookkeeping that stays at this edge, out of the event contract.
       let tfoot = false;
+      // Whether `report-start` opened the report root. A stream may start
+      // part-way through (the walk driver reads an event's type and nothing
+      // else), and an unbalanced closing tag would be this target's own bug.
+      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
@@ -178,6 +341,25 @@ export function html() {
       // that may own the region. Taken from each event rather than counted, so
       // there is one spelling of a depth the stream already 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} */
@@ -219,21 +401,48 @@ export function html() {
         // edge, so the badge stays childless whatever stream a host compiles
         // against.
         "report-start": (event) => {
+          intl = { locale: event.locale, currency: event.currency, timeZone: event.timeZone };
           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.
+          out += '<div class="q-report"' + styleAttr(event) + ">";
+          rooted = true;
           if (event.columns) region = { count: event.columns, owner: -1, open: false };
         },
         // 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) => {
+          emit(
+            event,
+            '<div class="q-item q-' +
+              event.role +
+              '"' +
+              styleAttr(event) +
+              mark(event) +
+              ">" +
+              markup(event.tokens, event.style, intl) +
+              "</div>",
+          );
+        },
+        // 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) => {
           content(event);
           out +=
-            '<div class="q-item q-' +
-            event.role +
-            '"' +
-            styleAttr(event) +
-            ">" +
-            markup(event.tokens) +
-            "</div>";
+            '<div class="q-split q-' + event.role + '"' + styleAttr(event, "display:flex") + ">";
+          split = { slots: event.slots, at: 0 };
+        },
+        "split-end": () => {
+          split = null;
+          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
@@ -245,25 +454,27 @@ export function html() {
         // never the markup-passing join a cell body gets; an image without one
         // carries `alt=""`, the decorative-image convention.
         image: (event) => {
-          content(event);
           let source = sources.get(event.bytes);
           if (source === undefined)
             sources.set(
               event.bytes,
               (source = esc("data:image/" + event.format + ";base64," + base64(event.bytes))),
             );
-          out +=
+          emit(
+            event,
             '<div class="q-item q-image q-' +
-            event.role +
-            '"' +
-            styleAttr(event) +
-            '><img src="' +
-            source +
-            '" alt="' +
-            esc(text(event.alt || [])) +
-            // Both keep the aspect ratio, since neither names a height.
-            (event.fit === "width" ? '" style="width:100%">' : '" style="max-width:100%">') +
-            "</div>";
+              event.role +
+              '"' +
+              styleAttr(event) +
+              mark(event) +
+              '><img src="' +
+              source +
+              '" alt="' +
+              esc(text(event.alt || [])) +
+              // Both keep the aspect ratio, since neither names a height.
+              (event.fit === "width" ? '" style="width:100%">' : '" style="max-width:100%">') +
+              "</div>",
+          );
         },
         // Each group instance is wrapped in a `q-group` container carrying
         // the group name, so print CSS can keep a header with its rows
@@ -277,6 +488,7 @@ export function html() {
             '<div class="q-group' +
             (event.break || event.reset ? " q-break" : "") +
             '"' +
+            mark(event) +
             ' data-group="' +
             esc(event.name) +
             '">';
@@ -303,31 +515,50 @@ export function html() {
           for (let column of /** @type {any[]} */ (event.columns))
             cols +=
               "<col" + (column.width ? ' style="width:' + esc(column.width) + '%"' : "") + ">";
-          let headers = event.columns.map((/** @type {any} */ column) => column.header);
+          let headers = event.columns.map((/** @type {any} */ column) =>
+            Object.assign({}, column.header, { path: column.path }),
+          );
           out +=
-            '<table class="q-table">' +
+            '<table class="q-table"' +
+            mark(event) +
+            ">" +
             "<colgroup>" +
             cols +
             "</colgroup>" +
-            "<thead><tr>" +
-            cells(headers, "th") +
+            "<thead><tr" +
+            styleAttr({ style: unbox(event.style) }) +
+            ">" +
+            cells(headers, "th", attrs, intl) +
             "</tr></thead><tbody>";
         },
         row: (event) => {
-          out += "<tr" + styleAttr(event) + ">" + cells(event.cells, "td") + "</tr>";
+          out +=
+            "<tr" +
+            styleAttr({ style: unbox(event.style) }) +
+            ">" +
+            cells(event.cells, "td", attrs, intl) +
+            "</tr>";
         },
         "total-row": (event) => {
-          tfoot = true;
-          out += "</tbody><tfoot><tr>" + cells(event.cells, "td") + "</tr></tfoot>";
+          if (!tfoot) {
+            out += "</tbody><tfoot>";
+            tfoot = true;
+          }
+          out +=
+            "<tr" +
+            styleAttr({ style: unbox(event.style) }) +
+            ">" +
+            cells(event.cells, "td", attrs, intl) +
+            "</tr>";
         },
         "table-end": () => {
-          out += tfoot ? "</table>" : "</tbody></table>";
+          out += tfoot ? "</tfoot></table>" : "</tbody></table>";
         },
       });
       // A root region reaches here open when no full-width footer followed the
       // body it columns.
       close();
-      return out;
+      return rooted ? out + "</div>" : out;
     },
   };
 }

package/lib/style.css

@@ -23,15 +23,44 @@
  */
 
 /* shared:start */
+
+/*
+ * The baseline face hangs off the report root rather than off .q-item and
+ * .q-table: a direct rule beats an inherited one, so a rule on the items
+ * themselves would override the report default an author writes on the
+ * document, which the root carries as an inline font-family. The marking is
+ * outside the root and keeps its own rule for that reason.
+ */
+.q-report,
+.q-unlicensed {
+  font-family: sans-serif;
+}
+
+.q-report,
+.q-group {
+  display: flex;
+  flex-direction: column;
+}
+
 .q-table {
   width: 100%;
   border-collapse: collapse;
 }
 
+/* A visible text item occupies a line, and a literal newline is a break.
+   The class is the hook; a host overrides these the ordinary way, as with
+   .q-break. Empty table cells stay contentless, so they take only the
+   newline mapping. */
+.q-item {
+  min-height: 1lh;
+  white-space: pre-line;
+}
+
 .q-table th,
 .q-table td {
   padding: 2pt 6pt;
   text-align: left;
+  white-space: pre-line;
 }
 
 .q-table thead th {
@@ -82,6 +111,10 @@
  * 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.
  *
+ * Occupy and newline-as-break live in the shared block above: a screen needs
+ * them, and they follow the same pattern as `.q-break` -- class is the hook,
+ * the rule is overridable.
+ *
  * A host overrides any of these the ordinary way; `example/print.css` turns
  * `break-inside` back to `auto` for one group to let it span pages.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/html",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The HTML render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -39,17 +39,17 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.1.0",
+    "quario": "^0.3.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.1.0"
+    "quario": "^0.3.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
-      "limit": "1.7 kB",
+      "limit": "2.5 kB",
       "ignore": [
         "quario"
       ]