qa-engineer 0.9.2 → 0.11.0

package/packages/engine/lib/report/components/findings.mjs

@@ -0,0 +1,258 @@
+// The finding card — the unit of the report a developer actually works from.
+//
+// ## Collapsed by default, and why the summary has to carry weight
+//
+// A report with twenty findings expanded is a wall nobody reads. Collapsed, the
+// summary row is all most readers ever see, so it carries the four things needed to
+// triage without opening anything: severity, what is wrong, where, and whether it was
+// confirmed. Everything else lives inside.
+//
+// `<details>` rather than a JavaScript accordion: it opens with no script, it is
+// keyboard-operable and screen-reader-announced for free, and Ctrl-F finds text inside
+// a closed one in Chrome. The print stylesheet forces every one open, because a
+// printed report of collapsed headings is a printed table of contents.
+//
+// ## The order of the body
+//
+//   what happens now → what should happen → why it matters → how to see it
+//   → why it happens → how to fix it → what to re-test → the proof
+//
+// A reader who stops one third of the way down still has the defect, the gap, and the
+// business consequence. Root cause and fix direction come after that, because they are
+// what an engineer needs and the first three are what everyone needs.
+
+import {
+  e, slug, severityBadge, statusPill, chip, icon, plural,
+} from './primitives.mjs';
+import { evidenceGrid } from './evidence.mjs';
+import { SEVERITY } from '../theme/tokens.mjs';
+
+const DIMENSION_LABEL = Object.freeze({
+  functional: 'Functionality',
+  api: 'API',
+  performance: 'Performance',
+  security: 'Security',
+  ui: 'UI',
+  ux: 'UX',
+  data: 'Data',
+  accessibility: 'Accessibility',
+  console: 'Console',
+});
+
+const STATUS_LABEL = Object.freeze({
+  confirmed: 'Confirmed',
+  'validated-user-report': 'Validated user report',
+  'could-not-reproduce': 'Could not reproduce',
+  partial: 'Partially reproduced',
+  'fixed-in-run': 'Fixed during the run',
+});
+
+const LAYER_LABEL = Object.freeze({
+  frontend: 'Frontend',
+  backend: 'Backend',
+  network: 'Network',
+  data: 'Data',
+  infrastructure: 'Infrastructure',
+  'third-party': 'Third party',
+  unknown: 'Unknown',
+});
+
+export function dimensionLabel(dimension) {
+  return DIMENSION_LABEL[dimension] ?? dimension ?? '';
+}
+
+export function findingAnchor(id) {
+  return slug(id, 'f-');
+}
+
+/**
+ * Reproduction as steps when the run recorded steps, as prose otherwise.
+ *
+ * `steps[]` is the contract's structured form and is used when present. Failing that,
+ * numbered prose is split on its own numbering — nothing invented, nothing reordered.
+ * Unnumbered prose is left exactly as written, because guessing sentence boundaries in
+ * a repro turns "click Save. Wait 3s." into two steps that are really one.
+ */
+function reproBlock(finding) {
+  if (Array.isArray(finding.steps) && finding.steps.length > 0) {
+    return `<ol class="steps">${finding.steps.map((step) => `<li>${e(step)}</li>`).join('')}</ol>`;
+  }
+  const text = String(finding.repro ?? '').trim();
+  if (!text) return '<span class="empty">Not recorded</span>';
+
+  let lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (lines.length === 1) {
+    lines = text.split(/\s+(?=\d+[.)]\s)/).map((part) => part.trim()).filter(Boolean);
+  }
+  if (lines.length < 2 || !lines.every((line) => /^\d+[.)]\s/.test(line))) {
+    return e(text);
+  }
+  const steps = lines.map((line) => line.replace(/^\d+[.)]\s*/, ''));
+  return `<ol class="steps">${steps.map((step) => `<li>${e(step)}</li>`).join('')}</ol>`;
+}
+
+/** A labelled row in the behaviour list. */
+function row(term, body, railClass = null) {
+  if (!body) return '';
+  return `<dt>${e(term)}</dt><dd${railClass ? ` class="rail ${railClass}"` : ''}>${body}</dd>`;
+}
+
+/** The metrics table that turns "slow" into a number with a budget beside it. */
+function metricsPanel(metrics) {
+  if (!metrics || metrics.length === 0) return '';
+  const rows = metrics
+    .map(
+      (metric) =>
+        '<tr>' +
+        `<td>${e(metric.label)}</td>` +
+        `<td class="num"${metric.breached ? ' style="color:var(--sev-solid);font-weight:650"' : ''}>` +
+        `${e(metric.value)}</td>` +
+        `<td class="num muted">${e(metric.budget ?? '—')}</td>` +
+        '</tr>',
+    )
+    .join('');
+  return (
+    '<div class="table-wrap" style="margin-top:1rem"><table>' +
+    '<thead><tr><th>Measurement</th><th class="num">Observed</th><th class="num">Budget</th></tr></thead>' +
+    `<tbody>${rows}</tbody></table></div>`
+  );
+}
+
+/** Root cause: the investigation, rendered as a causal chain rather than a paragraph. */
+function rootCausePanel(rootCause) {
+  if (!rootCause?.summary) return '';
+  const chain =
+    Array.isArray(rootCause.chain) && rootCause.chain.length > 0
+      ? `<ol class="chain" style="margin-top:.5rem">${rootCause.chain.map((step) => `<li>${e(step)}</li>`).join('')}</ol>`
+      : '';
+  const meta = [
+    rootCause.layer ? chip(LAYER_LABEL[rootCause.layer] ?? rootCause.layer) : '',
+    Number.isFinite(rootCause.confidence)
+      ? chip(`${Math.round(rootCause.confidence * 100)}% confidence`)
+      : '',
+  ]
+    .filter(Boolean)
+    .join('');
+  return (
+    `<div>${e(rootCause.summary)}${chain}` +
+    (meta ? `<div style="margin-top:.5rem;display:flex;gap:.375rem;flex-wrap:wrap">${meta}</div>` : '') +
+    '</div>'
+  );
+}
+
+/** What QA re-runs once the fix lands — the half of a bug report that usually goes missing. */
+function regressionPanel(regression) {
+  if (!regression?.level) return '';
+  const tone = { high: 'critical', medium: 'medium', low: 'low' }[regression.level] ?? 'low';
+  const retest =
+    Array.isArray(regression.retest) && regression.retest.length > 0
+      ? `<ul class="clean" style="margin-top:.5rem">${regression.retest.map((item) => `<li>${e(item)}</li>`).join('')}</ul>`
+      : '';
+  return (
+    `<div><span class="badge sev-${tone}">${e(regression.level)} risk</span>` +
+    (regression.note ? `<div style="margin-top:.375rem">${e(regression.note)}</div>` : '') +
+    retest +
+    '</div>'
+  );
+}
+
+/**
+ * One finding, collapsed.
+ *
+ * `data-*` attributes on the element carry everything the client-side filter needs, so
+ * search and severity filtering run without a second copy of the findings in a script
+ * block — the DOM is the index.
+ */
+export function findingCard(finding, registry, { open = false } = {}) {
+  const severity = SEVERITY[finding.severity] ? finding.severity : 'low';
+  const anchor = findingAnchor(finding.id);
+  const tags = Array.isArray(finding.tags) ? finding.tags : [];
+
+  // Everything a reader might type into the search box, flattened once at render time.
+  const haystack = [
+    finding.id, finding.title, finding.actual, finding.expected, finding.fixDirection,
+    finding.businessImpact, finding.developerNotes, finding.page,
+    finding.rootCause?.summary, dimensionLabel(finding.dimension),
+    ...tags, ...(finding.affectedApis ?? []),
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+
+  const meta = [
+    `<span class="finding-id">${e(finding.id)}</span>`,
+    chip(dimensionLabel(finding.dimension)),
+    statusPill(finding.status, STATUS_LABEL[finding.status] ?? finding.status),
+    finding.page ? chip(finding.page) : '',
+    ...tags.map((tag) => chip(tag)),
+  ]
+    .filter(Boolean)
+    .join('');
+
+  const body = [
+    '<dl class="behaviour">',
+    row('Current behaviour', e(finding.actual), 'rail-now'),
+    row('Expected behaviour', e(finding.expected), 'rail-want'),
+    row('Business impact', finding.businessImpact ? e(finding.businessImpact) : '', 'rail-impact'),
+    row('Reproduction', reproBlock(finding)),
+    row('Root cause', rootCausePanel(finding.rootCause), 'rail-cause'),
+    row('Suggested fix', e(finding.fixDirection), 'rail-fix'),
+    row('Regression risk', regressionPanel(finding.regressionRisk)),
+    row(
+      'Affected APIs',
+      (finding.affectedApis ?? []).map((api) => `<code>${e(api)}</code>`).join(' '),
+    ),
+    row('Developer notes', finding.developerNotes ? e(finding.developerNotes) : ''),
+    '</dl>',
+    metricsPanel(finding.metrics),
+    evidenceGrid(finding.evidence, registry),
+  ].join('');
+
+  return (
+    `<details class="finding sev-${severity}" id="${e(anchor)}"${open ? ' open' : ''} ` +
+    `data-severity="${e(severity)}" data-dimension="${e(finding.dimension ?? '')}" ` +
+    `data-status="${e(finding.status ?? '')}" data-page="${e(finding.page ?? '')}" ` +
+    `data-tags="${e(tags.join(' '))}" data-search="${e(haystack)}">` +
+    '<summary>' +
+    severityBadge(severity) +
+    '<span class="finding-grow">' +
+    `<span class="finding-title">${e(finding.title)}</span>` +
+    `<span class="finding-meta">${meta}</span>` +
+    '</span>' +
+    `<span class="caret">${icon('chevron', 18)}</span>` +
+    '</summary>' +
+    `<div class="finding-body">${body}</div>` +
+    '</details>'
+  );
+}
+
+/** Every finding, worst first, with a stable tie-break so reruns diff cleanly. */
+export function findingList(findings, registry) {
+  const sorted = [...findings].sort((a, b) => {
+    const rank = (SEVERITY[a.severity] ?? SEVERITY.low).rank - (SEVERITY[b.severity] ?? SEVERITY.low).rank;
+    return rank !== 0 ? rank : String(a.id).localeCompare(String(b.id), 'en', { numeric: true });
+  });
+  if (sorted.length === 0) {
+    return '<div class="card"><div class="card-body empty">No findings recorded.</div></div>';
+  }
+  return (
+    sorted.map((finding) => findingCard(finding, registry)).join('') +
+    '<div class="no-results" id="no-results">' +
+    `<p><strong>Nothing matches those filters.</strong></p><p>${e(plural(sorted.length, 'finding'))} in total — ` +
+    'clear the search box or reset the severity filters to see them.</p></div>'
+  );
+}
+
+/** The severity legend, so a reader can calibrate without asking what "high" means. */
+export function severityLegend() {
+  const rows = Object.entries(SEVERITY)
+    .sort((a, b) => a[1].rank - b[1].rank)
+    .map(([key, value]) => `<tr><td>${severityBadge(key)}</td><td>${e(value.meaning)}</td></tr>`)
+    .join('');
+  return (
+    '<div class="table-wrap"><table><thead><tr><th>Severity</th><th>What it claims</th></tr></thead>' +
+    `<tbody>${rows}</tbody></table></div>`
+  );
+}
+
+export { STATUS_LABEL, DIMENSION_LABEL };

package/packages/engine/lib/report/components/nav.mjs

@@ -0,0 +1,99 @@
+// The sticky sidebar and the findings toolbar.
+//
+// A twelve-section report needs a map, and a report shared with six audiences needs a
+// way for each of them to reach their part of it: an engineering manager wants
+// Findings, a CTO wants Overview and Security, a designer wants Screenshots.
+//
+// Both controls degrade honestly. The sidebar is a list of in-page anchors, so it
+// works with scripting disabled and it prints as nothing (deliberately hidden). The
+// toolbar's search and filters need script, so they are rendered only when the report
+// has enough findings to be worth filtering, and the findings themselves are always
+// present in the document whether or not the toolbar ever runs.
+
+import { e, icon } from './primitives.mjs';
+import { SEVERITY, SEVERITY_ORDER } from '../theme/tokens.mjs';
+
+/** The sidebar: brand, then one anchor per section that has content. */
+export function sidebar(sections, { productName, subtitle }) {
+  const links = sections
+    .filter((section) => section.body)
+    .map(
+      (section) =>
+        `<a href="#${e(section.id)}" data-target="${e(section.id)}">` +
+        `<span>${e(section.navLabel ?? section.title)}</span>` +
+        (section.count === null || section.count === undefined
+          ? ''
+          : `<span class="n">${e(section.count)}</span>`) +
+        '</a>',
+    )
+    .join('');
+
+  return (
+    '<aside class="sidebar" aria-label="Report sections">' +
+    '<div class="sidebar-brand">' +
+    '<span class="sidebar-mark" aria-hidden="true">QA</span>' +
+    `<span><span class="sidebar-name">${e(productName)}</span>` +
+    `<br><span class="sidebar-sub">${e(subtitle)}</span></span>` +
+    '</div>' +
+    `<nav class="toc" aria-label="Sections">${links}</nav>` +
+    '</aside>'
+  );
+}
+
+/**
+ * Search, severity filters, expand/collapse, theme, print.
+ *
+ * The severity buttons start pressed — the default view is everything, and a filter
+ * that hides findings before the reader asks is how a report loses a critical.
+ */
+export function toolbar(counts, { dimensions = [] } = {}) {
+  const severityFilters = SEVERITY_ORDER.filter((key) => (counts[key] ?? 0) > 0)
+    .map(
+      (key) =>
+        `<button type="button" class="filter sev-${key}" data-filter="severity" data-value="${key}" ` +
+        `aria-pressed="true"><span class="dot"></span>${e(SEVERITY[key].label)} ` +
+        `<span class="tabular">${e(counts[key] ?? 0)}</span></button>`,
+    )
+    .join('');
+
+  const dimensionFilters = dimensions
+    .map(
+      (dimension) =>
+        `<button type="button" class="filter" data-filter="dimension" data-value="${e(dimension.key)}" ` +
+        `aria-pressed="true">${e(dimension.label)} <span class="tabular">${e(dimension.count)}</span></button>`,
+    )
+    .join('');
+
+  return (
+    '<div class="toolbar" role="search">' +
+    '<label class="search">' +
+    icon('search', 16) +
+    '<input type="search" id="finding-search" placeholder="Search findings, APIs, pages, root causes…" ' +
+    'autocomplete="off" aria-label="Search findings">' +
+    '</label>' +
+    `<div class="filters">${severityFilters}${dimensionFilters}</div>` +
+    '<span class="match-count" id="match-count" aria-live="polite"></span>' +
+    '<button type="button" class="iconbtn" id="toggle-all" title="Expand or collapse every finding" ' +
+    `aria-label="Expand or collapse every finding">${icon('expand', 16)}</button>` +
+    '<button type="button" class="iconbtn" id="toggle-theme" title="Switch between light and dark" ' +
+    `aria-label="Switch between light and dark">${icon('moon', 16)}</button>` +
+    '<button type="button" class="iconbtn" id="print-report" title="Print or save as PDF" ' +
+    `aria-label="Print or save as PDF">${icon('print', 16)}</button>` +
+    '</div>'
+  );
+}
+
+/** The lightbox shell. Empty until a screenshot is clicked. */
+export function lightbox() {
+  return (
+    '<div class="lightbox" id="lightbox" role="dialog" aria-modal="true" aria-label="Screenshot viewer" hidden>' +
+    '<div class="lightbox-bar">' +
+    '<span class="grow" id="lightbox-name"></span>' +
+    '<button type="button" id="lightbox-zoom">Zoom</button>' +
+    '<a id="lightbox-open" href="#" target="_blank" rel="noopener noreferrer">Open file</a>' +
+    `<button type="button" id="lightbox-close" aria-label="Close viewer">${icon('close', 16)}</button>` +
+    '</div>' +
+    '<img id="lightbox-img" alt="">' +
+    '</div>'
+  );
+}

package/packages/engine/lib/report/components/primitives.mjs

@@ -0,0 +1,246 @@
+// The small pieces every section is built from: escaping, formatting, badges, icons.
+//
+// Escaping lives here and is used everywhere, because a report renders text the run
+// did not author — page titles, console messages, response bodies, DOM excerpts. That
+// content is untrusted the same way a log line is untrusted, and a `<script>` in a
+// console error must reach the reader as characters, never as markup.
+
+import { SEVERITY, STATUS, VITALS, vitalBand, scoreBand } from '../theme/tokens.mjs';
+import { formatBytes } from '../../artifacts/mime.mjs';
+
+/** HTML-escape text for element content and quoted attribute values alike. */
+export function e(value) {
+  if (value === null || value === undefined) return '';
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+
+/**
+ * Escape for a JSON literal embedded in a `<script>` block.
+ *
+ * `JSON.stringify` alone is not enough: the string `</script>` inside any value ends
+ * the block early and drops the rest of the page into the document as markup. The
+ * `<` and `
`/`
` escapes close that off.
+ */
+export function jsonScript(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/** Join class names, dropping the falsy ones. */
+export function cx(...names) {
+  return names.filter(Boolean).join(' ');
+}
+
+/** An id safe to use as an anchor, derived from a finding or section key. */
+export function slug(value, prefix = '') {
+  const safe = [...String(value ?? '')]
+    .map((ch) => (/[\p{L}\p{N}]/u.test(ch) || ch === '-' || ch === '_' ? ch : '-'))
+    .join('')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  return safe ? `${prefix}${safe}` : '';
+}
+
+/** Sort TC-2 before TC-10, the way a reader expects a case list to run. */
+export function compareNatural(a, b) {
+  const key = (v) =>
+    String(v ?? '')
+      .split(/(\d+)/)
+      .map((part) => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : part.toLowerCase()));
+  const left = key(a);
+  const right = key(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const x = left[i];
+    const y = right[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x === y) continue;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** A severity badge. */
+export function severityBadge(severity) {
+  const key = SEVERITY[severity] ? severity : 'low';
+  return `<span class="badge sev-${key}">${e(SEVERITY[key].label)}</span>`;
+}
+
+/** A status pill — pass, fail, blocked, skipped, or a free-form label. */
+export function statusPill(status, label = null) {
+  const map = {
+    pass: 'passed', passed: 'passed', ok: 'passed', confirmed: 'failed',
+    fail: 'failed', failed: 'failed', issues: 'failed',
+    blocked: 'blocked', warn: 'blocked', warned: 'blocked',
+    skipped: 'skipped', 'not-checked': 'skipped',
+  };
+  const key = map[status] ?? 'neutral';
+  const text = label ?? STATUS[key]?.label ?? status;
+  return `<span class="pill st-${key}">${e(text)}</span>`;
+}
+
+/** A neutral chip for dimensions, tags, owners. */
+export function chip(text, title = null) {
+  if (!text) return '';
+  const attr = title ? ` title="${e(title)}"` : '';
+  return `<span class="chip"${attr}>${e(text)}</span>`;
+}
+
+/**
+ * A KPI tile.
+ *
+ * `variant` picks the accent: `sev-<key>` colours it by severity, `st-<key>` by test
+ * status. A zero gets muted deliberately — a wall of tiles where "0 critical" shouts
+ * as loudly as "3 critical" trains the reader to skip all of them.
+ */
+export function kpi({ value, label, sub = null, variant = null, zeroMuted = true }) {
+  const numeric = Number(value);
+  const isZero = zeroMuted && Number.isFinite(numeric) && numeric === 0;
+  const kind = variant?.startsWith('sev-') ? 'sev' : variant?.startsWith('st-') ? 'st' : '';
+  return (
+    `<div class="${cx('kpi', kind, variant, isZero && 'kpi-zero')}">` +
+    `<span class="kpi-n">${e(value)}</span>` +
+    `<span class="kpi-l">${e(label)}</span>` +
+    (sub ? `<span class="kpi-sub">${e(sub)}</span>` : '') +
+    '</div>'
+  );
+}
+
+/** A ring gauge for a 0–100 score, drawn as SVG so it survives print and PDF. */
+export function scoreGauge(score, label) {
+  const value = Math.max(0, Math.min(100, Math.round(Number(score))));
+  const band = scoreBand(value);
+  const radius = 20;
+  const circumference = 2 * Math.PI * radius;
+  const filled = (value / 100) * circumference;
+  return (
+    `<div class="score tone-${band}">` +
+    `<svg width="48" height="48" viewBox="0 0 48 48" role="img" ` +
+    `aria-label="${e(label)} score ${value} out of 100">` +
+    `<circle cx="24" cy="24" r="${radius}" fill="none" stroke="var(--border)" stroke-width="4"/>` +
+    `<circle cx="24" cy="24" r="${radius}" fill="none" stroke="var(--tone)" stroke-width="4" ` +
+    `stroke-linecap="round" stroke-dasharray="${filled.toFixed(2)} ${circumference.toFixed(2)}" ` +
+    'transform="rotate(-90 24 24)"/>' +
+    `<text x="24" y="24" text-anchor="middle" dominant-baseline="central" ` +
+    `font-size="14" font-weight="700" fill="var(--tone)">${value}</text>` +
+    '</svg>' +
+    `<div><div class="score-l">${e(label)}</div>` +
+    `<div class="score-b">${band === 'good' ? 'Good' : band === 'warn' ? 'Needs work' : 'Poor'}</div></div>` +
+    '</div>'
+  );
+}
+
+/** A duration in the largest unit that stays readable. */
+export function formatDuration(ms) {
+  const value = Number(ms);
+  if (!Number.isFinite(value) || value < 0) return '';
+  if (value < 1000) return `${Math.round(value)} ms`;
+  if (value < 60_000) return `${(value / 1000).toFixed(value < 10_000 ? 2 : 1)} s`;
+  const minutes = Math.floor(value / 60_000);
+  const seconds = Math.round((value % 60_000) / 1000);
+  return seconds ? `${minutes} m ${seconds} s` : `${minutes} m`;
+}
+
+/** A count with its noun, pluralised. */
+export function plural(count, singular, pluralForm = null) {
+  const n = Number(count) || 0;
+  return `${n} ${n === 1 ? singular : pluralForm ?? `${singular}s`}`;
+}
+
+export { formatBytes };
+
+/** Render one Core Web Vital as a tile whose colour states whether it is acceptable. */
+export function vitalTile(key, value) {
+  const spec = VITALS[key];
+  if (!spec || value === null || value === undefined) return '';
+  const band = vitalBand(key, value);
+  const shown =
+    spec.unit === 'bytes'
+      ? formatBytes(value)
+      : spec.unit === 'ms'
+        ? formatDuration(value)
+        : String(Number(value).toFixed(key === 'cls' ? 3 : 0));
+  return (
+    `<div class="kpi tone-${band}" style="--kpi-accent:var(--tone)" title="${e(spec.full)} — ${e(spec.plain)}">` +
+    `<span class="kpi-n" style="color:var(--tone)">${e(shown)}</span>` +
+    `<span class="kpi-l">${e(spec.label)}</span>` +
+    `<span class="kpi-sub">${e(spec.plain)}</span>` +
+    '</div>'
+  );
+}
+
+/**
+ * Inline SVG icons.
+ *
+ * Inline because the report has no second file to fetch, and an icon font would be a
+ * remote asset. Every one is 16×16 on a 24-unit grid, stroked with `currentColor` so
+ * it inherits the surrounding text colour in both themes.
+ */
+const ICON_PATHS = {
+  search: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/>',
+  chevron: '<path d="m9 6 6 6-6 6"/>',
+  sun: '<circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2M2 12h2m16 0h2M4.9 4.9l1.4 1.4m11.4 11.4 1.4 1.4M19.1 4.9l-1.4 1.4M6.3 17.7l-1.4 1.4"/>',
+  moon: '<path d="M20 14.5A8.5 8.5 0 0 1 9.5 4a8.5 8.5 0 1 0 10.5 10.5Z"/>',
+  expand: '<path d="M4 9V4h5M20 15v5h-5M15 4h5v5M9 20H4v-5"/>',
+  print: '<path d="M6 9V3h12v6M6 18H4v-6h16v6h-2M8 14h8v7H8z"/>',
+  warning: '<path d="M12 3 2 20h20L12 3Z"/><path d="M12 9v5m0 3v.5"/>',
+  file: '<path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8Z"/><path d="M14 3v5h5"/>',
+  close: '<path d="M6 6 18 18M18 6 6 18"/>',
+  zoom: '<circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5M11 8v6M8 11h6"/>',
+};
+
+export function icon(name, size = 16) {
+  const body = ICON_PATHS[name];
+  if (!body) return '';
+  return (
+    `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" ` +
+    'stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" ' +
+    `aria-hidden="true" focusable="false">${body}</svg>`
+  );
+}
+
+/** A `<section>` with a heading, an anchor, and an optional count badge. */
+export function section({ id, title, count = null, note = null, body }) {
+  if (!body) return '';
+  const badge = count === null ? '' : `<span class="count">${e(count)}</span>`;
+  return (
+    `<section class="section" id="${e(id)}" aria-labelledby="${e(id)}-h">` +
+    `<h2 id="${e(id)}-h">${e(title)}${badge}</h2>` +
+    (note ? `<p class="section-note">${e(note)}</p>` : '') +
+    body +
+    '</section>'
+  );
+}
+
+/** A table wrapped so wide content scrolls inside its own box, never the page. */
+export function table(headers, rows, { className = '' } = {}) {
+  if (rows.length === 0) return '';
+  const head = headers
+    .map((header) => {
+      const label = typeof header === 'string' ? header : header.label;
+      const numeric = typeof header === 'object' && header.numeric;
+      return `<th${numeric ? ' class="num"' : ''}>${e(label)}</th>`;
+    })
+    .join('');
+  return (
+    `<div class="table-wrap ${e(className)}"><table><thead><tr>${head}</tr></thead>` +
+    `<tbody>${rows.join('')}</tbody></table></div>`
+  );
+}
+
+/** A proportional bar for a table cell — payload size, duration, request share. */
+export function barCell(value, max, { colour = null, label = null } = {}) {
+  const ratio = max > 0 ? Math.max(0, Math.min(1, Number(value) / max)) : 0;
+  const style = colour ? ` style="--bar:${colour}"` : '';
+  return (
+    `<td class="bar-cell">${label === null ? '' : `<div class="tabular" style="margin-bottom:.25rem">${e(label)}</div>`}` +
+    `<div class="bar"${style}><span style="width:${(ratio * 100).toFixed(1)}%"></span></div></td>`
+  );
+}