@aiquants/contact-map 0.11.0 → 0.13.0

package/README.md

@@ -49,12 +49,12 @@ Peer dependencies:
 ```json
 {
   "peerDependencies": {
-    "@aiquants/directory-tree": "workspace:^",
-    "@aiquants/fuzzy-search": "workspace:^",
-    "@aiquants/resize-panels": "workspace:^",
-    "@aiquants/select-box": "workspace:^",
-    "@aiquants/swipe-overlay": "workspace:^",
-    "@aiquants/virtualscroll": "workspace:^",
+    "@aiquants/directory-tree": "^4.1.1",
+    "@aiquants/fuzzy-search": "^3.2.0",
+    "@aiquants/resize-panels": "^2.1.0",
+    "@aiquants/select-box": "^0.16.3",
+    "@aiquants/swipe-overlay": "^1.2.5",
+    "@aiquants/virtualscroll": "^3.16.0",
     "drizzle-orm": ">=1.0.0-beta.4 <2.0.0",
     "react": ">=18",
     "react-dom": ">=18",
@@ -64,6 +64,9 @@ Peer dependencies:
 }
 ```
 
+These are the ranges this version is published with. The repository's `package.json` writes the `@aiquants` ones as `workspace:^`, which publishing expands to `^` and the workspace's version, so `pnpm view @aiquants/contact-map@<version> peerDependencies` prints the ranges of any version.
+これはこの版を公開したときの範囲。リポジトリの `package.json` は `@aiquants` のものを `workspace:^` と書き、公開のときにワークスペースの版の `^` へ展開されるので、どの版の範囲も `pnpm view @aiquants/contact-map@<version> peerDependencies` で確かめられる。
+
 ---
 
 ## Architecture & Entry Points / アーキテクチャとエントリポイント
@@ -73,7 +76,8 @@ Peer dependencies:
 | `@aiquants/contact-map` | Universal | Domain types, Zod schemas, wire protocols, geometry, parsers, tree builders, and search query normalization. |
 | `@aiquants/contact-map/client` | Browser / SSR | React components (`ContactMapSearchPage`, `ContactMapSearchListView`, `ContactMapSearchTreeView`), hooks, and Worker clients. |
 | `@aiquants/contact-map/server` | Node / Server | DI port interfaces (`ContactMapServerPorts`), streaming handlers, and Drizzle MSSQL service queries. |
-| `@aiquants/contact-map/styles/contact-map.standalone.css` | CSS | Pre-compiled Tailwind v4 standalone utility styles. |
+| `@aiquants/contact-map/worker/treeWorker` | Web Worker (ES module) | The tree Worker script. The tree loads it from beside the client bundle (`dist/worker/treeWorker.mjs`) unless `workerUrls.treeWorker` points elsewhere or `treeWorkerFactory` builds the Worker. |
+| `@aiquants/contact-map/styles/contact-map.standalone.css` | CSS | Pre-compiled Tailwind v4 utility styles for a host without Tailwind CSS (see Styling). |
 
 ---
 
@@ -105,33 +109,38 @@ export async function loader({ request }: { request: Request }) {
 }
 ```
 
+The handler calls `authenticate` in one way only, `authenticate(request, { failureRedirect: null })`, so the arrow function above takes its parameter types from the setting, and a host function with overloads passes as it is when one of them takes `{ failureRedirect: null }` (`authenticate: authenticateInLoader`).
+ハンドラーは `authenticate` を 1 通りにだけ呼ぶ (`authenticate(request, { failureRedirect: null })`)。そのため上の矢印関数は引数の型を設定から得て、オーバーロードを持つホストの関数は、どれかが `{ failureRedirect: null }` を受け取ればそのまま渡せる (`authenticate: authenticateInLoader`)。
+
 `db`, `table`, `ensureConnection` and `authenticate` are required, and `createContactMapStreamHandler` / `createContactMapServer` throw a `TypeError` when `db` or `table` is missing, `table.contacted_at` is missing or is not a Drizzle column, `ensureConnection` or `authenticate` is not a function, or `firstBatchSize` / `nextBatchSize` is given but is not a number.
 They throw a `RangeError` when `table.contacted_at` is not a `datetime2` column (`datetime2` or `datetime2(0)` to `datetime2(7)`; a `datetime`, `datetimeoffset` or `date` column is refused) or `firstBatchSize` or `nextBatchSize` is a number but not an integer from 1 to `Number.MAX_SAFE_INTEGER`.
 Each message names the setting and ends with the value given (`[contact-map] server config authenticate must be the function that returns the request's user (…); got undefined`, `[contact-map] server config table.contacted_at must be a Drizzle datetime2 column; got "datetime"`). A stream open to everyone says so with an `authenticate` that returns a user; leaving the setting out never serves the contacts unauthenticated.
