@ponchia/ui 0.6.3 → 0.6.4

package/dist/css/table.css

@@ -1 +1 @@
-@layer bronto{.ui-table-wrap{border: 1px solid var(--line);border-radius: var(--radius-md);overflow: auto}.ui-table{border-collapse: collapse;font-family: var(--mono);font-size: var(--text-sm);min-inline-size: 100%;inline-size: 100%}.ui-table th,.ui-table td{border-block-end: 1px solid var(--line);overflow-wrap: anywhere;padding: 0.7rem 0.85rem;text-align: start;vertical-align: top}.ui-table th{background: var(--panel);color: var(--text-dim);font-size: var(--text-2xs);font-weight: 700;letter-spacing: var(--tracking-wide);position: sticky;text-transform: uppercase;inset-block-start: 0;z-index: 1}.ui-table td{color: var(--text-soft)}.ui-table tbody tr:last-child td{border-block-end: 0}.ui-table tbody tr{transition: background-color var(--duration-fast) var(--ease-standard)}@media (hover: hover){.ui-table tbody tr:hover td{background: var(--bg-accent)}}.ui-table--dense th,.ui-table--dense td{font-size: var(--text-xs);padding: 0.42rem 0.6rem}.ui-table--comfortable th,.ui-table--comfortable td{padding: 0.95rem 1.1rem}.ui-table--lined td{border-inline-end: 1px solid var(--line)}.ui-table--lined td:last-child{border-inline-end: 0}.ui-table .is-num,.ui-table th.is-num{font-variant-numeric: tabular-nums;text-align: end}.ui-table .is-pos{color: var(--success)}.ui-table .is-neg{color: var(--danger)}.ui-table .is-key{color: var(--text);font-weight: 600}.ui-table__empty td{color: var(--text-dim);padding: 2rem;text-align: center}.ui-table__sort{align-items: center;background: none;border: 0;color: inherit;cursor: pointer;display: flex;font: inherit;gap: 0.4rem;letter-spacing: inherit;padding: 0;text-transform: inherit;inline-size: 100%}.ui-table__sort::after{content: '↕';opacity: 0.4}.ui-table th[aria-sort='ascending'] .ui-table__sort::after{content: '↑';opacity: 1}.ui-table th[aria-sort='descending'] .ui-table__sort::after{content: '↓';opacity: 1}.ui-table__select{inline-size: 1px;white-space: nowrap}.ui-table--selectable tbody tr[aria-selected='true'] td{background: var(--bg-accent)}.ui-table__toolbar{align-items: center;border: 1px solid var(--line);border-block-end: 0;border-start-start-radius: var(--radius-md);border-start-end-radius: var(--radius-md);display: flex;gap: var(--space-sm);padding: var(--space-sm) var(--space-md)}.ui-table-wrap--loading{opacity: 0.6;pointer-events: none}}
+@layer bronto{.ui-table-wrap{border: 1px solid var(--line);border-radius: var(--radius-md);overflow: auto}.ui-table{border-collapse: collapse;font-family: var(--mono);font-size: var(--text-sm);min-inline-size: 100%;inline-size: 100%}.ui-table th,.ui-table td{border-block-end: 1px solid var(--line);overflow-wrap: break-word;padding: 0.7rem 0.85rem;text-align: start;vertical-align: top;word-break: normal}.ui-table th{background: var(--panel);color: var(--text-dim);font-size: var(--text-2xs);font-weight: 700;letter-spacing: var(--tracking-wide);position: sticky;text-transform: uppercase;inset-block-start: 0;z-index: 1}.ui-table td{color: var(--text-soft)}.ui-table tbody tr:last-child td{border-block-end: 0}.ui-table tbody tr{transition: background-color var(--duration-fast) var(--ease-standard)}@media (hover: hover){.ui-table tbody tr:hover td{background: var(--bg-accent)}}.ui-table--dense th,.ui-table--dense td{font-size: var(--text-xs);padding: 0.42rem 0.6rem}.ui-table--comfortable th,.ui-table--comfortable td{padding: 0.95rem 1.1rem}.ui-table--lined td{border-inline-end: 1px solid var(--line)}.ui-table--lined td:last-child{border-inline-end: 0}.ui-table--break-anywhere th,.ui-table--break-anywhere td{overflow-wrap: anywhere}.ui-table .is-num,.ui-table th.is-num{font-variant-numeric: tabular-nums;text-align: end}.ui-table .is-pos{color: var(--success)}.ui-table .is-neg{color: var(--danger)}.ui-table .is-key{color: var(--text);font-weight: 600}.ui-table__empty td{color: var(--text-dim);padding: 2rem;text-align: center}.ui-table__sort{align-items: center;background: none;border: 0;color: inherit;cursor: pointer;display: flex;font: inherit;gap: 0.4rem;letter-spacing: inherit;padding: 0;text-transform: inherit;inline-size: 100%}.ui-table__sort::after{content: '↕';opacity: 0.4}.ui-table th[aria-sort='ascending'] .ui-table__sort::after{content: '↑';opacity: 1}.ui-table th[aria-sort='descending'] .ui-table__sort::after{content: '↓';opacity: 1}.ui-table__select{inline-size: 1px;white-space: nowrap}.ui-table--selectable tbody tr[aria-selected='true'] td{background: var(--bg-accent)}.ui-table__toolbar{align-items: center;border: 1px solid var(--line);border-block-end: 0;border-start-start-radius: var(--radius-md);border-start-end-radius: var(--radius-md);display: flex;gap: var(--space-sm);padding: var(--space-sm) var(--space-md)}.ui-table-wrap--loading{opacity: 0.6;pointer-events: none}}

