Give the report a summary header it can be triaged from (refs #439) - #476

Refs #439. First of three serial PRs implementing Option A — Xcode-native, the
direction chosen from DIRECTION-PACKAGE-2026-08-12.md. This one is the summary
header only: the outcome ring, the per-device bars and the failure digest that sit
above the tree. A2 restyles the tree and rows; A3 does the filters and #460. Neither is
started here.

What lands

• Run summary — a ring showing every outcome's share, a legend with the counts, the
  total, and the run duration. All six Status cases are counted, so the buckets
  partition the run rather than leaving tests uncounted.
• Failure digest — one row per failed test with its assertion message and its suite,
  readable without expanding anything (the audit's finding 2). The test name is a
  <button>: clicking it activates the owning run, clears whatever the filter hid,
  expands the disclosure, selects the row and scrolls to it.
• Device bars — one row per run, a proportional bar and the same breakdown in words.
• Dark-first Apple palette for the header, as five new surface tokens plus
  --status-mixed, on the existing :root layer.
• The ring is inline SVG — one stroked <circle> per bucket, pathLength="100" so
  the dash arithmetic is percentages. No canvas, no fetch, no external anything; it works
  identically in --rendering-mode inline and linking.

The two derived numbers, and why the differential stays green

DifferentialTests renders every fixture through both readers and requires byte equality
after masking the four declared losses. No allow-list entry was added, and
differential-allowlist.json is not in this diff.

Counts are backend-identical and are compared as such. Status partitions the leaf
tests exactly, and the header asserts that the buckets add up to the run's test count on
both backends.

Duration is the sum of leaf test durations, never of groups — durationInSeconds is
null on every suite node in the modern format, which is the standing durations entry, so
a total that reached for a group's duration would read a real value on one backend and
zero on the other.

That sum is not backend-identical, and this PR does not pretend otherwise. The first
revision claimed it was, on the strength of three local fixtures where the leaf sums
matched to the last bit. CI disagreed, and CI was right. Downloading the failing run's
bundles and re-running against them isolates one divergent leaf on those bundles — a
second, unrelated one turned up in review and is covered below:

Legacy is ~3× modern and the test has three argument sets: legacy merges the argument
executions and sums them, modern reports the node's own value.

Both totals still render 5.04s, so the byte comparison passed; only a tight model-level
assertion caught it. That is luck, not safety. Legacy = 3 × modern means a slower runner
where modern reports 0.003s makes legacy 0.009s — a 6ms gap that crosses a 2-decimal
rounding boundary and turns the differential red intermittently. Loosening the tolerance
would have buried precisely the thing that breaks CI later.

So the header writes its total in the shape the existing durations rule already
normalises:

<span class="summary-meta">Duration <span class="summary-duration">(5.04s)</span> · 1 device</span>

Rendered copy: Duration (5.04s) · 1 device. The parentheses are not styling — (N.NNs)
is literally what KnownLossMasker's durations rule matches, so the header's total
inherits the loss that entry already declares instead of leaving it uncovered.
RunSummaryTests.testTheHeadersDurationIsWrittenInAMaskedShape proves that against the
masker rather than by reading the regex and believing it, so a copy edit that dropped the
parentheses fails immediately.

The second divergence, found in review — a format property, not a bug

This PR previously went on to claim every other leaf was exact. Review disproved that by
regenerating the fixtures: a leaf the run repeated can differ too, by microseconds.
Measured on RetryTests/testRetryOnFailure() (two repetitions), across three
prepareTestResults.sh generations of RetryResults.xcresult:

So it is generation-dependent, which is why an exact assertion passed on CI and in
development until someone rebuilt the bundle. The 11:43 generation localises it: the whole
gap sits in repetition 0 (0.12885606s legacy against 0.12900018s modern) while
repetition 1 is bit-identical, and the three sibling leaves in the same bundle agree
exactly in every generation.

This is not #477 and should not be filed under it. #477 is structural and closable —
legacy sums a parameterized case's argument executions and modern does not, so one side
can be changed to match. Here the arithmetic already agrees: design answer 8 has both
readers summing repetitions, so there is nothing left to converge. What remains is the two
formats measuring and reporting the same repetition independently at microsecond
precision, and no renderer-side change can make two independent measurements round to the
same microsecond. Exact equality is not something either format promises for a repetition
duration, so the differential must stop asserting it. It is recorded as a measured format
property in the migration spec's Verification section, amended in this PR — not left open
as a bug with no fix.

One consequence worth flagging, because it corrects something #477's own issue body says:
closing #477 will not free the header's total to be written in any shape. The
repetition property above reaches the same total by the same route, so the parenthesised,
durations-masked form stays necessary for as long as a repeated test can land in a
report. The comment in RunSummary.swift now names both divergences and says which is
which.

How the assertion is structured

The model-level assertion was not deleted, and the two divergences are handled
differently because they are different things:

The repetition count itself stays an exact assertion, so a backend that dropped a
repetition cannot hide inside the tolerance that same count is used to size. A guard
after the fixture loop fails if no repeated leaf was compared at all, so the weaker of
the two comparisons cannot quietly become dead code. Verified both ways on the fresh
generation: the previous exact-only assertion is red on it (144µs on
testRetryOnFailure()), the restructured one is green on that generation and on the
01:21 bundles.

One more vacuity hole closed on review feedback: keying leaves by identifier used
uniquingKeysWith and would silently drop the second of a duplicated pair, reporting
parity for a leaf it never compared. Identifiers are unique today because every fixture
is one plan on one destination; the moment a multi-run fixture lands they are not. The
uniqueness is now asserted rather than assumed, with a message naming the fix (put the
run in the key). Widening the key pre-emptively was rejected: it would buy coverage no
fixture exercises at the price of assuming both backends order runs identically, which
nothing pins. Mutation-verified — duplicating the leaf list fails it on every fixture.

Note testXCTestCaseDurationsAgreeAcrossBackends still holds those same leaves to a flat
accuracy: 0.0005, tighter than 1ms × 2 for anything repeated twice. That is left alone
deliberately — it is the older blanket gate, and if a generation ever exceeds it the right
response is to give it the same per-repetition treatment, not to loosen either.

The root cause has an issue: #477. The migration design's answer 8 already solved the
identical problem for repetitions by summing in the renderer; answer 6 added arguments
at the same time as an "unexercised by fixtures" slot, and nobody applied answer 8 to it.
The fix is to converge the backends by construction rather than by mask, per the spec's
own "an unmasked diff proves more than a masked one". #477 names the two things that come
out when it lands: the exclusion in the differential and the paragraph in
RunSummary.swift. This divergence predates this PR — it has been living under the
durations mask in the tree since the parameterized fixture landed — but the header is
the first place it aggregates into one number, which is what made it visible.

ParsedRun carries no run date, so the header states a duration and no start time. The
mockup derived one from the earliest activity timestamp; that is a field the differential
does not cover, so it is not read here.

Contrast

Every pairing below is the resolved one, read out of the live cascade in Chromium at
1440px rather than from a hand-written matrix. Text floor 4.5:1, non-text (WCAG 1.4.11)
floor 3:1. visual/tests/tokens.spec.ts enforces the text column automatically in both
themes and passes.

Text — light / dark

Tightest pairing in the header: 5.11:1, against a 4.5 floor.

Non-text — ring arcs, bar segments and legend swatches, against the card

Tightest: 4.21:1, against a 3:1 floor. The status values are the existing #439 tokens,
unchanged — in dark the header's card is the same #232327 those tokens were already
sized against, so it inherits their measurements exactly.

Deliberately below 3:1

--color-summary-border (1.51 light / 1.39 dark) and --color-donut-track (1.28 / 1.39).
Both are decorative: a card edge and the ring's empty groove carry nothing the arcs and
the legend do not already carry in colour and in text, and 1.4.11 scopes the floor to
graphics you must perceive to understand the content. Raising them to 3:1 would draw the
heavy outline the rest of the sheet already avoids.

Deviations from the mockup, and why

1. No counts printed inside the bars. The mockup puts white numerals on the segments.
   Measured: white on its --green is 3.13:1 light / 2.02:1 dark, on --gray
   3.26 / 2.87, on --red 4.23 / 3.41 — all under the 4.5 floor for 11px text. The
   counts moved out into the caption beside the bar, and the bar became a pure graphic
   held to the 3:1 non-text floor. This is the C-refresh discipline applied to the
   mockup's own errors, as directed.
2. Corrected palette, not the mockup's. The status colours are C's contrast-vetted
   tokens, not the mockup's raw Apple values (#34c759, #ff453a, #ffd60a). Only
   surfaces and --status-mixed are new.
3. No run start time — ParsedRun has no date; see above.
4. Duration is the leaf sum, written Duration (5.04s), not the mockup's
   "Selected tests ran for 27.51 s" — see above. The parenthesised form is what keeps a
   declared known loss covered.
5. The ring is a stroked SVG, not conic-gradient. The direction package proposed
   CSS; inline SVG was specified for this PR, and it is the better fit anyway: a ring
   drawn with conic-gradient needs a second element to punch the hole, and the dash
   arithmetic here is computed in Swift at fixed precision, which is what keeps the golden
   files byte-stable.
6. Mixed gets a solid hue rather than the tree's split-diamond treatment. A 12px ring
   arc and a 10px legend swatch are too small to read a split at. The tree's glyph is
   unchanged.
7. The device bar spans its column instead of the mockup's fixed 220px. The mockup
   capped its main at 1100px; the report is a full-width app shell with no centred
   document column, and pinning the bar would leave it stranded at 1440.
8. The suite label comes from the test identifier, not from the parent group's title:
   the identifier is the one key the differential already pins as equal across backends,
   while the legacy tree wraps every suite in "Selected tests" and "<target>.xctest"
   levels the modern tree does not have.
9. The header lives inside <header>, the existing banner landmark, rather than as a
   new top-level section — a section outside every landmark would regress axe's region
   rule, closed in Rendered report has six axe-core accessibility violations, two of them critical/serious #462.
10. At 375px the suite drops under the message instead of being hidden. The mockup
    deletes that column at ≤480px, but it is the only thing telling two same-named tests
    apart (testOne() appears in both SecondSuite and ThirdSuite in the fixture).
11. The band scrolls — capped at 50vh, 40vh narrow — so a run with many failures can
    never push the tree off the screen. The digest card disappears entirely when nothing
    failed.
12. The ring carries no accessible name of its own. The mockup gives the donut
    role="img" with aria-label="16 tests: 9 passed, 6 failed, 1 skipped". The SVG here
    is aria-hidden="true" instead, because that sentence is already in the document
    twice — as the .donut-center text and as the legend rows — and a role="img" name
    would make a screen reader read the same tally three times. Explained in the template
    comment; listed here because it is still a deviation.
13. The device-bars head keeps only its left-hand label. The mockup's head is two
    spans, Devices & Configurations and Passed / Failed / Skipped. The right-hand one
    is dropped: deviation 1 moved the counts out of the bars and into a per-row caption
    that names each number in words, so a column header over a column that no longer
    exists would point at nothing.
14. Digest meta reads 6 failures, not the mockup's 6 total failures. "Total" adds
    nothing when the digest is the complete list by construction.

Byte regions touched

HTMLTemplates.swift is insertion-only: every one of its ten hunks is -N,0. Not a
single existing line of the stylesheet, the markup or the script was modified or deleted.

Untouched, deliberately: run, testSummary, testCase, testCaseWithIterations,
testGroup, iteration, activity, and every attachment template; the three-pane
layout; the filter pills; the resizers; the attachment pane. The digest's jump reaches its
target through the ids those templates already emit (activities-<uuid> /
iterations-<uuid>), which is why none of them needed an id added.

Summary.swift gains six lines (the RUN_SUMMARY placeholder and its comment).
RunSummary.swift and RunSummary+HTML.swift are new. No reader was touched.

Test-pin changes

• CoreTests.testResultStatusCount — comment only, two lines. It said the two
  Expected Failure cases "are counted in no header bucket at all". That is still true of
  the per-run filter pills it asserts on, which A1 did not touch, but no longer true of
  the report, so the comment now says which of the two readings it means and that they
  disagree until A3 rebuilds the filters. No assertion changed.
• CoreTests.testSummaryHeaderAccountsForExpectedFailures — new. On the real fixture,
  where the pass/fail split cannot be pinned, it asserts the two properties that can be:
  the legend's buckets add up to the run's test count, and the sample sources' two
  deliberate expected failures land in a bucket rather than nowhere.
• DifferentialTests.testSummaryHeaderNumbersAgreeAcrossBackends — new, per the
  section above. It lives in DifferentialSummaryHeaderTests.swift, an extension on the
  same class, so it shares the cached summaries (a fresh class would double a suite already
  dominated by xcresulttool subprocess time) without pushing DifferentialTests.swift
  past the 400-line lint threshold. Net swiftlint warnings introduced by this PR: zero.
• HTMLEscapingTests — two new tests. The header is a second place every hostile
  leaf string reaches markup, and it needed its own coverage: the existing assertions are
  document-wide, so a raw copy in the header would hide behind the escaped copy the tree
  already renders. One asserts on the #run-summary subtree specifically (verified by
  mutation — removing the escaping fails it), the other that every digest data-target is
  a hex digest, the same tripwire the onclick handlers have.
• RunSummaryTests — new, 9 tests on the synthetic fixture (the only one whose
  numbers are constants). Notably testDurationSumsLeafTestsAndNotGroups, which works
  because the fixture's group declares 6s while its leaves add to 9s, and
  testEveryDigestJumpTargetsAnElementInTheDocument, which catches a digest pointing at a
  row the page does not contain.
• visual/tests/behaviour.spec.ts — two new browser tests. The jump is the only part
  of this PR that is behaviour rather than markup, and rendered-HTML assertions cannot see
  it: one asserts it expands and selects the test it names, the other that it reveals a
  row the active filter has hidden.
• Goldens — Snapshots/index.html and index-inline.html, +475 lines each, zero
  deletions, which is the same insertion-only property as the template.

Verification

• swift test, both CI legs (XCHR_RESULT_READER=auto and =modern): 153 tests, 3
  skipped, 0 failures on each. The three skips are the standing environment-gated ones
  (BaselineCaptureTests, testRetryFunctionalityJunit per CoreTests.testRetryFunctionalityJunit expectations drift with Xcode version #378,
  VisualFixtureDumpTests) and are unrelated to this PR
• Run against two independent fixture generations, not one: the local bundles and a
  set freshly rebuilt with prepareTestResults.sh afterwards. That second generation is
  the one carrying the repetition divergence above, so it is the generation on which the
  previous exact-only assertion is red — green on both is the claim, and the red one was
  reproduced first to prove the new assertion is doing work
• Run against CI's own fixtures, downloaded from the failing run, not just the local
  ones — those are the bundles that actually exercise the Parameterized Swift Testing durations diverge across backends (legacy sums the argument executions, modern does not) #477 divergence
• DifferentialTests: green, allow-list unchanged (differential-allowlist.json is
  not in this diff)
• visual/: 13/13, including axe-core (no critical or serious violations) and the
  automated text contrast gate in both themes. Stated precisely, because an earlier
  revision of this section overstated it: tokens.spec.ts walks text nodes and holds each
  to 4.5:1, dropping to 3:1 only where WCAG's large-text exemption applies (≥24px, or
  ≥18.66px bold) — that 3:1 is the large-text floor, not the 1.4.11 non-text floor. No
  automated non-text gate exists; axe's color-contrast rule is text-only as well. The
  non-text table above (ring arcs, bar segments, legend swatches) is computed by hand from
  the resolved cascade. The Contrast section already said this; these two now agree.