-The handler calls `authenticate(request, { failureRedirect: null })` after checking the resume cursor (a malformed cursor gets 400 without authenticating), answers 401 when no user comes back, and sends a returned `cookie` as `Set-Cookie` on the 401 and on the stream response alike, so a session the call refreshed reaches the browser. The stream is sent with `Cache-Control: no-store, no-transform`.
+The handler calls `authenticate(request, { failureRedirect: null })` after checking the resume cursor (a malformed cursor gets 400 without authenticating), answers 401 when no user comes back, and sends a returned `cookie` as `Set-Cookie` on the 401 and on the stream response alike, so a session the call refreshed reaches the browser. When `authenticate` throws, the handler logs the error through `logger` and answers 500 with `{ "error": "authentication failed on the server" }`, so nothing of the session infrastructure reaches the client. The stream is sent with `Cache-Control: no-store, no-transform`.
 
 The resume cursor (`StreamCursor`: each chunk line's `nextCursor`, sent back as `cursor_contacted_at` / `cursor_person_id`) is written by the server and opaque to clients. Its `contacted_at` is the last row's value in UTC with exactly 7 fractional digits (`YYYY-MM-DDThh:mm:ss.fffffffZ`, the 100 ns of `datetime2(7)`), read from the database as text so that no digit is lost to the driver's millisecond `Date`, or `null` once the stream has reached the rows without one; its `person_id` is the last row's id, any safe integer (a signed key may be negative).
 The chunk query checks both values by the rules below when it writes the cursor, so the next request accepts every cursor the server writes; a chunk whose last row's `person_id` is not a safe integer fails with an error naming the value.
 The handler accepts only that form naming a real instant from year 1 on and a `cursor_person_id` holding a safe integer written in canonical decimal (`0`, or digits without a leading zero after an optional minus sign); anything else (`-0`, `+5`, `05`, `1e3`, …) gets 400 before authenticating.
 The next chunk compares the bare column with the cursor cast to `datetime2(7)`, so an index on (`is_active`, `contacted_at`, `person_id`) can seek. `createContactMapServer().getContactsStreamChunk(cursor)` checks the cursor by the same rules and throws a `TypeError` (a value of the wrong type or shape) or a `RangeError` (any other form) before connecting.
 `ContactMapStreamClient` sends the cursor back unchanged. When a resumed request gets 400 (the cursor was written by a server of another version), it drops the cursor and loads from the beginning again once, keeping the records it has (they are keyed by `person_id`); a 400 to a request without a cursor, or a second 400 in the same load, ends the load at once with `[contact-map] the server rejected the stream request (400); reload the page`.
-A 401 or 403 ends the load at once in phase `auth-required` with the error `Authentication required`, without retrying (`retryNow()` starts again from the last cursor, for example after the user signs in again). Any other failed response is retried with backoff and sets the error to `[contact-map] the stream request failed (status <status>)`.
+A 401 or 403 ends the load at once in phase `auth-required` with the error `Authentication required`, without retrying (`retryNow()` starts again from the last cursor, for example after the user signs in again). Any other failed response (the 500 of a throwing `authenticate` included) is retried with backoff (1 s, doubling up to 30 s; the annotation shows `annotationReconnecting` meanwhile) and sets the error to `[contact-map] the stream request failed (status <status>)`. The sixth failure in a row ends the load in phase `failed` (`retryNow()` starts again from the last cursor).
 
 `db`・`table`・`ensureConnection`・`authenticate` は必須で、`db` か `table` が無い、`table.contacted_at` が無いか Drizzle の列でない、`ensureConnection` か `authenticate` が関数でない、または `firstBatchSize` / `nextBatchSize` が数値でなければ `createContactMapStreamHandler` / `createContactMapServer` は `TypeError` を、`table.contacted_at` が `datetime2` の列 (`datetime2` か `datetime2(0)` から `datetime2(7)`。`datetime`・`datetimeoffset`・`date` の列は断る) でないか、`firstBatchSize` か `nextBatchSize` が 1 から `Number.MAX_SAFE_INTEGER` までの整数でない数値なら `RangeError` を投げる。
-どの文言も設定を名指し、与えた値で終わる (`[contact-map] server config authenticate must be the function that returns the request's user (…); got undefined`、`[contact-map] server config table.contacted_at must be a Drizzle datetime2 column; got "datetime"`)。誰にでも開くストリームは user を返す `authenticate` で明示し、設定を書き漏らしても認証なしで連絡先を配ることはない。ハンドラーは再開カーソルを検査してから (不正な形は認証せずに 400) `authenticate(request, { failureRedirect: null })` を呼び、user が無ければ 401 を返し、返された `cookie` は 401 にもストリームの応答にも `Set-Cookie` で載せる (呼び出しが更新したセッションをブラウザへ届ける)。ストリームは `Cache-Control: no-store, no-transform` で送る。
+どの文言も設定を名指し、与えた値で終わる (`[contact-map] server config authenticate must be the function that returns the request's user (…); got undefined`、`[contact-map] server config table.contacted_at must be a Drizzle datetime2 column; got "datetime"`)。誰にでも開くストリームは user を返す `authenticate` で明示し、設定を書き漏らしても認証なしで連絡先を配ることはない。ハンドラーは再開カーソルを検査してから (不正な形は認証せずに 400) `authenticate(request, { failureRedirect: null })` を呼び、user が無ければ 401 を返し、返された `cookie` は 401 にもストリームの応答にも `Set-Cookie` で載せる (呼び出しが更新したセッションをブラウザへ届ける)。
+`authenticate` が例外を投げると、ハンドラーはそのエラーを `logger` へ出し、500 (`{ "error": "authentication failed on the server" }`) を返す (セッションの基盤の詳細はクライアントへ出さない)。ストリームは `Cache-Control: no-store, no-transform` で送る。
 
 再開カーソル (`StreamCursor`。各チャンク行の `nextCursor` で、`cursor_contacted_at` / `cursor_person_id` として送り返す) はサーバーが書き、クライアントにとって形は不透明。`contacted_at` は最後の行の値を UTC で小数部ちょうど 7 桁 (`YYYY-MM-DDThh:mm:ss.fffffffZ`、`datetime2(7)` の 100 ns) で表したもので、ドライバのミリ秒までの `Date` で桁を落とさないようデータベースから文字列で読む。日時の無い行へ進んだ後は `null`。`person_id` は最後の行の ID で、負を含む任意の安全な整数 (符号付きのキーは負にもなる)。
 チャンクの照会はカーソルを書くときに両方の値を下の規則で確かめるので、サーバーが書いたカーソルは次の要求が必ず受け入れる。最後の行の `person_id` が安全な整数でないチャンクは、その値を示すエラーで失敗する。
 ハンドラーは 1 年以降の実在する日時を表すこの形と、安全な整数を正規の 10 進 (`0` か、省略できる負の符号に続く先頭が 0 でない数字) で書いた `cursor_person_id` だけを受け入れ、それ以外 (`-0`・`+5`・`05`・`1e3` など) は認証の前に 400 で断る。次のチャンクは素の列と `datetime2(7)` へ CAST したカーソルを比べるので、(`is_active`, `contacted_at`, `person_id`) の索引でシークできる。`createContactMapServer().getContactsStreamChunk(cursor)` も同じ規則でカーソルを検査し、接続の前に `TypeError` (型や形の誤り) か `RangeError` (それ以外の形) を投げる。
 `ContactMapStreamClient` はカーソルをそのまま送り返す。再開した要求が 400 を受けたら (別の版のサーバーが書いたカーソル)、カーソルを捨てて最初から 1 回だけ読み直し、受信済みのレコードは残す (`person_id` で重ねる)。カーソルの無い要求への 400 と、同じ読み込みでの 2 回目の 400 は、`[contact-map] the server rejected the stream request (400); reload the page` で即座に読み込みを終える。
-401 と 403 は再試行せず、段階 `auth-required`・エラー `Authentication required` で即座に読み込みを終える (`retryNow()` で最終カーソルから読み直す。たとえば再ログインの後)。それ以外の失敗の応答はバックオフで再試行し、エラーを `[contact-map] the stream request failed (status <status>)` にする。
+401 と 403 は再試行せず、段階 `auth-required`・エラー `Authentication required` で即座に読み込みを終える (`retryNow()` で最終カーソルから読み直す。たとえば再ログインの後)。それ以外の失敗の応答 (`authenticate` が投げたときの 500 を含む) はバックオフ (1 秒から倍々に最大 30 秒。その間、注記は `annotationReconnecting` を表示) で再試行し、エラーを `[contact-map] the stream request failed (status <status>)` にする。続けて 6 回目の失敗で、段階 `failed` として読み込みを終える (`retryNow()` で最終カーソルから始め直す)。
 
 ### 2. Client Page Setup / クライアント側ページの設定
 
 ```tsx
 // app/routes/contact_map.tsx
-import { ContactMapConfigProvider, ContactMapSearchPage } from "@aiquants/contact-map/client"
-import "@aiquants/contact-map/styles/contact-map.standalone.css"
+import { ContactMapConfigProvider, ContactMapSearchPage, contactMapShouldRevalidate } from "@aiquants/contact-map/client"
+
+export const shouldRevalidate = contactMapShouldRevalidate
 
 export default function ContactMapRoute() {
     return (
@@ -147,6 +156,12 @@ export default function ContactMapRoute() {
 }
 ```
 
+Export `contactMapShouldRevalidate` as the route's `shouldRevalidate`. On the same path, a change of nothing but the page's own URL state (the list / tree tab `view` and the search term `q`) does not run the route's loader, since the records stream in on the client. Every other transition keeps React Router's decision (another path, another parameter, and the unchanged URL after an action, a `revalidate()` call or a link to the current page), so a loader that checks the session still runs then; a submission is decided by its URL the same way. It is built with `@aiquants/route-revalidation`.
+ルートの `shouldRevalidate` には `contactMapShouldRevalidate` を公開する。同じパスでページ自身の URL の状態 (一覧とツリーのタブ `view` と検索語 `q`) だけが変わる遷移では、ルートのローダーを走らせない (レコードはクライアントへストリームで届く)。ほかの遷移 (別のパス・ほかのパラメータ・アクションの後や `revalidate()`・今のページへのリンクのような URL の変わらない場合) は React Router の判断を保つので、セッションを確かめるローダーはそのときも走る。送信も URL で同じに決める。`@aiquants/route-revalidation` で組んでいる。
+
+The page needs its styles, which depend on the host: a host that builds with Tailwind CSS v4 generates the classes itself, and a host without it imports the standalone CSS (see Styling).
+ページにはスタイルが要り、その用意はホストによって変わる: Tailwind CSS v4 でビルドするホストは自分のビルドでクラスを生成し、Tailwind CSS を使わないホストはスタンドアロンの CSS を読み込む (スタイルの節を参照)。
+
 ### 3. Stream Endpoint / ストリームのエンドポイント
 
 The stream endpoint is a setting like `locale` and `workerUrls`: set `streamEndpoint` on `ContactMapAppView` or on a surrounding `ContactMapConfigProvider`, and when both set it the view's prop wins. It has no default; the stream reads the one value that results.
@@ -185,40 +200,119 @@ A Worker that cannot be created or fails is recreated twice, 250 ms and then 500
 ビューが重ねる設定 (`ContactMapAppView` の `streamEndpoint`・`workerUrls`・`locale`・`labels`、`ContactMapSearchPage` の `workerUrls`) も、props が自身で持つときだけ読む。
 Worker を作れないか Worker が落ちると、250 ms 後と 500 ms 後の 2 回作り直す (待つ間に届いたレコードは新しい Worker へ送り、Worker を前倒しでは作らない)。障害ごとに `[TreeWorker]` の警告をエラーと共にログへ出し、続けて 3 回目の障害は、Worker の出どころの設定とツリーを戻すものを挙げたエラーとして出す。モジュール常駐のセッション (`workerUrls.treeWorker`) はページの再読み込み、factory のセッション (`treeWorkerFactory`) はビューの再マウントで戻り、それまでツリーの更新は止まる。Worker が構築を終えると回数は 0 に戻る。
 
+The tree view starts its session when it mounts. A host that wants the tree finished before the tree tab opens feeds the module-resident session itself: inside the same provider (so the fallback names agree), call `useTreeWorker` with the stream's records, for example in the layout that frames the page. The tree view then finds the session holding those records and shows its snapshot at once. A `treeWorkerFactory` gives every hook its own session, so this works only without one.
+ツリービューはマウントのときにセッションを始める。ツリーのタブを開く前にツリーを組み終えておきたいホストは、モジュール常駐のセッションへ自分でレコードを渡す: 同じプロバイダーの中で (代替名を揃えるため)、ページを囲むレイアウトなどからストリームのレコードで `useTreeWorker` を呼ぶ。ツリービューはそのレコードを持つセッションを見つけ、スナップショットをすぐに出す。`treeWorkerFactory` はフックごとにセッションを持たせるので、これが効くのは factory を指定しないときだけ。
+
+```tsx
+import { useContactMapStream, useTreeWorker } from "@aiquants/contact-map/client"
+
+// rendered inside ContactMapConfigProvider, next to the page
+function PrebuildContactMapTree() {
+    const { records, isComplete } = useContactMapStream()
+    useTreeWorker(records, isComplete)
+    return null
+}
+```
+
+## Styling / スタイル
+
+The components are styled with Tailwind CSS v4 utility classes: the semantic colors of a shadcn/ui-style host (`bg-background`, `text-muted-foreground`, `border-border`, ...), read from the host's `--background`, `--foreground`, ... variables (HSL components), and the `dark:` variant of a `dark` class on an ancestor.
+
+- A host that builds with Tailwind CSS v4 generates the classes in its own build: it adds an `@source` for the package's files (`@source "<path to node_modules>/@aiquants/contact-map/dist";` for the published package), keeps the semantic colors in its `@theme`, and defines the `animate-progress-indeterminate` utility of the indeterminate progress bar (the definition below). It does not import the standalone CSS as well, whose copy of the utilities would compete with its own.
+- A host without Tailwind CSS imports `@aiquants/contact-map/styles/contact-map.standalone.css`: the package's utilities, the semantic color mapping and the progress animation, compiled. It reads the host's `--background`, ... variables at run time.
+- Either way, the host imports the CSS of the embedded packages itself, which the standalone CSS leaves out so that an older copy baked into it never overrides the host's newer one: `@aiquants/virtualscroll/styles/virtualscroll.css`, `@aiquants/directory-tree/styles/directory-tree.css` and `@aiquants/resize-panels/styles/resize-panels.css`.
+
+コンポーネントは Tailwind CSS v4 のユーティリティクラスで装飾する: shadcn/ui 流のホストの意味の色 (`bg-background`・`text-muted-foreground`・`border-border` など。ホストの `--background`・`--foreground` などの変数 (HSL の成分) から読む) と、祖先の `dark` クラスによる `dark:` バリアント。
+
+- Tailwind CSS v4 でビルドするホストは、自分のビルドでクラスを生成する: パッケージのファイルへの `@source` を足し (公開版なら `@source "<node_modules への道>/@aiquants/contact-map/dist";`)、意味の色を自分の `@theme` に置き、不確定の進捗バーの `animate-progress-indeterminate` ユーティリティを定義する (定義は下)。スタンドアロンの CSS は併せて読み込まない (その写しのユーティリティが自分のものと競り合う)。
+- Tailwind CSS を使わないホストは `@aiquants/contact-map/styles/contact-map.standalone.css` を読み込む: パッケージのユーティリティ・意味の色の対応・進捗のアニメーションをコンパイルしたもの。ホストの `--background` などの変数は実行時に読む。
+- どちらの場合も、埋め込みのパッケージの CSS はホストが自分で読み込む (スタンドアロンの CSS は含めないので、焼き込んだ古い写しがホストの新しい CSS を上書きしない): `@aiquants/virtualscroll/styles/virtualscroll.css`・`@aiquants/directory-tree/styles/directory-tree.css`・`@aiquants/resize-panels/styles/resize-panels.css`。
+
+A host that builds with Tailwind CSS v4 (in the CSS file its build reads; the `@source` path is relative to that file):
+Tailwind CSS v4 でビルドするホスト (ビルドが読む CSS ファイルに書く。`@source` の道はそのファイルからの相対):
+
+```css
+@source "../node_modules/@aiquants/contact-map/dist";
+
+@theme {
+  --animate-progress-indeterminate: progress-indeterminate 2s ease-in-out infinite;
+
+  @keyframes progress-indeterminate {
+    0% {
+      transform: translateX(-100%);
+    }
+    50% {
+      transform: translateX(300%);
+    }
+    100% {
+      transform: translateX(-100%);
+    }
+  }
+}
+```
+
+A host without Tailwind CSS (once, for example in its root module):
+Tailwind CSS を使わないホスト (ルートのモジュールなどで 1 度だけ):
+
+```ts
+import "@aiquants/contact-map/styles/contact-map.standalone.css"
+```
+
+The package reads these host CSS variables, each `0px` while the host leaves it unset. It never names a variable of another package: a host binds them in its own layout layer.
+パッケージは次のホストの CSS 変数を読み、ホストが設定しない間はどれも `0px`。ほかのパッケージの変数は名指さないので、ホストが自分のレイアウトの層で結ぶ。
+
+| Variable | Read by | Meaning |
+| --- | --- | --- |
+| `--header-height` | The list view's height (on the root element) | The list never reaches above this distance from the top of the viewport (a fixed header's height). |
+| `--footer-height` | The list view's height (on the root element) | Taken from the bottom of the viewport (a fixed footer's height). |
+| `--scrollbar-height` | The list view's height (on the root element) | Taken from the bottom of the viewport as well (room kept for a horizontal scrollbar). |
+| `--aqcm-overlay-right` | The detail popup and the swipe overlay | Their right inset, such as the width of a menu pinned to the right edge: `:root { --aqcm-overlay-right: var(--my-pinned-menu-width, 0px); }`. |
+
+| 変数 | 読むもの | 意味 |
+| --- | --- | --- |
+| `--header-height` | 一覧ビューの高さ (ルート要素で読む) | 一覧はビューポートの上端からこの距離より上へ出ない (固定したヘッダーの高さ)。 |
+| `--footer-height` | 一覧ビューの高さ (ルート要素で読む) | ビューポートの下端から差し引く (固定したフッターの高さ)。 |
+| `--scrollbar-height` | 一覧ビューの高さ (ルート要素で読む) | 同じくビューポートの下端から差し引く (横のスクロールバーのために空ける高さ)。 |
+| `--aqcm-overlay-right` | 詳細のポップアップとスワイプのオーバーレイ | 右端の余白 (右端にピン留めしたメニューの幅など): `:root { --aqcm-overlay-right: var(--my-pinned-menu-width, 0px); }`。 |
+
 ## Search Normalization / 検索語の正規化
 
 The search box reads its text as keywords. Each whitespace-separated word is a keyword of its own, and the words between two quotation marks (`"`, `＂`, `“`, `”`; any of them opens or closes a group, and a group left open runs to the end) are one keyword.
 The page searches every keyword with `@aiquants/fuzzy-search`: `useFuzzySearch`'s `querySetsOf` reads the term with `parseQuerySets`, and `FuzzySearchManager.searchSets` searches one query set per keyword. The AND / OR button next to the search box combines the keywords' answers: AND keeps the contacts every keyword finds (intersection), OR the contacts any keyword finds (union). The button starts at OR, and switching it searches the current term again without rebuilding the index.
 A quoted keyword is matched by fuzzy-search's multi-word matching, whose operator is the settings tab's "Operator for words inside quotes" select (`multiTermOperator`, AND at first): AND requires every word of the group to appear in some search field, OR does not. A keyword of one word matches the same under either operator.
 A "Maximum results" cap of the index or Levenshtein settings (no limit at first) applies to each keyword's answer before the keywords are combined, so with a cap an AND search can miss a contact that one keyword's capped answer left out.
