@aiquants/daily-report 0.22.1 → 0.23.0

package/README.md

@@ -8,7 +8,7 @@ Follows the `@aiquants/authz-*` DI layering — every app-specific concern (auth
 | :--- | :--- | :--- |
 | `@aiquants/daily-report` | Types, zod SSE schemas, business-date / text / comment utilities | 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 | node |
+| `@aiquants/daily-report/server` | `createDailyReportServer` (service + loaders/actions), `defineDailyReportSchema`, SSE fan-out reader, SQL result cache, the sharp thumbnail renderer | node |
 
 ## Install
 
@@ -22,21 +22,51 @@ Monorepo (already a pnpm workspace package):
 External projects:
 
 ```bash
-pnpm add @aiquants/daily-report react react-dom react-router drizzle-orm zod
+pnpm add @aiquants/daily-report @aiquants/virtualscroll @aiquants/swipe-overlay @aiquants/resize-panels react react-dom react-router drizzle-orm zod
 ```
 
-`react` / `react-dom` / `react-router` / `drizzle-orm` / `zod` are **peer dependencies**. `@aiquants/sse` (the SSE wire contract, server response helpers and the reopening client) is a regular **dependency**: it arrives transitively, so consumers do not declare it. Build / test: `pnpm run build` (tsup → dist) / `pnpm run test` (vitest).
+`@aiquants/virtualscroll` / `@aiquants/swipe-overlay` / `@aiquants/resize-panels` / `react` / `react-dom` / `react-router` / `drizzle-orm` / `zod` are **peer dependencies**. React must be **19 or later** (`react` / `react-dom` `>=19`): the rows register their keyboard focus targets with ref callbacks that return a cleanup.
+`@aiquants/virtualscroll` must be **3.8.0 or later**: both views pass its scroll-bar option `enableArrowButtonTabStops: false`, which takes the scroll bar's arrow buttons out of the Tab order (the views scroll by keyboard themselves; see [Keyboard, focus and selection](#keyboard-focus-and-selection-list--detaillist)). The label catalog reuses its 7 engine keys (see [Localization](#localization-locale--labels)).
+That floor is declared once, in `peer-floors.json` (`{ "@aiquants/virtualscroll": "3.8.0" }`), and every publish path runs `scripts/check-peer-floors.mjs` (`pnpm run check:peer-floors`) right after the leak check: each `publish:*` script before its version bump (so a refusal leaves no bumped version behind), and `prepublishOnly` before every `pnpm publish`, a bare one included (for example a re-run after a `publish:*` whose registry step failed).
+`workspace:^` publishes `^<version>` of the linked workspace package (`node_modules/@aiquants/virtualscroll/package.json`), so while that version is below the floor the check exits 1 and the publish stops (exit 2 for a configuration error, such as a floor that names no `workspace:` peer).
+`@aiquants/sse` (the SSE wire contract, server response helpers and the reopening client) is a regular **dependency**: it arrives transitively, so consumers do not declare it.
+The server entry needs **Node.js 20.3 or later** (`engines.node` `>=20.3.0`): the thumbnail stage deadlines combine the generation's signal with a timer through `AbortSignal.any`. `src/server/node-engine-floor.spec.ts` reads the server-side modules' syntax tree and fails when one of them uses a listed runtime API newer than the declared floor.
+Build / test: `pnpm run build` (tsup → dist) / `pnpm run test` (vitest) / `pnpm run typecheck:examples` (the host examples under `examples/`, which are not shipped) / `pnpm run check:bundle` (the gzip size at level 9 of every shipped ESM entry and the standalone stylesheet — `dist/client.mjs`, `dist/index.mjs`, `dist/server.mjs`, `dist/styles/daily-report.standalone.css` — against `bundleBudget` in `package.json`; an `.mjs` or `.css` target of `exports` without a budget fails the check).
+`pnpm run verify` runs the type checks, Biome (`src/` and `scripts/`), markdownlint, the two count ratchets (docstrings, then the no-fallback guard), the unit tests with per-file coverage floors, the coverage ratchet, the examples, the build and, last, the bundle check.
+Every source file under `src` (without specs, tests, declarations and test helpers) and every gate script under `scripts` (`scripts/**/*.mjs`) has a committed floor of branch and function coverage in `coverage-floors.json`: Vitest fails a file below its floor, `pnpm run check:coverage` (`scripts/ratchet-coverage.mjs`) fails a file without an entry or an entry without a file, and `pnpm run coverage:ratchet` raises each floor to the measured percentage rounded down after a whole-suite coverage run (a file at 100 % stays at 100; no floor is ever lowered by the script).
+Each gate script is a two-statement command-line entry around the `main({ packageRoot, argv })` of its module under `scripts/lib/` (the shared exit codes, JSON readers and error descriptions are `scripts/lib/cli.mjs`); the specs run `main` in the test process against temporary packages and keep one subprocess test of each entry, so the scripts' logic is measured by the same floors as `src` (all at 100).
+A new file enters the ratchet only at 100 % of both metrics: the script records no entry below that, so a file that cannot reach 100 % needs a committed entry with a non-empty `exemption` (the reason, reviewed with the floors), which the script keeps while it raises the floors.
+Two source guards keep per-file counts that only go down, through one engine (`scripts/lib/count-ratchet.mjs`): each file must match its entry exactly and a file without an entry counts 0, so a count below the entry fails too until the baseline is lowered (a fixed violation cannot come back unnoticed); an entry for a file the scan does not cover is stale; the exit code is 0 (pass), 1 (findings, each with its fix) or 2 (a configuration error, nothing proven); and `--write` lowers the entries to the measured counts and drops those at 0 and the stale ones, never raising or adding one.
+The guards are the violations of the workspace's docstring and comment language rules, in `docstring-baseline.json` (`scripts/ratchet-docstrings.mjs`: `pnpm run check:docstrings` verifies, `pnpm run docstrings:ratchet` lowers), and the implicit value substitutions (`??` / `||` fallbacks) of the production sources, in `no-fallback-baseline.json` at the package root (`scripts/check-no-fallback.mjs`: `pnpm run check:no-fallback` verifies, `pnpm run no-fallback:ratchet` lowers).
+A substitution that the specification or a port contract defines is a reviewed exception of the no-fallback guard instead (`EXCEPTIONS` in `scripts/lib/check-no-fallback.mjs`: the file, the exact expression, the number of `occurrences` it covers and the reason), and its matches are not counted; an exception that matches another number of expressions than it declares fails (exit 1: fewer means the expression was fixed or rewritten, more a new copy that needs its own review), and a malformed list is exit 2.
+Every TypeScript or JavaScript code block of this README names its source in its info string: an example file, or a `#region` of one, which `src/docs-examples.spec.ts` compares byte for byte (`ts examples/<file>.ts[#<region>]`), or `illustrative` for a fragment that is not type-checked.
+
+**Browser floor**: Chrome 121, Firefox 122, Safari 17.4 (Baseline 2024). The client uses each platform feature below as it is, with no feature detection and no second code path, so on an engine under the floor the listed behaviour fails and nothing else replaces it. Two CSS features of the table are newer than parts of the floor, and the row says what those engines draw:
+
+| Feature | Supported from | Used for | Below the floor |
+| --- | --- | --- | --- |
+| `Element.checkVisibility({ visibilityProperty: true })` | Chrome 121, Firefox 122, Safari 17.4 (the method alone: Chrome 105, Firefox 106) | Finding Tab stops for the `Ctrl+Home` / `Ctrl+End` exits and the mobile overlay's Tab wrap | Without the method (Safari before 17.4) those key handlers throw a `TypeError`: the exit keys keep their browser meaning, and at the overlay's ends Tab moves to the browser's own interface instead of wrapping (the page behind the dialog stays inert). With the method but not the option (Chrome 105–120, Firefox 106–121) an element hidden by `visibility: hidden` counts as a stop, so an exit key whose nearest stop is such an element is consumed while focus stays where it was |
+| `:has()` | Chrome 105, Firefox 121, Safari 15.4 | The List card's selection ring and keyboard focus outline, and the forced-colours selection outline of a List row with a card (all read from the card's primary button) | List cards show neither the selection nor keyboard focus (the DetailList is unaffected) |
+| Container size queries and container query units (`cqi`) | Chrome 105, Firefox 110, Safari 16 | The attachment grid's column count; the tile frame's height (`100cqi` of the frame's own inline-size container); the view-mode toolbar's end inset in the single-column List | One attachment column at every width; frames sized by `aspect-ratio` alone (below); the toolbar's end edge overhangs the List's scroll bar by 8 px |
+| CSS `round()` | Chrome 125, Firefox 118, Safari 15.4 | The tile frame's whole-pixel height `round(nearest, 100cqi * 320 / 480, 1px)` (see [Attachment display](#attachment-display)) | Chrome 121–124, inside the floor, drop that height declaration: the frame's `aspect-ratio: 480 / 320`, always declared beside it, sizes the frame at the exact fractional 2t / 3, so the frames of one grid can paint one device pixel apart |
+| `scrollbar-gutter: stable` | Chrome 94, Firefox 97, Safari 18.2 | The side pane's tab panels keep their scroll bar's width whatever their content's height | Safari 17.4–18.1, inside the floor, ignore it; their default scroll bars overlay the content and take no width |
+| `<dialog>` with `showModal()` | Chrome 37, Firefox 98, Safari 15.4 | The mobile detail overlay (a modal dialog in the top layer) | Opening the overlay throws a `TypeError` from a layout effect, which React hands to the nearest error boundary |
+
+File names are cut at code-point boundaries rather than grapheme boundaries, because `Intl.Segmenter` (Firefox 125) is above the floor (see [Attachment display](#attachment-display)).
 
 ### Tailwind CSS
 
 This package has **no hand-written component CSS**, so it ships **no components-only artifact** — only a standalone build for non-Tailwind hosts. Components carry Tailwind utility classes in JSX. Pick one consumption mode:
 
-**Tailwind v4 host (required if your app builds Tailwind itself)** — add the package source to your app's scan targets so all utilities are generated in one canonical build, define the `dark:` variant, and map the shadcn tokens the components reference (`bg-background`, `text-muted-foreground`, ... do not exist in Tailwind's default theme, so those utilities are not generated unless the tokens are mapped):
+**Tailwind v4 host (required if your app builds Tailwind itself)** — add the package to your app's scan targets (the published package ships its classes in `dist`; inside the monorepo, scan `src` without the specs and test helpers, as the package's own standalone build does) so all utilities are generated in one canonical build, define the `dark:` variant, and map the shadcn tokens the components reference (`bg-background`, `text-muted-foreground`, ... do not exist in Tailwind's default theme, so those utilities are not generated unless the tokens are mapped):
 
 ```css
 /* app tailwind.css (Tailwind v4) */
-@source "../node_modules/@aiquants/daily-report/src/**/*.{ts,tsx}";
-/* monorepo: @source "../../../../packages/daily-report/src/**/*.{ts,tsx}"; */
+@source "../node_modules/@aiquants/daily-report/dist/**/*.mjs";
+/* monorepo: scan the sources, without the specs and test helpers (their literals style no element):
+@source "../../../../packages/daily-report/src/**/*.{ts,tsx}";
+@source not "../../../../packages/daily-report/src/**/*.spec.{ts,tsx}";
+@source not "../../../../packages/daily-report/src/**/test-helpers/**"; */
 @plugin "tailwindcss-animate";
 @custom-variant dark (&:where(.dark, .dark *));
 @theme inline {
@@ -48,8 +78,9 @@ This package has **no hand-written component CSS**, so it ships **no components-
 
 The host must also:
 
-- Load the `tailwindcss-animate` plugin. The components use `animate-in` / `fade-in` / `zoom-in-95` entrance animations; without `@plugin "tailwindcss-animate"` those classes are not generated and the animations silently no-op.
+- Load the `tailwindcss-animate` plugin. The components use `animate-in` / `fade-in` / `zoom-in-95` / `slide-in-from-bottom-2` entrance animations (all under `motion-safe:`); without `@plugin "tailwindcss-animate"` those classes are not generated and the animations silently no-op.
 - Define the shadcn CSS variables themselves (`--background`, `--muted`, `--radius`, ...).
+- Map the radius scale as the standalone build does: `--radius-lg: var(--radius)` and `--radius-xl: calc(var(--radius) + 4px)` (with `-md` and `-sm` below). The tab bars are `rounded-xl` with a 4 px inset around `rounded-lg` tabs, so they stay concentric only when xl − lg = 4 px for your `--radius`.
 - Import the `@aiquants/virtualscroll` peer CSS once. Do NOT `@import` the standalone build alongside your own Tailwind build: it duplicates utilities your build also emits, and concatenated builds cannot reproduce the single-build canonical order (base utilities before variants), so base/variant winners flip regardless of `@layer` wrapping (e.g. a later duplicate `.flex` beats an earlier `.sm:hidden`).
 
 **Non-Tailwind host** — import the single self-contained standalone build (`pnpm run build:css` → `dist/styles/daily-report.standalone.css`):
@@ -63,11 +94,12 @@ The standalone build bundles every JSX utility (and maps the shadcn tokens), but
 ## Required database schema
 
 Seven tables: `DailyReportHub` (core/cross-source), `DailyReportInternal` (in-app content), `DailyReportComment`, `DailyReportLabel`, `DailyReportHub_Label`, `DailyReportUserStatus` (read status & stars), and the optional `DailyReportAttachment` (attachment metadata — omit it and the attachment feature degrades gracefully: `attachments` stays an empty array and the attachment endpoint returns 404 for every token).
-Attachment delivery additionally requires the `attachmentIdCodec` and `readAttachment` DI ports on `createDailyReportServer` (see `DailyReportServerConfig`); the factory then exposes `dailyReportServer.attachment.loader`, which the host app must mount on its own byte-serving route (e.g. `daily_report.api.attachment.$token` — a route separate from the `:endpoint` JSON router, whose fixed `Content-Type: application/json` + CSP headers are incompatible with byte delivery).
+Attachment delivery additionally requires the `attachmentIdCodec` and `readAttachment` DI ports — service configuration keys (`DailyReportServiceConfig`), which `createDailyReportServer` accepts because `DailyReportServerConfig` extends the service configuration; see [Attachments](#attachments).
+The factory then exposes `dailyReportServer.attachment.loader`, which the host app must mount on its own byte-serving route (e.g. `daily_report.api.attachment.$token` — a route separate from the `:endpoint` JSON router, whose fixed `Content-Type: application/json` + CSP headers are incompatible with byte delivery). The route must name its parameter `token`: a route without it is a configuration error that every request answers with 500 and an `error` log line (see **Thumbnail endpoint** below). The same route and loader also serve thumbnails (`?thumbnail=tile`); no extra route is needed.
 
 Existing apps can inject their own drizzle models (structural typing — see `DailyReportTables`). Greenfield projects can generate definitions:
 
-```ts
+```ts illustrative
 import { defineDailyReportSchema } from "@aiquants/daily-report/server"
 const tables = defineDailyReportSchema("dbo_app", { userTable: Users })
 ```
@@ -76,7 +108,7 @@ const tables = defineDailyReportSchema("dbo_app", { userTable: Users })
 
 ## Server wiring (DI)
 
-```ts
+```ts illustrative
 // app/services/daily-report/config.server.ts
 import { createDailyReportServer, type DailyReportDb, type DailyReportRedisProvider } from "@aiquants/daily-report/server"
 
@@ -98,7 +130,7 @@ export const dailyReportServer = createDailyReportServer({
 
 Route mounts (React Router v7, flexible file convention):
 
-```ts
+```ts illustrative
 // daily_report._index/loader.server.ts
 export const loader = async (args) => {
     const r = await dailyReportServer.index.loader(args)
@@ -121,13 +153,19 @@ export const loader = (args) => dailyReportServer.sse.loader(args)
 - `draftLabelName` / `draftLabelNames` — Database label names representing draft states (single string or array of candidates like `["Draft", "Work in Progress"]`). Used for server-side cross-user visibility filtering (hiding drafts from other users) and `isDraft` evaluation.
 - `resolveVisibleSourceTypes(request)` — **Optional row-level authorization port.** Returns the `Hub.source_type` values this request may view. Applies uniformly to every server data path: list (ids stream), business-date list, detail, comments, attachment bytes, and SSE. See [Source-type visibility](#source-type-visibility) below.
 - `enableDevCacheClear` — Gates the dev-only `POST /action` `intent=clearCache` (flush every worker's cache). Default `false` → the handler returns `400` before touching the service. Wire `import.meta.env.DEV` to enable it only in development (any authenticated user could otherwise flush all caches without limit).
-- Primary tuning parameters: `idsTtlMs` (180s) / `businessDateTtlMs` (300s) / `streamKey` / `streamMaxLen` / `loginRedirectPath`.
+- `attachmentIdCodec` / `readAttachment` / `attachmentThumbnailRenderer` / `attachmentMaxBytes` — Attachment delivery ports and size limit, owned by the service. See [Attachments](#attachments).
+- Primary tuning parameters: `idsTtlMs` (180s) / `businessDateTtlMs` (300s) / `streamKey` / `streamMaxLen` / `loginRedirectPath`, plus the attachment tuning keys listed under [Attachments](#attachments).
+
+**Configuration errors** follow one convention on the server and on the client: the message reads `[daily-report] <path> must be <expectation>`, `<path>` being the public key or argument to fix, and ends with `; got <value>` only when it shows a value.
+A rejected value — a wrong type included, also a port or a function given with the wrong type — is a `RangeError` whose message ends with `; got <value>` (a string as JSON; a number, a boolean, `null` or `undefined` as written; an array as `array`; anything else only its `typeof`). An unknown key is a `RangeError` that lists the known keys as JSON strings: `<path> must be one of "<key>", "<key>", …; got "<unknown key>"`. A missing (`undefined`) function or port is a `TypeError`, without `; got`.
+For example `[daily-report] attachmentConcurrency must be an integer >= 1; got "2"`, `[daily-report] config key must be one of "apiBasePath", "ssePath", …; got "title"` and `[daily-report] readAttachment must be injected when attachmentIdCodec is given`.
+The three helpers of `src/shared/config-errors.ts` (`configValueError`, `configKeyError`, `configPortError`) are the only code that constructs a `RangeError` or a `TypeError`, so every such message has the prefix and the form: `src/host-facing-errors.spec.ts` reads the sources' syntax tree (specs and test helpers aside) and fails on a construction anywhere else.
 
 ### Source-type visibility
 
 Restrict which report categories a viewer may see, without the package depending on any authorization library. The port receives the request and returns plain strings; your app decides the policy.
 
-```ts
+```ts illustrative
 createDailyReportServer({
   // …existing config
   resolveVisibleSourceTypes: async (request, { reason }) => {
@@ -163,7 +201,7 @@ createDailyReportServer({
 
 Return `{ read, comment }` from the same port to restrict **reading and writing comments** independently of the report bodies — this is what connects a per-category comment permission (e.g. `daily_report_legacy_comment`) to actual access control.
 
-```ts
+```ts illustrative
 resolveVisibleSourceTypes: async (request, { reason }) => {
   const grants = await yourAuthz.grantsFor(request, { skipCache: reason === "refresh" })
   return {
@@ -186,6 +224,370 @@ resolveVisibleSourceTypes: async (request, { reason }) => {
 - **Writing to external sources remains impossible regardless** — `addComment` rejects any non-`Internal` source type outright, so for external categories the comment dimension effectively controls *reading*.
 - **Cache**: the dimension is folded into the cache-key digest, so revoking only the comment grant invalidates immediately. When `comment` follows `read` (the default) the digest is byte-identical to before, so existing deployments see no cache churn.
 
+### Attachments
+
+Attachment bytes are served by `dailyReportServer.attachment.loader` at `GET {apiBasePath}/attachment/{token}`. The query string names exactly one delivery:
+
+| Delivery | URL | Response |
+| --- | --- | --- |
+| inline | `{apiBasePath}/attachment/{token}` | The original (shown by the browser for inline-safe types) |
+| download | `...?download=1` | The original with `Content-Disposition: attachment` |
+| thumbnail | `...?thumbnail=<variant>` | A downscaled preview in the named variant, when a renderer port is injected |
+
+- **Build and parse the URL with the shared codec** (root entry `@aiquants/daily-report`). `buildDailyReportAttachmentUrl(apiBasePath, token, request)` takes `{ kind: "inline" }`, `{ kind: "download" }` or `{ kind: "thumbnail", variant }` (the `DailyReportAttachmentDeliveryRequest` union), and `parseDailyReportAttachmentQuery(searchParams)` reads a query back into the same request or into `{ kind: "invalid", reason: "thumbnail_variant" | "download_value" | "conflict" }` (`DailyReportAttachmentInvalidQuery`). The parameter names are private to the codec.
+- **Variants** form the closed, frozen list `DAILY_REPORT_ATTACHMENT_THUMBNAIL_VARIANTS` (root entry). It has one variant, `tile`: the box 480 × 320 a preview fits in, twice the largest tile frame of 240 × 160 CSS px. `isDailyReportAttachmentThumbnailVariant(value)` accepts the list's own keys only, exactly (`Tile`, `" tile"` and `toString` are not variants).
+- **Parsing is strict.** `thumbnail` must be one known variant name, `download` must be exactly `1`, the two cannot be combined, and neither may repeat. Anything else — `?thumbnail=1`, `?thumbnail=true`, `?download=true`, `?download=yes`, `?thumbnail=tile&download=1` — answers **400** `{"error":{"message":"Invalid attachment request"}}` right after authentication, before any port or database query runs, and writes no log line. Other parameters are ignored, and names are case-sensitive (`?Download=1` is an unknown parameter, so the request stays inline).
+- **The original's type**: the declared type is the row's `file_type` when it is a valid media type, otherwise the type the read port reported. An inline-safe declared type (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `application/pdf`, `text/plain`) is sent as itself, inline (as an attachment for a download); any other declared type, and a missing one, is sent as `application/octet-stream` with `Content-Disposition: attachment`, because the declared type comes from outside the package and an inline `text/html` or `image/svg+xml` would run script in the host's origin.
+- **Methods**: the original (inline and download) answers `GET` and `HEAD` (a HEAD reads metadata only and reports the same `Content-Length` as GET); any other method answers **405** with `Allow: GET, HEAD`. The thumbnail answers `GET` only (see **Thumbnail endpoint** below). Both 405s are checked right after the query, before the ports and the token.
+
+**Configuration**
+
+| Key | Owner | Default | Requires | Meaning |
+| --- | --- | --- | --- | --- |
+| `attachmentIdCodec` | service | not injected | `readAttachment` | Obfuscates attachment ids (use an instance separate from the user-id codec). Without the codec and the read port, the detail's `attachments` is always `[]` and the endpoint answers 404. |
+| `readAttachment` | service | not injected | `attachmentIdCodec` | Reads the original bytes (`DailyReportReadAttachment`). |
+| `attachmentThumbnailRenderer` | service | not injected | `readAttachment`, `attachmentIdCodec` | Renders the preview (`DailyReportAttachmentThumbnailRenderer`: `{ id, render }`; the package's sharp implementation is `createSharpThumbnailRenderer`). Validated when the service is created. Without it `hasThumbnail` is always `false` and every thumbnail request answers 404 (it never falls back to the original). |
+| `attachmentMaxBytes` | service | 32 MiB | `readAttachment` | Upper bound for an original, for every delivery. Keep it below the read port's wire limit. Integer ≥ 1. |
+| `attachmentRateLimitPerMinute` | handlers | 60 | `readAttachment` | Original downloads per user per minute; a token is spent before authorization. Integer ≥ 1. |
+| `attachmentConcurrency` | handlers | 4 | `readAttachment` | Simultaneous original reads; the slot is held until the body is sent, and the request fails fast with 503 when none is free. Integer ≥ 1. |
+| `attachmentThumbnailRateLimitPerMinute` | handlers | 120 | `attachmentThumbnailRenderer` | Thumbnail generations per user per minute, in a bucket separate from originals; revalidations (requests with `If-None-Match`) pay from a second bucket of ten times this value. Both admit before authorization, and an empty bucket answers 429 at once; a revalidation that does not end in a 304 also pays a generation token, right after authorization (see **Rate admission** below). Integer ≥ 1. |
+| `attachmentThumbnailConcurrency` | handlers | 2 | `attachmentThumbnailRenderer` | Simultaneous thumbnail generations (read + render), with a wait queue. Integer ≥ 1. |
+| `attachmentThumbnailCacheBytes` | handlers | 8 MiB | `attachmentThumbnailRenderer` | Total size of the thumbnail cache. `0` disables caching. Integer ≥ 0. |
+
+- **The service is the only owner of the delivery configuration.** The four service keys go to `createDailyReportService` / `createDailyReportServer`; the service resolves them once into the frozen `service.attachmentDelivery` (`DailyReportAttachmentDelivery`: `{ idCodec, readAttachment, thumbnailRenderer, maxBytes }`, uninjected ports `undefined`, `maxBytes` resolved to its default), and the handlers read only that object.
+  The `hasThumbnail` flag in the lists and the endpoint's behaviour therefore always come from the same values. `createDailyReportHandlers` does not accept these keys; a hand-written service stand-in passed to it must provide `attachmentDelivery`.
+- **Keys work only together with the keys in the Requires column, and a partial wiring fails at creation.** A key given without a key it requires throws a `TypeError` that names both, for example `[daily-report] readAttachment must be injected when attachmentIdCodec is given` or `[daily-report] attachmentThumbnailRenderer must be injected when attachmentThumbnailConcurrency is given`.
+  A key counts as given unless it is `undefined` (so `null` counts), and the first missing key is reported. So there are three valid wirings: no attachment port (no attachments; none of the other attachment keys either), the codec and the read port (originals only, with `attachmentMaxBytes` and the original tuning keys), or all three ports (originals and thumbnails, every key).
+  `createDailyReportService` checks the ports and `attachmentMaxBytes`; `createDailyReportHandlers` checks the tuning keys against the ports of `service.attachmentDelivery` (a hand-written service stand-in is checked too); `createDailyReportServer` runs both.
+- **The six numeric settings are validated once, at creation.** Only an omitted key (`undefined`) takes the default. Any other value that is not a safe integer at or above the minimum — `null`, `NaN`, `1.5`, `Infinity`, `-1` or the string `"2"` — throws a `RangeError` that names the public key, for example `[daily-report] attachmentThumbnailCacheBytes must be an integer >= 0; got -1` or `[daily-report] attachmentConcurrency must be an integer >= 1; got "2"`.
+  `createDailyReportService` checks `attachmentMaxBytes`; the handler factory checks the other five (`createDailyReportServer` runs both). The wiring check runs first, so a numeric key given without its port throws the `TypeError`.
+- **Handler tuning is per process.** Rate buckets, gates and the cache live in the handler factory's closure and are not shared across workers; the effective container-wide limit is the configured value times the number of workers. `createDailyReportServer` forwards the five tuning keys explicitly.
+- **Heap estimate per process**: `attachmentConcurrency × attachmentMaxBytes` for originals, plus `attachmentThumbnailConcurrency × (attachmentMaxBytes + the renderer's decode memory)` for thumbnails, plus `attachmentThumbnailCacheBytes`. The package's sharp renderer decodes only a source whose predicted working set is at most `DAILY_REPORT_SHARP_THUMBNAIL_DECODE_BUDGET_BYTES` (200,000,000 bytes, server entry), and the prediction is built to stay above the measured one: read that constant in your own estimate instead of restating it (see **The sharp renderer** below).
+
+**Read port**
+
+The port type spelled out (the example file checks that it is identical to the exported `DailyReportReadAttachment`):
+
+```ts examples/attachment-port-contracts.ts#read-attachment
+type DailyReportReadAttachment = (
+    filePath: string,
+    options: { maxBytes: number; head: boolean; principal?: string; signal: AbortSignal },
+) => Promise<
+    | { ok: true; bytes: Uint8Array<ArrayBuffer>; contentType?: string | null; size?: number }
+    | { ok: false; reason: "not_found" | "denied" | "too_large" | "invalid_path" | "unavailable"; code?: string }
+>
+```
+
+- Never throw; return a typed failure. `filePath` stays on the server. With `head: true` read metadata only and declare the real `size` (the HEAD `Content-Length` must match GET).
+- **`principal` is for attribution and audit only: the read result must not depend on it.** The SQL predicate (`getAttachmentForUser`) is the only authorization boundary; the port reads the `filePath` of a row that has already been authorized. Thumbnail generation relies on this: requests waiting for the same content share one read, made with the first requester's `principal`, and the outcome is cached for every authorized viewer of that attachment.
+  So a host whose storage enforces per-principal ACLs must not inject `attachmentThumbnailRenderer` (one requester's read and its cached outcome would reach authorized viewers outside that ACL), and `denied` is only for a refusal that is the same for every requester (a path outside the sandbox, a permission the service's own credentials lack).
+- **The `bytes` of `ok: true` are the complete object, at most `maxBytes` long.** A read that ends early must fail (`unavailable`), and an object over `maxBytes` must fail as `too_large` without being read. Because an object can change between its size check and its read, the server checks what a read returns:
+  - bytes over `maxBytes` are a port contract violation on either delivery: 500, logged at `error` as `reason=port_contract code=over_max_bytes`, and nothing is sent, rendered, cached or recorded;
+  - a thumbnail generation compares what it observed with the size the attachment row declares (`fileSize`, which the content identity names): the length it read, or for a `too_large` only that the object is over `maxBytes`. A row without a size has nothing to compare and is **verified**. When they differ — a truncated read, an object replaced under the same row, or a `too_large` for a row whose known size is within the limit (every eligible row's is) — the outcome is **unverified**:
+    that request is still answered (a thumbnail as 200 with `Cache-Control: no-store` and no `ETag`, a failure as the 404), nothing is cached, the response log line ends with `identity=unverified`, and `size_mismatch expected=<n> got=<m>` (`got=><maxBytes>` for a `too_large`) is logged at `warn`. A truncated read that the renderer rejects therefore never becomes a cached 404 for every viewer, and a browser never keeps a preview of the wrong bytes through 304s.
+- **`signal` aborts when the package no longer needs the result.** An original download passes the request's own `request.signal`. A thumbnail generation passes a signal that aborts when every request waiting for that content has gone (one of them leaving is not enough) or when the read stage's deadline passes (`readMs`, see the time budget below).
+- Forward it to your storage calls, combined with your own per-call deadline (for example `AbortSignal.any([options.signal, AbortSignal.timeout(ms)])`). An original download has no package deadline: its signal never aborts while the request is alive, so without your own deadline one hung call holds the handler indefinitely.
+- Once aborted, settle promptly with a typed failure (normally `unavailable`) instead of throwing. A failure that settles after the abort is the abort's doing, not a verdict about the object: report it as `unavailable`, never `not_found` (`not_found` is a verdict that the object is gone, which the package records as a missing object).
+- A read that has already been aborted when it settles is discarded whatever its kind, for an original download and a thumbnail generation alike: 503 (`reason=aborted`) and no missing- or present-object record, so an aborted `unavailable` is never logged as a storage outage (502) and a racing `not_found` never marks the object missing.
+  The original download logs `503 attachment=<id> viewer=<id> reason=aborted`; the thumbnail generation also caches nothing and does not render. No disconnected client receives either 503. An original request that is already aborted when it arrives gets the same 503 without reading.
+- A thumbnail read still running at its deadline is answered with 502 (`reason=read_timeout`) without waiting for it; nothing is cached and the object is not marked missing. The generation slot stays held until the port actually settles (releasing it earlier would start the next read while this one still holds the original), and a settlement after the deadline is logged as `read_overrun ms=<elapsed>`.
+  A read that has still not settled at twice its budget is logged once, at that moment, as `read_stuck ms=<elapsed>`: such a port keeps its slot for the life of the worker, and once every slot is held every thumbnail request waits `queueWaitMs` and answers 503. A port that honours the signal settles early and hands the slot to the next queued generation. Code that calls a `DailyReportReadAttachment` directly (tests, for example) must pass `signal`.
+
+Example — a read port over a host object store (the file is type-checked by `pnpm run typecheck:examples` and not shipped):
+
+```ts examples/read-attachment-port.ts
+/**
+ * Example read port over a host-provided object store (not shipped; type-checked by `pnpm run typecheck:examples`).
+ * ホストのオブジェクトストアの上に組む読み取りポートの例 (同梱しない。`pnpm run typecheck:examples` で型検査する)。
+ *
+ * It follows the port contract: typed failures instead of exceptions, the package's `signal` combined with a per-call deadline,
+ * the real size declared on HEAD, and `unavailable` (never `not_found`) for a failure that settles after an abort.
+ * ポート契約に従う: 例外ではなく種別付きの失敗で返し、パッケージの `signal` を呼び出しごとの締め切りと合成し、HEAD では実サイズを申告し、
+ * 中断の後に決着した失敗は `not_found` ではなく `unavailable` にする。
+ */
+import type { DailyReportAttachmentError, DailyReportReadAttachment } from "@aiquants/daily-report/server"
+
+/**
+ * The part of the host's storage client this port uses.
+ * この読み取りポートが使う、ホストのストレージクライアントの面。
+ */
+export type ObjectStore = {
+    /** Metadata of an object, or null when it does not exist; rejects on a storage error or an abort. 実体のメタデータ (無ければ null。ストレージの失敗と中断では拒否する)。 */
+    stat: (key: string, signal: AbortSignal) => Promise<{ size: number; contentType: string | null } | null>
+    /** Bytes of an object; rejects on a storage error or an abort. 実体のバイト列 (ストレージの失敗と中断では拒否する)。 */
+    read: (key: string, signal: AbortSignal) => Promise<Uint8Array<ArrayBuffer>>
+}
+
+/**
+ * Settings of the read port, supplied by the host.
+ * 読み取りポートの設定 (ホストが渡す)。
+ */
+export type ObjectStoreReadSettings = {
+    /** Deadline of one storage call (ms). ストレージ呼び出し 1 回の締め切り (ms)。 */
+    callTimeoutMs: number
+    /** Maps a stored file path to an object key, or null for a path this store must not read. 保存されたファイルパスをオブジェクトキーへ写す (読んではならないパスは null)。 */
+    resolveKey: (filePath: string) => string | null
+}
+
+/** 中断・締め切り・到達不能で決着した読み取り (実体についての判定ではない)。 */
+const UNAVAILABLE: DailyReportAttachmentError = Object.freeze({ ok: false, reason: "unavailable" })
+
+/**
+ * Creates a read port that reads attachments from the object store.
+ * オブジェクトストアから添付を読む読み取りポートを作る処理。
+ *
+ * @param store Host storage client. ホストのストレージクライアント。
+ * @param settings Per-call deadline and the path-to-key mapping. 呼び出しごとの締め切りと、パスからキーへの写像。
+ * @returns The read port. 読み取りポート。
+ */
+export const createObjectStoreReadAttachment = (store: ObjectStore, settings: ObjectStoreReadSettings): DailyReportReadAttachment => {
+    /**
+     * Combines the package's signal with the deadline of one storage call.
+     * パッケージのシグナルと、ストレージ呼び出し 1 回の締め切りを合成する処理。
+     *
+     * @param signal Signal from the package. パッケージから渡されたシグナル。
+     * @returns A signal that aborts on either. どちらでも中断されるシグナル。
+     */
+    const callSignal = (signal: AbortSignal): AbortSignal => AbortSignal.any([signal, AbortSignal.timeout(settings.callTimeoutMs)])
+
+    /**
+     * Reads an attachment (metadata only on HEAD) and settles with the bytes or a typed failure; never throws.
+     * 添付を読み (HEAD ではメタデータだけ)、バイト列か種別付きの失敗で決着する処理。例外は投げない。
+     *
+     * @param filePath Stored file path (never leaves the server). 保存されたファイルパス (サーバーの外へ出ない)。
+     * @param options Size bound, HEAD flag and the package's signal. サイズの上限・HEAD か・パッケージのシグナル。
+     * @returns The bytes, or a typed failure. バイト列、または種別付きの失敗。
+     */
+    const readAttachment: DailyReportReadAttachment = async (filePath, { maxBytes, head, signal }) => {
+        const key = settings.resolveKey(filePath)
+        if (key === null) return { ok: false, reason: "invalid_path" }
+        if (signal.aborted) return UNAVAILABLE
+        try {
+            const stat = await store.stat(key, callSignal(signal))
+            // 中断の後に届いた「無い」は打ち切りの結果であって実体の判定ではない (not_found はパッケージが実体消失として記録する)
+            if (stat === null) return signal.aborted ? UNAVAILABLE : { ok: false, reason: "not_found" }
+            if (stat.size > maxBytes) return { ok: false, reason: "too_large" }
+            // HEAD の Content-Length は GET と一致しなければならないので、読まずに実サイズを申告する
+            if (head) return { ok: true, bytes: new Uint8Array(0), contentType: stat.contentType, size: stat.size }
+            const bytes = await store.read(key, callSignal(signal))
+            // メタデータを読んだ後に実体が伸びていることがある
+            if (bytes.byteLength > maxBytes) return { ok: false, reason: "too_large" }
+            return { ok: true, bytes, contentType: stat.contentType, size: bytes.byteLength }
+        } catch (error) {
+            return { ok: false, reason: "unavailable", code: error instanceof Error ? error.name : undefined }
+        }
+    }
+    return readAttachment
+}
+```
+
+**Thumbnail renderer port**
+
+The port type spelled out (the example file checks that it is identical to the exported `DailyReportAttachmentThumbnailRenderer`):
+
+```ts examples/attachment-port-contracts.ts#thumbnail-renderer
+type DailyReportAttachmentThumbnailRenderer = {
+    readonly id: string
+    readonly render: (
+        source: Uint8Array<ArrayBuffer>,
+        options: { format: "png" | "jpeg" | "gif" | "webp"; maxWidth: number; maxHeight: number; signal: AbortSignal },
+    ) => Promise<{ ok: true; bytes: Uint8Array<ArrayBuffer>; contentType: "image/webp" | "image/jpeg" | "image/png" } | { ok: false; reason: "unsupported" | "failed" }>
+}
+```
+
+- `id` names the version of your rendering pipeline, for example `sharp-<version>/vips-<version>/webp-q75-e4/flatten-#ffffff/v1` (the id of the package's sharp renderer below, with the versions read from `sharp.versions` at run time), so a library update never leaves the id stale.
+  **Change it whenever the output bytes change** — output format, quality, effort, library version, or how you implement the contract. The id is part of the content identity and therefore of the ETag: a new id makes both the in-process cache and browser revalidation (304) stop reusing old previews. If you change the output without changing the id, browsers keep the old preview through 304s.
+- `createDailyReportService` / `createDailyReportServer` check the port when they are created, in this order, by the convention under **Configuration errors**: a port that is not an object (`null` included)
+  throws `RangeError` (`[daily-report] attachmentThumbnailRenderer must be an object with id and render; got null`), a missing `render` throws `TypeError` (`[daily-report] attachmentThumbnailRenderer.render must be a function`), a `render` that is given but is not a function throws `RangeError` (`…render must be a function; got "sharp"`), and an `id` that is not a string with non-whitespace content throws `RangeError` (`[daily-report] attachmentThumbnailRenderer.id must be a non-blank string naming the rendering pipeline version; got ""`).
+- `render`: fit the image inside `maxWidth` × `maxHeight` — the box of the requested variant — keeping the aspect ratio (never enlarge), apply the EXIF orientation, drop metadata, flatten transparency onto white, bound decode memory before decoding (a pixel count alone does not: a 16-bit sample takes twice the bytes of an 8-bit one), start no decoder other than the one for `format`, and never throw.
+- `signal` aborts when every request waiting for that content has gone or when the render stage's deadline passes (`renderMs`). A renderer that can stop (a remote image service, for example) should forward it and settle with `{ ok: false, reason: "failed" }`.
+  A render still running at its deadline is answered with 502 (`reason=render_timeout`), and a result that settles after everyone has gone is discarded (503); neither is cached. A renderer that cannot stop (in-process libvips) is still valid: the response is bounded by the deadline, but the generation slot stays held until the render settles (`render_overrun ms=<elapsed>`; a render that has still not settled at twice its budget is logged once as `render_stuck ms=<elapsed>`).
+- `format` is detected by the package from the leading bytes (PNG, JPEG, GIF87a / GIF89a, RIFF…WEBP), not taken from the declared type. Bytes with any other signature (SVG, TIFF, HEIF, BMP, ...) are never handed to the port.
+- `unsupported` means the content itself cannot be downscaled (deterministic); `failed` means a transient failure (retry may succeed).
+- The result's `contentType` is typed by the closed set (`DailyReportAttachmentThumbnailOutputMediaType`, derived from `DAILY_REPORT_ATTACHMENT_THUMBNAIL_OUTPUT_MEDIA_TYPES`) and must have 1 byte to `DAILY_REPORT_ATTACHMENT_THUMBNAIL_MAX_OUTPUT_BYTES`. Both are also checked at run time, for hosts written in JavaScript.
+  The bytes are checked too, not only the label: their leading signature must be the format the `contentType` names, and the size in their header (PNG `IHDR`, WebP `VP8` / `VP8L` / `VP8X`, the first JPEG `SOFn`) must be readable and fit the requested box. Anything else — including a thrown exception or an unknown failure reason — is a contract violation answered with 500 and never cached, so an undecodable or oversized preview is never cached for every viewer and never pinned by 304s.
+
+Values for implementing the port:
+
+| Value | Entry | Value |
+| --- | --- | --- |
+| `DAILY_REPORT_ATTACHMENT_THUMBNAIL_OUTPUT_MEDIA_TYPES` | server | `image/webp`, `image/jpeg`, `image/png` — the types the port may return (a frozen tuple; mutating it does not change the output check) |
+| `DAILY_REPORT_ATTACHMENT_THUMBNAIL_MAX_OUTPUT_BYTES` | server | `1048576` (1 MiB) |
+| `DAILY_REPORT_ATTACHMENT_THUMBNAIL_VARIANTS` | root | `{ tile: { maxWidth: 480, maxHeight: 320 } }` (frozen) — the box handed to `render` |
+
+**The sharp renderer (`createSharpThumbnailRenderer`)**: the server entry implements the port on sharp (libvips). The host passes its own `sharp` module, typed by `SharpLike` (the part the renderer uses), so the package never depends on sharp. The renderer:
+
+- fits the image into the box without enlarging it, applies the EXIF orientation, flattens transparency onto white and encodes WebP at quality 75 and effort 4 (metadata is dropped). It reads only the first frame of an animation.
+- reads the source's layout from its bytes before it starts sharp — for a JPEG its frame header (the first `SOFn` and `SOS`, read the way libjpeg reads them: one scan or several, and the sampling factors), for a PNG the interlace method in `IHDR`, for a WebP its chunks (lossy, lossy with an `ALPH` alpha plane, lossless or animated); a source whose layout cannot be read is `unsupported` without starting sharp.
+  It then reads the image header (`metadata()`, on the same pipeline with the same options) and decodes only an image within both bounds: at most 50,000,000 pixels (sharp's `limitInputPixels`) and a predicted working set of at most `DAILY_REPORT_SHARP_THUMBNAIL_DECODE_BUDGET_BYTES` (200,000,000 bytes). An image over either bound, a sample format outside the list below or a header without numeric dimensions is `unsupported` (content-determined, cached) without decoding.
+- predicts the working set of one render with `predictSharpThumbnailWorkingSetBytes(source, format, header)` from one frozen table, `DAILY_REPORT_SHARP_THUMBNAIL_WORKING_SET_MODEL` (both in the server entry): the buffer the layout's decoder holds for the whole image before it can shrink, plus `pipelineRows` = 2,048 full-width rows of decoded pixels (width × bands × bytes per sample; `uchar` / `char` 1, `ushort` / `short` 2, `uint` / `int` / `float` 4, `complex` / `double` 8) that libvips holds, plus `fixedBytes` = 4 MiB (the WebP encoder of the 480 × 320 output and libvips' own structures):
+
+  | Layout | Whole-image buffer | Largest square admitted |
+  | --- | --- | --- |
+  | Baseline (one-scan) JPEG, PNG without interlacing, lossy WebP | none: decoded row by row | 7,071² (the pixel limit; only very wide images reach the budget) |
+  | Multi-scan JPEG (progressive, or a first scan without every component) | the DCT coefficients: 64 coefficients of 2 bytes per 8 × 8 block of every component at its sampling factors, with libjpeg's rounding (outside libvips' memory accounting) | 5,218² at 4:4:4, 4,456² for CMYK, the pixel limit at 4:2:0 |
+  | Interlaced (Adam7) PNG | the decoded raster: width × height × bands × bytes per sample | 6,047² in 8-bit RGBA, 4,028² in 16-bit RGBA |
+  | GIF | 4 bytes per pixel | 6,047² with alpha, 6,270² without |
+  | Lossless WebP | 4 bytes per pixel | 6,047² with alpha, 6,270² without |
+  | Lossy WebP with an alpha plane | 5 bytes per pixel | 5,492² |
+  | Animated WebP | 9 bytes per pixel | 4,231² |
+
+  The table was fitted on sharp 0.35.5 / libvips 8.18.7 at one libvips thread over 107 layouts (every format and layout above, squares and aspect ratios up to 800:1, flat, noise and gradient content, the EXIF orientations), each rendered once in a fresh process, the working set measured as the peak resident set after the render minus the resident set before it. No render exceeded its prediction (the closest reached 93 % of it), the most full-width rows any render needed was 1,656 (2,048 is 1.24 times that), and every layout measured over the budget is refused.
+  The whole-image buffers of a lossy WebP with alpha and of an animated WebP are the most libwebp can allocate (measured: about 2.1 and 4.1 bytes per pixel). A host that checks its own decoders can assert measured ≤ `predictSharpThumbnailWorkingSetBytes(...)` ≤ the budget.
+- changes sharp's settings for the whole process when it is created: libvips' operation cache is turned off (the package caches the outcomes), libvips uses one thread per image (`sharp.concurrency(1)`: the model's rows were measured at one thread, and libvips' line caches grow with the thread count — a 7,071² 8-bit RGBA PNG took 42.2 MB at 1 thread, 64.5 MB at 4 and 89.2 MB at 8; the package's generation gate decides how many renders run at once), and every loader is blocked except one per format the package hands over (PNG, JPEG, GIF, WebP). An Ultra HDR JPEG is a valid JPEG:
+  the JPEG loader decodes its SDR base image, and the 480 × 320 WebP is byte-identical to the one the Ultra HDR loader made. A host that uses sharp for anything else gets the same settings there, so create the renderer once.
+- answers `failed` (transient, retried by the next request) only when the error message reports exhausted resources (memory, threads, open files, disk space; for example `webpsave: picture memory error` or `Error creating thread: Resource temporarily unavailable`). Every other failure is `unsupported` and cached: treating an unknown message as transient would read and decode a broken attachment again on every view.
+- checks the abort signal before it starts, after the header read (before decoding) and when it settles (libvips cannot be stopped midway), and answers `failed` for an aborted render.
+- is named `sharp-<sharp version>/vips-<libvips version>/webp-q75-e4/flatten-#ffffff/v1`, from `sharp.versions` at run time.
+
+Example — the wiring; the host imports its own sharp (type-checked, not shipped):
+
+```ts examples/sharp-thumbnail-renderer.ts
+/**
+ * Example: the package's sharp renderer on the host's own sharp module (not shipped; type-checked by `pnpm run typecheck:examples`).
+ * パッケージの sharp の描画ポートを、ホスト自身の sharp モジュールで使う例 (同梱しない。`pnpm run typecheck:examples` で型検査する)。
+ *
+ * The package implements the renderer and never depends on sharp: the host imports its own module and passes it. Creating the renderer
+ * changes sharp's settings for the whole process (the libvips operation cache off, one libvips thread per image, every loader except the
+ * PNG, JPEG, GIF and WebP ones blocked), so create it once, in the module that owns sharp.
+ * 描画ポートはパッケージが実装し、パッケージは sharp に依存しない。ホストが自分の sharp を読み込んで渡す。描画ポートを作ると
+ * プロセス全体の sharp の設定が変わる (libvips の操作キャッシュを切り、1 枚の画像を 1 スレッドで扱い、PNG・JPEG・GIF・WebP の
+ * 読み込み器のほかを封じる) ので、sharp を持つモジュールで 1 回だけ作る。
+ */
+import { createSharpThumbnailRenderer } from "@aiquants/daily-report/server"
+import sharp from "sharp"
+
+/**
+ * The process's thumbnail renderer port; its id is `sharp-<sharp version>/vips-<libvips version>/webp-q75-e4/flatten-#ffffff/v1`.
+ * プロセスのサムネイル描画ポート。id は `sharp-<sharp の版>/vips-<libvips の版>/webp-q75-e4/flatten-#ffffff/v1`。
+ */
+export const thumbnailRenderer = createSharpThumbnailRenderer(sharp)
+```
+
+Reference values for sizing, not guarantees (one development host: sharp 0.35.5, libvips 8.18.7, Node 24, one libvips thread per image; p50 of warm runs): a 1920 × 1080 PNG screenshot about 35 ms, a 1280 × 800 PNG about 27 ms, a 12 MP JPEG about 79 ms, a 12 MP PNG about 200 ms with a process peak of about 194 MiB. A baseline JPEG is cheap because libvips shrinks it while decoding (a progressive one fills its coefficient buffer first, above); PNG cost grows with the pixel count.
+
+Example — the wiring (the ports are service keys; the tuning keys stay in the host's base configuration):
+
+```ts examples/attachment-wiring.ts
+/**
+ * Example wiring of attachment delivery into `createDailyReportServer` (not shipped; type-checked by `pnpm run typecheck:examples`).
+ * 添付配信を `createDailyReportServer` へ結線する例 (同梱しない。`pnpm run typecheck:examples` で型検査する)。
+ *
+ * The three ports are service keys, like `attachmentMaxBytes`; the tuning keys (`attachmentThumbnailConcurrency`, ...) configure the
+ * handlers of one process and stay in the host's base configuration. Every attachment key works only together with the ports it
+ * needs, and injecting all three ports makes every attachment key valid. Mount `attachment.loader` of the result on the host's own
+ * byte-serving route (`{apiBasePath}/attachment/{token}`); thumbnails use the same route.
+ * 3 つのポートは `attachmentMaxBytes` と同じくサービスのキーで、調整値 (`attachmentThumbnailConcurrency` など) は 1 プロセスの
+ * ハンドラーの設定としてホストの基本設定に置く。添付のキーはどれも要るポートと組でしか効かず、3 つのポートをすべて注入すれば
+ * 添付のどのキーも有効になる。結果の `attachment.loader` はホスト自身のバイト列配信ルート (`{apiBasePath}/attachment/{token}`) に
+ * マウントし、サムネイルも同じルートを使う。
+ */
+import { createDailyReportServer, type DailyReportIdCodec, type DailyReportServerConfig } from "@aiquants/daily-report/server"
+import { createObjectStoreReadAttachment, type ObjectStore, type ObjectStoreReadSettings } from "./read-attachment-port"
+import { thumbnailRenderer } from "./sharp-thumbnail-renderer"
+
+/**
+ * What the host supplies: its server configuration without the attachment ports, and what the read port is built from.
+ * ホストが渡すもの: 添付のポートを除いたサーバー設定と、読み取りポートの材料。
+ */
+export type AttachmentWiring = {
+    /** The rest of the server configuration, including the attachment size limit and tuning keys. 添付のサイズ上限と調整値を含む、サーバー設定の残り。 */
+    base: Omit<DailyReportServerConfig, "attachmentIdCodec" | "readAttachment" | "attachmentThumbnailRenderer">
+    /** Attachment id obfuscation (an instance separate from the user-id codec). 添付 ID の難読化 (ユーザー ID のコーデックとは別のインスタンス)。 */
+    idCodec: DailyReportIdCodec
+    /** Storage client and its read settings. ストレージクライアントとその読み取り設定。 */
+    storage: { store: ObjectStore; settings: ObjectStoreReadSettings }
+}
+
+/**
+ * Creates the daily-report server with attachment delivery and thumbnails enabled.
+ * 添付配信とサムネイルを有効にした日報サーバーを作る処理。
+ *
+ * @param wiring Base configuration and the attachment dependencies. 基本設定と添付の依存。
+ * @returns The server; mount its `attachment.loader` on the attachment route. サーバー (`attachment.loader` を添付のルートへマウントする)。
+ * @throws {RangeError} When a numeric attachment setting in `base` is not an integer in range. `base` の添付の数値設定が範囲内の整数でないとき。
+ */
+export const createDailyReportServerWithAttachments = ({ base, idCodec, storage }: AttachmentWiring): ReturnType<typeof createDailyReportServer> =>
+    createDailyReportServer({
+        ...base,
+        attachmentIdCodec: idCodec,
+        readAttachment: createObjectStoreReadAttachment(storage.store, storage.settings),
+        attachmentThumbnailRenderer: thumbnailRenderer,
+    })
+```
+
+**`hasThumbnail`**: every `DailyReportAttachmentSummary` carries a required `hasThumbnail: boolean`. It is `true` only when both `attachmentThumbnailRenderer` and `readAttachment` are injected, the declared `fileType` is exactly one of `image/png`, `image/jpeg`, `image/gif` or `image/webp` (exact match: `IMAGE/PNG`, parameters and surrounding whitespace do not qualify), the known `fileSize` is at most `attachmentMaxBytes` (an unknown size qualifies; the read port's `too_large` enforces the bound), and `state` is not `"absent"`.
+On the SSE wire an attachment entry without `hasThumbnail` (published before the field existed) is accepted as `false` (`.default(false)`); a non-boolean value is rejected.
+The client places a thumbnail on this flag alone; it has no switch of its own.
+
+**Thumbnail endpoint (`?thumbnail=tile`)**
+
+- **GET only**: `HEAD` and every other method answer 405 with `Allow: GET` (checked right after the query). A HEAD response would need a generated body to report the same `Content-Length` as GET.
+- **Order**: authenticate → query (400) → method → ports → token → viewer → renderer port → rate admission (below; an empty bucket answers 429 without resolving visibility or running the authorization query)
+  → authorization (`getAttachmentForUser`, the SQL predicate) → eligibility, identity and ETag → `If-None-Match` (304) → the generation token of a revalidation (below) → not visible / not eligible (404) → cache → generation. The cache, joining a generation and the 304 all come **after** authorization, so a cached preview is never returned to a viewer who cannot see the attachment.
+- **Rate admission uses two buckets per user and process**. Every token is taken synchronously — before the first `await` on admission, right after authorization's last `await` otherwise — so concurrent requests can never spend one token twice. With L = `attachmentThumbnailRateLimitPerMinute`:
+  - The **generation bucket** holds L tokens and refills L per minute. Every answer except a matching 304 needs one of its tokens. A request without `If-None-Match` can never be a 304, so it spends its token on admission or is answered 429 (`reason=rate_limit`) before authorization.
+    A request that fails authorization (`not_visible`) or goes on to generate (a cache miss) keeps the whole token spent; a cache hit and a not-eligible 404 give back all but a tenth of it, the tenth paying for the authorization query. A refund refills the bucket first and never lifts it above L.
+  - The **revalidation bucket** holds 10 L tokens (L ÷ the tenth) and refills 10 L per minute. A request with `If-None-Match` spends one of them on admission or is answered 429 before authorization (`reason=revalidation_rate_limit`); it holds no generation token while it waits for authorization.
+    After authorization, a matching ETag answers 304 and takes nothing more (the revalidation bucket has paid for its query). Any other answer — not visible, not eligible or an ETag that does not match — spends a generation token at that point under the generation bucket's rules, or is answered 429 (`reason=rate_limit`) when none is left.
+    Invisible attachments and visible ones with another ETag pay alike, so that 429 does not reveal whether the attachment is visible; only a visible attachment's right ETag answers 304.
+  - Bounds per user and process, by construction: generations and `not_visible` answers at most L from a full bucket, then L per minute; authorization queries at most 11 L in flight at once (L requests holding a generation token, 10 L holding a revalidation token), and from full buckets at one instant, or per minute of refill, at most 10 L answered right after authorization plus 10 L revalidations (2,400 at the default 120).
+  - First views and revisits never refuse each other: a revisit waiting for authorization holds no generation token, so it cannot make a concurrent first view answer 429, and revisiting thumbnails the browser already holds is a 304 per tile while the revalidation bucket has tokens, also right after new tiles emptied the generation bucket. A run of refusals writes one log line per bucket, not one per request (see **Log levels** below).
+- **Identity**: `JSON.stringify([rendererId, box.maxWidth, box.maxHeight, attachmentId, filePath, fileType, fileSize])`, with the renderer `id`, the box of the requested variant (not its name: the box decides the output bytes) and the current file path, type and size, so an attachment rewritten under the same id, a new rendering pipeline or a different box is regenerated. The cache, generation joining and the ETag all use it; the ETag is the strong SHA-256 of the key, so the path never leaves the server.
+  A generation's outcome carries this identity only when what it read matched the row's size (**verified**; see **Read port** above); an **unverified** outcome gets no validator and is never cached.
+- **Revalidation**: a verified preview carries `Cache-Control: private, no-cache` and the ETag. `If-None-Match` is compared weakly (`W/` stripped, lists accepted); `*` never matches. A match answers 304 without touching the gate, storage or renderer. Re-mounted thumbnails cost one 304 round trip, and a logout or a visibility change takes effect on the next revalidation.
+  An unverified preview is sent with `Cache-Control: no-store` and no `ETag`: the browser neither keeps nor revalidates it, so a later `If-None-Match` can never pin it through 304s, and the next view generates again.
+- **Generation**: a process-local gate with `attachmentThumbnailConcurrency` slots and a FIFO wait queue (at most 64 waiting, 8 per user, waiting at most `queueWaitMs`). A slot is held while the original is read and rendered. Concurrent requests for the same identity join one generation; the joined requests share one read made with the first requester's principal. A request that disconnects withdraws from the shared generation, but its handler still settles with the shared outcome (which no client receives).
+  The generation has its own abort signal, which fires only when every joined request has gone, and passes it to the gate wait and to both ports. An abandoned generation leaves the wait queue; a port that honours the signal settles early and hands the slot to the next queued generation; and a stage that settles after the abort is discarded before its result is looked at (see **Read port** above).
+- **Time budget**: one budget bounds a cache miss from the generation gate onward — the wait for a slot, the read, the render and the transfer — so a request that has reached the gate leaves the server within the sum of those stages, and the client waits exactly that sum before counting a load as failed. Each port stage runs under its own deadline and answers 502 at the deadline even when the port ignores the signal; a deadline that passes after every requester has gone ends as 503 `aborted` instead, since nobody receives it.
+  Two things are outside the budget. Authentication and authorization run before the gate and are bounded only by the host's own timeouts; their time is taken out of the client's sum as well. And the budget cannot end a port that ignores its signal: after the 502 such a port keeps its generation slot, and the server logs `read_stuck` / `render_stuck` once when it has not settled at twice its stage budget.
+
+  | Stage | Budget | At the deadline |
+  | --- | --- | --- |
+  | `queueWaitMs` — waiting for a generation slot | 30 s | 503 `reason=queue` (`Retry-After: 5`) |
+  | `readMs` — reading the original | 30 s | 502 `reason=read_timeout` |
+  | `renderMs` — decoding, resizing, encoding | 10 s | 502 `reason=render_timeout` |
+  | `transferMarginMs` — sending the response (at most 1 MiB) | 5 s | (the client's margin) |
+  | Client load timeout | 75 s (the sum) | the load counts as one failure |
+
+- **Cache**: an LRU bounded by `attachmentThumbnailCacheBytes` and 1,024 entries (each entry weighs its body plus 256 bytes). A preview is stored as an owned copy sized exactly to its body, so a view into a larger buffer never keeps that buffer alive, and later writes to the port's buffer do not change the cached preview.
+  It stores only verified outcomes: successful previews and the content-determined failures (signature mismatch, the port's `unsupported`, and the read port's `too_large` for a row whose size is unknown — on a row with a known size, which eligibility keeps within `attachmentMaxBytes`, a `too_large` is always unverified). It never stores unverified outcomes, `failed`, timeouts, storage errors (including `not_found`), queue rejections, aborts or exceptions.
+- **Presence records**: `not_found` sets the missing mark (`markAttachmentMissing`). A successful read does **not** call `markAttachmentPresent` (it would issue an unconditional UPDATE on every view, and `present` and `unknown` look the same on screen);
+  the client never requests a thumbnail from a summary that already says `absent` (`hasThumbnail: false`). The endpoint itself does not check `state`, though, so a request from an older summary (for example the automatic retry right after a `not_found`) still reads and renders, and a successful read leaves the mark unchanged. Recovery is left to the original download. Cache hits and 304s record nothing.
+
+| Status | When |
+| --- | --- |
+| 200 | Preview. Headers: the port's `Content-Type`, `Content-Length`, `Cache-Control: private, no-cache` and `ETag` (an unverified preview: `Cache-Control: no-store` and no `ETag`), `X-Content-Type-Options: nosniff`, `Content-Security-Policy: default-src 'none'; sandbox`, `X-Frame-Options: SAMEORIGIN`, forwarded `Set-Cookie` |
+| 304 | `If-None-Match` matches (carries `Cache-Control`, `ETag`, `Set-Cookie`) |
+| 400 | A query that names no delivery (unknown or repeated variant such as `?thumbnail=1`, combined with `download`), or a malformed token |
+| 401 / 403 | Not authenticated / no internal user |
+| 404 | Ports not injected, not visible, not eligible, signature mismatch, `unsupported`, `too_large`, `not_found`, `denied`, `invalid_path` — one identical body for all |
+| 405 | Any method other than GET (`Allow: GET`) |
+| 429 | An empty generation bucket (`reason=rate_limit`) or revalidation bucket (`reason=revalidation_rate_limit`), or a revalidation that is not a matching 304 when no generation token is left after authorization (`reason=rate_limit`) (`Retry-After: 60`) |
+| 502 | Storage unreachable (`unavailable`), the port's `failed` (`render_failed`), or a stage deadline (`read_timeout`, `render_timeout`) |
+| 503 | Wait queue full or wait timed out (`queue`), or the generation abandoned by every waiting request (`aborted`; no one receives it) (`Retry-After: 5`) |
+| 500 | Unexpected exception, including one thrown by a port during generation (logged as `500 attachment=<id> viewer=<id> variant=thumbnail cache=miss reason=port_exception message=<msg>`, never cached), or a port contract violation (`port_contract`: a render result outside the contract, logged with `code=` `content_type`, `bytes`, `empty`, `too_large`, `signature` or `dimensions`, or a read over `maxBytes`, `code=over_max_bytes`), or a host route that passes no `token` parameter (a route misconfiguration, below) |
+
+Error responses are JSON (`{ "error": { "message": "..." } }`) with `Cache-Control: no-store` (a 404 or 405 without freshness information may otherwise be cached heuristically, `Set-Cookie` included), and forward `Set-Cookie`. Log lines carry `attachment=<id> viewer=<id> variant=thumbnail`, plus `cache=hit|miss|revalidated` once the cache stage is reached; the 200 and 404 lines of an unverified outcome end with `identity=unverified`.
+Unexpected exceptions outside generation go to the loader's shared catch and are logged as `500 attachment=? viewer=? reason=unexpected message=<msg>` (no `variant`).
+A route that mounts `attachment.loader` without a `token` route parameter is the host's configuration error, on both deliveries: right after the port check the loader throws `[daily-report] params.token must be passed by the route that mounts attachment.loader; declare a "token" route parameter ({apiBasePath}/attachment/{token})`, which that catch logs and answers 500, without decoding an empty token or querying the database.
+Rejections up to the renderer-port check (401 / 400 / 405 / 404 for a missing port / 403) are not logged.
+The package never writes the file path itself; a `port_exception` line includes the port's own error message verbatim, so keep paths out of your port's error messages.
+
+**Log levels** (both deliveries; the line formats are fixed):
+
+| Level | Outcomes |
+| --- | --- |
+| `info` | 200, 304, the 503 nobody receives (`reason=aborted`), 404 `not_eligible`, and the content-determined 404s (`signature`, `unsupported`, `too_large`; cached when verified) |
+| `warn` | 404 `not_visible` (a sign of token enumeration), the storage 404s (`not_found`, `denied`, `invalid_path`), 413 (`db_size`, and the port's `too_large` on an original), the first 429 of a bucket's run of refusals and the run's `rate_limit_suppressed` / `revalidation_rate_limit_suppressed` line, the busy 503s (`queue`, `concurrency`), every 502, port settlements after a deadline (`read_overrun`, `render_overrun`), ports still unsettled at twice their stage budget (`read_stuck`, `render_stuck`) and thumbnail reads that do not match the row's size (`size_mismatch`: another length, or a `too_large` on a row whose size is known) |
+| `error` | 500 (`port_exception`, `port_contract` including a read over `maxBytes` (`code=over_max_bytes`), the loader's `unexpected`, a route without the `token` parameter among them) and failed `markAttachmentMissing` / `markAttachmentPresent` writes |
+
+`error` is left to failures of the server itself, so an alert on `error` does not fire on user traffic or on upstream storage states.
+
+**429 lines**: each rate bucket of a user (the original's, and the thumbnail's generation and revalidation buckets) writes its `429 … reason=rate_limit` (`reason=revalidation_rate_limit`) line only for the first refusal after an admission.
+The later refusals of the run are counted, and the bucket's next admission writes one `rate_limit_suppressed count=<N> viewer=<id>` (`revalidation_rate_limit_suppressed …`) line (with `variant=thumbnail` on the thumbnail path), N being the refusals that had no line of their own; the 429 of a revalidation refused after authorization counts in the generation bucket's run.
+A client therefore cannot write log lines at its request rate.
+
 ### Transactions
 
 日報の作成と編集はそれぞれ 1 トランザクションで書き切る。入口は `createDailyReportService` 内の `inTransaction` 1 つに限り、**デッドロックの犠牲になったトランザクションだけをやり直す** (判定は [`@aiquants/mssql`](../mssql/README.md) が持ち、閉包は `capture` で包んで ORM が原因を消す前に押さえる)。鍵の範囲が重なる並行操作はデッドロックしうるため、犠牲になった側は従来 500 になって書いた内容が消えていた。
@@ -196,7 +598,7 @@ resolveVisibleSourceTypes: async (request, { reason }) => {
 
 ## Client wiring
 
-```tsx
+```tsx illustrative
 // daily_report._index/route.tsx
 import { createDailyReportClientLoader, DailyReportPage, dailyReportShouldRevalidate } from "@aiquants/daily-report/client"
 
@@ -220,6 +622,7 @@ export default function Route() {
                         title: "Field Reports", content: "Body",
                     },
                     onError: (info) => yourToast(info.message), // Optional: route mutation failures to your own toast
+                    headingLevel: 2,                        // Optional: level of each report's heading, 2–5 (default 3)
                     // apiBasePath: "/daily_report/api", ssePath: "/sse/daily_report/updates"
                 }}
             />
@@ -228,9 +631,14 @@ export default function Route() {
 }
 ```
 
-`config` is **required** and so is its `onSessionExpired` port (omitting it is a type error, TS2741; a non-function throws a `TypeError` at render). The package never navigates by itself: when the session is gone — the SSE stream ends with `auth-required`, or the ids stream answers 401 / 403 — it calls `onSessionExpired()` exactly once per occurrence and stops. A typical host reloads the route (`navigate(0)`) so its own loader redirects to the login page. `DailyReportConfigProvider` takes the same required `config`; outside a provider, the default configuration's `onSessionExpired` throws.
+`config` is **required** and so is its `onSessionExpired` port (omitting it is a type error, TS2741; at render a missing port throws a `TypeError`, `[daily-report] config.onSessionExpired must be a function …`, and a value that is not a function a `RangeError` ending with `; got <value>`; every client configuration error follows the convention under **Configuration errors** in [DI ports](#di-ports)).
+The package never navigates by itself: when the session is gone — the SSE stream ends with `auth-required`, or the ids stream answers 401 / 403 — it calls `onSessionExpired()` exactly once per occurrence and stops. A typical host reloads the route (`navigate(0)`) so its own loader redirects to the login page. `DailyReportConfigProvider` takes the same required `config`; outside a provider, the default configuration's `onSessionExpired` throws.
+
+`config.headingLevel` is the level of each report's heading: an integer from 2 to 5 (default 3), so that the section headings inside a report, one level lower, stay within `h6`. Pick the level that continues your page's outline (see [Document structure](#keyboard-focus-and-selection-list--detaillist)); any other value (`1`, `6`, `3.5`, `"3"`, `null`) throws a `RangeError` at render (`[daily-report] config.headingLevel must be an integer from 2 to 5 …; got 6`).
 
 `DailyReportPage` is layout-agnostic (header rendering via `renderHeader` slot, error boundaries/footer control managed by the app). For fine-grained usage, `DailyReportActionProvider`, `DailyReportResolvedContent`, `useDailyReportDetail`, etc. can be imported individually.
+Every field `useDailyReportDetail(reportHubId, businessDate)` returns — `report`, `error`, `isLoading` and `isRefetching` — belongs to the id it is called with: the hook keeps them as one record keyed by the id. On the first render after the id changes it already returns that id's starting state: its cached report (one definition, also used by the loading effect: the report cache, expired entries included, then the business date's cached list), `isLoading` only when nothing is cached, no error and no refetch yet — never the previous id's report, error or loading flags.
+An expired cached report is therefore drawn at once, never preceded by `null`, and refetched behind it; an answer that arrives for an earlier id is dropped. An id of 0 or less fetches nothing and returns no report (0 also returns an `Invalid ID` error).
 
 Mutation failures (save / publish / delete / comment) are surfaced through an error seam: inject `config.onError(info: DailyReportErrorInfo)` to route them into your own toast/notification system, or omit it to use the package's built-in `role="alert"` banner (auto-dismiss + manual close). Failures on a continuation that resolves after a no-reload user switch are suppressed. If you compose `DailyReportActionProvider` yourself instead of using `DailyReportPage`, wrap it in `DailyReportErrorProvider` (both are exported from `@aiquants/daily-report/client`) so `onError` / the banner work.
 
@@ -240,6 +648,310 @@ If your app overrides `config.apiBasePath`, pass the same value to `createDailyR
 `DailyReportPage` subscribes via `useDailyReportIdsStream`, rendering the list as soon as the first chunk arrives (on cache misses the server races a fast `TOP 200` first page against the cached full query, so first paint does not wait for the full id scan).
 There is no `dailyReportIds` prop and no deferred `/ids` JSON fetch (the old `ids` endpoint was removed).
 
+### View height (host layout)
+
+Each view (List and DetailList) is as tall as the space the host's layout leaves it: the platform's layout sizes every box from the page down to the view, and no script computes or writes a height.
+
+- **Host contract**: render `DailyReportPage` (or `DailyReportResolvedContent`) as the content of a column flex container (`display: flex; flex-direction: column`) whose height is bounded — a definite height, or the growing item of a column with a minimum height, such as a `min-height: 100dvh` shell whose footer follows the content. The header that `renderHeader` returns and the page box are items of that container, and the page box takes the rest of it. Nothing is bound and no host variable is read.
+  Outside such a container the view has no height to fill: its size is contained (below), so its content cannot size it, and it is 0 px tall.
+- **The fill chain**: every box from the page box down to a view's root — the page box, its centred width-capped wrapper, the view-mode tabs and the active tab panel — fills the rest of its parent column (`flex: 1 1 0%; min-height: 0`, `FILL_COLUMN_CLASS_NAME`) and declares no height. The wrapper's padding is 4 px at the top and the sides and none at the bottom, so the view's box ends exactly at the page's bottom edge.
+- **The view's root contains its size** (`VIEW_ROOT_CLASS_NAME`: the fill rule, `contain: size` and `overflow: clip`): its box is sized as if it were empty, so what the view renders — a `VirtualScroll` given the measured height — never feeds back into the root's size, into the intrinsic size of an ancestor (a host column with a minimum height does not grow) or into the document's scroll height. The clip keeps rows drawn for the previous height from painting outside the box during the one frame before the view renders the new height.
+  Layout and paint are not contained, so the mobile overlay, a fixed-position descendant, keeps the viewport as its containing block.
+- **One measurement**: `VirtualScroll` needs its viewport size as a number (`viewportSize`), so the view's root reads its own border box once in a layout effect before the first paint (`useDynamicViewportHeight`; until then the view renders no body, so no row is ever drawn at a guessed height; the List also waits for its row slot, below) and then follows it with one `ResizeObserver` on the root alone (`box: "border-box"`), whose delivery only hands `borderBoxSize[0].blockSize` to React state and reads and writes nothing.
+  The height is the layout's own box, so the same layout gives the same height whatever the order of the measurements, every change is followed, a sub-pixel one included, and 0 stays 0. The value reaches only `viewportSize`: the list column, the panel group and the scroll container write no height.
+- **G-symmetric frame**: the rows' gutter G is inside the view's box, so the last aligned surface — a List or DetailList row aligned to the bottom, or the List's side pane — sits exactly G = 8 px above the page's bottom edge (where a footer that follows the page starts), the distance from the view-mode toolbar to the first surface at the top.
+- **Empty list**: `labels.listEmpty` is laid over the top of the list area (absolutely positioned inside the scroll container, out of the flow), so an empty view keeps the same box.
+
+### Keyboard, focus and selection (List / DetailList)
+
+Each view keeps one cursor: the selected report, the report that holds the view's single Tab stop, the row that owns focus, and at most one pending focus request, all keyed by report id.
+The keys are delegated to each view's **list**: the element that holds the view's `VirtualScroll` (its rows and its scroll bar). In the List view the resize handle and the side pane lie outside the list.
+
+| Key | List | DetailList | Default prevented |
+| --- | --- | --- | --- |
+| `ArrowUp` / `ArrowDown` | Selects the previous / next report and reveals it by the nearer edge. Focus moves to the card's primary button (to the row frame while the card is not shown). | Selects the previous / next report and aligns it to the top (the reading start); focus moves to the row. | Yes, also at the ends (no wrap-around) |
+| `Home` / `End` | First / last report, aligned to the top / bottom | First / last report, aligned to the top / bottom (to the top when the last row is taller than the viewport) | Yes |
+| `PageDown` / `PageUp` | Selects the farthest row that still fits in the viewport together with the focused row, revealed by the nearer edge | The same; a focused row taller than the viewport is first scrolled by min(overflow, ⌊0.875 × viewport⌋) without changing the selection | Yes |
+| `Enter` / `Space` | The focused primary button's native activation: selects (on a mobile layout it also opens the detail overlay) | On the row element itself: selects without scrolling. On a control inside the row: that control's own action | Native / yes |
+| `Ctrl+Home` / `Ctrl+End` | Leaves the list: focus moves to the last Tab stop before the list / the first one after it (below; on the desktop layout `Ctrl+End` reaches the resize handle), which the browser scrolls into view; the selection does not change | The same | Yes, when there is such a stop (otherwise not handled: the key keeps its browser meaning) |
+| `Tab` / `Shift+Tab` | Moves through the Tab-stop row's controls only (below); Tab never selects | The same | No |
+| Any other key, a modifier combination, IME | Not handled, and cancels a pending focus request | The same | No |
+
+- **The move starts from the focused row**, not from the selection: Tab into a row, press `ArrowDown`, and the report after that row is selected.
+- **Held keys move at once, then at most once per frame.** The first repeated keydown (`repeat`) of a key is checked like any key and starts a repeat stream from the focused row; it and every later repeat on the same axis have their default prevented.
+  A repeat that finds the stream's frame fence open — the first one, and any repeat after a frame in which nothing was pending — moves at once inside its own keydown (one selection, the scroll, one focus request; React commits the discrete event synchronously), so a key that repeats more slowly than the display refreshes moves once per keydown and never waits for a frame.
+  The repeats behind the fence only add their step: the arrows one row each (up and down cancel out), `PageUp` / `PageDown` one page each, and `Home`, `End` and `Enter` / `Space` on a DetailList row count once; they read neither the DOM nor the layout.
+  The frame right after an immediate move applies nothing (two moves never commit in one frame); every later frame applies what accumulated as one move with `flushSync` from the row that holds focus, so the next key already starts from the new row, and a frame with nothing pending opens the fence again. A key that repeats faster than the display therefore moves at most once per frame. A repeat on another axis (rows, pages, `Home`, `End`, activation) applies what is pending before it starts a new stream.
+  A key that is not a repeat first resolves its command, drops the pending focus request and then applies the pending repeats synchronously: the destination row renders and takes focus inside that call, however far the repeats went, so the key moves from there. Every `keyup` applies what is pending and ends the stream; a pointer press, a wheel or touch start in the view, focus leaving the view and unmounting end it without applying it.
+  On a slow device the keys therefore never queue up, and the selection stops when the key is released. `Ctrl+Home` / `Ctrl+End` are never accumulated. While a stream lasts, the desktop side pane keeps showing the report the stream started from (see **List side pane** below).
+- **Ignored keys**: `Alt` / `Ctrl` / `Meta` / `Shift` combinations other than `Ctrl+Home` / `Ctrl+End` alone (so `Ctrl+PageDown` and `Shift+End` keep their browser meaning); an event whose default is already prevented; IME composition (`isComposing` or `keyCode` 229);
+  keys from outside a row (the scroll bar, the side pane, the mobile overlay); keys from an input region — a `form` (every control of the in-row edit form and of the comment form, their buttons included) or an editable element (`input`, `textarea`, `select`, `contenteditable` other than `"false"`, `audio[controls]`, `video[controls]`) —
+  or from inside ARIA widgets that use these keys themselves (`combobox`, `listbox`, `menu`, `menubar`, `radiogroup`, `slider`, `spinbutton`, `textbox`, `tree`, `grid`, `scrollbar`, `tablist`, `toolbar`, `treegrid`, `separator`) between the key's origin and the view's scroll container, the exits included.
+  So no key pressed in an open in-row editor moves the list (moving it would scroll the editing row out of the rendered window and discard what was typed). Only elements **inside** the view count: wrapping the whole view in a host `form`, `role="grid"`, `role="listbox"` or `contenteditable` region does not disable the keys. While the viewport has no size yet, the movement keys are not handled.
+- **One Tab order rule for both views: only the Tab-stop row's controls are in the Tab order.** The Tab-stop row is the row that owns focus (below) while it is inside the visible range, otherwise the selected row while it is visible, otherwise the first visible row (until the view has reported its visible range: the focus owner, then the selection).
+  Every focusable control the package draws inside a row reads the rule: the List card's primary button, ★ and 既読, the DetailList row's ★, 既読, 編集 (on the viewer's own reports) and 削除, the comment controls (delete and its confirmation, the comment field and its send button), the edit form's fields and buttons, and the attachment links keep their natural order in the Tab-stop row and have `tabIndex=-1` in every other row. The stop row's own element is a stop too where it takes focus: a DetailList row (`tabIndex=0`) and a List row frame whose card is not shown.
+  So the Tab path through a view is one row's controls long, however many rows are rendered: crossing the List takes exactly 3 presses (the primary button, ★ and 既読). Because the focus owner is the stop, a control reached by pointer continues within its own row, and a row in edit mode keeps its form in the Tab order.
+  The scroll bar's two arrow buttons are not Tab stops in either view (`enableArrowButtonTabStops: false` of `@aiquants/virtualscroll`), because the keys above already scroll the list. The arrows still scroll on a press and while held and keep their names; they sit inside the scroll bar's `role="scrollbar"` element, whose children ARIA 1.2 makes presentational, so whether assistive technology presents them as separate buttons depends on the browser (Chromium does).
+- **Leaving the list** (`Ctrl+Home` / `Ctrl+End`, as in the WAI-ARIA feed pattern): focus moves to the last Tab stop before the list or the first one after it — where real `Shift+Tab` from the list's first stop and real `Tab` from its last stop go — and the browser scrolls it into view as it does for Tab.
+  In the List view the exits are measured from the list like in the DetailList, so on the desktop layout `Ctrl+End` moves to the resize handle (then Tab goes on to the side pane), and `Ctrl+Home` to the last stop before the list (in `DailyReportPage`, the last control of the view-mode toolbar).
+  The stops come from the package's one model of sequential focus navigation (`readFocusCapability`, `listTabbables` and `partitionTabbables` in `src/client/keyboard/dom-node.ts`), which the mobile overlay's Tab wrap uses as well. The order is the flat tree's: open shadow roots at their hosts, slotted elements at their slots (an empty slot shows its own children), and a focusable ancestor before its descendants (the package writes no positive `tabindex`). The list's descendants do not count; a focusable ancestor of the list (a host tab panel around the view, for example)
+  counts before it, as real `Shift+Tab` returns there.
+  An element with a `tabindex` that parses as an integer is a stop when the value is 0 or more (a negative value makes it focusable but not a stop; an unparsable value counts as absent). Without one, its kind decides:
+  `a` / `area` with `href`, `button`, `input` other than `type="hidden"` (of a radio group only the checked radio, or the first enabled and rendered one when none is checked), `select`, `textarea`, the first `summary` of a `details`, an editing host (`contenteditable` true, empty or `plaintext-only` under a parent that is not editable), `audio` and `video` with `controls`, `iframe`, `embed`, an `object` that shows a document, and — as Chromium does — a keyboard-focusable scroll container:
+  an element that overflows on an axis whose `overflow` is `auto` or `scroll` and has no stop among its descendants (the document's own scroller excluded).
+  A stop must also be enabled (not `:disabled`), outside every `inert` subtree (shadow-root boundaries are crossed to the host) and visible to `checkVisibility({ visibilityProperty: true })` (not inside `display: none` or `content-visibility: hidden`, not `display: contents`, not `visibility: hidden`; an element that `content-visibility: auto` skips still counts, since it stays in the Tab order); an `area` counts when an image that uses its map is visible.
+  The stops of a closed shadow root cannot be seen and are not counted; an element outside the HTML and SVG namespaces is not counted even with a `tabindex` (Chromium stops there, but script cannot focus it), and an `audio` element with `controls` is one stop (Chromium also stops inside its built-in controls).
+  When there is no such element on that side, the key is not handled and keeps its browser meaning; for example, when nothing focusable follows the list on the page, `Ctrl+End` scrolls the document as usual. `labels.listKeyboardHelp` names both exits and says that they apply when there is a control before or after the list.
+- **Focus follows the selection by report id, inside the key's commit.** A key move focuses its destination before its one synchronous commit ends, whether or not the row was rendered: a destination outside the rendered window gets the alignment scroll (`scrollToIndex`) in that same commit, which renders it, and a move without alignment lands on a fully visible row, which is rendered already (a key that only scrolls, such as `PageDown` inside a tall DetailList row, requests nothing).
+  So no key leaves a focus request behind: a wheel that follows in the same task finds the destination focused and changes nothing. Focus is set with `focus({ preventScroll: true })` (native focus scrolling would move the pane's `overflow: hidden` content element away from the virtual scroll position).
+  A request stays pending only on the paths that send focus to a row that may lie outside the rendered window: the focus owner's report leaving the list and the selected report deleted from the side pane or the mobile overlay (the table below), and the List's return to the card whose overlay closed (its scroll runs in an effect after the commit). Such a request settles when its row registers, however long that takes;
+  the next key, a `pointerdown`, `wheel` or `touchstart` in the view, and the destination leaving the list drop it, and a dropped request never settles later.
+  Focus is only ever taken from nowhere — no element, `body`, or an element inside an `inert` subtree such as the mobile overlay while it slides out (such an element cannot keep focus; `isFocusNowhere` in `src/client/keyboard/dom-node.ts`) — or from inside the view; focus that has meanwhile moved to the side pane, the open overlay or a host element stays there and the request is dropped.
+- **A key move writes before focus and commits once.** The row cursor owns the `tabindex` of every registered focus target (0 on the Tab-stop row, −1 on every other row; the row components render none): it writes the attribute when a target registers and when the row's Tab stop changes, and never rewrites a value the element already has.
+  A move first makes the destination current and the Tab stop while focus is still on the origin (the cursor writes the destination's `tabindex="0"` then, without a React commit); then focus moves; then, once focus has left the origin, the selection and the Tab stop settle on the destination (the cursor writes the origin's `-1`). The rows' states, the host's selection and the scroll commit in one synchronous React commit.
+  No step writes the `tabindex` of the element that holds focus (Chromium recalculates the document's style and layout on the spot when that happens, to check that the element can still take focus), and none reads layout after a write, so every style recalculation a key forces comes from its one `focus()` call (which recomputes style to check that the element can take focus).
+  When the destination is not rendered yet, focus is still on the origin as the commit starts: the destination renders in that commit, registers and takes focus, and the commit's layout effect then settles the origin, which keeps the Tab stop until then.
+  The commit renders the destination's and the origin's row frames, the view and the host component that owns the controlled selection (the List's `selectedReportHubId`, the DetailList's `selectedItemId`), and `VirtualScroll` only when the key scrolled. Report rows, card bodies and the row renderer do not render, and no context value changes per key.
+  A row that the commit brings into the rendered window outside the rows the key shows — the rows of the viewport after the scroll, plus one on each side, computed from the same row heights `VirtualScroll` uses (overscan rows, in other words) — mounts its row element alone, with an empty surface that fills its slot and `aria-busy="true"` (a DetailList row without its name and description references, whose elements do not exist yet), and renders its body in a transition right after the commit; a held row that the next key's shown rows reach renders its body inside that key's commit.
+  While held, the row fills the box `VirtualScroll` gives it (the List's slot; the DetailList's measured or estimated height), so holding moves neither the other rows nor the scroll anchor.
+- **The row that owns focus keeps it.** Each view has at most one focus owner, the row it gives focus back to. One rule decides it, a pure transition over these events (`nextFocusOwner` in `src/client/keyboard/focus-ownership.ts`; the view only translates DOM events into them): outside the list a pointer press ends ownership, and inside the list only focus transitions change it.
+
+  | Event | Focus owner after it |
+  | --- | --- |
+  | Focus enters an element of a row | That row |
+  | Focus enters an element of the list outside every row | None |
+  | Focus moves to an element outside the list (the resize handle and the side pane included) | None |
+  | Focus goes nowhere (`body`): the focused element was removed or scrolled out of the rendered window, the window lost focus, or a press inside the list landed on something that does not take focus | Unchanged: giving focus back is the owner's job |
+  | A pointer press outside the list, anywhere in the list's document, also while focus is already nowhere | None |
+  | A pointer press inside the list (a gutter, the focused card or row, another row) | Unchanged; a press that moves focus into a row changes the owner through that focus |
+  | The list changes and the owner's report is still listed | Unchanged |
+  | The list changes and the owner's report is gone (a delete, an SSE removal, a stale removal) | The report now at the owner's index (clamped to the new length), which takes focus and becomes the Tab stop; none in an empty list |
+  | The selected report is deleted from the side pane or the mobile overlay | The report now at the deleted report's index, which takes focus and becomes the Tab stop |
+
+  Wheel and touch scrolling change nothing. While a row owns focus and its focus target is replaced (the List frame ⇄ card while loading, a control that disappears, the DetailList body turning into an error, loading or edit form and back), remounted, or scrolled back into the rendered window while focus is nowhere (`body`), the row's registered target takes focus again; focus left on a List row frame moves to the card's primary button when the card arrives.
+  Focus is only ever taken from nowhere: focus that the user put elsewhere is never moved.
+- **Keyboard focus is revealed**: when an element inside a row receives keyboard focus (`:focus-visible`), the view scrolls the row frame into the visible area by the nearer edge — or, for a row taller than the viewport, the focused element with 8 px around it. Focus from a pointer never scrolls.
+- **Keyboard-focus attribute**: while keyboard focus is inside a view, the view root carries `data-daily-report-keyboard-focus` (the List's `[data-testid="daily-report-root"]`, the DetailList's scroll container). Every `focusin` and `keydown` inside the view sets it from the focused element (`:focus-visible`; a key press can turn pointer focus into keyboard focus without moving it), and `pointerdown` inside the view or focus leaving it removes it.
+  It is a plain DOM attribute toggled with `toggleAttribute`, so arrow keys moving between rows never rewrite it and nothing re-renders. The floating tap-scroll circle hides while it is present, because the circle is drawn over the rows.
+- **Pointer selection**: in the List the card's primary `<button>` selects on `click` (a pointer click, Enter or Space; the click that ends a drag is swallowed by the scroll pane), and ★ / 既読 run only their own action. In the DetailList a click on a row selects it without scrolling, except clicks on controls inside the row (`button`, `a[href]`, `input`, `textarea`, `select`, `label`, `[role="button"]`, `contenteditable`). Without `onSelectItem` the DetailList handles neither clicks nor keys.
+- **Host selections and list changes**: when the host changes the selection, the selection ring follows it and the DetailList scrolls that row to the top (when the selected report is not in the list yet, as soon as it arrives); focus does not move.
+  A change of the list alone (SSE inserts and deletes, a stale removal) keeps what is on screen in place. Rows are keyed by report id in both views, and both views anchor their scroll position on a report, the way CSS scroll anchoring does: each time the view reports its visible range, it records the first visible report and how many px of it are hidden above the viewport, and when the list changes it finds that report by id and restores the same offset with one scroll, in a layout effect before paint (only when that report or a row of the visible window changed).
+  An insert or a delete before or inside the rendered window therefore leaves the first visible report — and the focus inside the rows — where it was. At the start of the list (scroll position 0) no anchor is kept, so reports that arrive at the top are shown;
+  a pending selection reveal (a DetailList selection waiting for its report) takes precedence over the anchor (a key move needs no precedence: its scroll, its destination's render and the focus all end inside its own commit); and when the anchor report itself is removed, the first remaining report that followed it on screen is shown at its offset.
+- **List side pane**: keys select through `onSelectItem` directly, so on a mobile layout they never open the detail overlay.
+  On the desktop layout the pane follows the selection in a deferred render: its frame (`[data-testid="daily-report-side-pane"]`) takes the new `data-report-id` in the key's own render and carries `aria-busy="true"` until the content catches up, and the content (`data-displayed-report-id`) renders from `useDeferredValue` of the selection, so React draws it when the main thread is free and drops an unfinished catch-up for a newer key.
+  While a held key repeats, the content keeps the report the repeat stream started from and does not render at all (the frame keeps following the selection, with `aria-busy="true"`); it catches up once, when the stream ends.
+  The content is keyed by the displayed report: each change of the displayed report mounts it exactly once, so nothing of one report (its loaded detail, an open editor, its comments, its thumbnails) renders under the next, and coming back to a report mounts its attachments once (one conditional request per loaded thumbnail). The chosen tab (article or relations) belongs to the pane, and to the mobile overlay, and is kept across reports.
+  Auto-read and the article tab's scroll to the top follow the displayed report. Auto-read marks an unread report read once the pane has dwelt on it for 500 ms: on the desktop layout while the pane has caught up with the selection (the displayed report is the selected one and the pane is not `aria-busy`), in the mobile overlay while the overlay is open. The clock stops when the pane stops dwelling (a newer key, a held key's stream, the overlay sliding out)
+  and starts over when it dwells again, so a report that was only selected — never displayed —, passed over with a held key, or opened in the overlay and closed within 500 ms stays unread. A report whose read state the viewer toggled is not marked again while it stays displayed.
+  The mobile overlay shows the report it opened, so its pane carries the same `data-displayed-report-id` and no `aria-busy`.
+  The article tab scrolls to its end (where the comments are) only after the viewer's own comment has been posted; a comment that arrives over SSE, from another user or another tab, never moves what the viewer is reading.
+- **Screen readers**: each list references `labels.listKeyboardHelp` (visually hidden) through `aria-describedby` — the DetailList only when it handles keys (with `onSelectItem`); there is no live region, announcements come from focus.
+  The List card's primary button is named by its content ("YYYY-MM-DD creator"), described first by the row state (`labels.rowState`: read or unread, and starred), then by the markers the card paints and then by its preview, and carries `aria-current="true"` when selected. A DetailList row is named by its report heading (date, author and subject; `aria-labelledby`) and described by the row state and the markers its header paints.
+  The markers are the attachment marker (`<labels.attachments>: <count>`) and the source badge (its full `name` when the configuration gives one, otherwise its label); a description references only the markers that are painted. A row without content (loading, failed, missing, editing) is named by its ISO business date, with `aria-busy="true"` while loading. At most one element per view carries `aria-current`. ★, 既読, 編集 and 削除 carry `aria-label` equal to their `title` and no `aria-pressed`.
+- **Document structure**: every report has a heading at `config.headingLevel` (an integer from 2 to 5, default 3; pick the level that continues the host page's outline). A DetailList card starts with a visually hidden heading `<date> <author> <subject>`, which names the row.
+  The side pane and the mobile overlay start with two label / value pairs: `labels.businessDate`, whose value is the report heading (the business date alone), and `labels.author` with the author's name; each label and each value is read once, and the source badge sits beside the pair, outside it. The overlay names its dialog by the heading and the author's value together (`<date> <author>`, the name of the List card).
+  The sections inside a report — customer, subject, content, attendees and comments in the DetailList card; content and comments in the side pane; attachments in both — are headings one level lower.
+  Every label and its value is a pair of its own (`dt` / `dd` inside a `dl`, one `MetadataField` primitive), and no value repeats its label as text (no `区分: 日報`): the DetailList metadata column (author, created at, updated by, updated at, business date, and the visit time, the category and the creation category, each when present) and the side pane's subject, customer and visit time; both attachment lists are named by their section heading.
+  The DetailList header's chips are one `dl` too: ID, business date, author, visit time, updated at, and the category and the creation category when present, each label once, with the dates as `<time datetime>`; the header's markers and buttons sit outside the list.
+  Both tab lists are named by what they switch (`aria-label`): the view-mode tabs by `labels.viewTabList`, the side pane's tabs by `labels.reportTabList` (the report heading names only the business date, which reports of the same day share).
+- **Editing**: on the viewer's own reports, an Edit button (`labels.edit`, `data-detail-edit-button`, a pencil icon) stands before Delete in the DetailList header and in the side pane's action row. It is the keyboard way into the editor; a double click is the pointer shortcut. Entering the editor this way moves focus to its title field, and Cancel or a successful Publish returns focus to the Edit button (when the button is not rendered, the DetailList row takes focus itself and the side pane focuses its report heading).
+  A draft that opens in the editor by itself does not move focus. The editor is a real `<form>` whose submission is cancelled: Save, Publish and Cancel are `type="button"`, and an implicit submission (Enter in the title) or a `requestSubmit()` neither navigates nor saves nor publishes, so what was typed stays. As an input region the form keeps the list keys out (above).
+- **Deleting a comment**: the trash button of the viewer's own comment is a disclosure (`aria-expanded`; while open, `aria-controls` names the confirmation pill it shows under itself). The confirmation has no time limit (WCAG 2.2.1): it stays open until it is confirmed or cancelled — by pressing the trash button again, by Escape (the comment list takes it before the mobile overlay while the confirmation is open; an Escape that belongs to an IME composition is left alone), by focus leaving the trash button and the confirmation, or by a pointer press outside them.
+  A cancel by the trash button or by Escape returns focus to the trash button when focus was on the confirmation.
+  Confirming moves focus before the comment is hidden: to the next remaining trash button, else the previous one, else the comment section's heading (`tabIndex=-1`) — the same in the side pane, the mobile overlay and the DetailList row — so focus never falls to `body`.
+- **Mobile detail overlay** (List, single-column layout): the platform's modal dialog, a `<dialog data-daily-report-mobile-overlay>` (implicit `dialog` role, no `aria-modal`) opened with `showModal()`. It is drawn in the top layer, above every host `z-index`, and everything outside it is inert while it is open, host chrome included: no focus, no pointer, nothing in the accessibility tree.
+  It is named by the report heading at its top and the author's value under it (`aria-labelledby` lists both: `<date> <author>`). That heading (`tabIndex=-1`) is the dialog's first focusable descendant, so `showModal()`'s own focusing steps move focus to it in the same commit (the overlay focuses it explicitly as well). Tab and Shift+Tab wrap inside it (its stops are counted on every press by the model of **Leaving the list**;
+  on Shift+Tab the container of a roving-focus widget around the origin, such as the tabs' `tablist`, is not counted before it, because real Shift+Tab leaves such a widget without stopping at it), and Escape closes it unless the key belongs to an IME composition.
+  Every close request goes through the overlay's own close path, which also pops the history entry the overlay pushed: the platform's `cancel` (an Escape the overlay's key handling did not take, Android's back gesture) is default-prevented and routed there, except one caused within 50 ms by an Escape the overlay declined during an IME composition; when the platform closes the dialog by itself (a `cancel` the page is not allowed to stop), the close path runs too, and the dialog opens modally again when the close is refused.
+  Closing it by any means (close button, Escape, backdrop, browser back, a switch to the desktop layout) first blurs the focus inside the dialog, then ends the modal state with `close()` (the platform returns focus, without scrolling, to the element that had it when the dialog opened, when that element is still in the document), and then the view hands focus to the report's card with `preventScroll`, the list scrolling only when that row is not fully visible.
+  The dialog is never opened again to show the slide-out: it stays rendered while closed (its layout does not depend on the `open` attribute) and `inert` — no focus, no pointer, nothing in the accessibility tree — until it has slid out, and the row cursor counts focus left inside it as focus that is nowhere. Opening the overlay again during the slide-out shows the same dialog modally again.
+  The dialog itself takes focus (`tabIndex=-1`), so pressing a non-focusable part of it never drops focus to `body`. The backdrop is a decorative layer (`data-daily-report-overlay-backdrop`, `aria-hidden`, without a role or a name, not focusable): pressing it closes the overlay, while keyboard and assistive-technology users close it with Escape or the close button. Its transitions run only under `prefers-reduced-motion: no-preference`.
+- **Iframes and shadow roots**: the views never read the global `document`; focus checks, the handoff, the body scroll lock and the overlay use the view's own document or shadow root, the Tab-stop search walks open shadow roots, and script-driven scrolling reads the reduced-motion preference of the element's own window.
+- `VirtualScroll`'s own `enableKeyboardNavigation` stays `false`; the keys are handled by the package.
+
+### Selection and focus appearance
+
+Selection and keyboard focus are two separate channels, identical in both views, so "selected and focused" never looks like "focused":
+
+| State | Channel | Geometry | Light | Dark | Forced colours |
+| --- | --- | --- | --- | --- | --- |
+| Selected | box-shadow ring; the surface paints no shadow outside it | 2 px, 0–2 px outside the surface | blue-500 | blue-500 | 2 px `Highlight` outline of the row frame in the ring's band (below) |
+| Keyboard focus on a row or card | outline | 2 px at offset 4 (4–6 px outside) | blue-600 | blue-400 | kept (system colour) |
+| Keyboard focus on a control or link | outline | 2 px at offset 2 | blue-600 | blue-400 | kept |
+| Pointer focus | none | — | — | — | — |
+| Hover (cards) | blue-300 border, `shadow-lg` (a selected card paints no shadow), 2 px lift (motion-safe) | — | — | — | — |
+
+The selected surface sets the shadow colour to transparent (`shadow-transparent`; the selection rules are the only ones that write a shadow colour), and every shadow size the surface can take — the resting `shadow-sm`, the hover `shadow-lg` and the mid-scroll reset `[[data-daily-report-scrolling]_&]:hover:shadow-sm`, whose specificity (0,3,0) beats the selection rules' (0,2,0) — reads its colour from that one variable (`--tw-shadow-color`).
+Whichever size rule wins the cascade, a selected surface therefore paints nothing outside its ring, at rest, hovered or mid-scroll, and the 2 px separation band below the ring is page colour like the other three edges (any shadow there tints the band: the resting `shadow-sm` shifts its relative luminance by 0.026 in the light theme, and a `shadow-md` brings the ring down to 3.12:1 against it).
+
+- **Row gutter G = 8 px** on all four sides of both row frames: ring 2 + separation 2 + outline 2 + hover lift 2. Every term is a CSS pixel quantity and is written in px (`p-[8px]`, the lift `-translate-y-[2px]`), because the ring and the outline do not scale with the root font size and a `rem` term would break the sum at any root other than 16 px; the lengths built on G — the focus reach, the toolbar insets, the frame radius — are px too. A row aligned to either edge of the viewport while hovered, selected and focused is therefore never clipped, at any root font size;
+  a DetailList row is its measured body plus 2G = 16.
+- **List slot P**: the List card's content is sized in rem, so the slot follows the page's root font size R: P(R) = 2G + 2 × (1 + 15) (the card's border and padding) + 4 (spare) + 6.75R = 52 px + 6.75 rem, rounded up to a whole CSS pixel (`listRowSlotHeight`), so every row top stays on a whole pixel. R is read from the root element's computed style and read again whenever a hidden 1 rem probe inside the List (`data-daily-report-root-font-size-probe`) changes size, and the List renders its `VirtualScroll` only once P is known (measured before the first paint).
+  That one value sizes the row frames, `VirtualScroll`'s rows and the keyboard's row geometry, and when it changes the List keeps the first visible row in place by rescaling the scroll position. At the default 16 px root P = 160, the value of `DEFAULT_ITEM_HEIGHT` (exported as P(16); the List itself never reads it): the card is P − 2G = 144 px, cards are 16 px apart and an edge-aligned card sits exactly 8 px from the edge.
+- **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 too narrow for both (a phone with a pinned host menu), the action row wraps under the button instead of squeezing it to nothing, and the card clips the preview lines that no longer fit.
+  The content of a full card is 6.75 rem: the pills' line 1.5 rem + 0.5 + three one-line preview paragraphs of 1.25 rem, 0.5 rem apart (24 + 8 + 3 × 20 + 2 × 8 = 108 px at a 16 px root), inside a 1 + 15 inset at the top and the bottom (the inset counts the border, below), so 1 + 15 + 6.75R + 15 + 1 ≤ P − 2G with at least 4 px to spare at every root font size (140 ≤ 144 at 16 px).
+- **Forced colours**: the ring (a box shadow) disappears, so the row frame draws the selection itself: a 2 px solid `Highlight` outline at offset −8 (−G), which puts the line in the ring's band, 0–2 px outside the surface. The frame's corner radius is the surface's radius plus G (`calc(var(--radius-2xl) + 8px)`, 24 at a 16 px root), so the line is concentric with the surface at every root font size.
+  A DetailList row and a List row without a card read their own `aria-current`; a List row with a card reads its card's primary button (`:has(> [data-daily-report-card] > [aria-current=true])`). The selected row differs by shape as well as by colour (WCAG 1.4.1); the surface border stays 1 px in every state, and the focus outline (4–6 px outside) sits beside the selection line without touching it.
+- **State comes from the row itself**: a row frame styles its surface — the direct child that carries `data-daily-report-row-surface` in every load state — from its own `aria-current` / `:focus-visible`, and the List card surface styles itself from its direct-child primary button (`:has(> …)`). Conditions on an ancestor read only the attributes the package writes itself (`data-daily-report-scrolling`, `data-daily-report-keyboard-focus`), so an ancestor that carries shared attributes such as `aria-current` never lights up a row.
+- **A key press restyles only what paints the change**: every selector that depends on another element's state ends in the styled element's own class or attribute, and `:has()` sits only on the styled element itself. A featureless subject (`*:`, `group-*`) or an ancestor's `:has(:focus-visible)` would make the browser restyle whole rows or the whole view on each key; `src/client/ui/tailwind-selector-scope.spec.ts` compiles the package's classes and fails on either form.
+- **Containment keeps a row's work inside the row**: each List row frame is `contain: size layout style` (its height is the fixed slot) and each DetailList row frame `contain: layout style` (its height follows its content), so a change inside one row never lays out or restyles another. Neither contains paint, because the hover `shadow-lg` of an unselected surface (22 px below, 12 px to the sides) reaches beyond the 8 px gutter G that paint containment would clip (the resting `shadow-sm`, 4 px below, stays inside G; a selected surface paints no shadow).
+  Both side-pane tab panels (article and relations) are one scroll box, `contain: strict`: its size comes from the pane's column and, as a scroll container, it already clips, so its content never restyles or repaints the pane around it and cannot change the panel's size.
+  Neither the panel nor a DetailList row frame is a relayout boundary in Chromium (the panel is a flex item, and the row frame has no size containment), so a layout inside one still starts at the document root and walks the dirty chain of its ancestors; the tile frames inside them are boundaries of their own whose own style never changes, so an image's size arriving on load and the waiting pulse starting or stopping lay out inside the frame alone (**Frame** in [Attachment display](#attachment-display)).
+  The panel reserves its scroll bar's width whatever the content's height (`scrollbar-gutter: stable`), so the width its content gets — and with it the attachment grid's tracks — never depends on whether the article overflows, and it keeps the focus reach (below) inside its clipping edges.
+  The tokens are `LIST_ROW_CONTAINMENT_CLASS_NAME`, `DETAIL_ROW_CONTAINMENT_CLASS_NAME` and `SIDE_PANE_ARTICLE_CONTAINMENT_CLASS_NAME`; `src/client/ui/row-containment.spec.ts` compiles them and measures the two shadows against G.
+  Outside the rows, the side pane's tab panels are the package's own (`role="tabpanel"`, named by their trigger, hidden and empty while not selected) and read no computed style when they mount, and the scroll bar's business-day bubble reads its date and wheel state from a store of its own (`useSyncExternalStore`), so a change of the visible range or a wheel re-renders only the bubble, never the view or `VirtualScroll`.
+- **Focus indicators are the package's own**: every focus indicator the package draws is one of the outlines above, including those of its tabs, buttons, switches, inputs and text areas (`src/client/ui`); none uses the host's `--ring` (measured at 2.43:1 in light and 1.22:1 in dark against the tab list), and no element that carries a focus indicator transitions its colours (in Tailwind 4 `transition-colors` also fades the outline in).
+  No element is scaled: a scaled element scales its outline with it. The switches are drawn at their real size — a 40 × 24 track whose transparent 4 px border (its style declared) frames a 16 px thumb that moves 16 px — so the 24 px track is its own target and its 2 px outline at offset 2 is drawn at full width. `src/client/ui/focus-indicator.spec.ts` checks the shipped CSS, including that no rule scales an element.
+- **Focus reach**: a control's outline reaches 4 px outside it (offset 2 + width 2 = 4 = u; a row's or a card's outline stays inside the gutter G), and every box that clips its content and holds focusable content keeps that reach inside its clipping edges, so no outline is ever cut.
+  The rows' gutter holds it in both views; the side pane's tab panels — the pane's scroll box, also inside the mobile overlay — carry `FOCUS_RING_REACH_CLASS_NAME` (`-mx-[4px] px-[4px] pb-[4px] scroll-p-[4px]`, in px like the outline it holds): the negative inline margin and the equal padding move the clipping edges 4 px out on both sides without moving or narrowing the content, `pb-[4px]` keeps the last control's outline, `scroll-p-[4px]` keeps the outline of a control that Tab scrolls to an edge, and the panel's 8 px top padding holds the top.
+  The view-mode toolbar clips nothing (it wraps instead, below).
+  `src/client/ui/focus-indicator.spec.ts` reads the sources and fails on a class constant that scrolls or contains paint (`overflow-*-auto` / `-scroll`, `contain-strict` / `-content` / `-paint`) without the reach token after following the constants it is built from, and on such a class written outside a constant; its one allowed constant, the containment token, is only ever composed into the side pane's scroll box.
+- **State colours are the package's own too**: the switches and the tabs take every state colour from package tokens (`SWITCH_TRACK_COLOR_CLASS_NAME`, `SWITCH_THUMB_COLOR_CLASS_NAME`, `SEGMENTED_TRIGGER_CLASS_NAME`), never from the host's `--input`, `--primary`, `--background` or `--muted`.
+  The switch track is slate-500 when off and blue-600 when on (dark: slate-400 / blue-400) under a white thumb (dark: slate-950). The selected tab is a white surface (dark: slate-950) with slate-900 text (dark: slate-100) and a 2 px blue-600 bottom line (dark: blue-400), the line being the cue that does not depend on colour; every tab reserves that line as a transparent border, so selecting one moves nothing. Unselected labels are slate-600 (dark: slate-300).
+  In forced colours the thumb is `ButtonText`, the track has a `ButtonText` border and the on track a `Highlight` fill, and the selected line is `Highlight`, so the state survives the colour override. `src/client/ui/ui-state-contrast.spec.ts` computes every pair below from the compiled CSS and the palette (the toolbar surface is slate-100 at 60 % over the slate-50 page, dark slate-900 at 60 % over slate-950):
+
+  | Pair | Light | Dark | Minimum |
+  | --- | --- | --- | --- |
+  | Switch thumb / off track | 4.76 | 7.66 | 3 |
+  | Switch thumb / on track | 5.25 | 7.64 | 3 |
+  | Off track / toolbar surface | 4.43 | 7.18 | 3 |
+  | On track / toolbar surface | 4.88 | 7.16 | 3 |
+  | Selected tab line / selected tab | 5.25 | 7.64 | 3 |
+  | Selected tab line / the side pane's tab track | 4.79 | 5.54 | 3 |
+  | Selected tab line / toolbar surface | 4.88 | 7.16 | 3 |
+  | Unselected label / the side pane's tab track | 6.90 | 9.83 | 4.5 |
+  | Unselected label / toolbar surface | 7.03 | 12.71 | 4.5 |
+  | Selected label / selected tab | 17.83 | 18.40 | 4.5 |
+
+- **Borders declare their style**: every border the package draws sets `border-solid` itself, so a host whose base layer resets the border style of every element (for example `* { border: none }` in Tailwind v4, which turns `--tw-border-style` into `none`) cannot erase it; the hover border and the switch track depend on it.
+  The card-like surfaces — the List card and its skeleton, the desktop side pane, the DetailList card and its skeleton — share one token (`CARD_SURFACE_CLASS_NAME`): a 16 px corner, a 1 px slate-200 / dark slate-700 border, white / dark slate-900 at 70 %, a 16 px inset that counts the border (1 px border + 15 px padding, so the content edge is 16 px from the visible edge and its corner concentric with the surface's) and `shadow-sm`.
+  Two more surfaces have one token each, and no other place writes their classes: the placeholder panel (`PLACEHOLDER_PANEL_CLASS_NAME`: the side pane's selection prompt and its loading and empty tabs; a dashed 1 px border, the 12 px corner of an inner panel and the 12 px inset of every such panel (1 + 11), slate-50 / dark slate-900 at 40 %, slate-600 / dark slate-300 text) and the reading panel (`READING_PANEL_CLASS_NAME`: a report's content in the side pane and in the DetailList card;
+  a 12 px corner and a concentric 12 px inset, slate-50 / dark slate-800 at 60 %, slate-700 / dark slate-200 text on 24 px lines). The scroll bar's business-day bubble is the bordered pill (`BORDERED_PILL_CLASS_NAME`: 24 px tall, its text 12 px in = 1 px border + 11 px padding, the radius of its round ends). `src/client/ui/border-style.spec.ts` checks these rules, a source scan included.
+- **Motion**: everything that moves animates only transform or opacity under `motion-safe` — the hover lift, the thumbnail fade, the loading pulse (on a thumbnail frame's skin, only while the frame may show its load activity, see [Attachment display](#attachment-display)), the switch's thumb, the entrance of the comment delete confirmation and of the error banner, the mobile overlay's slide and its backdrop.
+  The one exception is the mobile overlay layer: its right edge follows the host's pinned-chrome offset (`--aqdr-overlay-right`) over 0.5 s, also under `motion-safe`, in step with the host's own transitions.
+  State surfaces never animate their opacity: a row's surface (`data-daily-report-row-surface`, which paints the selection ring and the focus outline) and its ancestors up to the row frame stay opaque and still: the List's loading skeleton pulses an element inside its surface (the DetailList's skeleton does not pulse), so a selected or focused loading row keeps both indicators at 3:1 or more at the pulse's trough.
+  Selection, focus, colours and borders switch instantly, and with reduced motion nothing moves, script included: the side pane's scroll after the viewer posts a comment is smooth only while the pane's own window does not prefer reduced motion and instant under `prefers-reduced-motion: reduce` (`scrollBehaviorFor` in `src/client/ui/motion.ts` reads the preference on every scroll, because browsers do not apply it to a script's `behavior: "smooth"`).
+  A touch or pen flick starts no glide under `prefers-reduced-motion: reduce` either: `VirtualScroll` continues a flick with a scripted `requestAnimationFrame` glide (for up to 10 s with the views' fast-scroll options), so each view reads the preference of its own window (`useReducedMotion`, which follows a change from the next render and is `false` on the server) and passes inertia options whose start threshold no velocity reaches (`inertiaOptionsFor(true)`); the content still follows the finger 1:1 while it drags and stops when it is released.
+  Both option sets are module constants, so the view's props to `VirtualScroll` stay equal from render to render.
+  While the list scrolls (`data-daily-report-scrolling` on the view's scroll container) the hover lift and its shadow are held still. `src/client/ui/motion-policy.spec.ts` checks the shipped CSS, and scans the sources so that no smooth scroll behaviour, no `animate()` call and no inertia option other than one chosen by `inertiaOptionsFor` is written outside `src/client/ui/motion.ts`.
+- **Spacing**: every spacing the package writes is 4 (within a group), 8 (between parts) or 16 (between items), and every box length it writes sits on the 4 px grid, line boxes included: one-line text such as each List preview line has a 20 px line box (`leading-5`, the preview's lines 8 px apart at a 28 px pitch) and the reading text of the side pane, the DetailList content and the comments a 24 px one (`leading-6`); no line height is proportional to the font size.
+  These are the values at the default 16 px root: lengths written in rem (type, line boxes, the card's content, most spacing) scale with the root font size, while the CSS-pixel quantities of the state indicators — G and the lengths built on it — are written in px and keep their values at every root (see **Row gutter G** and **List slot P**).
+  Two lengths follow the container instead, by design: the attachment grid's fluid track width t = (W − 16 (n − 1)) / n (horizontal) and the tile frame's height derived from it, h(t) = round(2t / 3) (see [Attachment display](#attachment-display)). A surface that holds k rows of tiles is therefore off the 4 px grid by exactly k · h(t) (mod 4), which the app's visual contract asserts.
+  The frame height is not snapped to 4 px: snapping moves the frame's shape more than 0.01 away from 3 : 2 (196 → 132 gives |t / h − 3 / 2| = 0.0152, 171 → 116 gives 0.026) and letterboxes a 3 : 2 image, which fills an unsnapped frame exactly.
+  A bordered box counts its border in its inset, so that its content edge sits on the grid measured from the visible edge: border + padding is on the ladder — 16 for the card surfaces, the error panel, the sides of the error banner and the mobile overlay's close button (1 + 15), 8 for the form fields, the comment input and the top and bottom of the error banner (1 + 7), 4 for the bordered tab bar, the development box and the top and bottom of the text input (1 + 3) — or equals a 12 px corner.
+  **The 12 px tier**: every panel with a 12 px corner has one inset, 12, equal to its corner, so its content box's corner is concentric with the panel's — the reading panel, the DetailList metadata column and the DetailList skeleton's inner panel (`p-3`, no border), the placeholder panel, a posted comment and the bordered pill (1 + 11); a 24 px pill has the same 12 px padding at its round ends. The tab bars are not in that tier: their 4 px inset makes them concentric with their 8 px tabs (12 − 4 = 8).
+  The only other exception is the visually hidden text. `src/client/ui/spacing-ladder.spec.ts` checks every class the package writes, that every bordered box's border + padding is on the ladder or equals its corner, and that every 12 px-corner panel's inset is 12.
+- **Side pane** (List, desktop layout): the panel group fills the view's root, and the list and the side-pane panels both take its height ([View height](#view-height-host-layout)), so a long report scrolls only inside the pane's article tab and never lengthens the page. The pane sits G inside its panel on all four sides, so its top and bottom edges line up with the first and last cards, and its bottom edge sits exactly G above the page's bottom edge, as far as the toolbar is above the first surface.
+- **Tab bars are one segmented control**: the side pane's tabs and the view-mode toolbar share one geometry. The bar has a 12 px corner (`rounded-xl`) and a total inset of 4 px that counts its border (4 px padding without a border, `SEGMENTED_LIST_CLASS_NAME`; 1 px border + 3 px padding with one, `SEGMENTED_BORDERED_LIST_CLASS_NAME`), the same at the top and at the sides.
+  The tabs are 24 px tall with 12 px labels and an 8 px corner (`rounded-lg`), so both bars are 4 + 24 + 4 = 32 px tall and every tab is concentric with its bar: 12 − 4 = 8. Because xl − lg = 4 equals the inset both in Tailwind's scale and in a host `--radius` scale (lg = `--radius`, xl = `--radius` + 4 px), the pair stays concentric for any host radius; the toolbar's children at its end corners (the create button, the development box) are `rounded-lg` too.
+- **View-mode toolbar** (`DailyReportResolvedContent`, above every view): its start edge is inset by G and lines up with the cards; its end edge lines up with the active view's content: G in the desktop List, where the side pane ends the row, and G + the scroll-bar width (8 + 8 = 16) in the DetailList and in the single-column List, where the scroll bar ends it. Both insets are written in px (`ml-[8px]`, `mr-[8px]` / `mr-[16px]`), like G and the scroll bar, so they line up at every root font size.
+  It never scrolls sideways and hides nothing: when it is narrower than its one-row width its controls wrap onto a second row, every label kept. It clips nothing, so the tabs' outlines, which reach 4 px outside them into the bar's 4 px inset, are never cut (the **Focus reach** rule above). Its tab list is named by `labels.viewTabList`.
+- **Scroll bars**: both views theme VirtualScroll's scroll bar through its root class (`VIEW_SCROLL_BAR_THEME_CLASS_NAME`): the track is slate-100 / dark slate-900 and the thumb slate-500 (slate-600 / 400 on hover, slate-700 / 300 while dragged), at least 3:1 against the track in both themes (lowest 4.35 / 3.74); the arrow glyphs reach 6.90 / 6.14 in light and 6.78 / 5.56 in dark on their resting and hover backgrounds.
+- **Type and contrast**: no text is smaller than 12 px (`text-xs`); 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` (`TAP_SCROLL_CIRCLE_OPTIONS.className`).
+- **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 every side), so the icons sit on the 4 px grid without depending on a font. In the List card the markers and toggles stand 4 px apart; the header pills and the source badge are 24 px tall like the targets.
+  The star is a regular five-pointed star, outlined when off and filled gold when on (with a darker gold edge in the light theme); read is a check, unread an 8 px dot, edit a pencil, delete a trash can. Every icon state reaches at least 3.59:1 against each background it sits on, the button's hover background included, in both themes; in forced colours the star is drawn in `CanvasText` (off) and `Highlight` (on). The side pane shows them in the order star, read, edit, delete, centred on the first line of the subject.
+  Unread is shown by the dot on the read toggle and by the row state in the description; no surface changes its border or its layout for it (a card's border is the same 1 px in every state).
+  The comment's trash button takes the 16 px icon's place in the 20 px line of the comment header (its 24 px target overhangs by 2 px, so the header keeps its height), turns red while its confirmation waits (at least 3.59:1 on the comment surfaces), and the confirmation pill carries the control focus outline.
+
+### Attachment display
+
+- Attachments with `hasThumbnail: true` are laid out as tiles in a grid; the others as rows. Each group keeps the original order.
+- **Section heading**: the section is headed by `labels.attachments`, a heading one level below the report heading (`config.headingLevel` + 1), and both the grid and the rows list are named by it (`aria-labelledby`).
+- **Grid**: the attachment section is a size container, and the number of columns follows its width W: n(W) = 1 + ⌊(W + 16) / 256⌋ up to 5 (breakpoints at 240, 496, 752 and 1,008 px; 256 = the largest frame width 240 + the 16 px gap).
+  The grid itself is at most 1,264 px wide, the width at which 5 tracks are exactly 240 px, so a track t is never wider than 240 px (t ≤ 240, equal only at the cap) inside any container, however wide, and at a device pixel ratio up to 2 a thumbnail is never upscaled.
+  Each track is t(W) = (W − 16 (n − 1)) / n. For example, at 1280 × 800 and at 1920 × 1080 the DetailList card's content column is W = 1,136 (the rows, beside the 8 px scroll bar) − 2 × 8 (G) − 2 × (1 + 15) (the card's border and padding) − 16 − 240 (the gap and the metadata column) = 832 px, which holds 4 tracks of 196 px.
+  The side pane's grid sits in the pane's scroll box, whose stable scroll-bar gutter g is taken whatever the content's height (the panel's classic scroll-bar width, 10 px for Chromium's thin scroll bar on Linux; 0 for overlay scroll bars), and whose focus reach (`-mx-[4px] px-[4px]`) leaves the content's width unchanged. In a 1,144 px content column with the List panel at its default 360 px the pane's content is 1,144 − 360 − 2 × 8 (the detail panel's G) − 2 × (1 + 15) (the pane's border and padding) = 736 px, so W = 736 − g:
+  n = 3 at any scroll-bar width (W stays between 496 and 752), with t = (736 − 32) / 3 = 234⅔ for overlay scroll bars and (726 − 32) / 3 = 231⅓ beside a 10 px gutter. The 390 px phone overlay's pane is 358 px wide, W = 358 − g: 2 tracks of 171 px (overlay scroll bars) or of 166 px (a 10 px gutter).
+  Every native scroll container that holds a grid reserves its scroll-bar gutter (the side pane's scroll box; the views' rows sit beside `VirtualScroll`'s own scroll bar of fixed width), so a grid's track width never depends on whether its container overflows.
+  Every length of the grid — the breakpoints, the cap and the gap — is written in px, because the bounds are CSS-pixel quantities: in rem they would grow with the root font size (a 20 px root would make the tracks 300 px wide, upscaled 1.25× at a device pixel ratio of 2).
+- **Tile**: one link to the original wraps the thumbnail frame and the file name; below it one line holds the size and the download link. The frame is decorative (`aria-hidden="true"`, no link of its own), so the tile link is named by the file name and a tile has two Tab stops (the preview, then the download). The download link has a 24 px hit area, and its accessible name is the download label followed by the file name.
+- **File name**: a long name is shortened in its stem and keeps its extension visible, on one line. In a tile grid the name is fitted exactly to the track: the longest start of the stem that still fits, an ellipsis that touches the extension, then the extension, drawn as one run clipped to the track (so the ellipsis never floats a glyph's width away from the extension, and a sub-pixel misfit is clipped instead of adding a second ellipsis).
+  The extension is kept whole up to half the track; a longer one keeps the start that fits in half the track plus an ellipsis. The names are cut between code points of the NFC-normalized name, not between graphemes, so a combining sequence or a joined emoji at the cut can be split (`Intl.Segmenter` is above the browser floor).
+  One `ResizeObserver` per document watches every grid in it (created from the document's own window, disconnected when its last grid stops) and supplies the track width, computed from the grid's content width with the column formula above, not by measuring tiles.
+  A notification only reads its records: it keeps each grid's track width and asks for one animation frame when a track width differs from the one last handed out. It never writes the DOM, never commits and never reads layout, so nothing done during a delivery can resize an element that any observer watches — the grid, or a virtual-scroll row around it — and the browser never reports a ResizeObserver loop.
+  In that frame, before its style and layout, every grid whose track width changed receives it and re-fits its names, all in one `flushSync` however many grids changed. A notification with an unchanged track width (a height-only change, or a new width with the same track, such as 150 px in one column and 316 px in two) or a width of 0 (an ancestor with `display: none`) hands out nothing, a width that changes back before the frame cancels its own hand-out, and a grid hidden and shown again at the same width does not re-render.
+  The frames never wait for this: CSS sizes them in the layout that sizes the tracks (**Frame**, below). Only the names do, so a grid's first frame draws its long names with the CSS truncation described below, and the next frame draws them fitted.
+  The text is measured with one canvas `measureText` per document in the names' computed font (no forced layout), with one measuring function per font string, so a fit whose width and measure are unchanged keeps its identity and no name re-renders. One `loadingdone` listener per document (on `document.fonts`, added after the first fit) re-fits only the grids whose names a loaded face can draw — the face's family is one of the names' families and its `unicode-range` covers a character of a name, of its NFC form or the ellipsis (an unreadable range counts as covering)
+  — after dropping that font's measure, since the glyph widths change while the font string stays the same; other font loads re-render nothing.
+  Outside a grid (the rows of non-image attachments) and until the grid's width is known, the name truncates with CSS: the stem ellipsizes and the extension, kept up to half the width, follows it.
+  The visible name is hidden from assistive technology either way, and a visually hidden copy of the whole name gives each link one unbroken name (no space before the extension); `title` holds the whole name too.
+- **Tab order inside list rows**: the attachment links follow the row rule of [Keyboard, focus and selection](#keyboard-focus-and-selection-list--detaillist): inside a DetailList row they are Tab stops only in the view's Tab-stop row (`tabIndex=-1` in every other row); in the side pane and the mobile overlay they keep their natural order.
+- **Marker**: the List card and the DetailList header show `DailyReportAttachmentIndicator` when a report has attachments: a 24 px tall box without padding or radius (its first ink starts at the content edge) holding a 16 px paperclip icon and, from 2 attachments on, the count in 12 px type on a 16 px line; it is named `<labels.attachments>: <count>` (`role="img"`).
+  Its required `id` prop lands on that `role="img"` element, so a row's description can reference the marker (pass an id unique in the document, for example from `useId()`); with no attachment nothing is rendered, and the description leaves it out.
+- **Frame**: as wide as its track and h(t) = round(2t / 3) whole CSS px tall — the ratio of the variant box (480 × 320 for `tile`), rounded to the nearest pixel. CSS computes it, in the same layout that sizes the track: each frame sits in an inline-size container of its own (an `@container` wrapper exactly as wide as its track, so `100cqi` is t) and has the style `aspect-ratio: 480 / 320; height: round(nearest, 100cqi * 320 / 480, 1px); contain: strict`, the sizes built from the variant box (`ATTACHMENT_TILE_FRAME_STYLE`).
+  No script measures or writes a frame, so its height is right from the first frame, a width change resizes the frames in the layout that changes the width, and every row of a grid draws its frames with the same number of device pixels at an integer device pixel ratio (a fractional height such as 130.33 px would give rows of 130 and 131; at a fractional ratio such as 1.25 or 1.5 the product can still be fractional).
+  The rounding keeps the frame within |t / h − 3 / 2| ≤ 0.75 / h, under 0.01 for every track of a grid with two or more columns (t ≥ 112, h ≥ 75); for the widths above, 196 → 131, 234⅔ → 156, 231⅓ → 154, 171 → 114 and 166 → 111. On Chrome 121–124, which lack `round()`, the height declaration is dropped and the aspect ratio alone gives the fractional 2t / 3 (see the browser floor table).
+  The height depends only on the track and stays the same before, during and after loading and after a failure (virtual-scroll row heights do not shift).
+  The frame paints nothing itself: its only child, the **skin** (`data-testid="daily-report-attachment-thumbnail-skin"`), is an absolutely positioned box that fills it and paints every state — the background, the waiting pulse, the rounded clip, the inner rim — and holds the image or the failure message.
+  The image keeps its aspect ratio inside the skin and is not enlarged; it has no corner radius of its own, and the skin's rounded clip (`overflow: hidden`) alone makes the corners, so an image narrower or shorter than the frame shows no notches of the background where it meets the straight edges (the frame does not clip the corners as well: a second clip at the same edge anti-aliases the corner pixels twice and lightens them).
+  The skin's inner rim turns blue while the tile link (`data-daily-report-attachment-preview`) is hovered, on devices that can hover, and a deeper blue while it is pressed; the background never animates.
+  The frame is a relayout boundary: its strict containment (size, layout, paint, style) changes neither its size, which comes from its own style alone (the container's full width and the height above, or the aspect ratio), nor what is painted, since paint containment clips at the frame's edge and the skin lies inside it; and as a positioned box that is not a flex or grid item (its parent is the block `@container` wrapper), Chromium lays out what changes inside the frame — the image's intrinsic size arriving on load, a style change of the skin — inside the frame alone, not from the document root.
+  Only a change inside the frame stops there: a boundary whose own computed style changes is laid out by its parent, from the document root. So the frame's own style never changes after mount — its classes are its box alone (`relative block w-full`: no variant, no paint, no animation) and its inline style is `ATTACHMENT_TILE_FRAME_STYLE` — and every state is drawn inside it, by the skin and the image, which read the frame's attributes.
+- **`data-thumbnail-state`** on the frame is `pending` (waiting or loading), `loaded` (the image fades in) or `unavailable` (an icon and `labels.attachmentThumbnailUnavailable` inside the skin; the icon reaches 4.35:1 / 5.56:1 and the label 6.90:1 / 5.58:1 in the light / dark theme). The loader's internal phases are not exposed.
+- **The waiting pulse runs only where the tile can be seen**: a `pending` frame's skin pulses (under `prefers-reduced-motion: no-preference`) only while the frame also carries the boolean attribute `data-thumbnail-active`. The frame's load controller decides it (`showActivity`) and the attribute is toggled on the frame element, without a React render, so visibility changes and key moves add no commit; only the skin reads it, so a toggle restyles the skin, never the frame (see **Frame**):
+  an observed frame (waiting for its 250 ms or for a slot, below) carries the attribute exactly while it is visible, and before its first visibility record it carries none; a granted load sets it and stops observing, so the frame keeps it through the load and, after a failed attempt, through the retry wait — both bounded — until observation starts again (the attribute is removed then) or the frame is released (unmount, a URL change, hiding under `<Activity>`). Once the image has loaded the state is no longer `pending`, so a remaining attribute pulses nothing.
+  A frame rendered but never seen — a row in the overscan — therefore never pulses: an animation whose element is not visible is not composited, and Chromium would restyle it on the main thread on every frame of an otherwise idle page. A frame that starts from the page's memory (a loaded URL, a remembered failure) is not observed and is only told to hide its activity when it is released.
+- **The original is never fetched automatically** — only a click on its link fetches it. A thumbnail `<img>` (`fetchpriority="low"`) gets its `src` (the `?thumbnail=tile` URL) only after its frame has been visible for 250 ms (`IntersectionObserver` with the implicit root, so clipping by an ancestor's `overflow` counts) **and** a page-wide load slot is free (2 slots shared by every thumbnail on the page). Attachments passed over by a held arrow key or a fast scroll send no request.
+  Every frame of a document shares one `IntersectionObserver`, created from that document's own window (a frame inside an iframe uses the iframe's) and disconnected when its last frame stops, so rows streaming past add and remove targets instead of creating observers.
+- **Why 2 slots, counted page-wide**: browser connections are shared per origin by every tab of the browser profile, not per page. Under HTTP/1.1 an origin gets 6 connections, which Chromium shares across all tabs of a profile. This screen always holds one for SSE, plus a second one for the ids stream only while it loads the list. With 2 thumbnail slots the screen uses at most 4, which leaves 2 for detail fetches, navigation and the user's downloads (fewer when other tabs of the same origin hold resident streams); thumbnails that filled the rest would stall them.
+  Under HTTP/2 all tabs of a profile share one connection per origin, and the limit is the server's number of concurrent streams. The value stays 2 because it must be safe wherever HTTP/1.1 remains (development, E2E, TLS-inspecting proxies, deployments without HTTP/2), and it also bounds how many server-side renders one screen starts at once. Module state cannot see other tabs, so the page is the widest unit that can be counted; counting per component or per list would multiply the limit when the side pane and several DetailList cards show thumbnails at once.
+- A frame waiting for a slot keeps being observed: if it leaves view it gives up its place in the queue, and when it comes back it waits the 250 ms again before queuing.
+- A load ends on `load`, on `error`, or after 75 s without either, counted from the moment the slot was granted. 75 s is the sum of the server's time budget, which bounds a request from the generation gate onward, so the client does not give up on a response the server may still produce once the request has reached the gate; authentication and authorization come before the gate and their time is taken out of the same 75 s. The slot is returned then, and a timed-out load has its `src` removed first.
+- A failed or timed-out load is retried once, 5 s later, through the same visible-settle-slot path (an `<img>` cannot see the status code, so a transient 503 / 502 looks the same as a permanent failure). Only when the retry also fails does the frame become `unavailable`.
+  The 5 s and the 60 s below are the server's own timing, read by both sides from one shared module (`src/shared/attachment-delivery-timing.ts`) because an `<img>` cannot follow a `Retry-After` it receives: 5 s is the `Retry-After` of the server's overload 503, and 60 s is the window of the per-minute rate buckets, the `Retry-After` of their 429.
+- **Page-wide progress**: the page remembers up to 1,024 thumbnail URLs (the least recently used is forgotten first). A URL that loaded before shows its image in the first render of a remounted frame, with no observation, slot or timer — for example after the arrow keys moved away from a report and back.
+  Because thumbnails are `private, no-cache`, the browser revalidates such an image with one conditional request (answered 304 without a body when unchanged, after authorization); the revalidation waits for no settle time and takes no slot, and at most one runs per mounted frame. If it fails, the page forgets that the URL loaded, counts one failed attempt, and the frame goes on with the retry wait.
+  A URL whose attempts are all used up shows `unavailable` at once, without a request, for 60 s after its last failure (one rate-limit window); after that, one fresh attempt starts. A URL between attempts keeps its failure count and its retry time across remounts.
+- **One writer of `src`**: React never renders the image's `src`. A layout effect projects it from the frame's state before paint on every commit (the URL while a load is granted and once it has loaded, none while waiting) and writes the attribute only when it differs, because rewriting the same value makes the browser drop the loaded image and fetch it again.
+- **Unmounting, a URL change and hiding under `<Activity>`** release everything the frame holds: observation, the settle wait, the slot (a waiting frame leaves the queue), the deadline and the retry wait. An unfinished load also has its `src` attribute removed, so the browser aborts it: a granted load without `load` or `error` yet, and a loaded URL's revalidation before its `load` — frames that only scroll past leave no request behind. A granted first load also returns to `pending`; a revalidation keeps `loaded`.
+  Showing a hidden frame again, and React's StrictMode remounting a frame to check its effects, run the layout effect again on the same element before the load lifecycle restarts, so the projection writes back a `src` that the release removed: a frame hidden before its revalidation's `load` shows `loaded` again at once, without a slot or a timer, and revalidates once more.
+  A frame whose image has fired `load` keeps its `src` across any number of hide-and-show cycles and nothing is requested again; a first load aborted by a real unmount never gets its `src` back.
+
+| `data-testid` | Element |
+| --- | --- |
+| `daily-report-attachment-section` | Attachment section (the size container) |
+| `daily-report-attachment-grid` | `<ul>` of tiles (only when at least one attachment has a thumbnail) |
+| `daily-report-attachment-rows` | `<ul>` of rows (only when at least one attachment has no thumbnail) |
+| `daily-report-attachment-item` | One attachment (tile or row), with `data-attachment-state` = `present` / `absent` / `unknown` |
+| `daily-report-attachment-link` | Link to the original: the tile link (wrapping the frame and the name) or a row's name link |
+| `daily-report-attachment-name` | Struck-through name of a missing attachment (no link) |
+| `daily-report-attachment-download` | Download link |
+| `daily-report-attachment-thumbnail-frame` | Thumbnail frame, the relayout boundary whose own style never changes (`aria-hidden`, `data-thumbnail-state`, `data-thumbnail-active` while it may show its load activity) |
+| `daily-report-attachment-thumbnail-skin` | The frame's only child, absolutely positioned over it: the background, the waiting pulse, the rounded clip and the rim, around the image or the failure message |
+| `daily-report-attachment-thumbnail` | Thumbnail `<img>` (inside the skin) |
+| `daily-report-attachment-thumbnail-unavailable` | Failure message inside the skin |
+| `daily-report-attachment-indicator` | Attachment marker of a List card or a DetailList header (`data-attachment-count`) |
+
+### Test hooks
+
+DOM hooks are `data-*` attributes, test ids and ARIA; class names are styling and never selectors.
+
+| Hook | Element |
+| --- | --- |
+| `[data-daily-report-row="<id>"]` | Row frame of both views (`role="listitem"` with `aria-posinset` / `aria-setsize`), in every load state |
+| `[data-daily-report-row-surface]` | Surface of a row frame: 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-card]` | List card surface (present while the card is shown) |
+| `button[data-daily-report-button="<id>"]` | List card primary button (selection, focus target, `aria-current`) |
+| `[role="listitem"][data-daily-report-button="<id>"]` | DetailList row element (also its focus target) |
+| `[data-list-star-button="<id>"]` / `[data-list-read-button="<id>"]` | List card toggles |
+| `[data-detail-star-button="<id>"]` / `[data-detail-read-button="<id>"]` / `[data-detail-edit-button="<id>"]` / `[data-detail-delete-button="<id>"]` | Toggles, edit and delete in the DetailList header and the List side pane (edit and delete on the viewer's own reports only) |
+| `[data-testid="daily-report-side-pane"]` | List side pane: `data-report-id` is the selected report, `data-displayed-report-id` the report its content shows; the desktop pane carries `aria-busy="true"` while the two differ (the overlay's pane shows the report it opened, so they are equal) |
+| `[data-daily-report-keyboard-focus]` | View root while keyboard focus is inside the view (List: `daily-report-root`; DetailList: its scroll container) |
+| `[data-daily-report-scrolling]` | View's scroll container while its list scrolls (until 150 ms after the last scroll event) |
+| `dialog[data-daily-report-mobile-overlay]` | Mobile detail overlay: the `<dialog>` element itself (its implicit role is `dialog`; it carries `open` while open, and stays in the DOM without `open`, `inert`, while it slides out) |
+| `[data-daily-report-overlay-panel]` | The overlay's sliding panel inside the dialog (the report content and the close button) |
+| `[data-daily-report-overlay-backdrop]` | The overlay's backdrop inside the dialog (`aria-hidden`, not focusable; a press on it closes the overlay) |
+| `[data-thumbnail-state]` | Thumbnail frame state (`pending` / `loaded` / `unavailable`) |
+| `[data-thumbnail-active]` | Thumbnail frame that may show its load activity (visible while observed, or a granted load); a `pending` frame's skin pulses only with it |
+| `[data-daily-report-root-font-size-probe]` | Hidden 1 rem probe inside the List's root whose size change re-reads the root font size (`aria-hidden`, fixed, out of the flow) |
+| `[data-daily-report-attachment-preview]` | Tile link that wraps a thumbnail frame (the skin's hover and press rim read it) |
+| `data-testid` | `daily-report-root`, `daily-report-list`, `daily-report-detail-list`, `daily-report-side-pane`, and the attachment ids above |
+
+Only the package writes `data-daily-report-keyboard-focus` and `data-daily-report-scrolling`. Hosts may select on them — in tests, or in CSS to adapt 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.
+
+`[data-testid="daily-report-list"]` and `[data-testid="daily-report-detail-list"]` carry a read-only `__virtualScroll` accessor for end-to-end tests, with the same shape in both views: the current `VirtualScroll` handle plus `findReportIndex(id)`, `getReportItem(index)` and `getReportIds(limit = 20)` over the view's committed list. It only observes: 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`)
 
 Every string the package renders on its own comes from one built-in catalog per **UI chrome
@@ -247,7 +959,7 @@ locale**: English (`"en"`, the default) and Japanese (`"ja"`). Pick the language
 `config.locale` and override single keys with `config.labels`, which are laid over the catalog of
 `locale`:
 
-```tsx
+```tsx illustrative
 <DailyReportPage
     config={{
         locale: "ja",
@@ -257,38 +969,37 @@ locale**: English (`"en"`, the default) and Japanese (`"ja"`). Pick the language
 ```
 
 - **One surface for all wording.** The catalog covers the 7 engine chrome keys of
-  `@aiquants/virtualscroll` plus 81 own keys: field headings, the page title (`title`, passed to
-  `renderHeader` and used as the accessible name of both lists), tabs, buttons, placeholders,
-  `confirm()` / `alert()` texts, stream badges, the load-error screen and the mutation-failure
-  message. The engine part of each catalog is `VIRTUAL_SCROLL_LABEL_CATALOGS[locale]`, reused by
+  `@aiquants/virtualscroll` plus 84 own keys: field headings, the page title (`title`, passed to
+  `renderHeader` and used as the accessible name of both lists), the lists' keyboard help, the row state read to
+  screen readers, tabs, buttons, placeholders, `confirm()` / `alert()` texts, stream badges, the load-error screen
+  and the mutation-failure message. The engine part of each catalog is `VIRTUAL_SCROLL_LABEL_CATALOGS[locale]`, reused by
   value, so the scroll arrows and the "No items" text always speak the same language as the rest.
 - **Forwarded to every embedded `VirtualScroll`.** Both the List and the DetailList pass `locale`
   and the 7 engine keys of the resolved labels to their `VirtualScroll`. The engine label object keeps
   its identity while its values are unchanged, so rebuilding `config.labels` on every render does not
   re-render the memoized list subtree.
-- **Formatter keys.** Nine keys take arguments and are functions: `totalCount(count)`,
+- **Formatter keys.** Ten keys take arguments and are functions: `totalCount(count)`,
   `debounce(milliseconds)`, `streamProgressCount(loaded)`, `streamProgressRatio(loaded, total, percent)`,
   `streamRetrying(loaded)`, `reportLoadFailed(reportHubId)`, `reportSummaryLoadFailed(reportHubId)`,
-  `interviewerWithAffiliation(name, affiliation)` and `operationFailed(operation)` (`operation` is a
+  `interviewerWithAffiliation(name, affiliation)`, `operationFailed(operation)` (`operation` is a
   `DailyReportOperation`: `create` / `update` / `publish` / `delete` / `addComment` / `deleteComment` /
-  `toggleStar` / `toggleRead`). An override of such a key must be a function too.
+  `toggleStar` / `toggleRead`) and `rowState({ isRead, isStarred })`. An override of such a key must be a function too.
 - **Digit grouping follows the UI locale, not the runtime.** The built-in formatters group numbers with
   the BCP 47 tag bound to their locale (`en` → `"en-US"`, `ja` → `"ja-JP"`); a host override receives
   the raw number and formats it itself.
 - **Fail-fast**: an unsupported `locale` (`"EN"`, `"ja-JP"`, `"fr"`, `""`, `null`, ...) throws a
-  `RangeError` at render. So do an unknown `labels` key (including the removed `fieldLabels`
-  container), a string key whose value is not a string with non-whitespace content, and a formatter
-  key whose value is not a function. An `undefined` value keeps the catalog value.
+  `RangeError` at render. So do an unknown `labels` key (a key error that lists the 91 keys), a string
+  key whose value is not a string with non-whitespace content, and a formatter key whose value is not a
+  function. An `undefined` value keeps the catalog value.
 - **`config` has a closed key set**: `apiBasePath`, `ssePath`, `draftLabelName`, `locale`, `labels`,
-  `sourceTypeConfigs`, `renderHeader`, `showDevControls`, `onError`. The removed keys throw a
-  `RangeError` that names the replacement — `config.fieldLabels was removed in 0.21.0; use
-  config.labels (the same 21 keys)` and `config.title was removed in 0.21.0; use config.labels.title`
-  — even when their value is `undefined`. Any other unknown key throws a `RangeError` listing the
-  accepted keys. This runs at render because a config built outside a typed object literal (a
-  `useMemo` result, a variable) skips TypeScript's excess-property check.
+  `sourceTypeConfigs`, `renderHeader`, `showDevControls`, `headingLevel`, `onError`, `onSessionExpired`. Any other
+  own key — also one whose value is `undefined` — throws the key error of **Configuration errors**
+  (`[daily-report] config key must be one of "apiBasePath", …, "onSessionExpired"; got "<key>"`). This runs at
+  render because a config built outside a typed object literal (a `useMemo` result, a variable) skips
+  TypeScript's excess-property check.
 - **`defaultDailyReportClientConfig` is spreadable input.** Its type `DailyReportClientConfigDefaults`
   holds only the locale-independent defaults (`apiBasePath`, `ssePath`, `draftLabelName`,
-  `renderHeader`, `showDevControls`) and it is frozen. It carries no `locale`, `labels` or
+  `renderHeader`, `showDevControls`, `headingLevel`) and it is frozen. It carries no `locale`, `labels` or
   `sourceTypeConfigs`, so `{ ...defaultDailyReportClientConfig, locale: "ja" }` renders Japanese. The
   resolved configuration from `useDailyReportConfig()` is output only: spreading it into `config`
   would pin its labels as overrides.
@@ -298,9 +1009,11 @@ locale**: English (`"en"`, the default) and Japanese (`"ja"`). Pick the language
   without a display name is sent as `""`).
 - **`labels` must be a plain object** (prototype `Object.prototype` or `null`); arrays, class
   instances and objects created with `Object.create(proto)` throw a `RangeError`. Only own properties
-  are read, so a label key inherited from a polluted `Object.prototype` is never applied. Error
-  messages describe the rejected value without throwing (a string as JSON, `null`, otherwise only its
-  `typeof` tag).
+  are read, so a label key inherited from a polluted `Object.prototype` is never applied. Every error
+  follows the package's convention (see **Configuration errors** in [DI ports](#di-ports)): a rejected
+  value names its key (`[daily-report] labels.<key> must be …; got <value>`), a rejected object reads
+  `[daily-report] labels must be a plain object (prototype Object.prototype or null); got array`, an unknown key
+  `[daily-report] labels key must be one of "scrollUp", …; got "<key>"`, and describing the value never throws.
 - **No language negotiation**: the package never reads `navigator.language`; map it to a supported
   value yourself. No `lang` attribute is stamped either — the document language belongs to the host.
 - **Not tied to `locale`**: `draftLabelName` (a label name stored in the database) and
@@ -312,7 +1025,7 @@ locale**: English (`"en"`, the default) and Japanese (`"ja"`). Pick the language
   grouping follows `locale` (`en` → `"en-US"`, `ja` → `"ja-JP"`) and dates stay in ISO form. Packages
   that do format dates (for example `@aiquants/period-slider`) name that separate axis `formatLocale`.
 
-Exported API (`@aiquants/daily-report/client`): `DAILY_REPORT_LABEL_KEYS` (all 88 keys, engine keys
+Exported API (`@aiquants/daily-report/client`): `DAILY_REPORT_LABEL_KEYS` (all 91 keys, the 7 engine keys
 first), `DAILY_REPORT_LABEL_CATALOGS` (the frozen catalogs), `resolveDailyReportLabels(locale, labels)`
 (the effective frozen labels — the catalog object itself when `labels` is `undefined`), the resolved
 `locale` / `labels` on `useDailyReportConfig()`, and the types `DailyReportLocale` (= `VirtualScrollLocale`),
@@ -334,9 +1047,8 @@ first), `DAILY_REPORT_LABEL_CATALOGS` (the frozen catalogs), `resolveDailyReport
 | `createdAt` | created-at heading | Created at | 作成日時 |
 | `updatedAt` | updated-at heading | Updated at | 更新日時 |
 | `updatedBy` | updated-by heading | Updated by | 更新者 |
-| `category` | category chip / `category: value` prefix | Category | 区分 |
-| `categoryInfo` | metadata panel: category block heading | Category | 区分情報 |
-| `creationCategory` | `creationCategory: value` prefix | Creation category | 作成区分 |
+| `category` | DetailList: label of the category chip and of the metadata column's category pair | Category | 区分 |
+| `creationCategory` | DetailList: label of the creation-category chip and of the metadata column's creation-category pair | Creation category | 作成区分 |
 | `customer` | customer heading | Customer | 顧客 |
 | `subject` | subject heading | Subject | 件名 |
 | `content` | content heading | Content | 内容 |
@@ -345,13 +1057,17 @@ first), `DAILY_REPORT_LABEL_CATALOGS` (the frozen catalogs), `resolveDailyReport
 | `attachments` | attachment section heading, attachment marker name | Attachments | 添付ファイル |
 | `attachmentMissing` | note on a missing attachment | File is missing | 実体が見つかりません |
 | `attachmentDownload` | attachment download link | Download | ダウンロード |
+| `attachmentThumbnailUnavailable` | inside a thumbnail frame whose preview failed to load | Preview unavailable | プレビューを表示できません |
 | `tabArticle` | side pane tab | Overview | 概要 |
 | `tabRelations` | side pane tab | Related | 関連 |
+| `reportTabList` | accessible name (`aria-label`) of the side pane's tab list | Report sections | 日報の表示の切り替え |
 | `relationsEmpty` | side pane related tab body | No related view configured yet. | 関連ビューはまだ構成されていません。 |
 | `title` | `renderHeader({ title })`, both lists' `aria-label` | Daily Reports | 日報 |
+| `listKeyboardHelp` | both lists' `aria-describedby`, visually hidden (the DetailList only with `onSelectItem`) | Up and Down arrows: previous or next report. Home and End: first or last report. Page Up and Page Down: move by a page. Enter or Space on a report row: make it current. Control+Home and Control+End: move to the nearest control before or after the list, when there is one. | ↑↓ で前後の日報、Home / End で先頭・末尾、PageUp / PageDown でページ移動、日報の行で Enter または Space を押すと選択、Ctrl+Home / Ctrl+End で一覧の直前・直後の操作部品があればそこへ移ります。 |
 | `tabList` | top-level tab | 📄 List | 📄 一覧 |
 | `tabTree` | top-level tab | 🌳 Tree | 🌳 ツリー |
 | `tabDetailList` | top-level tab | 📋 DetailList | 📋 詳細一覧 |
+| `viewTabList` | accessible name (`aria-label`) of the top-level tab list | Views | 表示の切り替え |
 | `treeComingSoon` | tree tab body | The tree view is coming soon | ツリーは現在準備中です |
 | `totalCountLoading` | header annotation while loading | Total: loading... | 総件数: 読み込み中... |
 | `createReport` | create button | New report | 日報作成 |
@@ -369,7 +1085,7 @@ first), `DAILY_REPORT_LABEL_CATALOGS` (the frozen catalogs), `resolveDailyReport
 | `streamFailed` | stream badge (failed) | Failed to load | 読み込みに失敗しました |
 | `streamRetry` | stream badge retry button | Retry | 再試行 |
 | `streamRevalidating` | stream badge (revalidating) | Refreshing | 最新化中 |
-| `listEmpty` | package empty state under an empty list | No data | データがありません |
+| `listEmpty` | package empty state, laid over the top of an empty list | No data | データがありません |
 | `selectPrompt` | side pane without a selection | Select a report from the list on the left. | 左側の一覧から日報を選択してください。 |
 | `loading` | side pane loading (edit mode) | Loading... | 読み込み中... |
 | `reportNotFound` | list card of a vanished report | Report not found | 日報が見つかりません |
@@ -382,9 +1098,8 @@ first), `DAILY_REPORT_LABEL_CATALOGS` (the frozen catalogs), `resolveDailyReport
 | `markRead` | read toggle (unread) | Mark as read | 既読にする |
 | `markUnread` | read toggle (read) | Mark as unread | 未読にする |
 | `deleteReport` | report delete button | Delete | 削除する |
+| `edit` | edit button of the viewer's own report (`aria-label` / tooltip) | Edit | 編集 |
 | `resizeHandle` | list / detail resize handle `aria-label` | Resize the border between the report list and the detail pane | 日報一覧と詳細ペインの境界のサイズ変更ハンドル |
-| `overlayBackdrop` | mobile overlay backdrop `aria-label` | Tap the background to close | 背景をタップして閉じる |
-| `overlayDialog` | mobile detail dialog `aria-label` | Report details | 日報詳細 |
 | `close` | mobile overlay close button, error banner close `aria-label` | Close | 閉じる |
 | `formTitle` | edit form | Title | タイトル |
 | `formTitlePlaceholder` | edit form | Enter the report title | 日報のタイトルを入力 |
@@ -408,68 +1123,13 @@ first), `DAILY_REPORT_LABEL_CATALOGS` (the frozen catalogs), `resolveDailyReport
 | `reportSummaryLoadFailed` | list card load failure | `(12345)` → Failed to load the summary of report 12,345. | `(12345)` → 日報 12,345 の概要読み込みに失敗しました。 |
 | `interviewerWithAffiliation` | interviewer chip | `("Sato", "Acme")` → Sato (Acme) | `("佐藤", "山田商事")` → 佐藤 (山田商事) |
 | `operationFailed` | error banner / `DailyReportErrorInfo.message` | `("update")` → Failed to save the report. Please try again later. | `("update")` → 日報の保存に失敗しました。時間をおいて再度お試しください。 |
-
-#### Migrating from 0.20.x (breaking changes in 0.21.0)
-
-0.21.0 is a clean cut-over: there are no aliases for the removed names. It needs the peer
-`@aiquants/virtualscroll` 3.7.0 or later (the engine label catalog it reuses).
-
-1. **The default UI language is English.** The Japanese wording that used to be hard-coded in the
-   components (buttons, placeholders, confirmation dialogs, status badges, loading / error screens,
-   the failure banner) now renders in English when `locale` is omitted. A host that relies on the
-   Japanese chrome must opt in with `config.locale: "ja"`. The ja catalog keeps the former Japanese
-   wording except four values aligned with the shared `@aiquants` vocabulary: `treeComingSoon`
-   (`ツリーは現在準備中です`), `resizeHandle` (`日報一覧と詳細ペインの境界のサイズ変更ハンドル`),
-   `unknownUser` (`不明なユーザー`, formerly `"Unknown"` / `不明`) and `interviewerWithAffiliation`
-   (half-width parentheses: `佐藤 (山田商事)`).
-2. **`config.fieldLabels` → `config.labels`** (the same 21 keys). The type `DailyReportFieldLabels`
-   and the value `defaultDailyReportFieldLabels` are removed; use `DailyReportLabels` /
-   `DAILY_REPORT_LABEL_CATALOGS[locale]`. A leftover `fieldLabels` key throws a `RangeError` at
-   render, even inside a `useMemo` config that TypeScript does not flag.
-3. **`config.title` → `config.labels.title`** (en `"Daily Reports"`, ja `"日報"`). It is still what
-   `renderHeader({ title })` receives and the accessible name of both lists. A leftover `title` key
-   throws a `RangeError` at render.
-4. **Adding only `locale: "ja"` replaces your vocabulary with the catalog's.** The ja catalog carries
-   neutral headings (`顧客`, `内容`, `コメント`, `概要`, `関連`, ...). Move the domain wording you used to
-   pass in `fieldLabels` into `labels` in the same change, e.g.
-   `{ locale: "ja", labels: { customer: "顧客・面談先", content: "商談内容", comments: "コメント一覧", tabArticle: "記事", tabRelations: "相関" } }`.
-5. **`locale: "ja"` also translates what used to stay English**: the top-level tabs (`📄 一覧` /
-   `🌳 ツリー` / `📋 詳細一覧`), the page title (`日報`), the load-error badge (`エラー`), the side-pane
-   tabs (`概要` / `関連`), the scroll arrows (`上へスクロール` / `下へスクロール`) and the empty state
-   (`項目がありません`). Keep the English form through `labels`, e.g.
-   `labels: { tabList: "📄 List", tabDetailList: "📋 DetailList" }`.
-6. **Resolved config shape**: `DailyReportClientConfig` (the value of `useDailyReportConfig()`) loses
-   `title` / `fieldLabels`, gains the resolved `locale` / `labels`, and `sourceTypeConfigs` is always
-   present (the built-in default when omitted).
-7. **`defaultDailyReportClientConfig`** is now the frozen, locale-independent input
-   `DailyReportClientConfigDefaults` (`apiBasePath`, `ssePath`, `draftLabelName`, `renderHeader`,
-   `showDevControls`). It no longer has `title`, `fieldLabels` or `sourceTypeConfigs`; read resolved
-   values through `useDailyReportConfig()`.
-8. **Built-in `Internal` badge**: when `sourceTypeConfigs` is omitted, its label is
-   `labels.sourceInternal` — en `"Original"` (formerly always `オリジナル`), ja `"オリジナル"`.
-9. **`DailyReportErrorInfo`**: `operation` is narrowed from `string` to `DailyReportOperation`, and
-   `message` is `labels.operationFailed(operation)` in the chosen locale (English by default).
-10. **`mergeComments(legacyComments, modernComments, currentUserId, unknownAuthorName)`** (root
-    export): the fourth argument is new and required, `currentUserId` is no longer optional (pass
-    `undefined` to keep the server's `isMine`), and a blank or non-string `unknownAuthorName` throws a
-    `RangeError`. A comment without an author name (legacy `name` or relational `userName` that is
-    empty, `null` or missing) gets `unknownAuthorName`; the client passes `labels.unknownUser`.
-11. **Server `addComment`**: the SSE `comment-add` payload sends `userName: ""` (formerly `"Unknown"`)
-    for an author without a display name, like the read paths; the client renders
-    `labels.unknownUser`. Comments with an empty author name show `labels.unknownUser` instead of `-`.
-12. **List side-pane load error** renders `labels.reportLoadFailed(reportHubId)` instead of the
-    exception message (the same text as the DetailList).
-13. **Explicit `undefined`** for `apiBasePath` / `ssePath` / `draftLabelName` / `showDevControls` /
-    `renderHeader` now resolves to the default (it used to override the default with `undefined`).
-
-Unchanged: `draftLabelName` (label data stored in the database) does not follow `locale`, and dates
-keep their ISO form.
+| `rowState` | visually hidden row state, the first description of the List card's primary button and of a DetailList row | `({ isRead: false, isStarred: true })` → Unread, starred | `({ isRead: false, isStarred: true })` → 未読、スター付き |
 
 ### External Source Badge Configuration (`sourceTypeConfigs`)
 
 Display parameters (label names and badge CSS classes) for reports ingested from external sources can be overridden using `sourceTypeConfigs`. This prevents the package from hardcoding specific third-party service names or designs, leaving display customization to the host application.
 
-```tsx
+```tsx illustrative
 sourceTypeConfigs: {
     Internal: {
         label: "Native",
@@ -480,19 +1140,25 @@ sourceTypeConfigs: {
         badgeClassName: "bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400",
     },
     LegacyPortal: {
-        label: "Legacy Portal",
+        label: "LP",
+        name: "Legacy Portal",
         badgeClassName: "bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400",
     },
 }
 ```
 
+- `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.
+  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 primary button and the DetailList row are described by it, so screen reader users hear the name the badge stands for.
+- A report's source type is read from one field only, the loaded report's `DailyReportDetail.sourceType` (the server fills it, with `Internal` for reports the package creates), and each row, the side pane and the mobile overlay resolve its configuration once. That one value draws the badge, decides whether the row's description references it, and decides whether the comment form is shown: `allowComment` when the configuration sets it, otherwise only for `Internal` and for a report without a source type (the form is a display choice; the server decides whether a comment may be posted).
+
 ### Troubleshooting: Hook errors / Multiple React instances (Cannot read properties of null)
 
 If you encounter `TypeError: Cannot read properties of null (reading 'useMemo')` or "Invalid hook call", it means multiple React instances are loaded in memory. This often happens because the bundler/framework (Vite/React Router v7) resolves separate React packages for your application and this dependency (especially when linked via monorepo or npm link).
 
 To fix this, update your consumer application's `vite.config.ts` to deduplicate React:
 
-```typescript
+```typescript illustrative
 import path from "node:path"
 import { defineConfig } from "vite"
 
@@ -524,6 +1190,10 @@ export default defineConfig({
 })
 ```
 
+## Breaking changes and migrations
+
+Every breaking change and its migration is listed per version in `CHANGELOG.md`, which ships with the package.
+
 ## Realtime Architecture
 
 1. Mutation services publish to Redis Stream (`daily-report:sse-stream`) in sequence: `invalidate -> epoch increment -> SSE publish`.
@@ -567,15 +1237,23 @@ Stop signals are **in-band**: the server answers 200 and writes `retry: 86400000
 
 ## API Surface (Summary)
 
-- **server**: `createDailyReportServer` / `createDailyReportService` (`getDailyReportIdsByExternalId` returns `{ items, streamAnchor }`; `readSseStreamAnchor`) / `createDailyReportHandlers` / `DAILY_REPORT_SSE_VISIBILITY_REFRESH_MS` / `DAILY_REPORT_SSE_CATCH_UP_BATCH` / `defineDailyReportSchema` / `DailyReportSseReader` / `SqlResultCache` / `transformJsonArray` / `jsonResponseWithETag` / `generateETag` / `isStreamIdLte`
-- **client**: `DailyReportPage` / `DailyReportResolvedContent` / `DailyReportList` / `DailyReportDetailList` /
-  `DailyReportActionProvider` / `useDailyReportActionContext` (`sseStatus`) / `useDailyReportDetail` /
-  `useDailyReportPrefetch` / `useDailyReportComments` / `useDailyReportSseConnection` (returns
-  `DailyReportSseConnectionStatus`) / `useDailyReportIdsStream` (state carries `streamAnchor`) /
-  `resyncDailyReportIdsStream` / `DailyReportIdsStreamStatus` / `DailyReportIdsStreamClient` (`resync()`) /
-  `DailyReportConfigProvider` / `useDailyReportConfig` / `defaultDailyReportClientConfig` / `resolveDailyReportLabels` /
-  `DAILY_REPORT_LABEL_CATALOGS` / `DAILY_REPORT_LABEL_KEYS` / `createDailyReportClientLoader` /
-  `dailyReportShouldRevalidate`
-- **shared**: `DailyReportItem` / `DailyReportDetail` / `DailyReportUser` / `dailyReportSseMessageSchema` (8 discriminated union types) / `DAILY_REPORT_SSE_TERMINAL_EVENTS` / `DAILY_REPORT_SSE_HEARTBEAT_MS` / `DAILY_REPORT_SSE_CURSOR_PARAM` / `isDailyReportSseStreamId` / `DailyReportSseStreamAnchor` / `normalizeBusinessDateKey` / `mergeComments(legacyComments, modernComments, currentUserId, unknownAuthorName)`
+Every entry exports by name (no `export *`), so a module-internal helper never becomes public by accident. `src/public-surface.spec.ts` pins the runtime and the type names of the three entries below and fails when a public name is missing from this section.
+
+- **shared** (`@aiquants/daily-report`, isomorphic):
+  - Values: `buildDailyReportAttachmentUrl` / `parseDailyReportAttachmentQuery` / `DAILY_REPORT_ATTACHMENT_THUMBNAIL_VARIANTS` / `isDailyReportAttachmentThumbnailVariant` (the attachment URL codec and the variant list), `DAILY_REPORT_SSE_TERMINAL_EVENTS` / `DAILY_REPORT_SSE_HEARTBEAT_MS` / `DAILY_REPORT_SSE_CURSOR_PARAM` / `isDailyReportSseStreamId` (the SSE wire constants),
+    `dailyReportSseMessageSchema` (8 discriminated union types) with its members `connectedMessageSchema` / `reportCreateMessageSchema` / `reportUpdateMessageSchema` / `reportPublishMessageSchema` / `reportDeleteMessageSchema` / `statusUpdateMessageSchema` / `commentAddMessageSchema` / `commentDeleteMessageSchema` and the part schemas `dailyReportDetailSchema` / `dailyReportPostedCommentSchema` / `dailyReportExternalCommentSchema` / `dailyReportInterviewerSchema` / `dailyReportLabelDefSchema`,
+    `isIdsStreamChunkLine`, `normalizeBusinessDateKey`, `mergeComments(legacyComments, modernComments, currentUserId, unknownAuthorName)`.
+  - Types: `DailyReportItem` / `DailyReportDetail` / `DailyReportUser` / `DailyReportInterviewer` / `DailyReportLabelDef` / `DailyReportPostedComment` / `DailyReportExternalComment` / `DailyReportAttachmentSummary`, `DailyReportSseMessage` / `DailyReportSseStreamAnchor` / `DailyReportIdsStreamChunkLine`, `DailyReportAttachmentDeliveryRequest` / `DailyReportAttachmentInvalidQuery` / `DailyReportAttachmentThumbnailVariant` / `DailyReportAttachmentThumbnailBox`.
+- **client** (`@aiquants/daily-report/client`, React):
+  - Components: `DailyReportPage` / `DailyReportResolvedContent` / `DailyReportList` / `DailyReportDetailList` / `DailyReportAttachmentIndicator`, the providers `DailyReportConfigProvider` / `DailyReportActionProvider` / `DailyReportErrorProvider`.
+  - Hooks: `useDailyReportConfig` / `useDailyReportActionContext` (`sseStatus`) / `useDailyReportDetail` / `useDailyReportPrefetch` / `useDailyReportComments` / `useDailyReportSseConnection` (returns `DailyReportSseConnectionStatus`) / `useDailyReportIdsStream` (state carries `streamAnchor`).
+  - The ids stream: `DailyReportIdsStreamClient` (`resync()`) / `DailyReportIdsStreamStatus` / `primeDailyReportIdsStreamSession` / `bootstrapDailyReportIdsStreamSession` / `ensureDailyReportIdsStreamSession` / `resyncDailyReportIdsStream`; the route helpers `createDailyReportClientLoader` / `dailyReportShouldRevalidate`.
+  - Configuration and wording: `defaultDailyReportClientConfig` / `resolveDailyReportLabels` / `DAILY_REPORT_LABEL_CATALOGS` / `DAILY_REPORT_LABEL_KEYS` / `resolveSourceTypeConfig`; the layout values `DEFAULT_ITEM_HEIGHT` (the List slot P at a 16 px root) / `TAP_SCROLL_CIRCLE_OPTIONS`.
+  - Types: `DailyReportClientConfigInput` / `DailyReportClientConfigDefaults` / `SourceTypeConfig` / `DailyReportLocale` / `DailyReportLabels` / `DailyReportLabelOverrides` / `DailyReportOperation` / `DailyReportErrorInfo` / `DailyReportSseConnectionStatus`.
+- **server** (`@aiquants/daily-report/server`, Node.js):
+  - Factories: `createDailyReportServer` / `createDailyReportService` (`getDailyReportIdsByExternalId` returns `{ items, streamAnchor }`; `readSseStreamAnchor`; `attachmentDelivery`) / `createDailyReportHandlers` / `defineDailyReportSchema` / `createEpochStore`, the viewer scope `DailyReportViewerScope`.
+  - Attachments: `createSharpThumbnailRenderer` / `predictSharpThumbnailWorkingSetBytes` / `DAILY_REPORT_SHARP_THUMBNAIL_WORKING_SET_MODEL` / `DAILY_REPORT_SHARP_THUMBNAIL_DECODE_BUDGET_BYTES` / `DAILY_REPORT_ATTACHMENT_THUMBNAIL_OUTPUT_MEDIA_TYPES` / `DAILY_REPORT_ATTACHMENT_THUMBNAIL_MAX_OUTPUT_BYTES`.
+  - SSE and caching: `DailyReportSseReader` / `DAILY_REPORT_SSE_VISIBILITY_REFRESH_MS` / `DAILY_REPORT_SSE_CATCH_UP_BATCH` / `isStreamIdLte` / `SqlResultCache` / `transformJsonArray` / `jsonResponseWithETag` / `generateETag`.
+  - Types: `DailyReportServerConfig` / `DailyReportServiceConfig` / `DailyReportTables` / `DailyReportDb` / `DailyReportAuthenticate` / `DailyReportAuthResult` / `DailyReportIdCodec` / `DailyReportRedisProvider` / `StreamEntry` / `ExternalReportFields`, and for attachments `DailyReportAttachmentDelivery` / `DailyReportReadAttachment` / `DailyReportAttachmentError` / `DailyReportAttachmentFailure` / `DailyReportAttachmentThumbnailRenderer` / `DailyReportAttachmentThumbnail` / `DailyReportAttachmentThumbnailSourceFormat` / `DailyReportAttachmentThumbnailOutputMediaType` / `SharpLike`.
 
 MIT