package/docs/dots.md

@@ -0,0 +1,146 @@
+# Dot surfaces
+
+The dot-matrix is the library's signature: one lit/dim/accent dot vocabulary
+expressed across backgrounds, dividers, indicators, loaders, and a family of
+data-bound reporting surfaces. Everything here lives in the core stylesheet
+(`@ponchia/ui` / `@ponchia/ui/css`); the glyph icon set built on the same
+primitive is documented in `docs/glyphs.md`.
+
+All classes are in the typed registry (`@ponchia/ui/classes`) and the
+language-neutral `classes.json`; those are authoritative.
+
+## Tokens
+
+Density and expression are token-driven, so a surface re-skins without new CSS:
+
+| Token | Role |
+| --- | --- |
+| `--field-dot` | the dim (unlit) dot |
+| `--field-dot-hot` | a lit cell |
+| `--field-dot-accent` | the accented lit cell |
+| `--dot-gap` / `--dot-size` | `.ui-dotgrid` background density |
+| `--dotmatrix-cols` / `--dotmatrix-gap` / `--dotmatrix-dot` | matrix density |
+| `--dotmatrix-dot-radius` | `0` fuses dots into crisp pixels |
+
+The Tier-3 **display-expression** knobs speak in brightness + time rather than
+hue (a dot-matrix display has no decorative colour). They default to a no-op, so
+the base render is unchanged; the opt-in colorways (`@ponchia/ui/css/skins.css`)
+set them:
+
+| Knob | Default | Effect |
+| --- | --- | --- |
+| `--dotmatrix-glow` | `0` (off) | phosphor bloom around lit cells |
+| `--dotmatrix-pulse-min` | `0.55` | the floor the `--pulse` animation dips to |
+| `--dotmatrix-reveal-step` | `3ms` | per-cell cadence of the `--reveal` scan |
+
+## Decorative surfaces
+
+- `.ui-dotgrid` — a tiled dot-grid background (`--accent`, `--dense` modifiers).
+- `.ui-dotfield` — a fixed full-bleed dot backdrop.
+- `.ui-dotrule` — a dotted divider in place of a plain rule.
+- `.ui-halftone` — render host content (an `<img>` or a box with its own
+  background) through a dot lattice, so a thumbnail takes on the dot look. A
+  **style filter**, not a data viz — the dots are a fixed lattice, not
+  value-modulated. Tune with `--halftone-dot` / `--halftone-gap`.
+
+## Indicators & loaders
+
+- `.ui-dot` — a status dot with tones (`--accent/--success/--warning/--danger/--info`)
+  and a `--live` pulse ring; `.ui-status` is the dot + label row.
+- `.ui-dotloader` — three blinking dots.
+- `.ui-dotspinner` — the signature comet loader (`--sm` / `--lg`).
+- `.ui-dotbar` — a segmented LED progress bar; light a segment with `is-on`,
+  or `--indeterminate` for the sweep.
+
+## Data-bound reporting surfaces
+
+These map data onto the dot vocabulary. The boundary is the same as `ui-spark`
+and `ui-meter`: **the host normalises the data** (lights `is-on`, sets
+`data-level`, or writes `--v` 0..1) and the leaf only lays out + tones. None
+compute a scale, bin, or threshold. Each is opaque to assistive tech, so the
+container MUST carry a host-written `role="img"` + `aria-label` with the exact
+value — rounding to whole cells is presentation-only, so keep the figure in the
+label (WCAG 1.4.1).
+
+### `.ui-matrix` cell grid
+
+`.ui-dotmatrix` is the raw data-bound grid (the one the glyphs render on): a grid
+of `.ui-dotmatrix__cell` (with `--hot` / `--accent` tones) plus the `--reveal` /
+`--pulse` animations. You map data → cell class.
+
+### `.ui-waffle` — unit / part-to-whole
+
+An N×N field of dots ("73 of 100"). The host marks the lit cells with `is-on`.
+
+```html
+<div class="ui-waffle" role="img" aria-label="73 of 100 quota met" style="--waffle-cols: 10">
+  <i class="is-on"></i><i class="is-on"></i><!-- … 73 lit, 27 dim … --><i></i>
+</div>
+```
+
+Knobs: `--waffle-cols` (default 10), `--waffle-gap`, `--waffle-size`.
+
+### `.ui-activity` — contribution / calendar heatmap
+
+A GitHub-style density-over-time grid. Day cells flow down each weekday column
+(`grid-auto-flow: column`); intensity is `data-level="0..4"`, a 5-step ramp the
+host bins the data into.
+
+```html
+<div class="ui-activity" role="img" aria-label="commits, last 12 weeks">
+  <i data-level="0"></i><i data-level="3"></i><i data-level="4"></i><!-- … -->
+</div>
+```
+
+Knobs: `--activity-rows` (default 7), `--activity-cell`, `--activity-gap`.
+
+### `.ui-level` — LED level / VU meter
+
+A vertical column of discrete segments lit to a threshold (signal, load, VU). It
+fills from the bottom; the host lights segments with `is-on`. `--warn` /
+`--danger` re-point the lit colour for the whole meter when the host crosses a
+threshold (the host owns the threshold).
+
+```html
+<div class="ui-level ui-level--warn" role="img" aria-label="CPU 82%, high">
+  <i class="is-on"></i><i class="is-on"></i><i></i><!-- … --></div>
+```
+
+Knobs: `--level-segments` count is up to your markup; `--level-height`,
+`--level-size`, `--level-gap`.
+
+### `.ui-dotgauge` — radial dot gauge
+
+A 0..1 reading (`--v`) drawn as a ring of dots filling along an arc.
+
+```html
+<div class="ui-dotgauge" role="img" aria-label="Health 64%" style="--v: .64"></div>
+```
+
+Knobs: `--v`, `--gauge-size`, `--gauge-sweep` (default 270deg), `--gauge-from`,
+`--gauge-dot`.
+
+### `.ui-readout` — big dot-matrix numeric
+
+The row wrapper produced by `renderReadout` (see `docs/glyphs.md`) — a Nothing-style
+hero numeric composed from digit glyphs. Tune character spacing with
+`--readout-gap`; spaces render as a `.ui-readout__spacer` of width `--readout-space`.
+
+### `.ui-spark--dots`
+
+A modifier on the inline `ui-spark` dataword (`@ponchia/ui/css/spark.css`) that
+renders each bar as a stack of dots instead of a solid bar — same `--v` contract.
+
+## Responsive density — `.ui-dotfit`
+
+Wrap a dot surface in `.ui-dotfit` to make it respond to its **container** (the
+card) rather than the viewport, via a container query — so the same component
+reads well in a wide hero and a narrow tile without per-instance overrides.
+
+## Accessibility, forced colors & print
+
+Lit/dim/accent encode meaning via background-color, which Windows High Contrast
+Mode flattens — the dot surfaces opt out of forced-color remapping and pin lit
+states to distinct system colours (the activity ramp collapses to present vs
+absent). The data surfaces also set `print-color-adjust: exact` so their fills
+survive printing. Animations honour `prefers-reduced-motion`.

