@aiquants/daily-report 0.7.0 → 0.8.0

package/src/client/streaming/daily-report-ids-stream-session.spec.ts

@@ -0,0 +1,360 @@
+/**
+ * Lifecycle tests for the module-resident ids stream session.
+ * モジュール常駐 ids ストリームセッションのライフサイクルテスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **userKey (難読化ユーザー ID) が変わったらセッションを作り直す** — 別ユーザーの
+ *   受信済みデータを次のユーザーへ見せてはならない。
+ * - **failed セッションへの再訪 (ensure) は自動 retry する** — 再訪はユーザーの再試行意思。
+ * - **完走から一定時間を過ぎた再訪はバックグラウンド再検証する** (SWR)。
+ * - **フックはセッション生成前でも安全に IDLE を返し、生成後は再購読なしで追従する。**
+ *
+ * モジュールスコープ状態を分離するため、テストごとに `vi.resetModules()` +
+ * 動的 import でモジュールを作り直す (use-daily-report.spec.ts と同じ流儀)。
+ */
+import { act, renderHook } from "@testing-library/react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import type { DailyReportIdsStreamState } from "./daily-report-ids-stream-client"
+
+/** FakeClient の呼び出し記録と状態操作面。 */
+type FakeClientHandle = {
+    startCalls: number
+    retryCalls: number
+    refreshCalls: Array<{ forceRefresh?: boolean }>
+    disposeCalls: number
+    upserts: Array<{ reportHubId: number; businessDate: string | null }>
+    removals: number[]
+    setState: (partial: Partial<DailyReportIdsStreamState>) => void
+    options: { apiBasePath?: string }
+}
+
+/** 生成された FakeClient のハンドル一覧 (生成順)。 */
+const createdClients: FakeClientHandle[] = []
+
+/** ユーザー切替時の詳細キャッシュ破棄の呼び出し記録。 */
+const clearCacheMock = vi.fn()
+
+vi.mock("../hooks/use-daily-report", () => ({
+    clearDailyReportCache: () => clearCacheMock(),
+}))
+
+vi.mock("./daily-report-ids-stream-client", () => {
+    class FakeClient {
+        private listeners = new Set<() => void>()
+        private state: DailyReportIdsStreamState = {
+            items: [],
+            loadedCount: 0,
+            totalCount: null,
+            phase: "idle",
+            isRevalidating: false,
+            hasCompletedOnce: false,
+            completedAt: null,
+            error: null,
+        }
+        readonly handle: FakeClientHandle
+
+        constructor(options: { apiBasePath?: string } = {}) {
+            this.handle = {
+                startCalls: 0,
+                retryCalls: 0,
+                refreshCalls: [],
+                disposeCalls: 0,
+                upserts: [],
+                removals: [],
+                options,
+                setState: (partial) => {
+                    this.state = { ...this.state, ...partial }
+                    for (const listener of this.listeners) listener()
+                },
+            }
+            createdClients.push(this.handle)
+        }
+
+        getState() {
+            return this.state
+        }
+
+        subscribe(listener: () => void) {
+            this.listeners.add(listener)
+            return () => this.listeners.delete(listener)
+        }
+
+        start() {
+            this.handle.startCalls += 1
+        }
+
+        retry() {
+            this.handle.retryCalls += 1
+        }
+
+        refresh(options: { forceRefresh?: boolean } = {}) {
+            this.handle.refreshCalls.push(options)
+        }
+
+        dispose() {
+            this.handle.disposeCalls += 1
+        }
+
+        applyExternalUpsert(item: { reportHubId: number; businessDate: string | null }) {
+            this.handle.upserts.push(item)
+        }
+
+        applyExternalRemoval(reportHubId: number) {
+            this.handle.removals.push(reportHubId)
+        }
+    }
+    return { DailyReportIdsStreamClient: FakeClient }
+})
+
+/** テスト対象モジュールを新品で読み込む。 */
+const importSession = async () => await import("./daily-report-ids-stream-session")
+
+beforeEach(() => {
+    vi.resetModules()
+    createdClients.length = 0
+    clearCacheMock.mockClear()
+    vi.useFakeTimers()
+})
+
+afterEach(() => {
+    vi.useRealTimers()
+})
+
+describe("ensureDailyReportIdsStreamSession", () => {
+    it("初回 ensure でクライアントを生成して start する", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ apiBasePath: "/daily_report/api", userKey: "userA" })
+        expect(createdClients).toHaveLength(1)
+        expect(createdClients[0].startCalls).toBe(1)
+        expect(createdClients[0].options.apiBasePath).toBe("/daily_report/api")
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("同一 userKey の再 ensure はセッションを再利用する", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients).toHaveLength(1)
+        expect(createdClients[0].disposeCalls).toBe(0)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("userKey が変わったら旧セッションと詳細キャッシュを破棄して作り直す", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        session.ensureDailyReportIdsStreamSession({ userKey: "userB" })
+        expect(createdClients).toHaveLength(2)
+        expect(createdClients[0].disposeCalls).toBe(1)
+        expect(createdClients[1].startCalls).toBe(1)
+        // 旧ユーザーが閲覧した詳細 (下書き含む) を新ユーザーへ供給しない
+        expect(clearCacheMock).toHaveBeenCalledTimes(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("apiBasePath が変わったら作り直す (同一ユーザーなので詳細キャッシュは保持)", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ apiBasePath: "/a", userKey: "userA" })
+        session.ensureDailyReportIdsStreamSession({ apiBasePath: "/b", userKey: "userA" })
+        expect(createdClients).toHaveLength(2)
+        expect(createdClients[0].disposeCalls).toBe(1)
+        expect(clearCacheMock).not.toHaveBeenCalled()
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("failed セッションへの ensure は retry する", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        createdClients[0].setState({ phase: "failed" })
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients[0].retryCalls).toBe(1)
+        expect(createdClients[0].refreshCalls).toHaveLength(0)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("完走直後の ensure は再検証しないが、鮮度窓を過ぎた ensure は refresh する", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        createdClients[0].setState({ phase: "complete", hasCompletedOnce: true, completedAt: Date.now() })
+
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients[0].refreshCalls).toHaveLength(0)
+
+        // 鮮度窓 (60 秒) を越えて再訪
+        vi.advanceTimersByTime(61_000)
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients[0].refreshCalls).toHaveLength(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("再検証の諦め (completedAt 据え置き) 後の ensure は再び refresh する — 古いデータを新鮮扱いしない", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        createdClients[0].setState({ phase: "complete", hasCompletedOnce: true, completedAt: Date.now() })
+
+        vi.advanceTimersByTime(61_000)
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients[0].refreshCalls).toHaveLength(1)
+
+        // 再検証の力尽き publish: phase は complete のまま、completedAt は据え置き
+        createdClients[0].setState({ isRevalidating: false, error: new Error("gave up") })
+
+        // 次の ensure は据え置かれた completedAt を根拠に再検証を再度走らせる
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients[0].refreshCalls).toHaveLength(2)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("undefined と既定文字列の apiBasePath は同一視され、セッションを破棄しない", async () => {
+        const session = await importSession()
+        // clientLoader 相当 (apiBasePath 未指定 = undefined)
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        // ページ effect 相当 (config の既定文字列)
+        session.ensureDailyReportIdsStreamSession({ apiBasePath: "/daily_report/api", userKey: "userA" })
+        expect(createdClients).toHaveLength(1)
+        expect(createdClients[0].disposeCalls).toBe(0)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+})
+
+describe("ensure / isRevalidating ガード", () => {
+    it("走行中の再検証 (isRevalidating) がある間の ensure は refresh を重ねない", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        createdClients[0].setState({ phase: "complete", hasCompletedOnce: true, completedAt: Date.now() })
+        vi.advanceTimersByTime(61_000)
+
+        // 1 回目の ensure が再検証を起動する想定 (FakeClient は refresh を記録するだけ)
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients[0].refreshCalls).toHaveLength(1)
+
+        // 実クライアントは再検証中 isRevalidating を立てる。以後の ensure は重ねない
+        createdClients[0].setState({ isRevalidating: true })
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        session.primeDailyReportIdsStreamSession()
+        expect(createdClients[0].refreshCalls).toHaveLength(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+})
+
+describe("bootstrapDailyReportIdsStreamSession", () => {
+    it("セッションが無ければローダー時点で生成して start する (コールドロードの最重要最適化)", async () => {
+        const session = await importSession()
+        session.bootstrapDailyReportIdsStreamSession({ apiBasePath: "/daily_report/api", userKey: "userA" })
+        expect(createdClients).toHaveLength(1)
+        expect(createdClients[0].startCalls).toBe(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("userKey 不一致なら描画前に破棄 (詳細キャッシュ含む) し、新ユーザーで即時再生成する", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        session.bootstrapDailyReportIdsStreamSession({ userKey: "userB" })
+        expect(createdClients[0].disposeCalls).toBe(1)
+        expect(createdClients).toHaveLength(2)
+        expect(createdClients[1].startCalls).toBe(1)
+        expect(clearCacheMock).toHaveBeenCalledTimes(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("userKey 一致なら既存セッションを保ち鮮度確認を行う (failed は retry)。パスは照合しない", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ apiBasePath: "/custom/api", userKey: "userA" })
+        createdClients[0].setState({ phase: "failed" })
+        // factory 未指定 (undefined → 既定値) でもセッションは破棄されない —
+        // 照合するとナビゲーションごとのスラッシングが再発する
+        session.bootstrapDailyReportIdsStreamSession({ userKey: "userA" })
+        expect(createdClients).toHaveLength(1)
+        expect(createdClients[0].disposeCalls).toBe(0)
+        expect(createdClients[0].retryCalls).toBe(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+})
+
+describe("外部ミューテーション中継", () => {
+    it("upsert / removal はセッションのクライアントへ委譲され、セッション無しでは何もしない", async () => {
+        const session = await importSession()
+        // セッション無し: 例外なく無視される
+        session.upsertDailyReportIdsStreamItem({ reportHubId: 1, businessDate: "2026-08-01" })
+        session.removeDailyReportIdsStreamItem(1)
+        expect(createdClients).toHaveLength(0)
+
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        session.upsertDailyReportIdsStreamItem({ reportHubId: 2, businessDate: "2026-08-02" })
+        session.removeDailyReportIdsStreamItem(3)
+        expect(createdClients[0].upserts).toEqual([{ reportHubId: 2, businessDate: "2026-08-02" }])
+        expect(createdClients[0].removals).toEqual([3])
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+})
+
+describe("primeDailyReportIdsStreamSession", () => {
+    it("セッションが無ければ何もしない", async () => {
+        const session = await importSession()
+        session.primeDailyReportIdsStreamSession()
+        expect(createdClients).toHaveLength(0)
+    })
+
+    it("既存セッションがあれば userKey 未確定でも鮮度確認を先行できる", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        createdClients[0].setState({ phase: "complete", hasCompletedOnce: true, completedAt: Date.now() })
+        vi.advanceTimersByTime(61_000)
+        session.primeDailyReportIdsStreamSession()
+        expect(createdClients[0].refreshCalls).toHaveLength(1)
+        // prime はセッションを作り直さない
+        expect(createdClients).toHaveLength(1)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+})
+
+describe("useDailyReportIdsStream", () => {
+    it("セッション生成前は IDLE、生成後は再購読なしで追従する", async () => {
+        const session = await importSession()
+        const { result } = renderHook(() => session.useDailyReportIdsStream())
+        expect(result.current.phase).toBe("idle")
+        expect(result.current.items).toEqual([])
+
+        act(() => {
+            session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        })
+        act(() => {
+            createdClients[0].setState({
+                phase: "streaming",
+                loadedCount: 2,
+                items: [
+                    { reportHubId: 2, businessDate: "2026-08-01" },
+                    { reportHubId: 1, businessDate: "2026-08-01" },
+                ],
+            })
+        })
+        expect(result.current.phase).toBe("streaming")
+        expect(result.current.loadedCount).toBe(2)
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("retry / refresh のエントリポイントはクライアントへ委譲する", async () => {
+        const session = await importSession()
+        session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+        session.retryDailyReportIdsStream()
+        session.refreshDailyReportIdsStream({ forceRefresh: true })
+        expect(createdClients[0].retryCalls).toBe(1)
+        expect(createdClients[0].refreshCalls).toEqual([{ forceRefresh: true }])
+        session.resetDailyReportIdsStreamSessionForTesting()
+    })
+
+    it("resetDailyReportIdsStreamSessionForTesting はセッションを破棄して IDLE へ戻す", async () => {
+        const session = await importSession()
+        const { result } = renderHook(() => session.useDailyReportIdsStream())
+        act(() => {
+            session.ensureDailyReportIdsStreamSession({ userKey: "userA" })
+            createdClients[0].setState({ phase: "streaming", loadedCount: 1 })
+        })
+        expect(result.current.phase).toBe("streaming")
+        act(() => {
+            session.resetDailyReportIdsStreamSessionForTesting()
+        })
+        expect(createdClients[0].disposeCalls).toBe(1)
+        expect(result.current.phase).toBe("idle")
+    })
+})

package/src/client/streaming/daily-report-ids-stream-session.ts

@@ -0,0 +1,280 @@
+/**
+ * Module-resident session and React hook for the daily-report ids stream.
+ * 日報 ID ストリームのモジュール常駐セッションと React フック。
+ *
+ * セッション (クライアント実体 + 完走時刻) をモジュールスコープに置くことで、
+ * ページのアンマウント/再マウントをまたいで受信済みデータが生き残り、
+ * 再訪時はローディング画面なしで即座に一覧を復元できる。鮮度は
+ * 「完走から一定時間経過後の再訪でバックグラウンド再検証」(SWR) で担保する。
+ * マウント中のリアルタイム性は SSE が担うため、これで欠落窓は実質「離脱中」のみになる。
+ */
+import { useSyncExternalStore } from "react"
+import type { DailyReportItem } from "../../shared/types"
+import { defaultDailyReportClientConfig } from "../config-context"
+import { clearDailyReportCache } from "../hooks/use-daily-report"
+import { DailyReportIdsStreamClient, type DailyReportIdsStreamState } from "./daily-report-ids-stream-client"
+
+/** 完走からこの時間を過ぎた再訪で、バックグラウンド再検証を走らせる。 */
+const REVALIDATE_AFTER_MS = 60_000
+
+/** セッション 1 世代分の記録。 */
+type SessionRecord = {
+    client: DailyReportIdsStreamClient
+    /** セッションの持ち主 (難読化ユーザー ID。未登録ユーザーは null)。 */
+    userKey: string | null
+    /** 正規化済み API ベースパス (既定値解決済み)。 */
+    apiBasePath: string
+    unsubscribe: () => void
+}
+
+let session: SessionRecord | null = null
+
+/** セッションの生成/破棄とクライアント publish の両方を伝えるリスナー群。 */
+const sessionListeners = new Set<() => void>()
+
+/** セッション未生成時に返す不変スナップショット (SSR の getServerSnapshot も兼ねる)。 */
+const IDLE_STATE: DailyReportIdsStreamState = {
+    items: [],
+    loadedCount: 0,
+    totalCount: null,
+    phase: "idle",
+    isRevalidating: false,
+    hasCompletedOnce: false,
+    completedAt: null,
+    error: null,
+}
+
+/**
+ * Full-document reload indirection (mockable seam for auth-expiry tests).
+ * ドキュメント全体を再読込する間接層 (認証切れテストで差し替え可能にする継ぎ目)。
+ */
+export const reloadDocument = (): void => {
+    if (typeof window !== "undefined") {
+        window.location.reload()
+    }
+}
+
+/** 全セッションリスナーへ変更を通知する。 */
+const notifySessionListeners = (): void => {
+    for (const listener of sessionListeners) {
+        listener()
+    }
+}
+
+/** 現行セッションを破棄する (ユーザー切替・HMR・テストリセット用)。 */
+const destroySession = (): void => {
+    if (!session) return
+    session.unsubscribe()
+    session.client.dispose()
+    session = null
+    notifySessionListeners()
+}
+
+/**
+ * Ensures a stream session for the given user, creating/refreshing as needed.
+ * 指定ユーザーのストリームセッションを確立する処理 (必要に応じ生成/再検証)。
+ *
+ * - ユーザーまたは API パスが変わっていれば作り直す (別ユーザーのデータを見せない)。
+ * - failed なら自動 retry (再訪 = ユーザーの再試行意思とみなす)。
+ * - 完走から {@link REVALIDATE_AFTER_MS} 経過していればバックグラウンド再検証。
+ *
+ * SSR では何もしない。clientLoader とページマウントの両方から呼ばれ、冪等。
+ *
+ * @param options.apiBasePath API ベースパス (config の apiBasePath)。
+ * @param options.userKey 難読化ユーザー ID (未登録ユーザーは null)。
+ */
+export const ensureDailyReportIdsStreamSession = (options: { apiBasePath?: string; userKey: string | null }): void => {
+    if (typeof window === "undefined") return
+
+    // 呼び出し元によって undefined / 既定文字列が混在するため、比較前に必ず正規化する。
+    // 正規化を欠くと clientLoader (undefined) とページ effect (既定文字列) の往復で
+    // セッションが毎回破棄され、モジュール常駐による即時復元が丸ごと無効化される
+    const apiBasePath = options.apiBasePath ?? defaultDailyReportClientConfig.apiBasePath
+
+    if (session && (session.userKey !== options.userKey || session.apiBasePath !== apiBasePath)) {
+        // ユーザーが変わる場合はモジュール常駐の詳細キャッシュも破棄する
+        // (旧ユーザーが閲覧した下書き詳細等が TTL 内の新ユーザーへ供給されるのを防ぐ)
+        if (session.userKey !== options.userKey) {
+            clearDailyReportCache()
+        }
+        destroySession()
+    }
+
+    if (!session) {
+        const client = new DailyReportIdsStreamClient({ apiBasePath })
+        session = {
+            client,
+            userKey: options.userKey,
+            apiBasePath,
+            // 通知はそのままセッションリスナーへ中継する (完走時刻はクライアントが state に刻む)
+            unsubscribe: client.subscribe(notifySessionListeners),
+        }
+        client.start()
+        notifySessionListeners()
+        return
+    }
+
+    runFreshnessCheck(session)
+}
+
+/**
+ * Retries a failed session or starts a background revalidation when stale.
+ * failed セッションの retry、または鮮度切れ時のバックグラウンド再検証を起動する処理。
+ *
+ * 再検証が既に走行中 (`isRevalidating`) の間は何もしない。ガードを欠くと、1 回の
+ * 再訪で走る複数の確立呼び出し (clientLoader の prime / ensure / ページ effect) が
+ * それぞれ走行中の再検証を中断して先頭からやり直し、NDJSON を多重ダウンロードする。
+ */
+const runFreshnessCheck = (record: SessionRecord): void => {
+    const state = record.client.getState()
+    if (state.phase === "failed") {
+        record.client.retry()
+        return
+    }
+    if (state.phase === "complete" && !state.isRevalidating && state.completedAt !== null && Date.now() - state.completedAt > REVALIDATE_AFTER_MS) {
+        record.client.refresh()
+    }
+}
+
+/**
+ * Bootstraps the session from the clientLoader: create when absent, else reconcile.
+ * clientLoader からのセッション起動処理。不在なら生成、既存なら照合と鮮度確認。
+ *
+ * コールドロードの最重要ゲート対策: 生成をページマウントの effect まで遅らせると、
+ * ストリームの最初のバイト要求が「serverLoader 完了 → ハイドレーション → effect flush」
+ * の後ろに直列化される。ローダー時点で生成すればハイドレーションと並行してフェッチが走る。
+ *
+ * パス契約: 生成時のパスは factory オプション (未指定は既定値へ正規化)。
+ * `config.apiBasePath` だけを上書きした利用者では初回のみ誤パスで生成されるが、
+ * ページマウント側の ensure がパス不一致を検知して作り直す (自己修復・初回 1 回きり)。
+ * **既存セッションのパスはここでは照合しない** — 照合すると、factory 未指定 ×
+ * config 上書きの組み合わせでナビゲーションごとにセッションが破棄されるスラッシングになる。
+ *
+ * @param options.apiBasePath 生成時に使う API ベースパス (未指定は既定値)。
+ * @param options.userKey 難読化ユーザー ID (未登録ユーザーは null)。
+ */
+export const bootstrapDailyReportIdsStreamSession = (options: { apiBasePath?: string; userKey: string | null }): void => {
+    if (typeof window === "undefined") return
+    if (!session) {
+        ensureDailyReportIdsStreamSession(options)
+        return
+    }
+    if (session.userKey !== options.userKey) {
+        // 別ユーザーのデータは描画前に破棄し (詳細キャッシュ含む)、新ユーザーのストリームを即時開始する
+        clearDailyReportCache()
+        destroySession()
+        ensureDailyReportIdsStreamSession(options)
+        return
+    }
+    runFreshnessCheck(session)
+}
+
+/**
+ * Kicks a freshness check for an existing session before the user is known.
+ * ユーザー確定前に既存セッションの鮮度確認だけを先行させる処理。
+ *
+ * clientLoader が serverLoader を await する前に呼び、再訪 (支配的経路) の
+ * 再検証開始を数十〜数百 ms 前倒しする。セッションが無ければ何もしない
+ * (誰のデータを読むべきか分からないため)。直後の reconcile が userKey を照合し、
+ * ユーザーが変わっていればセッションごと破棄されるので先行は安全。
+ * 走行中の再検証は中断しない (runFreshnessCheck の isRevalidating ガード)。
+ */
+export const primeDailyReportIdsStreamSession = (): void => {
+    if (typeof window === "undefined" || !session) return
+    runFreshnessCheck(session)
+}
+
+/**
+ * Relays an externally-known item upsert into the resident stream data.
+ * 外部由来のアイテム upsert を常駐ストリームデータへ中継する処理。
+ *
+ * プロバイダーの作成/公開系ミューテーション (ローカル操作と SSE) から呼ばれる。
+ * これを欠くと、鮮度窓内の再訪で「作成したばかりの日報が消える」。
+ */
+export const upsertDailyReportIdsStreamItem = (item: DailyReportItem): void => {
+    session?.client.applyExternalUpsert(item)
+}
+
+/**
+ * Relays an externally-known item removal into the resident stream data.
+ * 外部由来のアイテム削除を常駐ストリームデータへ中継する処理。
+ *
+ * report-delete SSE・ローカル削除・stale 安全弁から呼ばれる。
+ * これを欠くと、鮮度窓内の再訪で「削除したはずの日報が蘇る」。
+ */
+export const removeDailyReportIdsStreamItem = (reportHubId: number): void => {
+    session?.client.applyExternalRemoval(reportHubId)
+}
+
+/**
+ * Restarts a failed stream (UI retry button entry point).
+ * failed ストリームを再開する処理 (UI の再試行ボタン入口)。
+ */
+export const retryDailyReportIdsStream = (): void => {
+    session?.client.retry()
+}
+
+/**
+ * Re-validates the stream, optionally bypassing the server-side cache.
+ * ストリームを再検証する処理 (サーバーキャッシュのバイパス指定可)。
+ *
+ * 開発向けリロード/キャッシュクリアボタンから呼ばれる。
+ *
+ * @param options.forceRefresh サーバー側 SqlResultCache をバイパスするか。
+ */
+export const refreshDailyReportIdsStream = (options: { forceRefresh?: boolean } = {}): void => {
+    session?.client.refresh(options)
+}
+
+/**
+ * Returns the current session's owner key (undefined when no session exists).
+ * 現行セッションの持ち主 (userKey) を返す処理 (セッション不在時は undefined)。
+ *
+ * 遅延解決するミューテーション継続の門番に使う。POST /action の待機中にリロード無しの
+ * ユーザー切替が起きると、切替時の三重遮断 (セッション破棄 + 詳細キャッシュ破棄 +
+ * プロバイダーリマウント) の**後**に旧ユーザーの継続が解決し、モジュール常駐状態
+ * (新ユーザーのセッション・詳細キャッシュ) へ旧ユーザーのデータを注入してしまう。
+ * 継続側は開始時点の userKey とこの値を比較し、不一致 (undefined 含む) なら
+ * モジュール常駐状態への書き込みを放棄する (fail-closed)。
+ */
+export const getDailyReportIdsStreamSessionUserKey = (): string | null | undefined => session?.userKey
+
+/** セッション購読 (useSyncExternalStore 用)。 */
+const subscribeSession = (listener: () => void): (() => void) => {
+    sessionListeners.add(listener)
+    return () => sessionListeners.delete(listener)
+}
+
+/** 現在のスナップショットを返す (セッション未生成時は不変の IDLE)。 */
+const getSessionSnapshot = (): DailyReportIdsStreamState => session?.client.getState() ?? IDLE_STATE
+
+/** SSR スナップショット (常に IDLE)。 */
+const getServerSnapshot = (): DailyReportIdsStreamState => IDLE_STATE
+
+/**
+ * React binding for the module-resident ids stream session.
+ * モジュール常駐 ids ストリームセッションの React バインディング。
+ *
+ * セッションが後から生成されても再購読なしで追従する (リスナーはセッションではなく
+ * モジュールに属する)。スナップショット参照は publish 単位で安定している。
+ *
+ * @returns Current stream state. 現在のストリーム状態。
+ */
+export const useDailyReportIdsStream = (): DailyReportIdsStreamState => {
+    return useSyncExternalStore(subscribeSession, getSessionSnapshot, getServerSnapshot)
+}
+
+/**
+ * Destroys the session (test isolation helper).
+ * セッションを破棄するテスト用ヘルパー。
+ */
+export const resetDailyReportIdsStreamSessionForTesting = (): void => {
+    destroySession()
+}
+
+// HMR: モジュール差し替え時に旧セッションの接続とリスナーを確実に始末する
+if (typeof import.meta !== "undefined" && (import.meta as { hot?: { dispose: (cb: () => void) => void } }).hot) {
+    ;(import.meta as unknown as { hot: { dispose: (cb: () => void) => void } }).hot.dispose(() => {
+        destroySession()
+    })
+}

package/src/client.ts

@@ -9,15 +9,19 @@ export * from "./client/components/daily-report-comment-item"
 export * from "./client/components/daily-report-comment-section"
 export * from "./client/components/daily-report-detail-list"
 export * from "./client/components/daily-report-edit-form"
+export * from "./client/components/daily-report-ids-stream-status"
 export * from "./client/components/daily-report-list"
 export * from "./client/components/daily-report-page"
 export * from "./client/components/daily-report-resolved-content"
 export * from "./client/components/unread-indicator"
 export * from "./client/config-context"
 export * from "./client/contexts/daily-report-action-context"
+export * from "./client/hooks/use-animated-number"
 export * from "./client/hooks/use-daily-report"
 export * from "./client/hooks/use-daily-report-comments"
 export * from "./client/hooks/use-daily-report-sse-connection"
 export * from "./client/hooks/use-dynamic-viewport-height"
 export * from "./client/route-helpers"
+export * from "./client/streaming/daily-report-ids-stream-client"
+export * from "./client/streaming/daily-report-ids-stream-session"
 export * from "./client/utils/constants"

package/src/index.ts

@@ -4,6 +4,7 @@
  */
 export * from "./shared/business-date"
 export * from "./shared/comment-adapter"
+export * from "./shared/ids-stream"
 export * from "./shared/logger"
 export * from "./shared/sse-schema"
 export * from "./shared/text-utils"