Warm timeline cache from realtime events

Author: IM.codes

web/src/app.tsx

@@ -112,6 +112,7 @@ import { shouldSubscribeTerminalRaw, type TerminalSubscribeViewMode } from './te
 import { onWatchCommand } from './watch-bridge.js';
 import { watchProjectionStore } from './watch-projection.js';
 import { isIdleSessionStateTimelineEvent, isRunningTimelineEvent } from './timeline-running.js';
+import { ingestTimelineEventForCache } from './hooks/useTimeline.js';
 
 // On web: if opened by the native app for passkey auth, render the bridge page.
 const nativeCallback = typeof window !== 'undefined'
@@ -1173,6 +1174,7 @@ export function App() {
       // Detect model from JSONL usage.update events (authoritative, overrides terminal scan)
       if (msg.type === 'timeline.event') {
         const event = msg.event;
+        ingestTimelineEventForCache(event, selectedServerId);
         watchProjectionStore.handleTimelineEvent(event);
         if (isRunningTimelineEvent(event) && !event.sessionId.startsWith('deck_sub_')) {
           setSessions((prev) => prev.map((s) =>

web/src/hooks/useTimeline.ts

@@ -94,6 +94,20 @@ function pruneTimelineCache(): void {
   }
 }
 
+function scopeCacheKey(serverId: string | null | undefined, sessionId: string): string {
+  return serverId ? `${serverId}:${sessionId}` : sessionId;
+}
+
+function scopeEventsForDb(cacheKey: string, events: TimelineEvent[]): TimelineEvent[] {
+  if (cacheKey === events[0]?.sessionId) return events;
+  return events.map((event) => ({ ...event, sessionId: cacheKey }));
+}
+
+function persistTimelineEvents(cacheKey: string, events: TimelineEvent[]): void {
+  if (events.length === 0) return;
+  sharedDb.putEvents(scopeEventsForDb(cacheKey, events)).catch(() => {});
+}
+
 export function __resetTimelineCacheForTests(): void {
   eventsCache.clear();
   eventsCacheAccess.clear();
@@ -108,6 +122,14 @@ export function __setTimelineCacheForTests(cacheKey: string, events: TimelineEve
   setCachedEvents(cacheKey, events);
 }
 
+export function ingestTimelineEventForCache(event: TimelineEvent, serverId?: string | null): void {
+  const cacheKey = scopeCacheKey(serverId, event.sessionId);
+  const existing = getCachedEvents(cacheKey) ?? [];
+  const merged = mergeTimelineEvents(existing, [event], MAX_MEMORY_EVENTS);
+  if (merged !== existing) setCachedEvents(cacheKey, merged);
+  persistTimelineEvents(cacheKey, [event]);
+}
+
 export interface UseTimelineResult {
   events: TimelineEvent[];
   loading: boolean;
@@ -130,7 +152,7 @@ export function useTimeline(
 ): UseTimelineResult {
   // IDB + memory cache key: scope by serverId to prevent cross-server pollution
   // when different servers share the same session name (e.g. deck_cd_brain).
-  const cacheKey = serverId && sessionId ? `${serverId}:${sessionId}` : sessionId;
+  const cacheKey = sessionId ? scopeCacheKey(serverId, sessionId) : sessionId;
   const cacheKeyRef = useRef(cacheKey);
   cacheKeyRef.current = cacheKey;
   const [events, setEvents] = useState<TimelineEvent[]>([]);
@@ -320,11 +342,8 @@ export function useTimeline(
   // IDB helper: scope events by cacheKey so cross-server sessions don't collide
   const idbPutEvents = useCallback((evts: TimelineEvent[]) => {
     const key = cacheKeyRef.current;
-    if (!key || key === evts[0]?.sessionId) {
-      sharedDb?.putEvents(evts).catch(() => {});
-    } else {
-      sharedDb?.putEvents(evts.map(e => ({ ...e, sessionId: key }))).catch(() => {});
-    }
+    if (!key) return;
+    persistTimelineEvents(key, evts);
   }, []);
 
   // Listen for WS messages

web/test/use-timeline-cache.test.ts

@@ -1,14 +1,15 @@
 /**
  * @vitest-environment jsdom
  */
-import { beforeEach, describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { render, screen, cleanup, act, waitFor } from '@testing-library/preact';
 import { h } from 'preact';
 import type { ServerMessage, TimelineEvent, WsClient } from '../src/ws-client.js';
 import {
   __getTimelineCacheKeysForTests,
   __resetTimelineCacheForTests,
   __setTimelineCacheForTests,
+  ingestTimelineEventForCache,
   useTimeline,
 } from '../src/hooks/useTimeline.js';
 
@@ -138,6 +139,58 @@ describe('useTimeline global cache bounds', () => {
     });
   });
 
+  it('renders immediately from globally ingested timeline events before the first history request returns', async () => {
+    const sessionName = `deck_sub_codex_sdk_${Date.now()}`;
+    const serverId = `srv-${Date.now()}`;
+    let handler: ((msg: ServerMessage) => void) | null = null;
+    const sendTimelineHistoryRequest = vi.fn(() => 'history-live');
+
+    ingestTimelineEventForCache({
+      eventId: `${sessionName}-live-1`,
+      sessionId: sessionName,
+      ts: 1,
+      epoch: 7,
+      seq: 1,
+      source: 'daemon',
+      confidence: 'high',
+      type: 'assistant.text',
+      payload: { text: 'live cached text' },
+    }, serverId);
+
+    const ws: WsClient = {
+      connected: true,
+      onMessage: (next: (msg: ServerMessage) => void) => {
+        handler = next;
+        return () => { handler = null; };
+      },
+      sendTimelineHistoryRequest,
+    } as unknown as WsClient;
+
+    function Probe() {
+      const { events } = useTimeline(sessionName, ws, serverId);
+      return h('div', { 'data-testid': 'probe' }, events[0]?.payload.text as string ?? '');
+    }
+
+    render(h(Probe, {}));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('probe').textContent).toBe('live cached text');
+    });
+    expect(sendTimelineHistoryRequest).toHaveBeenCalledWith(sessionName, 300);
+
+    await act(async () => {
+      handler?.({
+        type: 'timeline.history',
+        sessionName,
+        requestId: 'history-live',
+        epoch: 7,
+        events: [],
+      } as ServerMessage);
+    });
+
+    expect(screen.getByTestId('probe').textContent).toBe('live cached text');
+  });
+
   it('keeps timeline history isolated across servers for the same session name', async () => {
     const sessionName = `deck_shared_${Date.now()}`;
     let handlerA: ((msg: ServerMessage) => void) | null = null;