+The settings tab's "Input delay (ms)" (`debounceMs`, 300 at first) is the one wait between typing and searching: the page searches that long after the text last changed and hands the engine `debounceMs: 0`. "Reset all" returns every search setting to the page's initial ones (fuzzy-search's defaults, with AND for the words inside quotes) and keeps the Worker URLs.
 
 The search page normalizes the typed text with `normalizeSearchInput` (exported from `@aiquants/contact-map`) into the fuzzy search term. The contact fields (name, company, department, title, email, phone numbers) are matched as stored. Every keyword is therefore only brought into a form those fields can hold:
 
 - Invisible characters (U+200B, U+FEFF) are removed before the keywords are read, and each keyword's surrounding whitespace (U+3000 and U+00A0 included) is trimmed.
 - Width, kana (hiragana → katakana) and case are unified with select-box's `normalizeText` (`ＡＢＣ商事` → `abc商事`, `さとう` → `サトウ`). Kana stays as written (`つづき` → `ツヅキ`).
+  Its options are `CONTACT_MAP_SEARCH_NORMALIZE_OPTIONS` (exported from `@aiquants/contact-map`), which sets all eight of select-box's `NormalizeOptions`, so a change of select-box's defaults never changes the search term: `convertWidth`, `convertKana` and `convertCase` on, `convertRomaji` off (the next rule reads romaji), and `normalizeVariants`, `ignoreSpaces`, `ignoreSymbols` and `ignoreLongVowels` off, because the fields hold spelling variants, spaces, symbols and prolonged sound marks as written (`佐々木`, `自由ヶ丘`, `ーヒー` and `don’t` stay).
 - The keywords are replaced by their katakana readings only when every keyword is romaji that reads completely. Each must hold only Latin letters and whitespace, and select-box's `romajiToKatakana` must leave no letter untransliterated (`tanaka` → `タナカ`, `yamada taro` → `ヤマダ タロ`, `"yamada taro" suzuki` → `"ヤマダ タロ" スズキ`, `tsuduki` → `ツヅキ`).
 - Mixed text, digits and symbols, and words that do not read completely keep their width / kana / case form, and so does every other keyword of the text (`user@example.com`, `営業部 tanaka`, `tanaka1`, `ke-su`, `sony`, `"yamada taro" sony`).
 - The keywords are written back with fuzzy-search's `formatQuerySets`: single spaces between them, a keyword holding whitespace in ASCII quotation marks (`＂ＡＢＣ 商事＂` → `"abc 商事"`), and neither a blank keyword nor a keyword that normalization made equal to an earlier one. `parseQuerySets` therefore reads exactly these keywords from the term. Text without quotation marks becomes its whitespace-separated words, each normalized as above and written once, separated by single spaces.
 
-The result highlight and the exact-match ranking are one derivation from the text as typed. `createSearchQueryPattern(query)` finds the spellings that `getSearchQuerySpellings(query)` lists (select-box's `getNormalizedVariants` of each word of the text's keywords and of its normalized form's keywords, read with fuzzy-search's `parseQuerySets`, so a quotation mark is never part of a spelling), longest first and case-insensitively.
-`HighlightedText` marks its matches, and `createExactMatchRanker(query, fields)` moves the results with a match in one of the fields to the top, keeping the fuzzy order within each group. A field is therefore highlighted exactly when it ranks its record as an exact match. A kana reading is marked only when every keyword reads as romaji.
+The result highlight and the exact-match ranking are one derivation from the text as typed. `createSearchQueryPattern(query)` finds the spellings that `getSearchQuerySpellings(query)` lists (select-box's `getNormalizedVariants` of each word of the text's keywords and of its normalized form's keywords, read with fuzzy-search's `parseQuerySets`, so a quotation mark is never part of a spelling, each followed by its half-width katakana spelling when every kana of it has one: `ﾀﾅｶ` after `タナカ`, `ｻﾄｳ` after `サトウ`, the form many stored fields hold), longest first and case-insensitively.
+`HighlightedText` marks its matches in `mark` elements, dark text on yellow and, under the `dark` class, light text on dark amber (both above the 7:1 contrast of WCAG 2.2 AAA), and `createExactMatchRanker(query, fields)` moves the results with a match in one of the fields to the top, keeping the fuzzy order within each group. A field is therefore highlighted exactly when it ranks its record as an exact match. A kana reading is marked only when every keyword reads as romaji.
 
-The typed query is used because normalization can drop a spelling it holds. select-box reads a prolonged sound mark that follows no kana as a hyphen, so `ーヒー` (the middle of `コーヒー`) becomes the search term `-ヒー`, while the highlight and the ranking still find `ーヒー`. The search outlet context carries both: `searchQuery` (as typed) and `searchTerm` (`normalizeSearchInput(searchQuery)`). The select-box peer range is ^0.11.0, expanded from `workspace:^` at publish.
+The typed query is used because normalization can drop a spelling it holds. The width unification (Unicode NFKC) reads `㈱` as `(株)`, so `㈱山田` becomes the search term `(株)山田`, while the highlight and the ranking still find `㈱山田` in a company stored with `㈱`. The search outlet context carries both: `searchQuery` (as typed) and `searchTerm` (`normalizeSearchInput(searchQuery)`).
 
 検索欄はテキストをキーワードとして読む。空白で区切った語はそれぞれ 1 つのキーワードで、2 つの引用符 (`"`・`＂`・`“`・`”`。どれでも組を開き閉じ、開いたままの組は終わりまで続く) の間の語はまとめて 1 つのキーワード。ページはどのキーワードも `@aiquants/fuzzy-search` で検索する: `useFuzzySearch` の `querySetsOf` が `parseQuerySets` で検索語を読み、`FuzzySearchManager.searchSets` がキーワードごとに 1 つの問い合わせのセットを検索する。検索欄の隣の AND / OR ボタンはキーワードの答えをまとめ、AND はどのキーワードも見つけた連絡先 (積集合)、OR はどれかのキーワードが見つけた連絡先 (和集合) を残す。ボタンは OR で始まり、切り替えると索引を建て直さずに今の検索語を検索し直す。
 引用符で囲んだキーワードは fuzzy-search の複数語の照合で照合し、その演算子は設定タブの「引用符の中の語の演算子」セレクト (`multiTermOperator`。最初は AND): AND は組のどの語もいずれかの検索フィールドに現れることを求め、OR は求めない。1 語のキーワードはどちらの演算子でも同じに照合する。
+索引か Levenshtein の設定の「最大結果数」(最初は上限なし) はキーワードの答えをまとめる前に各キーワードの答えへ効くので、上限があると AND の検索は、あるキーワードの上限で切られた答えから漏れた連絡先を見落とすことがある。
+設定タブの「入力遅延 (ms)」(`debounceMs`。最初は 300) が入力から検索までの唯一の待ちで、ページはテキストが最後に変わってからその時間の後に検索し、エンジンへは `debounceMs: 0` を渡す。「すべてリセット」はどの検索設定もページの初期の設定 (fuzzy-search の既定に、引用符の中の語の AND を重ねたもの) へ戻し、Worker の URL は保つ。
 
 検索ページは入力されたテキストを `normalizeSearchInput` (`@aiquants/contact-map` から公開) で正規化し、あいまい検索の検索語にする。連絡先のフィールド (氏名・会社・部署・役職・メール・電話番号) は保存されたままの値で照合する。そのため各キーワードは、それらのフィールドが持ちうる形に揃えるだけ:
 
 - キーワードを読む前に不可視文字 (U+200B・U+FEFF) を除き、各キーワードの端の空白 (U+3000・U+00A0 を含む) を除く。
-- select-box の `normalizeText` で全角/半角・かな (ひらがな → カタカナ)・大文字小文字を統一する (`ＡＢＣ商事` → `abc商事`、`さとう` → `サトウ`)。かなは書いたまま (`つづき` → `ツヅキ`)。
+- select-box の `normalizeText` で全角/半角・かな (ひらがな → カタカナ)・大文字小文字を統一する (`ＡＢＣ商事` → `abc商事`、`さとう` → `サトウ`)。かなは書いたまま (`つづき` → `ツヅキ`)。設定は `CONTACT_MAP_SEARCH_NORMALIZE_OPTIONS` (`@aiquants/contact-map` から公開) で、select-box の `NormalizeOptions` の 8 つをすべて指定するので、select-box の既定が変わっても検索語は変わらない: `convertWidth`・`convertKana`・`convertCase` は有効、`convertRomaji` は無効 (ローマ字は次の規則で読む)、`normalizeVariants`・`ignoreSpaces`・`ignoreSymbols`・`ignoreLongVowels` は無効 (フィールドは異体字・空白・記号・長音記号を書いたまま持つため。`佐々木`・`自由ヶ丘`・`ーヒー`・`don’t` はそのまま)。
 - どのキーワードも完全に読めるローマ字のときだけ、各キーワードをカタカナの読みに置き換える。どれもラテン文字と空白だけで、select-box の `romajiToKatakana` が音訳しない文字を残さないことが条件 (`tanaka` → `タナカ`、`yamada taro` → `ヤマダ タロ`、`"yamada taro" suzuki` → `"ヤマダ タロ" スズキ`、`tsuduki` → `ツヅキ`)。
 - 混在テキスト・数字や記号・完全には読めない語は全角/半角・かな・大文字小文字の形のままで、そのテキストのほかのキーワードも同じ (`user@example.com`、`営業部 tanaka`、`tanaka1`、`ke-su`、`sony`、`"yamada taro" sony`)。
 - キーワードは fuzzy-search の `formatQuerySets` で書き戻す: キーワードの間は 1 つの空白、空白を持つキーワードは ASCII の引用符で囲み (`＂ＡＢＣ 商事＂` → `"abc 商事"`)、空のキーワードと、正規化で先のキーワードと等しくなったキーワードは書かない。そのため `parseQuerySets` は検索語からちょうどこれらのキーワードを読む。引用符の無いテキストは、空白で区切った各語を上のとおり正規化して 1 度ずつ並べ、1 つの空白で区切ったものになる。
 
-検索結果のハイライトと完全一致による並べ替えは、入力されたままのテキストからの 1 つの導出。`createSearchQueryPattern(query)` は `getSearchQuerySpellings(query)` が並べる表記 (テキストのキーワードとその正規化形のキーワードの各語に対する select-box の `getNormalizedVariants`。語は fuzzy-search の `parseQuerySets` で読むため、引用符は表記の一部にならない) を、最長のものから大文字小文字を区別せずに探す。`HighlightedText` はその一致に印を付け、`createExactMatchRanker(query, fields)` はいずれかのフィールドに一致を持つ結果を先頭へ移す (各グループ内ではあいまい検索の順序を保つ)。そのため、フィールドにハイライトが付くのは、そのフィールドがレコードを完全一致として並べさせるときちょうど。かなの読みに印が付くのはどのキーワードもローマ字として読めるときだけ。
+検索結果のハイライトと完全一致による並べ替えは、入力されたままのテキストからの 1 つの導出。`createSearchQueryPattern(query)` は `getSearchQuerySpellings(query)` が並べる表記 (テキストのキーワードとその正規化形のキーワードの各語に対する select-box の `getNormalizedVariants`。語は fuzzy-search の `parseQuerySets` で読むため、引用符は表記の一部にならない。どの仮名も半角の形を持つ表記には、続けて半角カナの表記を置く: `タナカ` の次に `ﾀﾅｶ`、`サトウ` の次に `ｻﾄｳ`。保存されたフィールドに多い形) を、最長のものから大文字小文字を区別せずに探す。`HighlightedText` はその一致に `mark` 要素で印を付け (明るいテーマは黄色の上の暗い文字、`dark` クラスの下は暗い琥珀色の上の明るい文字。どちらも WCAG 2.2 AAA の 7:1 を超える)、`createExactMatchRanker(query, fields)` はいずれかのフィールドに一致を持つ結果を先頭へ移す (各グループ内ではあいまい検索の順序を保つ)。そのため、フィールドにハイライトが付くのは、そのフィールドがレコードを完全一致として並べさせるときちょうど。かなの読みに印が付くのはどのキーワードもローマ字として読めるときだけ。
 
-入力されたままの検索語を使うのは、正規化が検索語の持つ表記を落とすことがあるため。select-box はかなに続かない長音記号をハイフンと読むので、`ーヒー` (`コーヒー` の途中) は検索語 `-ヒー` になるが、ハイライトと並べ替えは `ーヒー` を探し続ける。検索のアウトレットコンテキストは両方を運ぶ: `searchQuery` (入力されたまま) と `searchTerm` (`normalizeSearchInput(searchQuery)`)。select-box のピア範囲は ^0.11.0 (公開時に `workspace:^` から展開)。
+入力されたままの検索語を使うのは、正規化が検索語の持つ表記を落とすことがあるため。全角/半角の統一 (Unicode の NFKC) は `㈱` を `(株)` と読むので、`㈱山田` は検索語 `(株)山田` になるが、ハイライトと並べ替えは `㈱` で保存された会社の `㈱山田` を探し続ける。検索のアウトレットコンテキストは両方を運ぶ: `searchQuery` (入力されたまま) と `searchTerm` (`normalizeSearchInput(searchQuery)`)。
 
 ## Localization / UI 言語
 
@@ -236,6 +330,8 @@ Every string the client components render on their own (tabs, buttons, headings,
 | `ContactMapConfigProvider` | `config.streamEndpoint` | `string` | Same-origin absolute path of the NDJSON stream. No default; it or the view's `streamEndpoint` must be set (see Stream Endpoint). |
 | `ContactMapConfigProvider` | `config.locale` | `ContactMapLocale` (`"en" \| "ja"`) | Omitted ⇒ `"en"`. At mount a non-string throws a `TypeError` and any other string a `RangeError`, both naming `locale`. |
 | `ContactMapConfigProvider` | `config.labels` | `ContactMapLabelOverrides` | Partial overrides over `CONTACT_MAP_LABEL_CATALOGS[locale]`, validated at mount; errors name `labels`. |
+| `ContactMapConfigProvider` | `config.openEmailsWithGmail` | `boolean` | Initial value of the settings tab's Gmail toggle; omitted ⇒ `false`. While it is on, an email address links to Gmail's web compose window instead of `mailto:`, and double-clicking (or double-tapping) an address in the popup opens it. |
+| `ContactMapConfigProvider` | `config.treeWorkerFactory` | `() => Worker` | Builds the tree Worker for a bundler that needs its own construction; every call must return a new Worker, and each hook then has its own session (see the tree paragraphs above). |
 | `ContactMapConfigProvider` | `config.workerUrls` | `ContactMapWorkerUrls` | A plain object of only `indexWorker`, `levenshteinWorker` and `treeWorker`, each left out or a string with non-whitespace; checked in every render, a server render included (`assertContactMapWorkerUrls`: `TypeError` / `RangeError`); the views read only the checked copy. One `treeWorker` per browser tab (see the tree paragraph above). |
 | `ContactMapAppView` | `streamEndpoint` | `string` | When given it wins over the surrounding provider's `streamEndpoint`. |
 | `ContactMapAppView` | `locale` | `ContactMapLocale` | When given it wins over the surrounding provider's `locale`; its errors name `ContactMapAppView locale`. |
@@ -270,8 +366,8 @@ export default function ContactMapRoute() {
   It names the setting as the surface calls it (`labels`, `ContactMapAppView labels`, `server config firstBatchSize`), and it ends with `; got <value>`: the rejected value, or the rejected key, written the same way everywhere (a quoted string, `undefined`, `null`, `-0`, `10n`, `Symbol(x)`, `[object URL]`).
 - Two views of one browser tab that disagree on `streamEndpoint` or `workerUrls.treeWorker`, and a CommonJS build without `workerUrls.treeWorker`, throw a plain `Error` (no single value is wrong).
 - A unit key (`recordUnit`, `companyUnit`, `resultUnit`, `timesUnit`, `itemsUnit`, `charactersUnit`) receives the number exactly as it is displayed (`"1"`, `"1,001"`, `"1.0"`), so the English singular / plural follows what the reader sees: only a displayed `"1"` is singular (`"1.0 items"`). `timesUnit` / `itemsUnit` / `charactersUnit` / `throughputUnit` are appended to the number without a separator and carry their own leading space.
-- The 7 engine keys and the 2 row kind words are checked here under the same rule before they are handed to `@aiquants/virtualscroll` and `@aiquants/directory-tree`, so their errors follow the package's rule too.
-- The result is frozen. The list VirtualScroll receives exactly the 7 engine keys and the DirectoryTree exactly its 9 keys, both kept value-stable, so an inline `labels` object recreated on every render does not rebuild the embedded scroll chrome.
+- The embedded keys (`VIRTUAL_SCROLL_LABEL_KEYS` of `@aiquants/virtualscroll` and the row kind words of `@aiquants/directory-tree`, together `DIRECTORY_TREE_LABEL_KEYS`) are checked here under the same rule before they are handed to those packages, so their errors follow the package's rule too.
+- The result is frozen. The list VirtualScroll receives exactly the keys of `VIRTUAL_SCROLL_LABEL_KEYS` and the DirectoryTree exactly those of `DIRECTORY_TREE_LABEL_KEYS`, both kept value-stable, so an inline `labels` object recreated on every render does not rebuild the embedded scroll chrome.
 - `overrides` 未指定なら凍結カタログそのもの (同一 identity) を返す。
 - `overrides` は素の object (プロトタイプが `Object.prototype` か `null`) に限り、それ以外 (`null`・プリミティブ・配列・クラスインスタンス・他 object 継承) は `TypeError`。読むのは自身のプロパティのみで、各プロパティをちょうど 1 回読み、ラベル集合は検査した値そのものから作る。
 - `CONTACT_MAP_LABEL_KEYS` 外の自身のキーは、最も近いキーを示す短い `RangeError` (`[contact-map] labels has a key that is not a label key (did you mean "searchTab"? CONTACT_MAP_LABEL_KEYS lists every key); got "serchTab"`)。
@@ -280,13 +376,19 @@ export default function ContactMapRoute() {
 - 設定の検査 (`locale`・`labels`・`streamEndpoint`・`workerUrls`・サーバーの設定・行数・`getContactsStreamChunkQuery` か `createContactMapServer().getContactsStreamChunk` に渡す再開カーソル (文言ではどちらも `getContactsStreamChunkQuery cursor`)・代替名) は、型や形の誤り (必須の設定が無い場合を含む) を `TypeError`、型は合うが許されない値 (設定が受け取らないキーを含む) を `RangeError` にする。設定は面の呼び名で名指し (`labels`・`ContactMapAppView labels`・`server config firstBatchSize`)、末尾は `; got <値>` で、拒否した値か拒否したキーをどこでも同じ表記で書く (引用符付きの文字列・`undefined`・`null`・`-0`・`10n`・`Symbol(x)`・`[object URL]`)。
 - ブラウザのタブの 2 つのビューが `streamEndpoint` か `workerUrls.treeWorker` で食い違う場合と、`workerUrls.treeWorker` の無い CommonJS のビルドは、どの値 1 つが誤りでもないので素の `Error`。
 - 単位キー (`recordUnit`、`companyUnit`、`resultUnit`、`timesUnit`、`itemsUnit`、`charactersUnit`) は表示どおりの数値文字列 (`"1"`、`"1,001"`、`"1.0"`) を受け取るため、英語の単数 / 複数は読み手が見る値に従う (単数は表示 `"1"` のときだけで `"1.0 items"`)。`timesUnit` / `itemsUnit` / `charactersUnit` / `throughputUnit` は数値の直後に区切りなしで連結されるため、先頭の空白は単位側が持つ。
-- エンジン 7 キーと行種別語 2 キーも、`@aiquants/virtualscroll` と `@aiquants/directory-tree` へ渡す前にここで同じ規則で検査するので、その例外もパッケージの規則に従う。
-- 結果は凍結される。一覧の VirtualScroll にはエンジン 7 キーだけ、DirectoryTree には 9 キーだけを値安定のまま渡すため、毎レンダー作り直すインライン `labels` でも埋込みスクロールのクロームは再構築されない。
+- 埋込みキー (`@aiquants/virtualscroll` の `VIRTUAL_SCROLL_LABEL_KEYS` と `@aiquants/directory-tree` の行種別語。合わせて `DIRECTORY_TREE_LABEL_KEYS`) も、それらのパッケージへ渡す前にここで同じ規則で検査するので、その例外もパッケージの規則に従う。
+- 結果は凍結される。一覧の VirtualScroll には `VIRTUAL_SCROLL_LABEL_KEYS` のキーだけ、DirectoryTree には `DIRECTORY_TREE_LABEL_KEYS` のキーだけを値安定のまま渡すため、毎レンダー作り直すインライン `labels` でも埋込みスクロールのクロームは再構築されない。
 
 ### Chrome locale and number formatting / クロームロケールと数値書式
 
-`locale` is the UI chrome language (`"en"` | `"ja"`), not a BCP 47 tag. contact-map has no separate formatting-locale prop (`formatLocale`): the chrome locale also fixes digit grouping through a spec-defined mapping, `en` → `"en-US"` and `ja` → `"ja-JP"`. Every count the package renders (annotation, registered / result counts, tree node counts, member counts in the tree, statistics) is grouped with that tag, never with the runtime default locale, so the server render and the browser render agree. Dates keep their ISO-based format.
-`locale` は UI クロームの言語 (`"en"` | `"ja"`) で BCP 47 タグではない。contact-map には書式ロケール専用の prop (`formatLocale`) は無く、クロームロケールが仕様で定めた対応 (`en` → `"en-US"`、`ja` → `"ja-JP"`) で桁区切りも決める。パッケージが描画する件数 (注記、登録件数 / 検索結果件数、ツリーのノード数・所属人数、統計) はすべてこのタグで桁区切りし、実行環境の既定ロケールは使わないため、サーバー描画とブラウザ描画が一致する。日付は ISO ベースの書式のまま。
+`locale` is the UI chrome language (`"en"` | `"ja"`), not a BCP 47 tag. contact-map has no separate formatting-locale prop (`formatLocale`): the chrome locale also fixes digit grouping through a spec-defined mapping, `en` → `"en-US"` and `ja` → `"ja-JP"`. Every count the package renders (annotation, registered / result counts, tree node counts, member counts in the tree, statistics) is grouped with that tag, never with the runtime default locale, so the server render and the browser render agree.
+`locale` は UI クロームの言語 (`"en"` | `"ja"`) で BCP 47 タグではない。contact-map には書式ロケール専用の prop (`formatLocale`) は無く、クロームロケールが仕様で定めた対応 (`en` → `"en-US"`、`ja` → `"ja-JP"`) で桁区切りも決める。パッケージが描画する件数 (注記、登録件数 / 検索結果件数、ツリーのノード数・所属人数、統計) はすべてこのタグで桁区切りし、実行環境の既定ロケールは使わないため、サーバー描画とブラウザ描画が一致する。
+
+### Dates / 日時
+
+A record's timestamps (`contacted_at`, `created_at`, `updated_at`) are written as the database stores them. The driver reads a zone-less `datetime2` value as UTC (the mssql driver's default, `useUTC: true`), so the stream carries a stored `2026-10-03 09:00:00` as `2026-10-03T09:00:00.000Z`, and the default `recordDateTime` / `recordDate` labels (`formatStoredDateTime` / `formatStoredDate`, exported from `@aiquants/contact-map`) write its UTC fields without a zone (`2026-10-03 09:00:00`, `2026-10-03`), the same in every locale and in every browser time zone.
+The statistics panel's "Statistics updated at" is a moment of the browser session, so its default `statsTimestamp` label (`formatLocalDateTime`) writes the browser's local time. A host overrides any of the three through `labels` (each receives a `Date`); a timestamp that is not a date is shown as it came, and a missing one as `-`.
+レコードの日時 (`contacted_at`・`created_at`・`updated_at`) はデータベースが保存しているとおりに書く。ドライバはゾーンの無い `datetime2` の値を UTC として読む (mssql のドライバの既定 `useUTC: true`) ので、ストリームは保存された `2026-10-03 09:00:00` を `2026-10-03T09:00:00.000Z` として運び、既定の `recordDateTime` / `recordDate` ラベル (`formatStoredDateTime` / `formatStoredDate`。`@aiquants/contact-map` から公開) は UTC の各欄をゾーンを付けずに書く (`2026-10-03 09:00:00`・`2026-10-03`)。どのロケールでも、ブラウザのどの時間帯でも同じ。統計パネルの「統計更新時刻」はブラウザのセッションの中の時刻なので、既定の `statsTimestamp` ラベル (`formatLocalDateTime`) はブラウザの現地時刻で書く。ホストは 3 つのどれも `labels` で上書きできる (どれも `Date` を受け取る)。日時として読めない値は届いたまま、無い値は `-` と表示する。
 
 ### Tree fallback names / ツリーの代替名
 
@@ -309,8 +411,8 @@ Not part of the catalog / カタログ対象外:
 
 ### Catalog / カタログ
 
-Function keys are shown with their arguments; the cells show sample output (`count = 2`, `displayed = "2"`, `loaded = 1200`, `name = "<name>"`, `memberCount = 1200`, `fieldLabel = "<label>"`).
-関数キーは引数付きで示し、セルには出力例 (`count = 2`、`displayed = "2"`、`loaded = 1200`、`name = "<name>"`、`memberCount = 1200`、`fieldLabel = "<label>"`) を載せる。
+Function keys are shown with their arguments; the cells show sample output (`count = 2`, `displayed = "2"`, `loaded = 1200`, `name = "<name>"`, `memberCount = 1200`, `fieldLabel = "<label>"`, `value = new Date("2026-10-03T09:00:00Z")` in a browser at UTC+9).
+関数キーは引数付きで示し、セルには出力例 (`count = 2`、`displayed = "2"`、`loaded = 1200`、`name = "<name>"`、`memberCount = 1200`、`fieldLabel = "<label>"`、UTC+9 のブラウザで `value = new Date("2026-10-03T09:00:00Z")`) を載せる。
 
 | Key | en | ja |
 | --- | --- | --- |
@@ -318,6 +420,10 @@ Function keys are shown with their arguments; the cells show sample output (`cou
 | `scrollDown` | `"Scroll down"` | `"下へスクロール"` |
 | `scrollLeft` | `"Scroll left"` | `"左へスクロール"` |
 | `scrollRight` | `"Scroll right"` | `"右へスクロール"` |
+| `verticalScrollBar` | `"Vertical"` | `"縦方向"` |
+| `horizontalScrollBar` | `"Horizontal"` | `"横方向"` |
+| `verticalScrollThumb` | `"Vertical scroll position"` | `"縦スクロール位置"` |
+| `horizontalScrollThumb` | `"Horizontal scroll position"` | `"横スクロール位置"` |
 | `scrollToTop` | `"Top"` | `"先頭へ"` |
 | `scrollToBottom` | `"Bottom"` | `"末尾へ"` |
 | `noItems` | `"No items"` | `"項目がありません"` |
@@ -329,6 +435,8 @@ Function keys are shown with their arguments; the cells show sample output (`cou
 | `annotationStreamingProgress({ loaded, total, percent })` | `"Streaming (1,200 / 4,800 · 25%)"` | `"ストリーミング読み込み中 (1,200 / 4,800 件・25%)"` |
 | `annotationStreamingCount(loaded)` | `"Streaming (1,200 loaded)"` | `"ストリーミング読み込み中 (1,200 件)"` |
 | `annotationLoadFailed(loaded)` | `"Failed to load (1,200 received)"` | `"読み込みに失敗しました (1,200 件受信済)"` |
+| `annotationReconnecting(loaded)` | `"Reconnecting (1,200 received)"` | `"再接続中 (1,200 件受信済)"` |
+| `annotationAuthRequired` | `"Session expired: sign in again, then retry"` | `"セッションが切れました。サインインし直してから再試行してください"` |
 | `annotationRetry` | `"Retry"` | `"再試行"` |
 | `recordUnit(displayed)` | `"records"` | `"件"` |
 | `companyUnit(displayed)` | `"companies"` | `"社"` |
@@ -426,6 +534,8 @@ Function keys are shown with their arguments; the cells show sample output (`cou
 | `fieldCreatedAt` | `"Created at"` | `"作成日時"` |
 | `fieldUpdatedBy` | `"Updated by"` | `"更新者"` |
 | `fieldUpdatedAt` | `"Updated at"` | `"更新日時"` |
+| `recordDateTime(value)` | `"2026-10-03 09:00:00"` | `"2026-10-03 09:00:00"` |
+| `recordDate(value)` | `"2026-10-03"` | `"2026-10-03"` |
 | `popupCustomMobilePhone` | `"Mobile (custom)"` | `"携帯電話 (カスタム)"` |
 | `popupMobilePhone` | `"Mobile"` | `"携帯電話"` |
 | `popupCustomCompanyPhone` | `"Company phone (custom)"` | `"会社電話 (カスタム)"` |
@@ -552,6 +662,7 @@ Function keys are shown with their arguments; the cells show sample output (`cou
 | `statLastSearchTime` | `"Last search time"` | `"最後の検索時間"` |
 | `statErrorCount` | `"Errors"` | `"エラー数"` |
 | `statUpdatedAt` | `"Statistics updated at"` | `"統計更新時刻"` |
+| `statsTimestamp(value)` | `"2026-10-03 18:00:00"` | `"2026-10-03 18:00:00"` |
 | `statsOperationsHeading` | `"Operations"` | `"操作統計"` |
 | `statTotalOperations` | `"Total operations"` | `"総操作数"` |
 | `statsIndexHeading` | `"Index statistics"` | `"インデックス統計"` |
@@ -606,56 +717,6 @@ Function keys are shown with their arguments; the cells show sample output (`cou
 | `charactersUnit(displayed)` | `" characters"` | `" 文字"` |
 | `throughputUnit` | `" ops/s"` | `" ops/秒"` |
 
-### Migrating from 0.1.x to 0.2.0 / 0.1.x から 0.2.0 への移行
-
-Breaking changes / 破壊的変更:
-
-- **Default chrome language is `en`.** Hosts that relied on the former Japanese chrome must opt in with `locale="ja"` on `ContactMapAppView` or `config.locale = "ja"` in `ContactMapConfigProvider`. `locale` is the chrome language only; there is no `formatLocale` prop (digit grouping follows `locale`, see above).
-- **Invalid chrome settings fail fast.** When the provider or the view mounts, an unsupported `locale` string (`"ja-JP"`, `"EN"`, `""`, ...), an unknown label key or a blank label throws a `RangeError`, and a value of the wrong type (a non-string `locale`, a `labels` that is not a plain object, a non-string for a string key, a non-function for a function key) a `TypeError`.
-- **`WorkerStatsSection`** takes `kind: "index" | "levenshtein"` instead of `title: string`.
-- **`SwipeOverlay`'s `title`** no longer defaults to `"詳細"` and **`ContactMapAppView`'s `title`** has no hard-coded default; omitted, they use the `overlayTitle` / `appTitle` labels.
-- **Tree builder API.** `new IncrementalTreeBuilder(naming)` and `buildDirectoryTree(records, naming)` require `naming: ContactMapTreeNaming`. A directory entry's `name` is now the bare company / department name and its member count is `memberCount` (the former `"<name> (N)"` is composed by the client with `treeDirectoryName`).
-- **Tree worker API.** `TreeWorkerSession.syncRecords(records, naming)` and `syncTreeWorkerRecords(records, naming)` take the names; the `RESET_TREE` message carries `naming` and must precede a generation's `APPEND_RECORDS` / `FINALIZE_TREE` (the worker throws otherwise). `useTreeWorker(records, isComplete)` keeps its signature and reads the names from the provider.
-- **Fallback names are chrome.** In `en` a contact without a company is under `"Uncategorized"` and a nameless person is `"(No Name)"` everywhere (formerly the fixed Japanese `未分類` / `名前未設定` in the tree). With `locale="ja"` they stay `未分類` / `名前未設定`; `noName` in the detail panel, popup and list is `名前未設定` too.
-- **Counts are grouped with `"en-US"` / `"ja-JP"`** by chrome locale instead of the runtime default; the registered count, the result count and the total search count are now grouped as well (`1,234` instead of `1234`).
-- **Peer floors.** `@aiquants/virtualscroll` ^3.7.0, `@aiquants/directory-tree` ^3.12.0 and `@aiquants/select-box` ^0.10.0 (all expanded from `workspace:^` at publish). contact-map uses only the text normalization helpers of select-box and renders no `SelectBox`, so the select-box floor comes from the `workspace:^` expansion, not from a new API.
-
-- **既定のクローム言語は `en`。** 従来の日本語クロームに依存していたホストは `ContactMapAppView` に `locale="ja"`、または `ContactMapConfigProvider` の `config.locale = "ja"` で明示的に選ぶ。`locale` はクローム言語だけで、`formatLocale` prop は無い (桁区切りは `locale` に従う。上記参照)。
-- **不正なクローム設定は即座に失敗。** プロバイダーかビューのマウント時に、非対応の `locale` の文字列 (`"ja-JP"`、`"EN"`、`""` など)・未知のラベルキー・空白のラベルは `RangeError`、型の誤り (文字列でない `locale`、素の object でない `labels`、文字列キーに文字列以外、関数キーに関数以外) は `TypeError`。
-- **`WorkerStatsSection`** は `title: string` の代わりに `kind: "index" | "levenshtein"` を受け取る。
-- **`SwipeOverlay` の `title`** は `"詳細"` を既定にせず、**`ContactMapAppView` の `title`** も固定の既定値を持たない。省略時は `overlayTitle` / `appTitle` ラベル。
-- **ツリービルダー API。** `new IncrementalTreeBuilder(naming)` と `buildDirectoryTree(records, naming)` は `naming: ContactMapTreeNaming` が必須。ディレクトリエントリの `name` は会社名 / 部署名そのもので、所属人数は `memberCount` (従来の `"<名前> (N)"` はクライアントが `treeDirectoryName` で組み立てる)。
-- **ツリー Worker API。** `TreeWorkerSession.syncRecords(records, naming)` と `syncTreeWorkerRecords(records, naming)` は代替名を受け取る。`RESET_TREE` メッセージは `naming` を運び、世代の `APPEND_RECORDS` / `FINALIZE_TREE` より先に送ることが必須 (違反すると Worker が例外)。`useTreeWorker(records, isComplete)` のシグネチャは変わらず、代替名はプロバイダーから読む。
-- **代替名はクローム。** `en` では会社名の無い連絡先は `"Uncategorized"` の下、氏名の無い人物はどこでも `"(No Name)"` (従来ツリーでは固定の日本語 `未分類` / `名前未設定`)。`locale="ja"` では `未分類` / `名前未設定` のままで、詳細パネル・ポップアップ・一覧の `noName` も `名前未設定`。
-- **件数はクロームロケールに応じて `"en-US"` / `"ja-JP"` で桁区切り** (実行環境の既定ではない)。登録件数・検索結果件数・総検索回数も桁区切りされる (`1234` ではなく `1,234`)。
-- **ピア下限。** `@aiquants/virtualscroll` ^3.7.0、`@aiquants/directory-tree` ^3.12.0、`@aiquants/select-box` ^0.10.0 (いずれも公開時に `workspace:^` から展開)。contact-map は select-box のテキスト正規化関数だけを使い `SelectBox` を描画しないため、select-box の下限は新 API ではなく `workspace:^` の展開による。
-
-New API / 新しい API:
-
-- `locale` and `labels` on `ContactMapConfig` and `ContactMapAppViewProps`; `@aiquants/contact-map/client` exports `CONTACT_MAP_LABEL_KEYS`, `CONTACT_MAP_LABEL_CATALOGS`, `resolveContactMapLabels`, `useContactMapLabels` and the types `ContactMapLocale`, `ContactMapLabels`, `ContactMapOwnLabels`, `ContactMapLabelOverrides`, `ContactMapStreamProgress`, `ContactMapQueryLengthStat`, `ContactMapHistoryEntry`, `WorkerStatsKind`.
-- `@aiquants/contact-map` exports `ContactMapTreeNaming` and `assertContactMapTreeNaming`; `ContactMapDirectoryEntry` gains `memberCount`.
-- `ContactMapConfig` と `ContactMapAppViewProps` の `locale` / `labels`。`@aiquants/contact-map/client` から `CONTACT_MAP_LABEL_KEYS`、`CONTACT_MAP_LABEL_CATALOGS`、`resolveContactMapLabels`、`useContactMapLabels` と型 `ContactMapLocale`、`ContactMapLabels`、`ContactMapOwnLabels`、`ContactMapLabelOverrides`、`ContactMapStreamProgress`、`ContactMapQueryLengthStat`、`ContactMapHistoryEntry`、`WorkerStatsKind` を公開。
-- `@aiquants/contact-map` から `ContactMapTreeNaming` と `assertContactMapTreeNaming` を公開し、`ContactMapDirectoryEntry` に `memberCount` を追加。
-
-```tsx
-// before (0.1.x): Japanese chrome without any prop
-<ContactMapAppView renderHeader={renderHeader} workerUrls={workerUrls} />
-
-// after (0.2.0): opt into the Japanese catalog explicitly
-<ContactMapAppView locale="ja" renderHeader={renderHeader} workerUrls={workerUrls} />
-```
-
-```ts
-// before (0.1.x)
-const { tree } = buildDirectoryTree(records)
-session.syncRecords(records)
-
-// after (0.2.0): pass the fallback names of the chrome locale
-const naming = { uncategorizedCompany: labels.uncategorizedCompany, unnamedPerson: labels.noName }
-const { tree } = buildDirectoryTree(records, naming)
-session.syncRecords(records, naming)
-```
-
 ---
 
 ## License / ライセンス

package/dist/client.d.mts

@@ -7,7 +7,8 @@ import * as _aiquants_virtualscroll from "@aiquants/virtualscroll";
 import { VirtualScrollLocale } from "@aiquants/virtualscroll";
 import * as _aiquants_fuzzy_search from "@aiquants/fuzzy-search";
 import { UseFuzzySearchOptions as UseFuzzySearchOptions$1, UnifiedWorkerStats } from "@aiquants/fuzzy-search";
-import { R as ResponsiveLayoutSpec, a as ResponsiveThresholds, C as ContactMapDirectoryEntry, b as ContactRecordForTree, c as ContactMapTreeNaming } from "./tree-types-CDq16q63.mjs";
+import { R as ResponsiveThresholds, C as ContactMapDirectoryEntry, a as ContactRecordForTree, b as ContactMapTreeNaming } from "./tree-types-B9J5unS2.mjs";
+import * as _aiquants_route_revalidation from "@aiquants/route-revalidation";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 interface AdvancedSearchSettingsProps {
     searchOptions: UseFuzzySearchOptions;
@@ -93,6 +94,7 @@ type ContactMapOwnLabels = {
     readonly annotationStreamingProgress: (progress: ContactMapStreamProgress) => string;
     readonly annotationStreamingCount: (loaded: number) => string;
     readonly annotationLoadFailed: (loaded: number) => string;
+    readonly annotationReconnecting: (loaded: number) => string;
     readonly annotationAuthRequired: string;
     readonly annotationRetry: string;
     readonly recordUnit: (displayed: string) => string;
@@ -191,6 +193,8 @@ type ContactMapOwnLabels = {
     readonly fieldCreatedAt: string;
     readonly fieldUpdatedBy: string;
     readonly fieldUpdatedAt: string;
+    readonly recordDateTime: (value: Date) => string;
+    readonly recordDate: (value: Date) => string;
     readonly popupCustomMobilePhone: string;
     readonly popupMobilePhone: string;
     readonly popupCustomCompanyPhone: string;
@@ -317,6 +321,7 @@ type ContactMapOwnLabels = {
     readonly statLastSearchTime: string;
     readonly statErrorCount: string;
     readonly statUpdatedAt: string;
+    readonly statsTimestamp: (value: Date) => string;
     readonly statsOperationsHeading: string;
     readonly statTotalOperations: string;
     readonly statsIndexHeading: string;
@@ -536,7 +541,6 @@ interface ContactMapConfig {
     openEmailsWithGmail?: boolean;
     treeWorkerFactory?: () => Worker;
     workerUrls?: ContactMapWorkerUrls;
-    layoutSpec?: Partial<ResponsiveLayoutSpec>;
     locale?: ContactMapLocale;
     labels?: ContactMapLabelOverrides;
 }
@@ -706,7 +710,7 @@ declare const getTreeWorkerSession: (treeWorkerUrl?: string) => TreeWorkerSessio
 declare const resetTreeWorkerSessionForTesting: () => void;
 declare function useTreeWorker(records: readonly ContactRecordForTree[], isComplete?: boolean): TreeWorkerState;
 declare const useContactMapLabels: () => ContactMapLabels;
-declare function contactMapShouldRevalidate(): boolean;
+declare const contactMapShouldRevalidate: _aiquants_route_revalidation.RouteShouldRevalidate;
 type ProgressProps = react.ComponentPropsWithoutRef<"div"> & {
     value?: number;
     max?: number;
@@ -719,7 +723,6 @@ interface SwipeOverlayProps {
     children: ReactNode;
     className?: string;
     title?: string;
-    direction?: "bottom" | "top" | "left" | "right";
 }
 declare const SwipeOverlay: ({ isOpen, onClose, children, className, title }: SwipeOverlayProps) => react.JSX.Element | null;
 declare const Tabs: react.ForwardRefExoticComponent<TabsPrimitive.TabsProps & react.RefAttributes<HTMLDivElement>>;

package/dist/client.d.ts

@@ -7,7 +7,8 @@ import * as _aiquants_virtualscroll from "@aiquants/virtualscroll";
 import { VirtualScrollLocale } from "@aiquants/virtualscroll";
 import * as _aiquants_fuzzy_search from "@aiquants/fuzzy-search";
 import { UseFuzzySearchOptions as UseFuzzySearchOptions$1, UnifiedWorkerStats } from "@aiquants/fuzzy-search";
-import { R as ResponsiveLayoutSpec, a as ResponsiveThresholds, C as ContactMapDirectoryEntry, b as ContactRecordForTree, c as ContactMapTreeNaming } from "./tree-types-CDq16q63.js";
+import { R as ResponsiveThresholds, C as ContactMapDirectoryEntry, a as ContactRecordForTree, b as ContactMapTreeNaming } from "./tree-types-B9J5unS2.js";
+import * as _aiquants_route_revalidation from "@aiquants/route-revalidation";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 interface AdvancedSearchSettingsProps {
     searchOptions: UseFuzzySearchOptions;
@@ -93,6 +94,7 @@ type ContactMapOwnLabels = {
     readonly annotationStreamingProgress: (progress: ContactMapStreamProgress) => string;
     readonly annotationStreamingCount: (loaded: number) => string;
     readonly annotationLoadFailed: (loaded: number) => string;
+    readonly annotationReconnecting: (loaded: number) => string;
     readonly annotationAuthRequired: string;
     readonly annotationRetry: string;
     readonly recordUnit: (displayed: string) => string;
@@ -191,6 +193,8 @@ type ContactMapOwnLabels = {
     readonly fieldCreatedAt: string;
     readonly fieldUpdatedBy: string;
     readonly fieldUpdatedAt: string;
+    readonly recordDateTime: (value: Date) => string;
+    readonly recordDate: (value: Date) => string;
     readonly popupCustomMobilePhone: string;
     readonly popupMobilePhone: string;
     readonly popupCustomCompanyPhone: string;
@@ -317,6 +321,7 @@ type ContactMapOwnLabels = {
     readonly statLastSearchTime: string;
     readonly statErrorCount: string;
     readonly statUpdatedAt: string;
+    readonly statsTimestamp: (value: Date) => string;
     readonly statsOperationsHeading: string;
     readonly statTotalOperations: string;
     readonly statsIndexHeading: string;
@@ -536,7 +541,6 @@ interface ContactMapConfig {
     openEmailsWithGmail?: boolean;
     treeWorkerFactory?: () => Worker;
     workerUrls?: ContactMapWorkerUrls;
-    layoutSpec?: Partial<ResponsiveLayoutSpec>;
     locale?: ContactMapLocale;
     labels?: ContactMapLabelOverrides;
 }
@@ -706,7 +710,7 @@ declare const getTreeWorkerSession: (treeWorkerUrl?: string) => TreeWorkerSessio
 declare const resetTreeWorkerSessionForTesting: () => void;
 declare function useTreeWorker(records: readonly ContactRecordForTree[], isComplete?: boolean): TreeWorkerState;
 declare const useContactMapLabels: () => ContactMapLabels;
-declare function contactMapShouldRevalidate(): boolean;
+declare const contactMapShouldRevalidate: _aiquants_route_revalidation.RouteShouldRevalidate;
 type ProgressProps = react.ComponentPropsWithoutRef<"div"> & {
     value?: number;
     max?: number;
@@ -719,7 +723,6 @@ interface SwipeOverlayProps {
     children: ReactNode;
     className?: string;
     title?: string;
-    direction?: "bottom" | "top" | "left" | "right";
 }
 declare const SwipeOverlay: ({ isOpen, onClose, children, className, title }: SwipeOverlayProps) => react.JSX.Element | null;
 declare const Tabs: react.ForwardRefExoticComponent<TabsPrimitive.TabsProps & react.RefAttributes<HTMLDivElement>>;