@quario/html 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to @quario/html are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- **HTML fragments for compiled reports.** Semantic tables, stable `q-*`
+  classes, every interpolated value escaped. Pass `html()` to `report.render`
+  and wrap the fragment in your own page. The default look ships as
+  `@quario/html/style.css`, not as inline style in the markup.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -0,0 +1,186 @@
+# @quario/html
+
+**The HTML render target for [quario](https://www.npmjs.com/package/quario).** Renders a report
+definition to an HTML fragment with semantic tables, a stable class contract, and every
+interpolated value escaped.
+
+## Install
+
+```bash
+npm install quario @quario/html
+```
+
+The engine is a peer dependency, installed beside the target. ESM-only, Node 22+, and
+browser-ready through any standards-based ESM bundler.
+
+## Quick start
+
+```js
+import { quario } from "quario";
+import { html } from "@quario/html";
+
+const schema = {
+  data: "$.orders[*]",
+  aggregates: { total: "sum:=@.price * @.qty" },
+  groups: [
+    {
+      name: "region",
+      by: "=@.region",
+      aggregates: { subtotal: "sum:=@.price * @.qty" },
+      header: [{ type: "text", value: "{{ region.key }}", style: { bold: true } }],
+      footer: [{ type: "text", value: "Subtotal {{ money(region.subtotal) }}" }],
+    },
+  ],
+  detail: {
+    columns: [
+      { header: "Product", value: "{{ @.product }}" },
+      { header: "Amount", value: "{{ money(@.price * @.qty) }}", style: { align: "right" } },
+    ],
+  },
+  footer: [{ type: "text", value: "Grand total {{ money($.total) }}" }],
+};
+
+const data = { orders: [{ region: "North", product: "Desk", price: 250, qty: 2 }] };
+
+const report = quario().report(schema, { money: (n) => "$" + n.toFixed(2) });
+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>
+<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
+page shell and stylesheet.
+
+## API
+
+### `html()`
+
+The target factory takes no options and 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.
+
+```js
+const report = quario().report(schema, funcs);
+const page = await report.render(html(), data);
+
+report.names; // free variable names the expressions read
+report.functions; // registry function names the definition calls
+report.paths; // the data query's frozen dependency topology
+report.stream(data); // the raw event generator, if you want events instead
+```
+
+Engine-level options (`query` budgets, the license key) live on the instance
+(`quario({ query, license })`); see the [engine README](https://www.npmjs.com/package/quario).
+
+Rendering is asynchronous and hands the loop back between batches, so a large report never blocks the
+host. Compilation stays synchronous; render-time failures reject with the same located errors.
+
+## Output contract
+
+These classes are the contract host CSS targets. They are stable, and changing them is a breaking
+change.
+
+| Emits                                     | For                                                                                                                                             |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<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"` |
+| `<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                    |
+
+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.
+
+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
+the schema and ignored here until a target honors them.
+
+## Unlicensed marking
+
+An unlicensed render opens the fragment with `<div class="q-unlicensed">` holding the wording
+from `report-start.marking` as escaped text. A licensed render emits no badge. The element and its
+position are normative; visual treatment belongs to the host. The shipped stylesheet leaves the
+badge unstyled, because a watermark would escape the fragment's box onto the host page.
+
+## Escaping
+
+**Every interpolated value is escaped.** `{{{ }}}` is a definition error, so no schema syntax can
+exempt a data value from escaping. Generated attribute values, including classes and inline
+styles built from expressions, are escaped too.
+
+Literal template text passes through verbatim as author-controlled markup. A definition is
+trusted configuration. Its _data_ is untrusted, and data can never reach the document unescaped.
+
+## Printing to PDF
+
+For a browserless, deterministic document, use
+[`@quario/pdf`](https://www.npmjs.com/package/@quario/pdf), same schema, same API, a
+`Uint8Array` out. Use the HTML print route below when you want full CSS typography and already
+have a browser or Paged-CSS engine in your pipeline.
+
+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-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.
+3. Print with a headless browser (`page.pdf()` in Playwright or Puppeteer, page numbers via the
+   footer template) or a Paged-CSS engine (WeasyPrint, Prince; page numbers via `@page` margin
+   boxes).
+
+### 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:
+
+```js
+import { readFileSync } from "node:fs";
+
+const css = readFileSync(new URL(import.meta.resolve("@quario/html/style.css")), "utf8");
+const page = `<!doctype html><html><head><style>${css}</style></head><body>${fragment}</body></html>`;
+```
+
+Its **selectors** are contract; its **rules** are not. It is a reference default meant to be
+overridden. Every rule is ordinary specificity, so your own stylesheet loaded after it wins
+without `!important` anywhere. Link nothing at all and you get unstyled markup.
+
+Two things it leaves to you: `@page` geometry and body type, which only a host can decide, and
+any watermark treatment of `.q-unlicensed`, left as plain text here because `position: fixed`
+would paint over your whole page. `example/print.css` in the repository is a host's half showing
+both, and `example/print.js` is the complete pipeline.
+
+## License
+
+Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
+licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+
+Pass your license key once, on the instance; it is verified offline:
+
+```js
+const q = quario({ license: "quario_..." });
+await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
+```

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+import type { Target } from "quario";
+
+/**
+ * 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>>;

package/lib/index.js

@@ -0,0 +1,333 @@
+/**
+ * @quario/html — the HTML render target: a pure consumer of the engine's
+ * public event stream, passed to a compiled report's `render` and serializing
+ * each event to the HTML contract described in SCHEMA.md.
+ *
+ * All HTML escaping lives here, at the markup edge: every interpolated token
+ * value is escaped, literal template text passes verbatim as author-controlled
+ * markup, and every generated attribute value is escaped. The core stream
+ * never carries markup-escaped text.
+ */
+
+import { 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]);
+
+// 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) => {
+  let out = "";
+  for (let token of tokens) out += "literal" in token ? token.literal : esc(token.value);
+  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.
+let CHUNK = 0x8000;
+/** @type {(bytes: Uint8Array) => string} */
+let base64 = (bytes) => {
+  let binary = "";
+  for (let at = 0; at < bytes.length; at += CHUNK)
+    binary += String.fromCharCode(...bytes.subarray(at, at + CHUNK));
+  return btoa(binary);
+};
+
+// Map the neutral style vocabulary to inline CSS — the one place in the stack
+// that speaks CSS. Every mapper coerces: a computed result of the wrong shape
+// emits nothing, so untrusted data reaching a style expression can never
+// 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;
+/** @type {(value: any) => boolean} */
+let isHex = (value) => typeof value === "string" && HEX.test(value);
+let ALIGNMENTS = ["left", "center", "right"];
+
+// 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"]);
+/** @type {(value: string) => string} */
+let named = (value) => {
+  let key = value.toLowerCase();
+  // 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 + "'" : "";
+};
+/** @type {Record<string, (value: any) => string>} */
+let CSS = {
+  family: (value) => {
+    if (typeof value !== "string" || !value) return "";
+    let name = named(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" : ""),
+  color: (value) => (isHex(value) ? "color:" + value : ""),
+  background: (value) => (isHex(value) ? "background-color:" + value : ""),
+  align: (value) => (ALIGNMENTS.includes(value) ? "text-align:" + value : ""),
+};
+
+/** @type {(name: string, value: any) => string} */
+let decl = (name, value) => {
+  if (value == null || !Object.hasOwn(CSS, name)) return "";
+  return CSS[name](value);
+};
+
+/** @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(" ") : "";
+};
+
+/** @type {(name: string) => boolean} */
+let isDecoration = (name) => name === "underline" || name === "strikethrough";
+
+/** @type {(out: string[], style: any, seen: { decoration: boolean }) => void} */
+let pushDecoration = (out, style, seen) => {
+  if (seen.decoration) return;
+  seen.decoration = true;
+  let deco = decoration(style);
+  if (deco) out.push(deco);
+};
+
+/** @type {(out: string[], name: string, value: any) => void} */
+let pushDecl = (out, name, value) => {
+  let declaration = decl(name, value);
+  if (declaration) out.push(declaration);
+};
+
+// 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) => {
+  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]);
+  }
+  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) + '"' : "";
+};
+
+/** @type {(list: any[], tag: string) => string} */
+let cells = (list, tag) =>
+  list
+    .map((cell) => "<" + tag + styleAttr(cell) + ">" + markup(cell.tokens) + "</" + tag + ">")
+    .join("");
+
+/**
+ * The HTML render target:
+ * `quario().report(schema).render(html(), data)`.
+ *
+ * Rendering is async: the engine's `walk` driver dispatches events to the
+ * handlers below and hands the loop back between batches, so a very large
+ * report never blocks the event loop. This target emits an unpaginated
+ * fragment, so `report-start.page` band closures are ignored — page furniture
+ * belongs to the host's print CSS.
+ *
+ * @returns {{name: "html", compile: (stream: any) => (data?: any) => Promise<string>}}
+ *   The target (see SCHEMA.md, "Instances and targets").
+ */
+export function html() {
+  return {
+    name: "html",
+    compile: (stream) => async (data) => {
+      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.
+      /** @type {Map<Uint8Array, string>} */
+      let sources = new Map();
+      // Whether a `total-row` already closed the `<tbody>` — markup
+      // bookkeeping that stays at this edge, out of the event contract.
+      let tfoot = 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.
+      /** @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.
+      let depth = 0;
+      // Does this event stay full-width, outside the columns? The declaring
+      // node's own bands do.
+      /** @type {(event: any) => boolean} */
+      let fullWidth = (event) =>
+        isReportBand(event.role) ||
+        (OWN.has(event.role) && region != null && region.owner === depth - 1);
+      // Close the container if one is open. The count itself survives: a report
+      // header is full-width and arrives *before* the body it columns, so
+      // forgetting the count here would leave that body uncolumned.
+      let close = () => {
+        if (!region || !region.open) return;
+        region.open = false;
+        out += "</div>";
+      };
+      // Open the container the node owes, at the first content that belongs
+      // inside it — which is what leaves that node's own bands above it.
+      let openColumns = () => {
+        if (!region || region.open) return;
+        region.open = true;
+        out += '<div class="q-columns" style="column-count:' + esc(region.count) + '">';
+      };
+      // Everything that is not one of the declaring node's own bands is the
+      // content between them: it opens the container owed, or falls inside the
+      // one already open.
+      /** @type {(event: any) => void} */
+      let content = (event) => {
+        // The overwhelmingly common case, and the hottest path in the render:
+        // no node declared a count, so there is nothing to open or close.
+        if (!region) return;
+        if (fullWidth(event)) close();
+        else openColumns();
+      };
+      // 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), {
+        // 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.
+        "report-start": (event) => {
+          if (event.marking) out += '<div class="q-unlicensed">' + esc(event.marking) + "</div>";
+          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) => {
+          content(event);
+          out +=
+            '<div class="q-item q-' +
+            event.role +
+            '"' +
+            styleAttr(event) +
+            ">" +
+            markup(event.tokens) +
+            "</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.
+        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 +=
+            '<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>";
+        },
+        // 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 }`).
+        "group-start": (event) => {
+          content(event);
+          depth = event.depth + 1;
+          out +=
+            '<div class="q-group' +
+            (event.break || event.reset ? " q-break" : "") +
+            '"' +
+            ' data-group="' +
+            esc(event.name) +
+            '">';
+          // Declared after the container the instance itself sits in opened,
+          // so a count on this group columns what it brackets rather than
+          // what brackets it.
+          if (event.columns) region = { count: event.columns, owner: event.depth, open: false };
+        },
+        "group-end": (event) => {
+          // The instance that owes or holds the columns is the one ending here:
+          // it closes the container and forgets the count, so nothing later
+          // can reopen one on its behalf.
+          if (region && region.owner === event.depth) {
+            close();
+            region = null;
+          }
+          depth = event.depth;
+          out += "</div>";
+        },
+        "table-start": (event) => {
+          content(event);
+          tfoot = false;
+          let cols = "";
+          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);
+          out +=
+            '<table class="q-table">' +
+            "<colgroup>" +
+            cols +
+            "</colgroup>" +
+            "<thead><tr>" +
+            cells(headers, "th") +
+            "</tr></thead><tbody>";
+        },
+        row: (event) => {
+          out += "<tr" + styleAttr(event) + ">" + cells(event.cells, "td") + "</tr>";
+        },
+        "total-row": (event) => {
+          tfoot = true;
+          out += "</tbody><tfoot><tr>" + cells(event.cells, "td") + "</tr></tfoot>";
+        },
+        "table-end": () => {
+          out += tfoot ? "</table>" : "</tbody></table>";
+        },
+      });
+      // A root region reaches here open when no full-width footer followed the
+      // body it columns.
+      close();
+      return out;
+    },
+  };
+}

