tuffgal 0.1.0-alpha.9 → 0.2.0-alpha.2

package/dist/reporter/template.js

@@ -6,6 +6,17 @@ const STATUS_LABELS = {
     skipped: 'skipped',
     new: 'new baseline',
 };
+/**
+ * The matcher token for a breakpoint bucket key, shared by the filter pills and
+ * the `[data-breakpoint]` hooks so a token always matches its container. The
+ * empty-string key (the defensive parse-guard bucket where a result carried no
+ * breakpoint) maps to the reserved `legacy` token — the same string
+ * {@link renderDeletedEntry} uses for the pre-breakpoint layout. Every other key
+ * is the real breakpoint name, passed through verbatim.
+ */
+function breakpointToken(key) {
+    return key === '' ? 'legacy' : key;
+}
 const STATUS_MARKERS = {
     pass: '✓',
     changed: '~',
@@ -17,8 +28,15 @@ const STATUS_MARKERS = {
  * Static HTML report. Rocks a terminal, dev-tool aesthetic. Dark mode by
  * default, monospace font for data, sharp borders, and minimal but
  * evocative icons + neon colors to indicate statuses.
+ *
+ * `<main>` reading order: an optional environment-mismatch banner (first, only
+ * when `environment.mismatch`), then the summary, the stories, and an optional
+ * deleted (orphaned-baseline) section last. The banner and deleted section are
+ * peer `<h2>` landmarks; the two supplementary per-action notes (candidate /
+ * a11y-drift) contribute no heading levels, so the outline stays
+ * H1 → summary → stories → deleted.
  */
-export function renderReport(result, reportDir) {
+export function renderReport(result, reportDir, interactiveMode = false) {
     const dateLabel = formatDate(result.finishedAt);
     return `
 <!doctype html>
@@ -40,98 +58,258 @@ export function renderReport(result, reportDir) {
       </p>
     </header>
     <main id="main" tabindex="-1">
+      ${renderEnvMismatch(result)}
       ${renderSummary(result)}
-      ${renderStories(result, reportDir)}
+      ${renderStories(result, reportDir, interactiveMode)}
+      ${renderDeleted(result)}
     </main>
     <script src="assets/report.js"></script>
   </body>
 </html>
 `;
 }
+/**
+ * The status totals double as the report's filter controls: each is a native
+ * `<button aria-pressed>` single-select filter, with the "stories" total acting
+ * as the "show all / clear" control (pressed by default). The expand-all /
+ * collapse-all pair sits at the right end of the same row — the slot the old
+ * coverage stats used to occupy. The `<ul>` stays a plain list (no composite
+ * role): a non-filter total and the bulk-toggle group share it, so a
+ * radiogroup/fieldset could not cleanly scope just the filters.
+ *
+ * A second, independent filter dimension — the breakpoint filter — renders
+ * BELOW the totals row inside this same summary region (see
+ * {@link renderBreakpointFilters}), but only when the run spans two or more
+ * distinct breakpoints. The two dimensions are ANDed by report.js.
+ */
 function renderSummary(result) {
-    const screens = result.customCoverage.screens;
-    const flows = result.customCoverage.flows;
     return `
 <section class="summary" aria-labelledby="summary-heading">
   <h2 id="summary-heading">summary</h2>
   <ul class="summary-list" aria-label="Run totals">
-    ${summaryItem('stories', result.totals.stories)}
-    ${summaryItem('passed', result.totals.passed, 'pass')}
-    ${summaryItem('changed', result.totals.changed, 'changed')}
-    ${summaryItem('failed', result.totals.failed, 'failed')}
-    ${coverageItem('screens', screens)}
-    ${coverageItem('flows', flows)}
+    ${summaryFilter('stories', result.totals.stories, 'all', true, ' — show all stories')}
+    ${summaryFilter('passed', result.totals.passed, 'pass', false, ', show only passed stories')}
+    ${summaryFilter('new', result.totals.new, 'new', false, ', show only new stories')}
+    ${summaryFilter('changed', result.totals.changed, 'changed', false, ', show only changed stories')}
+    ${summaryFilter('failed', result.totals.failed, 'failed', false, ', show only failed stories')}
+    <li class="story-bulk-toggle">
+      <button type="button" class="story-bulk-toggle-button" data-bulk-toggle="expand"><span class="bulk-verb">Expand</span><span class="bulk-scope-sr sr-only"> all screenshots</span></button>
+      <span class="bulk-sep" aria-hidden="true">/</span>
+      <button type="button" class="story-bulk-toggle-button" data-bulk-toggle="collapse"><span class="bulk-verb">Collapse</span><span class="bulk-scope-sr sr-only"> all screenshots</span></button>
+      <span class="bulk-scope" aria-hidden="true">screenshots</span>
+    </li>
   </ul>
+  ${renderBreakpointFilters(result)}
 </section>
 `;
 }
-function coverageItem(label, metric) {
-    const pct = `${(metric.ratio * 100).toFixed(0)}%`;
+/**
+ * The distinct breakpoints a run spanned, in first-seen order across every
+ * story's flat action array — the SAME order {@link renderStoryActions} buckets
+ * a single story's groups in, extended across stories. Each distinct breakpoint
+ * carries the capture dimensions of the FIRST action seen at it (the same source
+ * {@link renderBreakpointGroup} labels a group with), so the filter pill can
+ * echo the size.
+ *
+ * The bucket KEY is `action.breakpoint ?? ''` — identical to
+ * {@link renderStoryActions}, so a filter token always matches a rendered
+ * `[data-breakpoint]` container. The empty-string key is a defensive parse-guard
+ * only (the runner always tags a real breakpoint name); it maps to the reserved
+ * `legacy` token/label. A live `ActionResult` never carries the literal
+ * `'legacy'` breakpoint — that synthetic name is confined to orphaned-baseline
+ * (`deleted`) entries — so the empty-string bucket and a real `legacy` bucket
+ * cannot collide within one run's stories.
+ */
+function distinctBreakpoints(result) {
+    const seen = new Set();
+    const distinct = [];
+    for (const story of result.stories) {
+        for (const action of story.actions) {
+            const key = action.breakpoint ?? '';
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            distinct.push({
+                key,
+                width: action.breakpointWidth,
+                height: action.breakpointHeight,
+            });
+        }
+    }
+    return distinct;
+}
+/**
+ * The breakpoint filter group: a second single-select filter dimension, sibling
+ * to the status totals inside the summary region. Rendered ONLY when the run
+ * spans two or more distinct breakpoints — a single-breakpoint run makes the
+ * filter a no-op, so the whole group is omitted.
+ *
+ * Each pill is a native `<button aria-pressed>` toggle (like the status filter),
+ * grouped in a `role="group"` with an accessible label so assistive tech reads
+ * the two rows as distinct filter axes. A leading "all breakpoints" reset is
+ * pressed by default and clears the dimension. The neutral palette (outline
+ * default, filled + bold when pressed) carries no status hue, so the two rows
+ * read as siblings without implying a status.
+ *
+ * The visible `.indicator` carries the human LABEL (breakpoint name + decorative
+ * dimensions), while `data-breakpoint-filter` carries the MATCHER TOKEN (the
+ * exact bucket key). report.js echoes the label, matches on the token against a
+ * container's `data-breakpoint`. The blank-bucket token/label is `legacy` (with
+ * the shared "(pre-breakpoint layout)" sr-only clarifier); every other token is
+ * the real breakpoint name. Dimensions reuse the exact idiom of
+ * {@link renderBreakpointGroup}: a decorative aria-hidden `375×667` plus an
+ * sr-only `375 by 667 pixels` longhand so the `×` glyph is never read as "x".
+ */
+function renderBreakpointFilters(result) {
+    const distinct = distinctBreakpoints(result);
+    if (distinct.length < 2) {
+        return '';
+    }
+    const pills = distinct.map((bp) => breakpointFilter(bp)).join('\n  ');
     return `
-<li class="summary-item coverage">
-  <span class="count">${pct}</span>
-  <span class="label">${label}</span>
-  <span class="coverage-detail" aria-hidden="true">· ${metric.covered}/${metric.total}</span>
-  <span class="sr-only">${metric.covered} of ${metric.total} ${label} covered</span>
-</li>
+<div class="breakpoint-filters" role="group" aria-label="Filter by breakpoint">
+  <button type="button" class="breakpoint-filter" data-breakpoint-filter="all" aria-pressed="true" aria-controls="stories-list">
+    <span class="indicator label">all breakpoints</span><span class="sr-only">, show results at every breakpoint</span>
+  </button>
+  ${pills}
+</div>
 `;
 }
-function summaryItem(label, value, statusKey) {
+/**
+ * One breakpoint rendered as an unpressed single-select filter pill. The blank
+ * bucket (`key === ''`) reads visibly as "legacy" with an sr-only
+ * "(pre-breakpoint layout)" clarifier, mirroring {@link renderDeletedEntry};
+ * both the visible name and the `data-breakpoint-filter` token become the
+ * reserved `legacy` string so the token still matches the flat list's
+ * `data-breakpoint="legacy"` hook. Dimensions render only when the recorded
+ * result carried them.
+ */
+function breakpointFilter(bp) {
+    const isLegacy = bp.key === '';
+    const token = breakpointToken(bp.key);
+    const name = isLegacy
+        ? 'legacy<span class="sr-only"> (pre-breakpoint layout)</span>'
+        : `${escapeHtml(bp.key)}`;
+    const dimensions = bp.width !== undefined && bp.height !== undefined
+        ? ` <span class="breakpoint-dimensions" aria-hidden="true">${bp.width}×${bp.height}</span><span class="sr-only"> ${bp.width} by ${bp.height} pixels</span>`
+        : '';
+    return `<button type="button" class="breakpoint-filter" data-breakpoint-filter="${escapeHtml(token)}" aria-pressed="false" aria-controls="stories-list">
+    <span class="indicator label"><span class="breakpoint-name">${name}</span>${dimensions}</span><span class="sr-only">, show only results at this breakpoint</span>
+  </button>`;
+}
+/**
+ * One status total rendered as a single-select filter button. The visible count
+ * sits OUTSIDE the button as a sibling span and is wired to it via
+ * aria-describedby, so only the word ("passed") is the pill button while the
+ * count still reads as the button's description. The accessible name is the
+ * visible label plus a visually-hidden action suffix (e.g. ", show only passed
+ * stories"), composed from contents so the visible text is never dropped (WCAG
+ * 2.5.3 — never an aria-label). The `data-filter` token ("pass") is kept
+ * distinct from the visible label ("passed") so report.js matches
+ * `story[data-status="pass"]`.
+ */
+function summaryFilter(label, value, filter, pressed, actionSuffix) {
     return `
-<li class="summary-item"${statusKey ? ` data-status="${statusKey}"` : ''}>
-  <span class="count">${value}</span>
-  <span class="indicator label">${label}</span>
+<li class="summary-item" data-status="${filter}">
+  <span class="count" id="summary-count-${filter}">${value}</span><button type="button" class="summary-filter" data-filter="${filter}" aria-pressed="${pressed}" aria-controls="stories-list" aria-describedby="summary-count-${filter}"><span class="indicator label">${label}</span><span class="sr-only">${actionSuffix}</span></button>
+  <span class="bulk-sep" aria-hidden="true">·</span>
 </li>
 `;
 }
-function renderStories(result, reportDir) {
+/**
+ * Environment-mismatch banner, rendered first inside `<main>` (above the
+ * summary) ONLY when `environment.mismatch === true` — i.e. a CI run whose
+ * committed baselines were captured under a different, pixel-affecting
+ * environment, or whose committed manifest could not be read at all.
+ *
+ * `role="alert"` is an explicit acceptance criterion. It does NOT auto-announce
+ * on content present at load, so the real discoverability comes from the banner
+ * being first in reading order behind a `<h2>` landmark. Kept because it is
+ * harmless and specified.
+ *
+ * The "warning" meaning is carried by the TEXT (the heading word and body copy),
+ * never by color alone (WCAG 1.4.1): body text stays `--text` / amber
+ * `--changed`, and the red accent lives only on the section's left border (a
+ * non-text ≥3:1 cue, mirroring `.action-error`).
+ *
+ * Two copy branches: the `['manifest']` sentinel (committed manifest unreadable,
+ * so the diverging keys can't be enumerated) drops the key list for a plain
+ * "can't be verified" message; any other mismatch lists the diverging keys.
+ */
+function renderEnvMismatch(result) {
+    const environment = result.environment;
+    if (environment?.mismatch !== true) {
+        return '';
+    }
+    const isManifestSentinel = environment.mismatchKeys.length === 1 &&
+        environment.mismatchKeys[0] === 'manifest';
+    const body = isManifestSentinel
+        ? `<p>The committed baseline manifest could not be read, so the capture environment can't be verified. Expect a full re-approve.</p>`
+        : `<p>Expect a full re-approve — baselines were captured under a different environment.</p>
+    <ul aria-label="Changed environment keys">
+      ${environment.mismatchKeys
+            .map((key) => `<li><code>${escapeHtml(key)}</code></li>`)
+            .join('\n      ')}
+    </ul>`;
+    return `
+<section class="env-mismatch" role="alert" aria-labelledby="env-mismatch-heading">
+  <h2 id="env-mismatch-heading">capture environment changed</h2>
+  ${body}
+</section>
+`;
+}
+/**
+ * Deleted (orphaned committed baselines) section — a peer landmark rendered
+ * AFTER the stories section, inside `<main>`, ONLY when `deleted` is non-empty.
+ * Lists each orphaned baseline (action + breakpoint) that `approve --prune`
+ * would remove. A `'legacy'` breakpoint (the pre-breakpoint `<action>/0.png`
+ * layout) reads cryptically on its own, so it carries an sr-only clarifier.
+ */
+function renderDeleted(result) {
+    if (result.deleted.length === 0) {
+        return '';
+    }
+    const items = result.deleted
+        .map((entry) => renderDeletedEntry(entry))
+        .join('\n    ');
+    return `
+<section class="deleted" aria-labelledby="deleted-heading">
+  <h2 id="deleted-heading">deleted</h2>
+  <p>These committed baselines have no matching story this run. <code>tuffgal approve --prune</code> removes them.</p>
+  <ul aria-label="Orphaned baselines to be pruned on approve">
+    ${items}
+  </ul>
+</section>
+`;
+}
+function renderDeletedEntry(entry) {
+    const breakpoint = entry.breakpoint === 'legacy'
+        ? 'legacy<span class="sr-only"> (pre-breakpoint layout)</span>'
+        : escapeHtml(entry.breakpoint);
+    return `<li><code>${escapeHtml(entry.action)}</code> ${breakpoint}</li>`;
+}
+function renderStories(result, reportDir, interactiveMode) {
     const items = result.stories
-        .map((story, index) => renderStory(story, index, reportDir))
+        .map((story, index) => renderStory(story, index, reportDir, interactiveMode))
         .join('\n');
     const total = result.stories.length;
+    // The interactive controls now live in the summary row; this section keeps
+    // only the two live regions (both server-rendered between the heading and the
+    // list so a screen reader announces filter/bulk changes reliably) and the
+    // list itself, whose id the summary filter buttons target via aria-controls.
     return `
 <section aria-labelledby="stories-heading">
   <h2 id="stories-heading">stories</h2>
-  <div class="stories-toolbar">
-    <fieldset class="story-filter">
-      <legend class="sr-only">filter</legend>
-      ${storyFilterRadio('all', true)}
-      ${storyFilterRadio('passed', false)}
-      ${storyFilterRadio('changed', false)}
-      ${storyFilterRadio('failed', false)}
-    </fieldset>
-    <p class="story-filter-status" role="status" aria-live="polite">Showing all ${total} stories</p>
-    <div class="story-bulk-toggle">
-      <button type="button" class="chip story-bulk-toggle-button" data-bulk-toggle="expand">Expand all</button>
-      <button type="button" class="chip story-bulk-toggle-button" data-bulk-toggle="collapse">Collapse all</button>
-    </div>
-    <p class="bulk-toggle-status sr-only" role="status" aria-live="polite"></p>
-  </div>
-  <ol class="stories" aria-label="Stories executed in dependency order">
+  <p class="story-filter-status" role="status" aria-live="polite" aria-atomic="true">Showing all ${total} stories</p>
+  <p class="bulk-toggle-status sr-only" role="status" aria-live="polite" aria-atomic="true"></p>
+  <ol class="stories" id="stories-list" aria-label="Stories executed in dependency order">
     ${items}
   </ol>
   <p class="stories-empty" hidden>No matching stories</p>
 </section>
 `;
 }
-function storyFilterRadio(status, checked) {
-    const inputId = `story-filter-${status}`;
-    const value = status === 'passed' ? 'pass' : status;
-    return `
-<label for="${inputId}" class="chip chip--toggle story-filter-label">
-  <input
-    type="radio"
-    name="story-filter"
-    id="${inputId}"
-    value="${value}"
-    data-filter-name="${status}"
-    ${checked ? 'checked' : ''}
-  />
-  ${status}
-</label>
-`;
-}
-function renderStory(story, storyIndex, reportDir) {
+function renderStory(story, storyIndex, reportDir, interactiveMode) {
     return `
 <li class="story" data-status="${story.status}">
   <div class="story-row">
@@ -142,7 +320,7 @@ function renderStory(story, storyIndex, reportDir) {
   </div>
   <p class="story-prose">${escapeHtml(story.story)}</p>
   <br/>
-  ${renderStoryActions(story, storyIndex, reportDir)}
+  ${renderStoryActions(story, storyIndex, reportDir, interactiveMode)}
 </li>
 `;
 }
@@ -165,7 +343,7 @@ function renderStory(story, storyIndex, reportDir) {
  * shot-panel `id`s stay globally unique across groups and report.js's
  * `name="<actionId>-shot"` radio grouping never collides between modes.
  */
-function renderStoryActions(story, storyIndex, reportDir) {
+function renderStoryActions(story, storyIndex, reportDir, interactiveMode) {
     // Bucket actions by breakpoint, preserving first-seen order.
     const order = [];
     const buckets = new Map();
@@ -178,17 +356,20 @@ function renderStoryActions(story, storyIndex, reportDir) {
         buckets.get(key).push({ action, id: `s${storyIndex}-a${actionIndex}` });
     });
     // One mode (or untagged) → flat list, no caption. Captions only earn their
-    // chrome when there is more than one mode to tell apart.
+    // chrome when there is more than one mode to tell apart. The flat list still
+    // carries the `data-breakpoint` hook (keyed off the sole bucket) so the
+    // breakpoint filter can hide the whole single-mode story when it does not
+    // match — no visible chrome is added, only the filter hook.
     if (order.length <= 1) {
         const actions = story.actions
-            .map((action, actionIndex) => renderAction(action, `s${storyIndex}-a${actionIndex}`, reportDir))
+            .map((action, actionIndex) => renderAction(action, `s${storyIndex}-a${actionIndex}`, reportDir, interactiveMode))
             .join('\n');
-        return `<ol class="actions" aria-label="Actions">
+        return `<ol class="actions" aria-label="Actions" data-breakpoint="${escapeHtml(breakpointToken(order[0] ?? ''))}">
     ${actions}
   </ol>`;
     }
     return order
-        .map((key, groupIndex) => renderBreakpointGroup(key, buckets.get(key), `s${storyIndex}-bp${groupIndex}`, reportDir))
+        .map((key, groupIndex) => renderBreakpointGroup(key, buckets.get(key), `s${storyIndex}-bp${groupIndex}`, reportDir, interactiveMode))
         .join('\n');
 }
 /**
@@ -208,8 +389,12 @@ function renderStoryActions(story, storyIndex, reportDir) {
  * Dimensions render in their own `aria-hidden` span (decorative "375×667")
  * with an sr-only longhand ("375 by 667 pixels") so screen readers don't read
  * the `×` glyph as "x" mid-stream.
+ *
+ * The group `<div>` additionally carries a `data-breakpoint` hook (the bucket
+ * key's matcher token) so the breakpoint filter can hide a whole group whose
+ * mode is not selected. Purely additive — the caption/label idiom is untouched.
  */
-function renderBreakpointGroup(key, entries, groupId, reportDir) {
+function renderBreakpointGroup(key, entries, groupId, reportDir, interactiveMode) {
     const labelId = `${groupId}-label`;
     const name = key;
     // The capture dimensions recorded on the result reflect per-config and
@@ -220,14 +405,12 @@ function renderBreakpointGroup(key, entries, groupId, reportDir) {
         recorded.breakpointHeight !== undefined
         ? { width: recorded.breakpointWidth, height: recorded.breakpointHeight }
         : undefined;
-    const dimensionMarkup = dimensions
-        ? `<span class="breakpoint-dimensions" aria-hidden="true">${dimensions.width}×${dimensions.height}</span><span class="sr-only">${dimensions.width} by ${dimensions.height} pixels</span>`
-        : '';
+    const dimensionMarkup = dimensions ? dimensionPair(dimensions) : '';
     const actions = entries
-        .map(({ action, id }) => renderAction(action, id, reportDir))
+        .map(({ action, id }) => renderAction(action, id, reportDir, interactiveMode))
         .join('\n');
     return `
-<div class="breakpoint-group">
+<div class="breakpoint-group" data-breakpoint="${escapeHtml(breakpointToken(key))}">
   <p class="breakpoint-label" id="${labelId}">
     <span class="breakpoint-name">${escapeHtml(name)}</span>
     ${dimensionMarkup}
@@ -239,8 +422,8 @@ function renderBreakpointGroup(key, entries, groupId, reportDir) {
 </div>
 `;
 }
-function renderAction(action, actionId, reportDir) {
-    const screenshots = renderScreenshots(action, actionId, reportDir);
+function renderAction(action, actionId, reportDir, interactiveMode) {
+    const screenshots = renderScreenshots(action, actionId, reportDir, interactiveMode);
     const errorBlock = action.status === 'failed'
         ? `<pre class="action-error">${escapeHtml(action.failureMessage ?? 'unknown error')}</pre>`
         : '';
@@ -264,14 +447,56 @@ ${statusBadge(action.status)}
   ${rowInner}
 </div>
 `;
+    const notes = renderActionNotes(action, reportDir);
     return `
 <li class="action" data-status="${action.status}">
   ${row}
   ${parameters}
   ${errorBlock}
+  ${notes}
 </li>
 `;
 }
+/**
+ * Supplementary per-action prose, rendered inside `li.action` after the
+ * row/screenshots/error block. Both are plain `<p role="note">` — NOT headings:
+ * they live in the story `<ol>` subtree, so a heading would orphan under a
+ * list-item (same rationale as {@link renderBreakpointGroup}'s caption). Neither
+ * is a live region (present at load), so an a11y-only `changed` row can carry
+ * BOTH with no double-announce.
+ *
+ *   - candidate note: on `changed`/`new` rows only — supplementary prose flagging
+ *     "this run's actual screenshot is the proposed new baseline". Names the
+ *     Actual variant explicitly (the note sits OUTSIDE the <details>, so "this
+ *     render" would point at whichever tab is selected — or nothing when
+ *     collapsed). No aria wiring; it does not duplicate the status badge's
+ *     sr-only label.
+ *   - a11y-drift note: gated STRICTLY on `a11yChanged === true`, NEVER inferred
+ *     from a missing `diffPath` (a size-mismatch `changed` row also lacks a
+ *     diffPath yet deliberately omits `a11yChanged`; keying on `!diffPath` would
+ *     misfire on it — the load-bearing discriminator, per the ActionResult
+ *     contract). Renders the recorded `a11yBaselinePath` as plain escaped
+ *     `<code>` TEXT, not a link (the report is portable / opened over file://),
+ *     relativized like the other paths when absolute.
+ *
+ * Order: candidate note first, then a11y-drift note, so an a11y-only changed row
+ * reads "proposed new baseline" before the a11y specifics.
+ */
+function renderActionNotes(action, reportDir) {
+    const notes = [];
+    if (action.status === 'changed' || action.status === 'new') {
+        notes.push(`<p class="candidate-note" role="note">This run's actual screenshot is the proposed new baseline.</p>`);
+    }
+    if (action.a11yChanged === true) {
+        const path = action.a11yBaselinePath;
+        const displayPath = path !== undefined ? toReportRelative(reportDir, path) : undefined;
+        const pathMarkup = displayPath !== undefined
+            ? ` Proposed a11y baseline written to <code>${escapeHtml(displayPath)}</code>.`
+            : '';
+        notes.push(`<p class="a11y-drift-note" role="note">Accessibility snapshot changed.${pathMarkup}</p>`);
+    }
+    return notes.join('\n  ');
+}
 function renderParameters(parameters) {
     if (!parameters || Object.keys(parameters).length === 0) {
         return '';
@@ -281,11 +506,43 @@ function renderParameters(parameters) {
         .join('');
     return `<dl class="action-parameters">${entries}</dl>`;
 }
-function renderScreenshots(action, actionId, reportDir) {
+/**
+ * A "changed" row whose diff could not be computed: baseline and actual differ
+ * in dimensions, so pixelmatch throws before producing a diffRatio or diff
+ * image, leaving only the recorded failureMessage. Centralizes the predicate
+ * shared by the radio fallback, the diff radio's describedby wiring, and
+ * renderDiffStats' unavailable note.
+ */
+function isDiffUnavailable(action) {
+    return (action.diffRatio === undefined &&
+        action.status === 'changed' &&
+        !!action.failureMessage);
+}
+function renderScreenshots(action, actionId, reportDir, interactiveMode) {
     if (!action.actualPath && !action.baselinePath) {
         return '';
     }
-    const baseline = action.baselinePath
+    // interactiveMode swaps the radio-tab output for the single-image
+    // press-and-hold viewer. When it is false the function falls through to the
+    // radio-tab output below, byte-identical with the pre-interactiveMode render.
+    //
+    // When the baseline and actual differ in dimensions the diff is uncomputable
+    // (renderDiffStats' unavailable branch — both paths present, `changed` status,
+    // a recorded failureMessage, no diffRatio). Press-flipping between two
+    // differently-sized captures misaligns everything and reads as "everything
+    // changed", so fall back to the radio-tab render: visible panels, baseline +
+    // actual, and the disabled diff option carrying the mismatch reason.
+    const diffUncomputable = action.baselinePath !== undefined &&
+        action.actualPath !== undefined &&
+        isDiffUnavailable(action);
+    if (interactiveMode && !diffUncomputable) {
+        return renderInteractiveScreenshots(action, actionId, reportDir);
+    }
+    // A `new` baseline writes its baseline straight from this run's actual, so the
+    // two paths point at byte-identical PNGs. There is no prior state to compare
+    // against, so suppress the baseline variant for display — like the diff, it is
+    // not a real artifact here. The path stays in the data model for `approve`.
+    const baseline = action.baselinePath && action.status !== 'new'
         ? toReportRelative(reportDir, action.baselinePath)
         : undefined;
     const actual = action.actualPath
@@ -294,30 +551,205 @@ function renderScreenshots(action, actionId, reportDir) {
     const diff = action.diffPath
         ? toReportRelative(reportDir, action.diffPath)
         : undefined;
-    const defaultTab = diff ? 'diff' : 'actual';
+    const defaultTab = 'actual';
     const available = { baseline, actual, diff };
     const initialTab = available[defaultTab] !== undefined
         ? defaultTab
         : ['baseline', 'actual', 'diff'].find((name) => available[name] !== undefined);
     const diffStatsId = `${actionId}-diff-stats`;
-    const diffStats = action.diffRatio !== undefined
-        ? `<p class="diff-stats" id="${diffStatsId}"><span class="count">${parseFloat((action.diffRatio * 100).toFixed(2))}%</span> <span class="label">differs</span> <span class="coverage-detail">· ${(action.diffPixels ?? 0).toLocaleString('en-US')} pixels</span></p>`
-        : '';
+    const diffStats = renderDiffStats(action, diffStatsId);
+    // renderDiffStats emits the `diff-stats--unavailable` note (with this id) when
+    // the diff is uncomputable. The diff radio is disabled in that case, so wire
+    // its aria-describedby to the note — a keyboard/AT user reaching the disabled
+    // diff option then hears why no diff exists. (The diff PANEL only takes the
+    // association when a real diff image renders, below.)
+    const diffNoteUnavailable = isDiffUnavailable(action);
+    // When only one variant is real (the common case for a `new` baseline, whose
+    // baseline is suppressed and has no diff), a radio group offering a single
+    // choice is noise to AT. Drop the controls and show the image alone; the row's
+    // status badge already announces "new baseline". Zero variants — a `new` row
+    // whose actual capture is somehow missing — collapses to nothing.
+    const soleVariant = ['baseline', 'actual', 'diff'].filter((name) => available[name] !== undefined);
+    if (soleVariant.length <= 1) {
+        const only = soleVariant[0];
+        if (only === undefined) {
+            return '';
+        }
+        const lone = shotPanel(actionId, only, available[only], SHOT_ALT[only](action), true);
+        return `${diffStats}${lone}`;
+    }
     return `
 <fieldset class="shot-radio" data-default-tab="${defaultTab}">
   <legend class="sr-only">Screenshot to display</legend>
   ${shotRadio(actionId, 'baseline', baseline === undefined, initialTab === 'baseline')}
   ${shotRadio(actionId, 'actual', actual === undefined, initialTab === 'actual')}
-  ${shotRadio(actionId, 'diff', diff === undefined, initialTab === 'diff')}
+  ${shotRadio(actionId, 'diff', diff === undefined, initialTab === 'diff', diffNoteUnavailable ? { describedById: diffStatsId } : undefined)}
   ${diffStats}
 </fieldset>
-${shotPanel(actionId, 'baseline', baseline, `${action.action} baseline screenshot`, initialTab === 'baseline')}
-${shotPanel(actionId, 'actual', actual, `${action.action} actual screenshot from this run`, initialTab === 'actual')}
-${shotPanel(actionId, 'diff', diff, `Pixel diff overlay for ${action.action}; changed regions are highlighted`, initialTab === 'diff', action.diffRatio !== undefined ? diffStatsId : undefined)}
+${shotPanel(actionId, 'baseline', baseline, SHOT_ALT.baseline(action), initialTab === 'baseline')}
+${shotPanel(actionId, 'actual', actual, SHOT_ALT.actual(action), initialTab === 'actual')}
+${shotPanel(actionId, 'diff', diff, SHOT_ALT.diff(action), initialTab === 'diff', action.diffRatio !== undefined ? diffStatsId : undefined)}
 `;
 }
-function shotRadio(actionId, name, disabled, checked) {
+/** Alt text per screenshot variant, shared by the radio-tab and collapsed render. */
+const SHOT_ALT = {
+    baseline: (action) => `${action.action} baseline screenshot`,
+    actual: (action) => `${action.action} actual screenshot from this run`,
+    diff: (action) => `Pixel diff overlay for ${action.action}; changed regions are highlighted`,
+};
+/**
+ * The pixel-diff overlay only exists when baseline and actual share dimensions.
+ * A mismatch (e.g. a fullPage capture whose document grew taller) throws before
+ * a diff is computed, so `diffRatio` is absent and there is no diff image to
+ * show — surface the recorded reason here, in the slot the "% differs" stat
+ * would normally occupy, so a "changed" row never reads as an unexplained no-op.
+ *
+ * The mismatch note folds baseline and actual sizes into ONE sentence and renders
+ * each dimension pair in the file's split idiom (a `breakpoint-dimensions` span
+ * carrying the `×` glyph for sight, plus an `sr-only` "W by H pixels" longhand for
+ * AT — never a bare `x`). It reads those numbers from the structured
+ * `action.sizeMismatch` pair, NOT by parsing `failureMessage`. When that pair is
+ * absent (a malformed or older result), it falls back to escaping the recorded
+ * `failureMessage` prose rather than risk a wrong parse.
+ */
+function renderDiffStats(action, diffStatsId) {
+    if (action.diffRatio !== undefined) {
+        return `<p class="diff-stats" id="${diffStatsId}"><span class="count">${parseFloat((action.diffRatio * 100).toFixed(2))}%</span> <span class="label">differs</span> <span class="coverage-detail">· ${(action.diffPixels ?? 0).toLocaleString('en-US')} pixels</span></p>`;
+    }
+    if (action.status !== 'changed' || !action.failureMessage) {
+        return '';
+    }
+    const label = action.sizeMismatch
+        ? `No pixel diff — screenshot resized from ${dimensionPair(action.sizeMismatch.baseline)} to ${dimensionPair(action.sizeMismatch.actual)}.`
+        : `No pixel diff. ${escapeHtml(action.failureMessage)}`;
+    return `<p class="diff-stats diff-stats--unavailable" id="${diffStatsId}"><span class="label">${label}</span></p>`;
+}
+/**
+ * A `width`×`height` pair in the file's split idiom: the `×` glyph is sight-only
+ * (aria-hidden), and AT hears the spoken "W by H pixels" longhand instead of an
+ * ambiguous "x". Shared by {@link renderDiffStats} (the size-mismatch note) and
+ * {@link renderBreakpointGroup} (the per-mode caption), which emit byte-identical
+ * markup. {@link breakpointFilter} renders the same idiom but keeps its own
+ * inline copy: its sr-only longhand carries a leading space (` W by H pixels`)
+ * that this helper omits, so routing it through here would change the rendered
+ * bytes.
+ */
+function dimensionPair(size) {
+    return `<span class="breakpoint-dimensions" aria-hidden="true">${size.width}×${size.height}</span><span class="sr-only">${size.width} by ${size.height} pixels</span>`;
+}
+/**
+ * Interactive screenshot viewer (interactiveMode). One native radio group per
+ * action is the committed-state source of truth — keyboard, touch, and AT all
+ * operate the radios (reusing `name="${actionId}-shot"`), and the chips render
+ * permanently visible (the mouse/touch path to every variant, including Diff).
+ * report.js layers a VISUAL-ONLY press-and-hold blink-compare on a SINGLE
+ * shared `<img>`: press shows the committed variant's counterpart (baseline
+ * normally, actual when baseline is committed); release/leave/dragstart
+ * reverts. No hover behavior. The gesture rewrites only the img src and the
+ * aria-hidden "Showing:" caption (which names the DISPLAYED variant, preview
+ * included) — never radio state, the img alt, or any ARIA. The controls +
+ * caption live OUTSIDE the clipped `.shot-stage` so
+ * the focus ring is never clipped or painted over screenshot pixels. The diff
+ * variant — and its radio — is omitted entirely (not disabled) when this action
+ * produced no diff image; the existing diff-stats association then rides on the
+ * diff radio control rather than the image, leaving no dangling describedby.
+ * (Distinct from the dimension-mismatch case, where the diff is uncomputable:
+ * renderScreenshots never reaches this viewer and instead falls back to the
+ * radio-tab render with a disabled — not omitted — diff radio.)
+ */
+function renderInteractiveScreenshots(action, actionId, reportDir) {
+    // A `new` baseline writes its baseline straight from this run's actual, so the
+    // two paths point at byte-identical PNGs. There is no prior state to compare
+    // against, so suppress the baseline variant for display — like the diff, it is
+    // omitted (no radio, no image). The path stays in the data model for `approve`.
+    const baseline = action.baselinePath && action.status !== 'new'
+        ? toReportRelative(reportDir, action.baselinePath)
+        : undefined;
+    const actual = action.actualPath
+        ? toReportRelative(reportDir, action.actualPath)
+        : undefined;
+    const diff = action.diffPath
+        ? toReportRelative(reportDir, action.diffPath)
+        : undefined;
+    // Default committed variant is `actual`; only a baseline-only row (no actual
+    // capture this run) commits to baseline instead. renderScreenshots' guard
+    // guarantees at least one of the two exists, so `committedSrc` is never empty
+    // at runtime — the `?? ''` only satisfies the optional types.
+    const committed = actual !== undefined ? 'actual' : 'baseline';
+    const committedSrc = (committed === 'actual' ? actual : baseline) ?? '';
+    // When only one variant is real (the common case for a `new` baseline, whose
+    // baseline is suppressed and has no diff), the press-and-hold flip has nothing
+    // to toggle to — a lone radio in a group is noise to AT. Render the image alone;
+    // the row's status badge already announces "new baseline". Zero variants — a
+    // `new` row whose actual capture is missing — collapses to nothing.
+    const variantCount = [baseline, actual, diff].filter((v) => v !== undefined).length;
+    if (variantCount === 0) {
+        return '';
+    }
+    if (variantCount === 1) {
+        return `
+<div class="shot-stage">
+  <img
+    class="shot-image"
+    src="${escapeHtml(committedSrc)}"
+    alt="${escapeHtml(`Screenshot of ${action.action}`)}"
+    loading="lazy"
+  />
+</div>
+`;
+    }
+    const diffStatsId = `${actionId}-diff-stats`;
+    const diffStats = renderDiffStats(action, diffStatsId);
+    const radios = [
+        baseline !== undefined
+            ? shotRadio(actionId, 'baseline', false, committed === 'baseline', {
+                label: 'Baseline',
+            })
+            : '',
+        actual !== undefined
+            ? shotRadio(actionId, 'actual', false, committed === 'actual', {
+                label: 'Actual',
+            })
+            : '',
+        diff !== undefined
+            ? shotRadio(actionId, 'diff', false, false, {
+                label: 'Diff',
+                describedById: diffStats !== '' ? diffStatsId : undefined,
+            })
+            : '',
+    ].join('');
+    const captionLabel = committed === 'actual' ? 'Actual' : 'Baseline';
+    const dataSrc = [
+        baseline !== undefined
+            ? ` data-src-baseline="${escapeHtml(baseline)}"`
+            : '',
+        actual !== undefined ? ` data-src-actual="${escapeHtml(actual)}"` : '',
+        diff !== undefined ? ` data-src-diff="${escapeHtml(diff)}"` : '',
+    ].join('');
+    return `
+<fieldset class="shot-interactive">
+  <legend class="sr-only">${escapeHtml(action.action)} screenshot</legend>
+  ${radios}
+  <p class="shot-caption" aria-hidden="true">Showing: <span class="shot-caption-variant">${captionLabel}</span></p>
+  ${diffStats}
+</fieldset>
+<div class="shot-stage">
+  <img
+    class="shot-image"
+    src="${escapeHtml(committedSrc)}"
+    alt="${escapeHtml(`Screenshot of ${action.action}`)}"
+    loading="lazy"
+    ${dataSrc}
+  />
+</div>
+`;
+}
+function shotRadio(actionId, name, disabled, checked, opts) {
     const inputId = `${actionId}-radio-${name}`;
+    const label = opts?.label ?? name;
+    const describedBy = opts?.describedById
+        ? ` aria-describedby="${opts.describedById}"`
+        : '';
     return `
 <label for="${inputId}" class="chip chip--toggle shot-radio-label">
   <input
@@ -325,11 +757,11 @@ function shotRadio(actionId, name, disabled, checked) {
     name="${actionId}-shot"
     id="${inputId}"
     value="${name}"
-    data-tab="${name}"
+    data-tab="${name}"${describedBy}
     ${disabled ? 'disabled' : ''}
     ${checked ? 'checked' : ''}
   />
-  ${name}
+  ${label}
 </label>
 `;
 }