package/docs/glyphs.md

@@ -0,0 +1,114 @@
+# Display glyphs
+
+`@ponchia/ui/glyphs` is a small, frozen bitmap icon set rendered on the same
+`.ui-dotmatrix` dot primitive as every other dot surface (see `docs/dots.md`).
+CSS-first to the core: a glyph is just a grid of dot cells — `.` off, `#` hot,
+`*` accent — so it re-skins with the same `--field-dot*` tokens and the Tier-3
+display knobs as the rest of the dot family. No icon font, no SVG sprite, no
+runtime dependency. The module is side-effect-free and SSR-safe (`renderGlyph`
+returns a string; nothing touches the DOM).
+
+```js
+import { renderGlyph } from '@ponchia/ui/glyphs';
+el.innerHTML = renderGlyph('check', { label: 'Done' });
+```
+
+The authoritative API is the generated, CI-drift-checked `glyphs/glyphs.d.ts`.
+Read it before guessing a name — `GlyphName` is a literal union, so a typo is a
+type error.
+
+## Three render paths
+
+A glyph can be drawn three ways; pick by size regime.
+
+| Path | Call | DOM | When |
+| --- | --- | --- | --- |
+| Dot display | `renderGlyph(name)` | `GLYPH_SIZE²` cells (256) | the signature dot-matrix look at display sizes |
+| Solid pixel | `renderGlyph(name, { solid: true })` | 256 cells, fused | legible crisp icon at small/inline sizes (~16–24px) |
+| Mask icon | `renderGlyph(name, { render: 'mask' })` | **one** `.ui-icon` node | icon-at-scale (e.g. one per table row): inherits `currentColor`, scales with the text |
+
+The mask path is the lightest — one node instead of 256 — and the right default
+for an icon repeated many times. It is single-tone: an accent `*` cell renders
+the same as a hot `#` cell (both become opaque mask regions).
+
+> Pixel-crisp sizes: the bitmap is a 16-unit grid, so the dot/solid paths look
+> sharpest at integer multiples (16/32/48/64px). The mask path scales smoothly
+> with the text; arbitrary `em` sizes soften the edges slightly, which is fine
+> for inline use.
+
+### `renderGlyph(name, options)`
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `grid` | boolean | `true` | show the unlit panel dots; `false` → glyph-only |
+| `solid` | boolean | `false` | square, gapless pixels (implies glyph-only) |
+| `anim` | `'reveal' \| 'pulse'` | — | decorative animation (reduced-motion-safe) |
+| `label` | string | — | expose as `role="img"` with this name; omit → decorative (`aria-hidden`) |
+| `dot` | CSS length | `0.08em` | one dot size (`--dotmatrix-dot`; sanitized) |
+| `gap` | CSS length | — | gap between dots (`--dotmatrix-gap`; sanitized) |
+| `render` | `'mask'` | — | the one-node `.ui-icon` path |
+| `size` | CSS length | `1em` | with `render: 'mask'`, the icon size (`--icon-size`) |
+
+## Big numeric readout — `renderReadout`
+
+Compose digits and punctuation into a row of dot-matrix glyphs — the
+Nothing-style hero numeric for a KPI, clock, countdown, or percentage.
+
+```js
+import { renderReadout } from '@ponchia/ui/glyphs';
+el.innerHTML = renderReadout('12:48', { label: '12:48 remaining' });
+el.innerHTML = renderReadout('73%', { label: '73 percent of quota', render: 'mask' });
+```
+
+Recognised characters: `0-9`, `:`, `,`, `.`, `%`, `-`, `+`, and space (a blank
+advance). Anything else is skipped. Every per-glyph option (`solid`, `render`,
+`dot`, `gap`, `anim`) passes through to each character; `gap` sets the spacing
+between characters. The digits are decorative — the readout's **value** is its
+accessible name, so pass a `label` (it defaults to the raw text). Output wraps
+in `.ui-readout` (see `docs/dots.md`).
+
+## Finding a glyph — `findGlyphs` / `GLYPH_TAGS`
+
+Names follow the "depict, don't name the purpose" convention (`trash`, not
+`delete`). `findGlyphs(query)` resolves an intent word to real names by matching
+the name OR a curated search alias (`GLYPH_TAGS`), case-insensitively:
+
+```js
+import { findGlyphs } from '@ponchia/ui/glyphs';
+findGlyphs('delete'); // → ['trash']
+findGlyphs('chart'); // → ['bar-chart']
+findGlyphs(''); // → every name
+```
+
+## DOM placeholders — `initDotGlyph`
+
+When you would rather drop a placeholder than inline markup, the optional
+`initDotGlyph` behavior (`@ponchia/ui/behaviors`) expands
+`[data-bronto-glyph="name"]` in place. It is idempotent and returns a cleanup.
+
+| Attribute | Value | Effect |
+| --- | --- | --- |
+| `data-bronto-glyph` | glyph name | expand into a `.ui-dotmatrix` grid |
+| `data-bronto-glyph-label` | text | expose as `role="img"`; omit → decorative |
+| `data-bronto-glyph-solid` | — | square, gapless pixel glyph |
+| `data-bronto-glyph-anim` | `reveal \| pulse` | decorative animation |
+| `data-bronto-glyph-render` | `mask` | the one-node `.ui-icon` path (not 256 cells) |
+| `data-bronto-glyph-size` | CSS length | with `render="mask"`, sets `--icon-size` |
+
+An unknown name is left untouched.
+
+## Accessibility
+
+- A glyph next to a text label is redundant → keep it decorative (`aria-hidden`,
+  the default).
+- An icon-only control labels the **control** (`aria-label` on the `<button>`),
+  not the glyph.
+- A standalone meaningful glyph passes `label` → `role="img"` + `aria-label`.
+- A cell-mode glyph is a sea of 256 nodes; the wrapper carries the single
+  `role="img"`/`aria-hidden`, so assistive tech never walks the cells.
+
+## Two-tone glyphs
+
+The accent (`*`) tone lifts one feature of a glyph onto `--field-dot-accent`.
+The curated two-tone set is `spark`, `warning`, and `info`; every other glyph is
+monotone. Two-tone only shows in the cell render — the mask path is single-tone.

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 529 classes across 161 component groups
+- 540 classes across 167 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
   vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
