@aiquants/daily-report 0.7.0 → 0.8.0

package/src/client/contexts/daily-report-action-context.tsx

@@ -3,13 +3,13 @@
  * 日報の楽観的 CRUD と SSE 同期を提供するアクションコンテキスト。
  */
 import { type Context, createContext, type ReactNode, useCallback, useContext, useEffect, useRef, useState } from "react"
-import { useRevalidator } from "react-router"
 import { createLogger, LogLevel } from "../../shared/logger"
 import type { DailyReportSseMessage } from "../../shared/sse-schema"
 import type { DailyReportCommentItem, DailyReportDetail, DailyReportItem, DailyReportUser } from "../../shared/types"
 import { useDailyReportConfig } from "../config-context"
 import { acquireMutationLock, applyDailyReportServerUpdates, clearDailyReportCache, DailyReportCache, deleteDailyReportCache, getCachedReport, registerRecentDeletion, releaseMutationLock, subscribeCacheReady, updateDailyReportCache, writeCache } from "../hooks/use-daily-report"
 import { useDailyReportSseConnection } from "../hooks/use-daily-report-sse-connection"
+import { getDailyReportIdsStreamSessionUserKey, refreshDailyReportIdsStream, removeDailyReportIdsStreamItem, upsertDailyReportIdsStreamItem, useDailyReportIdsStream } from "../streaming/daily-report-ids-stream-session"
 
 const logger = createLogger(LogLevel.INFO, "daily-report-action-context")
 
@@ -25,7 +25,7 @@ type ActionResponse = {
     [key: string]: unknown
 }
 
