@aiquants/daily-report 0.7.0 → 0.9.0

package/README.md

@@ -62,7 +62,8 @@ The standalone build bundles every JSX utility (and maps the shadcn tokens), but
 
 ## Required database schema
 
-Six tables: `DailyReportHub` (core/cross-source), `DailyReportInternal` (in-app content), `DailyReportComment`, `DailyReportLabel`, `DailyReportHub_Label`, `DailyReportUserStatus` (read status & stars).
+Seven tables: `DailyReportHub` (core/cross-source), `DailyReportInternal` (in-app content), `DailyReportComment`, `DailyReportLabel`, `DailyReportHub_Label`, `DailyReportUserStatus` (read status & stars), and the optional `DailyReportAttachment` (attachment metadata — omit it and the attachment feature degrades gracefully: `attachments` stays an empty array and the attachment endpoint returns 404 for every token).
+Attachment delivery additionally requires the `attachmentIdCodec` and `readAttachment` DI ports on `createDailyReportServer` (see `DailyReportServerConfig`); the factory then exposes `dailyReportServer.attachment.loader`, which the host app must mount on its own byte-serving route (e.g. `daily_report.api.attachment.$token` — a route separate from the `:endpoint` JSON router, whose fixed `Content-Type: application/json` + CSP headers are incompatible with byte delivery).
 
 Existing apps can inject their own drizzle models (structural typing — see `DailyReportTables`). Greenfield projects can generate definitions:
 
@@ -126,16 +127,15 @@ export const loader = (args) => dailyReportServer.sse.loader(args)
 import { createDailyReportClientLoader, DailyReportPage, dailyReportShouldRevalidate } from "@aiquants/daily-report/client"
 
 export const shouldRevalidate = dailyReportShouldRevalidate
