@aiquants/daily-report 0.20.1 → 0.22.0

package/README.md

@@ -25,7 +25,7 @@ External projects:
 pnpm add @aiquants/daily-report react react-dom react-router drizzle-orm zod
 ```
 
-`react` / `react-dom` / `react-router` / `drizzle-orm` / `zod` are **peer dependencies**. Build / test: `pnpm run build` (tsup → dist) / `pnpm run test` (vitest).
+`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).
 
 ### Tailwind CSS
 
@@ -156,7 +156,7 @@ createDailyReportServer({
 - **How it reaches the service**: the resolved set is wrapped in a `DailyReportViewerScope` and passed as the **first** argument of every gated service method.
   The class is nominal (it holds a private field), so `{ visible: null }`, `{ ...scope, visible: null }` and `new DailyReportViewerScope(...)` are all type errors — the only ways to obtain one are `DailyReportViewerScope.restrictTo(tokens)` — which accepts `readonly string[]` only, so it cannot be handed a nullish value and quietly widen — and `DailyReportViewerScope.unrestricted(auditReason)`.
   Because a bare `null` is not spellable as a visibility value, `grep -rn "DailyReportViewerScope.unrestricted("` enumerates every unfiltered read in a codebase, each carrying a written reason.
-- **Performance**: the port is called once per request on the critical path (cache keys incorporate the resolved set), so keep it fast — cache grants per session/user with a short TTL (≤ 60s). A live SSE connection re-resolves on its existing keep-alive tick (~60s) to bound how long a revoked grant keeps streaming; that call passes `reason: "refresh"` and reuses the connection's original `Request`, so a cache keyed on request identity **must** be bypassed when `reason === "refresh"` or the re-check silently returns the stale set.
+- **Performance**: the port is called once per request on the critical path (cache keys incorporate the resolved set), so keep it fast — cache grants per session/user with a short TTL (≤ 60s). A live SSE connection re-resolves on a dedicated 60 s timer (independent of the heartbeat) to bound how long a revoked grant keeps streaming; that call passes `reason: "refresh"` and reuses the connection's original `Request`, so a cache keyed on request identity **must** be bypassed when `reason === "refresh"` or the re-check silently returns the stale set.
 - **SSE latency**: because a live connection re-resolves periodically, a grant change (in either direction) takes effect for the stream within ~60s. Events dropped before a widening are not replayed; the next read (which re-resolves per request) restores them.
 
 ### Comment visibility
@@ -211,11 +211,13 @@ export default function Route() {
                 user={user}
                 userId={userId}
                 config={{
+                    onSessionExpired: () => navigate(0),    // Required: the host decides the navigation on session expiry
                     renderHeader: ({ title, annotation }) => <YourHeader title={title} annotation={annotation} />,
                     showDevControls: import.meta.env.DEV,   // Toggle SSE subscriptions, etc.
-                    draftLabelName: "Draft",                // Label name for draft states (matches target DB)
-                    fieldLabels: {                          // Card/detail header labels (customizable per key)
-                        businessDate: "Date", content: "Body", comments: "Comments", /* ... override to match app locale */
+                    draftLabelName: "Draft",                // Label name for draft states (matches target DB; not tied to locale)
+                    locale: "en",                           // UI chrome language: "en" (default) | "ja"
+                    labels: {                               // Optional per-key overrides over the catalog of `locale`
+                        title: "Field Reports", content: "Body",
                     },
                     onError: (info) => yourToast(info.message), // Optional: route mutation failures to your own toast
                     // apiBasePath: "/daily_report/api", ssePath: "/sse/daily_report/updates"
@@ -226,6 +228,8 @@ 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.
+
 `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.
 
 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.
@@ -236,10 +240,230 @@ 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).
 
-### Field Labels (`fieldLabels`)
+### Localization (`locale` / `labels`)
+
+Every string the package renders on its own comes from one built-in catalog per **UI chrome
+locale**: English (`"en"`, the default) and Japanese (`"ja"`). Pick the language with
+`config.locale` and override single keys with `config.labels`, which are laid over the catalog of
+`locale`:
+
+```tsx
+<DailyReportPage
+    config={{
+        locale: "ja",
+        labels: { content: "商談内容", comments: "コメント一覧", tabArticle: "記事" },
+    }}
+/>
+```
 
-Card and detail headings (`id` / `businessDate` / `author` / `visitTime` / `createdAt` / `updatedAt` / `updatedBy` / `category` / `categoryInfo` / `creationCategory` / `customer` / `subject` / `content` / `interviewers` / `comments` / `attachments` / `attachmentMissing` / `attachmentDownload` / `tabArticle` / `tabRelations` / `relationsEmpty` — all 21 keys of `DailyReportFieldLabels`) are fully dependency-injected.
-**The package includes neutral English defaults** (`Business date` / `Customer` / `Content`, etc.), and consuming applications override headings via `fieldLabels`. This ensures the package itself carries no domain-specific wording. Partial overrides merge deeply over defaults (`DailyReportConfigProvider` performs a 1-level deep merge).
+- **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
+  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)`,
+  `debounce(milliseconds)`, `streamProgressCount(loaded)`, `streamProgressRatio(loaded, total, percent)`,
+  `streamRetrying(loaded)`, `reportLoadFailed(reportHubId)`, `reportSummaryLoadFailed(reportHubId)`,
+  `interviewerWithAffiliation(name, affiliation)` and `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.
+- **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.
+- **`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.
+- **`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
+  `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.
+- **Unknown authors**: a comment whose author name is unknown — a legacy comment without a name, a
+  relational comment with an empty `userName`, the pending comment of a viewing user without any name
+  or email — shows `labels.unknownUser`. The server never sends a fixed fallback name (an author
+  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).
+- **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
+  `sourceTypeConfigs` (host data). Only the built-in default badge map used when `sourceTypeConfigs`
+  is omitted takes its `Internal` label from `labels.sourceInternal`.
+- **Host notifications**: `config.onError` receives `DailyReportErrorInfo` with the stable
+  `operation` key and `message` = `labels.operationFailed(operation)` in the chosen locale.
+- **`locale` is the only language axis.** This package has no BCP 47 `formatLocale` option: digit
+  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
+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`),
+`DailyReportLabels`, `DailyReportLabelOverrides` and `DailyReportOperation`.
+
+| Key | Where it appears | `en` | `ja` |
+| --- | --- | --- | --- |
+| `scrollUp` | engine: vertical ScrollBar up arrow (`aria-label`) | Scroll up | 上へスクロール |
+| `scrollDown` | engine: vertical ScrollBar down arrow (`aria-label`) | Scroll down | 下へスクロール |
+| `scrollLeft` | engine: horizontal arrow (not rendered by this package) | Scroll left | 左へスクロール |
+| `scrollRight` | engine: horizontal arrow (not rendered by this package) | Scroll right | 右へスクロール |
+| `scrollToTop` | engine: top pill (not enabled by this package) | Top | 先頭へ |
+| `scrollToBottom` | engine: bottom pill (not enabled by this package) | Bottom | 末尾へ |
+| `noItems` | engine: empty list text | No items | 項目がありません |
+| `id` | DetailList card: id chip | ID | ID |
+| `businessDate` | business date heading | Business date | 営業日 |
+| `author` | author heading | Author | 作成者 |
+| `visitTime` | visit time heading | Visit time | 訪問時間 |
+| `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 | 作成区分 |
+| `customer` | customer heading | Customer | 顧客 |
+| `subject` | subject heading | Subject | 件名 |
+| `content` | content heading | Content | 内容 |
+| `interviewers` | interviewer list heading | Attendees | 面談者 |
+| `comments` | comment section heading | Comments | コメント |
+| `attachments` | attachment section heading, attachment marker name | Attachments | 添付ファイル |
+| `attachmentMissing` | note on a missing attachment | File is missing | 実体が見つかりません |
+| `attachmentDownload` | attachment download link | Download | ダウンロード |
+| `tabArticle` | side pane tab | Overview | 概要 |
+| `tabRelations` | side pane tab | Related | 関連 |
+| `relationsEmpty` | side pane related tab body | No related view configured yet. | 関連ビューはまだ構成されていません。 |
+| `title` | `renderHeader({ title })`, both lists' `aria-label` | Daily Reports | 日報 |
+| `tabList` | top-level tab | 📄 List | 📄 一覧 |
+| `tabTree` | top-level tab | 🌳 Tree | 🌳 ツリー |
+| `tabDetailList` | top-level tab | 📋 DetailList | 📋 詳細一覧 |
+| `treeComingSoon` | tree tab body | The tree view is coming soon | ツリーは現在準備中です |
+| `totalCountLoading` | header annotation while loading | Total: loading... | 総件数: 読み込み中... |
+| `createReport` | create button | New report | 日報作成 |
+| `createReportTitle` | create button tooltip | Create a daily report | 日報を作成 |
+| `devControls` | dev toolbox tooltip (`showDevControls`) | Development-only controls | 開発環境限定コントロール |
+| `devSseToggle` | dev toolbox: SSE switch tooltip | Toggle SSE real-time sync | SSE リアルタイム同期切替 |
+| `devReload` | dev toolbox: reload tooltip | Reload data | データ再取得 (リロード) |
+| `devClearCache` | dev toolbox: clear-cache tooltip | Clear the cache and reload | キャッシュ破棄 & 再取得 |
+| `autoRead` | auto-read switch label | Auto-read | 自動既読 |
+| `autoReadTitle` | auto-read switch tooltip | Mark reports as read automatically while viewing them | 日報閲覧時の自動既読処理切替 |
+| `loadErrorBadge` | header annotation on load failure | Error | エラー |
+| `loadError` | load-failure screen | Failed to load the daily reports. | 日報データの読み込みに失敗しました。 |
+| `reload` | load-failure screen button | Reload | 再読み込み |
+| `loadingIds` | loading screen | Loading report IDs... | 日報 ID を読み込み中です... |
+| `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 | データがありません |
+| `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 | 日報が見つかりません |
+| `contentEmpty` | side pane: report without content | No content has been entered. | 内容は登録されていません。 |
+| `contentEmptyPreview` | list card preview: report without content | No content has been entered | 内容は登録されていません |
+| `confirmDelete` | `confirm()` before deleting a report | Are you sure you want to delete this report? | 本当に削除しますか？ |
+| `deleteFailed` | `alert()` after a failed delete | Failed to delete the report | 削除に失敗しました |
+| `starAdd` | star toggle (unstarred) | Add star | スターを付ける |
+| `starRemove` | star toggle (starred) | Remove star | スターを外す |
+| `markRead` | read toggle (unread) | Mark as read | 既読にする |
+| `markUnread` | read toggle (read) | Mark as unread | 未読にする |
+| `deleteReport` | report delete button | Delete | 削除する |
+| `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 | 日報のタイトルを入力 |
+| `formContent` | edit form | Content | 内容 |
+| `formContentPlaceholder` | edit form | Enter the report content | 日報の内容を入力 |
+| `formCancel` | edit form | Cancel | キャンセル |
+| `formSave` | edit form | Save | 保存 |
+| `formPublish` | edit form | Publish | 公開 |
+| `commentPlaceholder` | comment form | Add a comment... | コメントを追加... |
+| `commentSend` | comment form | Send | 送信 |
+| `commentDelete` | comment trash button (`aria-label` / tooltip) | Delete comment | 削除 |
+| `commentDeleteConfirm` | comment delete confirmation | Delete | 削除する |
+| `unknownUser` | author name when none is known (legacy / relational comment without a name, optimistic data of a user without a name) | Unknown | 不明なユーザー |
+| `sourceInternal` | built-in `Internal` badge (only when `sourceTypeConfigs` is omitted) | Original | オリジナル |
+| `totalCount` | header annotation | `(1234)` → Total: 1,234 | `(1234)` → 総件数: 1,234 件 |
+| `debounce` | header annotation | `(300)` → Debounce: 300 ms | `(300)` → デバウンス: 300 ms |
+| `streamProgressCount` | stream badge before the total is known | `(1234)` → Loading 1,234 | `(1234)` → 読み込み中 1,234 件 |
+| `streamProgressRatio` | stream badge once the total is known | `(1234, 5000, 25)` → Loading 1,234 / 5,000 (25%) | `(1234, 5000, 25)` → 読み込み中 1,234 / 5,000 (25%) |
+| `streamRetrying` | stream badge (reconnecting) | `(1234)` → Reconnecting... (1,234 received) | `(1234)` → 再接続中... (1,234 件受信済) |
+| `reportLoadFailed` | detail load failure (side pane, DetailList card) | `(12345)` → Failed to load report 12,345. | `(12345)` → 日報 12,345 の読み込みに失敗しました。 |
+| `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.
 
 ### External Source Badge Configuration (`sourceTypeConfigs`)
 
@@ -304,13 +528,54 @@ export default defineConfig({
 
 1. Mutation services publish to Redis Stream (`daily-report:sse-stream`) in sequence: `invalidate -> epoch increment -> SSE publish`.
 2. `DailyReportSseReader` uses a single blocking `xRead` loop to fan-out events to all SSE connections (eliminating per-connection Redis TCP connections).
-3. `sse.loader` implements catch-up (`xRange`) using `Last-Event-ID` / `lastEventId` and 5-second keep-alive pings. `recipientRawUserId` is filtered server-side and removed before transmission to prevent internal ID leaks.
-4. On the client, `useDailyReportSseConnection` handles exponential backoff reconnects, and the action context correlates optimistic updates with SSE echoes using `clientTempId`.
+3. `sse.loader` is built on `@aiquants/sse/server` (`createSseResponse`, `terminalStreamResponse`, `startSseHeartbeat`, `readLastEventId`). Its responses carry only `SSE_RESPONSE_HEADERS` plus the forwarded `Set-Cookie` (no `Connection` or other hop-by-hop header, which HTTP/2 forbids). `recipientRawUserId` is filtered server-side and removed before transmission to prevent internal ID leaks. Catch-up and live entries pass through the same filters (recipient, source-type visibility, comment redaction).
+4. On the client, `useDailyReportSseConnection` runs on `useReopeningEventSource` (`@aiquants/sse/react`): full-jitter backoff from 2 s to 30 s, the failure count reset only after 30 s of healthy open, one native browser reconnect (which carries the cursor in the `Last-Event-ID` header), and a stale watch of 45 s (three heartbeat periods).
+   The action context correlates optimistic updates with SSE echoes using `clientTempId`, and exposes the connection status as `sseStatus` (`DailyReportSseConnectionStatus`: the reopening status, or `{ kind: "resyncing" }` while a `resync-required` waits for a fresh ids anchor).
+
+### SSE wire contract
+
+Stop signals are **in-band**: the server answers 200 and writes `retry: 86400000` before one named terminal event, so a client that does not listen for the event (an older bundle) reconnects at most once a day instead of in a loop. A non-200 response is reserved for a misconfigured endpoint.
+
+| Server-side situation | Response | Client (`useDailyReportSseConnection`) |
+| --- | --- | --- |
+| Not authenticated | 200, `retry: 86400000` → `event: auth-required` (`Set-Cookie` forwarded) | terminated; calls `config.onSessionExpired()` once; never reconnects |
+| Authenticated but no internal user | 200, `retry: 86400000` → `event: forbidden` | terminated; no navigation (a reload cannot fix it); visible through `sseStatus` |
+| Unknown endpoint | 404 | treated as retryable; backoff up to 30 s |
+| Unexpected error before the stream starts (for example the internal-user lookup fails) | 500 with the body `Internal Server Error` (no error detail), `Set-Cookie` forwarded | treated as retryable; backoff up to 30 s |
+| Malformed cursor | 200, `retry: 86400000` → `event: resync-required` | rereads the ids (server cache bypassed) and reopens from the new anchor |
+| Cursor older than the oldest retained entry (the stream is trimmed with `MAXLEN ~ streamMaxLen`) | 200, `connected` → heartbeat → `retry: 86400000` → `event: resync-required` → end | same as above |
+| The start of a catch-up page is trimmed away before the page is read | 200, the entries delivered so far → `retry: 86400000` → `event: resync-required` → end | same as above |
+| Empty stream, or a cursor inside the retained window or in the future | 200, `connected` → heartbeat → catch-up (every entry) → live | continues |
+| Redis failure during the catch-up | the body ends (`producer-failed`) | one native reconnect with `Last-Event-ID`, then the utility's own backoff; the cursor is kept |
+
+- **Resume cursor**: `readLastEventId` reads the `Last-Event-ID` header first, then the `lastEventId` query parameter (`DAILY_REPORT_SSE_CURSOR_PARAM`). The browser's own reconnect reuses the URL it opened with (a stale query) but sends a fresh header, so the header is always the newer value. A cursor must be a Redis stream id of the form `<ms>-<seq>` with 1–15 digits per part (`isDailyReportSseStreamId`); anything else is answered with `resync-required`. The client URL-encodes the cursor.
+- **`connected` frame**: `data: {"type":"connected"}` with `id:` set to the resume position (the cursor, or the newest entry at connect time when there is no cursor). On the cursor path it is written before any Redis round trip.
+  The same frame is used as an anchor-only frame for entries the viewer's filters drop (addressed to another user, or a source type the viewer cannot see), so the client's cursor keeps advancing without receiving their content.
+  Without it, a tab whose visible traffic is quiet while other users' read / star updates flow would keep an old cursor, and its next reconnect would fall outside the retained window (`resync-required`, then an ids rescan that bypasses the server cache).
+- **Catch-up**: entries after the cursor are read in pages of 1,000 (`xRange` is inclusive, so each page skips its start id) until the stream end; every entry is delivered. When a page does not start with its start id, the oldest retained entry is read again: if it is newer than the start id, the range after it may have been trimmed, so the connection ends with `resync-required` instead of silently skipping it (a cursor that is simply not an entry id inside the retained window continues).
+- **Ids on the wire only increase**: live entries that arrive during the catch-up are queued, not written. The catch-up stops in front of the first queued entry (the fan-out reader delivers every entry after it in order), then the queue is written in id order and later live entries are written as they arrive. Writing a live entry first would let a disconnect move the client's resume position past catch-up entries it never received, and an older `report-update` would overwrite a newer one on the client.
+- **Heartbeat**: `startSseHeartbeat` writes a jittered `retry:` (2,000–10,000 ms), an immediate named `event: heartbeat` (`data: {"serverTime":<ms>}`, no `id:`), then one every 15 s (`DAILY_REPORT_SSE_HEARTBEAT_MS`). Named events are ignored by `onmessage`, so old bundles are unaffected.
+- **Stream anchor (`streamAnchor`)**: the ids stream carries the newest SSE entry id on its first authoritative line
+  (the line with `total`, or the short-circuit line when the whole data set fits in the fast first page; never on a
+  provisional line). The service reads it inside the cached fetcher **before** the SQL, so every cache path (bucket hit,
+  joining an in-flight fetch, refresh-ahead) returns an array that already reflects every update up to the anchor. The
+  SSE hook does not connect until an anchor arrives and then uses it as the first cursor, which closes the gap between
+  loading the ids and opening the stream. `null` means "position unknown" (empty stream, no redis, read failure): the
+  hook then opens without a cursor and the server starts from the newest entry at connect time.
+- **Delivery is idempotent**: an anchor can be up to one ids-cache TTL old; replaying from it is safe because `report-*` messages upsert and `comment-add` is matched by comment id.
+- **A resync that gives up is retried**: after `resync-required` the hook asks the ids session for a rescan (`resyncDailyReportIdsStream()`) and does not reconnect until an anchor newer than the one it had arrives. When that rescan gives up (the ids phase stays `complete` with an `error`, which happens after repeated failures during an outage), the hook asks again after a full-jitter backoff from 2 s to 30 s while SSE is enabled, until an anchor arrives. An initial ids scan that ends in `failed` is left to the page's manual retry.
 
 ## API Surface (Summary)
 
-- **server**: `createDailyReportServer` / `createDailyReportService` / `createDailyReportHandlers` / `defineDailyReportSchema` / `DailyReportSseReader` / `SqlResultCache` / `transformJsonArray` / `jsonResponseWithETag` / `generateETag` / `isStreamIdLte`
-- **client**: `DailyReportPage` / `DailyReportResolvedContent` / `DailyReportList` / `DailyReportDetailList` / `DailyReportActionProvider` / `useDailyReportActionContext` / `useDailyReportDetail` / `useDailyReportPrefetch` / `useDailyReportComments` / `useDailyReportSseConnection` / `useDailyReportIdsStream` / `DailyReportIdsStreamStatus` / `DailyReportIdsStreamClient` / `DailyReportConfigProvider` / `createDailyReportClientLoader` / `dailyReportShouldRevalidate`
-- **shared**: `DailyReportItem` / `DailyReportDetail` / `DailyReportUser` / `dailyReportSseMessageSchema` (8 discriminated union types) / `normalizeBusinessDateKey` / `mergeComments`
+- **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)`
 
 MIT