@aiquants/daily-report 0.43.0 → 0.44.0

package/README.md

@@ -3,13 +3,14 @@
 Reusable **daily-report** feature package: a virtual-scrolling report list and detail UI with optimistic updates and SSE real-time sync (React Router
 v7 / v8), and a drizzle (**mssql**) server layer. It follows the `@aiquants/authz-*` DI layering: every app-specific concern (authentication, user
 resolution, id obfuscation, Redis, legacy tables, the page chrome) is injected through ports, so the package carries no application- or
-domain-specific knowledge. It is one module with three entries:
+domain-specific knowledge. It is one module with four entries:
 
 | Entry | Contents | Environment |
 | :--- | :--- | :--- |
-| `@aiquants/daily-report` | Types; the strict wire readers (`dailyReportDetailSchema` and `dailyReportSseMessageSchema`, built on the package's in-place reader; `readIdsStreamChunkLine` with `forEachIdsStreamRow`; `readDailyReportSearchMarksAnswer`); the action wire contract and the endpoint tables; the attachment URL codec and the thumbnail variants; the business-date normalizer and the echo-id pattern; the logger contract; the search wire types | isomorphic |
+| `@aiquants/daily-report` | Types; the strict wire readers (`dailyReportDetailSchema` and `dailyReportSseMessageSchema`, built on the package's in-place reader; `readIdsStreamChunkLine` with `forEachIdsStreamRow`; `readDailyReportSearchMarksAnswer`); the action wire contract and the endpoint tables; the attachment URL codec and the thumbnail variants; the business-date normalizer and the echo-id pattern; the logger contract; the search wire types (the search, the search-marks and the per-id `reports` answers) | isomorphic |
 | `@aiquants/daily-report/client` | `DailyReportPage`, list/detail components, hooks, action context, route helpers | browser (React) |
 | `@aiquants/daily-report/server` | `createDailyReportServer` (service + loaders/actions), `defineDailyReportSchema`, SSE fan-out reader, SQL result cache, the sharp thumbnail renderer | node |
+| `@aiquants/daily-report/testing` | `createDailyReportTestInstrumentation` (the views' test handle, the row pass's counters and the re-estimate counters, provided through the client entry's `DailyReportInstrumentationContext` in a host's test build only) and the types of the row pass's events | browser (tests) |
 
 ## Contents
 
@@ -87,7 +88,7 @@ pnpm add @aiquants/daily-report @aiquants/virtualscroll @aiquants/swipe-overlay
 names with ref callbacks that return a cleanup.
 `zod` may be 3.25.76 or later, zod 4 included (`>=3.25.76 <5.0.0`): the package reads zod only through its `zod/v3` entry, which every version in that
 range ships, so the shipped declarations compile and a mismatch names the same issue codes whichever version the host installs.
-The peer floor of `@aiquants/virtualscroll` is **3.17.0**: install 3.17.0 or later.
+The peer floor of `@aiquants/virtualscroll` is **3.18.0**: install 3.18.0 or later.
 Both views name their active row through its `activeItemIndex`, which renders `aria-activedescendant` in the same render as the row and keeps that
 row mounted, count that row as shown only beyond its `activeItemVisibleInset`, describe an empty composite by its empty text, and skip the rendering
 of far rows through its `itemZones` and `useVirtualScrollItem`; they bind its focus-ring colour variable `--aqvs-focus-ring-color` to the row outline
@@ -545,9 +546,12 @@ its payload — with one strict parser each, after authentication and before any
   The mismatch names the failing paths and the issue codes only, never a value (`<path>: <code>` items joined by a semicolon and a space, the root as
   `(root)`), so a host debugging a version skew or a rewriting proxy learns which fields failed and nothing it received reaches a log.
   The package's client fails the action with `[daily-report] <intent> answered a body that is not its result (<mismatch>)`, and reads the `report` and
-  `business-date` endpoints with strict schemas (`{ report }` and `{ reports }` of `dailyReportDetailSchema`): a body that does not match rejects with
+  `business-date` endpoints with strict schemas (`{ report }` and `{ reports }` of `dailyReportDetailSchema`) and the `reports` endpoint with the
+  strict schema of its per-id outcomes (`{ outcomes }`: exactly one outcome per requested id, in request order, so a missing, duplicate, unrequested
+  or reordered id fails the whole answer): a body that does not match rejects with
   `[daily-report] <endpoint> answered a body that does not match its schema (<mismatch>)`, a status other than 2xx with
-  `[daily-report] <endpoint> answered HTTP <status>`.
+  `[daily-report] <endpoint> answered HTTP <status>`, and a `failed` outcome rejects only that report's readers with
+  `[daily-report] reports answered the outcome failed for report <id>` (the batch's other reports settle; [Requests](#requests) under the text search).
   Every detail on the wire — an SSE message's report or posted comment, the action's answer and the read endpoints' answers — is read by one strict
   reader of the shape, on which `dailyReportDetailSchema` is built: it checks the parsed JSON value where it lies and outputs that same value when it
   conforms, so a conforming answer is neither copied nor reshaped (a zod object schema would copy every report's whole tree).
@@ -569,8 +573,9 @@ its payload — with one strict parser each, after authentication and before any
   viewer's id (`userId` of `DailyReportPage`, which the host's loader builds with this port) with the comment's author id (which the service writes
   with it), for comments that arrive by SSE too; an implementation that returns another text on every call (a fresh salt, for example) makes the
   viewer's own comments look like someone else's.
-- `redis` — `getClient()` (get/incr/xAdd/xRange/xRevRange) + `createClient()` (blocking xRead). Structurally matches a `node-redis` v5 client. If
-  omitted, SSE publishing is skipped (with a warning) and epoch is disabled.
+- `redis` — `getClient()` (get/incr/xAdd/xRange/xRevRange/xInfoStream) + `createClient()` (blocking xRead). Structurally matches a `node-redis` v5
+  client. The SSE catch-up from the stream origin reads XINFO STREAM's `length` and `entries-added`, which Redis 7.0 and later report (**Catch-up**
+  under the SSE route). If omitted, SSE publishing is skipped (with a warning) and epoch is disabled.
 - `externalSources[]` — When `Hub.source_type` matches, performs a `LEFT JOIN` on `Hub.source_id_num = idColumn` and converts fields via `mapRow`.
 - `draftLabelNames` — **Required**: the database label names that mark a draft, the canonical one first (such as `["Draft", "Work in Progress"]`,
   since sources may call their drafts by different names). `createDailyReportService` copies and freezes the list, and throws
@@ -1698,15 +1703,17 @@ unexpected error, a request that is not the package's client (another origin's p
 | Malformed cursor | 200, `retry: 86400000` → `event: resync-required` | rereads the ids (server cache bypassed) and reopens from the new anchor |
 | Cursor older than the oldest retained entry (the stream is trimmed with `MAXLEN ~ streamMaxLen`) | 200, `connected` → heartbeat → `retry: 86400000` → `event: resync-required` → end | same as above |
 | The start of a catch-up page is trimmed away before the page is read | 200, the entries delivered so far → `retry: 86400000` → `event: resync-required` → end | same as above |
-| Empty stream, or a cursor inside the retained window or in the future | 200, `connected` → heartbeat → catch-up (every entry) → live | continues |
-| Redis failure during the catch-up, or the stream tail cannot be read while the shared reader fixes its read position (`ready()` rejects; on the path without a cursor before `connected` is written) | the body ends (`producer-failed`) | one native reconnect with `Last-Event-ID`, then the utility's own backoff; the cursor is kept |
+| The stream origin `0-0` as the cursor (the anchor of an ids read on an empty stream) while the stream has removed an entry (XINFO STREAM's `entries-added` exceeds its `length`: trimmed or deleted) | 200, `connected` → heartbeat → `retry: 86400000` → `event: resync-required` → end | same as above |
+| Empty stream (any cursor: no page is read, and entries appended later arrive live), a cursor inside the retained window or in the future, or the origin `0-0` while the stream has removed no entry (the catch-up starts at the stream's first entry) | 200, `connected` → heartbeat → catch-up (every entry) → live | continues |
+| Redis failure during the catch-up, an XINFO STREAM reply without the counts (`length` and `entries-added` must be safe integers with `entries-added` ≥ `length` ≥ 0; a Redis older than 7.0 has no `entries-added`), or the stream tail cannot be read while the shared reader fixes its read position (`ready()` rejects; on the path without a cursor before `connected` is written) | the body ends (`producer-failed`) | one native reconnect with `Last-Event-ID`, then the utility's own backoff; the cursor is kept |
 
 - **Resume cursor**: `readLastEventId` reads the `Last-Event-ID` header first, then the `lastEventId` query parameter
   (`DAILY_REPORT_SSE_CURSOR_PARAM`). The browser's own reconnect reuses the URL it opened with (a stale query) but sends a fresh header, so the header
   is always the newer value. A cursor must be a Redis stream id of the form `<ms>-<seq>` with 1–15 digits per part; anything else is answered with
   `resync-required`. The client URL-encodes the cursor.
 - **`connected` frame**: `data: {"type":"connected"}` with `id:` set to the resume position (the cursor, or the newest entry at connect time when
-  there is no cursor). On the cursor path it is written before any Redis round trip.
+  there is no cursor), and without `id:` while that position names no entry (the origin cursor `0-0`, or an empty stream without a cursor). On the
+  cursor path it is written before any Redis round trip.
   Without a cursor it is written only after the shared reader has fixed its read position (`DailyReportSseReader.ready()`), so every entry appended
   after a client sees `connected` reaches that client; on the cursor path the catch-up is read after that point instead, so nothing appended between
   the catch-up and the position fix is lost.
@@ -1727,9 +1734,15 @@ unexpected error, a request that is not the package's client (another origin's p
   most 64 MiB into the process, also when every entry is as large as an event can be. A catch-up reads its pages per connection; a catch-up of 1,000
   small events takes 113 round trips (one check of the oldest entry and 112 pages, each new page reading 9 entries after its start).
 - **Catch-up**: entries after the cursor are read in pages of `DAILY_REPORT_SSE_CATCH_UP_BATCH` (`xRange` is inclusive, so each page skips its start
-  id) until the stream end; every entry is delivered. When a page does not start with its start id, the oldest retained entry is read again: if it is
-  newer than the start id, the range after it may have been trimmed, so the connection ends with `resync-required` instead of silently skipping it (a
-  cursor that is simply not an entry id inside the retained window continues).
+  id) until the stream end; every entry is delivered. The catch-up first reads the oldest retained entry. An empty stream reads no page, for any
+  cursor: the shared reader, subscribed before the catch-up, delivers every entry appended later live (a page read would take an entry appended
+  meanwhile for a trimmed range). A cursor that names an entry is witnessed by the oldest retained entry: when that is newer than the cursor, the
+  range after the cursor may have been trimmed, so the connection ends with `resync-required`. The stream origin `0-0` names no entry, so its witness
+  is that the stream has never removed an entry (XINFO STREAM's `entries-added` equals its `length`): the oldest retained entry is then the first the
+  stream ever got, and the first page starts there and delivers it too; otherwise the connection ends with `resync-required`. When a page does not
+  start with its start id, the oldest retained entry is read again: if it is newer than the start id, the range after it may have been trimmed, so the
+  connection ends with `resync-required` instead of silently skipping it (a cursor that is simply not an entry id inside the retained window
+  continues).
 - **Ids on the wire only increase**: live entries that arrive during the catch-up are queued, not written. The catch-up stops in front of the first
   queued entry (the fan-out reader delivers every entry after it in order), then the queue is written in id order and later live entries are written
   as they arrive. Writing a live entry first would let a disconnect move the client's resume position past catch-up entries it never received, and an
@@ -1741,8 +1754,11 @@ unexpected error, a request that is not the package's client (another origin's p
   provisional line). The service reads it inside the cached fetcher **before** the SQL, so every cache path (bucket hit,
   joining an in-flight fetch, refresh-ahead) returns an array that already reflects every update up to the anchor. The
   SSE hook does not connect until an anchor arrives and then uses it as the first cursor, which closes the gap between
-  loading the ids and opening the stream. `null` means "position unknown" (empty stream, no redis, read failure): the
-  hook then opens without a cursor and the server starts from the newest entry at connect time.
+  loading the ids and opening the stream. An empty stream anchors at the stream origin `"0-0"`, which the hook sends as
+  its cursor like any other anchor, so a report published between the ids read and the connect arrives through the
+  catch-up (**Catch-up** above). `null` means only "position unknown" (no redis, a read failure, or a viewer without an
+  internal user): the hook then opens without a cursor and the server starts from the newest entry at connect time,
+  so an entry appended between the ids read and the connect is not delivered (the gap that an unknown position leaves).
 - **Delivery is idempotent**: an anchor can be up to one ids-cache TTL old; replaying from it is safe because `report-*` messages upsert and
   `comment-add` is matched by comment id.
 - **Event size**: the service writes an event to the stream only when its JSON is at most 6,356,992 bytes: the action's form cap (1 MiB,
@@ -1994,37 +2010,51 @@ The 400s come in order, all before any service call: `q` and `combine` (`Invalid
 (`Invalid search query` with the plan's `reason`). `q` stays required: a blank `q` (`q=` included) with a filter is the filters-only search, and
 without one it is still the 400 `empty`.
 A request without filter parameters adds no condition to the SQL: its statement and parameters are those of the text search alone.
-`GET {apiBasePath}/reports?ids=<id,id,...>` (distinct canonical ids, at most 100) answers the visible details among them, `{ reports }`. Neither is
-cached on the server.
+`GET {apiBasePath}/reports?ids=<id,id,...>` (distinct canonical ids, at most 100) answers one outcome per requested id, in request order, `{ outcomes }`
+(`DailyReportSearchDetailsAnswer` of `DailyReportSearchDetailOutcome`): `ok` with the report (its delivered JSON copy, read strictly), `not_found`
+for an id the viewer cannot read, a missing id and a deleted report alike (never told apart, so the answer is no existence oracle), or `failed` for a
+report the viewer may read whose own assembly failed (its display fields, its mapping, its JSON copy or the strict read of that copy); the server logs a
+`failed` report's id and cause on its logger, and the answer carries no cause, so the batch's other ids are answered. The cause is logged once per
+read and report in a window of 60 s (`[DailyReportService] <read>: report <id> passed the visibility predicate but its own assembly failed` at
+`error`, the read being the service method, `getDailyReportDetailsByIdsByExternalId` here and `markDailyReportSearchHits` for the marks); later
+failures of that report in that read are only counted, and the window's end writes them as one `warn` line,
+`[DailyReportService] failed_report_suppressed count=<n> since=<the window's start, ISO> read=<read> report=<id>`, so a broken report that every
+batch asks for writes a bounded number of lines. The reports are read in slices under the request's signal, like the marks (**Slices** below).
+A failure before or across the
+visibility predicate (the viewer's resolution, the query, the batched label, comment and attachment reads, the canonical draft label) fails the whole
+request with 500, since a per-id `failed` for an id that never passed the predicate would tell it apart from `not_found`. Neither is cached on the
+server.
 `reports` has an admission of its own from the same factory, never the search's: 2 × the larger of `concurrency` and
 `DAILY_REPORT_SEARCH_BATCHES_IN_FLIGHT` (2, the batch reads the client keeps in flight) reads at once per process, of which one viewer holds at most
 half, so a viewer always passes the client's two concurrent reads (a `concurrency` of 1 admits 4 per process),
 and 10 × `rateLimitPerMinute` reads per viewer and minute, in a bucket apart from the search's, so paging through a large answer neither runs out of
 reads nor spends the searches.
-Its order is the search's: the ids (400), then a viewer without an internal user answered `{ reports: [] }` with no admission and no dataset query,
+Its order is the search's: the ids (400), then a viewer without an internal user answered every id `not_found` with no admission and no dataset query,
 then the admission with the request's signal (an aborted request takes no slot, returns its token and gets the bodyless 503; a read that finds the
 gate full or its viewer at its share waits for a slot like a search-marks batch, for at most 2 s, then gets 429 with `Retry-After: 1`; an empty bucket
-is 429 with one window's `Retry-After`), the query, and the slot's release whatever the outcome. Its refusal lines name `route=reports`.
+is 429 with one window's `Retry-After`), the read with the request's signal (in slices, yielding to the event loop between them), and the slot's
+release whatever the outcome. Its refusal lines name `route=reports`.
 `GET {apiBasePath}/search-marks?q=<text>&combine=intersection|union&ids=<id,id,...>` (the shown answer's query and at most 100 distinct canonical ids,
 the rows a view draws) answers `{ wordsDigest, reports, deferred }` (`DailyReportSearchMarksAnswer`): in `reports`, for each requested report the
-viewer may read that the answer's budget holds (below), once, its id, the mask of the keywords it matches (`matchedSets`: bit i for keyword i, for an
+viewer may read, whose delivered copy the server assembles (as `reports` does: a report that fails to assemble is logged and left out like an unreadable
+one, so one broken report never removes the marks of its neighbours) and that the answer's budget holds (below), once, its id, the mask of the keywords it matches (`matchedSets`: bit i for keyword i, for an
 OR of two or more keywords;
 `null` otherwise) and the marks of every non-empty field value the views draw (`fields`, by key: `subject`, `content`, `author`, `employeeName`,
 `updatedBy`, `category`, `creationCategory`, `customerName`, `interviewer:<i>:name|affiliation`, `attachment:<i>` and `comment:<id>:author|content`,
 the comment's id in the list `useDailyReportComments` returns).
 In `deferred`, the ids of the readable requested reports past the budget, in the answer's order (empty when it held them all), so a requested id is in
-`reports`, in `deferred`, or — not readable — in neither, and never twice. `wordsDigest` is the digest of the answer's `words`.
+`reports`, in `deferred`, or — not readable, or failed to assemble — in neither, and never twice. `wordsDigest` is the digest of the answer's `words`.
 A field's marks (`DailyReportSearchFieldMarks`) are the fingerprint of the raw value they were computed on (FNV-1a 32 over its UTF-16 units) and
 either `ranges`, flat `[start, end, tier]` triples in UTF-16 offsets of that value,
 or `dense: true` without `ranges`, for a field with more ranges than `maxFieldRanges` (10,000: more marks than a reader can tell apart, whose drawing
 alone would add tens of ms to the client's render; a one-letter word over a report of 21,200 units marks about 2,000). The client's reader refuses a
 field with both, a `dense` that is not `true`, a `deferred` id that was not requested, is listed twice or also has marks, and an answer that defers
-ids without carrying a report (the server always answers the first report, so such an answer breaks the contract, and asking again would make no
-progress).
+ids without carrying a report (the server always answers the first assembled report, so such an answer breaks the contract, and asking again would
+make no progress).
 A field's triples are its maximal runs of one tier, overlapping and adjacent occurrences merged into one, so they never overlap and a field carries at
 most one triple per UTF-16 unit of its value.
 An answer has a budget: at most 500,000 ranges and 4,000,000 raw UTF-16 units of the fields it marks.
-The reports are marked in the answer's order, and the first is always answered, so every request makes progress; from the first later report that
+The reports are marked in the answer's order, and the first assembled report is always answered, so every request makes progress; from the first later report that
 would take the answer past either bound (its units are counted before a field is marked, its ranges after), every report is deferred: its fields are
 not marked and its id goes to `deferred`, for the client to ask again (**Arrival** under **Highlights** below).
 The budget holds whole a one-letter word over 100 reports of 21,200 units each (about 200,000 ranges and 2,120,000 units; 1.6–2.9 MB, against 2.2 MB
@@ -2042,7 +2072,9 @@ runs, and its marks equal those of the per-occurrence definition byte for byte.
 work passes 8 ms or 5 ms have passed on the
 process's monotonic clock, and the first step of a slice always runs, so every slice makes progress), and the service yields to the event loop and
 checks the request's signal between two slices,
-inside a field too. No step of the work is longer than a block of 0.5 ms of estimated work, except the index text of one piece of a line (at most
+inside a field too. The delivered read slices the same way, with the same slicing, before the marks and as the whole of `reports` (a report's JSON
+copy and strict read are one step, so the read yields before the next report once a slice has run 5 ms, and the longest synchronous block of a
+`reports` answer is its one serialization); before the marks the service yields once more after it, so the marks start a fresh slice. No step of the work is longer than a block of 0.5 ms of estimated work, except the index text of one piece of a line (at most
 4,000 units) and one grapheme cluster longer than a
 block of the segmentation: on values of 1,000,000 units — only line breaks, one letter per line, invisible characters with line breaks, a fullwidth
 `ＡＢ` line with no cut between its pieces,
@@ -2065,17 +2097,19 @@ Its order is the search's and the details': 404 without the `search` block, 400
 400 for the ids, then a viewer without an internal user answered `{ wordsDigest, reports: [], deferred: [] }` with no admission and no dataset query,
 then the admission with the request's signal, the marks (in slices, yielding to the event loop between slices, inside a field too), the slot's release
 whatever the outcome, and the JSON. It is not cached on the server either.
-The service takes the request's signal too (`markDailyReportSearchHits(scope, userId, plan, ids, { signal })`) and checks it before each read and
-after each yield, stopping at the next slice once the client has left, between two slices of one field too.
-Options that are not an object carrying an `AbortSignal` stop the call before any query with a host-facing error: an omitted `options` or `signal` is
-a `TypeError`
-(`[daily-report] markDailyReportSearchHits: options.signal must be the request's AbortSignal (new AbortController().signal for a call that is never aborted)`),
-any other value a `RangeError` ending with `; got <value>`.
-The route always passes the request's signal; drizzle cannot cancel a running query, so the slot is held until the read in progress ends. A request
+Both per-id reads of the service take the request's signal (`markDailyReportSearchHits(scope, userId, plan, ids, { signal })` and
+`getDailyReportDetailsByIdsByExternalId(scope, ids, externalId, { signal })`) and check it before each query and after each yield, stopping at the
+next slice once the client has left, between two slices of one field too.
+Options that are not an object carrying an `AbortSignal` stop the call before any query with a host-facing error naming the method: an omitted
+`options` or `signal` is a `TypeError`
+(`[daily-report] markDailyReportSearchHits: options.signal must be the request's AbortSignal (new AbortController().signal for a call that is never aborted)`,
+and the same with `getDailyReportDetailsByIdsByExternalId`), any other value a `RangeError` ending with `; got <value>`.
+The two routes always pass the request's signal; drizzle cannot cancel a running query, so the slot is held until the read in progress ends. A request
 whose client left — while it waited, when its slot was granted, at one of the service's checks or after the service answered — is answered 503 without
 a body, with `Retry-After` and `Cache-Control: no-store` and no ETag, and writes no error line;
-the four search routes share this answer and its checks (the search, `reports` and `search-facets` pass no signal to their services and check it when
-the slot is granted and when the read ends; a read that fails with an error of its own is still the 500), and the refusal of an aborted request is
+the four search routes share this answer and its checks (the search and `search-facets` pass no signal to their services and check it when the slot
+is granted and when the read ends, `reports` and `search-marks` pass it to theirs; a read that fails with an error of its own is still the 500), and
+the refusal of an aborted request is
 never recorded as busy, on any of them (`search-facets` included).
 Its 200 carries no ETag and `Cache-Control: no-store` (serialized once, with the shared security headers), and so does every other answer of the
 endpoint — its 400, 404 and 429, the router's 405 and 500 for it, and that 503 —, as every answer of the API route that is not a 200 does (**The API
@@ -2134,8 +2168,8 @@ line wraps instead of truncating;
 it comes first in the field's description (before the syntax help), and the field is `aria-invalid` only for an invalid query (busy, unavailable and
 other failures are no input errors).
 The AND / OR toggle and the filter toggle share one look: a 24 px pill with 12 px semibold text, in the field face (OR; the closed filter row), whose
-boundary comes from the text-field token as the field's does, or the filled face (AND; the open filter row), blue-700 under white text (dark blue-600)
-and `Highlight` under `HighlightText` in forced colours (**Text fields** in [Selection and focus appearance](#selection-and-focus-appearance)).
+boundary comes from the text-field token as the field's does, or the filled face (AND; the open filter row), blue-800 under white text (dark: a light
+blue-300 fill under slate-950 text) and `Highlight` under `HighlightText` in forced colours (**Text fields** in [Selection and focus appearance](#selection-and-focus-appearance)).
 The faces differ only in colour, so a toggle that changes its face moves nothing. Each toggle stacks its current label and an invisible reserved label
 in one grid cell — the AND / OR toggle the other mode's label, the filter toggle its label with the largest number of selected values (every filter at
 its limit) —,
@@ -2263,7 +2297,7 @@ While an answer shows, the List cards, the side pane and the DetailList rows mar
   fill continues under the `…` while its underline ends at the last character shown (a cut at a mark's start shows a filled `…` alone).
   An `interviewerWithAffiliation` template that does not insert the name and the affiliation verbatim (it rewrites them, uses one twice, or words
   itself by their values) draws the pill plain. `LIKE` counts an occurrence inside a grapheme cluster, so such a match marks the whole cluster.
-- **Look**: one token: yellow-200 under slate-900 (dark yellow-800 under yellow-50; 15.33:1 and 6.61:1 on any surface, since the mark sets its own
+- **Look**: one token: yellow-200 under slate-900 (dark yellow-900 under yellow-50; 15.33:1 and 8.38:1 on any surface, since the mark sets its own
   text colour), a solid underline for a word and a dotted one for a reading (a cue that does not depend on colour), and the system `Mark` / `MarkText`
   in forced colours.
   It writes `margin`, `border` and `padding` 0 and inherits the font, so a host's `mark` rule cannot change it and a mark changes no width, no line
@@ -2750,8 +2784,8 @@ view, and no script computes or writes a height.
   text anyway.
 - **Empty list**: an empty view shows exactly one message, `VirtualScroll`'s own empty state with the engine label `labels.noItems` (en "No items", ja
   「項目がありません」), which `VirtualScroll` draws over the top of its content, out of the flow, so an empty view keeps the same box. The views render no
-  message of their own; they only theme the engine's (on `VirtualScroll`'s root: 16 px above and below, slate-500 in light and slate-400 in dark:
-  4.55:1 and 7.66:1 against the page, where the engine's default grey reaches only 4.17:1 in dark).
+  message of their own; they only theme the engine's (on `VirtualScroll`'s root: 16 px above and below, in the quiet text colour: 7.39:1 and 9.75:1
+  against the page in light and dark, where the engine's default grey reaches only 4.17:1 in dark).
   Because the views pass an active row (`activeItemIndex`, `null` while the list is empty), `VirtualScroll` draws the message outside the composite —
   in a layer over the composite's box, with the same pixels and the same `.aqvs-no-items-container` / `.aqvs-no-items-text` hooks — and names it first
   in the composite's `aria-describedby`, before the key help: the `treegrid` owns nothing but rows, and a screen reader entering an empty view (a
@@ -2903,9 +2937,15 @@ the resize handle and the side pane lie outside the list.
   renderer do not render, and no context value changes per key.
   The app's keyboard harness counts the style and layout work that starts inside a keydown dispatch or inside a frame callback the key caused: 0 in
   every run of its nine conditions.
-- **Rows mount in two passes.** A row that a commit mounts outside the visible range first renders as a **shell**: its row frame, with its role,
-  id, position, set size, level and selection, named by the report's ISO business date and `aria-busy="true"`, and an empty surface
-  (`data-daily-report-row-shell`) that fills the box `VirtualScroll` gives the row, so nothing moves when the body arrives.
+- **Rows mount in two passes.** A row that a commit mounts outside the visible range first renders as a **shell**: its row frame, with its role, id,
+  position, set size, level and selection, and a surface (`data-daily-report-row-shell`) that fills the box `VirtualScroll` gives the row, so nothing
+  moves when the body arrives. The surface is the card's surface without content (the card surface token: its radius, border, colours and shadow),
+  so the selection ring and the focus outline around a shell are concentric with it as around a card, and the resting surface does not change when
+  the card lands. While the report's details are still loading, the shell is named by the report's ISO business date and is
+  `aria-busy="true"`. Once the details are in the store, the shell is a **named shell**: it holds, hidden, the card's own name and the parts of the
+  card's description that do not depend on drawing (the row state, the attachment marker with its count, the source badge's text, the List preview and
+  the matched-keywords sentence), made by the same functions as the card's, so the active descendant announces the row as it will read as a card. Only
+  the matched-fields and outside-view sentences, which the drawn leaves report, arrive with the card. The settled DOM never contains a shell.
   One scheduler per view then advances the rows one at a time — a shell to its body, a body that still draws older inputs to the latest ones (a report
   that arrived by a load's answer or an SSE update, or the report's search marks) — each unit applied with `flushSync` as one commit of its own.
   A row reads its report's details and search marks through one input source from the moment it mounts, and a unit draws what the source holds when it
@@ -2917,18 +2957,27 @@ the resize handle and the side pane lie outside the list.
     two cases named below (a row that becomes visible, and a newer input of a visible row outside a key hold). The first callback after the scheduler
     wakes only calibrates. The scheduler arms itself
     with a `MessageChannel` message and calls `requestAnimationFrame` only from its own message and callbacks — never from a keydown, a commit or the
-    held key's frame — so the harness never counts its work as a key's.
+    held key's frame — with one exception: when a key hold starts (in its first repeat keydown, before the hold's first step) in a view that has a
+    measured row (each mounted row declares how its box is sized, and the DetailList's rows are measured), and the scheduler has no frame requested and
+    has not classified the hold yet, it requests one bare listening frame there (it applies no unit, writes no DOM and reads no clock in the keydown),
+    and its `hold-start` event says so (`listening`), so a harness that counts frames requested in a keydown as key work can tell the scheduler's frame
+    apart. A view whose rows all have fixed boxes (the List) never listens, since the key frames' evidence below classifies measured rows only: during
+    a hold its scheduler sleeps whenever no unit can run.
   - **A frame's share.** A key-free frame applies its first unit, then more units only while their measured costs (the p90 of the latest 32 per kind
     of unit, known after 8; kinds are a box sizing and a change: a body over a shell, a change that can change the box, the marks alone) fit half the
     frame interval and the time left in the frame. At today's costs a DetailList card takes one frame, and the List packs 1–3 rows. A frame whose
     callbacks started late (a GC or a long task ran before them) skips its first unit when that unit no longer fits (a 2 ms margin); a unit of a
     visible or reach row is skipped by at most one late frame in a row.
   - **Order.** By zone — visible, then the active row's reach, then near, then far (**Far rows skip rendering** below) — and within a zone by the
-    distance from the active row, the side the keys travel towards first; equal ranks keep the order the units were added in. While a key is held, far
-    rows ahead in the travel direction are drawn after the near ones, so the rows a hold brings into the reach already have their bodies; far rows
-    behind wait for the key's release.
+    distance from the active row, the side the keys travel towards first; equal ranks keep the order the units were added in. The travel direction is
+    the active row's move, read at every frame callback and, during a hold, whenever units are ranked, so a hold takes its direction from its first
+    key step (a hold upwards draws the far rows above from its first key) and never from a jump before it. While a key is held, far rows ahead in the
+    travel direction are drawn after the near ones, so the rows a hold brings into the reach already have their bodies; far rows behind wait for the
+    key's release. While the active row is pinned outside the rendered range or absent (a wheel or a fling), the rows are ranked by the pane instead:
+    those ahead of the pane's travel first, by their distance from the visible range, and while the pane moves, the units of one viewport ahead of it
+    are never skipped as late, so the rows a fling passes are drawn before they become visible.
   - **Visible rows are never stale.** A row that becomes visible with a pending unit renders its body inside the commit that made it visible, so a
-    visible row is never a shell and never shows outdated data or marks (counted). Outside a key hold, a newer input of a row that is already visible
+    visible row is never a shell and never shows outdated data or marks (counted), with one exception on a device where a card exceeds a frame (below). Outside a key hold, a newer input of a row that is already visible
     is drawn at once: in the commit that brings it, or, when it arrives as a store notification, in one commit at the end of the notifying task.
   - **Search answers lead the rows' inputs.** While a search answer is shown, each view keeps its rendered rows and 24–40 rows beyond each rendered
     edge subscribed to the details and the marks (8 more rows on the side it travels towards whenever fewer than 24 remain, 32 on each side after a
@@ -2948,9 +2997,22 @@ the resize handle and the side pane lie outside the list.
   With a 30 ms key repeat at 60 Hz, a hold has about 0.8 key-free frames per key and brings about one row per key into the reach, so a 40-key hold
   keeps several bodied rows ahead of the active row; holds longer than about 60 keys draw the bodies they reveal inside the key's own commit (one
   complete card each, counted).
-  On a slow device (the CPU slowed 4×) a held key renders about 9 frames a second — the next frame's p95 is about 109 ms against the 33 ms target —
-  because each key frame's own style, layout and paint take that long; every row that enters the visible range is still complete, with its card and
-  marks, at its entry.
+  On a device where a DetailList card exceeds a frame, a held key draws no card in its frames. The scheduler classifies the device from what it
+  measures, with no device constant: a kind of unit exceeds the frame when its measured p50 exceeds the class limit, the display's frame interval
+  floored at the 60 Hz interval, less 2 ms. That is 14.67 ms on a 60 Hz display and on a faster one alike: an interval more than 1 ms below 16.67 ms
+  (a display above about 64 Hz) is judged as 16.67 ms, because the frame targets are written for 60 Hz frames, so the class follows the device's CPU
+  and not the display's rate (a 120 Hz display's own interval less 2 ms, 6.33 ms, would classify every DetailList hold at 1×). The interval is the
+  display's, read from the frames that were not pushed back, so a slow device does not stretch it. During a hold and for the DetailList's measured
+  cards, a kind also exceeds the frame when the median of the hold's key frames does (from 3 samples: the key frames' own weight, measured even
+  while the scheduler draws nothing, from their busy time, or from their cadence when a frame's work outlasted the class limit and missed the vsync
+  after it, which a gap of 1.5 display intervals past the vsync before the one nearest the limit's end shows: 1.5 intervals at 60 Hz, 2.5 at 120 Hz
+  and 144 Hz). The end-of-frame message of the frame after which the scheduler slept adds no sample: it waits behind input and rendering, so its time
+  measures that wait, not the frame. On such a device the rows that enter
+  the visible range during the hold stay named shells, the scheduler sleeps, and after the key's release it draws the active row's card first and then
+  the visible shells in their visible order. At 1× no kind ever exceeds the frame on a 60, 120 or 144 Hz display (a DetailList card's p50 is
+  7.3–8.4 ms and the key frames' median at most about 13.6 ms), so every entering row is complete at its entry. With the
+  CPU slowed 4× before a 40-key hold, the hold classifies itself by its 6th or 7th key, 23–26 rows enter as named shells, and the next frame's p95 is
+  27.4–45.1 ms (median 33.4) against the 33 ms target. The List's rows fit a frame even then, so the List keeps every row complete at its entry.
   Decisions never wait for the drawing: the card and the error surface are both drawn from the unit's snapshot, and only the safety valve that
   removes a row whose report no longer exists, the busy state of a row whose card or error waits for its unit (a load error that arrived but is not
   drawn yet keeps the row's skeleton, never a "not found" surface), and a DetailList body's draft and ownership, its opening of the viewer's own draft
@@ -3073,10 +3135,14 @@ the resize handle and the side pane lie outside the list.
     (re-recording there would read the clamped position against the previous list's rows, name another report and leave the view displaced by up to
     the last row's height).
   - **Scrolls `VirtualScroll` makes for the user** (wheel, drag, the scroll bar, inertia) are recorded each time the view reports its visible range,
-    once per frame. A fling far beyond the DetailList's rendered window is not symmetric: the rows it passes as shells are drawn above the pane
-    afterwards and grow from the unmeasured estimate (352 px, below every measured row) to their heights, and `VirtualScroll`'s compensation keeps the
-    visible rows in place, so wheeling back by the same distance lands several hundred px (up to about 1,100) away from where the fling started; the
-    visible rows never jump. A list change in the frame before that report first advances the anchor by the distance scrolled since it was recorded and
+    once per frame. During a fling far beyond the rendered window the rows are ranked by the pane (those ahead of its travel first) and the rows of
+    one viewport ahead of a moving pane are drawn before they become visible (**Rows mount in two passes**). Over rows of one height (the List)
+    wheeling back by the same distance lands where the fling started. Over measured rows (the DetailList) a fling is not yet symmetric: the rows it
+    passes before they are drawn are laid out at the measured estimate (below) and change to their own heights when they are drawn above the pane, and
+    `VirtualScroll`'s compensation keeps the visible rows in place, so a plain 20,000 px fling and back lands 156–548 px away from where it started
+    (measured in Chromium with React's development build, where a card takes 10–26 ms to draw, so the rows a fling passes are measured late); the
+    visible rows never jump, and content that was drawn and measured never moves: wheeling there and back in steps that each wait until the rows they
+    mount are drawn lands on the start report exactly. A list change in the frame before that report first advances the anchor by the distance scrolled since it was recorded and
     restores from there: it neither undoes the user's scroll nor shifts the content by a row.
     Over rows of one height (the List) the new anchor follows from the distance by arithmetic; over measured rows (the DetailList) it walks the
     previous list's row heights from the anchor to the report now at the top, so the walk is bounded by the rows passed since the record (one frame's
@@ -3201,6 +3267,9 @@ the resize handle and the side pane lie outside the list.
   the comment form: see [External Source Badge Configuration](#external-source-badge-configuration-sourcetypeconfigs)).
   The comment field is named by that heading (`aria-labelledby`; `labels.comments`), which renders whenever the form does, so the field has a name of
   its own in the DetailList row, the side pane and the mobile overlay; its placeholder (`labels.commentPlaceholder`) stays a hint, not its name.
+  While a post is sent, the field keeps the draft, read-only, with the submit button disabled, and empties only when the post is accepted; a refused
+  post (401, 403, a 5xx) leaves the draft, its text and its caret untouched, so a viewer whose session ended sends it again after signing in
+  (the package's part of WCAG 2.2.5; keeping a draft across a navigation or a reload is the host's).
   A report of a source that takes no comments and has none shows no empty section, and deleting the last comment of such a report removes the section,
   so focus goes to the report's anchor above.
 - **Mobile detail overlay** (List, single-column layout): the platform's modal dialog, a `<dialog data-daily-report-mobile-overlay>` (implicit
@@ -3258,6 +3327,7 @@ and their versions, and per step either a pass or the text announced.
 | Empty and no-category views | A search that matches nothing, and a viewer who may see no category: Tab into the view | The composite is announced by its title, described by the empty text (「項目がありません」) and the keyboard help, with no row; for the viewer without a category, the page's notice (「閲覧できる日報の区分がありません。…」) is reached in browse mode before the view |
 | Overlay close | Phone layout, List: open a report's overlay with Enter on the composite and close it with Escape; open it with a tap and close it with the close button | After the keyboard close, focus is on the composite and the same row is announced as active; after the tap close, focus is on the card's primary button, announced with its position first |
 | Touch hand-back in the DetailList | Touch reader, DetailList: in the active row of your own report from a source that takes no comments, delete its last comment (the trash button, then the confirmation) | The comment section leaves and focus lands on the row's name heading, announced as the report's date, author and subject (not on the list as a whole) |
+| Held key on a slow device | Desktop, DetailList with a search answer shown, Chrome's CPU throttling at 4× (DevTools, Performance): hold ArrowDown for about 40 keys, then release | While the key is held, each active row is announced with its name and its description (state, attachments, source, the matched-keywords sentence), even when its card has not been drawn; after the release, the active row's card arrives first and its description gains the matched-fields sentence; nothing is announced twice |
 | Far rows | Browse mode (NVDA, JAWS, Narrator) or swiping (VoiceOver on iOS, TalkBack) past the visible rows | The rows within one viewport of the visible range are reached; rows farther away are reached only once the list has scrolled near them (**Far rows skip rendering**); the active row is always reached |
 | Switch Access | Android, Switch Access with Chrome, List on the phone layout: scan to a card and select it, then close the overlay with its close button | The card is reachable by scanning and opens the overlay; after the close, focus (which Switch Access follows) is on that card's primary button, or on the composite when the page recorded no pointer input for the action (a hand-back after no recorded input lands on the composite): record which, and that scanning continues from there |
 | Forced colours | Windows contrast theme (forced colours) with the keyboard: move the active row with the arrows, wheel it out of view, then press a key | The selected row shows the system's `Highlight` outline, the active row's keyboard outline shows in the system colour while it is visible, and the composite's 2 px pane ring shows while the active row is out of view |
@@ -3334,8 +3404,9 @@ luminance by 0.026 in the light theme, and a `shadow-md` brings the ring down to
   Measured in Chromium 148 at 412 × 915 and 2.625: with bodies rounded to 4 px, a DetailList row of 980 px ended at 6,478.5 device pixels and the
   surface edge of the next row blended into two rows of device pixels; rounded to q, the revealed row's surface top sits at device pixel 273 in every
   reveal.
-  A row that has not been measured yet is laid out at an estimate of 352 px (88 u = 44 × 8), also on the lattice at every ratio of the domain, so the
-  unmeasured rows above the window move the rows below by whole device pixels. An image attachment tile is padded to q as well (**Tile** in
+  A row that has not been measured yet is laid out at the view's measured estimate — the median of the heights the view has measured, rounded up to
+  8 px (2 u), and 440 px (110 u) until it has measured one; the view applies a changed estimate only at rest, with the first visible report kept in
+  place — also on the lattice at every ratio of the domain, so the unmeasured rows above the window move the rows below by whole device pixels. An image attachment tile is padded to q as well (**Tile** in
   [Attachment display](#attachment-display)), so the rows below an image grid stay on whole device pixels.
 - **List card**: a wrapping row of the primary button and the action row (markers and toggles), with the preview always on the next line. The primary
   button takes the remaining width but never less than 96 px, enough for the business-date pill, and the action row keeps to the card's end; on a card
@@ -3481,16 +3552,19 @@ luminance by 0.026 in the light theme, and a `shadow-md` brings the ring down to
 
 - **Text fields**: the comment input, the edit form's `Input` and `Textarea` and the search field, and the outline of the search band's toggles in
   their field face (the OR toggle and the closed filter toggle), take their boundary and placeholder from one token: a 1 px slate-500 border in both
-  schemes and a slate-500 placeholder (dark slate-400).
+  schemes and a placeholder in the quiet text colour (below).
   Each field declares its own `border border-solid` beside its inset and its own package fill (white, the comment input slate-50 turning white on
   focus; dark slate-900, the comment input slate-800 turning slate-900); none reads the host's `--input`, `--muted-foreground`, `--primary` or
   `--destructive`.
   The boundary reaches the 3:1 of WCAG 1.4.11 against every surface a field sits on and against the field's own fill, its focus fill included (light:
-  4.76 on white and 4.55 on slate-50; dark: 3.74 on slate-900, 3.07 on slate-800 and 4.23 on slate-950), and the placeholder reaches 4.5:1 on each
-  field's fill.
-  The toggles' filled face (AND, and the open filter toggle) is a blue-700 fill (dark blue-600), whose edge is its boundary (6.52:1 on the page, dark
-  3.84:1), under white text (6.82:1, dark 5.25:1); it stands 6.82:1 (dark 3.40:1) from the field face's fill, so open and closed differ in more than
-  hue, and forced colours draw it as `Highlight` under `HighlightText` while the field face keeps the forced button colours.
+  4.76 on white and 4.55 on slate-50; dark: 3.74 on slate-900, 3.07 on slate-800 and 4.23 on slate-950), and the placeholder reaches 7:1 on each
+  field's fill (light: 7.73 on white, 7.39 on the comment input's slate-50; dark: 8.62 on slate-900, 7.07 on the comment input's slate-800).
+  The toggles' filled face (AND, and the open filter toggle) is a blue-800 fill under white text in light and a light blue-300 fill under slate-950
+  text in dark, whose edge is its boundary (8.43:1 on the page, dark 11.12:1), with its text at 8.82:1 (dark 11.12:1); it stands 8.82:1 (dark 9.83:1)
+  from the field face's fill, so open and closed differ in more than hue, and the blue-400 focus outline, drawn 2 px outside the face, stands 1.45:1
+  from the dark fill. No dark fill under white text can meet both the 7:1 of the text and the 3:1 of the fill against the page, since the two ratios
+  multiply to white against the slate-950 page, 20.16 < 7 × 3. Forced colours draw it as `Highlight` under `HighlightText` while the field face keeps
+  the forced button colours.
   `src/client/ui/ui-state-contrast.spec.ts` computes these pairs for every site from the site's own classes (so a site that drops the token fails),
   and its host-token guard covers the token, the primitives and the sites.
 
@@ -3704,8 +3778,25 @@ luminance by 0.026 in the light theme, and a `shadow-md` brings the ring down to
   are exactly the token's, and the search box's spec renders every status message in both locales and checks that the line carries the token and no
   truncating class.
 - **Type and contrast**: no text is smaller than 12 px (`text-xs`; a scan of every module under `src/client` rejects a smaller arbitrary size,
-  `src/client/components/report-views.spec.tsx`); text reaches 4.5:1 and the indicators 3:1 in both themes (section labels slate-500 / slate-400: 4.77
-  / 7.09). The floating tap-scroll circle hides while the view root carries `data-daily-report-keyboard-focus` (through the class both views pass in
+  `src/client/components/report-views.spec.tsx`); every text colour reaches 7:1 (WCAG 1.4.6, AAA) against every surface it can sit on, in both themes
+  and every state (hover, active, `aria-*`, `data-*`, translucent surfaces composited over theirs), and the indicators 3:1:
+  `src/client/ui/aaa-text-contrast.spec.ts` scans every class literal of the shipped client (and the comment authors' colours) that sets a text colour,
+  refuses one without a registered surface, and measures each against its surfaces. The quiet text (section labels, metadata, placeholders, the empty
+  view, inactive tabs) is one token, `--aqdr-text-quiet` (light `oklch(44% 0.046 257.417)`, dark `oklch(77% 0.040 256.788)`: slate-500's and
+  slate-400's hue and chroma), whose lightness `src/client/ui/aaa-quiet-text.spec.ts` solves from the surfaces it sits on (light 7.06–7.73, dark
+  7.07–9.75). A source badge's colours are the host's (**External Source Badge Configuration**). Targets stay at WCAG 2.5.8's 24 px, except the
+  List's resize handle with its 10 px hit area and the 8 px scroll bar beside it (**Side pane** above); 2.5.5's 44 px is not claimed.
+- **WCAG 2.2 AAA beyond contrast**: met are 1.4.9 (no images of text), 2.1.3 (every function by the keyboard, the List splitter's arrow keys
+  included), 2.2.3 (nothing on a timer; **The built-in notice**), 2.3.2 (no flashes), 2.3.3 (motion follows `prefers-reduced-motion`), 2.4.8 (the page
+  and the report headings tell where the viewer is), 2.4.9 (links name their purpose), 2.4.10 (sections carry headings), 2.4.12 and 2.4.13 (the focus
+  is never obscured, and its outline is 2 px at 3:1), 3.1.3, 3.1.4 (abbreviated source badges, **External Source Badge Configuration**), 3.2.5 and
+  3.3.6. Not met, by decision: 2.2.4 (Interruptions): live updates (SSE) apply as they arrive, with no pause, and
+  the scroll anchoring keeps the rows on screen in place. Not met at AA: 2.5.8 for the List's resize handle and the scroll bar beside it, and 2.5.7 for
+  the List's splitter (**Side pane** above): a path without dragging belongs to `@aiquants/resize-panels`, and larger hit areas for the handle and the
+  bar wait for the same layout pass as 2.5.5. Not claimed yet: 2.5.5 (44 px targets), 1.4.8 (a line measure and the List preview's
+  leading) and 3.3.5 (a help control for the search syntax), which need a layout pass, and 3.1.6 (readings of names), which needs readings from the
+  host's directory. 2.2.5 is met by the package for a refused comment post (**One comment section rule** above); keeping work across a
+  re-authentication elsewhere is the host's, as is 2.2.6 (telling users how long a session lasts). The floating tap-scroll circle hides while the view root carries `data-daily-report-keyboard-focus` (through the class both views pass in
   `VirtualScroll`'s tap-scroll circle options).
 - **Action buttons and icons**: the List card's star and read toggles, the star, read, edit and delete buttons of the DetailList header and the side
   pane, and the trash button of the viewer's comments share one 24 px round target that never shrinks, with a 16 px SVG icon centred in it (4 px on
@@ -3987,7 +4078,7 @@ DOM hooks are `data-*` attributes, test ids and ARIA; class names are styling an
 | `[data-daily-report-row="<id>"]` | Row frame of both views (`role="row"` with `id`, `aria-rowindex`, `aria-posinset`, `aria-setsize`, `aria-level` and an explicit `aria-selected`; the set size is the declared total while the ids stream delivers and `-1` before it is declared, see **Screen readers**), in every load state |
 | `[data-daily-report-active]` | The active row's frame (the row the composite's `aria-activedescendant` names) |
 | `[data-daily-report-row-surface]` | Surface of a row frame (`role="gridcell"`): its direct child that paints the selection ring and the focus outline, in every load state (opaque and never animated; a loading pulse runs inside it) |
-| `[data-daily-report-row-shell]` | The empty surface of a shell: a row mounted outside the visible range whose body is still to come (**Rows mount in two passes**) |
+| `[data-daily-report-row-shell]` | The surface of a shell, the card's surface without content: a row mounted outside the visible range whose body is still to come (**Rows mount in two passes**) |
 | `[data-daily-report-card]` | List card surface (present while the card is shown) |
 | `button[data-daily-report-button="<id>"]` | List card primary button (the click target that selects, and the pointer hand-back target; never a Tab stop, `tabIndex=-1`) |
 | `[data-daily-report-row-focus]` | A row's own focus target, where a pointer or touch hand-back lands: the List card's primary button, or the DetailList card's visually hidden name heading (`tabIndex=-1`; never a Tab stop) |
@@ -4014,21 +4105,30 @@ Only the package writes `data-daily-report-keyboard-focus`, `data-daily-report-s
 their own content inside a view — but never set them. When the pane content matters, wait for `data-displayed-report-id`, not `data-report-id`: during
 a key's render the frame already names the new selection while the content still shows the previous report.
 
+A host's test build instruments the views by providing `createDailyReportTestInstrumentation()` (testing entry) through
+`DailyReportInstrumentationContext` (client entry) around the page; production provides none, so no view carries a test handle or reports a row-pass
+event there, and none of the testing entry's code is in the client bundle. A view reads the context once, when it mounts. Instrumented,
 `[data-testid="daily-report-list"]` and `[data-testid="daily-report-detail-list"]` carry a `__virtualScroll` accessor for end-to-end tests, with the
 same shape in both views. It is the read-only part of the current `VirtualScroll` handle — `getViewportSize()`, `getScrollPosition()`,
 `getScrollAnchor()`, `getRange()` and `getFenwickSize()` — plus `findReportIndex(id)`, `getReportItem(index)` and `getReportIds(limit = 20)` over the
-view's committed list, one way to move the position, `revealIndex(index, options)`, and one read-only view of the view's row pass,
-`rowPass.counters()`: the counts since the view mounted, read when it is called — `syncReleases` (units drawn synchronously, in a commit or a
-notification's microtask commit), `oversizeFrames` (key-free frames whose first unit alone exceeded the frame's share), `lateFrames` (late key-free
-frames the pass skipped) and `lateForcedFrames` (late key-free frames it applied a unit in regardless). A performance probe reads them before and
-after a key hold and reports the differences, so it copies none of the pass's constants or rules (**Rows mount in two passes**).
-The client entry exports the contract as types, so a host's tests import it instead of restating it (type-only, no bundle bytes):
-`DailyReportViewTestHandle` is the accessor, `DailyReportViewTestReadHandle` its read-only part, and `DailyReportRevealOptions` the options of
-`revealIndex`, which are the second argument of `VirtualScroll`'s `scrollToIndex` (its alignment and offset, as the peer defines them).
+view's committed list, one way to move the position, `revealIndex(index, options)`, and one read-only view of the view's row pass:
+`rowPass.counters()`, the counts of its events since the view mounted, read when it is called — `syncReleases` (units drawn synchronously, in a
+commit or a notification's microtask commit), `deferredVisible` (units of a frame-exceeding kind kept pending when their row became visible during a
+hold), `oversizeFrames` (key-free frames whose first unit alone exceeded the frame's share), `lateFrames` (late key-free frames the pass skipped),
+`lateForcedFrames` (late key-free frames it applied a unit in regardless) and `unitFrames` (frames that applied units) — and
+`rowPass.unitKinds()`, the latest `p50`, `p90` and `budget` (the class limit: the frame interval, floored at the 60 Hz interval on a faster display,
+less the late-frame margin) of each unit kind its unit frames
+reported — and one read-only view of the view's re-estimates: `estimate.counters()` — `reEstimates` (position changes `VirtualScroll` made for a
+new row-height estimate, the cause `re-estimate`) and `reEstimatesInMotion` (those made while the view moved: during a key hold or while it
+scrolled; 0 by design, since the view applies an estimate at rest only). A performance probe reads them before and after a key hold and reports the
+differences, so it copies none of the pass's constants or rules (**Rows mount in two passes**).
+The testing entry exports the contract as types, so a host's tests import it instead of restating it (type-only):
+`DailyReportViewTestHandle` is the accessor, `DailyReportViewTestReadHandle` its read-only part, and `DailyReportRevealOptions` (client entry) the
+options of `revealIndex`, which are the second argument of `VirtualScroll`'s `scrollToIndex` (its alignment and offset, as the peer defines them).
 `revealIndex` goes through the view's scroller (the `VirtualScroll` alignment of `scrollToIndex`, then the anchor's record, like a key move; see
 **Host selections and list changes**), so a list change right after it keeps the revealed report in place. The accessor has none of the handle's
-functions that move the position (`scrollToIndex`, `scrollBy`, `scrollTo`, `applyWheel`, `updateItemSize`) and no selection backdoor: select through
-the UI (a click, the keys). Read it on every use; it is `undefined` while the list is not mounted.
+functions that move the position (`scrollToIndex`, `scrollBy`, `scrollTo`, `applyWheel`, `updateItemSize`, `setItemHeightEstimate`) and no
+selection backdoor: select through the UI (a click, the keys). Read it on every use; it is `undefined` while the list is not mounted.
 
 ### Localization (`locale` / `labels`)
 
@@ -4232,23 +4332,29 @@ prevents the package from hardcoding specific third-party service names or desig
 sourceTypeConfigs: {
     Internal: {
         label: "Native",
-        badgeClassName: "bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400",
+        badgeClassName: "bg-emerald-100 text-emerald-900 dark:bg-emerald-900/30 dark:text-emerald-400",
     },
     ExternalCRM: {
         label: "External CRM",
-        badgeClassName: "bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400",
+        badgeClassName: "bg-red-100 text-red-900 dark:bg-red-900/30 dark:text-red-300",
     },
     LegacyPortal: {
         label: "LP",
         name: "Legacy Portal",
-        badgeClassName: "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
+        badgeClassName: "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-300",
     },
 }
 ```
 
-- `label` is the text on the badge. When it is an abbreviation, give the full name in `name` (WCAG 3.1.4): the badge then renders the label as
-  `<abbr title="<name>">` (pointer users see the expansion), hides the abbreviation from assistive technology and reads the name once instead. Without
-  `name` the badge shows its label and nothing is substituted.
+- The badge's colours are the host's: the package's 7:1 guard reads only the package's own classes, so a `badgeClassName` must keep its text at 7:1
+  (WCAG 1.4.6) itself, against its fill composited over the card and over the overlay in both schemes (light: white under both; dark: `slate-900/70`
+  over `slate-950` under the card, `slate-900` under the overlay). The pairs above do, by the package's contrast math at the lower of the two
+  surfaces: 8.47:1 light and 7.93:1 dark for emerald (the built-in `Internal` badge's own pair), 8.22:1 and 8.54:1 for red, 7.23:1 and 8.63:1 for
+  blue. A `-800` text on a green or red `-100` fill falls short in light (6.45:1 and 6.86:1), and a red or blue `-400` text on a `-900/30` fill falls
+  short in dark (5.68:1 and 5.94:1 over the overlay).
+- `label` is the text on the badge. When it is an abbreviation, give the full name in `name` (WCAG 3.1.4): a badge whose label differs from its `name`
+  renders the label as `<abbr title="<name>">` (pointer users see the expansion), hides the abbreviation from assistive technology and reads the name
+  once instead. Without `name`, or with a `name` equal to the label (which abbreviates nothing), the badge shows its label and nothing is substituted.
   A `name` that is given must be a non-blank string; anything else (`""`, `"  "`, `null`, a number) throws a `RangeError` at render that names the
   source type.
 - The badge is part of the row description (see [Keyboard, focus and selection](#keyboard-focus-and-selection-list--detaillist)): the List card's
@@ -4365,7 +4471,9 @@ Documenting a name here is no reason to export it, and the values that tune the
     `DAILY_REPORT_SEARCH_BATCHES_IN_FLIGHT` (2, the batched reads the package's client keeps in flight per API base path, from which the server sizes
     a viewer's share of the `reports` and `search-marks` admissions), and the answer of `search-marks`: `DailyReportSearchMarksAnswer`
     (`{ wordsDigest, reports, deferred }`) of `DailyReportSearchReportMarks` (a report's id, `matchedSets` and `fields`) and
-    `DailyReportSearchFieldMarks` (a field's `fingerprint`, with its `ranges` or `dense: true`).
+    `DailyReportSearchFieldMarks` (a field's `fingerprint`, with its `ranges` or `dense: true`), and the answer of `reports`:
+    `DailyReportSearchDetailsAnswer` (`{ outcomes }`, one `DailyReportSearchDetailOutcome` per requested id in request order: `ok` with its `report`,
+    `not_found` or `failed`).
 - **client** (`@aiquants/daily-report/client`, React):
   - Components: `DailyReportPage` / `DailyReportResolvedContent` / `DailyReportList` / `DailyReportDetailList` / `DailyReportAttachmentIndicator`, the
     providers `DailyReportConfigProvider` / `DailyReportActionProvider` / `DailyReportErrorProvider` (required above the action provider:
@@ -4406,20 +4514,30 @@ Documenting a name here is no reason to export it, and the values that tune the
     slot P**), so rows are located by `[data-daily-report-row]` or the test handle.
   - The rows' shape: `DailyReportRows` (`Pick<ReadonlyArray<DailyReportItem>, "length" | "at"> & Iterable<DailyReportItem>`: what
     `DailyReportActionState.items` is and both views' `dailyReportItems` take; a plain array is one too).
+  - The selection's phase: `DailyReportSelectionPhase` (`"held"` for each key of a held-key repeat stream, `"settled"` for every other selection and
+    once at a stream's end: the second argument of both views' `onSelectItem`). Every way a stream ends (the key's release, another key, a pointer
+    press, a wheel, focus leaving the view, the view unmounting) passes the stream's last selection once as `"settled"`, unless the host settled
+    another selection during the stream or no key of the stream selected. A host may record `"held"` selections without rendering them; rendering
+    them is also correct, at the cost of a render per key.
   - Types: `DailyReportClientConfigInput` / `DailyReportClientConfigDefaults` / `DailyReportClientConfig` (the resolved configuration
     `useDailyReportConfig` returns) / `DailyReportHeaderProps` (what `renderHeader` receives) / `DailyReportSearchSettingInput` /
     `DailyReportSearchSetting` (`config.search` as passed and as resolved) / `DailyReportSourceTypeConfig` (one entry of `sourceTypeConfigs`) /
     `DailyReportLocale` / `DailyReportLabels` / `DailyReportLabelOverrides` / `DailyReportOperation` / `DailyReportErrorInfo` /
     `DailyReportSseConnectionStatus`,
-    and the end-to-end test handle's contract `DailyReportViewTestHandle` / `DailyReportViewTestReadHandle` / `DailyReportRevealOptions` /
-    `DailyReportListNavigationHandle` (the read-only getters of the views' `VirtualScroll` handle that `DailyReportViewTestReadHandle` builds on) (see
-    [Test hooks](#test-hooks)).
+    the options of the test handle's reveal `DailyReportRevealOptions` and `DailyReportListNavigationHandle` (the read-only getters of the views'
+    `VirtualScroll` handle that the testing entry's `DailyReportViewTestReadHandle` builds on) (see [Test hooks](#test-hooks)).
+  - Test instrumentation: `DailyReportInstrumentationContext` (null by default; a host's test build provides the testing entry's instrumentation
+    through it, and production provides none) with its value's contract `DailyReportInstrumentation` / `DailyReportInstrumentedView` /
+    `DailyReportViewInstrumentation` (see [Test hooks](#test-hooks)).
 - **server** (`@aiquants/daily-report/server`, Node.js):
   - Factories: `createDailyReportServer` (whose `knownSourceTypes` lists the package's own source type, `Internal`, then each `externalSources`
     adapter's, frozen) / `createDailyReportService` (`getDailyReportIdsByExternalId` returns `{ items, streamAnchor, snapshot }`;
     `readSseStreamAnchor`; `attachmentDelivery`, `null` without the `attachments` block; `titleMaxLength`;
     and for the search `searchLimits`, `null` without the `search` block, `searchFilterSourceTypes` (the source types a filter may name: frozen, the
-    very array of `knownSourceTypes`), `searchDailyReports` (it takes `DailyReportSearchCriteria`), `getDailyReportDetailsByIdsByExternalId`,
+    very array of `knownSourceTypes`), `searchDailyReports` (it takes `DailyReportSearchCriteria`), `getDailyReportDetailsByIdsByExternalId` (it
+    answers one `DailyReportSearchDetailOutcome` per requested id, in request order, and takes the request's `{ signal }` like
+    `markDailyReportSearchHits`: validated before any query, its reason thrown at the next check after an abort, before a query or after a yield
+    between two reports' copies),
     `markDailyReportSearchHits` (it takes the request's `{ signal }`, validated before any query, and throws its reason at its next check after an
     abort, before a read or after a yield between two slices of the marks; its answer holds the reports within the marks budget and defers the rest),
     `listDailyReportSearchFacets`, `reconcileSearchIndex`) / `createDailyReportHandlers` / `defineDailyReportSchema` / `defineDailyReportSearchSchema`
@@ -4482,6 +4600,13 @@ Documenting a name here is no reason to export it, and the values that tune the
     `DailyReportSearchCriteria` (what `searchDailyReports` takes: `{ plan, filters }`, the plan `null` for a filters-only search) /
     `DailyReportSearchFilters` (the parsed filters, each `null` when unset: the source types as a lower-case set, the authors and customers as
     `DailyReportSearchNameFilter`, a non-empty tuple) / `DailyReportSearchFacets` (the answer of `search-facets`).
+- **testing** (`@aiquants/daily-report/testing`, a host's tests):
+  - `createDailyReportTestInstrumentation()`, the value a host's test build provides through `DailyReportInstrumentationContext` (see
+    [Test hooks](#test-hooks)).
+  - Types: `DailyReportViewTestHandle` (the views' test handle) / `DailyReportViewTestReadHandle` (its read-only part) /
+    `DailyReportRowPassCounters` / `DailyReportRowPassKindReading` (what its `rowPass` reads) and the row pass's events it counts,
+    `DailyReportRowPassEvent` / `DailyReportRowPassUnitFrameEvent` / `DailyReportRowPassUnitKind` / `DailyReportRowBoxSizing` /
+    `DailyReportRowUnitChange`, and `DailyReportReEstimateCounters` (what its `estimate` reads: the re-estimates and those made in motion).
 
 ## License