-type DailyReportActionContextType = {
+export type DailyReportActionContextType = {
     /** 表示中ユーザー (楽観的コメントの作者名等に使用)。 */
     user?: DailyReportUser
     /** reportHubId -> Map<tempCommentId, content> (追加コメントの一時IDと内容) */
@@ -137,18 +137,35 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
     /** 自分が発行したアクションのID（SSEエコー無視用） */
     const processedClientTempIds = useRef<Set<string>>(new Set())
 
-    const revalidator = useRevalidator()
+    // トゥームストーン掃除のゲート参照。ストリーミング途中の部分配列で掃除すると、
+    // 後続チャンク到着前に削除された ID のトゥームストーンが失われ、遅れて届いた
+    // 削除前スナップショットのチャンクで日報が復活する (effect の依存を増やさないため ref 経由)
+    const streamState = useDailyReportIdsStream()
+    const isStreamSettledRef = useRef(false)
+    isStreamSettledRef.current = streamState.phase === "complete" && !streamState.isRevalidating
+
+    /**
+     * 遅延解決するミューテーション継続の門番。POST /action の待機中にリロード無しの
+     * ユーザー切替が起きた場合、この判定が偽になり、継続はモジュール常駐状態
+     * (常駐ストリームセッション・DailyReportCache・ミューテーションロック) への
+     * 書き込みを放棄する。放棄しないと、旧ユーザーの日報行が新ユーザーの一覧へ
+     * 注入され (観測集合に刻まれて完走剪定も免れる)、切替時に破棄したはずの
+     * 詳細キャッシュへ旧ユーザーの下書き本文が再シードされる (実測再現済み)。
+     * 同一ユーザーの通常ナビゲーション (アンマウント) ではセッションが生き続けるため
+     * 真のままであり、作成直後の日報が常駐データから欠ける round-3 の退行は起こさない。
+     */
+    const isSessionStillOurs = useCallback(() => getDailyReportIdsStreamSessionUserKey() === (userId ?? null), [userId])
 
     const refetchData = useCallback(async () => {
         logger.info("[DailyReportActionProvider] Refetching data without page reload...")
-        if (revalidator.state === "idle") {
-            revalidator.revalidate()
-        }
+        // ID 一覧はストリームセッションのバックグラウンド再検証で更新する
+        // (ルーター再検証は dailyReportShouldRevalidate に抑止されるため使わない)
+        refreshDailyReportIdsStream()
         setVersion((v) => v + 1)
         DailyReportCache.listeners.forEach((listener: (id: number) => void) => {
             listener(-1)
         })
-    }, [revalidator])
+    }, [])
 
     const clearCacheAndRefetch = useCallback(async () => {
         logger.info("[DailyReportActionProvider] Clearing client & server/DB cache and refetching data without page reload...")
@@ -175,15 +192,16 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
             logger.warn("[DailyReportActionProvider] Failed to clear server-side cache:", e)
         }
 
-        // 3. ルートローダーの再フェッチ & UI 再描画
-        if (revalidator.state === "idle") {
-            revalidator.revalidate()
-        }
+        // 3. ID 一覧ストリームをサーバーキャッシュバイパスで再検証 & UI 再描画。
+        // POST 待機中にユーザー切替が起きた場合は放棄する (新ユーザーのストリームを
+        // 冗長に強制再ダウンロードさせない)
+        if (!isSessionStillOurs()) return
+        refreshDailyReportIdsStream({ forceRefresh: true })
         setVersion((v) => v + 1)
         DailyReportCache.listeners.forEach((listener: (id: number) => void) => {
             listener(-1)
         })
-    }, [apiBasePath, revalidator])
+    }, [apiBasePath, isSessionStillOurs])
 
     /**
      * Queue for SSE messages that arrived before the target report was cached.
@@ -281,6 +299,11 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
      * レポートアイテムをリストへ upsert し、businessDate 降順を維持します。
      */
     const upsertItem = useCallback((reportHubId: number, businessDate: string | null | undefined) => {
+        // モジュール常駐ストリームセッションへも反映する (鮮度窓内の再訪で作成直後の日報が
+        // 消えないように)。businessDate 未指定は「既存値を保持」の意図なので中継しない
+        if (businessDate !== undefined) {
+            upsertDailyReportIdsStreamItem({ reportHubId, businessDate: businessDate ?? null })
+        }
         setItems((prev) => {
             const nextBusinessDate = businessDate ?? prev.find((item) => item.reportHubId === reportHubId)?.businessDate ?? null
             const exists = prev.some((item) => item.reportHubId === reportHubId)
@@ -304,59 +327,101 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
      * Remove a stale item from the list as a safety net.
      * フェッチ後にレポートが見つからなかった場合の安全弁としてアイテムを除去する。
      */
-    const removeStaleItem = useCallback((reportHubId: number) => {
-        removedIds.current.add(reportHubId)
-        setItems((prev) => prev.filter((item) => item.reportHubId !== reportHubId))
-    }, [])
+    const removeStaleItem = useCallback(
+        (reportHubId: number) => {
+            // ユーザー切替後の遅延発火は新ユーザーのセッションへトゥームストーンを刻んでしまう
+            if (!isSessionStillOurs()) return
+            removedIds.current.add(reportHubId)
+            // 常駐ストリームデータからも除去する (再訪時に安全弁が再発動し続けるのを防ぐ)
+            removeDailyReportIdsStreamItem(reportHubId)
+            setItems((prev) => prev.filter((item) => item.reportHubId !== reportHubId))
+        },
+        [isSessionStillOurs],
+    )
 
     /**
-     * Merge initialItems with prevItems instead of replacing.
+     * Merge initialItems with prevItems instead of replacing (render-phase derived state).
      * Items already in the list are kept even if temporarily absent from the API response.
      * Removal is handled exclusively by the report-delete SSE handler.
      *
-     * initialItems と prevItems をマージする（全置換ではない）。
-     * API レスポンスから一時的に欠落した ID も prevItems に残っていれば保持する。
-     * 削除は report-delete SSE ハンドラーでのみ行う。
+     * initialItems と prevItems をマージする (全置換ではない)。render-phase の
+     * 派生状態パターン (prev 比較 + render 中の setState) で行うことが重要 —
+     * effect で行うと「最初のチャンクのコミットは items が空 (VirtualScroll が
+     * 一瞬 No items を描画) → effect 後の 2 コミット目で行が出る」という
+     * 1 コミット分の遅延と空表示フラッシュが生まれる。render 中の setState は
+     * React が子のコミット前に同一コンポーネントを再レンダーする公式パターン。
+     * マージは純粋 (ref は読み取りのみ)。StrictMode の二重レンダーにも冪等。
      */
-    // initialItems と prevItems のマージ — 削除済み ID の復活を防止する
-    // 外部リソース同期: React Router loader の initialItems 更新に反応する
-    useEffect(() => {
-        // initialItems に含まれない removedIds エントリは不要なのでクリーンアップ
-        const initialIds = new Set(initialItems.map((item) => item.reportHubId))
-        // Set のイテレーション中の delete は JS 仕様で安全 (visited は再訪問しない)
-        for (const id of removedIds.current) {
-            if (!initialIds.has(id)) {
-                removedIds.current.delete(id)
+    const [prevInitialItems, setPrevInitialItems] = useState(initialItems)
+    if (initialItems !== prevInitialItems) {
+        setPrevInitialItems(initialItems)
+        // initialItems をベースにマップを構築 (removedIds を除外)
+        const mergedMap = new Map<number, DailyReportItem>()
+        for (const item of initialItems) {
+            if (!removedIds.current.has(item.reportHubId)) {
+                mergedMap.set(item.reportHubId, item)
             }
         }
-
-        setItems((prevItems) => {
-            // initialItems をベースにマップを構築（removedIds を除外）
-            const mergedMap = new Map<number, DailyReportItem>()
-            for (const item of initialItems) {
-                if (!removedIds.current.has(item.reportHubId)) {
-                    mergedMap.set(item.reportHubId, item)
-                }
+        // 現在の items にのみ存在する ID を保持 (削除は report-delete SSE で行う)
+        for (const item of items) {
+            if (!(mergedMap.has(item.reportHubId) || removedIds.current.has(item.reportHubId))) {
+                mergedMap.set(item.reportHubId, item)
             }
+        }
+        // businessDate 降順でソート。正規化済み YYYY-MM-DD は辞書順 = 時系列順なので
+        // 文字列比較で足りる (Date 構築はチャンク到着ごとの全件ソートで比較 1 回あたり
+        // 2 個生成され、数万件 × 数十チャンクで数百万回の構築になる)。null は末尾。
+        // ストリームはソート順どおりに届き末尾へ追記されるため、通常は整列済み —
+        // O(n) の検査で確認できたらソートを丸ごと省略する (20 万件級で毎 publish の
+        // O(n log n) を O(n) へ落とす)
+        const merged = Array.from(mergedMap.values())
+        let isSorted = true
+        for (let i = 1; i < merged.length; i++) {
+            if ((merged[i - 1].businessDate ?? "") < (merged[i].businessDate ?? "")) {
+                isSorted = false
+                break
+            }
+        }
+        if (!isSorted) {
+            merged.sort((a, b) => {
+                const left = a.businessDate ?? ""
+                const right = b.businessDate ?? ""
+                if (left === right) return 0
+                return left < right ? 1 : -1
+            })
+        }
+        setItems(merged)
+    }
 
-            // prevItems にのみ存在する ID を保持（削除は report-delete SSE で行う）
-            for (const item of prevItems) {
-                if (!(mergedMap.has(item.reportHubId) || removedIds.current.has(item.reportHubId))) {
-                    mergedMap.set(item.reportHubId, item)
+    /**
+     * トゥームストーン (removedIds) のクリーンアップ副作用。
+     * ストリームの全量が出揃っている (complete かつ再検証中でない) ときにのみ行う。
+     * 部分配列からの欠落は「サーバーに存在しない」証拠にならない。
+     * 依存配列: initialItems (チャンク到着・再検証ごと)。クリーンアップ: なし。
+     * ref の変異を伴うため render-phase ではなく effect に置く。
+     */
+    useEffect(() => {
+        if (isStreamSettledRef.current) {
+            const initialIds = new Set(initialItems.map((item) => item.reportHubId))
+            // Set のイテレーション中の delete は JS 仕様で安全 (visited は再訪問しない)
+            for (const id of removedIds.current) {
+                if (!initialIds.has(id)) {
+                    removedIds.current.delete(id)
                 }
             }
-
-            // businessDate 降順でソート
-            return Array.from(mergedMap.values()).sort((a, b) => {
-                const dateA = a.businessDate ? new Date(a.businessDate).getTime() : 0
-                const dateB = b.businessDate ? new Date(b.businessDate).getTime() : 0
-                return dateB - dateA
-            })
-        })
+        }
     }, [initialItems])
 
     const handleSseMessage = useCallback(
         (payload: Exclude<DailyReportSseMessage, { type: "connected" }>) => {
+            // セッション切替〜プロバイダーアンマウントの隙間で届いた旧ユーザーの SSE は破棄する。
+            // clientLoader の bootstrap は React のコミット前にモジュールセッションを新ユーザーへ
+            // 差し替えるため、旧プロバイダーの EventSource が閉じるまでの間に届いたメッセージ
+            // (下書きの recipient 宛配信を含む) が、破棄済みキャッシュと新セッションへ
+            // 旧ユーザーのデータを書き込んでしまう (POST 継続と同じ汚染シグネチャ・実測再現済み)
+            if (!isSessionStillOurs()) {
+                return
+            }
             // Ignore echo of own actions
             // 自分が発行したアクションのエコーは無視する
             // clientTempId は connected 以外すべてのメッセージに存在する（型で保証済み）
@@ -463,6 +528,8 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
                     manuallyTrackingIds.current.delete(reportHubId)
                     // マージロジックでの復活を防止するために削除済み ID を記録
                     removedIds.current.add(reportHubId)
+                    // 常駐ストリームデータからも除去 (鮮度窓内の再訪で削除済み日報が蘇らないように)
+                    removeDailyReportIdsStreamItem(reportHubId)
 
                     // 削除されたレポートへの待機中 SSE メッセージを破棄
                     const pendingEntry = pendingSseQueue.current.get(reportHubId)
@@ -495,7 +562,7 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
                 }
             }
         },
-        [isProcessedId, upsertItem, user, enqueuePendingSseMessage],
+        [isProcessedId, isSessionStillOurs, upsertItem, user, enqueuePendingSseMessage],
     )
 
     // 常に最新の handleSseMessage をキューのリプレイから参照できるようにする
@@ -574,10 +641,20 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
             if (typeof data.clientTempId !== "string" || data.clientTempId !== clientTempId) {
                 throw new Error(`Invalid clientTempId for ${intent}`)
             }
+            // ユーザー切替後に解決した継続は、モジュール常駐状態 (常駐セッション・詳細キャッシュ)
+            // を旧ユーザーのデータで汚染しないよう onSuccess を放棄する
+            if (!isSessionStillOurs()) {
+                logger.warn(`[executeAction] ${intent} resolved after a user switch; discarding continuation`)
+                throw new Error(`Stale continuation for ${intent}`)
+            }
             return (await callbacks.onSuccess?.(data)) as T
         } catch (e) {
             logger.error(`${intent} failed:`, e)
-            callbacks.onFailure?.()
+            // 切替後の失敗も同様: onFailure のロールバックが旧値をモジュールキャッシュへ
+            // 書き戻すため放棄する (プロバイダー自身の state は key リマウントで破棄済み)
+            if (isSessionStillOurs()) {
+                callbacks.onFailure?.()
+            }
             throw e
         } finally {
             if (!(options?.keepLock || options?.skipLock)) {
@@ -805,6 +882,11 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
 
             const newId = Number(res.reportHubId)
 
+            // 常駐ストリームセッションへも反映する。自分の SSE エコーは clientTempId で
+            // 抑止されるため upsertItem 経由の中継は届かず、ここで直接中継しないと
+            // 鮮度窓内の再訪で作成直後の日報が一覧から消える
+            upsertDailyReportIdsStreamItem({ reportHubId: newId, businessDate })
+
             // newId を一時的にロックし、createReport 以前に開始された背景 prefetch の
             // cacheMany による stale データ上書きを防止する
             acquireMutationLock(newId)
@@ -883,6 +965,10 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
                         applyDailyReportServerUpdates(id, data.report)
                         setVersion((v) => v + 1)
                     }
+                    // 成功確定後に常駐ストリームセッションへも反映する (自分の SSE エコーは
+                    // 抑止されるため)。失敗時に走らせると、並行削除済みの日報を誤って
+                    // 蘇らせトゥームストーンまで解除してしまう
+                    upsertDailyReportIdsStreamItem({ reportHubId: id, businessDate })
                 },
                 onFailure: () => {
                     // ロールバック
@@ -902,6 +988,8 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
 
         // マージロジックでの復活を防止するために削除済み ID を記録
         removedIds.current.add(id)
+        // 常駐ストリームデータからも除去 (鮮度窓内の再訪で削除済み日報が蘇らないように)
+        removeDailyReportIdsStreamItem(id)
         // Optimistic UI update
         setItems((prev) => prev.filter((item) => item.reportHubId !== id))
 
@@ -926,8 +1014,17 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
                 return
             }
 
-            // それ以外のエラーの場合は、楽観的更新をロールバックする
+            // それ以外のエラーの場合は、楽観的更新をロールバックする。
+            // 常駐ストリームデータの除去とトゥームストーンも upsert で巻き戻す
+            // (巻き戻さないと、実在する日報が次の全量走査まで再訪時の一覧から消える)。
+            // ユーザー切替後に解決した継続は巻き戻さない — 旧ユーザーの行を新ユーザーの
+            // セッションへ upsert しトゥームストーンまで解除してしまうため
+            // (元の catch と同様に握り潰す。呼び出し元 UI は既に破棄済み)
+            if (!isSessionStillOurs()) {
+                return
+            }
             removedIds.current.delete(id)
+            upsertDailyReportIdsStreamItem({ reportHubId: id, businessDate: targetItem?.businessDate ?? businessDate })
             if (targetItem) {
                 setItems((prev) => {
                     if (prev.some((i) => i.reportHubId === id)) return prev

package/src/client/hooks/use-animated-number.spec.ts

@@ -0,0 +1,103 @@
+/**
+ * Timing tests for the ease-out animated number hook.
+ * イーズアウト数値アニメーションフックのタイミングテスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **経過時間の基準は最初の rAF フレームのタイムスタンプ** — effect 内の
+ *   `performance.now()` 基準だと混雑時に負の進捗が生まれ 0 に張り付く
+ *   (contact-map で実測された既知の不具合の再発防止)。
+ * - **初回マウントは補間せず即時表示** (カウントアップ演出をしない)。
+ * - **中断された補間は表示中の値から次の補間を始める** (跳び戻りしない)。
+ */
+import { act, renderHook } from "@testing-library/react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { useAnimatedNumber } from "./use-animated-number"
+
+/** 手動発火の rAF キュー。 */
+let rafQueue: FrameRequestCallback[] = []
+
+beforeEach(() => {
+    rafQueue = []
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+        rafQueue.push(callback)
+        return rafQueue.length
+    })
+    vi.stubGlobal("cancelAnimationFrame", vi.fn())
+})
+
+afterEach(() => {
+    vi.unstubAllGlobals()
+})
+
+/** 保留中の rAF を 1 フレームだけ指定タイムスタンプで発火する。 */
+const fireFrame = (timestamp: number) => {
+    const frame = rafQueue.shift()
+    act(() => {
+        frame?.(timestamp)
+    })
+}
+
+describe("useAnimatedNumber", () => {
+    it("初回マウントは補間せず即時に値を表示する", () => {
+        const { result } = renderHook(() => useAnimatedNumber(42))
+        expect(result.current).toBe(42)
+        expect(rafQueue).toHaveLength(0)
+    })
+
+    it("値の変化をイーズアウト 3 次で補間する (基準は最初のフレーム時刻)", () => {
+        const { result, rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 0 } })
+        rerender({ value: 100 })
+
+        // 最初のフレームが基準になる (進捗 0)
+        fireFrame(5_000)
+        expect(result.current).toBe(0)
+
+        // 50ms 経過 → eased = 1 - 0.5^3 = 0.875
+        fireFrame(5_050)
+        expect(result.current).toBe(88)
+
+        // 100ms 経過 → 完了
+        fireFrame(5_100)
+        expect(result.current).toBe(100)
+        expect(rafQueue).toHaveLength(0)
+    })
+
+    it("基準フレームより過去のような大きなタイムスタンプでも進捗は 0-1 にクランプされる", () => {
+        const { result, rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 0 } })
+        rerender({ value: 100 })
+        fireFrame(5_000)
+        // 大幅超過は 1 へクランプ
+        fireFrame(99_999)
+        expect(result.current).toBe(100)
+    })
+
+    it("補間の中断は表示中の値から次の補間を開始する (跳び戻りしない)", () => {
+        const { result, rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 0 } })
+        rerender({ value: 100 })
+        fireFrame(1_000)
+        fireFrame(1_050)
+        expect(result.current).toBe(88)
+
+        // 補間途中で目標値を更新 → 旧アニメーションは破棄され、88 を起点に 200 へ向かう
+        rafQueue.length = 0
+        rerender({ value: 200 })
+        expect(result.current).toBe(88)
+
+        // 第 2 アニメーションの基準フレーム (進捗 0 = 起点 88 のまま)
+        fireFrame(2_000)
+        expect(result.current).toBe(88)
+        // 50ms 経過 → eased 0.875 → 88 + (200 - 88) × 0.875 = 186
+        fireFrame(2_050)
+        expect(result.current).toBe(186)
+        // 完了 → 200
+        fireFrame(2_100)
+        expect(result.current).toBe(200)
+    })
+
+    it("同値への再レンダーはアニメーションを起こさない", () => {
+        const { rerender } = renderHook(({ value }) => useAnimatedNumber(value, 100), { initialProps: { value: 7 } })
+        rerender({ value: 7 })
+        expect(rafQueue).toHaveLength(0)
+    })
+})

package/src/client/hooks/use-animated-number.ts

@@ -0,0 +1,69 @@
+/**
+ * Ease-out animated number for streaming counters.
+ * ストリーミングカウンター向けのイーズアウト数値アニメーションフック。
+ *
+ * 経過時間の基準は「最初の rAF フレームのタイムスタンプ」にする。effect 内の
+ * `performance.now()` を基準にすると、メインスレッド混雑時に保留中フレームの
+ * vsync 時刻が基準より過去になり、負の進捗が 3 乗されて 0 に張り付く
+ * (contact-map で実測された既知の不具合)。進捗は念のため 0 でもクランプする。
+ */
+import { useEffect, useRef, useState } from "react"
+
+/**
+ * Animates numeric changes with ease-out cubic.
+ * 数値変化をイーズアウト 3 次で補間するフック。
+ *
+ * @param value Target value. 目標値。
+ * @param durationMs Animation duration. アニメーション時間 (既定 250ms)。
+ * @returns Displayed (interpolated) value. 表示用の補間値。
+ */
+export const useAnimatedNumber = (value: number, durationMs = 250): number => {
+    const [display, setDisplay] = useState(value)
+    // 表示中の値の同期ミラー (アニメーション中断時の次回開始点に使う)
+    const displayRef = useRef(value)
+    const isFirstRef = useRef(true)
+
+    /**
+     * Animation effect.
+     * アニメーション副作用。
+     *
+     * 依存配列:
+     * - value: 目標値の変化でアニメーションを開始する
+     * - durationMs: 時間変更で再スケジュール
+     * クリーンアップ:
+     * - 実行中の rAF をキャンセルする (中断時は displayRef が現在値を保持)
+     */
+    useEffect(() => {
+        // 初回は補間せず即時表示する (マウント時のカウントアップ演出は不要)
+        if (isFirstRef.current) {
+            isFirstRef.current = false
+            displayRef.current = value
+            setDisplay(value)
+            return
+        }
+        const from = displayRef.current
+        if (from === value) return
+
+        let rafId: number | null = null
+        let startTimestamp: number | null = null
+        const step = (timestamp: number) => {
+            if (startTimestamp === null) {
+                startTimestamp = timestamp
+            }
+            const progress = Math.min(1, Math.max(0, (timestamp - startTimestamp) / durationMs))
+            const eased = 1 - (1 - progress) ** 3
+            const next = Math.round(from + (value - from) * eased)
+            displayRef.current = next
+            setDisplay(next)
+            if (progress < 1) {
+                rafId = requestAnimationFrame(step)
+            }
+        }
+        rafId = requestAnimationFrame(step)
+        return () => {
+            if (rafId !== null) cancelAnimationFrame(rafId)
+        }
+    }, [value, durationMs])
+
+    return display
+}

package/src/client/route-helpers.spec.ts

@@ -0,0 +1,100 @@
+/**
+ * Bootstrap-ordering tests for the daily-report clientLoader factory.
+ * 日報 clientLoader 工場の起動順序テスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **prime は serverLoader の解決を待たずに先行する** (再訪の再検証前倒し)。
+ * - **ローダー時点でセッションを bootstrap する** (コールドロードの最重要最適化 —
+ *   ページマウントの effect まで生成を遅らせると、ストリーム開始がハイドレーション
+ *   完了の後ろに直列化される)。
+ * - **`hydrate = true`** (初期ハイドレーションでも実行される契約)。
+ */
+import { describe, expect, it, vi } from "vitest"
+
+const calls: string[] = []
+const bootstrapMock = vi.fn((options: { apiBasePath?: string; userKey: string | null }) => {
+    calls.push(`bootstrap:${options.userKey}`)
+})
+const primeMock = vi.fn(() => {
+    calls.push("prime")
+})
+
+vi.mock("./streaming/daily-report-ids-stream-session", () => ({
+    bootstrapDailyReportIdsStreamSession: (options: { apiBasePath?: string; userKey: string | null }) => bootstrapMock(options),
+    primeDailyReportIdsStreamSession: () => primeMock(),
+}))
+
+import { createDailyReportClientLoader, dailyReportShouldRevalidate } from "./route-helpers"
+
+describe("createDailyReportClientLoader", () => {
+    it("prime → serverLoader → bootstrap(userKey) の順で起動し、serverData を素通しする", async () => {
+        calls.length = 0
+        const clientLoader = createDailyReportClientLoader<{ userId: string | null; extra: number }>()
+        const serverLoader = vi.fn(async () => {
+            calls.push("serverLoader")
+            return { userId: "ENC8", extra: 42 }
+        })
+
+        const result = await clientLoader({ serverLoader })
+
+        expect(calls).toEqual(["prime", "serverLoader", "bootstrap:ENC8"])
+        expect(result).toEqual({ userId: "ENC8", extra: 42 })
+    })
+
+    it("userId が文字列でない serverData は userKey null で起動する", async () => {
+        bootstrapMock.mockClear()
+        const clientLoader = createDailyReportClientLoader()
+        await clientLoader({ serverLoader: async () => ({ userId: null }) })
+        expect(bootstrapMock).toHaveBeenCalledWith({ apiBasePath: undefined, userKey: null })
+
+        await clientLoader({ serverLoader: async () => ({}) })
+        expect(bootstrapMock).toHaveBeenLastCalledWith({ apiBasePath: undefined, userKey: null })
+    })
+
+    it("factory の apiBasePath オプションは bootstrap へ透過する", async () => {
+        bootstrapMock.mockClear()
+        const clientLoader = createDailyReportClientLoader({ apiBasePath: "/custom/api" })
+        await clientLoader({ serverLoader: async () => ({ userId: "ENC9" }) })
+        expect(bootstrapMock).toHaveBeenCalledWith({ apiBasePath: "/custom/api", userKey: "ENC9" })
+    })
+
+    it("hydrate フラグが立っている (初期ハイドレーションでも実行される契約)", () => {
+        const clientLoader = createDailyReportClientLoader()
+        expect(clientLoader.hydrate).toBe(true)
+    })
+})
+
+describe("dailyReportShouldRevalidate", () => {
+    /** 最小限の引数組み立て。 */
+    const makeArgs = (over: Record<string, unknown> = {}) =>
+        ({
+            defaultShouldRevalidate: true,
+            currentUrl: new URL("http://localhost/daily_report"),
+            nextUrl: new URL("http://localhost/daily_report"),
+            actionResult: undefined,
+            actionStatus: undefined,
+            formAction: undefined,
+            formData: undefined,
+            formEncType: undefined,
+            formMethod: undefined,
+            json: undefined,
+            text: undefined,
+            ...over,
+            // biome-ignore lint/suspicious/noExplicitAny: ShouldRevalidateFunctionArgs の完全構築はテストに不要
+        }) as any
+
+    it("同一 URL かつ送信シグナル無しは再検証しない", () => {
+        expect(dailyReportShouldRevalidate(makeArgs())).toBe(false)
+    })
+
+    it("URL が変われば既定に従う", () => {
+        expect(dailyReportShouldRevalidate(makeArgs({ nextUrl: new URL("http://localhost/daily_report?businessDate=2026-08-01") }))).toBe(true)
+    })
+
+    it("ミューテーション intent は再検証しない (SSE が伝搬を担う)", () => {
+        const formData = new FormData()
+        formData.set("intent", "toggleRead")
+        expect(dailyReportShouldRevalidate(makeArgs({ formData }))).toBe(false)
+    })
+})