@@ -31,6 +31,12 @@ each one matches a real selector in the stylesheet.
 | `cls.accordionItem` | `ui-accordion__item` | part |
 | `cls.accordionSummary` | `ui-accordion__summary` | part |
 
+### `.ui-activity`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.activity` | `ui-activity` | base |
+
 ### `.ui-alert`
 
 | Registry key | Class | Kind |
@@ -486,6 +492,18 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.dotfield` | `ui-dotfield` | base |
 
+### `.ui-dotfit`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.dotfit` | `ui-dotfit` | base |
+
+### `.ui-dotgauge`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.dotgauge` | `ui-dotgauge` | base |
+
 ### `.ui-dotgrid`
 
 | Registry key | Class | Kind |
@@ -580,6 +598,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.grid` | `ui-grid` | base |
 
+### `.ui-halftone`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.halftone` | `ui-halftone` | base |
+
 ### `.ui-hint`
 
 | Registry key | Class | Kind |
@@ -679,6 +703,14 @@ each one matches a real selector in the stylesheet.
 | `cls.legendVertical` | `ui-legend--vertical` | modifier |
 | `cls.legendWithValues` | `ui-legend--with-values` | modifier |
 
+### `.ui-level`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.level` | `ui-level` | base |
+| `cls.levelDanger` | `ui-level--danger` | modifier |
+| `cls.levelWarn` | `ui-level--warn` | modifier |
+
 ### `.ui-lightbox`
 
 | Registry key | Class | Kind |