-export const clientLoader = createDailyReportClientLoader()   // Deferred fetching of /daily_report/api/ids
+export const clientLoader = createDailyReportClientLoader()   // Bootstraps the module-resident ids NDJSON stream session
 
 export default function Route() {
-    const { user, userId, dailyReportIds } = useLoaderData<typeof clientLoader>()
+    const { user, userId } = useLoaderData<typeof clientLoader>()
     return (
         <YourAppLayout>
             <DailyReportPage
                 user={user}
                 userId={userId}
-                dailyReportIds={dailyReportIds}
                 config={{
                     renderHeader: ({ title, annotation }) => <YourHeader title={title} annotation={annotation} />,
                     showDevControls: import.meta.env.DEV,   // Toggle SSE subscriptions, etc.
@@ -153,9 +153,16 @@ export default function Route() {
 
 `DailyReportPage` is layout-agnostic (header rendering via `renderHeader` slot, error boundaries/footer control managed by the app). For fine-grained usage, `DailyReportActionProvider`, `DailyReportResolvedContent`, `useDailyReportDetail`, etc. can be imported individually.
 
+The report id list is **not** part of the loader data: a module-resident NDJSON stream session (`GET {apiBasePath}/ids-stream`, resilient client with cursor resume + exponential backoff) supplies it.
+`createDailyReportClientLoader` warms an existing session (`primeDailyReportIdsStreamSession`) and then bootstraps (`bootstrapDailyReportIdsStreamSession`): when no session exists it is **created at loader time** so the stream fetch runs in parallel with hydration (the dominant cold-load optimization); when one exists, the obfuscated user id is reconciled (a different user destroys and recreates the session before render).
+If your app overrides `config.apiBasePath`, pass the same value to `createDailyReportClientLoader({ apiBasePath })` — forgetting it costs one wrong-path request on the very first load, self-healed by the page-mount `ensureDailyReportIdsStreamSession`.
+`DailyReportPage` subscribes via `useDailyReportIdsStream`, rendering the list as soon as the first chunk arrives (on cache misses the server races a fast `TOP 200` first page against the cached full query, so first paint does not wait for the full id scan).
+There is no `dailyReportIds` prop and no deferred `/ids` JSON fetch (the old `ids` endpoint was removed).
+
 ### Field Labels (`fieldLabels`)
 
-Card and detail headings (`id` / `businessDate` / `author` / `visitTime` / `createdAt` / `updatedAt` / `updatedBy` / `category` / `categoryInfo` / `creationCategory` / `customer` / `subject` / `content` / `interviewers` / `comments` / `tabArticle` / `tabRelations` / `relationsEmpty`) are fully dependency-injected. **The package includes neutral English defaults** (`Business date` / `Customer` / `Content`, etc.), and consuming applications override headings via `fieldLabels`. This ensures the package itself carries no domain-specific wording. Partial overrides merge deeply over defaults (`DailyReportConfigProvider` performs a 1-level deep merge).
+Card and detail headings (`id` / `businessDate` / `author` / `visitTime` / `createdAt` / `updatedAt` / `updatedBy` / `category` / `categoryInfo` / `creationCategory` / `customer` / `subject` / `content` / `interviewers` / `comments` / `attachments` / `attachmentMissing` / `attachmentDownload` / `tabArticle` / `tabRelations` / `relationsEmpty` — all 21 keys of `DailyReportFieldLabels`) are fully dependency-injected.
+**The package includes neutral English defaults** (`Business date` / `Customer` / `Content`, etc.), and consuming applications override headings via `fieldLabels`. This ensures the package itself carries no domain-specific wording. Partial overrides merge deeply over defaults (`DailyReportConfigProvider` performs a 1-level deep merge).
 
 ### External Source Badge Configuration (`sourceTypeConfigs`)
 
@@ -226,7 +233,7 @@ export default defineConfig({
 ## API Surface (Summary)
 
 - **server**: `createDailyReportServer` / `createDailyReportService` / `createDailyReportHandlers` / `defineDailyReportSchema` / `DailyReportSseReader` / `SqlResultCache` / `transformJsonArray` / `jsonResponseWithETag` / `generateETag` / `isStreamIdLte`
-- **client**: `DailyReportPage` / `DailyReportResolvedContent` / `DailyReportList` / `DailyReportDetailList` / `DailyReportActionProvider` / `useDailyReportActionContext` / `useDailyReportDetail` / `useDailyReportPrefetch` / `useDailyReportComments` / `useDailyReportSseConnection` / `DailyReportConfigProvider` / `createDailyReportClientLoader` / `dailyReportShouldRevalidate`
+- **client**: `DailyReportPage` / `DailyReportResolvedContent` / `DailyReportList` / `DailyReportDetailList` / `DailyReportActionProvider` / `useDailyReportActionContext` / `useDailyReportDetail` / `useDailyReportPrefetch` / `useDailyReportComments` / `useDailyReportSseConnection` / `useDailyReportIdsStream` / `DailyReportIdsStreamStatus` / `DailyReportIdsStreamClient` / `DailyReportConfigProvider` / `createDailyReportClientLoader` / `dailyReportShouldRevalidate`
 - **shared**: `DailyReportItem` / `DailyReportDetail` / `DailyReportUser` / `dailyReportSseMessageSchema` (8 discriminated union types) / `normalizeBusinessDateKey` / `mergeComments`
 
 MIT

package/dist/client.d.mts

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { ReactNode, Context, RefObject } from 'react';
 import { ScrollBarThumbOverlayRenderProps, ScrollPaneInertiaOptions, ScrollBarTapCircleOptions } from '@aiquants/virtualscroll';
 import { D as DailyReportAttachmentSummary, a as DailyReportItem, b as DailyReportDetail, c as DailyReportUser } from './types-Ct1ggzy-.mjs';
-import { U as UIComment, D as DailyReportSseMessage } from './sse-schema-Df49KA7B.mjs';
+import { U as UIComment, D as DailyReportSseMessage } from './sse-schema-BiUnufrI.mjs';
 import { ShouldRevalidateFunction } from 'react-router';
 import 'zod';
 
@@ -107,10 +107,14 @@ type DailyReportEditFormProps = {
 };
 declare const DailyReportEditForm: ({ report, onCancel, onPublishSuccess }: DailyReportEditFormProps) => react.JSX.Element;
 
+/**
+ * Renders the streaming progress / recovery badge for the ids stream.
+ * ids ストリームの進捗・復旧バッジを描画するコンポーネント。
+ */
+declare const DailyReportIdsStreamStatus: () => react.JSX.Element | null;
+
 type DailyReportListProps = {
     dailyReportItems: DailyReportItem[];
-    initialSelectedBusinessDate?: string | null;
-    initialSelectedReportHubId?: number | null;
     autoMarkRead?: boolean;
     selectedReportHubId: number | null;
     onSelectItem: (reportHubId: number | null) => void;
@@ -122,7 +126,7 @@ type DailyReportListProps = {
  * Daily report list cards with key metadata and preview content via virtual scrolling.
  * 主なメタデータと内容プレビューを仮想スクロール表示する日報リスト。
  */
-declare const DailyReportList: ({ dailyReportItems, initialSelectedBusinessDate, initialSelectedReportHubId, autoMarkRead, selectedReportHubId, onSelectItem, userId, initialScrollOffset, onScrollOffsetChange }: DailyReportListProps) => react.JSX.Element;
+declare const DailyReportList: ({ dailyReportItems, autoMarkRead, selectedReportHubId, onSelectItem, userId, initialScrollOffset, onScrollOffsetChange }: DailyReportListProps) => react.JSX.Element;
 
 /** ヘッダー描画スロットに渡される引数。 */
 type DailyReportHeaderProps = {
@@ -161,6 +165,18 @@ type DailyReportFieldLabels = {
     tabRelations: string;
     relationsEmpty: string;
 };
+/**
+ * Mutation-failure notification payload (for a host-supplied error surface).
+ * ミューテーション失敗の通知情報 (ホストが独自の通知 UI を出すための口)。
+ */
+type DailyReportErrorInfo = {
+    /** 失敗した操作の種別 (create / update / publish / delete / addComment / deleteComment / toggleStar / toggleRead)。 */
+    operation: string;
+    /** 表示用のメッセージ (パッケージ内蔵バナー用)。 */
+    message: string;
+    /** 元例外 (診断用)。 */
+    cause?: unknown;
+};
 /** データソースごとのバッジ表示設定。 */
 type SourceTypeConfig = {
     label: string;
@@ -186,6 +202,11 @@ type DailyReportClientConfig = {
     renderHeader: (props: DailyReportHeaderProps) => ReactNode;
     /** 開発向けコントロール (SSE 購読トグル等) を表示するか。 */
     showDevControls: boolean;
+    /**
+     * ミューテーション失敗時の通知ポート。未指定ならパッケージ内蔵の role="alert"
+     * バナーで表示する。ホストが独自トースト等を持つ場合はここへ委譲する。
+     */
+    onError?: (info: DailyReportErrorInfo) => void;
 };
 /**
  * Partial client-config override. `fieldLabels` may itself be partially overridden.
@@ -219,13 +240,15 @@ declare const useDailyReportConfig: () => DailyReportClientConfig;
 declare const resolveSourceTypeConfig: (sourceType?: string | null, sourceTypeConfigs?: Record<string, SourceTypeConfig>) => SourceTypeConfig | undefined;
 
 /**
- * Error display component for daily report data fetch failures.
- * 日報データの取得失敗時に表示するエラーコンポーネント。
+ * Error display when the ids stream terminally failed before any data arrived.
+ * データ未受信のまま ID ストリームが力尽きたときのエラー表示コンポーネント。
+ *
+ * 再試行はストリームセッションの retry へ直結する (受信済みカーソルから再開)。
  */
 declare const DailyReportLoadError: () => react.JSX.Element;
 /**
- * Suspense fallback while daily report identifiers resolve.
- * 日報 ID 解決中のサスペンスフォールバック。
+ * Loading screen shown only until the first stream chunk arrives.
+ * 最初のストリームチャンクが届くまでの間だけ表示するローディング画面。
  */
 declare const DailyReportLoading: () => react.JSX.Element;
 type DailyReportPageProps = {
@@ -233,8 +256,6 @@ type DailyReportPageProps = {
     user?: DailyReportUser;
     /** 難読化済みの内部ユーザー ID (未登録ユーザーは null)。 */
     userId?: string | null;
-    /** clientLoader で defer した日報 ID 一覧 (Promise) または解決済み配列。 */
-    dailyReportIds?: Promise<DailyReportItem[]> | DailyReportItem[] | null;
     /** クライアント設定の部分上書き (ヘッダー描画・パス・ラベル名・フィールドラベルなど)。 */
     config?: DailyReportClientConfigInput;
 };
@@ -245,14 +266,15 @@ type DailyReportPageProps = {
 declare const DailyReportPage: ({ config, ...rest }: DailyReportPageProps) => react.JSX.Element;
 
 type DailyReportResolvedContentProps = {
-    dailyReportItems: DailyReportItem[];
     userId?: string | null;
 };
 /**
- * Displays fetched daily reports with layout and tabbed virtual scroll views.
- * レイアウトとタブ付き仮想スクロールで取得済み日報を表示するコンポーネント。
+ * Displays streamed daily reports with layout and tabbed virtual scroll views.
+ * レイアウトとタブ付き仮想スクロールでストリーム受信済み日報を表示するコンポーネント。
+ *
+ * アイテムは Action Context (ストリームチャンクをマージ済み) から読む。
  */
-declare const DailyReportResolvedContent: ({ dailyReportItems: _initialItems, userId }: DailyReportResolvedContentProps) => react.JSX.Element;
+declare const DailyReportResolvedContent: ({ userId }: DailyReportResolvedContentProps) => react.JSX.Element;
 
 type UnreadIndicatorProps = {
     className?: string;
@@ -343,6 +365,35 @@ declare const DailyReportActionProvider: ({ children, user, initialItems, userId
     userId?: string | null;
 }) => react.JSX.Element;
 
+type DailyReportErrorSurface = {
+    /** ミューテーション失敗を通知する。 */
+    notifyError: (info: DailyReportErrorInfo) => void;
+};
+/**
+ * Returns the error-surface API (safe no-op outside the provider).
+ * 通知 API を返す処理 (Provider 外では no-op)。
+ */
+declare const useDailyReportErrorSurface: () => DailyReportErrorSurface;
+/**
+ * Provides the mutation error surface and renders the default alert banner.
+ * ミューテーション通知シームを供給し、既定のアラートバナーを描画するプロバイダー。
+ *
+ * `config.onError` があればホストへ委譲し、内蔵バナーは描画しない (二重表示防止)。
+ */
+declare const DailyReportErrorProvider: ({ children }: {
+    children: ReactNode;
+}) => react.JSX.Element;
+
+/**
+ * Animates numeric changes with ease-out cubic.
+ * 数値変化をイーズアウト 3 次で補間するフック。
+ *
+ * @param value Target value. 目標値。
+ * @param durationMs Animation duration. アニメーション時間 (既定 250ms)。
+ * @returns Displayed (interpolated) value. 表示用の補間値。
+ */
+declare const useAnimatedNumber: (value: number, durationMs?: number) => number;
+
 type CacheEntry<T> = {
     data: T;
     expiresAt: number;
@@ -451,7 +502,21 @@ declare const registerRecentDeletion: (cId: number) => Map<number, number>;
  * 解除関数を返す。
  */
 declare const subscribeCacheReady: (reportHubId: number, callback: () => void) => (() => void);
-declare const applyDailyReportServerUpdates: (_reportHubIdd: number, report: DailyReportDetail) => void;
+declare const applyDailyReportServerUpdates: (_reportHubId: number, report: DailyReportDetail) => void;
+/**
+ * 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} を使うこと — そちらは値をそのまま書く。
+ */
+declare const applyBroadcastReportUpdate: (report: DailyReportDetail) => void;
 type DailyReportDetailResource = {
     report: DailyReportDetail | null;
     error: Error | null;
@@ -538,13 +603,17 @@ declare const useDynamicViewportHeight: (containerRef: RefObject<HTMLDivElement
  */
 declare const dailyReportShouldRevalidate: ShouldRevalidateFunction;
 /**
- * Fetches the deferred daily report id list from the API endpoint.
- * API エンドポイントから日報 ID 一覧を遅延取得する処理。
- */
-declare const fetchDailyReportIds: (apiBasePath?: string, forceRefresh?: boolean) => Promise<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` を付与済み (初期ハイドレーションでも実行される)。
  */
@@ -553,12 +622,355 @@ declare const createDailyReportClientLoader: <TServerData extends Record<string,
 }) => {
     (args: {
         serverLoader: () => Promise<unknown>;
-    }): Promise<TServerData & {
-        dailyReportIds: Promise<DailyReportItem[]>;
-    }>;
+    }): Promise<TServerData>;
     hydrate: true;
 };
 
+/** ストリームのライフサイクル局面。 */
+type DailyReportIdsStreamPhase = "idle" | "streaming" | "retrying" | "complete" | "failed" | "auth-required";
+/** publish されるスナップショット。publish 間で参照が安定している。 */
+type DailyReportIdsStreamState = {
+    /** 受信済みアイテム (reportHubId で重複排除済み)。 */
+    items: DailyReportItem[];
+    /** 一意アイテム件数 (`items.length` と同値。表示用の別名)。 */
+    loadedCount: number;
+    /** サーバー申告の全体件数。先頭行未着なら null。 */
+    totalCount: number | null;
+    /** ライフサイクル局面。 */
+    phase: DailyReportIdsStreamPhase;
+    /** complete 後のバックグラウンド再検証が走っているか。 */
+    isRevalidating: boolean;
+    /** 一度でも完走したか (再検証中の UI 判定に使う)。 */
+    hasCompletedOnce: boolean;
+    /**
+     * 直近の「実際の完走」時刻 (未完走は null)。鮮度判定 (SWR 窓) の唯一の根拠。
+     * 完走の publish でのみ更新される — 再検証の諦めなど phase が complete のままの
+     * publish で更新すると、古いデータが新鮮扱いされ再検証が永久に走らなくなる。
+     */
+    completedAt: number | null;
+    /** 直近の失敗 (成功で null に戻る)。 */
+    error: Error | null;
+};
+/** テスト注入用の依存一式。 */
+type DailyReportIdsStreamClientOptions = {
+    /** API ベースパス (既定 `/daily_report/api`)。 */
+    apiBasePath?: string;
+    /** fetch 実装 (既定 globalThis.fetch)。 */
+    fetchFn?: (input: string, init: {
+        signal: AbortSignal;
+        headers: Record<string, string>;
+        cache: RequestCache;
+    }) => Promise<Response>;
+    /** タイマー実装 (既定 setTimeout / clearTimeout)。 */
+    setTimeoutFn?: (handler: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimeoutFn?: (id: ReturnType<typeof setTimeout>) => void;
+    /**
+     * 1 回の read が無音でいられる上限 (ms)。0 以下で無効。
+     * これを超えたら接続を half-open とみなして中断し、retryable として
+     * カーソル再開へ倒す。サーバーのハートビート間隔より必ず長く取る
+     * (生きているが遅いだけの全量クエリ待ちを誤って切らないため)。
+     */
+    readStallTimeoutMs?: number;
+    /** 警告ロガー (既定 console.warn)。 */
+    warn?: (...args: unknown[]) => void;
+    /**
+     * チャンク由来 publish の合体窓 (ms)。0 で無効 (毎チャンク即時 publish)。
+     * 高速回線ではネットワーク read が密集し、publish ごとに全件ソート + 全行再レンダーが
+     * 走るため、先頭は即時 (初回描画優先)・後続は窓内で合体するスロットルを掛ける。
+     * 完走 publish と外部ミューテーション (ユーザー操作の即時フィードバック) は対象外。
+     */
+    publishCoalesceMs?: number;
+};
+/**
+ * NDJSON ids stream client with dedupe, cursor resume, and exponential backoff.
+ * 重複排除・カーソル再開・指数バックオフを備えた NDJSON ids ストリームクライアント。
+ */
+declare class DailyReportIdsStreamClient {
+    private readonly apiBasePath;
+    private readonly fetchFn;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly warn;
+    /** 1 回の read が無音でいられる上限 (ms)。0 以下で無効。 */
+    private readonly readStallTimeoutMs;
+    /** reportHubId → アイテム。挿入順を保ち、再開の重複到着を吸収する。 */
+    private readonly itemMap;
+    private readonly listeners;
+    private state;
+    private lastCursor;
+    private consecutiveFailures;
+    private started;
+    private disposed;
+    /** 実行中ループの世代。refresh/dispose で進め、旧ループの続行を無効化する。 */
+    private loopGeneration;
+    private activeAbortController;
+    /**
+     * 先頭 (cursor 無し) から始まった走査で観測した ID の集合。
+     * 完走時にこの集合へ含まれない Map エントリを剪定し、サーバー側で削除された
+     * 日報がモジュール常駐データに永久残留するのを防ぐ。途中失敗のカーソル再開は
+     * 同じ走査の続きなので集合を引き継ぐ (全区間の和 = サーバーの全量)。
+     */
+    private activeSeenIds;
+    /**
+     * 外部削除のトゥームストーン。サーバーは配列全体を先に確定させてから送出するため、
+     * 走査中に届いた削除の後、同じ削除前スナップショットの後続チャンクが同 ID を
+     * 再配送してくる。これを吸収せずに素通しすると、削除済み日報が Map へ戻り
+     * 完走剪定も免れてしまう (観測集合に再記録されるため)。新しい走査の開始
+     * (削除コミット後のスナップショット) でクリアする。
+     */
+    private readonly externalRemovalTombstones;
+    /**
+     * 走行中の再検証中に届いた明示的キャッシュバイパス要求の持ち越しフラグ。
+     * 走行中の再検証は中断しない方針のため、要求を黙って捨てず完走後に連結実行する。
+     */
+    private pendingForceRefresh;
+    private wakeRetryWait;
+    private readonly handleOnline;
+    /** チャンク由来 publish の合体窓 (ms)。 */
+    private readonly publishCoalesceMs;
+    /** 合体窓のトレーリングタイマー。 */
+    private publishCoalesceTimer;
+    /** 直近のアイテム publish 時刻 (leading edge 判定用)。 */
+    private lastItemsPublishAt;
+    constructor(options?: DailyReportIdsStreamClientOptions);
+    /**
+     * Returns the current snapshot (stable reference between publishes).
+     * 現在のスナップショットを返す処理 (publish 間で参照が安定)。
+     */
+    getState(): DailyReportIdsStreamState;
+    /**
+     * Subscribes to snapshot updates.
+     * スナップショット更新の購読を登録する処理。
+     *
+     * @param listener Change callback. 変更通知コールバック。
+     * @returns Unsubscribe function. 購読解除関数。
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Starts the initial stream (idempotent).
+     * 初回ストリーミングを開始する処理 (冪等)。
+     */
+    start(): void;
+    /**
+     * Restarts after a terminal failure (no-op unless phase is "failed").
+     * failed からの手動再開処理 (failed 以外では何もしない)。
+     *
+     * 受信済みデータと再開カーソルは保持したまま続きから読む。
+     */
+    retry(): void;
+    /**
+     * Revalidates a completed stream in the background (SWR-style).
+     * 完走済みストリームをバックグラウンドで再検証する処理 (SWR)。
+     *
+     * カーソルを捨てて先頭から読み直し、Map の重複排除で差分を上書き吸収し、
+     * 完走時に「今回の走査で観測されなかった行」を剪定する (サーバー側削除の反映)。
+     * failed のときはカーソルを保持した再開に切り替える (forceRefresh 指定は失わない)。
+     * streaming/retrying 中は何もしない。
+     *
+     * @param options.forceRefresh サーバー側 SqlResultCache をバイパスするか。
+     */
+    refresh(options?: {
+        forceRefresh?: boolean;
+    }): void;
+    /**
+     * Applies an externally-known upsert (SSE / local mutation) to the resident data.
+     * 外部由来 (SSE / ローカル操作) の upsert を常駐データへ反映する処理。
+     *
+     * これを欠くと、マウント中に作成された日報がストリームセッションに存在せず、
+     * 鮮度窓内の再訪 (再検証なし) で一覧から消える。アクティブな走査中は観測集合にも
+     * 刻み、完走時の剪定で「生きていると分かっている行」を誤って落とさないようにする。
+     */
+    applyExternalUpsert(item: DailyReportItem): void;
+    /**
+     * Applies an externally-known removal (SSE report-delete / stale valve) to the resident data.
+     * 外部由来 (SSE report-delete / stale 安全弁) の削除を常駐データへ反映する処理。
+     *
+     * 走査中の後続チャンク (削除前スナップショット) による同一行の再配送は、
+     * クライアント側トゥームストーンが次の新しい走査までブロックする。
+     */
+    applyExternalRemoval(reportHubId: number): void;
+    /**
+     * Aborts everything and detaches listeners (terminal).
+     * すべてを中断しリスナーを外す終了処理 (以後再利用不可)。
+     */
+    dispose(): void;
+    /**
+     * Connection-retry loop: stream → classify → backoff → resume.
+     * 接続リトライループ。ストリーム → 結果分類 → バックオフ → カーソル再開。
+     */
+    private runStreamLoop;
+    /**
+     * Prunes map entries not observed by the completed full scan.
+     * 完走した全量走査で観測されなかった Map エントリを剪定する処理。
+     *
+     * サーバー側で削除された日報の残留 (再訪時の亡霊復活・loadedCount > totalCount) を防ぐ。
+     * 観測集合が無い場合 (理論上到達しない防御) は何も消さない。
+     */
+    private pruneUnseenItems;
+    /**
+     * Runs one streaming attempt and classifies its outcome.
+     * 1 回のストリーミング試行を実行し、結末を分類する処理。
+     */
+    private streamOnce;
+    /**
+     * Reads one chunk, racing the read against a stall watchdog.
+     * 1 チャンクを読む処理。読み取りを stall ウォッチドッグと競争させる。
+     *
+     * サーバーが無音のまま接続を half-open で放置しても (NAT/プロキシのアイドル切断・
+     * VPN 断・スリープ)、`reader.read()` は永久に保留したままになる。これを検知するため
+     * read とタイマーを競争させ、無音が上限を超えたら番兵を返す。生きているが遅いだけの
+     * 全量クエリ待ちはサーバーのハートビート (空行) が read を解決するので誤検知しない。
+     * `readStallTimeoutMs <= 0` のときは素の read (タイマーを張らない・テスト用)。
+     *
+     * @returns 読み取り結果、または stall を表す番兵。read の reject はそのまま伝播する。
+     */
+    private readWithStallGuard;
+    /**
+     * Merges chunk items into the dedupe map.
+     * チャンクのアイテム群を重複排除 Map へ取り込む処理。
+     *
+     * @returns True when anything was added or changed. 追加または内容変化があれば true。
+     */
+    private absorbChunkItems;
+    /** アイテム配列を再スナップショットして即時 publish する。 */
+    private publishItems;
+    /**
+     * チャンク由来のアイテム publish をスロットルする (leading edge 即時 + trailing 合体)。
+     * 最初のチャンクは即時に描画へ届け、窓内に密集した後続チャンクは 1 回の publish
+     * (= 1 回の全件ソートと再レンダー) へ合体する。合体窓 0 は無効 (常に即時)。
+     */
+    private schedulePublishItems;
+    /** 保留中のトレーリング publish を破棄する (完走 publish が全量を運ぶ場合など)。 */
+    private cancelScheduledPublishItems;
+    /** 部分状態をマージした新スナップショットを作り、購読者へ通知する。 */
+    private publish;
+    /** 再開カーソル付きのストリーム URL を構築する。 */
+    private buildStreamUrl;
+    /**
+     * バックオフ待機。online イベント・dispose・後続ループの開始で早期解除される。
+     *
+     * タイマー ID は待機ごとのローカルに閉じ、共有スロット (wakeRetryWait) は
+     * 「まだ自分を指しているときだけ」外す。単一スロットへ素朴に書くと、
+     * 追い越された旧待機の finish が新しいループのタイマーを消してしまい、
+     * 再検証が永久に固まる (実測済みの競合)。
+     */
+    private waitBeforeRetry;
+}
+
+/**
+ * Full-document reload indirection (mockable seam for auth-expiry tests).
+ * ドキュメント全体を再読込する間接層 (認証切れテストで差し替え可能にする継ぎ目)。
+ */
+declare const reloadDocument: () => void;
+/**
+ * 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)。
+ */
+declare const ensureDailyReportIdsStreamSession: (options: {
+    apiBasePath?: string;
+    userKey: string | null;
+}) => void;
+/**
+ * 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)。
+ */
+declare const bootstrapDailyReportIdsStreamSession: (options: {
+    apiBasePath?: string;
+    userKey: string | null;
+}) => void;
+/**
+ * Kicks a freshness check for an existing session before the user is known.
+ * ユーザー確定前に既存セッションの鮮度確認だけを先行させる処理。
+ *
+ * clientLoader が serverLoader を await する前に呼び、再訪 (支配的経路) の
+ * 再検証開始を数十〜数百 ms 前倒しする。セッションが無ければ何もしない
+ * (誰のデータを読むべきか分からないため)。直後の reconcile が userKey を照合し、
+ * ユーザーが変わっていればセッションごと破棄されるので先行は安全。
+ * 走行中の再検証は中断しない (runFreshnessCheck の isRevalidating ガード)。
+ */
+declare const primeDailyReportIdsStreamSession: () => void;
+/**
+ * Relays an externally-known item upsert into the resident stream data.
+ * 外部由来のアイテム upsert を常駐ストリームデータへ中継する処理。
+ *
+ * プロバイダーの作成/公開系ミューテーション (ローカル操作と SSE) から呼ばれる。
+ * これを欠くと、鮮度窓内の再訪で「作成したばかりの日報が消える」。
+ */
+declare const upsertDailyReportIdsStreamItem: (item: DailyReportItem) => void;
+/**
+ * Relays an externally-known item removal into the resident stream data.
+ * 外部由来のアイテム削除を常駐ストリームデータへ中継する処理。
+ *
+ * report-delete SSE・ローカル削除・stale 安全弁から呼ばれる。
+ * これを欠くと、鮮度窓内の再訪で「削除したはずの日報が蘇る」。
+ */
+declare const removeDailyReportIdsStreamItem: (reportHubId: number) => void;
+/**
+ * Restarts a failed stream (UI retry button entry point).
+ * failed ストリームを再開する処理 (UI の再試行ボタン入口)。
+ */
+declare const retryDailyReportIdsStream: () => void;
+/**
+ * Re-validates the stream, optionally bypassing the server-side cache.
+ * ストリームを再検証する処理 (サーバーキャッシュのバイパス指定可)。
+ *
+ * 開発向けリロード/キャッシュクリアボタンから呼ばれる。
+ *
+ * @param options.forceRefresh サーバー側 SqlResultCache をバイパスするか。
+ */
+declare const refreshDailyReportIdsStream: (options?: {
+    forceRefresh?: boolean;
+}) => void;
+/**
+ * Returns the current session's owner key (undefined when no session exists).
+ * 現行セッションの持ち主 (userKey) を返す処理 (セッション不在時は undefined)。
+ *
+ * 遅延解決するミューテーション継続の門番に使う。POST /action の待機中にリロード無しの
+ * ユーザー切替が起きると、切替時の三重遮断 (セッション破棄 + 詳細キャッシュ破棄 +
+ * プロバイダーリマウント) の**後**に旧ユーザーの継続が解決し、モジュール常駐状態
+ * (新ユーザーのセッション・詳細キャッシュ) へ旧ユーザーのデータを注入してしまう。
+ * 継続側は開始時点の userKey とこの値を比較し、不一致 (undefined 含む) なら
+ * モジュール常駐状態への書き込みを放棄する (fail-closed)。
+ */
+declare const getDailyReportIdsStreamSessionUserKey: () => string | null | undefined;
+/**
+ * React binding for the module-resident ids stream session.
+ * モジュール常駐 ids ストリームセッションの React バインディング。
+ *
+ * セッションが後から生成されても再購読なしで追従する (リスナーはセッションではなく
+ * モジュールに属する)。スナップショット参照は publish 単位で安定している。
+ *
+ * @returns Current stream state. 現在のストリーム状態。
+ */
+declare const useDailyReportIdsStream: () => DailyReportIdsStreamState;
+/**
+ * Destroys the session (test isolation helper).
+ * セッションを破棄するテスト用ヘルパー。
+ */
+declare const resetDailyReportIdsStreamSessionForTesting: () => void;
+
 /**
  * Shared constants for Daily Report data fetching parameters.
  * 日報データ取得で利用する共通パラメーター。
@@ -622,4 +1034,4 @@ declare const TAP_SCROLL_CIRCLE_OPTIONS: ScrollBarTapCircleOptions;
  */
 declare const CONTENT_DRAG_POINTER_INPUTS: readonly ["pen", "touch"];
 
-export { BusinessDayThumbOverlay, CONTENT_DRAG_POINTER_INPUTS, DAILY_REPORT_FETCH_DEBOUNCE_MS, DEFAULT_ITEM_HEIGHT, DailyReportActionProvider, DailyReportAttachmentIndicator, DailyReportAttachmentList, DailyReportCache, type DailyReportClientConfig, type DailyReportClientConfigInput, DailyReportCommentForm, DailyReportCommentItem, DailyReportCommentList, DailyReportConfigProvider, DailyReportDetailList, type DailyReportDetailResource, DailyReportEditForm, type DailyReportFieldLabels, type DailyReportHeaderProps, DailyReportList, DailyReportLoadError, DailyReportLoading, DailyReportPage, type DailyReportPageProps, DailyReportResolvedContent, EMPTY_DETAIL, EMPTY_ITEM, FAST_SCROLL_INERTIA_OPTIONS, FAST_SCROLL_WHEEL_MULTIPLIER, ITEM_CONTAINER_HEIGHT, ITEM_VERTICAL_PADDING, MAX_PREVIEW_LINES, PREFETCH_LOOKAHEAD, PREFETCH_MAX_DATES, SCROLL_BAR_WIDTH, type SourceTypeConfig, TAP_SCROLL_CIRCLE_OPTIONS, UnreadIndicator, VIRTUAL_SCROLL_OVERSCAN_COUNT, WHEEL_RESET_TIMEOUT_MS, acquireMutationLock, applyDailyReportServerUpdates, clearDailyReportCache, createDailyReportClientLoader, dailyReportShouldRevalidate, defaultDailyReportClientConfig, defaultDailyReportFieldLabels, deleteDailyReportCache, fetchDailyReportIds, getCachedReport, registerRecentDeletion, releaseMutationLock, resolveSourceTypeConfig, subscribeCacheReady, updateDailyReportCache, useDailyReportActionContext, useDailyReportComments, useDailyReportConfig, useDailyReportDetail, useDailyReportPrefetch, useDailyReportSseConnection, useDynamicViewportHeight, writeCache };
+export { BusinessDayThumbOverlay, CONTENT_DRAG_POINTER_INPUTS, DAILY_REPORT_FETCH_DEBOUNCE_MS, DEFAULT_ITEM_HEIGHT, type DailyReportActionContextType, DailyReportActionProvider, DailyReportAttachmentIndicator, DailyReportAttachmentList, DailyReportCache, type DailyReportClientConfig, type DailyReportClientConfigInput, DailyReportCommentForm, DailyReportCommentItem, DailyReportCommentList, DailyReportConfigProvider, DailyReportDetailList, type DailyReportDetailResource, DailyReportEditForm, type DailyReportErrorInfo, DailyReportErrorProvider, type DailyReportFieldLabels, type DailyReportHeaderProps, DailyReportIdsStreamClient, type DailyReportIdsStreamClientOptions, type DailyReportIdsStreamPhase, type DailyReportIdsStreamState, DailyReportIdsStreamStatus, DailyReportList, DailyReportLoadError, DailyReportLoading, DailyReportPage, type DailyReportPageProps, DailyReportResolvedContent, EMPTY_DETAIL, EMPTY_ITEM, FAST_SCROLL_INERTIA_OPTIONS, FAST_SCROLL_WHEEL_MULTIPLIER, ITEM_CONTAINER_HEIGHT, ITEM_VERTICAL_PADDING, MAX_PREVIEW_LINES, PREFETCH_LOOKAHEAD, PREFETCH_MAX_DATES, SCROLL_BAR_WIDTH, type SourceTypeConfig, TAP_SCROLL_CIRCLE_OPTIONS, UnreadIndicator, VIRTUAL_SCROLL_OVERSCAN_COUNT, WHEEL_RESET_TIMEOUT_MS, acquireMutationLock, applyBroadcastReportUpdate, applyDailyReportServerUpdates, bootstrapDailyReportIdsStreamSession, clearDailyReportCache, createDailyReportClientLoader, dailyReportShouldRevalidate, defaultDailyReportClientConfig, defaultDailyReportFieldLabels, deleteDailyReportCache, ensureDailyReportIdsStreamSession, getCachedReport, getDailyReportIdsStreamSessionUserKey, primeDailyReportIdsStreamSession, refreshDailyReportIdsStream, registerRecentDeletion, releaseMutationLock, reloadDocument, removeDailyReportIdsStreamItem, resetDailyReportIdsStreamSessionForTesting, resolveSourceTypeConfig, retryDailyReportIdsStream, subscribeCacheReady, updateDailyReportCache, upsertDailyReportIdsStreamItem, useAnimatedNumber, useDailyReportActionContext, useDailyReportComments, useDailyReportConfig, useDailyReportDetail, useDailyReportErrorSurface, useDailyReportIdsStream, useDailyReportPrefetch, useDailyReportSseConnection, useDynamicViewportHeight, writeCache };