• 375px overflow probe on both the synthetic and the real rendered report, both themes:
  the page does not scroll sideways, nothing crosses the viewport edge outside an
  intentional scroll container, and nothing in #run-summary crosses it at all
• swiftformat clean; swiftlint clean

Known limitations

• The digest has no device column. RunSummary.FailureRow carries uuid, testName,
  suiteName and message, and failures = runs.flatMap(\.failureRows), so one test plan
  run on two devices renders two rows that read identically and differ only in their
  data-target. The jump itself is correct — it activates the owning run, verified on a
  synthesized two-run report — so this is legibility, not correctness. Deferred to A2,
  which is where the per-run presentation is being reworked anyway; adding a column here
  would be undone by that pass.

Screenshots

Real report (TestResults.xcresult, 21 tests / 6 failures / 2 expected failures) and the
synthetic fixture, which is the only one that exercises all five buckets at once.

Sixteen shots — full page and header-only, at 1440 and 375, light and dark, for both fixtures — are in orca-artifacts/track3-a1-summary/, alongside the same crops of the mockup for comparison.

To look at it live rather than as a picture: the Test workflow renders the sample report on both legs and uploads it, so report-auto / report-modern on this PR's run open in a browser with every attachment inlined.

Summary by CodeRabbit

• New Features
  • Added a responsive run summary with test totals, duration, status donut, legends, and device breakdowns.
  • Added a failure digest for quickly locating failed tests.
  • Failure digest links now switch to Tests, reveal filtered or collapsed results, select the test, and scroll it into view.
  • Added light and dark themes, mobile layouts, and keyboard-accessible navigation.
• Bug Fixes
  • Improved expected-failure counts and duration reporting.
  • Prevented summary content from shrinking or becoming hidden.