@arcote.tech/arc-chat 0.7.20 → 0.7.21

package/src/react/derive-timeline.ts

@@ -0,0 +1,416 @@
+import type { AssistantContentBlock } from "@arcote.tech/arc-ai";
+import { orderMessages } from "../ordering";
+
+// ─── Czysta derywacja timeline'u ─────────────────────────────────
+//
+// Timeline NIE jest mutowalnym stanem — jest czystą funkcją dwóch źródeł:
+//   1. DB (liveQuery `getByScope`) — jedyne źródło prawdy o STRUKTURZE:
+//      lista wiadomości, finalne blocks, isGenerating/interrupted/error,
+//      tool_results.
+//   2. Overlays — ulotny, in-progress stan per generujący assistant row
+//      (bloki budowane z SSE przez shared reducer).
+// Plus lokalny optimistic state (pending sends / pending tool results).
+//
+// Dzięki temu klasyczne race'y dwóch kanałów (SSE `done` vs flip
+// `isGenerating` w DB, tool_result w trakcie nowego turnu, zgubione
+// `done`) przestają istnieć: derywacja zawsze liczy się od NAJNOWSZEGO
+// stanu obu źródeł, niezależnie od kolejności ich dostarczenia.
+
+export type ToolStatus = "pending" | "executing" | "complete" | "error";
+
+export type TimelineItem =
+  | {
+      type: "message";
+      id: string;
+      role: "user" | "assistant";
+      content: string;
+      isStreaming?: boolean;
+    }
+  | {
+      type: "tool";
+      id: string; // = toolCallId, stabilne pomiędzy overlayem a final blocks
+      toolCallId: string;
+      toolName: string;
+      params: Record<string, unknown>;
+      result?: unknown;
+      status: ToolStatus;
+      /** Legacy compat — true gdy brak wyniku. Renderowane przez ChatToolLog. */
+      calling: boolean;
+      error?: string;
+    }
+  | {
+      type: "interrupted";
+      id: string;
+      messageId: string;
+    };
+
+export type OverlayStatus = "connecting" | "live" | "done" | "gone";
+
+export interface AssistantOverlay {
+  blocks: AssistantContentBlock[];
+  status: OverlayStatus;
+}
+
+export interface PendingSend {
+  localId: string;
+  content: string;
+  sentAt: number;
+  /** `messageId` zwrócony przez mutację `sendMessage` (gdy już resolved). */
+  dbId?: string;
+}
+
+export interface DeriveTimelineInput {
+  history: any[] | undefined;
+  overlays: ReadonlyMap<string, AssistantOverlay>;
+  pendingSends: readonly PendingSend[];
+  pendingToolResults: ReadonlyMap<string, unknown>;
+  isServerTool: (toolName: string) => boolean;
+  /** Wstrzykiwany zegar — testowalność + staleness cutoff reguły busy. */
+  now: number;
+}
+
+export interface DerivedTimeline {
+  items: TimelineItem[];
+  /**
+   * Czy konwersacja jest "zajęta" (input disabled). Wyprowadzane z DB,
+   * nie z lokalnego flagu — pokrywa też okna między iteracjami tool-loopa,
+   * gdy żaden row nie jest `isGenerating`.
+   */
+  busy: boolean;
+  /** Czy jakiś interactive tool czeka na odpowiedź użytkownika. */
+  hasWaitingInteractive: boolean;
+}
+
+/**
+ * Cutoff świeżości dla klauzul busy opartych o "ostatnia aktywność w DB".
+ * Chroni przed wiecznym disabled gdy listener padł między zapisami (np.
+ * wyjątek w buildInstructions po saveToolResult). Po przekroczeniu busy
+ * degraduje się do zachowania sprzed redesignu (input enabled mimo
+ * trwającej pętli) — bezpieczny gorszy przypadek.
+ */
+const BUSY_STALENESS_MS = 120_000;
+
+function ts(value: string | Date): number {
+  return value instanceof Date ? value.getTime() : new Date(value).getTime();
+}
+
+function tryParseJson(str: string): unknown {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return str;
+  }
+}
+
+function parseBlocks(raw: unknown): AssistantContentBlock[] {
+  // Adapter Postgresa auto-parsuje kolumny tekstowe wyglądające jak JSON
+  // (deserializeValue w postgres-adapter) — po hydracji store'a z bazy
+  // `blocks` przychodzi jako GOTOWA tablica, nie string. Oba kształty są
+  // poprawne na tej granicy.
+  if (Array.isArray(raw)) return raw as AssistantContentBlock[];
+  if (typeof raw !== "string" || raw.length === 0) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Czy optimistic pending send ma już swój odpowiednik w DB. Match po
+ * `dbId` (deterministyczny, gdy mutacja zdążyła resolve'ować) z fallbackiem
+ * po treści (liveQuery push potrafi wyprzedzić resolve mutacji).
+ */
+export function isPendingSendSettled(
+  history: any[] | undefined,
+  pending: PendingSend,
+): boolean {
+  if (!history) return false;
+  for (const row of history) {
+    if (pending.dbId && row._id === pending.dbId) return true;
+    if (
+      row.role === "user" &&
+      row.content === pending.content &&
+      ts(row.createdAt) >= pending.sentAt - 60_000
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function deriveTimeline(input: DeriveTimelineInput): DerivedTimeline {
+  const {
+    history,
+    overlays,
+    pendingSends,
+    pendingToolResults,
+    isServerTool,
+    now,
+  } = input;
+
+  const rows = orderMessages(history ?? []);
+
+  // Wyniki tooli: DB jest autorytatywne; optimistic pending tylko dopóki
+  // tool_result row nie dotarł przez liveQuery.
+  const resultMap = new Map<
+    string,
+    { value: unknown; isError?: boolean; raw?: string }
+  >();
+  for (const msg of rows) {
+    if (msg.role === "tool_result" && msg.toolCallId) {
+      // `content` może przyjść jako string ALBO już sparsowany obiekt —
+      // patrz komentarz w parseBlocks (deserializacja adaptera Postgresa).
+      const content: unknown = msg.content;
+      resultMap.set(msg.toolCallId, {
+        value: typeof content === "string" ? tryParseJson(content) : content,
+        isError: msg.isError,
+        raw:
+          typeof content === "string"
+            ? content
+            : JSON.stringify(content ?? ""),
+      });
+    }
+  }
+  for (const [toolCallId, value] of pendingToolResults) {
+    if (!resultMap.has(toolCallId)) {
+      resultMap.set(toolCallId, { value });
+    }
+  }
+
+  const items: TimelineItem[] = [];
+
+  const pushBlocks = (
+    messageId: string,
+    blocks: AssistantContentBlock[],
+    options: { streaming?: boolean } = {},
+  ) => {
+    let textCount = 0;
+    blocks.forEach((block, idx) => {
+      if (block.type === "text") {
+        if (block.text) {
+          items.push({
+            type: "message",
+            id: `${messageId}_t${textCount}`,
+            role: "assistant",
+            content: block.text,
+            // Caret tylko na ostatnim bloku aktywnie streamowanego turnu.
+            isStreaming: options.streaming && idx === blocks.length - 1,
+          });
+        }
+        textCount++;
+        return;
+      }
+      const result = resultMap.get(block.id);
+      const status: ToolStatus = result
+        ? result.isError
+          ? "error"
+          : "complete"
+        : isServerTool(block.name)
+          ? "executing"
+          : "pending";
+      items.push({
+        type: "tool",
+        id: block.id,
+        toolCallId: block.id,
+        toolName: block.name,
+        params: block.arguments,
+        result: result?.value,
+        status,
+        calling: !result,
+        error: result?.isError ? (result.raw ?? String(result.value)) : undefined,
+      });
+    });
+  };
+
+  for (const msg of rows) {
+    // System rows to developer-injected priming prompts — LLM je widzi
+    // (buildHistory), timeline nie.
+    if (msg.role === "system") continue;
+    if (msg.role === "tool_result") continue; // renderowane przy tool blocku
+
+    if (msg.role === "user") {
+      items.push({
+        type: "message",
+        id: msg._id,
+        role: "user",
+        // Wiadomość użytkownika zaczynająca się od "{" / "[" wraca
+        // z Postgresa sparsowana — renderujemy zawsze string.
+        content:
+          typeof msg.content === "string"
+            ? msg.content
+            : JSON.stringify(msg.content ?? ""),
+      });
+      continue;
+    }
+
+    if (msg.role !== "assistant") continue;
+
+    if (msg.isGenerating) {
+      const overlay = overlays.get(msg._id);
+
+      // Stream nieosiągalny (410 po retry / błąd sieci) — natychmiastowy
+      // lokalny stan; lazy repair w route wkrótce utrwali `interrupted`
+      // w DB dla wszystkich klientów.
+      if (overlay?.status === "gone") {
+        items.push({
+          type: "interrupted",
+          id: `${msg._id}_interrupted`,
+          messageId: msg._id,
+        });
+        continue;
+      }
+
+      if (overlay && overlay.blocks.length > 0) {
+        const streaming =
+          overlay.status === "live" || overlay.status === "connecting";
+        // Interactive tool w trakcie streamowania pokazujemy dopiero z
+        // kompletem argumentów: overlay dodaje blok już przy
+        // `tool_call_pending` (arguments={}), a view komponenty interactive
+        // tooli (np. AskQuestionsView → registerInputOverride) montują się
+        // z params i oczekują pełnych danych. Filtr PRZED pushBlocks —
+        // dzięki temu caret ląduje na ostatnim WIDOCZNYM bloku (tekst
+        // trzyma caret, gdy args się streamują), a turn złożony z samego
+        // ukrytego toola spada do spinner-placeholdera niżej.
+        const visibleBlocks = streaming
+          ? overlay.blocks.filter(
+              (b) =>
+                b.type !== "tool_call" ||
+                isServerTool(b.name) ||
+                Object.keys(b.arguments ?? {}).length > 0,
+            )
+          : overlay.blocks;
+        if (visibleBlocks.length > 0) {
+          pushBlocks(msg._id, visibleBlocks, { streaming });
+          continue;
+        }
+      }
+
+      // Brak overlaya (SSE jeszcze się łączy), pusty stream albo same
+      // ukryte bloki — pusty streaming bubble (DS renderuje spinner).
+      items.push({
+        type: "message",
+        id: `${msg._id}_t0`,
+        role: "assistant",
+        content: "",
+        isStreaming: true,
+      });
+      continue;
+    }
+
+    if (msg.interrupted) {
+      items.push({
+        type: "interrupted",
+        id: `${msg._id}_interrupted`,
+        messageId: msg._id,
+      });
+      continue;
+    }
+
+    // Zamknięty turn — finalne blocks z DB. Klucze itemów identyczne jak
+    // przy overlayu (`${_id}_t${n}` / toolCallId) → przejście overlay→DB
+    // nie remountuje elementów.
+    pushBlocks(msg._id, parseBlocks(msg.blocks));
+
+    if (msg.error) {
+      items.push({
+        type: "message",
+        id: `${msg._id}_error`,
+        role: "assistant",
+        content: msg.error,
+      });
+    }
+  }
+
+  // Optimistic user messages — jeszcze nie potwierdzone przez liveQuery.
+  for (const pending of pendingSends) {
+    if (isPendingSendSettled(history, pending)) continue;
+    items.push({
+      type: "message",
+      id: pending.localId,
+      role: "user",
+      content: pending.content,
+    });
+  }
+
+  const hasWaitingInteractive = items.some(
+    (it) => it.type === "tool" && it.calling && !isServerTool(it.toolName),
+  );
+
+  return {
+    items,
+    busy: deriveBusy(rows, overlays, pendingSends, history, isServerTool, now),
+    hasWaitingInteractive,
+  };
+}
+
+function deriveBusy(
+  rows: any[],
+  overlays: ReadonlyMap<string, AssistantOverlay>,
+  pendingSends: readonly PendingSend[],
+  history: any[] | undefined,
+  isServerTool: (toolName: string) => boolean,
+  now: number,
+): boolean {
+  // 1. Trwa generacja (row otwarty, stream nie jest martwy).
+  for (const msg of rows) {
+    if (
+      msg.role === "assistant" &&
+      msg.isGenerating &&
+      !msg.interrupted &&
+      overlays.get(msg._id)?.status !== "gone"
+    ) {
+      return true;
+    }
+  }
+
+  // 2. Wiadomość wysłana, row jeszcze nie dotarł przez liveQuery.
+  if (pendingSends.some((p) => !isPendingSendSettled(history, p))) return true;
+
+  if (rows.length === 0) return false;
+  const lastActivityTs = Math.max(...rows.map((r) => ts(r.createdAt)));
+  const fresh = now - lastActivityTs < BUSY_STALENESS_MS;
+  if (!fresh) return false;
+
+  // 3. Gap A: ostatni assistant turn zamknął się server-tool callami,
+  //    których wyniki jeszcze nie dotarły (listener egzekwuje tool'e).
+  const lastAssistant = [...rows]
+    .reverse()
+    .find((r) => r.role === "assistant");
+  if (
+    lastAssistant &&
+    !lastAssistant.isGenerating &&
+    !lastAssistant.interrupted &&
+    !lastAssistant.error
+  ) {
+    const resultIds = new Set(
+      rows
+        .filter((r) => r.role === "tool_result" && r.toolCallId)
+        .map((r) => r.toolCallId),
+    );
+    const blocks = parseBlocks(lastAssistant.blocks);
+    const awaitingServerTool = blocks.some(
+      (b) =>
+        b.type === "tool_call" &&
+        isServerTool(b.name) &&
+        !resultIds.has(b.id),
+    );
+    if (awaitingServerTool) return true;
+  }
+
+  // 4. Gap B: ostatni row to świeży tool_result server-toola — listener
+  //    jest pomiędzy saveToolResult a startAssistantTurn następnej
+  //    iteracji (np. wolny buildInstructions). Po server-tool result
+  //    ZAWSZE następuje kolejny turn.
+  const lastRow = rows[rows.length - 1];
+  if (
+    lastRow.role === "tool_result" &&
+    lastRow.toolName &&
+    isServerTool(lastRow.toolName)
+  ) {
+    return true;
+  }
+
+  return false;
+}

package/src/react/use-assistant-overlays.ts

@@ -0,0 +1,269 @@
+import { useEffect, useRef, useState } from "react";
+import type { ChatStreamEvent } from "@arcote.tech/arc-ai";
+import { applyStreamEvent } from "../streaming/blocks-reducer";
+import type { AssistantOverlay } from "./derive-timeline";
+
+// ─── Overlay hook — SSE jako warstwa nakładkowa, nie źródło prawdy ──
+//
+// Per generujący assistant row (`isGenerating=true` w DB) utrzymuje
+// połączenie SSE i buduje `AssistantOverlay { blocks, status }` przez
+// SHARED reducer (`applyStreamEvent` — ten sam kod co serwerowy
+// `publish()`). Event `init` niesie snapshot — resetuje bazę bloków,
+// więc reconnect w dowolnym momencie jest bezstratny i idempotentny.
+//
+// Hook NIGDY nie dotyka timeline'u — wyłącznie aktualizuje mapę
+// overlayów. Autorytatywny koniec turnu to flip `isGenerating=false`
+// w DB (liveQuery); `done`/`error` z SSE są czysto advisory.
+//
+// Failure mode'y kanału SSE (martwy socket, throttling karty w tle,
+// BFCache, restart serwera) degradują się do "overlay przestał się
+// aktualizować" — derywacja renderuje placeholder/ostatni znany stan,
+// a DB ostatecznie domyka turn. Stąd recovery jest proste: zabij
+// połączenie i otwórz nowe (init snapshot naprawia wszystko).
+
+/** Telemetria — host app może podpiąć `globalThis.__arcChatOnStuck`. */
+function reportStreamGone(attrs: Record<string, unknown>): void {
+  // eslint-disable-next-line no-console
+  console.warn("[arc-chat][stream_gone]", attrs);
+  try {
+    (globalThis as any).__arcChatOnStuck?.(attrs);
+  } catch {
+    /* reporter must never break the chat */
+  }
+}
+
+/** Verbose timing gated za `globalThis.__ARC_CHAT_DEBUG`. */
+function chatDebug(...args: unknown[]): void {
+  if ((globalThis as any).__ARC_CHAT_DEBUG) {
+    const ts =
+      typeof performance !== "undefined" ? performance.now().toFixed(0) : "";
+    // eslint-disable-next-line no-console
+    console.debug(`[arc-chat +${ts}ms]`, ...args);
+  }
+}
+
+interface Connection {
+  ctrl: AbortController;
+  /** performance.now() ostatniego bajtu (dane + keepalive ping). */
+  lastByteAt: number | null;
+}
+
+const MAX_410_RETRIES = 4;
+const RETRY_DELAY_MS = 300;
+/** 2× serwerowy KEEPALIVE_INTERVAL_MS (5 s) + zapas. */
+const HEARTBEAT_TIMEOUT_MS = 12_000;
+
+export function useAssistantOverlays(
+  chatName: string,
+  generatingIds: readonly string[],
+): ReadonlyMap<string, AssistantOverlay> {
+  const [overlays, setOverlays] = useState<Map<string, AssistantOverlay>>(
+    () => new Map(),
+  );
+  /** Bump → effect przeładowuje połączenia (visibility / heartbeat / BFCache). */
+  const [reopenNonce, setReopenNonce] = useState(0);
+  const connsRef = useRef<Map<string, Connection>>(new Map());
+
+  const idsKey = generatingIds.join("|");
+
+  useEffect(() => {
+    const ids = new Set(generatingIds);
+
+    // GC overlayów rzędów, które przestały generować (derywacja i tak by
+    // je zignorowała — flip isGenerating przyniósł finalne blocks w tym
+    // samym rzędzie liveQuery).
+    setOverlays((prev) => {
+      let changed = false;
+      const next = new Map(prev);
+      for (const key of next.keys()) {
+        if (!ids.has(key)) {
+          next.delete(key);
+          changed = true;
+        }
+      }
+      return changed ? next : prev;
+    });
+
+    for (const messageId of generatingIds) {
+      const ctrl = new AbortController();
+      const conn: Connection = { ctrl, lastByteAt: null };
+      connsRef.current.set(messageId, conn);
+      /** Połączenie jest aktualne dopóki connsRef trzyma TĘ instancję —
+       *  zamiennik sekwencerów: eventy ze starych readerów są ignorowane. */
+      const isCurrent = () => connsRef.current.get(messageId) === conn;
+
+      const setOverlay = (
+        update: (prev: AssistantOverlay | undefined) => AssistantOverlay,
+      ) => {
+        if (!isCurrent()) return;
+        setOverlays((prev) => {
+          const next = new Map(prev);
+          next.set(messageId, update(prev.get(messageId)));
+          return next;
+        });
+      };
+
+      // Reconnect zachowuje ostatnie znane bloki (status connecting) —
+      // init snapshot zaraz je nadpisze; zero flasha do placeholdera.
+      setOverlay((prev) => ({
+        blocks: prev?.blocks ?? [],
+        status: "connecting",
+      }));
+      chatDebug("sse open", { messageId });
+
+      (async () => {
+        try {
+          // 410 = brak in-memory streamu. Serwer otwiera stream
+          // synchronicznie ze startem turnu (listener przed 1. awaitem),
+          // ale zostaje krótki residualny race + okno restartu serwera.
+          // Retry z backoffem; po wyczerpaniu → "gone" (route w tym
+          // czasie mógł już zrobić lazy repair `interrupted` w DB).
+          let res: Response | null = null;
+          for (let attempt = 0; ; attempt++) {
+            res = await fetch(`/route/chat/${chatName}/stream/${messageId}`, {
+              credentials: "include",
+              signal: ctrl.signal,
+              headers: { Accept: "text/event-stream" },
+            });
+            if (res.status !== 410) break;
+            if (attempt >= MAX_410_RETRIES) {
+              reportStreamGone({ chatName, messageId, reason: "410_exhausted" });
+              setOverlay((prev) => ({
+                blocks: prev?.blocks ?? [],
+                status: "gone",
+              }));
+              return;
+            }
+            await new Promise<void>((r) => setTimeout(r, RETRY_DELAY_MS));
+            if (!isCurrent()) return;
+          }
+          if (!res.ok) throw new Error(`Stream failed: ${res.status}`);
+
+          const reader = res.body!.getReader();
+          const decoder = new TextDecoder();
+          let buf = "";
+          conn.lastByteAt =
+            typeof performance !== "undefined" ? performance.now() : 0;
+
+          while (isCurrent()) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            conn.lastByteAt =
+              typeof performance !== "undefined" ? performance.now() : 0;
+            buf += decoder.decode(value, { stream: true });
+            const lines = buf.split("\n");
+            buf = lines.pop() ?? "";
+            for (const line of lines) {
+              if (!line.startsWith("data: ")) continue;
+              try {
+                const event = JSON.parse(line.slice(6)) as ChatStreamEvent;
+                chatDebug("sse event", event.type);
+                if (event.type === "init") {
+                  setOverlay(() => ({
+                    blocks: event.currentBlocks ?? [],
+                    status: "live",
+                  }));
+                } else if (event.type === "done" || event.type === "error") {
+                  // Advisory — zdejmuje caret od razu; autorytatywne
+                  // domknięcie (finalne blocks / error) przyjdzie flipem
+                  // isGenerating w DB.
+                  setOverlay((prev) => ({
+                    blocks: prev?.blocks ?? [],
+                    status: "done",
+                  }));
+                } else {
+                  setOverlay((prev) => ({
+                    blocks: applyStreamEvent(prev?.blocks ?? [], event),
+                    status: prev?.status ?? "live",
+                  }));
+                }
+                // Yield między eventami, żeby React nie batchował updateów
+                // w jeden render (streaming niewidoczny). queueMicrotask,
+                // NIE setTimeout(0): Chrome throttluje timeouty w kartach
+                // w tle do ≥1 s — microtaski nie są throttlowane, pętla
+                // domyka turn nawet w tle.
+                await new Promise<void>((r) => queueMicrotask(r));
+              } catch {}
+            }
+          }
+        } catch (err) {
+          if ((err as any)?.name === "AbortError") return;
+          if (!isCurrent()) return;
+          reportStreamGone({
+            chatName,
+            messageId,
+            reason: "network_error",
+            error: err instanceof Error ? err.message : String(err),
+          });
+          setOverlay((prev) => ({
+            blocks: prev?.blocks ?? [],
+            status: "gone",
+          }));
+        }
+      })();
+    }
+
+    // Cleanup zamyka WSZYSTKIE połączenia tego cyklu — następny run
+    // effectu (zmiana generatingIds / bump nonce / StrictMode remount)
+    // otwiera je od zera. Reconnect jest bezstratny: `init` snapshot
+    // resetuje bazę overlaya, a overlay state przeżywa cykl effectu.
+    return () => {
+      for (const conn of connsRef.current.values()) conn.ctrl.abort();
+      connsRef.current.clear();
+    };
+  }, [idsKey, reopenNonce, chatName]);
+
+  /** Wymuś przeładowanie połączeń (cleanup + ponowny run effectu). */
+  const reconnectAll = (reason: string) => {
+    if (connsRef.current.size === 0) return;
+    chatDebug("reconnect", { reason });
+    setReopenNonce((n) => n + 1);
+  };
+  const reconnectAllRef = useRef(reconnectAll);
+  reconnectAllRef.current = reconnectAll;
+
+  // ─── Visibility — powrót na kartę wymusza reconnect ────────────
+  // Chrome/Safari agresywnie zamrażają karty w tle: reader.read() potrafi
+  // wisieć na martwym sockecie bez błędu. Nie wykrywamy poszczególnych
+  // failure mode'ów — każdy powrót do widoczności przeładowuje połączenia.
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const onVisibility = () => {
+      if (document.visibilityState !== "visible") return;
+      reconnectAllRef.current("visibility");
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, []);
+
+  // ─── BFCache restore — wszystkie sockety są martwe ──────────────
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onPageShow = (e: PageTransitionEvent) => {
+      if (!e.persisted) return;
+      reconnectAllRef.current("bfcache");
+    };
+    window.addEventListener("pageshow", onPageShow);
+    return () => window.removeEventListener("pageshow", onPageShow);
+  }, []);
+
+  // ─── Heartbeat — cichy martwy socket przy aktywnej karcie ───────
+  // Serwer wysyła `: ping` co 5 s; brak bajtów > HEARTBEAT_TIMEOUT_MS
+  // oznacza martwe połączenie → reconnect.
+  useEffect(() => {
+    if (generatingIds.length === 0) return;
+    if (typeof performance === "undefined") return;
+    const id = setInterval(() => {
+      if (typeof document !== "undefined" && document.hidden) return;
+      for (const conn of connsRef.current.values()) {
+        if (conn.lastByteAt === null) continue;
+        if (performance.now() - conn.lastByteAt < HEARTBEAT_TIMEOUT_MS) continue;
+        reconnectAllRef.current("heartbeat");
+        return;
+      }
+    }, 3_000);
+    return () => clearInterval(id);
+  }, [idsKey]);
+
+  return overlays;
+}