@@ -893,6 +925,7 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.readout` | `ui-readout` | base |
+| `cls.readoutSpacer` | `ui-readout__spacer` | part |
 
 ### `.ui-reasoning`
 
@@ -1075,6 +1108,7 @@ each one matches a real selector in the stylesheet.
 | `cls.sparkBarAccent` | `ui-spark__bar--accent` | modifier |
 | `cls.sparkBarNeg` | `ui-spark__bar--neg` | modifier |
 | `cls.sparkBarPos` | `ui-spark__bar--pos` | modifier |
+| `cls.sparkDots` | `ui-spark--dots` | modifier |
 
 ### `.ui-spinner`
 
@@ -1204,6 +1238,7 @@ each one matches a real selector in the stylesheet.
 | `cls.tableSelect` | `ui-table__select` | part |
 | `cls.tableSort` | `ui-table__sort` | part |
 | `cls.tableToolbar` | `ui-table__toolbar` | part |
+| `cls.tableBreakAnywhere` | `ui-table--break-anywhere` | modifier |
 | `cls.tableComfortable` | `ui-table--comfortable` | modifier |
 | `cls.tableDense` | `ui-table--dense` | modifier |
 | `cls.tableLined` | `ui-table--lined` | modifier |
@@ -1356,6 +1391,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.vt` | `ui-vt` | base |
 
