@aiquants/daily-report 0.7.0 → 0.9.0

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/hooks/use-daily-report.spec.ts

@@ -30,6 +30,7 @@ describe("DailyReportCache public API", () => {
     let getCachedReport: typeof import("./use-daily-report").getCachedReport
     let updateDailyReportCache: typeof import("./use-daily-report").updateDailyReportCache
     let applyDailyReportServerUpdates: typeof import("./use-daily-report").applyDailyReportServerUpdates
+    let applyBroadcastReportUpdate: typeof import("./use-daily-report").applyBroadcastReportUpdate
 
     beforeEach(async () => {
         // モジュールキャッシュをリセットして、getGlobal がカスタム TTL を読み込むようにする
@@ -44,6 +45,7 @@ describe("DailyReportCache public API", () => {
         getCachedReport = mod.getCachedReport
         updateDailyReportCache = mod.updateDailyReportCache
         applyDailyReportServerUpdates = mod.applyDailyReportServerUpdates
+        applyBroadcastReportUpdate = mod.applyBroadcastReportUpdate
     })
 
     afterEach(() => {
@@ -100,8 +102,9 @@ describe("DailyReportCache public API", () => {
         })
     })
 
-    describe("applyDailyReportServerUpdates", () => {
-        it("キャッシュ済みレポートを完全置換する", () => {
+    describe("applyDailyReportServerUpdates (信頼経路: 自分の HTTP 応答・自分宛 status-update)", () => {
+        it("キャッシュ済みレポートを完全置換する (per-viewer 値も配信値を採用)", () => {
+            // 信頼経路の値は受信者自身の状態なので、そのまま書いてよい
             writeCache(makeMockReport({ subject: "Old", content: "Old" }), Date.now() + 1000)
             applyDailyReportServerUpdates(1, makeMockReport({ subject: "Fresh", content: "Fresh" }))
             const cached = getCachedReport(1)
@@ -114,6 +117,51 @@ describe("DailyReportCache public API", () => {
             expect(getCachedReport(42)?.subject).toBe("New")
         })
     })
+
+    describe("applyBroadcastReportUpdate (放送経路: 全ユーザー宛 SSE)", () => {
+        it("共有フィールドは配信値で更新し、per-viewer (isRead/isStarred) は受信者の値を保持する", () => {
+            // SSE の report が運ぶ isRead/isStarred は送信者 (操作者) の状態であり、
+            // 受信者のキャッシュへそのまま書くと他人の既読/スター状態で上書きされる
+            writeCache(makeMockReport({ subject: "Old", content: "Old", isRead: true, isStarred: true }), Date.now() + 1000)
+            applyBroadcastReportUpdate(makeMockReport({ subject: "Fresh", content: "Fresh", isRead: false, isStarred: false }))
+            const cached = getCachedReport(1)
+            expect(cached?.subject).toBe("Fresh")
+            expect(cached?.content).toBe("Fresh")
+            // 受信者自身の per-viewer 状態が生き残る
+            expect(cached?.isRead).toBe(true)
+            expect(cached?.isStarred).toBe(true)
+        })
+
+        it("commentItems[].isMine は per-viewer: キャッシュ済みは保持、送信者由来の新規は false 化する", () => {
+            // isMine はサーバーが送信者視点で計算するため、そのまま取り込むと受信者に
+            // 他人のコメントが「自分の」削除ボタン付きで見え、自分のコメントは isMine を失う
+            writeCache(makeMockReport({ commentItems: [{ id: 1, userName: "自分", content: "私の", createdAt: "2026-01-01 00:00:00", userId: "ENC8", isMine: true }] }) as never, Date.now() + 1000)
+            applyBroadcastReportUpdate(
+                makeMockReport({
+                    commentItems: [
+                        { id: 1, userName: "自分", content: "私の", createdAt: "2026-01-01 00:00:00", userId: "ENC8", isMine: false },
+                        { id: 2, userName: "他人", content: "他人の", createdAt: "2026-01-01 00:01:00", userId: "ENC9", isMine: true },
+                    ],
+                }) as never,
+            )
+            const cached = getCachedReport(1)
+            // 受信者自身のコメント (id=1) の isMine は保持、送信者が「自分の」とした id=2 は false 化
+            expect(cached?.commentItems.find((c) => c.id === 1)?.isMine).toBe(true)
+            expect(cached?.commentItems.find((c) => c.id === 2)?.isMine).toBe(false)
+        })
+
+        it("未キャッシュの ID も中立化して種まきする (行が stale 安全弁で消えるのを防ぐ)", () => {
+            // 未キャッシュを書かないと、鮮度窓内のリストキャッシュに新 id が無く、行が
+            // report=null に解決してトゥームストーン化され、作成/公開された日報が消える
+            applyBroadcastReportUpdate(makeMockReport({ reportHubId: 42, subject: "New", isRead: true, isStarred: true, commentItems: [{ id: 9, userName: "他人", content: "x", createdAt: "2026-01-01 00:00:00", userId: "ENC9", isMine: true }] }) as never)
+            const cached = getCachedReport(42)
+            expect(cached?.subject).toBe("New")
+            // per-viewer は中立値で入る (送信者の true を持ち込まない)
+            expect(cached?.isRead).toBe(false)
+            expect(cached?.isStarred).toBe(false)
+            expect(cached?.commentItems[0]?.isMine).toBe(false)
+        })
+    })
 })
 
 describe("getGlobal behavior (window グローバル変数の読み取り)", () => {

package/src/client/hooks/use-daily-report.ts

@@ -270,11 +270,40 @@ export const subscribeCacheReady = (reportHubId: number, callback: () => void):
     }
 }
 
-export const applyDailyReportServerUpdates = (_reportHubIdd: number, report: DailyReportDetail) => {
+export const applyDailyReportServerUpdates = (_reportHubId: number, report: DailyReportDetail) => {
     DailyReportCache.prune()
     DailyReportCache.set(report, Date.now() + TTL)
 }
 
+/**
+ * Applies a broadcast (cross-user SSE) report while preserving the viewer's own per-viewer state.
+ * 全ユーザー放送 (SSE) の report を、受信者自身の per-viewer 状態を保持したまま反映する処理。
+ *
+ * SSE の report-create/update/publish が運ぶ isRead/isStarred は**操作した本人の状態**。
+ * そのまま書くと受信者の既読/スター表示が他人の状態で上書きされる。共有フィールドだけを
+ * 取り込み、per-viewer フィールドは受信者のキャッシュ値を保持する。ローカルに無い日報は
+ * 種まきしない (送信者の per-viewer 値で汚すより、次のフェッチが受信者視点の正しい値を
+ * 取るのに任せるほうが安全)。
+ *
+ * ❗ 信頼できる経路 (自分の HTTP 応答・recipient フィルタ済みの自分宛 status-update) は
+ * {@link applyDailyReportServerUpdates} を使うこと — そちらは値をそのまま書く。
+ */
+export const applyBroadcastReportUpdate = (report: DailyReportDetail) => {
+    DailyReportCache.prune()
+    const cached = DailyReportCache.getReport(report.reportHubId, true)
+    // per-viewer フィールド (isRead / isStarred / commentItems[].isMine) は送信者視点なので
+    // 受信者のキャッシュ値を保持し、未キャッシュなら中立値 (false) で置く。共有フィールドは配信値。
+    // ❗ 未キャッシュでも必ず書く: 書かないと鮮度窓内のリストキャッシュに新 id が載らず、
+    //   作成/公開された他ユーザーの日報が stale 安全弁でトゥームストーン化され、閲覧中の
+    //   受信者の一覧から恒久的に消える (set は既定で syncList=true = リストにも反映する)
+    const cachedMine = new Map<number | string, boolean>()
+    for (const c of cached?.commentItems ?? []) {
+        cachedMine.set(c.id, c.isMine ?? false)
+    }
+    const commentItems = (report.commentItems ?? []).map((c) => ({ ...c, isMine: cachedMine.get(c.id) ?? false }))
+    DailyReportCache.set({ ...report, isRead: cached?.isRead ?? false, isStarred: cached?.isStarred ?? false, commentItems }, Date.now() + TTL)
+}
+
 // --- Data Loading ---
 /**
  * Fetch a single report by ID.

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)
+    })
+})

package/src/client/route-helpers.ts

@@ -3,8 +3,7 @@
  * 日報ページ向け React Router ルートヘルパー (再検証ポリシー / クライアントローダー)。
  */
 import type { ShouldRevalidateFunction, ShouldRevalidateFunctionArgs } from "react-router"
-import type { DailyReportItem } from "../shared/types"
-import { defaultDailyReportClientConfig } from "./config-context"
+import { bootstrapDailyReportIdsStreamSession, primeDailyReportIdsStreamSession } from "./streaming/daily-report-ids-stream-session"
 
 /**
  * Prevents loader revalidation when POP navigations keep identical URL state.
@@ -32,50 +31,30 @@ export const dailyReportShouldRevalidate: ShouldRevalidateFunction = ({ actionRe
 }
 
 /**
- * Fetches the deferred daily report id list from the API endpoint.
- * API エンドポイントから日報 ID 一覧を遅延取得する処理。
- */
-export const fetchDailyReportIds = (apiBasePath: string = defaultDailyReportClientConfig.apiBasePath, forceRefresh = false): Promise<DailyReportItem[]> => {
-    const url = new URL(`${apiBasePath}/ids`, typeof window !== "undefined" ? window.location.origin : "http://localhost")
-    if (forceRefresh) {
-        url.searchParams.set("forceRefresh", "true")
-        url.searchParams.set("_t", Date.now().toString())
-    }
-    return fetch(url.toString(), {
-        method: "GET",
-        headers: { "Content-Type": "application/json" },
-        cache: "no-cache",
-    })
-        .then(async (response) => {
-            if (!response.ok) {
-                throw new Error(`Failed to fetch daily report ids: ${response.status} ${response.statusText}`)
-            }
-            return response
-        })
-        .then(async (response) => response.json())
-        .then((data) => {
-            if (!(data.ids && Array.isArray(data.ids))) {
-                throw new Error("Invalid daily report ids response")
-            }
-            return data.ids as DailyReportItem[]
-        })
-}
-
-/**
- * Creates a React Router clientLoader that merges server data with deferred report ids.
- * サーバーデータへ遅延日報 ID を合成する React Router clientLoader を生成する処理。
+ * Creates a React Router clientLoader that bootstraps the ids stream session.
+ * ID ストリームセッションを起動する React Router clientLoader を生成する処理。
+ *
+ * ID 一覧は Promise で返さず、モジュール常駐のストリームセッションが供給する
+ * (ページ側は `useDailyReportIdsStream` で購読する)。ローダー時点でセッションを
+ * 生成することが**コールドロードの最重要最適化** — ページマウントの effect まで
+ * 遅らせると、ストリームの開始が「ハイドレーション完了 + effect flush」の後ろに
+ * 直列化される。再訪 (セッション既存) は serverLoader を待たずに鮮度確認を先行させる。
+ *
+ * `config.apiBasePath` を上書きするアプリは同じ値を `options.apiBasePath` にも渡すこと
+ * (渡し忘れは初回 1 回だけ誤パス生成 → ページマウントの ensure が自己修復する)。
  *
  * 返す関数へ `hydrate = true as const` を付与済み (初期ハイドレーションでも実行される)。
  */
 export const createDailyReportClientLoader = <TServerData extends Record<string, unknown>>(options?: { apiBasePath?: string }) => {
-    const clientLoader = async (args: { serverLoader: () => Promise<unknown> }): Promise<TServerData & { dailyReportIds: Promise<DailyReportItem[]> }> => {
-        // サーバーローダーの解決を待つ間に ID 取得を並行開始する
-        const idsPromise = fetchDailyReportIds(options?.apiBasePath)
+    const clientLoader = async (args: { serverLoader: () => Promise<unknown> }): Promise<TServerData> => {
+        // 再訪の主経路: 既存セッションの鮮度確認を serverLoader より先に始める
+        primeDailyReportIdsStreamSession()
         const serverData = (await args.serverLoader()) as TServerData
-        return {
-            ...serverData,
-            dailyReportIds: idsPromise,
-        }
+        // 不在なら生成 (コールドロードでハイドレーションと並行してフェッチを開始)、
+        // 既存なら userKey 照合 (別ユーザーは描画前に破棄・再生成) + 鮮度確認
+        const rawUserId = (serverData as { userId?: unknown }).userId
+        bootstrapDailyReportIdsStreamSession({ apiBasePath: options?.apiBasePath, userKey: typeof rawUserId === "string" ? rawUserId : null })
+        return serverData
     }
     clientLoader.hydrate = true as const
     return clientLoader