package/lib/style.css

@@ -0,0 +1,102 @@
+/*
+ * The reference stylesheet for a quario HTML fragment: the default look this
+ * target deliberately does not put in the markup.
+ *
+ * `@quario/html` supplies no omakase defaults of its own -- an inline
+ * `style` attribute would beat a host's stylesheet in the cascade and force
+ * `!important` on anyone restyling a default they never asked for. That rule
+ * is about where the bytes land, not about leaving the seam empty, so the
+ * defaults ship here instead: ordinary rules on the stable `q-*` classes,
+ * which any host rule of equal specificity overrides by source order alone.
+ * See docs/adr/0016-the-default-look-ships-as-a-stylesheet.md and
+ * docs/adr/0014-a-target-supplies-defaults-only-where-its-consumer-has-no-seam.md.
+ *
+ * The selector contract is normative (SCHEMA.md, "The HTML target"); these
+ * rules are not. They are a reference default -- adjust freely, or never link
+ * this file at all.
+ *
+ * The block between the `shared:` markers below is byte-identical to the one
+ * in `packages/viewer/lib/style.js`, which the viewer adopts into its shadow
+ * root. The two cannot be single-sourced -- the viewer imports no target
+ * package -- so `test/stylesheet.test.js` at the repo root fails when they
+ * drift. Edit one, edit the other.
+ */
+
+/* shared:start */
+.q-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.q-table th,
+.q-table td {
+  padding: 2pt 6pt;
+  text-align: left;
+}
+
+.q-table thead th {
+  border-bottom: 0.5pt solid #000;
+}
+
+.q-table tfoot td {
+  border-top: 0.5pt solid #000;
+  font-weight: bold;
+}
+
+.q-item.q-report-header {
+  font-size: 14pt;
+  font-weight: bold;
+}
+
+.q-item.q-group-header {
+  margin-top: 8pt;
+  font-weight: bold;
+}
+
+.q-item.q-group-footer {
+  margin-bottom: 8pt;
+}
+
+.q-item.q-report-footer {
+  margin-top: 10pt;
+  border-top: 1pt solid #000;
+  padding-top: 4pt;
+}
+
+/* A columned container is a fragmentation context on screen, not only in
+   print, so this is what keeps a label whole in one page column -- the rule
+   SCHEMA.md's "Page columns" leans on. Scoped to a columned region, so an
+   uncolumned report pays nothing. Inside the shared block because both sheets
+   need it: a sheet has no pages, but it can have columns. */
+.q-columns .q-group {
+  break-inside: avoid;
+}
+/* shared:end */
+
+/*
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+.q-table thead {
+  display: table-header-group;
+}
+
+.q-table tr {
+  break-inside: avoid;
+}
+
+.q-group {
+  break-inside: avoid;
+}
+
+.q-break {
+  break-before: page;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@quario/html",
+  "version": "0.1.0",
+  "description": "The HTML render target for quario — in the makings, not yet released",
+  "homepage": "https://getquario.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/html"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./style.css": "./lib/style.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "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",
+    "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.1.0",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "quario": "^0.1.0"
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "limit": "1.7 kB",
+      "ignore": [
+        "quario"
+      ]
+    },
+    {
+      "path": "lib/style.css",
+      "limit": "1 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}