+### `.ui-waffle`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.waffle` | `ui-waffle` | base |
+
 ## Table-local state classes
 
 Not in `cls` by design — these are plain `is-*` state hooks scoped to

package/docs/reporting.md

@@ -37,11 +37,11 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -150,6 +150,10 @@ they are all safe in the static, PDF-first report path.
   `ui-alert` for persistent notices, `ui-table` for structured evidence,
   `ui-timeline` for events, `ui-meter` for measured values, and `ui-num` for
   non-table numeric values.
+- In alerts, put the readable message in `<p class="ui-alert__body">…</p>`
+  and use `ui-alert__title` only for a separate title line. `ui-alert` is a
+  grid with a leading status dot; raw text or loose inline children such as
+  `<strong>` / `<code>` become separate grid items and can fragment in print.
 - Give `ui-report__finding` blocks an accessible name so the visual grouping is
   also programmatic: point `aria-labelledby` at the block's `ui-eyebrow` label
   (give it an `id`), or lead with a real heading. Do the same for a
@@ -167,6 +171,10 @@ they are all safe in the static, PDF-first report path.
   inside `ui-prose`; use `.ui-table` for curated evidence tables. If a
   `ui-report__evidence` block contains only a `ui-table-wrap`, the report layer
   removes the inner frame so evidence tables do not look double-boxed.
+  Report tables preserve words by default so identifiers and headings do not
+  split into unreadable fragments in PDF. Add `ui-table--break-anywhere` only
+  for machine-token tables where avoiding horizontal overflow matters more than
+  preserving words.
 - Every `<figure>` should include a `figcaption` using `ui-report__caption`.
 - Do not use raw color values. Theme with `--accent`; use status tones for
   status; use chart tokens only in chart figures.
@@ -589,9 +597,10 @@ need a full automatable browser, only a Chromium-class layout+print pass.
 - **By hand:** open the report in Chrome/Edge → Print (Cmd/Ctrl+P) → "Save as
   PDF". In **More settings**, enable **Background graphics** (the dialog's
   equivalent of `printBackground` — without it chart fills and swatches drop
-  out), and pick the paper size there. Paper size is a browser print setting,
-  not a token; the layer only themes the page _margin_ via
-  `--report-page-margin`.
+  out), and pick the paper size there. Paper size and page margins are browser
+  print settings; the report stylesheet uses a fixed 18mm `@page` margin because
+  Chromium-class print engines do not reliably resolve custom properties inside
+  `@page` rules.
 - **Headless, lightweight:** use **`chrome-headless-shell`** — the minimal
   headless-Chromium binary built for exactly this, a fraction of a full
   browser's weight. Drive it through Playwright/Puppeteer (or raw CDP) and
@@ -662,3 +671,5 @@ Before returning a report, an LLM should verify:
 - No raw chromatic colors appear in inline styles.
 - No remote scripts, styles, iframes, or images are required for the report.
 - Generated/untrusted body HTML was sanitized before insertion.
+- Alert text is wrapped in `.ui-alert__body`; no loose text or inline-only
+  elements are direct children of `.ui-alert`.

package/glyphs/glyphs.d.ts

@@ -8,7 +8,9 @@ export type GlyphName =
   | 'arrow-left'
   | 'arrow-right'
   | 'arrow-up'
+  | 'bar-chart'
   | 'bell'
+  | 'calendar'
   | 'check'
   | 'check-circle'
   | 'chevron-down'
@@ -18,14 +20,30 @@ export type GlyphName =
   | 'circle'
   | 'clock'
   | 'close'
+  | 'colon'
+  | 'comma'
+  | 'copy'
+  | 'database'
+  | 'digit-0'
+  | 'digit-1'
+  | 'digit-2'
+  | 'digit-3'
+  | 'digit-4'
+  | 'digit-5'
+  | 'digit-6'
+  | 'digit-7'
+  | 'digit-8'
+  | 'digit-9'
   | 'download'
   | 'edit'
   | 'eye'
   | 'eye-off'
   | 'file'
+  | 'filter'
   | 'folder'
   | 'gear'
   | 'grid'
+  | 'hash'
   | 'heart'
   | 'home'
   | 'info'
@@ -39,11 +57,16 @@ export type GlyphName =
   | 'more-horizontal'
   | 'more-vertical'
   | 'pause'
+  | 'percent'
+  | 'period'
   | 'play'
   | 'plus'
   | 'plus-circle'
   | 'refresh'
   | 'search'
+  | 'share'
+  | 'sliders'
+  | 'sort'
   | 'spark'
   | 'star'
   | 'sun'
@@ -111,5 +134,43 @@ export declare function glyph(name: GlyphNameInput): Glyph | undefined;
 /** 256 cell descriptors (row-major), or `[]` if unknown. */
 export declare function glyphCells(name: GlyphNameInput): GlyphCell[];
 
+/** The CSS `mask-image` `url()` for a glyph (the `--icon-mask` value on a
+ *  `.ui-icon`), or `''` if unknown. Single-tone. */
+export declare function glyphMask(name: GlyphNameInput): string;
+
 /** A full `.ui-dotmatrix` HTML string for a glyph (`''` if unknown). */
 export declare function renderGlyph(name: GlyphNameInput, options?: RenderGlyphOptions): string;
+
+/** Hand-curated intent→glyph search aliases (e.g. `trash`→`delete`/`remove`).
+ *  Keys are real glyph names; values are extra search terms. */
+export declare const GLYPH_TAGS: Readonly<Partial<Record<GlyphName, readonly string[]>>>;
+
+/** Glyph names whose name OR a search alias contains `query` (case-insensitive),
+ *  sorted. `findGlyphs('')` returns every name. */
+export declare function findGlyphs(query: string): GlyphName[];
+
+/** Options for renderReadout. The per-glyph fields pass through to renderGlyph
+ *  for each character; `gap` sets `--readout-gap` on the row. */
+export interface RenderReadoutOptions {
+  /** Accessible name for the whole readout (defaults to the raw text). The dot
+   *  digits are decorative; this carries the real value. */
+  label?: string;
+  /** CSS length between characters (sets `--readout-gap`; sanitized). */
+  gap?: string;
+  /** Render each character as square gapless pixels (legible small). */
+  solid?: boolean;
+  /** Show the unlit panel dots behind each character (default true). */
+  grid?: boolean;
+  /** Decorative per-character animation (reduced-motion-safe). */
+  anim?: 'reveal' | 'pulse';
+  /** CSS length for one dot of each character (sets `--dotmatrix-dot`). */
+  dot?: string;
+  /** `'mask'` renders each character as a single `.ui-icon` node (lightest). */
+  render?: 'mask';
+  /** With `render: 'mask'`, the per-character icon size. */
+  size?: string;
+}
+
+/** A row of dot-matrix glyphs for a numeric string (digits + `: , . % - +` and
+ *  space) — the big Nothing-style readout. `''` for empty input. */
+export declare function renderReadout(text: string, options?: RenderReadoutOptions): string;